# eupston/deepbeat-beatbox2midi architecture

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

- Interactive diagram: https://gitdiagram.com/eupston/deepbeat-beatbox2midi
- Repository: https://github.com/eupston/deepbeat-beatbox2midi

## Overview

##### Project type and purpose
- Deepbeat is a desktop, cross-platform, full-stack (single-process) application written in Python that provides a GUI for converting raw beatboxing audio into MIDI drum sequences. It embeds a trained Convolutional Neural Network (CNN) model, audio I/O modules, MIDI generation and playback, and packaging scripts.

##### File structure
Top-level components:
- Deepbeat.py – application entry point that initializes the PyQt UI and ties together modules
- Mainwindow.ui / Mainwindow.py – PyQt5 GUI layout and controller
- utils/ – domain logic: audio preprocessing, onset detection, model inference, silence removal, MIDI output, metronome, playback
- Build_setup/ – OS-specific packaging configurations and scripts (pyinstaller spec for Windows, py2app setup for macOS)
- requirements.txt – Python dependencies (PyQt5, TensorFlow/Keras, numpy, mido, etc.)

##### README for additional insights
- Describes the audio recorder + trimmer, CNN-based conversion “Kick/Snare/Hihat,” four drum-kit playback options, looper, tempo slider, and metronome.
- Mentions external dependency: Panotti CNN training code.
- Packaging via pyinstaller/py2app.

##### Main components and their interactions
a. Components:
1. GUI Layer (PyQt5)
- Audio Recorder Widget
- Trimmer Widget
- Controls: “Convert to MIDI,” tempo slider, metronome on/off, kit selector, looper, export button
2. Audio Preprocessing
- remove_silence.py
- onset_offset.py
- audio2midi.py (coordinates slicing and feeding windows to model)
3. Classification Engine
- predict.py (loads resources/beatbox_model2.hdf5)
- runs CNN inference per audio frame or window
4. MIDI Generator & Exporter
- midi_player.py (real-time playback using chosen drum-kit samples)
- audio2midi.py (maps model outputs to MIDI note events)
5. Metronome
- metronome.py (click track generation based on tempo slider)
6. Resources
- resources/drumkits (WAV samples for Kick, Snare, Hi-Hat)
7. Packaging Layer
- Build_setup (pyinstaller/py2app configs)
b. Relationships:
- User clicks “Record” → GUI triggers audio recording (PyAudio or QtMultimedia)
- Recorded raw WAV → pass to remove_silence → onset detection → segmented
- Each segment piped to predict → CNN outputs class labels + timestamps
- Labels → audio2midi converts to a MIDI track in memory
- track → either sent to midi_player for immediate playback (samples from resources/drumkits) or written to .mid file for export
- Tempo slider and looper modules influence playback timing loops and metronome.py
c. Architectural patterns:
- MVC-like separation: PyQt UI (View+Controller) vs. utils modules (Model/Service)
- Pipeline pattern in audio processing: chained transforms
- Resource externalization for model and sample assets
d. Key technologies:
- PyQt5 – GUI
- TensorFlow/Keras – CNN inference
- mido or python-rtmidi – MIDI generation/playback
- pyinstaller / py2app – packaging
- WAV I/O via built-in wave or sounddevice/PyAudio

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Application Entry Point
    Deepbeat["Deepbeat.py"]:::packaging
    click Deepbeat "https://github.com/eupston/deepbeat-beatbox2midi/blob/master/Deepbeat.py"

    subgraph "GUI Layer"
        direction TB
        Recorder["Audio Recorder Widget"]:::gui
        Trimmer["Trimmer Widget"]:::gui
        Controls["Controls\n(Convert, Tempo Slider,\nMetronome On/Off,\nKit Selector, Looper,\nExport Button)"]:::gui
        MainUI["Mainwindow.ui"]:::gui
        MainCtrl["Mainwindow.py"]:::gui
        click MainUI "https://github.com/eupston/deepbeat-beatbox2midi/blob/master/Mainwindow.ui"
        click MainCtrl "https://github.com/eupston/deepbeat-beatbox2midi/blob/master/Mainwindow.py"
        Deepbeat --> MainUI
        Deepbeat --> MainCtrl
        MainCtrl --> Recorder
        MainCtrl --> Trimmer
        MainCtrl --> Controls
    end

    subgraph "Core Processing Pipeline"
        direction TB
        Silence["remove_silence.py"]:::processing
        Onset["onset_offset.py"]:::processing
        Predict["predict.py"]:::processing
        Audio2MIDI["audio2midi.py"]:::processing
        MidiPlayer["midi_player.py"]:::processing
        Metronome["metronome.py"]:::processing

        click Silence "https://github.com/eupston/deepbeat-beatbox2midi/blob/master/utils/remove_silence.py"
        click Onset "https://github.com/eupston/deepbeat-beatbox2midi/blob/master/utils/onset_offset.py"
        click Predict "https://github.com/eupston/deepbeat-beatbox2midi/blob/master/utils/predict.py"
        click Audio2MIDI "https://github.com/eupston/deepbeat-beatbox2midi/blob/master/utils/audio2midi.py"
        click MidiPlayer "https://github.com/eupston/deepbeat-beatbox2midi/blob/master/utils/midi_player.py"
        click Metronome "https://github.com/eupston/deepbeat-beatbox2midi/blob/master/utils/metronome.py"

        Recorder -->|raw WAV| Silence
        Silence -->|trimmed audio| Onset
        Onset -->|audio segments| Predict
        Predict -->|class labels + timestamps| Audio2MIDI
        Audio2MIDI -->|MIDI events| MidiPlayer
        Audio2MIDI -->|.mid file| Export["Export .mid"]:::processing
        Controls -->|tempo value| Metronome
        Controls -->|looper settings| MidiPlayer
        Metronome -->|click track| MidiPlayer
    end

    subgraph "Resources"
        direction TB
        Model["beatbox_model2.hdf5"]:::resources
        Drumkits["resources/drumkits/"]:::resources
        Icon["Deepbeat_Icon.icns"]:::resources
        ExMIDI["beatbox.mid"]:::resources
        ExAudio["output.wav"]:::resources

        click Model "https://github.com/eupston/deepbeat-beatbox2midi/blob/master/resources/beatbox_model2.hdf5"
        click Drumkits "https://github.com/eupston/deepbeat-beatbox2midi/tree/master/resources/drumkits/"
        click Icon "https://github.com/eupston/deepbeat-beatbox2midi/blob/master/resources/images/Deepbeat_Icon.icns"
        click ExMIDI "https://github.com/eupston/deepbeat-beatbox2midi/blob/master/resources/beatbox.mid"
        click ExAudio "https://github.com/eupston/deepbeat-beatbox2midi/blob/master/resources/output.wav"

        Model --> Predict
        Drumkits --> MidiPlayer
        Icon --> MainUI
        ExMIDI --> MainCtrl
        ExAudio --> MainCtrl
    end

    subgraph "Packaging Layer"
        direction TB
        Py2App["Build_setup/Mac/setup.py"]:::packaging
        PyInstaller["Build_setup/Windows/deepbeat.spec"]:::packaging
        Req["requirements.txt"]:::packaging

        click Py2App "https://github.com/eupston/deepbeat-beatbox2midi/blob/master/Build_setup/Mac/setup.py"
        click PyInstaller "https://github.com/eupston/deepbeat-beatbox2midi/blob/master/Build_setup/Windows/deepbeat.spec"
        click Req "https://github.com/eupston/deepbeat-beatbox2midi/blob/master/requirements.txt"

        Deepbeat --> Py2App
        Deepbeat --> PyInstaller
        Deepbeat --> Req
    end

    %% Legend
    subgraph "Legend"
        direction TB
        GUI["GUI Components"]:::gui
        PROC["Processing Modules"]:::processing
        RES["Resources"]:::resources
        PKG["Packaging"]:::packaging
    end

    classDef gui fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef processing fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef resources fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef packaging fill:#D3D3D3,stroke:#333,stroke-width:1px;
```
