# jobicari/hmm-chordtracker architecture

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

- Interactive diagram: https://gitdiagram.com/jobicari/hmm-chordtracker
- Repository: https://github.com/jobicari/hmm-chordtracker

## Overview

Chordtracker is an experimental audio chord-recognition system with both offline evaluation and a live listening prototype. The offline workflow prepares annotated songs and audio features, trains acoustic models, decodes frame scores with temporal priors, and evaluates chord labels. The live branch processes incoming audio and presents delayed chord decisions. The README documents multiple model generations and dataset/vocabulary extensions; several are represented by their concrete modules or enclosing directories. Edges are limited to README statements and indexed imports; unsampled runtime wiring is not asserted.

Main entry points: [`scripts/run_v5.py`](https://github.com/jobicari/hmm-chordtracker/blob/main/scripts/run_v5.py) (Experiment runner), [`src/chordtracker/train_v7_2.py`](https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/train_v7_2.py) (CRNN training), [`src/chordtracker/play_along.py`](https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/play_along.py) (Play-along analysis), [`src/chordtracker/data_v5.py`](https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/data_v5.py) (RWC / GuitarSet data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data and features"]
  node_annotations["Chord annotations<br/>[data.py]"]
  node_v5data["RWC / GuitarSet data<br/>[data_v5.py]"]
  node_choco["ChoCo data<br/>[data_choco.py]"]
  node_v6data["V6 data<br/>[data_v6.py]"]
  node_causalfeatures["Causal CQT features<br/>[features_v7_1.py]"]
  node_v72data["V7.2 excerpts<br/>[data_v7_2.py]"]
  node_v8data["V8 vocabulary<br/>[data_v8.py]"]
end

subgraph group_models["Models and training"]
  node_runner["Experiment runner<br/>[run_v5.py]"]
  node_cnn["CNN acoustic model<br/>[model_v5.py]"]
  node_crnn["CRNN acoustic model<br/>[model_v6.py]"]
  node_v14model["V14 model<br/>[model_v14.py]"]
  node_trainer["CRNN training<br/>[train_v7_2.py]"]
end

subgraph group_decode["Decoding and evaluation"]
  node_hmm["Acoustic HMM<br/>[acoustic_hmm.py]"]
  node_transitions["Chord transitions<br/>[transitions.py]"]
  node_v8transitions["Extended transitions<br/>[transitions_v8.py]"]
  node_evaluator["Chord evaluation<br/>[evaluate.py]"]
end

subgraph group_live["Live experience"]
  node_streamfeatures["Streaming features"]
  node_playalong["Play-along analysis<br/>[play_along.py]"]
  node_workers["Live workers<br/>[live_workers.py]"]
  node_demo["Live demo server<br/>[demo_server.py]"]
end

node_musician(("Musician / audio"))

node_runner -->|"loads songs"| node_v5data
node_v5data -->|"uses annotations"| node_annotations
node_v5data -.->|"uses features"| node_causalfeatures
node_choco -->|"reuses data"| node_v5data
node_v72data -->|"uses targets"| node_v6data
node_v72data -->|"computes CQT"| node_causalfeatures
node_trainer -->|"builds batches"| node_v72data
node_trainer -->|"uses model"| node_cnn
node_trainer -->|"uses model"| node_crnn
node_v8data -->|"maps labels"| node_annotations
node_runner -->|"trains model"| node_trainer
node_runner -->|"decodes scores"| node_hmm
node_hmm -.->|"uses transitions"| node_transitions
node_v8transitions -->|"uses vocabulary"| node_v8data
node_runner -->|"scores results"| node_evaluator
node_playalong -->|"processes audio"| node_streamfeatures
node_playalong -->|"maps chords"| node_v8data
node_musician -.->|"submits audio"| node_demo
node_demo -->|"starts workers"| node_workers
node_demo -->|"uses analysis"| node_playalong
node_playalong -.->|"presents chords"| node_musician
node_v14model -->|"extends model"| node_crnn

click node_runner "https://github.com/jobicari/hmm-chordtracker/blob/main/scripts/run_v5.py"
click node_annotations "https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/data/data.py"
click node_v5data "https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/data_v5.py"
click node_choco "https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/data_choco.py"
click node_v6data "https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/data_v6.py"
click node_causalfeatures "https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/features_v7_1.py"
click node_v72data "https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/data_v7_2.py"
click node_v8data "https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/data_v8.py"
click node_cnn "https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/model_v5.py"
click node_crnn "https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/model_v6.py"
click node_v14model "https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/model_v14.py"
click node_trainer "https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/train_v7_2.py"
click node_hmm "https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/acoustic_hmm.py"
click node_transitions "https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/transitions.py"
click node_v8transitions "https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/transitions_v8.py"
click node_evaluator "https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/evaluate.py"
click node_streamfeatures "https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/streaming_features.py"
click node_playalong "https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/play_along.py"
click node_workers "https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/live_workers.py"
click node_demo "https://github.com/jobicari/hmm-chordtracker/blob/main/scripts/demo_server.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_annotations,node_v5data,node_choco,node_v6data,node_causalfeatures,node_v72data,node_v8data toneBlue
class node_runner,node_cnn,node_crnn,node_v14model,node_trainer toneAmber
class node_hmm,node_transitions,node_v8transitions,node_evaluator toneMint
class node_streamfeatures,node_playalong,node_workers,node_demo toneRose
class node_musician toneIndigo
```

## Components

### Data and features

- [Chord annotations](https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/data/data.py): `src/chordtracker/data/data.py`
- [RWC / GuitarSet data](https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/data_v5.py): `src/chordtracker/data_v5.py`
- [ChoCo data](https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/data_choco.py): `src/chordtracker/data_choco.py`
- [V6 data](https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/data_v6.py): `src/chordtracker/data_v6.py`
- [Causal CQT features](https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/features_v7_1.py): `src/chordtracker/features_v7_1.py`
- [V7.2 excerpts](https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/data_v7_2.py): `src/chordtracker/data_v7_2.py`
- [V8 vocabulary](https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/data_v8.py): `src/chordtracker/data_v8.py`

### Models and training

- [Experiment runner](https://github.com/jobicari/hmm-chordtracker/blob/main/scripts/run_v5.py): `scripts/run_v5.py`
- [CNN acoustic model](https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/model_v5.py): `src/chordtracker/model_v5.py`
- [CRNN acoustic model](https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/model_v6.py): `src/chordtracker/model_v6.py`
- [V14 model](https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/model_v14.py): `src/chordtracker/model_v14.py`
- [CRNN training](https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/train_v7_2.py): `src/chordtracker/train_v7_2.py`

### Decoding and evaluation

- [Acoustic HMM](https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/acoustic_hmm.py): `src/chordtracker/acoustic_hmm.py`
- [Chord transitions](https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/transitions.py): `src/chordtracker/transitions.py`
- [Extended transitions](https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/transitions_v8.py): `src/chordtracker/transitions_v8.py`
- [Chord evaluation](https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/evaluate.py): `src/chordtracker/evaluate.py`

### Live experience

- [Streaming features](https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/streaming_features.py): `src/chordtracker/streaming_features.py`
- [Play-along analysis](https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/play_along.py): `src/chordtracker/play_along.py`
- [Live workers](https://github.com/jobicari/hmm-chordtracker/blob/main/src/chordtracker/live_workers.py): `src/chordtracker/live_workers.py`
- [Live demo server](https://github.com/jobicari/hmm-chordtracker/blob/main/scripts/demo_server.py): `scripts/demo_server.py`

### Other components

- **Musician / audio**

## Connections

- Experiment runner → RWC / GuitarSet data: loads songs (evidence: `scripts/run_v5.py`)
- RWC / GuitarSet data → Chord annotations: uses annotations (evidence: `src/chordtracker/data_v5.py`)
- RWC / GuitarSet data → Causal CQT features: uses features
- ChoCo data → RWC / GuitarSet data: reuses data (evidence: `src/chordtracker/data_choco.py`)
- V7.2 excerpts → V6 data: uses targets (evidence: `src/chordtracker/data_v7_2.py`)
- V7.2 excerpts → Causal CQT features: computes CQT (evidence: `src/chordtracker/data_v7_2.py`)
- CRNN training → V7.2 excerpts: builds batches (evidence: `src/chordtracker/train_v7_2.py`)
- CRNN training → CNN acoustic model: uses model (evidence: `src/chordtracker/train_v7_2.py`)
- CRNN training → CRNN acoustic model: uses model (evidence: `src/chordtracker/train_v7_2.py`)
- V8 vocabulary → Chord annotations: maps labels (evidence: `src/chordtracker/data_v8.py`)
- Experiment runner → CRNN training: trains model (evidence: `scripts/run_v5.py`)
- Experiment runner → Acoustic HMM: decodes scores (evidence: `scripts/run_v5.py`)
- Acoustic HMM → Chord transitions: uses transitions
- Extended transitions → V8 vocabulary: uses vocabulary (evidence: `src/chordtracker/transitions_v8.py`)
- Experiment runner → Chord evaluation: scores results (evidence: `scripts/run_v5.py`)
- Play-along analysis → Streaming features: processes audio (evidence: `src/chordtracker/play_along.py`)
- Play-along analysis → V8 vocabulary: maps chords (evidence: `src/chordtracker/play_along.py`)
- Musician / audio → Live demo server: submits audio
- Live demo server → Live workers: starts workers (evidence: `scripts/demo_server.py`)
- Live demo server → Play-along analysis: uses analysis (evidence: `scripts/demo_server.py`)
- Play-along analysis → Musician / audio: presents chords
- V14 model → CRNN acoustic model: extends model (evidence: `src/chordtracker/model_v14.py`)
