ffmpeg-skill 3.4.2 → 3.5.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.2`) | any release |
+| `skill.version` | the npm / package.json version (`3.5.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.2", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "3.5.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,7 @@ 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 |
 | `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.2",
+  "version": "3.5.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,7 @@ 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] [--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,7 +713,11 @@ 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.
 

package/scripts/_contract.py

@@ -652,6 +652,7 @@ 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"},
                  "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,7 @@ 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 --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)
 """
@@ -83,9 +84,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 +98,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
@@ -455,6 +459,13 @@ 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("--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 "
@@ -525,6 +536,13 @@ 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
     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",
@@ -549,7 +567,7 @@ def main() -> int:
     # 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(inside_margin(silences, duration, tail, lead) + 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 +582,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(inside_margin(silences, duration, tail, lead)), 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 +592,11 @@ def main() -> int:
         "kept_duration": round(kept, 3),
         "removed_seconds": round(silence_only, 3),
     }
+    if silences or not args.filler or args.speech_aware:
+        # 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.
+        summary["margins"] = {"lead": lead, "tail": tail}
     if kinds:
         summary.update(kinds)
     if args.speech_aware:
@@ -641,7 +664,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: