yt-audio-cli

A simple command-line tool for downloading audio from YouTube and other sites.

What This Is

yt-audio-cli is an opinionated wrapper around yt-dlp and FFmpeg, designed specifically for audio downloads. It provides sensible defaults and a streamlined interface for common audio extraction tasks.

• yt-dlp handles all video/audio downloading and site support (1000+ sites)
• FFmpeg handles audio conversion and processing
• yt-audio-cli ties them together with audio-focused defaults and a simplified CLI

If you need advanced features like video downloads, custom format selection, or fine-grained control, use yt-dlp directly.

Quick Start

# Install
pip install yt-audio-cli

# Download audio
yt-audio-cli https://youtube.com/watch?v=VIDEO_ID

Requirements

FFmpeg must be installed on your system for audio conversion:

• Windows: winget install FFmpeg or download from ffmpeg.org
• macOS: brew install ffmpeg
• Linux: sudo apt install ffmpeg (Debian/Ubuntu) or sudo dnf install ffmpeg (Fedora)

yt-dlp is installed automatically as a Python dependency.

Installation

pip install yt-audio-cli

Or with uv:

uv tool install yt-audio-cli

Usage

Download Audio

# Single video (saves as MP3 by default)
yt-audio-cli https://youtube.com/watch?v=VIDEO_ID

# Multiple videos (downloaded in parallel)
yt-audio-cli URL1 URL2 URL3

# Entire playlist
yt-audio-cli https://youtube.com/playlist?list=PLAYLIST_ID

# From a batch file (one URL per line)
yt-audio-cli --batch urls.txt

Choose Format

yt-audio-cli -f opus URL   # Opus (smallest size)
yt-audio-cli -f aac URL    # AAC
yt-audio-cli -f mp3 URL    # MP3 (default)
yt-audio-cli -f wav URL    # WAV (lossless)

Choose Quality

yt-audio-cli -q best URL    # Highest quality (default)
yt-audio-cli -q good URL    # Balanced
yt-audio-cli -q small URL   # Smallest file size

# Or set exact bitrate (32-320 kbps)
yt-audio-cli -b 256 URL

Save Location

# Save to specific folder
yt-audio-cli -o ~/Music URL

# Default: current directory

Skip Metadata

# Don't embed title/artist in the file
yt-audio-cli --no-metadata URL

Parallel Downloads

# Use 8 concurrent workers (default: 4)
yt-audio-cli -w 8 URL1 URL2 URL3

# Single-threaded download
yt-audio-cli -w 1 URL

Batch File

# Download from a file containing URLs (one per line)
yt-audio-cli --batch urls.txt

# Combine batch file with additional URLs
yt-audio-cli --batch urls.txt https://youtube.com/watch?v=EXTRA

Batch file format:

# Comments start with #
https://youtube.com/watch?v=VIDEO1
https://youtube.com/watch?v=VIDEO2

# Blank lines are ignored
https://youtube.com/watch?v=VIDEO3

Retry Failed Downloads

# Retry failed downloads up to 5 times (default: 3)
yt-audio-cli -r 5 URL

# Disable retries
yt-audio-cli -r 0 URL

Options

Option	Short	Description	Default
--format	-f	Audio format (mp3, aac, opus, wav)	mp3
--output	-o	Output directory	Current dir
--quality	-q	Quality preset (best, good, small)	best
--bitrate		Exact bitrate in kbps (32-320)	-
--workers	-w	Concurrent download workers (1-16)	4
--retries	-r	Retry attempts for failures (0-10)	3
--batch	-b	Path to file containing URLs	-
--no-metadata		Skip embedding metadata	-
--force	-F	Re-download even if file exists	-
--version	-v	Show version	-
--help		Show help	-

Note: By default, files that already exist in the output directory are skipped. Use --force to re-download them.

Troubleshooting

"FFmpeg not found" Install FFmpeg using the instructions in Requirements.

"Video unavailable" The video may be private, age-restricted, or region-locked. This is a limitation of the source site, not yt-dlp or this tool.

"Signature solving failed" / JS challenge warnings YouTube uses JavaScript challenges to protect some video formats. You may see warnings like:

yt-dlp: [youtube] Signature solving failed: Some formats may be missing.

Downloads usually still work (yt-dlp falls back to alternative formats), but to resolve these warnings:

• Install Deno (recommended): curl -fsSL https://deno.land/install.sh | sh
• Or download the solver: yt-dlp --remote-components ejs:github

See yt-dlp EJS wiki for more details.

Download fails Check your internet connection and verify the URL is correct. If the issue persists, ensure yt-dlp is up to date: pip install -U yt-dlp

Metadata

__metadata__ = {
    "name": "yt-audio-cli",
    "version": "0.2.2",
    "author": "pyyupsk",
    "license": "MIT",
    "python": ">=3.12",
    "repository": "github.com/pyyupsk/yt-audio-cli",
}

Disclaimer

[!IMPORTANT] This tool is intended for downloading content you have the right to access. Respect copyright laws and the terms of service of the platforms you use.

[!CAUTION] The authors are not responsible for any misuse of this software.

License

This project is licensed under the MIT License.