Metadata-Version: 2.4
Name: musicmandu
Version: 1.0.4
Summary: A production-grade YouTube music downloader CLI
Author: Milan Prajapati
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: yt-dlp>=2023.0.0
Requires-Dist: ffmpeg-downloader>=0.1.0

# _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:

```bash
pip install typer rich yt-dlp ffmpeg-downloader
```

---

## 🛠 Usage & Commands

Run the CLI using standard Python execution syntax:

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

### 1. Greet Users (`greet`)

Test the CLI setup or display a custom greeting.

```bash
# 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.

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

### 3. View Built-in Help

Display automatically generated command descriptions, arguments, and flags.

```bash
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.
