ffmpeg-skill 3.8.22 → 3.8.23

package/docs/contract.md

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

@@ -175,7 +175,9 @@ the next source frame and may keep up to one frame of timestamp. A `.mp4`/`.mov`
 edit list hides the priming. A source whose audio starts after its picture keeps
 that offset. An audio-only `--accurate` cut
 still uses `make_zero`; that priming is what `precision: codec_frame` counts
-in the length. Since 3.0.0 `keyframe_snapped` equals `start_snapped` (2.x: true
+in the length, and it pads a sound that starts after `--start` with silence. A stream copy to an audio output
+cannot: it starts at the sound's first packet, and an `audio_lead_dropped` warning (`{seconds,
+segments}`) says how much silence it left out (from one frame of the picture on). Since 3.0.0 `keyframe_snapped` equals `start_snapped` (2.x: true
 for every stream copy, `precision` `packet`); `start_snapped` is measured: true when a copied picture starts more
 than a frame from `--start`, or when its start could not be measured (an unknown start is
 never claimed exact); `null` under `--dry-run`.
@@ -344,7 +346,10 @@ the rectangle for you. Use this when the rectangle is already known (a
 face-detection box, a saved crop, a hand-picked region). The rectangle must
 lie entirely inside the source frame (after accounting for display rotation);
 `--width`/`--height` must be even (4:2:0 chroma) and are refused, never
-rounded, if they aren't; an odd `--x`/`--y` is taken as given.
+rounded, if they aren't; an odd `--x`/`--y` is taken as given. The source's
+subtitle track is kept (converted to mov_text in MP4/MOV, SubRip in Matroska);
+`dropped_non_av_streams: true` says it was dropped: the container refused it, or
+refused a data stream beside it (a timecode track), and the retry drops both.
 
 ### cropdetect.py — measure black bars, report the crop rectangle
 ```
@@ -515,7 +520,8 @@ default, keeps the original framing and lets the edges show: vidstab's own
 "optimal zoom" is off). Needs an ffmpeg built with
 `--enable-libvidstab`; `doctor` reports this tool `usable: no` when that's
 missing (a plain Homebrew ffmpeg build, for example) rather than failing at
-run time.
+run time. The frames keep their times, so the source's subtitle track is kept
+as `crop.py` keeps it (`dropped_non_av_streams` says when it could not be).
 
 ### sequence.py — numbered/globbed image sequence to video
 ```

package/scripts/_common/runner.py

@@ -2813,6 +2813,30 @@ def default_selection_maps(meta: Optional[Dict[str, Any]], dst: str) -> List[str
     return maps
 
 
+def subtitle_codec_args(src: Optional[str], output: str) -> List[str]:
+    """`-c:s` for a command that maps every subtitle stream of `src` (`-map 0:s?`) into `output`:
+    copy, and for each text track in a format the container does not take as it is the container's
+    own (subtitle_codec_for: mov_text in MP4/MOV, SubRip in Matroska for mov_text, WebVTT in WebM),
+    as export.py and a crop of several tracks convert it. A plain copy of SubRip into MP4 failed,
+    and the retry dropped the track (#520). Copy alone when the source cannot be read here."""
+    args = ["-c:s", "copy"]
+    if not src or not os.path.isfile(src):
+        return args
+    try:
+        out = subprocess.run([found_exe("ffprobe"), "-v", "error", "-select_streams", "s", "-show_entries",
+                              "stream=codec_name", "-of", "csv=p=0", *still_input_args(src), src],
+                             stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, encoding="utf-8",
+                             errors="replace", timeout=_probe_limit()).stdout
+    except (OSError, subprocess.TimeoutExpired):
+        return args
+    ext = os.path.splitext(output)[1]
+    for n, codec in enumerate(ln.strip() for ln in (out or "").splitlines() if ln.strip()):
+        conv = subtitle_codec_for(codec, ext)
+        if conv != "copy":
+            args += [f"-c:s:{n}", conv]
+    return args
+
+
 def run_keeping_subtitles(cmd: List[str], output: str, relabel_timecode: bool = False) -> bool:
     """Run an ffmpeg command that already maps its video/audio, trying first to also
     stream-copy any subtitle/data streams the source has (`-map 0:s?`/`0:d?` are no-ops when
@@ -2821,6 +2845,8 @@ def run_keeping_subtitles(cmd: List[str], output: str, relabel_timecode: bool =
     extra maps rather than let a tool that never touched subtitles start hard-failing because of
     them. `cmd` is the full argv *without* the output path. Returns True only when the
     retry-without-subtitles path was actually needed (i.e. subtitle/data streams were dropped).
+    A text track the container takes in another format is converted (subtitle_codec_args), so the
+    retry is left for a track no conversion fits (a bitmap track in MPEG-4) or a refused data stream.
 
     The retry is recorded with the first attempt's error (`diagnostics.fallbacks`,
     `non_av_streams_dropped`): the caller's `dropped_non_av_streams` says that streams went, the
@@ -2833,7 +2859,7 @@ def run_keeping_subtitles(cmd: List[str], output: str, relabel_timecode: bool =
     skip_tmcd = ["-map", "-0:d:m:timecode"] if relabel_timecode else []
     src = next((str(cmd[i + 1]) for i, a in enumerate(cmd[:-1]) if a == "-i"), None)
     first = run(cmd + ["-map", "0:s?", "-map", "0:d?"] + skip_tmcd + carried_stream_maps(src, output)
-                + ["-c:s", "copy", "-c:d", "copy", output], check=False)
+                + subtitle_codec_args(src, output) + ["-c:d", "copy", output], check=False)
     if first.returncode == 0:
         return False
     if classify_ffmpeg_failure(first.stderr or "") or not _has_non_av_streams(cmd):

package/scripts/_contract.py

@@ -495,6 +495,7 @@ DIAGNOSTIC_CODES = {
     "hdr10_metadata_dropped": ("warnings", "a PQ output measured without the source's HDR10 mastering-display and/or content-light metadata (an encoder with no option for it, e.g. prores_ks or libaom on FFmpeg before 7); {dropped, codec}"),
     "source_items_dropped": ("warnings", "the written file lacks a subtitle track, chapters, a cover picture, surround channels, attached files or a second video stream the first input carried (source_carry lists everything kept and dropped, tags included); not repeated for a subtitle track the tool already reports through dropped_non_av_streams; {dropped}"),
     "audio_tracks_dropped": ("warnings", "the source has more audio tracks than the output kept (the tools write one; cut.py also reports dropped_audio_streams). Not compared when two or more inputs have sound (grid --audio-from, a mix): which source the output carries is the tool's choice; {source, kept, dropped}"),
+    "audio_lead_dropped": ("warnings", "cut.py: an audio-only stream copy of a source whose sound starts after --start (by at least one frame of its picture) begins at the sound's first packet, so that much silence is left out and the extraction is early against the picture; kept as a copy within --tolerance, as a start that snaps is (--accurate pads it); a dry run reports it from the source, also where a run may re-encode instead (length_unjudged); {seconds: the total, segments: [{index, seconds}]}"),
     "grid_no_drawtext": ("fallbacks", "grid.py --label auto on a build without the drawtext filter: the cells were not labelled, as with --label none"),
     "scenes_sheet_no_drawtext": ("fallbacks", "scenes.py --sheet on a build without the drawtext filter: the sheet was drawn without timecode stamps, as with --no-timecode"),
     "look_no_drawtext": ("fallbacks", "look.py on a build without the drawtext filter: the sheet was drawn without timecode stamps, as with --no-timecode"),
@@ -616,9 +617,9 @@ FONT_USED_SCHEMA = {
 
 
 # the tools whose --json carries `dropped_non_av_streams` (a test reads the sources)
-NON_AV_STREAM_TOOLS = frozenset({"audio", "broll", "color", "cut", "deinterlace", "denoise", "export", "fit", "freeze",
+NON_AV_STREAM_TOOLS = frozenset({"audio", "broll", "color", "crop", "cut", "deinterlace", "denoise", "export", "fit", "freeze",
                                  "graphics", "join", "loudness", "overlay", "pad", "proxy", "redact", "speedramp",
-                                 "sphere", "straighten"})
+                                 "sphere", "stabilize", "straighten"})
 
 
 # Top-level keys a tool emits that its own branch in output_schema() does not list (#466 A194: the

package/scripts/crop.py

@@ -22,9 +22,8 @@ Examples:
 import argparse
 import sys
 
-from _common import add_common, apply_common, aac_args, cfr_args, with_cfr, default_output, die, emit, ffmpeg_base, info, probe, run, video_args, X264_PRESETS, fmt_secs
-from _common.probe import display_size, square_pixels, square_pixels_note
-from _common.runner import default_selection_maps
+from _common import add_common, apply_common, aac_args, cfr_args, with_cfr, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, video_args, X264_PRESETS, fmt_secs
+from _common.probe import display_size, probed_maps, square_pixels, square_pixels_note
 from _common.emit import note
 
 
@@ -70,20 +69,21 @@ def main() -> int:
         vf.insert(0, square_pixels(meta["video"]))
         note(square_pixels_note(meta["video"]))
     # the picture the rectangle was checked against, not the largest one default selection takes
-    cmd = ffmpeg_base() + ["-i", args.input] + default_selection_maps(meta, output) + ["-vf", with_cfr(",".join(vf), meta, args.fps)]
+    cmd = ffmpeg_base() + ["-i", args.input] + probed_maps(meta) + ["-vf", with_cfr(",".join(vf), meta, args.fps)]
     cmd += video_args(meta, args.crf, args.preset)
     cmd += cfr_args(meta, args.fps)
     if has_audio:
         cmd += aac_args()
     else:
         cmd += ["-an"]
-    cmd.append(output)
-    run(cmd)
+    # the crop keeps the timeline, so the subtitle/data tracks are copied as fit.py and color.py copy
+    # them, and dropped (said) only where the container refuses them (#520)
+    dropped_streams = run_keeping_subtitles(cmd, output)
 
     result = probe(output, role="output")
     v = result["video"]
     info(f"wrote {output} ({fmt_secs(result['duration'])}, {v['width']}x{v['height']})")
-    emit(output)
+    emit(output, dropped_non_av_streams=dropped_streams)
     return 0
 
 

package/scripts/cut.py

@@ -449,6 +449,19 @@ def first_frame_from(src: str, meta: dict, start: float, reencode: bool, edit_li
     return key[0] - v0
 
 
+def copied_lead(meta: dict, start: float, end: float) -> Optional[float]:
+    """The seconds of a sound's late start that an audio-only stream copy of start..end leaves out
+    (#515): the copy begins at the first packet, so a sound that starts after `start` on the file's
+    clock (stream_starts) comes out that much early. None when it is less than one frame of the
+    source's picture (1 ms without one), which no picture could show, or when the start is unknown."""
+    audio = meta.get("audio") or {}
+    if not isinstance(audio.get("start_time"), (int, float)):
+        return None
+    lead = min(stream_starts(meta)[1], end) - start
+    fps = (meta.get("video") or {}).get("fps")
+    return round(lead, 6) if lead >= (1.0 / float(fps) if fps else 0.001) else None
+
+
 def av_skew(out_meta: dict, edit_list_remedy: bool = False, expected: float = 0.0):
     """(seconds audio starts after video, warning note or None); None when either is missing.
     A lossless cut can start its streams apart -- Core Media HEVC once gave 3.7 s of sound with no
@@ -1044,11 +1057,25 @@ def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: i
             info(f"stream copy landed on a keyframe {abs(got - dur):.2f}s away from the requested cut "
                  f"(> {tolerance:.2f}s tolerance); re-encoding this segment for accuracy{alt}")
             return _with_notes(cut_one(src, start, end, dst, True, crf, preset, tolerance, meta, reasons + ["tolerance"], edit_list_ok), notes)
-    if reencode or audio_only:
+    if audio_only and not reencode:
         # an audio-only copy is judged by its written length too (above): a dry run that wrote
         # nothing says a real run may still re-encode it (#510 review)
-        pending = {"length_unjudged": True} if (STATE.dry_run and not reencode and copy_t is None and tolerance >= 0) else {}
-        return _outcome(meta, dst, reencode, reasons, **pending)
+        pending = {"length_unjudged": True} if (STATE.dry_run and copy_t is None and tolerance >= 0) else {}
+        lead = copied_lead(meta, start, end)
+        if lead:
+            # a copy cannot add silence: the sound starts at its first packet, `lead` earlier than it
+            # sat after `start` (#515). Kept within --tolerance, as a start that snapped is, and said.
+            # A dry run says it for a lead of --tolerance or more too: the run judges the written
+            # length, which is short by up to a packet less than the lead (0.351 s for a lead of
+            # 0.355), so it may keep that copy; it re-encodes and pads it otherwise (#542 review)
+            unsure = STATE.dry_run and 0 <= tolerance <= lead
+            notes.append(f"the sound starts {lead:.3f}s after {start:.3f}s in the source; a stream copy cannot "
+                         f"add silence, so the extraction starts with the sound, {lead:.3f}s early against the "
+                         "picture (--accurate pads it from the start"
+                         + ("; a run re-encodes and pads it instead when the copy comes out --tolerance or more short)" if unsure else ")"))
+        return _outcome(meta, dst, False, reasons, notes=notes, audio_lead_dropped_seconds=lead or None, **pending)
+    if reencode:
+        return _outcome(meta, dst, reencode, reasons)
     if STATE.dry_run:
         # the planned copy: whether it keeps an edit list is known; where it lands is not, so a
         # real run that judges the written copy by its length may still re-encode it (#510)
@@ -1962,6 +1989,15 @@ def main() -> int:
                f"(cut writes one audio track, on a stream copy as on a re-encode)")
         warn(msg, "audio_tracks_dropped", source=len(src_audio), kept=kept, dropped=dropped_audio)
         notes.append(msg)
+    # a copied audio extraction that starts with the sound, not where it sat after --start (#515); an
+    # outcome a re-cut replaced carries none, so this is what the written file holds
+    leads = [(i + 1, o["audio_lead_dropped_seconds"]) for i, o in enumerate(outcomes) if o.get("audio_lead_dropped_seconds")]
+    if leads:
+        where = (f" (segment{'s' if len(leads) > 1 else ''} {', '.join(str(i) for i, _ in leads)})"
+                 if len(outcomes) > 1 else "")
+        warn(f"the stream copy left out {sum(s for _, s in leads):.3f}s of silence before the sound{where}, so the "
+             "sound is early against the source's picture; --accurate keeps it", "audio_lead_dropped",
+             seconds=round(sum(s for _, s in leads), 6), segments=[{"index": i, "seconds": s} for i, s in leads])
     emit(output, expected_duration=round(expected, 6), duration_error_ms=error_ms, precision=precision, reencoded=reencoded,
          expect_streams=expect_streams, stream_reference=[meta], stream_windows=[(s, e) for s, e in requested],
          dropped_non_av_streams=bool(DROPPED_STREAMS), dropped_audio_streams=max(dropped_audio, 0),

package/scripts/overlay.py

@@ -187,6 +187,12 @@ def enable_expr(start: Optional[float], end: Optional[float], meta: Optional[dic
     return window_expr(start, end, meta)
 
 
+def fade_out_length(start: float, end: float, fade: float) -> float:
+    """The fade-out of a layer shown from `start` to `end`: --fade, cut to the window when the window
+    is shorter, so the fade still ends at `end` (audio.py and cut.py cap theirs the same way)."""
+    return min(fade, end - start)
+
+
 def alpha_expr(opacity: float, start: Optional[float], end: Optional[float], fade: float) -> str:
     """Time-varying alpha with linear fade in/out inside [start, end]."""
     if fade <= 0 or (start is None and end is None):
@@ -195,8 +201,8 @@ def alpha_expr(opacity: float, start: Optional[float], end: Optional[float], fad
     parts = [f"{opacity:g}"]
     fin = f"min(1,(t-{s:.3f})/{fade:g})"
     parts.append(fin)
-    if end is not None:
-        parts.append(f"min(1,({end:.3f}-t)/{fade:g})")
+    if end is not None and end > s:
+        parts.append(f"min(1,({end:.3f}-t)/{fade_out_length(s, end, fade):g})")
     return "max(0," + "*".join(parts) + ")"
 
 
@@ -527,8 +533,12 @@ def main() -> int:
             # the common ask, and a matching fade-out at the very end surprised every eval run)
             s = start if start is not None else 0.0
             chain.append(f"fade=t=in:st={s:.3f}:d={args.fade:g}:alpha=1")
-            if end is not None and end > args.fade:
-                chain.append(f"fade=t=out:st={end - args.fade:.3f}:d={args.fade:g}:alpha=1")
+            if end is not None and end > s:
+                # a fade-out longer than the layer's window is cut to it, so the layer still leaves
+                # at --end fully faded (#517: with --end at or before --fade it was left out, and the
+                # layer vanished at full opacity); the text layer's alpha_expr() caps it the same way
+                out = fade_out_length(s, end, args.fade)
+                chain.append(f"fade=t=out:st={end - out:.3f}:d={out:g}:alpha=1")
         x, y = position_exprs(args.position, args.margin, text_mode=False, margins=safe_margins)
         grid = on_grid(x, y, (vw, vh), (lw, lh))
         if grid:

package/scripts/stabilize.py

@@ -27,9 +27,9 @@ import sys
 import tempfile
 from pathlib import Path
 
-from _common.probe import PROBED_VIDEO
-from _common.runner import ffmpeg_failure_extra, default_selection_maps, require_filter
-from _common import add_common, apply_common, aac_args, cfr_args, with_cfr, default_output, die, emit, escape_filter_path, ffmpeg_base, info, probe, require_tool, run, video_args, X264_PRESETS, run_analysis, dry_run_input_pending, fmt_secs, record_fallback, EVEN_SCALE
+from _common.probe import PROBED_VIDEO, probed_maps
+from _common.runner import ffmpeg_failure_extra, require_filter
+from _common import add_common, apply_common, aac_args, cfr_args, with_cfr, default_output, die, emit, escape_filter_path, ffmpeg_base, info, probe, require_tool, run_keeping_subtitles, video_args, X264_PRESETS, run_analysis, dry_run_input_pending, fmt_secs, record_fallback, EVEN_SCALE
 
 
 def main() -> int:
@@ -104,19 +104,20 @@ def main() -> int:
             # Equivalent to relative=0:smoothing=0 -- overrides --smoothing, since averaging a
             # camera path makes no sense once every frame is locked to one fixed reference.
             transform_vf += ":tripod=1"
-        cmd = ffmpeg_base() + ["-i", args.input] + default_selection_maps(meta, output) + ["-vf", with_cfr(transform_vf, meta)]
+        cmd = ffmpeg_base() + ["-i", args.input] + probed_maps(meta) + ["-vf", with_cfr(transform_vf, meta)]
         cmd += video_args(meta, args.crf, args.preset)
         cmd += cfr_args(meta)
         if has_audio:
             cmd += aac_args()
         else:
             cmd += ["-an"]
-        cmd.append(output)
-        run(cmd)
+        # the frames keep their times, so the subtitle/data tracks are copied as fit.py and color.py
+        # copy them, and dropped (said) only where the container refuses them (#520)
+        dropped_streams = run_keeping_subtitles(cmd, output)
 
     result = probe(output, role="output")
     info(f"wrote {output} ({fmt_secs(result['duration'])}, {result['video']['width']}x{result['video']['height']})")
-    emit(output)
+    emit(output, dropped_non_av_streams=dropped_streams)
     return 0