ffmpeg-skill 3.8.2 → 3.8.4

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.4`) | 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.4", "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.4",
   "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/broll.py

@@ -21,7 +21,7 @@ import argparse
 import sys
 from typing import Any, Dict, List
 
-from _common.decision import av_trim, conform_output_t, conform_to_length, frame_rate, grid_at_or_after, stream_starts
+from _common.decision import av_trim, conform_output_t, conform_to_length, frame_rate, grid_at_or_after, silence_filter, stream_starts
 from _common import STATE, add_common, aac_args, apply_common, cfr_args, as_limited, default_output, die, draws_chroma, drawn_chain, emit, ffmpeg_base, info, time_arg, label_chain, matrix_chain, overlay_format, range_chain, probe, run, validate_color, video_args, X264_PRESETS, fmt_secs
 from _common.emit import note, record_fallback
 from _common.probe import display_size, square_pixels, square_pixels_note
@@ -162,8 +162,14 @@ def main() -> int:
                 # sample moved a track that starts 0.3 s late 0.279 s early (#409)
                 v0b = stream_starts(c["meta"])[0]
                 first = max(v0b, grid_at_or_after(c["from"], v0b, frame_rate(c["meta"])))
+                # the delay is --at to the sample of the mix's rate: `int(at * 1000)` cut 1.001 to
+                # 1000 ms and wrote 1.2346 s as 1234 ms, the cutaway's sound 48 and 29 samples
+                # early. A whole millisecond keeps the text it had, rounded (silence_filter)
+                delay = silence_filter(MIX_RATE, lead=c["at"])
+                if "S:" not in delay:
+                    delay = f"adelay={round(c['at'] * 1000)}|{round(c['at'] * 1000)}"
                 parts.append(f"[{i + 1}:a:0]{av_trim(first, first + c['length'])[1]},"
-                             f"aformat=sample_rates=48000:channel_layouts=stereo,adelay={int(c['at'] * 1000)}|{int(c['at'] * 1000)}[ab{i}]")
+                             f"aformat=sample_rates=48000:channel_layouts=stereo,{delay}[ab{i}]")
                 layers.append(f"[ab{i}]")
             # the mix ends with the A-roll, to the sample (#493): every layer is 48 kHz, so the count
             # is in that rate. `atrim=duration={:.3f}` and `-t {:.3f}` cut it to the millisecond. A

package/scripts/fit.py

@@ -39,7 +39,7 @@ import sys
 from fractions import Fraction
 from typing import List
 
-from _common.decision import SEEK_MARGIN, delivered_rate, frame_rate, grid_at_or_after, stream_starts
+from _common.decision import SEEK_MARGIN, delivered_rate, frame_rate, grid_at_or_after, length_output_t, stream_starts
 from _common.timeline import exact_rate, output_timecode_args
 from _common import video_args, STATE, add_common, apply_common, emit, aac_args, aspect_ratio, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, pad_filters, add_pad_fill_args, X264_PRESETS, time_arg, fmt_secs, frame_size, display_size, square_pixels, square_pixels_note, note
 from _common.emit import input_length
@@ -162,6 +162,12 @@ def main() -> int:
         # (#491). Not under --dry-run, where render.py plans a clip's speed stage on the source in
         # place of a cut that does not exist yet and records the stand-in itself (A97)
         src_dur = (meta.get("duration") or 0.0) if STATE.dry_run else input_length(meta)
+        # The output's -t is all that ends the kept track where the source's sound runs on past
+        # the target (a trim; a speed change too small to retime), so it is written to the sample
+        # of that track's rate, not to the millisecond: `-t 1.234` wrote 59244 samples (48 kHz)
+        # as 59232 and `-t 1.235` wrote 59261 as 59280 (length_output_t). No sound, or a dry
+        # run's pending input, has no rate and keeps the millisecond.
+        rate = (audio_streams[args.audio_stream].get("sample_rate") if has_audio and audio_streams else None)
         if args.method == "speed":
             if src_dur <= 0 and STATE.dry_run:
                 src_dur = target  # planning against an intermediate that does not exist yet
@@ -178,7 +184,9 @@ def main() -> int:
                     vf.append("tblend=all_mode=average")
                 if has_audio:
                     af.append(atempo_chain(factor))
-            post += ["-t", f"{target:.3f}"]
+            # atempo's sound ends before the target (13 to 62 ms before it on FFmpeg 6.1.1), so the
+            # millisecond cuts nothing off a retimed track and stays
+            post += ["-t", f"{target:.3f}" if af else length_output_t(target, rate, runs_on=True)]
             STATE.duration_hint = target
         else:
             if target < src_dur:
@@ -189,7 +197,7 @@ def main() -> int:
                 # picture would not be the one the start timecode below names
                 m = min(SEEK_MARGIN, round(start, 3))
                 pre_input += ["-ss", f"{start - m:.3f}"]
-                post += (["-ss", f"{m:.3f}"] if m > 0 else []) + ["-t", f"{target:.3f}"]
+                post += (["-ss", f"{m:.3f}"] if m > 0 else []) + ["-t", length_output_t(target, rate, runs_on=True)]
                 # the output starts on the first frame at or after the seek (a seek before a
                 # picture that starts after the file's origin: on its first frame): its start
                 # timecode is that frame's, not the source's first frame's

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, silence_filter, stream_starts
 from _common.timeline import output_timecode_args
 from _common.runner import default_selection_maps
 from _common.emit import input_length
@@ -377,9 +377,17 @@ def main() -> int:
             # its length instead of -shortest, which cut the reference's tail whenever the second
             # file started earlier (head_trim > 0) or was simply shorter
             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"]
+            # the delay is the measured offset to the sample of the second's rate: at the default
+            # --fine-ms 1 without --fix-drift the offset is a whole millisecond and the text is the
+            # one it was; a finer step (0.25 ms: 0.23425 s) or a drift-adjusted offset (kept to
+            # 0.1 ms) was rounded to `adelay=234` (silence_filter)
+            lead = [silence_filter(sec_sr, lead=offset)] if offset > 0 and round(offset * sec_sr) else []
+            af_parts = on_clock + drift_af + lead + ["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]