Metadata-Version: 2.4
Name: TruMusic
Version: 1.4.11
Summary: Audio file auto-tagger
Author-email: Jacob Truman <jacob.truman@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/jacobtruman/TruMusic
Project-URL: Documentation, https://github.com/jacobtruman/TruMusic
Project-URL: Repository, https://github.com/jacobtruman/TruMusic
Project-URL: Issues, https://github.com/jacobtruman/TruMusic/issues
Keywords: music,audio,tagging,youtube,download
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mutagen>=1.45
Requires-Dist: requests>=2.28
Requires-Dist: ytmusicapi<2.0,>=1.9
Requires-Dist: yt-dlp>=2024.0.0
Requires-Dist: TruLogger>=1.0
Requires-Dist: ascii_magic>=2.3
Requires-Dist: rich>=13.0
Requires-Dist: tomli>=2.0; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: types-requests>=2.28; extra == "dev"

[![CI/CD](https://github.com/jacobtruman/TruMusic/actions/workflows/python-publish.yml/badge.svg)](https://github.com/jacobtruman/TruMusic/actions/workflows/python-publish.yml)
[![PyPI version](https://badge.fury.io/py/TruMusic.svg)](https://badge.fury.io/py/TruMusic)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

# 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

```bash
pip install TruMusic
```

### Requirements

- Python 3.10+
- FFmpeg (for audio conversion)

#### Installing FFmpeg

**macOS:**
```bash
brew install ffmpeg
```

**Ubuntu/Debian:**
```bash
sudo apt install ffmpeg
```

**Windows:**
Download from [ffmpeg.org](https://ffmpeg.org/download.html) and add to PATH.

## Usage

### Download an Album

Search by artist and album name:
```bash
trumusic -a "artist name" -t "album title"
```

Or use a direct YouTube Music album link:
```bash
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):
```bash
trumusic -l "https://www.youtube.com/watch?v=VIDEO_ID"
```

### Interactive Mode

Just run without arguments to be prompted:
```bash
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:
```bash
trumusic_cleanup
```

## Configuration

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

```toml
# 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:
```bash
trumusic -a "artist" --cookies-from-browser chrome
```

Or set it in your config file:
```toml
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

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

### Running Tests

```bash
pytest
```

### Linting

```bash
ruff check .
ruff format .
```

## License

MIT License - see [LICENSE](LICENSE) for details.

## Contributing

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