# dan3oft/zhtext architecture

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

- Interactive diagram: https://gitdiagram.com/dan3oft/zhtext
- Repository: https://github.com/dan3oft/zhtext

## Overview

zhtext is an offline-first Mandarin study tool: a learner supplies links or local media, the CLI obtains audio and captions, uses captions or speech recognition to produce Chinese segments, adds pinyin and optional translation, then displays and saves the results. The graph preserves separate source-handling, transcription, language-enrichment, and presentation stages. Source excerpts show the main calls and integrations; other relationships are included only where the README documents them.

Main entry points: [`zhtext/cli.py`](https://github.com/dan3oft/zhtext/blob/main/zhtext/cli.py) (CLI workflow), [`zhtext/download.py`](https://github.com/dan3oft/zhtext/blob/main/zhtext/download.py) (Generic media fetch), [`zhtext/transcribe.py`](https://github.com/dan3oft/zhtext/blob/main/zhtext/transcribe.py) (Whisper transcription), [`zhtext/translate.py`](https://github.com/dan3oft/zhtext/blob/main/zhtext/translate.py) (Translation workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Media input"]
  node_source_resolver["Source resolver<br/>[download.py]"]
  node_generic_fetch["Generic media fetch<br/>[download.py]"]
  node_kaltura_fetch["Kaltura fetch<br/>[download.py]"]
  node_audio_extract["Audio extraction<br/>[download.py]"]
  node_caption_parser["Caption parsing<br/>[download.py]"]
  node_audio["Audio file"]
  node_captions["Caption segments"]
end

subgraph group_transcription["Chinese transcription"]
  node_transcriber["Whisper transcription<br/>[transcribe.py]"]
  node_segments["Chinese segments<br/>[download.py]"]
end

subgraph group_language["Language enrichment"]
  node_pinyin["Pinyin conversion<br/>[translate.py]"]
  node_translator["Translation workflow<br/>[translate.py]"]
  node_argos_models["Argos models<br/>[translate.py]"]
  node_model_index[("Model index and cache<br/>[translate.py]")]
end

subgraph group_presentation["Results"]
  node_cli["CLI workflow<br/>[cli.py]"]
  node_display["Terminal display<br/>[cli.py]"]
  node_saved_files["Transcript and subtitles<br/>[cli.py]"]
end

node_learner(("Learner"))
node_media_services{{"Media services"}}
node_local_media["Local media"]
node_whisper{{"faster-whisper"}}
node_argos_service{{"Argos model index"}}

node_learner -->|"supplies sources"| node_cli
node_cli -->|"fetches links"| node_source_resolver
node_source_resolver -->|"routes Kaltura"| node_kaltura_fetch
node_source_resolver -->|"routes others"| node_generic_fetch
node_kaltura_fetch -->|"requests media"| node_media_services
node_generic_fetch -->|"downloads media"| node_media_services
node_kaltura_fetch -->|"extracts audio"| node_audio_extract
node_generic_fetch -->|"produces audio"| node_audio
node_audio_extract -->|"produces audio"| node_audio
node_kaltura_fetch -->|"parses captions"| node_caption_parser
node_generic_fetch -->|"parses subtitles"| node_caption_parser
node_caption_parser -->|"returns segments"| node_captions
node_cli -->|"transcribes audio"| node_transcriber
node_transcriber -->|"runs recognition"| node_whisper
node_transcriber -->|"reads audio"| node_audio
node_transcriber -->|"returns segments"| node_segments
node_cli -->|"uses when available"| node_captions
node_cli -->|"converts text"| node_pinyin
node_cli -->|"translates segments"| node_translator
node_translator -->|"loads packages"| node_model_index
node_model_index -->|"fetches index"| node_argos_service
node_translator -->|"runs translation"| node_argos_models
node_argos_models -->|"loads cached models"| node_model_index
node_cli -->|"prints results"| node_display
node_cli -->|"writes TXT and SRT"| node_saved_files

click node_cli "https://github.com/dan3oft/zhtext/blob/main/zhtext/cli.py"
click node_source_resolver "https://github.com/dan3oft/zhtext/blob/main/zhtext/download.py"
click node_generic_fetch "https://github.com/dan3oft/zhtext/blob/main/zhtext/download.py"
click node_kaltura_fetch "https://github.com/dan3oft/zhtext/blob/main/zhtext/download.py"
click node_audio_extract "https://github.com/dan3oft/zhtext/blob/main/zhtext/download.py"
click node_caption_parser "https://github.com/dan3oft/zhtext/blob/main/zhtext/download.py"
click node_transcriber "https://github.com/dan3oft/zhtext/blob/main/zhtext/transcribe.py"
click node_segments "https://github.com/dan3oft/zhtext/blob/main/zhtext/download.py"
click node_pinyin "https://github.com/dan3oft/zhtext/blob/main/zhtext/translate.py"
click node_translator "https://github.com/dan3oft/zhtext/blob/main/zhtext/translate.py"
click node_argos_models "https://github.com/dan3oft/zhtext/blob/main/zhtext/translate.py"
click node_model_index "https://github.com/dan3oft/zhtext/blob/main/zhtext/translate.py"
click node_display "https://github.com/dan3oft/zhtext/blob/main/zhtext/cli.py"
click node_saved_files "https://github.com/dan3oft/zhtext/blob/main/zhtext/cli.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_source_resolver,node_generic_fetch,node_kaltura_fetch,node_audio_extract,node_caption_parser,node_audio,node_captions toneBlue
class node_transcriber,node_segments toneAmber
class node_pinyin,node_translator,node_argos_models,node_model_index toneMint
class node_cli,node_display,node_saved_files toneRose
class node_learner,node_media_services,node_local_media,node_whisper,node_argos_service toneIndigo
```

## Components

### Media input

- [Source resolver](https://github.com/dan3oft/zhtext/blob/main/zhtext/download.py): `zhtext/download.py`
- [Generic media fetch](https://github.com/dan3oft/zhtext/blob/main/zhtext/download.py): `zhtext/download.py`
- [Kaltura fetch](https://github.com/dan3oft/zhtext/blob/main/zhtext/download.py): `zhtext/download.py`
- [Audio extraction](https://github.com/dan3oft/zhtext/blob/main/zhtext/download.py): `zhtext/download.py`
- [Caption parsing](https://github.com/dan3oft/zhtext/blob/main/zhtext/download.py): `zhtext/download.py`
- **Audio file**
- **Caption segments**

### Chinese transcription

- [Whisper transcription](https://github.com/dan3oft/zhtext/blob/main/zhtext/transcribe.py): `zhtext/transcribe.py`
- [Chinese segments](https://github.com/dan3oft/zhtext/blob/main/zhtext/download.py): `zhtext/download.py`

### Language enrichment

- [Pinyin conversion](https://github.com/dan3oft/zhtext/blob/main/zhtext/translate.py): `zhtext/translate.py`
- [Translation workflow](https://github.com/dan3oft/zhtext/blob/main/zhtext/translate.py): `zhtext/translate.py`
- [Argos models](https://github.com/dan3oft/zhtext/blob/main/zhtext/translate.py): `zhtext/translate.py`
- [Model index and cache](https://github.com/dan3oft/zhtext/blob/main/zhtext/translate.py): `zhtext/translate.py`

### Results

- [CLI workflow](https://github.com/dan3oft/zhtext/blob/main/zhtext/cli.py): `zhtext/cli.py`
- [Terminal display](https://github.com/dan3oft/zhtext/blob/main/zhtext/cli.py): `zhtext/cli.py`
- [Transcript and subtitles](https://github.com/dan3oft/zhtext/blob/main/zhtext/cli.py): `zhtext/cli.py`

### Other components

- **Learner**
- **Media services**
- **Local media**
- **faster-whisper**
- **Argos model index**

## Connections

- Learner → CLI workflow: supplies sources (evidence: `README.md`)
- CLI workflow → Source resolver: fetches links (evidence: `zhtext/cli.py`)
- Source resolver → Kaltura fetch: routes Kaltura (evidence: `zhtext/download.py`)
- Source resolver → Generic media fetch: routes others (evidence: `zhtext/download.py`)
- Kaltura fetch → Media services: requests media (evidence: `zhtext/download.py`)
- Generic media fetch → Media services: downloads media (evidence: `zhtext/download.py`)
- Kaltura fetch → Audio extraction: extracts audio (evidence: `zhtext/download.py`)
- Generic media fetch → Audio file: produces audio (evidence: `zhtext/download.py`)
- Audio extraction → Audio file: produces audio (evidence: `zhtext/download.py`)
- Kaltura fetch → Caption parsing: parses captions (evidence: `zhtext/download.py`)
- Generic media fetch → Caption parsing: parses subtitles (evidence: `zhtext/download.py`)
- Caption parsing → Caption segments: returns segments (evidence: `zhtext/download.py`)
- CLI workflow → Whisper transcription: transcribes audio (evidence: `zhtext/cli.py`)
- Whisper transcription → faster-whisper: runs recognition (evidence: `zhtext/transcribe.py`)
- Whisper transcription → Audio file: reads audio (evidence: `zhtext/transcribe.py`)
- Whisper transcription → Chinese segments: returns segments (evidence: `zhtext/transcribe.py`)
- CLI workflow → Caption segments: uses when available (evidence: `zhtext/cli.py`)
- CLI workflow → Pinyin conversion: converts text (evidence: `zhtext/cli.py`)
- CLI workflow → Translation workflow: translates segments (evidence: `zhtext/cli.py`)
- Translation workflow → Model index and cache: loads packages (evidence: `zhtext/translate.py`)
- Model index and cache → Argos model index: fetches index (evidence: `zhtext/translate.py`)
- Translation workflow → Argos models: runs translation (evidence: `zhtext/translate.py`)
- Argos models → Model index and cache: loads cached models (evidence: `zhtext/translate.py`)
- CLI workflow → Terminal display: prints results (evidence: `zhtext/cli.py`)
- CLI workflow → Transcript and subtitles: writes TXT and SRT (evidence: `zhtext/cli.py`)
