# yatingmusic/remi architecture

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

- Interactive diagram: https://gitdiagram.com/yatingmusic/remi
- Repository: https://github.com/yatingmusic/remi

## Overview

##### Project type and purpose
- This is a research-oriented machine-learning pipeline for symbolic music generation. It is neither a web app nor a full-stack service; instead it’s an open-source toolkit that:
- Reads raw MIDI files
- Converts them into a custom, text-like token representation (“REMI”)
- Trains or fine-tunes a Transformer-XL model on those tokens
- Generates new (or continuation) MIDI sequences from the trained model

##### File structure
Top-level files and directories:
- chord_recognition.py – optional script for chord analysis of MIDI
- finetune.py – script to fine-tune the Transformer model on new data
- main.py – generation example (from scratch and continuation)
- midi2remi.ipynb – notebook showing how to convert MIDI to REMI tokens
- model.py – definition of PopMusicTransformer class (load, generate, close)
- modules.py – Transformer-XL core modules borrowed from kimiyoung/transformer-xl
- utils.py – helper functions (e.g., data loading, token mapping)
- result/ – folder to hold generated MIDI outputs

Patterns and indicators:
- A clear data-processing pipeline: MIDI → REMI tokens → model input
- Two main workflows: training/finetuning (finetune.py) vs. inference/generation (main.py)
- Separation of concerns: “modules.py” for architecture, “model.py” for orchestration

##### Key insights from the README
- REMI provides a metrical context for rhythm and harmony.
- Underlying model: Transformer-XL (tensorflow-gpu 1.14.0).
- External library: miditoolkit for MIDI parsing.
- Two checkpoints provided for inference (“tempo” only and “tempo+chord”).
- Data directories (not in this distribution) house train/evaluation MIDI files.
- Generation parameters: n_target_bar, temperature, top_k sampling.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Ingestion Layer
    subgraph "Data Ingestion Layer"
        RawMIDI["Raw MIDI Files"]:::data
        Parser["MIDI Parser (miditoolkit)"]:::data
    end
    RawMIDI --> Parser
    click Parser "https://github.com/yatingmusic/remi/blob/master/utils.py"

    Chord["Chord Analysis Script (optional)"]:::data
    Parser --> Chord
    click Chord "https://github.com/yatingmusic/remi/blob/master/chord_recognition.py"

    %% Conversion Module
    subgraph "Conversion Module"
        Notebook["Notebook: MIDI→REMI"]:::conversion
        REUintils["REMI Encoder (utils.py)"]:::conversion
        REMITokens["REMI Token Sequences"]:::data
    end
    Parser --> Notebook
    Notebook --> REUintils
    REUintils --> REMITokens
    click Notebook "https://github.com/yatingmusic/remi/blob/master/midi2remi.ipynb"
    click REUintils "https://github.com/yatingmusic/remi/blob/master/utils.py"

    %% Model Layer
    subgraph "Model Layer"
        Core["Transformer-XL Core (modules.py)"]:::model
        Orchestrator["PopMusicTransformer (model.py)"]:::model
    end
    REMITokens --> Core
    Core --> Orchestrator
    click Core "https://github.com/yatingmusic/remi/blob/master/modules.py"
    click Orchestrator "https://github.com/yatingmusic/remi/blob/master/model.py"

    %% Training/Fine-tuning Workflow
    subgraph "Training/Fine-tuning"
        Trainer["Training/Fine-tuning (finetune.py)"]:::model
        Checkpoints["Model Checkpoints"]:::storage
    end
    Orchestrator --> Trainer
    Trainer --> Checkpoints
    click Trainer "https://github.com/yatingmusic/remi/blob/master/finetune.py"

    %% Inference/Generation Workflow
    subgraph "Inference/Generation"
        Params["Generation Parameters\n(top_k, temperature, n_target_bar)"]:::inference
        Generator["Inference/Generation (main.py)"]:::inference
        GeneratedRaw["Generated MIDI (.midi)"]:::data
    end
    Checkpoints --> Generator
    Params --> Generator
    Generator --> GeneratedRaw
    click Generator "https://github.com/yatingmusic/remi/blob/master/main.py"

    %% Output Storage
    subgraph "Output Storage"
        Results["Storage: result/"]:::storage
    end
    GeneratedRaw --> Results
    click Results "https://github.com/yatingmusic/remi/tree/master/result/"

    %% Optional Audio Playback
    subgraph "Audio Playback"
        DAW["DAW / FluidSynth + SoundFont"]:::external
    end
    GeneratedRaw --> DAW

    classDef data fill:#ADD8E6,stroke:#333;
    classDef conversion fill:#90EE90,stroke:#333;
    classDef model fill:#FFA500,stroke:#333;
    classDef inference fill:#DA70D6,stroke:#333;
    classDef storage fill:#D3D3D3,stroke:#333;
    classDef external fill:#DCDCDC,stroke:#333;
```
