ffmpeg-skill 1.17.2 → 1.18.0

package/scripts/_contract.py

@@ -411,11 +411,16 @@ def output_schema(name: str, meta: Dict[str, Any]) -> Dict[str, Any]:
         extra = {"audiogram": {"type": "object", "description": "{style, background ('image' or 'color'), image, position, vis_height, platform, captions, title, stages, verified} -- present on every run, so a plain waveform answers background 'color' (1.16)"},
                  "notes": {"type": "array", "items": {"type": "string"}}}
     elif name == "scenes":
-        extra = {"file": {"type": "string"}, "duration": {"type": "number"}, "scene_count": {"type": "integer"}, "scenes": {"type": "array"}, "audio_peaks": {"type": "array"}}
+        extra = {"file": {"type": "string"}, "duration": {"type": "number"}, "scene_count": {"type": "integer"}, "scenes": {"type": "array"}, "audio_peaks": {"type": "array"},
+                 "shots": {"type": "array", "description": "--shots (1.18): [{start, end, label, flow_magnitude}]"},
+                 "audio_peaks_db": {"type": "array", "description": "--audio-peaks (1.18): [{time, level}] measured dBFS, distinct from audio_peaks above"},
+                 "speech": {"type": "array", "description": "--speech (1.18): [{time, speech_music_ratio}]"}}
     elif name == "silence":
-        extra = {"silences": {"type": "array"}, "keep": {"type": "array"}, "input_duration": {"type": "number"}, "kept_duration": {"type": "number"}, "removed_seconds": {"type": "number"}}
+        extra = {"silences": {"type": "array"}, "keep": {"type": "array"}, "input_duration": {"type": "number"}, "kept_duration": {"type": "number"}, "removed_seconds": {"type": "number"},
+                 "speech_aware": {"type": "object", "description": "--speech-aware (1.18): {min_silence, floor, breaths_kept, breaths_kept_seconds, breaths}"}}
     elif name == "sync":
-        extra = {"reference": {"type": "string"}, "second": {"type": "string"}, "offset_seconds": {"type": "number"}, "confidence": {"type": "number"}, "meaning": {"type": "string"}, "drift": {"type": "object"}}
+        extra = {"reference": {"type": "string"}, "second": {"type": "string"}, "offset_seconds": {"type": "number"}, "confidence": {"type": "number"}, "meaning": {"type": "string"}, "drift": {"type": "object"},
+                 "sources": {"type": "array", "description": "1.18: [{path, offset_s, confidence, drift_ppm}], one per SOURCE; the only per-source shape once more than one SOURCE is given"}}
     elif name == "look":
         extra = {"outputs": {"type": "array", "items": {"type": "string"}}}
     elif name == "render":

package/scripts/cropdetect.py

@@ -33,7 +33,10 @@ import sys
 from collections import Counter
 from typing import Dict, List, Tuple
 
-from _common import add_common, apply_common, die, emit, info, print_json, probe, require_tool, run_analysis
+from _common import add_common, apply_common, die, emit, info, print_json, probe, require_tool, run_analysis, decode_gray_frames, frame_flow
+
+MOTION_CENTRE_FPS = 2.0
+MOTION_CENTRE_W, MOTION_CENTRE_H = 64, 36
 
 CROP_RE = re.compile(r"crop=(\d+):(\d+):(\d+):(\d+)")
 
@@ -61,6 +64,52 @@ def detect(path: str, seconds: float, samples: int, limit: float, round_to: int,
     return rects
 
 
+def motion_centre(path: str, seconds: float, samples: int, duration: float, sw: int, sh: int) -> List[Dict]:
+    """Per-second motion centroid: {time, x, y, x_frac, y_frac} -- a report-only measurement,
+    the same sampled-window approach as detect() above. x/y are pixel coordinates in the SOURCE
+    frame (consistent with the --round crop rectangle this tool already reports in source
+    pixels); x_frac/y_frac are the same position as a 0..1 fraction of source_width/height, for a
+    caller that wants to reframe without first knowing the source size. This never picks a
+    subject -- it reports where in the frame the measured pixel motion was concentrated, which is
+    not the same thing as where the interesting subject is (a moving background behind a still
+    speaker centres the motion on the background)."""
+    per_window = max(0.5, seconds / max(1, samples))
+    cell = 8  # NxN diff grid at decode resolution
+    cw, ch = MOTION_CENTRE_W / cell, MOTION_CENTRE_H / cell
+    out: List[Dict] = []
+    for i in range(samples):
+        start = 0.0 if duration <= 0 else (duration - per_window) * i / max(1, samples - 1) if samples > 1 else 0.0
+        start = max(0.0, start)
+        frames = decode_gray_frames(path, MOTION_CENTRE_FPS, MOTION_CENTRE_W, MOTION_CENTRE_H,
+                                     start=start, seconds=per_window, check=False)
+        for k in range(len(frames) - 1):
+            prev, cur = frames[k], frames[k + 1]
+            wsum = wx = wy = 0.0
+            for gy in range(cell):
+                for gx in range(cell):
+                    x0, x1 = int(gx * cw), int((gx + 1) * cw)
+                    y0, y1 = int(gy * ch), int((gy + 1) * ch)
+                    diff = 0
+                    for y in range(y0, y1):
+                        row = y * MOTION_CENTRE_W
+                        for x in range(x0, x1):
+                            diff += abs(prev[row + x] - cur[row + x])
+                    cx = (gx + 0.5) / cell
+                    cy = (gy + 0.5) / cell
+                    wsum += diff
+                    wx += diff * cx
+                    wy += diff * cy
+            t = start + (k + 1) / MOTION_CENTRE_FPS
+            if wsum <= 0:
+                out.append({"time": round(t, 2), "x": None, "y": None, "x_frac": None, "y_frac": None, "motion": 0.0})
+                continue
+            xf, yf = wx / wsum, wy / wsum
+            out.append({"time": round(t, 2), "x": round(xf * sw), "y": round(yf * sh),
+                        "x_frac": round(xf, 3), "y_frac": round(yf, 3), "motion": round(wsum / (MOTION_CENTRE_W * MOTION_CENTRE_H), 2)})
+    out.sort(key=lambda r: r["time"])
+    return out
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input")
@@ -68,6 +117,10 @@ def main() -> int:
     ap.add_argument("--samples", type=int, default=5, help="number of windows spread across the file (default 5)")
     ap.add_argument("--limit", type=float, default=0.0941176, help="black-pixel threshold, 0..1 (default ~0.094, cropdetect's own default)")
     ap.add_argument("--round", type=int, default=16, dest="round_to", help="the reported width/height are rounded to a multiple of this (default 16)")
+    ap.add_argument("--motion-centre", action="store_true",
+                    help="report the motion centroid per second, sampled the same way as the crop "
+                         "detection above (report only -- this tool never picks a reframe, it hands "
+                         "the calling agent numbers to reframe with)")
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)
@@ -102,6 +155,11 @@ def main() -> int:
             info(f"detected crop={w}:{h}:{x}:{y} (source {sw}x{sh}, confidence {result['confidence']:.0%}) -- "
                  f"crop.py {args.input} --x {x} --y {y} --width {w} --height {h}")
 
+    if args.motion_centre:
+        centre = motion_centre(args.input, args.seconds, args.samples, duration, sw, sh)
+        result["motion_centre"] = centre
+        info(f"--motion-centre: {len(centre)} measured points")
+
     if args.json:
         emit(None, **result)
     else:

package/scripts/multicam.py

@@ -26,12 +26,16 @@ Examples:
   python3 multicam.py camA.mp4 camB.mp4 --auto 8 -o edit.mp4              # alternate cameras every 8 s
 """
 import argparse
+import math
 import sys
-from typing import List, Tuple
+from typing import Dict, List, Tuple
 
-from _common import video_args, aac_args, add_common, apply_common, default_output, die, emit, ffmpeg_base, info, time_arg, probe, run, x264_args, X264_PRESETS, fmt_secs
+from _common import video_args, aac_args, add_common, apply_common, default_output, die, emit, ffmpeg_base, info, time_arg, probe, run, x264_args, X264_PRESETS, fmt_secs, decode_pcm_mono, rms_envelope, STATE
 from sync import measure_offset
 
+ENERGY_WINDOW_S = 0.25  # --switch energy: loudness measured over this window on the reference timeline
+ENERGY_RATE = 8000      # decode rate for the per-camera loudness envelope
+
 
 def parse_switch(spec: str, n: int) -> List[Tuple[float, float, int]]:
     out = []
@@ -55,12 +59,75 @@ def parse_switch(spec: str, n: int) -> List[Tuple[float, float, int]]:
     return out
 
 
+def energy_switch(inputs: List[str], metas: List["Dict"], offsets: List[float], ratios: List[float],
+                  ref_dur: float, min_shot: float, window_s: float = ENERGY_WINDOW_S) -> List[Tuple[float, float, int]]:
+    """Auto-switch cuts: at every `window_s` step on the reference timeline, cut to whichever
+    camera (of those WITH video) measures the loudest audio at that moment, then merge the
+    winners into runs and fold any run shorter than `min_shot` into its neighbour. This is a
+    measured loudest-camera pick, the same spirit as scenes.py --rank-by audio: it is a proxy for
+    "who is talking", not a judgement -- a loud crowd or a camera with a hot mic wins over a
+    quiet subject exactly like scenes.py's own audio ranking does."""
+    candidates = [c for c, m in enumerate(metas) if m.get("video")]
+    if not candidates:
+        die("no input has video; --switch energy needs at least one camera with a picture")
+    envs: "Dict[int, List[float]]" = {}
+    step = max(1, int(ENERGY_RATE * window_s))
+    for c in candidates:
+        samples = decode_pcm_mono(inputs[c], ENERGY_RATE, check=False)
+        envs[c] = rms_envelope(samples, step) if samples else []
+    n_windows = max(1, int(math.ceil(ref_dur / window_s)))
+    winners: List[int] = []
+    for i in range(n_windows):
+        t = i * window_s
+        best_c, best_v = candidates[0], -1.0
+        for c in candidates:
+            src_t = (t - offsets[c]) * ratios[c]
+            idx = int(src_t / window_s)
+            env = envs[c]
+            val = env[idx] if 0 <= idx < len(env) else -1.0
+            if val > best_v:
+                best_v, best_c = val, c
+        winners.append(best_c)
+    # collapse into runs
+    runs: List[List] = []
+    for i, c in enumerate(winners):
+        t0, t1 = i * window_s, min(ref_dur, (i + 1) * window_s)
+        if runs and runs[-1][2] == c:
+            runs[-1][1] = t1
+        else:
+            runs.append([t0, t1, c])
+    # fold a run shorter than min_shot into its neighbour: the next run if there is one, else the
+    # previous one -- a single pass is enough because folding only ever lengthens a run, and a
+    # run just extended is re-checked on the next iteration through the while loop.
+    changed = True
+    while changed and len(runs) > 1:
+        changed = False
+        for i, r in enumerate(runs):
+            if r[1] - r[0] < min_shot:
+                if i + 1 < len(runs):
+                    runs[i + 1][0] = r[0]
+                else:
+                    runs[i - 1][1] = r[1]
+                del runs[i]
+                changed = True
+                break
+    return [(s, e, c) for s, e, c in runs]
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("inputs", nargs="+", help="reference camera first, then other cameras / recorders")
     ap.add_argument("-o", "--output", help="output file (default: <reference>_multicam.mp4)")
-    ap.add_argument("--switch", help="switch list START-END:CAM,... on the reference timeline")
+    ap.add_argument("--switch", help="switch list START-END:CAM,... on the reference timeline, or "
+                                     "the literal 'energy' to auto-switch to whichever camera is "
+                                     "loudest at each moment (respecting --min-shot)")
     ap.add_argument("--auto", type=float, help="no switch list: alternate through the cameras every N seconds")
+    ap.add_argument("--min-shot", type=float, default=1.5,
+                    help="--switch energy: never cut to a new camera for less than this many "
+                         "seconds (default 1.5)")
+    ap.add_argument("--edl", help="write the resulting cut list to this file, one START-END per line "
+                                  "(cut.py --segments format); the camera index for each cut is in "
+                                  "the JSON `cuts` field alongside it")
     ap.add_argument("--audio", type=int, default=0, help="input index to take audio from (default 0 = reference)")
     ap.add_argument("--offsets-only", action="store_true", help="print the measured offsets and exit")
     ap.add_argument("--max-offset", type=float, default=30.0)
@@ -137,8 +204,13 @@ def main() -> int:
                 print(f"{p}: {o:+.3f}s (confidence {c:.2f})")
         return 0
 
+    if args.min_shot <= 0:
+        die(f"--min-shot must be positive, got {args.min_shot:g}")
     ref_dur = metas[0]["duration"] or 0.0
-    if args.switch:
+    energy_mode = args.switch == "energy"
+    if energy_mode:
+        cuts = energy_switch(args.inputs, metas, offsets, ratios, ref_dur, args.min_shot)
+    elif args.switch:
         cuts = parse_switch(args.switch, n)
     elif args.auto:
         if args.auto <= 0:
@@ -167,6 +239,13 @@ def main() -> int:
         if not metas[c].get("video"):
             die(f"camera {c} ({args.inputs[c]}) has no video; it can only be used with --audio")
 
+    if args.edl:
+        if not STATE.dry_run:
+            with open(args.edl, "w", encoding="utf-8") as fh:
+                for s, e, _c in filled:
+                    fh.write(f"{s:.3f}-{e:.3f}\n")
+        info(f"wrote {args.edl}")
+
     v0 = metas[0]["video"]
     w, h = args.width or v0["width"], args.height or v0["height"]
     if v0.get("rotation") in (90, -90, 270, -270) and not (args.width or args.height):
@@ -212,7 +291,8 @@ def main() -> int:
     run(cmd)
     r = probe(output, role="output")
     info(f"wrote {output} ({fmt_secs(r['duration'])}, {len(filled)} cuts, audio from input {a})")
-    emit(output, cuts=[[round(s, 3), round(e, 3), c] for s, e, c in filled], **report)
+    extra = {"switch_mode": "energy", "min_shot": args.min_shot} if energy_mode else {}
+    emit(output, cuts=[[round(s, 3), round(e, 3), c] for s, e, c in filled], **report, **extra)
     return 0
 
 

package/scripts/scenes.py

@@ -25,7 +25,11 @@ from typing import Dict, List, Optional, Tuple
 # `detect_scenes` moved into _common/probe.py in 1.16.0 (see silence.py); the body is unchanged.
 from _common import (detect_scenes, STATE, add_common, apply_common, beat_grid, default_font_file, die, emit,
                      escape_filter_path, ffmpeg_base, info, print_json, probe, run, decode_pcm_mono,
-                     rms_envelope, BEAT_MIN_CONFIDENCE)
+                     rms_envelope, BEAT_MIN_CONFIDENCE, decode_gray_frames, frame_flow, label_shot_flow)
+
+SHOT_FPS = 4.0          # frames/second sampled for --shots' flow estimate
+SHOT_W, SHOT_H = 48, 27  # decode size for --shots (16:9-ish; enough blocks, still a few KB/shot)
+SPEECH_STEP_S = 1.0      # --speech energy-ratio window
 
 
 
@@ -54,6 +58,51 @@ def parse_beat_range(text: str) -> "tuple":
     return (lo, hi)
 
 
+def shot_flow_label(path: str, start: float, end: float) -> Dict:
+    """{start, end, label, flow_magnitude} for one shot: decode it at SHOT_FPS/SHOT_W x SHOT_H
+    and block-match consecutive frames (see _common.decision.frame_flow / label_shot_flow). A
+    shot under two sampled frames has nothing to compare and is reported static with
+    flow_magnitude 0 -- there is no motion measurement to make on a single frame."""
+    frames = decode_gray_frames(path, SHOT_FPS, SHOT_W, SHOT_H, start=start, seconds=max(0.0, end - start), check=False)
+    flows = [frame_flow(frames[i], frames[i + 1], SHOT_W, SHOT_H) for i in range(len(frames) - 1)]
+    label = label_shot_flow(flows)
+    return {"start": round(start, 3), "end": round(end, 3), "label": label["label"], "flow_magnitude": label["flow_magnitude"]}
+
+
+def audio_peaks_db(samples: "List[float]", rate: int, step_s: float = 0.25) -> List[Dict]:
+    """--audio-peaks: local maxima of the loudness envelope reported as measured dBFS, not the
+    unitless RMS scenes.py has always put in the (unconditional) `audio_peaks` key -- a
+    different unit needs a different key so the existing one keeps meaning what it always has."""
+    env = rms_envelope(samples, int(rate * step_s))
+    peaks = []
+    for i, val in enumerate(env):
+        if val <= 1e-6:
+            continue
+        if (i == 0 or env[i - 1] <= val) and (i == len(env) - 1 or env[i + 1] <= val):
+            level = round(20 * math.log10(val), 1)
+            peaks.append({"time": round(i * step_s, 2), "level": level})
+    return peaks
+
+
+def speech_music_ratio(samples: "List[float]", rate: int, step_s: float = SPEECH_STEP_S) -> List[Dict]:
+    """--speech: a per-second zero-crossing-rate ratio, reported as a measured number, not a
+    speech/music label. Speech's rapid consonant transients drive the zero-crossing rate up and
+    make it jump window to window; sustained tones (music, a held note, room tone) cross zero at
+    a steadier rate. ratio = this window's ZCR / the file's median ZCR, so 1.0 is "typical for
+    this file" regardless of its overall noisiness -- a proxy, in the same spirit as scenes.py's
+    --rank-by, not a classifier: nothing here decides what is speech."""
+    step = max(1, int(rate * step_s))
+    zcrs: List[float] = []
+    for i in range(0, len(samples) - step + 1, step):
+        block = samples[i:i + step]
+        crossings = sum(1 for a, b in zip(block, block[1:]) if (a >= 0) != (b >= 0))
+        zcrs.append(crossings / max(1, len(block) - 1))
+    if not zcrs:
+        return []
+    med = sorted(zcrs)[len(zcrs) // 2] or 1e-9
+    return [{"time": round(i * step_s, 2), "speech_music_ratio": round(z / med, 3)} for i, z in enumerate(zcrs)]
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input")
@@ -76,6 +125,15 @@ def main() -> int:
     ap.add_argument("--min-confidence", type=float, default=BEAT_MIN_CONFIDENCE,
                     help="with --beats: below this confidence the grid is still reported, marked "
                          f"usable: false (default {BEAT_MIN_CONFIDENCE})")
+    ap.add_argument("--shots", action="store_true",
+                    help="label each detected shot static / pan / motion by a measured optical-flow "
+                         "proxy (lightweight block matching over sampled frames); reports flow_magnitude too")
+    ap.add_argument("--audio-peaks", action="store_true",
+                    help="report loudness peaks as {time, level} in measured dBFS (separate from the "
+                         "always-on `audio_peaks` RMS list used to pick --highlights)")
+    ap.add_argument("--speech", action="store_true",
+                    help="report a per-second speech-vs-music energy ratio (zero-crossing-rate proxy, "
+                         "a measurement, not a speech/music classification)")
     ap.add_argument("--sheet", help="write a contact sheet PNG with the first frame of every scene")
     ap.add_argument("--no-timecode", action="store_true", help="--sheet without the burnt-in timecode stamp (a way out if drawtext itself is unusable, see doctor)")
     add_common(ap)
@@ -100,7 +158,8 @@ def main() -> int:
     # With --beats the file is decoded once, at the finer rate, and both envelopes come from that
     # one pass: the 0.5 s scene blocks are an exact multiple of the 10 ms onset blocks.
     beat_rate = 22050
-    fine_samples = decode_pcm_mono(args.input, beat_rate, check=False) if (args.beats and meta.get("audio")) else None
+    need_fine = args.beats or args.audio_peaks or args.speech
+    fine_samples = decode_pcm_mono(args.input, beat_rate, check=False) if (need_fine and meta.get("audio")) else None
     if fine_samples is not None:
         env = audio_envelope(args.input, step_s, rate=beat_rate, samples=fine_samples)
     else:
@@ -128,6 +187,32 @@ def main() -> int:
     result: Dict = {"file": args.input, "duration": round(dur, 3), "scene_count": len(scenes), "scenes": scenes, "audio_peaks": peaks}
     info(f"{len(scenes)} scenes, {len(peaks)} audio peaks over {dur:.1f}s")
 
+    if args.shots:
+        shots = [shot_flow_label(args.input, s, e) for s, e in zip(bounds[:-1], bounds[1:]) if e - s > 0.05]
+        result["shots"] = shots
+        counts = {}
+        for sh in shots:
+            counts[sh["label"]] = counts.get(sh["label"], 0) + 1
+        info(f"--shots: {len(shots)} shots (" + ", ".join(f"{v} {k}" for k, v in sorted(counts.items())) + ")")
+
+    if args.audio_peaks:
+        if not meta.get("audio"):
+            result["audio_peaks_db"] = []
+            info("--audio-peaks: no audio stream, nothing to measure")
+        else:
+            db_samples = fine_samples if fine_samples is not None else decode_pcm_mono(args.input, 22050, check=False)
+            result["audio_peaks_db"] = audio_peaks_db(db_samples, 22050 if fine_samples is not None else 22050)
+            info(f"--audio-peaks: {len(result['audio_peaks_db'])} peaks")
+
+    if args.speech:
+        if not meta.get("audio"):
+            result["speech"] = []
+            info("--speech: no audio stream, nothing to measure")
+        else:
+            sp_samples = fine_samples if fine_samples is not None else decode_pcm_mono(args.input, 22050, check=False)
+            result["speech"] = speech_music_ratio(sp_samples, 22050)
+            info(f"--speech: {len(result['speech'])} one-second windows")
+
     if args.beats:
         # A beat grid is a measurement of the music's periodicity, not a statement about where a
         # cut belongs. scenes.py reports what it measured, including a low confidence: reporting a

package/scripts/silence.py

@@ -42,6 +42,32 @@ def merge_spans(spans: List[Tuple[float, float]]) -> List[Tuple[float, float]]:
     return out
 
 
+BREATH_FLOOR = 0.12  # shortest gap silencedetect is asked for under --speech-aware
+
+
+def speech_aware_silences(path: str, threshold: float, min_silence: float) -> "Tuple[List[Tuple[float, float]], List[Tuple[float, float]]]":
+    """(sentence-boundary silences to remove, breaths kept) for --speech-aware.
+
+    Re-runs the same silencedetect() already used everywhere else in this file, but with a much
+    shorter minimum duration, so short in-sentence breaths are measured at all -- the plain
+    `detect()` call above never sees them because its own --min-silence floor filters them out
+    before they reach Python. Every gap silencedetect measured that is still shorter than
+    --min-silence sits *inside* a sentence -- the two speech-flagged stretches on either side of
+    it are close together in time because nothing longer separated them from the gaps around
+    them -- and is kept rather than cut; --min-silence keeps the meaning it already has for
+    --filler and the plain run: the shortest gap this tool will remove."""
+    floor = min(BREATH_FLOOR, min_silence)
+    fine = detect(path, threshold, floor)
+    boundaries, breaths = [], []
+    for s, e in fine:
+        length = (e - s) if e != float("inf") else float("inf")
+        if length >= min_silence:
+            boundaries.append((s, e))
+        else:
+            breaths.append((s, e))
+    return boundaries, breaths
+
+
 def keep_ranges(silences: List[Tuple[float, float]], duration: float, margin: float, min_keep: float) -> List[Tuple[float, float]]:
     keeps: List[Tuple[float, float]] = []
     cursor = 0.0
@@ -182,6 +208,11 @@ def main() -> int:
     ap.add_argument("--min-silence", type=float, default=0.6, help="only remove gaps at least this long in seconds (default 0.6)")
     ap.add_argument("--margin", type=float, default=0.15, help="seconds of silence to keep on each side of speech (default 0.15)")
     ap.add_argument("--min-keep", type=float, default=0.2, help="drop kept pieces shorter than this (default 0.2)")
+    ap.add_argument("--speech-aware", action="store_true",
+                    help="keep breaths shorter than --min-silence when they sit inside a sentence "
+                         "(measured by re-running silence detection at a much shorter floor), and "
+                         "only cut at sentence-boundary pauses (--min-silence or longer). Composes "
+                         "with --filler through the same keep_ranges() removal list.")
     ap.add_argument("--list", action="store_true", help="only print silences and the kept ranges")
     ap.add_argument("--edl", help="write the kept ranges to this file, one START-END per line")
     fil = ap.add_argument_group("filler words (1.17)")
@@ -229,7 +260,11 @@ def main() -> int:
     if not meta.get("audio"):
         die("input has no audio stream to analyse")
     duration = meta.get("duration") or 0.0
-    silences = detect(args.input, args.threshold, args.min_silence)
+    breaths: List[Tuple[float, float]] = []
+    if args.speech_aware:
+        silences, breaths = speech_aware_silences(args.input, args.threshold, args.min_silence)
+    else:
+        silences = detect(args.input, args.threshold, args.min_silence)
     filler_info, filler_ranges = resolve_filler(args, meta) if args.filler else (None, [])
     # One sorted, merged removal list through the graph the tool already has: filler removal IS
     # time-range removal, so it reuses keep_ranges() and the same aselect/concat chain.
@@ -253,6 +288,16 @@ def main() -> int:
         "kept_duration": round(kept, 3),
         "removed_seconds": round(silence_only, 3),
     }
+    if args.speech_aware:
+        summary["speech_aware"] = {
+            "min_silence": args.min_silence, "floor": min(BREATH_FLOOR, args.min_silence),
+            "breaths_kept": len(breaths),
+            "breaths_kept_seconds": round(sum((e - s) for s, e in breaths if e != float("inf")), 3),
+            "breaths": [[round(s, 3), None if e == float("inf") else round(e, 3)] for s, e in breaths],
+        }
+        info(f"--speech-aware: {len(breaths)} breath(s) kept "
+             f"({summary['speech_aware']['breaths_kept_seconds']:.2f}s), "
+             f"{len(silences)} sentence-boundary silence(s) cut")
     if filler_info is not None:
         # removed_seconds above is the silence-only figure, unchanged in meaning; the filler share
         # is reported inside `filler`, and removed_seconds_total is the additive sibling that