ffmpeg-skill 3.8.0 → 3.8.1

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

@@ -63,7 +63,7 @@ from _common.runner import (
     STATE, _timed_out, _unwatch, _watch, X264_PRESETS
 )
 from _common.emit import (
-    absorb_stage, audit, _brief, _BRIEF_DROP, _brief_summary, _CURRENT_CTX, die, emit, info, note, _plan_at_exit, _plan_inputs,
+    absorb_stage, audit, _brief, input_length, _BRIEF_DROP, _brief_summary, _CURRENT_CTX, die, emit, info, note, _plan_at_exit, _plan_inputs,
     _plan_unbound_inputs, _PLAN_STRIP, PLAN_VERSION, print_json, record_fallback, record_skip, refuse, _set_current_ctx, warn,
     write_plan
 )
@@ -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, 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, 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

@@ -15,7 +15,7 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional, Sequence, Tuple
 from _common.color import (as_limited, bt709_label_filter, bt709_matrix_args, bt709_matrix_filter, bt709_tag_args, drawn_stream_format,
                            is_neutral_color, limited_range_filter, rgb_island, rgb_to_bt709_filter, _sdr_bt709)
-from _common.emit import die, record_fallback, refuse, warn
+from _common.emit import die, input_length, record_fallback, refuse, warn
 from _common.runner import read_json
 from _common.runner import CODECS, STATE, ffmpeg_encoders, ffmpeg_list_error, ffmpeg_version, hw_platform_reason
 
@@ -431,6 +431,30 @@ def av_trim(start: float, end: Optional[float], rate: float = 0.0, fill_gaps: bo
             f"atrim=start={start:.6f}{aend},asetpts=PTS-{start:.6f}/TB,{pad}")
 
 
+def conform_filter(samples: int, rate: int) -> str:
+    """Pad with silence or trim to exactly `samples` at `rate` (#478): counted in samples, not in
+    seconds written to the millisecond, which left a result up to 24 samples (48 kHz) off. The
+    aformat pins the rate the count is in, so a resampler FFmpeg inserts sits ahead of the count."""
+    head = f"aformat=sample_rates={rate}," if rate else ""
+    return f"{head}apad=whole_len={samples},atrim=end_sample={samples}"
+
+
+def conform_to_length(length: float, rate: int) -> str:
+    """Pad with silence or trim a track to `length` seconds of a timeline that starts at 0, to the
+    sample (#478, #493). The count is of samples, and sound that starts after 0 keeps its start
+    (apad and atrim=end_sample do not move timestamps): N samples from 0.3 s end 0.3 s past
+    `length`. The trim on the timestamp ends it there; half a sample of slack keeps the Nth sample
+    of a track that starts at 0. audio.py, grid.py, broll.py and multicam.py end their sound with
+    this; `atrim=duration={length:.3f}` cut 59244 samples (48 kHz) to 59232."""
+    return conform_filter(round(length * rate), rate) + f",atrim=end={length + 0.5 / rate:.6f}"
+
+
+def conform_output_t(length: float, rate: int) -> str:
+    """The output `-t` beside conform_to_length(): `-t {length:.3f}` would cut the conformed sound
+    back to the millisecond, so the limit sits half a sample past the last one."""
+    return f"{length + 0.5 / rate:.6f}"
+
+
 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
@@ -440,7 +464,7 @@ def av_clip_length(meta: Optional[Dict[str, Any]], fps: float) -> float:
     v = (meta.get("video") or {}).get("duration")
     a = (meta.get("audio") or {}).get("duration")
     if not v:
-        return meta.get("duration") or 0.0
+        return input_length(meta)  # a file that states no length at all is refused, not 0 s long (#491)
     if a:
         v0, a0 = stream_starts(meta)
         a = a + a0 - v0  # where the sound ends, counted from the first frame

package/scripts/_common/emit.py

@@ -647,6 +647,29 @@ def stream_length(meta: Dict[str, Any], kind: str) -> Optional[float]:
     return None
 
 
+LENGTH_UNREAD_HINT = ("remux the file so its container states a length (export.py INPUT --preset copy -o remuxed.mkv), "
+                      "then run this on the remux")
+
+
+def input_length(meta: Optional[Dict[str, Any]], path: Optional[str] = None) -> float:
+    """An input's length in seconds, for a tool that computes with it (#491). A file that states
+    no length (Matroska written to a pipe: ffprobe prints N/A for the container and every stream)
+    probes as duration None, and `meta.get("duration") or 0.0` read that as a clip 0 s long: a
+    speed factor of 0.00x, "--at 1 is outside the clip (0..0.000)", a reverse of no frames. Unread
+    is not zero, so this refuses, as check.py's duration row says "could not measure". A dry run's
+    pending input (probe()'s stub, duration 0.0), a stated length of 0 and a still picture (one
+    image read by an image demuxer has no length to state) pass through as before."""
+    meta = meta or {}
+    length = meta.get("duration")
+    fmt = meta.get("format") or ""
+    still = fmt == "image2" or fmt.endswith("_pipe")  # probe._is_still()'s rule, on the probe document
+    if length is None and not meta.get("dry_run") and not still:
+        die(f"the length of {path or meta.get('file') or 'the input'} could not be read: neither its container nor "
+            "its streams state one, and this operation is computed from the input's length",
+            kind="input", hint=LENGTH_UNREAD_HINT)
+    return float(length or 0.0)
+
+
 def stream_end(meta: Dict[str, Any], kind: str) -> Optional[float]:
     """Where one stream ends on the file's timeline: its start plus its own length."""
     length = stream_length(meta, kind)

package/scripts/audio.py

@@ -30,6 +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 warn
+from _common.decision import 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"
@@ -254,14 +255,6 @@ def property_step(name: str, expected: int, measured: Any) -> Dict[str, Any]:
     return {"step": name, "expected": expected, "measured": value, "ok": value == expected}
 
 
-def conform_filter(samples: int, rate: int) -> str:
-    """Pad with silence or trim to exactly `samples` at `rate` (#478): counted in samples, not in
-    seconds written to the millisecond, which left a result up to 24 samples (48 kHz) off. The
-    aformat pins the rate the count is in, so a resampler FFmpeg inserts sits ahead of the count."""
-    head = f"aformat=sample_rates={rate}," if rate else ""
-    return f"{head}apad=whole_len={samples},atrim=end_sample={samples}"
-
-
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input")
@@ -564,12 +557,9 @@ def main() -> int:
     elif main_dur and (args.replace or args.music or keep_video):
         if rate:
             conform_samples = round(main_dur * rate)
-            # The count is of samples, and sound that starts after the picture keeps its start
-            # (apad and atrim=end_sample do not move timestamps): N samples from 0.3 s end 0.3 s
-            # past the picture. The trim on the timestamp, which is what this was before #478,
-            # ends it with the picture; half a sample of slack keeps the Nth sample of a track
-            # that starts at 0.
-            post.append(conform_filter(conform_samples, rate) + f",atrim=end={main_dur + 0.5 / rate:.6f}")
+            # counted in samples and ended on the timestamp, so sound that starts after the picture
+            # still ends with it (conform_to_length, shared with grid, broll and multicam since #493)
+            post.append(conform_to_length(main_dur, rate))
         else:
             # a dry run's pending input: no rate to count in yet; the real run counts samples
             post.append(f"apad,atrim=0:{main_dur:.6f}")

package/scripts/broll.py

@@ -21,10 +21,14 @@ import argparse
 import sys
 from typing import Any, Dict, List
 
-from _common.decision import av_trim, 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, 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
+from _common.emit import input_length
+
+
+MIX_RATE = 48000  # every layer of a b/mix sound is resampled to it before the mix
 
 
 def main() -> int:
@@ -57,7 +61,7 @@ def main() -> int:
     meta_a = probe(args.input)
     if not meta_a.get("video"):
         die("A-roll has no video stream")
-    dur_a = meta_a.get("duration") or 0.0
+    dur_a = input_length(meta_a)
     # the cutaway is scaled onto the frame ffmpeg has already rotated, not the stored one, and
     # onto a non-square-pixel A-roll squared at its display aspect (#411)
     w, h = display_size(meta_a["video"])
@@ -98,7 +102,7 @@ def main() -> int:
             die(f"cutaway {i + 1}: --at {at:g}s is past the end of the A-roll ({dur_a:.3f}s)")
         if dur_a and at + length > dur_a + 0.01:
             die(f"cutaway {i + 1}: {at:g}s + {length:g}s runs past the end of the A-roll ({dur_a:.3f}s)")
-        dur_b = meta_b.get("duration") or 0.0
+        dur_b = input_length(meta_b)
         if dur_b and start_b + length > dur_b + 0.01 and not STATE.dry_run:
             die(f"cutaway {i + 1}: {path} has only {dur_b - start_b:.3f}s from {start_b:g}s, {length:g}s asked for")
         if cutaways and at < cutaways[-1]["at"] + cutaways[-1]["length"]:
@@ -161,7 +165,11 @@ def main() -> int:
                 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}]")
                 layers.append(f"[ab{i}]")
-            parts.append(f"{''.join(layers)}amix=inputs={len(layers)}:normalize=0:dropout_transition=0,atrim=duration={dur_a:.3f}[aout]")
+            # 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
+            # dry run's pending A-roll has no length to count, and keeps the old filter.
+            tail = conform_to_length(dur_a, MIX_RATE) if dur_a > 0 else f"atrim=duration={dur_a:.3f}"
+            parts.append(f"{''.join(layers)}amix=inputs={len(layers)}:normalize=0:dropout_transition=0,{tail}[aout]")
             aout = "[aout]"
 
     cmd += ["-filter_complex", ";".join(parts), "-map", vout]
@@ -174,7 +182,7 @@ def main() -> int:
         cmd += aac_args()
     else:
         cmd += ["-an"]
-    cmd += ["-t", f"{dur_a:.3f}", output]
+    cmd += ["-t", conform_output_t(dur_a, MIX_RATE) if aout == "[aout]" and dur_a > 0 else f"{dur_a:.3f}", output]
     run(cmd)
 
     result = probe(output, role="output")

package/scripts/export.py

@@ -52,7 +52,7 @@ from _common.decision import hw_preset_video, restate_last_swap
 from _common.emit import note, record_fallback, record_skip, warn
 from _common.probe import PROBED_AUDIO, PROBED_VIDEO, probed_maps, square_pixels, square_pixels_note
 from _common.runner import ffmpeg_encoders, guard_sidecar, remember_written, replace_checked, replace_checked_together, reserve_sibling, run_analysis as _run_analysis, subtitle_codec_for
-from _common.emit import file_identity
+from _common.emit import file_identity, input_length
 from check import SPECS as PLATFORMS, measure_loudness
 from _common.probe import SILENT_PEAK_DBFS, shorter_than_a_loudness_block
 from _platforms import ALIASES as _ALIASES, PLATFORMS as PLATFORM_TABLE, TP_TOLERANCE_DB, UPLOAD_LIMITS_AS_OF, resolve as resolve_platform
@@ -443,7 +443,7 @@ def size_video_args(args, video: List[str], p: Dict, meta: Dict, has_audio: bool
             + (" (--hw puts it on VideoToolbox, which has no two-pass mode)" if STATE.hw else ""))
     if not math.isfinite(args.max_mb) or args.max_mb <= 0:
         die(f"--max-mb must be a positive number of MiB, got {args.max_mb:g}")
-    dur = float(meta.get("duration") or 0.0)
+    dur = input_length(meta)  # the bitrate is the size over the length: no stated length is refused (#491)
     if p["max"] and not args.allow_long:
         dur = min(dur, float(p["max"]))
     if dur <= 0:

package/scripts/fit.py

@@ -42,6 +42,7 @@ from typing import List
 from _common.decision import SEEK_MARGIN, delivered_rate, frame_rate, grid_at_or_after, 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
 BLUR_DARKEN = 0.15  # how much --fit blur dims the blurred background copy (eq brightness)
 
 
@@ -157,6 +158,10 @@ def main() -> int:
         target = time_arg(args.duration, "--duration", meta["video"].get("fps") if meta.get("video") else None)
         if target <= 0:
             die("target duration must be > 0")
+        # speed and trim are both computed from the source's length: one that states none is refused
+        # (#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)
         if args.method == "speed":
             if src_dur <= 0 and STATE.dry_run:
                 src_dur = target  # planning against an intermediate that does not exist yet

package/scripts/freeze.py

@@ -21,6 +21,7 @@ import sys
 
 from _common.decision import av_trim, frame_durations, frame_rate, grid_at_or_after, 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
 
 
 def main() -> int:
@@ -43,7 +44,7 @@ def main() -> int:
     meta = probe(args.input)
     if not meta.get("video"):
         die("input has no video stream")
-    dur = meta.get("duration") or 0.0
+    dur = input_length(meta)
     fps = meta["video"].get("fps") or 30.0
     if args.at is not None:
         at = time_arg(args.at, "--at", (meta.get("video") or {}).get("fps"))

package/scripts/graphics.py

@@ -49,6 +49,7 @@ from _common.fonts import font_choice, record_font_choice
 from _common.probe import display_size, square_pixels, square_pixels_note
 from _ass_overlay import text_overlay_ass, EMOJI_SENTINEL
 from _common import drawtext_fontfile  # noqa: E402
+from _common.emit import input_length  # noqa: E402
 
 # where the template's text chain goes in a filter_complex it builds (graphics.main fills it in)
 TEXT = "@TEXT@"
@@ -201,7 +202,7 @@ def main(force_route: Optional[str] = None) -> int:
         info(f"--platform {args.platform}: safe margins top {m_top} / bottom {m_bottom} / left {m_left} / right {m_right} px")
     fps = meta["video"].get("fps")
     s = time_arg(args.start, "--start", fps) if args.start else 0.0
-    e = time_arg(args.end, "--end", fps) if args.end else dur
+    e = time_arg(args.end, "--end", fps) if args.end else input_length(meta)  # no --end is the clip's end (#491)
     # the picture's own length first: sound that runs on keeps the container open past the last frame
     picture_len = meta["video"].get("duration") or dur
     if picture_len and s >= picture_len:

package/scripts/grid.py

@@ -34,6 +34,8 @@ from _common.emit import note, record_fallback  # noqa: E402
 from _common.fonts import script_font_for_text  # noqa: E402
 from _common.probe import square_pixels  # noqa: E402
 from _common.wrap import text_width_em  # noqa: E402
+from _common.emit import input_length  # noqa: E402
+from _common.decision import conform_output_t, conform_to_length  # noqa: E402
 
 LABEL_MARGIN = 10
 
@@ -114,7 +116,7 @@ def main() -> int:
     if args.audio_from is not None and not metas[args.audio_from].get("audio"):
         die(f"--audio-from {args.audio_from}: {args.inputs[args.audio_from]} has no audio stream")
 
-    durations = [m.get("duration") or 0.0 for m in metas]
+    durations = [input_length(m) for m in metas]
     target_duration = max(durations) if args.pad else min(durations)
 
     # each label is drawn with a font that covers its own script, as every other text-drawing tool
@@ -188,12 +190,24 @@ def main() -> int:
     cw, ch = args.cell_width + args.gap, args.cell_height + args.gap
     layout = "|".join(f"{c * cw}_{r * ch}" for r in range(args.rows) for c in range(args.cols))
     parts.append("".join(f"[v{i}]" for i in range(n)) + f"xstack=inputs={n}:layout={layout}:fill={args.background}[out]")
-    if args.audio_from is not None and args.pad and durations[args.audio_from] < target_duration:
+    # The sound ends with the grid, to the sample (#493): padded when its clip is shorter than a
+    # --pad grid, trimmed when it is longer. `apad,atrim=duration={:.3f}` and the output's
+    # `-t {:.3f}` both cut it to the millisecond (59244 samples at 48 kHz came out as 59232). A dry
+    # run's pending input has no rate to count in yet, and keeps the old filter, as audio.py does.
+    audio_rate = (metas[args.audio_from]["audio"].get("sample_rate") or 0) if args.audio_from is not None else 0
+    conformed = bool(audio_rate and target_duration > 0)
+    audio_source = None
+    if conformed:
+        parts.append(f"[{args.audio_from}:a:0]{conform_to_length(target_duration, audio_rate)}[aout]")
+        audio_source = "[aout]"
+    elif args.audio_from is not None and args.pad and durations[args.audio_from] < target_duration:
         parts.append(f"[{args.audio_from}:a:0]apad,atrim=duration={target_duration:.3f}[aout]")
+        audio_source = "[aout]"
+    elif args.audio_from is not None:
+        audio_source = f"{args.audio_from}:a:0"
     cmd += ["-filter_complex", ";".join(parts), "-map", "[out]"]
 
-    if args.audio_from is not None:
-        audio_source = "[aout]" if (args.pad and durations[args.audio_from] < target_duration) else f"{args.audio_from}:a:0"
+    if audio_source:
         cmd += ["-map", audio_source]
     # A grid is an 8-bit SDR composite by design (a comparison/contact artefact, not a
     # deliverable); an HDR input is flattened like look.py's contact sheet flattens it. Say so
@@ -206,7 +220,7 @@ def main() -> int:
         cmd += aac_args()
     else:
         cmd += ["-an"]
-    cmd += ["-t", f"{target_duration:.3f}", output]
+    cmd += ["-t", conform_output_t(target_duration, audio_rate) if conformed else f"{target_duration:.3f}", output]
     run(cmd)
 
     result = probe(output, role="output")

package/scripts/join.py

@@ -50,6 +50,7 @@ from _common.emit import note, warn
 from _common.decision import av_clip_length, av_trim, stream_starts
 from _common.probe import display_size, square_pixels, square_pixels_note
 from _common.timeline import exact_rate
+from _common.emit import input_length
 
 TRANSITIONS = ["fade", "dissolve", "wipeleft", "wiperight", "wipeup", "wipedown", "slideleft", "slideright",
                "circleopen", "circleclose", "fadeblack", "fadewhite", "smoothleft", "smoothright", "radial", "none"]
@@ -704,6 +705,8 @@ def main() -> int:
             skipped=skipped)
     validate_color(args.pad_color, "--pad-color")
     metas = [probe(p) for p in args.inputs]
+    for p, m in zip(args.inputs, metas):
+        input_length(m, p)  # every clip is placed by its length: one that states none is refused, not 0 s (#491)
     # A pending input's probe is the dry-run stub, whose (0x0) video stream says nothing about the
     # file an earlier step will write. Its extension stands in: a step names its output for what
     # it holds, so an audio extension (.wav, .m4a, .aiff, ... -- every audio file this skill

package/scripts/look.py

@@ -25,6 +25,7 @@ from _common import ffmpeg_filters, filter_missing_hint  # noqa: E402
 from _common.emit import note, record_fallback  # noqa: E402
 from _common.color import bt709_label_filter, bt2020_sdr_to_bt709_chain, hdr_to_sdr_chain, is_bt2020_sdr  # noqa: E402
 from _common.probe import PROBED_VIDEO, display_size, square_pixels, square_pixels_note  # noqa: E402
+from _common.emit import input_length  # noqa: E402
 
 # --guides: broadcast safe areas as outlines, in fractions of the frame (a tile as much as a frame).
 # Action and title safe are SMPTE ST 2046-1's 93 % and 90 % of a 16:9 picture; the 4:3 centre cut
@@ -363,6 +364,7 @@ def main() -> int:
         except ValueError:
             die("--tiles must look like 4x3")
         n = cols * rows
+        dur = input_length(meta)  # the sheet is spread over the length: none stated is refused with the way out (#491)
         if not dur:
             die("cannot build a contact sheet without a known duration")
         frames_avail = int((meta["video"].get("fps") or 0) * dur) or 1

package/scripts/loop.py

@@ -36,6 +36,7 @@ from _common import STATE, concat_list_line, add_common, aac_args, apply_common,
 from _common.emit import warn
 from _common.decision import av_trim
 from _common.probe import decode_gray_frames, decode_pcm_mono
+from _common.emit import input_length
 
 
 # The loop filter's size is capped at 32767 frames, so one boomerang cycle (2N-2 frames) must fit.
@@ -248,7 +249,7 @@ def main() -> int:
     meta = probe(args.input)
     if not meta.get("video"):
         die("input has no video stream")
-    src_dur = meta.get("duration") or 0.0
+    src_dur = input_length(meta)  # no stated length: refused with the way out (#491)
     if src_dur <= 0:
         die("input has no measurable duration to loop")
     has_audio = bool(meta.get("audio")) and not args.boomerang

package/scripts/metadata.py

@@ -33,6 +33,7 @@ from typing import Any, Dict, List, Optional
 from _common import (guard_sidecar, add_common, apply_common, default_output, description_block, detect_scenes, detect_silences,
                      die, emit, ffmpeg_base, fmt_chapter_time, info, propose_chapters, time_arg, probe, run,
                      STATE, read_text_or_die)
+from _common.emit import input_length
 
 CHAPTER_CONTAINERS = {".mp4", ".m4v", ".m4a", ".mov", ".mkv", ".mka", ".webm"}
 TAG_KEYS = ("title", "artist", "album", "comment", "date", "genre")
@@ -230,7 +231,8 @@ def main() -> int:
         die(f"{out_ext or 'this'} container cannot hold chapter markers; write to one of "
             f"{', '.join(sorted(CHAPTER_CONTAINERS))} (the streams are copied, so choose the matching family: .mp4/.mov/.m4a for MPEG-4, .mkv/.mka/.webm for Matroska)")
 
-    duration = meta.get("duration") or 0.0
+    # the last chapter ends at the file's end and --auto-chapters spaces them over its length (#491)
+    duration = input_length(meta) if (args.chapters or args.auto_chapters) else (meta.get("duration") or 0.0)
     chapters: Optional[List[Dict[str, Any]]] = parse_chapters(args.chapters, duration) if args.chapters else None
     auto: Optional[Dict[str, Any]] = None
     notes: List[str] = []

package/scripts/multicam.py

@@ -34,8 +34,9 @@ from typing import Dict, List, Tuple
 
 from _common import guard_sidecar, label_chain, matrix_chain, range_chain, video_args, aac_args, add_common, apply_common, default_output, die, emit, ffmpeg_base, info, time_arg, probe, run, x264_args, X264_PRESETS, fmt_secs, decode_pcm_mono, rms_envelope, STATE
 from _common.emit import note, record_fallback, record_skip, warn
-from _common.decision import av_trim, rebase_project_paths
+from _common.decision import av_trim, conform_output_t, conform_to_length, rebase_project_paths
 from _common.probe import display_size, square_pixels, square_pixels_note
+from _common.emit import input_length
 from sync import measure_offset
 
 ENERGY_WINDOW_S = 0.25  # --switch energy: loudness measured over this window on the reference timeline
@@ -187,8 +188,8 @@ def main() -> int:
         ratio = 1.0
         skipped_reason = None
         if args.fix_drift:
-            ref_dur = metas[0]["duration"] or 0.0
-            sec_dur = probe(p)["duration"] or 0.0
+            ref_dur = input_length(metas[0])
+            sec_dur = input_length(probe(p))
             overlap_end = min(ref_dur, sec_dur + off)
             window = 60.0
             head_len = min(args.analyze_seconds, overlap_end)
@@ -242,7 +243,7 @@ def main() -> int:
 
     if args.min_shot <= 0:
         die(f"--min-shot must be positive, got {args.min_shot:g}")
-    ref_dur = metas[0]["duration"] or 0.0
+    ref_dur = input_length(metas[0])
     energy_mode = args.switch == "energy"
     if energy_mode:
         cuts = energy_switch(args.inputs, metas, offsets, ratios, ref_dur, args.min_shot)
@@ -339,12 +340,17 @@ def main() -> int:
         afx += [f"asetrate={sr * ratios[a]:.6f}", f"aresample={sr}"]
     if offsets[a] > 0:
         afx.append(f"adelay={int(round(offsets[a] * 1000))}:all=1")
-    afx += [f"atrim=0:{ref_dur:.3f}", "aformat=sample_rates=48000:channel_layouts=stereo"]
+    # the sound ends with the reference, to the sample (#493), counted at the 48 kHz it is written
+    # in; `atrim=0:{:.3f}` and `-t {:.3f}` cut it to the millisecond. A dry run's pending reference
+    # has no length to count, and keeps the old filter.
+    conformed = ref_dur > 0
+    afx += [conform_to_length(ref_dur, 48000) if conformed else f"atrim=0:{ref_dur:.3f}",
+            "aformat=sample_rates=48000:channel_layouts=stereo"]
     parts.append(f"[{a}:a]{','.join(afx)}[aout]")
 
     output = args.output or default_output(args.inputs[0], "multicam", "mp4")
     cmd += ["-filter_complex", ";".join(parts), "-map", "[vout]", "-map", "[aout]"]
-    cmd += video_args(metas[0], args.crf, args.preset, convert_matrix=False) + aac_args() + ["-t", f"{ref_dur:.3f}", output]
+    cmd += video_args(metas[0], args.crf, args.preset, convert_matrix=False) + aac_args() + ["-t", conform_output_t(ref_dur, 48000) if conformed else f"{ref_dur:.3f}", output]
 
     if args.write_project:
         # Same cut decision as the combined render above (project_clips was built alongside the

package/scripts/scenes.py

@@ -32,6 +32,7 @@ from _common.emit import note, record_fallback  # noqa: E402
 from _common.color import bt709_label_filter  # noqa: E402
 from _common.probe import PROBED_VIDEO, square_pixels  # noqa: E402
 from _common import dry_run_input_pending  # noqa: E402
+from _common.emit import input_length  # noqa: E402
 
 SHOT_FPS = 4.0          # frames/second sampled for --shots' flow estimate
 SHOT_W, SHOT_H = 48, 27  # decode size for --shots (16:9-ish; enough blocks, still a few KB/shot)
@@ -176,7 +177,7 @@ def main() -> int:
             die("--beats needs an audio stream; this file has none", kind="input")
         if args.beat_step <= 0:
             die("--beat-step must be greater than 0", kind="input")
-    dur = meta.get("duration") or 0.0
+    dur = input_length(meta)
     cuts = [0.0] if (audio_only or pending) else detect_scenes(args.input, args.threshold, args.min_scene, dur, args.ratio)
     has_audio = bool(meta.get("audio")) and not pending
     bounds = cuts + [dur]

package/scripts/silence.py

@@ -35,6 +35,7 @@ from _common.emit import refuse
 from _common import detect_silences as detect, STATE, add_common, apply_common, default_output, die, emit, info, is_audio_output, print_json, probe, X264_PRESETS, measured_level_dbfs, fmt_secs
 from _common.decision import frame_rate, stream_starts
 from _common.probe import PROBED_AUDIO
+from _common.emit import input_length
 
 
 
@@ -657,7 +658,7 @@ def main() -> int:
     meta = probe(args.input)
     if not meta.get("audio"):
         die("input has no audio stream to analyse")
-    duration = meta.get("duration") or 0.0
+    duration = input_length(meta)
     breaths: List[Tuple[float, float]] = []
     if args.speech_aware:
         silences, breaths = speech_aware_silences(args.input, args.threshold, args.min_silence)

package/scripts/speedramp.py

@@ -21,6 +21,7 @@ from typing import List, Tuple
 
 from _common.decision import av_trim, 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
 
 MAX_SPEED = 20.0
 MIN_SPEED = 0.05
@@ -72,7 +73,7 @@ def main() -> int:
     meta = probe(args.input)
     if not meta.get("video"):
         die("input has no video stream")
-    dur = meta.get("duration") or 0.0
+    dur = input_length(meta)
     if abs(segments[0][0] - 0.0) > 0.01:
         die(f"segments must start at 0, first segment starts at {segments[0][0]:g}")
     if abs(segments[-1][1] - dur) > 0.5:

package/scripts/sync.py

@@ -38,6 +38,7 @@ from _common.emit import record_skip, warn
 from _common.decision import SEEK_MARGIN, frame_rate, grid_at_or_after, stream_starts
 from _common.timeline import output_timecode_args
 from _common.runner import default_selection_maps
+from _common.emit import input_length
 
 SR = 8000  # decode sample rate
 
@@ -227,8 +228,8 @@ def measure_one(reference: str, path: str, args) -> Dict:
     # the head to measure over) or low_confidence (the tail did not correlate); None when applied
     skipped_reason = None
     if args.fix_drift:
-        ref_dur = probe(reference)["duration"] or 0.0
-        sec_dur = probe(path)["duration"] or 0.0
+        ref_dur = input_length(probe(reference))
+        sec_dur = input_length(probe(path))
         overlap_end = min(ref_dur, sec_dur + offset)
         head_len = min(args.analyze_seconds, overlap_end)
         tail_start = overlap_end - args.drift_window