Metadata-Version: 2.4
Name: py-music-assistant
Version: 0.0.1
Summary: Python HTTP client and mediavocab bridge for a Music Assistant server
Author-email: JarbasAI <jarbasai@mailfence.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/TigreGotico/py-music-assistant
Project-URL: Source, https://github.com/TigreGotico/py-music-assistant
Keywords: music-assistant,mediavocab,ovos,OpenVoiceOS,OCP,media
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Requires-Dist: ovos-utils>=0.0.38
Requires-Dist: mediavocab>=1.0.0
Requires-Dist: music-assistant-models>=1.0.0
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Dynamic: license-file

# py-music-assistant

Python HTTP client and [mediavocab](https://github.com/TigreGotico/mediavocab)
bridge for a [Music Assistant](https://www.music-assistant.io/) server.

It is the single transport + conversion layer shared by the OVOS Music Assistant
integrations:

- **[ovos-media-plugin-mass](https://github.com/OpenVoiceOS/ovos-media-plugin-mass)** — playback backend (`opm.media.audio`)
- **[ovos-media-provider-mass](https://github.com/OpenVoiceOS/ovos-media-provider-mass)** — catalog/search provider (`opm.media.provider`)
- **[ovos-skill-music-assistant](https://github.com/OpenVoiceOS/ovos-skill-music-assistant)** — legacy OCP search skill

## Install

```bash
pip install py-music-assistant
```

## Usage

```python
from py_music_assistant import SimpleHTTPMusicAssistantClient, search_to_releases

api = SimpleHTTPMusicAssistantClient("http://192.168.1.100:8095")

# raw search (dict of buckets: tracks/albums/artists/radio/podcasts/audiobooks)
res = api.search_media("viagra boys", limit=10)

# mapped to typed mediavocab.Release objects (unranked; score them yourself)
releases = search_to_releases(res)
for r in releases:
    print(r.work.title, r.work.media_type, r.uri)   # e.g. "Worms" MUSIC library://track/9903
```

The client talks to the server's synchronous JSON `/api` endpoint (no WebSocket
lifecycle). Item `uri`s are `library://<type>/<id>` identifiers that the
`ovos-media-plugin-mass` backend resolves and plays.

## Docs

- [docs/index.md](docs/index.md) — overview
- [docs/client-api.md](docs/client-api.md) — `SimpleHTTPMusicAssistantClient` reference
- [docs/mediavocab-bridge.md](docs/mediavocab-bridge.md) — dict → `Release` mapping

## Tests

```bash
pip install -e .[test]
pytest test/                                   # network-free (mocked + fixtures)
MASS_SERVER_URL=http://<host>:8095 pytest test/live/   # opt-in, against a real server
```

## License

Apache-2.0
