diff --git a/404.html b/404.html index 47cdda73..6e1ff891 100644 --- a/404.html +++ b/404.html @@ -5,8 +5,8 @@
MS will parse configuration from all configuration types. You can mix and match configurations but it is generally better to stick to one or the other.
MS will parse environmental variables present in the OS/container when it is run. This method means MS does not require files to run.
For Docker container...
docker run -e "SPOTIFY_CLIENT_ID=yourId" -e "SPOTIFY_CLIENT_SECRET=yourSecret" ...
For Docker Compose
services: multi-scrobbler: image: foxxmd/multi-scrobbler environment: - SPOTIFY_CLIENT_ID=yourId - SPOTIFY_CLIENT_SECRET=yourSecret - MALOJA_URL=http://domain.tld:42010 - MALOJA_API_KEY=1234 # ... # ...
For a local/node installation export variables before running...
SPOTIFY_CLIENT_ID=yourId SPOTIFY_CLIENT_SECRET=yourSecret npm run start
MS will parse configuration files located in the directory specified by the CONFIG_DIR environmental variable. This variable defaults to:
CONFIG_DIR
PROJECT_DIR/config
/config
MS will parse configuration from all configuration types. You can mix and match configurations but it is generally better to stick to one type.
MS will parse environmental variables present in the OS/container when it is run.
This method means MS does not require config files but it will still create and use data files in the local or docker data directory.
services: multi-scrobbler: image: foxxmd/multi-scrobbler environment: - JELLYFIN_URL=192.168.0.110:8096 - JELLYFIN_APIKEY=c9fae8756fbf481ebd9c5bb56b - JELLYFIN_USER=MyUser - JELLYFIN_ID=myJellyin # ... # ...
.json
Each file is named by the type of the Client/Source found in below sections. Each file as an array of that type of Client/Source.
Example directory structure:
/CONFIG_DIR plex.json spotify.json maloja.json
[ { "id": "MySpotify", "name": "Foxx Spotify", "enable": true, "clients": [], "data": { "clientId": "a89cba1569901a0671d5a9875fed4be1", "clientSecret": "ec42e09d5ae0ee0f0816ca151008412a", "redirectUri": "http://localhost:9078/callback", "interval": 60 } }]
MS will parse an all-in-one configuration file located in the directory specified by the CONFIG_DIR environmental variable. This variable defaults to:
PROJECT_DIR/config/config.json
/config/config.json
Each config file is named after the type of the Client/Source. Within each file, a JSON array defines all of the instances for that type of Client/Source.
/CONFIG_DIR jellyfin.json lastfm.json koito.json
[ { "name": "Foxx JF Server", "id": "foxxJf", "data": { "url": "http://localhost:8096", "user": "FoxxMD", "apiKey": "c9fae8756fbf481ebd9c5bb56bd6540c" } }]
[ { "name": "Foxx JF Server", "id": "foxxJf", "data": { "url": "http://localhost:8096", "user": "FoxxMD", "apiKey": "c9fae8756fbf481ebd9c5bb56bd6540c" } }, { "name": "Foo's JF Server", "id": "fooJf", "data": { "url": "http://192.168.0.150:8096", "user": "foo", "apiKey": "9c5bb56bd6540c756fbf481ebd9c5c40" } }]
MS will parse an all-in-one configuration file (config.json) located in the directory specified by the CONFIG_DIR environmental variable. The file's location defaults to:
config.json
The AIO config also enables setting default options for sources/clients as well as global options for MS itself.
/config/config.json.example
Explore the schema for this configuration, along with an example generator and validator, here
{ "debugMode": false, "disableWeb": false, "sourceDefaults": { "logPayload": false, "logFilterFailure": "warn", "logPlayerState": false, "scrobbleThresholds": { "duration": 30, "percent": 50 }, "maxPollRetries": 1, "maxRequestRetries": 1, "retryMultiplier": 1.5 }, "clientDefaults": { "maxRequestRetries": 1, "retryMultiplier": 1.5 }, "sources": [ { "type": "spotify", "enable": true, "clients": ["myConfig"], "name": "Cool Spotify Name", "id": "mySpotifyId", "data": { "clientId": "a89cba1569901a0671d5a9875fed4be1", "clientSecret": "ec42e09d5ae0ee0f0816ca151008412a", "redirectUri": "http://localhost:9078/callback" } } ], "clients": [ { "type": "maloja", "enable": true, "name": "Foxx Maloja", "id": "myMalojaId", "data": { "url": "http://localhost:42010", "apiKey": "myMalojaKey" } } ], "webhooks": [ { "name": "FirstGotifyServer", "type": "gotify", "url": "http://localhost:8070", "token": "MyGotifyToken", "priorities": { "info": 5, "warn": 7, "error": 10 } }, { "type": "ntfy", "name": "MyNtfyFriendlyNameForLogs", "url": "http://localhost:9991", "topic": "MyMultiScrobblerTopic", "username": "Optional", "password": "Optional", "priorities": { "info": 3, "warn": 4, "error": 5 } } ]}
Compared to their File equivalent, Sources/Clients configured using AIO require an additional type property.
type
[ { "name": "Foxx JF Server", "type: "jellyfin", "id": "foxxJf", "data": { "url": "http://localhost:8096", "user": "FoxxMD", "apiKey": "c9fae8756fbf481ebd9c5bb56bd6540c" } }]
You can find an example of the required type value by referring to the AIO tab in each Source/Client's Configuration section example.
See the Configuration Types above for your options for creating Source and Client configurations.
Multi-scrobbler will not throw an error if the environmental value is not found. Instead, it will leave the string as-is and log a warning (WARN level) with the names of the missing environmental variable names like so:
WARN
WARN : [App] [Sources] [spotify Secrets] Matched: None | Unmatched: SPOTIFY_SECRET
Verify that interpolation keys/environmental variable names you will use do not collide with existing ENV names used by multi-scrobbler. Use the docs search to verify the name you want to use is not already used elsewhere by multi-scrobbler.
Defines the URL that is used to generate default redirect URLs for authentication on spotify and lastfm -- as well as some logging hints.
Defines the URL that is used to generate default redirect URLs for authentication for services like spotify and lastfm -- as well as some logging hints.
http://localhost:9078
BASE_URL
baseUrl
Useful when running with docker so that you do not need to specify redirect URLs for each configuration.
EX Lastfm Redirect Url is BASE_URL:PORT/lastfm/callback (when no other redirectUri is specified for lastfm configuration)
BASE_URL:PORT/lastfm/callback
192.168.0.101
http://192.168.0.101:9078/lastfm/callback
http://my.domain.local
http://my.domain.local:9078/lastfm/callback
http://192.168.0.101/my/subfolder
http://192.168.0.101:9078/my/subfolder/lastfm/callback
my.domain.local:80
http://192.168.0.101:80/lastfm/callback
my.domain.local:9000
http://my.domain.local:9000/lastfm/callback
192.168.0.101:4000/my/subfolder
http://192.168.0.101:4000/my/subfolder/lastfm/callback
https://192.168.0.101
https://192.168.0.101:443/lastfm/callback
Multi-scrobbler implements caching to persist important data across restarts, reduce external API calls, and make some actions faster.
Multi-scrobbler implements caching to reduce external API calls and make some actions faster.
A default in-memory cache store is used so that you always benefit from some caching. An optional, secondary store can be configured for greater caching capabilities.
Authentication sessions/tokens/etc... are cached for quicker requests and for persistence across restarts.
The results of transform rules are cached so that if a scrobble with identical data (track/artists/album) is identified and it has the same set of transform rules then the cached transform results can be applied.
API Calls to external (metadata) services used to Enhance Scrobbles, like calls to Musicbrainz, can be cached to avoid duplicate calls and speed up scrobble transformations.
Auth caching defaults to a file that is stored in the CONFIG_DIR directory using the pre-defined file name ms-auth.cache.
ms-auth.cache
This provides automatic persistence across restarts for long-lived auth data/credentials if you have configured a persisted volume/bind mount for configuration (/config is mounted in docker compose).
If you wish to use the secondary store for caching Auth you must explicitly configure it. This is because valkey can potentially be ephemeral if you do not provide a volume for its data directory.
To explicitly configure auth to use the secondary store:
services: multi-scrobbler: # ... environment: - CACHE_AUTH=valkey # ...
{ "cache": { "auth": { "provider": "valkey" } }, // ...}
Auth caching defaults to a file that is stored in the DATA_DIR directory using the pre-defined file name ms-auth.cache.
DATA_DIR
Using a secondary store enables:
Multi-scrobbler depends on a SQLite database (ms.db) that is created on first run and stored in the CONFIG_DIR. When upgrading Multi-scrobbler version, if there are any required database changes than this database is automatically backed up and migrated.
ms.db
The database stores all Plays for your Sources/Clients as well as metadata and debugging information to help troubleshoot issues. Each Play is associated with a Source/Config in the database based on your configuration.
You should set IDs for each Source/Client so that the database can identify these even when the configuration is changed.
You must set IDs for each Source/Client so that the database can identify these even when the configuration is changed.
The amount of data stored for each Play can widely vary based on a few factors:
This Source has the same data limitations as the Last.fm (Source) and Last.fm (Client) have: Last.fm does not support separating artists/album artists fields which means any multi-artist tracks will have all artists combined into one string. This makes scrobbling to other services, and using metadata corrections like Musicbrainz, more difficult.
If your application has the option to scrobble using Listenbrainz then use the Listenbrainz (Endpoint) Source instead.
If a slug is not provided in configuration then multi-scrobbler will accept Last.fm scrobbles at
http://localhost:9078/2.0/
which is the "standard" Last.fm server path for scrobbling
Use a slug only if you need to setup multiple Last.fm Endpoint sources and cannot use different tokens.
If a slug is used then the URL will be:
http://localhost:9078/api/lastfm/mySlug
When setting up your Last.fm client to communicate with Multi-Scrobbler replace the Last.fm domain with your Multi-Scrobbler domain:
https://last.fm => https://yourMSDomain
MS accepts Last.fm API calls with the same url base and structure as the last.fm api, IE http://yourMSDomain/2.0/
http://yourMSDomain/2.0/
If you are only setting up one Lastfm Endpoint Source then you do not need to configure any explicit username/apiKey/password for MS. If your Last.fm Client requires these credentials use any fake values you want.
Currently, Multi-Scrobbler only supports the Mobile Application auth flow. If your client requires one of the other authentication flows please open an issue.
Note: Your client does not need to implement any auth in order to use a Lastfm Endpoint Source. You can directly make track.scrobble or track.updateNowPlaying api calls to http://yourMSDomain/2.0/ with any fake auth data you want.
track.scrobble
track.updateNowPlaying
If you have more than one Lastfm Endpoint Source then you should configure username/apiKey for MS, per Source. This enables MS to differentiate scrobbles for each Source.
Use the same username and/or API Key you configure with MS when setting up your Last.fm Client. These values can be anything you want, as long as they match between MS and your client. Password can be anything and is not checked.
If you cannot use different username/apiKey per Source (or Last.fm Client) you can still differentiate Sources by using a different url base (slug) for Last.fm communication.
Setting a slug in config will change the url base for MS like this:
slug: "mySlug"
http://yourMsDomain/api/lastfm/mySlug
The above url base is equivalent to making calls to http://yourMSDomain/2.0/
This is configuration for the ENV Config Type.
LFM_ID
myComponentId
LFM_NAME
My Cool Component
LFM_ENABLE
LFM_SLUG
Bold/Italic = Required
This displays the structure of the File Configuration for a endpointlfm type Source with all possible properties, their shape, and descriptions/types. Use this to understand how to write a valid config.
This displays an example config file of a endpointlfm Source File Configuration that adheres to the shown Config Structure.
LFM_USERNAME
LFM_API_KEY
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.
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.
[ { "name": "LFM For App", "enable": true, "id": "myLfmApp", "data": { "slug": "mySlug" } }]
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 endpointlfm type from the respective sources node below, then expand it.
sources
This displays an example config file of a all-in-one (config.json) configuration that includes a endpointlfm Source that adheres to the shown Config Structure.
{ "sources": [ { "name": "LFM For App", "enable": true, "id": "myLfmApp", "data": { "slug": "mySlug" }, "type": "endpointlfm" } ]}