Blackbox
Blackbox is a generic Client that sends your scrobbles and Now Playing activity to any URL you choose, like a webhook.
Use it to feed your own app, script, or home automation with listening activity from any of your Sources.
One-Way Only
For a Blackbox Client, Multi-Scrobbler only sends data to your endpoint.
It deliberately does not have any functions for fetching existing scrobbles from your client (for duplicate detection). This is to keep the Blackbox implementation simple.
If you need this richer functionality you are better off emulating a Listenbrainz Client.
Note Blackbox does still do duplicate detection but only uses scrobbles Multi-Scrobbler has already sent to this Client.
Your endpoint must accept a POST request with a JSON body. Any 2xx response is treated as a successful scrobble. Anything else fails the scrobble and it will be retried later.
Payload
Section titled “Payload”You can specify the style of payload MS will send to your endpoint using payloadStyle (or ENV BLACKBOX_PAYLOAD_STYLE):
ms(default) - sends Multi-Scrobbler’s in-house Play objectlistenbrainz- same payload as the ListenBrainz submit listens API.
Sends payloads with Multi-Scrobbler’s in-house Play object.
This contains much more information than listenbrainz style but its specific to MS. Use in config like:
- File/AIO -
"payloadStyle": "ms" - ENV -
BLACKBOX_PAYLOAD_STYLE=ms
Note Now Playing uses the same behavior as Discord and othe realtime Clients IE events are sent when a Source Player is stopped, paused, Play changes, etc…
Configuration Explorer, Json Schema Download, and Example
play is the scrobbled Play.
Structure
All possible properties with their shape, types, and descriptions.
Example
An example that adheres to the shown Structure. Edits are validated against it, any errors show up as squiggly lines.
{ "type": "scrobble", "play": { "data": { "track": { "name": "Hand In Glove", "metadata": [ { "name": "spotify", "id": "1xlkleZh90GUEyBegEKyr3", "idType": "track" }, { "name": "isrc", "id": "GBKQU2696027" } ] }, "artists": [ { "name": "The Smiths", "metadata": [ { "name": "musicbrainz", "id": "5df4799b-67f4-4ccd-97c7-bc8114b727e0", "idType": "artist" } ] } ], "albumArtists": [{ "name": "The Smiths" }], "album": { "name": "The Smiths", "image": "https://example.com/art/the-smiths.jpg" }, "duration": 205, "playDate": "2026-11-13T14:05:00.000Z", "listenedFor": 198 }, "meta": { "source": "jellyfin", "parsedFrom": "player", "trackId": "a1b2c3d4", "user": "foxx", "deviceId": "living-room-tv", "mediaPlayerName": "Jellyfin Web", "url": { "web": "https://jellyfin.example.com/details?id=a1b2c3d4" } } }}play is the Player reporting Now Playing, which includes the Play being listened to. When Now Playing stops, play is null.
Download Now Playing JSON Schema
Structure
All possible properties with their shape, types, and descriptions.
Example
An example that adheres to the shown Structure. Edits are validated against it, any errors show up as squiggly lines.
{ "type": "nowPlaying", "play": { "platformId": "living-room-tv-foxx", "playerLastUpdatedAt": "2026-11-13T14:06:30.000Z", "position": 90, "listenedDuration": 88, "status": { "reported": "playing", "calculated": "playing", "stale": false, "orphaned": false }, "play": { "data": { "track": { "name": "Hand In Glove", "metadata": [ { "name": "spotify", "id": "1xlkleZh90GUEyBegEKyr3", "idType": "track" }, { "name": "isrc", "id": "GBKQU2696027" } ] }, "artists": [ { "name": "The Smiths", "metadata": [ { "name": "musicbrainz", "id": "5df4799b-67f4-4ccd-97c7-bc8114b727e0", "idType": "artist" } ] } ], "album": { "name": "The Smiths" }, "duration": 205, "playDate": "2026-11-13T14:05:00.000Z" }, "meta": { "source": "jellyfin", "parsedFrom": "player", "deviceId": "living-room-tv", "trackProgressPosition": 90 } } }}The same payload as the ListenBrainz submit listens API.
- File/AIO -
"payloadStyle": "listenbrainz" - ENV -
BLACKBOX_PAYLOAD_STYLE=listenbrainz
Scrobbles use "listen_type": "single" and Now Playing uses "listen_type": "playing_now".
Note Now Playing uses the same behavior as Listenbrainz IE events are only sent when the current Play changes.
Headers
Section titled “Headers”Use headers to send extra headers with every request, like an API key or token:
"headers": { "Authorization": "Bearer mytoken"}Header values are partially redacted when logged on startup.
Health and Auth Checks
Section titled “Health and Auth Checks”Optional URLs Multi-Scrobbler calls with a GET request (including your headers) when the Client starts:
endpointHealth(or ENVBLACKBOX_ENDPOINT_HEALTH) checks that your service is reachable and readyendpointAuthchecks that yourheadersare accepted- Note There is no ENV equivalent for this due to the potential complexity of headers. You will need to use File/AIO config if you need auth + headers.
A 2xx response is treated as success. If these are not set, Multi-Scrobbler skips the check and assumes your endpoint is ready.
Configuration
Section titled “Configuration”Configuration Type
This is configuration for the ENV Config Type.
| Environmental Variable | Type | Default | Description |
|---|---|---|---|
BLACKBOX_ID |
string | A globally unique ID EX myComponentId |
|
BLACKBOX_NAME |
string | Value of BLACKBOX_ID |
A vanity name EX My Cool Component |
BLACKBOX_ENABLE |
boolean | true | Should this component be used? |
BLACKBOX_ENDPOINT |
string | URL scrobble payloads are sent to | |
BLACKBOX_ENDPOINT_HEALTH |
string | URL to use for testing service is reachable and ready. Any 2xx response is treated as success. | |
BLACKBOX_PAYLOAD_STYLE |
listenbrainz OR ms | ms | Format of the payload sent to endpoint |
Bold/Italic = Required
Config Structure
This displays the structure of the File Configuration for a blackbox type Client with all possible properties, their shape, and descriptions/types. Use this to understand how to write a valid config.
Config Example
This displays an example config file of a blackbox Client File Configuration that adheres to the shown Config Structure.
- text mode lets you edit the JSON directly.
- tree mode gives you a guided point-and-click editing experience that always keeps the JSON syntax valid.
Both modes validate that the configuration is correct. Any errors show up as squiggly lines.
After you finish editing, switch to text and then copy all text to get a completed config.
Config Example Mobile Experience
This displays an example config file of a blackbox Client File Configuration that adheres to the shown Config Structure.
The example config file editor is meant for a larger screen experience so only the read-only example is shown. Please use this site on a tablet/laptop/desktop to enable file editor features.
[ { "id": "MyBlackbox", "name": "MyCoolBlackbox", "data": { "endpoint": "http://192.168.1.100:8080/scrobble", "payloadStyle": "ms", "headers": { "Authorization": "Bearer mytoken" } }, "enable": true }]Config Structure
This displays the structure of the all-in-one (config.json) configuration with all possible properties, their shape, and descriptions/types. Use this to understand how to write a valid config.
Select the blackbox type from the respective clients node below, then expand it.
Config Example
This displays an example config file of a all-in-one (config.json) configuration that includes a blackbox Client that adheres to the shown Config Structure.
- text mode lets you edit the JSON directly.
- tree mode gives you a guided point-and-click editing experience that always keeps the JSON syntax valid.
Both modes validate that the configuraion is correct. Any errors show up as squiggly lines.
After you finish editing, switch to text and then copy all text to get a completed config.
Config Example Mobile Experience
This displays an example config file of a all-in-one (config.json) configuration that includes a blackbox Client that adheres to the shown Config Structure.
The example config file editor is meant for a larger screen experience so only the read-only example is shown. Please use this site on a tablet/laptop/desktop to enable file editor features.
{ "clients": [ { "type": "blackbox", "id": "MyBlackbox", "name": "MyCoolBlackbox", "data": { "endpoint": "http://192.168.1.100:8080/scrobble", "payloadStyle": "ms", "headers": { "Authorization": "Bearer mytoken" } }, "enable": true } ]}