Youtube-to-mp3-ripper/README.md

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:

sudo apt update
sudo apt install -y python3 python3-venv python3-pip ffmpeg

Create and activate a virtual environment:

python3 -m venv .venv
source .venv/bin/activate

Install Python dependencies:

pip install -r requirements.txt

Confirm the required tools are available:

ffmpeg -version
yt-dlp --version

Run

Start the local server:

.venv/bin/uvicorn backend.main:app --reload --host 127.0.0.1 --port 8000

Open:

http://localhost:8000

Converted files are stored locally in:

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:

sudo apt install -y ffmpeg

Virtual environment creation fails with ensurepip is not available:

sudo apt install -y python3-venv python3-pip
python3 -m venv .venv

Missing or outdated yt-dlp:

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:

uvicorn backend.main:app --reload --host 127.0.0.1 --port 8001