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
Release files for ovos-bus-client 2.11.23a1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| ovos_bus_client-2.11.23a1.tar.gz | 130.2 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| ovos_bus_client-2.11.23a1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 273.1 kB
Release files / ovos_bus_client-2.11.23a1.tar.gz
| Download URL | ovos_bus_client-2.11.23a1.tar.gz |
|---|---|
| Size | 130.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fe3191ceb50abdba1a8d63f338b145eaecdaf42cd2daee9a921e3fc3ca3d3b1e
|
|
BLAKE2b-256 checksum How to use checksums |
99ae4ca01f9ee07bc9a7a6baa4df83aeeb3b1963b247875a31121c037535d9f0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / ovos_bus_client-2.11.23a1-py3-none-any.whl
| Download URL | ovos_bus_client-2.11.23a1-py3-none-any.whl |
|---|---|
| Size | 142.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
90dd98d3d75ec0c1cad048aa7604207bc851dc5e90cb69d71b96c13d0635ec45
|
|
BLAKE2b-256 checksum How to use checksums |
4cbebf0723ff8853673a17d7ce49c65608e3f6801af27408b5290c7c8687dd87
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
