# sweetcocoa/pop2piano architecture

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

- Interactive diagram: https://gitdiagram.com/sweetcocoa/pop2piano
- Repository: https://github.com/sweetcocoa/pop2piano

## Overview

Pop2Piano generates piano-cover MIDI from pop audio, with inference as the user-to-result path: a user runs test-set inference, which loads each sample, invokes the generation wrapper, and saves composer-specific MIDI. Its dataset workflow downloads media and preprocesses beat timing, quantized MIDI, and aligned audio; evaluation measures generated melody accuracy. The graph includes documented but unsampled preprocessing branches by directory path; relationships for those branches are omitted where source evidence does not establish calls.

Main entry points: [`transformer_wrapper.py`](https://github.com/sweetcocoa/pop2piano/blob/main/transformer_wrapper.py) (Transformer Generation), [`preprocess/bpm_quantize.py`](https://github.com/sweetcocoa/pop2piano/blob/main/preprocess/bpm_quantize.py) (Tempo Quantization), [`evaluate/inference_testset.py`](https://github.com/sweetcocoa/pop2piano/blob/main/evaluate/inference_testset.py) (Test-set Inference), [`midiaudiopair.py`](https://github.com/sweetcocoa/pop2piano/blob/main/midiaudiopair.py) (Sample Metadata)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_generation["Cover Generation"]
  node_inference["Test-set Inference"]
  node_wrapper["Transformer Generation"]
  node_tokenizer["MIDI Tokenizer<br/>[midi_tokenizer.py]"]
  node_audio_input["Audio Features<br/>[input.py]"]
  node_generated_midi["Generated MIDI"]
end

subgraph group_dataset["Dataset Preparation"]
  node_downloader["Media Downloader<br/>[download.py]"]
  node_media["Original Media"]
  node_beat_quantizer["Beat Quantization<br/>[beat_quantizer.py]"]
  node_bpm_quantize["Tempo Quantization<br/>[bpm_quantize.py]"]
  node_alignment["Audio-MIDI Alignment<br/>[pop_align.py]"]
  node_spleeter["Stem Separation<br/>[split_spleeter.py]"]
  node_preprocess_accuracy["Melody Accuracy Prep<br/>[melody_accuracy.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_evaluation_runner["Test-set Evaluation"]
  node_accuracy["Melody Accuracy"]
end

subgraph group_shared["Shared Data and DSP"]
  node_sample["Sample Metadata<br/>[midiaudiopair.py]"]
  node_dsp["Audio DSP<br/>[dsp.py]"]
  node_beat_features["Beat Features"]
end

node_user(("User"))

node_user -->|"runs"| node_inference
node_inference -->|"loads sample"| node_sample
node_inference -->|"invokes generation"| node_wrapper
node_wrapper -->|"writes MIDI"| node_generated_midi
node_wrapper -->|"uses tokens"| node_tokenizer
node_wrapper -->|"uses features"| node_audio_input
node_wrapper -->|"uses beat quantization"| node_beat_quantizer
node_wrapper -->|"uses DSP"| node_dsp
node_user -->|"runs downloader"| node_downloader
node_downloader -.->|"downloads media"| node_media
node_bpm_quantize -->|"loads sample"| node_sample
node_bpm_quantize -->|"extracts and quantizes"| node_beat_quantizer
node_bpm_quantize -->|"mixes audio"| node_dsp
node_bpm_quantize -->|"saves beat data"| node_beat_features
node_alignment -->|"loads sample"| node_sample
node_alignment -->|"uses audio helpers"| node_dsp
node_evaluation_runner -->|"loads sample"| node_sample
node_evaluation_runner -->|"scores melody"| node_accuracy
node_inference -->|"evaluates melody"| node_accuracy

click node_inference "https://github.com/sweetcocoa/pop2piano/blob/main/evaluate/inference_testset.py"
click node_wrapper "https://github.com/sweetcocoa/pop2piano/blob/main/transformer_wrapper.py"
click node_tokenizer "https://github.com/sweetcocoa/pop2piano/blob/main/midi_tokenizer.py"
click node_audio_input "https://github.com/sweetcocoa/pop2piano/blob/main/layer/input.py"
click node_sample "https://github.com/sweetcocoa/pop2piano/blob/main/midiaudiopair.py"
click node_downloader "https://github.com/sweetcocoa/pop2piano/blob/main/download/download.py"
click node_beat_quantizer "https://github.com/sweetcocoa/pop2piano/blob/main/preprocess/beat_quantizer.py"
click node_bpm_quantize "https://github.com/sweetcocoa/pop2piano/blob/main/preprocess/bpm_quantize.py"
click node_alignment "https://github.com/sweetcocoa/pop2piano/blob/main/preprocess/pop_align.py"
click node_spleeter "https://github.com/sweetcocoa/pop2piano/blob/main/preprocess/split_spleeter.py"
click node_preprocess_accuracy "https://github.com/sweetcocoa/pop2piano/blob/main/preprocess/melody_accuracy.py"
click node_evaluation_runner "https://github.com/sweetcocoa/pop2piano/blob/main/evaluate/evaluate_testset.py"
click node_accuracy "https://github.com/sweetcocoa/pop2piano/blob/main/evaluate/midi_melody_accuracy.py"
click node_dsp "https://github.com/sweetcocoa/pop2piano/blob/main/utils/dsp.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_inference,node_wrapper,node_tokenizer,node_audio_input,node_generated_midi,node_user toneBlue
class node_downloader,node_media,node_beat_quantizer,node_bpm_quantize,node_alignment,node_spleeter,node_preprocess_accuracy toneAmber
class node_evaluation_runner,node_accuracy toneMint
class node_sample,node_dsp,node_beat_features toneRose
```

## Components

### Cover Generation

- [Test-set Inference](https://github.com/sweetcocoa/pop2piano/blob/main/evaluate/inference_testset.py): `evaluate/inference_testset.py`
- [Transformer Generation](https://github.com/sweetcocoa/pop2piano/blob/main/transformer_wrapper.py): `transformer_wrapper.py`
- [MIDI Tokenizer](https://github.com/sweetcocoa/pop2piano/blob/main/midi_tokenizer.py): `midi_tokenizer.py`
- [Audio Features](https://github.com/sweetcocoa/pop2piano/blob/main/layer/input.py): `layer/input.py`
- **Generated MIDI**

### Dataset Preparation

- [Media Downloader](https://github.com/sweetcocoa/pop2piano/blob/main/download/download.py): `download/download.py`
- **Original Media**
- [Beat Quantization](https://github.com/sweetcocoa/pop2piano/blob/main/preprocess/beat_quantizer.py): `preprocess/beat_quantizer.py`
- [Tempo Quantization](https://github.com/sweetcocoa/pop2piano/blob/main/preprocess/bpm_quantize.py): `preprocess/bpm_quantize.py`
- [Audio-MIDI Alignment](https://github.com/sweetcocoa/pop2piano/blob/main/preprocess/pop_align.py): `preprocess/pop_align.py`
- [Stem Separation](https://github.com/sweetcocoa/pop2piano/blob/main/preprocess/split_spleeter.py): `preprocess/split_spleeter.py`
- [Melody Accuracy Prep](https://github.com/sweetcocoa/pop2piano/blob/main/preprocess/melody_accuracy.py): `preprocess/melody_accuracy.py`

### Evaluation

- [Test-set Evaluation](https://github.com/sweetcocoa/pop2piano/blob/main/evaluate/evaluate_testset.py): `evaluate/evaluate_testset.py`
- [Melody Accuracy](https://github.com/sweetcocoa/pop2piano/blob/main/evaluate/midi_melody_accuracy.py): `evaluate/midi_melody_accuracy.py`

### Shared Data and DSP

- [Sample Metadata](https://github.com/sweetcocoa/pop2piano/blob/main/midiaudiopair.py): `midiaudiopair.py`
- [Audio DSP](https://github.com/sweetcocoa/pop2piano/blob/main/utils/dsp.py): `utils/dsp.py`
- **Beat Features**

### Other components

- **User**

## Connections

- User → Test-set Inference: runs (evidence: `evaluate/inference_testset.py`)
- Test-set Inference → Sample Metadata: loads sample (evidence: `evaluate/inference_testset.py`)
- Test-set Inference → Transformer Generation: invokes generation (evidence: `evaluate/inference_testset.py`)
- Transformer Generation → Generated MIDI: writes MIDI
- Transformer Generation → MIDI Tokenizer: uses tokens (evidence: `transformer_wrapper.py`)
- Transformer Generation → Audio Features: uses features (evidence: `transformer_wrapper.py`)
- Transformer Generation → Beat Quantization: uses beat quantization (evidence: `transformer_wrapper.py`)
- Transformer Generation → Audio DSP: uses DSP (evidence: `transformer_wrapper.py`)
- User → Media Downloader: runs downloader (evidence: `README.md`)
- Media Downloader → Original Media: downloads media
- Tempo Quantization → Sample Metadata: loads sample (evidence: `preprocess/bpm_quantize.py`)
- Tempo Quantization → Beat Quantization: extracts and quantizes (evidence: `preprocess/bpm_quantize.py`)
- Tempo Quantization → Audio DSP: mixes audio (evidence: `preprocess/bpm_quantize.py`)
- Tempo Quantization → Beat Features: saves beat data (evidence: `preprocess/bpm_quantize.py`)
- Audio-MIDI Alignment → Sample Metadata: loads sample (evidence: `preprocess/pop_align.py`)
- Audio-MIDI Alignment → Audio DSP: uses audio helpers (evidence: `preprocess/pop_align.py`)
- Test-set Evaluation → Sample Metadata: loads sample (evidence: `evaluate/evaluate_testset.py`)
- Test-set Evaluation → Melody Accuracy: scores melody (evidence: `evaluate/evaluate_testset.py`)
- Test-set Inference → Melody Accuracy: evaluates melody (evidence: `evaluate/inference_testset.py`)
