# nagmdrs/speaker_recognition architecture

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

- Interactive diagram: https://gitdiagram.com/nagmdrs/speaker_recognition
- Repository: https://github.com/nagmdrs/speaker_recognition

## Overview

##### Project type and purpose
- Type: End-to-end machine-learning pipeline for speaker recognition
- Purpose: Ingest raw audio, compute mel spectrograms, feed into ECAPA-TDNN model, train/evaluate, and produce embeddings + visualizations (attention maps, t-SNE plots).

##### File structure
Top-level components:
- Configuration: cfg.py, config.yaml
- Core model: base_model.py (ECAPA-TDNN + mel frontend)
- Orchestration wrappers: train_model.py (training + t-SNE), main_model.py (train/eval/inference), plot_attention.py (attention viz)
- Utilities: helperFiles/ (dataLoader.py, losses.py, tools.py, list generators)
- Artifacts: exps/ (checkpoints), Results/ (scores), params/ (speaker lists)

##### README for additional insights
- Architecture: SE-Res2Blocks, attentive pooling, channel attention
- Outputs: 192-dim embeddings
- Metrics: EER, minDCF
- Dataset: VoxCeleb (external)

##### Main components & interactions
a. Data Ingestion & Preprocessing
– Scripts: helperFiles/create_train_list.py, create_eval_list.py
– Inputs: raw audio files (external VoxCeleb dataset)
– Outputs: params/train_list.txt, params/eval_list.txt
– DataLoader (helperFiles/dataLoader.py) reads lists → loads waveforms → computes mel spectrograms via frontend in base_model.py

b. Model (ECAPA-TDNN)
– Module: base_model.py
– Receives mel spectrograms → SE-Res2Blocks → attentive pooling → 192-dim embeddings

c. Training & Evaluation
– Script: train_model.py
- Uses config.yaml/cfg.py parameters
- Feeds embeddings + labels into specified loss functions (helperFiles/losses.py)
- Logs metrics (EER, minDCF)
- Saves checkpoints under exps/expX/
- Generates t-SNE plots

– Alternative orchestration: main_model.py (wraps train/eval/inference routines)

d. Visualization & Post-processing
– Script: plot_attention.py
- Loads trained checkpoint
- Runs attention maps over mel spectrograms
- Outputs plots to Images/ or Results/

e. Configuration & Utilities
– cfg.py & config.yaml hold hyperparameters (learning rate, batch size, model depths, mel settings)
– helperFiles/tools.py provides logging, metric computation, etc.

##### Architectural patterns & design principles
- Separation of concerns: distinct modules for config, data loading, model definition, training loops, visualization
- Modular layering:
– Data layer → Model layer → Training/Eval layer → Visualization layer
- Reusability: helperFiles utilities used across scripts
- Checkpointing & experiment tracking: exps/ directory per experiment

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Dataset
    Vox["VoxCeleb Dataset"]:::external

    %% Data Ingestion & List Generation
    subgraph "Data Ingestion & List Generation"
        CTL["create_train_list.py"]:::code
        CEL["create_eval_list.py"]:::code
        TL["params/train_list.txt"]:::data
        EL["params/eval_list.txt"]:::data
    end

    %% Data Loading & Preprocessing
    subgraph "Data Loading & Preprocessing"
        DL["dataLoader.py"]:::code
        FE["base_model.py<br/>(mel frontend)"]:::code
    end

    %% Core Model
    subgraph "Core Model"
        CM["base_model.py<br/>(ECAPA-TDNN)"]:::code
    end

    %% Training & Evaluation
    subgraph "Training & Evaluation"
        CFG["cfg.py"]:::code
        YML["config.yaml"]:::code
        TM["train_model.py"]:::code
        LM["losses.py"]:::code
        EX["exps/"]:::data
        MM["main_model.py"]:::code
    end

    %% Visualization & Post-processing
    subgraph "Visualization & Post-processing"
        PA["plot_attention.py"]:::code
        RS["Results/"]:::data
    end

    %% Utilities
    subgraph "Utilities"
        TO["tools.py"]:::code
        SW["single_word_utterances.py"]:::code
    end

    %% Data Flow
    Vox -->|raw .wav| CTL
    Vox -->|raw .wav| CEL
    CTL -->|train_list| TL
    CEL -->|eval_list| EL
    TL --> DL
    EL --> DL
    DL -->|mel-spectrogram| FE
    FE --> CM
    CM -->|embeddings| TM
    CFG --> TM
    YML --> TM
    LM --> TM
    TO --> TM
    CM --> LM
    TM -->|checkpoints| EX
    TM -->|t-SNE plots| RS
    EX --> PA
    PA -->|attention maps| RS
    EX --> MM
    MM -->|inference embeddings| RS

    %% Click Events
    click CTL "https://github.com/nagmdrs/speaker_recognition/blob/main/helperFiles/create_train_list.py"
    click CEL "https://github.com/nagmdrs/speaker_recognition/blob/main/helperFiles/create_eval_list.py"
    click TL "https://github.com/nagmdrs/speaker_recognition/blob/main/params/train_list.txt"
    click EL "https://github.com/nagmdrs/speaker_recognition/blob/main/params/eval_list.txt"
    click DL "https://github.com/nagmdrs/speaker_recognition/blob/main/helperFiles/dataLoader.py"
    click FE "https://github.com/nagmdrs/speaker_recognition/blob/main/base_model.py"
    click CM "https://github.com/nagmdrs/speaker_recognition/blob/main/base_model.py"
    click TM "https://github.com/nagmdrs/speaker_recognition/blob/main/train_model.py"
    click CFG "https://github.com/nagmdrs/speaker_recognition/blob/main/cfg.py"
    click YML "https://github.com/nagmdrs/speaker_recognition/blob/main/config.yaml"
    click LM "https://github.com/nagmdrs/speaker_recognition/blob/main/helperFiles/losses.py"
    click MM "https://github.com/nagmdrs/speaker_recognition/blob/main/main_model.py"
    click PA "https://github.com/nagmdrs/speaker_recognition/blob/main/plot_attention.py"
    click TO "https://github.com/nagmdrs/speaker_recognition/blob/main/helperFiles/tools.py"
    click SW "https://github.com/nagmdrs/speaker_recognition/blob/main/helperFiles/single_word_utterances.py"
    click EX "https://github.com/nagmdrs/speaker_recognition/tree/main/exps/"
    click RS "https://github.com/nagmdrs/speaker_recognition/tree/main/Results/"

    %% Styles
    classDef code fill:#cce5ff,stroke:#4d94ff,stroke-width:1px
    classDef data fill:#d5f5d5,stroke:#2ca02c,stroke-width:1px
    classDef external fill:#ffe5cc,stroke:#ff9933,stroke-width:1px,stroke-dasharray: 5 5
```
