ffmpeg-skill 3.8.21 → 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.21`) | 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.21", "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.21",
+  "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/decision.py

@@ -711,20 +711,80 @@ def graph_with_cfr(graph: str, label: str, meta: Optional[Dict[str, Any]],
     return f"{graph};[{bare}]{f}[{bare}cfr]", f"[{bare}cfr]"
 
 
-def cfr_at_input(graph: str, meta: Optional[Dict[str, Any]], fps: Optional[float] = None, src: str = "[0:v]") -> str:
+def cfr_at_input(graph: str, meta: Optional[Dict[str, Any]], fps: Optional[float] = None, src: str = "[0:v]",
+                 origin: Optional[float] = None) -> str:
     """A -filter_complex graph with cfr_filter() on its main picture as it is decoded (`src`, which
     the graph reads once), for a graph that composites onto that picture and moves no frame in
     time. After an overlay the conform comes too late: FFmpeg 6.1's overlay ends its output at its
-    last frame's start, so an fps filter there lost the last frame (3.963 s of a 4 s picture)."""
+    last frame's start, so an fps filter there lost the last frame (3.963 s of a 4 s picture).
+    With `origin` (where the picture starts on the graph's clock, stream_starts()) the picture is
+    moved to start at 0 ahead of the conform, so the grid is laid from its first frame, and the
+    conformed frames get a microsecond time base, for a graph that cuts the picture on that grid
+    (freeze.py, #523): the caller counts the picture's times from its own start. The fps
+    filter's grid starts at the clock's 0, so a picture that starts 50 ms in was cut a frame off
+    the times computed from its start, and its output's time base is one frame, to which `trim`
+    rescales its bound (a half-frame bound written to the microsecond, 3.907407 at 27 fps, became
+    the frame at 3.888889 and cut it). The picture is not moved back after the conform: from
+    FFmpeg 7.0 setpts leaves its output frames no duration and no rate, and a tpad after it (the
+    hold) cloned nothing: 109 frames for 135 on 7.1."""
     f = cfr_filter(meta, fps)
     if not f:
         return graph
     if graph.count(src) != 1:
         # a graph that read the picture twice, or not at all, would go unconformed or not parse
         raise ValueError(f"cfr_at_input: the graph reads {src} {graph.count(src)} times, not once")
+    if origin is not None:
+        f = f"setpts=PTS-{origin:.6f}/TB,{f},settb=AVTB" if origin else f"{f},settb=AVTB"
     return f"{src}{f}[cfrin];" + graph.replace(src, "[cfrin]")
 
 
+def atempo_lead(sample_rate: Any) -> int:
+    """How many samples of its input `atempo` leaves out at the start: half its window, which is
+    the power of two at or above sample_rate / 24 (2048 at 44.1 and 48 kHz, so 1024 samples, 21 ms
+    at 48 kHz). Its output opens on the sample half a window in (measured at 8, 22.05, 32, 44.1,
+    48 and 96 kHz on FFmpeg 6.1.1), so every sound after it is that much early: speedramp.py's beeps
+    came 21 ms early at 1x and 40 ms at 0.5x, and fit.py --method speed's the same (#523). 0 when
+    the rate is not known (a dry run's pending input)."""
+    try:
+        rate = int(sample_rate or 0)
+    except (TypeError, ValueError):
+        return 0
+    window = rate // 24
+    if window < 1:
+        return 0
+    pot = 1 << (window.bit_length() - 1)
+    return (pot * 2 if pot < window else pot) // 2
+
+
+def atempo_chain_with_lead(stages: List[str], sample_rate: Any) -> str:
+    """`atempo` stages (each value as written) led by silence and trimmed after, so the output
+    keeps the input's timing from its first sample: a beep at 0.5 s of a 1x stage came out at
+    0.479 s (FFmpeg 6.1.1). Each stage leaves out atempo_lead() samples of its own input, which
+    are the earlier stages' tempo product times that many of the chain's input, so one lead of
+    their sum goes in front of the first stage: an `adelay` between two stages made FFmpeg 6.1.1
+    fail a graph that joins the result with `concat` ("Invalid data found when processing
+    input", speedramp.py with a 0.25x segment). That lead alone put the chain's first window,
+    which atempo fades in, over the input's first 21 ms: a 10 ms attack there came out 7 dB down
+    at 1x and was gone at 2x (#541 review). So one whole window more of silence goes in front
+    (as many of the chain's input samples as leave a window of it ahead of every stage), and
+    that much of the output, at the chain's tempo, is cut off again and its timestamps moved
+    back by it, so a track that starts after 0 keeps its start. The bare stages when the rate is
+    not known (a dry run's pending input)."""
+    lead = atempo_lead(sample_rate)
+    chain = ",".join(f"atempo={value}" for value in stages)
+    if not lead:
+        return chain
+    total, product, widest = 0.0, 1.0, 1.0
+    for value in stages:
+        total += lead * product
+        product *= float(value)
+        widest = max(widest, product)
+    extra = round(2 * lead * widest)  # a window of silence ahead of the stage that shrinks it most
+    cut = round(extra / product)
+    return (f"adelay={round(total) + extra}S:all=1,{chain},"
+            f"atrim=start_sample={cut},asetpts=PTS-{cut}/SR/TB")
+
+
 def delivered_rate(meta: Optional[Dict[str, Any]], fps: Optional[float] = None) -> Optional[float]:
     """The constant rate cfr_args() forces on the output (its -r), or None when it forces none and
     the output keeps the source's rate -- what a start timecode is counted at

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/audio.py

@@ -30,7 +30,7 @@ from typing import Any, Dict, List
 from _common.probe import SILENT_PEAK_DBFS
 from _common import STATE, add_common, dry_run_input_pending, require_tool, apply_common, audio_codec_for, db_to_linear, default_output, die, emit, ffmpeg_base, info, is_audio_output, measured_level_dbfs, probe, run, run_keeping_subtitles, fmt_secs
 from _common.emit import file_origin, stream_end, warn
-from _common.decision import LOSSLESS_AUDIO_EXT, conform_filter, conform_to_length
+from _common.decision import LOSSLESS_AUDIO_EXT, atempo_chain_with_lead, conform_filter, conform_to_length
 
 # --downmix: ITU-R BS.775 fold-down, renormalised by pan's '<' (see main()).
 DOWNMIX_PAN = "pan=stereo|FL<FL+0.707*FC+0.707*BL+0.707*SL|FR<FR+0.707*FC+0.707*BR+0.707*SR"
@@ -559,7 +559,9 @@ def main() -> int:
         fx.append(f"extrastereo=m={1 + 2 * args.stereo_widen:g}")
     tempo_steps = atempo_steps(args.tempo) if args.tempo is not None and args.tempo != 1.0 else []
     if tempo_steps:
-        fx.append(",".join(f"atempo={f:.10g}" for f in tempo_steps))
+        # led by the samples atempo leaves out, at the rate the track has there (the source's:
+        # --sample-rate resamples after the chain), or it opened 21 ms in (#523)
+        fx.append(atempo_chain_with_lead([f"{f:.10g}" for f in tempo_steps], main_track_rate(args, meta)))
     # the main track's length in the output: the source's, or the source's / --tempo on an audio
     # output of the input's own sound (beside a picture, or for --replace, it is the picture's)
     main_dur = dur / args.tempo if dur and tempo_steps and not (keep_video or args.replace) else dur

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/fit.py

@@ -36,9 +36,9 @@ Examples:
 import argparse
 import sys
 from fractions import Fraction
-from typing import List
+from typing import Any, List
 
-from _common.decision import SEEK_MARGIN, delivered_rate, frame_durations, frame_rate, grid_at_or_after, length_output_t, stream_starts
+from _common.decision import SEEK_MARGIN, atempo_chain_with_lead, delivered_rate, frame_durations, 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, cfr_filter, default_output, die, ffmpeg_base, info, probe, run, run_keeping_subtitles, validate_color, 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
@@ -53,18 +53,21 @@ def parse_aspect(value: str) -> Fraction:
     return ratio
 
 
-def atempo_chain(factor: float) -> str:
-    """atempo accepts 0.5..100 per instance; chain for extreme factors."""
+def atempo_chain(factor: float, sample_rate: Any = 0) -> str:
+    """atempo accepts 0.5..100 per instance; chain for extreme factors. The chain is led by the
+    samples atempo leaves out (atempo_chain_with_lead, at the track's `sample_rate`), so the
+    retimed sound keeps its timing against the retimed picture (#523: about 21 ms early in input
+    time without them)."""
     parts: List[str] = []
     remaining = factor
     while remaining < 0.5:
-        parts.append("atempo=0.5")
+        parts.append("0.5")
         remaining /= 0.5
     while remaining > 100.0:
-        parts.append("atempo=100.0")
+        parts.append("100.0")
         remaining /= 100.0
-    parts.append(f"atempo={remaining:.6f}")
-    return ",".join(parts)
+    parts.append(f"{remaining:.6f}")
+    return atempo_chain_with_lead(parts, sample_rate)
 
 
 def picture_output_t(target: float, meta: dict) -> str:
@@ -218,7 +221,7 @@ def main() -> int:
                     vf.append(frame_durations(meta, delivered_rate(meta) or frame_rate(meta) or src_fps))
                     regridded = True
                 if has_audio:
-                    af.append(atempo_chain(factor))
+                    af.append(atempo_chain(factor, rate))
             # atempo's sound is not the input's length over the factor (it comes out some
             # milliseconds short or long), and the millisecond -t stays on a retimed track: padding
             # it to the target's samples (apad after atempo in -af) never ended on FFmpeg 8.0.1

package/scripts/freeze.py

@@ -18,8 +18,9 @@ Examples:
 """
 import argparse
 import sys
+from fractions import Fraction
 
-from _common.decision import av_trim, delivered_rate, frame_durations, frame_rate, grid_at_or_after, silence_filter, stream_starts, tpad_length
+from _common.decision import av_trim, cfr_at_input, cfr_filter, delivered_rate, frame_durations, frame_rate, grid_at_or_after, silence_filter, stream_starts, tpad_length
 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, time_arg, fmt_secs, run
 from _common.emit import input_length
 
@@ -63,6 +64,15 @@ def main() -> int:
     # starts 0.1 s late 0.1 s early (147 frames for 150).
     v0 = stream_starts(meta)[0]
     rate = frame_rate(meta) or fps
+    if cfr_filter(meta):
+        # A VFR source is put on the delivered grid as it is decoded (the graph's cfr_at_input
+        # below), and every frame time is on that grid (#523): on the source's own frames the
+        # head ended at its last frame's nominal duration, so with --at inside a gap the hold, and
+        # everything after it, started the rest of the gap early against the sound, which is cut
+        # at --at (56 ms at --at 0.15, 93 ms at --at 2.2 on a 27 fps average clip with gaps from
+        # 0.1 and 2.1 s). A hold is then counted in frames of that rate, the rate its frames are
+        # cloned at.
+        rate = delivered_rate(meta) or rate
     cut_at = grid_at_or_after(at, v0, rate)
     # no frame at or after --at (no --at holds at the clip's end): the insert tail would be empty
     # and the hold lost, so hold the last frame as --mode extend does (#416 review)
@@ -98,8 +108,11 @@ def main() -> int:
         # the video actually holds for, a permanent A/V drift from this point on. Pad audio by
         # the same, frame-rounded duration the video actually gets.
         actual_hold = n / rate
-        head_v, head_a = av_trim(v0, cut_at, rate)
-        tail_v, tail_a = av_trim(cut_at, None, rate)
+        # a conformed VFR picture starts at 0 on the graph's clock (cfr_at_input's origin), so its
+        # trims are counted from its own start; the sound's stay on the input's clock
+        vo = v0 if cfr_filter(meta) else 0.0
+        head_v, head_a = av_trim(v0 - vo, cut_at - vo, rate)[0], av_trim(v0, cut_at, rate)[1]
+        tail_v, tail_a = av_trim(cut_at - vo, None, rate)[0], av_trim(cut_at, None, rate)[1]
         # The hold is its own segment: the frame at cut_at, cut on the input's clock and cloned to
         # n frames there (tpad's stop clone), then shifted like the tail. From FFmpeg 7.0 setpts
         # leaves its output's frame rate unknown and its frames' durations 0, so the earlier tpad
@@ -114,11 +127,27 @@ def main() -> int:
         half = 0.5 / rate
         # the graph closes on the rate the encoder line delivers (a VFR source is conformed to its
         # average): closed on r_frame_rate, -r then resampled it and the picture ran late (#512)
-        hold_v = (f"trim=start={cut_at - half:.6f},trim=end_frame=1,"
+        hold_v = (f"trim=start={cut_at - vo - half:.6f},trim=end_frame=1,"
                   f"tpad=stop_mode=clone:stop={n - 1},setpts=PTS-STARTPTS")
+        # Every segment is a whole count of frames on one grid, so the joined picture's timestamps
+        # are rebuilt from its running frame count before the closing fps: FFmpeg 6.1.1's video
+        # concat gives a one-frame segment no length (it ends a segment at its last frame's
+        # timestamp), so a hold of one frame (--hold 0.04 at 30 fps) was dropped and the rest of
+        # the picture ran a frame before its sound, as speedramp.py's one-frame segments did
+        grid = frame_durations(meta, delivered_rate(meta) or rate)
+        q = Fraction(grid[len("fps="):]) if "/" in grid else Fraction(delivered_rate(meta) or rate).limit_denominator(1001)
         vf = (f"[0:v]split=3[a][b][c];[a]{head_v}[head];"
               f"[b]{hold_v}[hold];[c]{tail_v}[tail];"
-              f"[head][hold][tail]concat=n=3:v=1:a=0,{frame_durations(meta, delivered_rate(meta) or rate)}[outv]")
+              f"[head][hold][tail]concat=n=3:v=1:a=0,setpts=N*{q.denominator}/({q.numerator}*TB),{grid}[outv]")
+        # the grid is laid from the picture's start (the picture moved to 0 ahead of the fps
+        # filter, and the trims above counted from there), on a microsecond time base: laid from
+        # the clock's 0, a picture that starts 50 ms in came out a frame early after the hold, and
+        # on the fps filter's base of one frame the trim's half-frame bound 3.907407 (--at 3.9)
+        # became frame 105 itself, which was cut from the head and held in place of frame 106.
+        # It is not moved back after the conform: from FFmpeg 7.0 a setpts leaves its frames no
+        # duration and no rate, and the hold's tpad after it cloned nothing (109 frames for 135
+        # on 7.1)
+        vf = cfr_at_input(vf, meta, origin=v0)
         cmd = ffmpeg_base() + ["-i", args.input, "-filter_complex", vf, "-map", "[outv]"]
         if has_audio:
             af = (f"[0:a]asplit[aa][ab];[aa]{head_a}[ahead];"

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/reverse.py

@@ -15,7 +15,7 @@ import argparse
 import math
 import sys
 
-from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run, video_args, X264_PRESETS, fmt_secs
+from _common import add_common, apply_common, aac_args, cfr_args, cfr_filter, default_output, die, emit, ffmpeg_base, info, probe, run, video_args, X264_PRESETS, fmt_secs
 from _common.emit import warn
 from _common.decision import (HELD_FRAMES_WARN_BYTES, av_clip_length, av_trim, delivered_rate, frame_durations, frame_rate,
                               held_frames_bytes, stream_starts)
@@ -49,6 +49,17 @@ def main() -> int:
              f"({vdur:.0f}s of {v['width']}x{v['height']}) -- cut the part to reverse first (cut.py) if RAM is tight",
              "memory_heavy", duration=meta.get("duration"), bytes=held)
     cmd = ffmpeg_base() + ["-i", args.input]
+    # A VFR source is put on the delivered grid before the reversal (#523). `reverse` hands its
+    # frames the forward timestamps in order, so a reversed VFR picture kept its gaps where they
+    # were in forward time: every flash of the 27 fps average clip came 0.19 s late against the
+    # reversed sound (0.23 s without sound). On a constant grid the reversed picture is the forward
+    # one mirrored. Each slot takes the last frame that starts before the slot ends (round=down),
+    # which is the frame the reversed slot opens on: the nearest frame to its start (the forward
+    # conform's choice) dropped a last frame that starts after the last slot's middle, and the
+    # reversal then opened on the frame before it. The conformed picture's time base is one frame,
+    # and a trim rescales its bound to it (a half-frame bound can round onto a frame and cut it:
+    # freeze.py), so a microsecond base follows.
+    reversed_conform = f"{cfr_filter(meta)}:round=down,settb=AVTB" if cfr_filter(meta) else ""
     if has_audio:
         # Both streams are reversed about one end (#409); each reversed about its own end put a sound
         # 0.6 s longer than its picture 0.396 s off. As in a join, both start at the first frame (the
@@ -73,13 +84,14 @@ def main() -> int:
         vlen = meta["video"].get("duration") or length
         end = math.ceil(length * rate - 1e-6) / rate
         vtrim, atrim = av_trim(stream_starts(meta)[0], None)
+        conform = f"{reversed_conform}," if reversed_conform else ""
         cmd += ["-filter_complex",
                 f"[0:v:0]tpad=stop_mode=clone:stop_duration={max(0.0, end - vlen) + 2 / rate:.6f},{vtrim},"
-                f"trim=end={end - 0.5 / max(rate, frame_rate(meta) or rate):.6f},reverse,{frame_durations(meta, rate)}[v];"
+                f"{conform}trim=end={end - 0.5 / max(rate, frame_rate(meta) or rate):.6f},reverse,{frame_durations(meta, rate)}[v];"
                 f"[0:a:0]{atrim},apad=whole_dur={end:.6f},atrim=end={end:.6f},areverse,asetpts=N/SR/TB[a]",
                 "-map", "[v]", "-map", "[a]"]
     else:
-        cmd += ["-vf", "reverse"]
+        cmd += ["-vf", f"{reversed_conform},reverse" if reversed_conform else "reverse"]
     cmd += video_args(meta, args.crf, args.preset)
     cmd += cfr_args(meta)
     if has_audio:

package/scripts/speedramp.py

@@ -18,9 +18,9 @@ Examples:
 import argparse
 import sys
 from fractions import Fraction
-from typing import List, Tuple
+from typing import Any, List, Tuple
 
-from _common.decision import av_trim, conform_filter, delivered_rate, frame_durations, frame_rate, grid_at_or_after, stream_starts
+from _common.decision import atempo_chain_with_lead, av_trim, conform_filter, delivered_rate, frame_durations, frame_rate, grid_at_or_after, stream_starts
 from _common import add_common, apply_common, aac_args, default_output, die, emit, ffmpeg_base, info, probe, run, video_args, X264_PRESETS, fmt_secs, time_arg
 from _common.emit import input_length
 
@@ -28,18 +28,20 @@ MAX_SPEED = 20.0
 MIN_SPEED = 0.05
 
 
-def atempo_chain(factor: float) -> str:
-    """atempo accepts 0.5..100 per instance; chain for factors outside that range."""
+def atempo_chain(factor: float, sample_rate: Any = 0) -> str:
+    """atempo accepts 0.5..100 per instance; chain for factors outside that range. The chain is
+    led by the samples atempo leaves out (atempo_chain_with_lead, at the track's `sample_rate`):
+    without them every segment's sound came out 21 ms early at 1x and 40 ms at 0.5x (#523)."""
     parts: List[str] = []
     remaining = factor
     while remaining < 0.5:
-        parts.append("atempo=0.5")
+        parts.append("0.5")
         remaining /= 0.5
     while remaining > 100.0:
-        parts.append("atempo=100.0")
+        parts.append("100.0")
         remaining /= 100.0
-    parts.append(f"atempo={remaining:.6f}")
-    return ",".join(parts)
+    parts.append(f"{remaining:.6f}")
+    return atempo_chain_with_lead(parts, sample_rate)
 
 
 def parse_segment(raw: str) -> Tuple[float, float, float]:
@@ -118,7 +120,8 @@ def main() -> int:
         # leaves at the unscaled 1/rate, so every 2x segment pushed the rest of the picture two
         # frames late against the sound (and added those frames)
         vchain = f"[0:v]{vtrim},setpts=PTS/{factor:.6f},{frame_durations(meta, out_rate)}"
-        achain = f"[0:a]{atrim},{atempo_chain(factor)}"
+        # a 1x segment is not retimed: atempo would place its sound by windows for nothing (#541)
+        achain = f"[0:a]{atrim}" if factor == 1.0 else f"[0:a]{atrim},{atempo_chain(factor, srate)}"
         if out_rate:
             # Each segment holds the frames (and samples) between its retimed ends on the whole
             # output's grid, not its own length rounded: eight 0.5 s segments at 27 fps rounded

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