bandcheck 0.1.0__tar.gz

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

bandcheck-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: bandcheck
+Version: 0.1.0
+Summary: Find audio files whose real frequency range is lower than their sample rate claims (upsampled or lossy-encoded).
+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/Bandcheck
+Project-URL: Issues, https://github.com/BoobalanArjunan/Bandcheck/issues
+Project-URL: Source, https://github.com/BoobalanArjunan/Bandcheck
+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
+
+# bandcheck
+
+**Find audio files whose real frequency range is lower than their sample rate claims.**
+
+A file saved as "48 kHz WAV" may hold audio that was recorded at 16 kHz and upsampled, or that went through an MP3 or AAC encoder before being converted back. Everything above the source's limit is empty. A header never shows this. bandcheck measures where the sound really stops and tells you which files hold much less than they claim.
+
+> **Status: alpha (0.1.0).** Tested on generated audio, real speech recordings (LibriSpeech dev-clean), and 44.1 kHz studio music (MUSDB18-HQ). Run `scripts/real_data_check.py` (see `docs/REAL_DATA_CHECK.md`) on your own data.
+
+## Install
+
+```bash
+pip install --pre bandcheck      # after it is published; until then: pip install -e ".[dev]"
+```
+Needs Python 3.9+. Depends only on numpy, scipy, soundfile.
+
+## Use
+
+```bash
+bandcheck check my_dataset/                        # every audio file in the folder
+bandcheck check clip.wav
+bandcheck check my_dataset/ --need-hz 8000 --out verdicts.csv
+```
+Options: `--need-hz N` (fail files whose sound stops below N Hz, e.g. 8000 for a 16 kHz speech model), `--show-pass`, `--jobs 4`, `--out file.csv`.
+The report ends with a table by sample rate (files, how many are flagged, median cut-off), so you see at once that, for example, one rate holds most of the problem files.
+
+## What the verdicts mean
+
+| verdict | meaning | exit code |
+|---|---|---|
+| PASS | no sharp cut-off, or the sound reaches at least 90% of the way to the Nyquist frequency (or 19.5 kHz) | 0 |
+| WARN | sound stops at 60-90% of the way to Nyquist. Typical of an MP3/AAC lowpass or a source one step lower in rate | 0 |
+| FAIL | sound stops below 60% of the way, or below the `--need-hz` you asked for. Typical of upsampled audio | 1 |
+| REVIEW | too short, silent, or too few loud parts to measure | 0 |
+| ERROR | file could not be read | 0 |
+
+For WARN and FAIL it lists the likely causes, for example `upsampled from 16000 Hz or a lossy encoder's lowpass (MP3/AAC)`. One cut-off frequency cannot tell an upsampled file from a lossy encode, so every candidate is listed and you decide.
+
+## How it works (short)
+1. Reads the file at its own sample rate (no resampling) and averages the channels.
+2. Averages the power spectrum over the loud parts (frames within 30 dB of the loudest).
+3. Looks for the sharpest drop in that average: the level just below a frequency compared with the level just above it. A drop of 25 dB or more, with nothing coming back above it, counts as a cut-off. The cut-off is reported where the level has fallen 10 dB.
+4. Compares the cut-off with the Nyquist frequency of the file.
+
+## What has been measured
+
+### 1. Real Speech Audio (LibriSpeech dev-clean, 200 files)
+- **Original recordings:**
+  - 185 PASS, 11 WARN, 1 FAIL, 3 REVIEW, 0 ERROR.
+  - Flagged files exhibited genuine hardware or codec lowpass cut-offs (e.g. 4.8 kHz cut-off on `7850-286674-0017.flac`, 7.0–7.1 kHz on audiobook recordings).
+- **Planted upsampling test (185 files evaluated):**
+  - From 8 kHz: 185 / 185 flagged as FAIL (median detected cut-off ratio: 1.03).
+  - From 11.025 kHz: 185 / 185 flagged as WARN (median detected cut-off ratio: 1.05).
+  - Detected cut-off sat within 3–5% of the source Nyquist frequency (consistent with resampling anti-aliasing filter transition).
+
+![Spectrogram Verification](real_check/spectrogram_verification.png)
+
+### 2. Real 44.1 kHz Studio Music (MUSDB18-HQ, 200 files)
+- **Original recordings:**
+  - 197 PASS (98.5%), 2 WARN, 0 FAIL, 1 REVIEW, 0 ERROR.
+  - Flagged originals: 2 files (`other.wav` at 19.1 kHz, `drums.wav` at 19.3 kHz, both at 87% of 22.05 kHz Nyquist).
+- **Planted upsampling test (197 files evaluated):**
+  - From 8 kHz: 191 / 197 flagged as FAIL (median ratio 1.02).
+  - From 11.025 kHz: 185 / 197 flagged as FAIL (median ratio 1.05).
+  - From 16 kHz: 162 / 197 flagged as FAIL (median ratio 1.10).
+- **Planted MP3 encodes:**
+  - 64 kbps: 171 / 197 flagged, median cut-off 11.1 kHz.
+  - 128 kbps: 157 / 197 flagged, median cut-off 16.5 kHz.
+
+### 3. Synthetic Audio & Bug Injection
+- Full-band audio at 16, 22.05, 44.1 and 48 kHz: no cut-off found, PASS.
+- Audio lowpassed at 16, 19 and 20 kHz (44.1 and 48 kHz files) and 6-7 kHz (16 kHz files): cut-off found within 2% of where it was put.
+- Audio upsampled from 8, 11.025, 16, 22.05 and 24 kHz: flagged every time; the cut-off sits about 4-11% above the source's Nyquist frequency, because resampler filters roll off a little past it.
+- MP3 copies made with ffmpeg (mono): 64 kbps gave a cut-off near 16.6 kHz (WARN); 128, 192 and 256 kbps gave about 20.1 kHz (PASS).
+- 79 tests pass. 25 deliberately planted bugs in the code were each caught by the tests (5 needed a stronger test first).
+
+## Limits (read these)
+- **Defaults and thresholds:** The 25 dB drop, the 90% and 60% limits and the 19.5 kHz rule are judgement defaults set on generated audio; on 200 LibriSpeech dev-clean files, 12 were flagged (11 WARN, 1 FAIL), and caught 370 of 370 planted copies (from 8 and 11.025 kHz sources).
+- **Cannot tell upsampled from lossy-encoded** from one number, and cannot tell either from a recording that really was made with a limited microphone or filter. It reports where the sound stops, not why.
+- **Gradual roll-offs are not detected.** A gentle filter with no sharp edge, or dull-sounding music, passes.
+- **Cut-offs below 2.5 kHz are not looked for.** Speech and music change a lot there.
+- A quiet recording or one with long silences is judged on its louder parts only.
+- The channels are averaged, so a file with one full-band channel and one band-limited channel passes.
+- It tells you the bandwidth, not whether the audio is good.
+
+## Licence
+MIT.

bandcheck-0.1.0/README.md

@@ -0,0 +1,86 @@
+# bandcheck
+
+**Find audio files whose real frequency range is lower than their sample rate claims.**
+
+A file saved as "48 kHz WAV" may hold audio that was recorded at 16 kHz and upsampled, or that went through an MP3 or AAC encoder before being converted back. Everything above the source's limit is empty. A header never shows this. bandcheck measures where the sound really stops and tells you which files hold much less than they claim.
+
+> **Status: alpha (0.1.0).** Tested on generated audio, real speech recordings (LibriSpeech dev-clean), and 44.1 kHz studio music (MUSDB18-HQ). Run `scripts/real_data_check.py` (see `docs/REAL_DATA_CHECK.md`) on your own data.
+
+## Install
+
+```bash
+pip install --pre bandcheck      # after it is published; until then: pip install -e ".[dev]"
+```
+Needs Python 3.9+. Depends only on numpy, scipy, soundfile.
+
+## Use
+
+```bash
+bandcheck check my_dataset/                        # every audio file in the folder
+bandcheck check clip.wav
+bandcheck check my_dataset/ --need-hz 8000 --out verdicts.csv
+```
+Options: `--need-hz N` (fail files whose sound stops below N Hz, e.g. 8000 for a 16 kHz speech model), `--show-pass`, `--jobs 4`, `--out file.csv`.
+The report ends with a table by sample rate (files, how many are flagged, median cut-off), so you see at once that, for example, one rate holds most of the problem files.
+
+## What the verdicts mean
+
+| verdict | meaning | exit code |
+|---|---|---|
+| PASS | no sharp cut-off, or the sound reaches at least 90% of the way to the Nyquist frequency (or 19.5 kHz) | 0 |
+| WARN | sound stops at 60-90% of the way to Nyquist. Typical of an MP3/AAC lowpass or a source one step lower in rate | 0 |
+| FAIL | sound stops below 60% of the way, or below the `--need-hz` you asked for. Typical of upsampled audio | 1 |
+| REVIEW | too short, silent, or too few loud parts to measure | 0 |
+| ERROR | file could not be read | 0 |
+
+For WARN and FAIL it lists the likely causes, for example `upsampled from 16000 Hz or a lossy encoder's lowpass (MP3/AAC)`. One cut-off frequency cannot tell an upsampled file from a lossy encode, so every candidate is listed and you decide.
+
+## How it works (short)
+1. Reads the file at its own sample rate (no resampling) and averages the channels.
+2. Averages the power spectrum over the loud parts (frames within 30 dB of the loudest).
+3. Looks for the sharpest drop in that average: the level just below a frequency compared with the level just above it. A drop of 25 dB or more, with nothing coming back above it, counts as a cut-off. The cut-off is reported where the level has fallen 10 dB.
+4. Compares the cut-off with the Nyquist frequency of the file.
+
+## What has been measured
+
+### 1. Real Speech Audio (LibriSpeech dev-clean, 200 files)
+- **Original recordings:**
+  - 185 PASS, 11 WARN, 1 FAIL, 3 REVIEW, 0 ERROR.
+  - Flagged files exhibited genuine hardware or codec lowpass cut-offs (e.g. 4.8 kHz cut-off on `7850-286674-0017.flac`, 7.0–7.1 kHz on audiobook recordings).
+- **Planted upsampling test (185 files evaluated):**
+  - From 8 kHz: 185 / 185 flagged as FAIL (median detected cut-off ratio: 1.03).
+  - From 11.025 kHz: 185 / 185 flagged as WARN (median detected cut-off ratio: 1.05).
+  - Detected cut-off sat within 3–5% of the source Nyquist frequency (consistent with resampling anti-aliasing filter transition).
+
+![Spectrogram Verification](real_check/spectrogram_verification.png)
+
+### 2. Real 44.1 kHz Studio Music (MUSDB18-HQ, 200 files)
+- **Original recordings:**
+  - 197 PASS (98.5%), 2 WARN, 0 FAIL, 1 REVIEW, 0 ERROR.
+  - Flagged originals: 2 files (`other.wav` at 19.1 kHz, `drums.wav` at 19.3 kHz, both at 87% of 22.05 kHz Nyquist).
+- **Planted upsampling test (197 files evaluated):**
+  - From 8 kHz: 191 / 197 flagged as FAIL (median ratio 1.02).
+  - From 11.025 kHz: 185 / 197 flagged as FAIL (median ratio 1.05).
+  - From 16 kHz: 162 / 197 flagged as FAIL (median ratio 1.10).
+- **Planted MP3 encodes:**
+  - 64 kbps: 171 / 197 flagged, median cut-off 11.1 kHz.
+  - 128 kbps: 157 / 197 flagged, median cut-off 16.5 kHz.
+
+### 3. Synthetic Audio & Bug Injection
+- Full-band audio at 16, 22.05, 44.1 and 48 kHz: no cut-off found, PASS.
+- Audio lowpassed at 16, 19 and 20 kHz (44.1 and 48 kHz files) and 6-7 kHz (16 kHz files): cut-off found within 2% of where it was put.
+- Audio upsampled from 8, 11.025, 16, 22.05 and 24 kHz: flagged every time; the cut-off sits about 4-11% above the source's Nyquist frequency, because resampler filters roll off a little past it.
+- MP3 copies made with ffmpeg (mono): 64 kbps gave a cut-off near 16.6 kHz (WARN); 128, 192 and 256 kbps gave about 20.1 kHz (PASS).
+- 79 tests pass. 25 deliberately planted bugs in the code were each caught by the tests (5 needed a stronger test first).
+
+## Limits (read these)
+- **Defaults and thresholds:** The 25 dB drop, the 90% and 60% limits and the 19.5 kHz rule are judgement defaults set on generated audio; on 200 LibriSpeech dev-clean files, 12 were flagged (11 WARN, 1 FAIL), and caught 370 of 370 planted copies (from 8 and 11.025 kHz sources).
+- **Cannot tell upsampled from lossy-encoded** from one number, and cannot tell either from a recording that really was made with a limited microphone or filter. It reports where the sound stops, not why.
+- **Gradual roll-offs are not detected.** A gentle filter with no sharp edge, or dull-sounding music, passes.
+- **Cut-offs below 2.5 kHz are not looked for.** Speech and music change a lot there.
+- A quiet recording or one with long silences is judged on its louder parts only.
+- The channels are averaged, so a file with one full-band channel and one band-limited channel passes.
+- It tells you the bandwidth, not whether the audio is good.
+
+## Licence
+MIT.

bandcheck-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bandcheck"
+dynamic = ["version"]
+description = "Find audio files whose real frequency range is lower than their sample rate claims (upsampled or lossy-encoded)."
+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/Bandcheck"
+Issues = "https://github.com/BoobalanArjunan/Bandcheck/issues"
+Source = "https://github.com/BoobalanArjunan/Bandcheck"
+
+[project.optional-dependencies]
+dev = ["pytest"]
+
+[project.scripts]
+bandcheck = "bandcheck.cli:main"
+
+[tool.setuptools.dynamic]
+version = { attr = "bandcheck._version.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

bandcheck-0.1.0/setup.cfg

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

bandcheck-0.1.0/src/bandcheck/__init__.py

@@ -0,0 +1,5 @@
+"""bandcheck: does an audio file really hold the frequency range its sample rate promises?"""
+from ._version import __version__
+from .check import Verdict, check_file, judge
+
+__all__ = ["__version__", "Verdict", "check_file", "judge"]

bandcheck-0.1.0/src/bandcheck/_version.py

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

bandcheck-0.1.0/src/bandcheck/check.py

@@ -0,0 +1,89 @@
+"""Compare the real bandwidth of a file with what its sample rate promises, and give a verdict."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional
+
+import numpy as np
+
+from .spectrum import Spectrum, find_cliff, load_mono, mean_spectrum
+
+FULL_FRACTION = 0.90       # cut-off at or above this share of the Nyquist frequency: full band
+FULL_HZ = 19500.0          # ... or at or above this frequency, whatever the sample rate
+FAKE_FRACTION = 0.60       # cut-off below this share of Nyquist: the file holds much less than it claims
+NATIVE_RATES = (8000, 11025, 12000, 16000, 22050, 24000, 32000, 44100)
+RATE_LOW, RATE_HIGH = 0.90, 1.12     # the measured cut-off sits at 0.9 to 1.12 times the source's Nyquist (resampler filters)
+
+OK, LIMITED, FAKE, UNSURE, ERROR = "OK", "LIMITED", "FAKE", "UNSURE", "ERROR"
+
+
+@dataclass
+class Verdict:
+    file: str
+    sample_rate: Optional[int]
+    status: str
+    cutoff_hz: Optional[float]
+    reason: str
+    likely_source: str = ""
+    seconds: float = 0.0
+
+    @property
+    def level(self) -> str:
+        return {OK: "PASS", LIMITED: "WARN", UNSURE: "REVIEW", FAKE: "FAIL", ERROR: "ERROR"}[self.status]
+
+    @property
+    def fraction(self) -> Optional[float]:
+        return None if (self.cutoff_hz is None or not self.sample_rate) else self.cutoff_hz / (self.sample_rate / 2)
+
+
+def source_guess(cutoff_hz: float, sample_rate: int) -> str:
+    """One cut-off cannot tell an upsampled file from a lossy encode, so every candidate is listed."""
+    rates = [r for r in NATIVE_RATES if r < sample_rate and RATE_LOW <= cutoff_hz / (r / 2) <= RATE_HIGH]
+    parts = (["upsampled from " + " or ".join(f"{r} Hz" for r in rates)] if rates else []) + ["a lossy encoder's lowpass (MP3/AAC)"]
+    return " or ".join(parts)
+
+
+def judge(sp: Optional[Spectrum], file: str = "", sample_rate: Optional[int] = None, need_hz: Optional[float] = None) -> Verdict:
+    if sp is None:
+        return Verdict(file, sample_rate, UNSURE, None, "too short, silent or too few loud parts to measure a bandwidth")
+    sr, nyq, secs = sp.sample_rate, sp.sample_rate / 2, sp.active_seconds
+    c = find_cliff(sp)
+    if c is None:
+        return Verdict(file, sr, OK, None, "no sharp cut-off found", "", secs)
+    frac = c.cutoff_hz / nyq
+    kHz = c.cutoff_hz / 1000
+    if need_hz is not None and c.cutoff_hz < need_hz:
+        return Verdict(file, sr, FAKE, c.cutoff_hz, f"sound stops at {kHz:.1f} kHz, but {need_hz / 1000:g} kHz is required", source_guess(c.cutoff_hz, sr), secs)
+    if frac >= FULL_FRACTION or c.cutoff_hz >= FULL_HZ:
+        return Verdict(file, sr, OK, c.cutoff_hz, f"sound reaches {kHz:.1f} kHz ({100 * frac:.0f}% of the way to {nyq / 1000:g} kHz)", "", secs)
+    if frac < FAKE_FRACTION:
+        return Verdict(file, sr, FAKE, c.cutoff_hz, f"sound stops at {kHz:.1f} kHz, only {100 * frac:.0f}% of the way to {nyq / 1000:g} kHz", source_guess(c.cutoff_hz, sr), secs)
+    return Verdict(file, sr, LIMITED, c.cutoff_hz, f"sound stops at {kHz:.1f} kHz ({100 * frac:.0f}% of the way to {nyq / 1000:g} kHz)", source_guess(c.cutoff_hz, sr), secs)
+
+
+def check_file(path, need_hz: Optional[float] = None) -> Verdict:
+    p = Path(path)
+    try:
+        x, sr = load_mono(p)
+    except Exception as e:  # unreadable audio
+        return Verdict(p.name, None, ERROR, None, f"could not read audio: {e}")
+    return judge(mean_spectrum(x, sr), p.name, sr, need_hz)
+
+
+def summary_by_rate(vs: List[Verdict]) -> List[dict]:
+    """One row per sample rate: files, how many are flagged (WARN or FAIL), median cut-off among those with a cut-off."""
+    rows = {}
+    for v in vs:
+        if v.sample_rate is None:
+            continue
+        r = rows.setdefault(v.sample_rate, {"rate": v.sample_rate, "files": 0, "flagged": 0, "cutoffs": []})
+        r["files"] += 1
+        r["flagged"] += v.level in ("WARN", "FAIL")
+        if v.cutoff_hz:
+            r["cutoffs"].append(v.cutoff_hz)
+    out = []
+    for r in sorted(rows.values(), key=lambda r: r["rate"]):
+        out.append({"rate": r["rate"], "files": r["files"], "flagged": r["flagged"],
+                    "median_cutoff_hz": float(np.median(r["cutoffs"])) if r["cutoffs"] else None})
+    return out

bandcheck-0.1.0/src/bandcheck/cli.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from concurrent.futures import ProcessPoolExecutor
+from functools import partial
+from pathlib import Path
+
+from . import __version__
+from .check import check_file
+from .report import text, write_csv
+
+AUDIO_EXT = {".wav", ".flac", ".mp3", ".ogg", ".m4a", ".aiff", ".aif"}
+
+
+def find_audio(source: Path):
+    if source.is_file():
+        return [source]
+    return sorted(p for p in source.rglob("*") if p.suffix.lower() in AUDIO_EXT and not p.name.startswith("._") and "__MACOSX" not in p.parts)
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="bandcheck", description="Find audio files whose real frequency range is lower than their sample rate claims.")
+    ap.add_argument("--version", action="version", version=f"bandcheck {__version__}")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    c = sub.add_parser("check", help="check one file or every audio file in a folder")
+    c.add_argument("source", type=Path)
+    c.add_argument("--need-hz", type=float, help="fail files whose sound stops below this frequency (for example 8000 for 16 kHz speech models)")
+    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)
+
+    if not a.source.exists():
+        print(f"error: {a.source} not found", file=sys.stderr)
+        return 2
+    files = find_audio(a.source)
+    if not files:
+        print("error: no audio files found", file=sys.stderr)
+        return 2
+    job = partial(check_file, need_hz=a.need_hz)
+    if a.jobs > 1:
+        with ProcessPoolExecutor(a.jobs) as ex:
+            vs = list(ex.map(job, files, chunksize=1))
+    else:
+        vs = [job(f) for f in files]
+    print(text(vs, 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())

bandcheck-0.1.0/src/bandcheck/report.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import csv
+from collections import Counter
+from typing import List
+
+from .check import Verdict, summary_by_rate
+
+
+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 (band-limited), {c['REVIEW']} need a look, "
+            f"{c['FAIL']} fail (much less bandwidth than claimed), {c['ERROR']} unreadable")
+
+
+def text(vs: List[Verdict], show_pass: bool = False) -> str:
+    L = []
+    for v in vs:
+        if v.level == "PASS" and not show_pass:
+            continue
+        src = f"  likely: {v.likely_source}" if v.likely_source else ""
+        L.append(f"{v.level:6} {v.file}  {v.sample_rate or '-'} Hz  {v.reason}{src}")
+    rows = summary_by_rate(vs)
+    if rows:
+        L += ["", "By sample rate:"]
+        for r in rows:
+            mc = f", median cut-off {r['median_cutoff_hz'] / 1000:.1f} kHz" if r["median_cutoff_hz"] else ""
+            L.append(f"  {r['rate']} Hz: {r['files']} files, {r['flagged']} flagged{mc}")
+    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", "sample_rate", "cutoff_hz", "cutoff_fraction", "verdict", "reason", "likely_source", "seconds_analysed"])
+        for v in vs:
+            w.writerow([v.file, v.sample_rate or "", "" if v.cutoff_hz is None else round(v.cutoff_hz, 1),
+                        "" if v.fraction is None else round(v.fraction, 3), v.level, v.reason, v.likely_source, round(v.seconds, 1)])

bandcheck-0.1.0/src/bandcheck/spectrum.py

@@ -0,0 +1,108 @@
+"""Audio -> long-term average spectrum, and the search for a sharp cut-off in it.
+
+A file that was upsampled, or lowpassed by a lossy encoder, has real sound up to some frequency and almost nothing
+above it, with a steep drop in between (a "cliff"). Natural sound fades gradually. So BandCheck looks for the steepest
+drop in the average spectrum and reports where it is. Light on purpose: numpy, scipy, soundfile only.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+import numpy as np
+import soundfile as sf
+from scipy.signal import medfilt, stft
+
+MAX_SECONDS = 120.0          # long files: only the middle 2 minutes are used
+MIN_SECONDS = 2.0
+ACTIVE_FLOOR_DB = -30.0      # frames more than 30 dB below the loudest frame are ignored
+MIN_ACTIVE_FRAMES = 4
+SEARCH_FROM_HZ = 2500.0      # a cliff below this is not looked for (speech and music change a lot down there)
+EDGE_MARGIN_HZ = 500.0       # a cliff must leave at least this much spectrum above it to compare
+SIDE_GAP_HZ, SIDE_SPAN_HZ = 200.0, 1000.0   # compare the level just below the cliff with the level just above it
+GRID_HZ = 50.0
+CLIFF_DB = 25.0              # the drop that counts as a cliff
+KNEE_DB = 10.0               # the cut-off is reported where the level has fallen this far below the band's own level
+SMOOTH_HZ = 100.0
+
+
+@dataclass
+class Spectrum:
+    freqs: np.ndarray
+    level_db: np.ndarray         # average power per bin, dB, relative to its own maximum
+    sample_rate: int
+    seconds: float               # length of the audio analysed
+    active_seconds: float        # time in frames that were loud enough to use
+
+
+@dataclass
+class Cliff:
+    cutoff_hz: float
+    drop_db: float               # level just below the cut-off minus level just above it
+    floor_db: float              # median level of everything above the cut-off, relative to just below it
+
+
+def load_mono(path, max_seconds: float = MAX_SECONDS):
+    """Reads the file at its OWN sample rate (no resampling) -> (mono float64, sample rate)."""
+    x, sr = sf.read(str(path), dtype="float64", always_2d=True)
+    x = x.mean(axis=1)
+    n = int(max_seconds * sr)
+    if len(x) > n:
+        s = (len(x) - n) // 2
+        x = x[s:s + n]
+    return x, int(sr)
+
+
+def mean_spectrum(x: np.ndarray, sr: int) -> Optional[Spectrum]:
+    """Average power spectrum over the loud frames. None if the audio is too short, silent or has too few loud frames."""
+    if len(x) < MIN_SECONDS * sr or not np.any(np.abs(x) > 1e-9):
+        return None
+    n = int(2 ** round(np.log2(max(sr / 10.0, 256))))        # about 10 Hz per bin
+    n = min(max(n, 512), 8192)
+    _, _, Z = stft(x, fs=sr, nperseg=n, noverlap=n // 2, boundary=None, padded=False)
+    P = np.abs(Z) ** 2
+    energy = P.sum(axis=0)
+    if energy.max() <= 0:
+        return None
+    active = energy > energy.max() * 10 ** (ACTIVE_FLOOR_DB / 10)
+    if active.sum() < MIN_ACTIVE_FRAMES:
+        return None
+    S = P[:, active].mean(axis=1)
+    L = 10 * np.log10(S + 1e-30)
+    L -= L.max()
+    freqs = np.linspace(0, sr / 2, len(L))
+    hop = n // 2
+    return Spectrum(freqs, L, sr, len(x) / sr, float(active.sum() * hop / sr))
+
+
+def find_cliff(sp: Spectrum) -> Optional[Cliff]:
+    """The sharpest drop (at least CLIFF_DB) in the smoothed average spectrum, or None if the spectrum fades gradually."""
+    f, nyq = sp.freqs, sp.sample_rate / 2
+    df = f[1] - f[0]
+    k = max(3, int(SMOOTH_HZ / df) | 1)
+    Ls = medfilt(sp.level_db, k)
+    best_g, best_d = None, 0.0
+    for g in np.arange(SEARCH_FROM_HZ, nyq - EDGE_MARGIN_HZ, GRID_HZ):
+        lo = (f >= g - SIDE_SPAN_HZ) & (f < g - SIDE_GAP_HZ)
+        hi = (f > g + SIDE_GAP_HZ) & (f <= min(g + SIDE_SPAN_HZ, nyq))
+        if lo.sum() < 3 or hi.sum() < 3:
+            continue
+        d = float(np.median(Ls[lo]) - np.median(Ls[hi]))
+        if d > best_d:
+            best_g, best_d = g, d
+    if best_g is None or best_d < CLIFF_DB:
+        return None
+    lo = (f >= best_g - SIDE_SPAN_HZ) & (f < best_g - SIDE_GAP_HZ)
+    hi = (f > best_g + SIDE_GAP_HZ) & (f <= min(best_g + SIDE_SPAN_HZ, nyq))
+    below, above = float(np.median(Ls[lo])), float(np.median(Ls[hi]))
+    knee = below - min(KNEE_DB, (below - above) / 2)         # where the level has fallen 10 dB: the edge of the usable band
+    win = (f >= best_g - SIDE_SPAN_HZ) & (f <= best_g + SIDE_SPAN_HZ)
+    idx = np.nonzero(win & (Ls <= knee))[0]
+    cutoff = float(f[idx[0]]) if len(idx) else float(best_g)
+    rest = f > cutoff + SIDE_GAP_HZ
+    if rest.sum() < 3:
+        return None
+    floor = float(np.median(Ls[rest]) - below)
+    if -floor < CLIFF_DB - 5:        # content comes back above the drop: a notch or a gap, not a cut-off
+        return None
+    return Cliff(cutoff, best_d, floor)

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

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: bandcheck
+Version: 0.1.0
+Summary: Find audio files whose real frequency range is lower than their sample rate claims (upsampled or lossy-encoded).
+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/Bandcheck
+Project-URL: Issues, https://github.com/BoobalanArjunan/Bandcheck/issues
+Project-URL: Source, https://github.com/BoobalanArjunan/Bandcheck
+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
+
+# bandcheck
+
+**Find audio files whose real frequency range is lower than their sample rate claims.**
+
+A file saved as "48 kHz WAV" may hold audio that was recorded at 16 kHz and upsampled, or that went through an MP3 or AAC encoder before being converted back. Everything above the source's limit is empty. A header never shows this. bandcheck measures where the sound really stops and tells you which files hold much less than they claim.
+
+> **Status: alpha (0.1.0).** Tested on generated audio, real speech recordings (LibriSpeech dev-clean), and 44.1 kHz studio music (MUSDB18-HQ). Run `scripts/real_data_check.py` (see `docs/REAL_DATA_CHECK.md`) on your own data.
+
+## Install
+
+```bash
+pip install --pre bandcheck      # after it is published; until then: pip install -e ".[dev]"
+```
+Needs Python 3.9+. Depends only on numpy, scipy, soundfile.
+
+## Use
+
+```bash
+bandcheck check my_dataset/                        # every audio file in the folder
+bandcheck check clip.wav
+bandcheck check my_dataset/ --need-hz 8000 --out verdicts.csv
+```
+Options: `--need-hz N` (fail files whose sound stops below N Hz, e.g. 8000 for a 16 kHz speech model), `--show-pass`, `--jobs 4`, `--out file.csv`.
+The report ends with a table by sample rate (files, how many are flagged, median cut-off), so you see at once that, for example, one rate holds most of the problem files.
+
+## What the verdicts mean
+
+| verdict | meaning | exit code |
+|---|---|---|
+| PASS | no sharp cut-off, or the sound reaches at least 90% of the way to the Nyquist frequency (or 19.5 kHz) | 0 |
+| WARN | sound stops at 60-90% of the way to Nyquist. Typical of an MP3/AAC lowpass or a source one step lower in rate | 0 |
+| FAIL | sound stops below 60% of the way, or below the `--need-hz` you asked for. Typical of upsampled audio | 1 |
+| REVIEW | too short, silent, or too few loud parts to measure | 0 |
+| ERROR | file could not be read | 0 |
+
+For WARN and FAIL it lists the likely causes, for example `upsampled from 16000 Hz or a lossy encoder's lowpass (MP3/AAC)`. One cut-off frequency cannot tell an upsampled file from a lossy encode, so every candidate is listed and you decide.
+
+## How it works (short)
+1. Reads the file at its own sample rate (no resampling) and averages the channels.
+2. Averages the power spectrum over the loud parts (frames within 30 dB of the loudest).
+3. Looks for the sharpest drop in that average: the level just below a frequency compared with the level just above it. A drop of 25 dB or more, with nothing coming back above it, counts as a cut-off. The cut-off is reported where the level has fallen 10 dB.
+4. Compares the cut-off with the Nyquist frequency of the file.
+
+## What has been measured
+
+### 1. Real Speech Audio (LibriSpeech dev-clean, 200 files)
+- **Original recordings:**
+  - 185 PASS, 11 WARN, 1 FAIL, 3 REVIEW, 0 ERROR.
+  - Flagged files exhibited genuine hardware or codec lowpass cut-offs (e.g. 4.8 kHz cut-off on `7850-286674-0017.flac`, 7.0–7.1 kHz on audiobook recordings).
+- **Planted upsampling test (185 files evaluated):**
+  - From 8 kHz: 185 / 185 flagged as FAIL (median detected cut-off ratio: 1.03).
+  - From 11.025 kHz: 185 / 185 flagged as WARN (median detected cut-off ratio: 1.05).
+  - Detected cut-off sat within 3–5% of the source Nyquist frequency (consistent with resampling anti-aliasing filter transition).
+
+![Spectrogram Verification](real_check/spectrogram_verification.png)
+
+### 2. Real 44.1 kHz Studio Music (MUSDB18-HQ, 200 files)
+- **Original recordings:**
+  - 197 PASS (98.5%), 2 WARN, 0 FAIL, 1 REVIEW, 0 ERROR.
+  - Flagged originals: 2 files (`other.wav` at 19.1 kHz, `drums.wav` at 19.3 kHz, both at 87% of 22.05 kHz Nyquist).
+- **Planted upsampling test (197 files evaluated):**
+  - From 8 kHz: 191 / 197 flagged as FAIL (median ratio 1.02).
+  - From 11.025 kHz: 185 / 197 flagged as FAIL (median ratio 1.05).
+  - From 16 kHz: 162 / 197 flagged as FAIL (median ratio 1.10).
+- **Planted MP3 encodes:**
+  - 64 kbps: 171 / 197 flagged, median cut-off 11.1 kHz.
+  - 128 kbps: 157 / 197 flagged, median cut-off 16.5 kHz.
+
+### 3. Synthetic Audio & Bug Injection
+- Full-band audio at 16, 22.05, 44.1 and 48 kHz: no cut-off found, PASS.
+- Audio lowpassed at 16, 19 and 20 kHz (44.1 and 48 kHz files) and 6-7 kHz (16 kHz files): cut-off found within 2% of where it was put.
+- Audio upsampled from 8, 11.025, 16, 22.05 and 24 kHz: flagged every time; the cut-off sits about 4-11% above the source's Nyquist frequency, because resampler filters roll off a little past it.
+- MP3 copies made with ffmpeg (mono): 64 kbps gave a cut-off near 16.6 kHz (WARN); 128, 192 and 256 kbps gave about 20.1 kHz (PASS).
+- 79 tests pass. 25 deliberately planted bugs in the code were each caught by the tests (5 needed a stronger test first).
+
+## Limits (read these)
+- **Defaults and thresholds:** The 25 dB drop, the 90% and 60% limits and the 19.5 kHz rule are judgement defaults set on generated audio; on 200 LibriSpeech dev-clean files, 12 were flagged (11 WARN, 1 FAIL), and caught 370 of 370 planted copies (from 8 and 11.025 kHz sources).
+- **Cannot tell upsampled from lossy-encoded** from one number, and cannot tell either from a recording that really was made with a limited microphone or filter. It reports where the sound stops, not why.
+- **Gradual roll-offs are not detected.** A gentle filter with no sharp edge, or dull-sounding music, passes.
+- **Cut-offs below 2.5 kHz are not looked for.** Speech and music change a lot there.
+- A quiet recording or one with long silences is judged on its louder parts only.
+- The channels are averaged, so a file with one full-band channel and one band-limited channel passes.
+- It tells you the bandwidth, not whether the audio is good.
+
+## Licence
+MIT.

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

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+src/bandcheck/__init__.py
+src/bandcheck/_version.py
+src/bandcheck/check.py
+src/bandcheck/cli.py
+src/bandcheck/report.py
+src/bandcheck/spectrum.py
+src/bandcheck.egg-info/PKG-INFO
+src/bandcheck.egg-info/SOURCES.txt
+src/bandcheck.egg-info/dependency_links.txt
+src/bandcheck.egg-info/entry_points.txt
+src/bandcheck.egg-info/requires.txt
+src/bandcheck.egg-info/top_level.txt
+tests/test_bandcheck.py

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

@@ -0,0 +1 @@
+

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

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

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

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

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

@@ -0,0 +1 @@
+bandcheck

bandcheck-0.1.0/tests/test_bandcheck.py

@@ -0,0 +1,359 @@
+import csv
+
+import numpy as np
+import pytest
+import soundfile as sf
+from scipy.signal import firwin, fftconvolve
+
+import bandcheck.check as chk
+import synth
+from bandcheck.check import (FAKE, LIMITED, OK, UNSURE, check_file, judge, source_guess, summary_by_rate)
+from bandcheck.cli import find_audio, main
+from bandcheck.report import summary_line, text, write_csv
+from bandcheck.spectrum import Cliff, Spectrum, find_cliff, load_mono, mean_spectrum
+from conftest import cut, full, up, write
+
+
+def spec_of(x, sr):
+    return mean_spectrum(synth.to_pcm16(x).astype(float) / 32767, sr)
+
+
+def fake_spec(sr=44100, secs=10.0):
+    f = np.linspace(0, sr / 2, 2049)
+    return Spectrum(f, np.zeros_like(f), sr, secs, secs)
+
+
+# ---------------------------------------------------------------- full-band audio passes
+@pytest.mark.parametrize("sr", [16000, 22050, 44100, 48000])
+def test_full_band_audio_passes(tmp_path, sr):
+    v = check_file(write(tmp_path / "a.wav", full(sr), sr))
+    assert v.status == OK and v.level == "PASS" and v.cutoff_hz is None
+    assert v.sample_rate == sr and v.likely_source == ""
+
+
+@pytest.mark.parametrize("tilt", [1.0, 1.5, 2.0, 2.5])
+def test_steeply_falling_natural_spectra_have_no_cliff(tilt):
+    """Dull sound that fades gradually is not a cut-off."""
+    assert find_cliff(spec_of(synth.make_full(44100, 12, 1, tilt=tilt), 44100)) is None
+
+
+def test_quiet_recordings_are_not_flagged(tmp_path):
+    for level in (0.001, 0.01):
+        assert check_file(write(tmp_path / "q.wav", synth.make_full(44100, 12, 2, level=level), 44100)).status == OK
+
+
+def test_a_gap_in_the_spectrum_is_not_a_cutoff():
+    """A band-stop (sound on both sides) is a notch, not the end of the band."""
+    x = full(44100)
+    band = firwin(2001, [10000, 11500], pass_zero=False, fs=44100)
+    y = x - fftconvolve(x, band, mode="same")
+    assert find_cliff(spec_of(y, 44100)) is None
+
+
+# ---------------------------------------------------------------- lowpass (lossy-encoder-like) detection
+@pytest.mark.parametrize("sr,fc", [(44100, 16000), (44100, 19000), (44100, 20000), (48000, 16000), (48000, 20000), (16000, 6000), (16000, 7000)])
+def test_cutoff_is_found_where_it_was_put(sr, fc):
+    c = find_cliff(spec_of(cut(sr, fc), sr))
+    assert c is not None
+    assert abs(c.cutoff_hz - fc) / fc < 0.02
+    assert c.drop_db > 30 and c.floor_db < -25
+
+
+def test_cutoff_found_for_other_seeds():
+    for seed in (1, 2, 3):
+        c = find_cliff(spec_of(cut(44100, 17000, seed), 44100))
+        assert c is not None and abs(c.cutoff_hz - 17000) < 400
+
+
+@pytest.mark.parametrize("sr,fc,status", [
+    (44100, 16000, LIMITED), (48000, 16000, LIMITED), (48000, 19000, LIMITED),
+    (44100, 20000, OK), (48000, 20000, OK), (16000, 7500, OK), (48000, 10000, FAKE), (44100, 12000, FAKE)])
+def test_verdict_for_lowpassed_audio(tmp_path, sr, fc, status):
+    v = check_file(write(tmp_path / "a.wav", cut(sr, fc), sr))
+    assert v.status == status, v.reason
+
+
+# ---------------------------------------------------------------- upsampled audio
+@pytest.mark.parametrize("sr,src,status", [(16000, 8000, FAKE), (16000, 11025, LIMITED), (44100, 16000, FAKE), (44100, 22050, FAKE),
+                                           (48000, 16000, FAKE), (48000, 24000, FAKE), (48000, 8000, FAKE)])
+def test_upsampled_audio_is_flagged_and_names_its_source(tmp_path, sr, src, status):
+    """Upsampling to a rate close to the source (11.025 to 16 kHz keeps 72% of the band) is a warning; far from it, a failure."""
+    v = check_file(write(tmp_path / "a.wav", up(sr, src), sr))
+    assert v.status == status, v.reason
+    assert 0.9 * src / 2 <= v.cutoff_hz <= 1.12 * src / 2
+    assert f"upsampled from {src} Hz" in v.likely_source or f"{src} Hz" in v.likely_source
+
+
+def test_the_reason_says_how_much_is_missing(tmp_path):
+    v = check_file(write(tmp_path / "a.wav", up(48000, 16000), 48000))
+    assert "kHz" in v.reason and "% of the way to 24 kHz" in v.reason
+
+
+def test_source_guess_lists_every_candidate_and_the_lossy_option():
+    g = source_guess(5781, 16000)
+    assert "11025 Hz" in g and "12000 Hz" in g and "lossy" in g
+    assert source_guess(8636, 48000).startswith("upsampled from 16000 Hz")
+    assert "upsampled" not in source_guess(3000, 48000) and "lossy" in source_guess(3000, 48000)
+    assert "from 48000" not in source_guess(24000, 48000)           # never "upsampled from" the file's own rate or higher
+    assert "from 44100" not in source_guess(20000, 44100)
+
+
+# ---------------------------------------------------------------- need-hz
+def test_need_hz_fails_files_that_stop_too_low(tmp_path):
+    p = write(tmp_path / "a.wav", cut(44100, 16000), 44100)
+    assert check_file(p, need_hz=12000).status == LIMITED
+    v = check_file(p, need_hz=18000)
+    assert v.status == FAKE and "18 kHz is required" in v.reason
+
+
+def test_need_hz_does_nothing_without_a_cutoff(tmp_path):
+    assert check_file(write(tmp_path / "a.wav", full(44100), 44100), need_hz=20000).status == OK
+
+
+# ---------------------------------------------------------------- verdict boundaries (cut-off position forced)
+def force(monkeypatch, cutoff):
+    monkeypatch.setattr(chk, "find_cliff", lambda sp: Cliff(cutoff, 40.0, -40.0))
+
+
+@pytest.mark.parametrize("sr,cutoff,status", [
+    (32000, 0.9 * 16000, OK), (32000, 0.9 * 16000 - 1, LIMITED), (44100, 19500, OK), (48000, 19499, LIMITED),
+    (48000, 0.6 * 24000, LIMITED), (48000, 0.6 * 24000 - 1, FAKE), (16000, 0.9 * 8000, OK), (16000, 0.9 * 8000 - 1, LIMITED),
+    (16000, 0.6 * 8000 - 1, FAKE)])
+def test_thresholds(monkeypatch, sr, cutoff, status):
+    force(monkeypatch, cutoff)
+    assert judge(fake_spec(sr), "a.wav", sr).status == status
+
+
+def test_need_hz_boundary(monkeypatch):
+    force(monkeypatch, 15000.0)
+    assert judge(fake_spec(), "a", 44100, need_hz=15000.0).status == LIMITED
+    assert judge(fake_spec(), "a", 44100, need_hz=15000.1).status == FAKE
+
+
+def test_levels_and_fraction():
+    v = chk.Verdict("a", 48000, FAKE, 12000.0, "r")
+    assert v.level == "FAIL" and v.fraction == 0.5
+    assert chk.Verdict("a", None, chk.ERROR, None, "r").fraction is None
+    assert {chk.Verdict("a", 1, s, None, "").level for s in (OK, LIMITED, FAKE, UNSURE, chk.ERROR)} == {"PASS", "WARN", "FAIL", "REVIEW", "ERROR"}
+
+
+# ---------------------------------------------------------------- edge cases
+def test_silent_and_short_files_are_review(tmp_path):
+    assert check_file(write(tmp_path / "s.wav", np.zeros(44100 * 10), 44100)).status == UNSURE
+    assert check_file(write(tmp_path / "t.wav", full(44100)[:44100], 44100)).status == UNSURE
+    assert judge(None, "a", 44100).status == UNSURE
+
+
+def test_one_click_in_silence_has_too_few_loud_frames(tmp_path):
+    x = np.zeros(44100 * 10)
+    x[44100] = 0.5
+    assert check_file(write(tmp_path / "c.wav", x, 44100)).status == UNSURE
+
+
+def test_unreadable_file_is_error(tmp_path):
+    p = tmp_path / "bad.wav"
+    p.write_bytes(b"this is not audio")
+    v = check_file(p)
+    assert v.status == chk.ERROR and "could not read" in v.reason and v.sample_rate is None
+
+
+def test_low_sample_rate_without_room_to_search():
+    assert judge(spec_of(synth.make_full(8000, 12, 1), 8000), "a", 8000).status == OK
+
+
+def test_cutoff_below_the_search_start_is_not_reported(tmp_path):
+    """A cut-off far below 2.5 kHz is outside the search (speech and music vary a lot there), so it is not flagged."""
+    assert find_cliff(spec_of(cut(16000, 1000), 16000)) is None
+
+
+def test_stereo_equals_mono(tmp_path):
+    x = cut(44100, 16000)
+    st = np.stack([x, x], axis=1)
+    p = tmp_path / "s.wav"
+    sf.write(str(p), synth.to_pcm16(st), 44100, subtype="PCM_16")
+    a, b = check_file(p), check_file(write(tmp_path / "m.wav", x, 44100))
+    assert a.status == b.status and abs(a.cutoff_hz - b.cutoff_hz) < 1.0
+
+
+def test_one_dead_channel_still_measured(tmp_path):
+    x = cut(44100, 16000)
+    p = tmp_path / "d.wav"
+    sf.write(str(p), synth.to_pcm16(np.stack([x, 0 * x], axis=1)), 44100, subtype="PCM_16")
+    assert check_file(p).status == LIMITED
+
+
+def test_flac_and_24_bit(tmp_path):
+    x = cut(48000, 16000)
+    sf.write(str(tmp_path / "a.flac"), x, 48000, subtype="PCM_24")
+    assert check_file(tmp_path / "a.flac").status == LIMITED
+
+
+def test_gain_does_not_change_the_result():
+    for g in (0.05, 1.0, 3.0):
+        c = find_cliff(mean_spectrum(g * cut(44100, 16000), 44100))
+        assert c is not None and abs(c.cutoff_hz - 16000) < 400
+
+
+def test_load_mono_keeps_the_files_own_rate_and_uses_the_middle(tmp_path):
+    p = write(tmp_path / "a.wav", full(22050), 22050)
+    x, sr = load_mono(p)
+    assert sr == 22050 and len(x) == 12 * 22050
+    x2, _ = load_mono(p, max_seconds=4)
+    assert len(x2) == 4 * 22050
+
+
+def test_active_seconds_counts_only_loud_parts():
+    x = np.concatenate([full(44100)[:44100 * 4], np.zeros(44100 * 8)])
+    sp = mean_spectrum(x, 44100)
+    assert sp is not None and sp.seconds == pytest.approx(12.0, abs=0.01) and 3.0 < sp.active_seconds < 5.5
+
+
+def test_quiet_sections_do_not_hide_the_cutoff():
+    quiet = 0.001 * full(44100)
+    loud = cut(44100, 16000)
+    x = np.concatenate([quiet[:44100 * 6], loud[:44100 * 6]])
+    c = find_cliff(mean_spectrum(x, 44100))
+    assert c is not None and abs(c.cutoff_hz - 16000) < 400
+
+
+def test_two_cutoffs_the_sharpest_drop_wins():
+    x = cut(48000, 20000)
+    y = cut(48000, 10000)
+    c = find_cliff(spec_of(0.5 * x + 0.5 * y, 48000))
+    assert c is not None and (abs(c.cutoff_hz - 10000) < 500 or abs(c.cutoff_hz - 20000) < 500)
+
+
+# ---------------------------------------------------------------- summary and reports
+def test_summary_by_rate():
+    vs = [chk.Verdict("a", 48000, FAKE, 8000.0, ""), chk.Verdict("b", 48000, OK, None, ""), chk.Verdict("c", 48000, LIMITED, 16000.0, ""),
+          chk.Verdict("d", 16000, OK, None, ""), chk.Verdict("e", None, chk.ERROR, None, "")]
+    rows = summary_by_rate(vs)
+    assert rows == [{"rate": 16000, "files": 1, "flagged": 0, "median_cutoff_hz": None},
+                    {"rate": 48000, "files": 3, "flagged": 2, "median_cutoff_hz": 12000.0}]
+
+
+def test_text_report_hides_passes_by_default():
+    vs = [chk.Verdict("good.wav", 48000, OK, None, "no sharp cut-off found"), chk.Verdict("bad.wav", 48000, FAKE, 8000.0, "stops low", "upsampled from 16000 Hz")]
+    t = text(vs)
+    assert "bad.wav" in t and "good.wav" not in t and "likely: upsampled from 16000 Hz" in t
+    assert "good.wav" in text(vs, show_pass=True)
+    assert "48000 Hz: 2 files, 1 flagged" in t
+    assert "2 files: 1 pass, 0 warn" in summary_line(vs)
+
+
+def test_csv_columns_and_values(tmp_path):
+    out = tmp_path / "v.csv"
+    write_csv(out, [chk.Verdict("a.wav", 48000, FAKE, 8000.0, "r", "x", 9.96)])
+    row = list(csv.DictReader(open(out, encoding="utf-8")))[0]
+    assert list(row) == ["file", "sample_rate", "cutoff_hz", "cutoff_fraction", "verdict", "reason", "likely_source", "seconds_analysed"]
+    assert (row["verdict"], row["cutoff_hz"], row["cutoff_fraction"], row["seconds_analysed"]) == ("FAIL", "8000.0", "0.333", "10.0")
+
+
+# ---------------------------------------------------------------- command line
+def make_folder(tmp_path):
+    write(tmp_path / "good.wav", full(44100), 44100)
+    write(tmp_path / "limited.wav", cut(44100, 16000), 44100)
+    (tmp_path / "sub").mkdir()
+    write(tmp_path / "sub" / "fake.wav", up(48000, 16000), 48000)
+    return tmp_path
+
+
+def test_cli_folder_exit_code_and_output(tmp_path, capsys):
+    rc = main(["check", str(make_folder(tmp_path))])
+    out = capsys.readouterr().out
+    assert rc == 1
+    assert "FAIL   fake.wav" in out and "WARN   limited.wav" in out and "good.wav" not in out
+    assert "3 files: 1 pass, 1 warn" in out and "By sample rate:" in out
+
+
+def test_cli_exit_zero_when_nothing_fails(tmp_path, capsys):
+    write(tmp_path / "good.wav", full(44100), 44100)
+    write(tmp_path / "limited.wav", cut(44100, 16000), 44100)
+    assert main(["check", str(tmp_path)]) == 0
+
+
+def test_cli_single_file_show_pass_and_out(tmp_path, capsys):
+    p = write(tmp_path / "good.wav", full(16000), 16000)
+    o = tmp_path / "v.csv"
+    assert main(["check", str(p), "--show-pass", "--out", str(o)]) == 0
+    assert "good.wav" in capsys.readouterr().out
+    assert list(csv.DictReader(open(o, encoding="utf-8")))[0]["verdict"] == "PASS"
+
+
+def test_cli_need_hz(tmp_path, capsys):
+    write(tmp_path / "limited.wav", cut(44100, 16000), 44100)
+    assert main(["check", str(tmp_path)]) == 0
+    assert main(["check", str(tmp_path), "--need-hz", "18000"]) == 1
+
+
+def test_cli_parallel_jobs_same_result(tmp_path, capsys):
+    d = make_folder(tmp_path)
+    main(["check", str(d)])
+    one = capsys.readouterr().out
+    main(["check", str(d), "--jobs", "2"])
+    assert capsys.readouterr().out == one
+
+
+def test_cli_skips_macos_junk_and_non_audio(tmp_path):
+    write(tmp_path / "a.wav", full(16000), 16000)
+    (tmp_path / "._a.wav").write_bytes(b"junk")
+    (tmp_path / "notes.txt").write_text("x")
+    (tmp_path / "__MACOSX").mkdir()
+    (tmp_path / "__MACOSX" / "b.wav").write_bytes(b"junk")
+    assert [p.name for p in find_audio(tmp_path)] == ["a.wav"]
+
+
+def test_cli_usage_errors(tmp_path, capsys):
+    assert main(["check", str(tmp_path / "missing")]) == 2
+    assert main(["check", str(tmp_path)]) == 2
+    assert "error" in capsys.readouterr().err
+
+
+def test_cli_unreadable_file_listed_but_not_failing(tmp_path, capsys):
+    (tmp_path / "bad.wav").write_bytes(b"not audio")
+    assert main(["check", str(tmp_path)]) == 0
+    assert "ERROR" in capsys.readouterr().out
+
+
+def test_version(capsys):
+    with pytest.raises(SystemExit):
+        main(["--version"])
+    assert "bandcheck 0.1.0" in capsys.readouterr().out
+
+
+# ---------------------------------------------------------------- tests added after the planted-bug check
+def test_a_20_db_step_is_not_a_cutoff():
+    """A shelf that drops 20 dB is below the 25 dB needed to call something a cut-off."""
+    x = 0.1 * full(44100) + cut(44100, 16000)
+    assert find_cliff(spec_of(x, 44100)) is None
+
+
+def test_a_30_db_step_is_a_cutoff():
+    x = 0.03 * full(44100) + cut(44100, 16000)
+    c = find_cliff(spec_of(x, 44100))
+    assert c is not None and abs(c.cutoff_hz - 16000) < 500
+
+
+def test_quiet_full_band_passages_do_not_hide_a_cutoff():
+    """Parts more than 30 dB under the loudest frame are ignored, so a quiet hiss does not fill in the empty band."""
+    x = np.concatenate([cut(44100, 16000)[:44100 * 3], 0.03 * full(44100)[:44100 * 9]])     # 3 s loud, 9 s quiet
+    c = find_cliff(mean_spectrum(synth.to_pcm16(x).astype(float) / 32767, 44100))
+    assert c is not None and abs(c.cutoff_hz - 16000) < 500
+
+
+def test_stereo_channels_are_averaged_so_a_full_band_channel_counts(tmp_path):
+    p = tmp_path / "s.wav"
+    sf.write(str(p), synth.to_pcm16(np.stack([cut(44100, 16000), full(44100)], axis=1)), 44100, subtype="PCM_16")
+    assert check_file(p).status == OK
+
+
+def test_a_long_file_is_judged_by_its_middle(tmp_path):
+    x = np.concatenate([cut(44100, 16000)[:44100 * 4], full(44100)[:44100 * 4], cut(44100, 16000)[:44100 * 4]])
+    p = write(tmp_path / "long.wav", x, 44100)
+    xs, sr = load_mono(p, max_seconds=4)
+    assert find_cliff(mean_spectrum(xs, sr)) is None            # the full-band middle, not the cut first 4 s
+
+
+def test_spectrum_level_is_relative_to_its_loudest_bin():
+    sp = spec_of(full(44100), 44100)
+    assert sp.level_db.max() == pytest.approx(0.0, abs=1e-9) and sp.level_db.min() < -20