# zerobearing2/omatalk architecture

> Architecture diagram of the GitHub repository zerobearing2/omatalk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zerobearing2/omatalk
- Repository: https://github.com/zerobearing2/omatalk
- Video tour (about a minute): https://gitdiagram.com/zerobearing2/omatalk/video

## Overview

Omatalk is a local text-to-speech service: the user or hotkey requests speech, the daemon captures selected text or clipboard content when needed, synthesizes sentence-first chunks, and streams audio to PipeWire. The CLI also exposes configuration, status, stop, and voice-list operations; the separately maintained bar plugin follows daemon state over a socket. The README documents installation and lifecycle capabilities, but their implementation is not mapped here. Source excerpts are limited, so uncertain internal wiring is omitted.

Main entry points: [`daemon/omatalkd.py`](https://github.com/zerobearing2/omatalk/blob/master/daemon/omatalkd.py) (Daemon service), [`daemon/cli.py`](https://github.com/zerobearing2/omatalk/blob/master/daemon/cli.py) (CLI commands), [`daemon/engine.py`](https://github.com/zerobearing2/omatalk/blob/master/daemon/engine.py) (Kokoro engine), [`daemon/player.py`](https://github.com/zerobearing2/omatalk/blob/master/daemon/player.py) (Audio player)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_configcmd["Config commands<br/>[cli.py]"]
end

subgraph group_daemon["Speech daemon"]
  node_daemonservice["Daemon service<br/>[omatalkd.py]"]
  node_socket["Unix socket<br/>[omatalkd.py]"]
  node_capture["Text capture<br/>[omatalkd.py]"]
end

subgraph group_runtime["Speech runtime"]
  node_chunker["Sentence chunker<br/>[chunker.py]"]
  node_engine["Kokoro engine<br/>[engine.py]"]
  node_player["Audio player<br/>[player.py]"]
end

subgraph group_settings["Configuration and state"]
  node_config[("Effective config<br/>[config.py]")]
  node_models[("Model and voices<br/>[config.py]")]
end

node_user(("User"))
node_hotkey(("Hyprland hotkey"))
node_barplugin["Bar plugin"]
node_kokoro["Kokoro ONNX"]
node_pipewire["PipeWire"]
node_wlpaste["wl-paste"]
node_notify["Desktop notifications"]

node_user -->|"runs commands"| node_cli
node_hotkey -->|"runs speak"| node_cli
node_cli -->|"sends commands"| node_socket
node_socket -->|"dispatches"| node_daemonservice
node_daemonservice -->|"captures text"| node_capture
node_capture -->|"runs capture"| node_wlpaste
node_daemonservice -->|"splits text"| node_chunker
node_daemonservice -->|"synthesizes chunks"| node_engine
node_engine -->|"calls synthesis"| node_kokoro
node_engine -->|"loads models"| node_models
node_daemonservice -->|"streams samples"| node_player
node_player -->|"plays PCM"| node_pipewire
node_daemonservice -->|"loads settings"| node_config
node_cli -->|"handles config"| node_configcmd
node_configcmd -->|"reads and writes"| node_config
node_configcmd -->|"lists voices"| node_models
node_daemonservice -->|"serves state"| node_socket
node_barplugin -.->|"follows state"| node_socket
node_daemonservice -->|"reports errors"| node_notify
node_cli -->|"reports daemon down"| node_notify

click node_cli "https://github.com/zerobearing2/omatalk/blob/master/daemon/cli.py"
click node_configcmd "https://github.com/zerobearing2/omatalk/blob/master/daemon/cli.py"
click node_daemonservice "https://github.com/zerobearing2/omatalk/blob/master/daemon/omatalkd.py"
click node_socket "https://github.com/zerobearing2/omatalk/blob/master/daemon/omatalkd.py"
click node_capture "https://github.com/zerobearing2/omatalk/blob/master/daemon/omatalkd.py"
click node_chunker "https://github.com/zerobearing2/omatalk/blob/master/daemon/chunker.py"
click node_engine "https://github.com/zerobearing2/omatalk/blob/master/daemon/engine.py"
click node_player "https://github.com/zerobearing2/omatalk/blob/master/daemon/player.py"
click node_config "https://github.com/zerobearing2/omatalk/blob/master/daemon/config.py"
click node_models "https://github.com/zerobearing2/omatalk/blob/master/daemon/config.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_configcmd,node_user toneBlue
class node_daemonservice,node_socket,node_capture toneAmber
class node_chunker,node_engine,node_player toneMint
class node_config,node_models toneRose
class node_hotkey,node_barplugin,node_kokoro,node_pipewire,node_wlpaste,node_notify toneIndigo
```

## Components

### User entry points

- [CLI commands](https://github.com/zerobearing2/omatalk/blob/master/daemon/cli.py): `daemon/cli.py`
- [Config commands](https://github.com/zerobearing2/omatalk/blob/master/daemon/cli.py): `daemon/cli.py`

### Speech daemon

- [Daemon service](https://github.com/zerobearing2/omatalk/blob/master/daemon/omatalkd.py): `daemon/omatalkd.py`
- [Unix socket](https://github.com/zerobearing2/omatalk/blob/master/daemon/omatalkd.py): `daemon/omatalkd.py`
- [Text capture](https://github.com/zerobearing2/omatalk/blob/master/daemon/omatalkd.py): `daemon/omatalkd.py`

### Speech runtime

- [Sentence chunker](https://github.com/zerobearing2/omatalk/blob/master/daemon/chunker.py): `daemon/chunker.py`
- [Kokoro engine](https://github.com/zerobearing2/omatalk/blob/master/daemon/engine.py): `daemon/engine.py`
- [Audio player](https://github.com/zerobearing2/omatalk/blob/master/daemon/player.py): `daemon/player.py`

### Configuration and state

- [Effective config](https://github.com/zerobearing2/omatalk/blob/master/daemon/config.py): `daemon/config.py`
- [Model and voices](https://github.com/zerobearing2/omatalk/blob/master/daemon/config.py): `daemon/config.py`

### Other components

- **User**
- **Hyprland hotkey**
- **Bar plugin**
- **Kokoro ONNX**
- **PipeWire**
- **wl-paste**
- **Desktop notifications**

## Connections

- User → CLI commands: runs commands
- Hyprland hotkey → CLI commands: runs speak
- CLI commands → Unix socket: sends commands
- Unix socket → Daemon service: dispatches
- Daemon service → Text capture: captures text
- Text capture → wl-paste: runs capture
- Daemon service → Sentence chunker: splits text
- Daemon service → Kokoro engine: synthesizes chunks
- Kokoro engine → Kokoro ONNX: calls synthesis
- Kokoro engine → Model and voices: loads models
- Daemon service → Audio player: streams samples
- Audio player → PipeWire: plays PCM
- Daemon service → Effective config: loads settings
- CLI commands → Config commands: handles config
- Config commands → Effective config: reads and writes
- Config commands → Model and voices: lists voices
- Daemon service → Unix socket: serves state
- Bar plugin → Unix socket: follows state
- Daemon service → Desktop notifications: reports errors
- CLI commands → Desktop notifications: reports daemon down