# liutunglin/harmonica-sheet-generator architecture

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

- Interactive diagram: https://gitdiagram.com/liutunglin/harmonica-sheet-generator
- Repository: https://github.com/liutunglin/harmonica-sheet-generator

## Overview

##### Project type and purpose
- This is a domain-specific open-source music generation tool (a CLI/GUI Python application) that produces three-track harmonica MIDI sheets (melody, chords, bass) based on user-selected styles and tempos.

##### File structure
- Top-level directories and files:
- midis/ – output folder for generated MIDI files
- models/ – pre-trained Magenta model files (.mag) for melody and lookback RNN
- scripts/ – core Python scripts for configuration, UI, and each generation step
- requirements.txt, README.md, .gitignore
- Within scripts/:
- ui.py – GUI entry point
- generate_midi.py – orchestrator that ties all generation steps and writes the final MIDI
- generate_chords.py, generate_bass.py, generate_melody.py – individual track generators
- style_config.py – style definitions (chord progressions & rhythms)
- chords.py – helper module for chord notes lookup

##### README for additional insights
- The system uses Magenta’s improv_rnn (LSTM) for conditioned melody generation.
- Chord generation relies on a predefined set of harmonica chords and progressions.
- Bass generation follows simple root-note and arpeggio patterns.
- Users interact via CLI flags or a simple GUI.
- Outputs are MIDI files in the midis/ directory for further editing in DAWs.

##### Main components and interactions
a. Components
1. User Interface
– CLI (generate_midi.py + args)
– GUI (ui.py)
2. Style Configuration
– style_config.py defines progressions & rhythm patterns by style
3. Generation Engine
i. Chord Generator (scripts/generate_chords.py + chords.py)
ii. Melody Generator (scripts/generate_melody.py + models/improv_rnn.mag)
iii. Bass Generator (scripts/generate_bass.py)
4. Assembler & MIDI Writer
– scripts/generate_midi.py invokes each sub-generator, merges tracks, writes MIDI
5. File System
– models/ (input .mag files)
– midis/ (output .mid files)
6. External Dependencies
– Magenta (TensorFlow) for RNN inference
– Python libraries from requirements.txt

b. Relationships / Data flow
- User → (CLI flags or GUI) → Orchestrator
- Orchestrator → Style Config → each generator
- Each generator → produces a track (note sequence)
- Assembler → merges tracks → writes MIDI → midis/

##### Important architectural patterns & design principles
- Pipeline pattern: clear separation of stages (config → chords → melody → bass → assembly)
- Modularity: each track generator is an independent script/module
- Plug-in-style models: additional Magenta models can be swapped in models/
- Single responsibility: style_config.py only defines progression and rhythm data
- Extensibility: add new styles or instruments by extending style_config or adding new scripts

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User
    User(("User"))

    %% User Interface Layer
    subgraph "User Interface"
        CLI["CLI Interface"]:::ui
        GUI["GUI (ui.py)"]:::ui
    end

    %% Configuration Layer
    subgraph "Configuration Layer"
        Config["Style Config (style_config.py)"]:::config
    end

    %% Generation Layer
    subgraph "Generation Layer"
        Chords["Chord Gen\n(generate_chords.py)"]:::gen
        ChordUtil["Chord Utilities\n(chords.py)"]:::gen
        Melody["Melody Gen\n(generate_melody.py)"]:::gen
        Bass["Bass Gen\n(generate_bass.py)"]:::gen
    end

    %% Assembler & File I/O Layer
    subgraph "Assembler & File I/O"
        Assembler["Orchestrator & MIDI Writer\n(generate_midi.py)"]:::io
        Midis["midis/ (output MIDI)"]:::io
    end

    %% File System - Models
    subgraph "Model Files"
        ImprovModel["improv_rnn.mag"]:::io
        LookbackModel["lookback_rnn.mag"]:::io
    end

    %% External Dependencies
    Req["requirements.txt"]:::ext

    %% Data Flow
    User --> CLI
    User --> GUI
    CLI --> Assembler
    GUI --> Assembler

    Assembler --> Config
    Config --> Chords
    Config --> Melody
    Config --> Bass

    Chords --> Assembler
    Melody --> Assembler
    Bass --> Assembler

    Assembler --> Midis

    ImprovModel --> Melody
    LookbackModel --> Melody

    Req --> Assembler

    %% Click Events
    click GUI "https://github.com/liutunglin/harmonica-sheet-generator/blob/improve_rnn/scripts/ui.py"
    click Assembler "https://github.com/liutunglin/harmonica-sheet-generator/blob/improve_rnn/scripts/generate_midi.py"
    click Config "https://github.com/liutunglin/harmonica-sheet-generator/blob/improve_rnn/scripts/style_config.py"
    click Chords "https://github.com/liutunglin/harmonica-sheet-generator/blob/improve_rnn/scripts/generate_chords.py"
    click ChordUtil "https://github.com/liutunglin/harmonica-sheet-generator/blob/improve_rnn/scripts/chords.py"
    click Melody "https://github.com/liutunglin/harmonica-sheet-generator/blob/improve_rnn/scripts/generate_melody.py"
    click ImprovModel "https://github.com/liutunglin/harmonica-sheet-generator/blob/improve_rnn/models/improv_rnn.mag"
    click LookbackModel "https://github.com/liutunglin/harmonica-sheet-generator/blob/improve_rnn/models/lookback_rnn.mag"
    click Bass "https://github.com/liutunglin/harmonica-sheet-generator/blob/improve_rnn/scripts/generate_bass.py"
    click Midis "https://github.com/liutunglin/harmonica-sheet-generator/tree/improve_rnn/midis/"
    click Req "https://github.com/liutunglin/harmonica-sheet-generator/blob/improve_rnn/requirements.txt"

    %% Styles
    classDef ui fill:#ffeb99,stroke:#333,stroke-width:1px
    classDef config fill:#ffd699,stroke:#333,stroke-width:1px
    classDef gen fill:#d2f8d2,stroke:#333,stroke-width:1px
    classDef io fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef ext fill:#e0ccff,stroke:#333,stroke-width:1px
```
