musicmandu 1.0.5

A production-grade YouTube music downloader CLI

musicmandu

musicmandu is a production-grade, zero-configuration command-line interface (CLI) tool written in Python. It allows users to seamlessly download high-quality audio from YouTube videos and automatically process them into fully tagged, album-art-embedded MP3 files.

---

Features

• Zero Manual Dependencies: Automatically detects, downloads, and caches the correct system-specific FFmpeg binaries at runtime—even when Windows user paths contain spaces.
• High-Quality Audio: Downloads the best available audio stream and converts it into a clean 192 kbps MP3 file.
• Rich Metadata Integration: Automatically extracts and embeds metadata such as the title and creator, then downloads and embeds the video's high-resolution thumbnail as album art.
• Sleek Visual Feedback: Uses Rich console components to replace noisy console output with clean status spinners and styled messages.

---

Installation & Prerequisites

Requirements

• Python 3.10 or later
• pip or pipx

FFmpeg does not need to be installed manually. musicmandu automatically downloads and configures a compatible FFmpeg binary when required.

Install with pipx — Recommended

pipx installs the CLI in an isolated environment and makes the musicmandu command available globally.

pipx install musicmandu

If pipx is not installed:

python -m pip install --user pipx
python -m pipx ensurepath

Restart your terminal after running ensurepath, then install:

pipx install musicmandu

Install with pip

python -m pip install musicmandu

Verify the installation:

musicmandu --help

Upgrade

With pipx:

pipx upgrade musicmandu

With pip:

python -m pip install --upgrade musicmandu

---

🛠 Usage & Commands

After installation, run musicmandu directly from your terminal:

musicmandu [COMMAND] [ARGUMENTS] [OPTIONS]

Greet Users

musicmandu greet Milan

Formal greeting:

musicmandu greet "Mr. Wayne" --formal

Download Tracks

musicmandu download "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

Full YouTube URLs containing playlist or radio parameters are also supported:

musicmandu download "https://www.youtube.com/watch?v=LNOGXL3Nvqs&list=RDLNOGXL3Nvqs&start_radio=1"

View Help

musicmandu --help
musicmandu download --help
musicmandu greet --help

---

Architecture & Under the Hood

The application relies on three core frameworks to provide a seamless user experience:

• Typer: Powers command parsing, argument handling, flags, and dynamically generated help screens.
• Rich: Manages styled terminal output, layout, and responsive loading indicators.
• yt-dlp and ffmpeg-downloader: Handle the download and processing pipeline, including metadata extraction, high-bitrate audio retrieval, thumbnail downloading, and FFmpeg-based MP3 conversion.

How yt-dlp and FFmpeg Work Together

YouTube never stores music as standard MP3 files. To save internet bandwidth, YouTube splits videos into separate streams (one stream for just the video, and one stream for just the audio) and compresses them into modern, web-optimized formats like .webm or .m4a.

Because of this, yt-dlp cannot just "download an MP3" from YouTube—the MP3 file literally does not exist on YouTube's servers.

This is where the teamwork happens:

Plaintext

[YouTube Servers]
       │
       ▼ (Downloads raw .webm/.m4a stream)
┌──────────────┐
│   yt-dlp     │  <─── Role: The Courier (Fetches the raw files)
└──────┬───────┘
       │
       ▼ (Hands raw file + thumbnail + title)
┌──────────────┐
│   FFmpeg     │  <─── Role: The Factory Worker (Converts & polishes)
└──────┬───────┘
       │
       ▼ (Outputs a perfect, tagged asset)
[ Finished .mp3 File ]

Step 1: yt-dlp acts as the "Courier"

When you pass a URL to your musicmandu tool, yt-dlp connects to YouTube. It bypasses the website restrictions, scans the background metadata, and downloads two things:

1. The highest-quality raw audio stream available (usually a .webm or .m4a file).
2. The high-resolution video thumbnail image file.

Step 2: yt-dlp hands the files to FFmpeg

Once the download is complete, yt-dlp looks at the configuration you wrote in your Python script ('preferredcodec': 'mp3'). It realizes the file is a web-format and needs to become an MP3.

yt-dlp automatically wakes up FFmpeg in the background and hands it three raw items:

• The raw audio file (.webm)
• The image file (.jpg)
• The text data (Song Title and Artist Name)

Step 3: FFmpeg acts as the "Factory Worker"

FFmpeg takes those pieces and performs three rapid tasks in milliseconds:

1. Extraction/Conversion: It decodes the .webm audio and re-encodes it into a high-quality 320kbps MP3 stream.
2. Metadata Tagging: It writes the Artist name and Song Title directly into the hidden data layer of the audio file.
3. Artwork Embedding: It takes the thumbnail image, shrinks it, and literally glues it inside the MP3 file as the album cover.

Step 4: Clean up

Once FFmpeg finishes creating the perfect .mp3 file, yt-dlp deletes the temporary raw files it originally downloaded, leaving you with just a clean, beautiful, ready-to-play music file in your folder.

Runtime Dependency Sandbox

When the download command is invoked, the application runs a gatekeeper function named ensure_ffmpeg_installed.

If a valid FFmpeg installation cannot be found in the system path, the application downloads and caches a platform-specific FFmpeg binary. It then maps the binary into the current process environment without modifying the user's global system configuration.

---

License

Distributed under the MIT License. See LICENSE for more information.