ffmpeg-skill 3.8.2 → 3.8.3

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.8.2`) | any release |
+| `skill.version` | the npm / package.json version (`3.8.3`) | 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.8.2", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "3.8.3", "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"},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "3.8.2",
+  "version": "3.8.3",
   "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/scripts/_common/__init__.py

@@ -74,7 +74,7 @@ from _common.probe import (
     display_size, pixel_aspect, square_pixels, square_pixels_note
 )
 from _common.decision import (
-    aac_args, add_pad_fill_args, conform_filter, conform_to_length, conform_output_t, aspect_ratio, audio_codec_for, AUDIO_CODECS, brand_caption_style, BRAND_DEFAULTS,
+    aac_args, add_pad_fill_args, conform_filter, conform_to_length, conform_output_t, length_output_t, silence_filter, aspect_ratio, audio_codec_for, AUDIO_CODECS, brand_caption_style, BRAND_DEFAULTS,
     description_block, _evidence_rank, fmt_chapter_time, propose_chapters,
     frame_flow, label_shot_flow, MOTION_GRID, MOTION_SEARCH, MOTION_STATIC_PX, MOTION_PAN_SPREAD,
     filler_spans, FILLER_WORDS, FILLER_AMBIGUOUS, FILLER_DISCOURSE_MARKERS, FILLER_MAX_WORD,

package/scripts/_common/decision.py

@@ -456,6 +456,62 @@ def conform_output_t(length: float, rate: int) -> str:
     return f"{length + 0.5 / rate:.6f}"
 
 
+def length_output_t(length: float, rate: Optional[int], runs_on: bool = False) -> str:
+    """The output `-t` of a tool that leaves the sound's end to it (overlay.py, waveform.py,
+    loop.py, sync.py --replace-audio): the millisecond text they always wrote unless it cuts
+    samples off the track at `rate` (`-t 1.234` wrote 59244 samples at 48 kHz as 59232), and then
+    the length to the microsecond, which FFmpeg rounds to the nearest sample. `runs_on` is for
+    sound that goes on past the length (an endless apad, a loop's next repeat): there the
+    millisecond text is also left when it rounds up (`-t 1.235` wrote 59261 as 59280). No half
+    sample of slack as in conform_output_t(): this `-t` ends the picture too, and with the slack a
+    layer's frame that starts exactly at the end came through on a 1/60000 or 1/90000 time base
+    (FFmpeg 6.1.1). A rate of 0 or None (no sound, a dry run's pending input) keeps the
+    millisecond text."""
+    text = f"{length:.3f}"
+    if rate:
+        def names(micro: int) -> int:
+            # the samples FFmpeg makes of a -t of `micro` microseconds: a rescale that rounds a
+            # half up, where Python's round() takes it to the even count (0.005 s at 44.1 kHz is
+            # 220.5 samples: 221 written, round() says 220)
+            return (micro * rate + 500_000) // 1_000_000
+        written, asked = names(round(float(text) * 1_000_000)), round(length * rate)
+        if written < asked or (runs_on and written != asked):
+            # the microsecond text is a rounding too (2.00001042 s is 96001 samples at 48 kHz and
+            # "2.000010" names 96000): the microsecond nearest the length, moved by whole
+            # microseconds until it names the count asked. A microsecond is a twentieth of a
+            # sample at 48 kHz, so this is a step or two, not conform_output_t()'s half sample
+            micro = round(length * 1_000_000)
+            while names(micro) < asked:
+                micro += 1
+            while names(micro) > asked:
+                micro -= 1
+            return f"{micro // 1_000_000}.{micro % 1_000_000:06d}"
+    return text
+
+
+def silence_filter(rate: Optional[int], lead: Optional[float] = None, tail: Optional[float] = None) -> str:
+    """Silence of `lead` seconds ahead of a track and/or `tail` seconds after it (pad.py,
+    freeze.py). An amount in whole milliseconds is written as it always was (`adelay=MS:all=1`,
+    `apad=pad_dur=S.mmm`), the millisecond rounded, not cut: int(1.001 * 1000) is 1000. One that
+    is not is counted in samples at `rate`, pinned by an aformat as in conform_filter():
+    `adelay=234` and `apad=pad_dur=0.234` for 0.23425 s left the sound 12 samples short at 48 kHz.
+    A rate of 0 or None (a dry run's pending input) keeps the millisecond form."""
+    amounts = [v for v in (lead, tail) if v is not None]
+    if rate and any(round(v * rate) != round(round(v, 3) * rate) for v in amounts):
+        parts = [f"aformat=sample_rates={rate}"]
+        if lead:
+            parts.append(f"adelay={round(lead * rate)}S:all=1")
+        if tail:
+            parts.append(f"apad=pad_len={round(tail * rate)}")
+        return ",".join(parts)
+    parts = []
+    if lead is not None:
+        parts.append(f"adelay={round(lead * 1000)}:all=1")
+    if tail is not None:
+        parts.append(f"apad=pad_dur={tail:.3f}")
+    return ",".join(parts)
+
+
 def av_clip_length(meta: Optional[Dict[str, Any]], fps: float) -> float:
     """The one length a clip holds once both streams start at its first frame (av_trim from the
     video's start): the video's, or where the sound ends when it runs more than a frame past the

package/scripts/freeze.py

@@ -19,7 +19,7 @@ Examples:
 import argparse
 import sys
 
-from _common.decision import av_trim, frame_durations, frame_rate, grid_at_or_after, stream_starts
+from _common.decision import av_trim, frame_durations, frame_rate, grid_at_or_after, silence_filter, stream_starts
 from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, video_args, X264_PRESETS, MissingFpsError, time_arg, fmt_secs, run
 from _common.emit import input_length
 
@@ -73,7 +73,7 @@ def main() -> int:
         vf = f"tpad=stop_mode=clone:stop_duration={args.hold:.3f}"
         cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf, "-map", "0:v:0"]
         if has_audio:
-            cmd += ["-map", "0:a:0?", "-af", f"apad=pad_dur={args.hold:.3f}"]
+            cmd += ["-map", "0:a:0?", "-af", silence_filter(meta["audio"].get("sample_rate"), tail=args.hold)]
     elif at == 0 or cut_at <= v0 + 1e-6:
         # A freeze at the very start has no preceding "head" segment to hold on to (the
         # split/trim/concat approach below needs a non-empty head, which trim=end=0 can't give
@@ -82,7 +82,7 @@ def main() -> int:
         vf = f"tpad=start_mode=clone:start_duration={args.hold:.3f}"
         cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf, "-map", "0:v:0"]
         if has_audio:
-            cmd += ["-map", "0:a:0?", "-af", f"adelay={int(args.hold * 1000)}:all=1"]
+            cmd += ["-map", "0:a:0?", "-af", silence_filter(meta["audio"].get("sample_rate"), lead=args.hold)]
     else:
         # freeze N frames at `at` by holding on that one source frame for --hold seconds, then
         # resuming the rest of the clip: split the timeline at `at` and hold the remainder's

package/scripts/loop.py

@@ -34,7 +34,7 @@ import tempfile
 
 from _common import STATE, concat_list_line, add_common, aac_args, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, parse_time, probe, refuse_output_is_input, require_filter, require_tool, run, video_args, X264_PRESETS, time_arg, fmt_secs
 from _common.emit import warn
-from _common.decision import av_trim
+from _common.decision import av_trim, length_output_t
 from _common.probe import decode_gray_frames, decode_pcm_mono
 from _common.emit import input_length
 
@@ -320,7 +320,8 @@ def main() -> int:
         else:
             cmd += ["-map", "0:v:0", "-vf", vtrim]
     if target is not None:
-        cmd += ["-t", f"{target:.3f}"]
+        # the sound ends at --duration to the sample, not to the millisecond (length_output_t)
+        cmd += ["-t", length_output_t(target, (meta.get("audio") or {}).get("sample_rate") if has_audio else None, runs_on=True)]
     cmd += video_args(meta, args.crf, args.preset)
     # a crossfade's repeat is already constant at `rate` (its graph's fps=): the loop keeps that rate,
     # not a variable-rate source's average, which re-timed every repeat by a frame or two

package/scripts/overlay.py

@@ -38,6 +38,7 @@ from _common import still_input_args  # noqa: E402
 from _common import STATE, script_font_for_text, drawtext_clean, drawtext_line_metrics, drawtext_text_opts, drawtext_draws_newline_glyph, is_multiline, needs_shaping, LANGUAGE_NAMES, has_emoji, detect_script, emoji_clusters, load_brand, drawn_chain, label_chain, layer_base_chain, matrix_chain, overlay_format, range_chain, rgb_chain_to_bt709, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_drawtext, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, X264_PRESETS, time_arg, fmt_secs
 from _common.emit import note, warn
 from _common.color import is_rgb
+from _common.decision import length_output_t
 from _common.alpha import (add_alpha_args, audio_line, check_alpha_args, decoder_args_for, default_ext, finish_chain,
                            has_alpha_plane, report as alpha_report, source_alpha, source_format, tag_args, video_line)
 from _common.probe import display_size, square_pixels, square_pixels_note
@@ -362,6 +363,10 @@ def main() -> int:
         die(f"--audio-stream {args.audio_stream}: input has {len(audio_streams)} audio stream(s), 0..{len(audio_streams) - 1}")
     if args.audio_stream and not audio_streams:
         die("--audio-stream needs an input with audio streams")
+    # the -t that ends a layer at the main input's length: to the sample of the kept track when the
+    # millisecond would cut it (length_output_t); no sound, or a pending input, keeps the millisecond
+    kept_track = audio_streams[args.audio_stream] if audio_streams else (meta.get("audio") or {})
+    main_t = length_output_t(meta["duration"], kept_track.get("sample_rate")) if meta.get("duration") else None
     # ffmpeg applies display rotation before the filter graph, so the frame this overlay is
     # composited on is the displayed one. A 320x180 phone file tagged 90 degrees is 180 wide here.
     # A non-square-pixel source is made square at its display aspect first (#411), so a logo or
@@ -454,7 +459,7 @@ def main() -> int:
             # streams -- a preserved subtitle/data stream that ends earlier (run_keeping_subtitles)
             # must not be allowed to cut the whole output short via -shortest's "stop at whichever
             # mapped stream finishes first" semantics.
-            cmd += ["-t", f"{meta['duration']:.3f}"]
+            cmd += ["-t", main_t]
         else:
             # No known duration to bound by -t (e.g. probe found no video duration): -shortest is
             # the only thing stopping the looped still from running forever. FFmpeg 7+'s
@@ -567,7 +572,7 @@ def main() -> int:
         if meta.get("duration"):
             # See the --image branch above: -t (exact, bounds only the main input) instead of
             # -shortest (would also stop at a preserved subtitle/data stream that ends earlier).
-            cmd += ["-t", f"{meta['duration']:.3f}"]
+            cmd += ["-t", main_t]
         else:
             cmd += ["-shortest"]
     else:

package/scripts/pad.py

@@ -17,6 +17,7 @@ import argparse
 import sys
 
 from _common.emit import record_fallback
+from _common.decision import silence_filter
 from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, drawn_chain, emit, EVEN_SCALE, ffmpeg_base, info, probe, run_keeping_subtitles, validate_color, video_args, X264_PRESETS, time_arg, fmt_secs, run
 
 
@@ -64,7 +65,8 @@ def main() -> int:
             # front (one -filter_complex), so the record is made here, as broll and stabilize do
             record_fallback(f"{args.input} is {v.get('width')}x{v.get('height')}: scaled to even dimensions first",
                             "odd_dimensions_scaled_even", output=output, scale=EVEN_SCALE)
-        af = f"adelay={int(args.start * 1000)}:all=1,apad=pad_dur={args.end:.3f}"
+        # the silence is counted in samples when --start/--end is not a whole millisecond
+        af = silence_filter(meta["audio"].get("sample_rate"), args.start, args.end)
         cmd += ["-filter_complex", f"[0:v:0]{even}{vf}[v];[0:a:0]{af}[a]", "-map", "[v]", "-map", "[a]"]
     else:
         cmd += ["-vf", vf, "-map", "0:v:0"]

package/scripts/sync.py

@@ -35,7 +35,7 @@ from typing import Dict, List
 from _common.runner import fail_if_classified
 from _common import video_args, add_common, apply_common, emit, aac_args, audio_codec_for, default_output, die, ffmpeg_base, info, probe, require_tool, run, run_analysis, x264_args, decode_pcm_mono, rms_envelope
 from _common.emit import record_skip, warn
-from _common.decision import SEEK_MARGIN, frame_rate, grid_at_or_after, stream_starts
+from _common.decision import SEEK_MARGIN, frame_rate, grid_at_or_after, length_output_t, stream_starts
 from _common.timeline import output_timecode_args
 from _common.runner import default_selection_maps
 from _common.emit import input_length
@@ -379,7 +379,10 @@ def main() -> int:
             ref_dur = probe(args.reference).get("duration")
             af_parts = on_clock + drift_af + ([f"adelay={delay_ms}:all=1"] if delay_ms > 0 else []) + ["apad"]
             cmd += ["-af", ",".join(af_parts)]
-            cmd += aac_args() + (["-t", f"{ref_dur:.3f}"] if ref_dur else ["-shortest"]) + [output]
+            # to the sample of the rate the second's sound is written at, not to the millisecond:
+            # the endless apad is ended by this -t alone (length_output_t)
+            ref_t = length_output_t(ref_dur, (second_meta.get("audio") or {}).get("sample_rate"), runs_on=True) if ref_dur else None
+            cmd += aac_args() + (["-t", ref_t] if ref_dur else ["-shortest"]) + [output]
             proc = run(cmd, check=False)
             fail_if_classified(proc)  # a cause the re-encode would hit too is reported, not retried (#415)
             if proc.returncode != 0:

package/scripts/waveform.py

@@ -41,6 +41,7 @@ from _common import (add_common, apply_common, aac_args, default_output, die, dr
                      info, load_brand, pad_filters, probe, rgb_chain_to_bt709, run, STATE, validate_color, video_args, X264_PRESETS,
                      fmt_secs, child_args, run_tool, measured_level_dbfs, sibling_temp)
 from _common.emit import absorb_stage_hw, note, warn
+from _common.decision import length_output_t
 
 WAVEFORM_MODES = ["point", "line", "p2p", "cline"]
 
@@ -232,7 +233,9 @@ def main() -> int:
     # audio ends (a 12 s source came out 14.08 s on 5.1.1, #146), so the output is also capped
     # at the source's own duration when probe knows it.
     if meta.get("duration"):
-        cmd += ["-t", f"{float(meta['duration']):.3f}"]
+        # to the sample of the drawn track when the millisecond would cut it (length_output_t)
+        drawn_track = audio_streams[args.audio_stream] if audio_streams else meta["audio"]
+        cmd += ["-t", length_output_t(float(meta["duration"]), drawn_track.get("sample_rate"))]
     cmd += ["-shortest", render]
     titled_tmp = sibling_temp(output, "titled")
     intermediates = [p for p in (render, titled_tmp) if p != output]