primocode 10.16.0 → 10.17.1

package/editor/helpers/voice_levels.py

@@ -0,0 +1,233 @@
+"""Voice level per phrase (or per EDL range) against the speaker's reference level.
+
+The level of a range is the RMS of its SPEECH samples only (pauses inside the range are
+left out, using the speech regions of the source), after an 80 Hz high-pass so room
+rumble does not count as voice. The reference is the speech-weighted median of the levels
+(the level half of the speech time sits at or above), so a cut split between a loud take and
+a quiet take is measured against the take with more speech, not against the middle.
+Ranges at least --drop-db below the reference are listed with the `gain_db` to write in the
+EDL (the whole difference, capped at +-12).
+
+Modes:
+- phrases: `voice_levels.py <video>` uses edit/transcripts/<stem>.json (phrases as in
+  takes_packed.md). Without a transcript it falls back to the speech regions.
+- EDL: `voice_levels.py [<video>] --edl edit/edl.json` measures the EDL ranges WITH their
+  current gain_db applied, so a gain already set is not suggested again. Ranges --drop-db
+  above the reference are listed too. The suggestion is the final gain_db (current + change).
+  Sources resolve like render_cut (absolute, or relative to the edit dir or its parent). With
+  a video only that source is listed.
+
+Writes edit/verify/voice_levels.json with every range measured.
+
+Usage:
+    uv run python helpers/voice_levels.py <video> [--edit-dir DIR] [--edl edl.json] [--drop-db 5] [--all]
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+import numpy as np
+
+from common import load_json, now_iso, save_json
+from pack_transcripts import phrases_for_transcript
+from render_cut import resolve_source
+from speech_regions import SAMPLE_RATE, AudioError, load_mono, load_or_compute_regions
+from verify_cut import weighted_median
+
+GAIN_CAP_DB = 12.0
+MIN_SPEECH_S = 0.2
+HIGHPASS = "highpass=f=80"
+
+
+def _db(x: float) -> float:
+    return float(10.0 * np.log10(x + 1e-12))
+
+
+def measure_range(mono: np.ndarray, speech: list[list[float]], start: float, end: float) -> dict:
+    """Speech-only RMS and peak of [start, end]."""
+    n = len(mono)
+    total_sq, total_n = 0.0, 0
+    for s, e in speech:
+        a, b = max(s, start), min(e, end)
+        if b <= a:
+            continue
+        i, j = int(a * SAMPLE_RATE), min(int(b * SAMPLE_RATE), n)
+        if j <= i:
+            continue
+        seg = mono[i:j].astype(np.float64)
+        total_sq += float(np.dot(seg, seg))
+        total_n += j - i
+    i0, j0 = int(max(start, 0.0) * SAMPLE_RATE), min(int(end * SAMPLE_RATE), n)
+    peak = float(np.max(np.abs(mono[i0:j0]))) if j0 > i0 else 0.0
+    speech_s = total_n / SAMPLE_RATE
+    return {
+        "speech_s": round(speech_s, 2),
+        "level_db": round(_db(total_sq / total_n), 1) if speech_s >= MIN_SPEECH_S else None,
+        "peak_db": round(20.0 * np.log10(peak + 1e-9), 1),
+    }
+
+
+def _source_audio(path: Path, edit_dir: Path, cache: dict) -> tuple[np.ndarray, list[list[float]]]:
+    key = str(path)
+    if key not in cache:
+        regions = load_or_compute_regions(path, edit_dir)
+        mono, _ = load_mono(path, af=HIGHPASS)
+        cache[key] = (mono, regions["speech"])
+    return cache[key]
+
+
+def ranges_from_edl(edl_path: Path, edit_dir: Path) -> list[dict]:
+    edl = load_json(edl_path)
+    if not isinstance(edl, dict) or not isinstance(edl.get("ranges"), list):
+        raise ValueError(f"EDL inválido (sem 'ranges'): {edl_path}")
+    sources = edl.get("sources") or {}
+    out = []
+    for i, r in enumerate(edl["ranges"]):
+        stem = r.get("source")
+        src = sources.get(stem)
+        if not src:
+            raise ValueError(f"o range {r.get('id', i + 1)} usa a fonte '{stem}', que não está em 'sources'")
+        path = resolve_source(str(src), edl_path.parent)
+        out.append({"id": r.get("id") or f"r{i + 1}", "source": stem, "path": path,
+                    "start": float(r["start"]), "end": float(r["end"]),
+                    "text": r.get("quote") or r.get("beat") or "", "edl_gain_db": float(r.get("gain_db") or 0.0)})
+    return out
+
+
+def ranges_from_video(video: Path, edit_dir: Path) -> tuple[list[dict], str]:
+    transcript = load_json(edit_dir / "transcripts" / f"{video.stem}.json")
+    if isinstance(transcript, dict) and transcript.get("words"):
+        phrases = phrases_for_transcript(transcript)
+        return [{"id": f"f{i + 1}", "source": video.stem, "path": video, "start": p["start"], "end": p["end"],
+                 "text": p["text"]} for i, p in enumerate(phrases)], "phrases"
+    regions = load_or_compute_regions(video, edit_dir)
+    merged: list[list[float]] = []
+    for s, e in regions["speech"]:
+        if merged and s - merged[-1][1] < 0.5:
+            merged[-1][1] = e
+        else:
+            merged.append([s, e])
+    return [{"id": f"t{i + 1}", "source": video.stem, "path": video, "start": s, "end": e, "text": ""}
+            for i, (s, e) in enumerate(merged)], "regions"
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="Compara o volume da voz de cada frase (ou range do EDL) com o nível de referência da pessoa.")
+    ap.add_argument("video", type=Path, nargs="?", help="vídeo (opcional com --edl: sem ele mede todas as fontes)")
+    ap.add_argument("--edit-dir", type=Path, default=None, help="pasta edit (padrão: pasta do EDL ou <pasta do vídeo>/edit)")
+    ap.add_argument("--edl", type=Path, default=None, help="edl.json: mede os ranges do corte em vez das frases")
+    ap.add_argument("--drop-db", type=float, default=5.0, help="avisa trechos pelo menos isso abaixo (ou acima, no EDL) da referência (padrão 5)")
+    ap.add_argument("--all", action="store_true", help="lista todos os trechos, não só os baixos")
+    args = ap.parse_args()
+
+    if args.video is None and args.edl is None:
+        sys.exit("informe o vídeo ou --edl edit/edl.json")
+    video = args.video.absolute() if args.video else None
+    if video is not None and not video.exists():
+        sys.exit(f"vídeo não encontrado: {video}")
+    edl_path = None
+    if args.edl is not None:
+        edl_path = args.edl.absolute()
+        if not edl_path.exists() and video is not None and (video.parent / "edit" / args.edl).exists():
+            edl_path = (video.parent / "edit" / args.edl).absolute()
+        if not edl_path.exists():
+            sys.exit(f"EDL não encontrado: {edl_path}")
+    if args.edit_dir:
+        edit_dir = args.edit_dir.absolute()
+    elif edl_path is not None:
+        edit_dir = edl_path.parent
+    else:
+        edit_dir = video.parent / "edit"
+
+    try:
+        if edl_path is not None:
+            ranges, mode = ranges_from_edl(edl_path, edit_dir), "edl"
+        else:
+            ranges, mode = ranges_from_video(video, edit_dir)
+    except (ValueError, KeyError, TypeError) as exc:
+        sys.exit(str(exc))
+    if not ranges:
+        sys.exit("nenhum trecho para medir (sem fala detectada)")
+
+    cache: dict = {}
+    try:
+        for r in ranges:
+            if not Path(r["path"]).exists():
+                sys.exit(f"fonte não encontrada: {r['path']}")
+            mono, speech = _source_audio(Path(r["path"]), edit_dir, cache)
+            r.update(measure_range(mono, speech, r["start"], r["end"]))
+    except AudioError as exc:
+        sys.exit(str(exc))
+
+    edl_mode = mode == "edl"
+    for r in ranges:
+        # EDL mode: the level heard in the cut includes the gain already in the EDL.
+        current = float(r.get("edl_gain_db") or 0.0) if edl_mode else 0.0
+        r["current_gain_db"] = current
+        r["heard_db"] = None if r["level_db"] is None else round(r["level_db"] + current, 1)
+    measured = [r for r in ranges if r["heard_db"] is not None]
+    if not measured:
+        sys.exit("nenhum trecho tem fala suficiente para medir")
+    reference = weighted_median([r["heard_db"] for r in measured], [r["speech_s"] for r in measured])
+    for r in ranges:
+        if r["heard_db"] is None:
+            r.update(diff_db=None, low=False, high=False, gain_db=r["current_gain_db"])
+            continue
+        diff = round(r["heard_db"] - reference, 1)
+        low = diff <= -args.drop_db
+        high = edl_mode and diff >= args.drop_db
+        final = r["current_gain_db"] - diff if (low or high) else r["current_gain_db"]
+        r.update(diff_db=diff, low=low, high=high, gain_db=round(min(GAIN_CAP_DB, max(-GAIN_CAP_DB, final)), 1))
+
+    shown = [r for r in ranges if video is None or r["source"] == video.stem]
+    unit = {"edl": ("range do EDL", "ranges do EDL"), "phrases": ("frase", "frases"),
+            "regions": ("trecho de fala", "trechos de fala")}[mode][0 if len(shown) == 1 else 1]
+    scope = video.stem if video is not None else "todas as fontes"
+    gain_note = ", com o gain_db do EDL" if edl_mode else ""
+    print(f"Nível de voz · {scope} · {len(shown)} {unit} · referência {reference:.1f} dB "
+          f"(RMS só da fala{gain_note}; mediana pesada pelo tempo de fala)")
+    if mode == "regions":
+        print("  (sem transcrição: medi os trechos de fala; rode transcribe.py para medir por frase)")
+    listed = shown if args.all else [r for r in shown if r["low"] or r["high"]]
+    for r in listed:
+        where = f"{r['id']} {r['source']} " if edl_mode else ""
+        if r["heard_db"] is None:
+            print(f"  {where}[{r['start']:06.2f}-{r['end']:06.2f}] sem fala suficiente para medir")
+            continue
+        tip = ""
+        if r["low"] or r["high"]:
+            tip = (f"  gain_db final {r['gain_db']:+.1f} (hoje {r['current_gain_db']:+.1f})" if edl_mode
+                   else f"  gain_db {r['gain_db']:+.1f} se usar no EDL")
+        text = f'  "{r["text"][:60]}"' if r["text"] else ""
+        print(f"  {where}[{r['start']:06.2f}-{r['end']:06.2f}] {r['heard_db']:6.1f} dB ({r['diff_db']:+.1f}){tip}{text}")
+    n_low = sum(1 for r in shown if r["low"])
+    n_high = sum(1 for r in shown if r["high"])
+    if n_low + n_high == 0:
+        both = "abaixo ou acima" if edl_mode else "abaixo"
+        print(f"  nenhum trecho {args.drop_db:g} dB ou mais {both} da referência")
+    elif not args.all:
+        parts = []
+        if n_low:
+            parts.append(f"{n_low} {'trecho baixo' if n_low == 1 else 'trechos baixos'}")
+        if n_high:
+            parts.append(f"{n_high} {'trecho alto' if n_high == 1 else 'trechos altos'}")
+        print(f"  {' e '.join(parts)}. No EDL, troque o gain_db do range pelo valor final mostrado "
+              f"(máximo {GAIN_CAP_DB:g} dB para cima ou para baixo).")
+
+    out = edit_dir / "verify" / "voice_levels.json"
+    save_json(out, {
+        "mode": mode,
+        "edl": str(edl_path) if edl_path else None,
+        "reference_db": round(reference, 1),
+        "drop_db": args.drop_db,
+        "measured_at": now_iso(),
+        "ranges": [{k: (str(v) if k == "path" else v) for k, v in r.items()} for r in ranges],
+    })
+    print(f"  detalhes em {out}")
+
+
+if __name__ == "__main__":
+    main()

package/editor/helpers/voz_check.py

@@ -0,0 +1,386 @@
+"""Saturação e eco de sala na voz de cada vídeo, medidos na onda (sem ouvir). O noise_check.py chama este.
+
+Saturação (a voz bateu no teto do microfone ou do arquivo). Lido no áudio original, na taxa dele, canal a canal,
+de uma vez só:
+  - amontoado no teto: teto = o nível que só 0,1% das amostras da fala passa; conta quanto da fala fica a menos de
+    1 dB dele contra quanto fica de 3 a 4 dB abaixo. Voz natural rareia perto do topo (fica abaixo de 0,5) e um
+    limitador bem forte chega a uns 0,7; voz que bateu no teto se espreme nele (2 ou mais), mesmo quando o volume
+    foi abaixado depois e o arquivo não chega a 0 dBFS;
+  - platôs: 4 ou mais amostras seguidas exatamente iguais longe do zero (corte digital em arquivo sem compressão);
+  - acima de 0 dBFS: o AAC de um áudio cortado no teto devolve amostras acima de 1,0 (uma voz alta e limpa passa
+    em um ou dois pontos; dez pontos ou mais é corte);
+  - momentos no teto: janelas de 10 ms a menos de 1 dB do teto, juntadas quando estão a menos de 50 ms (os tempos
+    para ouvir).
+  Diagnóstico: "saturada", "possível" (ouça os tempos listados antes de afirmar) ou "ok".
+
+Eco de sala (a voz continua soando na sala depois que a pessoa para). Duas medidas:
+  - cauda nas pausas: em cada fim de frase seguido de 0,25 s de pausa, a queda do volume (banda da voz, janelas de
+    5 ms) é ajustada numa reta entre 5 dB e 25 dB abaixo do fim da fala (ou até 5 dB do chão de ruído), como um
+    tempo de reverberação: quanto tempo a voz levaria para cair 60 dB. Voz perto do microfone cai em menos de
+    0,25 s; sala vazia e parede lisa passam de 0,4 s. Mediana dos fins de frase (pelo menos 3, com 15 dB de folga
+    acima do ruído);
+  - repetição: o cepstro médio dos trechos com fala (janelas de 1 s) mostra um pico quando o som volta igual
+    depois de 35 a 500 ms (parede longe, sala grande, eco de caixa). Pico 60 vezes acima da variação normal conta.
+  Diagnóstico: "forte" (cauda de 0,6 s ou mais, ou repetição muito marcada), "leve" (cauda de 0,4 a 0,6 s, ou
+  repetição), "não" ou "não deu para medir".
+
+Os números são medida, não escuta: diga "medi" e, para decidir o tratamento, ouça os tempos listados.
+
+Uso:
+    uv run python helpers/voz_check.py <video ou áudio> [...] [--json]
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import subprocess
+import sys
+from pathlib import Path
+
+import numpy as np
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from common import probe_video, require_binary  # noqa: E402
+
+WIN_S = 0.010
+NEAR_PEAK_DB = 1.0
+MOMENT_GAP_S = 0.05
+PLATEAU_RUN = 4               # amostras iguais seguidas
+PLATEAU_MIN = 0.1             # longe do zero (silêncio digital também é "igual")
+LOUD_BELOW_DB = 20.0          # janelas de fala: até 20 dB abaixo da fala forte
+HIST_LO_DB, HIST_HI_DB, HIST_STEP = -40.0, 6.0, 0.25
+RMS_LO_DB, RMS_HI_DB = -100.0, 10.0
+TOP_SHARE = 0.001             # teto = nível que só 0,1% das amostras da fala passa
+SAT_PILEUP = 1.5              # medido: voz limpa 0,35; limitador forte 0,7; saturada (mesmo abaixada) 2,3 a 6
+MAYBE_PILEUP = 1.0
+PLATEAU_EVENTS = 20
+MAYBE_PLATEAUS = 3
+OVER_EVENTS = 10              # o AAC de uma voz alta e limpa passa de 0 dBFS em um ou dois pontos
+MAYBE_OVER = 4
+ECHO_SR = 16000
+ECHO_HOP_S = 0.005
+ECHO_PAUSE_S = 0.25
+ECHO_MIN_RANGE_DB = 15.0
+ECHO_MIN_OFFSETS = 3
+ECHO_LEVE_S = 0.40
+ECHO_FORTE_S = 0.60
+CEPS_N = 16384                # 1 s a 16 kHz
+CEPS_HOP = 4096
+CEPS_RANGE_S = (0.035, 0.5)   # abaixo de 35 ms mora a altura da voz e os harmônicos dela
+CEPS_BASE_S = 0.02
+CEPS_REPEAT_Z = 60.0
+CEPS_STRONG_Z = 250.0
+
+
+def utf8_console() -> None:
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[attr-defined]
+        except (AttributeError, ValueError, OSError):
+            pass
+
+
+def fmt_t(t: float) -> str:
+    m, s = divmod(max(0.0, t), 60)
+    return f"{int(m)}:{s:04.1f}"
+
+
+# ------------------------------------------------------------------ saturação
+
+
+def measure_clipping(path: Path, info: dict) -> dict:
+    sr = int(info.get("sample_rate") or 48000)
+    ch = max(1, int(info.get("audio_channels") or 1))
+    w = max(1, int(round(sr * WIN_S)))
+    cmd = ["ffmpeg", "-v", "error", "-nostdin", "-i", str(path), "-vn", "-map", "0:a:0", "-f", "f32le", "-"]
+    proc = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    assert proc.stdout is not None
+    nb = int((HIST_HI_DB - HIST_LO_DB) / HIST_STEP)
+    nr = int(RMS_HI_DB - RMS_LO_DB)
+    # amostras por nível da amostra (0,25 dB) e pelo volume da janela de 10 ms em que ela está (1 dB): no fim só
+    # as janelas de fala contam, sem ler o arquivo duas vezes
+    hist = np.zeros((nr, nb), dtype=np.int64)
+    per_rms = np.zeros(nr, dtype=np.int64)
+    win_max: list[np.ndarray] = []
+    plateaus = over = 0
+    over_windows: list[int] = []
+    frame_bytes = w * ch * 4
+    rest = b""
+    done = 0
+    while True:
+        chunk = proc.stdout.read(frame_bytes * 1000)
+        if not chunk:
+            break
+        data = rest + chunk
+        usable = len(data) - len(data) % frame_bytes
+        rest = data[usable:]
+        if not usable:
+            continue
+        x = np.frombuffer(data[:usable], dtype=np.float32).reshape(-1, ch)
+        per = np.abs(x).astype(np.float64).reshape(-1, w * ch)
+        win_max.append(per.max(axis=1))
+        rb = np.clip((20 * np.log10(np.sqrt((per ** 2).mean(axis=1)) + 1e-12) - RMS_LO_DB).astype(np.int64), 0, nr - 1)
+        per_rms += np.bincount(rb, minlength=nr) * w * ch
+        rows, cols = np.nonzero(per > 10 ** (HIST_LO_DB / 20))
+        if rows.size:
+            idx = np.clip(((20 * np.log10(per[rows, cols]) - HIST_LO_DB) / HIST_STEP).astype(np.int64), 0, nb - 1)
+            np.add.at(hist, (rb[rows], idx), 1)
+        above = per > 1.0
+        if above.any():
+            over += int(above.sum())
+            over_windows += list(np.flatnonzero(above.any(axis=1)) + done)
+        for c in range(ch):
+            col = x[:, c]
+            eq = (np.diff(col) == 0) & (np.abs(col[1:]) >= PLATEAU_MIN)
+            if eq.any():
+                d = np.diff(np.concatenate([[0], eq.astype(np.int8), [0]]))
+                starts, ends = np.flatnonzero(d == 1), np.flatnonzero(d == -1)
+                plateaus += int(((ends - starts) >= PLATEAU_RUN - 1).sum())
+        done += per.shape[0]
+    err = proc.stderr.read().decode("utf-8", "replace") if proc.stderr else ""
+    proc.wait()
+    if proc.returncode != 0 or not win_max:
+        return {"error": f"não consegui ler o áudio: {err.strip()[-200:]}"}
+    wmax = np.concatenate(win_max)
+    peak = float(wmax.max())
+    if peak <= 1e-6:
+        return {"error": "áudio mudo"}
+    peak_db = 20 * math.log10(peak)
+    # janelas de fala: até LOUD_BELOW_DB abaixo da fala forte (percentil 95 do volume das janelas)
+    cum = np.cumsum(per_rms)
+    loud_bin = int(np.searchsorted(cum, 0.95 * cum[-1]))
+    first = max(0, loud_bin - int(LOUD_BELOW_DB))
+    h = hist[first:].sum(axis=0)
+    speech_samples = int(per_rms[first:].sum())
+    # teto: o nível que só 0,1% das amostras da fala passa
+    from_top = np.cumsum(h[::-1])
+    k_top = nb - 1 - int(np.searchsorted(from_top, TOP_SHARE * speech_samples))
+    ceil_db = HIST_LO_DB + (k_top + 1) * HIST_STEP
+    step = int(round(1.0 / HIST_STEP))
+    near = int(h[max(0, k_top + 1 - step):].sum())
+    band = int(h[max(0, k_top + 1 - 4 * step): max(0, k_top + 1 - 3 * step)].sum())
+    pileup = near / max(1, band)
+    fraction = near / max(1, speech_samples)
+    hot = np.flatnonzero(20 * np.log10(wmax + 1e-12) >= ceil_db - NEAR_PEAK_DB)
+    moments: list[list[int]] = []
+    gap = int(round(MOMENT_GAP_S / WIN_S))
+    for i in hot:
+        if moments and i - moments[-1][1] <= gap:
+            moments[-1][1] = int(i)
+        else:
+            moments.append([int(i), int(i)])
+    over_moments = 0
+    last = -10 ** 9
+    for i in over_windows:
+        if i - last > gap:
+            over_moments += 1
+        last = i
+    if plateaus >= PLATEAU_EVENTS or over_moments >= OVER_EVENTS or pileup >= SAT_PILEUP:
+        level = "saturada"
+    elif plateaus >= MAYBE_PLATEAUS or over_moments >= MAYBE_OVER or pileup >= MAYBE_PILEUP:
+        level = "possivel"
+    else:
+        level = "ok"
+    return {"level": level, "peak_dbfs": round(peak_db, 2), "ceiling_dbfs": round(ceil_db, 2),
+            "pileup": round(pileup, 2), "near_ceiling_fraction": round(fraction, 5), "moments": len(moments),
+            "moment_times": [round(a * WIN_S, 2) for a, _ in moments][:12], "plateaus": plateaus,
+            "over_full_scale": over, "over_moments": over_moments,
+            "speech_s": round(speech_samples / ch / sr, 2)}
+
+
+# ------------------------------------------------------------------ eco
+
+
+def echo_envelope(path: Path) -> np.ndarray:
+    """dB em janelas de 5 ms da banda da voz (200 Hz a 5 kHz), mono a 16 kHz."""
+    cmd = ["ffmpeg", "-v", "error", "-nostdin", "-i", str(path), "-vn", "-map", "0:a:0", "-af",
+           f"aresample={ECHO_SR}:async=1:first_pts=0,highpass=f=200,lowpass=f=5000", "-ac", "1", "-f", "f32le", "-"]
+    raw = subprocess.run(cmd, capture_output=True).stdout
+    x = np.frombuffer(raw, dtype=np.float32).astype(np.float64)
+    w = int(ECHO_SR * ECHO_HOP_S)
+    n = len(x) // w
+    if n == 0:
+        return np.zeros(0)
+    return 10 * np.log10((x[: n * w].reshape(n, w) ** 2).mean(axis=1) + 1e-12)
+
+
+def repetition(path: Path) -> dict | None:
+    """Pico do cepstro médio da fala entre 35 e 500 ms: o som que volta igual depois de um tempo."""
+    raw = subprocess.run(["ffmpeg", "-v", "error", "-nostdin", "-i", str(path), "-vn", "-map", "0:a:0", "-af",
+                          f"aresample={ECHO_SR}", "-ac", "1", "-f", "f32le", "-"], capture_output=True).stdout
+    x = np.frombuffer(raw, dtype=np.float32).astype(np.float64)
+    starts = list(range(0, len(x) - CEPS_N, CEPS_HOP))
+    if len(starts) < 4:
+        return None
+    rms_db = np.array([10 * math.log10(float(np.mean(x[i:i + CEPS_N] ** 2)) + 1e-12) for i in starts])
+    loud = float(np.percentile(rms_db, 90))
+    win = np.hanning(CEPS_N)
+    acc = np.zeros(CEPS_N // 2)
+    used = 0
+    for i, level in zip(starts, rms_db):
+        if level < loud - 15:
+            continue
+        spec = np.abs(np.fft.rfft(x[i:i + CEPS_N] * win)) ** 2
+        acc += np.fft.irfft(np.log(spec + 1e-10))[: CEPS_N // 2]
+        used += 1
+    if used < 3:
+        return None
+    c = acc / used
+    lo, hi = int(CEPS_RANGE_S[0] * ECHO_SR), int(CEPS_RANGE_S[1] * ECHO_SR)
+    half = int(CEPS_BASE_S * ECHO_SR) // 2
+    seg = c[lo - half: hi + half]
+    base = np.array([np.median(seg[k - half: k + half + 1]) for k in range(half, len(seg) - half)])
+    r = c[lo:hi] - base
+    mad = float(np.median(np.abs(r))) + 1e-12
+    z = r / mad
+    k = int(np.argmax(z))
+    return {"z": round(float(z[k]), 1), "atraso_s": round((lo + k) / ECHO_SR, 3), "janelas": used}
+
+
+def measure_echo(path: Path) -> dict:
+    rep_ = repetition(path)
+    res = measure_tail(path)
+    if rep_ is not None:
+        res["repeticao"] = rep_
+        if rep_["z"] >= CEPS_REPEAT_Z:
+            strong = rep_["z"] >= CEPS_STRONG_Z
+            if res["level"] in ("sem_medida", "nao") or (strong and res["level"] == "leve"):
+                res["level"] = "forte" if strong else "leve"
+            res["por"] = "repeticao" if "rt60_s" not in res or res["rt60_s"] < ECHO_LEVE_S else "cauda_e_repeticao"
+    return res
+
+
+def measure_tail(path: Path) -> dict:
+    env = echo_envelope(path)
+    if env.size < int(2.0 / ECHO_HOP_S):
+        return {"level": "sem_medida", "why": "áudio curto demais"}
+    floor = float(np.percentile(env, 10))
+    loud = float(np.percentile(env, 95))
+    speech_th = max(floor + 15.0, loud - 25.0)
+    pause_n = int(round(ECHO_PAUSE_S / ECHO_HOP_S))
+    look = int(round(0.6 / ECHO_HOP_S))
+    is_speech = env >= speech_th
+    rows = []
+    i = 0
+    n = len(env)
+    while i < n - pause_n:
+        # último quadro de fala seguido de pausa (nada de fala por ECHO_PAUSE_S)
+        if is_speech[i] and not is_speech[i + 1: i + 1 + pause_n].any():
+            lo = max(0, i - 10)
+            top = lo + int(np.argmax(env[lo: i + 1]))
+            l0 = float(env[top])
+            stop_db = max(l0 - 25.0, floor + 5.0)
+            if l0 - stop_db >= ECHO_MIN_RANGE_DB:
+                seg = env[top: min(n, top + look)]
+                below5 = np.flatnonzero(seg <= l0 - 5.0)
+                below_end = np.flatnonzero(seg <= stop_db)
+                if below5.size and below_end.size and below_end[0] > below5[0] + 1:
+                    a, b = int(below5[0]), int(below_end[0])
+                    t = np.arange(a, b + 1) * ECHO_HOP_S
+                    slope = float(np.polyfit(t, seg[a: b + 1], 1)[0])
+                    if slope < -1.0:
+                        rows.append({"em": round((top) * ECHO_HOP_S, 2), "rt60": round(min(5.0, 60.0 / -slope), 3),
+                                     "queda_db": round(l0 - stop_db, 1)})
+            i += pause_n
+            continue
+        i += 1
+    if len(rows) < ECHO_MIN_OFFSETS:
+        why = ("ruído alto demais perto da voz" if loud - floor < ECHO_MIN_RANGE_DB + 10
+               else f"só {len(rows)} fim(ns) de frase com pausa para medir")
+        return {"level": "sem_medida", "why": why, "offsets": len(rows), "floor_db": round(floor, 1)}
+    rt = float(np.median([r["rt60"] for r in rows]))
+    level = "forte" if rt >= ECHO_FORTE_S else "leve" if rt >= ECHO_LEVE_S else "nao"
+    worst = sorted(rows, key=lambda r: -r["rt60"])[:5]
+    return {"level": level, "rt60_s": round(rt, 3), "offsets": len(rows),
+            "worst_times": [r["em"] for r in worst], "floor_db": round(floor, 1)}
+
+
+# ------------------------------------------------------------------ juntos
+
+
+def measure_voice(path: Path) -> dict:
+    try:
+        info = probe_video(path)
+    except Exception as exc:  # noqa: BLE001
+        return {"error": f"não consegui ler: {exc}"}
+    if not info.get("has_audio"):
+        return {"error": "sem áudio"}
+    return {"saturacao": measure_clipping(path, info), "eco": measure_echo(path)}
+
+
+def clip_text(c: dict) -> str:
+    if c.get("error"):
+        return f"saturação: {c['error']}"
+    when = ", ".join(fmt_t(t) for t in c.get("moment_times", [])[:6])
+    extra = []
+    if c["pileup"] >= MAYBE_PILEUP:
+        extra.append(f"{c['near_ceiling_fraction']:.1%} da fala espremida no teto")
+    if c["plateaus"]:
+        extra.append(f"{c['plateaus']} platôs")
+    if c["over_moments"]:
+        extra.append(f"passou de 0 dBFS em {c['over_moments']} pontos")
+    more = f" ({', '.join(extra)})" if extra else ""
+    if c["level"] == "saturada":
+        return (f"voz SATURADA em {c['moments']} momentos ({when}...){more}. Não se recupera por inteiro: dá para "
+                "suavizar, não para desfazer. Se der, grave de novo com o microfone mais longe ou o ganho mais baixo")
+    if c["level"] == "possivel":
+        return f"possível saturação{more}: ouça {when} antes de dizer que saturou"
+    return f"sem saturação (pico {c['peak_dbfs']:.1f} dBFS)"
+
+
+def echo_text(e: dict) -> str:
+    if e.get("error"):
+        return ""
+    rt = str(round(e["rt60_s"], 2)).replace(".", ",") if "rt60_s" in e else None
+    if e["level"] == "sem_medida":
+        return f"eco não medido ({e['why']})"
+    if e["level"] == "nao":
+        return f"sem eco de sala (a voz some em {rt} s nas pausas)"
+    what = "eco de sala forte" if e["level"] == "forte" else "eco de sala leve"
+    parts = []
+    if rt and e["rt60_s"] >= ECHO_LEVE_S:
+        when = ", ".join(fmt_t(t) for t in e.get("worst_times", [])[:4])
+        parts.append(f"a voz leva uns {rt} s para sumir nas pausas (ouça em {when})")
+    rp = e.get("repeticao") or {}
+    if rp.get("z", 0) >= CEPS_REPEAT_Z:
+        parts.append(f"o som volta repetido uns {round(rp['atraso_s'] * 1000)} ms depois")
+    return (f"{what}: {'; '.join(parts)}. Trate leve e compare antes e depois no mesmo volume percebido "
+            "(references/revisao.md, Voz)")
+
+
+def line_for(name: str, r: dict) -> str:
+    if r.get("error"):
+        return f"  {name}: {r['error']}"
+    parts = [clip_text(r["saturacao"]), echo_text(r["eco"])]
+    return f"  {name} · " + " · ".join(p for p in parts if p)
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="Mede saturação e eco de sala na voz de cada vídeo.")
+    ap.add_argument("paths", nargs="+", type=Path, help="vídeos ou áudios")
+    ap.add_argument("--json", action="store_true", help="imprime o JSON")
+    args = ap.parse_args()
+    utf8_console()
+    require_binary("ffmpeg")
+    require_binary("ffprobe")
+    out = {}
+    for p in args.paths:
+        p = p.expanduser().absolute()
+        if not p.is_file():
+            print(f"erro: não encontrado: {p}", file=sys.stderr)
+            return 2
+        key = p.stem if p.stem not in out and not any(q != p and q.stem == p.stem for q in args.paths) else p.name
+        out[key] = measure_voice(p)
+    if args.json:
+        print(json.dumps(out, ensure_ascii=False, indent=2))
+        return 0
+    print("Voz (saturação e eco de sala, medidos na onda):")
+    for name, r in out.items():
+        print(line_for(name, r))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())