ffmpeg-skill 3.8.1 → 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.1`) | 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.1", "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.1",
+  "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/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,6 +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.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
@@ -893,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/_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/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/graphics.py

@@ -44,7 +44,7 @@ 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
@@ -750,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/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: