Skip to content

OVOS & Music Assistant

In a nutshell

OVOS and Music Assistant (MA) are two different open-source projects. OVOS can use an MA server as a media backend, and a HiveMind satellite can expose itself as a playback endpoint MA can stream to. There is no single combined install; pick the direction that matches what you want.

Direction What it does Status
OVOS plays media through MA An OVOS assistant searches and plays music/radio/podcasts via a running Music Assistant server All three pieces public and on PyPI as alpha releases (see below)
MA loads out-of-tree providers A Music Assistant server loads community-maintained providers not shipped with MA itself music-assistant-plugin-manager, public and on PyPI
MA streams to an OVOS device Music Assistant sees an OVOS-powered device as a playback endpoint, browses its library, and streams to it Via hivemind-media-player + Home Assistant's Music Assistant integration; see below

Direction 1: OVOS plays media through Music Assistant

Three pieces work together, all named after the OCP media stack:

ovos-skill-music-assistant, the OCP skill both of the above replace, is archived. Install ovos-media-provider-mass and ovos-media-plugin-mass instead. See MediaProvider plugins for the full replacement table.

Direction 2: Music Assistant loads out-of-tree providers

music-assistant-plugin-manager (pip install --pre music-assistant-plugin-manager, since every release is a prerelease) is independent of OVOS: it loads community-maintained providers into a Music Assistant server via its music-assistant-community wrapper command. Use it to run MA providers that aren't shipped with MA itself, regardless of whether you also use OVOS.

Direction 3: Music Assistant streams to an OVOS device

Via Home Assistant, not a direct OVOS↔MA link

This path goes through Home Assistant: Home Assistant is the HiveMind client, not the OVOS device. It connects to whatever runs hivemind-core on the OVOS side and drives it as an admin, so it can trigger playback on the device's real "default" session rather than an isolated one. Music Assistant then sees the resulting HA entity as a playback endpoint. There is no direct HiveMind↔Music-Assistant protocol.

The OVOS side runs hivemind-core plus whatever agent answers ovos.common_play.*, since it's the same bus messages regardless of what runs behind it. Two options:

  • A full hivemind-ovos-agent-plugin node: a complete ovos-core install exposed over HiveMind. Heavier, but you get the whole assistant, not just playback.
  • hivemind-player-protocol: a lighter HiveMind agent plugin for when you only want playback and don't want to run full ovos-core. It currently embeds the legacy ovos-audio service, not ovos-media; its status query does not yet report real player state.

Home Assistant needs an admin client to reach the device's real "default" session instead of an isolated one translated away from it (see Session isolation between clients):

hivemind-core add-client --name home-assistant --admin true
hivemind-core allow-msg "ovos.common_play.play" <NODE_ID>
hivemind-core allow-msg "ovos.common_play.pause" <NODE_ID>
hivemind-core allow-msg "ovos.common_play.resume" <NODE_ID>
hivemind-core allow-msg "ovos.common_play.stop" <NODE_ID>
hivemind-core allow-msg "ovos.common_play.next" <NODE_ID>
hivemind-core allow-msg "ovos.common_play.previous" <NODE_ID>
hivemind-core allow-msg "speak" <NODE_ID>

hivemind-homeassistant connects to hivemind-core with those credentials and, once you pick "Media Player" as the device type in the HA config flow, exposes it as a media_player entity plus a notify entity for TTS. Once that entity exists, Music Assistant (running as its own Home Assistant integration) treats it like any other media player: it can browse your library and stream to the device without further OVOS-side configuration.

Related: ovos-media · HiveMind · Home Assistant