phasecheck 0.1.0__tar.gz

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

phasecheck-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: phasecheck
+Version: 0.1.0
+Summary: Find stereo audio files whose channels cancel each other when mixed down to mono (out-of-phase or inverted channels).
+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/Phasecheck
+Project-URL: Issues, https://github.com/BoobalanArjunan/Phasecheck/issues
+Project-URL: Source, https://github.com/BoobalanArjunan/Phasecheck
+Classifier: Development Status :: 4 - Beta
+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
+
+# phasecheck
+
+Finds stereo files that lose level or sound thin when played in mono, usually because one channel is polarity-inverted
+or partly out of phase with the other.
+
+> **Status: 0.1.0.** Checked on real stereo music (MUSDB18-HQ) with planted problems and untouched originals; results below.
+> The thresholds (6 dB and 10 dB) were set on generated audio and are unchanged. They are provisional.
+
+```bash
+pip install -e ".[dev]"
+phasecheck check my_songs/ --out report.csv
+phasecheck check song.wav --json
+```
+
+## What it measures
+Over the loud parts of the file (frames within 30 dB of the loudest, middle 2 minutes of long files):
+
+- **Downmix loss (dB):** how much quieter the mono sum is than the average of the two channels. 0 dB means identical channels,
+  about 3 dB means unrelated channels, large values mean the channels cancel.
+- **Correlation** between the channels (-1 to 1), and the loss in four bands (20-250 Hz, 250 Hz-2 kHz, 2-8 kHz, above 8 kHz;
+  a band counts only if it holds at least 1% of the energy).
+- **Dual mono** (identical channels) and a **silent channel**.
+
+| Verdict | When |
+|---|---|
+| FAIL | full-band loss of 10 dB or more |
+| WARN | loss of 6 dB or more, or one band at 10 dB or more |
+| REVIEW | one channel is silent, or too little audio to judge |
+| SKIP | mono, or more than two channels |
+| PASS | otherwise (identical channels are noted) |
+
+Exit code 1 only when a FAIL exists; 2 for a bad path or settings.
+
+## Real-data results (MUSDB18-HQ, 200 files per run)
+Two runs on different songs: `test` split first, then `train`. The plan for each was fixed and tagged before the run
+(`eval-spec-pc-v1`, `eval-spec-pc-v2`; see `docs/`). **The first run failed its plan** (inverted-channel copies were expected
+to reach FAIL in 99% of cases; they reached 54%). The criterion was wrong, because how much an inversion loses depends on how
+correlated the channels were; the v2 plan corrected it and was run once on new songs, with no code or threshold change.
+
+| `train` split (v2 run) | result |
+|---|---|
+| Untouched originals flagged WARN or FAIL | 1 of 200 (range 0-3%) |
+| Right channel inverted, original correlation 0.5 or more: flagged WARN or FAIL | 168 of 169 = 99% (97-100%) |
+| Same copies reaching FAIL (10 dB or more) | 128 of 169 = 76% |
+| Same inversion, original correlation under 0.5 | 1 of 11 flagged: **not reliably detectable** |
+| Right channel inverted, all copies | 169 of 180 = 94% flagged, 128 of 180 = 71% FAIL |
+| Only full mixtures | 39 of 39 flagged, 28 of 39 FAIL |
+| 2-8 kHz band inverted | 62 of 71 = 87% (78-93%) |
+| Dual mono recognised | 180 of 180 |
+
+On the first (`test`) run: 0 of 199 originals flagged; all-copies detection 180 of 194 = 93% flagged, 104 of 194 = 54% FAIL; band 31 of 38 = 82%.
+
+The one flagged original (train: a vocals stem, correlation -0.79) measures 9.7 dB quieter in a mono mix (bass about 19.5 dB quieter); not yet checked by ear.
+
+Ranges are 95% Wilson intervals. Stems and mixtures of the same song are not independent, so the real uncertainty is wider.
+The planted copies are made by one method; real polarity mistakes may differ. Only MUSDB18-HQ was used.
+
+## Limits (please read)
+- **One dataset.** Tested on MUSDB18-HQ only (western-style studio stems and mixtures). Field recordings, spaced microphones and other styles may behave differently. Wide stereo can have low
+  correlation without any mono problem; that is why the verdict uses the downmix loss, not the correlation.
+- **Swapped left and right channels cannot be detected.** Nothing in the audio says which side is which.
+- **A passage that cancels is averaged into the whole file.** A short out-of-phase section in a long song may not reach WARN.
+- A flagged file is not proof of a mistake: some recordings really cancel in mono. Listen to the mono mix.
+- Only the middle 2 minutes of a long file are judged.
+- Inverted channels whose correlation was under about 0.5 are not reliably caught: the mono mix hardly changes.
+- An inverted mixture usually shows as WARN, not FAIL (about 72% of inverted mixtures reached FAIL).
+- Thresholds (6 / 10 dB) are provisional and were chosen on generated audio.
+
+## Tests
+`pytest -q` (57 tests). The checker itself was also tested by planting 21 deliberate bugs in the code and confirming
+the tests catch them (the two that survived the first round now have their own tests).
+
+## License
+
+MIT. Copyright (c) 2026 Boobalan Arjunan.

phasecheck-0.1.0/README.md

@@ -0,0 +1,75 @@
+# phasecheck
+
+Finds stereo files that lose level or sound thin when played in mono, usually because one channel is polarity-inverted
+or partly out of phase with the other.
+
+> **Status: 0.1.0.** Checked on real stereo music (MUSDB18-HQ) with planted problems and untouched originals; results below.
+> The thresholds (6 dB and 10 dB) were set on generated audio and are unchanged. They are provisional.
+
+```bash
+pip install -e ".[dev]"
+phasecheck check my_songs/ --out report.csv
+phasecheck check song.wav --json
+```
+
+## What it measures
+Over the loud parts of the file (frames within 30 dB of the loudest, middle 2 minutes of long files):
+
+- **Downmix loss (dB):** how much quieter the mono sum is than the average of the two channels. 0 dB means identical channels,
+  about 3 dB means unrelated channels, large values mean the channels cancel.
+- **Correlation** between the channels (-1 to 1), and the loss in four bands (20-250 Hz, 250 Hz-2 kHz, 2-8 kHz, above 8 kHz;
+  a band counts only if it holds at least 1% of the energy).
+- **Dual mono** (identical channels) and a **silent channel**.
+
+| Verdict | When |
+|---|---|
+| FAIL | full-band loss of 10 dB or more |
+| WARN | loss of 6 dB or more, or one band at 10 dB or more |
+| REVIEW | one channel is silent, or too little audio to judge |
+| SKIP | mono, or more than two channels |
+| PASS | otherwise (identical channels are noted) |
+
+Exit code 1 only when a FAIL exists; 2 for a bad path or settings.
+
+## Real-data results (MUSDB18-HQ, 200 files per run)
+Two runs on different songs: `test` split first, then `train`. The plan for each was fixed and tagged before the run
+(`eval-spec-pc-v1`, `eval-spec-pc-v2`; see `docs/`). **The first run failed its plan** (inverted-channel copies were expected
+to reach FAIL in 99% of cases; they reached 54%). The criterion was wrong, because how much an inversion loses depends on how
+correlated the channels were; the v2 plan corrected it and was run once on new songs, with no code or threshold change.
+
+| `train` split (v2 run) | result |
+|---|---|
+| Untouched originals flagged WARN or FAIL | 1 of 200 (range 0-3%) |
+| Right channel inverted, original correlation 0.5 or more: flagged WARN or FAIL | 168 of 169 = 99% (97-100%) |
+| Same copies reaching FAIL (10 dB or more) | 128 of 169 = 76% |
+| Same inversion, original correlation under 0.5 | 1 of 11 flagged: **not reliably detectable** |
+| Right channel inverted, all copies | 169 of 180 = 94% flagged, 128 of 180 = 71% FAIL |
+| Only full mixtures | 39 of 39 flagged, 28 of 39 FAIL |
+| 2-8 kHz band inverted | 62 of 71 = 87% (78-93%) |
+| Dual mono recognised | 180 of 180 |
+
+On the first (`test`) run: 0 of 199 originals flagged; all-copies detection 180 of 194 = 93% flagged, 104 of 194 = 54% FAIL; band 31 of 38 = 82%.
+
+The one flagged original (train: a vocals stem, correlation -0.79) measures 9.7 dB quieter in a mono mix (bass about 19.5 dB quieter); not yet checked by ear.
+
+Ranges are 95% Wilson intervals. Stems and mixtures of the same song are not independent, so the real uncertainty is wider.
+The planted copies are made by one method; real polarity mistakes may differ. Only MUSDB18-HQ was used.
+
+## Limits (please read)
+- **One dataset.** Tested on MUSDB18-HQ only (western-style studio stems and mixtures). Field recordings, spaced microphones and other styles may behave differently. Wide stereo can have low
+  correlation without any mono problem; that is why the verdict uses the downmix loss, not the correlation.
+- **Swapped left and right channels cannot be detected.** Nothing in the audio says which side is which.
+- **A passage that cancels is averaged into the whole file.** A short out-of-phase section in a long song may not reach WARN.
+- A flagged file is not proof of a mistake: some recordings really cancel in mono. Listen to the mono mix.
+- Only the middle 2 minutes of a long file are judged.
+- Inverted channels whose correlation was under about 0.5 are not reliably caught: the mono mix hardly changes.
+- An inverted mixture usually shows as WARN, not FAIL (about 72% of inverted mixtures reached FAIL).
+- Thresholds (6 / 10 dB) are provisional and were chosen on generated audio.
+
+## Tests
+`pytest -q` (57 tests). The checker itself was also tested by planting 21 deliberate bugs in the code and confirming
+the tests catch them (the two that survived the first round now have their own tests).
+
+## License
+
+MIT. Copyright (c) 2026 Boobalan Arjunan.

phasecheck-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "phasecheck"
+dynamic = ["version"]
+description = "Find stereo audio files whose channels cancel each other when mixed down to mono (out-of-phase or inverted channels)."
+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 :: 4 - Beta",
+  "License :: OSI Approved :: MIT License",
+  "Topic :: Multimedia :: Sound/Audio :: Analysis",
+]
+
+[project.urls]
+Homepage = "https://github.com/BoobalanArjunan/Phasecheck"
+Issues = "https://github.com/BoobalanArjunan/Phasecheck/issues"
+Source = "https://github.com/BoobalanArjunan/Phasecheck"
+
+[project.optional-dependencies]
+dev = ["pytest"]
+
+[project.scripts]
+phasecheck = "phasecheck.cli:main"
+
+[tool.setuptools.dynamic]
+version = { attr = "phasecheck._version.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

phasecheck-0.1.0/setup.cfg

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

phasecheck-0.1.0/src/phasecheck/__init__.py

@@ -0,0 +1,5 @@
+"""phasecheck: do the two channels of a stereo file cancel each other when mixed down to mono?"""
+from ._version import __version__
+from .check import Verdict, check_file, judge
+
+__all__ = ["__version__", "Verdict", "check_file", "judge"]

phasecheck-0.1.0/src/phasecheck/_version.py

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

phasecheck-0.1.0/src/phasecheck/analysis.py

@@ -0,0 +1,106 @@
+"""Stereo audio -> how much of it survives a mono downmix.
+
+Mixing a stereo file to mono (the average of the two channels) keeps sound that is the same in both channels and
+cancels sound that is opposite in the two channels. A file whose channels are partly or wholly out of phase can lose
+level or vanish when a training pipeline converts it to mono. phasecheck measures that loss.
+
+downmix_loss_db: 0 dB when the channels are identical (nothing is lost), about 3 dB when they are unrelated (the normal
+case for wide stereo), and large when they are in opposite phase (the mono mix is much quieter than the channels).
+Light on purpose: numpy, scipy, soundfile only.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+import numpy as np
+import soundfile as sf
+from scipy.signal import 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
+NPERSEG = 2048
+BANDS_HZ = ((20.0, 250.0), (250.0, 2000.0), (2000.0, 8000.0), (8000.0, 1e9))
+BAND_NAMES = ("20-250 Hz", "250 Hz-2 kHz", "2-8 kHz", "above 8 kHz")
+MIN_BAND_SHARE_DB = -20.0      # a band counts only if it holds at least 1% of the energy
+SILENT_CHANNEL_DB = -60.0      # a channel this far below the other is treated as silent (wavewash finds dead channels)
+LOSS_CAP_DB = 60.0
+IDENTICAL_DB = 0.2             # channels are "identical" if the mono mix loses less than this and their correlation is above 0.9999
+
+
+@dataclass
+class PhaseResult:
+    sample_rate: int
+    seconds: float
+    active_seconds: float
+    loss_db: float                                   # full-band downmix loss
+    correlation: float                               # full-band, -1 (opposite) .. +1 (identical)
+    band_loss_db: Dict[str, Optional[float]] = field(default_factory=dict)   # None for a band that is empty or holds too little energy
+    dual_mono: bool = False                          # both channels identical (mono stored as stereo)
+    silent_channel: Optional[int] = None             # 0 or 1 if one channel is silent next to the other
+
+
+def load_stereo(path, max_seconds: float = MAX_SECONDS):
+    """Reads the file at its own sample rate -> (array of shape (samples, channels), sample rate). Long files: the middle part."""
+    x, sr = sf.read(str(path), dtype="float64", always_2d=True)
+    n = int(max_seconds * sr)
+    if len(x) > n:
+        s = (len(x) - n) // 2
+        x = x[s:s + n]
+    return x, int(sr)
+
+
+def _loss_db(p_mono: float, p_l: float, p_r: float) -> float:
+    mean_ch = (p_l + p_r) / 2
+    if mean_ch <= 0:
+        return 0.0
+    return float(min(LOSS_CAP_DB, -10 * np.log10(max(p_mono, mean_ch * 10 ** (-LOSS_CAP_DB / 10)) / mean_ch)))
+
+
+def analyse(left: np.ndarray, right: np.ndarray, sr: int) -> Optional[PhaseResult]:
+    """Downmix loss of a stereo pair, measured over its loud parts. None if too short, silent or too few loud frames."""
+    n = min(len(left), len(right))
+    if n < MIN_SECONDS * sr:
+        return None
+    left, right = left[:n], right[:n]
+    if not (np.any(np.abs(left) > 1e-9) or np.any(np.abs(right) > 1e-9)):
+        return None
+    nper = min(NPERSEG, 2 ** int(np.log2(max(n // 4, 256))))
+    f, _, ZL = stft(left, fs=sr, nperseg=nper, noverlap=nper // 2, boundary=None, padded=False)
+    _, _, ZR = stft(right, fs=sr, nperseg=nper, noverlap=nper // 2, boundary=None, padded=False)
+    PL, PR = np.abs(ZL) ** 2, np.abs(ZR) ** 2
+    PM = np.abs(ZL + ZR) ** 2 / 4
+    cross = np.real(ZL * np.conj(ZR))
+    energy = PL.sum(axis=0) + PR.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
+    PL, PR, PM, cross = PL[:, active], PR[:, active], PM[:, active], cross[:, active]
+    hop = nper // 2
+    tl, tr, tm = PL.sum(), PR.sum(), PM.sum()
+    silent = None
+    if tl > 0 and 10 * np.log10(max(tr, 1e-30) / tl) < SILENT_CHANNEL_DB:
+        silent = 1
+    elif tr > 0 and 10 * np.log10(max(tl, 1e-30) / tr) < SILENT_CHANNEL_DB:
+        silent = 0
+    denom = np.sqrt(tl * tr)
+    corr = float(cross.sum() / denom) if denom > 0 else 0.0
+    loss = _loss_db(tm, tl, tr)
+    total = tl + tr
+    bands: Dict[str, Optional[float]] = {}
+    for (lo, hi), name in zip(BANDS_HZ, BAND_NAMES):
+        sel = (f >= lo) & (f < min(hi, sr / 2 + 1))
+        if not sel.any():
+            bands[name] = None
+            continue
+        bl, br, bm = PL[sel].sum(), PR[sel].sum(), PM[sel].sum()
+        if total <= 0 or 10 * np.log10(max(bl + br, 1e-30) / total) < MIN_BAND_SHARE_DB:
+            bands[name] = None
+            continue
+        bands[name] = _loss_db(bm, bl, br)
+    dual = loss < IDENTICAL_DB and corr > 0.9999 and abs(10 * np.log10(max(tl, 1e-30) / max(tr, 1e-30))) < 0.5
+    return PhaseResult(sr, n / sr, float(active.sum() * hop / sr), loss, float(np.clip(corr, -1, 1)), bands, bool(dual), silent)

phasecheck-0.1.0/src/phasecheck/check.py

@@ -0,0 +1,71 @@
+"""Turn a downmix measurement into a verdict."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from .analysis import PhaseResult, analyse, load_stereo
+
+WARN_DB = 6.0        # full-band downmix loss at or above this: WARN (provisional; not yet tuned on real recordings)
+FAIL_DB = 10.0       # at or above this: FAIL
+BAND_FAIL_DB = 10.0  # one frequency band (holding at least 1% of the energy) at or above this: WARN
+
+OK, LIMITED, FAKE, UNSURE, SKIPPED, ERROR = "OK", "LIMITED", "FAKE", "UNSURE", "SKIPPED", "ERROR"
+
+
+@dataclass
+class Verdict:
+    file: str
+    sample_rate: Optional[int]
+    channels: int
+    status: str
+    reason: str
+    loss_db: Optional[float] = None
+    correlation: Optional[float] = None
+    worst_band: str = ""
+    worst_band_loss_db: Optional[float] = None
+    dual_mono: bool = False
+    seconds: float = 0.0
+
+    @property
+    def level(self) -> str:
+        return {OK: "PASS", LIMITED: "WARN", UNSURE: "REVIEW", FAKE: "FAIL", SKIPPED: "SKIP", ERROR: "ERROR"}[self.status]
+
+
+def judge(res: Optional[PhaseResult], file: str = "", sample_rate: Optional[int] = None, channels: int = 2,
+          warn_db: float = WARN_DB, fail_db: float = FAIL_DB) -> Verdict:
+    if res is None:
+        return Verdict(file, sample_rate, channels, UNSURE, "too short, silent or too few loud parts to measure")
+    base = dict(file=file, sample_rate=res.sample_rate, channels=channels, loss_db=round(res.loss_db, 1),
+                correlation=round(res.correlation, 3), seconds=res.active_seconds)
+    present = {k: v for k, v in res.band_loss_db.items() if v is not None}
+    wb, wl = max(present.items(), key=lambda kv: kv[1]) if present else ("", None)
+    base.update(worst_band=wb, worst_band_loss_db=None if wl is None else round(wl, 1), dual_mono=res.dual_mono)
+    if res.silent_channel is not None:
+        side = "left" if res.silent_channel == 0 else "right"
+        return Verdict(status=UNSURE, reason=f"the {side} channel is silent next to the other, so there is nothing to cancel (a dead channel is wavewash's job)", **base)
+    if res.dual_mono:
+        return Verdict(status=OK, reason="both channels are identical (mono stored as stereo); the mono mix loses nothing", **base)
+    if res.loss_db >= fail_db:
+        why = " The channels are close to opposite in phase." if res.correlation <= -0.5 else ""
+        return Verdict(status=FAKE, reason=f"a mono mix is {res.loss_db:.1f} dB quieter than the channels (correlation {res.correlation:.2f}).{why}", **base)
+    if res.loss_db >= warn_db:
+        return Verdict(status=LIMITED, reason=f"a mono mix is {res.loss_db:.1f} dB quieter than the channels (correlation {res.correlation:.2f}); partly out of phase", **base)
+    if wl is not None and wl >= BAND_FAIL_DB:
+        return Verdict(status=LIMITED, reason=f"the {wb} band cancels in a mono mix ({wl:.1f} dB loss) although the whole file does not", **base)
+    return Verdict(status=OK, reason=f"a mono mix loses {res.loss_db:.1f} dB (correlation {res.correlation:.2f}); nothing cancels", **base)
+
+
+def check_file(path, warn_db: float = WARN_DB, fail_db: float = FAIL_DB) -> Verdict:
+    p = Path(path)
+    try:
+        x, sr = load_stereo(p)
+    except Exception as e:  # unreadable audio
+        return Verdict(p.name, None, 0, ERROR, f"could not read audio: {e}")
+    ch = x.shape[1]
+    if ch == 1:
+        return Verdict(p.name, sr, 1, SKIPPED, "mono file; nothing to check")
+    if ch > 2:
+        return Verdict(p.name, sr, ch, SKIPPED, f"{ch} channels; only two-channel files are checked")
+    return judge(analyse(x[:, 0], x[:, 1], sr), p.name, sr, 2, warn_db, fail_db)

phasecheck-0.1.0/src/phasecheck/cli.py

@@ -0,0 +1,59 @@
+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 FAIL_DB, WARN_DB, check_file
+from .report import text, to_json, 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="phasecheck", description="Find stereo audio files whose channels cancel each other in a mono downmix.")
+    ap.add_argument("--version", action="version", version=f"phasecheck {__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("--warn-db", type=float, default=WARN_DB, help=f"downmix loss that earns a WARN (default {WARN_DB:g} dB)")
+    c.add_argument("--fail-db", type=float, default=FAIL_DB, help=f"downmix loss that earns a FAIL (default {FAIL_DB:g} dB)")
+    c.add_argument("--out", type=Path, help="write every verdict to this CSV")
+    c.add_argument("--json", action="store_true", help="print the full report as JSON (instead of text)")
+    c.add_argument("--show-pass", action="store_true", help="also list files that passed or were skipped")
+    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
+    if a.warn_db > a.fail_db:
+        print("error: --warn-db must not be larger than --fail-db", 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, warn_db=a.warn_db, fail_db=a.fail_db)
+    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(to_json(vs) if a.json else 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())

phasecheck-0.1.0/src/phasecheck/report.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import csv
+import json
+from collections import Counter
+from typing import List
+
+from . import __version__
+from .check import Verdict
+
+EVIDENCE = ("alpha. Tested on generated audio only; not yet measured on real recordings. The 6 dB and 10 dB limits are provisional. "
+            "See the README.")
+LEVELS = ("PASS", "WARN", "FAIL", "REVIEW", "SKIP", "ERROR")
+
+
+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 (partly out of phase), {c['FAIL']} fail (cancel in a mono mix), "
+            f"{c['REVIEW']} need a look, {c['SKIP']} skipped (not two-channel), {c['ERROR']} unreadable")
+
+
+def text(vs: List[Verdict], show_pass: bool = False) -> str:
+    L = []
+    for v in vs:
+        if v.level in ("PASS", "SKIP") and not show_pass:
+            continue
+        L.append(f"{v.level:6} {v.file}  {v.sample_rate or '-'} Hz  {v.reason}")
+    return "\n".join(L + ([""] if L else []) + [summary_line(vs)])
+
+
+def _row(v: Verdict) -> dict:
+    return {"file": v.file, "sample_rate": v.sample_rate, "channels": v.channels, "verdict": v.level, "reason": v.reason,
+            "downmix_loss_db": v.loss_db, "correlation": v.correlation, "worst_band": v.worst_band,
+            "worst_band_loss_db": v.worst_band_loss_db, "dual_mono": v.dual_mono, "seconds_analysed": round(v.seconds, 1)}
+
+
+def write_csv(path, vs: List[Verdict]) -> None:
+    rows = [_row(v) for v in vs]
+    cols = list(_row(Verdict("", None, 0, "OK", "")).keys())
+    with open(path, "w", newline="", encoding="utf-8") as f:
+        w = csv.writer(f)
+        w.writerow(cols)
+        for r in rows:
+            w.writerow(["" if r[c] is None else r[c] for c in cols])
+
+
+def to_dict(vs: List[Verdict]) -> dict:
+    c = Counter(v.level for v in vs)
+    return {"tool": "phasecheck", "version": __version__, "evidence": EVIDENCE,
+            "summary": {"files": len(vs), **{k: c[k] for k in LEVELS}}, "files": [_row(v) for v in vs]}
+
+
+def to_json(vs: List[Verdict]) -> str:
+    return json.dumps(to_dict(vs), indent=2)

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

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: phasecheck
+Version: 0.1.0
+Summary: Find stereo audio files whose channels cancel each other when mixed down to mono (out-of-phase or inverted channels).
+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/Phasecheck
+Project-URL: Issues, https://github.com/BoobalanArjunan/Phasecheck/issues
+Project-URL: Source, https://github.com/BoobalanArjunan/Phasecheck
+Classifier: Development Status :: 4 - Beta
+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
+
+# phasecheck
+
+Finds stereo files that lose level or sound thin when played in mono, usually because one channel is polarity-inverted
+or partly out of phase with the other.
+
+> **Status: 0.1.0.** Checked on real stereo music (MUSDB18-HQ) with planted problems and untouched originals; results below.
+> The thresholds (6 dB and 10 dB) were set on generated audio and are unchanged. They are provisional.
+
+```bash
+pip install -e ".[dev]"
+phasecheck check my_songs/ --out report.csv
+phasecheck check song.wav --json
+```
+
+## What it measures
+Over the loud parts of the file (frames within 30 dB of the loudest, middle 2 minutes of long files):
+
+- **Downmix loss (dB):** how much quieter the mono sum is than the average of the two channels. 0 dB means identical channels,
+  about 3 dB means unrelated channels, large values mean the channels cancel.
+- **Correlation** between the channels (-1 to 1), and the loss in four bands (20-250 Hz, 250 Hz-2 kHz, 2-8 kHz, above 8 kHz;
+  a band counts only if it holds at least 1% of the energy).
+- **Dual mono** (identical channels) and a **silent channel**.
+
+| Verdict | When |
+|---|---|
+| FAIL | full-band loss of 10 dB or more |
+| WARN | loss of 6 dB or more, or one band at 10 dB or more |
+| REVIEW | one channel is silent, or too little audio to judge |
+| SKIP | mono, or more than two channels |
+| PASS | otherwise (identical channels are noted) |
+
+Exit code 1 only when a FAIL exists; 2 for a bad path or settings.
+
+## Real-data results (MUSDB18-HQ, 200 files per run)
+Two runs on different songs: `test` split first, then `train`. The plan for each was fixed and tagged before the run
+(`eval-spec-pc-v1`, `eval-spec-pc-v2`; see `docs/`). **The first run failed its plan** (inverted-channel copies were expected
+to reach FAIL in 99% of cases; they reached 54%). The criterion was wrong, because how much an inversion loses depends on how
+correlated the channels were; the v2 plan corrected it and was run once on new songs, with no code or threshold change.
+
+| `train` split (v2 run) | result |
+|---|---|
+| Untouched originals flagged WARN or FAIL | 1 of 200 (range 0-3%) |
+| Right channel inverted, original correlation 0.5 or more: flagged WARN or FAIL | 168 of 169 = 99% (97-100%) |
+| Same copies reaching FAIL (10 dB or more) | 128 of 169 = 76% |
+| Same inversion, original correlation under 0.5 | 1 of 11 flagged: **not reliably detectable** |
+| Right channel inverted, all copies | 169 of 180 = 94% flagged, 128 of 180 = 71% FAIL |
+| Only full mixtures | 39 of 39 flagged, 28 of 39 FAIL |
+| 2-8 kHz band inverted | 62 of 71 = 87% (78-93%) |
+| Dual mono recognised | 180 of 180 |
+
+On the first (`test`) run: 0 of 199 originals flagged; all-copies detection 180 of 194 = 93% flagged, 104 of 194 = 54% FAIL; band 31 of 38 = 82%.
+
+The one flagged original (train: a vocals stem, correlation -0.79) measures 9.7 dB quieter in a mono mix (bass about 19.5 dB quieter); not yet checked by ear.
+
+Ranges are 95% Wilson intervals. Stems and mixtures of the same song are not independent, so the real uncertainty is wider.
+The planted copies are made by one method; real polarity mistakes may differ. Only MUSDB18-HQ was used.
+
+## Limits (please read)
+- **One dataset.** Tested on MUSDB18-HQ only (western-style studio stems and mixtures). Field recordings, spaced microphones and other styles may behave differently. Wide stereo can have low
+  correlation without any mono problem; that is why the verdict uses the downmix loss, not the correlation.
+- **Swapped left and right channels cannot be detected.** Nothing in the audio says which side is which.
+- **A passage that cancels is averaged into the whole file.** A short out-of-phase section in a long song may not reach WARN.
+- A flagged file is not proof of a mistake: some recordings really cancel in mono. Listen to the mono mix.
+- Only the middle 2 minutes of a long file are judged.
+- Inverted channels whose correlation was under about 0.5 are not reliably caught: the mono mix hardly changes.
+- An inverted mixture usually shows as WARN, not FAIL (about 72% of inverted mixtures reached FAIL).
+- Thresholds (6 / 10 dB) are provisional and were chosen on generated audio.
+
+## Tests
+`pytest -q` (57 tests). The checker itself was also tested by planting 21 deliberate bugs in the code and confirming
+the tests catch them (the two that survived the first round now have their own tests).
+
+## License
+
+MIT. Copyright (c) 2026 Boobalan Arjunan.

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

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

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

@@ -0,0 +1 @@
+

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

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

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

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

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

@@ -0,0 +1 @@
+phasecheck

phasecheck-0.1.0/tests/test_phasecheck.py

@@ -0,0 +1,402 @@
+import csv
+import json
+
+import numpy as np
+import pytest
+import soundfile as sf
+
+import phasecheck.check as chk
+import synth
+from conftest import pair, sound, write
+from phasecheck.analysis import LOSS_CAP_DB, PhaseResult, analyse, load_stereo
+from phasecheck.check import FAKE, LIMITED, OK, SKIPPED, UNSURE, Verdict, check_file, judge
+from phasecheck.cli import find_audio, main
+from phasecheck.report import summary_line, text, to_dict, to_json, write_csv
+
+SR = 44100
+
+
+def res(left, right, sr=SR):
+    return analyse(synth.to_pcm16(left).astype(float) / 32767, synth.to_pcm16(right).astype(float) / 32767, sr)
+
+
+def rot(degrees, sr=SR, seed=0):
+    """The sound and the same sound shifted by a fixed phase angle (see synth.rotate)."""
+    x = sound(sr, seed)
+    return x, synth.rotate(x, degrees)
+
+
+def expected_loss(degrees):
+    return -10 * np.log10((1 + np.cos(np.deg2rad(degrees))) / 2)
+
+
+# ---------------------------------------------------------------- the basic relationships
+def test_identical_channels_lose_nothing_and_are_dual_mono():
+    x = sound(SR)
+    r = res(x, x)
+    assert r.loss_db < 0.2 and r.correlation > 0.999 and r.dual_mono
+    v = judge(r, "a.wav", SR)
+    assert v.status == OK and v.dual_mono and "mono stored as stereo" in v.reason
+
+
+def test_channels_a_quarter_turn_apart_lose_3_db_and_pass():
+    r = res(*rot(90))
+    assert abs(r.loss_db - 3.01) < 0.3 and abs(r.correlation) < 0.05 and not r.dual_mono
+    assert judge(r, "a.wav", SR).status == OK
+
+
+def test_independent_noise_channels_pass():
+    """Real stereo is somewhere between identical and unrelated; unrelated channels lose about 2-4 dB."""
+    r = res(sound(SR, 0), sound(SR, 1))
+    assert 1.0 < r.loss_db < 5.0 and not r.dual_mono
+    assert judge(r, "a.wav", SR).status == OK
+
+
+def test_inverted_channels_fail_with_a_large_loss():
+    x = sound(SR)
+    r = res(x, -x)
+    assert r.loss_db >= 40 and r.correlation < -0.99
+    v = judge(r, "a.wav", SR)
+    assert v.status == FAKE and v.level == "FAIL" and "opposite in phase" in v.reason
+
+
+def test_the_loss_is_capped():
+    x = sound(SR)
+    assert res(x, -x).loss_db <= LOSS_CAP_DB
+
+
+def test_a_quieter_right_channel_in_phase_is_fine_and_not_dual_mono():
+    x = sound(SR)
+    r = res(x, 0.5 * x)
+    assert r.loss_db < 1.0 and r.correlation > 0.999 and not r.dual_mono
+    assert judge(r, "a.wav", SR).status == OK
+
+
+def test_partly_out_of_phase_channels_warn():
+    r = res(*rot(130))                            # 7.5 dB
+    assert abs(r.loss_db - expected_loss(130)) < 0.4 and 6 <= r.loss_db < 10
+    v = judge(r, "a.wav", SR)
+    assert v.status == LIMITED and v.level == "WARN" and "partly out of phase" in v.reason
+
+
+def test_strongly_out_of_phase_channels_fail():
+    r = res(*rot(160))                            # 15 dB
+    assert abs(r.loss_db - expected_loss(160)) < 1.0 and r.loss_db >= 10
+    assert judge(r, "a.wav", SR).status == FAKE
+
+
+def test_correlation_sign_follows_the_phase():
+    x = sound(SR)
+    assert res(x, x).correlation > 0.99 and res(x, -x).correlation < -0.99
+    assert abs(res(*rot(90)).correlation) < 0.05
+    assert res(*rot(60)).correlation > 0.4 and res(*rot(120)).correlation < -0.4
+
+
+# ---------------------------------------------------------------- one band out of phase
+def band_flipped(lo, hi, sr=SR):
+    x = sound(sr)
+    return x, x - 2 * synth.band(x, sr, lo, hi)
+
+
+def test_a_band_inverted_in_one_channel_is_found_by_its_band():
+    x, y = band_flipped(2000, 8000)
+    r = res(x, y)
+    assert r.band_loss_db["2-8 kHz"] is not None and r.band_loss_db["2-8 kHz"] >= 10
+    v = judge(r, "a.wav", SR)
+    assert v.status in (LIMITED, FAKE) and v.worst_band == "2-8 kHz"
+
+
+def test_a_band_holding_almost_no_energy_is_ignored():
+    """The sound ends at 5 kHz; a trace of sound above 8 kHz (under 1% of the energy) is inverted in one channel."""
+    low = synth.band(sound(SR, 0), SR, 100, 5000)
+    trace = 0.01 * synth.band(sound(SR, 1), SR, 9000, 15000)
+    r = res(low + trace, low - trace)
+    assert r.band_loss_db["above 8 kHz"] is None
+    assert judge(r, "a.wav", SR).status == OK
+
+
+def test_the_same_trace_counts_when_it_holds_enough_energy():
+    low = synth.band(sound(SR, 0), SR, 100, 5000)
+    trace = 0.5 * synth.band(sound(SR, 1), SR, 9000, 15000)
+    r = res(low + trace, low - trace)
+    assert r.band_loss_db["above 8 kHz"] is not None and r.band_loss_db["above 8 kHz"] >= 10
+    assert judge(r, "a.wav", SR).status == LIMITED
+
+
+def test_band_rule_warns_when_the_whole_file_does_not_cancel():
+    x, y = band_flipped(2000, 8000)
+    r = res(x, y)
+    assert r.loss_db < chk.WARN_DB                          # the file as a whole is fine
+    v = judge(r, "a.wav", SR)
+    assert v.status == LIMITED and "band cancels" in v.reason
+
+
+def test_bands_that_do_not_exist_at_a_low_sample_rate_are_none():
+    r = res(sound(16000), sound(16000, 1), 16000)
+    assert r.band_loss_db["above 8 kHz"] is None
+
+
+# ---------------------------------------------------------------- only the loud parts count
+def test_a_quiet_inverted_passage_is_ignored():
+    x = sound(SR, 0, 8.0)
+    half = len(x) // 2
+    left = x
+    right = np.concatenate([x[:half], -x[half:] * 0.003])   # second half inverted but about 50 dB quieter
+    left = np.concatenate([x[:half], x[half:] * 0.003])
+    r = res(left, right)
+    assert r.loss_db < 1.0
+    assert judge(r, "a.wav", SR).status == OK
+
+
+def test_a_loud_inverted_passage_counts_but_is_averaged_into_the_file():
+    """Known limit: a passage that cancels completely only costs the file as a whole its share of the energy, so it can pass."""
+    x = sound(SR, 0, 8.0)
+    half = len(x) // 2
+    right = np.concatenate([x[:half], -x[half:]])
+    r = res(x, right)
+    kept = float(np.sum(x[:half] ** 2) / np.sum(x ** 2))              # share of the energy that stays in phase
+    assert abs(r.loss_db - (-10 * np.log10(kept))) < 0.4
+    assert 1.0 < r.loss_db < 6.0
+    assert judge(r, "a.wav", SR).status == OK
+
+
+def test_a_long_file_is_judged_by_its_middle(tmp_path):
+    x = sound(SR, 0, 12.0)
+    third = len(x) // 3
+    right = np.concatenate([-x[:third], x[third:2 * third], -x[2 * third:]])
+    p = write(tmp_path / "long.wav", pair(x, right), SR)
+    data, sr = load_stereo(p, max_seconds=4)
+    assert data.shape[0] == 4 * SR
+    r = analyse(data[:, 0], data[:, 1], sr)
+    assert r.loss_db < 0.3                                   # the in-phase middle, not the inverted ends
+
+
+# ---------------------------------------------------------------- files that cannot be judged
+def test_a_silent_channel_is_not_a_phase_problem(tmp_path):
+    x = sound(SR)
+    v = check_file(write(tmp_path / "s.wav", pair(x, np.zeros_like(x)), SR))
+    assert v.status == UNSURE and "silent" in v.reason and "right" in v.reason
+    v = check_file(write(tmp_path / "s2.wav", pair(np.zeros_like(x), x), SR))
+    assert v.status == UNSURE and "left" in v.reason
+
+
+def test_a_mono_file_is_skipped(tmp_path):
+    v = check_file(write(tmp_path / "m.wav", sound(SR), SR))
+    assert v.status == SKIPPED and v.level == "SKIP" and v.channels == 1
+
+
+def test_a_file_with_more_than_two_channels_is_skipped(tmp_path):
+    x = sound(SR)
+    p = tmp_path / "q.wav"
+    sf.write(str(p), synth.to_pcm16(np.stack([x, x, x], axis=1)), SR, subtype="PCM_16")
+    v = check_file(p)
+    assert v.status == SKIPPED and v.channels == 3 and "3 channels" in v.reason
+
+
+def test_a_short_file_needs_a_look(tmp_path):
+    x = sound(SR, 0, 1.0)
+    assert check_file(write(tmp_path / "s.wav", pair(x, -x), SR)).status == UNSURE
+
+
+def test_an_all_silent_file_needs_a_look(tmp_path):
+    z = np.zeros(SR * 4)
+    assert check_file(write(tmp_path / "z.wav", pair(z, z), SR)).status == UNSURE
+
+
+def test_an_unreadable_file_is_an_error(tmp_path):
+    p = tmp_path / "bad.wav"
+    p.write_bytes(b"not audio")
+    v = check_file(p)
+    assert v.status == chk.ERROR and v.level == "ERROR" and "could not read" in v.reason
+
+
+def test_judge_of_nothing_needs_a_look():
+    assert judge(None, "a.wav", SR).status == UNSURE
+
+
+# ---------------------------------------------------------------- thresholds
+def test_thresholds_can_be_changed():
+    r = res(*rot(130))                                      # 7.5 dB
+    assert judge(r, "a", SR).status == LIMITED
+    assert judge(r, "a", SR, warn_db=8.5, fail_db=12).status == OK
+    assert judge(r, "a", SR, warn_db=3, fail_db=7).status == FAKE
+
+
+def test_defaults_are_the_documented_values():
+    assert (chk.WARN_DB, chk.FAIL_DB, chk.BAND_FAIL_DB) == (6.0, 10.0, 10.0)
+
+
+# ---------------------------------------------------------------- sample rates
+@pytest.mark.parametrize("sr", [16000, 22050, 48000])
+def test_the_same_relationship_gives_the_same_loss_at_every_rate(sr):
+    x = sound(sr)
+    assert res(x, x, sr).dual_mono
+    assert res(x, -x, sr).loss_db >= 40
+    assert abs(res(x, synth.rotate(x, 90), sr).loss_db - 3.01) < 0.3
+
+
+# ---------------------------------------------------------------- reports
+def test_csv_columns_and_values(tmp_path):
+    out = tmp_path / "v.csv"
+    write_csv(out, [Verdict("a.wav", 44100, 2, FAKE, "r", 31.2, -0.98, "2-8 kHz", 40.0, False, 7.0)])
+    row = list(csv.DictReader(open(out, encoding="utf-8")))[0]
+    assert list(row) == ["file", "sample_rate", "channels", "verdict", "reason", "downmix_loss_db", "correlation", "worst_band",
+                         "worst_band_loss_db", "dual_mono", "seconds_analysed"]
+    assert (row["verdict"], row["downmix_loss_db"], row["correlation"], row["worst_band"], row["channels"]) == ("FAIL", "31.2", "-0.98", "2-8 kHz", "2")
+
+
+def test_json_report_has_the_summary_and_every_file():
+    vs = [Verdict("a.wav", 44100, 2, FAKE, "r", 31.2, -0.98),
+          Verdict("b.wav", 44100, 2, OK, "ok", 3.0, 0.0),
+          Verdict("m.wav", 44100, 1, SKIPPED, "mono")]
+    d = to_dict(vs)
+    assert d["tool"] == "phasecheck" and d["version"] and "alpha" in d["evidence"]
+    assert d["summary"] == {"files": 3, "PASS": 1, "WARN": 0, "FAIL": 1, "REVIEW": 0, "SKIP": 1, "ERROR": 0}
+    a = d["files"][0]
+    assert (a["file"], a["verdict"], a["downmix_loss_db"], a["correlation"], a["channels"]) == ("a.wav", "FAIL", 31.2, -0.98, 2)
+    assert json.loads(to_json(vs))["summary"]["files"] == 3
+
+
+def test_text_report_hides_pass_and_skip_unless_asked():
+    vs = [Verdict("a.wav", 44100, 2, FAKE, "r"), Verdict("b.wav", 44100, 2, OK, "ok"), Verdict("m.wav", 44100, 1, SKIPPED, "mono")]
+    t = text(vs)
+    assert "a.wav" in t and "b.wav" not in t and "m.wav" not in t
+    t2 = text(vs, show_pass=True)
+    assert "b.wav" in t2 and "m.wav" in t2
+    assert "1 pass" in summary_line(vs) and "1 skipped" in summary_line(vs) and "1 fail" in summary_line(vs)
+
+
+# ---------------------------------------------------------------- command line
+def make_folder(tmp_path):
+    x = sound(SR)
+    write(tmp_path / "good.wav", pair(sound(SR, 0), sound(SR, 1)), SR)
+    write(tmp_path / "bad.wav", pair(x, -x), SR)
+    (tmp_path / "sub").mkdir()
+    write(tmp_path / "sub" / "mono.wav", x, SR)
+    return tmp_path
+
+
+def test_find_audio_walks_folders_and_skips_junk(tmp_path):
+    make_folder(tmp_path)
+    (tmp_path / "._hidden.wav").write_bytes(b"x")
+    (tmp_path / "notes.txt").write_text("x")
+    names = [p.name for p in find_audio(tmp_path)]
+    assert names == ["bad.wav", "good.wav", "mono.wav"]
+
+
+def test_cli_exit_code_is_1_when_something_fails(tmp_path, capsys):
+    make_folder(tmp_path)
+    assert main(["check", str(tmp_path)]) == 1
+    out = capsys.readouterr().out
+    assert "FAIL" in out and "bad.wav" in out and "good.wav" not in out
+
+
+def test_cli_exit_code_is_0_when_nothing_fails(tmp_path, capsys):
+    write(tmp_path / "good.wav", pair(sound(SR, 0), sound(SR, 1)), SR)
+    assert main(["check", str(tmp_path)]) == 0
+
+
+def test_cli_json_prints_valid_json(tmp_path, capsys):
+    make_folder(tmp_path)
+    rc = main(["check", str(tmp_path), "--json"])
+    d = json.loads(capsys.readouterr().out)
+    assert rc == 1 and d["summary"]["files"] == 3
+    assert (d["summary"]["PASS"], d["summary"]["FAIL"], d["summary"]["SKIP"]) == (1, 1, 1)
+
+
+def test_cli_writes_csv(tmp_path):
+    make_folder(tmp_path)
+    out = tmp_path / "v.csv"
+    main(["check", str(tmp_path), "--out", str(out)])
+    assert len(list(csv.DictReader(open(out, encoding="utf-8")))) == 3
+
+
+def test_cli_threshold_options_change_the_verdict(tmp_path, capsys):
+    write(tmp_path / "p.wav", pair(*rot(130)), SR)
+    assert main(["check", str(tmp_path)]) == 0                                   # WARN only
+    assert main(["check", str(tmp_path), "--fail-db", "7", "--warn-db", "3"]) == 1
+
+
+def test_cli_rejects_warn_above_fail(tmp_path, capsys):
+    make_folder(tmp_path)
+    assert main(["check", str(tmp_path), "--warn-db", "12", "--fail-db", "8"]) == 2
+
+
+def test_cli_missing_path_and_empty_folder(tmp_path, capsys):
+    assert main(["check", str(tmp_path / "nope")]) == 2
+    assert main(["check", str(tmp_path)]) == 2
+
+
+def test_cli_parallel_jobs_same_result(tmp_path, capsys):
+    make_folder(tmp_path)
+    main(["check", str(tmp_path), "--json"])
+    a = json.loads(capsys.readouterr().out)
+    main(["check", str(tmp_path), "--json", "--jobs", "2"])
+    b = json.loads(capsys.readouterr().out)
+    assert a["summary"] == b["summary"] and [f["file"] for f in a["files"]] == [f["file"] for f in b["files"]]
+
+
+def test_cli_version(capsys):
+    with pytest.raises(SystemExit):
+        main(["--version"])
+    assert "phasecheck 0.1.0" in capsys.readouterr().out
+
+
+# ---------------------------------------------------------------- the limits themselves (judge on a hand-made measurement)
+def made(loss, corr=0.0, bands=None, dual=False, silent=None):
+    return PhaseResult(SR, 8.0, 8.0, loss, corr, bands or {"20-250 Hz": 3.0, "250 Hz-2 kHz": 3.0, "2-8 kHz": 3.0, "above 8 kHz": 3.0}, dual, silent)
+
+
+@pytest.mark.parametrize("loss,expected", [(5.99, OK), (6.0, LIMITED), (9.99, LIMITED), (10.0, FAKE), (30.0, FAKE)])
+def test_full_band_limits_are_at_6_and_10_db(loss, expected):
+    assert judge(made(loss), "a", SR).status == expected
+
+
+@pytest.mark.parametrize("band_loss,expected", [(9.99, OK), (10.0, LIMITED), (25.0, LIMITED)])
+def test_band_limit_is_10_db(band_loss, expected):
+    v = judge(made(3.0, bands={"20-250 Hz": 3.0, "250 Hz-2 kHz": band_loss, "2-8 kHz": 3.0, "above 8 kHz": None}), "a", SR)
+    assert v.status == expected
+    if expected == LIMITED:
+        assert v.worst_band == "250 Hz-2 kHz" and v.worst_band_loss_db == band_loss
+
+
+def test_the_worst_band_is_the_one_with_the_largest_loss():
+    v = judge(made(3.0, bands={"20-250 Hz": 2.0, "250 Hz-2 kHz": 4.0, "2-8 kHz": 9.0, "above 8 kHz": 6.0}), "a", SR)
+    assert v.worst_band == "2-8 kHz" and v.worst_band_loss_db == 9.0
+
+
+def test_a_correlation_below_minus_half_is_called_opposite_in_phase():
+    assert "opposite in phase" in judge(made(12.0, corr=-0.5), "a", SR).reason
+    assert "opposite in phase" not in judge(made(12.0, corr=-0.49), "a", SR).reason
+
+
+def test_a_silent_channel_wins_over_everything_else():
+    v = judge(made(60.0, corr=-1.0, silent=1), "a", SR)
+    assert v.status == UNSURE
+
+
+def test_dual_mono_wins_over_the_loss_rules():
+    assert judge(made(0.0, corr=1.0, dual=True), "a", SR).status == OK
+
+
+def test_verdict_levels_and_fraction_free_properties():
+    assert [Verdict("a", 1, 2, s, "").level for s in (OK, LIMITED, FAKE, UNSURE, SKIPPED, chk.ERROR)] == ["PASS", "WARN", "FAIL", "REVIEW", "SKIP", "ERROR"]
+
+
+# ---------------------------------------------------------------- planted-bug follow-ups
+def test_a_level_difference_of_nearly_a_decibel_is_not_dual_mono():
+    x = sound(SR)
+    r = res(x, 0.9 * x)            # right is 0.9 dB quieter: in phase, loses nothing, but not identical
+    assert r.loss_db < 0.2 and r.correlation > 0.9999
+    assert not r.dual_mono
+    assert res(x, 0.97 * x).dual_mono   # 0.26 dB apart still counts as identical
+
+
+def test_only_the_loud_part_counts_as_active_time():
+    x = sound(SR, seconds=8.0)
+    half = len(x) // 2
+    y = x.copy()
+    y[half:] *= 10 ** (-50 / 20)   # second half 50 dB quieter, below the loud-frame floor
+    r = res(y, y)
+    assert 3.0 < r.active_seconds < 4.5
+    assert res(x, x).active_seconds > 7.0