ovos-media

July 31, 2026 · View on GitHub

Warning: this is pre-release software. It is under active development, is not yet deployed in OpenVoiceOS, and its APIs may change without notice. It is published in the open for transparency. Do not depend on it in production yet.

The OVOS Virtual Media Player is a standalone daemon. It plays audio, video, and web content for OpenVoiceOS. It tracks playback state per session, integrates with MPRIS/D-Bus, and uses a pluggable backend architecture.

ovos-media implements OCP (OVOS Common Playback): one logical media player per session that every media voice command targets. It handles both OVOS-initiated playback ("play jazz") and transport control ("pause", "next", "stop the music"). It also bridges to the host OS over MPRIS, so it can control playback OVOS did not start, such as a browser tab or a desktop player, as long as that player speaks the open standard. The concept is specified in OVOS-OCP-1.

ovos-media is the modern replacement for the legacy audio service (the ovos-ocp-audio-plugin bundled inside ovos-audio). It splits the monolith into small, swappable pieces: the OCP pipeline finds media, providers supply catalogs, backends play streams, extractors resolve URIs.

How it fits together

 "play jazz on the kitchen speaker"
              │
              ▼
   ovos-core ─ OCP pipeline (ovos-ocp-pipeline-plugin)
              │   classify media type + parse the request
              │   query MediaProvider plugins, rank results
              ▼
   ovos-media (this daemon)
              │   pick a playback backend, manage the queue / now-playing,
              │   expose state over the bus / MPRIS / GUI
              ▼
   playback backend (opm.media.audio | .video | .web)
              │   hand the URI to vlc / mpv / spotify / chromecast / browser …
              ▼
   stream extractor (opm.ocp.extractor) resolves youtube//… , rss//… , file://…

Every arrow is a plugin boundary, so each piece can be replaced independently:

Concern	Plugin group	Examples
Find media (catalogs/search)	`opm.media.provider`	youtube, bandcamp, soundcloud, tunein, somafm, pyradios
Play audio	`opm.media.audio`	vlc, mplayer, simple (cli), ffplay, spotify, chromecast, mass, mpris
Play video	`opm.media.video`	vlc, mplayer, chromecast
Render web/webview	`opm.media.web`	(rendered via the GUI WebView)
Resolve a stream URI	`opm.ocp.extractor`	youtube, m3u, rss, files

Search results flow as mediavocab.Release objects: a typed catalog model shared across the whole media ecosystem. A provider written once works for playback, MPRIS metadata, and the GUI alike.

Install

pip install ovos-media

Install at least one playback backend (audio is the minimum to hear anything):

pip install ovos-media-plugin-vlc        # or -mplayer / -simple / -spotify / -chromecast

Enable it

ovos-media runs alongside ovos-audio (which keeps handling TTS). Turn off the legacy audio service and run the daemon:

// mycroft.conf
{
  "enable_old_audioservice": false
}

ovos-media          # start the daemon

Ask OVOS to play something and the OCP pipeline routes the request here.

Configuration

All configuration lives under the "media" key in mycroft.conf. The essentials:

{
  "media": {
    // MPRIS / D-Bus integration (off by default)
    "enable_mpris": false,
    // let MPRIS pause/stop other media players on the system
    "manage_external_players": false,

    // order of preference per playback type; the first backend that can
    // handle the URI wins. Users may also name a backend in the utterance.
    "preferred_audio_services": ["vlc", "mplayer", "cli"],
    "preferred_video_services": ["vlc"],

    // declare the backends available to each playback type.
    // "module" is the plugin's entry-point name; "aliases" are spoken names.
    "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 }
    }
  }
}

See docs/configuration.md for every option (per-backend config, MPRIS roles, GUI update interval, queue behaviour).

Documentation

Start at docs/index.md.

Getting started: install, enable, first playback
Architecture: the daemon, the bus API, the plugin boundaries
Media providers: write a catalog/search plugin (opm.media.provider)
Playback backends: audio/video/web backend plugins
Configuration reference
MPRIS / D-Bus
Migrating from the legacy audio service

Status

ovos-media is the OCP-native playback stack and is opt-in today (enable it by turning off the legacy audio service). Catalogs are supplied by MediaProvider plugins (opm.media.provider). The legacy OCP search skills still work during the transition.

Credits

The original OCP dataset used to train the media classifiers was sponsored by @NeonGeckoCom as part of The OCP Sprint. More recent media-metadata datasets are maintained by TigreGotico and published in the Media Metadata collection on Hugging Face.