🌟 Interactive Studio UI

Experience a terminal workflow inspired by modern developer tooling. No complex CLI flags required — simply run python main.py or dus-yt-music-dl (or yt-music-dl):

┌─────────────────────────────────────────────────────────────────────────────┐
│                                                                             │
│  ██████╗  ██╗   ██╗ ███████╗                                                │
│  ██╔══██╗ ██║   ██║ ██╔════╝                                                │
│  ██║  ██║ ██║   ██║ ███████╗                                                │
│  ██║  ██║ ██║   ██║ ╚════██║                                                │
│  ██████╔╝ ╚██████╔╝ ███████║                                                │
│  ╚═════╝   ╚═════╝  ╚══════╝                                                │
│                                                                             │
│  🎵 DUS YouTube Music Studio Pro CLI | Android Client Profile                │
│  Personal Content Archival • 1:1 Square Art                                 │
│  Output Destination: downloads/                                             │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Enter YouTube Music Track / Playlist URL: https://music.youtube.com/watch?v=...

╭─ Track Identified ──────────────────────────────────────────────────────────╮
│ 🎵 Title    : Creator Original Track (Independent Release)                  │
│ 🎤 Artist   : Your Channel / Independent Artist                             │
│ ⏱️ Duration : 3:45                                                          │
│ 🔗 URL      : https://music.youtube.com/watch?v=...                         │
╰─────────────────────────────────────────────────────────────────────────────╯

Step 1: Choose Audio Format
  [1] MP3   - Universal Compatibility (320k, 256k, 192k, 128k) [Default]
  [2] M4A   - Pristine Apple AAC (Native 129k Stream Copy / 256k)
  [3] FLAC  - Lossless PCM Uncompressed (Studio Quality)
  [4] OPUS  - Next-Gen High-Efficiency Audio

Step 2: Choose Audio Quality / Bitrate
  [1] 320 kbps (Best Quality) [Default]
  [2] 256 kbps (High Quality)
  [3] 192 kbps (Medium Quality - Matches YouTube Source)
  [4] 128 kbps (Low Quality - Compact)
  [5] ALL 4 QUALITIES (320k + 256k + 192k + 128k in one pass!)

✨ Multi-Quality Download Summary
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Filename                            ┃ Bitrate ┃ Filesize ┃ Cover Art              ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Creator-Original-Song-320kbps.mp3   │  320k   │  8.60 MB │ 1:1 Square (1200x1200) │
│ Creator-Original-Song-256kbps.mp3   │  256k   │  6.88 MB │ 1:1 Square (1200x1200) │
│ Creator-Original-Song-192kbps.mp3   │  192k   │  5.16 MB │ 1:1 Square (1200x1200) │
│ Creator-Original-Song-128kbps.mp3   │  128k   │  3.44 MB │ 1:1 Square (1200x1200) │
└─────────────────────────────────────┴─────────┴──────────┴────────────────────────┘

🚀 Key Features

⚡ Quick Start

1. Prerequisites Check

Ensure Python 3.10+, FFmpeg, and Node.js are installed:

# Windows (PowerShell via winget)
winget install Python.Python.3.11 Gyan.FFmpeg OpenJS.NodeJS.LTS

# macOS (Homebrew)
brew install python@3.11 ffmpeg node

# Linux (Ubuntu / Debian)
sudo apt update && sudo apt install -y python3 python3-pip ffmpeg nodejs

# Android (Termux App)
pkg update && pkg install -y python ffmpeg nodejs clang libjpeg-turbo
termux-setup-storage

2. Installation

📦 Option A: Install from PyPI (Recommended & Easiest)

Install globally in one command directly from PyPI (Windows, macOS, Linux, or Android Termux):

pip install --upgrade dus-yt-music-dl

🛠️ Option B: Install from Source (Developer Mode)

# Clone the repository
git clone https://github.com/dusmamud/youtube-music-downloader.git
cd youtube-music-downloader

# Install dependencies and register CLI command in editable mode
pip install -r requirements.txt
pip install -e .

3. Run Studio Dashboard

# Run the global CLI tool directly from any terminal
dus-yt-music-dl

# (yt-music-dl alias also supported)
# yt-music-dl

# Or run via local repository script
python main.py

💻 CLI Cheat Sheet

For automated scripts, batch jobs, and command-line power users:

1. Basic Single Song Download (Android Client Mode)

python main.py "https://music.youtube.com/watch?v=YOUR_OWN_TRACK_ID"

2. 4-in-1 Multi-Bitrate Download (320k + 256k + 192k + 128k)

python main.py "https://music.youtube.com/watch?v=YOUR_OWN_TRACK_ID" -m

3. Studio Quality Lossless FLAC or Native OPUS

# Lossless Studio PCM FLAC
python main.py "https://music.youtube.com/watch?v=YOUR_OWN_TRACK_ID" -f flac

# Native Lightweight OPUS (~141 kbps)
python main.py "https://music.youtube.com/watch?v=YOUR_OWN_TRACK_ID" -f opus

4. Batch Download Entire Playlists or Albums

python main.py "https://music.youtube.com/playlist?list=YOUR_PLAYLIST_ID" --batch -f mp3 -q 320k

5. Inspect Stream Formats (-F)

python main.py "https://music.youtube.com/watch?v=YOUR_OWN_TRACK_ID" -F

6. Authenticate with Browser Cookies (For Your Private Playlists)

# Using Firefox (Recommended on Windows)
python main.py "URL" --browser firefox

# Using Chrome or Edge
python main.py "URL" --browser chrome

# Using custom cookies.txt
python main.py "URL" --cookies "C:\path\to\cookies.txt"

7. Filename Schemes (clean vs formal)

# Clean (Default: Artist-Title-320kbps.mp3 - OS Safe)
python main.py "URL" -n clean

# Formal (Artist - Title (320kbps).mp3)
python main.py "URL" -n formal

8. Dry-Run Extraction Simulation (Zero Disk Writes)

python main.py "https://music.youtube.com/watch?v=YOUR_OWN_TRACK_ID" --dry-run

🏗️ Architecture

The diagram below illustrates the resilient download and transcoding lifecycle:

graph TD
    A["YouTube Music URL"] --> B{"Authentication Mode"}
    B -->|"Default (Cookie-Free)"| C["InnerTube Android Client Emulation<br/>(Pixel 8 / Galaxy S24 / OnePlus 12)"]
    B -->|"Browser Session"| D["Firefox / Chrome / Edge Cookie SQLite"]
    B -->|"cookies.txt"| E["Netscape Format Cookie File"]

    C & D & E --> F["Node.js Challenge Sandbox<br/>(Solves JS n-sig signatures)"]
    F --> G["Raw Native Stream Extraction<br/>(Opus 251 @ 141kbps / AAC 140 @ 129kbps)"]

    G --> H{"Processing Pipeline"}
    H --> I["Pillow Image Engine<br/>(1:1 Center-Crop 1200x1200 JPEG)"]
    H --> J["FFmpeg Audio Engine<br/>(MP3 320k / M4A / FLAC / OPUS)"]

    I & J --> K["Mutagen Metadata Injector<br/>(ID3v2.3 Title, Artist, Album, Year, APIC Art)"]
    K --> L["Final Library Output<br/>(downloads/Artist-Title-320kbps.mp3)"]

📚 Documentation Hub

Explore the complete documentation for setup instructions, troubleshooting, and API usage:

📁 Repository Structure

youtube-music-downloader/
├── main.py                        # Root launcher (100% backward-compatible)
├── downloader.py                  # Legacy backward-compatibility bridge
├── interactive.py                 # Legacy backward-compatibility bridge
├── config.py                      # Legacy backward-compatibility bridge
├── utils.py                       # Legacy backward-compatibility bridge
├── pyproject.toml                 # Modern PEP 621 packaging & CLI entry point
├── requirements.txt               # Package runtime dependencies
├── README.md                      # Primary project documentation
├── TEST_GUIDE.md                  # Developer & test suite guide
├── docs/                          # Detailed In-Depth Documentation
│   ├── INSTALLATION.md            # Comprehensive OS setup guide
│   ├── USAGE.md                   # CLI flag matrix & Python API guide
│   └── TROUBLESHOOTING.md         # Diagnostic flowchart & error resolutions
├── downloads/                     # Default output destination
├── tests/                         # Dedicated automated test suite
│   ├── __init__.py
│   └── test_downloader.py         # 8 comprehensive integration test cases
├── test_download.py               # Root backward-compatible test runner
└── yt_music_dl/                   # Core Modular Python Package
    ├── __init__.py                # Package exports (__version__ = "1.1.0")
    ├── config.py                  # Centralized configuration & device pools
    ├── cli.py                     # Argument parser & command router
    ├── core/                      # Core Business Logic Layer
    │   ├── __init__.py
    │   ├── downloader.py          # YtMusicDownloader engine & transcode pipeline
    │   ├── metadata.py            # 1:1 Square album art crop & ID3v2.3 tagger
    │   └── device_profiler.py     # Android InnerTube mobile device spoofing
    ├── ui/                        # User Interface Layer
    │   ├── __init__.py
    │   ├── interactive.py         # CloudCode-style interactive REPL studio
    │   └── banner.py              # Visual presentation & format tables
    └── utils/                     # Modular System Utilities
        ├── __init__.py
        ├── system.py              # Dependency verification & browser detection
        ├── formatters.py          # Clean vs Formal filename formatters
        └── cleanup.py             # Temporary file cleanup routines

🧪 Testing & Verification

Run the automated test suite before committing changes:

# Run package test suite:
python -m unittest discover tests

# Or run root legacy tests:
python test_download.py

• Dependency Check: Verifies yt-dlp, ffmpeg, and node on PATH.
• Parser & Options: Tests flag parsing and _build_ydl_opts generation across all 3 auth modes.
• Android Profiler: Asserts realistic device generation (Google Pixel, Samsung Galaxy, OnePlus).
• Dry-Run Simulation: Simulates live YouTube extraction with zero disk contamination.
• Teardown Cleanup: Asserts .part and .ytdl files are purged on test finish.

💡 For comprehensive test execution and writing new test cases, see TEST_GUIDE.md.

🔧 Troubleshooting Quick Reference

💡 For complete diagnostics and advanced scenarios, see docs/TROUBLESHOOTING.md.

⚖️ Legal Disclaimer & Terms of Use

This software is strictly intended as a personal media backup utility and educational tool for:

1. Content Creators: Archiving your own original musical tracks and audio previously uploaded to YouTube.
2. Public Domain & Creative Commons: Downloading tracks that are explicitly released under open licenses (CC-BY, CC0, Public Domain).
3. Fair Use Research: Transformative educational analysis under Section 107 of the U.S. Copyright Act.

Non-Circumvention Statement: This software does NOT circumvent or decrypt DRM technologies (Widevine, FairPlay). The authors and contributors do not host or distribute copyrighted media and assume zero liability for user actions. Please read the full DISCLAIMER.md.

📄 License

Distributed under the MIT License. See LICENSE for details.