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

• ⚡ Lightning-Fast Short Command: No more typing out long commands. Just hit mdu to launch.
• 🎮 Fully Interactive Menu: Uses arrow keys and interactive prompts—no complex flags required for regular use.
• 🎬 Video & Audio Support: Toggle seamlessly between high-bitrate MP3 Audio (320 kbps) and crisp MP4 Video.
• Zero Manual Dependencies: Automatically detects, downloads, and caches the correct system-specific FFmpeg binaries at runtime—even when Windows user paths contain spaces.
• Rich Metadata Integration: (Audio Mode) Automatically extracts and embeds metadata, 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:

mdu --help

Upgrade

With pipx:

pipx upgrade musicmandu

With pip:

python -m pip install --upgrade musicmandu

🛠 Usage & Commands

1. The Interactive Way (Recommended)

Simply type the 3-letter command and hit Enter. An interactive guide will appear, letting you navigate options using your keyboard's arrow keys:

mdu

  MusicMandu CLI
──────────────────────────────────────────────────

? Welcome to MusicMandu! What would you like to do?
  1. Greet User
❯ 2. Audio Download (MP3)
  3. Video Download (MP4)
  4. Exit

2. The Power-User Way (Direct Commands)

If you are in a rush or writing a script, you can completely bypass the menus by supplying arguments directly.

Audio Download (Default)

mdu download "[https://www.youtube.com/watch?v=dQw4w9WgXcQ](https://www.youtube.com/watch?v=dQw4w9WgXcQ)"

Video Download

Force a video download by appending the --video or -v flag:

mdu download "[https://www.youtube.com/watch?v=dQw4w9WgXcQ](https://www.youtube.com/watch?v=dQw4w9WgXcQ)" --video
# or
mdu download "[https://www.youtube.com/watch?v=dQw4w9WgXcQ](https://www.youtube.com/watch?v=dQw4w9WgXcQ)" -v

Greet Users

mdu greet Milan

View Help

mdu --help
mdu download --help
mdu 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.
• Questionary: Drives the premium, user-friendly interactive terminal prompts and menus.
• 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.