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 resolve it to its album (or to a 1-track "single" album for standalone releases):
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)
-
Install a browser extension to export cookies:
- Chrome: "Get cookies.txt LOCALLY" or "EditThisCookie"
- Firefox: "cookies.txt"
-
Log into YouTube/YouTube Music in your browser
-
Export cookies for youtube.com to a file
-
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:
- Open https://music.youtube.com and log in
- Open Developer Tools (F12 or Cmd+Option+I)
- Go to the Network tab
- Click any request to music.youtube.com
- Find Cookie in Request Headers and copy the value
- 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:
- Export cookies from your browser using an extension
- 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.
1 maintainer
Metadata
1 maintainer
Release files for TruMusic 1.4.15
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| trumusic-1.4.15.tar.gz | 31.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| trumusic-1.4.15-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 57.0 kB
Release files / trumusic-1.4.15.tar.gz
| Download URL | trumusic-1.4.15.tar.gz |
|---|---|
| Size | 31.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
af2c177455e2869201551220ea9419599e56352e27ae9d7ff30e32e8a8e5017b
|
|
BLAKE2b-256 checksum How to use checksums |
7efd97262fba034dc81d12f00562bd79bcbf1bf01780d070a7729bd9ef711432
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 14, 2026.
Transparency logRelease files / trumusic-1.4.15-py3-none-any.whl
| Download URL | trumusic-1.4.15-py3-none-any.whl |
|---|---|
| Size | 25.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
aebc6c0ec0c0bc8c0152d5cda654e21a4b2530e6d3a91516d005358db3ffc42d
|
|
BLAKE2b-256 checksum How to use checksums |
612d26b913b4452f785c559ca12ebb261cb4c3a233c13073561393b2ec3e140c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 14, 2026.
Transparency log
