# craftycode121/musicgeneration architecture

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

- Interactive diagram: https://gitdiagram.com/craftycode121/musicgeneration
- Repository: https://github.com/craftycode121/musicgeneration

## Overview

MIDI Generator is a CLI-driven autoregressive piano-music system: it obtains and parses MAESTRO MIDI, trains a Transformer+CfC model to predict pitch, velocity, and duration, generates events from a seed, and exports them as MIDI and optionally WAV. It also supports checkpoint reuse and loss/audio analysis. The README documents data download and parsing modules that are absent from the supplied tree; their node is therefore left without a source path. The sampled files establish the main orchestration and model/training/export details.

Main entry points: [`main.py`](https://github.com/craftycode121/musicgeneration/blob/main/main.py) (Pipeline CLI), [`src/training/train.py`](https://github.com/craftycode121/musicgeneration/blob/main/src/training/train.py) (Training loop), [`src/export.py`](https://github.com/craftycode121/musicgeneration/blob/main/src/export.py) (MIDI and WAV export), [`src/training/loss.py`](https://github.com/craftycode121/musicgeneration/blob/main/src/training/loss.py) (Loss and optimizer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["CLI Workflow"]
  node_main["Pipeline CLI<br/>[main.py]"]
  node_maestro["MAESTRO ingest"]
end

subgraph group_learning["Model and Training"]
  node_params["Parameter init<br/>[params.py]"]
  node_dataset["Windowed dataset<br/>[dataset.py]"]
  node_trainer["Training loop<br/>[train.py]"]
  node_loss["Loss and optimizer<br/>[loss.py]"]
  node_model["Transformer + CfC<br/>[forward.py]"]
end

subgraph group_outputs["Generation and Output"]
  node_checkpoint["Checkpoint I/O<br/>[checkpoint.py]"]
  node_generator["Event generation<br/>[generate.py]"]
  node_export["MIDI and WAV export<br/>[export.py]"]
end

subgraph group_inspection["Analysis"]
  node_audio["Generated WAV"]
  node_audio_analysis["Audio analysis<br/>[audio_analysis.py]"]
  node_loss_plots["Loss plots<br/>[loss_curves.py]"]
end

node_user(("CLI user"))
node_fluidsynth["fluidsynth"]
node_audio_player["Local audio player"]

node_user -->|"chooses stage"| node_main
node_main -->|"downloads and parses"| node_maestro
node_main -->|"builds windows"| node_dataset
node_main -->|"initializes"| node_params
node_main -->|"starts training"| node_trainer
node_trainer -->|"batches data"| node_dataset
node_trainer -->|"updates and evaluates"| node_loss
node_loss -->|"computes predictions"| node_model
node_trainer -->|"returns best params and history"| node_main
node_main -->|"saves or loads"| node_checkpoint
node_main -->|"plots history"| node_loss_plots
node_main -->|"generates from seed"| node_generator
node_generator -->|"predicts next event"| node_model
node_main -->|"exports events"| node_export
node_export -.->|"renders MIDI"| node_fluidsynth
node_export -->|"writes WAV"| node_audio
node_main -->|"analyzes WAV"| node_audio_analysis
node_audio -->|"reads samples"| node_audio_analysis
node_main -.->|"requests playback"| node_audio_player

click node_main "https://github.com/craftycode121/musicgeneration/blob/main/main.py"
click node_params "https://github.com/craftycode121/musicgeneration/blob/main/src/model/params.py"
click node_dataset "https://github.com/craftycode121/musicgeneration/blob/main/src/training/dataset.py"
click node_trainer "https://github.com/craftycode121/musicgeneration/blob/main/src/training/train.py"
click node_loss "https://github.com/craftycode121/musicgeneration/blob/main/src/training/loss.py"
click node_model "https://github.com/craftycode121/musicgeneration/blob/main/src/model/forward.py"
click node_checkpoint "https://github.com/craftycode121/musicgeneration/blob/main/src/checkpoint.py"
click node_generator "https://github.com/craftycode121/musicgeneration/blob/main/src/generate.py"
click node_export "https://github.com/craftycode121/musicgeneration/blob/main/src/export.py"
click node_audio_analysis "https://github.com/craftycode121/musicgeneration/blob/main/src/analysis/audio_analysis.py"
click node_loss_plots "https://github.com/craftycode121/musicgeneration/blob/main/src/analysis/loss_curves.py"

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_main,node_maestro,node_user toneBlue
class node_params,node_dataset,node_trainer,node_loss,node_model toneAmber
class node_checkpoint,node_generator,node_export toneMint
class node_audio,node_audio_analysis,node_loss_plots toneRose
class node_fluidsynth,node_audio_player toneIndigo
```

## Components

### CLI Workflow

- [Pipeline CLI](https://github.com/craftycode121/musicgeneration/blob/main/main.py): `main.py`
- **MAESTRO ingest**

### Model and Training

- [Parameter init](https://github.com/craftycode121/musicgeneration/blob/main/src/model/params.py): `src/model/params.py`
- [Windowed dataset](https://github.com/craftycode121/musicgeneration/blob/main/src/training/dataset.py): `src/training/dataset.py`
- [Training loop](https://github.com/craftycode121/musicgeneration/blob/main/src/training/train.py): `src/training/train.py`
- [Loss and optimizer](https://github.com/craftycode121/musicgeneration/blob/main/src/training/loss.py): `src/training/loss.py`
- [Transformer + CfC](https://github.com/craftycode121/musicgeneration/blob/main/src/model/forward.py): `src/model/forward.py`

### Generation and Output

- [Checkpoint I/O](https://github.com/craftycode121/musicgeneration/blob/main/src/checkpoint.py): `src/checkpoint.py`
- [Event generation](https://github.com/craftycode121/musicgeneration/blob/main/src/generate.py): `src/generate.py`
- [MIDI and WAV export](https://github.com/craftycode121/musicgeneration/blob/main/src/export.py): `src/export.py`

### Analysis

- **Generated WAV**
- [Audio analysis](https://github.com/craftycode121/musicgeneration/blob/main/src/analysis/audio_analysis.py): `src/analysis/audio_analysis.py`
- [Loss plots](https://github.com/craftycode121/musicgeneration/blob/main/src/analysis/loss_curves.py): `src/analysis/loss_curves.py`

### Other components

- **CLI user**
- **fluidsynth**
- **Local audio player**

## Connections

- CLI user → Pipeline CLI: chooses stage
- Pipeline CLI → MAESTRO ingest: downloads and parses
- Pipeline CLI → Windowed dataset: builds windows
- Pipeline CLI → Parameter init: initializes
- Pipeline CLI → Training loop: starts training
- Training loop → Windowed dataset: batches data
- Training loop → Loss and optimizer: updates and evaluates
- Loss and optimizer → Transformer + CfC: computes predictions
- Training loop → Pipeline CLI: returns best params and history
- Pipeline CLI → Checkpoint I/O: saves or loads
- Pipeline CLI → Loss plots: plots history
- Pipeline CLI → Event generation: generates from seed
- Event generation → Transformer + CfC: predicts next event
- Pipeline CLI → MIDI and WAV export: exports events
- MIDI and WAV export → fluidsynth: renders MIDI
- MIDI and WAV export → Generated WAV: writes WAV
- Pipeline CLI → Audio analysis: analyzes WAV
- Generated WAV → Audio analysis: reads samples
- Pipeline CLI → Local audio player: requests playback