video-download/download-backend/README.md

Video Download Backend

FastAPI service that wraps yt-dlp to expose endpoints for inspecting video metadata and downloading media files.

Requirements

• Python 3.11+
• fastapi, uvicorn[standard], yt-dlp (install via pip install -r requirements.txt)
• ffmpeg available in PATH (required for merging best video and audio streams into mp4)
• aiofiles (installed via requirements.txt) to support static file serving

Running locally

cd download-backend
python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

The API will be available at http://localhost:8000. Interactive docs are served at http://localhost:8000/docs.

API Overview

• GET /health – simple readiness check.
• GET /api/info?url=<video_url> – returns normalized metadata plus available formats for a given video.
• POST /api/download – downloads the requested video (optionally specifying a format_id), stores it in tmp_downloads/, and returns a JSON response with a download_url. The service inspects available formats, preferring MP4 progressive or MP4 video + M4A audio when available, and gracefully falls back through compatible combinations before using yt-dlp's generic best selection.

Downloaded files are served at http://localhost:8000/downloads/<file-name> for direct access while the server is running.

Download payload

{
  "url": "https://www.youtube.com/watch?v=...",
  "format_id": "22",
  "filename": "optional-custom-name"
}

• format_id matches the entries in the formats array returned by /api/info.
• filename is optional; omit the extension to let yt-dlp set it automatically.

Temporary files are cleaned up automatically after each request.