| Name | CLI-Music-Downloader JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | None |
| Summary | A powerful command-line music downloader with automatic album artwork and intelligent organization |
| upload_time | 2025-08-24 04:57:24 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT License
Copyright (c) 2024 CLI Music Downloader
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLYIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
|
| keywords |
music
downloader
youtube
metadata
album-art
mp3
lyrics
cli
musicbrainz
shazam
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
pytest
pytest-asyncio
pytest-mock
instantmusic
eyed3
mutagen
requests
lyricsgenius
shazamio
musicbrainzngs
acrcloud
pylast
discogs-client
aiohttp
aiofiles
Pillow
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# CLI Music Downloader
🎵 **A powerful command-line music downloader with automatic album artwork and intelligent organization**
[](https://www.apple.com/macos/)
[](https://www.zsh.org/)
[](LICENSE)
By The Way! This is my first major software release. If you enjoyed this tool please consider donating via the following link:
<a href="https://www.buymeacoffee.com/jordolang" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>
## ✨ Features
- 🎵 **High-quality music downloads** from YouTube with optimal audio extraction
- 🎨 **Automatic album artwork** fetching from iTunes API and Google Images
- 📁 **Smart organization** by artist in `~/Music/<Artist>/<Song>.mp3`
- 🏷️ **Enhanced metadata system** with MusicBrainz, Last.fm, and Discogs integration
- 🎼 **MusicBrainz integration** for comprehensive music metadata
- 🎧 **Audio fingerprinting** with Shazam for accurate song identification
- 📝 **Automatic lyrics** fetching and embedding from Genius API
- 🔧 **Warp Terminal integration** with custom workflows
- 🛠️ **Robust error handling** and fallback mechanisms
- 📱 **Multiple image formats** support (JPEG, PNG, WebP)
- 🔍 **Intelligent search** with artist/track parsing
- 📊 **Batch processing** for existing music libraries
- ⚙️ **Flexible metadata sources** with a priority system
## 🚀 Quick Start
### 🎯 Simple Installation (Recommended)
**Install with a single command using pip:**
```bash
# Install from PyPI (once published)
pip install CLI-Music-Downloader
# Or install directly from GitHub
pip install git+https://github.com/jordolang/CLI-Music-Downloader.git
# Install with all optional features
pip install CLI-Music-Downloader[all]
```
**Start downloading immediately:**
```bash
# Download with comprehensive metadata and album art
cli-music-downloader download "The Beatles Hey Jude"
download-music "Taylor Swift Shake It Off"
download-music "Queen Bohemian Rhapsody"
```
### Docker Setup (Alternative)
**Easy deployment with environment-specific configuration:**
```bash
# Clone and setup
git clone https://github.com/yourusername/CLI-Music-Downloader.git
cd CLI-Music-Downloader
# Development setup
cp .env.example .env
# Edit .env with your configuration
docker-compose up -d
# Download music
docker-compose exec cli-music-downloader download_music "The Beatles Hey Jude"
```
### Development Installation
**One-command music downloads with everything included:**
```bash
# Download with lyrics, album art, and metadata automatically
download_music "Taylor Swift Shake It Off"
download_music "The Beatles Hey Jude"
download_music "Queen Bohemian Rhapsody"
```
### ✅ **Production Ready Features**
🎯 **What Each Download Includes:**
- ✅ High-quality audio from YouTube (typically 128-320 kbps)
- ✅ Official album artwork from iTunes API (600x600px)
- ✅ Complete lyrics from Genius API embedded in ID3 tags
- ✅ Comprehensive metadata (artist, title, album, genre, year)
- ✅ Perfect file organization: `~/Music/Artist/Song.mp3`
- ✅ Smart artist parsing (handles "Ed Sheeran", "Taylor Swift", etc.)
- ✅ Graceful error handling with fallback mechanisms
🧪 **Tested Production Examples:**
- **RANI - Amen**: 209s audio, 66.4KB artwork, 1,395 chars lyrics ✅
- **Taylor Swift - Shake It Off**: 242s audio, 51.5KB artwork, 3,124 chars lyrics ✅
- **Ed Sheeran - Perfect**: Full metadata, lyrics, and artwork ✅
### Prerequisites
- macOS (tested on macOS Monterey+)
- Python 3.8+ with pip
- Homebrew (for system dependencies)
- Warp Terminal (optional, for workflow integration)
## Development Setup
1. Create virtual environment: `python3 -m venv .venv`
2. Activate virtual environment: `source .venv/bin/activate`
3. Install dependencies: `pip install -r requirements.txt`
4. Configure Genius API for lyrics: `export GENIUS_API_KEY="your_api_key_here"`
### 🔑 API Configuration
To enable lyrics functionality, obtain a Genius API key:
1. Visit [Genius API](https://genius.com/api-clients)
2. Create an account and generate a Client Access Token
3. Add to your shell profile:
```bash
echo 'export GENIUS_API_KEY="your_token_here"' >> ~/.zshrc
source ~/.zshrc
```
### System Dependencies
The downloader uses several metadata management tools that need to be installed via Homebrew:
```bash
brew install exiftool id3v2
```
- **exiftool**: Advanced metadata extraction and manipulation
- **id3v2**: Command-line ID3 tag editor for MP3 files
### Installation
1. **Clone the repository:**
```bash
git clone https://github.com/yourusername/CLI-Music-Downloader.git
cd CLI-Music-Downloader
```
2. **Run the installation script:**
```bash
chmod +x scripts/install.sh
./scripts/install.sh
```
3. **Or install manually:**
```bash
# Install core dependencies
pip install instantmusic eyed3 requests
# Install enhanced metadata dependencies
pip install musicbrainzngs mutagen lyricsgenius shazamio pylast discogs-client
# Copy scripts to local bin
cp bin/download_music ~/.local/bin/
cp bin/fixalbumart_improved ~/.local/bin/
cp scripts/download_music.py ~/.local/bin/
cp batch_metadata.py ~/.local/bin/
chmod +x ~/.local/bin/download_music
chmod +x ~/.local/bin/fixalbumart_improved
chmod +x ~/.local/bin/download_music.py
chmod +x ~/.local/bin/batch_metadata.py
# Install Warp workflow (optional)
mkdir -p ~/.config/warp/workflows
cp workflows/download_music.yaml ~/.config/warp/workflows/
```
## 🎵 Usage
### Basic Downloads
```bash
# Download a song with enhanced metadata
download_music "The Beatles Hey Jude"
download_music "Pink Floyd - Comfortably Numb"
download_music "Queen Bohemian Rhapsody"
```
### Enhanced Metadata Features
```bash
# Download with full metadata from MusicBrainz
download_music "https://example.com/song" --metadata-source musicbrainz
# Download with specific metadata source
download_music "Adele Rolling in the Deep" --metadata-source all
# Force metadata refresh for existing files
download_music "Artist Song" --force-metadata
# Skip metadata enhancement entirely
download_music "Artist Song" --skip-metadata
# Provide explicit artist and title hints
download_music "search term" --artist "The Beatles" --title "Hey Jude"
```
### Batch Metadata Processing
```bash
# Fix metadata for existing files
batch_metadata.py --fix "Adele - Rolling in the Deep.mp3"
# Scan entire music library for metadata issues
batch_metadata.py --scan ~/Music
# View detailed metadata report
batch_metadata.py --report --detailed
# Dry run to see what would be fixed
batch_metadata.py --fix ~/Music/Artist --dry-run
```
### Warp Terminal Workflow
1. Open Warp Terminal
2. Press `Cmd+Shift+R` to open workflow picker
3. Type "Download Music" and select the workflow
4. Enter your search query (e.g., "Radiohead Creep")
5. Press Enter and enjoy! 🎉
### Album Art Fixer (Standalone)
```bash
# Fix album art for existing files
fixalbumart_improved "/path/to/song.mp3" "Artist Name" "Track Name"
# Auto-detect from filename (works with "Artist - Track.mp3" format)
fixalbumart_improved "/path/to/Artist - Track.mp3"
```
## 🐳 Docker Environment Configuration
### Environment Variables
The Docker setup supports comprehensive environment configuration for different deployment scenarios:
| Variable | Description | Default | Example |
|----------|-------------|---------|----------|
| `MUSIC_PATH` | Music directory path | `~/Music` | `/data/music` |
| `CONFIG_PATH` | Configuration directory | `~/.config/cli-music-downloader` | `/data/config` |
| `DOWNLOAD_QUALITY` | Audio quality | `best` | `320`, `256`, `128` |
| `METADATA_SOURCE` | Metadata source | `all` | `musicbrainz`, `lastfm` |
| `GENIUS_API_KEY` | Genius API for lyrics | - | `your-api-key` |
### Deployment Examples
```bash
# Development with custom music directory
MUSIC_PATH=~/MyMusic docker-compose up -d
# Production with high-quality downloads
DOWNLOAD_QUALITY=best MUSIC_PATH=/data/music docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
# Custom metadata source
METADATA_SOURCE=musicbrainz docker-compose up -d
```
### Configuration Files
- **`.env.example`**: Template for environment variables
- **`.env.development`**: Development-specific settings
- **`.env.production`**: Production-optimized settings
- **`docker-compose.yml`**: Base Docker configuration
- **`docker-compose.prod.yml`**: Production overrides
For complete configuration details, see [docs/ENVIRONMENT_CONFIGURATION.md](docs/ENVIRONMENT_CONFIGURATION.md).
## 📁 Project Structure
```
CLI-Music-Downloader/
├── bin/
│ ├── download_music # Main download script
│ └── fixalbumart_improved # Album art processor
├── workflows/
│ └── download_music.yaml # Warp Terminal workflow
├── scripts/
│ ├── install.sh # Installation script
│ ├── uninstall.sh # Uninstallation script
│ ├── download_music.py # Enhanced Python downloader
│ ├── lyrics_metadata.py # Lyrics and metadata handler
│ └── metadata_manager.py # Multi-source metadata manager
├── batch_metadata.py # Batch metadata processor
├── examples/
│ └── sample_usage.md # Usage examples
├── docs/
│ ├── TROUBLESHOOTING.md # Common issues and solutions
│ ├── API.md # Technical documentation
│ └── ENVIRONMENT_CONFIGURATION.md # Environment config guide
├── docker-compose.yml # Docker configuration
├── docker-compose.prod.yml # Production overrides
├── Dockerfile # Container definition
├── .env.example # Environment template
├── .env.development # Development settings
├── .env.production # Production settings
├── README.md # This file
├── LICENSE # MIT License
└── requirements.txt # Python dependencies
```
## 🔧 How It Works
1. **Download Audio**: Uses `instantmusic` (powered by yt-dlp) to download high-quality audio from YouTube
2. **Organize Files**: Automatically creates artist folders and moves files to `~/Music/<Artist>/`
3. **Fetch Album Art**:
- Primary: iTunes API for high-quality official artwork
- Fallback: Google Images search with quality filtering
4. **Embed Metadata**: Uses `eyed3` to properly tag files and embed album artwork
5. **Error Recovery**: Graceful handling of network issues and missing artwork
## 📚 Metadata Sources and Priorities
The CLI Music Downloader uses multiple metadata sources to ensure comprehensive and accurate music information:
### 1. MusicBrainz (Primary Source)
- **Data Retrieved:** Artist, album, year, track numbers, genre, MusicBrainz IDs
- **Features:** Release group analysis, artist credit handling
- **Confidence:** High (90%)
- **Use Case:** Primary source for all metadata lookups
### 2. Shazam (Audio Fingerprinting)
- **Data Retrieved:** Artist, title, album (when available)
- **Features:** Audio identification from downloaded file
- **Confidence:** Medium-High (70%)
- **Use Case:** When filename parsing fails or metadata is missing
### 3. Genius (Lyrics)
- **Data Retrieved:** Song lyrics
- **Features:** Clean lyrics processing, embedded in ID3 tags
- **Integration:** Uses existing LyricsMetadataHandler
- **Use Case:** Lyrics enhancement for downloaded tracks
### 4. Last.fm (Genre and Artist Info)
- **Data Retrieved:** Genre tags, artist information, album details
- **Features:** Community-driven tagging, extensive database
- **Confidence:** Medium (60%)
- **Use Case:** Fallback for genre and additional artist information
### 5. Discogs (Release Information)
- **Data Retrieved:** Detailed release info, catalog numbers, formats
- **Features:** Comprehensive release database
- **Confidence:** Medium (60%)
- **Use Case:** Specialized release information and catalog data
### Source Selection Strategy
The system automatically selects the best source based on:
- Data availability and completeness
- Source reliability and confidence scores
- User preferences (via `--metadata-source` flag)
- Fallback hierarchy when primary sources fail
## 📍 Troubleshooting Common Metadata Issues
### Missing Metadata
**Symptoms:** Downloaded files have empty or incomplete metadata fields
**Solutions:**
```bash
# Force metadata refresh
download_music "Artist Song" --force-metadata
# Try different metadata source
download_music "Artist Song" --metadata-source musicbrainz
# Provide explicit artist/title hints
download_music "search term" --artist "Artist" --title "Song"
```
### Incorrect Metadata
**Symptoms:** Wrong artist, title, album, or other metadata fields
**Solutions:**
```bash
# Force metadata refresh with specific source
batch_metadata.py --fix "path/to/file.mp3" --dry-run
# Use batch processor to fix multiple files
batch_metadata.py --fix ~/Music/Artist --verbose
```
### API Rate Limiting
**Symptoms:** "Rate limit exceeded" or slow metadata fetching
**Solutions:**
- Wait before retrying requests
- Use batch processing with delays: `batch_metadata.py --fix ~/Music`
- Check API key configurations for Last.fm and Discogs
### Audio Fingerprinting Failures
**Symptoms:** Shazam identification not working
**Solutions:**
- Ensure audio file is not corrupted
- Try with different metadata source: `--metadata-source musicbrainz`
- Check file format compatibility (MP3, FLAC, M4A supported)
### Network Connectivity Issues
**Symptoms:** Metadata lookup timeouts or connection errors
**Solutions:**
```bash
# Skip metadata if network issues persist
download_music "Artist Song" --skip-metadata
# Run metadata enhancement later
batch_metadata.py --fix ~/Music/newly_downloaded
```
### Configuration Issues
**Symptoms:** Metadata sources not working despite correct setup
**Solutions:**
```bash
# View current configuration
batch_metadata.py --config
# Set API keys via environment variables
export GENIUS_API_KEY="your_key_here"
export LASTFM_API_KEY="your_key_here"
export DISCOGS_USER_TOKEN="your_token_here"
```
For extensive troubleshooting tips, visit the [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md).
---
## 🎨 Album Art Sources
### iTunes API (Primary)
- ✅ High-quality official artwork (600x600px)
- ✅ Reliable metadata
- ✅ Fast response times
- ✅ No rate limiting for reasonable usage
### Google Images (Fallback)
- ✅ Extensive coverage
- ✅ Quality filtering (1KB-5MB)
- ✅ Multiple format support
- ⚠️ May require user-agent headers
## 🛠️ Dependencies
### Core Dependencies
- **[instantmusic](https://github.com/yask123/Instant-Music-Downloader)**: Core music downloading
- **[eyed3](https://eyed3.readthedocs.io/)**: ID3 tag manipulation
- **[requests](https://requests.readthedocs.io/)**: HTTP requests for album art
- **[yt-dlp](https://github.com/yt-dlp/yt-dlp)**: YouTube audio extraction (dependency of instantmusic)
### Enhanced Metadata Dependencies
- **[musicbrainzngs](https://python-musicbrainzngs.readthedocs.io/)**: MusicBrainz API client
- **[mutagen](https://mutagen.readthedocs.io/)**: Advanced audio metadata handling
- **[lyricsgenius](https://lyricsgenius.readthedocs.io/)**: Genius API for lyrics
- **[shazamio](https://github.com/dotX12/ShazamIO)**: Audio fingerprinting and identification
- **[pylast](https://github.com/pylast/pylast)**: Last.fm API client
- **[discogs-client](https://github.com/joalla/discogs_client)**: Discogs API client
## 📱 Output Structure
Downloaded music is organized as:
```
~/Music/
├── Coldplay/
│ └── Yellow (Official Video).mp3
├── The Beatles/
│ └── Hey Jude.mp3
├── Queen/
│ └── Bohemian Rhapsody (Official Video).mp3
└── ...
```
Each file includes:
- 🏷️ **Comprehensive ID3 tags:** artist, title, album, year, track number, genre
- 🎨 **High-quality embedded album artwork** (up to 600x600px)
- 🎵 **Optimal audio quality** (typically 128-320 kbps)
- 📝 **Embedded lyrics** (when available from Genius API)
- 🆔 **MusicBrainz IDs** for precise music identification
- 📊 **Validation metadata** ensuring data quality
## 🔍 Troubleshooting
### Common Issues
**"Command not found: download_music"**
```bash
# Ensure ~/.local/bin is in your PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```
**"Album art processing failed"**
- Network connectivity issues
- Try running `fixalbumart_improved` manually on the file
- Check if Python dependencies are properly installed
**"No such file or directory"**
- Run the installation script: `./scripts/install.sh`
- Verify all dependencies are installed
See [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) for more detailed solutions.
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- [instantmusic](https://github.com/yask123/Instant-Music-Downloader) for the core downloading functionality
- [yt-dlp](https://github.com/yt-dlp/yt-dlp) for reliable YouTube audio extraction
- [eyed3](https://eyed3.readthedocs.io/) for ID3 tag manipulation
- Apple iTunes API for high-quality album artwork
- The open-source community for inspiration and tools
## ⭐ Star History
If this project helped you, please consider giving it a star! ⭐
---
**Made with ❤️ for music lovers who appreciate good tooling**
Raw data
{
"_id": null,
"home_page": null,
"name": "CLI-Music-Downloader",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Jordan Lang <jordolang@example.com>",
"keywords": "music, downloader, youtube, metadata, album-art, mp3, lyrics, cli, musicbrainz, shazam",
"author": null,
"author_email": "Jordan Lang <jordolang@example.com>",
"download_url": "https://files.pythonhosted.org/packages/01/64/1dc52f9e0c602ea96c163a7243a66fe26f99ae45d93d0f1d8c4ea3d5eb1f/cli_music_downloader-1.0.0.tar.gz",
"platform": null,
"description": "# CLI Music Downloader\n\n\ud83c\udfb5 **A powerful command-line music downloader with automatic album artwork and intelligent organization**\n\n[](https://www.apple.com/macos/)\n[](https://www.zsh.org/)\n[](LICENSE)\n\nBy The Way! This is my first major software release. If you enjoyed this tool please consider donating via the following link:\n\n<a href=\"https://www.buymeacoffee.com/jordolang\" target=\"_blank\"><img src=\"https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png\" alt=\"Buy Me A Coffee\" style=\"height: 60px !important;width: 217px !important;\" ></a>\n\n## \u2728 Features\n\n- \ud83c\udfb5 **High-quality music downloads** from YouTube with optimal audio extraction\n- \ud83c\udfa8 **Automatic album artwork** fetching from iTunes API and Google Images\n- \ud83d\udcc1 **Smart organization** by artist in `~/Music/<Artist>/<Song>.mp3`\n- \ud83c\udff7\ufe0f **Enhanced metadata system** with MusicBrainz, Last.fm, and Discogs integration\n- \ud83c\udfbc **MusicBrainz integration** for comprehensive music metadata\n- \ud83c\udfa7 **Audio fingerprinting** with Shazam for accurate song identification\n- \ud83d\udcdd **Automatic lyrics** fetching and embedding from Genius API\n- \ud83d\udd27 **Warp Terminal integration** with custom workflows\n- \ud83d\udee0\ufe0f **Robust error handling** and fallback mechanisms\n- \ud83d\udcf1 **Multiple image formats** support (JPEG, PNG, WebP)\n- \ud83d\udd0d **Intelligent search** with artist/track parsing\n- \ud83d\udcca **Batch processing** for existing music libraries\n- \u2699\ufe0f **Flexible metadata sources** with a priority system\n\n## \ud83d\ude80 Quick Start\n\n### \ud83c\udfaf Simple Installation (Recommended)\n\n**Install with a single command using pip:**\n\n```bash\n# Install from PyPI (once published)\npip install CLI-Music-Downloader\n\n# Or install directly from GitHub\npip install git+https://github.com/jordolang/CLI-Music-Downloader.git\n\n# Install with all optional features\npip install CLI-Music-Downloader[all]\n```\n\n**Start downloading immediately:**\n\n```bash\n# Download with comprehensive metadata and album art\ncli-music-downloader download \"The Beatles Hey Jude\"\ndownload-music \"Taylor Swift Shake It Off\"\ndownload-music \"Queen Bohemian Rhapsody\"\n```\n\n### Docker Setup (Alternative)\n\n**Easy deployment with environment-specific configuration:**\n\n```bash\n# Clone and setup\ngit clone https://github.com/yourusername/CLI-Music-Downloader.git\ncd CLI-Music-Downloader\n\n# Development setup\ncp .env.example .env\n# Edit .env with your configuration\ndocker-compose up -d\n\n# Download music\ndocker-compose exec cli-music-downloader download_music \"The Beatles Hey Jude\"\n```\n\n### Development Installation\n\n**One-command music downloads with everything included:**\n\n```bash\n# Download with lyrics, album art, and metadata automatically\ndownload_music \"Taylor Swift Shake It Off\"\ndownload_music \"The Beatles Hey Jude\"\ndownload_music \"Queen Bohemian Rhapsody\"\n```\n\n### \u2705 **Production Ready Features**\n\n\ud83c\udfaf **What Each Download Includes:**\n- \u2705 High-quality audio from YouTube (typically 128-320 kbps)\n- \u2705 Official album artwork from iTunes API (600x600px)\n- \u2705 Complete lyrics from Genius API embedded in ID3 tags\n- \u2705 Comprehensive metadata (artist, title, album, genre, year)\n- \u2705 Perfect file organization: `~/Music/Artist/Song.mp3`\n- \u2705 Smart artist parsing (handles \"Ed Sheeran\", \"Taylor Swift\", etc.)\n- \u2705 Graceful error handling with fallback mechanisms\n\n\ud83e\uddea **Tested Production Examples:**\n- **RANI - Amen**: 209s audio, 66.4KB artwork, 1,395 chars lyrics \u2705\n- **Taylor Swift - Shake It Off**: 242s audio, 51.5KB artwork, 3,124 chars lyrics \u2705\n- **Ed Sheeran - Perfect**: Full metadata, lyrics, and artwork \u2705\n\n### Prerequisites\n\n- macOS (tested on macOS Monterey+)\n- Python 3.8+ with pip\n- Homebrew (for system dependencies)\n- Warp Terminal (optional, for workflow integration)\n\n## Development Setup\n1. Create virtual environment: `python3 -m venv .venv`\n2. Activate virtual environment: `source .venv/bin/activate`\n3. Install dependencies: `pip install -r requirements.txt`\n4. Configure Genius API for lyrics: `export GENIUS_API_KEY=\"your_api_key_here\"`\n\n### \ud83d\udd11 API Configuration\n\nTo enable lyrics functionality, obtain a Genius API key:\n1. Visit [Genius API](https://genius.com/api-clients)\n2. Create an account and generate a Client Access Token\n3. Add to your shell profile:\n ```bash\n echo 'export GENIUS_API_KEY=\"your_token_here\"' >> ~/.zshrc\n source ~/.zshrc\n ```\n\n### System Dependencies\n\nThe downloader uses several metadata management tools that need to be installed via Homebrew:\n\n```bash\nbrew install exiftool id3v2\n```\n\n- **exiftool**: Advanced metadata extraction and manipulation\n- **id3v2**: Command-line ID3 tag editor for MP3 files\n\n### Installation\n\n1. **Clone the repository:**\n ```bash\n git clone https://github.com/yourusername/CLI-Music-Downloader.git\n cd CLI-Music-Downloader\n ```\n\n2. **Run the installation script:**\n ```bash\n chmod +x scripts/install.sh\n ./scripts/install.sh\n ```\n\n3. **Or install manually:**\n ```bash\n # Install core dependencies\n pip install instantmusic eyed3 requests\n \n # Install enhanced metadata dependencies\n pip install musicbrainzngs mutagen lyricsgenius shazamio pylast discogs-client\n \n # Copy scripts to local bin\n cp bin/download_music ~/.local/bin/\n cp bin/fixalbumart_improved ~/.local/bin/\n cp scripts/download_music.py ~/.local/bin/\n cp batch_metadata.py ~/.local/bin/\n chmod +x ~/.local/bin/download_music\n chmod +x ~/.local/bin/fixalbumart_improved\n chmod +x ~/.local/bin/download_music.py\n chmod +x ~/.local/bin/batch_metadata.py\n \n # Install Warp workflow (optional)\n mkdir -p ~/.config/warp/workflows\n cp workflows/download_music.yaml ~/.config/warp/workflows/\n ```\n\n## \ud83c\udfb5 Usage\n\n### Basic Downloads\n\n```bash\n# Download a song with enhanced metadata\ndownload_music \"The Beatles Hey Jude\"\ndownload_music \"Pink Floyd - Comfortably Numb\"\ndownload_music \"Queen Bohemian Rhapsody\"\n```\n\n### Enhanced Metadata Features\n\n```bash\n# Download with full metadata from MusicBrainz\ndownload_music \"https://example.com/song\" --metadata-source musicbrainz\n\n# Download with specific metadata source\ndownload_music \"Adele Rolling in the Deep\" --metadata-source all\n\n# Force metadata refresh for existing files\ndownload_music \"Artist Song\" --force-metadata\n\n# Skip metadata enhancement entirely\ndownload_music \"Artist Song\" --skip-metadata\n\n# Provide explicit artist and title hints\ndownload_music \"search term\" --artist \"The Beatles\" --title \"Hey Jude\"\n```\n\n### Batch Metadata Processing\n\n```bash\n# Fix metadata for existing files\nbatch_metadata.py --fix \"Adele - Rolling in the Deep.mp3\"\n\n# Scan entire music library for metadata issues\nbatch_metadata.py --scan ~/Music\n\n# View detailed metadata report\nbatch_metadata.py --report --detailed\n\n# Dry run to see what would be fixed\nbatch_metadata.py --fix ~/Music/Artist --dry-run\n```\n\n### Warp Terminal Workflow\n\n1. Open Warp Terminal\n2. Press `Cmd+Shift+R` to open workflow picker\n3. Type \"Download Music\" and select the workflow\n4. Enter your search query (e.g., \"Radiohead Creep\")\n5. Press Enter and enjoy! \ud83c\udf89\n\n### Album Art Fixer (Standalone)\n\n```bash\n# Fix album art for existing files\nfixalbumart_improved \"/path/to/song.mp3\" \"Artist Name\" \"Track Name\"\n\n# Auto-detect from filename (works with \"Artist - Track.mp3\" format)\nfixalbumart_improved \"/path/to/Artist - Track.mp3\"\n```\n\n## \ud83d\udc33 Docker Environment Configuration\n\n### Environment Variables\n\nThe Docker setup supports comprehensive environment configuration for different deployment scenarios:\n\n| Variable | Description | Default | Example |\n|----------|-------------|---------|----------|\n| `MUSIC_PATH` | Music directory path | `~/Music` | `/data/music` |\n| `CONFIG_PATH` | Configuration directory | `~/.config/cli-music-downloader` | `/data/config` |\n| `DOWNLOAD_QUALITY` | Audio quality | `best` | `320`, `256`, `128` |\n| `METADATA_SOURCE` | Metadata source | `all` | `musicbrainz`, `lastfm` |\n| `GENIUS_API_KEY` | Genius API for lyrics | - | `your-api-key` |\n\n### Deployment Examples\n\n```bash\n# Development with custom music directory\nMUSIC_PATH=~/MyMusic docker-compose up -d\n\n# Production with high-quality downloads\nDOWNLOAD_QUALITY=best MUSIC_PATH=/data/music docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d\n\n# Custom metadata source\nMETADATA_SOURCE=musicbrainz docker-compose up -d\n```\n\n### Configuration Files\n\n- **`.env.example`**: Template for environment variables\n- **`.env.development`**: Development-specific settings\n- **`.env.production`**: Production-optimized settings\n- **`docker-compose.yml`**: Base Docker configuration\n- **`docker-compose.prod.yml`**: Production overrides\n\nFor complete configuration details, see [docs/ENVIRONMENT_CONFIGURATION.md](docs/ENVIRONMENT_CONFIGURATION.md).\n\n## \ud83d\udcc1 Project Structure\n\n```\nCLI-Music-Downloader/\n\u251c\u2500\u2500 bin/\n\u2502 \u251c\u2500\u2500 download_music # Main download script\n\u2502 \u2514\u2500\u2500 fixalbumart_improved # Album art processor\n\u251c\u2500\u2500 workflows/\n\u2502 \u2514\u2500\u2500 download_music.yaml # Warp Terminal workflow\n\u251c\u2500\u2500 scripts/\n\u2502 \u251c\u2500\u2500 install.sh # Installation script\n\u2502 \u251c\u2500\u2500 uninstall.sh # Uninstallation script\n\u2502 \u251c\u2500\u2500 download_music.py # Enhanced Python downloader\n\u2502 \u251c\u2500\u2500 lyrics_metadata.py # Lyrics and metadata handler\n\u2502 \u2514\u2500\u2500 metadata_manager.py # Multi-source metadata manager\n\u251c\u2500\u2500 batch_metadata.py # Batch metadata processor\n\u251c\u2500\u2500 examples/\n\u2502 \u2514\u2500\u2500 sample_usage.md # Usage examples\n\u251c\u2500\u2500 docs/\n\u2502 \u251c\u2500\u2500 TROUBLESHOOTING.md # Common issues and solutions\n\u2502 \u251c\u2500\u2500 API.md # Technical documentation\n\u2502 \u2514\u2500\u2500 ENVIRONMENT_CONFIGURATION.md # Environment config guide\n\u251c\u2500\u2500 docker-compose.yml # Docker configuration\n\u251c\u2500\u2500 docker-compose.prod.yml # Production overrides\n\u251c\u2500\u2500 Dockerfile # Container definition\n\u251c\u2500\u2500 .env.example # Environment template\n\u251c\u2500\u2500 .env.development # Development settings\n\u251c\u2500\u2500 .env.production # Production settings\n\u251c\u2500\u2500 README.md # This file\n\u251c\u2500\u2500 LICENSE # MIT License\n\u2514\u2500\u2500 requirements.txt # Python dependencies\n```\n\n## \ud83d\udd27 How It Works\n\n1. **Download Audio**: Uses `instantmusic` (powered by yt-dlp) to download high-quality audio from YouTube\n2. **Organize Files**: Automatically creates artist folders and moves files to `~/Music/<Artist>/`\n3. **Fetch Album Art**: \n - Primary: iTunes API for high-quality official artwork\n - Fallback: Google Images search with quality filtering\n4. **Embed Metadata**: Uses `eyed3` to properly tag files and embed album artwork\n5. **Error Recovery**: Graceful handling of network issues and missing artwork\n\n## \ud83d\udcda Metadata Sources and Priorities\n\nThe CLI Music Downloader uses multiple metadata sources to ensure comprehensive and accurate music information:\n\n### 1. MusicBrainz (Primary Source)\n- **Data Retrieved:** Artist, album, year, track numbers, genre, MusicBrainz IDs\n- **Features:** Release group analysis, artist credit handling\n- **Confidence:** High (90%)\n- **Use Case:** Primary source for all metadata lookups\n\n### 2. Shazam (Audio Fingerprinting)\n- **Data Retrieved:** Artist, title, album (when available)\n- **Features:** Audio identification from downloaded file\n- **Confidence:** Medium-High (70%)\n- **Use Case:** When filename parsing fails or metadata is missing\n\n### 3. Genius (Lyrics)\n- **Data Retrieved:** Song lyrics\n- **Features:** Clean lyrics processing, embedded in ID3 tags\n- **Integration:** Uses existing LyricsMetadataHandler\n- **Use Case:** Lyrics enhancement for downloaded tracks\n\n### 4. Last.fm (Genre and Artist Info)\n- **Data Retrieved:** Genre tags, artist information, album details\n- **Features:** Community-driven tagging, extensive database\n- **Confidence:** Medium (60%)\n- **Use Case:** Fallback for genre and additional artist information\n\n### 5. Discogs (Release Information)\n- **Data Retrieved:** Detailed release info, catalog numbers, formats\n- **Features:** Comprehensive release database\n- **Confidence:** Medium (60%)\n- **Use Case:** Specialized release information and catalog data\n\n### Source Selection Strategy\nThe system automatically selects the best source based on:\n- Data availability and completeness\n- Source reliability and confidence scores\n- User preferences (via `--metadata-source` flag)\n- Fallback hierarchy when primary sources fail\n\n## \ud83d\udccd Troubleshooting Common Metadata Issues\n\n### Missing Metadata\n**Symptoms:** Downloaded files have empty or incomplete metadata fields\n\n**Solutions:**\n```bash\n# Force metadata refresh\ndownload_music \"Artist Song\" --force-metadata\n\n# Try different metadata source\ndownload_music \"Artist Song\" --metadata-source musicbrainz\n\n# Provide explicit artist/title hints\ndownload_music \"search term\" --artist \"Artist\" --title \"Song\"\n```\n\n### Incorrect Metadata\n**Symptoms:** Wrong artist, title, album, or other metadata fields\n\n**Solutions:**\n```bash\n# Force metadata refresh with specific source\nbatch_metadata.py --fix \"path/to/file.mp3\" --dry-run\n\n# Use batch processor to fix multiple files\nbatch_metadata.py --fix ~/Music/Artist --verbose\n```\n\n### API Rate Limiting\n**Symptoms:** \"Rate limit exceeded\" or slow metadata fetching\n\n**Solutions:**\n- Wait before retrying requests\n- Use batch processing with delays: `batch_metadata.py --fix ~/Music`\n- Check API key configurations for Last.fm and Discogs\n\n### Audio Fingerprinting Failures\n**Symptoms:** Shazam identification not working\n\n**Solutions:**\n- Ensure audio file is not corrupted\n- Try with different metadata source: `--metadata-source musicbrainz`\n- Check file format compatibility (MP3, FLAC, M4A supported)\n\n### Network Connectivity Issues\n**Symptoms:** Metadata lookup timeouts or connection errors\n\n**Solutions:**\n```bash\n# Skip metadata if network issues persist\ndownload_music \"Artist Song\" --skip-metadata\n\n# Run metadata enhancement later\nbatch_metadata.py --fix ~/Music/newly_downloaded\n```\n\n### Configuration Issues\n**Symptoms:** Metadata sources not working despite correct setup\n\n**Solutions:**\n```bash\n# View current configuration\nbatch_metadata.py --config\n\n# Set API keys via environment variables\nexport GENIUS_API_KEY=\"your_key_here\"\nexport LASTFM_API_KEY=\"your_key_here\"\nexport DISCOGS_USER_TOKEN=\"your_token_here\"\n```\n\nFor extensive troubleshooting tips, visit the [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md).\n\n---\n\n## \ud83c\udfa8 Album Art Sources\n\n### iTunes API (Primary)\n- \u2705 High-quality official artwork (600x600px)\n- \u2705 Reliable metadata\n- \u2705 Fast response times\n- \u2705 No rate limiting for reasonable usage\n\n### Google Images (Fallback)\n- \u2705 Extensive coverage\n- \u2705 Quality filtering (1KB-5MB)\n- \u2705 Multiple format support\n- \u26a0\ufe0f May require user-agent headers\n\n## \ud83d\udee0\ufe0f Dependencies\n\n### Core Dependencies\n- **[instantmusic](https://github.com/yask123/Instant-Music-Downloader)**: Core music downloading\n- **[eyed3](https://eyed3.readthedocs.io/)**: ID3 tag manipulation\n- **[requests](https://requests.readthedocs.io/)**: HTTP requests for album art\n- **[yt-dlp](https://github.com/yt-dlp/yt-dlp)**: YouTube audio extraction (dependency of instantmusic)\n\n### Enhanced Metadata Dependencies\n- **[musicbrainzngs](https://python-musicbrainzngs.readthedocs.io/)**: MusicBrainz API client\n- **[mutagen](https://mutagen.readthedocs.io/)**: Advanced audio metadata handling\n- **[lyricsgenius](https://lyricsgenius.readthedocs.io/)**: Genius API for lyrics\n- **[shazamio](https://github.com/dotX12/ShazamIO)**: Audio fingerprinting and identification\n- **[pylast](https://github.com/pylast/pylast)**: Last.fm API client\n- **[discogs-client](https://github.com/joalla/discogs_client)**: Discogs API client\n\n## \ud83d\udcf1 Output Structure\n\nDownloaded music is organized as:\n```\n~/Music/\n\u251c\u2500\u2500 Coldplay/\n\u2502 \u2514\u2500\u2500 Yellow (Official Video).mp3\n\u251c\u2500\u2500 The Beatles/\n\u2502 \u2514\u2500\u2500 Hey Jude.mp3\n\u251c\u2500\u2500 Queen/\n\u2502 \u2514\u2500\u2500 Bohemian Rhapsody (Official Video).mp3\n\u2514\u2500\u2500 ...\n```\n\nEach file includes:\n- \ud83c\udff7\ufe0f **Comprehensive ID3 tags:** artist, title, album, year, track number, genre\n- \ud83c\udfa8 **High-quality embedded album artwork** (up to 600x600px)\n- \ud83c\udfb5 **Optimal audio quality** (typically 128-320 kbps)\n- \ud83d\udcdd **Embedded lyrics** (when available from Genius API)\n- \ud83c\udd94 **MusicBrainz IDs** for precise music identification\n- \ud83d\udcca **Validation metadata** ensuring data quality\n\n## \ud83d\udd0d Troubleshooting\n\n### Common Issues\n\n**\"Command not found: download_music\"**\n```bash\n# Ensure ~/.local/bin is in your PATH\necho 'export PATH=\"$HOME/.local/bin:$PATH\"' >> ~/.zshrc\nsource ~/.zshrc\n```\n\n**\"Album art processing failed\"**\n- Network connectivity issues\n- Try running `fixalbumart_improved` manually on the file\n- Check if Python dependencies are properly installed\n\n**\"No such file or directory\"**\n- Run the installation script: `./scripts/install.sh`\n- Verify all dependencies are installed\n\nSee [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) for more detailed solutions.\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgments\n\n- [instantmusic](https://github.com/yask123/Instant-Music-Downloader) for the core downloading functionality\n- [yt-dlp](https://github.com/yt-dlp/yt-dlp) for reliable YouTube audio extraction\n- [eyed3](https://eyed3.readthedocs.io/) for ID3 tag manipulation\n- Apple iTunes API for high-quality album artwork\n- The open-source community for inspiration and tools\n\n## \u2b50 Star History\n\nIf this project helped you, please consider giving it a star! \u2b50\n\n---\n\n**Made with \u2764\ufe0f for music lovers who appreciate good tooling**\n\n\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2024 CLI Music Downloader\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLYIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n \n ",
"summary": "A powerful command-line music downloader with automatic album artwork and intelligent organization",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/jordolang/CLI-Music-Downloader/issues",
"Changelog": "https://github.com/jordolang/CLI-Music-Downloader/releases",
"Documentation": "https://github.com/jordolang/CLI-Music-Downloader#readme",
"Homepage": "https://github.com/jordolang/CLI-Music-Downloader",
"Repository": "https://github.com/jordolang/CLI-Music-Downloader.git"
},
"split_keywords": [
"music",
" downloader",
" youtube",
" metadata",
" album-art",
" mp3",
" lyrics",
" cli",
" musicbrainz",
" shazam"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "65939d15743301a258bdb85b1476fc9175fc0260952f7e3dc2b121cb9dbb5a70",
"md5": "9e7cdd6762b27705a59273fbe381e1aa",
"sha256": "fc43db2aa03731bceb547d209134c6f8574717a278d2d9675afb2c0f2c614090"
},
"downloads": -1,
"filename": "cli_music_downloader-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9e7cdd6762b27705a59273fbe381e1aa",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 35810,
"upload_time": "2025-08-24T04:57:23",
"upload_time_iso_8601": "2025-08-24T04:57:23.104010Z",
"url": "https://files.pythonhosted.org/packages/65/93/9d15743301a258bdb85b1476fc9175fc0260952f7e3dc2b121cb9dbb5a70/cli_music_downloader-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "01641dc52f9e0c602ea96c163a7243a66fe26f99ae45d93d0f1d8c4ea3d5eb1f",
"md5": "2a8224bae5b3b42b9f6ce499fd7d6cda",
"sha256": "f465a9fb9898ed306a5e655b0d1376ca691cfa9245f1199d7bc0708c4a51135f"
},
"downloads": -1,
"filename": "cli_music_downloader-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "2a8224bae5b3b42b9f6ce499fd7d6cda",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 96621,
"upload_time": "2025-08-24T04:57:24",
"upload_time_iso_8601": "2025-08-24T04:57:24.505526Z",
"url": "https://files.pythonhosted.org/packages/01/64/1dc52f9e0c602ea96c163a7243a66fe26f99ae45d93d0f1d8c4ea3d5eb1f/cli_music_downloader-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-24 04:57:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jordolang",
"github_project": "CLI-Music-Downloader",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "pytest",
"specs": [
[
">=",
"6.0.0"
]
]
},
{
"name": "pytest-asyncio",
"specs": [
[
">=",
"0.21.0"
]
]
},
{
"name": "pytest-mock",
"specs": [
[
">=",
"3.10.0"
]
]
},
{
"name": "instantmusic",
"specs": [
[
">=",
"2.2"
]
]
},
{
"name": "eyed3",
"specs": [
[
">=",
"0.9.6"
]
]
},
{
"name": "mutagen",
"specs": [
[
">=",
"1.45.1"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.25.1"
]
]
},
{
"name": "lyricsgenius",
"specs": [
[
">=",
"3.0.1"
]
]
},
{
"name": "shazamio",
"specs": [
[
">=",
"0.3.0"
]
]
},
{
"name": "musicbrainzngs",
"specs": [
[
">=",
"0.7.1"
]
]
},
{
"name": "acrcloud",
"specs": [
[
">=",
"1.4.0"
]
]
},
{
"name": "pylast",
"specs": [
[
">=",
"5.2.0"
]
]
},
{
"name": "discogs-client",
"specs": [
[
">=",
"2.3.0"
]
]
},
{
"name": "aiohttp",
"specs": [
[
">=",
"3.8.0"
]
]
},
{
"name": "aiofiles",
"specs": [
[
">=",
"0.8.0"
]
]
},
{
"name": "Pillow",
"specs": [
[
">=",
"8.0.0"
]
]
}
],
"lcname": "cli-music-downloader"
}
