ovos-media documentation

ovos-media is the OCP-native media daemon for OpenVoiceOS. It plays audio, video, and web content on behalf of OVOS, managing the queue, now-playing state, and playback backends, while broadcasting that state over the MessageBus and MPRIS/D-Bus. It runs alongside ovos-audio, which continues to handle TTS.

Apache-2.0 · Python 3.10+

New here? Read the Glossary & core concepts first (5 minutes). It explains OCP, providers vs. backends vs. extractors, Signals/Release, and the mental model the rest of these docs assume.

Start here

You are…	Go to
new to the media stack	Glossary → Getting started
running or tuning a device	Getting started → Configuration
writing a search plugin	Glossary → Media providers
writing a player plugin	Backends
writing a game or interactive skill	OCP skills (still a skill, not a provider)
wiring desktop or playerctl	MPRIS
hacking on the daemon	Architecture
running HiveMind satellites or a server	Sessions
migrating from the old stack	Migration guide

---

How it fits together

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

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

Concern	Plugin group	Examples
Find media (catalog/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 media ecosystem, so a provider written once feeds both playback and MPRIS metadata.

---

Documentation

Document	What it covers
Glossary & core concepts	Read first. Every acronym + the mental model (provider vs. backend vs. extractor, Signals/Release)
Getting started	Install, enable the daemon, run your first playback
Architecture	The daemon's layers, bus API, state machine, MPRIS integration
Sessions	The default/local session filter, how a HiveMind server ignores satellite sessions (validate_source)
Media providers	Writing a catalog/search plugin (opm.media.provider), the new search layer
Playback backends	Audio/video/web backend plugins, discovery, writing a custom backend
Configuration	Full mycroft.conf reference for the media and media_providers keys
MPRIS integration	D-Bus MPRIS support, external player control, playerctl
Migration guide	Moving from the legacy audio service to ovos-media
OCP skills	Media search skills are superseded by media providers. Game and interactive skills stay here.

---

Quick config example

{
  "enable_old_audioservice": false,
  "media": {
    "preferred_audio_services": ["vlc", "mplayer", "cli"],
    "enable_mpris": true
  }
}

Full reference: configuration.md.