This release is a pre-release and may not be stable for production use.
HiveMind Media Player
Turn any device into a remotely controlled OVOS media player via HiveMind.
hivemind-media-player ships HiveMindPlayerProtocol, a HiveMind agent protocol
plugin (hivemind.agent.protocol) that embeds ovos-media (the OCP-native media
daemon) for playback and ovos-audio for TTS only, plus optional ovos-PHAL, and
exposes it to any HiveMind client. Remote controllers send standard OCP (Open Voice
OS Common Play) messages over the HiveMind encrypted WebSocket; the wire contract
is unchanged regardless of which media backend is embedded underneath. The player
device handles playback locally.
This is for devices that are not running a full OVOS instance. Think of a Raspberry Pi dedicated to being a networked speaker.
New to HiveMind? Read docs/getting-started.md —
a from-scratch walkthrough covering what this actually does, install,
the two config files, registering a client with add-client and the
allow-msg whitelist, and verifying a play command round-trips.
Architecture
remote controller HiveMind (encrypted WebSocket) this device
(Home Assistant, <---------------------------------> hivemind-core
hivemind-player-ctl, + HiveMindPlayerProtocol
any OCP client) + ovos-media (playback, VLC/MPV...)
+ ovos-audio (TTS only)
The player agent answers no natural-language questions (natural_language_query
yields only the end-of-query sentinel). Its sole role is to receive OCP bus
messages forwarded by hivemind-core and play them through the embedded
ovos-media daemon. Because a satellite's session is always namespaced by
hivemind-core rather than left as the device-local "default" (HiveMind-Bridge-1
§4), the embedded daemon is started to act on every authorized session — this
device is a single dedicated player, not a multi-session host.
Install
pip install hivemind-player-protocol
Optional extras (VLC, MPV backends):
pip install "hivemind-player-protocol[extras]"
Or from source:
git clone https://github.com/JarbasHiveMind/hivemind-media-player
cd hivemind-media-player
pip install -e .
Dependencies
The whole stack rides the ovos-bus-client 2.x line (HiveMind core 4.6.x
requires it). That line, and the OVOS components updated to ride it
(ovos-audio, ovos-media, ovos-plugin-manager, ovos-workshop), are currently
published as prereleases.
pyproject.toml pins each dependency to its prerelease floor (for example
ovos-bus-client>=2.0.0a3). A plain pip install then resolves the right
versions. No --pre flag is needed. Do not add --pre. The floor pins
opt into the prereleases, package by package, and keep resolution deterministic.
hivemind-core itself (AGPL) is not a runtime dependency. The plugin only
imports its AgentProtocol base. The host process supplies hivemind-core.
The test suite pulls it in through the [e2e] extra.
Quickstart
1. Configure hivemind-core
Edit ~/.config/hivemind-core/server.json on the player device:
{
"agent_protocol": {
"module": "hivemind-player-agent-plugin",
"hivemind-player-agent-plugin": {}
}
}
2. Configure TTS and playback
Edit ~/.config/mycroft/mycroft.conf on the same device: tts configures
the embedded ovos-audio (TTS only), media configures the embedded
ovos-media playback backends.
{
"tts": {
"module": "ovos-tts-plugin-server"
},
"media": {
"preferred_audio_services": ["vlc"],
"audio_players": {
"vlc": {
"module": "ovos-media-audio-plugin-vlc",
"aliases": ["VLC"],
"active": true
}
}
}
}
See docs/configuration.md for the full reference.
3. Create a client credential
On the player device (where hivemind-core will run):
hivemind-core add-client
# note the Access Key and Password printed
4. Grant OCP permissions
# replace 3 with your Node ID from add-client
hivemind-core allow-msg "ovos.common_play.play" 3
hivemind-core allow-msg "ovos.common_play.pause" 3
hivemind-core allow-msg "ovos.common_play.resume" 3
hivemind-core allow-msg "ovos.common_play.stop" 3
hivemind-core allow-msg "ovos.common_play.next" 3
hivemind-core allow-msg "ovos.common_play.previous" 3
hivemind-core allow-msg "ovos.common_play.status" 3
hivemind-core allow-msg "speak" 3
See Permissions for the full list.
5. Set the identity on the controller
On the device that will send commands:
hivemind-client set-identity \
--key <access_key> --password <password> \
--host <player_device_ip> --port 5678 --siteid player
6. Start hivemind-core on the player device
hivemind-core listen
7. Control playback
python hivemind-player-ctl.py play "http://example.com/audio/track.mp3"
python hivemind-player-ctl.py pause
python hivemind-player-ctl.py resume
python hivemind-player-ctl.py next
Home Assistant / Music Assistant Integration
With hivemind-homeassistant, HiveMind player devices appear as media players in Home Assistant. Music Assistant can then browse and play music to them.
Related projects:
hivemind-player-ctl
hivemind-player-ctl.py is a CLI to control a running player. It requires only
hivemind_bus_client and click.
Usage: python hivemind-player-ctl.py [OPTIONS] COMMAND
Options:
--key TEXT Access key (or read from identity file)
--password TEXT Password (or read from identity file)
Commands:
play URI Start playback of a URI
pause Pause
resume Resume
stop Stop
next Next track
prev Previous track
shuffle.set Enable shuffle
shuffle.unset Disable shuffle
repeat.set Enable repeat-all
repeat.unset Disable repeat
interactive Interactive shell
Permissions
Core audio
| Message | Purpose |
|---|---|
speak |
TTS output |
mycroft.audio.is_alive |
Health check |
mycroft.audio.is_ready |
Readiness check |
mycroft.stop |
Stop all audio |
OCP (Open Voice OS Common Play, served by the embedded ovos-media)
Media control is ovos.common_play.* only; the legacy mycroft.audio.service.*
verbs are not served by the embedded stack.
| Message | Purpose |
|---|---|
ovos.common_play.play |
Start playback |
ovos.common_play.pause |
Pause |
ovos.common_play.play_pause |
Toggle play/pause |
ovos.common_play.resume |
Resume |
ovos.common_play.stop |
Stop |
| Message | Purpose |
|---|---|
ovos.common_play.next |
Next track |
ovos.common_play.previous |
Previous track |
ovos.common_play.status |
Query player status (polled by hivemind-ma-player) |
ovos.common_play.track_info |
Query track info |
| Message | Purpose |
|---|---|
ovos.common_play.playlist.queue |
Queue a track |
ovos.common_play.playlist.clear |
Clear the queue |
ovos.common_play.playlist.set |
Replace the queue |
ovos.common_play.set_track_position |
Seek to position |
ovos.common_play.seek |
Seek by an offset |
| Message | Purpose |
|---|---|
ovos.common_play.shuffle.set |
Enable shuffle |
ovos.common_play.shuffle.unset |
Disable shuffle |
ovos.common_play.shuffle.toggle |
Toggle shuffle |
| Message | Purpose |
|---|---|
ovos.common_play.repeat.set |
Enable repeat |
ovos.common_play.repeat.unset |
Disable repeat |
ovos.common_play.repeat.toggle |
Toggle repeat |
| Message | Purpose |
|---|---|
ovos.common_play.like |
Like the current track |
ovos.common_play.unlike |
Unlike the current track |
ovos.common_play.likes |
Query liked tracks |
PHAL (optional)
| Message | Purpose |
|---|---|
mycroft.phal.is_alive |
PHAL health |
mycroft.phal.is_ready |
PHAL readiness |
| Message | Purpose |
|---|---|
mycroft.volume.get |
Query volume |
mycroft.volume.set |
Set volume |
| Message | Purpose |
|---|---|
mycroft.volume.increase |
Volume up |
mycroft.volume.decrease |
Volume down |
mycroft.volume.mute |
Mute |
mycroft.volume.unmute |
Unmute |
Running the tests
The suite is end-to-end. It stands up a real hivemind-core master
in-process and drives the real player plugin over a real HiveMessageBusClient
(through hivescope). It asserts
that remote play, pause, and stop control commands round-trip from a
satellite, through the deny-by-default ACL, to the player.
The media playback backend is mocked. The embedded ovos-media daemon is
disabled (disable_media=True), so no real media backend plugin loads and
nothing touches an audio device or the network.
pip install -e ".[test]" # pulls hivescope + in-process hivemind-core ([e2e])
pytest tests/
The heavyweight e2e hosts live in the [e2e] extra. [test] includes them plus
the test runner. hivescope and hivemind-core are required test dependencies.
The suite never importorskips them.
Documentation
docs/architecture.md: how the player protocol fits into HiveMind.docs/configuration.md: configuration reference.docs/permissions.md: full permissions reference.
License
Apache 2.0.
Metadata
Release files for hivemind-player-protocol 0.1.4a1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| hivemind_player_protocol-0.1.4a1.tar.gz | 12.6 kB | Without provenance | Details for hivemind_player_protocol-0.1.4a1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| hivemind_player_protocol-0.1.4a1-py3-none-any.whl | Python 3 | none | any | Details for hivemind_player_protocol-0.1.4a1-py3-none-any.whl |
Total release size: 21.4 kB
Release files / hivemind_player_protocol-0.1.4a1.tar.gz
| Download URL | hivemind_player_protocol-0.1.4a1.tar.gz |
|---|---|
| Size | 12.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
dc9ab9ade8eda400bb1e14b8eb4fa8183fa358681163b0d41169800bfca7eb7b
|
|
BLAKE2b-256 checksum How to use checksums |
9fbc30bbe5efb22e2dc5f5abc60e7fbfd6da2573b92afa96f40221f0ff091bd6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / hivemind_player_protocol-0.1.4a1-py3-none-any.whl
| Download URL | hivemind_player_protocol-0.1.4a1-py3-none-any.whl |
|---|---|
| Size | 8.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0f5fbaee2b78ad76d758e4f0f3957d15172eed4a3e3de27aa593bf6b2ca9aadf
|
|
BLAKE2b-256 checksum How to use checksums |
a413c8643acdd0b49e5b1b41505a76fcc07e864e8257015dee2129d82a2fc83e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Security for hivemind-player-protocol 0.1.4a1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.