Koito

Other Uses

To monitor and re-scrobble activity from a Koito account create a Koito (Source)

Setup a Koito server if you have not already done this.

• Create (or get) an API Key
  • From your Koito server dashboard navigate to Settings (bottom-left icon) => API Keys
  • Create a new Key (or use an existing) and Copy the key using the copy icon to the right of the key
  • EX pM195xPV98CDpk0QW47FIIOR8AKATAX5DblBF-Jq0t1MbbKL
• Take note of your Koito username (used below as KOITO_USER)
• Determine your Koito URL
  • This is the URL you use to access your Koito dashboard OR whatever URL is accessible from your multi-scrobbler instance.
  • EX dashboard at http://192.168.0.100:4110 => KOITO_URL is set to http://192.168.0.100:4110

Koito Base URL

Using the URL path /apis/listenbrainz Koito docs describe is not required. The Koito URL used for multi-scrobbler should only be the base URL. Only include a URL path if your Koito base url is not at host:port. See the table below for examples.

Base URL Examples

KOITO_URL	MS Detected Base URL	Example Scrobble Api URL
http://192.168.0.100:4110	http://192.168.0.100:4110	http://192.168.0.100:4110/apis/listenbrainz/1
https://koito.mydomain.com	https://koito.mydomain.com	https://koito.mydomain.com/apis/listenbrainz/1
http://192.168.0.100:4110/apis/listenbrainz	http://192.168.0.100:4110	http://192.168.0.100:4110/apis/listenbrainz/1
http://192.168.0.100:80/koito	http://192.168.0.100:80/koito	http://192.168.0.100:80/koito/apis/listenbrainz/1

Tip

For Koito versions <=0.1.7, you must have the environment variable KOITO_ALLOWED_HOSTS set correctly in your Koito environment/container. Ensure it is set to the IP address or domain name that you use to access Koito with e.g. koito.mydomain.com.

Configuration

Scrobbling Device Data

Many Sources report device identifiers with their listening data which can be included in the scrobble data for this client.

However, Multi-Scrobbler does not include this information in scrobble data because it can contain Personally Identifiable Information (PII).

You can opt-in to including this data by defining an explicit list of identifiers that are matched against real device idenitifiers that are then used instead of the real identifier, when scrobbling.

You define a list of matching strings with optional labels. The most-specific matched-string to a real device identifier gets picked and then it, or it’s label, is used as the device identifier in the scrobble data.

Examples and Configuration

In each of the examples configurations below, the resulting behavior for device identifier reporting is…

• Any device with the string iphone in it will be reported as only iphone
• A device with the string smithFamily-roku will be reported as familyRoku
• Any other device with the string roku in it will be reported as roku

ENV

Define a comma-delimited list of match:label entries to the env KOITO_ALLOW_DEVICE_LIST

services:
  multi-scrobbler:
    # ...
    environment:
      # ...
      - KOITO_ALLOW_DEVICE_LIST=iphone,roku,smithFamily-roku:familyRoku

File

Define a dictionary of allowDeviceList entries. Entries without a label should use an empty string.

{
    "id": "MyClient",
    "data": { /* ... */},
    "options": {
        // ...
        "allowDeviceList": {
            "iphone": "",
            "smithFamily-roku": "familyRoku",
            "roku": ""
        }
    }
}

AIO

Define a dictionary of allowDeviceList entries. Entries without a label should use an empty string.

config.json

{
    "clients": [{
        "id": "MyClient",
        "type": // ...,
        "data": { /* ... */ },
        "options": {
            // ...
            "allowDeviceList": {
                "iphone": "",
                "smithFamily-roku": "familyRoku",
                "roku": ""
            }
        }
    }]
}

ENV

Configuration Type

This is configuration for the ENV Config Type.

Environmental Variable	Type	Default	Description
KOITO_ID	string		A globally unique ID EX myComponentId
KOITO_NAME	string	Value of KOITO_ID	A vanity name EX My Cool Component
KOITO_ENABLE	boolean	true	Should this component be used?
KOITO_URL	string		URL for the Koito server
KOITO_TOKEN	string		User token for the user to scrobble for
KOITO_USER	string		Username of the user to scrobble for
KOITO_ALLOW_DEVICE_LIST	string		A comma-delimited list of match:label entries to use as media_play in scrobble submit data, when none is present.

Bold/Italic = Required

File

Config Structure

This displays the structure of the File Configuration for a koito 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 koito 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.

Important

Only client koito configs will validate correctly in the editor but both source and client koito configs are allowed in the real CONFIG/koito.json

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 koito 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.

CONFIG/koito.json

[
  {
    "id": "myKoitoClient",
    "name": "Koito Client A",
    "data": {
      "url": "http://192.168.0.100:4110",
      "token": "029b081ba-9156-4pe7-88e5-3be671f5ea2b",
      "username": "admin"
    },
    "configureAs": "client"
  }
]

AIO

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 koito 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 koito 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 koito 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.

CONFIG/config.json

{
  "clients": [
    {
      "type": "koito",
      "id": "myKoitoClient",
      "name": "Koito Client A",
      "data": {
        "url": "http://192.168.0.100:4110",
        "token": "029b081ba-9156-4pe7-88e5-3be671f5ea2b",
        "username": "admin"
      },
      "configureAs": "client"
    }
  ]
}