Initial commit

download-backend/README.md

@@ -0,0 +1,45 @@
+# Video Download Backend
+
+FastAPI service that wraps [yt-dlp](https://github.com/yt-dlp/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
+
+```bash
+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
+
+```json
+{
+  "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.