Metadata-Version: 2.4
Name: musicmandu
Version: 1.0.7
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
Requires-Dist: questionary>=2.0.0
Requires-Dist: pyfiglet>=1.0.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.

---

<img width="1120" height="455" alt="image" src="https://github.com/user-attachments/assets/b4a4d305-b57c-4d7c-b954-b5ed1b982eac" />


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

```bash
pipx install musicmandu
```

If `pipx` is not installed:

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

Restart your terminal after running `ensurepath`, then install:

```bash
pipx install musicmandu
```

### Install with `pip`

```bash
python -m pip install musicmandu
```

Verify the installation:

```bash
mdu --help
```

### Upgrade

With `pipx`:

```bash
pipx upgrade musicmandu
```

With `pip`:

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

```Bash
mdu
```

```Plaintext
  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)

```Bash
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:

```Bash
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

```Bash
mdu greet Milan
```

### View Help

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