Powerful real-time tracker for Last.fm that brings your music data to life with automated Spotify playback, instant activity alerts and deep scrobble analytics.
New to Python or unsure what is installed? Follow the Python install walkthrough first.
Install from PyPI:
pip install lastfm_monitorRun the setup wizard:
lastfm_monitor --setupThe wizard asks for the target, the Last.fm API credentials and optional notifications. Review the settings before saving them. See Setup & First Run for how to get the Last.fm API key and shared secret and the required privacy settings.
For the manual single-file method, dependencies and upgrade commands, see Installation.
- Listening activity: Track songs, active and inactive periods, pauses and resumes.
- Playback detail: Show listening duration, skipped tracks and an optional progress indicator.
- Profile changes: Track followers, followed accounts, About Me bio and display name.
- Activity gaps: Detect offline listening and estimate Spotify private mode, which is not always accurate.
- Spotify playback: Follow the tracked user's songs, pauses and resumes in your local Spotify client.
- Session statistics: Summarize listening time, tracks, skips, repeats and pauses.
- Last.fm Wrapped: Generate top artist, track and album statistics from CSV history.
- Music and lyrics links: Open configurable searches from console output and email.
- Event alerts: Configure email, Discord and ntfy notifications for listening and profile changes.
- CSV history: Save listened tracks with timestamps.
- Saved state: Retain activity, friend lists and tracked profile fields across restarts.
- Guided setup: Configure the monitor with
--setupand check readiness with--doctor. - Flexible settings: Use config files, dotenv files, environment variables and command-line options.
- Runtime controls: Adjust the running monitor through supported signals.
Use Quick Install & Run above for first-time setup. The table uses PyPI commands. For the manual script equivalents, see Run Individual Commands.
Replace the target placeholders with a Last.fm username. Monitoring requires the Last.fm API key and shared secret described in the setup guide.
| I want to... | Run this |
|---|---|
| Configure the target, credentials and alerts | lastfm_monitor --setup |
| Start monitoring with existing authentication | lastfm_monitor <lastfm_username> |
| Check authentication, connectivity and one target | lastfm_monitor --doctor <lastfm_username> |
| Enter or replace securely the Last.fm API key and shared secret | lastfm_monitor --set-lastfm-credentials |
| Enter or replace securely the optional Spotify credentials for track details | lastfm_monitor --set-spotify-credentials |
| Configure and test webhook alerts | Use the setup wizard or follow Webhook Settings |
| Save an SMTP password for email alerts | lastfm_monitor --set-smtp-password |
| Send a test email | lastfm_monitor --send-test-email |
| Save a new webhook URL | lastfm_monitor --set-webhook-url |
| Send a test webhook | lastfm_monitor --send-test-webhook |
| List the ten most recent tracks | lastfm_monitor <lastfm_username> -l -n 10 |
| Alert on the tracks and albums listed in a file | lastfm_monitor <lastfm_username> -s tracks.txt |
| Write every scrobble to a CSV file | lastfm_monitor <lastfm_username> -b scrobbles.csv |
| Play every scrobble in your own Spotify client | lastfm_monitor <lastfm_username> -g |
| Use a specific configuration and secrets file | lastfm_monitor --config-file lastfm_monitor.conf --env-file .env <lastfm_username> |
| List every supported command-line flag | lastfm_monitor --help |
The monitored account must expose the activity described in User Privacy Settings.
Running the tool with no arguments offers the wizard if you have not saved a user. If a user is already saved, it starts monitoring that user.
The tool runs until interrupted (Ctrl+C). Use tmux or screen for persistence and run multiple copies to monitor several users.
For credentials, saved users and notification setup, see the full Setup & First Run guide.
For the Spotify metadata backends, email and webhook setup, see Configuration. For notification choices, listing commands, automatic playback and output files, see Usage.
If a run fails, start with Doctor Preflight.
Full documentation is available at misiektoja.github.io/lastfm_monitor:
| Page | What it covers |
|---|---|
| Installation | Python walkthrough, PyPI or manual installation, upgrades |
| Setup & First Run | Setup wizard, Last.fm credentials, privacy settings, the first monitoring run |
| Configuration | Config file, Spotify metadata backends, SMTP, webhooks, storing secrets, check intervals |
| Usage | Monitoring mode, listing mode, notifications, CSV export, automatic playback, signals, terminal output |
| Troubleshooting | --doctor preflight checks, what to do when something fails, --verbose and --debug output |
| Testing | Running the offline suite, the linter and the docs build |
| About | Change log, contributing, security, license, support |
See RELEASE_NOTES.md for details.
Bug reports, documentation fixes and code contributions are welcome. See CONTRIBUTING.md for the development setup, the checks CI enforces and what a change needs before it is merged. Participation is covered by the Code of Conduct.
Report a suspected vulnerability privately through GitHub security advisories, never as a public issue. SECURITY.md covers the reporting process, the supported versions and the security posture of stored credentials and configuration loading.
- misiektoja (@misiektoja)
Licensed under GPLv3. See LICENSE. Dependency licenses are listed in THIRD_PARTY_NOTICES.md.
Questions, bug reports and vulnerability reports each have a place, listed in SUPPORT.md.
If the project is useful to you, you can support its development through GitHub Sponsors or Buy Me a Coffee.