# kb-labb/easytranscriber architecture

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

- Interactive diagram: https://gitdiagram.com/kb-labb/easytranscriber
- Repository: https://github.com/kb-labb/easytranscriber

## Overview

easytranscriber turns audio and optional metadata into transcriptions with word-level timestamps, using configurable ASR backends and GPU-accelerated forced alignment. Its built-in easysearch indexes transcription chunks or alignments in SQLite and provides a browser interface for querying transcripts and playing audio. The pipeline and search entry-point excerpts are partial; the README documents alignment and search capabilities, while some internal wiring is not shown, so those relationships are omitted when unsupported.

Main entry points: [`src/easytranscriber/pipelines.py`](https://github.com/kb-labb/easytranscriber/blob/main/src/easytranscriber/pipelines.py) (Pipeline), [`src/easytranscriber/search/app.py`](https://github.com/kb-labb/easytranscriber/blob/main/src/easytranscriber/search/app.py) (Search web app), [`src/easytranscriber/data/datamodel.py`](https://github.com/kb-labb/easytranscriber/blob/main/src/easytranscriber/data/datamodel.py) (Transcript outputs), [`src/easytranscriber/asr/ct2.py`](https://github.com/kb-labb/easytranscriber/blob/main/src/easytranscriber/asr/ct2.py) (CTranslate2 ASR)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_transcribe["Transcription pipeline"]
  node_pipeline["Pipeline<br/>[pipelines.py]"]
  node_vad["Voice detection<br/>[pipelines.py]"]
  node_ct2["CTranslate2 ASR<br/>[ct2.py]"]
  node_hf["Hugging Face ASR<br/>[hf.py]"]
  node_cohere["Cohere ASR<br/>[cohere.py]"]
end

subgraph group_audio_data["Audio and data"]
  node_audio_reader["Audio reader<br/>[audio.py]"]
  node_dataset["Audio datasets<br/>[dataset.py]"]
  node_collators["Batch collators<br/>[collators.py]"]
  node_data_model["Speech data model<br/>[datamodel.py]"]
end

subgraph group_search["Transcript search"]
  node_search_cli["easysearch command<br/>[__main__.py]"]
  node_indexer["Transcript indexer<br/>[indexer.py]"]
  node_sqlite[("SQLite search index<br/>[db.py]")]
  node_web_app["Search web app<br/>[app.py]"]
  node_web_ui["Search interface"]
end

subgraph group_align_text["Alignment and text"]
  node_normalizer["Text normalization<br/>[normalization.py]"]
  node_alignment["Forced alignment<br/>[pipelines.py]"]
  node_transcripts["Transcript outputs<br/>[datamodel.py]"]
end

node_user(("Audio user"))
node_audio_files["Audio files"]
node_search_user(("Search user"))
node_audio_service["Audio playback files"]

node_user -->|"submits audio"| node_pipeline
node_audio_files -->|"provides input"| node_pipeline
node_pipeline -->|"runs detection"| node_vad
node_pipeline -->|"loads chunks"| node_dataset
node_dataset -->|"reads segments"| node_audio_reader
node_dataset -->|"uses metadata"| node_data_model
node_pipeline -->|"dispatches ASR"| node_ct2
node_pipeline -->|"dispatches ASR"| node_hf
node_pipeline -->|"dispatches ASR"| node_cohere
node_ct2 -->|"batches features"| node_collators
node_hf -->|"batches features"| node_collators
node_cohere -->|"batches audio"| node_collators
node_pipeline -->|"configures normalization"| node_normalizer
node_pipeline -->|"performs alignment"| node_alignment
node_alignment -->|"produces timestamps"| node_transcripts
node_ct2 -->|"saves transcription"| node_transcripts
node_hf -->|"saves transcription"| node_transcripts
node_cohere -->|"saves transcription"| node_transcripts
node_search_user -->|"starts search"| node_search_cli
node_search_cli -->|"indexes files"| node_indexer
node_indexer -->|"writes index"| node_sqlite
node_search_cli -->|"starts server"| node_web_app
node_web_app -->|"queries index"| node_sqlite
node_web_app -->|"renders pages"| node_web_ui
node_web_app -->|"serves audio"| node_audio_service

click node_pipeline "https://github.com/kb-labb/easytranscriber/blob/main/src/easytranscriber/pipelines.py"
click node_vad "https://github.com/kb-labb/easytranscriber/blob/main/src/easytranscriber/pipelines.py"
click node_ct2 "https://github.com/kb-labb/easytranscriber/blob/main/src/easytranscriber/asr/ct2.py"
click node_hf "https://github.com/kb-labb/easytranscriber/blob/main/src/easytranscriber/asr/hf.py"
click node_cohere "https://github.com/kb-labb/easytranscriber/blob/main/src/easytranscriber/asr/cohere.py"
click node_audio_reader "https://github.com/kb-labb/easytranscriber/blob/main/src/easytranscriber/audio.py"
click node_dataset "https://github.com/kb-labb/easytranscriber/blob/main/src/easytranscriber/data/dataset.py"
click node_collators "https://github.com/kb-labb/easytranscriber/blob/main/src/easytranscriber/data/collators.py"
click node_data_model "https://github.com/kb-labb/easytranscriber/blob/main/src/easytranscriber/data/datamodel.py"
click node_normalizer "https://github.com/kb-labb/easytranscriber/blob/main/src/easytranscriber/text/normalization.py"
click node_alignment "https://github.com/kb-labb/easytranscriber/blob/main/src/easytranscriber/pipelines.py"
click node_transcripts "https://github.com/kb-labb/easytranscriber/blob/main/src/easytranscriber/data/datamodel.py"
click node_search_cli "https://github.com/kb-labb/easytranscriber/blob/main/src/easytranscriber/search/__main__.py"
click node_indexer "https://github.com/kb-labb/easytranscriber/blob/main/src/easytranscriber/search/indexer.py"
click node_sqlite "https://github.com/kb-labb/easytranscriber/blob/main/src/easytranscriber/search/db.py"
click node_web_app "https://github.com/kb-labb/easytranscriber/blob/main/src/easytranscriber/search/app.py"
click node_web_ui "https://github.com/kb-labb/easytranscriber/tree/main/src/easytranscriber/search/templates"

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_pipeline,node_vad,node_ct2,node_hf,node_cohere,node_user,node_search_user toneBlue
class node_audio_reader,node_dataset,node_collators,node_data_model toneAmber
class node_search_cli,node_indexer,node_sqlite,node_web_app,node_web_ui toneMint
class node_normalizer,node_alignment,node_transcripts toneRose
class node_audio_files,node_audio_service toneIndigo
```

## Components

### Transcription pipeline

- [Pipeline](https://github.com/kb-labb/easytranscriber/blob/main/src/easytranscriber/pipelines.py): `src/easytranscriber/pipelines.py`
- [Voice detection](https://github.com/kb-labb/easytranscriber/blob/main/src/easytranscriber/pipelines.py): `src/easytranscriber/pipelines.py`
- [CTranslate2 ASR](https://github.com/kb-labb/easytranscriber/blob/main/src/easytranscriber/asr/ct2.py): `src/easytranscriber/asr/ct2.py`
- [Hugging Face ASR](https://github.com/kb-labb/easytranscriber/blob/main/src/easytranscriber/asr/hf.py): `src/easytranscriber/asr/hf.py`
- [Cohere ASR](https://github.com/kb-labb/easytranscriber/blob/main/src/easytranscriber/asr/cohere.py): `src/easytranscriber/asr/cohere.py`

### Audio and data

- [Audio reader](https://github.com/kb-labb/easytranscriber/blob/main/src/easytranscriber/audio.py): `src/easytranscriber/audio.py`
- [Audio datasets](https://github.com/kb-labb/easytranscriber/blob/main/src/easytranscriber/data/dataset.py): `src/easytranscriber/data/dataset.py`
- [Batch collators](https://github.com/kb-labb/easytranscriber/blob/main/src/easytranscriber/data/collators.py): `src/easytranscriber/data/collators.py`
- [Speech data model](https://github.com/kb-labb/easytranscriber/blob/main/src/easytranscriber/data/datamodel.py): `src/easytranscriber/data/datamodel.py`

### Transcript search

- [easysearch command](https://github.com/kb-labb/easytranscriber/blob/main/src/easytranscriber/search/__main__.py): `src/easytranscriber/search/__main__.py`
- [Transcript indexer](https://github.com/kb-labb/easytranscriber/blob/main/src/easytranscriber/search/indexer.py): `src/easytranscriber/search/indexer.py`
- [SQLite search index](https://github.com/kb-labb/easytranscriber/blob/main/src/easytranscriber/search/db.py): `src/easytranscriber/search/db.py`
- [Search web app](https://github.com/kb-labb/easytranscriber/blob/main/src/easytranscriber/search/app.py): `src/easytranscriber/search/app.py`
- [Search interface](https://github.com/kb-labb/easytranscriber/tree/main/src/easytranscriber/search/templates): `src/easytranscriber/search/templates`

### Alignment and text

- [Text normalization](https://github.com/kb-labb/easytranscriber/blob/main/src/easytranscriber/text/normalization.py): `src/easytranscriber/text/normalization.py`
- [Forced alignment](https://github.com/kb-labb/easytranscriber/blob/main/src/easytranscriber/pipelines.py): `src/easytranscriber/pipelines.py`
- [Transcript outputs](https://github.com/kb-labb/easytranscriber/blob/main/src/easytranscriber/data/datamodel.py): `src/easytranscriber/data/datamodel.py`

### Other components

- **Audio user**
- **Audio files**
- **Search user**
- **Audio playback files**

## Connections

- Audio user → Pipeline: submits audio (evidence: `README.md`)
- Audio files → Pipeline: provides input (evidence: `README.md`)
- Pipeline → Voice detection: runs detection (evidence: `src/easytranscriber/pipelines.py`)
- Pipeline → Audio datasets: loads chunks (evidence: `src/easytranscriber/pipelines.py`)
- Audio datasets → Audio reader: reads segments (evidence: `src/easytranscriber/data/dataset.py`)
- Audio datasets → Speech data model: uses metadata (evidence: `src/easytranscriber/data/dataset.py`)
- Pipeline → CTranslate2 ASR: dispatches ASR (evidence: `src/easytranscriber/pipelines.py`)
- Pipeline → Hugging Face ASR: dispatches ASR (evidence: `src/easytranscriber/pipelines.py`)
- Pipeline → Cohere ASR: dispatches ASR (evidence: `src/easytranscriber/pipelines.py`)
- CTranslate2 ASR → Batch collators: batches features (evidence: `src/easytranscriber/asr/ct2.py`)
- Hugging Face ASR → Batch collators: batches features (evidence: `src/easytranscriber/asr/hf.py`)
- Cohere ASR → Batch collators: batches audio (evidence: `src/easytranscriber/asr/cohere.py`)
- Pipeline → Text normalization: configures normalization (evidence: `src/easytranscriber/pipelines.py`)
- Pipeline → Forced alignment: performs alignment (evidence: `README.md`)
- Forced alignment → Transcript outputs: produces timestamps (evidence: `README.md`)
- CTranslate2 ASR → Transcript outputs: saves transcription (evidence: `src/easytranscriber/asr/ct2.py`)
- Hugging Face ASR → Transcript outputs: saves transcription (evidence: `src/easytranscriber/asr/hf.py`)
- Cohere ASR → Transcript outputs: saves transcription (evidence: `src/easytranscriber/asr/cohere.py`)
- Search user → easysearch command: starts search (evidence: `README.md`)
- easysearch command → Transcript indexer: indexes files (evidence: `src/easytranscriber/search/__main__.py`)
- Transcript indexer → SQLite search index: writes index (evidence: `src/easytranscriber/search/indexer.py`)
- easysearch command → Search web app: starts server (evidence: `src/easytranscriber/search/__main__.py`)
- Search web app → SQLite search index: queries index (evidence: `src/easytranscriber/search/app.py`)
- Search web app → Search interface: renders pages (evidence: `src/easytranscriber/search/app.py`)
- Search web app → Audio playback files: serves audio (evidence: `src/easytranscriber/search/app.py`)
