Concepts Overview¶

In a nutshell

This tab explains how OpenVoiceOS is built: the processes, the shared message bus that connects them, and the rules each part must follow. It is for developers, integrators, and curious users who want the architecture, not just the install steps. For hands-on install and setup, see the Get Started tab.

This tab is for anyone who wants to understand how OpenVoiceOS is built, not just use it: developers, integrators, and curious users.

Start here¶

High-level Overview: the whole system as a team of small independent parts talking over a shared channel.
The Life of an Utterance: follow one spoken sentence from microphone to answer.
MessageBus Service: the shared channel every other part talks over.
Security & Trust Model: what OVOS assumes about the device it runs on.

Working with the bus¶

These go deeper than the service page, for when you are debugging traffic rather than learning the model.

Bus Restart & Reconnect: what happens to a client when the bus goes away.
Bus Namespace Migration: the old and new topic names, and which to emit.
Bus Recipes: worked examples of common message exchanges.
Bus Bridges: connecting one bus to another without merging them.
Scheduled Events: asking for something to happen later.
dig_for_message: how a handler finds the message it is answering, and why the wrong one is a common bug.

Specs and quality¶

OVOS components follow written specs, and this manual has tooling to check code against them. Start with the specs themselves, then the tooling, then the badge scale used to mark how mature each part is.

Formal Specifications: component contracts written down, not just implemented.
Specification Tooling: tools that check code against those contracts.
ovos-spec-tools: the library those tools are built on.
ovos-test-harness: running a component against a spec.
Maturity Scale: how to read the maturity badges used throughout this manual.

System pieces¶

Two cross-cutting pieces don't fit under a single service: how plugins get discovered, and how to run OVOS as a library instead of a full assistant.

Composable Deployments: using OVOS as a library instead of the full assistant.

Plugin discovery and the list of plugin types live in the Plugins tab with the rest of the ecosystem. Start at How Plugins Load.

Configuration¶

Start with the overview to learn where config files live and how they layer, then use the reference and locations pages as lookup tables.

Overview: how settings are changed and where they live.
Internals: how the layers are merged, for when the result surprises you.
Reference: lookup table of settings and defaults.
All Configuration Keys: every key OVOS ships, generated from the shipped file.
Locations: the folders OVOS reads and writes.

ovos-core Internals¶

ovos-core is the process that owns skills and intent matching. Its parts:

Overview, Skill Manager, Intent Service, Skill Installer.

Sibling Services¶

These run as their own processes on the bus, separate from ovos-core. Each page covers one service; start with whichever one matches the part of the system you're investigating.

Speech Service, Audio Service, Media Service.
Media internals: OCP Pipeline Plugin, MPRIS Integration, Legacy Compatibility.
Screens on OVOS Today, GUI Service (legacy).
PHAL for hardware access, and Writing PHAL Plugins.

Digging into how intents get matched? That's the Pipeline tab. Building a skill? That's the Skills tab.