# theairdemon/musicgenerator architecture

> Architecture diagram of the GitHub repository theairdemon/musicgenerator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/theairdemon/musicgenerator
- Repository: https://github.com/theairdemon/musicgenerator

## Overview

1. **What this repository is**
   - `musicGenerator` is a versioned music-composition system written primarily in Python.
   - Its core job is to turn music-theory rules and genre presets into song structures, then export them as MIDI-oriented artifacts for playback or DAW use.

2. **Repo structure is versioned by architecture**
   - The root contains multiple generations of the project: `Version 1 (deprecated)`, `Version 2 (deprecated)`, `Version 3 (stable)`, and `Version 4 (dev)`.
   - This is not a single flat codebase; it is an evolution path. For an architecture diagram, the current system should center on Version 4, with Versions 1–3 treated as historical layers showing how the pipeline evolved.

3. **Current core pipeline: Version 4**
   - `Version 4 (dev)/SongGen.py` appears to be the main orchestration class.
   - `RunSongGen.py` is the entry entrypoint that likely initializes configuration and triggers generation.
   - The flow is: genre/structure inputs → generator modules → MIDI output, with optional playback/rendering integration.

4. **Generation subsystem is split into focused modules**
   - `Version 4 (dev)/Generators/` contains the functional stages of song creation:
     - `GenChords.py` for chord progressions
     - `GenHarmony.py` for harmony parts
     - `GenMelody.py` for lead melody creation
     - `GenRhythm.py` for rhythmic patterns
     - `GenDrums.py` for percussion
     - `GenMidi.py` for writing/exporting MIDI
   - This suggests a pipeline where musical concerns are separated by domain, rather than handled in one monolithic generator.

5. **Genre subsystem provides constraints and style**
   - `Version 4 (dev)/Genres/` is the style/metadata layer.
   - `DefineGenre.py` and the `GenreDefinitions/` package (`anime.py`, `classical.py`, `cyberpunk.py`, `fantasy.py`, `lofi.py`, `base.py`) indicate genre-specific templates or rule sets.
   - Supporting files like `MelodyInfo.py`, `RhythmInfo.py`, `StructureInfo.py`, and `MidiInfo.py` suggest that genre definitions feed structured parameters into the generator pipeline.

6. **Primary data flow**
   - The generator likely starts with genre selection and high-level song shape, then progressively derives lower-level musical parts.
   - A typical flow is: genre definition → structure/rhythm/melody constraints → chords/harmony/drums/melody generation → MIDI assembly/export.
   - This layered flow is important for the architecture diagram because each stage consumes the output of the previous one.

7. **Output boundary: MIDI is the main artifact**
   - Across the README and filenames, MIDI is the key interchange format.
   - `GenMidi.py`, older `song_gen.py`, and legacy files like `test_midi.py` indicate that the system’s output is designed to be imported into external audio tooling rather than producing final mastered audio itself.
   - The repository therefore sits upstream of a DAW or synth/rendering pipeline.

8. **Audio playback / rendering integration**
   - The root `fluidsynth.sh` and the Godot app under `musicgeneratorapp/` suggest a playback/rendering path around FluidSynth.
   - `musicgeneratorapp/Scripts/FluidSynthInstruments.gd` and `Main.gd` imply a UI/frontend that can select or manage instruments and drive playback of generated music.
   - This is a distinct boundary from the Python generator: Python creates music data, while the app handles user interaction and audio presentation.

9. **Godot app as the user-facing layer**
   - `Version 4 (dev)/musicgeneratorapp/` is a separate frontend project built in Godot.
   - Its scene and script structure (`Scenes/Main.tscn`, `Scripts/Main.gd`, `project.godot`) indicates a lightweight application shell around the generation/playback workflow.
   - In an architecture diagram, this should be shown as a client UI that invokes or consumes the generator, not as the generation engine itself.

10. **Stable and deprecated versions show the architecture’s evolution**
   - `Version 3 (stable)/SongGen.py` is the last compact Python-only version and likely represents the mature single-file generator.
   - `Version 2 (deprecated)/Song Generator.ipynb` shows the notebook-era prototype.
   - `Version 1 (deprecated)/` contains low-level note/sound libraries (`noteLib.py`, `soundLib.py`, `music.java`, `songs.java`, `generator.py`) and raw artifacts such as `Africa.mid`, which suggests early experimentation with direct synthesis and MIDI generation.

11. **Legacy V1 differs architecturally from V3/V4**
   - Version 1 generated sounds directly, with a stronger coupling between note logic and playback/synthesis.
   - Version 3 and especially Version 4 move toward a cleaner separation: theory/rules, generation modules, song orchestration, and output/export.
   - That shift is one of the main architectural themes of the repo.

12. **Testing and experiments**
   - Files like `Version 4 (dev)/Generators/test1.py`, `Version 4 (dev)/test1`, and `Version 4 (dev)/test1.c` look like experimentation or proof-of-concept code rather than core product paths.
   - They are useful to note as auxiliary development artifacts, but they are not central subsystems.

13. **Important boundaries to draw**
   - **Input/configuration boundary:** genre choice, key/mode, structure, and style parameters.
   - **Core generation boundary:** chord, melody, rhythm, drums, harmony modules.
   - **Artifact boundary:** MIDI generation and any files handed to external tools.
   - **Presentation/playback boundary:** Godot UI and FluidSynth-based playback/rendering.

14. **How to diagram the system**
   - Show Version 4 as the main architecture.
   - Place `SongGen.py`/`RunSongGen.py` at the center.
   - Feed it from the `Genres` package and fan out into the `Generators` modules.
   - Route output through `GenMidi.py` to MIDI files, then optionally through FluidSynth/Godot for playback or user interaction.
   - Treat Versions 1–3 as historical layers that explain the design evolution, not as the active runtime path.

Main entry points: [`Version 4 (dev)/SongGen.py`](https://github.com/theairdemon/musicgenerator/blob/HEAD/Version%204%20(dev)/SongGen.py) (SongGen.py), [`Version 4 (dev)/Generators/GenMidi.py`](https://github.com/theairdemon/musicgenerator/blob/HEAD/Version%204%20(dev)/Generators/GenMidi.py) (GenMidi.py), [`Version 4 (dev)/Genres/GenreDefinitions`](https://github.com/theairdemon/musicgenerator/tree/HEAD/Version%204%20(dev)/Genres/GenreDefinitions) (Genre defs), [`Version 4 (dev)/Generators/GenRhythm.py`](https://github.com/theairdemon/musicgenerator/blob/HEAD/Version%204%20(dev)/Generators/GenRhythm.py) (Rhythm)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_v4_core["Version 4 Core"]
  node_v4_runsonggen["RunSongGen.py<br/>entrypoint<br/>[RunSongGen.py]"]
  node_v4_songgen["SongGen.py<br/>orchestrator<br/>[SongGen.py]"]
  node_v4_chords["Chords<br/>music-stage<br/>[GenChords.py]"]
  node_v4_harmony["Harmony<br/>music-stage<br/>[GenHarmony.py]"]
  node_v4_melody["Melody<br/>music-stage<br/>[GenMelody.py]"]
  node_v4_rhythm["Rhythm<br/>music-stage<br/>[GenRhythm.py]"]
  node_v4_drums["Drums<br/>music-stage<br/>[GenDrums.py]"]
  node_v4_midi["GenMidi.py<br/>artifact-export<br/>[GenMidi.py]"]
end

subgraph group_v4_genres["Version 4 Genres"]
  node_v4_definegenre["DefineGenre.py<br/>genre-router<br/>[DefineGenre.py]"]
  node_v4_gendefs["Genre defs<br/>genre-presets"]
  node_v4_melinfo["MelodyInfo<br/>genre-params<br/>[MelodyInfo.py]"]
  node_v4_rhyinfo["RhythmInfo<br/>genre-params<br/>[RhythmInfo.py]"]
  node_v4_structinfo["StructureInfo<br/>genre-params<br/>[StructureInfo.py]"]
  node_v4_midiinfo["MidiInfo<br/>genre-params<br/>[MidiInfo.py]"]
end

subgraph group_v4_ui["Version 4 UI"]
  node_v4_app["Godot app<br/>ui-client"]
end

subgraph group_history["History"]
  node_v3_songgen["V3 SongGen<br/>stable-gen<br/>[SongGen.py]"]
  node_v2_notebook["V2 notebook<br/>prototype"]
  node_v1_legacy["V1 legacy<br/>legacy-core"]
end

node_v4_runsonggen -->|"starts"| node_v4_songgen
node_v4_songgen -->|"loads"| node_v4_definegenre
node_v4_definegenre -->|"selects"| node_v4_gendefs
node_v4_gendefs -->|"feeds"| node_v4_melinfo
node_v4_gendefs -->|"feeds"| node_v4_rhyinfo
node_v4_gendefs -->|"feeds"| node_v4_structinfo
node_v4_gendefs -->|"feeds"| node_v4_midiinfo
node_v4_songgen -->|"drives"| node_v4_chords
node_v4_chords -->|"extends"| node_v4_harmony
node_v4_rhyinfo -->|"constrains"| node_v4_rhythm
node_v4_melinfo -->|"constrains"| node_v4_melody
node_v4_structinfo -->|"shapes"| node_v4_songgen
node_v4_rhythm -->|"supports"| node_v4_drums
node_v4_songgen -->|"drives"| node_v4_melody
node_v4_songgen -->|"drives"| node_v4_rhythm
node_v4_songgen -->|"drives"| node_v4_drums
node_v4_chords -->|"exports"| node_v4_midi
node_v4_harmony -->|"exports"| node_v4_midi
node_v4_melody -->|"exports"| node_v4_midi
node_v4_rhythm -->|"exports"| node_v4_midi
node_v4_drums -->|"exports"| node_v4_midi
node_v4_midi -->|"plays"| node_v4_app
node_v4_songgen -.->|"evolved from"| node_v3_songgen
node_v3_songgen -.->|"evolved from"| node_v2_notebook
node_v2_notebook -.->|"evolved from"| node_v1_legacy

click node_v4_runsonggen "https://github.com/theairdemon/musicgenerator/blob/master/Version 4 (dev)/RunSongGen.py"
click node_v4_songgen "https://github.com/theairdemon/musicgenerator/blob/master/Version 4 (dev)/SongGen.py"
click node_v4_chords "https://github.com/theairdemon/musicgenerator/blob/master/Version 4 (dev)/Generators/GenChords.py"
click node_v4_harmony "https://github.com/theairdemon/musicgenerator/blob/master/Version 4 (dev)/Generators/GenHarmony.py"
click node_v4_melody "https://github.com/theairdemon/musicgenerator/blob/master/Version 4 (dev)/Generators/GenMelody.py"
click node_v4_rhythm "https://github.com/theairdemon/musicgenerator/blob/master/Version 4 (dev)/Generators/GenRhythm.py"
click node_v4_drums "https://github.com/theairdemon/musicgenerator/blob/master/Version 4 (dev)/Generators/GenDrums.py"
click node_v4_midi "https://github.com/theairdemon/musicgenerator/blob/master/Version 4 (dev)/Generators/GenMidi.py"
click node_v4_definegenre "https://github.com/theairdemon/musicgenerator/blob/master/Version 4 (dev)/Genres/DefineGenre.py"
click node_v4_gendefs "https://github.com/theairdemon/musicgenerator/tree/master/Version 4 (dev)/Genres/GenreDefinitions"
click node_v4_melinfo "https://github.com/theairdemon/musicgenerator/blob/master/Version 4 (dev)/Genres/MelodyInfo.py"
click node_v4_rhyinfo "https://github.com/theairdemon/musicgenerator/blob/master/Version 4 (dev)/Genres/RhythmInfo.py"
click node_v4_structinfo "https://github.com/theairdemon/musicgenerator/blob/master/Version 4 (dev)/Genres/StructureInfo.py"
click node_v4_midiinfo "https://github.com/theairdemon/musicgenerator/blob/master/Version 4 (dev)/Genres/MidiInfo.py"
click node_v4_app "https://github.com/theairdemon/musicgenerator/tree/master/Version 4 (dev)/musicgeneratorapp"
click node_v3_songgen "https://github.com/theairdemon/musicgenerator/blob/master/Version 3 (stable)/SongGen.py"
click node_v2_notebook "https://github.com/theairdemon/musicgenerator/blob/master/Version 2 (deprecated)/Song Generator.ipynb"
click node_v1_legacy "https://github.com/theairdemon/musicgenerator/tree/master/Version 1 (deprecated)"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_v4_runsonggen,node_v4_songgen,node_v4_chords,node_v4_harmony,node_v4_melody,node_v4_rhythm,node_v4_drums,node_v4_midi toneBlue
class node_v4_definegenre,node_v4_gendefs,node_v4_melinfo,node_v4_rhyinfo,node_v4_structinfo,node_v4_midiinfo toneAmber
class node_v4_app toneMint
class node_v3_songgen,node_v2_notebook,node_v1_legacy toneRose
```

## Components

### Version 4 Core

Active Python generation pipeline.

- [RunSongGen.py](https://github.com/theairdemon/musicgenerator/blob/HEAD/Version%204%20(dev)/RunSongGen.py): entrypoint · Command-line entrypoint for starting generation. · `Version 4 (dev)/RunSongGen.py`
- [SongGen.py](https://github.com/theairdemon/musicgenerator/blob/HEAD/Version%204%20(dev)/SongGen.py): orchestrator · Main generator coordinator for Version 4. · `Version 4 (dev)/SongGen.py`
- [Chords](https://github.com/theairdemon/musicgenerator/blob/HEAD/Version%204%20(dev)/Generators/GenChords.py): music-stage · Builds chord progressions. · `Version 4 (dev)/Generators/GenChords.py`
- [Harmony](https://github.com/theairdemon/musicgenerator/blob/HEAD/Version%204%20(dev)/Generators/GenHarmony.py): music-stage · Adds harmonic parts and voicings. · `Version 4 (dev)/Generators/GenHarmony.py`
- [Melody](https://github.com/theairdemon/musicgenerator/blob/HEAD/Version%204%20(dev)/Generators/GenMelody.py): music-stage · Generates lead melody lines. · `Version 4 (dev)/Generators/GenMelody.py`
- [Rhythm](https://github.com/theairdemon/musicgenerator/blob/HEAD/Version%204%20(dev)/Generators/GenRhythm.py): music-stage · Creates rhythmic patterns and timing. · `Version 4 (dev)/Generators/GenRhythm.py`
- [Drums](https://github.com/theairdemon/musicgenerator/blob/HEAD/Version%204%20(dev)/Generators/GenDrums.py): music-stage · Generates percussion parts. · `Version 4 (dev)/Generators/GenDrums.py`
- [GenMidi.py](https://github.com/theairdemon/musicgenerator/blob/HEAD/Version%204%20(dev)/Generators/GenMidi.py): artifact-export · Assembles and writes MIDI output. · `Version 4 (dev)/Generators/GenMidi.py`

### Version 4 Genres

Genre presets and parameter definitions.

- [DefineGenre.py](https://github.com/theairdemon/musicgenerator/blob/HEAD/Version%204%20(dev)/Genres/DefineGenre.py): genre-router · Selects or resolves genre configuration. · `Version 4 (dev)/Genres/DefineGenre.py`
- [Genre defs](https://github.com/theairdemon/musicgenerator/tree/HEAD/Version%204%20(dev)/Genres/GenreDefinitions): genre-presets · Concrete genre rule sets and templates. · `Version 4 (dev)/Genres/GenreDefinitions`
- [MelodyInfo](https://github.com/theairdemon/musicgenerator/blob/HEAD/Version%204%20(dev)/Genres/MelodyInfo.py): genre-params · Melody constraints and metadata. · `Version 4 (dev)/Genres/MelodyInfo.py`
- [RhythmInfo](https://github.com/theairdemon/musicgenerator/blob/HEAD/Version%204%20(dev)/Genres/RhythmInfo.py): genre-params · Rhythm constraints and metadata. · `Version 4 (dev)/Genres/RhythmInfo.py`
- [StructureInfo](https://github.com/theairdemon/musicgenerator/blob/HEAD/Version%204%20(dev)/Genres/StructureInfo.py): genre-params · Song structure templates and metadata. · `Version 4 (dev)/Genres/StructureInfo.py`
- [MidiInfo](https://github.com/theairdemon/musicgenerator/blob/HEAD/Version%204%20(dev)/Genres/MidiInfo.py): genre-params · MIDI-oriented configuration metadata. · `Version 4 (dev)/Genres/MidiInfo.py`

### Version 4 UI

Godot playback and interaction layer.

- [Godot app](https://github.com/theairdemon/musicgenerator/tree/HEAD/Version%204%20(dev)/musicgeneratorapp): ui-client · User-facing playback and control shell. · `Version 4 (dev)/musicgeneratorapp`

### History

Deprecated and stable predecessors.

- [V3 SongGen](https://github.com/theairdemon/musicgenerator/blob/HEAD/Version%203%20(stable)/SongGen.py): stable-gen · Previous compact stable Python generator. · `Version 3 (stable)/SongGen.py`
- [V2 notebook](https://github.com/theairdemon/musicgenerator/blob/HEAD/Version%202%20(deprecated)/Song%20Generator.ipynb): prototype · Notebook-era prototype generation workflow. · `Version 2 (deprecated)/Song Generator.ipynb`
- [V1 legacy](https://github.com/theairdemon/musicgenerator/tree/HEAD/Version%201%20(deprecated)): legacy-core · Early note/sound-centric generation and playback code. · `Version 1 (deprecated)`

## Connections

- RunSongGen.py → SongGen.py: starts · CLI entrypoint launches the orchestrator.
- SongGen.py → DefineGenre.py: loads · Orchestrator resolves genre configuration.
- DefineGenre.py → Genre defs: selects · Genre router chooses a concrete preset.
- Genre defs → MelodyInfo: feeds · Genre presets populate melody constraints.
- Genre defs → RhythmInfo: feeds · Genre presets populate rhythm constraints.
- Genre defs → StructureInfo: feeds · Genre presets populate song structure.
- Genre defs → MidiInfo: feeds · Genre presets populate MIDI settings.
- SongGen.py → Chords: drives · Core orchestration starts harmonic construction.
- Chords → Harmony: extends · Chord material is elaborated into harmony.
- RhythmInfo → Rhythm: constrains · Rhythm parameters shape rhythmic generation.
- MelodyInfo → Melody: constrains · Melody parameters shape melodic generation.
- StructureInfo → SongGen.py: shapes · Structure metadata influences orchestration.
- Rhythm → Drums: supports · Rhythmic patterns inform percussion generation.
- SongGen.py → Melody: drives · Orchestrator coordinates melodic generation.
- SongGen.py → Rhythm: drives · Orchestrator coordinates rhythmic generation.
- SongGen.py → Drums: drives · Orchestrator coordinates drum generation.
- Chords → GenMidi.py: exports · Generated musical parts are assembled into MIDI.
- Harmony → GenMidi.py: exports · Harmony is written into the MIDI artifact.
- Melody → GenMidi.py: exports · Melody is written into the MIDI artifact.
- Rhythm → GenMidi.py: exports · Rhythmic data is written into the MIDI artifact.
- Drums → GenMidi.py: exports · Drum tracks are written into the MIDI artifact.
- GenMidi.py → Godot app: plays · Generated MIDI can be consumed by the Godot frontend.
- SongGen.py → V3 SongGen: evolved from · Version 4 grows out of the stable single-file generator.
- V3 SongGen → V2 notebook: evolved from · Stable script follows the notebook prototype.
- V2 notebook → V1 legacy: evolved from · Notebook prototype grew from early legacy code.