A self-hosted YouTube audio downloader with automatic metadata tagging.

• Search & Download — Paste a YouTube URL or search by name
• MP3 320kbps — Best quality audio extraction
• Auto-tag — Fetches artist, album, track number, year from MusicBrainz
• Cover Art — Downloads album artwork automatically
• YouTube Cookies — Optional upload to bypass rate limits
• i18n — Portuguese (PT) / English (EN) toggle
• Progress Tracking — Real-time download progress bars

• Backend: FastAPI (Python 3.11+)
• Frontend: Vanilla JS + Jinja2 templates
• Metadata: yt-dlp, MusicBrainz, mutagen

# Clone & enter
git clone https://github.com/<your-username>/blackpearl.git
cd blackpearl
# Create venv (Python 3.11+)
python3 -m venv .venv
source .venv/bin/activate # Linux/macOS
# .venv\Scripts\activate # Windows
# Install deps
pip install -r requirements.txt
# Run
python main.py

Open http://localhost:8046

• Python 3.11+
• FFmpeg (for audio conversion)
• Deno (optional, for YouTube JS challenges)

Linux (apt):

sudo apt install ffmpeg

macOS (brew):

brew install ffmpeg

Windows: Download from https://ffmpeg.org (add to PATH)

Required only if YouTube returns JS challenges. Install:

curl -fsSL https://deno.land/x/install/install.sh | sh
# Add ~/.deno/bin to PATH

1. Open the app
2. Paste a YouTube link (youtube.com/watch?v=...) or search term
3. Click search
4. Click download on the result
5. File saves to downloads/ with ID3 tags

When enabled (default), Black Pearl tries to:

1. Parse artist/track from YouTube title
2. Search YouTube Music for structured metadata
3. Query MusicBrainz for album/track info
4. Download cover art from Cover Art Archive
5. Apply ID3 tags and rename file

Disable via "Auto-tag" toggle in header.

If YouTube blocks downloads ("Sign in to confirm you're not a bot"):

1. Install "Get cookies.txt LOCALLY" extension in Librewolf/Firefox
2. Log into YouTube
3. Export cookies
4. Open Settings (gear icon) → Upload cookies.txt

Or the app auto-detects cookies from installed browsers (Firefox, Chrome, Brave, Edge, etc.).

blackpearl/
├── main.py # FastAPI backend
├── requirements.txt # Python deps
├── pyproject.toml # Project config
├── templates/
│ └── index.html # Jinja2 template
├── static/
│ ├── css/style.css # UI styles
│ └── js/app.js # Frontend logic
├── downloads/ # Downloaded files
├── cookies.txt # YouTube session (optional)
├── DESIGN.md # Design system
├── PRODUCT.md # Product brief
└── shape.md # Frontend spec

# Production run
uvicorn main:app --host 0.0.0.0 --port 8046
# Or with gunicorn
pip install gunicorn
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker

MIT