# blobbyblo/cqam-transcription architecture

> Architecture diagram of the GitHub repository blobbyblo/cqam-transcription, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/blobbyblo/cqam-transcription
- Repository: https://github.com/blobbyblo/cqam-transcription

## Overview

##### Three Main Zones
- Zone 1: External Dependencies
- FFmpeg (audio codec/format conversions)
- Hugging Face Hub / Whisper models
- Pyannote speaker‐diarization models
- Local file system for input/output storage
- Zone 2: Processing Pipeline
- Audio Preprocessing (utils/audio_utils.py)
- Speaker Diarization (diarization/diarize.py)
- Transcript Generation (transcription/whisper.py)
- (Optional) Manual Correction module
- Zone 3: UI Layer
- Tkinter GUI (gui/app.py)
- Pygame audio playback component
- Main entrypoint (main.py)

##### Components & Interactions
- FFmpeg: called by Audio Preprocessing for format conversion
- Whisper models: fetched from HF Hub, loaded by transcription module
- Pyannote models: loaded by diarization module
- Local FS: project root, .env for HF token, input/output folders
- Audio Preprocessor
– Inputs: raw .wav/.mp3 → normalizes, resamples → outputs cleaned audio
- Diarization
– Inputs: cleaned audio → assigns speaker segments → outputs time-stamped speakers
- Transcription
– Inputs: cleaned audio (+ speaker segments) → outputs text with speaker labels
- Correction (if used)
– Inputs: transcript → user edits → outputs final transcript
- Tkinter App
– File browse controls, start/pause buttons, volume slider
– Loads pipeline via subprocess or direct imports
- Pygame Audio Engine
– Handles playback, reports current time to GUI
– Signals UI to highlight transcript segments in sync

##### Simplification
- Omit test folders, setup scripts, and low-level utility internals.
- Do not show every file; aggregate by function (e.g., “Audio Preprocessing” rather than individual helper files).
- Focus only on how audio/data flows and which external systems are involved.

- The three logical layers you requested
- All major external tools and services
- The sequence of processing steps
- The UI interactions for playback and transcript display

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    subgraph "External Dependencies"
        FFmpeg["FFmpeg"]:::external
        HF["Hugging Face Hub / Whisper Models"]:::external
        Pyannote["Pyannote Models"]:::external
        LocalFS["Local File System"]:::external
        Env["Environment Configuration (.env)"]:::external
    end

    %% Processing Pipeline
    subgraph "Processing Pipeline"
        Preproc["Audio Preprocessing"]:::pipeline
        Diarize["Speaker Diarization"]:::pipeline
        Transcribe["Transcript Generation (Whisper)"]:::pipeline
        Correct["Manual Correction"]:::pipeline
        CUDA["CUDA Utility"]:::pipeline
    end

    %% UI Layer
    subgraph "UI Layer"
        Main["Main Entrypoint"]:::ui
        GUI["Tkinter GUI"]:::ui
        AudioEngine["Pygame Audio Playback"]:::ui
    end

    %% Data Flow
    FFmpeg -->|format conversion| Preproc
    LocalFS -->|input audio| Preproc
    Env -->|HF token| HF
    HF -->|model load| Transcribe
    Pyannote -->|model load| Diarize
    CUDA -->|device management| Diarize
    CUDA -->|device management| Transcribe

    Preproc -->|cleaned audio| Diarize
    Diarize -->|speaker segments| Transcribe
    Transcribe -->|raw transcript| Correct
    Correct -->|final transcript| GUI

    Main -->|start app| GUI
    GUI -->|playback| AudioEngine
    AudioEngine -->|time updates| GUI

    %% Connections from final pipeline to UI
    Transcribe -->|render transcript| GUI

    %% Click Events
    click Preproc "https://github.com/blobbyblo/cqam-transcription/blob/main/utils/audio_utils.py"
    click Diarize "https://github.com/blobbyblo/cqam-transcription/blob/main/diarization/diarize.py"
    click Transcribe "https://github.com/blobbyblo/cqam-transcription/blob/main/transcription/whisper.py"
    click Correct "https://github.com/blobbyblo/cqam-transcription/tree/main/correction/"
    click GUI "https://github.com/blobbyblo/cqam-transcription/blob/main/gui/app.py"
    click AudioEngine "https://github.com/blobbyblo/cqam-transcription/blob/main/gui/app.py"
    click Main "https://github.com/blobbyblo/cqam-transcription/blob/main/main.py"
    click CUDA "https://github.com/blobbyblo/cqam-transcription/blob/main/utils/cuda_utils.py"
    click LocalFS "https://github.com/blobbyblo/cqam-transcription/blob/main/examples/filler.wav"
    click Env "https://github.com/blobbyblo/cqam-transcription/tree/main/dotenv"

    %% Styles
    classDef external fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef pipeline fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef ui fill:#d4edda,stroke:#155724,stroke-width:2px;
```
