# oldgeorsk/canto-transcription architecture

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

- Interactive diagram: https://gitdiagram.com/oldgeorsk/canto-transcription
- Repository: https://github.com/oldgeorsk/canto-transcription

## Overview

This repository is a Cantonese interview transcription tool with an optional, independent speech-detection step. Its principal workflow takes interview audio through WhisperX transcription, optionally adds speaker diarization, and produces a timestamped raw transcript; researchers can then use an external AI platform and the supplied guide to create normalized written Chinese. VAD creates speech reports and optional clips but does not feed the transcription script. The README documents several integrations and output behaviors; sampled source excerpts show model use and parameter handling, but not every orchestration detail.

Main entry points: [`transcribe.py`](https://github.com/oldgeorsk/canto-transcription/blob/main/transcribe.py) (Transcription Runner), [`vad.py`](https://github.com/oldgeorsk/canto-transcription/blob/main/vad.py) (VAD Runner), [`vad_config.json`](https://github.com/oldgeorsk/canto-transcription/blob/main/vad_config.json) (VAD Settings), [`transcribe_config_whisperx.json`](https://github.com/oldgeorsk/canto-transcription/blob/main/transcribe_config_whisperx.json) (WhisperX Settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_vad["Optional VAD"]
  node_vad_runner["VAD Runner<br/>[vad.py]"]
  node_vad_config["VAD Settings<br/>[vad_config.json]"]
  node_silero["Silero VAD"]
  node_vad_report["Speech Report"]
  node_speech_clips["Speech Clips"]
end

subgraph group_transcription["Raw Transcription"]
  node_transcribe_runner["Transcription Runner<br/>[transcribe.py]"]
  node_whisperx_config["WhisperX Settings"]
  node_whisperx["WhisperX ASR"]
  node_pyannote["Speaker Diarization"]
  node_hf_token["HuggingFace Token"]
  node_raw_transcript["Raw Transcript"]
end

subgraph group_normalization["Text Normalization"]
  node_normalization_guide["Cantonese Writing Guide"]
  node_normalized_text["Normalized Text"]
end

node_researcher(("Researcher"))
node_audio["Interview Audio"]
node_ai_platform["AI Platform"]

node_researcher -->|"provides"| node_audio
node_researcher -->|"runs optionally"| node_vad_runner
node_audio -->|"analyzes"| node_vad_runner
node_vad_config -->|"configures"| node_vad_runner
node_vad_runner -->|"detects speech"| node_silero
node_vad_runner -->|"writes report"| node_vad_report
node_vad_runner -->|"writes clips"| node_speech_clips
node_researcher -->|"runs"| node_transcribe_runner
node_audio -->|"transcribes"| node_transcribe_runner
node_whisperx_config -->|"configures"| node_transcribe_runner
node_transcribe_runner -->|"runs ASR"| node_whisperx
node_transcribe_runner -->|"diarizes optionally"| node_pyannote
node_hf_token -->|"authorizes"| node_transcribe_runner
node_transcribe_runner -->|"writes transcript"| node_raw_transcript
node_researcher -->|"requests normalization"| node_ai_platform
node_raw_transcript -->|"provides text"| node_ai_platform
node_normalization_guide -->|"guides conversion"| node_ai_platform
node_ai_platform -->|"produces text"| node_normalized_text

click node_vad_runner "https://github.com/oldgeorsk/canto-transcription/blob/main/vad.py"
click node_vad_config "https://github.com/oldgeorsk/canto-transcription/blob/main/vad_config.json"
click node_transcribe_runner "https://github.com/oldgeorsk/canto-transcription/blob/main/transcribe.py"
click node_whisperx_config "https://github.com/oldgeorsk/canto-transcription/blob/main/transcribe_config_whisperx.json"
click node_normalization_guide "https://github.com/oldgeorsk/canto-transcription/blob/main/skills/spoken-to-written-Canto.md"

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_vad_runner,node_vad_config,node_silero,node_vad_report,node_speech_clips,node_audio toneBlue
class node_transcribe_runner,node_whisperx_config,node_whisperx,node_pyannote,node_hf_token,node_raw_transcript toneAmber
class node_normalization_guide,node_normalized_text toneMint
class node_researcher,node_ai_platform toneIndigo
```

## Components

### Optional VAD

- [VAD Runner](https://github.com/oldgeorsk/canto-transcription/blob/main/vad.py): `vad.py`
- [VAD Settings](https://github.com/oldgeorsk/canto-transcription/blob/main/vad_config.json): `vad_config.json`
- **Silero VAD**
- **Speech Report**
- **Speech Clips**

### Raw Transcription

- [Transcription Runner](https://github.com/oldgeorsk/canto-transcription/blob/main/transcribe.py): `transcribe.py`
- [WhisperX Settings](https://github.com/oldgeorsk/canto-transcription/blob/main/transcribe_config_whisperx.json): `transcribe_config_whisperx.json`
- **WhisperX ASR**
- **Speaker Diarization**
- **HuggingFace Token**
- **Raw Transcript**

### Text Normalization

- [Cantonese Writing Guide](https://github.com/oldgeorsk/canto-transcription/blob/main/skills/spoken-to-written-Canto.md): `skills/spoken-to-written-Canto.md`
- **Normalized Text**

### Other components

- **Researcher**
- **Interview Audio**
- **AI Platform**

## Connections

- Researcher → Interview Audio: provides (evidence: `README.md`)
- Researcher → VAD Runner: runs optionally (evidence: `README.md`)
- Interview Audio → VAD Runner: analyzes (evidence: `README.md`)
- VAD Settings → VAD Runner: configures (evidence: `README.md`)
- VAD Runner → Silero VAD: detects speech (evidence: `vad.py`)
- VAD Runner → Speech Report: writes report (evidence: `README.md`)
- VAD Runner → Speech Clips: writes clips (evidence: `README.md`)
- Researcher → Transcription Runner: runs (evidence: `README.md`)
- Interview Audio → Transcription Runner: transcribes (evidence: `README.md`)
- WhisperX Settings → Transcription Runner: configures (evidence: `README.md`)
- Transcription Runner → WhisperX ASR: runs ASR (evidence: `transcribe.py`)
- Transcription Runner → Speaker Diarization: diarizes optionally (evidence: `README.md`)
- HuggingFace Token → Transcription Runner: authorizes (evidence: `README.md`)
- Transcription Runner → Raw Transcript: writes transcript (evidence: `README.md`)
- Researcher → AI Platform: requests normalization (evidence: `README.md`)
- Raw Transcript → AI Platform: provides text (evidence: `README.md`)
- Cantonese Writing Guide → AI Platform: guides conversion (evidence: `README.md`)
- AI Platform → Normalized Text: produces text (evidence: `README.md`)
