ffmpeg-skill 3.6.5 → 3.6.6

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.6.5`) | any release |
+| `skill.version` | the npm / package.json version (`3.6.6`) | 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.6.5", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "3.6.6", "execution_mode": "local", "kind": "execution",
             "entrypoints": {"cli": "...", "mcp": "...", "contract": "...", "doctor": "..."},
             "not_provided": ["AI reasoning", "decisions", "production plans", "project IR", "approvals", "network access", "transcription engine"]},
   "requirements": {"python": ">=3.10 (standard library only)", "ffmpeg": ">=6.1", "ffprobe": ">=6.1"},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "3.6.5",
+  "version": "3.6.6",
   "mcpName": "io.github.kajisho5/ffmpeg-skill",
   "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 42 FFmpeg tools with a machine-readable contract, contract-derived MCP server, FFmpeg capability detection, probe-first / verify-last workflow. Cut, join, silence removal, fit, captions and karaoke, overlays, motion graphics, HDR to SDR, LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, project rendering, batch. No API keys, no cloud, no dependencies.",
   "keywords": [

package/scripts/_common/color.py

@@ -74,7 +74,8 @@ def is_rgb(meta: Optional[Dict[str, Any]]) -> bool:
 _EVEN_PAD = "pad=ceil(iw/2)*2:ceil(ih/2)*2:0:0,"
 _MATRIX_FILTER_RE = re.compile(r"^(?:(?:%s)?colorspace=ispace=(?:%s):iprimaries=bt709:itrc=bt709:space=bt709:primaries=bt709:trc=bt709(?:,crop=iw-[01]:ih-[01]:0:0:exact=1)?|(?:format=rgb24,)?%s)$"
                                % (re.escape(_EVEN_PAD), "|".join(NON_BT709_MATRICES), re.escape(rgb_to_bt709_filter())))
-_INPUT_VIDEO_REF = re.compile(r"\[(\d+):v(?::0)?\]")
+# [N:v], [N:v:0] and [N:V:0] (PROBED_VIDEO: the motion picture, not an attached cover)
+_INPUT_VIDEO_REF = re.compile(r"\[(\d+):[vV](?::0)?\]")
 
 
 def bt709_matrix_filter(meta: Optional[Dict[str, Any]]) -> Optional[str]:
@@ -263,7 +264,7 @@ def fold_bt709_matrix(cmd: Sequence[str]) -> List[str]:
 
     - no other filter: unchanged (the -vf is the graph);
     - a -vf: the conversion is prepended to that chain;
-    - a -filter_complex: every `[N:v]` / `[N:v:0]` reference to an input that reads the same file
+    - a -filter_complex: every `[N:v]` / `[N:v:0]` / `[N:V:0]` reference to an input that reads the same file
       as input 0 (the file the encoder line was built for; cut.py's segment join opens it once
       per segment) reads that input through the conversion instead. Other inputs are untouched.
 
@@ -298,7 +299,7 @@ def fold_bt709_matrix(cmd: Sequence[str]) -> List[str]:
         graph = _INPUT_VIDEO_REF.sub(through, str(out[graph_at + 1]))
         if not refs:
             die("internal: a BT.709 matrix conversion was requested for a -filter_complex that never reads "
-                "input 0's video as [0:v]", kind="ffmpeg")
+                "input 0's video as [0:v] or [0:V:0]", kind="ffmpeg")
         # one conversion per input, split when the graph reads that input more than once
         # (speedramp.py trims [0:v] once per segment)
         chains = [f"{ref}{conv}" + (f",split={len(labels)}" if len(labels) > 1 else "") + "".join(labels)

package/scripts/_common/probe.py

@@ -15,6 +15,14 @@ from typing import Any, Dict, List, Optional, Sequence, Tuple
 from _common.emit import die, warn
 from _common.runner import STATE, dry_run_input_pending, require_tool, run, run_analysis, still_input_args
 
+# The streams probe() describes, as stream specifiers: its `video` is the first picture that is not
+# a cover (`V`), its `audio` the first sound stream. Without a -map, FFmpeg picks the largest
+# picture and the sound with the default disposition or the most channels, so on a file with two
+# of either a tool measured one stream and wrote another: loudness measured track 1 and applied the
+# gain to track 0, cut and crop wrote the larger picture they never probed (A110, A118, A128, A258).
+PROBED_VIDEO = "V:0"
+PROBED_AUDIO = "a:0"
+
 
 def fingerprint(path: str) -> Dict[str, Any]:
     """Size plus a sha256 over the first and last 8 MiB: enough to notice a re-export, a re-trim
@@ -50,7 +58,8 @@ def decode_pcm_mono(path: str, sample_rate: int, seconds: Optional[float] = None
     # first_pts=0 pads a sound that starts after the file's start (or after `start`) with silence,
     # so sample i is at start + i / sample_rate on the file's clock: sync.py measured a track that
     # starts 0.3 s late 0.279 s off, and --replace-audio placed it that far late (#409)
-    cmd += ["-vn", "-af", "aresample=async=1:first_pts=0", "-ac", "1", "-ar", str(sample_rate), "-f", "s16le", "-"]
+    # the first audio track, the one probe() describes (default selection takes the most channels)
+    cmd += ["-map", f"0:{PROBED_AUDIO}", "-vn", "-af", "aresample=async=1:first_pts=0", "-ac", "1", "-ar", str(sample_rate), "-f", "s16le", "-"]
     proc = run_analysis(cmd, check=False, text=False)
     if proc.returncode != 0 or not proc.stdout:
         if check:
@@ -99,7 +108,7 @@ def decode_gray_frames(path: str, fps: float, width: int, height: int, *, start:
     cmd += ["-i", path]
     if seconds is not None:
         cmd += ["-t", f"{max(0.0, seconds):.3f}"]
-    cmd += ["-vf", f"fps={fps:g},scale={width}:{height}:flags=area,format=gray",
+    cmd += ["-map", f"0:{PROBED_VIDEO}", "-vf", f"fps={fps:g},scale={width}:{height}:flags=area,format=gray",
             "-f", "rawvideo", "-"]
     proc = run_analysis(cmd, check=False, text=False)
     if proc.returncode != 0 or not proc.stdout:
@@ -422,6 +431,26 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
 _CARRY: Dict[str, Dict[str, Any]] = {}
 
 
+def probed_maps(meta: Optional[Dict[str, Any]], *, video: bool = True, audio: bool = True,
+                audio_stream: int = 0, input_index: int = 0) -> List[str]:
+    """`-map` arguments for the picture and sound probe() describes in `meta` (audio track
+    `audio_stream` where a tool takes --audio-stream). A kind the file does not have is left out,
+    so the same call serves a silent clip and an audio-only file."""
+    out: List[str] = []
+    if video and (meta or {}).get("video"):
+        out += ["-map", f"{input_index}:{PROBED_VIDEO}"]
+    if audio and (meta or {}).get("audio"):
+        out += ["-map", f"{input_index}:a:{audio_stream}"]
+    return out
+
+
+def several_av_streams(meta: Optional[Dict[str, Any]]) -> bool:
+    """True when FFmpeg's default stream selection could pick a picture or a sound other than the
+    one probe() describes: more than one playable video stream or more than one audio stream."""
+    counts = (meta or {}).get("stream_counts") or {}
+    return (counts.get("video") or 0) > 1 or (counts.get("audio") or 0) > 1
+
+
 def carry_inventory(path: str) -> "Optional[Dict[str, Any]]":
     """The carry-over items probe() last read off `path` (see emit()'s source_carry), or None."""
     return _CARRY.get(os.path.realpath(path)) if path else None
@@ -628,10 +657,11 @@ def measured_level_dbfs(path: str, seconds: Optional[float] = 120.0,
                         audio_stream: Optional[int] = None) -> Optional[Dict[str, float]]:
     """Mean and peak level of the first `seconds` of audio (volumedetect), in dBFS; None if unmeasurable.
     Cheap enough to run once as a hint when a threshold-based tool found nothing. seconds=None
-    measures the whole file; audio_stream picks the Nth audio stream (default: ffmpeg's choice)."""
+    measures the whole file; audio_stream picks the Nth audio stream (default: the first, the one
+    probe() describes; FFmpeg's own choice was the track with the most channels)."""
     ffmpeg = require_tool("ffmpeg")
     head = ["-t", f"{seconds:.0f}"] if seconds is not None else []
-    pick = ["-map", f"0:a:{audio_stream}"] if audio_stream is not None else []
+    pick = ["-map", f"0:a:{audio_stream or 0}"]
     proc = run_analysis([ffmpeg, "-hide_banner", "-nostdin", *head, "-i", path, *pick, "-vn",
                          "-af", "volumedetect", "-f", "null", "-"], check=False)
     m_mean = re.search(r"mean_volume:\s*(-?[0-9.]+) dB", proc.stderr)
@@ -751,7 +781,7 @@ def measure_signal_range(path: str, standard: str, window: float = 10.0,
         stats_file = os.path.join(tmp, "stats.txt")
         vf = (f"signalstats=stat=brng,metadata=print:file={escape_filter_path(stats_file)},"
               f"{mask},signalstats,metadata=print:file=-")
-        cmd = [ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-map", "0:v:0", "-an", "-sn", "-dn", "-vf", vf, "-f", "null", "-"]
+        cmd = [ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-map", f"0:{PROBED_VIDEO}", "-an", "-sn", "-dn", "-vf", vf, "-f", "null", "-"]
         proc = run_analysis(cmd, check=False, record=True)
         try:
             with open(stats_file, encoding="utf-8", errors="replace") as f:
@@ -804,7 +834,7 @@ def analyze_levels(path: str, seconds: float = 20.0) -> Dict[str, Any]:
     white below ~235 with low saturation: the image looks grey and flat but is tagged as plain SDR.
     """
     ffmpeg = require_tool("ffmpeg")
-    cmd = [ffmpeg, "-hide_banner", "-nostdin", "-t", f"{seconds:.1f}", "-i", path, "-an",
+    cmd = [ffmpeg, "-hide_banner", "-nostdin", "-t", f"{seconds:.1f}", "-i", path, "-map", f"0:{PROBED_VIDEO}", "-an",
            "-vf", "fps=2,signalstats,metadata=print:file=-", "-f", "null", "-"]
     proc = run_analysis(cmd, check=False)
     vals: Dict[str, List[float]] = {}
@@ -976,7 +1006,7 @@ def detect_silences(path: str, threshold: float, min_silence: float) -> "List[Tu
     if dry_run_input_pending(path):
         return []
     ffmpeg = require_tool("ffmpeg")
-    cmd = [ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-vn", "-af",
+    cmd = [ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-map", f"0:{PROBED_AUDIO}", "-vn", "-af",
            f"silencedetect=noise={threshold}dB:d={min_silence}", "-f", "null", "-"]
     proc = run_analysis(cmd, check=False, record=True)
     if proc.returncode != 0:
@@ -1188,7 +1218,7 @@ def detect_scenes(path: str, threshold: float, min_len: float, duration: float,
     a real cut is a one-frame spike. On real footage this roughly doubles precision at
     equal recall compared with the raw scdet threshold."""
     ffmpeg = require_tool("ffmpeg")
-    proc = run_analysis([ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-an", "-vf",
+    proc = run_analysis([ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-map", f"0:{PROBED_VIDEO}", "-an", "-vf",
                          "scale=320:-2,scdet=threshold=0,metadata=print:file=-", "-f", "null", "-"])
     # No `sc_pass=1` on scdet: on FFmpeg 5.x that option means "pass only the frames whose
     # score exceeds the threshold", so every truly static frame (score exactly 0 -- a title

package/scripts/_common/runner.py

@@ -2045,6 +2045,26 @@ def subtitle_container_holds(codec: str, out_ext: str) -> bool:
     return True
 
 
+def default_selection_maps(meta: Optional[Dict[str, Any]], dst: str) -> List[str]:
+    """The -map arguments for a re-encode that would otherwise rely on ffmpeg's default stream
+    selection: none for a file with one picture and one sound (the default picks those, and a
+    subtitle stream the container can hold, as it always did), and with several, the picture
+    and sound probe() describes plus the first subtitle stream when `dst`'s container can hold it
+    -- what the default would have carried, without its largest-picture / most-channels choice
+    (A258, #484 review)."""
+    from _common.probe import probed_maps, several_av_streams  # probe imports this module
+    if not several_av_streams(meta):
+        return []
+    maps = probed_maps(meta)
+    subs = (meta or {}).get("subtitle_stream_details") or []
+    codec, ext = (subs[0].get("codec") or "") if subs else "", os.path.splitext(dst)[1]
+    if subs and subtitle_container_holds(codec, ext):
+        # with its own -c:s: the default subtitle encoder does not exist for every container
+        # (none for MP4 in FFmpeg 6.1) and is a text encoder that cannot take a bitmap track
+        maps += ["-map", "0:s:0", "-c:s", subtitle_codec_for(codec, ext)]
+    return maps
+
+
 def run_keeping_subtitles(cmd: List[str], output: str, relabel_timecode: bool = False) -> bool:
     """Run an ffmpeg command that already maps its video/audio, trying first to also
     stream-copy any subtitle/data streams the source has (`-map 0:s?`/`0:d?` are no-ops when

package/scripts/audio.py

@@ -157,6 +157,22 @@ def find_silent_tracks(args: argparse.Namespace, problems: List[Dict[str, Any]])
     return silent
 
 
+def main_track_channels(args: argparse.Namespace, meta: Dict[str, Any]) -> int:
+    """Channel count of the track audio.py processes: --replace's first audio track, else the
+    input's --audio-stream track; 0 when it is not known (a dry run's pending input)."""
+    if args.replace:
+        if dry_run_input_pending(args.replace) or not os.path.isfile(args.replace):
+            return 0
+        proc = run([require_tool("ffprobe"), "-v", "error", "-select_streams", "a:0", "-show_entries",
+                    "stream=channels", "-of", "csv=p=0", args.replace], quiet=True, check=False)
+        first = (proc.stdout or "").strip().splitlines()[:1]
+        return int(first[0]) if first and first[0].strip().isdigit() else 0
+    streams = meta.get("audio_streams") or []
+    if 0 <= args.audio_stream < len(streams):
+        return streams[args.audio_stream].get("channels") or 0
+    return (meta.get("audio") or {}).get("channels") or 0
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input")
@@ -279,7 +295,10 @@ def main() -> int:
         die(f"--audio-stream {args.audio_stream}: input has {len(streams)} audio stream(s), 0..{len(streams) - 1}")
     if args.audio_stream and not streams and not STATE.dry_run:
         die("--audio-stream needs an input with audio streams")
-    in_channels = (meta.get("audio") or {}).get("channels") or 0
+    # the channels of the track the graph processes (main_src below): the --audio-stream track,
+    # or --replace's first track. meta["audio"] is the input's first track, so a mono a:0 left a
+    # stereo --audio-stream 1 unfolded by --mono, and a stereo a:0 halved a mono one (A128)
+    in_channels = main_track_channels(args, meta)
     if args.stereo_widen is not None:
         if args.mono:
             die("--stereo-widen and --mono contradict each other: there is no stereo image in a 1-channel output")
@@ -324,7 +343,8 @@ def main() -> int:
     if args.limit:
         fx.append(dynamics_filter("alimiter", args))
     if args.mono:
-        in_ch = (meta.get("audio") or {}).get("channels") or 2
+        # after --downmix the track is the stereo fold-down, whatever the source had
+        in_ch = 2 if args.downmix else (in_channels or 2)
         if in_ch == 2:
             fx.append("pan=mono|c0=0.5*c0+0.5*c1")
         elif in_ch > 2:

package/scripts/check.py

@@ -47,6 +47,7 @@ from _platforms import PLATFORMS, PLATFORM_CHOICES, TP_TOLERANCE_DB, spec_of, re
 from _common.probe import (CHANGE_FLOOR, CHANGE_GRID, change_mask_tiles, change_tiles, LEGAL_RANGE_CHOICES, measure_signal_range, COMPARE_SSIM_WARN, CONTENT_FLAT_STD, SILENT_PEAK_DBFS, compare_pictures, detect_content,
                            detect_flashes, first_frame_stats, presentation_times, measured_level_dbfs)
 from _common.emit import file_identity
+from _common.probe import PROBED_AUDIO
 from _common import STATE, add_common, apply_common, die, emit, info, probe, require_tool, run, run_analysis, dry_run_input_pending
 
 # The one delivery table (scripts/_platforms.py): check.py's rows, export.py's presets and the
@@ -61,7 +62,10 @@ def measure_loudness(path: str) -> Dict[str, float]:
     if dry_run_input_pending(path):
         return {}
     ffmpeg = require_tool("ffmpeg")
-    proc = run_analysis([ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-vn", "-af", "loudnorm=I=-14:TP=-1:LRA=11:print_format=json", "-f", "null", "-"], check=False, record=True)
+    # the first audio track, the one the audio row's probe facts describe (and the one export and
+    # loudness write): default selection measured the track with the most channels
+    proc = run_analysis([ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-map", f"0:{PROBED_AUDIO}", "-vn",
+                         "-af", "loudnorm=I=-14:TP=-1:LRA=11:print_format=json", "-f", "null", "-"], check=False, record=True)
     m = re.search(r"\{[^{}]*\"input_i\"[^{}]*\}", proc.stderr, re.S)
     if not m:
         return {}

package/scripts/crop.py

@@ -23,6 +23,7 @@ import sys
 
 from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run, video_args, X264_PRESETS, fmt_secs
 from _common.probe import display_size, square_pixels, square_pixels_note
+from _common.runner import default_selection_maps
 from _common.emit import note
 
 
@@ -65,7 +66,8 @@ def main() -> int:
     if square_pixels(meta["video"]):
         vf.insert(0, square_pixels(meta["video"]))
         note(square_pixels_note(meta["video"]))
-    cmd = ffmpeg_base() + ["-i", args.input, "-vf", ",".join(vf)]
+    # the picture the rectangle was checked against, not the largest one default selection takes
+    cmd = ffmpeg_base() + ["-i", args.input] + default_selection_maps(meta, output) + ["-vf", ",".join(vf)]
     cmd += video_args(meta, args.crf, args.preset)
     cmd += cfr_args(meta, args.fps)
     if has_audio:

package/scripts/cropdetect.py

@@ -35,7 +35,7 @@ from typing import Dict, List, Optional, Tuple
 
 from _common import add_common, apply_common, die, emit, info, print_json, probe, require_tool, run_analysis, decode_gray_frames, frame_flow
 from _common.emit import note, warn
-from _common.probe import display_size, square_pixels, square_pixels_note
+from _common.probe import PROBED_VIDEO, display_size, square_pixels, square_pixels_note
 
 MOTION_CENTRE_FPS = 2.0
 MOTION_CENTRE_W, MOTION_CENTRE_H = 64, 36
@@ -57,7 +57,7 @@ def detect(path: str, seconds: float, samples: int, limit: float, round_to: int,
         start = 0.0 if duration <= 0 else (duration - per_window) * i / max(1, samples - 1) if samples > 1 else 0.0
         start = max(0.0, start)
         cmd = [ffmpeg, "-hide_banner", "-nostdin", "-ss", f"{start:.3f}", "-i", path, "-t", f"{per_window:.3f}",
-               "-vf", (square + "," if square else "") + f"cropdetect=limit={limit:g}:round={round_to}:reset=1", "-f", "null", "-"]
+               "-map", f"0:{PROBED_VIDEO}", "-vf", (square + "," if square else "") + f"cropdetect=limit={limit:g}:round={round_to}:reset=1", "-f", "null", "-"]
         proc = run_analysis(cmd, check=False)
         if proc.returncode != 0:
             # One window ffmpeg cannot decode (a damaged stretch) is skipped; the other windows

package/scripts/cut.py

@@ -61,7 +61,8 @@ from typing import List, Tuple
 from _common.runner import JsonTooDeep, fail_if_classified, read_json
 from _common import (beat_grid, snap_points, decode_pcm_mono, rms_envelope, BEAT_MIN_CONFIDENCE)
 from _common import require_tool
-from _common.probe import TS_EXTS, signatures_match, stream_signature
+from _common.probe import PROBED_AUDIO, PROBED_VIDEO, TS_EXTS, probed_maps, several_av_streams, signatures_match, stream_signature
+from _common.runner import subtitle_codec_for, subtitle_container_holds
 from _common.decision import SEEK_MARGIN, delivered_rate, frame_rate, grid_at_or_after, stream_starts
 from _common.timeline import output_timecode_args
 from _common import warn, record_fallback, refuse_existing_outputs, sibling_temp, source_codec_video_args, STATE, add_common, apply_common, audio_codec_for, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, is_audio_output, time_arg, probe, run, X264_PRESETS, keyframes_near, MissingFpsError, concat_list_line, place_output, refuse_output_is_input, fmt_secs, measure_frame_timing, dry_run_input_pending
@@ -147,6 +148,29 @@ def copy_args(meta: dict, dst: str) -> List[str]:
     return args
 
 
+def stream_maps(meta: dict, dst: str, copy: bool) -> List[str]:
+    """The -map arguments of a cut: the picture and the sound probe() describes, which every
+    measurement here (keyframes, start skew, timecode, length) is taken from. ffmpeg's default
+    selection wrote the largest picture and the track with the default disposition or the most
+    channels instead (A258). A stream copy of a file with one picture and one sound keeps the
+    default selection, command for command (it also carries a subtitle stream into a container
+    whose muxer names a subtitle codec, such as Matroska). With several, the first subtitle stream
+    is mapped when the container holds it as it is, and is otherwise left out and reported
+    (DROPPED_STREAMS)."""
+    audio_only = is_audio_output(dst) or not meta.get("video")
+    if copy and not several_av_streams(meta):
+        return []
+    maps = probed_maps(meta, video=not audio_only)
+    subs = meta.get("subtitle_stream_details") or []
+    if copy and not audio_only and subs:
+        codec, ext = subs[0].get("codec") or "", os.path.splitext(dst)[1].lstrip(".").lower()
+        if subtitle_container_holds(codec, ext) and subtitle_codec_for(codec, ext) == "copy":
+            maps += ["-map", "0:s:0"]
+        else:
+            DROPPED_STREAMS.append(dst)
+    return maps
+
+
 LOSSLESS_AUDIO = {"pcm_s16le", "pcm_s24le", "pcm_s32le", "pcm_f32le", "flac"}
 
 
@@ -870,7 +894,7 @@ def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: i
             # -ss before -i seeks, then decoding discards samples up to the exact start
             # (accurate_seek); atrim bounds the decoded stream to the requested length at sample
             # resolution.
-            cmd = ffmpeg_base() + ["-ss", f"{start:.6f}", "-i", src, "-t", f"{dur:.6f}"]
+            cmd = ffmpeg_base() + ["-ss", f"{start:.6f}", "-i", src, "-t", f"{dur:.6f}"] + stream_maps(meta, dst, copy=False)
             cmd += ["-af", f"atrim=end={dur:.6f},asetpts=PTS-STARTPTS"]
         else:
             # Seek SEEK_MARGIN early, then drop the margin on the output side, which decodes and
@@ -879,6 +903,7 @@ def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: i
             # `start` and lose the frames before it (-ss 9.9 on a B-frame HEVC file began at 10.0).
             m = min(SEEK_MARGIN, start)
             cmd = ffmpeg_base() + ["-ss", f"{start - m:.6f}", "-i", src, "-ss", f"{m:.6f}", "-t", f"{dur:.6f}"]
+            cmd += stream_maps(meta, dst, copy=False)
         # ffmpeg's default stream selection also picks one subtitle stream; a re-encode cannot
         # trim it (the cues kept their timestamps and the container grew to 2 s for a 1 s cut,
         # sweep F2), so the re-encode carries video/audio only and the result says so
@@ -901,7 +926,8 @@ def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: i
     elif audio_only:
         # output-side seek: an input seek on a video file lands on the previous video keyframe and on
         # FLAC/MP3 on a coarse index; reading from the start and dropping packets is exact to the packet
-        cmd = ffmpeg_base() + ["-i", src, "-ss", f"{start:.6f}", "-t", f"{dur:.6f}"] + copy_args(meta, dst) + ["-avoid_negative_ts", "make_zero", dst]
+        cmd = (ffmpeg_base() + ["-i", src, "-ss", f"{start:.6f}", "-t", f"{dur:.6f}"] + stream_maps(meta, dst, copy=True)
+               + copy_args(meta, dst) + ["-avoid_negative_ts", "make_zero", dst])
     else:
         # With --edit-list a single MP4/MOV output keeps the edit list the plain copy writes: the
         # keyframe's pre-roll is stored but hidden, so the picture and the sound start at `start`.
@@ -913,7 +939,8 @@ def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: i
         # Other concat parts (Matroska, MPEG-TS) keep make_zero.
         edit_list = (edit_list_ok or copy_t is not None) and os.path.splitext(dst)[1].lower() in EDIT_LIST_EXTS
         cmd = (ffmpeg_base() + ["-ss", f"{start:.6f}", "-i", src, "-t", f"{dur if copy_t is None else copy_t:.6f}"]
-               + copy_args(meta, dst) + ([] if edit_list else ["-avoid_negative_ts", "make_zero"]) + [dst])
+               + stream_maps(meta, dst, copy=True) + copy_args(meta, dst)
+               + ([] if edit_list else ["-avoid_negative_ts", "make_zero"]) + [dst])
     if not audio_only and (meta.get("timecode") or {}).get("value"):
         cmd[-1:-1] = output_timecode_args(meta, first_frame_from(src, meta, start, reencode, edit_list and copy_t is None),
                                           delivered_rate(meta) if reencode else None)
@@ -1098,7 +1125,7 @@ def _join_chunk(src: str, segments: List[Tuple[float, float]], dst: str, meta: d
             # concat filter starts the next segment after the longer stream, so a short picture
             # would leave a hole in the video there
             pad = f"tpad=stop_mode=clone:stop_duration={e - vend + 1.0:.6f}," if first + i in hold else ""
-            graph.append(f"[{i}:v:0]{pad}trim=start={a - half:.6f}:end={b - half:.6f},setpts=PTS-{a:.6f}/TB[v{i}]")
+            graph.append(f"[{i}:{PROBED_VIDEO}]{pad}trim=start={a - half:.6f}:end={b - half:.6f},setpts=PTS-{a:.6f}/TB[v{i}]")
             pads += f"[v{i}]"
         if has_a:
             # fade only the sides that meet another segment: the file's own start and end stay as cut
@@ -1109,7 +1136,7 @@ def _join_chunk(src: str, segments: List[Tuple[float, float]], dst: str, meta: d
                 fades += f",afade=t=in:st=0:d={fade:.6f}"
             if fade > 0 and n < (len(segments) if total is None else total) - 1:
                 fades += f",afade=t=out:st={b - a - fade:.6f}:d={fade:.6f}"
-            graph.append(f"[{i}:a:0]atrim=start={a:.6f}:end={b:.6f},asetpts=PTS-{a:.6f}/TB,"
+            graph.append(f"[{i}:{PROBED_AUDIO}]atrim=start={a:.6f}:end={b:.6f},asetpts=PTS-{a:.6f}/TB,"
                          f"aresample=async=1:first_pts=0{fades}[a{i}]")
             pads += f"[a{i}]"
     outs = ("[v]" if has_v else "") + ("[a]" if has_a else "")

package/scripts/export.py

@@ -50,7 +50,7 @@ from _common.runner import child_exit_code, fail_if_classified, kept_clause, mar
 from _common import STATE, run_analysis, add_common, apply_common, bt709_label_filter, bt709_matrix_args, bt709_tag_args, child_args, emit, cfr_args, default_output, die, encoder_args, ffmpeg_base, info, probe, require_tool, run, run_tool, validate_color, pad_filters, add_pad_fill_args, fmt_secs
 from _common.decision import hw_preset_video, restate_last_swap
 from _common.emit import note, record_fallback, record_skip, warn
-from _common.probe import square_pixels, square_pixels_note
+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 check import SPECS as PLATFORMS, measure_loudness
@@ -204,8 +204,8 @@ def _key_fill(args, p: Dict, meta: Dict, output: str, cmd: List[str], vf: List[s
     key_chain = ",".join(vf + ["alphaextract", "format=yuv422p10le"])
     tc = ((meta.get("timecode") or {}).get("value"))
     tc_args = ["-timecode", tc] if tc else []
-    cmd = cmd + ["-filter_complex", f"[0:v:0]split[f][k];[f]{fill_chain}[fill];[k]{key_chain}[key]"]
-    cmd += ["-map", "[fill]"] + (["-map", "0:a:0"] if has_audio else []) + p["video"] + tc_args + cfr_args(meta)
+    cmd = cmd + ["-filter_complex", f"[0:{PROBED_VIDEO}]split[f][k];[f]{fill_chain}[fill];[k]{key_chain}[key]"]
+    cmd += ["-map", "[fill]"] + probed_maps(meta, video=False, audio=has_audio) + p["video"] + tc_args + cfr_args(meta)
     # the fill is always written to a hidden sibling and moved into place only after the encode
     # succeeds: run() stages and cleans up only ffmpeg's last output (the key), so a failed encode
     # left a partial new fill (the retry was refused as output_exists) or truncated an existing one
@@ -410,7 +410,9 @@ def media_damage(path: str) -> Dict[str, int]:
     PTS) and every other error line, counted. What --repair is measured by, before and after."""
     # repeat+: every occurrence on its own line, not "Last message repeated N times", which hid
     # N timestamp warnings and was itself counted as a decode error
-    proc = run_analysis([require_tool("ffmpeg"), "-hide_banner", "-nostdin", "-v", "repeat+warning", "-i", path, "-f", "null", "-"],
+    # the streams a copy export writes (probed_maps), not the ones default selection would decode
+    proc = run_analysis([require_tool("ffmpeg"), "-hide_banner", "-nostdin", "-v", "repeat+warning", "-i", path,
+                         "-map", f"0:{PROBED_VIDEO}?", "-map", f"0:{PROBED_AUDIO}?", "-f", "null", "-"],
                         check=False, record=True)
     lines = [ln for ln in (proc.stderr or "").splitlines() if ln.strip()]
     # "Packet corrupt (stream = 0, dts = ...)" names a dts but is damage, not a timestamp problem
@@ -585,16 +587,19 @@ def main() -> int:
     # Subtitle and data streams (a soft-subtitle track muxed upstream, a camera's timecode) are
     # kept where the container can hold them: ffmpeg's default stream selection takes one video
     # and one audio stream only, and through 2.22.1 every preset dropped the rest without a word.
-    # Mapping them means mapping the picture and the sound too, the same streams probe() describes.
+    # The picture and the sound are mapped on every export, the same streams probe() describes:
+    # until A118 they were mapped only beside a subtitle or data stream, and without one ffmpeg's
+    # default selection took the larger picture and the track with the default disposition or the
+    # most channels, so which audio track an export kept depended on whether it had subtitles.
     subs = meta.get("subtitle_stream_details") or []
     data = _data_streams(args.input) if meta.get("data_streams") else []
     sub_codecs = [_subtitle_codec(s.get("codec") or "", out_ext) for s in subs]
-    if args.preset != "gif" and not p.get("keyfill") and (subs or data):
-        cmd += ["-map", "0:V:0"] + (["-map", "0:a:0"] if has_audio else [])
+    if args.preset != "gif" and not p.get("keyfill"):
+        cmd += probed_maps(meta, audio=has_audio)
 
     if args.preset == "gif":
         chain = ",".join(([gif_label] if gif_label else []) + ["fps=12"] + vf)
-        fc = f"[0:v]{chain},split[a][b];[a]palettegen=stats_mode=diff[p];[b][p]paletteuse=dither=bayer:bayer_scale=5:diff_mode=rectangle"
+        fc = f"[0:{PROBED_VIDEO}]{chain},split[a][b];[a]palettegen=stats_mode=diff[p];[b][p]paletteuse=dither=bayer:bayer_scale=5:diff_mode=rectangle"
         cmd += ["-filter_complex", fc, "-loop", "0", output]
         run(cmd)
         info(f"wrote {output}")

package/scripts/look.py

@@ -24,7 +24,7 @@ from _common import drawtext_fontfile  # noqa: E402
 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 display_size, square_pixels, square_pixels_note  # noqa: E402
+from _common.probe import PROBED_VIDEO, display_size, square_pixels, square_pixels_note  # 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
@@ -337,7 +337,7 @@ def main() -> int:
                 conv = "," + conv if conv else ""
                 return (f"scale={half}:{box_h}:force_original_aspect_ratio=decrease{conv}{pre},"
                         f"pad={half}:{box_h}:(ow-iw)/2:(oh-ih)/2:color=0x202020,setsar=1{stamp}")
-            fc = (f"[0:v]{lab}{sq}{fit(tm)}[a];[1:v]{lab2}{csq}{fit(tm2)}[b];"
+            fc = (f"[0:{PROBED_VIDEO}]{lab}{sq}{fit(tm)}[a];[1:{PROBED_VIDEO}]{lab2}{csq}{fit(tm2)}[b];"
                   f"[a][b]hstack=inputs=2[out]")
             cmd = ffmpeg_base() + ["-ss", f"{sec:.3f}", *still_input_args(args.input), "-i", args.input, "-ss", f"{sec:.3f}", *still_input_args(args.compare), "-i", args.compare,
                                    "-filter_complex", fc, "-map", "[out]", "-frames:v", "1", "-update", "1", out]
@@ -354,7 +354,7 @@ def main() -> int:
                 # several frames, or -o given as a stem/prefix without an image extension
                 out = os.path.join(outdir, f"{args.output and Path(args.output).stem or stem}_{sec:.3f}s.png")
             stamp = "" if args.no_timecode else f",drawtext=text='{escape_drawtext(fmt_hms(sec))}':{font_prefix}{FONT}"
-            cmd = ffmpeg_base() + ["-ss", f"{sec:.3f}", *still_input_args(args.input), "-i", args.input, "-vf", f"{lab}{sq}scale={args.width}:-2{tc.replace(',' + timecode_filter(font_prefix), '')}{stamp}", "-frames:v", "1", "-update", "1", out]
+            cmd = ffmpeg_base() + ["-ss", f"{sec:.3f}", *still_input_args(args.input), "-i", args.input, "-map", f"0:{PROBED_VIDEO}", "-vf", f"{lab}{sq}scale={args.width}:-2{tc.replace(',' + timecode_filter(font_prefix), '')}{stamp}", "-frames:v", "1", "-update", "1", out]
             run(cmd)
             outputs.append(out)
     else:
@@ -384,7 +384,7 @@ def main() -> int:
         tc_sheet = tc
         vf = (f"select='isnan(prev_selected_t)+gte(t-prev_selected_t\\,{step * 0.98:.6f})',{lab}{sq}scale={tile_w}:-2{tc_sheet},"
               f"tile={cols}x{rows}:padding=2:margin=2:color=0x202020")
-        cmd = ffmpeg_base() + ["-copyts", "-start_at_zero", "-ss", f"{seek:.6f}", *still_input_args(args.input), "-i", args.input, "-vf", vf, "-frames:v", "1", "-update", "1", out]
+        cmd = ffmpeg_base() + ["-copyts", "-start_at_zero", "-ss", f"{seek:.6f}", *still_input_args(args.input), "-i", args.input, "-map", f"0:{PROBED_VIDEO}", "-vf", vf, "-frames:v", "1", "-update", "1", out]
         run(cmd)
         outputs.append(out)
         info(f"contact sheet: {n} frames every {step:.2f}s")

package/scripts/loudness.py

@@ -23,6 +23,7 @@ from _platforms import TP_TOLERANCE_DB
 
 AUDIO_LENGTH_TOLERANCE = 0.03  # seconds: one AAC frame at 48 kHz is 0.021 s
 LUFS_TOLERANCE = 1.0  # LU: a normalised file within this of the requested -I is on target
+from _common.probe import PROBED_AUDIO, probed_maps
 from _common import STATE, add_common, apply_common, emit, AUDIO_CODECS, audio_codec_for, default_output, die, ffmpeg_base, info, probe, require_tool, run, run_analysis, run_keeping_subtitles, dry_run_input_pending
 
 
@@ -65,7 +66,11 @@ def measure(path: str, I: float, tp: float, lra: float) -> dict:
     if dry_run_input_pending(path):
         return {"input_i": "-20.0", "input_tp": "-3.0", "input_lra": "8.0", "input_thresh": "-30.0", "target_offset": "0.0", "silent": False, "placeholder": True}
     ffmpeg = require_tool("ffmpeg")
-    cmd = [ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-vn", "-af", f"loudnorm=I={I}:TP={tp}:LRA={lra}:print_format=json", "-f", "null", "-"]
+    # the first audio track, the one pass 2 normalises and probe() describes: without a -map,
+    # FFmpeg measured the track with the default disposition or the most channels, and the gain
+    # for that track was applied to a:0 (A110)
+    cmd = [ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-map", f"0:{PROBED_AUDIO}", "-vn",
+           "-af", f"loudnorm=I={I}:TP={tp}:LRA={lra}:print_format=json", "-f", "null", "-"]
     # Pass 1 is a measurement: it runs under --dry-run too, so the planned pass-2 command and
     # the reported input_i are real (before 1.4.6 a dry run returned a made-up -20 LUFS).
     proc = run_analysis(cmd, check=False, record=True)
@@ -112,9 +117,9 @@ def _normalize(args, meta: dict, stats: dict, lufs: float, tp_max: float, output
             af += f",atrim=duration={float(in_audio):.6f}"
         cmd = ffmpeg_base() + ["-i", args.input, "-af", af, "-ar", str(sr)]
         if ext in AUDIO_CODECS or not meta.get("video"):
-            cmd += ["-vn"] + audio_codec_for(output, bitrate)
+            cmd += ["-map", f"0:{PROBED_AUDIO}", "-vn"] + audio_codec_for(output, bitrate)
         else:
-            cmd += ["-map", "0:v:0", "-map", "0:a:0", "-c:v", "copy", "-c:a", "aac", "-b:a", bitrate]
+            cmd += probed_maps(meta) + ["-c:v", "copy", "-c:a", "aac", "-b:a", bitrate]
             if ext in (".mp4", ".mov", ".m4v"):
                 cmd += ["-movflags", "+faststart"]
             dropped_streams = run_keeping_subtitles(cmd, output)

package/scripts/scenes.py

@@ -30,7 +30,7 @@ from _common import drawtext_fontfile  # noqa: E402
 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  # noqa: E402
-from _common.probe import square_pixels  # noqa: E402
+from _common.probe import PROBED_VIDEO, square_pixels  # noqa: E402
 from _common import dry_run_input_pending  # noqa: E402
 
 SHOT_FPS = 4.0          # frames/second sampled for --shots' flow estimate
@@ -348,7 +348,7 @@ def main() -> int:
         vf = (f"select='{expr}'," + (lab + "," if lab else "") + (square + "," if square else "")
               + f"scale={tile_w}:-2{stamp},"
               f"tile={cols}x{rows}:padding=2:margin=2:color=0x202020")
-        run(ffmpeg_base() + ["-i", args.input, "-an", "-vf", vf, "-frames:v", "1", "-fps_mode", "vfr", "-update", "1", args.sheet])
+        run(ffmpeg_base() + ["-i", args.input, "-map", f"0:{PROBED_VIDEO}", "-an", "-vf", vf, "-frames:v", "1", "-fps_mode", "vfr", "-update", "1", args.sheet])
         info(f"wrote {args.sheet}")
         result["sheet"] = args.sheet
 

package/scripts/silence.py

@@ -34,6 +34,7 @@ from _common import guard_sidecar, refuse_existing_outputs, refuse_output_is_inp
 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
 
 
 
@@ -305,7 +306,8 @@ def cut_levels(path: str, tm: Dict[str, Any], duration: float,
     out = []
     with tempfile.TemporaryDirectory(prefix="silence-levels-") as tmp:
         raw = os.path.join(tmp, "pcm.s16le")
-        proc = run_analysis([require_tool("ffmpeg"), "-hide_banner", "-loglevel", "error", "-nostdin", "-i", path, "-vn",
+        proc = run_analysis([require_tool("ffmpeg"), "-hide_banner", "-loglevel", "error", "-nostdin", "-i", path,
+                             "-map", f"0:{PROBED_AUDIO}", "-vn",
                              "-ac", str(channels), "-ar", str(CUT_LEVEL_RATE), "-f", "s16le", "-y", raw],
                             check=False, text=False)
         if proc.returncode != 0 or not os.path.isfile(raw) or not os.path.getsize(raw):

package/scripts/stabilize.py

@@ -27,6 +27,8 @@ import sys
 import tempfile
 from pathlib import Path
 
+from _common.probe import PROBED_VIDEO
+from _common.runner import default_selection_maps
 from _common import STATE, add_common, apply_common, aac_args, cfr_args, default_output, die, emit, escape_filter_path, ffmpeg_base, info, probe, require_tool, run, video_args, X264_PRESETS, run_analysis, dry_run_input_pending, fmt_secs, record_fallback, EVEN_SCALE
 
 
@@ -79,8 +81,9 @@ def main() -> int:
             # A frame number, not a boolean: frame 1 is the standard reference for "lock to
             # this fixed frame" (mirrors vidstabtransform's own tripod=1 below).
             detect_vf += ":tripod=1"
+        # both passes read the picture probe() describes (its size chose the even scale above)
         detect_cmd = [ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin", "-y", "-i", args.input,
-                      "-vf", detect_vf, "-f", "null", "-"]
+                      "-map", f"0:{PROBED_VIDEO}", "-vf", detect_vf, "-f", "null", "-"]
         # Pass 1 is a measurement into a temp file (the transforms), so it runs under --dry-run
         # as well; only pass 2, the write, is skipped there.
         if not dry_run_input_pending(args.input):
@@ -94,7 +97,7 @@ def main() -> int:
             # Equivalent to relative=0:smoothing=0 -- overrides --smoothing, since averaging a
             # camera path makes no sense once every frame is locked to one fixed reference.
             transform_vf += ":tripod=1"
-        cmd = ffmpeg_base() + ["-i", args.input, "-vf", transform_vf]
+        cmd = ffmpeg_base() + ["-i", args.input] + default_selection_maps(meta, output) + ["-vf", transform_vf]
         cmd += video_args(meta, args.crf, args.preset)
         cmd += cfr_args(meta)
         if has_audio:

package/scripts/sync.py

@@ -37,6 +37,7 @@ from _common import video_args, add_common, apply_common, emit, aac_args, audio_
 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
 
 SR = 8000  # decode sample rate
 
@@ -392,14 +393,15 @@ def main() -> int:
             # Even a keyframe on the trim point moved the picture by its B-frame delay (+69 ms).
             # The re-encode below starts on the frame itself; a sound-only file is still copied.
             if head_trim > 0 and not drift_af and not has_video:
-                cmd = ffmpeg_base() + ["-ss", f"{head_trim:.4f}", "-i", args.second, "-c", "copy"]
+                # the second file's first audio track: the one decode_pcm_mono() measured
+                cmd = ffmpeg_base() + ["-ss", f"{head_trim:.4f}", "-i", args.second] + default_selection_maps(second_meta, output) + ["-c", "copy"]
                 if os.path.splitext(output)[1].lower() in (".mp4", ".mov", ".m4v"):
                     cmd += ["-movflags", "+faststart"]
                 cmd += ["-avoid_negative_ts", "make_zero", output]
                 proc = run(cmd, check=False)
                 fail_if_classified(proc)
                 if proc.returncode != 0:
-                    cmd = ffmpeg_base() + ["-ss", f"{head_trim:.4f}", "-i", args.second] + (video_args(probe(args.reference) if args.replace_audio else probe(args.second), args.crf) if has_video else []) + audio_codec_for(output) + [output]
+                    cmd = ffmpeg_base() + ["-ss", f"{head_trim:.4f}", "-i", args.second] + default_selection_maps(second_meta, output) + (video_args(probe(args.reference) if args.replace_audio else probe(args.second), args.crf) if has_video else []) + audio_codec_for(output) + [output]
                     run(cmd)
             else:
                 # Seek SEEK_MARGIN early and drop the margin on the output side, as cut.py's
@@ -415,7 +417,9 @@ def main() -> int:
                     cmd += ["-ss", f"{head_trim - m:.6f}"]
                     if m > 0:
                         out_seek = ["-ss", f"{m / (drift_ratio if drift_af else 1.0):.6f}"]
-                cmd += ["-i", args.second] + out_seek
+                # -map after the output-side -ss: both are output options, so the order is the
+                # same command, and the seek stays next to the -i it drops the margin from
+                cmd += ["-i", args.second] + out_seek + default_selection_maps(second_meta, output)
                 af_parts = on_clock + drift_af
                 if delay_ms > 0:
                     af_parts.append(f"adelay={delay_ms}:all=1")