# koljab/realtimestt architecture

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

- Interactive diagram: https://gitdiagram.com/koljab/realtimestt
- Repository: https://github.com/koljab/realtimestt

## Overview

RealtimeSTT is a speech-to-text library for microphone or application-fed audio, with optional live text, wake-word activation, and selectable recognition engines. Its main user path is to submit audio to a recorder, detect speech boundaries, produce realtime updates when enabled, and return a final transcript. The product also includes a packaged remote HTTP/WebSocket server and a browser streaming reference app. The graph follows documented capabilities and sampled module references; some internal call paths and server details are not shown in the excerpts, so those links are omitted rather than inferred.

Main entry points: [`RealtimeSTT/audio_recorder.py`](https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/audio_recorder.py) (Recorder API), [`RealtimeSTT/core/recording.py`](https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/core/recording.py) (Recording buffers), [`RealtimeSTT/core/realtime.py`](https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/core/realtime.py) (Realtime transcription), [`RealtimeSTT/transcription_engines`](https://github.com/koljab/realtimestt/tree/master/RealtimeSTT/transcription_engines) (Engine adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Audio and activation"]
  node_recorder["Recorder API<br/>[audio_recorder.py]"]
  node_audio["Audio input<br/>[audio_input.py]"]
  node_vad["Voice activity<br/>[voice_activity.py]"]
  node_wake["Wake words<br/>[wakeword.py]"]
  node_recording["Recording buffers<br/>[recording.py]"]
  node_state["Recorder state<br/>[state.py]"]
end

subgraph group_speech["Transcription workflow"]
  node_preview["Preview transcription"]
  node_realtime["Realtime transcription<br/>[realtime.py]"]
  node_boundary["Speech boundaries"]
  node_merge["Realtime text merge<br/>[realtime_merge.py]"]
  node_stabilizer["Text stabilization"]
  node_final["Final transcription<br/>[transcription.py]"]
  node_tail["Tail finalization"]
  node_callbacks["Events and callbacks"]
end

subgraph group_engines["Recognition engines"]
  node_engine_api["Engine interfaces<br/>[base.py]"]
  node_engine_adapters["Engine adapters"]
  node_model_manifests["Model manifests<br/>[model_manifests.py]"]
end

subgraph group_remote["Remote services"]
  node_production["Production HTTP/WebSocket API"]
  node_browser_server["Browser streaming server<br/>[server.py]"]
end

subgraph group_integrations["Client integrations"]
  node_remote_client["Recorder WebSocket client"]
  node_browser_client["Browser client<br/>[client.js]"]
end

node_user(("Application user"))
node_asr_service["ASR engine runtime"]

node_user -->|"configures and requests"| node_recorder
node_user -->|"feeds audio"| node_audio
node_recorder -->|"detects speech"| node_vad
node_recorder -.->|"optionally activates"| node_wake
node_recorder -->|"records utterance"| node_recording
node_recording -.->|"requests live preview"| node_preview
node_recording -.->|"requests live updates"| node_realtime
node_realtime -.->|"uses boundaries"| node_boundary
node_realtime -->|"merges updates"| node_merge
node_realtime -.->|"stabilizes text"| node_stabilizer
node_recording -->|"transcribes utterance"| node_final
node_final -->|"uses speech tail"| node_tail
node_recorder -->|"emits events"| node_callbacks
node_final -.->|"uses engine interface"| node_engine_api
node_engine_adapters -->|"implements interface"| node_engine_api
node_engine_adapters -.->|"runs recognition"| node_asr_service
node_engine_adapters -->|"resolves model profiles"| node_model_manifests
node_remote_client -->|"captures microphone audio"| node_audio
node_remote_client -.->|"streams to server"| node_production
node_user -->|"uses remote API"| node_production
node_browser_client -.->|"streams audio"| node_browser_server
node_browser_server -->|"uses recorder"| node_recorder
node_production -.->|"provides transcription"| node_engine_adapters

click node_recorder "https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/audio_recorder.py"
click node_audio "https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/audio_input.py"
click node_vad "https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/core/voice_activity.py"
click node_wake "https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/core/wakeword.py"
click node_recording "https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/core/recording.py"
click node_state "https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/core/state.py"
click node_preview "https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/core/preview_transcription.py"
click node_realtime "https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/core/realtime.py"
click node_boundary "https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/core/realtime_boundary_detector.py"
click node_merge "https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/core/realtime_merge.py"
click node_stabilizer "https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/core/realtime_text_stabilizer.py"
click node_final "https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/core/transcription.py"
click node_tail "https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/core/tail_transcription.py"
click node_callbacks "https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/core/realtime_callbacks.py"
click node_engine_api "https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/transcription_engines/base.py"
click node_engine_adapters "https://github.com/koljab/realtimestt/tree/master/RealtimeSTT/transcription_engines"
click node_model_manifests "https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/model_manifests.py"
click node_remote_client "https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/audio_recorder_client.py"
click node_production "https://github.com/koljab/realtimestt/blob/master/RealtimeSTT_server/production_server.py"
click node_browser_server "https://github.com/koljab/realtimestt/blob/master/example_fastapi_server/server.py"
click node_browser_client "https://github.com/koljab/realtimestt/blob/master/example_browserclient/client.js"

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_recorder,node_audio,node_vad,node_wake,node_recording,node_state,node_user toneBlue
class node_preview,node_realtime,node_boundary,node_merge,node_stabilizer,node_final,node_tail,node_callbacks toneAmber
class node_engine_api,node_engine_adapters,node_model_manifests toneMint
class node_production,node_browser_server toneRose
class node_remote_client,node_browser_client,node_asr_service toneIndigo
```

## Components

### Audio and activation

- [Recorder API](https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/audio_recorder.py): `RealtimeSTT/audio_recorder.py`
- [Audio input](https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/audio_input.py): `RealtimeSTT/audio_input.py`
- [Voice activity](https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/core/voice_activity.py): `RealtimeSTT/core/voice_activity.py`
- [Wake words](https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/core/wakeword.py): `RealtimeSTT/core/wakeword.py`
- [Recording buffers](https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/core/recording.py): `RealtimeSTT/core/recording.py`
- [Recorder state](https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/core/state.py): `RealtimeSTT/core/state.py`

### Transcription workflow

- [Preview transcription](https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/core/preview_transcription.py): `RealtimeSTT/core/preview_transcription.py`
- [Realtime transcription](https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/core/realtime.py): `RealtimeSTT/core/realtime.py`
- [Speech boundaries](https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/core/realtime_boundary_detector.py): `RealtimeSTT/core/realtime_boundary_detector.py`
- [Realtime text merge](https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/core/realtime_merge.py): `RealtimeSTT/core/realtime_merge.py`
- [Text stabilization](https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/core/realtime_text_stabilizer.py): `RealtimeSTT/core/realtime_text_stabilizer.py`
- [Final transcription](https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/core/transcription.py): `RealtimeSTT/core/transcription.py`
- [Tail finalization](https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/core/tail_transcription.py): `RealtimeSTT/core/tail_transcription.py`
- [Events and callbacks](https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/core/realtime_callbacks.py): `RealtimeSTT/core/realtime_callbacks.py`

### Recognition engines

- [Engine interfaces](https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/transcription_engines/base.py): `RealtimeSTT/transcription_engines/base.py`
- [Engine adapters](https://github.com/koljab/realtimestt/tree/master/RealtimeSTT/transcription_engines): `RealtimeSTT/transcription_engines`
- [Model manifests](https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/model_manifests.py): `RealtimeSTT/model_manifests.py`

### Remote services

- [Production HTTP/WebSocket API](https://github.com/koljab/realtimestt/blob/master/RealtimeSTT_server/production_server.py): `RealtimeSTT_server/production_server.py`
- [Browser streaming server](https://github.com/koljab/realtimestt/blob/master/example_fastapi_server/server.py): `example_fastapi_server/server.py`

### Client integrations

- [Recorder WebSocket client](https://github.com/koljab/realtimestt/blob/master/RealtimeSTT/audio_recorder_client.py): `RealtimeSTT/audio_recorder_client.py`
- [Browser client](https://github.com/koljab/realtimestt/blob/master/example_browserclient/client.js): `example_browserclient/client.js`

### Other components

- **Application user**
- **ASR engine runtime**

## Connections

- Application user → Recorder API: configures and requests
- Application user → Audio input: feeds audio
- Recorder API → Voice activity: detects speech
- Recorder API → Wake words: optionally activates (evidence: `RealtimeSTT/audio_recorder.py`)
- Recorder API → Recording buffers: records utterance (evidence: `RealtimeSTT/audio_recorder.py`)
- Recording buffers → Preview transcription: requests live preview (evidence: `RealtimeSTT/core/recording.py`)
- Recording buffers → Realtime transcription: requests live updates (evidence: `RealtimeSTT/core/recording.py`)
- Realtime transcription → Speech boundaries: uses boundaries
- Realtime transcription → Realtime text merge: merges updates
- Realtime transcription → Text stabilization: stabilizes text (evidence: `RealtimeSTT/core/initialization.py`)
- Recording buffers → Final transcription: transcribes utterance (evidence: `RealtimeSTT/core/recording.py`)
- Final transcription → Tail finalization: uses speech tail (evidence: `RealtimeSTT/core/recording.py`)
- Recorder API → Events and callbacks: emits events
- Final transcription → Engine interfaces: uses engine interface
- Engine adapters → Engine interfaces: implements interface (evidence: `RealtimeSTT/transcription_engines/funasr_engine.py`)
- Engine adapters → ASR engine runtime: runs recognition
- Engine adapters → Model manifests: resolves model profiles (evidence: `RealtimeSTT/transcription_engines/nemotron_engine.py`)
- Recorder WebSocket client → Audio input: captures microphone audio (evidence: `RealtimeSTT/audio_recorder_client.py`)
- Recorder WebSocket client → Production HTTP/WebSocket API: streams to server
- Application user → Production HTTP/WebSocket API: uses remote API
- Browser client → Browser streaming server: streams audio
- Browser streaming server → Recorder API: uses recorder (evidence: `example_fastapi_server/server.py`)
- Production HTTP/WebSocket API → Engine adapters: provides transcription
