Skip to content

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.

You can specify the style of payload MS will send to your endpoint using payloadStyle (or ENV BLACKBOX_PAYLOAD_STYLE):

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.

Download Scrobble 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": "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" }
}
}
}

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.

Optional URLs Multi-Scrobbler calls with a GET request (including your headers) when the Client starts:

  • endpointHealth (or ENV BLACKBOX_ENDPOINT_HEALTH) checks that your service is reachable and ready
  • endpointAuth checks that your headers are 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 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