🎵 Modern music discovery tool that integrates Last.fm, MusicBrainz, and both Headphones & Lidarr to automatically discover and queue new albums based on your listening history.
- Robust Retry Logic: Added retry mechanism (3 attempts) for all API calls
- Connection Error Handling: Gracefully handles ConnectionResetError, Timeout, and ConnectionError
- Exponential Backoff: Implements exponential backoff strategy for failed attempts
- Rate Limiting: Improved HTTP 429 rate limit handling
- Enhanced Stability: Fixes fatal crashes from intermittent connection issues
- Better Logging: Enhanced error logging for connection troubleshooting
- Dual Service Support: Choose between Headphones or Lidarr
- Modular Architecture: Clean service layer for easy extensibility
- Auto Update System: Built-in auto-update from GitHub releases
- Smart Discovery: Analyzes your Last.fm listening history to find similar artists
- Quality Filtering: Only queues studio albums, excluding compilations, live albums, EPs, etc.
- Duplicate Prevention: Maintains persistent cache to avoid adding albums multiple times
- Comprehensive Logging: Detailed logging both to console and file
- Dual Service Support: Seamlessly works with both Headphones and Lidarr
- Easy Service Switching: Change between services with a single configuration parameter
- Quality Profiles: Advanced quality and metadata profile management (Lidarr)
- Folder Management: Automatic root folder and library organization
- Robust API Handling: Built-in retry mechanisms with exponential backoff
- Rate Limiting: Respects API rate limits for all services
- Modular Architecture: Clean, extensible service layer design
- Configuration Validation: Startup validation ensures proper setup
- Fetch Recent Artists: Retrieves artists you've listened to recently on Last.fm
- Find Similar Artists: Discovers similar artists using Last.fm's recommendation engine
- Add to Music Service: Automatically adds both original and similar artists to your chosen service (Headphones/Lidarr)
- Queue Top Albums: Fetches and queues the most popular studio albums from each artist
- Smart Filtering: Uses MusicBrainz metadata to filter out non-studio releases
- Cache Management: Maintains cache to optimize performance and avoid duplicates
- Service Integration: Seamlessly works with your chosen music management service
"I for one am happy to wake up on my Sunday to this new music discovery tool."
— Shark7809
"Wow! That sounds amazing! For a newbie like me, who is just starting out in the Plexamp world."
— Hisxela
"This is something I've been looking for actually."
— AlteRedditor
"I'm excited to try this. I've already pulled in a few recommendations and can't wait to let the script keep running to see what else it uncovers."
— mush0uth2
"This is incredible! I'm in the middle of setting things up and was wandering if such thing existed, you made my day!!"
— williewaller
- Python 3.8+: Modern Python installation
- Last.fm Account: Free account with API key (Get API Key)
- MusicBrainz Access: Public API (no registration required)
- Option A: Headphones installation with API access
- Option B: Lidarr installation with API access
The easiest way to run DiscoveryLastFM is using Docker!
# Clone the repository
git clone https://github.com/MrRobotoGit/DiscoveryLastFM-Docker.git
cd DiscoveryLastFM-Docker
# Run the automated setup
./scripts/setup-docker.sh🔗 Complete Docker Guide & Examples
For advanced users who prefer running without Docker:
-
Clone the repository:
git clone https://github.com/MrRobotoGit/DiscoveryLastFM.git cd DiscoveryLastFM -
Install dependencies:
# Recommended for Debian/Ubuntu/Raspberry Pi sudo apt update && sudo apt install python3-requests python3-packaging # Alternative for other systems pip install requests packaging
-
Configure the script: Copy the example configuration and edit with your credentials:
cp config.example.py config.py
Edit
config.pywith your actual values:For Headphones users:
MUSIC_SERVICE = "headphones" LASTFM_USERNAME = "your_lastfm_username" LASTFM_API_KEY = "your_lastfm_api_key" HP_API_KEY = "your_headphones_api_key" HP_ENDPOINT = "http://your-headphones-server:port"
For Lidarr users:
MUSIC_SERVICE = "lidarr" LASTFM_USERNAME = "your_lastfm_username" LASTFM_API_KEY = "your_lastfm_api_key" LIDARR_API_KEY = "your_lidarr_api_key" LIDARR_ENDPOINT = "http://your-lidarr-server:port" LIDARR_ROOT_FOLDER = "/music" LIDARR_QUALITY_PROFILE_ID = 2 # 2=Lossless (recommended) LIDARR_METADATA_PROFILE_ID = 1 # 1=Standard
Choose your music management service with the MUSIC_SERVICE parameter:
MUSIC_SERVICE = "headphones" # or "lidarr"The script offers several configurable parameters:
| Parameter | Default | Description |
|---|---|---|
MUSIC_SERVICE |
"headphones" | Music service: "headphones" or "lidarr" |
RECENT_MONTHS |
3 | Months of listening history to analyze |
MIN_PLAYS |
20 | Minimum plays required to consider an artist |
SIMILAR_MATCH_MIN |
0.46 | Minimum similarity score for artist matching |
MAX_SIMILAR_PER_ART |
20 | Maximum similar artists to process per artist |
MAX_POP_ALBUMS |
5 | Maximum popular albums to queue per artist |
CACHE_TTL_HOURS |
24 | Cache time-to-live in hours |
| Parameter | Default | Description |
|---|---|---|
LIDARR_QUALITY_PROFILE_ID |
2 | Quality profile (1=Any, 2=Lossless, 3=Standard) |
LIDARR_METADATA_PROFILE_ID |
1 | Metadata profile (1=Standard, 2=None) |
LIDARR_MONITOR_MODE |
"all" | Monitor mode: "all", "future", "missing", etc. |
LIDARR_SEARCH_ON_ADD |
True | Auto-search when adding artists/albums |
python3 DiscoveryLastFM.pySet up a daily cron job for automated discovery:
# Run daily at 3:00 AM
0 3 * * * python3 /path/to/DiscoveryLastFM/DiscoveryLastFM.py >> /path/to/DiscoveryLastFM/log/discover.log 2>&1DiscoveryLastFM includes a built-in auto-update system to keep your installation current.
# Check for updates and install
python3 DiscoveryLastFM.py --update
# Show current version
python3 DiscoveryLastFM.py --version
# Show update status
python3 DiscoveryLastFM.py --update-status
# List available backups
python3 DiscoveryLastFM.py --list-backupsAdd to your config.py to enable automatic update checking:
AUTO_UPDATE_ENABLED = True # Enable automatic update checking
UPDATE_CHECK_INTERVAL_HOURS = 24 # Check frequency in hours
BACKUP_RETENTION_DAYS = 7 # Backup retention periodThe auto-update system includes automatic backup creation, safe installation with verification, and automatic rollback if issues are detected. Your configuration files and cache are always preserved during updates.
2025-06-22 03:00:01 INFO Analizzo 15 artisti...
2025-06-22 03:00:05 INFO Processo artista: Radiohead (a74b1b7f-71a5-4011-9441-d0b5e4122711)
2025-06-22 03:00:10 INFO Trovati 5 album per Thom Yorke
2025-06-22 03:00:15 INFO Aggiungo album f47ac10b-58cc-4372-a567-0e02b2c3d479
2025-06-22 03:05:30 INFO Sync completata in 5.5 minuti. Statistiche:
2025-06-22 03:05:30 INFO - Album aggiunti con successo: 42
2025-06-22 03:05:30 INFO - Errori riscontrati: 3
2025-06-22 03:05:30 INFO - Album skippati: 18
2025-06-22 03:05:30 INFO - Artisti processati: 85
DiscoveryLastFM/
├── DiscoveryLastFM.py # Main script
├── config.example.py # Example configuration file
├── config.py # Your configuration (not in git)
├── services/ # Service layer (v2.0)
│ ├── __init__.py # Module initialization
│ ├── base.py # Abstract base classes
│ ├── exceptions.py # Custom exceptions
│ ├── factory.py # Service factory
│ ├── headphones.py # Headphones service
│ └── lidarr.py # Lidarr service
├── tests/ # Test suite (v2.0)
│ ├── __init__.py
│ ├── test_headphones.py
│ ├── test_lidarr.py
│ └── fixtures/
├── lastfm_similar_cache.json # Cache file (not in git)
├── log/ # Log directory (not in git)
│ └── discover.log # Application logs
├── .gitignore # Git ignore file
├── README.md # This file
└── CHANGELOG.md # Version history
- Fetches recent listening history
- Discovers similar artists
- Retrieves album popularity data
- Validates album metadata
- Filters release types (studio vs. live/compilation)
- Resolves release group IDs
Headphones API:
- Adds artists to library
- Queues albums for download
- Checks for existing albums
- Force search functionality
Lidarr API:
- Artist management with quality profiles
- Album monitoring and search
- Advanced metadata management
- Command-based operations
The script includes robust error handling:
- Service Layer: Abstracted error handling across both Headphones and Lidarr
- Retry Logic: Automatic retries with exponential backoff
- Rate Limit Management: Respects API rate limits and retry-after headers
- Timeout Handling: Extended timeouts for heavy operations
- Configuration Validation: Startup validation ensures proper service setup
- Graceful Degradation: Continues processing even if some operations fail
- Service Switching: Easy migration between services with error recovery
- Intelligent Caching: Reduces API calls by caching similar artists and processed albums
- Rate Limiting: Built-in delays to respect API limitations
- Efficient Filtering: Early filtering to avoid processing unwanted content
- Batch Operations: Groups related operations where possible
General Issues:
- API Key Errors: Ensure all API keys are valid and have proper permissions
- Network Timeouts: Check network connectivity and increase timeout values if needed
- Rate Limiting: The script handles this automatically, but manual delays might be needed for very large libraries
- Cache Issues: Delete the cache file to reset if you encounter persistent issues
Service-Specific Issues:
Headphones:
- Check
HP_ENDPOINTformat (include http:// and port) - Verify API key in Headphones settings
- Ensure Headphones is running and accessible
Lidarr:
- Check
LIDARR_ENDPOINTformat (no trailing slash) - Verify API key in Lidarr Settings → General
- Confirm
LIDARR_ROOT_FOLDERexists and is writable - Validate quality and metadata profile IDs exist
Service Switching:
- Update
MUSIC_SERVICEparameter in config.py - Ensure all required configuration parameters are set
- Cache is compatible between services
Enable debug output by setting DEBUG_PRINT = True in the configuration.
- Headphones support
- Lidarr support
- Service layer architecture
- Zero breaking changes migration
- Advanced configuration management
- CSV export functionality
- Web dashboard interface
- Multiple instance support
- Enhanced caching system
- Plugin architecture for additional services
This project is licensed under the MIT License - see the LICENSE file for details.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
See CHANGELOG.md for a detailed history of changes.
- Last.fm for the music discovery API
- MusicBrainz for comprehensive music metadata
- Headphones for automated music management
- Lidarr for modern music library management
- The open-source community for continuous improvement and feedback
If you encounter any issues or have questions:
- Check the troubleshooting section
- Review the logs in
log/discover.log - Open an issue on GitHub with relevant log excerpts
Concept and development by Matteo Rancilio.
Note: This tool is designed for personal use. Please respect the terms of service of all integrated APIs and services.