# igmim-yassine/speech-training-recorder architecture

> Architecture diagram of the GitHub repository igmim-yassine/speech-training-recorder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/igmim-yassine/speech-training-recorder
- Repository: https://github.com/igmim-yassine/speech-training-recorder

## Overview

##### Project Type and Purpose
- This is a standalone, cross-platform desktop GUI application written in Python.
- Purpose: display randomized text prompts to the user, record dictated speech as WAV files, and log metadata in a TSV file.

##### File Structure
Top-level files and directories:
- recorder.py – main application entry point and controller logic
- audio.py – audio-capture and playback logic
- recorder.qml – GUI layout and bindings
- prompts/ – sample text prompt files
- requirements.txt – external Python library dependencies

##### README for Additional Insights
- External libraries (from requirements.txt): likely PySide2/PyQt5, sounddevice or pyaudio, etc.
- Usage: command-line args control prompts file, save directory, count, and length.
- Runtime behavior: load prompts → display in QML UI → user records audio → write WAV & TSV → allow playback or delete.

##### Main Components to Illustrate
a. User Interface Layer
– QML UI (recorder.qml) rendered by Python GUI framework (PySide2/PyQt5).
– Displays prompt text, record/play/delete buttons.
b. Application Controller
– recorder.py orchestrates:
- Loading prompts (from prompts/*.txt)
- Passing them to the UI
- Handling UI events (record, stop, play, delete)
- Invoking audio engine
- Writing metadata
c. Audio Engine
– audio.py encapsulates:
- Capturing audio from microphone
- Saving to .wav files
- Playing back existing recordings
d. Data Storage
– File System:
- prompts/*.txt (input)
- user-specified save directory:
– WAV files (recorded speech)
– recorder.tsv (metadata log)
e. External Dependencies
– Python runtime (3.x)
– GUI framework (PySide2/PyQt5)
– Audio backend (sounddevice, pyaudio, wave)

##### Relationships and Data Flows
- User → (UI) → Application Controller
- Controller → Prompt Loader → QML UI (prompts displayed)
- User clicks “Record” → Controller → Audio Engine → MIC → Controller
- Controller → File System (write .wav & TSV)
- User clicks “Play/Delete” → Controller → Audio Engine or File System

##### Architectural Patterns & Principles
– MVC-like separation:
- View: recorder.qml
- Controller: recorder.py
- Model/Services: audio.py, prompt loader, file I/O
– Single-process, event-driven GUI application
– Dependency inversion: controller depends on abstracted audio module

##### Checklist
[ ] Separation of concerns: UI, Controller, Services, Data Store
[ ] External dependencies noted (Python, PySide2, audio library)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layer
    subgraph "Application"
        UI["recorder.qml (UI)"]:::ui
        Controller["recorder.py (Controller)"]:::controller
        Audio["audio.py (Audio Engine)"]:::service
        Loader["Prompt Loader\n(prompts/*.txt)"]:::service
    end

    %% File System Data Store
    subgraph "File System" 
        Prompts["prompts/*.txt"]:::data
        SavDir["Save Directory\nWAV files & recorder.tsv"]:::data
    end

    %% External Dependencies & Docs
    CLI["CLI Args\n(prompts file, save dir, count, length)"]:::external
    Requirements["requirements.txt"]:::external
    Readme["README.md"]:::external
    Python["Python 3.x"]:::external
    GUIFrame["PySide2/PyQt5"]:::external
    AudioLib["sounddevice / pyaudio"]:::external

    %% Data Flows and Relationships
    CLI -->|"startup"| Controller
    Controller -->|"loadPrompts()"| Loader
    Loader -->|"prompts data"| UI
    UI -->|"UI events"| Controller
    Controller -->|"startRecording()"| Audio
    Audio -->|"audio data"| Controller
    Controller -->|"writeWAV()"| SavDir
    Controller -->|"appendTSV()"| SavDir
    UI -->|"play/delete"| Controller
    Controller -->|"playAudio()"| Audio
    Controller -->|"deleteFile()"| SavDir

    %% Dependency Links
    Controller --> Python
    Controller --> GUIFrame
    UI --> GUIFrame
    Audio --> AudioLib
    Requirements --> Python
    Requirements --> GUIFrame
    Requirements --> AudioLib
    Readme --> Controller

    %% Click Events
    click UI "https://github.com/igmim-yassine/speech-training-recorder/blob/master/recorder.qml"
    click Controller "https://github.com/igmim-yassine/speech-training-recorder/blob/master/recorder.py"
    click Audio "https://github.com/igmim-yassine/speech-training-recorder/blob/master/audio.py"
    click Prompts "https://github.com/igmim-yassine/speech-training-recorder/tree/master/prompts/"
    click Requirements "https://github.com/igmim-yassine/speech-training-recorder/blob/master/requirements.txt"
    click Readme "https://github.com/igmim-yassine/speech-training-recorder/blob/master/README.md"

    %% Styles
    classDef ui fill:#a8d0e6,stroke:#333,stroke-width:1px
    classDef controller fill:#b4eeb4,stroke:#333,stroke-width:1px
    classDef service fill:#ffdaa4,stroke:#333,stroke-width:1px
    classDef data fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef external fill:#e0bbe4,stroke:#333,stroke-width:1px
```
