musicmandu 1.0.1

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

musicmandu runs on Windows, macOS, and Linux.

1. Requirements

• Python 3.8 or later

2. Set Up the Project

Clone or navigate to the project directory, then install the required Python packages:

pip install typer rich yt-dlp ffmpeg-downloader

---

🛠 Usage & Commands

Run the CLI using standard Python execution syntax:

python main.py [COMMAND] [ARGUMENTS] [FLAGS]

1. Greet Users (greet)

Test the CLI setup or display a custom greeting.

# Standard greeting
python main.py greet Milan

# Formal greeting
python main.py greet "Mr. Wayne" --formal

2. Download Tracks (download)

Download audio and save a formatted MP3 file in the current working directory.

python main.py download "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

3. View Built-in Help

Display automatically generated command descriptions, arguments, and flags.

python main.py --help
python main.py download --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.