Metadata-Version: 2.4
Name: ovos-media-plugin-mass
Version: 0.0.2a6
Summary: Music Assistant playback backend for OVOS (ovos-media / ovos-audio)
Author-email: JarbasAi <jarbasai@mailfence.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/OpenVoiceOS/ovos-media-plugin-mass
Project-URL: Repository, https://github.com/OpenVoiceOS/ovos-media-plugin-mass
Keywords: ovos,OpenVoiceOS,OCP,media,audio,music-assistant,plugin
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ovos-plugin-manager<3.0.0,>=2.1.0
Requires-Dist: ovos-config<3.0.0,>=0.0.12
Requires-Dist: py-music-assistant>=0.0.1
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: ovoscope[audio,media]>=0.20.0a1; extra == "test"
Dynamic: license-file

# ovos-media-plugin-mass

Music Assistant **playback backend** for OVOS. It controls
[Music Assistant](https://www.music-assistant.io/) 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.

| Stack | Entry-point group | Class |
|---|---|---|
| `ovos-media` (current) | `opm.media.audio` | `MAssOCPAudioService` |
| `ovos-audio` (legacy) | `mycroft.plugin.audioservice` | `MAssAudioService` |

To **search** Music Assistant by voice you also need a catalog component:
[ovos-media-provider-mass](https://github.com/OpenVoiceOS/ovos-media-provider-mass)
on the `ovos-media` stack, or
[ovos-skill-music-assistant](https://github.com/OpenVoiceOS/ovos-skill-music-assistant)
on the legacy OCP/`ovos-audio` stack.

## Install

```bash
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`:

```bash
$ 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!
```

It emits configuration for both stacks:

```jsonc
// 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](docs/configuration.md) for the field reference.

## Related projects

- [py-music-assistant](https://github.com/TigreGotico/py-music-assistant): the shared HTTP client and mediavocab bridge (this plugin's transport layer)
- [ovos-media-provider-mass](https://github.com/OpenVoiceOS/ovos-media-provider-mass): the Music Assistant MediaProvider (search, `ovos-media` stack)
- [ovos-skill-music-assistant](https://github.com/OpenVoiceOS/ovos-skill-music-assistant): the Music Assistant OCP search skill (legacy stack)
- [hivemind-homeassistant](https://github.com/JarbasHiveMind/hivemind-homeassistant): exposes OVOS as a player in Home Assistant

## Docs

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

## Tests

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

The end-to-end tests ([test/end2end/](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
