youtube-dl-server

youtube-dl-server is a lightweight, self‑hosted media ingestion service that exposes a web UI and REST API for programmatically downloading videos from YouTube and other supported hosts. Built on Starlette (an ASGI framework) and powered by yt‑dlp or the legacy youtube-dl, it offers a clean separation between HTTP handling, task orchestration, and the underlying download engine. The application stores metadata in a lightweight SQLite database (.ydl-metadata.db) and persists downloaded files to a user‑defined volume, making it ideal for integration into media pipelines or cloud storage backends.

Key Features

• RESTful API – Endpoints for enqueueing downloads, checking status, and retrieving metadata.
• Web UI – A minimal front‑end for quick manual downloads, queue inspection, and configuration tweaking.
• Configurable download options – Exposes any yt‑dlp/youtube‑dl flag via YAML, including subtitles, format selection, and output templates.
• Profile support – Allows named sets of options for different use cases (e.g., high‑quality archival vs. quick thumbnails).
• Extensible via environment variables – Swap between yt‑dlp and youtube‑dl at runtime, override configuration paths, or mount custom config files.

Technical Stack

Core Capabilities

• Task Queue – Internally uses Python’s asyncio to manage concurrent download jobs.
• Metadata API – Exposes JSON endpoints for querying job status, progress percentages, and final file paths.
• Webhooks – Optional callback URLs can be configured to notify external services upon completion or failure.
• Extensibility – Since the download logic is a thin wrapper around yt‑dlp, developers can inject custom post‑processing scripts or integrate with other media services (e.g., transcoding, CDN uploads) by watching the output directory or subscribing to webhook events.

Deployment & Infrastructure

• Self‑hosting – Requires a machine with Docker (or Podman) and sufficient disk space for downloads.
• Scalability – Horizontal scaling is straightforward: run multiple instances behind a load balancer, each with its own output volume or a shared NFS mount.
• Resource Limits – Configure CPU/memory limits in Docker Compose; yt‑dlp respects system limits, but heavy concurrent downloads can saturate I/O.
• Persistence – Volume mounts (/youtube-dl) ensure that both downloaded files and the SQLite DB survive container restarts.

Integration & Extensibility

• Plugin hooks – The project’s modular design allows adding custom middleware in Starlette or extending the download command via environment variables.
• API clients – Libraries exist in several languages (Python, Node.js, Go) to consume the REST endpoints; developers can embed the service into CI/CD pipelines or media ingestion workflows.
• Webhooks – Configure a callback URL in config.yml; the server POSTs JSON payloads on job completion, enabling automated post‑processing pipelines.

Developer Experience

• Configuration – YAML is intuitive; missing files are auto‑generated with defaults.
• Documentation – README covers Docker usage, config schema, and API basics; community examples are available on GitHub.
• Community – MIT‑licensed, active forks (e.g., manbearwiz/youtube-dl-server) and issue trackers provide quick support.
• Extensibility – Adding a new yt‑dlp flag is as simple as inserting it into ydl_options; no code changes required.

Use Cases

Advantages Over Alternatives

• Performance – Starlette’s async core keeps the API responsive even under heavy download loads.
• Flexibility – Exposes the full feature set of yt‑dlp without wrapper limitations.
• Licensing – MIT license allows unrestricted commercial use and internal modifications.
• Simplicity – One Docker image, minimal config, no external dependencies beyond Docker.
• Extensibility – Easy to hook into existing DevOps tooling