tempocheck 0.1.0__tar.gz

tempocheck-0.1.0/LICENSE

@@ -0,0 +1,29 @@
+MIT License
+
+Copyright (c) 2026 Boobalan Arjunan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+This project depends on third-party libraries (numpy, scipy, soundfile,
+librosa, pyloudnorm, scikit-learn, tqdm, langdetect, matplotlib, and
+optionally openai-whisper, torch/torchaudio). Each carries its own license
+(mostly BSD/MIT/Apache-2.0) -- check requirements.txt and each package's own
+license before redistributing, especially if your GTV program has its own
+licensing rules.

tempocheck-0.1.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: tempocheck
+Version: 0.1.0
+Summary: Check that the BPM labels on your music files match the audio.
+Author-email: Boobalan Arjunan <boobalan_arjunan@composermind.com>
+Maintainer-email: Boobalan Arjunan <boobalan_arjunan@composermind.com>
+License: MIT
+Project-URL: Homepage, https://github.com/BoobalanArjunan/Tempocheck
+Project-URL: Issues, https://github.com/BoobalanArjunan/Tempocheck/issues
+Project-URL: Source, https://github.com/BoobalanArjunan/Tempocheck
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: scipy>=1.9
+Requires-Dist: soundfile>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# tempocheck
+
+**Check that the BPM labels on your music files match the audio.**
+
+Wrong tempo labels quietly hurt music-AI training (tempo-conditioned generation, DJ tools, retrieval). tempocheck listens to each file, measures its tempo, and tells you which labels look wrong, which are only a half/double-tempo difference, and which it cannot judge.
+
+> **Status: alpha (0.1.0).** Validated against tempo benchmarks (46 synthetic unit tests passing, zero false alarms on true labels). See [Benchmark validation results](#benchmark-validation-results) and [docs/REAL_DATA_CHECK.md](docs/REAL_DATA_CHECK.md).
+
+---
+
+## Installation
+
+```bash
+pip install --pre tempocheck      # after release; until then: pip install -e ".[dev]"
+```
+
+Requirements: Python 3.9+. Depends only on `numpy`, `scipy`, and `soundfile`.
+
+---
+
+## Command Line Usage (CLI)
+
+### 1. Check from filenames
+If your files encode tempo in their names (e.g. `night_drive_124bpm.wav`, `breakbeat_170.mp3`):
+```bash
+tempocheck check songs/
+```
+
+### 2. Check from a CSV catalog
+When metadata is stored in a CSV (columns `file` and `bpm`):
+```bash
+tempocheck check labels.csv --audio-dir songs/ --out verdicts.csv
+```
+
+### 3. Parallel processing
+Accelerate analysis across multi-core CPUs:
+```bash
+tempocheck check labels.csv --audio-dir songs/ --jobs 8 --show-pass
+```
+
+### 4. CI/CD Dataset Quality Gate
+`tempocheck` exits with code `1` if any file returns a `FAIL`, making it suitable for automated continuous integration:
+```bash
+tempocheck check incoming_stems/ || { echo "Mismatched BPM labels detected!"; exit 1; }
+```
+
+---
+
+## Python API (Using in Code)
+
+`tempocheck` can be imported directly into Python applications, PyTorch data loaders, and data preparation pipelines.
+
+### Single file verification
+```python
+from tempocheck import check_file
+
+verdict = check_file("tracks/night_drive.wav", label=124.0)
+
+print(verdict.level)       # "PASS", "WARN", "REVIEW", "FAIL", or "ERROR"
+print(verdict.estimate)    # Measured BPM, e.g. 123.9
+print(verdict.reason)      # e.g. "label matches the audio"
+print(verdict.prominence)  # Pulse strength score (e.g. 5.1; < 3.0 means weak pulse)
+```
+
+### Batch dataset filtering (Pandas / ETL)
+Filter out mismatched tracks before training generative audio models:
+```python
+import pandas as pd
+from tempocheck import check_file
+
+df = pd.read_csv("metadata.csv")  # columns: 'file_path', 'target_bpm'
+
+def validate_row(row):
+    v = check_file(row["file_path"], row["target_bpm"])
+    return pd.Series({
+        "verdict": v.level,
+        "measured_bpm": v.estimate,
+        "reason": v.reason
+    })
+
+results = df.apply(validate_row, axis=1)
+
+# Keep only validated tracks (PASS and harmonic WARN)
+clean_training_set = df[results["verdict"].isin(["PASS", "WARN"])]
+```
+
+### Low-level audio array & tempogram analysis
+Analyze in-memory audio NumPy arrays directly without reading from disk:
+```python
+from tempocheck.features import onset_envelope
+from tempocheck.estimate import estimate
+from tempocheck.check import judge
+
+# audio_mono: 1D float numpy array sampled at 22,050 Hz
+env = onset_envelope(audio_mono)
+tempo = estimate(env)
+
+print(f"BPM: {tempo.bpm:.1f} (prominence: {tempo.prominence:.2f})")
+print(f"Segment breakdown: {tempo.segments}")  # detects internal tempo shifts
+
+verdict = judge(label=120.0, t=tempo, file="stream_chunk.wav")
+```
+
+---
+
+## What the verdicts mean
+
+| Verdict | Meaning | Exit Code |
+|---|---|:---:|
+| **PASS** | Measured tempo is within 4% of the label | `0` |
+| **WARN** | Measured tempo is half, double, 1/3, 3x, 1.5x, or 2/3 of the label (both can be perceptually valid) | `0` |
+| **REVIEW** | Cannot judge: no steady pulse, tempo changes inside file, or audio supports multiple tempi | `0` |
+| **FAIL** | Audio clearly indicates a different tempo and does not support the label | `1` |
+| **ERROR** | Audio file could not be decoded or opened | `0` |
+
+---
+
+## Practical Applications
+
+- **Music-AI Conditioning Validation**: Avoid feeding mislabeled BPM tokens into text-to-music models (e.g. MusicLM, Stable Audio), which degrades rhythm generation.
+- **Sample Pack & Loop QA**: Ensure commercially sold sample packs and drum loops match their advertised tempo.
+- **DJ Library Ingestion**: Distinguish artistic half-time/double-time selections from genuinely wrong BPM tags.
+- **Tempo Drift Detection**: Flags live drummer acceleration or rubato sections (`REVIEW: tempo changes inside the file`) for manual beat-mapping.
+
+---
+
+## Benchmark validation results
+
+Tested with `scripts/real_data_check.py` across diverse tempos with planted label discrepancies. Detailed findings are in [`real_check/results.md`](real_check/results.md):
+
+- **False alarm rate on true labels**: **0.0%** (21 PASS, 4 WARN, 0 FAIL)
+- **Deliberately wrong labels caught (20%+ away)**: **88%** (22/25 marked FAIL)
+- **Tempo estimation accuracy**:
+  - **Acc1** (exact match within 4% tolerance): **84.0%**
+  - **Acc2** (including half/double/3x/1.5x harmonic tempo relations): **100.0%**
+- **Planted false alarm check**: 0 false alarms on true BPM labels.
+
+---
+
+## Limits (read these)
+
+- **Judgement defaults.** Numbers like the 4% tolerance and the "clear pulse" strength are reasoned defaults.
+- It is a simple estimator (onset curve + tempogram). Strong hi-hat or off-beat patterns can make it report double tempo; that shows up as WARN, not FAIL.
+- Songs without a steady beat (ambient, rubato, classical) are REVIEW, not wrong.
+- Only the middle 3 minutes of a file are used. Tempo changes inside a file are flagged REVIEW.
+- A FAIL means "the audio disagrees with the label", not "the label is wrong": listen to the file.
+
+---
+
+## Tests
+
+Run tests with `pytest`:
+```bash
+pytest -q
+```
+Suite of 46 tests on synthetic songs covering onsets, tempograms, swing, jitter, half-time, and harmonic relations. A planted-bug check (29 deliberate bugs in the code) was caught by the test suite.
+
+## License
+
+MIT. Copyright (c) 2026 Boobalan Arjunan.

tempocheck-0.1.0/README.md

@@ -0,0 +1,160 @@
+# tempocheck
+
+**Check that the BPM labels on your music files match the audio.**
+
+Wrong tempo labels quietly hurt music-AI training (tempo-conditioned generation, DJ tools, retrieval). tempocheck listens to each file, measures its tempo, and tells you which labels look wrong, which are only a half/double-tempo difference, and which it cannot judge.
+
+> **Status: alpha (0.1.0).** Validated against tempo benchmarks (46 synthetic unit tests passing, zero false alarms on true labels). See [Benchmark validation results](#benchmark-validation-results) and [docs/REAL_DATA_CHECK.md](docs/REAL_DATA_CHECK.md).
+
+---
+
+## Installation
+
+```bash
+pip install --pre tempocheck      # after release; until then: pip install -e ".[dev]"
+```
+
+Requirements: Python 3.9+. Depends only on `numpy`, `scipy`, and `soundfile`.
+
+---
+
+## Command Line Usage (CLI)
+
+### 1. Check from filenames
+If your files encode tempo in their names (e.g. `night_drive_124bpm.wav`, `breakbeat_170.mp3`):
+```bash
+tempocheck check songs/
+```
+
+### 2. Check from a CSV catalog
+When metadata is stored in a CSV (columns `file` and `bpm`):
+```bash
+tempocheck check labels.csv --audio-dir songs/ --out verdicts.csv
+```
+
+### 3. Parallel processing
+Accelerate analysis across multi-core CPUs:
+```bash
+tempocheck check labels.csv --audio-dir songs/ --jobs 8 --show-pass
+```
+
+### 4. CI/CD Dataset Quality Gate
+`tempocheck` exits with code `1` if any file returns a `FAIL`, making it suitable for automated continuous integration:
+```bash
+tempocheck check incoming_stems/ || { echo "Mismatched BPM labels detected!"; exit 1; }
+```
+
+---
+
+## Python API (Using in Code)
+
+`tempocheck` can be imported directly into Python applications, PyTorch data loaders, and data preparation pipelines.
+
+### Single file verification
+```python
+from tempocheck import check_file
+
+verdict = check_file("tracks/night_drive.wav", label=124.0)
+
+print(verdict.level)       # "PASS", "WARN", "REVIEW", "FAIL", or "ERROR"
+print(verdict.estimate)    # Measured BPM, e.g. 123.9
+print(verdict.reason)      # e.g. "label matches the audio"
+print(verdict.prominence)  # Pulse strength score (e.g. 5.1; < 3.0 means weak pulse)
+```
+
+### Batch dataset filtering (Pandas / ETL)
+Filter out mismatched tracks before training generative audio models:
+```python
+import pandas as pd
+from tempocheck import check_file
+
+df = pd.read_csv("metadata.csv")  # columns: 'file_path', 'target_bpm'
+
+def validate_row(row):
+    v = check_file(row["file_path"], row["target_bpm"])
+    return pd.Series({
+        "verdict": v.level,
+        "measured_bpm": v.estimate,
+        "reason": v.reason
+    })
+
+results = df.apply(validate_row, axis=1)
+
+# Keep only validated tracks (PASS and harmonic WARN)
+clean_training_set = df[results["verdict"].isin(["PASS", "WARN"])]
+```
+
+### Low-level audio array & tempogram analysis
+Analyze in-memory audio NumPy arrays directly without reading from disk:
+```python
+from tempocheck.features import onset_envelope
+from tempocheck.estimate import estimate
+from tempocheck.check import judge
+
+# audio_mono: 1D float numpy array sampled at 22,050 Hz
+env = onset_envelope(audio_mono)
+tempo = estimate(env)
+
+print(f"BPM: {tempo.bpm:.1f} (prominence: {tempo.prominence:.2f})")
+print(f"Segment breakdown: {tempo.segments}")  # detects internal tempo shifts
+
+verdict = judge(label=120.0, t=tempo, file="stream_chunk.wav")
+```
+
+---
+
+## What the verdicts mean
+
+| Verdict | Meaning | Exit Code |
+|---|---|:---:|
+| **PASS** | Measured tempo is within 4% of the label | `0` |
+| **WARN** | Measured tempo is half, double, 1/3, 3x, 1.5x, or 2/3 of the label (both can be perceptually valid) | `0` |
+| **REVIEW** | Cannot judge: no steady pulse, tempo changes inside file, or audio supports multiple tempi | `0` |
+| **FAIL** | Audio clearly indicates a different tempo and does not support the label | `1` |
+| **ERROR** | Audio file could not be decoded or opened | `0` |
+
+---
+
+## Practical Applications
+
+- **Music-AI Conditioning Validation**: Avoid feeding mislabeled BPM tokens into text-to-music models (e.g. MusicLM, Stable Audio), which degrades rhythm generation.
+- **Sample Pack & Loop QA**: Ensure commercially sold sample packs and drum loops match their advertised tempo.
+- **DJ Library Ingestion**: Distinguish artistic half-time/double-time selections from genuinely wrong BPM tags.
+- **Tempo Drift Detection**: Flags live drummer acceleration or rubato sections (`REVIEW: tempo changes inside the file`) for manual beat-mapping.
+
+---
+
+## Benchmark validation results
+
+Tested with `scripts/real_data_check.py` across diverse tempos with planted label discrepancies. Detailed findings are in [`real_check/results.md`](real_check/results.md):
+
+- **False alarm rate on true labels**: **0.0%** (21 PASS, 4 WARN, 0 FAIL)
+- **Deliberately wrong labels caught (20%+ away)**: **88%** (22/25 marked FAIL)
+- **Tempo estimation accuracy**:
+  - **Acc1** (exact match within 4% tolerance): **84.0%**
+  - **Acc2** (including half/double/3x/1.5x harmonic tempo relations): **100.0%**
+- **Planted false alarm check**: 0 false alarms on true BPM labels.
+
+---
+
+## Limits (read these)
+
+- **Judgement defaults.** Numbers like the 4% tolerance and the "clear pulse" strength are reasoned defaults.
+- It is a simple estimator (onset curve + tempogram). Strong hi-hat or off-beat patterns can make it report double tempo; that shows up as WARN, not FAIL.
+- Songs without a steady beat (ambient, rubato, classical) are REVIEW, not wrong.
+- Only the middle 3 minutes of a file are used. Tempo changes inside a file are flagged REVIEW.
+- A FAIL means "the audio disagrees with the label", not "the label is wrong": listen to the file.
+
+---
+
+## Tests
+
+Run tests with `pytest`:
+```bash
+pytest -q
+```
+Suite of 46 tests on synthetic songs covering onsets, tempograms, swing, jitter, half-time, and harmonic relations. A planted-bug check (29 deliberate bugs in the code) was caught by the test suite.
+
+## License
+
+MIT. Copyright (c) 2026 Boobalan Arjunan.

tempocheck-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tempocheck"
+dynamic = ["version"]
+description = "Check that the BPM labels on your music files match the audio."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [
+  { name = "Boobalan Arjunan", email = "boobalan_arjunan@composermind.com" },
+]
+maintainers = [
+  { name = "Boobalan Arjunan", email = "boobalan_arjunan@composermind.com" },
+]
+dependencies = ["numpy>=1.23", "scipy>=1.9", "soundfile>=0.12"]
+classifiers = ["Development Status :: 3 - Alpha", "License :: OSI Approved :: MIT License", "Topic :: Multimedia :: Sound/Audio :: Analysis"]
+
+[project.urls]
+Homepage = "https://github.com/BoobalanArjunan/Tempocheck"
+Issues = "https://github.com/BoobalanArjunan/Tempocheck/issues"
+Source = "https://github.com/BoobalanArjunan/Tempocheck"
+
+[project.optional-dependencies]
+dev = ["pytest"]
+
+[project.scripts]
+tempocheck = "tempocheck.cli:main"
+
+[tool.setuptools.dynamic]
+version = { attr = "tempocheck._version.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

tempocheck-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tempocheck-0.1.0/src/tempocheck/__init__.py

@@ -0,0 +1,5 @@
+"""tempocheck: does the BPM label on a music file match the audio?"""
+from ._version import __version__
+from .check import Verdict, check_file, judge
+
+__all__ = ["__version__", "Verdict", "check_file", "judge"]

tempocheck-0.1.0/src/tempocheck/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

tempocheck-0.1.0/src/tempocheck/check.py

@@ -0,0 +1,61 @@
+"""Compare a labelled BPM with the audio and give a verdict."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from .estimate import MIN_PROMINENCE, Tempo, estimate
+from .features import load_mono, onset_envelope
+
+TOL = 0.04                 # 4 percent: the usual "right tempo" tolerance in tempo research
+SUPPORT_RATIO = 0.8        # the label counts as "also supported by the audio" at this share of the best score
+RELATIONS = ((2.0, "audio is 2x the label"), (0.5, "audio is half the label"), (3.0, "audio is 3x the label"),
+             (1 / 3, "audio is a third of the label"), (1.5, "audio is 3/2 of the label"), (2 / 3, "audio is 2/3 of the label"))
+
+OK, OCTAVE, WRONG, UNSURE, ERROR = "OK", "OCTAVE", "WRONG", "UNSURE", "ERROR"
+
+
+@dataclass
+class Verdict:
+    file: str
+    label: float
+    status: str
+    estimate: Optional[float]
+    reason: str
+    prominence: float = 0.0
+
+    @property
+    def level(self) -> str:
+        return {OK: "PASS", OCTAVE: "WARN", UNSURE: "REVIEW", WRONG: "FAIL", ERROR: "ERROR"}[self.status]
+
+
+def close(a: float, b: float, tol: float = TOL) -> bool:
+    return abs(a - b) <= tol * b
+
+
+def judge(label: float, t: Tempo, file: str = "") -> Verdict:
+    if t.bpm is None:
+        return Verdict(file, label, UNSURE, None, "too short or silent to measure a tempo")
+    if len(t.segments) >= 2 and any(not close(s, t.segments[0], TOL) and not any(close(s, t.segments[0] * r, TOL) for r, _ in RELATIONS)
+                                    for s in t.segments[1:]):
+        return Verdict(file, label, UNSURE, t.bpm, "tempo changes inside the file: " + ", ".join(f"{s:g}" for s in t.segments), t.prominence)
+    if t.prominence < MIN_PROMINENCE:
+        return Verdict(file, label, UNSURE, t.bpm, f"no clear steady pulse (strength {t.prominence:.1f}); label cannot be judged", t.prominence)
+    if close(t.bpm, label):
+        return Verdict(file, label, OK, t.bpm, "label matches the audio", t.prominence)
+    for r, text in RELATIONS:
+        if close(t.bpm, label * r):
+            return Verdict(file, label, OCTAVE, t.bpm, f"{text} (measured {t.bpm:g}); both feel natural to some listeners", t.prominence)
+    if t.score_at(label) >= SUPPORT_RATIO * t.score_at(t.bpm):
+        return Verdict(file, label, UNSURE, t.bpm, f"audio supports both the label and {t.bpm:g}", t.prominence)
+    return Verdict(file, label, WRONG, t.bpm, f"audio says about {t.bpm:g}, label says {label:g}", t.prominence)
+
+
+def check_file(path, label: float) -> Verdict:
+    p = Path(path)
+    try:
+        env = onset_envelope(load_mono(p))
+    except Exception as e:  # unreadable audio
+        return Verdict(p.name, label, ERROR, None, f"could not read audio: {e}")
+    return judge(label, estimate(env), p.name)

tempocheck-0.1.0/src/tempocheck/cli.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from concurrent.futures import ProcessPoolExecutor
+from pathlib import Path
+
+from . import __version__
+from .check import TOL, check_file
+from .labels import LabelError, from_filenames, read_csv
+from .report import summary_line, text, write_csv
+
+
+def _job(args):
+    return check_file(*args)
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="tempocheck", description="Check that the BPM labels on your music match the audio.")
+    ap.add_argument("--version", action="version", version=f"tempocheck {__version__}")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    c = sub.add_parser("check", help="check labels from a CSV, or from a folder of files named like song_120bpm.wav")
+    c.add_argument("source", type=Path, help="labels.csv (columns: file, bpm) or a folder")
+    c.add_argument("--audio-dir", type=Path, help="folder the CSV's file names are relative to (default: the CSV's folder)")
+    c.add_argument("--out", type=Path, help="write every verdict to this CSV")
+    c.add_argument("--show-pass", action="store_true", help="also list files that passed")
+    c.add_argument("--jobs", type=int, default=1, help="files analysed in parallel (default 1)")
+    a = ap.parse_args(argv)
+
+    try:
+        if a.source.is_dir():
+            items, problems = from_filenames(a.source)
+        elif a.source.is_file():
+            items, problems = read_csv(a.source, a.audio_dir)
+        else:
+            print(f"error: {a.source} not found", file=sys.stderr)
+            return 2
+    except LabelError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+    if not items:
+        print("error: nothing to check" + (f" ({len(problems)} label problems, e.g. {problems[0]})" if problems else ""), file=sys.stderr)
+        return 2
+    if a.jobs > 1:
+        with ProcessPoolExecutor(a.jobs) as ex:
+            vs = list(ex.map(_job, items, chunksize=1))
+    else:
+        vs = [check_file(p, b) for p, b in items]
+    print(text(vs, problems, a.show_pass))
+    if a.out:
+        write_csv(a.out, vs)
+    return 1 if any(v.level == "FAIL" for v in vs) else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tempocheck-0.1.0/src/tempocheck/estimate.py

@@ -0,0 +1,77 @@
+"""Tempo from an onset curve: a Fourier tempogram (how strong is a steady pulse at each BPM) with a comb over the
+pulse's harmonics, so a true pulse at B gets support from B, 2B, 3B and 4B."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional, Tuple
+
+import numpy as np
+
+from .features import FPS
+
+GRID = np.arange(30.0, 300.0, 0.25)          # BPM values scored
+EST_MIN, EST_MAX = 50.0, 200.0               # the tempo is looked for in this range
+HARMONIC_WEIGHTS = (1.0, 0.75, 0.5, 0.25)
+MIN_PROMINENCE = 3.0                         # best score must be this many times the typical score, else "no clear pulse" (provisional)
+SEGMENT_SECONDS = 20.0
+PRIOR_CENTER, PRIOR_SIGMA_OCT = 110.0, 0.7    # gentle preference for everyday tempi when two readings (B and 2B) score alike (Ellis 2007)
+
+
+@dataclass
+class Tempo:
+    bpm: Optional[float]
+    prominence: float                        # best score / median score over the grid; high = clear pulse
+    score_at: "callable"                     # score_at(bpm) -> comb score, to ask "does the audio support THIS tempo?"
+    segments: List[float]                    # per-segment estimates (empty for short files)
+
+
+def _tempogram(env: np.ndarray) -> np.ndarray:
+    n = len(env)
+    w = np.hanning(n)
+    t = np.arange(n) / FPS
+    freqs = np.concatenate([GRID * h / 60.0 for h in (1, 2, 3, 4)])
+    freqs = np.unique(freqs)
+    # |sum env(t) e^{-2 pi i f t}| for each needed frequency, in chunks to keep memory small
+    out = np.empty(len(freqs))
+    e = env * w
+    for i in range(0, len(freqs), 256):
+        f = freqs[i:i + 256]
+        out[i:i + 256] = np.abs(np.exp(-2j * np.pi * np.outer(f, t)) @ e)
+    return freqs, out
+
+
+def _scores(env: np.ndarray):
+    freqs, mag = _tempogram(env)
+
+    def at(f_hz: float) -> float:
+        return float(np.interp(f_hz, freqs, mag))
+
+    def score_at(bpm: float) -> float:
+        return sum(wt * at(h * bpm / 60.0) for h, wt in zip((1, 2, 3, 4), HARMONIC_WEIGHTS))
+    grid_scores = np.array([score_at(b) for b in GRID])
+    return score_at, grid_scores
+
+
+def _best(grid_scores: np.ndarray) -> Tuple[float, float]:
+    m = (GRID >= EST_MIN) & (GRID <= EST_MAX)
+    prior = np.exp(-0.5 * (np.log2(GRID / PRIOR_CENTER) / PRIOR_SIGMA_OCT) ** 2)
+    i = int(np.argmax(np.where(m, grid_scores * prior, -1)))
+    med = float(np.median(grid_scores)) + 1e-12
+    return float(GRID[i]), float(grid_scores[i] / med)
+
+
+def estimate(env: np.ndarray) -> Tempo:
+    if len(env) < int(4 * FPS) or not np.any(env):
+        return Tempo(None, 0.0, lambda b: 0.0, [])
+    score_at, gs = _scores(env)
+    bpm, prom = _best(gs)
+    segs: List[float] = []
+    seg_n = int(SEGMENT_SECONDS * FPS)
+    if len(env) >= 2 * seg_n:
+        k = min(4, len(env) // seg_n)
+        for part in np.array_split(env, k):
+            _, g = _scores(part)
+            b, p = _best(g)
+            if p >= MIN_PROMINENCE:
+                segs.append(b)
+    return Tempo(bpm, prom, score_at, segs)

tempocheck-0.1.0/src/tempocheck/features.py

@@ -0,0 +1,45 @@
+"""Audio -> onset-strength curve (how strongly new sounds start, over time). Light on purpose: numpy, scipy, soundfile only."""
+from __future__ import annotations
+
+from math import gcd
+from pathlib import Path
+
+import numpy as np
+import soundfile as sf
+from scipy.signal import resample_poly, stft
+
+FS = 22050
+N_FFT = 1024
+HOP = 256                      # 86 frames per second
+FPS = FS / HOP
+N_BANDS = 24
+FMIN, FMAX = 30.0, 10000.0
+MAX_SECONDS = 180.0            # long files: only the middle 3 minutes are used
+
+
+def load_mono(path, max_seconds: float = MAX_SECONDS) -> np.ndarray:
+    x, sr = sf.read(str(path), dtype="float32", always_2d=True)
+    x = x.mean(axis=1)
+    if sr != FS:
+        g = gcd(int(sr), FS)
+        x = resample_poly(x, FS // g, int(sr) // g).astype(np.float32)
+    n = int(max_seconds * FS)
+    if len(x) > n:
+        s = (len(x) - n) // 2
+        x = x[s:s + n]
+    return x
+
+
+def onset_envelope(x: np.ndarray) -> np.ndarray:
+    """Positive change of log band energy, averaged over bands; mean removed. Empty array for audio shorter than ~1 s."""
+    if len(x) < FS // 2:
+        return np.zeros(0)
+    _, _, Z = stft(x, fs=FS, nperseg=N_FFT, noverlap=N_FFT - HOP, boundary=None, padded=False)
+    P = np.abs(Z) ** 2
+    freqs = np.linspace(0, FS / 2, P.shape[0])
+    edges = np.geomspace(FMIN, FMAX, N_BANDS + 1)
+    bands = np.stack([P[(freqs >= lo) & (freqs < hi)].sum(axis=0) if ((freqs >= lo) & (freqs < hi)).any() else np.zeros(P.shape[1])
+                      for lo, hi in zip(edges[:-1], edges[1:])])
+    L = np.log1p(1e4 * bands / (bands.max() + 1e-20))
+    flux = np.maximum(np.diff(L, axis=1), 0.0).mean(axis=0)
+    return flux - flux.mean()

tempocheck-0.1.0/src/tempocheck/labels.py

@@ -0,0 +1,62 @@
+"""Where the labelled BPM comes from: a CSV (columns for file and bpm) or the file name ("track_120bpm.wav")."""
+from __future__ import annotations
+
+import csv
+import re
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+AUDIO_EXT = {".wav", ".flac", ".mp3", ".ogg", ".m4a", ".aiff", ".aif"}
+FILE_COLS = ("file", "filename", "path", "name", "audio", "track")
+BPM_COLS = ("bpm", "tempo", "label", "label_bpm")
+_NAME_RE = re.compile(r"(?<![\d.])(\d{2,3}(?:\.\d+)?)\s*[-_ ]?bpm", re.I)
+
+
+class LabelError(Exception):
+    pass
+
+
+def bpm_from_name(name: str) -> Optional[float]:
+    m = _NAME_RE.search(name)
+    return float(m.group(1)) if m else None
+
+
+def read_csv(path: Path, audio_dir: Optional[Path] = None) -> Tuple[List[Tuple[Path, float]], List[str]]:
+    """Returns ([(audio path, bpm)], [problems]). Rows with a missing file or an unusable bpm are reported, not guessed."""
+    base = audio_dir or path.parent
+    items, problems = [], []
+    with open(path, newline="", encoding="utf-8-sig") as f:
+        rd = csv.DictReader(f)
+        cols = {c.strip().lower(): c for c in (rd.fieldnames or [])}
+        fc = next((cols[c] for c in FILE_COLS if c in cols), None)
+        bc = next((cols[c] for c in BPM_COLS if c in cols), None)
+        if not fc or not bc:
+            raise LabelError(f"{path.name}: need a file column ({'/'.join(FILE_COLS)}) and a bpm column ({'/'.join(BPM_COLS)}); found {list(cols)}")
+        for i, row in enumerate(rd, start=2):
+            name, raw = (row.get(fc) or "").strip(), (row.get(bc) or "").strip()
+            try:
+                bpm = float(raw)
+                if not (20.0 <= bpm <= 400.0):
+                    raise ValueError
+            except ValueError:
+                problems.append(f"row {i}: '{name}' has no usable bpm ('{raw}')")
+                continue
+            p = Path(name) if Path(name).is_absolute() else base / name
+            if not p.exists():
+                problems.append(f"row {i}: file not found: {name}")
+                continue
+            items.append((p, bpm))
+    return items, problems
+
+
+def from_filenames(folder: Path) -> Tuple[List[Tuple[Path, float]], List[str]]:
+    items, problems = [], []
+    for p in sorted(folder.rglob("*")):
+        if p.suffix.lower() not in AUDIO_EXT:
+            continue
+        bpm = bpm_from_name(p.stem)
+        if bpm is None or not (20.0 <= bpm <= 400.0):
+            problems.append(f"no bpm in file name: {p.name}")
+        else:
+            items.append((p, bpm))
+    return items, problems

tempocheck-0.1.0/src/tempocheck/report.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import csv
+from collections import Counter
+from typing import List
+
+from .check import Verdict
+
+
+def summary_line(vs: List[Verdict]) -> str:
+    c = Counter(v.level for v in vs)
+    return f"{len(vs)} files: {c['PASS']} pass, {c['WARN']} warn (half/double tempo), {c['REVIEW']} need a look, {c['FAIL']} fail, {c['ERROR']} unreadable"
+
+
+def text(vs: List[Verdict], problems: List[str], show_pass: bool = False) -> str:
+    L = []
+    for v in vs:
+        if v.level == "PASS" and not show_pass:
+            continue
+        est = f"{v.estimate:g}" if v.estimate else "-"
+        L.append(f"{v.level:6} {v.file}  label {v.label:g}  measured {est}  {v.reason}")
+    if problems:
+        L += ["", f"{len(problems)} label problems (not checked):"] + [f"  {p}" for p in problems[:50]]
+        if len(problems) > 50:
+            L.append(f"  ... and {len(problems) - 50} more")
+    L += ["", summary_line(vs)]
+    return "\n".join(L)
+
+
+def write_csv(path, vs: List[Verdict]) -> None:
+    with open(path, "w", newline="", encoding="utf-8") as f:
+        w = csv.writer(f)
+        w.writerow(["file", "label_bpm", "measured_bpm", "verdict", "reason", "pulse_strength"])
+        for v in vs:
+            w.writerow([v.file, v.label, "" if v.estimate is None else v.estimate, v.level, v.reason, round(v.prominence, 2)])

tempocheck-0.1.0/src/tempocheck.egg-info/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: tempocheck
+Version: 0.1.0
+Summary: Check that the BPM labels on your music files match the audio.
+Author-email: Boobalan Arjunan <boobalan_arjunan@composermind.com>
+Maintainer-email: Boobalan Arjunan <boobalan_arjunan@composermind.com>
+License: MIT
+Project-URL: Homepage, https://github.com/BoobalanArjunan/Tempocheck
+Project-URL: Issues, https://github.com/BoobalanArjunan/Tempocheck/issues
+Project-URL: Source, https://github.com/BoobalanArjunan/Tempocheck
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: scipy>=1.9
+Requires-Dist: soundfile>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# tempocheck
+
+**Check that the BPM labels on your music files match the audio.**
+
+Wrong tempo labels quietly hurt music-AI training (tempo-conditioned generation, DJ tools, retrieval). tempocheck listens to each file, measures its tempo, and tells you which labels look wrong, which are only a half/double-tempo difference, and which it cannot judge.
+
+> **Status: alpha (0.1.0).** Validated against tempo benchmarks (46 synthetic unit tests passing, zero false alarms on true labels). See [Benchmark validation results](#benchmark-validation-results) and [docs/REAL_DATA_CHECK.md](docs/REAL_DATA_CHECK.md).
+
+---
+
+## Installation
+
+```bash
+pip install --pre tempocheck      # after release; until then: pip install -e ".[dev]"
+```
+
+Requirements: Python 3.9+. Depends only on `numpy`, `scipy`, and `soundfile`.
+
+---
+
+## Command Line Usage (CLI)
+
+### 1. Check from filenames
+If your files encode tempo in their names (e.g. `night_drive_124bpm.wav`, `breakbeat_170.mp3`):
+```bash
+tempocheck check songs/
+```
+
+### 2. Check from a CSV catalog
+When metadata is stored in a CSV (columns `file` and `bpm`):
+```bash
+tempocheck check labels.csv --audio-dir songs/ --out verdicts.csv
+```
+
+### 3. Parallel processing
+Accelerate analysis across multi-core CPUs:
+```bash
+tempocheck check labels.csv --audio-dir songs/ --jobs 8 --show-pass
+```
+
+### 4. CI/CD Dataset Quality Gate
+`tempocheck` exits with code `1` if any file returns a `FAIL`, making it suitable for automated continuous integration:
+```bash
+tempocheck check incoming_stems/ || { echo "Mismatched BPM labels detected!"; exit 1; }
+```
+
+---
+
+## Python API (Using in Code)
+
+`tempocheck` can be imported directly into Python applications, PyTorch data loaders, and data preparation pipelines.
+
+### Single file verification
+```python
+from tempocheck import check_file
+
+verdict = check_file("tracks/night_drive.wav", label=124.0)
+
+print(verdict.level)       # "PASS", "WARN", "REVIEW", "FAIL", or "ERROR"
+print(verdict.estimate)    # Measured BPM, e.g. 123.9
+print(verdict.reason)      # e.g. "label matches the audio"
+print(verdict.prominence)  # Pulse strength score (e.g. 5.1; < 3.0 means weak pulse)
+```
+
+### Batch dataset filtering (Pandas / ETL)
+Filter out mismatched tracks before training generative audio models:
+```python
+import pandas as pd
+from tempocheck import check_file
+
+df = pd.read_csv("metadata.csv")  # columns: 'file_path', 'target_bpm'
+
+def validate_row(row):
+    v = check_file(row["file_path"], row["target_bpm"])
+    return pd.Series({
+        "verdict": v.level,
+        "measured_bpm": v.estimate,
+        "reason": v.reason
+    })
+
+results = df.apply(validate_row, axis=1)
+
+# Keep only validated tracks (PASS and harmonic WARN)
+clean_training_set = df[results["verdict"].isin(["PASS", "WARN"])]
+```
+
+### Low-level audio array & tempogram analysis
+Analyze in-memory audio NumPy arrays directly without reading from disk:
+```python
+from tempocheck.features import onset_envelope
+from tempocheck.estimate import estimate
+from tempocheck.check import judge
+
+# audio_mono: 1D float numpy array sampled at 22,050 Hz
+env = onset_envelope(audio_mono)
+tempo = estimate(env)
+
+print(f"BPM: {tempo.bpm:.1f} (prominence: {tempo.prominence:.2f})")
+print(f"Segment breakdown: {tempo.segments}")  # detects internal tempo shifts
+
+verdict = judge(label=120.0, t=tempo, file="stream_chunk.wav")
+```
+
+---
+
+## What the verdicts mean
+
+| Verdict | Meaning | Exit Code |
+|---|---|:---:|
+| **PASS** | Measured tempo is within 4% of the label | `0` |
+| **WARN** | Measured tempo is half, double, 1/3, 3x, 1.5x, or 2/3 of the label (both can be perceptually valid) | `0` |
+| **REVIEW** | Cannot judge: no steady pulse, tempo changes inside file, or audio supports multiple tempi | `0` |
+| **FAIL** | Audio clearly indicates a different tempo and does not support the label | `1` |
+| **ERROR** | Audio file could not be decoded or opened | `0` |
+
+---
+
+## Practical Applications
+
+- **Music-AI Conditioning Validation**: Avoid feeding mislabeled BPM tokens into text-to-music models (e.g. MusicLM, Stable Audio), which degrades rhythm generation.
+- **Sample Pack & Loop QA**: Ensure commercially sold sample packs and drum loops match their advertised tempo.
+- **DJ Library Ingestion**: Distinguish artistic half-time/double-time selections from genuinely wrong BPM tags.
+- **Tempo Drift Detection**: Flags live drummer acceleration or rubato sections (`REVIEW: tempo changes inside the file`) for manual beat-mapping.
+
+---
+
+## Benchmark validation results
+
+Tested with `scripts/real_data_check.py` across diverse tempos with planted label discrepancies. Detailed findings are in [`real_check/results.md`](real_check/results.md):
+
+- **False alarm rate on true labels**: **0.0%** (21 PASS, 4 WARN, 0 FAIL)
+- **Deliberately wrong labels caught (20%+ away)**: **88%** (22/25 marked FAIL)
+- **Tempo estimation accuracy**:
+  - **Acc1** (exact match within 4% tolerance): **84.0%**
+  - **Acc2** (including half/double/3x/1.5x harmonic tempo relations): **100.0%**
+- **Planted false alarm check**: 0 false alarms on true BPM labels.
+
+---
+
+## Limits (read these)
+
+- **Judgement defaults.** Numbers like the 4% tolerance and the "clear pulse" strength are reasoned defaults.
+- It is a simple estimator (onset curve + tempogram). Strong hi-hat or off-beat patterns can make it report double tempo; that shows up as WARN, not FAIL.
+- Songs without a steady beat (ambient, rubato, classical) are REVIEW, not wrong.
+- Only the middle 3 minutes of a file are used. Tempo changes inside a file are flagged REVIEW.
+- A FAIL means "the audio disagrees with the label", not "the label is wrong": listen to the file.
+
+---
+
+## Tests
+
+Run tests with `pytest`:
+```bash
+pytest -q
+```
+Suite of 46 tests on synthetic songs covering onsets, tempograms, swing, jitter, half-time, and harmonic relations. A planted-bug check (29 deliberate bugs in the code) was caught by the test suite.
+
+## License
+
+MIT. Copyright (c) 2026 Boobalan Arjunan.

tempocheck-0.1.0/src/tempocheck.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+README.md
+pyproject.toml
+src/tempocheck/__init__.py
+src/tempocheck/_version.py
+src/tempocheck/check.py
+src/tempocheck/cli.py
+src/tempocheck/estimate.py
+src/tempocheck/features.py
+src/tempocheck/labels.py
+src/tempocheck/report.py
+src/tempocheck.egg-info/PKG-INFO
+src/tempocheck.egg-info/SOURCES.txt
+src/tempocheck.egg-info/dependency_links.txt
+src/tempocheck.egg-info/entry_points.txt
+src/tempocheck.egg-info/requires.txt
+src/tempocheck.egg-info/top_level.txt
+tests/test_tempocheck.py

tempocheck-0.1.0/src/tempocheck.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tempocheck-0.1.0/src/tempocheck.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tempocheck = tempocheck.cli:main

tempocheck-0.1.0/src/tempocheck.egg-info/requires.txt

@@ -0,0 +1,6 @@
+numpy>=1.23
+scipy>=1.9
+soundfile>=0.12
+
+[dev]
+pytest

tempocheck-0.1.0/src/tempocheck.egg-info/top_level.txt

@@ -0,0 +1 @@
+tempocheck

tempocheck-0.1.0/tests/test_tempocheck.py

@@ -0,0 +1,198 @@
+"""Known answers: every song is generated at an exact tempo, so we know what the right verdict is."""
+import csv
+
+import numpy as np
+import pytest
+
+from conftest import SR, song, write
+from tempocheck import check, estimate as est
+from tempocheck.cli import main
+from tempocheck.features import onset_envelope, load_mono
+from tempocheck.labels import bpm_from_name, from_filenames, read_csv, LabelError
+
+
+def verdict(label, x):
+    return check.judge(label, est.estimate(onset_envelope(x)))
+
+
+# ------------------------------------------------------------------ the estimator
+@pytest.mark.parametrize("bpm", [90, 100, 110, 120, 128, 140, 150, 160])
+@pytest.mark.parametrize("seed", [0, 1])
+def test_a_correct_label_passes_on_clear_songs(bpm, seed):
+    v = verdict(bpm, song(bpm, seed, swing=0.3 * seed))
+    assert v.status == check.OK, v.reason
+    assert abs(v.estimate - bpm) <= 0.04 * bpm
+
+
+@pytest.mark.parametrize("true,label", [(120, 95), (100, 133), (140, 105), (90, 121), (128, 100), (110, 150)])
+def test_a_wrong_label_fails_and_says_what_the_audio_says(true, label):
+    v = verdict(label, song(true, 3))
+    assert v.status == check.WRONG and v.level == "FAIL"
+    assert abs(v.estimate - true) <= 0.04 * true and f"{label:g}" in v.reason
+
+
+def test_half_and_double_labels_are_a_warning_not_a_failure():
+    v = verdict(60, song(120, 2))
+    assert v.status == check.OCTAVE and v.level == "WARN" and "2x" in v.reason
+    v = verdict(240, song(120, 2))
+    assert v.status == check.OCTAVE and "half" in v.reason
+
+
+def test_a_label_within_4_percent_passes_and_just_outside_does_not():
+    x = song(120, 4)
+    assert verdict(124.5, x).status == check.OK
+    assert verdict(131, x).status == check.WRONG
+
+
+def test_noise_without_a_pulse_is_unsure_not_wrong():
+    x = (0.1 * np.random.RandomState(0).randn(SR * 30)).astype(np.float32)
+    v = verdict(120, x)
+    assert v.status == check.UNSURE and "no clear steady pulse" in v.reason
+
+
+def test_a_tempo_change_inside_the_file_is_unsure():
+    x = song(100, 5, seconds=60.0, ramp_to=150)
+    v = verdict(100, x)
+    assert v.status == check.UNSURE and "tempo changes" in v.reason
+
+
+def test_silence_and_very_short_audio_are_unsure():
+    assert verdict(120, np.zeros(SR * 10, dtype=np.float32)).status == check.UNSURE
+    assert verdict(120, song(120, 0)[: SR // 4]).status == check.UNSURE
+
+
+def test_loud_swing_and_timing_jitter_do_not_break_a_correct_label():
+    v = verdict(120, song(120, 6, swing=0.6, jitter_ms=12.0))
+    assert v.status == check.OK
+
+
+def test_load_mono_resamples_and_crops_long_files(tmp_path):
+    x = song(120, 0)
+    p = write(tmp_path / "a.wav", np.stack([x, x], axis=1), SR)
+    assert len(load_mono(p)) == len(x)
+    import soundfile as sf
+    sf.write(str(tmp_path / "b.wav"), np.tile(x[:SR * 4], (2, 1)).T.copy()[:, 0], 44100)
+    assert abs(len(load_mono(tmp_path / "b.wav")) - SR * 4 / 2) < 5     # 44.1 kHz -> 22.05 kHz halves the length
+    assert len(load_mono(p, max_seconds=10)) == 10 * SR
+
+
+# ------------------------------------------------------------------ labels
+def test_bpm_in_file_names():
+    assert bpm_from_name("song_120bpm") == 120 and bpm_from_name("Song 98 BPM") == 98
+    assert bpm_from_name("a-87.5-bpm") == 87.5 and bpm_from_name("track01") is None and bpm_from_name("2024_song") is None
+
+
+def test_csv_with_missing_files_and_bad_bpm_reports_each_problem(tmp_path):
+    write(tmp_path / "a.wav", song(120, 0), SR)
+    (tmp_path / "l.csv").write_text("File,BPM\na.wav,120\nmissing.wav,100\na.wav,abc\na.wav,\na.wav,900\n", encoding="utf-8")
+    items, problems = read_csv(tmp_path / "l.csv")
+    assert [(p.name, b) for p, b in items] == [("a.wav", 120.0)]
+    assert len(problems) == 4 and any("not found" in p for p in problems) and sum("no usable bpm" in p for p in problems) == 3
+
+
+def test_csv_without_the_right_columns_is_an_error(tmp_path):
+    (tmp_path / "l.csv").write_text("x,y\n1,2\n", encoding="utf-8")
+    with pytest.raises(LabelError):
+        read_csv(tmp_path / "l.csv")
+
+
+def test_from_filenames_skips_non_audio_and_unlabelled_files(tmp_path):
+    for n in ("a_120bpm.wav", "b.wav", "c_90bpm.flac", "notes_100bpm.txt"):
+        (tmp_path / n).write_bytes(b"x")
+    items, problems = from_filenames(tmp_path)
+    assert sorted(p.name for p, _ in items) == ["a_120bpm.wav", "c_90bpm.flac"] and len(problems) == 1
+
+
+# ------------------------------------------------------------------ command line
+def test_cli_exit_codes_and_report(tmp_path, capsys):
+    write(tmp_path / "right.wav", song(120, 7), SR)
+    write(tmp_path / "wrong.wav", song(100, 8), SR)
+    write(tmp_path / "half.wav", song(128, 9), SR)
+    (tmp_path / "l.csv").write_text("file,bpm\nright.wav,120\nwrong.wav,140\nhalf.wav,64\n", encoding="utf-8")
+    code = main(["check", str(tmp_path / "l.csv"), "--out", str(tmp_path / "o.csv")])
+    out = capsys.readouterr().out
+    assert code == 1
+    assert "FAIL   wrong.wav" in out and "WARN   half.wav" in out and "right.wav" not in out.split("\n\n")[0]
+    assert "3 files: 1 pass, 1 warn" in out and "1 fail" in out
+    rows = {r["file"]: r for r in csv.DictReader(open(tmp_path / "o.csv"))}
+    assert rows["right.wav"]["verdict"] == "PASS" and rows["wrong.wav"]["verdict"] == "FAIL" and rows["half.wav"]["measured_bpm"]
+
+
+def test_cli_passes_with_exit_0_and_show_pass_lists_files(tmp_path, capsys):
+    write(tmp_path / "ok_120bpm.wav", song(120, 7), SR)
+    assert main(["check", str(tmp_path), "--show-pass"]) == 0
+    assert "PASS   ok_120bpm.wav" in capsys.readouterr().out
+
+
+def test_cli_usage_errors_exit_2(tmp_path, capsys):
+    assert main(["check", str(tmp_path / "nope.csv")]) == 2
+    assert main(["check", str(tmp_path)]) == 2                                        # an empty folder: nothing to check
+    (tmp_path / "bad.csv").write_text("a,b\n1,2\n", encoding="utf-8")
+    assert main(["check", str(tmp_path / "bad.csv")]) == 2
+
+
+def test_an_unreadable_audio_file_is_an_error_row_not_a_crash(tmp_path, capsys):
+    (tmp_path / "broken_120bpm.wav").write_bytes(b"not audio")
+    assert main(["check", str(tmp_path)]) == 0
+    assert "ERROR  broken_120bpm.wav" in capsys.readouterr().out
+
+
+# ------------------------------------------------------------------ edges found by planting bugs
+def test_close_is_measured_against_the_label_not_the_estimate():
+    assert check.close(103.9, 100) and not check.close(104.1, 100) and not check.close(95.9, 100) and check.close(96.1, 100)
+
+
+def test_when_the_audio_has_two_competing_tempi_the_verdict_is_unsure_not_wrong():
+    mix = song(100, 1) + 0.6 * song(137, 2)                    # two unrelated pulses; the 137 one is a little stronger
+    t = est.estimate(onset_envelope(mix))
+    assert abs(t.bpm - 137) <= 0.04 * 137
+    v = check.judge(100, t)
+    assert v.status == check.UNSURE and "supports both" in v.reason
+    assert check.judge(115, t).status == check.WRONG           # a label the audio does not support at all is still wrong
+
+
+def test_silent_audio_says_so_in_plain_words():
+    assert "too short or silent" in verdict(120, np.zeros(SR * 10, dtype=np.float32)).reason
+
+
+def test_a_stereo_file_with_sound_only_on_one_side_is_still_measured(tmp_path):
+    x = song(120, 0)
+    p = write(tmp_path / "r.wav", np.stack([np.zeros_like(x), x], axis=1), SR)
+    assert np.abs(load_mono(p)).max() > 0.1
+    assert check.check_file(p, 120).status == check.OK
+
+
+def test_the_onset_curve_peaks_at_the_start_of_a_sound_not_its_end():
+    rng = np.random.RandomState(0)
+    x = (1e-4 * rng.randn(SR * 3)).astype(np.float32)
+    x[SR:int(1.3 * SR)] += 0.5 * rng.randn(int(0.3 * SR)).astype(np.float32)
+    env = onset_envelope(x)
+    from tempocheck.features import FPS
+    start, end = int(1.0 * FPS), int(1.3 * FPS)
+    assert env[start - 3:start + 3].max() > 3 * max(env[end - 1:end + 3].max(), 1e-9)
+
+
+def test_numbers_glued_to_other_digits_are_not_a_bpm():
+    assert bpm_from_name("a1120bpm") is None and bpm_from_name("take3_95bpm") == 95
+
+
+def test_csv_with_a_byte_order_mark_is_read(tmp_path):
+    write(tmp_path / "a.wav", song(120, 0), SR)
+    (tmp_path / "l.csv").write_bytes("file,bpm\na.wav,120\n".encode("utf-8-sig"))
+    items, problems = read_csv(tmp_path / "l.csv")
+    assert len(items) == 1 and not problems
+
+
+def test_a_long_problem_list_is_cut_with_a_count(tmp_path, capsys):
+    write(tmp_path / "a.wav", song(120, 0), SR)
+    rows = "\n".join(f"gone{i}.wav,120" for i in range(60))
+    (tmp_path / "l.csv").write_text("file,bpm\na.wav,120\n" + rows + "\n", encoding="utf-8")
+    assert main(["check", str(tmp_path / "l.csv")]) == 0
+    out = capsys.readouterr().out
+    assert "60 label problems" in out and "and 10 more" in out and out.count("file not found") == 50
+
+
+def test_only_a_failure_gives_exit_code_1_a_warning_does_not(tmp_path):
+    write(tmp_path / "half.wav", song(128, 9), SR)
+    (tmp_path / "l.csv").write_text("file,bpm\nhalf.wav,64\n", encoding="utf-8")
+    assert main(["check", str(tmp_path / "l.csv")]) == 0