# cb-42/annoteator architecture

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

- Interactive diagram: https://gitdiagram.com/cb-42/annoteator
- Repository: https://github.com/cb-42/annoteator

## Overview

AnNOTEators is a drum-audio transcription project: users provide a local recording or YouTube link and receive drum notation, optionally as PDF. The CLI coordinates downloading, drum separation, onset framing, neural drum-hit prediction, and notation generation; the README also documents notebook use and custom model development. The graph includes the documented training-data preparation and augmentation branch. Edges reflect calls visible in excerpts or README workflow statements; unsampled internals are not inferred.

Main entry points: [`main.py`](https://github.com/cb-42/annoteator/blob/main/main.py) (CLI workflow), [`model_development/data_preparation.py`](https://github.com/cb-42/annoteator/blob/main/model_development/data_preparation.py) (Data preparation), [`inference/prediction.py`](https://github.com/cb-42/annoteator/blob/main/inference/prediction.py) (Drum-hit prediction), [`inference/input_transform.py`](https://github.com/cb-42/annoteator/blob/main/inference/input_transform.py) (Drum separation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_transcription["Transcription workflow"]
  node_cli["CLI workflow<br/>[main.py]"]
  node_download["Audio download<br/>[input_transform.py]"]
  node_separation["Drum separation<br/>[input_transform.py]"]
  node_framing["Onset framing<br/>[input_transform.py]"]
  node_prediction["Drum-hit prediction<br/>[prediction.py]"]
  node_models["Pretrained networks"]
  node_notation["Notation generation<br/>[transcriber.py]"]
end

subgraph group_training["Model development"]
  node_egmd[("E-GMD dataset<br/>[e-gmd-v1.0.0]")]
  node_preparation["Data preparation"]
  node_augmentation["Audio augmentation<br/>[augment_audio.py]"]
end

node_musician(("Musician"))
node_youtube["YouTube source"]
node_audio["Audio file"]
node_sheet["Drum sheet music"]
node_training_user(("Data scientist"))
node_training_output["Prepared training data"]

node_musician -->|"provides input"| node_cli
node_cli -->|"downloads link"| node_download
node_youtube -->|"supplies audio"| node_download
node_cli -->|"uses local file"| node_audio
node_cli -->|"calls"| node_separation
node_separation -->|"reads"| node_audio
node_cli -->|"calls"| node_framing
node_framing -->|"frames drum track"| node_separation
node_cli -->|"calls"| node_prediction
node_prediction -->|"loads network"| node_models
node_prediction -->|"predicts framed clips"| node_framing
node_cli -->|"calls"| node_notation
node_notation -->|"constructs notation"| node_sheet
node_cli -->|"exports"| node_sheet
node_training_user -->|"prepares data"| node_preparation
node_egmd -->|"provides paired data"| node_preparation
node_preparation -->|"applies augmentations"| node_augmentation
node_preparation -->|"creates clips"| node_training_output
node_augmentation -.->|"augments clips"| node_training_output

click node_cli "https://github.com/cb-42/annoteator/blob/main/main.py"
click node_download "https://github.com/cb-42/annoteator/blob/main/inference/input_transform.py"
click node_separation "https://github.com/cb-42/annoteator/blob/main/inference/input_transform.py"
click node_framing "https://github.com/cb-42/annoteator/blob/main/inference/input_transform.py"
click node_prediction "https://github.com/cb-42/annoteator/blob/main/inference/prediction.py"
click node_models "https://github.com/cb-42/annoteator/tree/main/inference/pretrained_models"
click node_notation "https://github.com/cb-42/annoteator/blob/main/inference/transcriber.py"
click node_egmd "https://github.com/cb-42/annoteator/tree/main/dataset/e-gmd-v1.0.0/e-gmd-v1.0.0"
click node_preparation "https://github.com/cb-42/annoteator/blob/main/model_development/data_preparation.py"
click node_augmentation "https://github.com/cb-42/annoteator/blob/main/model_development/augment_audio.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_cli,node_download,node_separation,node_framing,node_prediction,node_models,node_notation toneBlue
class node_egmd,node_preparation,node_augmentation toneAmber
class node_musician,node_youtube,node_audio,node_sheet,node_training_user,node_training_output toneIndigo
```

## Components

### Transcription workflow

- [CLI workflow](https://github.com/cb-42/annoteator/blob/main/main.py): `main.py`
- [Audio download](https://github.com/cb-42/annoteator/blob/main/inference/input_transform.py): `inference/input_transform.py`
- [Drum separation](https://github.com/cb-42/annoteator/blob/main/inference/input_transform.py): `inference/input_transform.py`
- [Onset framing](https://github.com/cb-42/annoteator/blob/main/inference/input_transform.py): `inference/input_transform.py`
- [Drum-hit prediction](https://github.com/cb-42/annoteator/blob/main/inference/prediction.py): `inference/prediction.py`
- [Pretrained networks](https://github.com/cb-42/annoteator/tree/main/inference/pretrained_models): `inference/pretrained_models`
- [Notation generation](https://github.com/cb-42/annoteator/blob/main/inference/transcriber.py): `inference/transcriber.py`

### Model development

- [E-GMD dataset](https://github.com/cb-42/annoteator/tree/main/dataset/e-gmd-v1.0.0/e-gmd-v1.0.0): `dataset/e-gmd-v1.0.0/e-gmd-v1.0.0`
- [Data preparation](https://github.com/cb-42/annoteator/blob/main/model_development/data_preparation.py): `model_development/data_preparation.py`
- [Audio augmentation](https://github.com/cb-42/annoteator/blob/main/model_development/augment_audio.py): `model_development/augment_audio.py`

### Other components

- **Musician**
- **YouTube source**
- **Audio file**
- **Drum sheet music**
- **Data scientist**
- **Prepared training data**

## Connections

- Musician → CLI workflow: provides input (evidence: `README.md`)
- CLI workflow → Audio download: downloads link (evidence: `main.py`)
- YouTube source → Audio download: supplies audio (evidence: `README.md`)
- CLI workflow → Audio file: uses local file (evidence: `main.py`)
- CLI workflow → Drum separation: calls (evidence: `main.py`)
- Drum separation → Audio file: reads (evidence: `inference/input_transform.py`)
- CLI workflow → Onset framing: calls (evidence: `main.py`)
- Onset framing → Drum separation: frames drum track (evidence: `README.md`)
- CLI workflow → Drum-hit prediction: calls (evidence: `main.py`)
- Drum-hit prediction → Pretrained networks: loads network (evidence: `inference/prediction.py`)
- Drum-hit prediction → Onset framing: predicts framed clips (evidence: `inference/prediction.py`)
- CLI workflow → Notation generation: calls (evidence: `main.py`)
- Notation generation → Drum sheet music: constructs notation (evidence: `README.md`)
- CLI workflow → Drum sheet music: exports (evidence: `main.py`)
- Data scientist → Data preparation: prepares data (evidence: `README.md`)
- E-GMD dataset → Data preparation: provides paired data (evidence: `README.md`)
- Data preparation → Audio augmentation: applies augmentations (evidence: `model_development/data_preparation.py`)
- Data preparation → Prepared training data: creates clips (evidence: `README.md`)
- Audio augmentation → Prepared training data: augments clips