turnscope 0.1.0__tar.gz

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

turnscope-0.1.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: turnscope
+Version: 0.1.0
+Summary: Timing of a two-channel call recording: agent response delay, interruptions, barge-ins, dead air.
+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/Turnscope
+Project-URL: Issues, https://github.com/BoobalanArjunan/Turnscope/issues
+Project-URL: Source, https://github.com/BoobalanArjunan/Turnscope
+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: soundfile>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# turnscope
+
+Timing of a two-channel call recording (agent on one channel, customer on the other): how long the agent takes to answer, who interrupts whom, and where dead air happens.
+
+**Status: 0.1.0.** Validated on synthetic calls and authentic multi-channel conversational recordings (MagicHub full-duplex corpus, arXiv:2509.04093, CC BY 4.0). See benchmark results below.
+
+## Use
+
+    pip install -e .
+    turnscope analyze call.wav                       # channel 0 = agent, channel 1 = customer
+    turnscope analyze call.wav --agent-channel 1 --json out.json --csv out.csv
+    turnscope analyze call.wav --max-median-response 1.2 --max-p90-response 2.5   # exit code 1 if too slow
+
+It reports: response delay per hand-over (median, p90), agent interruptions of the customer, customer barge-ins (and whether the agent stopped), dead air of 3 s or more, and warnings (for example, one channel bleeding into the other).
+
+## How it works (short)
+
+Energy-based speech detection per channel: noise floor from the quietest 10% of frames, limits relative to the channel's own peak. Short gaps are bridged, short bursts dropped. If both channels are active and one is much louder, the quieter one is treated as leakage. Utterances closer than 0.5 s are merged. No model, no GPU, no network.
+
+## What is proven and what is not
+
+Synthetic calls with known turn timing (`scripts/synthetic_compare.py`, 20 random calls per row, 6 turns each). "Found" means every hand-over was detected; the simple threshold is a fixed -35 dB limit per channel with 0.3 s bridging, like an ffmpeg `silencedetect` script.
+
+| condition | turnscope found | error (s) | simple threshold found | error (s) |
+|---|---|---|---|---|
+| clean | 20/20 | 0.02 | 20/20 | 0.02 |
+| noisy (-40 dB floor) | 20/20 | 0.02 | 20/20 | 0.02 |
+| very noisy (-32 dB floor) | 20/20 | 0.03 | 0/20 | - |
+| quiet call (-25 dB) | 20/20 | 0.02 | 0/20 | - |
+| leakage -25 dB | 20/20 | 0.02 | 20/20 | 0.02 |
+| leakage -18 dB, room | 20/20 | 0.02 | 0/20 | - |
+| noisy + leakage -25 dB | 20/20 | 0.02 | 0/20 | - |
+
+Read this carefully:
+
+- The generator is mine, and speech is syllable-like noise, not real voices.
+- The fixed -35 dB baseline is a weak opponent on quiet or noisy calls; a hand-tuned threshold per file would do better. The real question is whether turnscope beats a *tuned* simple script on real calls. That is untested.
+- Leakage handling is validated only on synthetic leakage. Real dual-channel datasets are often cleanly separated, so it may matter little.
+- All thresholds (dominance, 3 s dead air, 0.5 s merge) are provisional.
+
+## Real-Data Check Benchmark (MagicHub Full-Duplex Corpus)
+
+Evaluated on authentic dual-track human conversations from the MagicHub full-duplex corpus (arXiv:2509.04093, CC BY 4.0; dual-track 16 kHz WAV) totaling 6 multi-turn conversations and 449 labelled turn transitions (3,021 ground-truth speech segments) using `scripts/real_data_check.py`:
+
+| Method | Speech F1 | Precision | Recall | Labelled Hand-Overs | Not Found in Audio (Missed) | Median Abs Error (s) | P90 Abs Error (s) |
+|---|---|---|---|---|---|---|---|
+| **TurnScope** | **0.897** | 0.944 | **0.856** | 449 | **126** | **0.277 s** | **0.440 s** |
+| Simple Threshold | 0.700 | **0.965** | 0.600 | 449 | 207 | 0.410 s | 1.339 s |
+
+### Key Findings
+1. **Accurate Speech Detection**: TurnScope achieves an F1 of **0.897** (vs 0.700 for the simple threshold), driven by a significantly higher speech recall (**85.6% vs 60.0%**), preventing soft speech from being clipped.
+2. **Superior Turn Discovery**: TurnScope misses **39% fewer hand-overs** (126 missed vs 207 for simple threshold), tracking rapid conversational hand-offs that a static threshold loses.
+3. **Low Response-Delay Error**: Response delay median error is **0.277 s** (32% lower error than baseline's 0.410 s), and P90 tail error is **0.440 s vs 1.339 s** (a **67% error reduction**), providing reliable conversational response timing without GPU or cloud dependency.
+
+## Stop rule
+
+Run `docs/REAL_DATA_CHECK.md`. If after two rounds of fixes turnscope is not clearly better than the simple threshold on real labelled calls, stop and do not publish.
+
+## Tests
+
+    pip install -e .[dev] && pytest     # 41 tests
+
+Planted-bug (mutation) checks were run on the core logic; no survivors after the last round.
+
+## License
+
+MIT. Copyright (c) 2026 Boobalan Arjunan.

turnscope-0.1.0/README.md

@@ -0,0 +1,67 @@
+# turnscope
+
+Timing of a two-channel call recording (agent on one channel, customer on the other): how long the agent takes to answer, who interrupts whom, and where dead air happens.
+
+**Status: 0.1.0.** Validated on synthetic calls and authentic multi-channel conversational recordings (MagicHub full-duplex corpus, arXiv:2509.04093, CC BY 4.0). See benchmark results below.
+
+## Use
+
+    pip install -e .
+    turnscope analyze call.wav                       # channel 0 = agent, channel 1 = customer
+    turnscope analyze call.wav --agent-channel 1 --json out.json --csv out.csv
+    turnscope analyze call.wav --max-median-response 1.2 --max-p90-response 2.5   # exit code 1 if too slow
+
+It reports: response delay per hand-over (median, p90), agent interruptions of the customer, customer barge-ins (and whether the agent stopped), dead air of 3 s or more, and warnings (for example, one channel bleeding into the other).
+
+## How it works (short)
+
+Energy-based speech detection per channel: noise floor from the quietest 10% of frames, limits relative to the channel's own peak. Short gaps are bridged, short bursts dropped. If both channels are active and one is much louder, the quieter one is treated as leakage. Utterances closer than 0.5 s are merged. No model, no GPU, no network.
+
+## What is proven and what is not
+
+Synthetic calls with known turn timing (`scripts/synthetic_compare.py`, 20 random calls per row, 6 turns each). "Found" means every hand-over was detected; the simple threshold is a fixed -35 dB limit per channel with 0.3 s bridging, like an ffmpeg `silencedetect` script.
+
+| condition | turnscope found | error (s) | simple threshold found | error (s) |
+|---|---|---|---|---|
+| clean | 20/20 | 0.02 | 20/20 | 0.02 |
+| noisy (-40 dB floor) | 20/20 | 0.02 | 20/20 | 0.02 |
+| very noisy (-32 dB floor) | 20/20 | 0.03 | 0/20 | - |
+| quiet call (-25 dB) | 20/20 | 0.02 | 0/20 | - |
+| leakage -25 dB | 20/20 | 0.02 | 20/20 | 0.02 |
+| leakage -18 dB, room | 20/20 | 0.02 | 0/20 | - |
+| noisy + leakage -25 dB | 20/20 | 0.02 | 0/20 | - |
+
+Read this carefully:
+
+- The generator is mine, and speech is syllable-like noise, not real voices.
+- The fixed -35 dB baseline is a weak opponent on quiet or noisy calls; a hand-tuned threshold per file would do better. The real question is whether turnscope beats a *tuned* simple script on real calls. That is untested.
+- Leakage handling is validated only on synthetic leakage. Real dual-channel datasets are often cleanly separated, so it may matter little.
+- All thresholds (dominance, 3 s dead air, 0.5 s merge) are provisional.
+
+## Real-Data Check Benchmark (MagicHub Full-Duplex Corpus)
+
+Evaluated on authentic dual-track human conversations from the MagicHub full-duplex corpus (arXiv:2509.04093, CC BY 4.0; dual-track 16 kHz WAV) totaling 6 multi-turn conversations and 449 labelled turn transitions (3,021 ground-truth speech segments) using `scripts/real_data_check.py`:
+
+| Method | Speech F1 | Precision | Recall | Labelled Hand-Overs | Not Found in Audio (Missed) | Median Abs Error (s) | P90 Abs Error (s) |
+|---|---|---|---|---|---|---|---|
+| **TurnScope** | **0.897** | 0.944 | **0.856** | 449 | **126** | **0.277 s** | **0.440 s** |
+| Simple Threshold | 0.700 | **0.965** | 0.600 | 449 | 207 | 0.410 s | 1.339 s |
+
+### Key Findings
+1. **Accurate Speech Detection**: TurnScope achieves an F1 of **0.897** (vs 0.700 for the simple threshold), driven by a significantly higher speech recall (**85.6% vs 60.0%**), preventing soft speech from being clipped.
+2. **Superior Turn Discovery**: TurnScope misses **39% fewer hand-overs** (126 missed vs 207 for simple threshold), tracking rapid conversational hand-offs that a static threshold loses.
+3. **Low Response-Delay Error**: Response delay median error is **0.277 s** (32% lower error than baseline's 0.410 s), and P90 tail error is **0.440 s vs 1.339 s** (a **67% error reduction**), providing reliable conversational response timing without GPU or cloud dependency.
+
+## Stop rule
+
+Run `docs/REAL_DATA_CHECK.md`. If after two rounds of fixes turnscope is not clearly better than the simple threshold on real labelled calls, stop and do not publish.
+
+## Tests
+
+    pip install -e .[dev] && pytest     # 41 tests
+
+Planted-bug (mutation) checks were run on the core logic; no survivors after the last round.
+
+## License
+
+MIT. Copyright (c) 2026 Boobalan Arjunan.

turnscope-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "turnscope"
+dynamic = ["version"]
+description = "Timing of a two-channel call recording: agent response delay, interruptions, barge-ins, dead air."
+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", "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/Turnscope"
+Issues = "https://github.com/BoobalanArjunan/Turnscope/issues"
+Source = "https://github.com/BoobalanArjunan/Turnscope"
+
+[project.optional-dependencies]
+dev = ["pytest"]
+
+[project.scripts]
+turnscope = "turnscope.cli:main"
+
+[tool.setuptools.dynamic]
+version = { attr = "turnscope._version.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

turnscope-0.1.0/setup.cfg

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

turnscope-0.1.0/src/turnscope/__init__.py

@@ -0,0 +1,5 @@
+"""turnscope: timing of a two-channel call recording."""
+from ._version import __version__
+from .analyze import Analysis, CallError, analyse, analyse_file
+
+__all__ = ["__version__", "Analysis", "CallError", "analyse", "analyse_file"]

turnscope-0.1.0/src/turnscope/_version.py

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

turnscope-0.1.0/src/turnscope/analyze.py

@@ -0,0 +1,146 @@
+"""From two channels of one call to timing numbers: response delay, interruptions, barge-ins, dead air."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+import numpy as np
+import soundfile as sf
+
+from .vad import speech_segments
+
+UTTER_GAP_S = 0.5          # pauses shorter than this inside one speaker's talk do not end the utterance
+MAX_RESPONSE_S = 10.0      # a gap longer than this between turns is not a "response" (the call went quiet) but dead air
+DEAD_AIR_S = 3.0           # both sides silent for at least this long, between the first and last speech
+MIN_OVERLAP_S = 0.2        # overlaps shorter than this are normal conversational overlap and are not counted
+STRONG_LEAK_DB = -15.0     # if one side leaks into the other this loudly, timing near overlaps is unreliable
+
+
+class CallError(Exception):
+    pass
+
+
+@dataclass
+class Event:
+    kind: str                  # "response" | "customer_pause" | "agent_interrupts" | "customer_barge_in"
+    at_s: float
+    value_s: float             # response: gap; interrupts: overlap length; barge_in: how long the agent kept talking
+    detail: str = ""
+
+
+@dataclass
+class Analysis:
+    file: str
+    duration_s: float
+    agent_speech_s: float
+    customer_speech_s: float
+    responses: List[float] = field(default_factory=list)
+    events: List[Event] = field(default_factory=list)
+    dead_air: List[Tuple[float, float]] = field(default_factory=list)
+    agent_not_yielding: int = 0
+    leak_agent_to_customer_db: Optional[float] = None
+    leak_customer_to_agent_db: Optional[float] = None
+    warnings: List[str] = field(default_factory=list)
+
+    def pct(self, q: float) -> Optional[float]:
+        return float(np.percentile(self.responses, q)) if self.responses else None
+
+    @property
+    def interrupts(self) -> int:
+        return sum(e.kind == "agent_interrupts" for e in self.events)
+
+    @property
+    def barge_ins(self) -> int:
+        return sum(e.kind == "customer_barge_in" for e in self.events)
+
+
+def utterances(segs: List[Tuple[float, float]]) -> List[Tuple[float, float]]:
+    out: List[List[float]] = []
+    for s, e in segs:
+        if out and s - out[-1][1] < UTTER_GAP_S:
+            out[-1][1] = e
+        else:
+            out.append([s, e])
+    return [(s, e) for s, e in out]
+
+
+def load_channels(path, agent_channel: int = 0, customer: Optional[Path] = None):
+    """(agent samples, customer samples, sample rate). One stereo file, or an agent file plus a --customer file."""
+    try:
+        x, sr = sf.read(str(path), dtype="float32", always_2d=True)
+    except Exception as e:  # noqa: BLE001
+        raise CallError(f"cannot read {Path(path).name}: {e}") from None
+    if customer is not None:
+        try:
+            y, sr2 = sf.read(str(customer), dtype="float32", always_2d=True)
+        except Exception as e:  # noqa: BLE001
+            raise CallError(f"cannot read {Path(customer).name}: {e}") from None
+        if sr2 != sr:
+            raise CallError(f"sample rates differ ({sr} and {sr2})")
+        a, c = x.mean(axis=1), y.mean(axis=1)
+    else:
+        if x.shape[1] != 2:
+            raise CallError(f"{Path(path).name} has {x.shape[1]} channel(s); two-channel audio (or an agent file plus --customer) is needed")
+        if agent_channel not in (0, 1):
+            raise CallError("--agent-channel must be 0 or 1")
+        a, c = x[:, agent_channel], x[:, 1 - agent_channel]
+    n = min(len(a), len(c))
+    return a[:n], c[:n], sr
+
+
+def analyse(agent: np.ndarray, customer: np.ndarray, sr: int, name: str = "") -> Analysis:
+    sa, sc, leak_ac, leak_ca = speech_segments(agent, customer, sr)
+    return from_segments(sa, sc, len(agent) / sr, name, leak_ac, leak_ca)
+
+
+def from_segments(sa, sc, duration_s: float, name: str = "", leak_ac=None, leak_ca=None) -> Analysis:
+    """Timing numbers from speech segments [(start_s, end_s)] of the agent and the customer (from turnscope's detector or from labels)."""
+    res = Analysis(name, duration_s, sum(e - s for s, e in sa), sum(e - s for s, e in sc),
+                   leak_agent_to_customer_db=leak_ac, leak_customer_to_agent_db=leak_ca)
+    if not sa:
+        res.warnings.append("no speech found on the agent channel (is --agent-channel right, or is the channel empty?)")
+    if not sc:
+        res.warnings.append("no speech found on the customer channel (is --agent-channel right, or is the channel empty?)")
+    for who, leak in (("agent into the customer channel", leak_ac), ("customer into the agent channel", leak_ca)):
+        if leak is not None and leak > STRONG_LEAK_DB:
+            res.warnings.append(f"strong leakage: the {who} is only {-leak:.0f} dB quieter; timing near overlaps is unreliable")
+    ua, uc = utterances(sa), utterances(sc)
+    allu = sorted([(s, e, "agent") for s, e in ua] + [(s, e, "customer") for s, e in uc])
+    for (xs, xe, xw), (ys, ye, yw) in zip(allu, allu[1:]):
+        if xw == yw:
+            continue
+        if ys >= xe:                                              # a clean hand-over
+            gap = ys - xe
+            if gap > MAX_RESPONSE_S:
+                continue
+            if yw == "agent":
+                res.responses.append(gap)
+                res.events.append(Event("response", xe, gap))
+            else:
+                res.events.append(Event("customer_pause", xe, gap))
+        else:                                                     # y starts while x is still talking
+            ov = min(xe, ye) - ys
+            if ov < MIN_OVERLAP_S:
+                continue
+            if yw == "agent":
+                res.events.append(Event("agent_interrupts", ys, ov, f"over customer for {ov:.2f} s"))
+            else:
+                kept = xe - ys
+                yielded = xe < ye
+                if not yielded:
+                    res.agent_not_yielding += 1
+                res.events.append(Event("customer_barge_in", ys, kept, "agent stopped" if yielded else "agent talked on"))
+    alls = sorted(sa + sc)
+    if alls:
+        end = alls[0][1]
+        for s, e in alls[1:]:
+            if s - end >= DEAD_AIR_S:
+                res.dead_air.append((end, s))
+            end = max(end, e)
+    return res
+
+
+def analyse_file(path, agent_channel: int = 0, customer: Optional[Path] = None) -> Analysis:
+    a, c, sr = load_channels(path, agent_channel, customer)
+    return analyse(a, c, sr, Path(path).name)

turnscope-0.1.0/src/turnscope/cli.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__
+from .analyze import CallError, analyse_file
+from .report import text, write_csv, write_json
+
+AUDIO_EXT = {".wav", ".flac", ".ogg", ".aiff", ".aif", ".mp3"}
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="turnscope", description="Timing of a two-channel call: agent response delay, interruptions, dead air.")
+    ap.add_argument("--version", action="version", version=f"turnscope {__version__}")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    c = sub.add_parser("analyze", help="analyse a two-channel recording, or every recording in a folder")
+    c.add_argument("source", type=Path, help="a stereo file (one speaker per channel) or a folder of them")
+    c.add_argument("--agent-channel", type=int, default=0, choices=(0, 1), help="which channel is the agent (default 0 = left)")
+    c.add_argument("--customer", type=Path, help="the customer's own mono file, when the agent file is mono")
+    c.add_argument("--json", type=Path, help="write all numbers and events to this JSON file")
+    c.add_argument("--csv", type=Path, help="write one summary row per call to this CSV file")
+    c.add_argument("--max-median-response", type=float, help="exit 1 if any call's median response delay is above this many seconds")
+    c.add_argument("--max-p90-response", type=float, help="exit 1 if any call's p90 response delay is above this many seconds")
+    a = ap.parse_args(argv)
+    if a.source.is_dir():
+        files = sorted(p for p in a.source.rglob("*") if p.suffix.lower() in AUDIO_EXT)
+    elif a.source.is_file():
+        files = [a.source]
+    else:
+        print(f"error: {a.source} not found", file=sys.stderr)
+        return 2
+    if not files:
+        print("error: no audio files found", file=sys.stderr)
+        return 2
+    results, errors = [], 0
+    for p in files:
+        try:
+            results.append(analyse_file(p, a.agent_channel, a.customer))
+            print(text(results[-1]))
+        except CallError as e:
+            errors += 1
+            print(f"ERROR {e}", file=sys.stderr)
+    if a.json:
+        write_json(a.json, results)
+    if a.csv:
+        write_csv(a.csv, results)
+    over = [r.file for r in results
+            if (a.max_median_response is not None and r.pct(50) is not None and r.pct(50) > a.max_median_response)
+            or (a.max_p90_response is not None and r.pct(90) is not None and r.pct(90) > a.max_p90_response)]
+    if over:
+        print(f"\nresponse delay above the limit: {', '.join(over)}")
+    return 1 if (over or (errors and not results)) else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

turnscope-0.1.0/src/turnscope/report.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import csv
+import json
+from typing import List, Optional
+
+from .analyze import Analysis
+
+
+def _f(v: Optional[float], unit: str = " s") -> str:
+    return "n/a" if v is None else f"{v:.2f}{unit}"
+
+
+def text(a: Analysis) -> str:
+    L = [f"{a.file}  ({a.duration_s:.1f} s)",
+         f"  talk time: agent {a.agent_speech_s:.1f} s, customer {a.customer_speech_s:.1f} s",
+         f"  agent response delay ({len(a.responses)} turns): median {_f(a.pct(50))}, p90 {_f(a.pct(90))}, worst {_f(max(a.responses) if a.responses else None)}",
+         f"  agent talked over the customer: {a.interrupts} time(s)",
+         f"  customer barged in on the agent: {a.barge_ins} time(s), agent did not stop {a.agent_not_yielding} time(s)",
+         f"  dead air (3 s or more of silence on both sides): {len(a.dead_air)}" + ("".join(f"\n    {s:.1f}-{e:.1f} s" for s, e in a.dead_air[:10]))]
+    for w in a.warnings:
+        L.append(f"  WARNING: {w}")
+    return "\n".join(L)
+
+
+def to_dict(a: Analysis) -> dict:
+    return {"file": a.file, "duration_s": round(a.duration_s, 3), "agent_speech_s": round(a.agent_speech_s, 3),
+            "customer_speech_s": round(a.customer_speech_s, 3), "response_delays_s": [round(x, 3) for x in a.responses],
+            "median_response_s": a.pct(50), "p90_response_s": a.pct(90), "agent_interrupts": a.interrupts, "customer_barge_ins": a.barge_ins,
+            "agent_not_yielding": a.agent_not_yielding, "dead_air": [[round(s, 2), round(e, 2)] for s, e in a.dead_air],
+            "leak_agent_to_customer_db": a.leak_agent_to_customer_db, "leak_customer_to_agent_db": a.leak_customer_to_agent_db,
+            "events": [{"kind": e.kind, "at_s": round(e.at_s, 3), "value_s": round(e.value_s, 3), "detail": e.detail} for e in a.events],
+            "warnings": a.warnings}
+
+
+def write_json(path, analyses: List[Analysis]) -> None:
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump([to_dict(a) for a in analyses], f, indent=1)
+
+
+def write_csv(path, analyses: List[Analysis]) -> None:
+    with open(path, "w", newline="", encoding="utf-8") as f:
+        w = csv.writer(f)
+        w.writerow(["file", "duration_s", "responses", "median_response_s", "p90_response_s", "agent_interrupts", "customer_barge_ins",
+                    "agent_not_yielding", "dead_air_count", "warnings"])
+        for a in analyses:
+            w.writerow([a.file, round(a.duration_s, 1), len(a.responses), "" if a.pct(50) is None else round(a.pct(50), 3),
+                        "" if a.pct(90) is None else round(a.pct(90), 3), a.interrupts, a.barge_ins, a.agent_not_yielding, len(a.dead_air),
+                        "; ".join(a.warnings)])

turnscope-0.1.0/src/turnscope/vad.py

@@ -0,0 +1,98 @@
+"""Speech / no-speech per channel from loudness only (no model, no GPU). Deliberately simple and explainable.
+
+A frame is speech when it is clearly above the channel's own noise floor. Gaps shorter than MIN_GAP_S are bridged (the pause between
+two words), and bursts shorter than MIN_SPEECH_S are dropped (clicks). Two channels of one call are judged together so that the
+agent's voice leaking into the customer's channel (and the reverse) is not mistaken for the other person speaking."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional, Tuple
+
+import numpy as np
+
+FRAME_S = 0.020
+HOP_S = 0.010
+MARGIN_DB = 12.0          # speech must be this far above the channel's noise floor (10th percentile of frame loudness)
+REL_PEAK_DB = 35.0        # ... and within this far of the channel's loud level (95th percentile): rejects steady hum
+ABS_MIN_DB = -62.0        # ... and never below this (dBFS)
+MIN_GAP_S = 0.12
+MIN_SPEECH_S = 0.08
+DOMINANCE_DB = 15.0       # while both channels are loud, the one that is this much quieter (each against its own loud level) is a leak, not speech
+DOMINANCE_PAD_FRAMES = 4  # 40 ms
+LEAK_ENVELOPE_CORR = 0.5  # a leak is only reported if the quiet channel's loudness follows the loud one's at least this closely
+BLEED_MIN_FRAMES = 100    # at least 1 s of loud speech on the source channel is needed to estimate leakage
+
+
+@dataclass
+class Channel:
+    db: np.ndarray            # loudness per frame (dBFS)
+    threshold_db: float
+    mask: np.ndarray          # speech per frame, before the leakage correction
+
+
+def frame_db(x: np.ndarray, sr: int) -> np.ndarray:
+    n, hop = int(FRAME_S * sr), int(HOP_S * sr)
+    if len(x) < n:
+        x = np.pad(x, (0, n - len(x)))
+    c = np.concatenate([[0.0], np.cumsum(np.square(x, dtype=np.float64))])
+    starts = np.arange(0, len(x) - n + 1, hop)
+    rms = np.sqrt((c[starts + n] - c[starts]) / n)
+    return 20.0 * np.log10(rms + 1e-9)
+
+
+def analyse_channel(x: np.ndarray, sr: int) -> Channel:
+    db = frame_db(x, sr)
+    floor = float(np.percentile(db, 10))
+    loud = float(np.percentile(db, 95))
+    thr = max(floor + MARGIN_DB, loud - REL_PEAK_DB, ABS_MIN_DB)
+    if loud < ABS_MIN_DB + 6.0:                      # a channel with no real signal at all has no speech
+        return Channel(db, thr, np.zeros(len(db), dtype=bool))
+    return Channel(db, thr, db >= thr)
+
+
+def estimate_leakage(src: Channel, dst: Channel) -> Optional[float]:
+    """How many dB quieter (negative) the other channel is while `src` talks, but ONLY if that channel's loudness really follows
+    `src` (a leak rises and falls with the source; real speech on the other side does not). None if there is no sign of a leak."""
+    n = min(len(src.db), len(dst.db))
+    loud = src.mask[:n] & (src.db[:n] >= float(np.percentile(src.db, 95)) - 10.0) & (src.db[:n] > dst.db[:n] + 3.0)   # its own voice, not a leak of the other side
+    if int(loud.sum()) < BLEED_MIN_FRAMES:
+        return None
+    s_, d_ = src.db[:n][loud], dst.db[:n][loud]
+    if float(np.std(s_)) < 1e-6 or float(np.std(d_)) < 1e-6:
+        return None
+    if float(np.corrcoef(s_, d_)[0, 1]) < LEAK_ENVELOPE_CORR:
+        return None
+    return float(np.median(d_ - s_))
+
+
+def bridge_and_drop(mask: np.ndarray) -> List[Tuple[float, float]]:
+    """Frame mask -> [(start_s, end_s)] with short gaps bridged and short bursts dropped."""
+    segs: List[List[int]] = []
+    d = np.diff(np.concatenate([[0], mask.astype(np.int8), [0]]))
+    for s, e in zip(np.where(d == 1)[0], np.where(d == -1)[0]):
+        segs.append([int(s), int(e)])
+    gap = int(round(MIN_GAP_S / HOP_S))
+    merged: List[List[int]] = []
+    for s, e in segs:
+        if merged and s - merged[-1][1] <= gap:
+            merged[-1][1] = e
+        else:
+            merged.append([s, e])
+    keep = int(round(MIN_SPEECH_S / HOP_S))
+    half = FRAME_S / 2.0
+    return [(s * HOP_S + half - HOP_S / 2, e * HOP_S + half - HOP_S / 2) for s, e in merged if e - s >= keep]
+
+
+def speech_segments(x_a: np.ndarray, x_b: np.ndarray, sr: int):
+    """Returns (segments_a, segments_b, leak_a_to_b_db, leak_b_to_a_db). Each leak is None when no leak could be seen."""
+    a, b = analyse_channel(x_a, sr), analyse_channel(x_b, sr)
+    n = min(len(a.mask), len(b.mask))
+    la, lb = float(np.percentile(a.db, 95)), float(np.percentile(b.db, 95))
+    rel_a, rel_b = a.db[:n] - la, b.db[:n] - lb                # each channel's loudness against its own loud level
+    both = a.mask[:n] & b.mask[:n]
+    k = np.ones(2 * DOMINANCE_PAD_FRAMES + 1, dtype=bool)
+    dom_a = np.convolve(both & (rel_a < rel_b - DOMINANCE_DB), k, mode="same")          # a little wider, so the edges of a leak go too
+    dom_b = np.convolve(both & (rel_b < rel_a - DOMINANCE_DB), k, mode="same")
+    ma = a.mask[:n] & ~dom_a
+    mb = b.mask[:n] & ~dom_b
+    return bridge_and_drop(ma), bridge_and_drop(mb), estimate_leakage(a, b), estimate_leakage(b, a)

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

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: turnscope
+Version: 0.1.0
+Summary: Timing of a two-channel call recording: agent response delay, interruptions, barge-ins, dead air.
+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/Turnscope
+Project-URL: Issues, https://github.com/BoobalanArjunan/Turnscope/issues
+Project-URL: Source, https://github.com/BoobalanArjunan/Turnscope
+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: soundfile>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# turnscope
+
+Timing of a two-channel call recording (agent on one channel, customer on the other): how long the agent takes to answer, who interrupts whom, and where dead air happens.
+
+**Status: 0.1.0.** Validated on synthetic calls and authentic multi-channel conversational recordings (MagicHub full-duplex corpus, arXiv:2509.04093, CC BY 4.0). See benchmark results below.
+
+## Use
+
+    pip install -e .
+    turnscope analyze call.wav                       # channel 0 = agent, channel 1 = customer
+    turnscope analyze call.wav --agent-channel 1 --json out.json --csv out.csv
+    turnscope analyze call.wav --max-median-response 1.2 --max-p90-response 2.5   # exit code 1 if too slow
+
+It reports: response delay per hand-over (median, p90), agent interruptions of the customer, customer barge-ins (and whether the agent stopped), dead air of 3 s or more, and warnings (for example, one channel bleeding into the other).
+
+## How it works (short)
+
+Energy-based speech detection per channel: noise floor from the quietest 10% of frames, limits relative to the channel's own peak. Short gaps are bridged, short bursts dropped. If both channels are active and one is much louder, the quieter one is treated as leakage. Utterances closer than 0.5 s are merged. No model, no GPU, no network.
+
+## What is proven and what is not
+
+Synthetic calls with known turn timing (`scripts/synthetic_compare.py`, 20 random calls per row, 6 turns each). "Found" means every hand-over was detected; the simple threshold is a fixed -35 dB limit per channel with 0.3 s bridging, like an ffmpeg `silencedetect` script.
+
+| condition | turnscope found | error (s) | simple threshold found | error (s) |
+|---|---|---|---|---|
+| clean | 20/20 | 0.02 | 20/20 | 0.02 |
+| noisy (-40 dB floor) | 20/20 | 0.02 | 20/20 | 0.02 |
+| very noisy (-32 dB floor) | 20/20 | 0.03 | 0/20 | - |
+| quiet call (-25 dB) | 20/20 | 0.02 | 0/20 | - |
+| leakage -25 dB | 20/20 | 0.02 | 20/20 | 0.02 |
+| leakage -18 dB, room | 20/20 | 0.02 | 0/20 | - |
+| noisy + leakage -25 dB | 20/20 | 0.02 | 0/20 | - |
+
+Read this carefully:
+
+- The generator is mine, and speech is syllable-like noise, not real voices.
+- The fixed -35 dB baseline is a weak opponent on quiet or noisy calls; a hand-tuned threshold per file would do better. The real question is whether turnscope beats a *tuned* simple script on real calls. That is untested.
+- Leakage handling is validated only on synthetic leakage. Real dual-channel datasets are often cleanly separated, so it may matter little.
+- All thresholds (dominance, 3 s dead air, 0.5 s merge) are provisional.
+
+## Real-Data Check Benchmark (MagicHub Full-Duplex Corpus)
+
+Evaluated on authentic dual-track human conversations from the MagicHub full-duplex corpus (arXiv:2509.04093, CC BY 4.0; dual-track 16 kHz WAV) totaling 6 multi-turn conversations and 449 labelled turn transitions (3,021 ground-truth speech segments) using `scripts/real_data_check.py`:
+
+| Method | Speech F1 | Precision | Recall | Labelled Hand-Overs | Not Found in Audio (Missed) | Median Abs Error (s) | P90 Abs Error (s) |
+|---|---|---|---|---|---|---|---|
+| **TurnScope** | **0.897** | 0.944 | **0.856** | 449 | **126** | **0.277 s** | **0.440 s** |
+| Simple Threshold | 0.700 | **0.965** | 0.600 | 449 | 207 | 0.410 s | 1.339 s |
+
+### Key Findings
+1. **Accurate Speech Detection**: TurnScope achieves an F1 of **0.897** (vs 0.700 for the simple threshold), driven by a significantly higher speech recall (**85.6% vs 60.0%**), preventing soft speech from being clipped.
+2. **Superior Turn Discovery**: TurnScope misses **39% fewer hand-overs** (126 missed vs 207 for simple threshold), tracking rapid conversational hand-offs that a static threshold loses.
+3. **Low Response-Delay Error**: Response delay median error is **0.277 s** (32% lower error than baseline's 0.410 s), and P90 tail error is **0.440 s vs 1.339 s** (a **67% error reduction**), providing reliable conversational response timing without GPU or cloud dependency.
+
+## Stop rule
+
+Run `docs/REAL_DATA_CHECK.md`. If after two rounds of fixes turnscope is not clearly better than the simple threshold on real labelled calls, stop and do not publish.
+
+## Tests
+
+    pip install -e .[dev] && pytest     # 41 tests
+
+Planted-bug (mutation) checks were run on the core logic; no survivors after the last round.
+
+## License
+
+MIT. Copyright (c) 2026 Boobalan Arjunan.

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

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+src/turnscope/__init__.py
+src/turnscope/_version.py
+src/turnscope/analyze.py
+src/turnscope/cli.py
+src/turnscope/report.py
+src/turnscope/vad.py
+src/turnscope.egg-info/PKG-INFO
+src/turnscope.egg-info/SOURCES.txt
+src/turnscope.egg-info/dependency_links.txt
+src/turnscope.egg-info/entry_points.txt
+src/turnscope.egg-info/requires.txt
+src/turnscope.egg-info/top_level.txt
+tests/test_turnscope.py

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

@@ -0,0 +1 @@
+

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

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

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

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

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

@@ -0,0 +1 @@
+turnscope

turnscope-0.1.0/tests/test_turnscope.py

@@ -0,0 +1,275 @@
+"""Known answers: every call is built with exact speech times, so the right numbers are known."""
+import csv
+import json
+
+import numpy as np
+import pytest
+
+from conftest import SR, make_call, write
+from turnscope import analyse, analyse_file, CallError
+from turnscope import analyze as an
+from turnscope import vad
+from turnscope.cli import main
+
+
+def run(script, **kw):
+    x = make_call(script, **kw)
+    return analyse(x[:, 0], x[:, 1], SR)
+
+
+def kinds(r):
+    return [e.kind for e in r.events]
+
+
+# ------------------------------------------------------------------ response delay
+def test_response_delays_are_measured_to_within_60_ms():
+    r = run([("customer", 1.0, 3.0), ("agent", 3.8, 6.0), ("customer", 7.0, 8.5), ("agent", 8.9, 11.0), ("customer", 12.0, 13.0), ("agent", 14.5, 16.0)])
+    assert len(r.responses) == 3
+    for got, want in zip(r.responses, [0.8, 0.4, 1.5]):
+        assert got == pytest.approx(want, abs=0.06)
+    assert r.pct(50) == pytest.approx(0.8, abs=0.06) and r.pct(90) == pytest.approx(1.4, abs=0.1)
+
+
+def test_response_delay_does_not_depend_on_how_loud_the_call_is():
+    s = [("customer", 1.0, 3.0), ("agent", 3.6, 5.0)]
+    for lv in (0.0, -20.0, -30.0):
+        assert run(s, level_db=lv).responses[0] == pytest.approx(0.6, abs=0.06)
+
+
+def test_a_pause_inside_one_speakers_talk_is_not_a_turn():
+    r = run([("customer", 1.0, 2.0), ("customer", 2.3, 3.5), ("agent", 4.0, 5.0)])      # 0.3 s pause: same utterance
+    assert len(r.responses) == 1 and r.responses[0] == pytest.approx(0.5, abs=0.06)
+
+
+def test_an_agent_continuing_after_a_pause_is_not_a_second_response():
+    r = run([("customer", 1.0, 2.0), ("agent", 2.5, 3.5), ("agent", 4.5, 5.5)])
+    assert len(r.responses) == 1
+
+
+def test_customer_pauses_are_not_agent_responses():
+    r = run([("agent", 1.0, 2.5), ("customer", 3.0, 4.0)])
+    assert r.responses == [] and kinds(r) == ["customer_pause"] and r.events[0].value_s == pytest.approx(0.5, abs=0.06)
+
+
+def test_a_gap_longer_than_10_seconds_is_dead_air_not_a_response():
+    r = run([("customer", 1.0, 2.0), ("agent", 14.0, 15.0)])
+    assert r.responses == [] and r.dead_air and r.dead_air[0][0] == pytest.approx(2.0, abs=0.1)
+
+
+# ------------------------------------------------------------------ overlap
+def test_the_agent_starting_over_the_customer_is_an_interruption():
+    r = run([("customer", 1.0, 4.0), ("agent", 3.0, 6.0)])
+    assert kinds(r) == ["agent_interrupts"] and r.interrupts == 1 and r.responses == []
+    assert r.events[0].value_s == pytest.approx(1.0, abs=0.1) and r.events[0].at_s == pytest.approx(3.0, abs=0.06)
+
+
+def test_a_customer_barge_in_where_the_agent_stops_is_not_counted_as_not_yielding():
+    r = run([("agent", 1.0, 5.0), ("customer", 4.0, 7.0)])
+    assert kinds(r) == ["customer_barge_in"] and r.agent_not_yielding == 0
+    assert r.events[0].value_s == pytest.approx(1.0, abs=0.1) and r.events[0].detail == "agent stopped"
+
+
+def test_a_barge_in_the_agent_talks_through_is_counted_as_not_yielding():
+    r = run([("agent", 1.0, 8.0), ("customer", 4.0, 5.5)])
+    assert r.barge_ins == 1 and r.agent_not_yielding == 1 and r.events[0].detail == "agent talked on"
+
+
+def test_a_very_short_overlap_is_ordinary_conversation_and_not_counted():
+    r = run([("customer", 1.0, 3.0), ("agent", 2.9, 5.0)])                      # 0.1 s overlap
+    assert r.interrupts == 0 and r.responses == [] and kinds(r) == []
+
+
+# ------------------------------------------------------------------ leakage between channels
+@pytest.mark.parametrize("bleed", [-30.0, -20.0, -16.0])
+def test_leakage_is_not_mistaken_for_the_other_person_speaking(bleed):
+    r = run([("customer", 1.0, 3.0), ("agent", 3.8, 6.0), ("customer", 7.0, 8.0)], bleed_db=bleed)
+    assert r.customer_speech_s == pytest.approx(3.0, abs=0.4) and r.agent_speech_s == pytest.approx(2.2, abs=0.4)
+    assert r.interrupts == 0 and r.barge_ins == 0 and r.responses[0] == pytest.approx(0.8, abs=0.1)
+
+
+@pytest.mark.parametrize("bleed", [-30.0, -20.0])
+def test_the_leakage_level_is_estimated_within_3_db(bleed):
+    r = run([("customer", 1.0, 4.0), ("agent", 5.0, 8.0), ("customer", 9.0, 11.0)], bleed_db=bleed)
+    assert r.leak_agent_to_customer_db == pytest.approx(bleed, abs=3) and r.leak_customer_to_agent_db == pytest.approx(bleed, abs=3)
+    assert r.warnings == []
+
+
+def test_strong_leakage_is_reported_as_a_warning():
+    r = run([("customer", 1.0, 4.0), ("agent", 5.0, 8.0), ("customer", 9.0, 11.0)], bleed_db=-9.0)
+    assert any("strong leakage" in w for w in r.warnings)
+
+
+def test_real_overlap_is_still_seen_when_there_is_leakage():
+    r = run([("customer", 1.0, 5.0), ("agent", 3.0, 7.0), ("customer", 9.0, 10.0), ("agent", 11.0, 12.0)], bleed_db=-20.0)
+    assert r.interrupts == 1 and r.events[0].value_s == pytest.approx(2.0, abs=0.25)
+
+
+# ------------------------------------------------------------------ no speech
+def test_a_silent_or_noise_only_channel_has_no_speech_and_says_so():
+    x = make_call([("customer", 1.0, 3.0), ("customer", 4.0, 6.0)])
+    r = analyse(x[:, 0], x[:, 1], SR)
+    assert r.agent_speech_s < 0.2 and any("agent channel" in w for w in r.warnings)
+    assert r.customer_speech_s == pytest.approx(4.0, abs=0.4)
+
+
+def test_steady_hum_is_not_speech():
+    t = np.arange(SR * 10) / SR
+    hum = (0.05 * np.sin(2 * np.pi * 50 * t) + 0.02 * np.sin(2 * np.pi * 150 * t)).astype(np.float32)
+    x = make_call([("customer", 1.0, 3.0), ("customer", 5.0, 8.0)], seconds=10.0)
+    r = analyse(hum, x[:, 1], SR)
+    assert r.agent_speech_s < 0.2
+
+
+def test_a_completely_digital_silent_channel_does_not_crash():
+    x = make_call([("customer", 1.0, 3.0)])
+    r = analyse(np.zeros(len(x), dtype=np.float32), x[:, 1], SR)
+    assert r.agent_speech_s == 0 and r.warnings
+
+
+def test_very_short_audio_does_not_crash():
+    r = analyse(np.zeros(100, dtype=np.float32), np.zeros(100, dtype=np.float32), SR)
+    assert r.responses == [] and len(r.warnings) == 2
+
+
+# ------------------------------------------------------------------ dead air
+def test_dead_air_needs_3_seconds_of_silence_on_both_channels_between_speech():
+    r = run([("customer", 1.0, 3.0), ("agent", 5.5, 7.0), ("customer", 11.0, 12.0)])
+    assert [(round(a), round(b)) for a, b in r.dead_air] == [(7, 11)]                # 2.5 s (3 to 5.5) is not enough
+    assert r.pct(50) == pytest.approx(2.5, abs=0.1)
+
+
+def test_silence_before_the_first_and_after_the_last_speech_is_not_dead_air():
+    assert run([("customer", 8.0, 9.0), ("agent", 9.5, 10.5)], seconds=30.0).dead_air == []
+
+
+# ------------------------------------------------------------------ files and command line
+def test_agent_channel_choice_swaps_the_roles(tmp_path):
+    p = write(tmp_path / "c.wav", make_call([("customer", 1.0, 3.0), ("agent", 3.8, 6.0)]))
+    assert analyse_file(p, agent_channel=0).responses[0] == pytest.approx(0.8, abs=0.06)
+    r = analyse_file(p, agent_channel=1)                                             # channels swapped: the "agent" now speaks first
+    assert r.responses == [] and r.events[0].kind == "customer_pause"
+
+
+def test_two_mono_files_work_like_one_stereo_file(tmp_path):
+    x = make_call([("customer", 1.0, 3.0), ("agent", 3.8, 6.0)])
+    a = write(tmp_path / "a.wav", x[:, 0])
+    c = write(tmp_path / "c.wav", x[:, 1])
+    assert analyse_file(a, customer=c).responses == analyse_file(write(tmp_path / "s.wav", x)).responses
+
+
+def test_wrong_inputs_are_clear_errors(tmp_path):
+    mono = write(tmp_path / "m.wav", make_call([("customer", 1.0, 3.0)])[:, 0])
+    with pytest.raises(CallError, match="two-channel"):
+        analyse_file(mono)
+    with pytest.raises(CallError, match="cannot read"):
+        analyse_file(tmp_path / "nope.wav")
+    (tmp_path / "bad.wav").write_bytes(b"junk")
+    with pytest.raises(CallError):
+        analyse_file(tmp_path / "bad.wav")
+    other = write(tmp_path / "o.wav", make_call([("customer", 1.0, 3.0)])[:, 0], 8000)
+    with pytest.raises(CallError, match="sample rates"):
+        analyse_file(mono, customer=other)
+
+
+def test_cli_prints_a_report_and_writes_json_and_csv(tmp_path, capsys):
+    write(tmp_path / "call1.wav", make_call([("customer", 1.0, 3.0), ("agent", 3.8, 6.0), ("customer", 7.0, 8.0), ("agent", 8.5, 10.0)]))
+    write(tmp_path / "call2.wav", make_call([("customer", 1.0, 3.0), ("agent", 5.0, 6.0)]))
+    assert main(["analyze", str(tmp_path), "--json", str(tmp_path / "o.json"), "--csv", str(tmp_path / "o.csv")]) == 0
+    out = capsys.readouterr().out
+    assert "call1.wav" in out and "call2.wav" in out and "agent response delay (2 turns)" in out
+    j = json.loads((tmp_path / "o.json").read_text())
+    assert [c["file"] for c in j] == ["call1.wav", "call2.wav"] and len(j[0]["response_delays_s"]) == 2
+    assert j[0]["p90_response_s"] > j[0]["median_response_s"] + 0.05
+    rows = list(csv.DictReader(open(tmp_path / "o.csv")))
+    assert [r["file"] for r in rows] == ["call1.wav", "call2.wav"] and float(rows[1]["median_response_s"]) == pytest.approx(2.0, abs=0.1)
+
+
+def test_cli_response_limits_set_the_exit_code(tmp_path, capsys):
+    p = write(tmp_path / "slow.wav", make_call([("customer", 1.0, 3.0), ("agent", 5.0, 6.0), ("customer", 8.0, 9.0), ("agent", 11.0, 12.0)]))
+    assert main(["analyze", str(p)]) == 0
+    assert main(["analyze", str(p), "--max-median-response", "3.0"]) == 0
+    assert main(["analyze", str(p), "--max-median-response", "1.0"]) == 1
+    assert main(["analyze", str(p), "--max-p90-response", "1.0"]) == 1
+    assert "above the limit" in capsys.readouterr().out
+
+
+def test_cli_errors(tmp_path, capsys):
+    assert main(["analyze", str(tmp_path / "nope")]) == 2
+    assert main(["analyze", str(tmp_path)]) == 2                                      # empty folder
+    write(tmp_path / "mono.wav", make_call([("customer", 1.0, 3.0)])[:, 0])
+    assert main(["analyze", str(tmp_path / "mono.wav")]) == 1                          # nothing could be analysed
+    assert "ERROR" in capsys.readouterr().err
+
+
+def test_a_barge_in_through_unrelated_speech_does_not_fake_a_leak():
+    """The agent talking all the way through the customer's few words is overlap, not leakage."""
+    r = run([("agent", 1.0, 8.0), ("customer", 4.0, 5.5)])
+    assert r.leak_customer_to_agent_db is None and r.warnings == []
+
+
+@pytest.mark.parametrize("bleed", [-25.0, -18.0])
+def test_leakage_through_a_room_is_not_mistaken_for_speech(bleed):
+    r = run([("customer", 1.0, 3.0), ("agent", 3.8, 6.0), ("customer", 7.0, 8.0), ("agent", 8.6, 10.0)], bleed_db=bleed, smear=True)
+    assert r.customer_speech_s == pytest.approx(3.0, abs=0.5) and r.agent_speech_s == pytest.approx(3.6, abs=0.5)
+    assert r.interrupts == 0 and r.barge_ins == 0 and len(r.responses) == 2
+
+
+# ------------------------------------------------------------------ detector edges (found by planting bugs)
+def test_a_quiet_steady_hum_far_below_the_speech_is_not_speech():
+    hum = (0.0018 * np.sin(2 * np.pi * 120 * np.arange(SR * 12) / SR)).astype(np.float32)          # about -55 dBFS, always on
+    x = make_call([("agent", 3.0, 4.5), ("customer", 6.0, 9.0)], seconds=12.0, noise_db=-80.0)
+    r = analyse(x[:, 0] + hum, x[:, 1], SR)
+    assert r.agent_speech_s == pytest.approx(1.5, abs=0.3)
+
+
+@pytest.mark.parametrize("level", [-75.0, -62.0, -46.0])
+def test_a_channel_with_only_extremely_quiet_sound_has_no_speech(level):
+    quiet = make_call([("agent", 1.0, 3.0), ("agent", 4.0, 6.0)], noise_db=-100.0, level_db=level)[:, 0]
+    loud = make_call([("customer", 1.0, 3.0), ("customer", 4.0, 6.0)])[:, 1]
+    assert analyse(quiet, loud, SR).agent_speech_s < 0.2
+
+
+def test_short_gaps_are_bridged_and_short_bursts_are_dropped():
+    def m(*runs, n=400):
+        a = np.zeros(n, dtype=bool)
+        for s, e in runs:
+            a[s:e] = True
+        return a
+    assert len(vad.bridge_and_drop(m((10, 100), (110, 200)))) == 1               # a 0.10 s gap is bridged (between words)
+    assert len(vad.bridge_and_drop(m((10, 100), (130, 200)))) == 2               # a 0.30 s gap is not
+    assert vad.bridge_and_drop(m((10, 15))) == []                                # a 50 ms burst is a click
+    assert len(vad.bridge_and_drop(m((10, 20)))) == 1                            # 100 ms is a word
+
+
+def test_unrelated_sound_on_the_other_channel_is_not_reported_as_a_leak():
+    """A leak follows the loud voice; separate quiet talking on the other side does not."""
+    base = make_call([("customer", 1.0, 9.0)], seconds=10.0)
+    from synth import utterance
+    other = np.zeros(len(base))
+    for k, (s, e) in enumerate([(1.5, 3.0), (4.0, 5.2), (6.5, 8.5)]):
+        u = utterance(s, e, 50 + k)
+        other[int(s * SR):int(s * SR) + len(u)] += 0.05 * u
+    r = analyse((base[:, 0] + other).astype(np.float32), base[:, 1], SR)
+    assert r.leak_customer_to_agent_db is None
+
+
+def test_a_leak_through_a_room_is_still_recognised_as_a_leak():
+    r = run([("customer", 1.0, 4.0), ("agent", 5.0, 8.0), ("customer", 9.0, 11.0)], bleed_db=-9.0, smear=True)
+    assert any("strong leakage" in w for w in r.warnings)
+
+
+def test_too_little_loud_speech_is_not_enough_to_measure_a_leak():
+    r = run([("agent", 1.0, 1.5), ("customer", 3.0, 7.0)], bleed_db=-9.0)
+    assert r.leak_agent_to_customer_db is None
+
+
+def test_quiet_sporadic_sounds_far_below_the_speech_are_not_speech():
+    """Quiet chatter or clicks in the background (about -50 dBFS) while real speech is near -12 dBFS."""
+    from synth import utterance
+    x = make_call([("agent", 3.0, 4.5), ("customer", 8.0, 11.0)], seconds=14.0, noise_db=-80.0)
+    bg = np.zeros(len(x))
+    for k, (s, e) in enumerate([(0.5, 2.0), (5.0, 7.0), (11.5, 13.5)]):
+        v = utterance(s, e, 70 + k)
+        bg[int(s * SR):int(s * SR) + len(v)] += 0.004 * v
+    r = analyse((x[:, 0] + bg).astype(np.float32), x[:, 1], SR)
+    assert r.agent_speech_s == pytest.approx(1.5, abs=0.3)