bleugreen · bleugreen · Jul 21, 2026 · Jul 21, 2026 · Jul 21, 2026 · Jul 21, 2026
diff --git a/.gitignore b/.gitignore
@@ -1,8 +1,13 @@
-data/
+data/*
+!data/splits/
+!data/splits/**
 data/fma
 experiments/
 *.hdf5
 *.json
+!src/deeprhythm/weights/v0.8-bundle.json
+!docs/research/results/*.json
+!docs/research/results/**/*.jsonl
 __pycache__
 *.pyc
 *.pyo

diff --git a/README.md b/README.md
@@ -48,6 +48,29 @@ pip install deeprhythm
 
 ## Usage
 
+### Opt-in v0.8 metrical predictor
+
+v0.8 separates rhythmic rate from metrical level and adds a frozen temporal
+beat representation. Its metrical fusion was distilled from a stronger
+beat-rate teacher, but inference remains self-contained and does not load that
+teacher or Phasefinder. Both branches reuse one decoded waveform and one
+nnAudio STFT. The versioned weights are bundled with the package and recorded
+in `src/deeprhythm/weights/v0.8-bundle.json`.
+
+```python
+from deeprhythm.model import MetricalDeepRhythmPredictor
+
+predictor = MetricalDeepRhythmPredictor(device="mps")
+bpm = predictor.predict("/path/to/song.wav")
+details = predictor.predict("/path/to/song.wav", include_details=True)
+```
+
+The original `DeepRhythmPredictor` remains unchanged. v0.8 is opt-in because
+its measured metrical correction is a modest net improvement and can still
+change an individually correct octave decision. It aggregates every complete
+eight-second clip after removing the first and last clips from tracks longer
+than 40 seconds, matching the frozen model's training and evaluation path.
+
 ### CLI Inference
 
 #### Single

diff --git a/data/splits/SHA256SUMS b/data/splits/SHA256SUMS
@@ -0,0 +1,12 @@
+9d4844560ef371c48ae56b4f4eb705da39e6bce8d4c8e7fac3c4c42df4ba50d4  archive-v0.7/ballroom.jsonl
+2578232af9164843a35d0bd1175e065d7b71bca50114d2709c6a4ba156f83e52  archive-v0.7/giantsteps.jsonl
+b0f210b7c5d9435450bdcbc8d7c240b8f3d3654710cf55bdc386c83879f3fd02  archive-v0.7/gtzan.jsonl
+532ee056939f549ca6e575060d0148a7271ef18a0739df2c6e440533ede0498f  ballroom/test.jsonl
+6961ac3e3384835920ddf57c83509efbbea950e72e05082e250778a826159d9b  ballroom/train.jsonl
+cfde5d0fe110f69ba1b13b261e47aff339bab507536af169b4b6352f8d40d113  ballroom/val.jsonl
+346b83bd51833e8f5f53b8c0d980f7fd8c01917642db60652c3720812e601fed  giantsteps/test.jsonl
+8044435b7f362a802726c98466080f63fd2351c72f8ac865f3482cebad2af644  giantsteps/train.jsonl
+8b8bbaeaf933a17be9b5c3724a6138fe27920db9e79ce896fa0bd56f320abc93  giantsteps/val.jsonl
+1db0216a5fd020ebb931f7682c91268c6448584fca8dd7fe67f57fef6127898f  gtzan/test.jsonl
+51f6bb6387ab777eb27a62d16a46c549a68d969fb6077d28c1905d8271418b87  gtzan/train.jsonl
+507f7dae232c7d95bb7e391bbf85706ecaeca17f3f7bca5befdfaa3ab63cf65e  gtzan/val.jsonl
diff --git a/data/splits/archive-v0.7/ballroom.jsonl b/data/splits/archive-v0.7/ballroom.jsonl
diff --git a/data/splits/archive-v0.7/giantsteps.jsonl b/data/splits/archive-v0.7/giantsteps.jsonl
diff --git a/data/splits/archive-v0.7/gtzan.jsonl b/data/splits/archive-v0.7/gtzan.jsonl
diff --git a/data/splits/ballroom/test.jsonl b/data/splits/ballroom/test.jsonl
diff --git a/data/splits/ballroom/train.jsonl b/data/splits/ballroom/train.jsonl
diff --git a/data/splits/ballroom/val.jsonl b/data/splits/ballroom/val.jsonl
diff --git a/data/splits/giantsteps/test.jsonl b/data/splits/giantsteps/test.jsonl
diff --git a/data/splits/giantsteps/train.jsonl b/data/splits/giantsteps/train.jsonl
diff --git a/data/splits/giantsteps/val.jsonl b/data/splits/giantsteps/val.jsonl
diff --git a/data/splits/gtzan/test.jsonl b/data/splits/gtzan/test.jsonl
diff --git a/data/splits/gtzan/train.jsonl b/data/splits/gtzan/train.jsonl
diff --git a/data/splits/gtzan/val.jsonl b/data/splits/gtzan/val.jsonl
diff --git a/data/splits/sources/gtzan/README.md b/data/splits/sources/gtzan/README.md
@@ -0,0 +1,22 @@
+# GTZAN
+Information about the GTZAN dataset for "music genre recognition" research.
+
+- index.txt: an index into the contents of the datasets, specifically the artist and track title of most wav files.
+- Fault-filtered partitions used in Kereliuk, Sturm, and Larsen, “[Deep learning, audio adversaries, and music content analysis](https://ieeexplore.ieee.org/document/7336950),” in Proc. WASPAA, 2015;
+Kereliuk, Sturm, and Larsen, “[Deep learning and music adversaries](https://ieeexplore.ieee.org/document/7254179),” IEEE Trans. Multimedia, vol. 17, pp. 2059–2071, Sep. 2015;
+Rodriguez-Algarra, Sturm, and Maruri-Aguilar, “[Analysing scattering-based music content analysis systems: Where’s the music?](https://scholar.google.com/citations?view_op=view_citation&hl=en&user=KdeYIvMAAAAJ&cstart=20&pagesize=80&sortby=pubdate&citation_for_view=KdeYIvMAAAAJ:sSrBHYA8nusC),” in Proc. ISMIR, 2016. Code repo: https://code.soundsoftware.ac.uk/projects/scatter_reeval
+  - test_filtered.txt
+  - test_stratified.txt
+  - train_filtered.txt
+  - train_stratified.txt
+  - valid_filtered.txt
+  - valid_stratified.txt
+
+## Other relevant publications:
+- Sturm, "[The GTZAN dataset: Its contents, its faults, their effects on evaluation, and its future use](https://arxiv.org/abs/1306.1461)", arXiv:1306.1461, 2013.
+- Sturm, “[The state of the art ten years after A State of the Art: Future research in music information retrieval](https://scholar.google.com/citations?view_op=view_citation&hl=en&user=KdeYIvMAAAAJ&citation_for_view=KdeYIvMAAAAJ:EUQCXRtRnyEC),” Journal of New Music Research, vol. 43, no. 2, pp. 147 – 172, 2014.
+- Sturm,“[A Simple Method to Determine if a Music Information Retrieval System is a‘Horse’](https://scholar.google.com/citations?view_op=view_citation&hl=en&user=KdeYIvMAAAAJ&cstart=20&pagesize=80&sortby=pubdate&citation_for_view=KdeYIvMAAAAJ:2P1L_qKh6hAC)”, IEEE Trans. Multimedia, vol. 16, no 6, pp. 1636 – 1644, Oct. 2014.
+- Sturm, “[A survey of evaluation in music genre recognition](https://scholar.google.com/citations?view_op=view_citation&hl=en&user=KdeYIvMAAAAJ&cstart=20&pagesize=80&sortby=pubdate&citation_for_view=KdeYIvMAAAAJ:bEWYMUwI8FkC),” chapter (pp. 29-66) in Nürnberger et al., eds., Adaptive Multimedia Retrieval: Semantics, Context, and Adaptation, Springer, 2014.
+- Sturm, “[An analysis of the GTZAN music genre dataset](https://scholar.google.com/citations?view_op=view_citation&hl=en&user=KdeYIvMAAAAJ&citation_for_view=KdeYIvMAAAAJ:4JMBOYKVnBMC),” in Proc. ACM Workshop on Music Info. Retrieval with User-centered and Multimodal Strategies, Nov. 2012.
+- Sturm, “[Two systems for automatic music genre recognition: What are they really recognizing?](https://scholar.google.com/citations?view_op=view_citation&hl=en&user=KdeYIvMAAAAJ&cstart=20&pagesize=80&sortby=pubdate&citation_for_view=KdeYIvMAAAAJ:j3f4tGmQtD8C),” in Proc. ACM Workshop on Music Info. Retrieval with User-centered and Multimodal Strategies, Nov. 2012.
+