# eyov7/aud2stm2mdi architecture

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

- Interactive diagram: https://gitdiagram.com/eyov7/aud2stm2mdi
- Repository: https://github.com/eyov7/aud2stm2mdi

## Overview

##### Main Components
- User Interface (Gradio-based Web UI) – Represented in app.py. This is the entry point for users where they upload the audio file, select options such as stem type, and trigger processing.
- Audio Stem Separation Module – Implemented in demucs_handler.py. This component manages the core logic for separating audio stems using the Demucs deep learning model, inclusing tensor processing via PyTorch.
- MIDI Conversion Module – Implemented in basic_pitch_handler.py. This handles transcription of the separated audio to MIDI files using Spotify's Basic Pitch with optimizations.
- Validation and Error Handling – Found in validators.py, ensuring audio file integrity, format, size, and sample rate are in order before processing.
- Deployment and Infrastructure – Include a component that represents the Lightning.ai deployment environment, highlighting that the application is packaged to run either locally or on the cloud.

##### Relationships and Interactions
- The User Interface (app.py) accepts audio inputs and passes file data to both the stem separation and MIDI conversion modules.
- The Stem Separation Module (demucs_handler.py) processes the audio input to extract stems and then either directly returns output or optionally connects to the MIDI conversion step.
- The MIDI Conversion Module (basic_pitch_handler.py) receives processed audio for note detection and MIDI file generation.
- The Validation Module (validators.py) is invoked early in the process to ensure the input file meets all criteria; errors propagate back to the UI if validation fails.
- External libraries (PyTorch, etc.) support both the stem separation and MIDI conversion processes.

##### Architectural Patterns and Design Principles
- Separation of concerns – Each Python file is dedicated to a single responsibility (UI, stem separation, MIDI conversion, validation).
- Modularity – The clear division into distinct modules allows for easy updates and potential scalability (for example, adding new models or conversion features).
- Robust Error Handling – As highlighted in the README, error handling is a crucial aspect, so show relevant communication between modules and error reporting back to the UI.
- Scalability and Deployment – Illustrate the deployment environment (Lightning.ai) indicating how compute resources (CPU/GPU) interface with the application.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface
    UI["Front-End UI (Gradio): app.py"]:::frontend

    %% Validation Layer
    VAL["Audio Validation: validators.py"]:::backend

    %% Processing Layer
    DEM["Stem Separation Engine: demucs_handler.py"]:::backend
    MIDI["MIDI Conversion Engine: basic_pitch_handler.py"]:::backend

    %% External Dependencies
    DEP["Dependency Layer: PyTorch, Demucs, Basic Pitch, numpy, pretty_midi"]:::external

    %% Deployment Environment
    DEPLOY["Cloud Deployment: Lightning.ai"]:::deployment

    %% Data flows
    UI -->|"uploadsAudio"| VAL
    VAL -->|"ifValid"| DEM
    DEM -->|"stemsOutput"| MIDI
    MIDI -->|"MIDIResult"| UI
    VAL -.->|"errorMessage"| UI

    %% External dependencies support
    DEP --> DEM
    DEP --> MIDI

    %% Deployment hosting arrow
    DEPLOY -->|"hosts"| UI

    %% Click Events
    click UI "https://github.com/eyov7/aud2stm2mdi/blob/main/app.py"
    click VAL "https://github.com/eyov7/aud2stm2mdi/blob/main/validators.py"
    click DEM "https://github.com/eyov7/aud2stm2mdi/blob/main/demucs_handler.py"
    click MIDI "https://github.com/eyov7/aud2stm2mdi/blob/main/basic_pitch_handler.py"
    click DEP "https://github.com/eyov7/aud2stm2mdi/blob/main/requirements.txt"

    %% Styles
    classDef frontend fill:#cfe2f3,stroke:#6fa8dc,stroke-width:2px;
    classDef backend fill:#d9ead3,stroke:#6aa84f,stroke-width:2px;
    classDef external fill:#fff2cc,stroke:#f1c232,stroke-width:2px;
    classDef deployment fill:#ead1dc,stroke:#b97a57,stroke-width:2px;
```
