ffmpeg-skill 3.4.3 → 3.6.0

package/README.md

@@ -587,9 +587,10 @@ Where it can be installed from today. Each route is spelled out below the table.
 | Codex plugin | Codex CLI | `codex plugin marketplace add kajisho5/ffmpeg-skill --sparse .claude-plugin`, then `codex plugin add ffmpeg-skill@ffmpeg-skill` |
 | Gemini CLI extension | Gemini CLI | `gemini extensions install https://github.com/kajisho5/ffmpeg-skill` |
 | MCP server | clients without a shell | `npx -y ffmpeg-skill mcp` (see [MCP](#mcp)) |
+| MCP Registry | clients that install from the registry | `io.github.kajisho5/ffmpeg-skill` ([entry](https://registry.modelcontextprotocol.io/v0/servers/io.github.kajisho5%2Fffmpeg-skill/versions/latest)); the release workflow publishes a new version there after npm, and a failed registry step leaves the entry on the previous version |
 | GitHub release | a pinned copy | [releases](https://github.com/kajisho5/ffmpeg-skill/releases) |
 
-Not listed in a directory yet: the Claude plugin directory, the Cursor Marketplace, the Gemini CLI extension gallery, the MCP Registry and Glama. This table gains a row when a listing goes live; until then the routes above are the whole list.
+Not listed in a directory yet: the Claude plugin directory, the Cursor Marketplace, the Gemini CLI extension gallery and Glama (each is submitted and waiting on its review or crawl). This table gains a row when a listing goes live; until then the routes above are the whole list.
 
 ```bash
 npx ffmpeg-skill              # Claude Code   → ~/.claude/skills/ffmpeg-skill

package/docs/contract.md

@@ -21,7 +21,7 @@ The contract is derived from the code that runs, not maintained beside it:
 | Field | Meaning | Changes when |
 |---|---|---|
 | `contract_version` | shape of this document (`2.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`3.4.3`) | any release |
+| `skill.version` | the npm / package.json version (`3.6.0`) | any release |
 
 A release that adds a tool or a flag keeps `contract_version`; a breaking change to the
 ToolSpec shape bumps it. Consumers pin on `contract_version` and read `skill.version`
@@ -149,7 +149,7 @@ JSON would have been rewritten for that. The flat keys, typed per tool in `outpu
   "deprecated": [],
   "removed": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"},
               {"what": "running on FFmpeg 5.x (the requirements.ffmpeg floor)", "since": "2.14.0", "replacement": "FFmpeg 6.1 or later; ...", "removed_in": "3.0.0", "where": "behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "3.4.3", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "3.6.0", "execution_mode": "local", "kind": "execution",
             "entrypoints": {"cli": "...", "mcp": "...", "contract": "...", "doctor": "..."},
             "not_provided": ["AI reasoning", "decisions", "production plans", "project IR", "approvals", "network access", "transcription engine"]},
   "requirements": {"python": ">=3.10 (standard library only)", "ffmpeg": ">=6.1", "ffprobe": ">=6.1"},
@@ -752,6 +752,8 @@ silence a tool reported as fine while another measurement disagreed):
 | `verification[]` step `duration` | `export.py` (a preset with a platform maximum, without `--allow-long`) | the written file's length against the maximum, measured as `check.py` measures it (the container's duration, `tolerance` 0). A length that cannot be read fails the step with `reason: not_measured` |
 | `verification[]` step `duration` (`property: audio_duration`) | `loudness.py` | the output's sound against the input's, to one AAC frame (at least 0.03 s): a levels pass changes no timing. A length that cannot be read fails the step with `reason: not_measured` |
 | `inputs_duration`, `transition_shortening`; step `duration`'s `inputs_total` | `join.py` | the clips' own total and how much the transitions took out of it. `expected_duration` is derived from the transition the join applied, so it cannot show that on its own |
+| `margins` | `silence.py` | `{lead, tail}`: the seconds of each silence kept before speech starts (`--margin-lead`) and after it ends (`--margin-tail`); both equal `--margin` unless one is named. Absent under `--filler` with neither `--speech-aware` nor a sentence flag, which removes no silences |
+| `silence_positions`, `sentence` | `silence.py --sentence-min-silence` / `--sentence-margin-tail` | per entry of `silences`, `sentence_end` when the transcript word before it ends in sentence-final punctuation, else `inside`; and `{min_silence, margin_tail, source, word_timings, sentence_end_words, silences}`. `sentence_end_words: 0` means the transcript had no such punctuation, so every silence used `--min-silence` and `--margin-tail` (warning `sentence_ends_not_found`) |
 | `silence_kinds`, `silence_breakdown` | `silence.py` | per detected silence, `digital` (at or below -90 dBFS) or `below_threshold` (quiet sound under `--threshold`), and the count and seconds of each with the level that defines it |
 
 Keys added after 2.21, all additive (#367 follow-up, and a report of a filename with a space that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "3.4.3",
+  "version": "3.6.0",
   "mcpName": "io.github.kajisho5/ffmpeg-skill",
   "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 42 FFmpeg tools with a machine-readable contract, contract-derived MCP server, FFmpeg capability detection, probe-first / verify-last workflow. Cut, join, silence removal, fit, captions and karaoke, overlays, motion graphics, HDR to SDR, LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, project rendering, batch. No API keys, no cloud, no dependencies.",
   "keywords": [

package/references/scripts.md

@@ -697,7 +697,8 @@ each shorter clip's last frame (with silence) out to the longest.
 
 ### silence.py — remove dead air / jump cuts
 ```
-silence.py INPUT [--threshold -35] [--min-silence 0.6] [--margin 0.2] [--min-keep 0.2] [--list] [--edl keep.txt] [--timemap map.json|map.csv] [--speech-aware] [-o OUT]
+silence.py INPUT [--threshold -35] [--min-silence 0.6] [--margin 0.2] [--margin-lead S] [--margin-tail S] [--min-keep 0.2] [--list]
+           [--sentence-min-silence S] [--sentence-margin-tail S]  (with --words FILE or --transcribe) [--edl keep.txt] [--timemap map.json|map.csv] [--speech-aware] [-o OUT]
 silence.py INPUT --filler --words transcript.json [--filler-lang auto|en|ja|ko|zh|es|de|fr|pt|it|nl|pl|ru|tr]
            [--filler-words FILE] [--filler-extra W,W] [--filler-keep W,W] [--filler-pad 0.02]
            [--transcribe] [--engine auto|parakeet-mlx|parakeet.cpp|whisper.cpp|faster-whisper|openai-whisper]
@@ -713,10 +714,31 @@ to `-45`; noisy ones `-30`. Always tell the user how many seconds were removed.
 
 **Breaths and weak word endings.** `--margin` is the padding kept on each side of every cut
 (default 0.2 s since 2.22, 0.15 s before; 0.3 s for a speaker who trails off). It is kept around
-silences only: a filler word's cut is the word plus `--filler-pad` (since 3.1.6). `--speech-aware` keeps the short
+silences only: a filler word's cut is the word plus `--filler-pad` (since 3.1.6). `--margin-tail`
+is what is kept after speech ends and `--margin-lead` what is kept before it starts again; each
+defaults to `--margin`, and the result's `margins` gives the two values used. A last syllable that
+is mostly breath wants more tail than the next word wants lead (`--margin-lead 0.1 --margin-tail
+0.4`). `--speech-aware` keeps the short
 breaths inside a sentence and cuts only at sentence-boundary pauses. A `--threshold` set too high
 (-25, say) counts a weak word ending as silence: the result then warns.
 
+**Pauses inside a sentence and after one.** With word timings (`--words FILE` or `--transcribe`),
+`--sentence-min-silence S` and `--sentence-margin-tail S` give a silence that follows a sentence
+end its own floor and its own tail; every other silence keeps `--min-silence` and `--margin-tail`.
+A sentence end is a transcript word whose text ends in `. ! ? 。 ！ ？ …` (also `।` and `؟`), read
+from the transcript and never from the sound; the word before a silence is the last one
+whose own midpoint lies before the silence's midpoint, which holds when the engine stretched a
+word's timing into the pause. `--words talk.json --min-silence 0.2 --sentence-min-silence
+0.3 --margin 0.1 --sentence-margin-tail 0.3` tightens pauses inside a sentence from 0.2 s and
+after one from 0.3 s, leaving the sentence end more room. The result lists `silence_positions`
+(`sentence_end` or `inside`, one per entry of `silences`) and `sentence` (`min_silence`,
+`margin_tail`, `source`, `word_timings`, `sentence_end_words`, `silences`). With no such punctuation
+in the transcript no silence is a sentence end: every one uses `--min-silence` and `--margin-tail`,
+and the run warns `sentence_ends_not_found`. Not with `--speech-aware`,
+which takes a sentence boundary from the pause's length instead; without a transcript the flags
+are refused. With `--filler` they turn silence removal on as well (`--filler` alone removes
+only the words), reading the same transcript.
+
 **Cut levels (2.22).** Every run measures the RMS level 50 ms either side of each cut on the
 source (`cut_points`: `source_time`, `output_time`, `edge` out/in, `rms_dbfs` of the loudest
 channel, `null` for digital silence; the whole key is `null`, with a `cut_levels_unmeasured`

package/scripts/_contract.py

@@ -243,7 +243,7 @@ DRY_RUN_ANALYSIS = {
     "scenes": "scene and audio-peak measurement runs; --sheet and --edl are not written",
     "report": "probe, loudness and contact-sheet measurements run; the HTML is not written",
     "cropdetect": "the cropdetect filter runs over the sampled windows to measure bars; this tool never writes a file regardless of --dry-run",
-    "silence": "silencedetect runs so the reported silences and keep ranges are real; the cut output is not written. --filler --transcribe also runs the speech engine (its word timings are what the filler spans are planned on), which may download a model on first use",
+    "silence": "silencedetect runs so the reported silences and keep ranges are real; the cut output is not written. --filler --transcribe also runs the speech engine (its word timings are what the filler spans are planned on), which may download a model on first use; so does --transcribe with --sentence-min-silence or --sentence-margin-tail",
     "loudness": "the loudnorm measurement pass runs so input_i and the planned pass-2 command are real; the normalised output is not written",
     "check": "read-only tool; the loudness measurement (or, when it is skipped, the audio row's volumedetect) and the --content decode run under --dry-run too, so every row is present",
     "stabilize": "vidstabdetect (pass 1, into a temp file) runs; the stabilised output (pass 2) is not written",
@@ -500,6 +500,7 @@ DIAGNOSTIC_CODES = {
     "sync_low_confidence": ("warnings", "sync.py / multicam.py: a source's offset has a correlation confidence below 0.1; {path, confidence}"),
     "cropdetect_windows_failed": ("warnings", "cropdetect.py: sampled windows ffmpeg could not decode (windows_failed); {failed, windows, starts}"),
     "filler_words_untimed": ("warnings", "silence.py --filler: listed words in the transcript with no usable timing were not removed (filler.matched_untimed); {count}"),
+    "sentence_ends_not_found": ("warnings", "silence.py --sentence-min-silence / --sentence-margin-tail: the transcript has no sentence-final punctuation, so every silence used --min-silence and --margin-tail (sentence.sentence_end_words is 0)"),
     "cut_near_sound": ("warnings", "silence.py: a cut point's level is within CUT_SOUND_MARGIN_DB of --threshold, so it may land in a breath or a word's weak tail (cut_warnings lists them)"),
     "cut_levels_unmeasured": ("warnings", "silence.py: the source could not be decoded to measure the level at each cut; cut_points and cut_warnings are null (unmeasured, not silent)"),
     "filler_removal_caution": ("warnings", "silence.py --filler: a removed word that is often an ordinary word, or a discourse marker added with --filler-extra (also in filler.warnings)"),
@@ -652,6 +653,9 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
                  "beat_grid": {"type": "object", "description": "--beats (1.17): {supported_beats, tempo_bpm, interval, confidence, phase, onsets, supported, unsupported, method, step_s (the envelope's real step: 220/22050 s for --beat-step 0.01, after 3.2.0), range_bpm, usable, onset_refinement (after 3.2.0: pcm-window-ratio when each onset was placed on the decoded samples, else null)}"}}
     elif name == "silence":
         extra = {"silences": {"type": "array"}, "keep": {"type": "array"}, "input_duration": {"type": "number"}, "kept_duration": {"type": "number"}, "removed_seconds": {"type": "number"},
+                 "margins": {"type": "object", "description": "{lead, tail}: the seconds of each silence kept before speech starts (--margin-lead) and after it ends (--margin-tail); both are --margin unless one is named; absent under --filler with neither --speech-aware nor a sentence flag, which removes no silences"},
+                 "silence_positions": {"type": "array", "description": "--sentence-min-silence / --sentence-margin-tail: per entry of silences, sentence_end when the transcript word before it ends in sentence-final punctuation, else inside"},
+                 "sentence": {"type": "object", "description": "--sentence-min-silence / --sentence-margin-tail: {min_silence, margin_tail (the floor and tail given to a silence after a sentence end), source, word_timings, sentence_end_words (transcript words that end a sentence; 0 means none did, so every silence used --min-silence and --margin-tail), silences (how many of silences are sentence_end)}"},
                  "removed_seconds_total": {"type": "number", "description": "--filler: seconds removed in all, silence plus filler words (removed_seconds stays the silence alone)"},
                  "cut_points": {"type": ["array", "null"], "description": "2.22: per cut {source_time, output_time, edge (out|in), rms_dbfs (the loudest channel 50 ms either side on the source; null for digital silence), filler (true on a removed filler word's edge)}; null when the source could not be decoded for it (cut_levels_unmeasured warning)"},
                  "cut_warnings": {"type": ["array", "null"], "description": "the cut_points (not filler cuts) within 10 dB of --threshold: where to listen (a cut_near_sound warning); verified is unchanged"},

package/scripts/render.py

@@ -134,7 +134,7 @@ OBJECT_KEYS: Dict[str, frozenset] = {
     "snap": frozenset({"to", "tolerance", "min_confidence", "source"}),
     "frame": frozenset({"aspect", "width", "height", "fps", "fit"}),
     "transition": frozenset({"type", "duration"}),
-    "silence": frozenset({"threshold", "min_silence", "margin"}),
+    "silence": frozenset({"threshold", "min_silence", "margin", "margin_lead", "margin_tail"}),
     # 1.16: the picture an audio-only source gets before the rest of the chain can work on it
     "audiogram": frozenset({"image", "image_fit", "style", "position", "vis_height", "opacity",
                             "platform", "title", "color", "background", "width", "height", "fps"}),
@@ -1428,7 +1428,8 @@ def main() -> int:
     if sil:
         nxt = str(work / f"tight{mid}")
         argv = [current, "-o", nxt]
-        for k, flag in (("threshold", "--threshold"), ("min_silence", "--min-silence"), ("margin", "--margin")):
+        for k, flag in (("threshold", "--threshold"), ("min_silence", "--min-silence"), ("margin", "--margin"),
+                        ("margin_lead", "--margin-lead"), ("margin_tail", "--margin-tail")):
             if sil.get(k) is not None:
                 argv += [flag, str(sil[k])]
         sh("silence.py", *argv, stage="silence")

package/scripts/silence.py

@@ -9,6 +9,9 @@ cut.py --segments --accurate cuts them (both streams on one set of frame-grid bo
 Examples:
   python3 silence.py talk.mp4                                 # -35 dB, gaps >= 0.6 s, 0.2 s margin
   python3 silence.py talk.mp4 --threshold -40 --min-silence 1 --margin 0.25
+  python3 silence.py talk.mp4 --margin-lead 0.1 --margin-tail 0.4   # less before a word, more after one
+  python3 silence.py talk.mp4 --words talk.json --min-silence 0.2 --sentence-min-silence 0.3 --sentence-margin-tail 0.3
+                                                              # pauses inside a sentence from 0.2 s, after one from 0.3 s with a longer tail
   python3 silence.py talk.mp4 --list                          # print the silences and the resulting cut list, no output
   python3 silence.py talk.mp4 --edl keep.txt                  # also save the kept ranges (START-END per line, cut.py --segments format)
 """
@@ -58,6 +61,76 @@ CUT_LEVEL_RATE = 8000
 CUT_LEVEL_CHANNELS = 2  # measured one by one; a surround source is folded to two first
 DIGITAL_SILENCE_DB = -90.0  # 2.20: at or below this a span is digital silence (16-bit dither sits near -96)
 BREATH_FLOOR = 0.12  # shortest gap silencedetect is asked for under --speech-aware
+# a transcript word that ends in one of these (after any closing quote or bracket) ends a sentence
+SENTENCE_END = ".!?\u3002\uff01\uff1f\u2026\u0964\u061f"
+SENTENCE_CLOSERS = "\"'\u201d\u2019\u300d\u300f\uff09)]\u3011 "
+
+
+def ends_sentence(word: str) -> bool:
+    """Whether a transcript word carries sentence-final punctuation: read off the text the speech
+    engine wrote, never guessed from the sound."""
+    text = str(word or "").rstrip(SENTENCE_CLOSERS)
+    return bool(text) and text[-1] in SENTENCE_END
+
+
+def silence_positions(silences: List[Tuple[float, float]], words: "list",
+                      duration: Optional[float] = None) -> List[str]:
+    """Per silence, `sentence_end` when the word spoken before it ends a sentence, else `inside`.
+    The word before a silence is the last one whose own midpoint lies before the silence's
+    midpoint; a silence that runs to the end of the file ends at `duration`. An engine
+    stretches a word's timing into the pause beside it, the end of the word before or the start
+    of the word after (on demos/footage/ai_talk_en.mp4 three word starts sit 0.45 to 0.5 s before
+    the sound does), and a word's midpoint stays on its own side of the pause either way. A
+    silence with no word before it is `inside`."""
+    timed = sorted(words, key=lambda w: w["start"] + w["end"])
+    out: List[str] = []
+    for s, e in silences:
+        if e == float("inf"):
+            e = max(s, duration) if duration is not None else s
+        ref = (s + e) / 2
+        before = [w for w in timed if (w["start"] + w["end"]) / 2 < ref]
+        out.append("sentence_end" if before and ends_sentence(before[-1]["word"]) else "inside")
+    return out
+
+
+def sentence_words(args) -> "Tuple[list, str]":
+    """(word timings, where they came from) for --sentence-min-silence / --sentence-margin-tail.
+    Under --filler the transcript that run read or made is reused; otherwise --words is read, or
+    --transcribe runs the local engine. Refuses without one: where a sentence ends is taken from
+    the transcript's punctuation, and there is no reading it off a pause."""
+    def usable(words: "list", source: str) -> "Tuple[list, str]":
+        # a word with no length or a time that is not a number cannot be placed against a pause
+        timed = [w for w in words if math.isfinite(w["start"]) and math.isfinite(w["end"]) and w["end"] > w["start"]]
+        if not timed:
+            die(f"no usable word timings in the transcript ({source}): every word's start and end must be "
+                "numbers with the end after the start, or there is nothing to place a sentence end against a pause",
+                kind="input")
+        return timed, source
+
+    if getattr(args, "_words", None) is not None:
+        return usable(args._words, args._words_source)
+    if args.words:
+        try:
+            raw = json.loads(read_text_or_die(args.words, "--words"))
+        except ValueError as exc:
+            die(f"--words {args.words}: not readable JSON ({exc})", kind="input")
+        words, _had_segments, _untimed = _words_from_transcript(raw)
+        if not words:
+            die(f"no word timings in {args.words}: the sentence flags need "
+                '{"words": [{"word": ..., "start": ..., "end": ...}]} (or the same inside "segments").',
+                kind="input")
+        return usable(words, f"whisper-json:{args.words}")
+    if args.transcribe:
+        asr_run = _asr.transcribe_words_result(args.input, None, model=args.model, engine=args.engine)
+        args._asr_notes = list(asr_run.notes)
+        if not asr_run.words:
+            die(f"{asr_run.engine or 'the local engine'} ran but produced no word-level timings, so there is "
+                "nothing to tell a sentence end from. Pass a transcript with word timings as --words.", kind="input")
+        family = "parakeet" if asr_run.engine in _asr.PARAKEET_ENGINES else "whisper"
+        return usable(asr_run.words, f"{family}:{asr_run.engine}" if asr_run.engine else "whisper")
+    die("--sentence-min-silence and --sentence-margin-tail need word timings: pass --words transcript.json "
+        "(a whisper JSON with word timestamps) or --transcribe. A sentence end is read from the transcript's "
+        "punctuation; a pause's length does not say where one is.", kind="input")
 
 
 def speech_aware_silences(path: str, threshold: float, min_silence: float) -> "Tuple[List[Tuple[float, float]], List[Tuple[float, float]]]":
@@ -83,9 +156,12 @@ def speech_aware_silences(path: str, threshold: float, min_silence: float) -> "T
     return boundaries, breaths
 
 
-def inside_margin(silences: List[Tuple[float, float]], duration: float, margin: float) -> List[Tuple[float, float]]:
-    """Each silence with --margin kept on both sides: the stretch actually removed. A silence too
-    short to hold two margins removes nothing (it is dropped, never turned inside out).
+def inside_margin(silences: List[Tuple[float, float]], duration: float, margin: float,
+                  lead: Optional[float] = None) -> List[Tuple[float, float]]:
+    """Each silence with a margin kept on both sides: the stretch actually removed. `margin` is
+    kept after the speech that ends where the silence starts (--margin-tail), `lead` before the
+    speech that starts where it ends (--margin-lead; the same as `margin` when not given). A
+    silence too short to hold both removes nothing (it is dropped, never turned inside out).
 
     The margin is applied to the silences alone, before they are merged with filler spans (#414):
     a filler word's span is the word itself plus --filler-pad, and taking a 0.2 s margin off each
@@ -94,7 +170,7 @@ def inside_margin(silences: List[Tuple[float, float]], duration: float, margin:
     out: List[Tuple[float, float]] = []
     for s, e in silences:
         a = s + margin
-        b = duration if e == float("inf") else min(duration, e - margin)
+        b = duration if e == float("inf") else min(duration, e - (margin if lead is None else lead))
         if b > a:
             out.append((a, b))
     return out
@@ -308,6 +384,7 @@ def resolve_filler(args, meta):
                 "faster-whisper word_timestamps=True / openai-whisper --word_timestamps True) and "
                 "pass the result with --words.", kind="input")
 
+    args._words, args._words_source = words, source  # the sentence flags read the same transcript
     lang = args.filler_lang
     reported_lang = lang
     if lang == "auto":
@@ -455,6 +532,20 @@ def main() -> int:
     ap.add_argument("--threshold", type=float, default=-35.0, help="silence level in dBFS (default -35; use -40..-45 for quiet rooms)")
     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.2, help="seconds of silence to keep on each side of speech (default 0.2; 0.15 before 2.22)")
+    ap.add_argument("--margin-lead", type=float, default=None, metavar="SECONDS",
+                    help="seconds of silence to keep before speech starts, when it should differ from --margin "
+                         "(default: --margin)")
+    ap.add_argument("--margin-tail", type=float, default=None, metavar="SECONDS",
+                    help="seconds of silence to keep after speech ends, when it should differ from --margin "
+                         "(default: --margin); a speaker whose last syllable trails off needs more here than "
+                         "before the next word")
+    ap.add_argument("--sentence-min-silence", type=float, default=None, metavar="SECONDS",
+                    help="for a silence after a word that ends a sentence, remove it only when it is at least this "
+                         "long, instead of --min-silence. Needs --words or --transcribe: a sentence end is the "
+                         "transcript's punctuation")
+    ap.add_argument("--sentence-margin-tail", type=float, default=None, metavar="SECONDS",
+                    help="for a silence after a word that ends a sentence, keep this much after the speech instead "
+                         "of --margin-tail. Needs --words or --transcribe")
     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 "
@@ -485,7 +576,7 @@ def main() -> int:
     fil.add_argument("--filler-pad", type=float, default=FILLER_PAD,
                      help=f"seconds trimmed either side of a filler word (default {FILLER_PAD})")
     fil.add_argument("--words", metavar="FILE",
-                     help="a whisper JSON with word-level timings, for --filler")
+                     help="a whisper JSON with word-level timings, for --filler and the sentence flags")
     fil.add_argument("--transcribe", action="store_true",
                      help="produce the word timings with a local speech engine, Parakeet or whisper (never required; the same "
                           "bridge caption.py uses)")
@@ -525,6 +616,26 @@ def main() -> int:
     if not math.isfinite(args.margin) or args.margin < 0:
         # nan made inside_margin() drop every silence and re-encode the whole file unchanged
         die(f"--margin must be a finite number of seconds, 0 or more (got {args.margin:g})", kind="input")
+    for flag, value in (("--margin-lead", args.margin_lead), ("--margin-tail", args.margin_tail)):
+        if value is not None and (not math.isfinite(value) or value < 0):
+            die(f"{flag} must be a finite number of seconds, 0 or more (got {value:g})", kind="input")
+    # what is kept after speech ends and before it starts again; --margin is the value of both
+    # unless one is named
+    tail = args.margin if args.margin_tail is None else args.margin_tail
+    lead = args.margin if args.margin_lead is None else args.margin_lead
+    by_sentence = args.sentence_min_silence is not None or args.sentence_margin_tail is not None
+    for flag, value in (("--sentence-min-silence", args.sentence_min_silence),
+                        ("--sentence-margin-tail", args.sentence_margin_tail)):
+        if value is not None and (not math.isfinite(value) or value < 0):
+            die(f"{flag} must be a finite number of seconds, 0 or more (got {value:g})", kind="input")
+    if by_sentence and args.speech_aware:
+        die("--speech-aware and the sentence flags answer the same question two ways: --speech-aware takes a "
+            "pause of --min-silence or longer as a sentence boundary, --sentence-min-silence and "
+            "--sentence-margin-tail take the transcript's punctuation. Pass one of them.", kind="input")
+    if by_sentence and not (args.words or args.transcribe):
+        sentence_words(args)  # refuses: no transcript to read a sentence end from
+    sentence_min = args.min_silence if args.sentence_min_silence is None else args.sentence_min_silence
+    sentence_tail = tail if args.sentence_margin_tail is None else args.sentence_margin_tail
     if args.filler_pad < 0:
         die("--filler-pad cannot be negative: a negative pad turns each word's span inside out "
             "(end before start) and the span is then silently dropped, so nothing is removed",
@@ -540,16 +651,44 @@ def main() -> int:
     breaths: List[Tuple[float, float]] = []
     if args.speech_aware:
         silences, breaths = speech_aware_silences(args.input, args.threshold, args.min_silence)
-    elif args.filler:
+    elif args.filler and not by_sentence:
         silences = []  # --filler alone: remove only the filler-word spans, not generic dead air
     else:
-        silences = detect(args.input, args.threshold, args.min_silence)
+        # with the sentence flags each kind of pause has its own floor: measure at the shorter one
+        silences = detect(args.input, args.threshold, min(args.min_silence, sentence_min) if by_sentence else args.min_silence)
     filler_info, filler_ranges = resolve_filler(args, meta) if args.filler else (None, [])
+    positions: List[str] = []
+    sentence_info: Optional[Dict[str, Any]] = None
+    if by_sentence:
+        words, words_source = sentence_words(args)
+        found = silence_positions(silences, words, duration)
+        # a silence that runs to the end of the file is as long as what is left of the file
+        kept_pairs = [(span, pos) for span, pos in zip(silences, found)
+                      if (duration if span[1] == float("inf") else span[1]) - span[0]
+                      >= (sentence_min if pos == "sentence_end" else args.min_silence)]
+        silences = [span for span, _ in kept_pairs]
+        positions = [pos for _, pos in kept_pairs]
+        marked = sum(1 for w in words if ends_sentence(w["word"]))
+        sentence_info = {"min_silence": sentence_min, "margin_tail": sentence_tail, "source": words_source,
+                         "word_timings": len(words), "sentence_end_words": marked,
+                         "silences": positions.count("sentence_end")}
+        if not marked:
+            warn("the transcript has no sentence-final punctuation, so no silence was taken as a sentence end: "
+                 "every silence used --min-silence and --margin-tail", "sentence_ends_not_found")
+
+    def margined(spans: List[Tuple[float, float]]) -> List[Tuple[float, float]]:
+        """The stretch of each silence that is removed: its own tail for one after a sentence end."""
+        if not by_sentence:
+            return inside_margin(spans, duration, tail, lead)
+        out: List[Tuple[float, float]] = []
+        for span, pos in zip(spans, positions):
+            out += inside_margin([span], duration, sentence_tail if pos == "sentence_end" else tail, lead)
+        return out
     # 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 select chain.
     # --margin is kept around the silences only (inside_margin), not around filler spans, whose
     # own trim is --filler-pad (#414); the merged list then goes through with no further margin.
-    removals = merge_spans(inside_margin(silences, duration, args.margin) + list(filler_ranges))
+    removals = merge_spans(margined(silences) + list(filler_ranges))
     keeps = keep_ranges(removals, duration, 0.0, args.min_keep)
     # what the render holds (on a picture, each bound on its nearest frame): the report, the EDL
     # and the time map all describe these, so a re-cut or a sum of `keep` is the rendered edit
@@ -564,7 +703,7 @@ def main() -> int:
     # the silences alone; everything removed is `removed_seconds_total`.
     silence_only = removed
     if args.filler:
-        silence_keeps = keep_ranges(merge_spans(inside_margin(silences, duration, args.margin)), duration, 0.0, args.min_keep)
+        silence_keeps = keep_ranges(merge_spans(margined(silences)), duration, 0.0, args.min_keep)
         silence_only = max(0.0, duration - sum(e - s for s, e in rendered_ranges(silence_keeps, meta, duration, video_out)))
     kinds = silence_kinds(args.input, silences, duration, args.threshold)
     summary = {
@@ -574,6 +713,15 @@ def main() -> int:
         "kept_duration": round(kept, 3),
         "removed_seconds": round(silence_only, 3),
     }
+    if silences or not args.filler or args.speech_aware or by_sentence:
+        # the seconds of each silence this run kept: `tail` from where the silence starts (after
+        # the speech before it), `lead` up to where it ends (before the speech after it). Absent
+        # under --filler with neither --speech-aware nor a sentence flag: no silence is detected.
+        summary["margins"] = {"lead": lead, "tail": tail}
+    if sentence_info is not None:
+        # which of `silences` follow a sentence end, and the floor and tail those were given
+        summary["silence_positions"] = positions
+        summary["sentence"] = sentence_info
     if kinds:
         summary.update(kinds)
     if args.speech_aware:
@@ -605,7 +753,7 @@ def main() -> int:
         die(f"{len(keeps)} keep ranges is above --max-cuts {args.max_cuts}: the filter graph grows "
             "with every range and a graph this size is slow and fragile. Raise --max-cuts if you "
             "mean it, or use --min-silence/--filler-pad to merge the short ones.", kind="input")
-    filler_only = args.filler and not args.speech_aware
+    filler_only = args.filler and not args.speech_aware and not by_sentence
     if filler_only:
         info(f"--filler only (no --speech-aware): skipping generic silence detection, "
              f"keeping {len(keeps)} range(s): {kept:.2f}s of {duration:.2f}s (removing {removed:.2f}s, filler only)")
@@ -641,7 +789,8 @@ def main() -> int:
         if near:
             where = ", ".join("%.2fs" % c["source_time"] for c in near[:5]) + (", ..." if len(near) > 5 else "")
             warn(f"{len(near)} cut point(s) sit within {CUT_SOUND_MARGIN_DB:g} dB of --threshold ({where}): "
-                 "a breath or a word's weak tail may be cut; listen there, or lower --threshold / raise --margin",
+                 "a breath or a word's weak tail may be cut; listen there, or lower --threshold / raise --margin "
+                 "(--margin-tail for an `out` edge, --margin-lead for an `in` edge)",
                  "cut_near_sound", cuts=len(near))
 
     def finish_time_map() -> None: