# omar-abuhadhoud/transcriber architecture

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

- Interactive diagram: https://gitdiagram.com/omar-abuhadhoud/transcriber
- Repository: https://github.com/omar-abuhadhoud/transcriber

## Overview

Transcriber is a local-first Windows desktop app for downloading media audio and transcribing it on the user’s GPU. The main workflow is to add local files—or download audio from a supported link into the queue—then run queued items one at a time and use the resulting text. Recovery files preserve partial output; completed transcripts can be copied, saved, or opened with Arabic RTL formatting. The README also documents installation and update capabilities. Some runtime connections are supported only by README or source-index references, so uncertain links are omitted or marked dashed.

Main entry points: [`ctk_ui/queue_page.py`](https://github.com/omar-abuhadhoud/transcriber/blob/main/ctk_ui/queue_page.py) (Transcription queue), [`ctk_ui/download_page.py`](https://github.com/omar-abuhadhoud/transcriber/blob/main/ctk_ui/download_page.py) (Download page), [`ctk_ui/app.py`](https://github.com/omar-abuhadhoud/transcriber/blob/main/ctk_ui/app.py) (App shell), [`ctk_ui/media_item.py`](https://github.com/omar-abuhadhoud/transcriber/blob/main/ctk_ui/media_item.py) (Media row)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop experience"]
  node_app["App shell<br/>[app.py]"]
  node_queue["Transcription queue<br/>[queue_page.py]"]
  node_media["Media row<br/>[media_item.py]"]
  node_transcript_output["Transcript actions<br/>[media_item.py]"]
end

subgraph group_downloads["Media downloads"]
  node_download_ui["Download page<br/>[download_page.py]"]
  node_url_dialog["Link dialog<br/>[url_dialog.py]"]
  node_download_pool["Download pool<br/>[pool.py]"]
  node_provider_registry["Provider registry<br/>[registry.py]"]
  node_download_contract["Downloader contract<br/>[base.py]"]
  node_ytdlp["Audio fetch<br/>[ytdlp.py]"]
  node_naming["Safe naming<br/>[naming.py]"]
end

subgraph group_transcription["Transcription runtime"]
  node_transcribe_worker["Transcription worker"]
  node_engine_registry["Engine registry<br/>[registry.py]"]
  node_qwen["Qwen ASR<br/>[qwen_asr.py]"]
  node_audio["Audio handling<br/>[audio.py]"]
  node_vad["Speech segmentation<br/>[vad.py]"]
  node_chunk_log["Chunk logging<br/>[chunk_log.py]"]
end

subgraph group_localdata["Local state"]
  node_recovery[("Recovery files<br/>[global_vars.py]")]
  node_paths["Local paths<br/>[paths.py]"]
end

subgraph group_lifecycle["Install and updates"]
  node_installer["Runtime provisioning<br/>[provision.py]"]
  node_install_state[("Install state<br/>[install_state.py]")]
  node_updater["Update service<br/>[update.py]"]
end

node_user(("User"))
node_model_host(("Model downloads"))
node_release_host(("Release service"))

node_user -->|"uses"| node_app
node_app -->|"builds"| node_queue
node_app -->|"builds"| node_download_ui
node_user -->|"adds media"| node_queue
node_queue -->|"creates rows"| node_media
node_media -->|"requests work"| node_queue
node_queue -->|"dispatches jobs"| node_transcribe_worker
node_transcribe_worker -.->|"selects engine"| node_engine_registry
node_engine_registry -.->|"provides engine"| node_qwen
node_qwen -->|"processes audio"| node_audio
node_qwen -->|"segments speech"| node_vad
node_qwen -->|"records chunks"| node_chunk_log
node_media -->|"streams text"| node_recovery
node_media -->|"offers actions"| node_transcript_output
node_user -->|"pastes link"| node_download_ui
node_download_ui -->|"opens"| node_url_dialog
node_url_dialog -->|"submits job"| node_download_pool
node_download_pool -->|"resolves provider"| node_provider_registry
node_download_pool -->|"runs downloader"| node_download_contract
node_download_contract -->|"delegates fetching"| node_ytdlp
node_ytdlp -->|"names output"| node_naming
node_download_ui -->|"adds finished media"| node_queue
node_download_ui -->|"uses download paths"| node_paths
node_recovery -->|"locates data"| node_paths
node_installer -->|"records provisioning"| node_install_state
node_installer -->|"fetches weights"| node_model_host
node_app -->|"launches update"| node_updater
node_updater -->|"checks releases"| node_release_host
node_updater -->|"checks installation"| node_install_state

click node_app "https://github.com/omar-abuhadhoud/transcriber/blob/main/ctk_ui/app.py"
click node_queue "https://github.com/omar-abuhadhoud/transcriber/blob/main/ctk_ui/queue_page.py"
click node_media "https://github.com/omar-abuhadhoud/transcriber/blob/main/ctk_ui/media_item.py"
click node_transcript_output "https://github.com/omar-abuhadhoud/transcriber/blob/main/ctk_ui/media_item.py"
click node_download_ui "https://github.com/omar-abuhadhoud/transcriber/blob/main/ctk_ui/download_page.py"
click node_url_dialog "https://github.com/omar-abuhadhoud/transcriber/blob/main/ctk_ui/url_dialog.py"
click node_download_pool "https://github.com/omar-abuhadhoud/transcriber/blob/main/downloader/pool.py"
click node_provider_registry "https://github.com/omar-abuhadhoud/transcriber/blob/main/downloader/registry.py"
click node_download_contract "https://github.com/omar-abuhadhoud/transcriber/blob/main/downloader/base.py"
click node_ytdlp "https://github.com/omar-abuhadhoud/transcriber/blob/main/downloader/ytdlp.py"
click node_naming "https://github.com/omar-abuhadhoud/transcriber/blob/main/downloader/naming.py"
click node_transcribe_worker "https://github.com/omar-abuhadhoud/transcriber/blob/main/transcriber/transcribe_module.py"
click node_engine_registry "https://github.com/omar-abuhadhoud/transcriber/blob/main/transcriber/registry.py"
click node_qwen "https://github.com/omar-abuhadhoud/transcriber/blob/main/transcriber/engines/qwen_asr.py"
click node_audio "https://github.com/omar-abuhadhoud/transcriber/blob/main/transcriber/audio.py"
click node_vad "https://github.com/omar-abuhadhoud/transcriber/blob/main/transcriber/vad.py"
click node_chunk_log "https://github.com/omar-abuhadhoud/transcriber/blob/main/transcriber/chunk_log.py"
click node_recovery "https://github.com/omar-abuhadhoud/transcriber/blob/main/global_vars.py"
click node_paths "https://github.com/omar-abuhadhoud/transcriber/blob/main/transcriber/paths.py"
click node_installer "https://github.com/omar-abuhadhoud/transcriber/blob/main/installer/provision.py"
click node_install_state "https://github.com/omar-abuhadhoud/transcriber/blob/main/transcriber/install_state.py"
click node_updater "https://github.com/omar-abuhadhoud/transcriber/blob/main/transcriber/update.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_app,node_queue,node_media,node_transcript_output,node_user toneBlue
class node_download_ui,node_url_dialog,node_download_pool,node_provider_registry,node_download_contract,node_ytdlp,node_naming toneAmber
class node_transcribe_worker,node_engine_registry,node_qwen,node_audio,node_vad,node_chunk_log toneMint
class node_recovery,node_paths toneRose
class node_installer,node_install_state,node_updater,node_model_host,node_release_host toneIndigo
```

## Components

### Desktop experience

- [App shell](https://github.com/omar-abuhadhoud/transcriber/blob/main/ctk_ui/app.py): `ctk_ui/app.py`
- [Transcription queue](https://github.com/omar-abuhadhoud/transcriber/blob/main/ctk_ui/queue_page.py): `ctk_ui/queue_page.py`
- [Media row](https://github.com/omar-abuhadhoud/transcriber/blob/main/ctk_ui/media_item.py): `ctk_ui/media_item.py`
- [Transcript actions](https://github.com/omar-abuhadhoud/transcriber/blob/main/ctk_ui/media_item.py): `ctk_ui/media_item.py`

### Media downloads

- [Download page](https://github.com/omar-abuhadhoud/transcriber/blob/main/ctk_ui/download_page.py): `ctk_ui/download_page.py`
- [Link dialog](https://github.com/omar-abuhadhoud/transcriber/blob/main/ctk_ui/url_dialog.py): `ctk_ui/url_dialog.py`
- [Download pool](https://github.com/omar-abuhadhoud/transcriber/blob/main/downloader/pool.py): `downloader/pool.py`
- [Provider registry](https://github.com/omar-abuhadhoud/transcriber/blob/main/downloader/registry.py): `downloader/registry.py`
- [Downloader contract](https://github.com/omar-abuhadhoud/transcriber/blob/main/downloader/base.py): `downloader/base.py`
- [Audio fetch](https://github.com/omar-abuhadhoud/transcriber/blob/main/downloader/ytdlp.py): `downloader/ytdlp.py`
- [Safe naming](https://github.com/omar-abuhadhoud/transcriber/blob/main/downloader/naming.py): `downloader/naming.py`

### Transcription runtime

- [Transcription worker](https://github.com/omar-abuhadhoud/transcriber/blob/main/transcriber/transcribe_module.py): `transcriber/transcribe_module.py`
- [Engine registry](https://github.com/omar-abuhadhoud/transcriber/blob/main/transcriber/registry.py): `transcriber/registry.py`
- [Qwen ASR](https://github.com/omar-abuhadhoud/transcriber/blob/main/transcriber/engines/qwen_asr.py): `transcriber/engines/qwen_asr.py`
- [Audio handling](https://github.com/omar-abuhadhoud/transcriber/blob/main/transcriber/audio.py): `transcriber/audio.py`
- [Speech segmentation](https://github.com/omar-abuhadhoud/transcriber/blob/main/transcriber/vad.py): `transcriber/vad.py`
- [Chunk logging](https://github.com/omar-abuhadhoud/transcriber/blob/main/transcriber/chunk_log.py): `transcriber/chunk_log.py`

### Local state

- [Recovery files](https://github.com/omar-abuhadhoud/transcriber/blob/main/global_vars.py): `global_vars.py`
- [Local paths](https://github.com/omar-abuhadhoud/transcriber/blob/main/transcriber/paths.py): `transcriber/paths.py`

### Install and updates

- [Runtime provisioning](https://github.com/omar-abuhadhoud/transcriber/blob/main/installer/provision.py): `installer/provision.py`
- [Install state](https://github.com/omar-abuhadhoud/transcriber/blob/main/transcriber/install_state.py): `transcriber/install_state.py`
- [Update service](https://github.com/omar-abuhadhoud/transcriber/blob/main/transcriber/update.py): `transcriber/update.py`

### Other components

- **User**
- **Model downloads**
- **Release service**

## Connections

- User → App shell: uses
- App shell → Transcription queue: builds (evidence: `ctk_ui/app.py`)
- App shell → Download page: builds (evidence: `ctk_ui/app.py`)
- User → Transcription queue: adds media
- Transcription queue → Media row: creates rows (evidence: `ctk_ui/queue_page.py`)
- Media row → Transcription queue: requests work (evidence: `ctk_ui/media_item.py`)
- Transcription queue → Transcription worker: dispatches jobs (evidence: `ctk_ui/queue_page.py`)
- Transcription worker → Engine registry: selects engine
- Engine registry → Qwen ASR: provides engine
- Qwen ASR → Audio handling: processes audio (evidence: `transcriber/engines/qwen_asr.py`)
- Qwen ASR → Speech segmentation: segments speech (evidence: `transcriber/engines/qwen_asr.py`)
- Qwen ASR → Chunk logging: records chunks (evidence: `transcriber/engines/qwen_asr.py`)
- Media row → Recovery files: streams text (evidence: `ctk_ui/media_item.py`)
- Media row → Transcript actions: offers actions (evidence: `ctk_ui/media_item.py`)
- User → Download page: pastes link
- Download page → Link dialog: opens (evidence: `ctk_ui/download_page.py`)
- Link dialog → Download pool: submits job (evidence: `ctk_ui/download_page.py`)
- Download pool → Provider registry: resolves provider (evidence: `downloader/pool.py`)
- Download pool → Downloader contract: runs downloader (evidence: `downloader/pool.py`)
- Downloader contract → Audio fetch: delegates fetching (evidence: `downloader/providers/youtube.py`)
- Audio fetch → Safe naming: names output (evidence: `downloader/ytdlp.py`)
- Download page → Transcription queue: adds finished media (evidence: `ctk_ui/app.py`)
- Download page → Local paths: uses download paths (evidence: `ctk_ui/download_page.py`)
- Recovery files → Local paths: locates data (evidence: `global_vars.py`)
- Runtime provisioning → Install state: records provisioning (evidence: `installer/provision.py`)
- Runtime provisioning → Model downloads: fetches weights
- App shell → Update service: launches update (evidence: `ctk_ui/app.py`)
- Update service → Release service: checks releases
- Update service → Install state: checks installation (evidence: `transcriber/update.py`)
