Self-hosted background-audio scrobbler. It listens to audio inputs (a mic, a line-in, a USB turntable, or the audio of your security cameras), identifies songs with Shazam, and scrobbles them to Last.fm, Libre.fm, ListenBrainz, and Maloja. Point it at a radio, a TV, or every room in the house.
On this page: How it works, Requirements, Quick start and Notes.
Guides, step by step
- Home Assistant: from adding the add-on repository to a room that scrobbles and a dashboard card.
- Kubernetes with Helm: secrets, storage, HTTPS for phones, and a sound card on one node.
- Proxmox VE: a USB turntable passed through to a VM or an LXC container.
- A phone as the microphone: HTTPS, permissions, and good matches on an iPhone or Android.
Set up
- Install: Docker, a systemd service or Kubernetes with Helm.
- Rooms and cameras: cameras, USB turntables, finding your audio device and the two ways to listen.
- Accounts and configuration: accounts, every environment variable, connecting Last.fm and cover art.
- Home Assistant: the add-on and devices over MQTT.
- A display by the hi-fi: show what a room plays on a tablet, a Raspberry Pi, a Home Assistant dashboard or an ESP32 with ESPHome.
Reference
- API: every route, and a REST sensor for Home Assistant.
- Architecture: diagrams of one room's cycle, and of rooms sharing the Shazam rate limit.
- Troubleshooting: what to check when nothing matches, and the measured recognition limits.
- Releasing: for maintainers, how a version is published and verified.
Every 15 seconds, ffmpeg records a 12-second chunk in each room. A room is one input: a microphone on the server, or a camera's RTSP or RTSPS stream. See Rooms and cameras. shazamio builds an audio signature locally and asks the Shazam API for a match.
This is the whole path, from input to scrobble. Architecture shows one room's cycle, and how rooms share Shazam.
flowchart TD
accTitle: How scrobSter turns sound into scrobbles
accDescr: A sound card or a camera feeds ffmpeg, which records a clip in each room. A silent or quiet clip is dropped. Otherwise its locally made fingerprint goes to Shazam, as does a clip posted from a browser microphone. A match gets MusicBrainz IDs from its ISRC and, if it is a new play for the user, is scrobbled to their Last.fm, Libre.fm, ListenBrainz and Maloja. Match and scrobble events also go to Home Assistant over MQTT and to GET /api/events.
mic["Sound card on the server"] --> cap
cam["Camera or stream"] --> cap
cap["ffmpeg records a clip in each room"] --> level{"Silent or quiet?"}
level -- "yes, ask nothing" --> cap
level -- no --> shazam["Shazam. Only the fingerprint, made locally, is sent"]
browser["Microphone in a browser"] -- "POST /api/match" --> shazam
shazam -- match --> enrich["MusicBrainz IDs, from the ISRC"]
enrich --> dedupe{"New play for this user?"}
dedupe -- yes --> services["Each user's Last.fm, Libre.fm, ListenBrainz, Maloja"]
shazam -- "match and scrobble events" --> events["MQTT to Home Assistant, and GET /api/events"]
A match does two things. It marks the track as playing now, so your profile shows the live "scrobbling now" line while the song continues. It also scrobbles the track once per play. A track that keeps playing is not scrobbled again, but a track that restarts is, because scrobSter compares the match offset. See Recognition limits.
When the music stops, the mark is removed. After NOW_PLAYING_STOP_SECONDS with
no match, scrobSter clears it, and it also clears it when you stop the listener.
ListenBrainz and Maloja are cleared through an API call. Last.fm has no method to
clear a mark, so its own copy disappears a few minutes later.
The default of 180 seconds is deliberate. Matches drop out during quiet passages, so a shorter limit would make the mark flicker during a song.
A web page shows the current match and the history. The JSON API serves mobile clients and Home Assistant.
Each person has an account and connects their own scrobbling services in Settings. A room is shared, so every user chooses, room by room on the Rooms tab, whether to receive what it hears. A microphone in a browser is different: that listen belongs to the person who recorded it, and goes only to them.
- Python 3.10 - 3.13
- ffmpeg on PATH
- An audio input device
python3 -m venv .venv
.venv/bin/pip install -r requirements.txtPut your settings in a .env file next to the code. Git ignores this file, and
your secrets stay out of the shell history.
# .env
AUDIO_DEVICE=:1
ADMIN_PASSWORD=choose-something-longThen start it:
.venv/bin/python -m scrobsterA real environment variable always overrides the file, so Docker and systemd work as usual.
Open http://localhost:8000 and sign in as admin. Connect your scrobbling
services under Settings.
Without ADMIN_PASSWORD, the first start makes a random password and writes it
to the log once. Read it there, then change it in Settings.
Toggle listening from the page.
Test recognition with a file first:
.venv/bin/python -m scrobster.listener some-song.wav- The Shazam API is unofficial and can change or block at any time. Keep
MATCH_INTERVALat 12 seconds or higher. - Scrobbles fire at match time, not at track end. This is fine for radio.
- Run the logic self-check with
.venv/bin/python test_scrobster.py. requirements.txtpins exact versions, so a rebuild cannot pull a shazamio that breaks matching. Dependabot opens weekly pull requests for the pins, the GitHub Actions and the base image; CI tests each one.
