# churchpresenter/stt architecture

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

- Interactive diagram: https://gitdiagram.com/churchpresenter/stt
- Repository: https://github.com/churchpresenter/stt

## Overview

STT is a real-time and batch speech-to-text platform with a browser control and display interface. The primary workflow captures or uploads audio, transcribes it, optionally translates it and synthesizes speech, then streams captions and stores session records for later review and export. The graph also includes the documented phase analysis, model management, file handling, and watchdog capabilities. Several subsystems are represented by their enclosing directory because their implementation files were not sampled; the README documents their roles, but not every internal call.

Main entry points: [`speech_to_text.py`](https://github.com/churchpresenter/stt/blob/main/speech_to_text.py) (STT server), [`stt/audio_capture.py`](https://github.com/churchpresenter/stt/blob/main/stt/audio_capture.py) (Audio capture), [`stt/llm_translate.py`](https://github.com/churchpresenter/stt/blob/main/stt/llm_translate.py) (Translation engines), [`stt/tts_backends.py`](https://github.com/churchpresenter/stt/blob/main/stt/tts_backends.py) (Text-to-speech)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture and transcription"]
  node_server["STT server<br/>[speech_to_text.py]"]
  node_audio["Audio capture<br/>[audio_capture.py]"]
  node_file_transcription["File transcription"]
  node_asr["Speech recognition<br/>[speech_to_text.py]"]
  node_vad_detection["VAD and sound detection<br/>[speech_to_text.py]"]
  node_calibration["Microphone calibration<br/>[calibration.py]"]
end

subgraph group_language["Translation and speech"]
  node_translation["Translation engines<br/>[llm_translate.py]"]
  node_language_catalog["Language catalogs<br/>[nllb_catalog.py]"]
  node_tts["Text-to-speech<br/>[tts_backends.py]"]
end

subgraph group_review["Review and session data"]
  node_caption_display["Caption display<br/>[speech_to_text.py]"]
  node_corrections["Corrections and staging"]
  node_phase_analysis["Service phase analysis<br/>[service_phase.py]"]
  node_sermon_summary["Sermon summaries<br/>[sermon_summary.py]"]
  node_session_store[("Session database<br/>[session_meta.py]")]
  node_file_manager["Backup file manager"]
end

subgraph group_operations["Models and operations"]
  node_model_manager["Model manager<br/>[downloads.py]"]
  node_watchdog["Watchdog<br/>[watchdog.py]"]
end

node_operator(("Operator"))
node_viewers(("Browser viewers"))
node_remote_translation["Paired STT server"]
node_cloud_tts["Edge-TTS service"]
node_huggingface["Hugging Face"]
node_managed_server["Managed STT process<br/>[speech_to_text.py]"]
node_nas["SMB/NAS share"]

node_operator -->|"operates"| node_server
node_viewers -->|"view captions"| node_caption_display
node_audio -->|"streams microphone audio"| node_server
node_server -->|"starts capture"| node_audio
node_server -->|"transcribes uploads"| node_file_transcription
node_server -->|"transcribes audio"| node_asr
node_server -->|"filters and classifies"| node_vad_detection
node_operator -->|"calibrates microphone"| node_calibration
node_server -->|"translates captions"| node_translation
node_translation -.->|"uses language codes"| node_language_catalog
node_server -.->|"offloads translation"| node_remote_translation
node_server -->|"synthesizes speech"| node_tts
node_tts -.->|"uses cloud voices"| node_cloud_tts
node_server -->|"streams captions"| node_caption_display
node_operator -->|"reviews captions"| node_corrections
node_server -->|"detects service phases"| node_phase_analysis
node_phase_analysis -.->|"provides sermon blocks"| node_sermon_summary
node_server -->|"records session"| node_session_store
node_operator -->|"manages backups"| node_file_manager
node_file_manager -.->|"delivers backups"| node_nas
node_operator -->|"manages models"| node_model_manager
node_model_manager -->|"downloads models"| node_huggingface
node_watchdog -->|"starts and restarts"| node_managed_server

click node_server "https://github.com/churchpresenter/stt/blob/main/speech_to_text.py"
click node_audio "https://github.com/churchpresenter/stt/blob/main/stt/audio_capture.py"
click node_file_transcription "https://github.com/churchpresenter/stt/tree/main/stt"
click node_asr "https://github.com/churchpresenter/stt/blob/main/speech_to_text.py"
click node_vad_detection "https://github.com/churchpresenter/stt/blob/main/speech_to_text.py"
click node_calibration "https://github.com/churchpresenter/stt/blob/main/stt/calibration.py"
click node_translation "https://github.com/churchpresenter/stt/blob/main/stt/llm_translate.py"
click node_language_catalog "https://github.com/churchpresenter/stt/blob/main/stt/nllb_catalog.py"
click node_tts "https://github.com/churchpresenter/stt/blob/main/stt/tts_backends.py"
click node_caption_display "https://github.com/churchpresenter/stt/blob/main/speech_to_text.py"
click node_corrections "https://github.com/churchpresenter/stt/tree/main/stt"
click node_phase_analysis "https://github.com/churchpresenter/stt/blob/main/stt/service_phase.py"
click node_sermon_summary "https://github.com/churchpresenter/stt/blob/main/stt/sermon_summary.py"
click node_session_store "https://github.com/churchpresenter/stt/blob/main/stt/session_meta.py"
click node_file_manager "https://github.com/churchpresenter/stt/tree/main/stt"
click node_model_manager "https://github.com/churchpresenter/stt/blob/main/stt/downloads.py"
click node_watchdog "https://github.com/churchpresenter/stt/blob/main/stt/watchdog.py"
click node_managed_server "https://github.com/churchpresenter/stt/blob/main/speech_to_text.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_server,node_audio,node_file_transcription,node_asr,node_vad_detection,node_calibration,node_viewers toneBlue
class node_translation,node_language_catalog,node_tts toneAmber
class node_caption_display,node_corrections,node_phase_analysis,node_sermon_summary,node_session_store,node_file_manager,node_remote_translation toneMint
class node_model_manager,node_watchdog toneRose
class node_operator,node_cloud_tts,node_huggingface,node_nas toneIndigo
class node_managed_server toneTeal
```

## Components

### Capture and transcription

- [STT server](https://github.com/churchpresenter/stt/blob/main/speech_to_text.py): `speech_to_text.py`
- [Audio capture](https://github.com/churchpresenter/stt/blob/main/stt/audio_capture.py): `stt/audio_capture.py`
- [File transcription](https://github.com/churchpresenter/stt/tree/main/stt): `stt`
- [Speech recognition](https://github.com/churchpresenter/stt/blob/main/speech_to_text.py): `speech_to_text.py`
- [VAD and sound detection](https://github.com/churchpresenter/stt/blob/main/speech_to_text.py): `speech_to_text.py`
- [Microphone calibration](https://github.com/churchpresenter/stt/blob/main/stt/calibration.py): `stt/calibration.py`

### Translation and speech

- [Translation engines](https://github.com/churchpresenter/stt/blob/main/stt/llm_translate.py): `stt/llm_translate.py`
- [Language catalogs](https://github.com/churchpresenter/stt/blob/main/stt/nllb_catalog.py): `stt/nllb_catalog.py`
- [Text-to-speech](https://github.com/churchpresenter/stt/blob/main/stt/tts_backends.py): `stt/tts_backends.py`

### Review and session data

- [Caption display](https://github.com/churchpresenter/stt/blob/main/speech_to_text.py): `speech_to_text.py`
- [Corrections and staging](https://github.com/churchpresenter/stt/tree/main/stt): `stt`
- [Service phase analysis](https://github.com/churchpresenter/stt/blob/main/stt/service_phase.py): `stt/service_phase.py`
- [Sermon summaries](https://github.com/churchpresenter/stt/blob/main/stt/sermon_summary.py): `stt/sermon_summary.py`
- [Session database](https://github.com/churchpresenter/stt/blob/main/stt/session_meta.py): `stt/session_meta.py`
- [Backup file manager](https://github.com/churchpresenter/stt/tree/main/stt): `stt`

### Models and operations

- [Model manager](https://github.com/churchpresenter/stt/blob/main/stt/downloads.py): `stt/downloads.py`
- [Watchdog](https://github.com/churchpresenter/stt/blob/main/stt/watchdog.py): `stt/watchdog.py`

### Other components

- **Operator**
- **Browser viewers**
- **Paired STT server**
- **Edge-TTS service**
- **Hugging Face**
- [Managed STT process](https://github.com/churchpresenter/stt/blob/main/speech_to_text.py): `speech_to_text.py`
- **SMB/NAS share**

## Connections

- Operator → STT server: operates (evidence: `README.md`)
- Browser viewers → Caption display: view captions (evidence: `README.md`)
- Audio capture → STT server: streams microphone audio (evidence: `README.md`)
- STT server → Audio capture: starts capture (evidence: `README.md`)
- STT server → File transcription: transcribes uploads (evidence: `README.md`)
- STT server → Speech recognition: transcribes audio (evidence: `README.md`)
- STT server → VAD and sound detection: filters and classifies (evidence: `README.md`)
- Operator → Microphone calibration: calibrates microphone (evidence: `README.md`)
- STT server → Translation engines: translates captions (evidence: `README.md`)
- Translation engines → Language catalogs: uses language codes
- STT server → Paired STT server: offloads translation (evidence: `README.md`)
- STT server → Text-to-speech: synthesizes speech (evidence: `README.md`)
- Text-to-speech → Edge-TTS service: uses cloud voices (evidence: `README.md`)
- STT server → Caption display: streams captions (evidence: `README.md`)
- Operator → Corrections and staging: reviews captions (evidence: `README.md`)
- STT server → Service phase analysis: detects service phases (evidence: `README.md`)
- Service phase analysis → Sermon summaries: provides sermon blocks (evidence: `stt/sermon_summary.py`)
- STT server → Session database: records session (evidence: `README.md`)
- Operator → Backup file manager: manages backups (evidence: `README.md`)
- Backup file manager → SMB/NAS share: delivers backups (evidence: `README.md`)
- Operator → Model manager: manages models (evidence: `README.md`)
- Model manager → Hugging Face: downloads models (evidence: `README.md`)
- Watchdog → Managed STT process: starts and restarts (evidence: `stt/watchdog.py`)