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:

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 directly by the backend plugin)
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 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 (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"],

    // 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.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ovos_media-2.1.2a1.tar.gz (196.3 kB view details)

Uploaded Sep 2, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

ovos_media-2.1.2a1-py3-none-any.whl (211.3 kB view details)

Uploaded Sep 2, 2026 Python 3

File details

Details for the file ovos_media-2.1.2a1.tar.gz.

File metadata

Download URL: ovos_media-2.1.2a1.tar.gz
Upload date: Sep 2, 2026
Size: 196.3 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for ovos_media-2.1.2a1.tar.gz
Algorithm	Hash digest
SHA256	`91faf40183ac38e75a9025a69ffc5e82952209c6337060a2ff78c16c561075cc`
MD5	`e4bdf2979b4201345feca79060bf188b`
BLAKE2b-256	`6c9422fb1dd4a42e709d2607b40055d2ef6f4a6d539e10e1d89f0cf74ca26439`

See more details on using hashes here.

File details

Details for the file ovos_media-2.1.2a1-py3-none-any.whl.

File metadata

Download URL: ovos_media-2.1.2a1-py3-none-any.whl
Upload date: Sep 2, 2026
Size: 211.3 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for ovos_media-2.1.2a1-py3-none-any.whl
Algorithm	Hash digest
SHA256	`89571638db7d2dcc334f4e03f927401fa1f9b41f78cbbe719d92a4d7f2a15b47`
MD5	`a3b2595575855de4eae2d222db59addb`
BLAKE2b-256	`a8b55f14f3c5f8869250bc3fe601f4151f3d4f6d66b0673da5328b82e710d150`