ffmpeg_media

FFmpeg Media brings end-to-end video processing to Drupal. Upload a video through Media Library, and FFmpeg Media handles the rest: transcoding, thumbnail generation, adaptive streaming, and output delivery — all within Drupal's own content model.

Built for Drupal 11.3+ and 12, the module wraps FFmpeg 8 in a service-oriented architecture with queue-based processing, conversion profiles, formatter-based configuration, and a plugin system that covers 8 codecs, 9 output formats, and 13 processors out of the box. Every component is extensible through standard Drupal plugin APIs.

Editors keep their familiar Drupal workflows. Developers get clean service boundaries, event-driven integration points, and a full Drush command surface. Operations teams get health probes, Prometheus metrics, and queue visibility. FFmpeg Media is designed for the entire team.

How it works

1. Upload/select a source video via Drupal Media.
2. Configure conversion on Manage Display using the FFmpeg field formatter.
3. Queue processing runs via cron, Drush, or worker processes.
4. FFmpeg generates configured outputs (for example MP4/WebM/HLS/DASH).
5. Outputs are stored and tracked for retrieval, playback, and operations.

Why FFmpeg Media

• Drupal-native workflow: no replacement of core Media upload UX.
• Queue safety: deduplication, retry/backoff, locks, stuck-process handling.
• Profile-based conversion: consistent output behavior per bundle/field.
• Modular architecture: enable only needed submodules.
• Operational visibility: health probes, metrics, progress endpoints, Drush tooling.

Core features

Conversion engine

• Queue-based transcoding with standard and large-file routing.
• Configurable conversion profiles (container, codec, quality, processors).
• Hardware acceleration detection with software fallback.
• Field-formatter based conversion configuration on Manage Display.

Outputs and processing

• Progressive outputs: MP4, WebM, MKV, FLV.
• Streaming outputs (submodule): HLS and DASH.
• Optional processors: metadata, thumbnails, GIFs, manifests, audio helpers, and more.

Player and editorial UX

• Optional Vidstack-based player submodule (local-first loading by default).
• Optional UI submodule with dashboard, status pages, and poster selection.

Whisper transcription (optional)

• ffmpeg_media_whisper uses whisper.cpp CLI (whisper-cli).
• Two-step pipeline: FFmpeg audio extraction + transcription to SRT/VTT.

What this module does not do

• It does not replace Drupal core upload handling.
• It does not bundle FFmpeg/ffprobe binaries.
• It is not a managed SaaS video platform.

Requirements

• Drupal 11.3+ or Drupal 12
• PHP 8.5+
• FFmpeg 8.x and ffprobe available on host/container
• Core modules: Media, File

Production setups should run queue workers (cron/Drush), ensure writable output storage, and monitor queue/system health.

Whisper setup (optional, for ffmpeg_media_whisper)

Install whisper.cpp and whisper-cli:

git clone https://github.com/ggml-org/whisper.cpp.git
cd whisper.cpp
cmake -B build
cmake --build build --config Release
sudo cmake --install build --config Release

Download a model and verify CLI:

./models/download-ggml-model.sh base.en
whisper-cli --help

Then configure path/model at /admin/config/media/ffmpeg-media/whisper.

Optional advanced path: if you want direct FFmpeg whisper-filter usage, build FFmpeg with --enable-whisper and verify via ffmpeg -filters | grep whisper.

Quick start

1. Enable module: drush en ffmpeg_media
2. Verify binaries: drush ffmpeg:status
3. Create/edit conversion profiles: /admin/config/media/ffmpeg-media/profiles
4. Open Manage Display for your media bundle.
5. Add FFmpeg formatter to the source field.
6. Enable auto-convert and choose a profile.
7. Upload a test video.
8. Process queue: drush ffmpeg:process

Submodules

• ffmpeg_media_streaming: HLS/DASH outputs and streaming settings.
• ffmpeg_media_player: Vidstack-based playback formatters.
• ffmpeg_media_ui: dashboard, status, poster selection, queue tools.
• ffmpeg_media_image: thumbnails, GIFs, segment previews.
• ffmpeg_media_whisper: transcription/subtitles via whisper.cpp CLI.
• ffmpeg_media_advanced: two-pass/HDR/watermark/subtitle burn/audio helpers.

Drush commands

Core commands include conversion, queue management, monitoring, and maintenance.

• ffmpeg:convert, ffmpeg:convert-all, ffmpeg:reconvert, ffmpeg:requeue-missing
• ffmpeg:process, ffmpeg:queue-clear
• ffmpeg:status, ffmpeg:progress, ffmpeg:processes
• ffmpeg:kill-stuck, ffmpeg:cleanup, ffmpeg:integrity-check
• ffmpeg:transcribe (with whisper submodule)

Production guidance

• Tune concurrency based on CPU, memory, and storage throughput.
• Keep health probes and metrics integrated into monitoring.
• Run integrity checks periodically.
• Use environment variables for sensitive credentials.

Security notes

• Array-based process execution for FFmpeg/ffprobe command safety.
• Path validation and stream-wrapper constraints for file operations.
• Role/permission-gated operations and API endpoints.
• Token-hardened health probe model for production deployments.

Developer extensibility

• Plugin types: codec, output, processor.
• Service-based architecture with DI/autowiring.
• Conversion lifecycle events for custom integrations.

FAQ

Does this replace Drupal Media uploads?

No. Uploads remain Drupal-native; FFmpeg Media starts after save.

Do I need all submodules?

No. Enable only the capabilities you need.

Can it run without the UI submodule?

Yes. Core workflows are available via formatter config + Drush.

Can I use GPU acceleration?

Yes. Hardware detection/fallback is built in; exact encoder availability depends on your FFmpeg build and host hardware.