# donovanblair16/song_analyzer_app_6 architecture

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

- Interactive diagram: https://gitdiagram.com/donovanblair16/song_analyzer_app_6
- Repository: https://github.com/donovanblair16/song_analyzer_app_6

## Overview

##### Project type and purpose
- This is a standalone Python-based audio analysis application (“song_analyzer_app_6”) with a GUI front end, an audio-feature extraction and manipulation engine, and a statistical modeling backend based on Gaussian Mixture Model – Hidden Markov Model (GMM-HMM).
- It supports both training new models (`run_gmmhmm_trainer.py`) and running predictions (`hmm_predictor.py`), plus interactive exploration (`data_explorer.py`, `section_editor.py`) and playback/plotting of audio segments.

##### File structure
- Top-level scripts:
- `main_app.py` – application entrypoint with GUI startup
- `audio_analysis_wrapper.py`, `audio_plotting.py`, `playback_manager.py`, `plot_manager.py` – ancillary services for analysis, plotting, and audio playback
- `run_gmmhmm_trainer.py`, `hmm_predictor.py` – CLI/train and predict commands
- `data_check.py`, `file_manager.py`, `find_outro_problem.py` – data-handling utilities
- `data_explorer.py`, `section_editor.py`, `gui_builder.py` – explorer and editor interfaces
- Module directories:
- `audio_analysis_modules/` – domain logic for loading audio, computing spectral and chroma features, segment detection
- `GMMHMM_modules/` – implementation of GMM-HMM model, configuration, feature or sequence analysis, GUI integration
- `hmm_model/` – serialized model artifacts and metadata (joblib, JSON, NumPy arrays)

##### README
- Minimal, only the project name. All architectural clues come from the code layout.

a. Main components:
1. User Interface Layer
- GUI Builder (`gui_builder.py`)
- Main Window (`main_app.py`)
- Section Editor (`section_editor.py`)
- Data Explorer (`data_explorer.py`)
2. Audio Analysis Engine
- Audio Loader & Preprocessor (`audio_analysis_modules/loading.py`, `data_utils.py`)
- Feature Extractors (spectral, chroma, custom; in both `audio_analysis_modules/feature_extraction.py` and `GMMHMM_modules/feature_extraction.py`)
- Section Detection (`audio_analysis_modules/section_detection.py`)
3. Modeling & Computation
- GMM-HMM Trainer (`GMMHMM_modules/hmm_model.py`, `run_gmmhmm_trainer.py`)
- Predictor (`hmm_predictor.py`, `GMMHMM_modules/analysis.py`)
- Configuration & Utilities (`GMMHMM_modules/config.py`)
4. Persistence & Artifacts
- Model Store (`hmm_model/` directory)
- File I/O Manager (`file_manager.py`)
5. Visualization & Playback
- Plot Manager (`plot_manager.py`, `audio_plotting.py`)
- Playback Manager (`playback_manager.py`)
6. Orchestration Scripts
- Data validation (`data_check.py`)
- Transition extraction (`extract_transitions.py`)
- Outro detection helper (`find_outro_problem.py`)
b. Relationships & Interactions
- UI triggers audio load → hands off to Audio Loader
- Features flow into either the Trainer or Predictor
- Trainer writes models into `hmm_model/`; Predictor reads from it
- Results feed back to UI for plotting or playback
- File Manager abstracts disk reads/writes (audio files, model files, CSV/JSON)
c. Architectural patterns/design principles
- Layered architecture: UI → Domain (audio analysis) → Modeling → Persistence
- Modularity: separate modules for audio, modeling, GUI, I/O, plotting
- Reusability: wrappers (audio_analysis_wrapper) let both UI and CLI use the same engine
d. Key technologies/frameworks
- Python 3 (standard library, `joblib` for model serialization, `numpy` for numeric arrays)
- Audio libraries (e.g., `librosa` – implied by feature-extraction code)
- GUI toolkit (likely `tkinter` or `PyQt` as used in `gui.py`/`gui_builder.py`)

##### Diagramming recommendations
- Blue for UI components
- Green for audio-analysis engine
- Orange for modeling components
- Gray for file/persistence services

##### Essential details
- Don’t omit the orchestration scripts—they show how the system is driven in different modes
- Shared utilities (`file_manager.py`, `GMMHMM_modules/config.py`) that tie components together
- Where dependencies like `numpy` and `joblib` are used (in modeling and persistence)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        UI1["GUI Builder"]:::ui
        UI2["Main Window"]:::ui
        UI3["Section Editor"]:::ui
        UI4["Data Explorer"]:::ui
    end

    %% Audio Analysis Engine
    subgraph "Audio Analysis Engine"
        AL["Audio Loader & Preprocessor"]:::audio
        DU["Audio Analysis Utilities"]:::audio
        SF["Spectral Feature Extraction"]:::audio
        CF["Chroma Feature Extraction"]:::audio
        GF["Feature Extraction Wrappers"]:::audio
        SD["Section Detection"]:::audio
        AW["Audio-Analysis Wrapper"]:::audio
    end

    %% Modeling & Computation
    subgraph "Modeling & Computation"
        T1["GMM-HMM Trainer CLI"]:::model
        M1["GMM-HMM Model Implementation"]:::model
        P1["Predictor CLI"]:::model
        A2["Sequence/Model Analysis Utilities"]:::model
        Cfg["Model Configuration & Parameters"]:::model
        FM["Feature Extraction for Modeling"]:::model
    end

    %% Persistence & Artifacts
    subgraph "Persistence & Artifacts"
        MS["Model Store"]:::persistence
        FI["File I/O Manager"]:::persistence
    end

    %% Visualization & Playback
    subgraph "Visualization & Playback"
        PM["Plot Manager"]:::viz
        AP["Audio Plotting Utilities"]:::viz
        PB["Playback Manager"]:::viz
    end

    %% Orchestration & Utilities
    subgraph "Orchestration & Utilities"
        DVal["Data Validation Script"]:::util
        TE["Transition Extraction Tool"]:::util
        OH["Outro Detection Helper"]:::util
    end

    %% Data Flows
    UI2 -->|triggers| AW
    UI3 -->|uses| AW
    UI4 -->|uses| AW
    AW -->|loads audio| AL
    AL -->|uses| DU
    AL -->|calls| SF
    AL -->|calls| CF
    AL -->|calls| GF
    AL -->|calls| SD
    AW -->|provides features| FM
    FM -->|to trainer| T1
    FM -->|to predictor| P1
    T1 -->|builds model| M1
    M1 -->|saves to| MS
    P1 -->|loads from| MS
    P1 -->|uses| A2
    Cfg -->|configures| T1
    Cfg -->|configures| P1
    FI -->|reads/writes| AL
    FI -->|reads/writes| M1
    UI2 -->|sends results| PM
    PM -->|plots via| AP
    UI2 -->|plays audio| PB
    DVal -->|validates data via| FI
    TE -->|extracts transitions via| A2
    OH -->|detects outros via| DU

    %% Click Events
    click UI1 "https://github.com/donovanblair16/song_analyzer_app_6/blob/main/gui_builder.py"
    click UI2 "https://github.com/donovanblair16/song_analyzer_app_6/blob/main/main_app.py"
    click UI3 "https://github.com/donovanblair16/song_analyzer_app_6/blob/main/section_editor.py"
    click UI4 "https://github.com/donovanblair16/song_analyzer_app_6/blob/main/data_explorer.py"
    click AL "https://github.com/donovanblair16/song_analyzer_app_6/blob/main/audio_analysis_modules/loading.py"
    click DU "https://github.com/donovanblair16/song_analyzer_app_6/blob/main/GMMHMM_modules/data_utils.py"
    click SF "https://github.com/donovanblair16/song_analyzer_app_6/blob/main/audio_analysis_modules/spectral_analysis.py"
    click CF "https://github.com/donovanblair16/song_analyzer_app_6/blob/main/audio_analysis_modules/chroma_analysis.py"
    click GF "https://github.com/donovanblair16/song_analyzer_app_6/blob/main/audio_analysis_modules/feature_extraction.py"
    click SD "https://github.com/donovanblair16/song_analyzer_app_6/blob/main/audio_analysis_modules/section_detection.py"
    click AW "https://github.com/donovanblair16/song_analyzer_app_6/blob/main/audio_analysis_wrapper.py"
    click T1 "https://github.com/donovanblair16/song_analyzer_app_6/blob/main/run_gmmhmm_trainer.py"
    click M1 "https://github.com/donovanblair16/song_analyzer_app_6/blob/main/GMMHMM_modules/hmm_model.py"
    click P1 "https://github.com/donovanblair16/song_analyzer_app_6/blob/main/hmm_predictor.py"
    click A2 "https://github.com/donovanblair16/song_analyzer_app_6/blob/main/GMMHMM_modules/analysis.py"
    click Cfg "https://github.com/donovanblair16/song_analyzer_app_6/blob/main/GMMHMM_modules/config.py"
    click FM "https://github.com/donovanblair16/song_analyzer_app_6/blob/main/GMMHMM_modules/feature_extraction.py"
    click MS "https://github.com/donovanblair16/song_analyzer_app_6/tree/main/hmm_model/"
    click FI "https://github.com/donovanblair16/song_analyzer_app_6/blob/main/file_manager.py"
    click PM "https://github.com/donovanblair16/song_analyzer_app_6/blob/main/plot_manager.py"
    click AP "https://github.com/donovanblair16/song_analyzer_app_6/blob/main/audio_plotting.py"
    click PB "https://github.com/donovanblair16/song_analyzer_app_6/blob/main/playback_manager.py"
    click DVal "https://github.com/donovanblair16/song_analyzer_app_6/blob/main/data_check.py"
    click TE "https://github.com/donovanblair16/song_analyzer_app_6/blob/main/extract_transitions.py"
    click OH "https://github.com/donovanblair16/song_analyzer_app_6/blob/main/find_outro_problem.py"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#0366d6,color:#0366d6;
    classDef audio fill:#d4edda,stroke:#28a745,color:#155724;
    classDef model fill:#fff3cd,stroke:#ffc107,color:#856404;
    classDef persistence fill:#e2e3e5,stroke:#6c757d,color:#343a40;
    classDef viz fill:#f5e1ff,stroke:#6f42c1,color:#38107e;
    classDef util fill:#f0f0f0,stroke:#999999,color:#444444;
```
