# dap-lab/4way-tabla-transcription architecture

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

- Interactive diagram: https://gitdiagram.com/dap-lab/4way-tabla-transcription
- Repository: https://github.com/dap-lab/4way-tabla-transcription

## Overview

1. **Repository purpose**
   - This repo is an offline ML pipeline for **tabla stroke transcription**: classifying strokes in audio into **Damped, Resonant treble, Resonant bass, Resonant both**.
   - It is organized around two paper-specific codebases: **`ismir_related`** (ISMIR 2021) and **`tismir_related`** (TISMIR 2023).

2. **Top-level split: training stack vs. inference/package-only stack**
   - **`ismir_related`** contains the full experimental workflow: data augmentation, training data creation, model training, evaluation, and transcription.
   - **`tismir_related`** is a lighter deployment-oriented package with **pretrained models**, normalization stats, utilities, and transcription code, but no augmentation/training scripts.

3. **Input data boundary**
   - The repo assumes a local **audio dataset** under `ismir_related/dataset`, plus curated **song lists** that define which recordings belong to each split or augmentation condition.
   - Separate `cv_folds` files define reproducible cross-validation and test partitions, so data splitting is explicit and not inferred at runtime.

4. **Augmentation subsystem**
   - `ismir_related/code/data-augmentation` provides standalone scripts for generating transformed audio variants and an accompanying `templates.npy`.
   - The generated examples in `audio-examples` and the songlists show that augmentation is treated as a preprocessing layer before classification, producing multiple derived datasets from the same original recordings.

5. **Training data preparation**
   - `make_train_data.py` and `make_test_data.py` are the bridge between raw/augmented audio and model-ready tensors or feature arrays.
   - `means_stds.npy` stores normalization statistics used to standardize features consistently during training and inference.

6. **Model training and evaluation**
   - `train.py` is the core training entry point.
   - `eval_cv.py` and `eval_test.py` separate **cross-validation assessment** from **held-out test evaluation**, indicating a research workflow where results are reported on both internal folds and a fixed test set.

7. **Inference / transcription path**
   - `transcribe.py` in both subprojects is the runtime entry point for classifying new audio.
   - It loads pretrained checkpoints from `saved_models`, applies the same normalization/feature logic from `utils.py`, and outputs stroke labels over the input audio stream.

8. **Model artifact layout**
   - The checkpoints are serialized as PyTorch `.pt` files under `saved_models`, so the architecture is built around **persisted neural network weights** rather than an online service.
   - In `ismir_related`, models are organized by class family under `1-way/B`, `1-way/D`, `1-way/RB`, `1-way/RT`, each with multiple numbered checkpoints, suggesting ensemble or fold-specific models.
   - `tismir_related/saved_models` similarly contains class-specific checkpoints for the later paper’s transcription setup.

9. **Reproducibility and experiment tracking**
   - Fixed fold files, song lists, saved normalization stats, and stored checkpoints make the repo reproducible without regenerating the full training corpus each time.
   - The repository therefore functions as an **experiment artifact bundle** as much as a codebase.

10. **How the major pieces connect**
   - **Raw tabla audio** → optional **augmentation** → **train/test data creation** → **model training** → **saved checkpoints + normalization stats** → **transcription/evaluation**.
   - The architecture is centered on this offline ML loop, with the TISMIR package representing the reusable inference slice of the larger ISMIR workflow.

Main entry points: [`ismir_related/code/stroke-classification/train.py`](https://github.com/dap-lab/4way-tabla-transcription/blob/main/ismir_related/code/stroke-classification/train.py) (Training), [`ismir_related/code/stroke-classification/make_train_data.py`](https://github.com/dap-lab/4way-tabla-transcription/blob/main/ismir_related/code/stroke-classification/make_train_data.py) (Data prep), [`ismir_related/code/stroke-classification/means_stds.npy`](https://github.com/dap-lab/4way-tabla-transcription/blob/main/ismir_related/code/stroke-classification/means_stds.npy) (Mean/std stats), [`tismir_related/transcribe.py`](https://github.com/dap-lab/4way-tabla-transcription/blob/main/tismir_related/transcribe.py) (Transcribe)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo_root["Repository"]
  node_raw_audio[("Tabla audio<br/>dataset")]
end

subgraph group_ismir["ISMIR workflow"]
  node_songlists["Song lists<br/>split manifests"]
  node_cv_folds["CV folds<br/>partition files"]
  node_augmentation["Augmentation<br/>preprocess scripts"]
  node_templates["Templates<br/>augmentation asset<br/>[templates.npy]"]
  node_data_prep["Data prep<br/>tensor builder<br/>[make_train_data.py]"]
  node_normalization["Mean/std stats<br/>scaling stats<br/>[means_stds.npy]"]
  node_trainer["Training<br/>[train.py]"]
  node_cv_eval["CV eval<br/>evaluation<br/>[eval_cv.py]"]
  node_test_eval["Test eval<br/>evaluation<br/>[eval_test.py]"]
  node_ismir_transcribe["Transcribe<br/>inference<br/>[transcribe.py]"]
  node_ismir_models[("ISMIR models<br/>pt checkpoints")]
  node_ismir_utils["ISMIR utils<br/>feature logic<br/>[utils.py]"]
end

subgraph group_tismir["TISMIR package"]
  node_tismir_transcribe["Transcribe<br/>inference<br/>[transcribe.py]"]
  node_tismir_models[("TISMIR models<br/>pt checkpoints")]
  node_tismir_utils["TISMIR utils<br/>feature logic<br/>[utils.py]"]
end

node_raw_audio -->|"organized by"| node_songlists
node_raw_audio -->|"transformed by"| node_augmentation
node_templates -->|"guides"| node_augmentation
node_songlists -->|"defines splits"| node_cv_folds
node_songlists -->|"inputs"| node_data_prep
node_cv_folds -->|"partitions"| node_data_prep
node_augmentation -->|"feeds"| node_data_prep
node_data_prep -->|"scales with"| node_normalization
node_data_prep -->|"supplies"| node_trainer
node_normalization -->|"applies"| node_trainer
node_trainer -->|"writes"| node_ismir_models
node_trainer -->|"assessed by"| node_cv_eval
node_trainer -->|"assessed by"| node_test_eval
node_ismir_models -->|"loaded by"| node_ismir_transcribe
node_ismir_utils -->|"supports"| node_ismir_transcribe
node_normalization -->|"applies"| node_ismir_transcribe
node_ismir_models -->|"loaded by"| node_tismir_transcribe
node_tismir_utils -->|"supports"| node_tismir_transcribe
node_tismir_models -->|"loaded by"| node_tismir_transcribe
node_normalization -->|"applies"| node_tismir_transcribe

click node_raw_audio "https://github.com/dap-lab/4way-tabla-transcription/tree/main/ismir_related/dataset"
click node_songlists "https://github.com/dap-lab/4way-tabla-transcription/tree/main/ismir_related/code/stroke-classification/songlists"
click node_cv_folds "https://github.com/dap-lab/4way-tabla-transcription/tree/main/ismir_related/code/stroke-classification/cv_folds"
click node_augmentation "https://github.com/dap-lab/4way-tabla-transcription/tree/main/ismir_related/code/data-augmentation"
click node_templates "https://github.com/dap-lab/4way-tabla-transcription/blob/main/ismir_related/code/data-augmentation/templates.npy"
click node_data_prep "https://github.com/dap-lab/4way-tabla-transcription/blob/main/ismir_related/code/stroke-classification/make_train_data.py"
click node_normalization "https://github.com/dap-lab/4way-tabla-transcription/blob/main/ismir_related/code/stroke-classification/means_stds.npy"
click node_trainer "https://github.com/dap-lab/4way-tabla-transcription/blob/main/ismir_related/code/stroke-classification/train.py"
click node_cv_eval "https://github.com/dap-lab/4way-tabla-transcription/blob/main/ismir_related/code/stroke-classification/eval_cv.py"
click node_test_eval "https://github.com/dap-lab/4way-tabla-transcription/blob/main/ismir_related/code/stroke-classification/eval_test.py"
click node_ismir_transcribe "https://github.com/dap-lab/4way-tabla-transcription/blob/main/ismir_related/code/stroke-classification/transcribe.py"
click node_ismir_models "https://github.com/dap-lab/4way-tabla-transcription/tree/main/ismir_related/code/stroke-classification/saved_models"
click node_ismir_utils "https://github.com/dap-lab/4way-tabla-transcription/blob/main/ismir_related/code/stroke-classification/utils.py"
click node_tismir_transcribe "https://github.com/dap-lab/4way-tabla-transcription/blob/main/tismir_related/transcribe.py"
click node_tismir_models "https://github.com/dap-lab/4way-tabla-transcription/tree/main/tismir_related/saved_models"
click node_tismir_utils "https://github.com/dap-lab/4way-tabla-transcription/blob/main/tismir_related/utils.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_raw_audio toneBlue
class node_songlists,node_cv_folds,node_augmentation,node_templates,node_data_prep,node_normalization,node_trainer,node_cv_eval,node_test_eval,node_ismir_transcribe,node_ismir_models,node_ismir_utils toneAmber
class node_tismir_transcribe,node_tismir_models,node_tismir_utils toneMint
```

## Components

### Repository

Offline tabla stroke transcription artifacts and code

- [Tabla audio](https://github.com/dap-lab/4way-tabla-transcription/tree/main/ismir_related/dataset): dataset · Local recordings used as the source corpus · `ismir_related/dataset`

### ISMIR workflow

Full experimental pipeline with augmentation, training, and evaluation

- [Song lists](https://github.com/dap-lab/4way-tabla-transcription/tree/main/ismir_related/code/stroke-classification/songlists): split manifests · Curated recording lists that define dataset conditions and splits · `ismir_related/code/stroke-classification/songlists`
- [CV folds](https://github.com/dap-lab/4way-tabla-transcription/tree/main/ismir_related/code/stroke-classification/cv_folds): partition files · Fixed cross-validation and test partitions · `ismir_related/code/stroke-classification/cv_folds`
- [Augmentation](https://github.com/dap-lab/4way-tabla-transcription/tree/main/ismir_related/code/data-augmentation): preprocess scripts · Standalone audio transformation generators for derived training variants · `ismir_related/code/data-augmentation`
- [Templates](https://github.com/dap-lab/4way-tabla-transcription/blob/main/ismir_related/code/data-augmentation/templates.npy): augmentation asset · Template array used by augmentation scripts · `ismir_related/code/data-augmentation/templates.npy`
- [Data prep](https://github.com/dap-lab/4way-tabla-transcription/blob/main/ismir_related/code/stroke-classification/make_train_data.py): tensor builder · Builds model-ready train and test datasets from audio and metadata · `ismir_related/code/stroke-classification/make_train_data.py`
- [Mean/std stats](https://github.com/dap-lab/4way-tabla-transcription/blob/main/ismir_related/code/stroke-classification/means_stds.npy): scaling stats · Feature normalization constants shared across training and inference · `ismir_related/code/stroke-classification/means_stds.npy`
- [Training](https://github.com/dap-lab/4way-tabla-transcription/blob/main/ismir_related/code/stroke-classification/train.py): model training · Core training entry point for stroke classifiers · `ismir_related/code/stroke-classification/train.py`
- [CV eval](https://github.com/dap-lab/4way-tabla-transcription/blob/main/ismir_related/code/stroke-classification/eval_cv.py): evaluation · Cross-validation scoring over the fixed folds · `ismir_related/code/stroke-classification/eval_cv.py`
- [Test eval](https://github.com/dap-lab/4way-tabla-transcription/blob/main/ismir_related/code/stroke-classification/eval_test.py): evaluation · Held-out test-set evaluation · `ismir_related/code/stroke-classification/eval_test.py`
- [Transcribe](https://github.com/dap-lab/4way-tabla-transcription/blob/main/ismir_related/code/stroke-classification/transcribe.py): inference · ISMIR runtime classifier for new audio · `ismir_related/code/stroke-classification/transcribe.py`
- [ISMIR models](https://github.com/dap-lab/4way-tabla-transcription/tree/main/ismir_related/code/stroke-classification/saved_models): pt checkpoints · Class-family checkpoints for the ISMIR workflow · `ismir_related/code/stroke-classification/saved_models`
- [ISMIR utils](https://github.com/dap-lab/4way-tabla-transcription/blob/main/ismir_related/code/stroke-classification/utils.py): feature logic · Shared normalization and feature-processing helpers · `ismir_related/code/stroke-classification/utils.py`

### TISMIR package

Deployment-oriented inference package with pretrained models

- [Transcribe](https://github.com/dap-lab/4way-tabla-transcription/blob/main/tismir_related/transcribe.py): inference · TISMIR runtime classifier for new audio · `tismir_related/transcribe.py`
- [TISMIR models](https://github.com/dap-lab/4way-tabla-transcription/tree/main/tismir_related/saved_models): pt checkpoints · Pretrained checkpoints bundled for deployment-oriented inference · `tismir_related/saved_models`
- [TISMIR utils](https://github.com/dap-lab/4way-tabla-transcription/blob/main/tismir_related/utils.py): feature logic · Shared normalization and feature-processing helpers · `tismir_related/utils.py`

## Connections

- Tabla audio → Song lists: organized by · Curated lists select recordings and augmentation conditions
- Tabla audio → Augmentation: transformed by · Raw recordings are expanded into derived variants
- Templates → Augmentation: guides · Template data supports augmentation generation
- Song lists → CV folds: defines splits · Lists and fold files make partitioning reproducible
- Song lists → Data prep: inputs · Split manifests feed training data creation
- CV folds → Data prep: partitions · Fold definitions drive train/test assembly
- Augmentation → Data prep: feeds · Augmented examples are consumed during data preparation
- Data prep → Mean/std stats: scales with · Prepared features use shared mean/std statistics
- Data prep → Training: supplies · Model-ready tensors are used for training
- Mean/std stats → Training: applies · Training uses the same feature standardization
- Training → ISMIR models: writes · Training produces stored checkpoints
- Training → CV eval: assessed by · Cross-validation evaluates trained models
- Training → Test eval: assessed by · Held-out testing evaluates trained models
- ISMIR models → Transcribe: loaded by · Inference loads persisted checkpoints
- ISMIR utils → Transcribe: supports · Shared feature logic powers runtime classification
- Mean/std stats → Transcribe: applies · Inference uses the same normalization stats
- ISMIR models → Transcribe: loaded by · Deployment inference loads pretrained checkpoints
- TISMIR utils → Transcribe: supports · Shared feature logic powers runtime classification
- TISMIR models → Transcribe: loaded by · Transcription uses bundled pretrained weights
- Mean/std stats → Transcribe: applies · Deployment inference reuses shared feature scaling