Music Assistant Skill

September 2, 2026 · View on GitHub

⚠️ DEPRECATED

This OCP search skill is deprecated and unmaintained. OCP search skills (OVOSCommonPlaybackSkill + @ocp_search) are replaced by MediaProvider plugins loaded by the OCP pipeline plugin. The search and catalog functionality moves to ovos-media-provider-mass, a MediaProvider running in-process within the OCP pipeline. Playback of Music Assistant tracks moves to ovos-media-plugin-mass, a playback backend for the ovos-media player daemon. Both packages are published and work once their respective stacks are active — ovos-media-provider-mass provides search results when the OCP pipeline invokes MediaProviders; ovos-media-plugin-mass handles playback when ovos-media is running as your player. Installing them does not replace this skill under the legacy OCP/ovos-audio stack.

This skill keeps working until the ovos-media stack flips to default and this repository is archived.

Music Assistant Skill

OCP search skill for Music Assistant.

It answers OCP play … requests with playable results from a Music Assistant server. The companion ovos-media-plugin-mass plays back the returned library:// uris.

Setup

Check which player stack you run before installing anything. On the classic ovos-audio/OCP stack, this skill does the catalog search and hands playback to ovos-media-plugin-mass; install both together. On the newer ovos-media stack, this skill is replaced entirely at flag day by ovos-media-provider-mass, which does catalog search and playback on its own — do not install this skill there.

For the classic stack:

pip install ovos-skill-music-assistant ovos-media-plugin-mass

Set your Music Assistant server URL in this skill's settings — the url field in settings.json, reachable through the OVOS control panel under this skill's settings page:

{ "url": "http://192.168.1.100:8095", "token": "your-mass-api-token" }

Music Assistant 2.11 and later require an API token: create one in the Music Assistant web UI under Settings → Users and put it in the token setting. Leave it blank for older, unauthenticated servers.

Settings changes made through the control panel before the skill's first run are only picked up on the run after that: the skill writes its own first-run marker into settings.json the first time it loads, which can overwrite a hand-edited file dropped in earlier. Reload the skill (or restart it) once after changing the URL for the first time if it does not seem to take effect.

Say "play some jazz on music assistant" to verify the setup works end to end.

If something goes wrong:

  • an "I couldn't reach your Music Assistant server" reply means the url in settings is wrong or the server is down — check both.
  • no results for something you know is in your library means Music Assistant itself does not have that media indexed — check its own search first.
  • an error about the server refusing the request usually means authentication: check the token setting — Music Assistant 2.11 and later reject requests without a valid API token.

Docs

Tests

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

The end-to-end tests (test/end2end/) run the real OCP pipeline in a ovoscope MiniCroft. A spoken utterance is classified into an ovos.common_play.query, this skill answers, and OCP selects a winner to play. The tests mock the Music Assistant HTTP client.

Credits

  • JarbasAi

Category

Entertainment

Tags

#audio #music #OCP #entertainment