Music Assistant Server Configuration Options: Complete Guide to Core Settings and Provider Setup

Music Assistant stores all settings as ConfigEntry objects, with core server options defined in config.yaml and provider-specific settings exposed through get_config_entries() methods that can be accessed via self.config.get_value() in Python.

The music-assistant/server repository manages configuration through a unified system where core HTTP server parameters, data directories, and TLS settings live alongside provider-specific authentication tokens and quality preferences. Configuration values are persisted in YAML format and accessed programmatically through the mass.config object or provider-local self.config instances. Understanding these configuration options enables precise control over network binding, music source authentication, and player behavior.

Core Server Configuration Options

The foundational settings for Music Assistant are defined in music_assistant/__main__.py and music_assistant/constants.py, with HTTP server security handled in music_assistant/helpers/webserver.py. These values are stored in the config.yaml file located in the data directory (default: $HOME/.musicassistant).

Network and HTTP Settings

The server exposes several critical networking parameters that control how the web interface and API accept connections:

• host (string, default: "0.0.0.0"): Defines the network interface for the HTTP server listener. Set to "127.0.0.1" to restrict local access only.
• port (integer, default: 8095): Specifies the TCP port for the HTTP API and web UI.
• allow_remote_access (boolean, default: False): When enabled, exposes the API to external networks, required for Home Assistant integration.
• http_password (secure string, optional): Enables basic authentication for the HTTP API when set.

TLS and Security Configuration

For HTTPS deployments, the SSL helper in music_assistant/helpers/ssl.py reads two optional parameters:

• ssl_cert (string, optional): Absolute path to a PEM-encoded TLS certificate.
• ssl_key (string, optional): Path to the private key corresponding to the certificate.

Logging and Data Directories

System-level paths and verbosity are controlled by:

• log_level (string, default: "info"): Controls output verbosity with values including debug, info, warning, or error.
• data_dir (string, default: "$HOME/.musicassistant"): Root directory for the library database, cache files, and configuration storage.

Provider-Specific Configuration

Each provider defines its own configuration schema through the get_config_entries() coroutine, returning tuples of ConfigEntry objects. Provider constants are typically defined in music_assistant/providers/<provider>/constants.py.

Music Source Providers

Authentication and quality settings for streaming services vary by integration:

YouTube Music (ytmusic):

• CONF_USERNAME: Account email address for authentication.
• CONF_COOKIE: Optional secure string for authenticated requests.
• CONF_PO_TOKEN_SERVER_URL: Token exchange service endpoint (e.g., "https://tokenserver.example.com").

ZVuk Music (zvuk_music):

• CONF_TOKEN: Secure API authentication token.
• CONF_QUALITY: Audio quality selection ("high", "medium", or "low").

YouSee (yousee):

• CONF_USERNAME and CONF_PASSWORD: Login credentials.
• CONF_QUALITY: Bitrate selection as integer (64, 128, or 256 KBPS).

Yandex Ynison (yandex_ynison):

• CONF_TOKEN: Manual Yandex token for own-mode authentication.
• CONF_X_TOKEN: Refresh token for QR-code login flows.
• CONF_YM_INSTANCE: Optional instance identifier for linking to specific Yandex Music providers.
• CONF_MASS_PLAYER_ID: Target player ID (or "auto").
• CONF_ALLOW_PLAYER_SWITCH: Boolean enabling automatic player switching.
• CONF_OUTPUT_SAMPLE_RATE and CONF_OUTPUT_BIT_DEPTH: Audio output specifications (e.g., "48000" and "24", or "auto").
• CONF_PUBLISH_NAME: Advertised name to Yandex Music (default: "Music Assistant").
• CONF_DEVICE_ID: Persistent device identifier for API sessions.

Spotify Connect (spotify_connect):

• CONF_CLIENT_ID and CONF_CLIENT_SECRET: Spotify developer credentials.
• CONF_REDIRECT_URI: OAuth callback URL (default: "http://localhost:8095/spotify/callback").

Player and Plugin Providers

Hardware and smart home integrations expose device-specific settings:

Yandex Smart Home (yandex_smarthome):

• CONF_CONNECTION_TYPE: Either "cloud" or "direct" connection mode.
• CONF_INSTANCE_NAME: Display name in the Yandex Smart Home UI.
• CONF_CLOUD_INSTANCE_PASSWORD, CONF_CLOUD_CONNECTION_TOKEN, CONF_CLOUD_INSTANCE_ID: Cloud authentication triplet.
• CONF_SKILL_ID and CONF_SKILL_TOKEN: Skill-specific credentials.
• CONF_DIRECT_ACCESS_TOKEN and CONF_DIRECT_CLIENT_SECRET: Direct mode security tokens.
• CONF_EXPOSED_PLAYERS: List of player IDs to expose to the smart home service.

Snapcast (snapcast):

• CONF_SERVER: Snapcast server address (e.g., "127.0.0.1").
• CONF_PORT: Control port (default: 1704).
• CONF_PASSWORD: Optional control password.

Universal Player (universal_player):

• CONF_PLAYER_ID: Underlying player identifier to proxy.
• CONF_VOLUME_STEP: Volume adjustment increment (integer, default: 5).

Accessing and Modifying Configuration

The configuration system supports three access patterns: YAML file editing, runtime API updates, and programmatic retrieval within provider code.

Configuration File Locations

The primary config.yaml resides in the data directory, containing core settings under root keys and provider entries under a providers: mapping. Provider-specific values use the same key names defined in their respective constants.py files.

Runtime Access Patterns

To retrieve configuration values within a provider class, use the instance configuration object:

# Inside any provider class (e.g., YtMusicProvider)

token = str(self.config.get_value(CONF_TOKEN))
quality = self.config.get_value(CONF_QUALITY)

For global core settings, access the mass configuration object:

# Update HTTP port without manual restart

mass.config.update("port", 8080)
await mass.restart()

To inspect the entire configuration state for debugging:

import json
print(json.dumps(mass.config.as_dict(), indent=2))

Summary

• Core settings including host, port, ssl_cert, and log_level are defined in music_assistant/__main__.py and stored in config.yaml.
• Provider configurations are declared via get_config_entries() in each provider's __init__.py, with keys like CONF_TOKEN and CONF_QUALITY defined in constants.py.
• Security options include http_password for basic auth and allow_remote_access for Home Assistant connectivity.
• Access methods range from YAML editing to runtime Python calls using self.config.get_value() and mass.config.update().

Frequently Asked Questions

How do I change the default port for Music Assistant server?

Edit the port key in config.yaml (default: 8095) or call mass.config.update("port", 8080) followed by await mass.restart() to change the HTTP API and web UI port without manual file editing.

Where are provider authentication tokens stored in Music Assistant?

Provider tokens and credentials are stored as secure strings in the config.yaml file under the providers: mapping, using keys like CONF_TOKEN or CONF_PASSWORD as defined in each provider's constants.py file.

Can I configure Music Assistant server without using the web interface?

Yes. For headless deployments, directly edit the config.yaml file in the data directory (default: $HOME/.musicassistant) or use the CLI helper with music_assistant config set <key> <value> for core settings, though provider-specific entries require YAML editing or API calls.

What is the difference between core and provider configuration in Music Assistant?

Core configuration controls server-wide behavior like network binding (host, port), TLS (ssl_cert), and logging (log_level), while provider configuration manages individual music source and player settings like CONF_USERNAME for YouTube Music or CONF_SERVER for Snapcast, accessed via self.config.get_value().

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}