# kb-labb/easyaligner architecture

> Architecture diagram of the GitHub repository kb-labb/easyaligner, 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/kb-labb/easyaligner
- Repository: https://github.com/kb-labb/easyaligner

## Overview

easyaligner is a Python forced-alignment library: users provide audio, transcript segments, and an acoustic model; the pipeline detects speech regions, extracts model emissions, then aligns normalized transcript tokens to audio and writes timestamped results. Text normalization preserves links to the original transcript, while tokenization and fuzzy matching support flexible segmentation and transcript matching. The README documents separate stage outputs and both known- and unknown-region workflows. The graph reflects those documented stages and indexed module references; several internal calls and optional paths were not shown in the excerpts.

Main entry points: [`src/easyaligner/pipelines.py`](https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/pipelines.py) (Pipeline orchestration), [`src/easyaligner/alignment/pytorch.py`](https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/alignment/pytorch.py) (Forced alignment), [`src/easyaligner/data/datamodel.py`](https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/data/datamodel.py) (Speech data model), [`src/easyaligner/text/normalization.py`](https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/text/normalization.py) (Text normalization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Alignment workflow"]
  node_pipeline["Pipeline orchestration<br/>[pipelines.py]"]
  node_vadstage["VAD stage<br/>[pipelines.py]"]
  node_emissions["Emission extraction<br/>[pipelines.py]"]
  node_alignment["Forced alignment<br/>[pytorch.py]"]
  node_results["Alignment results<br/>[datamodel.py]"]
  node_alignmentutils["Alignment utilities<br/>[utils.py]"]
end

subgraph group_text["Text processing"]
  node_normalization["Text normalization<br/>[normalization.py]"]
  node_tokenizer["Text tokenization<br/>[tokenizer.py]"]
  node_swedish["Swedish rules<br/>[sv.py]"]
  node_matching["Fuzzy matching<br/>[match.py]"]
end

subgraph group_data["Audio and metadata"]
  node_datamodel["Speech data model<br/>[datamodel.py]"]
  node_dataset["Audio datasets<br/>[dataset.py]"]
  node_collators["Batch collators<br/>[collators.py]"]
  node_datautils["Audio data utilities<br/>[utils.py]"]
  node_storage["Stage file output<br/>[utils.py]"]
end

subgraph group_vad["Speech detection"]
  node_vadrouter["VAD selection<br/>[vad.py]"]
  node_pyannote["Pyannote VAD<br/>[pyannote.py]"]
  node_silero["Silero VAD<br/>[silero.py]"]
  node_vadutils["VAD utilities<br/>[utils.py]"]
end

node_user(("Library user"))
node_acoustic["CTC acoustic model"]
node_outputstore[("Output files")]

node_user -->|"runs"| node_pipeline
node_pipeline -->|"runs VAD"| node_vadstage
node_pipeline -->|"extracts emissions"| node_emissions
node_pipeline -->|"runs alignment"| node_alignment
node_vadstage -->|"records segments"| node_datamodel
node_emissions -->|"infers logits"| node_acoustic
node_alignment -->|"normalizes tokens"| node_normalization
node_alignment -->|"uses utilities"| node_alignmentutils
node_alignment -->|"reads metadata"| node_datamodel
node_alignment -->|"produces alignments"| node_results
node_normalization -->|"uses language rules"| node_swedish
node_matching -->|"uses normalization"| node_normalization
node_dataset -->|"loads metadata"| node_datamodel
node_pipeline -.->|"uses datasets"| node_dataset
node_pipeline -.->|"batches features"| node_collators
node_pipeline -->|"saves stage files"| node_storage
node_storage -->|"writes files"| node_outputstore
node_vadrouter -->|"selects backend"| node_pyannote
node_vadrouter -->|"selects backend"| node_silero
node_pyannote -->|"uses helpers"| node_vadutils
node_silero -->|"uses helpers"| node_vadutils
node_vadutils -->|"builds segments"| node_datamodel
node_tokenizer -.->|"segments transcript"| node_user

click node_pipeline "https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/pipelines.py"
click node_vadstage "https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/pipelines.py"
click node_emissions "https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/pipelines.py"
click node_alignment "https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/alignment/pytorch.py"
click node_results "https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/data/datamodel.py"
click node_normalization "https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/text/normalization.py"
click node_tokenizer "https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/text/tokenizer.py"
click node_swedish "https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/text/languages/sv.py"
click node_matching "https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/text/match.py"
click node_alignmentutils "https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/alignment/utils.py"
click node_datamodel "https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/data/datamodel.py"
click node_dataset "https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/data/dataset.py"
click node_collators "https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/data/collators.py"
click node_datautils "https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/data/utils.py"
click node_storage "https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/utils.py"
click node_vadrouter "https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/vad/vad.py"
click node_pyannote "https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/vad/pyannote.py"
click node_silero "https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/vad/silero.py"
click node_vadutils "https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/vad/utils.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_pipeline,node_vadstage,node_emissions,node_alignment,node_results,node_alignmentutils,node_user toneBlue
class node_normalization,node_tokenizer,node_swedish,node_matching,node_outputstore toneAmber
class node_datamodel,node_dataset,node_collators,node_datautils,node_storage toneMint
class node_vadrouter,node_pyannote,node_silero,node_vadutils toneRose
class node_acoustic toneIndigo
```

## Components

### Alignment workflow

- [Pipeline orchestration](https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/pipelines.py): `src/easyaligner/pipelines.py`
- [VAD stage](https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/pipelines.py): `src/easyaligner/pipelines.py`
- [Emission extraction](https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/pipelines.py): `src/easyaligner/pipelines.py`
- [Forced alignment](https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/alignment/pytorch.py): `src/easyaligner/alignment/pytorch.py`
- [Alignment results](https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/data/datamodel.py): `src/easyaligner/data/datamodel.py`
- [Alignment utilities](https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/alignment/utils.py): `src/easyaligner/alignment/utils.py`

### Text processing

- [Text normalization](https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/text/normalization.py): `src/easyaligner/text/normalization.py`
- [Text tokenization](https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/text/tokenizer.py): `src/easyaligner/text/tokenizer.py`
- [Swedish rules](https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/text/languages/sv.py): `src/easyaligner/text/languages/sv.py`
- [Fuzzy matching](https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/text/match.py): `src/easyaligner/text/match.py`

### Audio and metadata

- [Speech data model](https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/data/datamodel.py): `src/easyaligner/data/datamodel.py`
- [Audio datasets](https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/data/dataset.py): `src/easyaligner/data/dataset.py`
- [Batch collators](https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/data/collators.py): `src/easyaligner/data/collators.py`
- [Audio data utilities](https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/data/utils.py): `src/easyaligner/data/utils.py`
- [Stage file output](https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/utils.py): `src/easyaligner/utils.py`

### Speech detection

- [VAD selection](https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/vad/vad.py): `src/easyaligner/vad/vad.py`
- [Pyannote VAD](https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/vad/pyannote.py): `src/easyaligner/vad/pyannote.py`
- [Silero VAD](https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/vad/silero.py): `src/easyaligner/vad/silero.py`
- [VAD utilities](https://github.com/kb-labb/easyaligner/blob/main/src/easyaligner/vad/utils.py): `src/easyaligner/vad/utils.py`

### Other components

- **Library user**
- **CTC acoustic model**
- **Output files**

## Connections

- Library user → Pipeline orchestration: runs (evidence: `README.md`)
- Pipeline orchestration → VAD stage: runs VAD (evidence: `src/easyaligner/pipelines.py`)
- Pipeline orchestration → Emission extraction: extracts emissions (evidence: `README.md`)
- Pipeline orchestration → Forced alignment: runs alignment (evidence: `README.md`)
- VAD stage → Speech data model: records segments (evidence: `src/easyaligner/pipelines.py`)
- Emission extraction → CTC acoustic model: infers logits (evidence: `src/easyaligner/pipelines.py`)
- Forced alignment → Text normalization: normalizes tokens (evidence: `src/easyaligner/alignment/pytorch.py`)
- Forced alignment → Alignment utilities: uses utilities (evidence: `src/easyaligner/alignment/pytorch.py`)
- Forced alignment → Speech data model: reads metadata (evidence: `src/easyaligner/alignment/pytorch.py`)
- Forced alignment → Alignment results: produces alignments (evidence: `README.md`)
- Text normalization → Swedish rules: uses language rules (evidence: `src/easyaligner/text/normalization.py`)
- Fuzzy matching → Text normalization: uses normalization (evidence: `src/easyaligner/text/match.py`)
- Audio datasets → Speech data model: loads metadata (evidence: `src/easyaligner/data/dataset.py`)
- Pipeline orchestration → Audio datasets: uses datasets (evidence: `src/easyaligner/pipelines.py`)
- Pipeline orchestration → Batch collators: batches features (evidence: `src/easyaligner/pipelines.py`)
- Pipeline orchestration → Stage file output: saves stage files (evidence: `src/easyaligner/pipelines.py`)
- Stage file output → Output files: writes files (evidence: `src/easyaligner/utils.py`)
- VAD selection → Pyannote VAD: selects backend (evidence: `src/easyaligner/vad/vad.py`)
- VAD selection → Silero VAD: selects backend (evidence: `src/easyaligner/vad/vad.py`)
- Pyannote VAD → VAD utilities: uses helpers (evidence: `src/easyaligner/vad/pyannote.py`)
- Silero VAD → VAD utilities: uses helpers (evidence: `src/easyaligner/vad/silero.py`)
- VAD utilities → Speech data model: builds segments (evidence: `src/easyaligner/vad/utils.py`)
- Text tokenization → Library user: segments transcript
