# FFmpeg Media - Project Overview


> **Module Name:** `ffmpeg_media`
> **Namespace:** `Drupal\ffmpeg_media`
> **Target Drupal:** 11.3+ / 12
> **PHP Requirement:** 8.5+
> **FFmpeg Requirement:** 8.x

---

## 1. Mission

Deliver a contrib-ready, production-grade video processing suite for Drupal that is:

- Reliable and scalable (queues, retries, locks)
- Extensible (plugins for codecs, outputs, processors)
- Fast (hardware acceleration with safe fallbacks)
- Practical (good defaults, clean admin UX, clear extension boundary)

---

## 2. Core Capabilities

### 2.1 Transcoding
- Queue-based conversion with full CRUD profile management
- Hardware acceleration (NVENC/CUDA/VAAPI/QSV/VideoToolbox/AMF/Vulkan/OpenHarmony)
- Per-title ABR ladder generation (BitrateAnalyzer)
- GOP alignment for streaming outputs

### 2.2 Processing Pipeline
- Thumbnails (single + segment)
- Animated GIFs (single + segment)
- Video metadata extraction
- Audio normalization
- Optional manifest output (JSON/YAML)

### 2.3 Streaming (Submodule)
- HLS + DASH outputs
- Adaptive representations configured via UI
- External subtitle tracks and multi-audio tracks

### 2.4 Whisper (Submodule)
- Local speech-to-text using whisper.cpp CLI
- WebVTT/SRT output

### 2.5 UI (Submodule)
- Dashboard with queue and conversion stats
- Poster selection
- Admin actions (transcode/refresh/clear)
- No separate uploader: source file uploads use Drupal core Media workflows

### 2.6 Admin UX
- Themed admin pages with Gin-compatible design system (dark mode, responsive)
- Guided formatter configuration flow via Manage Display with status guidance
- Conversion profile list with explanatory guide, settings reference, and profile cards
- Consistent BEM CSS with CSS custom properties across dashboard and profiles

### 2.7 Field Integrity
- Detects orphaned field definitions in entity.definitions.installed
- Periodic cron check (daily) with Drush command for manual inspection
- Repair workflow for orphaned definitions via Drush command/manual action

---

## 3. Non-Functional Requirements

- **Performance:** queue + concurrency controls, FFprobe caching
- **Stability:** retries, locks, stuck-process recovery
- **Security:** validated input paths/URLs, SSRF protection, command escaping
- **Maintainability:** strict types, interfaces, PHPUnit coverage

---

## 4. Module Layout

```
ffmpeg_media/
├── modules/
│   ├── ffmpeg_media_streaming
│   ├── ffmpeg_media_whisper
│   ├── ffmpeg_media_advanced
│   ├── ffmpeg_media_image
│   ├── ffmpeg_media_ui
│   └── ffmpeg_media_player
├── src/
├── config/
├── tests/
├── templates/
└── docs/
```

---

## 5. Success Criteria (Current)

- ✅ Drupal 11.3+/12 compatibility
- ✅ PHP 8.5+ runtime
- ✅ Full `qa:ci` gate green on the Drupal 11.3 / PHP 8.5.2 harness
- ✅ PHPCS clean (Drupal/DrupalPractice)
- ✅ PHPUnit suite green (core/contrib skips remain)
- ✅ Updated documentation (README + docs/*)
- ✅ Queue editor scheduling changes are read live without cache-reset coupling
- ✅ Stable CLI falls back to sequential processing when `--workers > 1`

---

## 6. Current Operations Snapshot

- ✅ Health probes can be enforced fail-closed in production via
  `health_probe_token_required`.
- ✅ Runtime environment overrides support probe hardening:
  `APP_ENV`, `FFMPEG_HEALTH_PROBE_REQUIRED`, `FFMPEG_HEALTH_PROBE_TOKEN`.
- ✅ Admin settings expose State-backed probe token rotation and requirement
  toggling for non-env deployments without exporting secrets.
- ✅ Repository-local load benchmark script available via
  `npm run benchmark:load`.
- ✅ The load benchmark uses conservative defaults on localhost-style dev
  targets and can be raised explicitly for tuned or production-like stacks.
- ✅ Repository-local API/header smoke validation available via
  `npm run security:smoke`.

---

*Last updated: 2026-03-28*
