TruMusic 1.4.7

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_..."

Plain video links are also accepted — TruMusic will look up the song and suggest matching albums:

trumusic -l "https://www.youtube.com/watch?v=VIDEO_ID"

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

Authentication is optional for most content. TruMusic will prompt you to set up authentication only when downloading age-restricted or members-only content.

When Authentication is Needed

If you encounter age-restricted tracks, TruMusic will offer to set up browser authentication:

1. Open https://music.youtube.com and log in
2. Open Developer Tools (F12 or Cmd+Option+I)
3. Go to the Network tab
4. Click any request to music.youtube.com
5. Find Cookie in Request Headers and copy the value
6. Paste when prompted

The credentials are saved to ~/.config/ytmusicapi/browser.json and are valid for ~2 years.

Alternative: Cookie File

You can also provide cookies via a file:

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.