113 lines
2.3 KiB
Markdown
113 lines
2.3 KiB
Markdown
# 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
|
|
```
|