# openvpi/game architecture

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

- Interactive diagram: https://gitdiagram.com/openvpi/game
- Repository: https://github.com/openvpi/game

## Overview

GAME transcribes singing audio into note sequences and MIDI/text, and can align predictions to labeled word boundaries. Its inference workflow runs through the inference API, producing model predictions that are decoded and optionally aligned or exported. Separate dataset preprocessing and model-training workflows prepare indexed features and train the model; evaluation and model export support those workflows. The README documents these capabilities, but sampled source is incomplete, so links between several API subsystems are intentionally omitted where ownership cannot be confirmed.

Main entry points: [`inference/api.py`](https://github.com/openvpi/game/blob/main/inference/api.py) (Inference API), [`training/api.py`](https://github.com/openvpi/game/blob/main/training/api.py) (Training API), [`inference/me_infer_module.py`](https://github.com/openvpi/game/blob/main/inference/me_infer_module.py) (Inference module), [`infer.py`](https://github.com/openvpi/game/blob/main/infer.py) (Inference command)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inference["Inference"]
  node_infer_cli["Inference command<br/>[infer.py]"]
  node_inference_api["Inference API<br/>[api.py]"]
  node_inference_data["Inference data<br/>[data.py]"]
  node_inference_engine["Inference engine<br/>[me_infer.py]"]
  node_inference_module["Inference module<br/>[me_infer_module.py]"]
  node_alignment["Word-note alignment<br/>[api.py]"]
  node_output_callbacks["Result writers<br/>[callbacks.py]"]
end

subgraph group_model["Model"]
  node_decoder["Boundary and pitch decoding<br/>[decoding.py]"]
  node_backbone["Adaptive backbone"]
  node_diffusion["Discrete diffusion<br/>[d3pm.py]"]
end

subgraph group_data["Data and training"]
  node_binarize_cli["Binarization command<br/>[binarize.py]"]
  node_preprocessing_api["Preprocessing API<br/>[api.py]"]
  node_notes_binarizer["Notes binarizer<br/>[notes_binarizer.py]"]
  node_indexed_dataset[("Indexed dataset<br/>[indexed_dataset.py]")]
  node_training_cli["Training command<br/>[train.py]"]
  node_training_api["Training API<br/>[api.py]"]
  node_training_module["Training module<br/>[me_module.py]"]
end

subgraph group_deployment["Evaluation and export"]
  node_evaluate_cli["Evaluation command<br/>[evaluate.py]"]
  node_deployment_api["Deployment API<br/>[api.py]"]
  node_exporter["Model exporter<br/>[exporter.py]"]
end

node_user(("Audio or dataset user"))
node_audio["Audio files"]
node_transcriptions["Labeled transcriptions"]
node_results["MIDI and text results"]
node_model_file["Model checkpoint"]

node_user -->|"runs"| node_infer_cli
node_infer_cli -->|"dispatches"| node_inference_api
node_user -->|"provides"| node_audio
node_user -.->|"provides"| node_transcriptions
node_inference_api -->|"loads inputs"| node_inference_data
node_inference_api -->|"invokes"| node_inference_engine
node_inference_engine -->|"runs model"| node_inference_module
node_inference_module -->|"computes features"| node_backbone
node_inference_module -->|"predicts boundaries"| node_diffusion
node_inference_api -->|"decodes predictions"| node_decoder
node_inference_api -.->|"aligns notes"| node_alignment
node_inference_api -->|"dispatches results"| node_output_callbacks
node_output_callbacks -->|"writes"| node_results
node_binarize_cli -->|"dispatches"| node_preprocessing_api
node_preprocessing_api -->|"processes notes"| node_notes_binarizer
node_notes_binarizer -->|"writes samples"| node_indexed_dataset
node_user -->|"runs"| node_training_cli
node_training_cli -->|"dispatches"| node_training_api
node_training_api -->|"loads samples"| node_indexed_dataset
node_training_api -->|"trains"| node_training_module
node_training_module -->|"optimizes"| node_backbone
node_training_api -->|"saves checkpoint"| node_model_file
node_user -->|"runs"| node_evaluate_cli
node_evaluate_cli -->|"dispatches"| node_deployment_api
node_user -->|"selects model"| node_model_file
node_deployment_api -->|"exports model"| node_exporter

click node_infer_cli "https://github.com/openvpi/game/blob/main/infer.py"
click node_inference_api "https://github.com/openvpi/game/blob/main/inference/api.py"
click node_inference_data "https://github.com/openvpi/game/blob/main/inference/data.py"
click node_inference_engine "https://github.com/openvpi/game/blob/main/inference/me_infer.py"
click node_inference_module "https://github.com/openvpi/game/blob/main/inference/me_infer_module.py"
click node_decoder "https://github.com/openvpi/game/blob/main/modules/decoding.py"
click node_backbone "https://github.com/openvpi/game/blob/main/modules/backbones/ebf_with_joint_attention.py"
click node_diffusion "https://github.com/openvpi/game/blob/main/modules/d3pm.py"
click node_alignment "https://github.com/openvpi/game/blob/main/inference/api.py"
click node_output_callbacks "https://github.com/openvpi/game/blob/main/inference/callbacks.py"
click node_binarize_cli "https://github.com/openvpi/game/blob/main/binarize.py"
click node_preprocessing_api "https://github.com/openvpi/game/blob/main/preprocessing/api.py"
click node_notes_binarizer "https://github.com/openvpi/game/blob/main/preprocessing/notes_binarizer.py"
click node_indexed_dataset "https://github.com/openvpi/game/blob/main/lib/indexed_dataset.py"
click node_training_cli "https://github.com/openvpi/game/blob/main/train.py"
click node_training_api "https://github.com/openvpi/game/blob/main/training/api.py"
click node_training_module "https://github.com/openvpi/game/blob/main/training/me_module.py"
click node_evaluate_cli "https://github.com/openvpi/game/blob/main/evaluate.py"
click node_deployment_api "https://github.com/openvpi/game/blob/main/deployment/api.py"
click node_exporter "https://github.com/openvpi/game/blob/main/deployment/exporter.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_infer_cli,node_inference_api,node_inference_data,node_inference_engine,node_inference_module,node_alignment,node_output_callbacks,node_user toneBlue
class node_decoder,node_backbone,node_diffusion toneAmber
class node_binarize_cli,node_preprocessing_api,node_notes_binarizer,node_indexed_dataset,node_training_cli,node_training_api,node_training_module toneMint
class node_evaluate_cli,node_deployment_api,node_exporter toneRose
class node_audio,node_transcriptions,node_results,node_model_file toneIndigo
```

## Components

### Inference

- [Inference command](https://github.com/openvpi/game/blob/main/infer.py): `infer.py`
- [Inference API](https://github.com/openvpi/game/blob/main/inference/api.py): `inference/api.py`
- [Inference data](https://github.com/openvpi/game/blob/main/inference/data.py): `inference/data.py`
- [Inference engine](https://github.com/openvpi/game/blob/main/inference/me_infer.py): `inference/me_infer.py`
- [Inference module](https://github.com/openvpi/game/blob/main/inference/me_infer_module.py): `inference/me_infer_module.py`
- [Word-note alignment](https://github.com/openvpi/game/blob/main/inference/api.py): `inference/api.py`
- [Result writers](https://github.com/openvpi/game/blob/main/inference/callbacks.py): `inference/callbacks.py`

### Model

- [Boundary and pitch decoding](https://github.com/openvpi/game/blob/main/modules/decoding.py): `modules/decoding.py`
- [Adaptive backbone](https://github.com/openvpi/game/blob/main/modules/backbones/ebf_with_joint_attention.py): `modules/backbones/ebf_with_joint_attention.py`
- [Discrete diffusion](https://github.com/openvpi/game/blob/main/modules/d3pm.py): `modules/d3pm.py`

### Data and training

- [Binarization command](https://github.com/openvpi/game/blob/main/binarize.py): `binarize.py`
- [Preprocessing API](https://github.com/openvpi/game/blob/main/preprocessing/api.py): `preprocessing/api.py`
- [Notes binarizer](https://github.com/openvpi/game/blob/main/preprocessing/notes_binarizer.py): `preprocessing/notes_binarizer.py`
- [Indexed dataset](https://github.com/openvpi/game/blob/main/lib/indexed_dataset.py): `lib/indexed_dataset.py`
- [Training command](https://github.com/openvpi/game/blob/main/train.py): `train.py`
- [Training API](https://github.com/openvpi/game/blob/main/training/api.py): `training/api.py`
- [Training module](https://github.com/openvpi/game/blob/main/training/me_module.py): `training/me_module.py`

### Evaluation and export

- [Evaluation command](https://github.com/openvpi/game/blob/main/evaluate.py): `evaluate.py`
- [Deployment API](https://github.com/openvpi/game/blob/main/deployment/api.py): `deployment/api.py`
- [Model exporter](https://github.com/openvpi/game/blob/main/deployment/exporter.py): `deployment/exporter.py`

### Other components

- **Audio or dataset user**
- **Audio files**
- **Labeled transcriptions**
- **MIDI and text results**
- **Model checkpoint**

## Connections

- Audio or dataset user → Inference command: runs
- Inference command → Inference API: dispatches
- Audio or dataset user → Audio files: provides
- Audio or dataset user → Labeled transcriptions: provides
- Inference API → Inference data: loads inputs
- Inference API → Inference engine: invokes
- Inference engine → Inference module: runs model
- Inference module → Adaptive backbone: computes features
- Inference module → Discrete diffusion: predicts boundaries
- Inference API → Boundary and pitch decoding: decodes predictions
- Inference API → Word-note alignment: aligns notes
- Inference API → Result writers: dispatches results
- Result writers → MIDI and text results: writes
- Binarization command → Preprocessing API: dispatches
- Preprocessing API → Notes binarizer: processes notes
- Notes binarizer → Indexed dataset: writes samples
- Audio or dataset user → Training command: runs
- Training command → Training API: dispatches
- Training API → Indexed dataset: loads samples
- Training API → Training module: trains
- Training module → Adaptive backbone: optimizes
- Training API → Model checkpoint: saves checkpoint
- Audio or dataset user → Evaluation command: runs
- Evaluation command → Deployment API: dispatches
- Audio or dataset user → Model checkpoint: selects model
- Deployment API → Model exporter: exports model