Configuring the Web API

To configure the Web API, duplicate the .env.example file in the webui/apifolder, then set the various environmental values. Alternatively, you can set the necessary and optional values with regular system level environmental values.

API specific values

Env. var. name	Required	Description
DB_HOST	Yes	MySQL database host. Example: localhost
DB_PORT	Yes	MySQL database port. Example: 3306
DB_NAME	Yes	MySQL database name. Example: tunesynctool
DB_USER	Yes	MySQL database username.
DB_PASSWORD	Yes	MySQL database password.
APP_SECRET	Yes	API secret. Used for signing JWTs.
ENCRYPTION_KEY	Yes	Used to encrypt authentication data for providers.
ENCRYPTION_SALT	Yes	Used to encrypt authentication data for providers.
REDIS_HOST	Yes	Connection host for Redis. Example: localhost
REDIS_PORT	Yes	Connection port for Redis. Example: 6379
ADMIN_PASSWORD	Yes	Password for the admin/default user.
APP_HOST	Yes	Full base URL of the API. Example: "https://api.tunesynctool.example.com"

Provider specific values

You don't have to configure all providers. You cannot partially set environmental values either, otherwise the API will fail to start on purpose.

Unconfigured providers and content related to them is hidden from API responses and the web UI aswell. If you have previously configured a provider, but then "unconfigured" it, you won't be able to reconnect your accounts or access any data tied to that provider account until you reconfigure the provider. For example, if you remove environmental values for Spotify, tunesynctool won't be able to load your Spotify playlists or show your previous tasks that involved Spotify because it is unable to fetch the necessary data from Spotify.

Spotify

Env. var. name	Description
SPOTIFY_CLIENT_ID	Spotify Client ID.
SPOTIFY_CLIENT_SECRET	Spotify Client secret.

How to obtain: https://developer.spotify.com/documentation/web-api/concepts/apps

Subsonic compatible

Env. var. name	Description
SUBSONIC_BASE_URL	Subsonic provider's base URL.
SUBSONIC_PORT	Subsonic provider's port.
SUBSONIC_LEGACY_AUTH	Whether to use legacy authentication with the Subsonic provider. By default this is off.

YouTube Music (Google)

Env. var. name	Description
GOOGLE_CLIENT_ID	Google client ID.
GOOGLE_CLIENT_SECRET	Google client secret.

How to obtain: https://developers.google.com/identity/protocols/oauth2/web-server#enable-apis

Deezer

Deezer support is experimental at the moment and does not require any manual configuration from the user.

---

Configuring the Python package and CLI

How to read the table below: if a value is marked as optional and the default value associated with it isn't None, the default value will be used as a fallback if the environmental variable isn't provided. Also, there's no need to set all the values. Only set the values for the services that you actually want to interact with.

CLI option name	Env. var. name	Default value	Description
--spotify-client-id	SPOTIFY_CLIENT_ID	None	Client ID of the Spotify app you created
--spotify-client-secret	SPOTIFY_CLIENT_SECRET	None	Client secret of the Spotify app you created
--spotify-redirect-uri	SPOTIFY_REDIRECT_URI	http://localhost:8888/callback	Callback URL of the Spotify app you created
--subsonic-base-url	SUBSONIC_BASE_URL	http://127.0.0.1	Base URL of your Subsonic compatible API
--subsonic-port	SUBSONIC_PORT	4533	Port of your Subsonic compatible API
--subsonic-username	SUBSONIC_USERNAME	None	Username to authenticate with your Subsonic compatible service
--subsonic-password	SUBSONIC_PASSWORD	None	Password to authenticate with your Subsonic compatible service
--subsonic-legacy-auth	SUBSONIC_LEGACY_AUTH	False	Whether to enable legacy authentication for the Subsonic server.
--deezer-arl	DEEZER_ARL	None	ARL token to authenticate with your Deezer account
--youtube-request-headers	YOUTUBE_REQUEST_HEADERS	None	Raw request headers from an authenticated request sent by your browser to music.youtube.com

[!TIP] The Supported services page has instructions to obtain the values listed here.

Using the Configuration class

You can import the Configuration class from the tunesynctool package as usual.

from tunesynctool import Configuration

You have the option to programmatically initialize a new Configuration object through its constructor or by loading options from environmental variables.

[!NOTE] It's good to know that Configuration is frozen after initialization, meaning you can't mutate configuration options after the object has been created.

from_env(cls) -> Configuration

The from_env() method, a factory method, eliminates the need to initialize a Configuration object before its usage. As its name suggests, it constructs a configuration object by retrieving values set within the environment.

[!TIP] Tunesynctool utilizes the python-dotenv package under the hood for automatically loading environmental variables into its configuration. For further details on how this package locates and retrieves environmental values, please refer to its documentation at: https://saurabh-kumar.com/python-dotenv/.

Validation

The validation of configuration values is not performed by the Configuration class, but rather delegated to the specific modules that utilize the configuration values pertinent to their functions. Consequently, in the context of streaming service drivers, each service driver is responsible for validating the configuration relevant to it during the initialization phase.