TruMusic 1.3.12

Audio file auto-tagger

TruMusic

A command-line utility for downloading music from YouTube Music and automatically tagging audio files with metadata and album artwork.

Features

• Download albums from YouTube Music with a simple search or direct link
• Automatic ID3/MP4 tagging with artist, album, track info, and cover art
• Beautiful terminal UI with progress tracking
• Support for MP3 and M4A formats
• Retry logic for failed downloads
• Dry-run mode for testing
• Configurable via config file

Installation

pip install TruMusic

Requirements

• Python 3.10+
• FFmpeg (for audio conversion)

Installing FFmpeg

macOS:

brew install ffmpeg

Ubuntu/Debian:

sudo apt install ffmpeg

Windows: Download from ffmpeg.org and add to PATH.

Usage

Download an Album

Search by artist and album name:

trumusic -a "artist name" -t "album title"

Or use a direct YouTube Music album link:

trumusic -l "https://music.youtube.com/playlist?list=OLAK5uy_..."

Interactive Mode

Just run without arguments to be prompted:

trumusic

Options

-a, --artist              Filter by artist name
-t, --title               Filter by album title (optional)
-l, --link                Direct YouTube Music album/playlist link
-f, --file_format         Output format: mp3 or m4a (default: mp3)
-d, --dry_run             Preview without downloading
-q, --quiet               Skip prompts, use defaults
-v, --verbose             Enable verbose logging
--cookies-from-browser    Extract cookies from browser (local machine only)
                          Supported: chrome, firefox, safari, edge, brave, opera, chromium

Clean Existing Tags

Remove and normalize tags on existing audio files in the current directory:

trumusic_cleanup

Configuration

Create ~/.config/trumusic/config.toml for persistent settings:

# TruMusic Configuration

base_dest_dir = "~/Music/TruMusic"
oauth_file = "~/.config/ytmusicapi/oauth.json"
cookie_file = "~/.config/yt-dlp/cookies.txt"
default_format = "mp3"
max_retries = 3
request_timeout = 30
retry_delay = 5

# Browser to extract cookies from (for age-restricted content)
# Only works when running locally, not on remote servers
# cookies_from_browser = "chrome"

# OAuth credentials (REQUIRED)
# Get these from Google Cloud Console - see Authentication section below
oauth_client_id = "your-client-id.apps.googleusercontent.com"
oauth_client_secret = "your-client-secret"

Age-Restricted Content

Some tracks require YouTube authentication to download (age-restricted or explicit content). TruMusic will automatically detect these and provide instructions.

Option 1: Cookie File (works on remote servers)

1. Install a browser extension to export cookies:

   • Chrome: "Get cookies.txt LOCALLY" or "EditThisCookie"
   • Firefox: "cookies.txt"

2. Log into YouTube/YouTube Music in your browser

3. Export cookies for youtube.com to a file

4. Copy the file to ~/.config/yt-dlp/cookies.txt (or specify a custom path in config)

Option 2: Browser Cookies (local machine only)

Use the --cookies-from-browser flag:

trumusic -a "artist" --cookies-from-browser chrome

Or set it in your config file:

cookies_from_browser = "chrome"

Supported browsers: chrome, firefox, safari, edge, brave, opera, chromium

Authentication

TruMusic requires OAuth credentials to access YouTube Music. You'll need to set this up once:

1. Create OAuth Credentials

1. Go to Google Cloud Console
2. Create a new project (or select an existing one)
3. Enable the YouTube Data API v3
4. Go to Credentials > Create Credentials > OAuth client ID
5. Select TVs and Limited Input devices as the application type
6. Copy the Client ID and Client Secret

2. Configure TruMusic

Add your credentials to ~/.config/trumusic/config.toml:

oauth_client_id = "your-client-id.apps.googleusercontent.com"
oauth_client_secret = "your-client-secret"

3. Authenticate

On first run, TruMusic will open a browser window to authenticate with YouTube Music. The OAuth token is saved to ~/.config/ytmusicapi/oauth.json.

For age-restricted content, you may need to provide cookies:

1. Export cookies from your browser using an extension
2. Save to ~/.config/yt-dlp/cookies.txt

Development

Setup

git clone https://github.com/jacobtruman/TruMusic.git
cd TruMusic
pip install -e ".[dev]"

Running Tests

pytest

Linting

ruff check .
ruff format .

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.