README.md

---
license: cc-by-4.0
tags:
  - guitar
  - tablature
  - fingering
  - onnx
  - music
library_name: onnx
---

# tab-labeler — symbolic guitar-tab fingering scorer (ONNX)

A tiny CNN that scores candidate **(string, fret)** placements for a sequence of
note-columns, so a guitar-tab **arranger** (Viterbi over hand positions) fingers
more like a human than a hand-tuned heuristic. The **symbolic arm** of a
two-model tab stack — the score/MIDI→tab counterpart to the audio→tab
[`cstr/tabcnn-onnx`](https://huggingface.co/cstr/tabcnn-onnx). It shares TabCNN's
exact per-string output contract, so the **same decoder** consumes both.

The model **never emits tab** — it only scores positions the arranger enumerated;
the arranger's transition cost + hard span cap stay the arbiter, so nothing
unplayable is produced. Missing → the heuristic is the fallback.

## Versions

| file | training data | agreement | notes |
|---|---|---|---|
| `tab-labeler.onnx` (**default, v2**) | GuitarSet | 82.7% | shipped baseline |
| `tab-labeler-v1-lowmove.onnx` (v1) | GuitarSet | 78.59% | lower-movement fallback |
| `tab-labeler-v3-egset.onnx` (v3) | GuitarSet **+ EGSet12** | 82.5% (val 0.829) | more data; **better position** (6.23 vs human 6.20). GuitarSet-validated; OOD (IDMT) comparison pending |
| `tab-labeler-v3c-egset-spanreg.onnx` (v3c) | GuitarSet + EGSet12, span-regularized | val 0.829 | tighter emission (span-proxy 1.66); full benchmark pending |

Agreement = per-note (string,fret) match vs held-out human (GuitarSet player 05,
60-song arranged benchmark). All models carry top-2 checkpoints (`.best.pt`).

## ★ Integration: hitting span<1.5 at agreement>82% (no retraining)

**Quality is more than agreement.** Measured against the human on all axes
(GuitarSet, 60 songs; human = agreement 100% / movement 5325 / **span 1.43** /
position 6.20):

```
                          agreement  movement  span   position
heuristic (no model)      57.0%      4095      1.34   4.93   (under-moves, under-reaches)
this model (mv=1.0)       82.7%      4372      1.68   6.43   (good move+pos; OVER-spans)
```

The model fingers at about the right position and moves about the right amount,
but picks **wider shapes than a human**. The fix is an **arranger-side knob**,
not a new model: because the arranger lets the model *replace* its local cost,
the span penalty is dropped — re-apply a span penalty **on top of** the emission
(`modelSpanCost` in CometBeat's `arrangeTab`). Sweep on v3 (GuitarSet):

| `modelSpanCost` | agreement | span |
|---|---|---|
| 0.00 | 82.5% | 1.77 |
| 0.20 | 83.5% | 1.59 |
| **0.50** | **84.0%** | **1.47** |

**Span and agreement are NOT a tradeoff — they align:** since the human fingers
compact (1.43), preferring compact shapes makes the model match the human *more*.
So `modelSpanCost≈0.5` gives **span 1.47 (<1.5) at agreement 84.0% (>82%)** with
movement still under the human — on any of these weights, no retraining.

## IO contract

- **Input** `input : float32[N, 49, 9, 1]` — per column, a **9-column window**
  (centred, zero-padded) of multi-hot **pitch-presence** over MIDI **40..88**
  (49 bins).
- **Output** `output : float32[N, 6, 21]` — per-string **LogSoftmax** log-probs.
  **class 0 = string silent**, **class k = fret k-1**. **String index 0 = high e**
  … 5 = low E. Emission for `(string,fret)` = `output[string][fret+1]`.

~338 k params, ~1.3 MB, opset 13. Conv / ReLU / MaxPool / Gemm / LogSoftmax —
runs on pure-Dart [`onnx_runtime_dart`](https://github.com/CrispStrobe/onnx_runtime_dart).

## Training + evaluation

- **Data:** [GuitarSet](https://zenodo.org/records/3371780) (CC BY 4.0) — exact
  `(pitch → string, fret)` labels; held out by guitarist (player 05 = val),
  ±2-semitone transposition aug. **v3/v3c additionally use
  [EGSet12](https://zenodo.org/records/11406378)** (CC BY 4.0, original electric
  compositions — a 7th player). (A Guitar-TECHS-augmented variant, CC BY 4.0, was
  trained too — val 0.823, slightly OOD; not published here.)
- **Objective:** sum of 6 per-string softmax cross-entropies (v3c adds a span
  regularizer on the predicted distribution).

## Provenance / license

**CC BY 4.0.** Derived weights redistributable **with attribution**. Trained on
GuitarSet (Xi et al., ISMIR 2018, CC BY 4.0); v3/v3c also on EGSet12 (CC BY 4.0).
No DadaGP / no request-gated data.

## Provenance — authored here, and outside the GPAI definition

Added 2026-08-02 during an account-wide provenance review.

**These weights were trained by this repository's maintainer**, not converted
from someone else's model. Most `cstr/*` repositories are GGUF/ONNX conversions
where the upstream research team remains the provider; this one is not, and the
distinction matters because the two attract different obligations. The training
data, hyperparameters and licence inheritance are documented above.

**EU AI Act Art. 53 does not apply.** Art. 53 binds providers of *general-purpose
AI models*, which Art. 3(63) defines as models displaying "significant generality"
and capable of "competently performing a wide range of distinct tasks". A CNN scoring candidate (string, fret) placements for guitar tablature
is a narrow, single-task model and does not meet that definition, so the
Art. 53(1)(c) copyright-policy and 53(1)(d) training-content duties are not
engaged. This is recorded explicitly because "trained here" and "subject to
Art. 53" are easy to conflate, and only the first is true.

The training-data documentation above is published because it is useful and
because the licence inheritance depends on it — not because Art. 53 compels it.