Configuration reference

September 9, 2026 · View on GitHub

ovos-media reads two top-level keys from the OVOS/Mycroft configuration file:

media, the daemon: backends, playback behaviour, MPRIS. Documented here.
media_providers, per-provider catalog/search settings. Documented in media-providers.md and summarised below.

The legacy audio service is turned off with the top-level enable_old_audioservice flag (see getting started and the migration guide).

Where to Configure

OVOS reads configuration from (in ascending priority order):

/etc/mycroft/mycroft.conf, system-wide defaults
~/.config/mycroft/mycroft.conf, user overrides (Mycroft-compat path)
~/.config/ovos/ovos.conf, user overrides (OVOS-native path)

Place your media block in the user config file for the path appropriate to your installation. Both paths are equivalent at runtime.

Minimal example:

{
  "media": {
    "preferred_audio_services": ["vlc", "mpv"],
    "enable_mpris": true
  }
}

MediaService.__init__ reads this section via Configuration().get("media", {}), and OCPMediaPlayer.__init__ stores it as self.ocp_config.

Backend Selection

OCPMediaPlayer._resolve_preferred_service

When ovos-media is about to play a track it resolves a preferred backend by walking the ordered list of names in the relevant config key and returning the first loaded backend whose name or aliases match. If the list is empty or no match is found, any available backend is used.

Key	Type	Default	Description
`preferred_audio_services`	list of strings	`[]`	Ordered preference list for audio backends (e.g. `["vlc", "mpv", "simple"]`). Also used as a generic fallback when no type-specific list is set.
`preferred_video_services`	list of strings	`[]`	Ordered preference list for video backends.
`preferred_web_services`	list of strings	`[]`	Ordered preference list for web/webview backends.

Backend plugin names are the entry-point keys registered under opm.media.audio, opm.media.video, or opm.media.web in each plugin's pyproject.toml.

Declaring Backends

Every backend plugin installed for a playback type loads automatically, so installing ovos-media plus a backend plugin is enough to get working playback with no configuration at all. Each discovered plugin loads under its entry-point name, with that name as its only alias and its own default config.

The audio_players, video_players, and web_players blocks customise that: an entry's key is a local name; module is the plugin's entry-point name, aliases are spoken names a user can say ("play on VLC"), and any other key is passed through to the plugin's config. A configured entry takes precedence over autoload for that module, loads before any undeclared plugin, and keeps the name/aliases/config given here. Set active: false to disable a module, whether declared or not.

Set autoload_backends to false to turn off automatic discovery and load only the backends declared in audio_players / video_players / web_players, matching the pre-autoload behaviour.

A backend that drives remote gear (a RemoteAudioPlayerBackend / RemoteVideoPlayerBackend / RemoteWebPlayerBackend subclass, e.g. a casting target or a Music Assistant install) is never autoloaded — it needs an explicit entry in the relevant _players block, since starting to control someone's remote hardware is not something a default install should do unasked. A backend that needs credentials or a specific target should also refuse to construct on an empty config, which keeps it out of a default install even if it is autoload-eligible.

{
  "media": {
    "audio_players": {
      "vlc": { "module": "ovos-media-audio-plugin-vlc", "aliases": ["VLC"], "active": true },
      "cli": { "module": "ovos-media-audio-plugin-cli", "aliases": ["Command Line"], "active": true }
    },
    "video_players": {
      "vlc": { "module": "ovos-media-video-plugin-vlc", "aliases": ["VLC"], "active": true }
    },
    "web_players": {}
  }
}

Web backends register under opm.media.web; add their declarations to web_players once one is installed.

Key	Type	Default	Description
`autoload_backends`	bool	`true`	Load every installed backend plugin not covered by an `active: false` entry below. Set to `false` to load only the backends declared below.
`audio_players`	dict	`{}`	Audio backends to customise, order, or disable (`opm.media.audio`), keyed by local name.
`video_players`	dict	`{}`	Video backends to customise, order, or disable (`opm.media.video`).
`web_players`	dict	`{}`	Web/webview backends to customise, order, or disable (`opm.media.web`).

The module value is the plugin's entry-point name (e.g. ovos-media-audio-plugin-vlc), which often differs from its pip package name (ovos-media-plugin-vlc). See backends.md for each plugin's entry-point name.

Any additional keys inside a player entry are passed through to that backend plugin's own config dict. See backends.md for the backend API.

Playback Behaviour

Key	Type	Default	Description
`autoplay`	bool	`true`	Automatically advance to the next track when the current one ends (and on invalid media).
`merge_search`	bool	`true`	Merge incoming search results into the playback queue alongside the user playlist rather than ignoring them.
`playback_mode`	enum or string	unset	Set to `PlaybackMode.FORCE_AUDIO` (or the string `"FORCE_AUDIO"`) to always use audio backends, bypassing video/web backend selection.
`validate_source`	bool	`true`	Only act on playback commands from the local/`"default"` session. Leave `true` on a server-side daemon so it ignores HiveMind satellite sessions; set `false` on a satellite not getting default-NAT'd sessions. See Sessions.

Play History

ovos-media keeps a small persisted record of what actually played, so a user can say "play my recently played" or "play my most played songs" the same way they'd say "play my liked songs". The daemon records a play into PlayHistoryStore (ovos_media/catalog/history.py) once a track's stream has been validated, so a corpse (a URI that fails to load and gets skipped) never pollutes either playlist. Recording is bounded to max_entries uris; once full, the least-played, oldest entries are evicted first, exempting the most recently played tracks so "recently played" cannot be starved by its own growth.

Key	Type	Default	Description
`history.enabled`	bool	`true`	Keep a play-history store and answer "recently played"/"most played" requests. Set `false` to skip the store entirely — no file is created and no keywords are registered.
`history.max_entries`	int	`500`	Maximum number of distinct uris kept in the history store before the oldest, least-played entries are evicted.

{
  "media": {
    "history": {
      "enabled": true,
      "max_entries": 500
    }
  }
}

MPRIS Integration

MPRIS (Media Player Remote Interfacing Specification) is the standard D-Bus protocol used by desktop environments to control media players. When enabled, ovos-media registers itself as org.mpris.MediaPlayer2.OCP on the session bus, making it controllable from KDE Connect, playerctl, the GNOME Shell media widget, and similar tools.

Key	Type	Default	Description
`enable_mpris`	bool	`false`	Start the D-Bus MPRIS exporter. When `false`, `self.mpris` is `None` and no D-Bus registration occurs.
`manage_external_players`	bool	`false`	Role B behaviour: poll for external MPRIS players and pause OCP when another player becomes active; also proxies skip/pause/shuffle/repeat to the external player.
`ignored_players`	list of strings	`["org.mpris.MediaPlayer2.OCP", "org.mpris.MediaPlayer2.plasma-browser-integration"]`	D-Bus player names excluded from external player scanning.
`mpris_poll_interval`	int (seconds)	`1`	Interval between external player scans. Only relevant when `manage_external_players` is `true`.
`dbus_type`	string	`"session"`	`"session"` or `"system"` D-Bus to connect to.

The event loop runs two passes per poll interval when manage_external_players is true: one scan_players call followed by a query_player pass over all known players. When manage_external_players is false, only the D-Bus export (Role A) is active and the loop sleeps for mpris_poll_interval between control-signal checks.

Full Example Configuration

{
  "media": {
    "preferred_audio_services": ["vlc", "mpv"],
    "preferred_video_services": ["vlc"],
    "preferred_web_services": [],
    "autoplay": true,
    "merge_search": true,
    "enable_mpris": true,
    "manage_external_players": true,
    "mpris_poll_interval": 2,
    "dbus_type": "session",
    "ignored_players": [
      "org.mpris.MediaPlayer2.OCP",
      "org.mpris.MediaPlayer2.plasma-browser-integration",
      "org.mpris.MediaPlayer2.kdeconnect"
    ]
  }
}

This configuration enables MPRIS with external player management, polls every two seconds, prefers VLC for both audio and video, and leaves the web service with no preference (first available backend wins).

Media Providers

Catalog/search providers are configured under the separate top-level media_providers key (not inside media), keyed by each provider's entry-point name. Keys are passed through to the provider's config; set enabled: false to disable a provider without uninstalling it.

{
  "media_providers": {
    "bandcamp": { "max_pages": 2 },
    "youtube": { "max_results": 10 },
    "soundcloud": { "enabled": false }
  }
}

Provider settings and the full provider list are documented in media-providers.md.