ytdlp/docs/ARCHITECTURE.md

Architecture

Current state

Browser
  -> FastAPI / Jinja interface
  -> POST /api/inspect
  -> URL validation
  -> yt-dlp metadata extraction (download disabled)
  -> normalized metadata and output previews

FastAPI runs inspection in a thread pool. The browser receives a deliberately small response and never receives yt-dlp's signed media URLs. Displayed output options are previews; backend download selectors are not implemented yet.

Next application boundary

Downloads will use durable jobs rather than long-running HTTP requests:

Web service -> SQLite job record <- Worker service
                                     |
                                     +-> yt-dlp
                                     +-> FFmpeg / ffprobe
                                     +-> per-job directory

The worker will claim one queued job at a time, update progress, validate the finished media, and record the artifact. This preserves state across web restarts and keeps media processing outside request handlers.

Planned output presets

1. Best available — highest useful source quality, merging separate video and audio streams without transcoding.
2. Compatible MP4 — prefer the highest H.264 video and AAC audio streams that can be merged into MP4 without transcoding.

If no compatible combination exists, the first version should report that instead of silently starting an expensive transcode. Transcoding can later be an explicit third outcome with CPU and time limits.

Production boundary

Production will route Cloudflare Access through Cloudflare Tunnel to the web service. The origin will not publish an application port directly.