This project allows you to turn any device into a media player that can be controlled remotely. It achieves this by using HiveMind to connect and control the Open Voice OS (OVOS) audio stack remotely.
Essentially, you'll run two main components:
hivemind-core: The central hub that manages connections and messages. Think of it as the brain of your remote control system.hivemind-player-agent: This is a small plugin that turns thehivemind-coredevice into a media player.
By running both of these, you can send standard Open Voice OS Common Play (OCP) messages to the player device to control audio playback. For example, you can send a message to play a song, pause it, or skip to the next track.
Note: This setup is designed for devices that are not already running Open Voice OS. It's perfect for things like a Raspberry Pi dedicated to being a speaker.
One of the most powerful uses of this protocol is to integrate your HiveMind players with Home Assistant 🏡 and Music Assistant. This allows you to turn any device you set up into a media player that can be controlled directly from your smart home dashboard.
By using hivemind-homeassistant, your HiveMind player will show up in Home Assistant. From there, you can use Music Assistant to browse and play music from various sources in your new HiveMind-powered player.
Related Projects:
- hivemind-homeassistant: A component that allows HiveMind devices to be discovered and controlled within Home Assistant.
- ovos-skill-music-assistant: An OVOS skill that enables you to search for media in your Music Assistant libraries.
- ovos-media-plugin-mass: An OVOS plugin that allows you to control Music Assistant players directly.
To get started, you'll need to configure both hivemind-core and the ovos-audio stack.
The first step is to tell HiveMind which agent to use. You'll edit the server.json configuration file, typically located at ~/.config/hivemind-core/server.json.
{
"agent_protocol": {
"module": "hivemind-player-agent-plugin",
"hivemind-player-agent-plugin": {}
}
}In this file, you'll set the agent_protocol module to "hivemind-player-agent-plugin". This tells HiveMind to load the correct plugin for controlling the player device.
Next, you need to configure the audio player itself. The ovos-audio stack is part of the Open Voice OS ecosystem and handles all audio playback and text-to-speech (TTS) functions. You'll configure it by editing mycroft.conf, usually found at ~/.config/mycroft/mycroft.conf.
Within this file, you'll find two key sections:
"Audio": This is where you configure the specific audio players you want to use."tts": This section is for configuring the text-to-speech module, which allows the device to speak.
The HiveMind player exposes a standalone ovos-audio under hivemind-core. This means all existing TTS and player plugins for OpenVoiceOS should work! Please refer to the OpenVoiceOS project for more information.
Here is an example configuration:
{
"play_wav_cmdline": "paplay %1",
"play_mp3_cmdline": "mpg123 %1",
"play_ogg_cmdline": "ogg123 -q %1",
"tts": {
"module": "ovos-tts-plugin-server"
},
"Audio": {
"backends": {
"OCP": {
"type": "ovos_common_play",
"preferred_audio_services": ["mpv", "vlc"],
"disable_mpris": true,
"dbus_type": "session",
"manage_external_players": false,
"active": true
},
"vlc": {
"type": "vlc",
"active": true,
"initial_volume": 100,
"low_volume": 50
},
"mpv": {
"type": "mpv",
"active": true,
"initial_volume": 100,
"low_volume": 50
}
}
}
}In this example, OCP is configured as the main audio backend, with a preference for using players like MPV or VLC. Specific vlc and mpv players are also configured for reference. This shows the flexibility of the ovos-audio stack to handle various playback plugins.
To ensure only authorized devices can control your media player, HiveMind uses a robust security and permissions system. You will need to create and configure an access key for your controlling device. This acts as a set of credentials, allowing it to connect to and send commands to hivemind-core.
First, use the hivemind-core add-client command to generate a unique set of credentials. You'll need the Access Key and Password from this output to connect your controlling device later.
$ hivemind-core add-client
Database backend: JsonDB
Credentials added to database!
Node ID: 3
Friendly Name: HiveMind-Node-2
Access Key: 57e488946808014168d9237c11e68959
Password: a60319726ca815102f7c5ff88527ec37
Encryption Key: 588816c6ba5477c3
WARNING: Encryption Key is deprecated, only use if your client does not support passwordKeep these credentials secure! You'll use them to authenticate your controlling device.
Once the client is created, you must explicitly grant it permission to send specific types of messages. The HiveMind permissions system operates on a "deny by default" principle, meaning you have to allow every message type you want to use.
Use the hivemind-core allow-msg command to grant these permissions. The command requires two arguments: the message type (e.g., "speak") and the Node ID of the client you just created.
For example, to allow your client (Node ID: 3) to trigger the text-to-speech engine ("speak"), you would run:
$ hivemind-core allow-msg "speak" 3
Allowed 'speak' for HiveMind-Node-2You must repeat this command for every message listed in the Permissions section below. This ensures your controlling device has all the necessary privileges to manage the media player.
These messages are required for core audio functionality, including text-to-speech and general playback status.
speakmycroft.audio.is_alivemycroft.audio.is_readymycroft.audio.speak.statusmycroft.stop
These are the primary messages used to control media playback, covering actions like playing, pausing, and managing playlists.
ovos.common_play.player.statusovos.common_play.track_infoovos.common_play.get_track_lengthovos.common_play.get_track_positionovos.common_play.playlist.queueovos.common_play.playovos.common_play.resumeovos.common_play.pauseovos.common_play.stopovos.common_play.previousovos.common_play.nextovos.common_play.set_track_positionovos.common_play.playlist.clearovos.common_play.shuffle.setovos.common_play.shuffle.unsetovos.common_play.repeat.setovos.common_play.repeat.unsetovos.common_play.repeat.one
(only if enabled manually — for systems without the OCP Audio Plugin)
If you're not using OCP, these messages provide a direct way to control the underlying audio service.
mycroft.audio.service.playmycroft.audio.service.resumemycroft.audio.service.pausemycroft.audio.service.stopmycroft.audio.service.prevmycroft.audio.service.nextmycroft.audio.service.set_track_position
(optional for platform/hardware plugins)
mycroft.phal.is_alivemycroft.phal.is_ready
(optional for volume control)
If you want to control the system's volume, you'll need to allow these specific volume control messages.
mycroft.volume.getmycroft.volume.setmycroft.volume.increasemycroft.volume.decreasemycroft.volume.mutemycroft.volume.unmute
The hivemind-player-ctl.py script provides a simple command-line interface (CLI) to remotely control your HiveMind-enabled media player. The only requirements are hivemind_bus_client and click.
The script requires an Access Key and Password to connect to hivemind-core. You can either provide these credentials as command-line arguments or, for convenience, let the script read them from a saved identity file. Refer to the Access Keys section of this README for instructions on generating these credentials.
All commands follow the same pattern: you invoke the script with the necessary authentication flags, followed by the specific command you wish to execute. To see a list of all available commands, use the --help flag:
python hivemind-player-ctl.py --helpHere are some common ways to use the script:
1. Playing a Media File
To start playback of a specific URI (e.g., an MP3 file on a web server), use the play command:
python hivemind-player-ctl.py --key <your_key> --password <your_password> play "http://example.com/audio/test.mp3"(Note: Replace <your_key> and <your_password> with your actual credentials)
2. Controlling Playback
Control playback using the dedicated commands. If your credentials are saved in an identity file, you can omit the --key and --password flags for a simpler command:
# Pause the current track
python hivemind-player-ctl.py pause
# Resume playback
python hivemind-player-ctl.py resume
# Skip to the next track
python hivemind-player-ctl.py next
# Go back to the previous track
python hivemind-player-ctl.py prev3. Shuffle and Repeat Enable or disable shuffle and repeat modes using the specific subcommands:
# Enable shuffle mode
python hivemind-player-ctl.py shuffle.set
# Disable shuffle mode
python hivemind-player-ctl.py shuffle.unset
# Enable repeat-all mode
python hivemind-player-ctl.py repeat.set
# Enable repeat-one mode
python hivemind-player-ctl.py repeat.one
# Disable repeat
python hivemind-player-ctl.py repeat.unset4. Using the Interactive Shell
For continuous control without having to re-run the script for every command, use the interactive command. This opens a dedicated shell where you can type commands like play, pause, and next.
python hivemind-player-ctl.py interactiveYou can then type commands directly into the prompt:
== Connected to HiveMind. Type 'quit' to exit.
Commands: play <uri>, pause, resume, next, prev, shuffle.<set|unset>, repeat.<set|unset|one>, quit
command: play "https://example.com/audio/another_song.wav"
command: pause
command: next
command: quit
