The open-source yt-dlp + FFmpeg + Whisper wrapper

The stack

Example: download → transcribe → reframe via REST

# Download → Transcribe → Reframe a video via the REST API
# (No CLI flags, no FFmpeg argv construction, no Whisper config.)

curl -X POST http://127.0.0.1:16888/api/download \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"}'
# → {"job_id": "j_abc123"}

# Poll until terminal (the MCP wait_for_job helper does this for you):
curl http://127.0.0.1:16888/api/jobs/j_abc123
# → {"status": "success", "output": {"downloaded_video_id": 42}}

# Auto-transcribe is chained — Whisper ran in the same job.
# Now reframe to 9:16 with face-tracking + burn captions:
curl -X POST http://127.0.0.1:16888/api/tools/reframe \
  -H "Content-Type: application/json" \
  -d '{"video_id": 42, "target_aspect": "9:16", "burn_captions": true}'
# → {"job_id": "j_xyz789"}
# → output mp4 at downloaded_video.video_path_9x16

Same operations are also exposed as MCP tools — Claude Code can chain them with natural-language prompts. See /developers/mcp-video-server/.

What ViralMint solves over raw yt-dlp + FFmpeg

• Format selection + remux defaults. yt-dlp's -f bestvideo+bestaudio is right most of the time but breaks on sites that serve segmented streams. The download wrapper picks the right format string per platform (different defaults for YouTube vs Bilibili vs Douyin) and remuxes to mp4 automatically.
• Cookie auth without per-call setup. Export browser cookies once via Settings → Cookies; yt-dlp uses them on every subsequent download for age-gated, private, or paid content. No CLI flags per call.
• Browser impersonation + Playwright fallback. When yt-dlp's direct extractor hits bot detection, the wrapper falls back to curl-cffi browser impersonation; when that fails, it spins up bundled Chromium via Playwright to capture the HLS manifest. Three tiers, automatic.
• Whisper word-timestamp → ASS subtitle alignment. Whisper outputs word-level timestamps; mapping them onto ASS-format subtitle timing with proper line breaks, max-2-words-per-frame styling, and language-aware spacing is non-trivial. ViralMint owns the alignment.
• FFmpeg argv discipline. Every FFmpeg call is built from argv lists (never shell=True string concatenation) so user input doesn't shell-inject. Reframe + caption burn + audio mix are single-pass filter graphs, not chained subprocess calls.
• Async-everywhere job model. Long-running operations (download, transcription, video generation) return a job_id immediately; poll GET /api/jobs/{id} for status / progress / output. No blocking subprocess waits in your code.

Where the code lives

• Download: backend/services/ytdlp_service.py — yt-dlp wrapper with the multi-tier fallback chain.
• Transcribe: backend/services/whisper_service.py — faster-whisper wrapper with model loading + word-timestamp extraction.
• FFmpeg: backend/services/ffmpeg_service.py — argv-list-based wrapper for stitch / caption / mix / reframe / normalize.
• REST API: backend/api/ — FastAPI routers for every operation, mounted on /api/*.
• MCP server: backend/mcp/ — FastMCP tools that wrap the REST routes for MCP-aware clients.
• Job runner: backend/core/task_runner.py — asyncio in-process dispatcher (no Redis / Celery).