ffmpeg-skill 3.1.5 → 3.1.7

package/scripts/_contract.py

@@ -276,7 +276,7 @@ REENCODE_META: Dict[str, Dict[str, str]] = {
     "speedramp": dict(video="always", audio="always", note="setpts/atempo per segment always forces a re-encode of both streams"),
     "broll":    dict(video="always", audio="conditional", note="the overlay graph always re-encodes the video stream; A's audio is stream-copied under --audio a and re-encoded to AAC under --audio b/mix"),
     "metadata": dict(video="never", audio="never", note="-c copy on every stream; only the container's chapters and tags change -- --auto-chapters decodes to measure, but still writes with -c copy"),
-    "loop":     dict(video="always", audio="conditional", note="-stream_loop always re-encodes both streams; the audio codec is always AAC when present. --boomerang re-encodes the video through reverse/loop filters and drops the audio"),
+    "loop":     dict(video="always", audio="conditional", note="the repeats (the concat demuxer, the file listed once per repeat) always re-encode both streams; the audio codec is always AAC when present. --boomerang re-encodes the video through reverse/loop filters and drops the audio"),
     "insert":    dict(video="always", audio="never", note="always encodes a fresh silent clip from the still image; there is no audio stream to touch"),
     "background": dict(video="always", audio="never", note="always encodes a fresh generated clip; there is no input to copy from"),
     "reverse":   dict(video="always", audio="conditional", note="video always re-encodes (reverse buffers and re-emits every frame); audio re-encodes to AAC when present and not dropped by --no-audio"),
@@ -440,6 +440,9 @@ ERROR_REASONS = {
     "encoder_missing": "--codec av1/prores: the build's encoder list was read and has no encoder for the codec (kind missing_tool; details: {codec, encoders}); or ffmpeg itself reported \"Unknown encoder\" for the encoder the command named (kind ffmpeg; details: {name}; the hint points at doctor)",
     "asr_engine_missing": "kind missing_tool: --transcribe (caption.py, silence.py --filler) found no local speech-to-text engine; the message lists the install lines; details: {}",
     "encoder_list_unreadable": "--codec av1/prores: the build's encoder list could not be read, so whether it has the encoder is unknown (kind ffmpeg); details: {codec, encoders, error}",
+    "no_speech": "kind input: --transcribe (caption.py, silence.py --filler) ran a local speech engine that heard no speech in the input; details: {engine}; also top-level reason and engine",
+    "engine_failed": "kind input: --transcribe: an installed speech engine ran and failed (a named --engine, or every engine --engine auto found); details: {engine, detail | engines: [{engine, reason, detail}]}; also top-level reason, engine and detail/engines",
+    "english_only": "kind input: --transcribe under --engine auto found only Parakeet engines, which it runs for English speech only, and the language is not English; details: {engine, engines}; also top-level reason, engine and engines",
 }
 
 # The codes of the collector's records (docs/design-decisions.md, "Nothing happens silently"):
@@ -454,7 +457,7 @@ DIAGNOSTIC_CODES = {
     "audit_log_unwritable": ("warnings", "an audit record could not be appended; never fails the run; {path, event, error}"),
     "plan_unbound_inputs": ("warnings", "render.py PLAN: inputs that did not exist when the plan was made, so were not checked; {paths}"),
     # the runner
-    "odd_dimensions_scaled_even": ("fallbacks", "an encode that failed on odd dimensions was run again scaled to even ones (the frame loses a row or column); {output, scale}"),
+    "odd_dimensions_scaled_even": ("fallbacks", "an encode that failed on odd dimensions was run again scaled to even ones, or a graph the retry cannot reach (broll.py's filter_complex) was scaled to even ones up front (the frame loses a row or column); {output, scale}"),
     "measurement_input_pending": ("skipped", "--dry-run: a measurement skipped because its input is an earlier stage's output that does not exist yet; {path}"),
     "non_av_streams_dropped": ("fallbacks", "the subtitle/data streams could not be copied, so the encode ran again without them (dropped_non_av_streams: true); {output, returncode, error: the first attempt's last stderr lines}; export.py adds dropped: the stream types this retry leaves out (data alone first, then subtitle too)"),
     "ffmpeg_list_unreadable": ("warnings", "`ffmpeg -encoders` / `-bsfs` could not be read; what needs the list says so instead of 'the build lacks it'; {list, tool, error}"),
@@ -547,13 +550,23 @@ FONT_USED_SCHEMA = {
 }
 
 
+# the tools whose --json carries `dropped_non_av_streams` (a test reads the sources)
+NON_AV_STREAM_TOOLS = frozenset({"audio", "broll", "color", "cut", "deinterlace", "denoise", "export", "fit", "freeze",
+                                 "graphics", "join", "loudness", "overlay", "pad", "proxy", "redact", "speedramp",
+                                 "sphere", "straighten"})
+
+
 def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str, Any]:
     """What the tool prints on stdout with --json (keys observed in the implementation). `hw`: the
     tool takes --hw, so its `notes` can also carry a VideoToolbox encode's quality line."""
     if name == "probe":
         return {"type": "object", "description": "one probe document, or an array of them for several inputs",
                 "properties": {"file": {"type": "string"}, "format": {"type": "string"}, "duration": {"type": "number"}, "size_bytes": {"type": "integer"},
-                               "video": {"type": ["object", "null"]}, "audio": {"type": ["object", "null"]}}, "additionalProperties": True}
+                               "video": {"type": ["object", "null"]}, "audio": {"type": ["object", "null"]},
+                               "timecode": {"type": "object", "description": "3.0.0: the source's start timecode {value, drop_frame, source}: the first HH:MM:SS[:;.]FF timecode tag from the video stream, then a tmcd data stream, then the container; all three null when none carries one"},
+                               "chapters": {"type": "array", "description": "the container's chapter markers [{index, start, end, title}]"},
+                               "subtitle_stream_details": {"type": "array", "description": "every subtitle stream in file order [{index (the n of -map 0:s:n), codec, language, title}]"}},
+                "additionalProperties": True}
     base = {"status": {"enum": ["completed"]}, "output": {"type": ["string", "null"], "description": "path written, or null"},
             "dry_run": {"type": "boolean"}, "commands": {"type": "array", "items": {"type": "string"}, "description": "every ffmpeg command line planned or run"},
             "probe": {"type": "object", "description": "probe of the output when a file was written"},
@@ -594,6 +607,13 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
                  "speech": {"type": "array", "description": "--speech (1.18): [{time, speech_music_ratio}]"}}
     elif name == "silence":
         extra = {"silences": {"type": "array"}, "keep": {"type": "array"}, "input_duration": {"type": "number"}, "kept_duration": {"type": "number"}, "removed_seconds": {"type": "number"},
+                 "removed_seconds_total": {"type": "number", "description": "--filler: seconds removed in all, silence plus filler words (removed_seconds stays the silence alone)"},
+                 "cut_points": {"type": ["array", "null"], "description": "2.22: per cut {source_time, output_time, edge (out|in), rms_dbfs (the loudest channel 50 ms either side on the source; null for digital silence), filler (true on a removed filler word's edge)}; null when the source could not be decoded for it (cut_levels_unmeasured warning)"},
+                 "cut_warnings": {"type": ["array", "null"], "description": "the cut_points (not filler cuts) within 10 dB of --threshold: where to listen (a cut_near_sound warning); verified is unchanged"},
+                 "timemap": {"type": "string", "description": "--timemap FILE: the source-to-output time map written (JSON or CSV)"},
+                 "silence_kinds": {"type": "array", "description": "2.20: per detected silence, digital (at or below -90 dBFS) or below_threshold"},
+                 "silence_breakdown": {"type": "object", "description": "2.20: {digital, below_threshold}: the count and seconds of each, with the level that defines it"},
+                 "hint": {"type": "string", "description": "when nothing sat below --threshold: the track's measured level and the --threshold that would find its pauses"},
                  "speech_aware": {"type": "object", "description": "--speech-aware (1.18): {min_silence, floor, breaths_kept, breaths_kept_seconds, breaths}"},
                  "filler": {"type": "object", "description": "--filler: {lang, source (whisper-json:FILE | whisper:ENGINE | parakeet:ENGINE), engine, transcription (with --transcribe: {engine, model, language, routing}), removed, removed_count, matched_untimed (listed words in the transcript with no usable timing, not removed), matched_too_long (listed words longer than a filler, kept), ...}"},
                  "notes": {"type": "array", "items": {"type": "string"}, "description": "--filler --transcribe under --engine auto: present when the English-only Parakeet model ran on English assumed (no --filler-lang, no language detected, no Whisper engine installed or none that succeeded); the transcript is wrong if the speech is not English"}}
@@ -651,6 +671,15 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
                  "notes": {"type": "array", "items": {"type": "string"}, "description": "--boomerang on a source with audio: the audio was dropped"}}
     elif name == "cut":
         extra = {"expected_duration": {"type": "number", "description": "seconds requested"},
+                 "mode": {"enum": ["copy", "hybrid", "accurate"], "description": "copy: nothing re-encoded at any stage, the join included; accurate: --accurate was asked for or forced; hybrid: asked for lossless but a segment or the join re-encoded anyway (reencode_reason says why)"},
+                 "requested_start": {"type": ["number", "null"], "description": "one segment: the requested start, clamped to the media's duration (null for --segments)"},
+                 "requested_end": {"type": ["number", "null"], "description": "one segment: the requested end, clamped to the media's duration (null for --segments)"},
+                 "requested_segments": {"type": ["array", "null"], "description": "--segments: [[start, end], ...] requested, clamped to the media's duration (null for one segment)"},
+                 "requested_duration": {"type": "number", "description": "the requested length, as expected_duration"},
+                 "output_duration": {"type": ["number", "null"], "description": "the written file's length, measured (null under --dry-run)"},
+                 "duration_delta_seconds": {"type": ["number", "null"], "description": "output_duration minus requested_duration (null under --dry-run)"},
+                 "nearest_keyframes": {"type": ["array", "null"], "description": "the keyframes within 5 s of a start whose stream copy snapped past --tolerance and was re-encoded (null otherwise)"},
+                 "snap": {"type": ["object", "null"], "description": "--snap beats: {mode, tolerance, confidence, tempo_bpm, grid, grid_points, moved, snapped, unchanged, source}; null otherwise"},
                  "dropped_audio_streams": {"type": "integer", "description": "audio tracks of the source this cut did not write (cut writes one, on a stream copy as on a re-encode); 0 for a source with one or none. A notes line and an audio_tracks_dropped warning say so too"},
                  "duration_error_ms": {"type": ["number", "null"], "description": "written minus requested, measured by ffprobe (null under --dry-run)"},
                  "precision": {"enum": ["packet", "sample", "codec_frame", "frame"],
@@ -696,6 +725,8 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
                  "audio": {"type": "object", "description": "what the mix was built from: voice (null | light | medium | strong), stereo_widen, effects/effects_volume, and with --music the music_volume plus duck (null when --duck was not given, else the threshold in dB and linear, ratio, attack_ms, release_ms, amount_db actually used)"}}
     if name in ("overlay", "graphics", "caption", "grid"):
         extra["font_used"] = FONT_USED_SCHEMA
+    if name in NON_AV_STREAM_TOOLS and "dropped_non_av_streams" not in extra:
+        extra["dropped_non_av_streams"] = {"type": "boolean", "description": "true when the source's subtitle or data streams are not in the output: either the run leaves them out by design (a path whose output they would no longer match, such as speedramp.py's, join.py's or freeze.py's), or they could not be copied and the encode ran again without them (then a non_av_streams_dropped fallback says why); export.py's non_av_streams lists them"}
     if name == "cropdetect":
         extra.update({"windows": {"type": "integer", "description": "sampled windows (--samples)"},
                       "windows_failed": {"type": "integer", "description": "windows ffmpeg could not decode and that were skipped (a cropdetect_windows_failed warning when > 0); every window failing is a kind ffmpeg failure"}})

package/scripts/broll.py

@@ -21,7 +21,10 @@ import argparse
 import sys
 from typing import Any, Dict, List
 
-from _common import STATE, add_common, aac_args, apply_common, cfr_args, default_output, die, draws_chroma, drawn_chain, emit, ffmpeg_base, info, time_arg, label_chain, matrix_chain, probe, run, validate_color, video_args, X264_PRESETS, fmt_secs
+from _common.decision import av_trim, 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, 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
 
 
 def main() -> int:
@@ -55,10 +58,20 @@ def main() -> int:
     if not meta_a.get("video"):
         die("A-roll has no video stream")
     dur_a = meta_a.get("duration") or 0.0
-    w, h = meta_a["video"]["width"], meta_a["video"]["height"]
-    # the cutaway is scaled onto the frame ffmpeg has already rotated, not the stored one
-    if meta_a["video"].get("rotation") in (90, -90, 270, -270):
-        w, h = h, w
+    # 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"])
+    a_chain = square_pixels(meta_a["video"])
+    if a_chain:
+        note(square_pixels_note(meta_a["video"], "the A-roll"))
+    if (w % 2 or h % 2) and w and h:
+        # an odd-sized A-roll cannot be encoded 4:2:0 at its own size, and the run-time even-scale
+        # retry does not reach a filter_complex: through 3.1.3 this failed as kind "ffmpeg" (#411)
+        ew, eh = max(2, w - w % 2), max(2, h - h % 2)  # never 0, which scale reads as "keep" (#416 review)
+        record_fallback(f"the A-roll is {w}x{h}, which 4:2:0 cannot hold: scaled to {ew}x{eh}",
+                        "odd_dimensions_scaled_even", output=args.output or default_output(args.input, "broll"), scale=f"scale={ew}:{eh}")
+        a_chain = (a_chain + "," if a_chain else "") + f"scale={ew}:{eh},setsar=1"
+        w, h = ew, eh
     fps = meta_a["video"].get("fps") or 30.0
     has_audio_a = bool(meta_a.get("audio"))
 
@@ -72,13 +85,13 @@ def main() -> int:
         meta_b = probe(path)
         if not meta_b.get("video"):
             die(f"{path} has no video stream")
-        at = time_arg(args.at[i], "--at", fps)
-        start_b = time_arg(per(args.from_, i, "0"), "--from", fps)
+        at = time_arg(args.at[i], "--at", fps, source=meta_a)
+        start_b = time_arg(per(args.from_, i, "0"), "--from", fps, source=meta_b)
         if args.end:
-            end = time_arg(per(args.end, i, "0"), "--end", fps)
+            end = time_arg(per(args.end, i, "0"), "--end", fps, source=meta_a)
             length = end - at
         else:
-            length = time_arg(per(args.duration, i, "4"), "--duration", fps)
+            length = time_arg(per(args.duration, i, "4"), "--duration", fps, source=meta_a)
         if length <= 0:
             die(f"cutaway {i + 1}: length must be > 0 (at {at:g}s, got {length:g}s)")
         if dur_a and at >= dur_a:
@@ -110,16 +123,19 @@ def main() -> int:
     convert = [matrix_chain(m, meta_a) for m in [meta_a] + [c["meta"] for c in cutaways]]
     if any(convert) or draws_chroma([args.pad_color], meta_a):
         convert = [cv or label_chain(m, meta_a) for cv, m in zip(convert, [meta_a] + [c["meta"] for c in cutaways])]
-    if convert[0]:
-        parts.append(f"[0:v]{convert[0]}null[a709]")
+    # overlay mixes samples: a full-range clip over or under a limited one is taken to limited range (#410)
+    convert = [cv + range_chain(m, meta_a) for cv, m in zip(convert, [meta_a] + [c["meta"] for c in cutaways])]
+    if convert[0] or a_chain:
+        parts.append(f"[0:v]{convert[0]}{a_chain or 'null'}[a709]")
         cur = "[a709]"
     pad = f"pad={w}:{h}:(ow-iw)/2:(oh-ih)/2:color="
     for i, c in enumerate(cutaways):
         geo = (f"scale={w}:{h}:force_original_aspect_ratio=decrease,"
-               + drawn_chain(pad + args.pad_color, c["meta"], [args.pad_color], pad + "black", line_meta=meta_a,
+               + drawn_chain(pad + args.pad_color, as_limited(c["meta"]), [args.pad_color], pad + "black", line_meta=meta_a,
                              tag=f"pad{i}", labelled=True))
+        b_sq = (square_pixels(c["meta"]["video"]) + ",") if square_pixels(c["meta"]["video"]) else ""
         parts.append(f"[{i + 1}:v]trim=start={c['from']:.3f}:duration={c['length']:.3f},setpts=PTS-STARTPTS+{c['at']:.3f}/TB,"
-                     f"{convert[i + 1]}{geo},setsar=1,fps={fps:g},format={'yuv420p10le' if (meta_a.get('video') or {}).get('bt2020_or_hdr') else 'yuv420p'}[b{i}]")
+                     f"{convert[i + 1]}{b_sq}{geo},setsar=1,fps={fps:g},format={'yuv420p10le' if (meta_a.get('video') or {}).get('bt2020_or_hdr') else 'yuv420p'}[b{i}]")
         parts.append(f"{cur}[b{i}]overlay=0:0:eof_action=pass:enable='between(t,{c['at']:.3f},{c['at'] + c['length']:.3f})'[v{i}]")
         cur = f"[v{i}]"
     vout = cur
@@ -137,7 +153,12 @@ def main() -> int:
                 parts.append(f"[0:a:0]aformat=sample_rates=48000:channel_layouts=stereo{gate}[a0]")
                 layers.append("[a0]")
             for i, c in enumerate(cutaways):
-                parts.append(f"[{i + 1}:a:0]atrim=start={c['from']:.3f}:duration={c['length']:.3f},asetpts=PTS-STARTPTS,"
+                # B's sound is shifted by the same constant as its picture, whose first frame (the
+                # first at or after --from) lands on --at; rebasing the sound to its own first
+                # sample moved a track that starts 0.3 s late 0.279 s early (#409)
+                v0b = stream_starts(c["meta"])[0]
+                first = max(v0b, grid_at_or_after(c["from"], v0b, frame_rate(c["meta"])))
+                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]")

package/scripts/caption.py

@@ -45,7 +45,7 @@ from _platforms import (PLATFORMS, PLATFORM_CHOICES, ASS_SCRIPT_HEIGHT, ass_unit
                         resolve as resolve_platform)
 from _ass_overlay import EMOJI_SENTINEL, emoji_placeholder, ass_escape
 from _common.emit import refuse  # noqa: E402
-from _common import require_filter, emoji_filter_chain, EMOJI_ASSET_HINT, emoji_asset_for, emoji_codepoint_name, emoji_support, resolve_emoji_assets, ADVANCE_EM, LATIN_EM, NO_SPACE_SCRIPTS, _char_em, char_script, text_width_em, emoji_clusters, has_emoji, detect_script, BIDI_SCRIPTS, STATE, brand_states_font, script_font_for_text, signed_time_arg, brand_caption_style, color_hex, drawn_chain, label_chain, load_brand, rgb_chain_to_bt709, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, fmt_smpte_time, info, MissingFpsError, parse_time, probe, run, x264_args, X264_PRESETS, read_text_or_die, fmt_secs, refuse_existing_outputs, guard_sidecar
+from _common import require_filter, emoji_filter_chain, EMOJI_ASSET_HINT, emoji_asset_for, emoji_codepoint_name, emoji_support, resolve_emoji_assets, ADVANCE_EM, LATIN_EM, NO_SPACE_SCRIPTS, _char_em, char_script, text_width_em, emoji_clusters, has_emoji, detect_script, BIDI_SCRIPTS, STATE, brand_states_font, script_font_for_text, signed_time_arg, brand_caption_style, color_hex, drawn_chain, label_chain, layer_base_chain, load_brand, rgb_chain_to_bt709, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, fmt_smpte_time, info, MissingFpsError, parse_time, probe, run, x264_args, X264_PRESETS, read_text_or_die, fmt_secs, refuse_existing_outputs, guard_sidecar
 # The line breaker, lifted into _common/text.py in 1.16.0 so graphics.py can use the same rules.
 # The ASR bridge and the SRT reader/writer live in _common.asr since 1.17 (silence.py --filler
 # shares them). They stay caption.py's public names -- every caller and test that reached for
@@ -53,6 +53,8 @@ from _common import require_filter, emoji_filter_chain, EMOJI_ASSET_HINT, emoji_
 from _common import asr as _asr
 from _common.asr import ENGINE_CHOICES
 from _common.emit import warn
+from _common.probe import display_size, square_pixels, square_pixels_note
+from _common.runner import subtitle_codec_for, subtitle_container_holds
 from _common.fonts import font_choice, record_font_choice
 from _common import (ASR_INSTALL_HINT, die_no_engine, parse_srt, transcribe, whisper_word_timings,
                      write_srt)
@@ -144,7 +146,9 @@ def word_durations_from_audio(video: str, start: float, end: float, n_words: int
         return [total_cs]
     ffmpeg = require_tool("ffmpeg")
     cmd = [ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin", "-ss", f"{start:.3f}", "-i", video,
-           "-map", f"0:a:{audio_stream}", "-t", f"{end - start:.3f}", "-vn", "-ac", "1", "-ar", "8000", "-f", "s16le", "-"]
+           "-map", f"0:a:{audio_stream}", "-t", f"{end - start:.3f}", "-vn",
+           # a sound that starts late is padded to its place on the file's clock (#414)
+           "-af", "aresample=async=1:first_pts=0", "-ac", "1", "-ar", "8000", "-f", "s16le", "-"]
     proc = run_analysis(cmd, check=False, text=False)  # under --timeout like every other measurement
     n = len(proc.stdout) // 2
     if proc.returncode != 0 or n < 800:
@@ -886,6 +890,23 @@ def track_title_for(code: Optional[str], given: Optional[str]) -> Optional[str]:
     return LANG_TITLES.get(code.split("-")[0].lower(), code)
 
 
+# a timing line in the grammar ffmpeg's SRT demuxer and parse_srt() read alike: hours, minutes,
+# seconds and three-digit milliseconds on both sides (ffmpeg allows position fields after it)
+_SHARED_SRT_TIMING = re.compile(r"^\s*\d{2,}:\d{2}:\d{2}[,.]\d{3}\s*-->\s*\d{2,}:\d{2}:\d{2}[,.]\d{3}(\s.*)?$")
+
+
+def srt_timings_shared_grammar(path: str) -> bool:
+    """True when every timing line of the SRT at `path` reads the same to ffmpeg's SRT demuxer as
+    to parse_srt(). ffmpeg refuses `00:01,000` (no hours) and reads `00:00:01,5` as 1.005 s, where
+    parse_srt() reads 1.5 s (#414); such a file is handed to ffmpeg as a rewritten copy."""
+    text = read_text_or_die(path, "--srt").lstrip("\ufeff").replace("\r\n", "\n")
+    # a cue's timing line is its first line with "-->", as parse_srt() reads it (and ffmpeg too);
+    # a later line holding "-->" is dialogue, not a timing this check should judge
+    blocks = [[ln for ln in b.split("\n") if ln.strip()] for b in re.split(r"\n\s*\n", text)]
+    timings = [next((ln for ln in b if "-->" in ln), None) for b in blocks]
+    return all(_SHARED_SRT_TIMING.match(line) for line in timings if line is not None)
+
+
 def mux_subtitle_codec(output: str) -> str:
     ext = Path(output).suffix.lower()
     if ext in (".mp4", ".m4v", ".mov"):
@@ -1129,6 +1150,11 @@ def main() -> int:
             die(f"--audio-stream {args.audio_stream}: input has {len(audio_streams)} audio stream(s), 0..{len(audio_streams) - 1}")
         if args.audio_stream and not audio_streams:
             die("--audio-stream needs an input with audio streams")
+        if args.transcribe and not audio_streams:
+            # refused before any engine runs, as silence.py refuses it, not an unclassified
+            # "Stream map '0:a:0' matches no streams" from the WAV extraction (#414)
+            die(f"--transcribe needs speech to transcribe, and {args.input} has no audio stream",
+                kind="input", hint="pick the file that carries the sound, or write the cues with --text")
         if args.mode != "mux":
             # before any transcription or sidecar: a build without libass fails these at parse time
             # with a message that names no filter (#393), so ask the build first, dry run included
@@ -1139,9 +1165,9 @@ def main() -> int:
 
     play_w = play_h = None
     if meta and meta.get("video"):
-        play_w, play_h = meta["video"]["width"], meta["video"]["height"]
-        if meta["video"].get("rotation") in (90, -90, 270, -270):
-            play_w, play_h = play_h, play_w
+        # the displayed frame: rotation applied, non-square pixels squared (#411) -- the burn
+        # below draws on the square-pixel picture, so a cue is not stretched by the player's SAR
+        play_w, play_h = display_size(meta["video"])
     # A --plan or --dry-run written before the input exists has no geometry to fit against, and a
     # plan that describes a different FontSize from the run that executes it is not a plan. When
     # --platform names a destination, that destination's frame IS the geometry the real run will
@@ -1379,9 +1405,15 @@ def main() -> int:
     side_notes: List[str] = list(getattr(args, "_asr_notes", None) or [])
     ass_counts: dict = {}  # --ass: ass_shifted / ass_unshifted (with --offset) and ass_malformed, into `caption`
     ass_sample_path = args.ass
+    normalised_only = False  # srt_path is a copy of the caller's SRT that only rewrites its timings
     if args.srt and not (args.text or args.transcribe) and os.path.exists(srt_path or ""):
         adjusted, changed = lay_out(parse_srt(srt_path))
-        if changed:
+        # ffmpeg's own SRT reader takes a narrower grammar than parse_srt(): a time without hours
+        # is refused and ",5" is read as 5 ms where this tool reads 500. A file outside the grammar
+        # both share goes to ffmpeg as the copy this tool writes, so it gets the cues counted
+        # here (#414)
+        normalised_only = not changed and not srt_timings_shared_grammar(srt_path)
+        if changed or normalised_only:
             new_srt = os.path.splitext(output)[0] + "_adjusted.srt"
             claim([(new_srt, "adjusted SRT")])
             if STATE.dry_run:
@@ -1391,8 +1423,10 @@ def main() -> int:
                 info(f"wrote {new_srt} ({len(adjusted)} cues, adjusted from {os.path.basename(srt_path)})")
             srt_path = new_srt
             planned_cues = adjusted
-            side_notes.append(f"the burned subtitles are {new_srt}, the adjusted copy of "
-                              f"{os.path.basename(args.srt)} this run writes (--offset/--max-lines/--min-duration)"
+            why = ("--offset/--max-lines/--min-duration" if changed else
+                   "its timings rewritten as hh:mm:ss,mmm, which ffmpeg reads as this tool does")
+            side_notes.append(f"the {'muxed' if args.mode == 'mux' else 'burned'} subtitles are {new_srt}, the adjusted copy of "
+                              f"{os.path.basename(args.srt)} this run writes ({why})"
                               + ("; re-run this command without --dry-run to produce it" if STATE.dry_run else ""))
     if args.ass and args.offset and os.path.exists(args.ass):
         shifted = os.path.splitext(output)[0] + "_offset.ass"
@@ -1423,10 +1457,34 @@ def main() -> int:
                             and not (STATE.dry_run and (args.text or args.transcribe))):
             die(f"SRT file not found: {srt_path}")
         codec = mux_subtitle_codec(output)
+        out_ext = Path(output).suffix.lower().lstrip(".")
+        # The picture and the sound are copied: a WebM holds only VP8/VP9/AV1 and Opus/Vorbis, so
+        # anything else is refused here, not left to fail unclassified in the muxer (#414)
+        if out_ext == "webm":
+            vcodec = (meta.get("video") or {}).get("codec")
+            # the stream -map 0:a:N copies (--audio-stream), not always the first one
+            audio_streams = meta.get("audio_streams") or []
+            acodec = audio_streams[args.audio_stream].get("codec") if args.audio_stream < len(audio_streams) else None
+            bad = [c for c in (vcodec,) if c and c not in ("vp8", "vp9", "av1")] + \
+                  [c for c in (acodec,) if c and c not in ("opus", "vorbis")]
+            if bad:
+                die(f"--mode mux copies the picture and the sound, and a .webm holds only VP8/VP9/AV1 video and "
+                    f"Opus/Vorbis audio; {args.input} carries {' and '.join(bad)}", kind="input",
+                    hint="write .mkv (any codec) or .mp4 instead, or re-encode first with export.py")
         # Keep any subtitle track(s) the input already has (e.g. chaining --mode mux once per
-        # language to build a multi-language set) -- copied byte-identical, distinct from the
-        # newly-added SRTs' own codec below.
+        # language to build a multi-language set): copied where the output container holds them as
+        # they are, else converted to its own text format as export.py converts them (#380, #414);
+        # a track the container cannot hold at all (a bitmap one in MPEG-4 or WebM) is refused.
         existing_subs = meta.get("subtitle_streams") or 0
+        existing_details = list(meta.get("subtitle_stream_details") or [])
+        existing_codecs = [(existing_details[i] if i < len(existing_details) else {}).get("codec") or ""
+                           for i in range(existing_subs)]
+        unheld = sorted({c or "unknown" for c in existing_codecs if not subtitle_container_holds(c, out_ext)})
+        if unheld:
+            die(f"{args.input} already carries a subtitle track ({', '.join(unheld)}) that a .{out_ext} file cannot "
+                "hold, and --mode mux keeps every existing track", kind="input",
+                hint="write .mkv, which holds any subtitle codec")
+        existing_out = [subtitle_codec_for(c, out_ext) for c in existing_codecs]
         # the first entry's path is srt_path, which --offset/--max-lines may have repointed at an
         # adjusted copy; the rest are taken as written
         added = [(srt_path, srt_tracks[0][1] if srt_tracks else args.language)] + \
@@ -1434,6 +1492,18 @@ def main() -> int:
         for path, _lang in added[1:]:
             if not os.path.exists(path) and not STATE.dry_run:
                 die(f"SRT file not found: {path}")
+        for n in range(1, len(added)):
+            path, lang = added[n]
+            if os.path.exists(path) and not srt_timings_shared_grammar(path):
+                # the same rule as the first track (#414): ffmpeg is given what parse_srt() reads
+                copy = f"{os.path.splitext(output)[0]}_track{n}.srt"
+                claim([(copy, f"normalised SRT {n}")])
+                if not STATE.dry_run:
+                    write_srt(parse_srt(path), copy)
+                    info(f"wrote {copy} (timings of {os.path.basename(path)} rewritten as hh:mm:ss,mmm)")
+                side_notes.append(f"subtitle track {n} is {copy}, a copy of {os.path.basename(path)} with its timings "
+                                  "rewritten as hh:mm:ss,mmm, which ffmpeg reads as this tool does")
+                added[n] = (copy, lang)
         titles = list(args.track_title or [])
         mp4_family = Path(output).suffix.lower() in (".mp4", ".m4v", ".mov")
         dropped_titles: List[str] = []
@@ -1452,13 +1522,16 @@ def main() -> int:
         if mp4_family:
             cmd += ["-movflags", "+faststart"]
         for i in range(existing_subs):
-            cmd += [f"-c:s:{i}", "copy"]
+            cmd += [f"-c:s:{i}", existing_out[i]]
         tracks: List[Dict[str, Any]] = []
+        converted: List[str] = []
         for i in range(existing_subs):
-            kept = (meta.get("subtitle_stream_details") or [])
-            detail = kept[i] if i < len(kept) else {}
+            detail = existing_details[i] if i < len(existing_details) else {}
+            written = detail.get("codec") if existing_out[i] == "copy" else existing_out[i]
+            if existing_out[i] != "copy":
+                converted.append(f"{detail.get('codec')} -> {existing_out[i]}")
             tracks.append({"index": i, "file": None, "language": detail.get("language"),
-                           "title": detail.get("title"), "codec": detail.get("codec"),
+                           "title": detail.get("title"), "codec": written,
                            "default": False, "cues": None, "kept_from_input": True})
         for n, (path, lang) in enumerate(added):
             idx = existing_subs + n
@@ -1509,6 +1582,9 @@ def main() -> int:
             notes.append(f"{total} subtitle tracks in an MPEG-4 container: the tracks are all there, "
                          "but many players only ever show the first -- write to .mkv for a "
                          "deliverable a viewer can actually switch")
+        if converted:
+            notes.append(f"the input's own subtitle track(s) were converted to the .{out_ext} container's text format "
+                         f"({', '.join(converted)}): their text and timing are kept, styling a format cannot carry is not")
         if dropped_titles:
             notes.append("an MPEG-4 container has no per-track title this tool can write back "
                          f"({', '.join(dropped_titles)} would be dropped), so the tracks are "
@@ -1520,6 +1596,14 @@ def main() -> int:
                          "as given and may not survive")
         run(cmd)
         result = probe(output, role="output")
+        # the language and title each track carries in the written file: a converted track keeps
+        # only what the container can store (MPEG-4 drops a two-letter code and every title)
+        written = result.get("subtitle_stream_details") or []
+        if len(written) == len(tracks):
+            for track, detail in zip(tracks, written):
+                track["language"] = detail.get("language")
+                if track["kept_from_input"]:
+                    track["title"] = detail.get("title")
         info(f"wrote {output} ({fmt_secs(result.get('duration'))}, mux, {len(added)} "
              f"subtitle track(s) added, codec {codec})")
         emit(output, tracks=tracks, subtitle_tracks=total, **({"notes": notes} if notes else {}),
@@ -1586,12 +1670,11 @@ def main() -> int:
             cues if (args.text or args.transcribe) else (
                 planned_cues if planned_cues is not None else parse_srt(srt_path)))
         if args.karaoke and not getattr(args, "_word_timings", None):
-            args._word_timings = whisper_word_timings(srt_path)
+            # a copy that only rewrote the timings keeps the caller's word-timing JSON beside it
+            args._word_timings = whisper_word_timings(args.srt if normalised_only else srt_path)
         ass_path = args.write_ass or os.path.splitext(output)[0] + ".ass"
         claim([(ass_path, "ASS")])
-        w, h = meta["video"]["width"], meta["video"]["height"]
-        if meta["video"].get("rotation") in (90, -90, 270, -270):
-            w, h = h, w
+        w, h = display_size(meta["video"])
         if not STATE.dry_run:  # the generated ASS is an artifact of this run: a plan writes nothing
             write_ass(cues_for_ass, ass_path, args, w, h, video=args.input if meta.get("audio") else None)
         info(f"wrote {ass_path} ({len(cues_for_ass)} cues, animate={args.animate}, karaoke={args.karaoke})")
@@ -1681,9 +1764,12 @@ def main() -> int:
         vf = drawn_chain(vf, meta, [args.color, args.outline_color]
                          + ([args.highlight_color, args.upcoming_color] if args.karaoke else []))
 
+    if square_pixels((meta or {}).get("video")):
+        vf = square_pixels(meta["video"]) + "," + vf
+        side_notes.append(square_pixels_note(meta["video"]))
     cmd = ffmpeg_base() + ["-i", args.input]
     chains, emoji_inputs = (emoji_filter_chain(emoji_plan or {}, "vsub", "vout", to_yuv=rgb_chain_to_bt709(meta),
-                                               base_chain=label_chain(meta, meta) if rgb_chain_to_bt709(meta) else "")
+                                               base_chain=layer_base_chain(meta))
                             if emoji_plan else ([], []))
     if chains:
         for spec in emoji_inputs:

package/scripts/color.py

@@ -43,7 +43,7 @@ CORRECTION = {
     "exposure":    (0.0,   -3.0,    3.0,   "stops"),   # exposure filter's own full range (linear-domain stops)
     "contrast":    (1.0,    0.0,    2.0,   "x"),       # eq filter; 0=flat grey, 1=unchanged, 2=double contrast
     "saturation":  (1.0,    0.0,    2.0,   "x"),       # eq filter; 0=grayscale, 1=unchanged, 2=double saturation
-    "temperature": (6500.0, 2000.0, 12000.0, "K"),     # colortemperature filter; 6500=unchanged (its own default)
+    "temperature": (6500.0, 2000.0, 12000.0, "K"),     # colortemperature filter; 6500=unchanged (no term: the filter itself tints at 6500)
     "tint":        (0.0,   -1.0,    1.0,   "x"),       # mapped to colorbalance midtones, see correction_chain()
     "gamma":       (1.0,    0.1,   10.0,   "x"),       # eq filter's own gamma option; 1=unchanged (its own default)
     "lift":        (0.0,   -1.0,    1.0,   "x"),       # colorbalance shadows (rs=gs=bs); 0=unchanged
@@ -116,11 +116,13 @@ def correction_chain(args: argparse.Namespace) -> str:
         die(f"--levels-out-black {out_black} must be less than --levels-out-white {out_white}")
 
     gm, rm, bm = -tint, tint / 2.0, tint / 2.0
-    rgb = [
-        f"exposure=exposure={exposure:g}",
-        f"colortemperature=temperature={temperature:g}",
-        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}",
-    ]
+    rgb = [f"exposure=exposure={exposure:g}"]
+    if temperature != CORRECTION["temperature"][0]:
+        # colortemperature at 6500 K is not the identity it is documented as here: it multiplies by
+        # its own approximation of that white point, which tinted grey 808080 to 7E7E7B (#410), so
+        # "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), 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):
@@ -156,6 +158,31 @@ def _rgb_stage(filters: list) -> str:
             + ",scale=out_color_matrix=bt601,format=yuv420p")
 
 
+# swscale's names for the non-BT.709 matrices a --codec prores re-encode keeps (it does not convert)
+_SWS_MATRIX = {"smpte170m": "bt601", "bt470bg": "bt601", "smpte240m": "smpte240m", "fcc": "fcc"}
+
+
+def lut_legs(meta=None) -> "tuple":
+    """(to RGB, back to YUV) around --lut's lut3d: explicit BT.709 conversions through float RGB,
+    the matrix the picture holds when it reaches them (an untagged or BT.709 source as it is, a
+    BT.601 or RGB one after x264_args(source=...)'s conversion), limited range on the way out.
+
+    lut3d takes RGB, and left to libavfilter the way in honoured the frame's BT.709 tag while the
+    way back used swscale's BT.601 default, so even an identity LUT shifted every colour (2FAE4E to
+    249A4B, #410); --correct had its legs pinned for the same reason in #159. A LUT maps the RGB the
+    picture really shows, so unlike --correct's working-space pair (bt601 both ways, see
+    _rgb_stage) these legs use the BT.709 the picture is: an identity LUT then returns every sample
+    as --lut-strength 0, which applies none, does (6.1, BT.709/BT.601/untagged, limited and full
+    range, 8- and 10-bit). The input range is read from the frames, as every scale here reads it."""
+    # --codec prores keeps a BT.601 (or other non-BT.709) source's matrix and tags instead of
+    # converting it (decision.video_args), so the legs use that matrix (#416 review)
+    matrix = "bt709"
+    if STATE.codec == "prores":
+        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=yuv420p")
+
+
 def hdr_to_sdr_chain(meta: dict, tonemap: str, peak: float, desat: float) -> str:
     v = meta["video"]
     trc = v.get("color_transfer") or "smpte2084"
@@ -442,6 +469,7 @@ def main() -> int:
         if not (0.0 <= args.lut_strength <= 1.0):
             die(f"--lut-strength {args.lut_strength:g} is outside 0..1")
         lut = f"lut3d=file={escape_filter_path(args.lut)}:interp=tetrahedral"
+        to_rgb, to_yuv = lut_legs(meta)
         if args.lut_strength == 0.0:
             # 0 means "no LUT at all" -- without this branch, 0 (falling outside the open interval
             # below) landed in the same "apply the LUT at full strength" fallback as an out-of-range
@@ -450,9 +478,10 @@ def main() -> int:
             vf = "format=yuv420p"
         elif args.lut_strength < 1.0:
             # blend graded and original
-            vf = f"split[o][g];[g]{lut}[g2];[o][g2]blend=all_mode=normal:all_opacity={args.lut_strength:g},format=yuv420p"
+            # blended in RGB, both pictures through the same two legs
+            vf = f"{to_rgb},split[o][g];[g]{lut}[g2];[o][g2]blend=all_mode=normal:all_opacity={args.lut_strength:g},{to_yuv}"
         else:
-            vf = f"{lut},format=yuv420p"
+            vf = f"{to_rgb},{lut},{to_yuv}"
         output = args.output or default_output(args.input, "lut")
         tag = "lut"
 

package/scripts/crop.py

@@ -22,6 +22,8 @@ import argparse
 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.emit import note
 
 
 def main() -> int:
@@ -51,15 +53,18 @@ def main() -> int:
     meta = probe(args.input)
     if not meta.get("video"):
         die("input has no video stream")
-    sw, sh = meta["video"]["width"], meta["video"]["height"]
-    if meta["video"].get("rotation") in (90, -90, 270, -270):
-        sw, sh = sh, sw
+    # the rectangle is in the displayed frame cropdetect.py reports: rotation applied, and a
+    # non-square-pixel source squared at its display aspect first (#411)
+    sw, sh = display_size(meta["video"])
     if args.x + args.width > sw or args.y + args.height > sh:
         die(f"crop rectangle ({args.x},{args.y},{args.width}x{args.height}) exceeds the source frame ({sw}x{sh})")
     has_audio = bool(meta.get("audio"))
 
     output = args.output or default_output(args.input, "crop")
     vf = [f"crop={args.width}:{args.height}:{args.x}:{args.y}", "setsar=1"]
+    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)]
     cmd += video_args(meta, args.crf, args.preset)
     cmd += cfr_args(meta, args.fps)

package/scripts/cropdetect.py

@@ -34,7 +34,8 @@ from collections import Counter
 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 warn
+from _common.emit import note, warn
+from _common.probe import display_size, square_pixels, square_pixels_note
 
 MOTION_CENTRE_FPS = 2.0
 MOTION_CENTRE_W, MOTION_CENTRE_H = 64, 36
@@ -43,10 +44,11 @@ CROP_RE = re.compile(r"crop=(\d+):(\d+):(\d+):(\d+)")
 
 
 def detect(path: str, seconds: float, samples: int, limit: float, round_to: int, duration: float,
-           failed: "Optional[List[Dict]]" = None) -> List[Tuple[int, int, int, int]]:
+           failed: "Optional[List[Dict]]" = None, square: str = "") -> List[Tuple[int, int, int, int]]:
     """Crop rectangles from `samples` windows spread over the file. A window ffmpeg cannot decode
     is skipped, and appended to `failed` as {start, seconds, error} when the caller passes a list,
-    so the result can say how many of the readings it stands on."""
+    so the result can say how many of the readings it stands on. `square` is the source's
+    square_pixels() scale, run first so the rectangle is in the frame crop.py crops (#411)."""
     ffmpeg = require_tool("ffmpeg")
     per_window = max(0.5, seconds / max(1, samples))
     rects: List[Tuple[int, int, int, int]] = []
@@ -55,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", f"cropdetect=limit={limit:g}:round={round_to}:reset=1", "-f", "null", "-"]
+               "-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
@@ -144,16 +146,18 @@ def main() -> int:
     meta = probe(args.input)
     if not meta.get("video"):
         die("input has no video stream")
-    sw, sh = meta["video"]["width"], meta["video"]["height"]
     # cropdetect and the grey decode both see the frame after ffmpeg applies rotation, so the
     # rectangle and the motion points are in that frame. Reporting the stored size made a
-    # 176x320 crop look taller than a 320x180 source.
-    if meta["video"].get("rotation") in (90, -90, 270, -270):
-        sw, sh = sh, sw
+    # 176x320 crop look taller than a 320x180 source. A non-square-pixel source is measured
+    # squared at its display aspect, the frame crop.py then crops (#411).
+    sw, sh = display_size(meta["video"])
+    if square_pixels_note(meta["video"]):
+        note(square_pixels_note(meta["video"]))
     duration = meta.get("duration") or 0.0
 
     failed: List[Dict] = []
-    rects = detect(args.input, args.seconds, args.samples, args.limit, args.round_to, duration, failed)
+    rects = detect(args.input, args.seconds, args.samples, args.limit, args.round_to, duration, failed,
+                   square_pixels(meta["video"]))
     # windows_failed: a window ffmpeg could not decode was skipped without a word, so a
     # crop measured on one window of five read as well-founded as one measured on all five
     result: Dict = {"file": args.input, "source_width": sw, "source_height": sh,