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
Metadata
2 maintainers
Release files for ovos-bus-client 2.11.24a1
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.24a1.tar.gz | 131.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| ovos_bus_client-2.11.24a1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 275.9 kB
Release files / ovos_bus_client-2.11.24a1.tar.gz
| Download URL | ovos_bus_client-2.11.24a1.tar.gz |
|---|---|
| Size | 131.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
863d20d2c45ab9f382c19c2df961893de979485e3861bc4ca2af5879252d4d67
|
|
BLAKE2b-256 checksum How to use checksums |
b6818f3cb6046a7d3bca404d467f533cba6ab00be751b6a4ac56cccdc73cbf43
|
| 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.24a1-py3-none-any.whl
| Download URL | ovos_bus_client-2.11.24a1-py3-none-any.whl |
|---|---|
| Size | 144.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
87faee8429f1e1e3b0c98452bbef5af8d0128a0a424ced77d0880331f01754c6
|
|
BLAKE2b-256 checksum How to use checksums |
aaa2ecc2272f1dba1ed8804d54bcd8881af236d1af301b5429a4872fbd2f6dbd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
