This release is a pre-release and may not be stable for production use.
OpenVoiceOS Bus Client
A Python client for the OVOS messagebus. Connect to OVOS, emit messages, and react to system events.
The OVOS messagebus is the nervous system of an OVOS install. Every component — STT, intent parsing, skills, TTS, audio, GUI — talks over it. This package is the Python client.
⚠️ The bus is private. It has no authentication — every connected client can issue any natural-language command, speak through the speakers, take over any subsystem, and read every other client's traffic. Keep it bound to
127.0.0.1(the default), never expose it on a network interface, and never put it behind a reverse proxy. For remote access, use HiveMind, which adds encryption, identity, and policy enforcement on top.
Install
pip install ovos-bus-client
Quick start
from ovos_bus_client import MessageBusClient, Message
client = MessageBusClient()
client.run_in_thread()
client.connected_event.wait()
client.emit(Message('speak', data={'utterance': 'Hello World'}))
Listening for messages:
from ovos_bus_client import MessageBusClient
client = MessageBusClient()
def on_speak(message):
print('OVOS said:', message.data.get('utterance'))
client.on('speak', on_speak)
client.run_forever()
Async alternative
For asyncio-native code, install the optional [async] extra and use
AsyncMessageBusClient:
pip install ovos-bus-client[async]
import asyncio
from ovos_bus_client import Message
from ovos_bus_client.client import AsyncMessageBusClient
async def main():
bus = AsyncMessageBusClient()
await bus.connect()
bus.on("speak", lambda m: print("OVOS said:", m.data.get("utterance")))
await bus.emit(Message("speak", {"utterance": "hello from asyncio"}))
reply = await bus.wait_for_response(
Message("ovos.languages.stt"), timeout=3.0,
)
await bus.close()
asyncio.run(main())
Both clients share the same Message, Session, and event-emitter shape;
pick whichever matches the rest of your application. See
docs/async_client.md for the full async reference.
CLI tools
| Command | Description |
|---|---|
ovos-speak <text> [lang] |
Ask OVOS to speak a phrase |
ovos-say-to <text> [lang] |
Inject an utterance into the intent pipeline |
ovos-listen |
Trigger the wake-word / listen cycle |
ovos-simple-cli [lang] |
Interactive text REPL for OVOS |
Configuration
MessageBusClient reads the websocket block of your OVOS config (loaded by ovos-config) — defaults to ws://127.0.0.1:8181/core. Override at construction:
MessageBusClient(host='127.0.0.1', port=8181)
Do not change host to anything routable. See the security callout above.
Migrating from 1.x
Two modules were removed in 2.0.0. Install their replacement packages if you used them:
| Removed | Replacement | Install |
|---|---|---|
ovos_bus_client.hpm.OVOSProtocol |
hivemind-ovos-agent-plugin |
pip install hivemind-ovos-agent-plugin |
ovos_bus_client.opm.OVOSMessagebusSolver |
ovos-messagebus-chat-plugin |
pip install ovos-messagebus-chat-plugin |
The HiveMind agent entry point (hivemind.agent.protocol) and the solver entry point (neon.plugin.solver) are no longer registered by this package. See docs/migration.md for details.
Documentation
Full developer docs live in docs/:
- Getting started — install to first message
- Core concepts — bus model and the security boundary
- Messages —
Message,GUIMessage, reply helpers - The client —
MessageBusClientAPI in depth - The async client —
AsyncMessageBusClient(pip install ovos-bus-client[async]) - Configuration — host, port, route, ssl
- Sessions —
Session,SessionManager,IntentContextManager - Waiters and collectors — request/response and multi-reply patterns
- High-level APIs —
GUIInterface,OCPInterface,EnclosureAPI - Scheduled events — firing an event at a wall-clock instant, once or on a recurrence
- CLI tools —
ovos-speak,ovos-listen,ovos-say-to,ovos-simple-cli - Common patterns — recipes for everyday use
- Testing —
FakeBus, isolating tests - Migration from 1.x — what moved out in 2.0
- Prerelease quirks — what changed since the last stable release
- Development — repo layout, releases
- Glossary — terms
Related
- ovos-pydantic-models — authoritative Pydantic v2 index of every OVOS bus message type. Opt-in validation layer for typing, docs generation, and integration tests. Browsable docs: https://openvoiceos.github.io/ovos-pydantic-models/.
- HiveMind — external-access layer in front of the bus; the right tool for remote clients.
License
Apache 2.0. See LICENSE.md.
2 maintainers
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file ovos_bus_client-2.11.11a1.tar.gz.
File metadata
- Download URL: ovos_bus_client-2.11.11a1.tar.gz
- Upload date:
- Size: 115.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
93b9af524034437ee9ceb9f8ff087b71673e9015babd1d00d9549212d21567d3
|
|
| MD5 |
e08386ddd2d8a2dccd3b59a7e8f25181
|
|
| BLAKE2b-256 |
8ead14f3d69742007cbc54ef3386d0d676dbf4031004d2a8182caeb9f850b15e
|
File details
Details for the file ovos_bus_client-2.11.11a1-py3-none-any.whl.
File metadata
- Download URL: ovos_bus_client-2.11.11a1-py3-none-any.whl
- Upload date:
- Size: 128.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
662a73d23bf7e13b2a7214f3dd992a101d9989405d64628ef4e971bb3dba27f5
|
|
| MD5 |
4c680238d5c844c306dab54409343ad5
|
|
| BLAKE2b-256 |
4d63d79fd6b2611378d0011f876fe632005195a28ee3cf3c55b9372fe4df4e9d
|
