youtube-audio-extractor 1.2.1

Extract audio from YouTube videos and playlists, convert to MP3 format

YouTube Audio Extractor

A command-line tool that extracts audio from YouTube videos and playlists, converting them to high-quality MP3 format for use on devices like iPods and other audio players.

Features

• Extract audio from individual YouTube videos
• Process entire YouTube playlists
• Convert to MP3 with selectable quality (128kbps, 192kbps, 320kbps)
• Optional output formats: mp3, m4a, opus, flac, mp4 (video)
• Embed proper metadata (title, artist, album, date)
• Download lyrics as .txt files alongside audio files
• Organize playlist downloads in folders
• Progress tracking and error recovery
• Cross-platform compatibility
• Auto-update support (CLI and Web UI)
• Interactive CLI wizard for guided operations

Installation

Install from PyPI

pip install youtube-audio-extractor

That's it! The package will automatically install all dependencies.

Upgrade

To upgrade to the latest release from PyPI:

macOS/Linux:

pip install --upgrade youtube-audio-extractor

Windows PowerShell:

pip install --upgrade youtube-audio-extractor

If you installed with pipx:

pip install --user pipx
pipx ensurepath
pipx install youtube-audio-extractor

Using a virtual environment (recommended)

Isolate dependencies to avoid conflicts with other Python projects.

macOS/Linux (bash/zsh):

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install youtube-audio-extractor

# Run the CLI
youtube-audio-extractor --help

# Run the Web UI
youtube-audio-extractor-web

Windows (PowerShell):

py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install youtube-audio-extractor

# Run the CLI
youtube-audio-extractor --help

# Run the Web UI
youtube-audio-extractor-web

Alternative with pipx (keeps tools isolated globally):

pip install --user pipx
pipx ensurepath
pipx install youtube-audio-extractor

Prerequisites

Python 3.8 or higher is required. Check your version:

python --version

ffmpeg is required for audio conversion:

• macOS: brew install ffmpeg
• Ubuntu/Debian: sudo apt install ffmpeg
• Windows: Download from ffmpeg.org or use choco install ffmpeg

Verify ffmpeg installation:

ffmpeg -version

Quick Start

1. Install the package:

   pip install youtube-audio-extractor
   

2. Extract audio from a video:

   youtube-audio-extractor "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
   

3. Extract a playlist:

   youtube-audio-extractor "https://www.youtube.com/playlist?list=PLAYLIST_ID"
   

4. Extract with lyrics:

   youtube-audio-extractor --lyrics "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
   

That's it! Your MP3 files will be saved in the downloads folder, and if you use --lyrics, you'll also get .txt files with the song lyrics.

Web UI (no GUI install required)

Run the embedded web interface:

youtube-audio-extractor-web             # defaults to http://127.0.0.1:5000
# or choose a port
YAE_PORT=5051 youtube-audio-extractor-web

Features available in the Web UI:

• Start downloads from URL or search query (non-URL input auto-treated as search)
• Quality/format/output directory
• Filters: min/max duration, include/exclude keywords
• Resume (skip already downloaded)
• Cookies upload (Netscape cookies.txt)
• Batch upload (.txt file), per-line options (e.g. | q=192 | f=m4a | min=120 | include=remix)
• Audio player with lyrics display - Play songs directly in browser with lyrics
• Health check, Stats (pretty last time and format mix), History with direct download links
• Stop running jobs (best-effort)
• Job collapsing - Collapse completed jobs to reduce clutter
• Check Updates - Button to check and install latest version from the Web UI

What's New in 1.2.0

• 🎵 Lyrics functionality - Download lyrics as .txt files with --lyrics
• 🎧 Web UI audio player - Play songs directly in browser with built-in player
• 📝 Lyrics display - View lyrics while playing songs in the Web UI
• 📁 Job collapsing - Collapse completed jobs to reduce clutter
• 🎯 Visual feedback - History buttons show current playing state
• ⬇️ Enhanced downloads - Download files directly from the audio player
• 🔄 Auto-update - CLI flag --check-updates and Web UI "Check Updates" button
• 🧭 Interactive CLI - Launch wizard with --interactive for guided flows

What's New in 1.1.0

• Multiple output formats via -f/--format (mp3, m4a, opus, flac)
• Playlist filtering: --min-duration, --max-duration, --include, --exclude
• Batch processing from file: --urls-file urls.txt
• YouTube search integration: --search with --search-limit
• Resume downloads: --resume to skip already-downloaded items
• Analytics report: --stats
• Health checks: --health
• Optional user config at ~/.youtube-extractor/config.yaml

Legal & Educational Notice

This tool is provided for educational and personal use only. Ensure your use complies with all applicable laws and YouTube's Terms of Service. Only download content you own, have permission to download, or that is in the public domain. The authors assume no liability for misuse.

Built by KetchaLegend.

Usage

Basic Usage

Extract a single video:

youtube-audio-extractor "https://www.youtube.com/watch?v=VIDEO_ID"

Extract a playlist:

youtube-audio-extractor "https://www.youtube.com/playlist?list=PLAYLIST_ID"

Command Options

youtube-audio-extractor [OPTIONS] URL

Options:

• -q, --quality: Audio quality in kbps (128, 192, 320) - default: 320
• -f, --format: Output format (mp3, m4a, opus, flac, mp4) - default: mp3
• -o, --output: Output directory - default: downloads
• --playlist-folder/--no-playlist-folder: Create folders for playlists - default: enabled
• --metadata/--no-metadata: Embed metadata in MP3 files - default: enabled
• --cookie-path: Path to cookies.txt (Netscape format) to pass to yt-dlp
• --search: Treat argument as search query (uses ytsearch)
• --search-limit: Number of results to fetch with --search (default 10, max 50)
• --urls-file: Process multiple URLs from a text file (one per line)
• --min-duration/--max-duration: Filter playlist items by duration (seconds)
• --include/--exclude: Comma-separated title keywords to include/exclude
• --resume: Skip items already downloaded (based on local history)
• --lyrics/--no-lyrics: Download lyrics as .txt files alongside audio files - default: disabled
• --stats: Show download statistics and exit
• --health: Run a health check (deps, output dir) and exit
• --check-updates: Check for a new version and prompt to install
• --interactive, -i: Launch interactive wizard (guided mode)
• -v, --verbose: Enable detailed logging
• -h, --help: Show help message

Examples

High-quality single video:

youtube-audio-extractor -q 320 "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

Playlist to custom directory:

youtube-audio-extractor -o ~/Music/Playlists "https://www.youtube.com/playlist?list=PLrAXtmRdnEQy6nuLMt9xaJGA6H_VjlXEL"
**Search and download top 5 results:**

```bash
youtube-audio-extractor --search --search-limit 5 "rick astley"

Batch process URLs from a file:

youtube-audio-extractor --urls-file urls.txt -q 192 -f m4a

Filter playlist (2-10 minutes, exclude live):

youtube-audio-extractor --min-duration 120 --max-duration 600 --exclude live "https://www.youtube.com/playlist?list=PLAYLIST_ID"

Download with lyrics:

youtube-audio-extractor --lyrics "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

Resume mode (skip already-downloaded):

youtube-audio-extractor --resume "https://www.youtube.com/playlist?list=PLAYLIST_ID"

**Lower quality for faster downloads:**

```bash
youtube-audio-extractor -q 128 -v "https://www.youtube.com/watch?v=VIDEO_ID"

Without metadata embedding:

youtube-audio-extractor --no-metadata "https://www.youtube.com/watch?v=VIDEO_ID"

Custom output directory:

youtube-audio-extractor -q 320 -o ~/Music "https://www.youtube.com/watch?v=VIDEO_ID"

Use cookies to avoid throttling/restrictions:

youtube-audio-extractor --cookie-path /path/to/cookies.txt "https://www.youtube.com/watch?v=VIDEO_ID"

Export cookies from your browser in Netscape format (e.g., using a cookies.txt exporter extension) and pass the file via --cookie-path.

Output Structure

Single Video

downloads/
└── Video_Title.mp3

Playlist

downloads/
└── Playlist_Name/
    ├── Video_1_Title.mp3
    ├── Video_2_Title.mp3
    └── Video_3_Title.mp3

Metadata

The tool automatically embeds the following metadata in MP3 files:

• Title: Video title
• Artist: Channel/uploader name
• Album: Playlist name (for playlist items)
• Date: Upload year
• Duration: Track length

Troubleshooting

Common Issues

1. "ffmpeg not found" error

Error: ffmpeg is not installed or not found in PATH

Solutions:

• Install ffmpeg using your system's package manager
• Ensure ffmpeg is added to your system PATH
• Restart your terminal after installation
• Test with: ffmpeg -version

2. "Permission denied" error

Error: Permission denied when creating output directory

Solutions:

• Check write permissions for the output directory
• Try a different output directory: -o ~/Downloads
• Run with appropriate permissions (avoid sudo if possible)
• Ensure the directory path exists and is accessible

3. "Video unavailable" error

Error: Video is unavailable or private

Solutions:

• Verify the URL is correct and accessible in a browser
• Check if the video is private, unlisted, or region-restricted
• Try a different video to test the tool
• Ensure stable internet connection

4. "Playlist not found" error

Error: Could not retrieve playlist information

Solutions:

• Verify the playlist URL is correct
• Check if the playlist is public (not private)
• Ensure the playlist contains videos
• Try accessing the playlist in a browser first

5. "Network timeout" error

Error: Network timeout during download

Solutions:

• Check your internet connection
• Try again later (YouTube may be temporarily unavailable)
• Use verbose mode (-v) to see detailed error information
• Consider using lower quality (-q 128) for faster downloads

6. "Disk space" error

Error: Insufficient disk space

Solutions:

• Free up disk space on your system
• Choose a different output directory with more space
• Use lower quality settings to reduce file sizes

7. "Invalid URL" error

Error: The provided URL is not a valid YouTube URL

Solutions:

• Ensure the URL starts with https://www.youtube.com/
• Copy the URL directly from your browser
• Remove any extra parameters or tracking information
• Test with a simple video URL first

Getting Help

Enable verbose logging for detailed error information:

youtube-audio-extractor -v "YOUR_URL"

Check system requirements:

python --version    # Should be 3.8+
ffmpeg -version     # Should show ffmpeg information
pip show youtube-audio-extractor  # Check if package is installed

Test with a known working video:

youtube-audio-extractor "https://www.youtube.com/watch?v=jNQXAC9IVRw"

Performance Tips

1. Use appropriate quality settings:

   • 320kbps: Best quality, larger files, slower downloads
   • 192kbps: Good balance of quality and size
   • 128kbps: Smaller files, faster downloads

2. For large playlists:

   • Use verbose mode (-v) to monitor progress
   • Ensure stable internet connection
   • Have sufficient disk space available
   • Consider processing in smaller batches

3. Network optimization:

   • Close other bandwidth-intensive applications
   • Use wired connection when possible
   • Avoid peak usage hours for better speeds

Technical Details

Dependencies

• yt-dlp: YouTube content downloading (actively maintained youtube-dl fork)
• ffmpeg-python: Audio conversion and processing
• mutagen: MP3 metadata manipulation
• click: Command-line interface framework
• Flask: Web UI server
• rich: Interactive CLI UI components

Supported Formats

• Input: Any format supported by yt-dlp (YouTube videos/playlists)
• Output (audio): mp3, m4a, opus, flac
• Output (video): mp4 (keeps video; no audio-only postprocessing)

Quality Settings

• 128kbps: ~1MB per minute of audio
• 192kbps: ~1.4MB per minute of audio
• 320kbps: ~2.4MB per minute of audio

Performance Optimizations

Fast Validation for Large Playlists

For playlists with many videos (50+), use fast validation to skip thorough checking:

youtube-audio-extractor --fast-validation "LARGE_PLAYLIST_URL"

Batch Processing

Process multiple videos with improved performance:

youtube-audio-extractor --batch-size 3 --urls-file urls.txt

Combined Optimizations

For maximum speed on large playlists:

youtube-audio-extractor --fast-validation --batch-size 5 -q 192 "LARGE_PLAYLIST_URL"

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Want to contribute or install from source? Check out the GitHub repository.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

User Configuration

Optional config file at ~/.youtube-extractor/config.yaml:

quality: "192"           # default quality
output_dir: "~/Music"    # default output folder
output_format: "m4a"     # mp3|m4a|opus|flac|mp4
embed_metadata: true

Credits

Created by: KetchaLegend

Legal Disclaimer

IMPORTANT COPYRIGHT NOTICE:

This tool is provided for educational and personal use only. Users are solely responsible for ensuring their use complies with applicable laws and YouTube's Terms of Service.

Copyright Responsibility

• User Responsibility: Users are entirely responsible for respecting copyright laws and intellectual property rights
• No Liability: The developers assume no responsibility for any copyright infringement or illegal use of this tool
• Content Ownership: Only download content you own, have permission to download, or that is in the public domain
• Terms of Service: Users must comply with YouTube's Terms of Service and any applicable platform policies

Prohibited Uses

• Downloading copyrighted content without permission
• Commercial use of downloaded content without proper licensing
• Violating YouTube's Terms of Service
• Any illegal distribution or use of downloaded content

Legal Compliance

By using this tool, you acknowledge that:

1. You are solely responsible for your actions and any legal consequences
2. You will only download content you have the right to download
3. You understand and accept all copyright and legal risks
4. The developers are not liable for any misuse of this software

USE AT YOUR OWN RISK. RESPECT COPYRIGHT LAWS.