ovos-media-plugin-mass

Music Assistant playback backend for OVOS. It controls Music Assistant players, playing the library://<type>/<id> uris that the Music Assistant catalog returns.

It ships one backend on both media stacks: the same plugin works with the legacy ovos-audio service and with the modern ovos-media service.

To search Music Assistant by voice you also need a catalog component: ovos-media-provider-mass on the ovos-media stack, or ovos-skill-music-assistant on the legacy OCP/ovos-audio stack.

Install

pip install ovos-media-plugin-mass

Configuration

The easiest way is the bundled ovos-mass-autoconfigure command, which scans your server and writes both the legacy and ovos-media player entries into mycroft.conf:

$ ovos-mass-autoconfigure
This script will auto configure Music Assistant devices under your mycroft.conf
Make sure your Music Assistant server is accessible from this device
Please enter your Music Assistant server url: http://192.168.1.100:8095

Scanning...
    - Found player: HomeLabRenderer - dlna:uuid:4b778a71-0499-485a-a5a4-88140603fba9

mycroft.conf updated!

When more than one player is found, it lists them and prompts for the default (the only player written to the legacy Audio backends and marked active: true on the ovos-media side — every other discovered player is written with active: false):

$ ovos-mass-autoconfigure
This script will auto configure Music Assistant devices under your mycroft.conf
Make sure your Music Assistant server is accessible from this device
Please enter your Music Assistant server url: http://192.168.1.100:8095

Scanning...
    - Found player: HomeLabRenderer - dlna:uuid:4b778a71-0499-485a-a5a4-88140603fba9
    - Found player: KitchenSpeaker - dlna:uuid:9a11a2f0-0a3b-4e3d-9a0e-2a5b6c7d8e9f
0 - HomeLabRenderer:dlna:uuid:4b778a71-0499-485a-a5a4-88140603fba9
1 - KitchenSpeaker:dlna:uuid:9a11a2f0-0a3b-4e3d-9a0e-2a5b6c7d8e9f
select default mass device: 0

mycroft.conf updated!

Run non-interactively (CI, provisioning scripts) with --url and --default/--player (index or player_id); without them, and with multiple players found on a non-tty stdin, the script exits with an error instead of hanging on input():

$ ovos-mass-autoconfigure --url http://192.168.1.100:8095 --default 0

It emits configuration for both stacks:

// Legacy Audio Service:
{"backends": {"mass-HomeLabRenderer:dlna": {
    "active": true, "type": "ovos_mass", "player_type": "dlna",
    "identifier": "uuid:4b778a71-0499-485a-a5a4-88140603fba9",
    "url": "http://192.168.1.100:8095"}}}

// ovos-media Service:
{"audio_players": {"mass-HomeLabRenderer:dlna": {
    "active": true, "module": "ovos-media-audio-plugin-mass", "player_type": "dlna",
    "aliases": ["HomeLabRenderer", "Home Lab Renderer"],
    "identifier": "uuid:4b778a71-0499-485a-a5a4-88140603fba9",
    "url": "http://192.168.1.100:8095"}}}

See docs/configuration.md for the field reference.

Related projects

• py-music-assistant: the shared HTTP client and mediavocab bridge (this plugin's transport layer)
• ovos-media-provider-mass: the Music Assistant MediaProvider (search, ovos-media stack)
• ovos-skill-music-assistant: the Music Assistant OCP search skill (legacy stack)
• hivemind-homeassistant: exposes OVOS as a player in Home Assistant

Docs

• docs/index.md: overview and how the two stacks fit together
• docs/architecture.md: backends, uri resolution, playback flow
• docs/configuration.md: configuration reference
• docs/faq.md: troubleshooting

Tests

pip install -e .[test]
pytest test/                  # unit + end2end (ovoscope), network-free

The end-to-end tests (test/end2end/) drive both backends through a real ovos-audio AudioService on a FakeBus via ovoscope, with the Music Assistant HTTP client mocked.

License

Apache-2.0