ffmpeg-skill 3.8.0 → 3.8.2

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.2`) | 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.2", "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"},
@@ -835,7 +835,7 @@ Keys added for the alpha path beyond `export.py` (additive; the `alpha` step on
 
 | key | tool | what it holds |
 |---|---|---|
-| `alpha_codec`, `alpha_mode`; step `alpha` | `color.py --correct/--lut --keep-alpha`, `graphics.py --keep-alpha`, `overlay.py --keep-alpha`, `background.py --transparent` | `alpha_codec`: the alpha line written (`--alpha-codec prores4444` (default), `qtrle`, `png`, `vp9`; the output must be a container that holds it, `.mov`/`.mkv`, `.mov` for qtrle, `.webm`/`.mkv` for vp9). `alpha_mode`: `straight` or `premultiplied` (`--alpha-mode`). The line keeps the source's colour tags and converts no matrix, as `--codec prores` does; `--codec` and `--keep-alpha` together are refused, and `--hw` leaves the line on the CPU. `alpha` step: `written {codec, pix_fmt, alpha_plane}` read back, `frames {expected, measured}`. `color.py`: the alpha is split off before the grade and merged back, so the written alpha must equal the source's frame by frame within 2 of 255 (`comparison {ok, paired, worst_delta, worst_frame}`). `graphics.py`/`overlay.py` (`property: alpha_at_least_source`): drawn layers add coverage, so every written frame's alpha must be at or above the source's within 2 of 255, the stream must store an alpha plane, and the output must not have turned opaque in every frame the source was transparent in (`reason`: `alpha_below_source`, `no_alpha_plane`, `opaque_everywhere`). `background.py --transparent`: every frame's alpha read back as 0 (`provenance: specification`). `--keep-alpha` on a source with no alpha plane is refused (`kind: input`) |
+| `alpha_codec`, `alpha_mode`; step `alpha` | `color.py --correct/--lut --keep-alpha`, `graphics.py --keep-alpha`, `overlay.py --keep-alpha`, `background.py --transparent` | `alpha_codec`: the alpha line written (`--alpha-codec prores4444` (default), `qtrle`, `png`, `vp9`; the output must be a container that holds it, `.mov`/`.mkv`, `.mov` for qtrle, `.webm`/`.mkv` for vp9). `alpha_mode`: `straight` or `premultiplied` (`--alpha-mode`). The line keeps the source's colour tags and converts no matrix, as `--codec prores` does (an RGB source that is neither HDR nor BT.2020, on a `prores4444`/`vp9` line has no matrix to keep: it is converted to BT.709 and tagged so; an HDR or BT.2020 one is not: FFmpeg's own conversion makes its YUV, as before); `--codec` and `--keep-alpha` together are refused, and `--hw` leaves the line on the CPU. `alpha` step: `written {codec, pix_fmt, alpha_plane}` read back, `frames {expected, measured}`. `color.py`: the alpha is split off before the grade and merged back, so the written alpha must equal the source's frame by frame within 2 of 255 (`comparison {ok, paired, worst_delta, worst_frame}`). `graphics.py`/`overlay.py` (`property: alpha_at_least_source`): drawn layers add coverage, so every written frame's alpha must be at or above the source's within 2 of 255, the stream must store an alpha plane, and the output must not have turned opaque in every frame the source was transparent in (`reason`: `alpha_below_source`, `no_alpha_plane`, `opaque_everywhere`). `background.py --transparent`: every frame's alpha read back as 0 (`provenance: specification`). `--keep-alpha` on a source with no alpha plane is refused (`kind: input`) |
 | `alpha_dropped`; step `alpha` with `reason: alpha_dropped` | `color.py --correct/--lut/--to-sdr` (and `--retag` when its copy falls back to a re-encode), `graphics.py`, `overlay.py` without `--keep-alpha` | on a source whose alpha is used (a frame below opaque; measured, streamed frame by frame, only when the source stores an alpha plane or a palette, so an opaque source runs and reports exactly as before; a stored plane whose alpha cannot be read counts as used and a kept step on it fails with `reason: source_alpha_unmeasured`; a VP9 source or layer with alpha needs the libvpx-vp9 decoder, `error.reason: decoder_missing` without it): the output's opaque line drops it, so the `alpha` step fails (`attribution: artifact`, a `hint`, an `alpha_dropped` warning) and `verified` is false. `--drop-alpha` says an opaque output is wanted: no step, `alpha_dropped: true` and a note. An `overlay.py --video` layer with alpha keeps it: a VP9 one is decoded with libvpx-vp9, an RGB one (qtrle, PNG) is converted to BT.709 with its alpha plane |
 
 Per-tool keys added after 2.10.11 ("nothing happens silently"), all additive:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "3.8.0",
+  "version": "3.8.2",
   "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/gotchas.md

@@ -76,7 +76,8 @@ opaque and the result says `verified: false` with a failing `alpha` step (`alpha
 transparency, start from `background.py --transparent --duration 5 --width 1920 --height 1080 -o canvas.mov`
 and draw one element on it
 with `graphics.py`/`overlay.py --keep-alpha`. An alpha line keeps the source's colour tags (as
-`--codec prores` does). `--alpha-mode premultiplied` multiplies the written colour by the alpha;
+`--codec prores` does); an RGB source that is neither HDR nor BT.2020 (qtrle, PNG) written to ProRes 4444 or VP9 becomes BT.709
+YUV, tagged BT.709. `--alpha-mode premultiplied` multiplies the written colour by the alpha;
 sources are taken as straight. A VP9 layer with alpha is decoded with libvpx-vp9; FFmpeg's own VP9
 decoder drops the alpha.
 

package/references/scripts.md

@@ -1457,7 +1457,7 @@ graphics.py INPUT --template lower-third|title|chapter|progress|countdown|bug|st
 ```
 `--keep-alpha` draws the template on the input's alpha (a canvas from `background.py --transparent`,
 or any alpha clip) and writes it in an alpha line (see `background.py`; ProRes 4444 by default) with
-the source's colour tags kept: boxes and bars are composited as layers with their alpha, drawtext and
+the source's colour tags kept (an RGB input that is neither HDR nor BT.2020, on a ProRes 4444/VP9 line: BT.709 YUV, tagged BT.709): boxes and bars are composited as layers with their alpha, drawtext and
 libass (`alpha=1`) draw into the alpha, all at 4:4:4. The `alpha` step checks that the written
 stream stores an alpha plane, that no frame's alpha fell below the source's, and that the output
 did not go opaque in every frame the source was transparent in. Without `--keep-alpha` on a source
@@ -1870,7 +1870,8 @@ overlay.py INPUT --image PNG [--scale W | --scale-percent P] | --text "..." [--f
            [--keep-alpha [--alpha-codec prores4444|qtrle|png|vp9] [--alpha-mode straight|premultiplied] | --drop-alpha]
 ```
 `--keep-alpha` composites onto the input's alpha (a `background.py --transparent` canvas or an alpha
-clip) and writes the result in an alpha line with the source's tags kept, checked as
+clip) and writes the result in an alpha line with the source's tags kept (an RGB input that is neither HDR nor BT.2020, on a
+ProRes 4444/VP9 line: BT.709 YUV, tagged BT.709), checked as
 `graphics.py --keep-alpha` is. A `--video` layer with alpha keeps it: VP9 with alpha (`export.py
 --preset vp9-alpha`) is decoded with libvpx-vp9 (FFmpeg's own VP9 decoder drops the alpha), and an
 RGB layer (qtrle, PNG in .mov, e.g. a `graphics.py --keep-alpha` element) is converted to BT.709 with
@@ -1981,7 +1982,9 @@ color.py INPUT --correct ... | --lut grade.cube ... -o OUT.mov [--keep-alpha [--
 `--keep-alpha` (with `--correct` or `--lut`) grades an alpha clip and keeps its alpha: the alpha is
 split off before the grade, never touched, and merged back in front of the alpha line (ProRes 4444
 by default, `--alpha-codec qtrle|png|vp9`); the grade runs at 4:4:4 and the source's colour tags are
-kept (no BT.709 conversion, as `--codec prores`). The `alpha` step compares the written alpha with
+kept (no BT.709 conversion, as `--codec prores`). An RGB source that is neither HDR nor BT.2020 (qtrle, PNG in `.mov`) has no matrix
+to keep: a ProRes 4444 or VP9 line of it is BT.709 YUV and tagged BT.709 (an HDR or BT.2020 one is not: FFmpeg's own conversion makes its YUV, as before), a qtrle or PNG line keeps
+its RGB. The `alpha` step compares the written alpha with
 the source's frame by frame on 64x36 copies, each within 2 of 255. A source without an alpha plane is
 refused. Without `--keep-alpha`, a grade of a source whose alpha is used writes opaque H.264 and the
 `alpha` step fails (`reason: alpha_dropped`, `verified: false`); `--drop-alpha` makes it a note

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

@@ -9,7 +9,9 @@ background.py's transparent canvas can do the same:
   writes a fully transparent canvas in the same lines. `--alpha-mode straight|premultiplied` says
   how the colour is stored, as export.py's does.
 - An alpha line keeps the source's colour tags and converts no matrix, as `--codec prores` does
-  (`keeps_source_tags()` in decision.py): an alpha master is an editing master.
+  (`keeps_source_tags()` in decision.py): an alpha master is an editing master. An RGB source has
+  no matrix to keep: on a line that stores YUV (ProRes 4444, VP9) it is converted to BT.709 and
+  tagged so (`rgb_to_bt709_line()`, #496); on an RGB line (qtrle, PNG) it stays the RGB it was.
 - Every completed run on a source whose alpha is really used (a frame below OPAQUE) gets an
   `alpha` verification step. Without `--keep-alpha` the output's picture has no alpha and that step
   fails (the output reported `verified: true` with the alpha gone before this module existed);
@@ -25,7 +27,7 @@ import threading
 from typing import Any, Dict, List, Optional
 
 from _common import runner as _runner
-from _common.color import carried_tag
+from _common.color import carried_tag, is_rgb, rgb_to_bt709_filter
 from _common.runner import STATE, ffmpeg_encoders, require_tool, run
 
 # A pixel format that carries an alpha plane (yuva*, rgba, argb, gbrap, ya8/ya16, ...).
@@ -283,13 +285,72 @@ def audio_line(codec: str) -> List[str]:
 
 _TAG_KEYS = (("colorspace", "color_space", "-colorspace"), ("color_primaries", "color_primaries", "-color_primaries"),
              ("color_trc", "color_transfer", "-color_trc"))
+# swscale's name for a tagged SDR matrix (scale=in_color_matrix / out_color_matrix)
+_SWS_MATRIX = {"bt709": "bt709", "smpte170m": "bt601", "bt470bg": "bt601", "smpte240m": "smpte240m", "fcc": "fcc"}
+
+
+def rgb_to_bt709_line(meta: Optional[Dict[str, Any]], codec: Optional[str] = None) -> bool:
+    """True when the alpha line being written (`codec`, default STATE.alpha_line) stores YUV
+    (ProRes 4444, VP9) and the source `meta` probes is RGB (qtrle, PNG in .mov/.mkv, an image).
+
+    An RGB source has no matrix for the line to keep, and the one FFmpeg picks where the graph
+    first needs YUV is BT.601, written with no tag on 6.1: a 1280x720 ProRes 4444 master of a
+    qtrle clip was read as BT.709 by every player and showed 30C050 as 26AB4D (#496). Such a
+    source is converted to BT.709 (source_format(); color.py's grade legs), RGB layers are
+    converted to match (decision.rgb_chain_to_bt709) and the line is tagged BT.709 (_source_tags),
+    as the H.264 line does for an RGB source. An RGB line (qtrle, PNG) is left as it was; an
+    HDR/BT.2020 source is not converted to BT.709 here (FFmpeg's own conversion makes its YUV, as
+    before)."""
+    codec = codec or STATE.alpha_line
+    v = (meta or {}).get("video") or {}
+    return bool(codec) and ALPHA_CODECS[codec]["pix_fmt"].startswith("yuv") and is_rgb(meta) and not v.get("bt2020_or_hdr")
+
+
+def source_format(meta: Optional[Dict[str, Any]]) -> str:
+    """The filter that starts a compositing graph on an alpha line: the source at 4:4:4 with its
+    alpha plane. An RGB source on a YUV line gets there by an explicit BT.709 conversion
+    (rgb_to_bt709_line); a palette is expanded first, because swscale turns one into YUV with
+    BT.601 whatever matrix is asked for. Every other source: `format=yuva444p`, as before."""
+    if rgb_to_bt709_line(meta):
+        pal = ((meta or {}).get("video") or {}).get("pix_fmt") == "pal8"
+        return ("format=rgba," if pal else "") + rgb_to_bt709_filter("yuva444p")
+    return "format=yuva444p"
+
+
+def rgb_line(codec: Optional[str] = None) -> bool:
+    """True when the alpha line being written stores RGB (qtrle, PNG)."""
+    codec = codec or STATE.alpha_line
+    return bool(codec) and not ALPHA_CODECS[codec]["pix_fmt"].startswith("yuv")
+
+
+def matrix_label(meta: Optional[Dict[str, Any]]) -> str:
+    """",setparams=colorspace=<the source's matrix>" to end a YUV chain with that an RGB line
+    (qtrle, PNG) converts, or "" (a YUV line, an untagged or RGB source).
+
+    finish_chain() labels the frames after the last filter of the graph, but FFmpeg places the
+    conversion to an RGB line where the formats first differ, which in color.py is in front of
+    `alphamerge` and so in front of that label: the graded YUV of a BT.709-tagged source reached
+    it untagged (6.1) or carrying the grade legs' working matrix (7.1+) and was read as BT.601
+    (30C050 written as 3CD753). Labelled here, the conversion reads the matrix the samples are in."""
+    if not rgb_line() or is_rgb(meta):
+        return ""
+    space = [val for p, val, _ in _source_tags(meta, "setparams") if p == "colorspace"]
+    return f",setparams=colorspace={space[0]}" if space else ""
 
 
 def _source_tags(meta: Optional[Dict[str, Any]], dest: str = "option") -> List[tuple]:
     """(setparams name, value, output option) per source tag that is passed on, the value spelled
-    for `dest` (carried_tag: an RGB source's `gbr` is left out, #454)."""
+    for `dest` (carried_tag: an RGB source's `gbr` is left out, #454). An RGB source on a YUV line
+    (rgb_to_bt709_line) is BT.709 YUV by then and says so: matrix bt709, and bt709 for a primaries
+    or transfer tag the source does not carry (the H.264 line's reading of an untagged picture)."""
     v = (meta or {}).get("video") or {}
-    tags = [(param, carried_tag(param, v.get(key), dest), flag) for param, key, flag in _TAG_KEYS]
+    to_709 = rgb_to_bt709_line(meta)
+    # the matrix is the one the conversion used, whatever the RGB source's own tag says (a qtrle
+    # clip retagged smpte170m would label its BT.709 samples BT.601); primaries and transfer are
+    # not converted, so the source's own are kept when it has them
+    tags = [(param, "bt709" if to_709 and param == "colorspace"
+             else carried_tag(param, v.get(key), dest) or ("bt709" if to_709 else None), flag)
+            for param, key, flag in _TAG_KEYS]
     return [t for t in tags if t[1]]
 
 
@@ -300,15 +361,24 @@ def finish_chain(codec: str, mode: Optional[str], meta: Optional[Dict[str, Any]]
     format (so no later conversion can drop the plane)."""
     tags = _source_tags(meta, "setparams")
     label = ("setparams=" + ":".join(f"{p}={val}" for p, val, _ in tags) + ",") if tags else ""
+    pix = ALPHA_CODECS[codec]["pix_fmt"]
     # premultiplied colour is colour x alpha in RGB: multiplied there (a YUV premultiply scales the
     # limited-range offsets too), after the tags are back so both conversions use the same matrix
-    return (label + ("format=gbrap,premultiply=inplace=1," if mode == "premultiplied" else "")
-            + f"format={ALPHA_CODECS[codec]['pix_fmt']}")
+    pre = "format=gbrap,premultiply=inplace=1," if mode == "premultiplied" else ""
+    matrix = _SWS_MATRIX.get(next((val for p, val, _ in tags if p == "colorspace"), None))
+    if pre and matrix and pix.startswith("yuv"):
+        # ... which 6.1 does not do by itself on a tagged YUV line: the way to RGB is placed in
+        # front of color.py's alphamerge (so in front of the label, and reads BT.601) and the way
+        # back takes swscale's BT.601 default whatever the frames say, so an opaque 30C050 of a
+        # BT.709 line came back 3CD753 (color.py) or 25AC4E (overlay.py). Both legs name the matrix.
+        pre = f"scale=in_color_matrix={matrix},format=gbrap,premultiply=inplace=1,scale=out_color_matrix={matrix},"
+    return label + pre + f"format={pix}"
 
 
 def tag_args(meta: Optional[Dict[str, Any]]) -> List[str]:
     """The source's colour tags as output options, so the written stream says what the frames do
-    (an alpha line keeps the source's tags, as --codec prores does)."""
+    (an alpha line keeps the source's tags, as --codec prores does; an RGB source on a YUV line is
+    tagged the BT.709 it was converted to)."""
     out: List[str] = []
     for _p, val, flag in _source_tags(meta):
         out += [flag, val]

package/scripts/_common/decision.py

@@ -15,7 +15,8 @@ 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.alpha import rgb_to_bt709_line
+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 +432,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 +465,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
@@ -869,9 +894,11 @@ def rgb_chain_to_bt709(line_meta: Optional[Dict[str, Any]], pix_fmt: str = "yuva
     with (rgb_to_bt709_filter), or "" when the line does not tag BT.709 (the lines matrix_chain()
     leaves alone). Without it the graph's own RGB-to-YUV step used FFmpeg's BT.601 default."""
     v = (line_meta or {}).get("video") or {}
-    if STATE.alpha_line is not None and v.get("color_space") == "bt709" and not v.get("bt2020_or_hdr"):
+    if (STATE.alpha_line is not None and (v.get("color_space") == "bt709" or rgb_to_bt709_line(line_meta))
+            and not v.get("bt2020_or_hdr")):
         # an alpha line keeps the source's tags: on a BT.709-tagged picture an RGB layer is made
-        # BT.709 too (FFmpeg 6.1's own conversion is BT.601), in 4:4:4 with its alpha plane
+        # BT.709 too (FFmpeg 6.1's own conversion is BT.601), in 4:4:4 with its alpha plane. An
+        # RGB source on a YUV line is a BT.709 picture as well (alpha.rgb_to_bt709_line, #496)
         return "," + rgb_to_bt709_filter("yuva444p")
     if keeps_source_tags() or v.get("bt2020_or_hdr"):
         return ""

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

@@ -578,6 +578,7 @@ def alpha_result_schema(name: str) -> Dict[str, Any]:
     if name == "background":
         out["alpha_codec"]["description"] += ". The `alpha` verification step reads every written frame back and expects alpha 0 (provenance specification)"
         return out
+    out["alpha_codec"]["description"] += " (an RGB source that is neither HDR nor BT.2020, on a prores4444/vp9 line has no matrix to keep: it is converted to BT.709 and tagged so; an HDR or BT.2020 one is not: FFmpeg's own conversion makes its YUV, as before)"
     out["alpha_dropped"] = {"type": "boolean", "description": "true when the source's alpha is used (a frame below opaque, or a stored alpha plane that could not be read) and the output does not keep it (color.py --retag too, when its copy fell back to an H.264 re-encode): without --keep-alpha the `alpha` verification step fails (reason alpha_dropped, attribution artifact, with an alpha_dropped warning); with --drop-alpha there is no such step and a note says the alpha was dropped on purpose. Absent on a source without alpha"}
     if name == "color":
         out["alpha_codec"]["description"] += ". --correct / --lut only: the grade works on the colour (at 4:4:4) and the source's alpha is merged back unchanged; the `alpha` step compares the written alpha with the source's frame by frame, tolerance 2 of 255 (comparison {ok, paired, worst_delta, worst_frame}; frames {expected, measured}; written {codec, pix_fmt, alpha_plane})"

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

@@ -35,8 +35,10 @@ from typing import List, Optional
 from _common.runner import fail_if_classified
 from _common import STATE, add_common, analyze_levels, LEGAL_RANGE_CHOICES, legal_limits, measure_signal_range, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, ffmpeg_bsfs, info, probe, require_tool, run, run_analysis, run_keeping_subtitles, x264_args, X264_PRESETS, fmt_secs
 from _common.emit import note, warn
+from _common.color import is_rgb, rgb_to_bt709_filter
 from _common.alpha import (add_alpha_args, audio_line, check_alpha_args, decoder_args_for, default_ext, finish_chain,
-                           report as alpha_report, source_alpha, tag_args, video_line)
+                           matrix_label, report as alpha_report, rgb_line, rgb_to_bt709_line, source_alpha, tag_args,
+                           video_line)
 from _common.decision import keeps_source_tags
 from _common.color import bt2020_sdr_to_bt709_chain, hdr_to_sdr_chain, is_bt2020_sdr  # noqa: E402,F401
 
@@ -97,7 +99,8 @@ def _checked_levels(args: argparse.Namespace, flag: str) -> int:
     return value
 
 
-def correction_chain(args: argparse.Namespace, out_fmt: str = "yuv420p") -> str:
+def correction_chain(args: argparse.Namespace, out_fmt: str = "yuv420p", matrix: str = "bt601",
+                     rgb_in: bool = False) -> str:
     """Always-present filter stages, in a fixed order chosen so each stage sees a picture already
     corrected by the previous one: exposure (linear light level) -> white balance (temperature/tint/
     lift/gain, so contrast/saturation act on colour-balanced footage) -> contrast/saturation/gamma
@@ -137,7 +140,7 @@ def correction_chain(args: argparse.Namespace, out_fmt: str = "yuv420p") -> str:
         # "unchanged" adds no term at all
         rgb.append(f"colortemperature=temperature={temperature:g}")
     rgb.append(f"colorbalance=rs={lift:g}:gs={lift:g}:bs={lift:g}:rm={rm:g}:gm={gm:g}:bm={bm:g}:rh={gain:g}:gh={gain:g}:bh={gain:g}")
-    terms = [_rgb_stage(rgb, out_fmt), f"eq=contrast={contrast:g}:saturation={saturation:g}:gamma={gamma:g}"]
+    terms = [_rgb_stage(rgb, out_fmt, matrix, rgb_in), f"eq=contrast={contrast:g}:saturation={saturation:g}:gamma={gamma:g}"]
     rgb2 = []
     if (in_black, in_white, out_black, out_white) != (0, 255, 0, 255):
         rimin, rimax = in_black / 255.0, in_white / 255.0
@@ -151,11 +154,11 @@ def correction_chain(args: argparse.Namespace, out_fmt: str = "yuv420p") -> str:
     if args.curves:
         rgb2.append(f"curves=preset={args.curves}")
     if rgb2:
-        terms.append(_rgb_stage(rgb2, out_fmt))
+        terms.append(_rgb_stage(rgb2, out_fmt, matrix))
     return ",".join(terms)
 
 
-def _rgb_stage(filters: list, out_fmt: str = "yuv420p") -> str:
+def _rgb_stage(filters: list, out_fmt: str = "yuv420p", matrix: str = "bt601", rgb_in: bool = False) -> str:
     """Wrap a run of RGB-only filters in explicit, matching YUV<->RGB conversions.
 
     exposure/colortemperature/colorbalance/colorlevels/curves take RGB, so libavfilter inserts a
@@ -168,9 +171,41 @@ def _rgb_stage(filters: list, out_fmt: str = "yuv420p") -> str:
     sides measured better than bt709 on both (34 dB) because swscale's 601 path round-trips
     8-bit 4:2:0 more exactly. The matrix here is only the working space of the conversion pair,
     never a tag: the output carries the encoder's BT.709 tags as before. `out_fmt` is yuv444p for
-    an alpha line (--keep-alpha), whose 4:4:4 master would otherwise get 4:2:0 chroma."""
-    return ("scale=in_color_matrix=bt601,format=gbrpf32le," + ",".join(filters)
-            + f",scale=out_color_matrix=bt601,format={out_fmt}")
+    an alpha line (--keep-alpha), whose 4:4:4 master would otherwise get 4:2:0 chroma.
+
+    The pair cancels only when the picture comes in as YUV. An RGB source (qtrle, PNG in .mov)
+    meets no matrix on the way in, so the way out is the one real RGB-to-YUV conversion of the
+    graph and `matrix` is the matrix of the YUV that leaves it. The H.264 line converts such a
+    source to BT.709 YUV first (x264_args(source=...)), so the pair cancels there as well. An
+    alpha line converts nothing in front, and with bt601 here its ProRes 4444 or VP9 master of an
+    RGB source held BT.601 YUV under no tag, which a player reads as BT.709 at HD (30C050 shown as
+    26AB4D, #496): for an RGB source on a YUV alpha line `matrix` is bt709 (working_matrix()),
+    and the line is tagged so. A later stage of the same chain takes the same matrix on both legs.
+
+    `rgb_in`: the picture reaches this stage as RGB (the first stage of an RGB source on an alpha
+    line), so the way in names no matrix. It has none to read, and with
+    `scale=in_color_matrix=bt709` in front of RGB frames FFmpeg 7.1 wrote BT.601 samples whatever
+    the way out asked for (30C050 as 26AB4D again; 6.1 was right either way). Seen in CI, not
+    traced inside FFmpeg: --lut-strength 0, whose chain has the way out alone, was right there."""
+    way_in = "format=gbrpf32le," if rgb_in else f"scale=in_color_matrix={matrix},format=gbrpf32le,"
+    return (way_in + ",".join(filters)
+            + f",scale=out_color_matrix={matrix},format={out_fmt}")
+
+
+def working_matrix(meta=None) -> "str | None":
+    """The matrix of the YUV an RGB source's grade writes on an alpha line, or None for every other
+    case (a YUV source, the H.264 line), whose legs are what they were.
+
+    bt709 on a line that stores YUV (ProRes 4444, VP9): that YUV is the master, tagged BT.709
+    (alpha.rgb_to_bt709_line). bt601 on a line that stores RGB (qtrle, PNG): the YUV is only the
+    grade's working format and FFmpeg converts it back for the line with its own default, BT.601
+    (unlabelled frames on 6.1, the tag the leg wrote on 7.1+), so the legs use that and the written
+    RGB is the graded RGB. --lut's legs said bt709 there and an identity LUT wrote 30C050 as 3CD753."""
+    if rgb_to_bt709_line(meta):
+        return "bt709"
+    if rgb_line() and is_rgb(meta):
+        return "bt601"
+    return None
 
 
 # swscale's names for the non-BT.709 matrices a --codec prores re-encode keeps (it does not convert)
@@ -195,8 +230,12 @@ def lut_legs(meta=None, out_fmt: str = "yuv420p") -> "tuple":
     matrix = "bt709"
     if keeps_source_tags():
         matrix = _SWS_MATRIX.get(((meta or {}).get("video") or {}).get("color_space"), "bt709")
-    return (f"scale=in_color_matrix={matrix},format=gbrpf32le",
-            f"scale=out_color_matrix={matrix}:out_range=tv,format={out_fmt}")
+        # an RGB source on an alpha line: the matrix of the YUV its line is written from (#496)
+        matrix = working_matrix(meta) or matrix
+    # an RGB source on an alpha line reaches the way in as RGB: no matrix is named there (see
+    # _rgb_stage's rgb_in; with one, FFmpeg 7.1 wrote BT.601 samples)
+    way_in = "format=gbrpf32le" if keeps_source_tags() and working_matrix(meta) else f"scale=in_color_matrix={matrix},format=gbrpf32le"
+    return (way_in, f"scale=out_color_matrix={matrix}:out_range=tv,format={out_fmt}")
 
 
 # --retag targets: ffprobe's names (colorspace, primaries, transfer) and the ITU-T H.273 code points
@@ -507,7 +546,8 @@ def main() -> int:
         if v.get("bt2020_or_hdr") and not args.force:
             die(f"{args.input} is HDR ({v.get('hdr_format')}); --correct works on SDR pixels and would tag PQ/HLG data as BT.709 "
                 f"without a tone map (sweep F10). Run --to-sdr first, or --force to grade the raw values anyway")
-        vf = "" if args.legalize and correction_is_identity(args) else correction_chain(args, out_fmt)
+        vf = ("" if args.legalize and correction_is_identity(args)
+              else correction_chain(args, out_fmt, working_matrix(meta) or "bt601", working_matrix(meta) is not None))
         output = args.output or default_output(args.input, "correct", ext)
         tag = "correct"
         # OBSERVED technical measurements (signalstats: luma / saturation distribution), never a
@@ -528,7 +568,9 @@ def main() -> int:
             # below) landed in the same "apply the LUT at full strength" fallback as an out-of-range
             # value did before the guard above existed: the one strength value documented to mean
             # "don't grade it" instead silently graded it at 100%, the opposite of what was asked.
-            vf = f"format={out_fmt}"
+            # (an RGB source on a YUV alpha line is still converted to the BT.709 that line is, #496)
+            vf = (("format=rgb24," if v.get("pix_fmt") == "pal8" else "") + rgb_to_bt709_filter(out_fmt)
+                  if rgb_to_bt709_line(meta) else f"format={out_fmt}")
         elif args.lut_strength < 1.0:
             # blend graded and original
             # blended in RGB, both pictures through the same two legs
@@ -550,8 +592,10 @@ def main() -> int:
     if alpha_codec:
         # --keep-alpha: the grade works on the colour and never touches the alpha, which is split off
         # the source, kept as it is and merged back (alphamerge) in front of the alpha line; the
-        # source's colour tags are kept, as --codec prores keeps them (no BT.709 conversion)
-        fc = (f"[0:v]split[ka_c][ka_a];[ka_c]{vf}[ka_g];[ka_a]alphaextract[ka_m];"
+        # source's colour tags are kept, as --codec prores keeps them (no BT.709 conversion). An
+        # RGB source has none: its YUV line is BT.709 and tagged so (working_matrix). An RGB line
+        # converts the graded YUV in front of alphamerge, so the matrix is labelled there too
+        fc = (f"[0:v]split[ka_c][ka_a];[ka_c]{vf}{matrix_label(meta)}[ka_g];[ka_a]alphaextract[ka_m];"
               f"[ka_g][ka_m]alphamerge,{finish_chain(alpha_codec, args.alpha_mode, meta)}[ka_v]")
         cmd = ffmpeg_base() + decoder_args_for(meta, args.input) + ["-i", args.input, "-filter_complex", fc,
                                                                      "-map", "[ka_v]", "-map", f"0:a:{args.audio_stream}?"]

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

@@ -44,11 +44,12 @@ from _common import (guard_sidecar, require_filter, aac_args, add_common, brand_
                      SAFE_WIDTH_FRACTION, drawtext_draws_newline_glyph, is_multiline, _DRAWTEXT_PENDING)
 from _common.emit import note, warn
 from _common.alpha import (add_alpha_args, audio_line, check_alpha_args, decoder_args_for, default_ext, finish_chain,
-                           report as alpha_report, source_alpha, tag_args, video_line)
+                           report as alpha_report, source_alpha, source_format, tag_args, video_line)
 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:
@@ -749,8 +750,8 @@ def main(force_route: Optional[str] = None) -> int:
         # 4:4:4 (overlay's default is 4:2:0); drawtext and libass (alpha=1) draw into the alpha too
         fc = [c.replace(":eof_action=pass", ":eof_action=pass:format=yuv444") for c in fc]
         if fc:
-            fc = ["[0:v]format=yuva444p[ka0]"] + [c.replace("[0:v]", "[ka0]") for c in fc]
-        square = "format=yuva444p" + ("," + square if square else "")
+            fc = [f"[0:v]{source_format(meta)}[ka0]"] + [c.replace("[0:v]", "[ka0]") for c in fc]
+        square = source_format(meta) + ("," + square if square else "")
     elif overlay_format(meta):
         # a 10-bit picture on a 10-bit line is composited at 10 bits (overlay's default is 8-bit)
         fc = [c.replace(":eof_action=pass", ":eof_action=pass" + overlay_format(meta)) for c in fc]

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

@@ -37,8 +37,9 @@ from _platforms import PLATFORMS, PLATFORM_CHOICES, safe_margins_px, resolve as
 from _common import still_input_args  # noqa: E402
 from _common import STATE, script_font_for_text, drawtext_clean, drawtext_line_metrics, drawtext_text_opts, drawtext_draws_newline_glyph, is_multiline, needs_shaping, LANGUAGE_NAMES, has_emoji, detect_script, emoji_clusters, load_brand, drawn_chain, label_chain, layer_base_chain, matrix_chain, overlay_format, range_chain, rgb_chain_to_bt709, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_drawtext, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, X264_PRESETS, time_arg, fmt_secs
 from _common.emit import note, warn
+from _common.color import is_rgb
 from _common.alpha import (add_alpha_args, audio_line, check_alpha_args, decoder_args_for, default_ext, finish_chain,
-                           has_alpha_plane, report as alpha_report, source_alpha, tag_args, video_line)
+                           has_alpha_plane, report as alpha_report, source_alpha, source_format, tag_args, video_line)
 from _common.probe import display_size, square_pixels, square_pixels_note
 from _common.wrap import wrap_text
 from _common import text_width_em
@@ -490,9 +491,27 @@ def main() -> int:
         # an alpha line composites at 4:4:4: the layer is not taken through 4:2:0 on the way
         # a 10-bit layer over a main overlay_format() composites at 10 bits stays 10-bit
         deep = bool(overlay_format(meta)) and (pip_meta["video"].get("bit_depth") or 8) > 8
-        chain.append("format=yuva444p" if alpha_codec else "format=yuva420p10le" if deep else "format=yuva420p")
+        keyed_601 = False
+        if alpha_codec and is_rgb(pip_meta) and rgb_chain_to_bt709(meta):
+            # an RGB layer (qtrle, PNG in .mov) on an alpha line that is BT.709 (a BT.709-tagged
+            # main, or an RGB main on a ProRes 4444/VP9 line): matrix_chain() converts nothing on
+            # an alpha line, so the layer became YUV with FFmpeg's BT.601 default and pure red
+            # read FF1800 under the line's tag (#496's sweep)
+            pal = "format=rgba," if pip_meta["video"].get("pix_fmt") == "pal8" else ""
+            if args.chromakey:
+                # chromakey turns its RGB key into YUV with BT.601 whatever the frames say, so the
+                # layer is keyed as BT.601 YUV (what it was before #496, and what the key is
+                # computed in) and taken to the line's BT.709 after the key
+                chain.append(pal + "scale=out_color_matrix=bt601:out_range=tv,format=yuva444p")
+                keyed_601 = True
+            else:
+                chain.append(pal + rgb_chain_to_bt709(meta).lstrip(","))
+        else:
+            chain.append("format=yuva444p" if alpha_codec else "format=yuva420p10le" if deep else "format=yuva420p")
         if args.chromakey:
             chain.append(f"chromakey={args.chromakey}:{args.chromakey_similarity:g}:{args.chromakey_blend:g}")
+            if keyed_601:
+                chain.append("scale=in_color_matrix=bt601:out_color_matrix=bt709:in_range=tv:out_range=tv,format=yuva444p")
         if args.opacity < 1:
             # the alpha is scaled in YUV: colorchannelmixer takes RGB only, so FFmpeg converted the
             # layer to RGB and overlay=format=auto then composited the whole main picture in RGB,
@@ -588,12 +607,12 @@ def main() -> int:
         cmd[first:first] = decoder_args_for(meta, args.input)
         if "-filter_complex" in cmd:
             i = cmd.index("-filter_complex") + 1
-            cmd[i] = ("[0:v]format=yuva444p[ka0];" + cmd[i].replace("[0:v]", "[ka0]").replace(":format=auto", ":format=yuv444")
+            cmd[i] = (f"[0:v]{source_format(meta)}[ka0];" + cmd[i].replace("[0:v]", "[ka0]").replace(":format=auto", ":format=yuv444")
                       + f";[out]{finish}[ka_v]")
             cmd[cmd.index("[out]")] = "[ka_v]"
         else:
             i = cmd.index("-vf") + 1
-            cmd[i] = f"format=yuva444p,{cmd[i]},{finish}"
+            cmd[i] = f"{source_format(meta)},{cmd[i]},{finish}"
         cmd += video_line(alpha_codec) + tag_args(meta) + cfr_args(meta)
         cmd += audio_line(alpha_codec) if meta.get("audio") else ["-an"]
         if STATE.hw:

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