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

Release files for ovos-media 2.4.2a1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ovos-media 2.4.2a1
File	Size	Uploaded
ovos_media-2.4.2a1.tar.gz	214.0 kB	Sep 25, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for ovos-media 2.4.2a1
File	Interpreter	ABI	Platform	Reset
ovos_media-2.4.2a1-py3-none-any.whl 236.8 kB Sep 25, 2026	Python 3	none	any	Details

Total release size: 450.8 kB

Release files / ovos_media-2.4.2a1.tar.gz

Download URL	ovos_media-2.4.2a1.tar.gz
Size	214.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`ee5c381535f62fa23e996875bc6c89a4d1dcf13c1958e7b8edfb28d637cc8050`
BLAKE2b-256 checksum How to use checksums	`905ee580fdf77d7ed99c0aed14f95c330f3f468406b94fe843768ca2aa044b08`
Upload date	Sep 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / ovos_media-2.4.2a1-py3-none-any.whl

Download URL	ovos_media-2.4.2a1-py3-none-any.whl
Size	236.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`cb774fad42487d080030dab693e91fddcf940e549a2a70a512769fb62384a121`
BLAKE2b-256 checksum How to use checksums	`40591bba1f59bbfd9f43944b9d86c053f2098d3c5d5e81b51c15287a22329412`
Upload date	Sep 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`