YouTube Music Downloader GUI

🎵 A modern, native-looking macOS GUI application for downloading music from YouTube with comprehensive metadata support

Built with Python and CustomTkinter, featuring integration with the existing CLI-Music-Downloader backend.

✨ Features

Core Functionality

🔍 Smart Search: Search YouTube by song name and choose from multiple results
📋 Playlist Support: Download entire playlists with track selection
🎨 Modern GUI: Clean, native macOS look using CustomTkinter
⚙️ Quality Selection: Choose audio quality (Best, 320, 256, 192, 128 kbps)
📊 Progress Tracking: Real-time progress bars with speed and ETA
⏸️ Pause/Resume: Full control over downloads with pause and resume capability

Metadata & Organization

🏷️ Comprehensive Metadata: Auto-tag with artist, title, album, year, genre, track numbers
🎵 Multi-Source: MusicBrainz, Shazam, Genius, Last.fm, Discogs integration
📝 Lyrics Support: Automatic lyrics fetching and embedding
🖼️ Album Art: High-quality artwork from iTunes API and Google Images
📁 Smart Organization: Saves to ~/Music/<Artist-Name>/<Song>.mp3
✏️ Metadata Editor: Manual editing of tags and album art

Advanced Features

🔄 Download Queue: Manage multiple downloads with queue system
🔔 Notifications: macOS system notifications for completed downloads
🎚️ Configurable: Extensive settings for download behavior and metadata sources
💾 State Persistence: Resume downloads after app restart
🔐 Duplicate Handling: Skip, overwrite, or rename duplicate files
⌨️ Keyboard Shortcuts: Cmd+F, Cmd+D, Cmd+P, Cmd+, (settings)

🚀 Installation

Prerequisites

macOS 10.15+ (Catalina or later)
Python 3.12+ (via pyenv)
Homebrew
System dependencies: ffmpeg, aria2, terminal-notifier

Quick Start

# 1. Install system dependencies
brew install ffmpeg aria2 terminal-notifier

# 2. Clone the repository
git clone https://github.com/jordolang/YouTube-Music-Downloader-GUI.git
cd YouTube-Music-Downloader-GUI

# 3. Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate

# 4. Install Python dependencies
pip install -r requirements.txt

# 5. Install CLI Music Downloader backend (if not already installed)
pip install -e ~/Repos/CLI-Music-Downloader

# 6. Run the application
python launcher.py

📖 Usage

Basic Workflow

Search for Music
- Type song name in search bar
- Press Enter or click Search button
- Select from multiple YouTube results
Configure Download
- Choose audio quality from dropdown
- Review estimated file size
- Select tracks (for playlists)
Download
- Click "Download" to start
- Monitor progress in Download Queue tab
- Pause/resume/cancel as needed
Access Your Music
- Files saved to ~/Music/<Artist>/
- Complete with metadata, lyrics, and album art

Playlist Downloads

Switch to "Playlist" tab
Paste YouTube playlist URL
Select individual tracks or "Select All"
Click "Download Selected"

Settings

Access via Cmd+, or Settings button:

General: Quality, save location, filename patterns, theme
Metadata: API keys, source priorities, auto-metadata
Advanced: Concurrent downloads, retry settings, engine selection

🛠️ Project Structure

YouTube-Music-Downloader-GUI/
├── gui_music_downloader/
│   ├── __init__.py
│   ├── main.py                    # Application entry point
│   ├── gui/                       # GUI components
│   │   ├── main_window.py         # Main application window
│   │   ├── search_tab.py          # Search results tab
│   │   ├── playlist_tab.py        # Playlist management tab
│   │   ├── queue_tab.py           # Download queue tab
│   │   ├── settings_dialog.py    # Settings dialog
│   │   ├── metadata_editor.py    # Metadata editor dialog
│   │   └── components/            # Reusable UI components
│   │       ├── progress_card.py   # Progress display card
│   │       ├── search_result_card.py  # Search result item
│   │       └── playlist_item.py   # Playlist track item
│   ├── backend/                   # Business logic
│   │   ├── config_manager.py      # Configuration management
│   │   ├── youtube_search.py      # YouTube search & metadata
│   │   ├── downloader.py          # Download engine abstraction
│   │   └── queue_manager.py       # Download queue management
│   ├── utils/                     # Utilities
│   │   ├── constants.py           # App constants
│   │   └── helpers.py             # Helper functions
│   └── assets/                    # Assets
│       ├── icons/                 # Application icons
│       └── themes/                # Custom themes
├── requirements.txt               # Python dependencies
├── launcher.py                    # Application launcher
├── setup.py                       # Package setup
├── config.json.example            # Example configuration
└── README.md                      # This file

🔧 Configuration

Configuration is stored at:

~/Library/Application Support/YouTubeMusicDownloader/config.json

API Keys (Optional but Recommended)

For enhanced metadata, add API keys in Settings > Metadata:

Genius API: Get Key - For lyrics
Last.fm API: Get Key - For genre/artist info
Discogs Token: Get Token - For release info

Example Configuration

{
  "general": {
    "default_quality": "Best",
    "save_location": "~/Music",
    "filename_pattern": "{artist} - {title}",
    "theme": "System"
  },
  "metadata": {
    "api_keys": {
      "genius": "your_genius_api_key",
      "lastfm": "your_lastfm_api_key",
      "discogs": "your_discogs_token"
    },
    "auto_metadata": true,
    "fetch_lyrics": true
  },
  "advanced": {
    "concurrent_downloads": 3,
    "download_engine": "ytdlp"
  }
}

🎯 Roadmap

v0.1.0 (Current - In Development)

v0.2.0 (Planned)

v0.3.0 (Future)

🐛 Troubleshooting

Common Issues

App won't start

Ensure Python 3.12+ is installed: python --version
Activate virtual environment: source .venv/bin/activate
Check dependencies: pip install -r requirements.txt

Downloads failing

Verify ffmpeg is installed: ffmpeg -version
Check internet connection
Try different quality setting

No metadata

Verify API keys in Settings > Metadata
Check MusicBrainz server status
Enable "Force Refresh" in settings

Slow downloads

Reduce concurrent downloads in Settings > Advanced
Check network speed
Try different download engine

📝 Development

Setting Up Development Environment

# Clone and enter directory
git clone https://github.com/jordolang/YouTube-Music-Downloader-GUI.git
cd YouTube-Music-Downloader-GUI

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install in editable mode with dev dependencies
pip install -e .
pip install -r requirements.txt

# Install CLI backend in editable mode
pip install -e ~/Repos/CLI-Music-Downloader

# Run the app
python -m gui_music_downloader.main

Running Tests

pytest tests/

Contributing

Fork the repository
Create a feature branch
Make your changes
Run tests
Submit a pull request

📄 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

Built on top of CLI-Music-Downloader
Uses CustomTkinter for modern GUI
Powered by yt-dlp for YouTube downloads
Metadata from MusicBrainz, Last.fm, Discogs, Genius APIs

💖 Support

If you find this tool useful, consider supporting the project:

📧 Contact

Author: Jordan Lang
GitHub: @jordolang
Issues: GitHub Issues

Note: This tool is for personal use. Please respect YouTube's Terms of Service and copyright laws.

Name		Name	Last commit message	Last commit date
Latest commit History 13 Commits
docs		docs
gui_music_downloader		gui_music_downloader
tests		tests
.gitignore		.gitignore
.python-version		.python-version
AGENTS.md		AGENTS.md
COMPLETION_SUMMARY.md		COMPLETION_SUMMARY.md
NEXT_STEPS.md		NEXT_STEPS.md
PROGRESS_UPDATE.md		PROGRESS_UPDATE.md
PROJECT_STATUS.md		PROJECT_STATUS.md
README.md		README.md
TESTING.md		TESTING.md
config.json.example		config.json.example
launcher.py		launcher.py
requirements.txt		requirements.txt
setup.py		setup.py

jordolang/YouTube-Music-Downloader-GUI

Folders and files

Latest commit

History

Repository files navigation