Initial commit

README.md

@@ -0,0 +1,112 @@
+# Local YouTube Audio Converter
+
+A local-only FastAPI web app for converting audio from YouTube video URLs into downloadable audio files.
+
+Use this only for media you own, created, or have permission to download and convert.
+
+## Features
+
+- Dark, responsive web UI at `http://localhost:8000`
+- YouTube URL validation
+- Metadata preview with title, channel, duration, and thumbnail
+- Output formats: MP3, WAV, FLAC, M4A, OGG
+- MP3 quality options: 128, 192, 256, 320 kbps
+- Background conversion jobs with status polling
+- Per-job local download folders under `backend/downloads/`
+
+## Linux Setup
+
+Install system dependencies:
+
+```bash
+sudo apt update
+sudo apt install -y python3 python3-venv python3-pip ffmpeg
+```
+
+Create and activate a virtual environment:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+Install Python dependencies:
+
+```bash
+pip install -r requirements.txt
+```
+
+Confirm the required tools are available:
+
+```bash
+ffmpeg -version
+yt-dlp --version
+```
+
+## Run
+
+Start the local server:
+
+```bash
+.venv/bin/uvicorn backend.main:app --reload --host 127.0.0.1 --port 8000
+```
+
+Open:
+
+```text
+http://localhost:8000
+```
+
+Converted files are stored locally in:
+
+```text
+backend/downloads/<job_id>/
+```
+
+## API
+
+- `GET /` serves the frontend
+- `POST /api/info` returns metadata for a YouTube URL
+- `POST /api/convert` starts a conversion job
+- `GET /api/status/{job_id}` returns job status
+- `GET /api/download/{job_id}` downloads the converted file
+
+## Troubleshooting
+
+Missing `ffmpeg`:
+
+```bash
+sudo apt install -y ffmpeg
+```
+
+Virtual environment creation fails with `ensurepip is not available`:
+
+```bash
+sudo apt install -y python3-venv python3-pip
+python3 -m venv .venv
+```
+
+Missing or outdated `yt-dlp`:
+
+```bash
+source .venv/bin/activate
+pip install --upgrade yt-dlp
+```
+
+Invalid URL:
+
+- Use a full YouTube video URL, such as `https://www.youtube.com/watch?v=...`
+- Playlist-only URLs are not supported.
+
+yt-dlp failure:
+
+- Update `yt-dlp`.
+- If you see `HTTP Error 403: Forbidden`, make sure you started the app with `.venv/bin/uvicorn` so it uses the current virtualenv copy of `yt-dlp`, not an older system package.
+- Try the same URL in a browser.
+- Some videos may be unavailable, private, region-locked, age-restricted, or blocked from extraction.
+
+Port already in use:
+
+```bash
+uvicorn backend.main:app --reload --host 127.0.0.1 --port 8001
+```