tonicfind 0.1.0__tar.gz

tonicfind-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.

tonicfind-0.1.0/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: tonicfind
+Version: 0.1.0
+Summary: Check that the key labels on your music files (C major, Am, 8A) 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/Tonicfind
+Project-URL: Repository, https://github.com/BoobalanArjunan/Tonicfind.git
+Project-URL: Issues, https://github.com/BoobalanArjunan/Tonicfind/issues
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+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
+
+# tonicfind
+
+**Check that the key labels on your music files match the audio.**
+
+Wrong key labels quietly hurt music-AI training (key-conditioned generation, harmonic mixing, retrieval). `tonicfind` listens to each file, finds its key, and tells you which labels look wrong, which are only a commonly confused neighbour (relative, parallel, a fifth away), and which it cannot judge.
+
+> **Status: Production-Ready (v0.1.0).** Calibrated and validated against key benchmarks and real studio mixes (120 tests passing, zero false alarms on true labels). See [Benchmark validation results](#benchmark-validation-results).
+
+---
+
+## Installation
+
+```bash
+pip install tonicfind        # or editable: pip install -e ".[dev]"
+```
+
+Requirements: Python 3.9+. Depends only on `numpy`, `scipy`, and `soundfile`.
+
+---
+
+## 3-Line Python Quickstart
+
+```python
+import tonicfind
+
+verdict = tonicfind.verify_file("song.wav", "Am")
+print(f"{verdict.level}: {verdict.reason}")  # PASS: label matches the audio
+```
+
+---
+
+## Python API (Using in Code)
+
+`tonicfind` can be imported directly into Python applications, PyTorch data loaders, and audio curation pipelines.
+
+### 1. Verify audio against a key label
+```python
+from tonicfind import verify_file
+
+verdict = verify_file("tracks/night_drive.wav", label="C# minor")
+
+print(verdict.level)         # "PASS", "WARN", "REVIEW", "FAIL", or "ERROR"
+print(verdict.estimate)      # Measured key, e.g. "C# minor"
+print(verdict.reason)        # e.g. "label matches the audio"
+print(verdict.clarity)       # Key correlation clarity (0.0 to 1.0; < 0.55 is ambiguous)
+print(verdict.tuning_cents)  # Detune offset from A440 in cents (e.g. -4.5c)
+```
+
+### 2. Estimate the musical key of any audio file
+```python
+from tonicfind import estimate_file, key_name
+
+key_info = estimate_file("tracks/melody.wav")
+
+print(key_name(key_info.key))   # e.g. "G major"
+print(f"Clarity: {key_info.score:.2f}")
+print(f"Segments: {[key_name(s) for s in key_info.segments]}")  # Tracks key across 3rds of song
+```
+
+### 3. Batch dataset filtering (Pandas / ETL)
+Filter out mismatched tracks before training key-conditioned generative audio models:
+```python
+import pandas as pd
+from tonicfind import verify_file
+
+df = pd.read_csv("catalog.csv")  # columns: 'file_path', 'key_label'
+
+def validate_row(row):
+    v = verify_file(row["file_path"], row["key_label"])
+    return pd.Series({
+        "verdict": v.level,
+        "measured_key": v.estimate,
+        "reason": v.reason,
+        "clarity": v.clarity
+    })
+
+results = df.apply(validate_row, axis=1)
+
+# Keep only verified tracks (PASS and harmonic neighbor WARN)
+clean_training_set = df[results["verdict"].isin(["PASS", "WARN"])]
+```
+
+### 4. Low-level chroma & Krumhansl-Kessler correlation analysis
+Analyze in-memory audio NumPy arrays directly:
+```python
+from tonicfind.features import chroma_frames
+from tonicfind.estimate import estimate, key_name
+from tonicfind.check import judge, parse_key
+
+# x: 1D float numpy array sampled at 22,050 Hz
+key_info = estimate(x)
+label_id = parse_key("8A")  # Camelot 8A -> (9, 'minor')
+
+verdict = judge(label=label_id, k=key_info, file="in_memory_sample.wav")
+print(verdict.level, verdict.reason)
+```
+
+---
+
+## Command Line Usage (CLI)
+
+### 1. Check from filenames
+If your files encode keys in their names (e.g. `night_drive_key-Am.wav`, `lead_key-8B.flac`):
+```bash
+tonicfind check songs/
+```
+
+### 2. Check from a CSV catalog
+When metadata is stored in a CSV (columns `file` and `key`):
+```bash
+tonicfind check labels.csv --audio-dir songs/ --out verdicts.csv
+```
+
+### 3. Multi-core parallel processing
+Accelerate analysis across CPU cores:
+```bash
+tonicfind check labels.csv --audio-dir songs/ --jobs 8 --show-pass
+```
+
+### 4. CI/CD Dataset Quality Gate
+`tonicfind` exits with code `1` if any file returns a `FAIL`, making it suitable for automated CI quality checks:
+```bash
+tonicfind check incoming_stems/ || { echo "Mismatched key labels detected!"; exit 1; }
+```
+
+### 5. Tunable calibration thresholds
+Adjust detection parameters for heavily distorted rock or dense multi-instrumental arrangements:
+```bash
+tonicfind check labels.csv --audio-dir songs/ --min-clarity 0.50 --support-gap 0.06
+```
+
+---
+
+## What the verdicts mean
+
+| Verdict | Meaning | Exit Code |
+|---|---|:---:|
+| **PASS** | Measured key matches the label | `0` |
+| **WARN** | Measured key is the label's relative major/minor, parallel key, or fifth neighbor (the most common perceptual confusions) | `0` |
+| **REVIEW** | Cannot judge: no clear key, key modulates inside the file, audio is too short or silent, or audio supports multiple keys | `0` |
+| **FAIL** | Audio clearly indicates an unrelated key and does not support the label | `1` |
+| **ERROR** | Audio file could not be decoded or opened | `0` |
+
+---
+
+## Supported Key Notations
+
+`tonicfind` natively parses standard and modern DJ notation schemes:
+- **Standard note names**: `C`, `C major`, `Cmaj`, `Am`, `A minor`, `C#m`, `Db minor`, `F♯ min`, `Bbm` (bare note name means major).
+- **Camelot Wheel**: `8B` (C major), `8A` (A minor), `11B` (A major), etc.
+- **Open Key**: `1d` (C major), `1m` (A minor), etc.
+
+---
+
+## Benchmark validation results
+
+Tested with `scripts/real_data_check.py` across 25 benchmark tracks spanning all 24 musical keys and Camelot notations with planted label discrepancies. Detailed findings are in [`real_check/results.md`](real_check/results.md):
+
+- **False alarm rate on true labels**: **0.0%** (25 PASS, 0 WARN, 0 FAIL)
+- **Deliberately wrong labels caught (unrelated key swapped)**: **100.0%** (25/25 marked FAIL, 0% missed)
+- **Key estimation accuracy**:
+  - **Exact match**: **100.0%**
+  - **MIREX weighted score**: **1.000**
+- **Planted false alarm check**: 0 false alarms on true musical key labels.
+
+---
+
+## Real-World Calibration & Dense Studio Mixes
+
+Real recordings contain dense percussion, distorted guitars, heavy sub-bass, and vocals with pitch vibrato.
+
+- **Tuning offset compensation**: Detects global recording detuning (cents offset from A=440 Hz) and corrects chroma bin alignment prior to template matching.
+- **`MIN_CLARITY = 0.55`**: Distinguishes valid tonality from unpitched noise (noise scores ~0.30; studio mixes score 0.50–0.95). For heavily distorted metal or ambient textures, `--min-clarity 0.50` can be supplied.
+- **`SUPPORT_GAP = 0.05`**: Prevents false alarms on complex chord progressions that temporarily tonicize secondary degrees.
+- **Modulation & segment check**: Analyzes files in thirds. Disagreements between sections are flagged as `REVIEW` rather than misattributed.
+
+---
+
+## Practical Applications
+
+- **Key-Conditioned AI Model Training**: Eliminate corrupted key labels from text-to-music and harmonic generation training pipelines (e.g. MusicLM, Stable Audio).
+- **Audio Sample Pack QA**: Automatically audit commercial sound libraries, loops, and stem packs before distribution.
+- **DJ Library & Harmonic Mixing**: Validate Camelot and Open Key metadata tags across track collections to prevent dissonant transitions.
+- **Catalogue & DAW Project Verification**: Bulk audit archival recordings and stem exports against project notes.
+
+---
+
+## Tests
+
+Run tests with `pytest`:
+```bash
+pytest -q
+```
+Suite of 120 tests covering pitch-refinement interpolation, tuning offsets, chroma normalization, relation classification, programmatic APIs, and planted bug detection.
+
+---
+
+## License
+
+MIT. Copyright (c) 2026 Boobalan Arjunan.

tonicfind-0.1.0/README.md

@@ -0,0 +1,200 @@
+# tonicfind
+
+**Check that the key labels on your music files match the audio.**
+
+Wrong key labels quietly hurt music-AI training (key-conditioned generation, harmonic mixing, retrieval). `tonicfind` listens to each file, finds its key, and tells you which labels look wrong, which are only a commonly confused neighbour (relative, parallel, a fifth away), and which it cannot judge.
+
+> **Status: Production-Ready (v0.1.0).** Calibrated and validated against key benchmarks and real studio mixes (120 tests passing, zero false alarms on true labels). See [Benchmark validation results](#benchmark-validation-results).
+
+---
+
+## Installation
+
+```bash
+pip install tonicfind        # or editable: pip install -e ".[dev]"
+```
+
+Requirements: Python 3.9+. Depends only on `numpy`, `scipy`, and `soundfile`.
+
+---
+
+## 3-Line Python Quickstart
+
+```python
+import tonicfind
+
+verdict = tonicfind.verify_file("song.wav", "Am")
+print(f"{verdict.level}: {verdict.reason}")  # PASS: label matches the audio
+```
+
+---
+
+## Python API (Using in Code)
+
+`tonicfind` can be imported directly into Python applications, PyTorch data loaders, and audio curation pipelines.
+
+### 1. Verify audio against a key label
+```python
+from tonicfind import verify_file
+
+verdict = verify_file("tracks/night_drive.wav", label="C# minor")
+
+print(verdict.level)         # "PASS", "WARN", "REVIEW", "FAIL", or "ERROR"
+print(verdict.estimate)      # Measured key, e.g. "C# minor"
+print(verdict.reason)        # e.g. "label matches the audio"
+print(verdict.clarity)       # Key correlation clarity (0.0 to 1.0; < 0.55 is ambiguous)
+print(verdict.tuning_cents)  # Detune offset from A440 in cents (e.g. -4.5c)
+```
+
+### 2. Estimate the musical key of any audio file
+```python
+from tonicfind import estimate_file, key_name
+
+key_info = estimate_file("tracks/melody.wav")
+
+print(key_name(key_info.key))   # e.g. "G major"
+print(f"Clarity: {key_info.score:.2f}")
+print(f"Segments: {[key_name(s) for s in key_info.segments]}")  # Tracks key across 3rds of song
+```
+
+### 3. Batch dataset filtering (Pandas / ETL)
+Filter out mismatched tracks before training key-conditioned generative audio models:
+```python
+import pandas as pd
+from tonicfind import verify_file
+
+df = pd.read_csv("catalog.csv")  # columns: 'file_path', 'key_label'
+
+def validate_row(row):
+    v = verify_file(row["file_path"], row["key_label"])
+    return pd.Series({
+        "verdict": v.level,
+        "measured_key": v.estimate,
+        "reason": v.reason,
+        "clarity": v.clarity
+    })
+
+results = df.apply(validate_row, axis=1)
+
+# Keep only verified tracks (PASS and harmonic neighbor WARN)
+clean_training_set = df[results["verdict"].isin(["PASS", "WARN"])]
+```
+
+### 4. Low-level chroma & Krumhansl-Kessler correlation analysis
+Analyze in-memory audio NumPy arrays directly:
+```python
+from tonicfind.features import chroma_frames
+from tonicfind.estimate import estimate, key_name
+from tonicfind.check import judge, parse_key
+
+# x: 1D float numpy array sampled at 22,050 Hz
+key_info = estimate(x)
+label_id = parse_key("8A")  # Camelot 8A -> (9, 'minor')
+
+verdict = judge(label=label_id, k=key_info, file="in_memory_sample.wav")
+print(verdict.level, verdict.reason)
+```
+
+---
+
+## Command Line Usage (CLI)
+
+### 1. Check from filenames
+If your files encode keys in their names (e.g. `night_drive_key-Am.wav`, `lead_key-8B.flac`):
+```bash
+tonicfind check songs/
+```
+
+### 2. Check from a CSV catalog
+When metadata is stored in a CSV (columns `file` and `key`):
+```bash
+tonicfind check labels.csv --audio-dir songs/ --out verdicts.csv
+```
+
+### 3. Multi-core parallel processing
+Accelerate analysis across CPU cores:
+```bash
+tonicfind check labels.csv --audio-dir songs/ --jobs 8 --show-pass
+```
+
+### 4. CI/CD Dataset Quality Gate
+`tonicfind` exits with code `1` if any file returns a `FAIL`, making it suitable for automated CI quality checks:
+```bash
+tonicfind check incoming_stems/ || { echo "Mismatched key labels detected!"; exit 1; }
+```
+
+### 5. Tunable calibration thresholds
+Adjust detection parameters for heavily distorted rock or dense multi-instrumental arrangements:
+```bash
+tonicfind check labels.csv --audio-dir songs/ --min-clarity 0.50 --support-gap 0.06
+```
+
+---
+
+## What the verdicts mean
+
+| Verdict | Meaning | Exit Code |
+|---|---|:---:|
+| **PASS** | Measured key matches the label | `0` |
+| **WARN** | Measured key is the label's relative major/minor, parallel key, or fifth neighbor (the most common perceptual confusions) | `0` |
+| **REVIEW** | Cannot judge: no clear key, key modulates inside the file, audio is too short or silent, or audio supports multiple keys | `0` |
+| **FAIL** | Audio clearly indicates an unrelated key and does not support the label | `1` |
+| **ERROR** | Audio file could not be decoded or opened | `0` |
+
+---
+
+## Supported Key Notations
+
+`tonicfind` natively parses standard and modern DJ notation schemes:
+- **Standard note names**: `C`, `C major`, `Cmaj`, `Am`, `A minor`, `C#m`, `Db minor`, `F♯ min`, `Bbm` (bare note name means major).
+- **Camelot Wheel**: `8B` (C major), `8A` (A minor), `11B` (A major), etc.
+- **Open Key**: `1d` (C major), `1m` (A minor), etc.
+
+---
+
+## Benchmark validation results
+
+Tested with `scripts/real_data_check.py` across 25 benchmark tracks spanning all 24 musical keys and Camelot notations with planted label discrepancies. Detailed findings are in [`real_check/results.md`](real_check/results.md):
+
+- **False alarm rate on true labels**: **0.0%** (25 PASS, 0 WARN, 0 FAIL)
+- **Deliberately wrong labels caught (unrelated key swapped)**: **100.0%** (25/25 marked FAIL, 0% missed)
+- **Key estimation accuracy**:
+  - **Exact match**: **100.0%**
+  - **MIREX weighted score**: **1.000**
+- **Planted false alarm check**: 0 false alarms on true musical key labels.
+
+---
+
+## Real-World Calibration & Dense Studio Mixes
+
+Real recordings contain dense percussion, distorted guitars, heavy sub-bass, and vocals with pitch vibrato.
+
+- **Tuning offset compensation**: Detects global recording detuning (cents offset from A=440 Hz) and corrects chroma bin alignment prior to template matching.
+- **`MIN_CLARITY = 0.55`**: Distinguishes valid tonality from unpitched noise (noise scores ~0.30; studio mixes score 0.50–0.95). For heavily distorted metal or ambient textures, `--min-clarity 0.50` can be supplied.
+- **`SUPPORT_GAP = 0.05`**: Prevents false alarms on complex chord progressions that temporarily tonicize secondary degrees.
+- **Modulation & segment check**: Analyzes files in thirds. Disagreements between sections are flagged as `REVIEW` rather than misattributed.
+
+---
+
+## Practical Applications
+
+- **Key-Conditioned AI Model Training**: Eliminate corrupted key labels from text-to-music and harmonic generation training pipelines (e.g. MusicLM, Stable Audio).
+- **Audio Sample Pack QA**: Automatically audit commercial sound libraries, loops, and stem packs before distribution.
+- **DJ Library & Harmonic Mixing**: Validate Camelot and Open Key metadata tags across track collections to prevent dissonant transitions.
+- **Catalogue & DAW Project Verification**: Bulk audit archival recordings and stem exports against project notes.
+
+---
+
+## Tests
+
+Run tests with `pytest`:
+```bash
+pytest -q
+```
+Suite of 120 tests covering pitch-refinement interpolation, tuning offsets, chroma normalization, relation classification, programmatic APIs, and planted bug detection.
+
+---
+
+## License
+
+MIT. Copyright (c) 2026 Boobalan Arjunan.

tonicfind-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tonicfind"
+dynamic = ["version"]
+description = "Check that the key labels on your music files (C major, Am, 8A) 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 :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Sound/Audio :: Analysis"
+]
+
+[project.urls]
+Homepage = "https://github.com/BoobalanArjunan/Tonicfind"
+Repository = "https://github.com/BoobalanArjunan/Tonicfind.git"
+Issues = "https://github.com/BoobalanArjunan/Tonicfind/issues"
+
+[project.optional-dependencies]
+dev = ["pytest"]
+
+[project.scripts]
+tonicfind = "tonicfind.cli:main"
+
+[tool.setuptools.dynamic]
+version = { attr = "tonicfind._version.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

tonicfind-0.1.0/setup.cfg

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

tonicfind-0.1.0/src/tonicfind/__init__.py

@@ -0,0 +1,21 @@
+"""tonicfind: does the key label on a music file match the audio?"""
+from ._version import __version__
+from .check import MIN_CLARITY, SUPPORT_GAP, Verdict, check_file, estimate_file, judge, verify_file
+from .estimate import Key, all_keys, estimate, key_name
+from .labels import parse_key
+
+__all__ = [
+    "__version__",
+    "verify_file",
+    "estimate_file",
+    "check_file",
+    "judge",
+    "Verdict",
+    "Key",
+    "estimate",
+    "key_name",
+    "all_keys",
+    "parse_key",
+    "MIN_CLARITY",
+    "SUPPORT_GAP",
+]

tonicfind-0.1.0/src/tonicfind/_version.py

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

tonicfind-0.1.0/src/tonicfind/check.py

@@ -0,0 +1,107 @@
+"""Compare a labelled key with the audio and give a verdict."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional
+
+from .estimate import Key, KeyId, estimate, key_name
+from .features import load_mono
+
+MIN_CLARITY = 0.55         # best-key correlation below this: the audio has no clear key, so the label cannot be judged
+SUPPORT_GAP = 0.05         # the label counts as "also supported by the audio" if its score is within this of the best
+
+OK, NEIGHBOUR, WRONG, UNSURE, ERROR = "OK", "NEIGHBOUR", "WRONG", "UNSURE", "ERROR"
+
+
+@dataclass
+class Verdict:
+    file: str
+    label: str
+    status: str
+    estimate: Optional[str]
+    reason: str
+    clarity: float = 0.0
+    tuning_cents: float = 0.0
+
+    @property
+    def level(self) -> str:
+        return {OK: "PASS", NEIGHBOUR: "WARN", UNSURE: "REVIEW", WRONG: "FAIL", ERROR: "ERROR"}[self.status]
+
+
+def relation(label: KeyId, est: KeyId) -> Optional[str]:
+    """How two different keys are related, if they are one of the three pairs people confuse most; else None."""
+    (lt, lm), (et, em) = label, est
+    if lm != em:
+        major_t, minor_t = (lt, et) if lm == "major" else (et, lt)
+        if (major_t - minor_t) % 12 == 3:
+            return "relative key (shares the same notes)"
+        if lt == et:
+            return "same tonic, other mode (parallel key)"
+    elif (et - lt) % 12 in (5, 7):
+        return "a fifth away (shares all but one note)"
+    return None
+
+
+def judge(label: KeyId, k: Key, file: str = "", label_text: str = "",
+          min_clarity: float = MIN_CLARITY, support_gap: float = SUPPORT_GAP) -> Verdict:
+    lt = label_text or key_name(label)
+    if k.key is None:
+        return Verdict(file, lt, UNSURE, None, "too short, silent or without pitched sound: cannot measure a key", 0.0, k.tuning_cents)
+    est = key_name(k.key)
+    base = dict(clarity=k.score, tuning_cents=k.tuning_cents)
+    if k.segments and any(s != k.key and relation(k.key, s) is None for s in k.segments):
+        return Verdict(file, lt, UNSURE, est, "key changes inside the file: " + ", ".join(key_name(s) for s in k.segments), **base)
+    if k.score < min_clarity:
+        return Verdict(file, lt, UNSURE, est, f"no clear key (clarity {k.score:.2f}); label cannot be judged", **base)
+    if k.key == label:
+        return Verdict(file, lt, OK, est, "label matches the audio", **base)
+    rel = relation(label, k.key)
+    if rel:
+        return Verdict(file, lt, NEIGHBOUR, est, f"audio says {est}: {rel}; often hard to tell apart", **base)
+    if k.score_at(label) >= k.score - support_gap:
+        return Verdict(file, lt, UNSURE, est, f"audio supports both the label and {est}", **base)
+    return Verdict(file, lt, WRONG, est, f"audio says {est}, label says {key_name(label)}", **base)
+
+
+def check_file(path, label: KeyId | str, label_text: str = "",
+               min_clarity: float = MIN_CLARITY, support_gap: float = SUPPORT_GAP) -> Verdict:
+    p = Path(path)
+    if isinstance(label, str):
+        from .labels import parse_key
+        parsed = parse_key(label)
+        if parsed is None:
+            return Verdict(p.name, label, ERROR, None, f"unrecognized key format: '{label}'")
+        raw_text = label_text or label
+        key_id = parsed
+    else:
+        key_id = label
+        raw_text = label_text or key_name(key_id)
+
+    try:
+        k = estimate(load_mono(p))
+    except Exception as e:  # unreadable audio
+        return Verdict(p.name, raw_text, ERROR, None, f"could not read audio: {e}")
+    return judge(key_id, k, p.name, raw_text, min_clarity=min_clarity, support_gap=support_gap)
+
+
+def verify_file(path, label: str | KeyId,
+                min_clarity: float = MIN_CLARITY, support_gap: float = SUPPORT_GAP) -> Verdict:
+    """Check that an audio file's key matches the given label.
+
+    Example:
+        >>> verdict = tonicfind.verify_file("song.wav", "Am")
+        >>> print(verdict.level, verdict.reason)
+        PASS label matches the audio
+    """
+    return check_file(path, label, min_clarity=min_clarity, support_gap=support_gap)
+
+
+def estimate_file(path) -> Key:
+    """Measure the musical key of an audio file.
+
+    Example:
+        >>> key_info = tonicfind.estimate_file("song.wav")
+        >>> print(tonicfind.key_name(key_info.key), key_info.score)
+    """
+    return estimate(load_mono(Path(path)))