ovos-media

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,
              │   broadcast state over the bus / MPRIS
              ▼
   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:

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

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; OCP is a desktop MPRIS player by default,
    // a machine with no session bus logs one warning and keeps running
    "enable_mpris": true,
    // 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"],

    // every installed backend plugin loads automatically; declare an entry
    // here to customise its name/aliases/config, control its load order, or
    // disable it with "active": false. "module" is the plugin's entry-point
    // name; "aliases" are spoken names. a backend that drives remote gear
    // (casting, Music Assistant) needs an explicit entry here - it is never
    // autoloaded.
    "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, autoload_backends, MPRIS roles, 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.