# 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
```