# ajshooting/nandemo-karaoke architecture

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

- Interactive diagram: https://gitdiagram.com/ajshooting/nandemo-karaoke
- Repository: https://github.com/ajshooting/nandemo-karaoke

## Overview

##### Main Components
- Audio Processing Module: Represented by the files in the src/audio folder. This module handles various tasks such as copying, downloading, playing, recording, and separating the audio signal.
- Graphical User Interface (GUI): Found in the src/gui directory. This component contains the main window (src/gui/main_window.py), UI layout files (ui/main_window.ui), and additional widgets (e.g., pitch_bar) which display real-time pitch and lyrics.
- Lyrics Processing Module: Located in src/lyrics, this part handles lyrics recognition (using Whisper) and searching functionality.
- Pitch Analysis Module: Located in src/pitch which performs pitch extraction and analysis.
- Main Application Orchestrator: The src/main.py file acts as the entry point, linking user interactions in the GUI to back-end audio, pitch, and lyrics processing.
- Testing Suite: The tests folder includes various tests (for similarity, spleeter, whisper, and youtube-dl) that validate the functionality of different modules.

##### Relationships and Interactions
- The User interacts with the GUI which serves as the primary interface.
- The GUI sends commands to the Audio Processing Module to start tasks such as recording, playing, or audio separation.
- Once the audio is processed, the Pitch Analysis Module extracts and analyzes the pitch information.
- In parallel, the Lyrics Processing Module listens for or retrieves the lyrics from the processed audio.
- The results from the Pitch and Lyrics modules are synchronized and displayed in the GUI, possibly using widgets like the pitch_bar.
- The main module (src/main.py) orchestrates these interactions and ensures that tasks happen in the correct order.
- Tests are designed to ensure that each module performs as expected.

##### Architectural Patterns and Design Principles
- Modular and Layered Architecture: The project cleanly separates functionality into different modules based on their domain (audio, GUI, lyrics, pitch).
- Separation of Concerns: Each module (GUI vs. audio processing vs. pitch analysis) is self-contained and communicates through clearly defined interfaces.
- Integration of External Libraries: Note the dependencies on Spleeter for audio separation, Whisper for lyrics recognition, and YIN for pitch detection. Represent these as external services or libraries that the internal modules use.
- Testing as a Core Design Aspect: The presence of tests for each main functionality indicates an emphasis on reliability and independent verification of components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level user
    User["User"]:::user

    %% Main Application Container
    subgraph "nandemo-karaoke Application"
        %% Core Modules Subgraph
        subgraph "Core Modules"
            GUI["GUI Module"]:::gui
            Audio["Audio Processing Module"]:::audio
            Lyrics["Lyrics Processing Module"]:::lyrics
            Pitch["Pitch Analysis Module"]:::pitch
            MainApp["Main Application"]:::main
        end
    end

    %% External Libraries
    subgraph "External Libraries"
        Spleeter["Spleeter"]:::external
        YIN["YIN"]:::external
        Whisper["Whisper"]:::external
    end

    %% Testing Suite
    subgraph "Testing Suite"
        Similarity["Similarity Test"]:::test
        SpleeterTest["Spleeter Test"]:::test
        WhisperTest["Whisper Test"]:::test
        YoutubeDLTest["Youtube-dl Test"]:::test
    end

    %% GUI Components Subgraph
    subgraph "GUI Components"
        MainWindow["Main Window"]:::guiComp
        UILayout["UI Layout"]:::guiComp
        PitchBar["Pitch Bar Widget"]:::guiComp
    end

    %% Audio Components Subgraph
    subgraph "Audio Components"
        Copy["Copy"]:::audioComp
        Download["Download"]:::audioComp
        Player["Player"]:::audioComp
        Recorder["Recorder"]:::audioComp
        Separator["Separator"]:::audioComp
    end

    %% Lyrics Components Subgraph
    subgraph "Lyrics Components"
        Recognizer["Recognizer"]:::lyricsComp
        Search["Search"]:::lyricsComp
    end

    %% Pitch Components Subgraph
    subgraph "Pitch Components"
        Analyzer["Analyzer"]:::pitchComp
        Extractor["Extractor"]:::pitchComp
    end

    %% Relationships between external entities
    User -->|"interacts"| GUI

    GUI -->|"commands"| Audio
    Audio -->|"audio_data"| Pitch
    Audio -->|"audio_data"| Lyrics
    Pitch -->|"pitch_results"| GUI
    Lyrics -->|"lyrics_results"| GUI

    MainApp -->|"orchestrates"| GUI
    MainApp -->|"orchestrates"| Audio
    MainApp -->|"orchestrates"| Pitch
    MainApp -->|"orchestrates"| Lyrics

    Audio -->|"separation"| Spleeter
    Pitch -->|"analysis"| YIN
    Lyrics -->|"recognition"| Whisper

    %% Relationships from modules to their components
    GUI -->|"contains"| MainWindow
    GUI -->|"contains"| UILayout
    GUI -->|"contains"| PitchBar

    Audio -->|"includes"| Copy
    Audio -->|"includes"| Download
    Audio -->|"includes"| Player
    Audio -->|"includes"| Recorder
    Audio -->|"includes"| Separator

    Lyrics -->|"includes"| Recognizer
    Lyrics -->|"includes"| Search

    Pitch -->|"includes"| Analyzer
    Pitch -->|"includes"| Extractor

    %% Testing relationships (dashed lines)
    SpleeterTest ---|"tests"| Audio
    YoutubeDLTest ---|"tests"| Audio
    Similarity ---|"tests"| Lyrics
    WhisperTest ---|"tests"| Lyrics

    %% Click Events for Core Modules and their components
    click Audio "https://github.com/ajshooting/nandemo-karaoke/tree/main/src/audio/"
    click GUI "https://github.com/ajshooting/nandemo-karaoke/tree/main/src/gui/"
    click MainApp "https://github.com/ajshooting/nandemo-karaoke/blob/main/src/main.py"
    click Lyrics "https://github.com/ajshooting/nandemo-karaoke/tree/main/src/lyrics/"
    click Pitch "https://github.com/ajshooting/nandemo-karaoke/tree/main/src/pitch/"

    %% Click Events for Audio Components
    click Copy "https://github.com/ajshooting/nandemo-karaoke/blob/main/src/audio/copy.py"
    click Download "https://github.com/ajshooting/nandemo-karaoke/blob/main/src/audio/download.py"
    click Player "https://github.com/ajshooting/nandemo-karaoke/blob/main/src/audio/player.py"
    click Recorder "https://github.com/ajshooting/nandemo-karaoke/blob/main/src/audio/recorder.py"
    click Separator "https://github.com/ajshooting/nandemo-karaoke/blob/main/src/audio/separator.py"

    %% Click Events for GUI Components
    click MainWindow "https://github.com/ajshooting/nandemo-karaoke/blob/main/src/gui/main_window.py"
    click UILayout "https://github.com/ajshooting/nandemo-karaoke/blob/main/src/gui/ui/main_window.ui"
    click PitchBar "https://github.com/ajshooting/nandemo-karaoke/blob/main/src/gui/widgets/pitch_bar.py"

    %% Click Events for Lyrics Components
    click Recognizer "https://github.com/ajshooting/nandemo-karaoke/blob/main/src/lyrics/recognizer.py"
    click Search "https://github.com/ajshooting/nandemo-karaoke/blob/main/src/lyrics/search.py"

    %% Click Events for Pitch Components
    click Analyzer "https://github.com/ajshooting/nandemo-karaoke/blob/main/src/pitch/analyzer.py"
    click Extractor "https://github.com/ajshooting/nandemo-karaoke/blob/main/src/pitch/extractor.py"

    %% Click Events for Testing Suite
    click Similarity "https://github.com/ajshooting/nandemo-karaoke/blob/main/tests/similarity.py"
    click SpleeterTest "https://github.com/ajshooting/nandemo-karaoke/blob/main/tests/spleeter-test.py"
    click WhisperTest "https://github.com/ajshooting/nandemo-karaoke/blob/main/tests/whisper-test.py"
    click YoutubeDLTest "https://github.com/ajshooting/nandemo-karaoke/blob/main/tests/youtube-dl-test.py"

    %% Styles
    classDef user fill:#ffe6f2,stroke:#d10068,stroke-width:2px;
    classDef gui fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef audio fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef lyrics fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef pitch fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef main fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef external fill:#fceabb,stroke:#bf9000,stroke-width:2px,stroke-dasharray: 5,5;
    classDef test fill:#e2e3e5,stroke:#6c757d,stroke-width:2px,stroke-dasharray: 3,3;
    classDef guiComp fill:#b3e6ff,stroke:#004085,stroke-width:2px;
    classDef audioComp fill:#c3e6cb,stroke:#155724,stroke-width:2px;
    classDef lyricsComp fill:#f5c6cb,stroke:#721c24,stroke-width:2px;
    classDef pitchComp fill:#ffeeba,stroke:#856404,stroke-width:2px;
```
