ffmpeg-skill 3.5.0 → 3.6.1

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.5.0`) | any release |
+| `skill.version` | the npm / package.json version (`3.6.1`) | 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.5.0", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "3.6.1", "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,7 +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` without `--speech-aware`, which removes no silences |
+| `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
@@ -896,7 +897,7 @@ here claims otherwise until real exit-code/stderr sniffing exists to back that u
 A refusal also carries `error.reason`, a stable snake_case code for *why*
 (`contract --json` → `json_output.error_reasons` lists them: `output_exists`, `output_is_input`,
 `output_is_directory`, `output_dir_missing`, `output_dir_not_writable`, `output_locked`,
-`media_path_is_url`, `media_path_is_playlist` (an HLS or ffconcat playlist given as media),
+`media_path_is_url` (`subfile,...:` included), `media_path_is_playlist` (an HLS, DASH, IMF or ffconcat playlist given as media, DASH and IMF told by content whatever the file is called), `media_path_has_line_break` (a path with a line break, which a concat list cannot hold),
 `output_looks_like_option` (an output starting with `-`, other than `-` for stdout), `output_path_taken` (two files one run writes share a path), `media_path_not_a_file` (a FIFO or device as input), `silence.py --timemap`'s `timemap_path_taken`, `join.py --copy`'s `join_copy_mismatch`,
 `render.py`'s `plan_*` reasons, `--codec av1`/`prores`'s `encoder_missing` and
 `encoder_list_unreadable`, and `--transcribe`'s `asr_engine_missing`, `no_speech`, `engine_failed`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "3.5.0",
+  "version": "3.6.1",
   "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] [--margin-lead S] [--margin-tail S] [--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]
@@ -721,6 +722,23 @@ is mostly breath wants more tail than the next word wants lead (`--margin-lead 0
 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/_ass_overlay.py

@@ -54,7 +54,7 @@ def ass_time(sec: float) -> str:
 
 def ass_color(hex_rgb: str, alpha: int = 0) -> str:
     h = str(hex_rgb).lstrip("#")
-    if len(h) != 6:
+    if len(h) != 6 or any(c not in "0123456789abcdefABCDEF" for c in h):
         raise ValueError(f"colour must be RRGGBB hex, got '{hex_rgb}'")
     return f"&H{alpha:02X}{h[4:6]}{h[2:4]}{h[0:2]}".upper()
 

package/scripts/_common/color.py

@@ -312,13 +312,20 @@ def fold_bt709_matrix(cmd: Sequence[str]) -> List[str]:
     return out[:at] + ["-vf", conv] + out[at:]
 
 
+_HEX6 = re.compile(r"^[0-9A-Fa-f]{6}$")
+
+
 def color_hex(value: str) -> str:
-    """Normalise '#ffd200' / 'ffd200' / '0xFFD200' to 'FFD200'."""
+    """Normalise '#ffd200' / 'ffd200' / '0xFFD200' to 'FFD200'. Six hex digits only: the result is
+    written into libass styles and drawtext/color options, so a six-letter colour name ("yellow")
+    used to pass the length check and draw black, reported verified, and a quote or comma reached
+    the filter graph."""
     v = str(value).strip().lstrip("#")
     if v.lower().startswith("0x"):
         v = v[2:]
-    if len(v) != 6:
-        die(f"colour must be RRGGBB, got '{value}'")
+    if not _HEX6.match(v):
+        die(f"colour must be six hex digits RRGGBB (e.g. FFD200 or #ffd200), got '{value}'; colour names are not "
+            "accepted here")
     return v.upper()
 
 

package/scripts/_common/decision.py

@@ -148,7 +148,15 @@ def concat_list_line(path: str) -> str:
     """One `file '...'` line for the concat demuxer. The demuxer reads backslash as an escape
     inside the quoted form, so a Windows path (C:\\Users\\...\\part000.mp4) must be written
     with forward slashes -- ffmpeg opens either spelling on Windows -- and a single quote in the
-    name is closed, escaped and reopened. Shared by cut.py (multi-segment) and sequence.py."""
+    name is closed, escaped and reopened. Shared by cut.py (multi-segment) and sequence.py.
+
+    A line break has no escape in this format: the demuxer reads each line as its own directive,
+    so a name containing one would add `file` entries to the list and pull in files the caller
+    never named. Such a path is refused."""
+    if "\n" in str(path) or "\r" in str(path):
+        refuse("input", "media_path_has_line_break",
+               f"{str(path)!r} contains a line break, which ffmpeg's concat list cannot hold (each line is a "
+               "directive of its own); rename the file", path=str(path))
     # only on Windows: on POSIX the quoted form takes a backslash literally, and it is part of the name (#408)
     escaped = (str(path).replace("\\", "/") if _on_windows() else str(path)).replace("'", "'\\''")
     return f"file '{escaped}'"

package/scripts/_common/emit.py

@@ -8,6 +8,7 @@ from __future__ import annotations
 import json
 import math
 import os
+import stat
 import sys
 from typing import Any, Dict, List, Optional, Sequence, Tuple
 from _common.runner import Context, ERROR_CODE, ERROR_RETRYABLE, STATE
@@ -319,7 +320,28 @@ def audit(event: str, details: Dict[str, Any], *, default_path: Optional[str] =
         rec["plan_sha256"] = plan_sha256
     rec["details"] = details
     try:
-        with open(path, "a", encoding="utf-8") as f:
+        # a default path is a hidden name in someone's output directory: never appended to through a
+        # symlink planted there. A log the caller named (--audit-log) is opened as named.
+        flags = os.O_WRONLY | os.O_APPEND | os.O_CREAT | (0 if ctx.audit_log else getattr(os, "O_NOFOLLOW", 0))
+        checked = not ctx.audit_log and not hasattr(os, "O_NOFOLLOW")
+        if checked and os.path.islink(path):
+            raise OSError(f"{path} is a symbolic link")
+        fd = os.open(path, flags, 0o666)
+        if checked:
+            # no O_NOFOLLOW (Windows): a link that appeared between the look above and the open is
+            # caught after it -- the descriptor must be the file now at that name, not a link's
+            # target -- and nothing is written through it
+            try:
+                st, at = os.fstat(fd), os.lstat(path)
+                # st_nlink: a link swapped for a hard link to its target before the lstat would
+                # otherwise pass the identity check; a log this tool created has one name
+                if (stat.S_ISLNK(at.st_mode) or (st.st_dev, st.st_ino) != (at.st_dev, at.st_ino)
+                        or not stat.S_ISREG(st.st_mode) or st.st_nlink != 1):
+                    raise OSError(f"{path} was replaced by a link while it was opened")
+            except BaseException:
+                os.close(fd)
+                raise
+        with os.fdopen(fd, "a", encoding="utf-8") as f:
             f.write(json.dumps(json_safe(rec), ensure_ascii=False, sort_keys=True) + "\n")
     except OSError as exc:
         warn(f"could not append the {event} record to the audit log {path} ({exc}); the run is unaffected",

package/scripts/_common/runner.py

@@ -775,21 +775,69 @@ _URL_SCHEME = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]+:")
 _URL_SCHEME_POSIX = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*:")
 
 
+def _is_subfile_url(value: str) -> bool:
+    """ffmpeg's url_find_protocol() also opens `subfile,<options>:<url>` through the subfile
+    protocol: the scheme stops at the comma, so the regexes above never see it."""
+    return value.startswith("subfile,") and ":" in value[len("subfile,"):]
+
+
 def looks_like_url(value: str) -> bool:
     """True for a value ffmpeg would open through a protocol rather than as a local file."""
+    if _is_subfile_url(value):
+        return True
     scheme = _URL_SCHEME if os.name == "nt" else _URL_SCHEME_POSIX
     return bool(scheme.match(value)) and not value.startswith("pipe:")
 
 
-_PLAYLIST_SUFFIXES = (".m3u8", ".m3u", ".ffconcat")
+def url_scheme(value: str) -> str:
+    """The protocol name ffmpeg would open `value` through (for a looks_like_url() value)."""
+    return "subfile" if _is_subfile_url(value) else value.split(":", 1)[0].lower()
+
+
+_PLAYLIST_SUFFIXES = (".m3u8", ".m3u", ".ffconcat", ".mpd")
 _PLAYLIST_MAGIC = (b"#EXTM3U", b"ffconcat")
+# ffmpeg probes a text format over the whole probe buffer (up to -probesize, 5,000,000 bytes), not
+# over a fixed prefix, and reads that buffer as a C string, so the scan below stops at the first
+# NUL byte: a real media file has one within its first few bytes, a manifest has none.
+_MANIFEST_SCAN_LIMIT = 5_000_000
+
+
+def _manifest_kind(path: str) -> Optional[str]:
+    """"DASH" or "IMF" when ffmpeg's own probe would read `path` as that manifest, whatever its
+    name: dash_probe() looks for `<MPD` and `dash:profile` or `3GPP:PSS:profile:DASH1`
+    (case-insensitively), imf_probe() for
+    `<CompositionPlaylist` and `ContentTitle>`. Either one names other files, local or remote, that
+    ffmpeg then opens (a DASH BaseURL is followed over HTTP even under -protocol_whitelist file)."""
+    buf = bytearray()
+    try:
+        with open(path, "rb") as fh:
+            while len(buf) < _MANIFEST_SCAN_LIMIT:
+                chunk = fh.read(65536)
+                if not chunk:
+                    break
+                nul = chunk.find(b"\0")
+                if nul >= 0:
+                    buf += chunk[:nul]
+                    break
+                buf += chunk
+    except OSError:
+        return None
+    text = bytes(buf[:_MANIFEST_SCAN_LIMIT])
+    low = text.lower()
+    if b"<mpd" in low and (b"dash:profile" in low or b"3gpp:pss:profile:dash1" in low):
+        return "DASH"
+    if b"<CompositionPlaylist" in text and b"ContentTitle>" in text:
+        return "IMF"
+    return None
 
 
 def _refuse_playlist(value: str) -> None:
-    """Refuse an input that ffmpeg would read as a playlist (HLS .m3u8, an ffconcat list) rather
-    than as media. A playlist names other files by path, so a media file handed to the skill could
-    pull in any file the user can read. The skill's own concat lists pass `-f concat` and are not
-    checked here."""
+    """Refuse an input that ffmpeg would read as a playlist (HLS .m3u8, a DASH .mpd, an IMF
+    composition playlist, an ffconcat list) rather than as media. A playlist names other files by
+    path or URL, so a media file handed to the skill could pull in any file the user can read, or
+    make ffmpeg fetch a URL. HLS and ffconcat are told by name or by their first bytes; DASH and IMF
+    by name or by the content ffmpeg's own probe looks for, anywhere before the first NUL byte. The
+    skill's own concat lists pass `-f concat` and are not checked here."""
     if os.path.exists(value) and not os.path.isfile(value) and not os.path.isdir(value):
         # a FIFO or a device: ffmpeg would block on it or read whatever it streams
         refuse("input", "media_path_not_a_file",
@@ -801,9 +849,14 @@ def _refuse_playlist(value: str) -> None:
                 head = fh.read(16).lstrip(b"\xef\xbb\xbf \t\r\n")
     except OSError:
         pass
+    kind = None
     if value.lower().endswith(_PLAYLIST_SUFFIXES) or head.startswith(_PLAYLIST_MAGIC):
+        kind = "HLS, DASH or ffconcat"
+    elif os.path.isfile(value):
+        kind = _manifest_kind(value)
+    if kind:
         refuse("input", "media_path_is_playlist",
-               f"{value!r} is a playlist (HLS or ffconcat), which ffmpeg would follow to the files it names; "
+               f"{value!r} is a playlist ({kind}), which ffmpeg would follow to the files or URLs it names; "
                "this skill takes media files only. Pass the media file itself", path=value)
 
 
@@ -836,9 +889,9 @@ def _refuse_url_media(cmd: Sequence[str]) -> None:
     for value in values:
         if looks_like_url(value):
             refuse("input", "media_path_is_url",
-                   f"{value!r} would be opened by ffmpeg as a URL ({value.split(':', 1)[0]}:), not as a local file; "
+                   f"{value!r} would be opened by ffmpeg as a URL ({url_scheme(value)}:), not as a local file; "
                    "this skill reads and writes local files only. Pass a plain path (a local name containing "
-                   "a colon works as ./name)", path=value, scheme=value.split(":", 1)[0].lower())
+                   "a colon works as ./name)", path=value, scheme=url_scheme(value))
 
 
 def _check_no_overwrite_input(cmd: Sequence[str]) -> None:
@@ -1243,10 +1296,73 @@ def _stage_existing_output(cmd: Sequence[str]) -> Tuple[List[str], Optional[str]
         return list(cmd), None, None
     d, base = os.path.split(output)
     stem, ext = os.path.splitext(base)
-    tmp = os.path.join(d, f".{stem}.ffskill-{os.getpid()}{ext}")
+    tmp = reserve_sibling(d, stem, ext)
     return list(cmd[:-1]) + [tmp], output, tmp
 
 
+def _reserve(d: str, stem: str, ext: str, tag: str) -> "Tuple[str, Optional[int]]":
+    """(path, open descriptor) of a hidden sibling created exclusively; (path, None) when the
+    directory refuses the create (the write that follows then fails there)."""
+    flags = os.O_CREAT | os.O_EXCL | os.O_WRONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_BINARY", 0)
+    n = 1
+    while True:
+        path = os.path.join(d, f".{stem}.ffskill-" + (f"{tag}-" if tag else "") + f"{os.getpid()}"
+                            + (f"-{n}" if n > 1 else "") + ext)
+        try:
+            return path, os.open(path, flags, 0o666)
+        except FileExistsError:
+            n += 1
+        except OSError:
+            return path, None
+
+
+def reserve_sibling(d: str, stem: str, ext: str, tag: str = "") -> str:
+    """Create the hidden sibling `.<stem>.ffskill-<pid><ext>` (or `...-<pid>-<n><ext>` when that
+    name is taken) exclusively, and return its path, for ffmpeg to write with -y. O_EXCL never
+    opens an existing entry, a symlink included, so a name planted in the output directory
+    beforehand is never written through. What it cannot stop is someone who may delete files in
+    that directory replacing this one between the create and ffmpeg's open: not possible in a
+    sticky shared directory (/tmp), nor in one only the caller can write. A copy this process makes
+    itself goes through copy_to_sibling(), which writes the descriptor it created."""
+    path, fd = _reserve(d, stem, ext, tag)
+    if fd is None:
+        # fail closed: a name that was not created exclusively is never handed to ffmpeg
+        refuse("input", "output_dir_not_writable", f"cannot create a temporary file in {d or '.'!r}",
+               output=os.path.join(d, stem + ext), directory=d or ".")
+    os.close(fd)
+    return path
+
+
+def copy_to_sibling(src: str, dst: str) -> str:
+    """Copy `src` into a hidden sibling of `dst` created exclusively, through the descriptor that
+    created it (never by reopening the name), and return the sibling's path for os.replace()."""
+    import shutil
+    d, base = os.path.split(dst)
+    stem, ext = os.path.splitext(base)
+    path, fd = _reserve(d, stem, ext, "")
+    if fd is None:
+        raise OSError(f"cannot create a temporary file beside {dst}")
+    try:
+        fout = os.fdopen(fd, "wb")
+    except BaseException:
+        os.close(fd)
+        try:
+            os.remove(path)
+        except OSError:
+            pass
+        raise
+    try:
+        with fout, open(src, "rb") as fin:
+            shutil.copyfileobj(fin, fout, 1 << 20)
+    except BaseException:
+        try:
+            os.remove(path)
+        except OSError:
+            pass
+        raise
+    return path
+
+
 HW_ENV = "FFMPEG_SKILL_HW"
 # set only by render.py/batch.py --hw/--no-hw for the stages they run: "the outer command chose
 # explicitly", so a child resolves $FFMPEG_SKILL_HW as a flag (export.py included), not a default
@@ -1846,7 +1962,6 @@ def place_output(src: str, dst: str, move: bool = False) -> None:
     _check_existing_output(cmd)
     d, base = os.path.split(dst)
     stem, ext = os.path.splitext(base)
-    tmp = os.path.join(d, f".{stem}.ffskill-{os.getpid()}{ext}")
     with _OutputLock(dst):
         if move:
             try:
@@ -1855,14 +1970,16 @@ def place_output(src: str, dst: str, move: bool = False) -> None:
                 return
             except OSError:
                 pass
+        tmp = None
         try:
-            shutil.copyfile(src, tmp)
+            tmp = copy_to_sibling(src, dst)
             os.replace(tmp, dst)
         except OSError as e:
-            try:
-                os.remove(tmp)
-            except OSError:
-                pass
+            if tmp:
+                try:
+                    os.remove(tmp)
+                except OSError:
+                    pass
             die(f"could not place {dst}: {e}", kind="output")
     _remember_output(cmd)
 

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",
@@ -424,7 +424,8 @@ ERROR_REASONS = {
     "output_exists": "an output already exists and --overwrite was not given; details.outputs: [{path, resolved, size, mtime_ns}]",
     "output_is_input": "the output resolves to the same file as an input; details: {output, input, resolved}",
     "output_is_directory": "the output path is a directory; details: {output}",
-    "media_path_is_playlist": "an input is a playlist (HLS .m3u8/.m3u or an ffconcat list, by name or by its first bytes) that ffmpeg would follow to the files it names; the skill takes media files only; details: {path}",
+    "media_path_is_playlist": "an input is a playlist that ffmpeg would follow to the files or URLs it names: HLS .m3u8/.m3u or an ffconcat list (by name or by its first bytes), a DASH manifest or an IMF composition playlist (by name or by the content ffmpeg's own probe looks for, whatever the file is called); the skill takes media files only; details: {path}",
+    "media_path_has_line_break": "a path written into a concat list (loop.py, join.py --copy, sequence.py, multi-part cuts) contains a line break, which the concat format cannot hold: each line is a directive, so the name would add entries to the list; details: {path}",
     "media_path_not_a_file": "an input exists but is not a regular file (a FIFO or a device), which ffmpeg would block on or read as a stream; details: {path}",
     "join_copy_mismatch": "join.py --copy: a clip's streams do not match the first clip's, it hides pre-roll frames with an edit list, or its picture and sound end more than 50 ms apart; details: {clips: [{index?, path, differs}]}",
     "output_path_taken": "two files one run writes (a side file and the output, or two side files) resolve to the same path, so the second would replace the first; details: {output, other}",
@@ -500,6 +501,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,7 +654,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 without --speech-aware, which removes no silences"},
+                 "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/batch.py

@@ -33,7 +33,7 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional
 
 from _common import STATE, add_common, apply_common, child_args, die, emit, info, run_tool, MEDIA_EXT as _MEDIA_EXT
-from _common.runner import HW_FORCED_ENV, _OutputLock, add_hw_orchestrator_args, env_hw, stop_children
+from _common.runner import HW_FORCED_ENV, _OutputLock, add_hw_orchestrator_args, copy_to_sibling, env_hw, stop_children
 from _common.emit import absorb_stage_hw, audit, note, shown, steps_encoder_report, warn
 
 HERE = Path(__file__).resolve().parent
@@ -265,16 +265,18 @@ def deliver(src: str, final: Path) -> None:
         except OSError:
             # another filesystem: copy beside the final path and rename, so a copy that fails part
             # way never leaves a truncated file where the caller's was
-            import shutil
-            tmp = final.with_name(f".{final.stem}.ffskill-{os.getpid()}-{threading.get_ident()}{final.suffix}")
+            # created exclusively and written through the descriptor that created it: never through
+            # an entry planted at the name, and two threads delivering side by side get two names
+            tmp = None
             try:
-                shutil.copyfile(src, tmp)
+                tmp = copy_to_sibling(str(src), str(final))
                 os.replace(tmp, final)
             except OSError as exc:
-                try:
-                    os.remove(tmp)
-                except OSError:
-                    pass
+                if tmp:
+                    try:
+                        os.remove(tmp)
+                    except OSError:
+                        pass
                 raise ItemError({"step": None, "tool": None, "kind": "output",
                                  "message": f"could not deliver {src} to {final}: {exc}"})
     log(f"  delivered the last written file to {final}")

package/scripts/caption.py

@@ -926,8 +926,8 @@ def mux_subtitle_codec(output: str) -> str:
 
 def ass_color(hex_rgb: str, alpha: int = 0) -> str:
     h = hex_rgb.lstrip("#")
-    if len(h) != 6:
-        die(f"colour must be RRGGBB hex, got '{hex_rgb}'")
+    if len(h) != 6 or any(c not in "0123456789abcdefABCDEF" for c in h):
+        die(f"colour must be six hex digits RRGGBB, got '{hex_rgb}'")
     r, g, b = h[0:2], h[2:4], h[4:6]
     return f"&H{alpha:02X}{b}{g}{r}".upper()
 

package/scripts/export.py

@@ -51,7 +51,7 @@ from _common import STATE, run_analysis, add_common, apply_common, bt709_label_f
 from _common.decision import hw_preset_video, restate_last_swap
 from _common.emit import note, record_fallback, record_skip, warn
 from _common.probe import square_pixels, square_pixels_note
-from _common.runner import ffmpeg_encoders, guard_sidecar, remember_written, run_analysis as _run_analysis, subtitle_codec_for
+from _common.runner import ffmpeg_encoders, guard_sidecar, remember_written, reserve_sibling, run_analysis as _run_analysis, subtitle_codec_for
 from _common.emit import file_identity
 from check import SPECS as PLATFORMS, measure_loudness
 from _platforms import ALIASES as _ALIASES, PLATFORMS as PLATFORM_TABLE, TP_TOLERANCE_DB, resolve as resolve_platform
@@ -213,7 +213,7 @@ def _key_fill(args, p: Dict, meta: Dict, output: str, cmd: List[str], vf: List[s
     if not STATE.dry_run:
         d, base = os.path.split(output)
         stem, ext = os.path.splitext(base)
-        fill_tmp = os.path.join(d, f".{stem}.ffskill-fill-{os.getpid()}{ext}")
+        fill_tmp = reserve_sibling(d, stem, ext, "fill")  # created exclusively: never through a planted link
     cmd += (p["audio"] if has_audio else ["-an"]) + [fill_tmp or output]
     cmd += ["-map", "[key]"] + p["video"] + tc_args + cfr_args(meta) + ["-an", key]
     try:

package/scripts/render.py

@@ -464,6 +464,64 @@ def check_overlay(ov: Any, label: str) -> None:
         die(f"{label}: scale sizes an image, logo or video layer; text size is font_size", kind="input")
 
 
+def project_input_files(proj: Dict[str, Any], rel: Any) -> List[str]:
+    """Every file a project names as an input: clip sources, music/replace/effects, the brand,
+    caption files (a --text value that names an existing file), overlay images, videos and fonts, the
+    audiogram image, a beat grid's source and the chapters file. Values of the wrong type are left
+    to the stage that reads them."""
+    found: List[str] = []
+
+    def add(value: Any, must_exist: bool = False) -> None:
+        if isinstance(value, str) and value:
+            p = rel(value)
+            if not must_exist or os.path.isfile(p):
+                found.append(p)
+
+    for c in proj.get("clips") or []:
+        if isinstance(c, dict):
+            add(c.get("src"))
+            if isinstance(c.get("snap"), dict):
+                add(c["snap"].get("source"))
+    for key in ("audio", "captions", "audiogram", "snap"):
+        if not isinstance(proj.get(key), dict):
+            continue
+        obj = proj[key]
+        if key == "audio":
+            for k in ("music", "replace", "effects"):
+                add(obj.get(k))
+        elif key == "captions":
+            add(obj.get("srt"))
+            add(obj.get("ass"))
+            add(obj.get("text"), must_exist=True)  # inline cue text is not a path
+        elif key == "audiogram":
+            add(obj.get("image"))
+        else:
+            add(obj.get("source"))
+    add(proj.get("brand"))
+    brand = proj.get("brand")
+    if isinstance(brand, str) and brand:
+        # the brand's own logo and font_file are read by the overlay and caption stages, resolved
+        # against the brand file as load_brand() resolves them; an unreadable brand is left to them
+        try:
+            data = json.loads(Path(rel(brand)).read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            data = None
+        if isinstance(data, dict):
+            base = Path(rel(brand)).resolve().parent
+            for k in ("logo", "font_file"):
+                v = data.get(k)
+                if isinstance(v, str) and v and "://" not in v:
+                    found.append(v if os.path.isabs(v) else str(base / v))
+    add(proj.get("chapters"), must_exist=True)
+    overlays = proj.get("overlays")
+    for ov in (overlays if isinstance(overlays, list) else []):  # any other type is the overlay stage's to refuse
+        if isinstance(ov, dict):
+            add(ov.get("image"))
+            add(ov.get("video"))
+            add(ov.get("font_file"))
+    return found
+
+
 def require_object(obj: Any, label: str) -> None:
     """Refuse a value that is not an object where the run reads it with .get(): "export": "reels"
     in a render, a string frame, a clip written as a bare path. 2.2.1 died there with a traceback
@@ -1216,8 +1274,13 @@ def main() -> int:
     if not clips:
         die("project.clips is empty")
     output = rel(proj.get("output") or "final.mp4")
-    # the final stage is a copy from the work dir, so run()'s own guard never sees the sources (review 5)
-    refuse_output_is_input(output, *[rel(c.get("src")) for c in clips if c.get("src")])
+    # the final stage is a copy from the work dir, so run()'s own guard never sees the sources
+    # (review 5): every file the project names is passed here, not only the clips, or --overwrite
+    # replaced a music bed or a brand file named as the output
+    if not args.stop_after or args.stop_after == "export":
+        # only a run that ends in the final copy writes `output`; a --stop-after preview writes
+        # its stage file inside the work directory and leaves `output` alone
+        refuse_output_is_input(output, *([os.path.abspath(args.project)] if args.project else []), *project_input_files(proj, rel))
     if _reaches("overlays", args.stop_after):
         # #326: an overlay video is the caller's file, never an earlier stage's output, so a
         # missing one is refused here, under --dry-run too, not after every stage before it ran
@@ -1396,7 +1459,12 @@ def main() -> int:
                           ("color", "--color"), ("background", "--background"),
                           ("width", "--width"), ("height", "--height"), ("fps", "--fps")):
             if ag.get(key) is not None:
-                argv += [flag, str(ag[key])]
+                value = ag[key]
+                if key == "image" and isinstance(value, str) and "://" not in value:
+                    # against the project file, as every other path here and as the output guard
+                    # checks it; it used to reach waveform.py as written, against the cwd
+                    value = rel(value)
+                argv += [flag, str(value)]
         argv += brand_args
         sh("waveform.py", *argv, stage="audiogram")
         current = nxt
@@ -1542,7 +1610,8 @@ def main() -> int:
         for k, flag in (("position", "--position"), ("start", "--start"), ("end", "--end"), ("fade", "--fade"), ("opacity", "--opacity"), ("scale", "--scale"), ("font_size", "--font-size"), ("font", "--font"), ("font_file", "--font-file"), ("margin", "--margin"), ("platform", "--platform"),
                         ("chromakey", "--chromakey"), ("chromakey_similarity", "--chromakey-similarity"), ("chromakey_blend", "--chromakey-blend")):
             if ov.get(k) is not None:
-                argv += [flag, str(ov[k])]
+                # font_file is a path: the same one project_input_files() guards
+                argv += [flag, rel(ov[k]) if k == "font_file" and ov[k] else str(ov[k])]
         if ov.get("box"):
             argv.append("--box")
         # review 12: the overlay stage was the one stage that never heard which destination this

package/scripts/silence.py

@@ -10,6 +10,8 @@ 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)
 """
@@ -59,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]]]":
@@ -312,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":
@@ -466,6 +539,13 @@ def main() -> int:
                     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 "
@@ -496,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)")
@@ -543,6 +623,19 @@ def main() -> int:
     # 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",
@@ -558,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, tail, lead) + 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
@@ -582,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, tail, lead)), 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 = {
@@ -592,11 +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:
+    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 alone, which detects no silences and so applies neither.
+        # 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:
@@ -628,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)")