ffmpeg-skill 3.1.5 → 3.1.7

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.1.5`) | any release |
+| `skill.version` | the npm / package.json version (`3.1.7`) | 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.1.5", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "3.1.7", "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"},
@@ -786,8 +786,10 @@ Per-tool keys added after 2.10.11 ("nothing happens silently"), all additive:
 | `matched_untimed`, `matched_too_long` | `silence.py --filler` (inside `filler`) | listed words that were not cut: no usable timing in the transcript (also a `filler_words_untimed` warning), or longer than a filler (`FILLER_MAX_WORD`, a held vowel) |
 
 `caption.py --transcribe` and `silence.py --filler --transcribe`: when a local speech engine ran
-and produced no cue, the refusal is `"<engine> found no speech in <input>"` with `kind: input`,
-`reason: "no_speech"` and `engine` in the failure document — distinct from the "no local
+and produced no cue (for `--filler`: a Whisper transcript with no text at all; text without word
+timings is a build without them, refused as such), the refusal is `"<engine> found no speech in
+<input>"` with `kind: input`, `reason: "no_speech"` and `engine` in the failure document (the
+three ASR reasons below are in `error.reason` too, with `error.details`) — distinct from the "no local
 speech-to-text engine found" refusal, which now only means no engine was found. When `--engine
 auto` found engines and none transcribed, the refusal is `kind: input` with `reason:
 "engine_failed"` (one ran and failed) or `"english_only"` (the only engines found were Parakeet
@@ -865,8 +867,9 @@ A refusal also carries `error.reason`, a stable snake_case code for *why*
 `output_is_directory`, `output_dir_missing`, `output_dir_not_writable`, `output_locked`,
 `media_path_is_url`, `media_path_is_playlist` (an HLS or ffconcat playlist given as media),
 `output_looks_like_option` (an output starting with `-`, other than `-` for stdout), `output_path_taken` (two files one run writes share a path), `media_path_not_a_file` (a FIFO or device as input), `silence.py --timemap`'s `timemap_path_taken`, `join.py --copy`'s `join_copy_mismatch`,
-`render.py`'s `plan_*` reasons, and `--codec av1`/`prores`'s `encoder_missing` and
-`encoder_list_unreadable`), and `error.details`, the facts the message is written from, so a
+`render.py`'s `plan_*` reasons, `--codec av1`/`prores`'s `encoder_missing` and
+`encoder_list_unreadable`, and `--transcribe`'s `asr_engine_missing`, `no_speech`, `engine_failed`
+and `english_only`), and `error.details`, the facts the message is written from, so a
 caller never parses the prose:
 
 ```
@@ -886,7 +889,8 @@ present on success and failure documents alike, only when one list is not empty,
 `render.py` stage reported carries `stage`. `contract --json` → `json_output.diagnostic_codes`
 lists every code with its bucket and meaning (a test reads every `warn()`/`record_fallback()`/
 `record_skip()` call against it). Among them: the runner's `odd_dimensions_scaled_even` (an encode
-re-run with an even scale; the frame loses a row or column), `non_av_streams_dropped` (with the
+re-run with an even scale, or broll.py's odd-sized A-roll scaled even up front; the frame loses a
+row or column), `non_av_streams_dropped` (with the
 first attempt's error beside `dropped_non_av_streams`), `measurement_input_pending` (skipped: a
 dry-run measurement of an earlier stage's output), `ffmpeg_list_unreadable` (`ffmpeg -encoders` or
 `-bsfs` could not be read; what needed it names the read failure, not a missing encoder) and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "3.1.5",
+  "version": "3.1.7",
   "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": [
     "ffmpeg",

package/references/ci-platform-pitfalls.md

@@ -178,8 +178,9 @@ these had ever shown up before.
   pads audio should do the same.
 - **FFmpeg 8.0 and 8.0.1's `aselect` passes every frame through** (its `activate` callback was lost
   in the filter conversion; fixed in 8.0.2/8.1). Nothing fails: the picture is cut and the sound is
-  not. silence.py tags the kept frames with `ametadata=mode=add:...:enable='<expr>'` and keeps them with
-  `ametadata=mode=select`; do not use `aselect` for removal.
+  not. Do not use `aselect` for removal: cut each range with `atrim` (silence.py re-cuts its ranges
+  through cut.py's `--segments --accurate` path; through 3.1.3 it tagged the kept frames with
+  `ametadata=mode=add` and kept them with `ametadata=mode=select`).
 - **FFmpeg 8.0, 8.0.1 and 8.1.0 draw the font's missing-glyph box at each line break of a multi-line
   `drawtext`** (each line is shaped with its newline; fixed in 8.0.2/8.1.1). `ffmpeg_version()` cannot
   tell 8.1.0 from 8.1.1; `drawtext_draws_newline_glyph()` reads the point release. graphics.py routes

package/references/gotchas.md

@@ -319,7 +319,11 @@ the stored width and height plus that rotation. A tool that places or measures
 a rectangle (`fit.py`, `crop.py`, `cropdetect.py`, `broll.py`, `overlay.py
 --scale-percent` / `--platform`, `look.py --safe`) uses the displayed size,
 the two swapped for 90° and 270°, because ffmpeg applies the tag before the
-filter graph.
+filter graph. A JPEG's EXIF Orientation counts as that rotation too. Footage that
+stores non-square pixels (DV, HDV/XDCAM 1440x1080, DVD) is reported with its
+`sample_aspect_ratio`; every tool that sizes, places or draws on the picture
+first scales it to square pixels at its display aspect (its height kept, a
+`notes` line says so), so rectangles and margins are in that displayed frame.
 
 ## Planning
 

package/references/scripts.md

@@ -513,7 +513,8 @@ freeze.py INPUT --hold T [--at T] [--mode insert|extend] [-o OUT]
 how long the freeze lasts. `--mode insert` (default) inserts the hold at
 `--at`, pushing everything after it later by `--hold` seconds. `--mode
 extend` only works with `--at` at (or past) the clip's end and just makes
-the last frame last `--hold` seconds longer, with nothing pushed. Audio is
+the last frame last `--hold` seconds longer, with nothing pushed; `--mode insert` at
+the clip's end (no `--at`) does the same. Audio is
 silent during the held frame in `--mode insert` (there is no source audio
 for a frozen moment that didn't exist before). `--mode insert` drops a
 subtitle/data track rather than copy it with timestamps that no longer match
@@ -650,15 +651,16 @@ silence.py INPUT --filler --words transcript.json [--filler-lang auto|en|ja|ko|z
            [--model MODEL] [--filler-list] [--max-cuts 400]
 ```
 Runs `silencedetect`, keeps `--margin` seconds of air around speech, drops
-gaps shorter than `--min-silence`, and re-encodes once: `select` for the picture
-(frame accurate), the same ranges through `ametadata` for the sound (not `aselect`, which passes every frame
-through on FFmpeg 8.0 and 8.0.1). `--list` prints silences, kept ranges and seconds removed
+gaps shorter than `--min-silence`, and re-encodes the kept ranges the way `cut.py --segments
+--accurate` does: both streams cut on the same frame times, so the sound never drifts from the
+picture at the cuts, and a sound that starts late keeps its offset. `--list` prints silences, kept ranges and seconds removed
 without rendering; `--edl` saves the kept ranges in `cut.py --segments` format
 so the user can edit the list by hand. Quiet rooms need `--threshold -40`
 to `-45`; noisy ones `-30`. Always tell the user how many seconds were removed.
 
 **Breaths and weak word endings.** `--margin` is the padding kept on each side of every cut
-(default 0.2 s since 2.22, 0.15 s before; 0.3 s for a speaker who trails off). `--speech-aware` keeps the short
+(default 0.2 s since 2.22, 0.15 s before; 0.3 s for a speaker who trails off). It is kept around
+silences only: a filler word's cut is the word plus `--filler-pad` (since 3.1.6). `--speech-aware` keeps the short
 breaths inside a sentence and cuts only at sentence-boundary pauses. A `--threshold` set too high
 (-25, say) counts a weak word ending as silence: the result then warns.
 
@@ -851,7 +853,11 @@ OTIO's adapters). Clips keep their in/out and speed (an M2 line, a `timeMap`, a
 `LinearTimeWarp`); `transition` becomes a cross dissolve centred on each cut, trimmed so the
 timeline is exactly as long as `join.py`'s crossfade would render it; `audio.music` is its own
 track; inline `chapters` are markers. Times take the render's own grammar (`"0:05"`,
-`hh:mm:ss:ff` at the source's fps), and the sequence is the project's `frame` sized by
+`hh:mm:ss:ff` at the source's fps; an `out` past a source's end ends at it, as the render
+cuts it, with a note; a chapter metadata.py would refuse is refused). Source positions count
+from each source's start timecode at its own frame rate (EDL source timecodes, drop-frame
+where the source's is; the FCPXML asset's `start`; OTIO's `available_range`), so a conform
+finds the frames (3.1.6). The sequence is the project's `frame` sized by
 fit.py's rule (`{aspect 16:9, width 1920}` is 1920x1080; an aspect alone takes the export
 preset's size when the preset has that aspect; an aspect fit.py refuses, such as `16/9`, is
 refused unless the project's own `fit.aspect` replaces it in the render). A clip of another

package/scripts/_common/__init__.py

@@ -70,7 +70,8 @@ from _common.emit import (
 from _common.probe import (
     analyze_levels, _aspect_string, _bit_depth, decode_pcm_mono, detect_scenes, detect_silences, fingerprint,
     _fraction, keyframes_near, classify_frame_timing, measure_frame_timing, SCORE_RE, SIL_RE, decode_gray_frames,
-    measured_level_dbfs, AUDIO_MEDIA_EXT, MEDIA_EXT, _output_failed, probe, rms_envelope, _to_float, _to_int, verify_output
+    measured_level_dbfs, AUDIO_MEDIA_EXT, MEDIA_EXT, _output_failed, probe, rms_envelope, _to_float, _to_int, verify_output,
+    display_size, pixel_aspect, square_pixels, square_pixels_note
 )
 from _common.decision import (
     aac_args, add_pad_fill_args, aspect_ratio, audio_codec_for, AUDIO_CODECS, brand_caption_style, BRAND_DEFAULTS,
@@ -84,7 +85,7 @@ from _common.decision import (
     _onset_strength, _pick_onsets, _autocorrelation_peak, _grid_score,
     brand_states_font, cfr_args, concat_list_line, db_to_linear, default_output, encoder_args, escape_filter_path,
     fmt_secs, fmt_smpte_time, fmt_srt_time, frame_size, is_audio_output, load_brand, MissingFpsError, pad_filters, parse_time,
-    signed_time_arg, source_codec_video_args, drawn_chain, draws_chroma, label_chain, matrix_chain, rgb_chain_to_bt709, SVT_PRESET, time_arg, video_args, x264_args, _x264_raw
+    signed_time_arg, source_codec_video_args, drawn_chain, draws_chroma, label_chain, layer_base_chain, matrix_chain, range_chain, rgb_chain_to_bt709, SVT_PRESET, time_arg, video_args, x264_args, _x264_raw
 )
 from _common.asr import (
     ASR_ENGINES, ASR_INSTALL_HINT, _asr_run, die_no_engine, parse_srt, transcribe, _transcribe_in,
@@ -93,7 +94,7 @@ from _common.asr import (
 )
 from _common.color import (
     bt709_label_filter, bt709_matrix_args, bt709_matrix_filter, bt709_tag_args, color_hex, _COLOR_TOKEN_RE, drawn_stream_format, fold_bt709_matrix,
-    is_neutral_color, is_rgb, NON_BT709_MATRICES, rgb_island, rgb_to_bt709_filter, _sdr_bt709, validate_color
+    as_limited, is_full_range, is_neutral_color, is_rgb, limited_range_filter, NON_BT709_MATRICES, rgb_island, rgb_to_bt709_filter, _sdr_bt709, validate_color
 )
 from _common.text import (
     ADVANCE_EM, BIDI_SCRIPTS, _char_em, char_script, default_font_file, detect_script, drawtext_boxborderw, drawtext_center_align, drawtext_fontfile,
@@ -215,7 +216,7 @@ __all__ = [
     "SCRIPTS", "_sdr_bt709", "_set_current_ctx", "_SHAPING_BUILD_CACHE", "SHAPING_SCRIPTS", "shell_quote", "sibling_temp", "still_input_args",
     "_SIGNALS_INSTALLED", "signed_time_arg", "_stage_existing_output", "STATE", "SVT_PRESET", "text_width_em",
     "time_arg", "_timed_out", "_to_float", "_to_int", "_unwatch", "validate_color", "verify_output",
-    "source_codec_video_args", "drawn_chain", "draws_chroma", "drawn_stream_format", "is_neutral_color", "rgb_island", "label_chain", "matrix_chain", "rgb_chain_to_bt709", "bt709_label_filter", "rgb_to_bt709_filter", "is_rgb", "video_args", "_VS15", "_VS16", "_watch", "WINDOWS_FONTS", "write_plan", "x264_args", "X264_PRESETS",
+    "source_codec_video_args", "drawn_chain", "draws_chroma", "drawn_stream_format", "is_neutral_color", "rgb_island", "label_chain", "layer_base_chain", "matrix_chain", "range_chain", "as_limited", "is_full_range", "limited_range_filter", "rgb_chain_to_bt709", "bt709_label_filter", "rgb_to_bt709_filter", "is_rgb", "video_args", "_VS15", "_VS16", "_watch", "WINDOWS_FONTS", "write_plan", "x264_args", "X264_PRESETS",
     "_x264_raw", "_ZWJ",
     "absorb_stage", "audit", "note", "_plan_unbound_inputs", "record_fallback", "record_skip", "refuse", "warn",
     "ASR_ENGINES", "ASR_INSTALL_HINT", "_asr_run", "die_no_engine", "parse_srt", "transcribe",
@@ -229,5 +230,6 @@ __all__ = [
     "PENALTY_IDEOGRAPHS", "PENALTY_NEUTRAL", "PENALTY_OKURIGANA", "PENALTY_PARTICLE", "PENALTY_SENTENCE_END",
     "_rebalance", "_rebalance_phrase", "SAFE_WIDTH_FRACTION", "_split_hyphens", "_slice_atom", "_particle_ends",
     "_particle_starts", "wrap_text", "wrap_variants", "WRAP_MODES",
-    "fit_size", "line_em_for_size", "MIN_CAPTION_FRACTION", "ass_units_local"
+    "fit_size", "line_em_for_size", "MIN_CAPTION_FRACTION", "ass_units_local",
+    "display_size", "pixel_aspect", "square_pixels", "square_pixels_note"
 ]

package/scripts/_common/asr.py

@@ -115,7 +115,9 @@ def die_no_speech(engine: str, video: str) -> None:
     """An engine ran and heard nothing: kind input, `reason: "no_speech"`, naming the engine and
     the input -- not the "no engine found" refusal (one was found) and not "no cues found in"
     the engine's own temporary SRT (a path the caller never gave and that is already deleted)."""
+    # the reason is error.reason as every refusal's is (#414), and stays top-level where 2.x put it
     die(f"{engine} found no speech in {video}", kind="input", reason=NO_SPEECH_REASON, engine=engine,
+        error_extra={"reason": NO_SPEECH_REASON, "details": {"engine": engine}},
         hint="check that the input (and --audio-stream) carries the speech, or write the cues by hand with --text")
 
 
@@ -135,6 +137,7 @@ def die_engine_failed(engine: str, video: str, tried: "List[Dict[str, str]]", in
     detail = next((t["detail"] for t in tried if t["engine"] == engine), "failed")
     die(f"--engine {engine} could not transcribe {video}: {engine} {detail}", kind="input",
         reason=ENGINE_FAILED_REASON, engine=engine, detail=detail,
+        error_extra={"reason": ENGINE_FAILED_REASON, "details": {"engine": engine, "detail": detail}},
         hint="fix the engine (its own message is in detail), or use --engine auto to fall back to another installed engine")
 
 
@@ -152,7 +155,9 @@ def die_engines_failed(tried: "List[Dict[str, str]]", video: str, flag: str, alt
     die(f"no installed speech-to-text engine could transcribe {video} for {flag}:\n"
         + "\n".join(f"  {t['engine']} {t['detail']}" for t in tried) + "\n" + alternative,
         kind="input", reason=ENGINE_FAILED_REASON if failed else ENGLISH_ONLY_REASON,
-        engine=(failed or tried)[0]["engine"], engines=[dict(t) for t in tried], hint=hint)
+        engine=(failed or tried)[0]["engine"], engines=[dict(t) for t in tried], hint=hint,
+        error_extra={"reason": ENGINE_FAILED_REASON if failed else ENGLISH_ONLY_REASON,
+                     "details": {"engine": (failed or tried)[0]["engine"], "engines": [dict(t) for t in tried]}})
 
 
 def _failed(engine: str, detail: str) -> "Dict[str, str]":
@@ -317,15 +322,11 @@ def _transcribe_in(tmpdir: str, video: str, out_srt: str, language: Optional[str
                    parakeet_model: Optional[str] = None) -> Transcription:
     """`model` is what the Whisper engines run; the Parakeet engines are offered `parakeet_model`
     (default `model`), which differs only for a Parakeet model from $FFMPEG_SKILL_ASR_MODEL."""
-    from _common import run_analysis, STATE
+    from _common import STATE
     pmodel = model if parakeet_model is None else parakeet_model
     language = engine_language(language)
     wav = os.path.join(tmpdir, "audio.wav")
-    # A wav in our own temp dir: a measurement input for the engine, not a deliverable, so it
-    # is not a run() call (no --dry-run gate, not recorded), but it keeps the time limit and
-    # reports an unreadable input as kind ffmpeg instead of a CalledProcessError traceback.
-    run_analysis([ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin", "-y", "-i", video,
-                  "-map", f"0:a:{audio_stream}", "-vn", "-ac", "1", "-ar", "16000", "-c:a", "pcm_s16le", wav])
+    engine_wav(ffmpeg, video, audio_stream, wav)
     # every engine found that did not transcribe, and why: the refusal names them rather than
     # telling the caller to install what is installed
     tried: "List[Dict[str, str]]" = []
@@ -980,6 +981,37 @@ def _heard_nothing(text: str, key: str) -> bool:
     return isinstance(doc, dict) and doc.get(key) == []
 
 
+def _whisper_heard_nothing(path: str, key: str) -> bool:
+    """True when a Whisper engine's JSON is well formed and none of its segments (`key`:
+    whisper.cpp's "transcription", openai-whisper's "segments") holds any text: the engine heard
+    no speech (#414). A document with text and no word timings is a build without them, not
+    silence, and stays the "no word-level timings" refusal."""
+    try:
+        doc = json.loads(Path(path).read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return False
+    if not isinstance(doc, dict) or not isinstance(doc.get(key), list):
+        return False
+    # every segment a dict with a text field, all of them blank: a segment with no `text` at all is
+    # output this skill cannot read, not silence (as _heard_nothing() reads Parakeet's)
+    return all(isinstance(seg, dict) and isinstance(seg.get("text"), str) and not seg["text"].strip()
+               for seg in doc[key])
+
+
+def engine_wav(ffmpeg: str, video: str, audio_stream: int, wav: str) -> None:
+    """The 16 kHz mono WAV an engine transcribes, on the file's clock: a sound that starts after
+    the file's start is padded with silence to its place (aresample first_pts=0, as
+    decode_pcm_mono() does since #409), so every cue and word time counts from the file's start,
+    not from the sound's first sample (#414: a sound 0.276 s late gave cues 0.276 s early).
+    A measurement input in our own temp dir, not a deliverable, so not a run() call (no
+    --dry-run gate, not recorded); it keeps the time limit and reports an unreadable input as
+    kind ffmpeg instead of a CalledProcessError traceback."""
+    from _common import run_analysis
+    run_analysis([ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin", "-y", "-i", video,
+                  "-map", f"0:a:{audio_stream}", "-vn", "-af", "aresample=async=1:first_pts=0",
+                  "-ac", "1", "-ar", "16000", "-c:a", "pcm_s16le", wav])
+
+
 def transcribe_words(video: str, language: "Optional[str]" = None, model: "Optional[str]" = None,
                      audio_stream: int = 0, engine: "Optional[str]" = None) -> "Tuple[List[Dict[str, Any]], Optional[str]]":
     """transcribe_words_result()'s (words, engine) alone: the call shape this function has had
@@ -1021,9 +1053,7 @@ def transcribe_words_result(video: str, language: "Optional[str]" = None, model:
     tmpdir = _tempfile.mkdtemp(prefix="ffskill_asrw_")
     try:
         wav = os.path.join(tmpdir, "audio.wav")
-        run_analysis([ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin", "-y", "-i", video,
-                      "-map", f"0:a:{audio_stream}", "-vn", "-ac", "1", "-ar", "16000",
-                      "-c:a", "pcm_s16le", wav])
+        engine_wav(ffmpeg, video, audio_stream, wav)
 
         tried: "List[Dict[str, str]]" = []  # engines found that gave no words, and why
 
@@ -1065,6 +1095,8 @@ def transcribe_words_result(video: str, language: "Optional[str]" = None, model:
             proc = _asr_run(cmd, _subprocess, "whisper.cpp")
             if proc.returncode == 0 and os.path.exists(base + ".json"):
                 words = _words_from_whisper_cpp_json(base + ".json")
+                if not words and _whisper_heard_nothing(base + ".json", "transcription"):
+                    die_no_speech("whisper.cpp", video)
                 info(f"word timings from whisper.cpp ({len(words)} words)")
                 return Transcription(words=words, engine="whisper.cpp",
                                      facts=dict(facts, engine="whisper.cpp", model=model_path,
@@ -1083,6 +1115,7 @@ def transcribe_words_result(video: str, language: "Optional[str]" = None, model:
             collected: list = []
             crashed: list = []
             heard: list = []
+            spoke: list = []  # a segment with text: speech was heard, word timings or not
 
             def work() -> None:
                 try:
@@ -1091,6 +1124,8 @@ def transcribe_words_result(video: str, language: "Optional[str]" = None, model:
                                                      **({"initial_prompt": prompt} if prompt else {}))
                     heard.append(getattr(decoded, "language", None))
                     for seg in segments:
+                        if str(getattr(seg, "text", "") or "").strip():
+                            spoke.append(True)
                         for w in (getattr(seg, "words", None) or []):
                             collected.append({"word": str(w.word).strip(),
                                               "start": float(w.start), "end": float(w.end)})
@@ -1109,6 +1144,8 @@ def transcribe_words_result(video: str, language: "Optional[str]" = None, model:
                 tried.append(_failed("faster-whisper", "found but failed: " + line))
                 failed = failed or "faster-whisper"
             else:
+                if not collected and not spoke:
+                    die_no_speech("faster-whisper", video)
                 info(f"word timings from faster-whisper ({len(collected)} words)")
                 return Transcription(words=[w for w in collected if w["word"]], engine="faster-whisper",
                                      facts=dict(facts, engine="faster-whisper", model=model,
@@ -1129,6 +1166,8 @@ def transcribe_words_result(video: str, language: "Optional[str]" = None, model:
             doc = os.path.join(tmpdir, "audio.json")
             if proc.returncode == 0 and os.path.exists(doc):
                 words = _words_from_openai_whisper_json(doc)
+                if not words and _whisper_heard_nothing(doc, "segments"):
+                    die_no_speech("openai-whisper", video)
                 info(f"word timings from openai-whisper ({len(words)} words)")
                 return Transcription(words=words, engine="openai-whisper",
                                      facts=dict(facts, engine="openai-whisper", model=model,

package/scripts/_common/color.py

@@ -153,6 +153,45 @@ def is_neutral_color(value: Any) -> bool:
     return False
 
 
+def is_full_range(meta: Optional[Dict[str, Any]]) -> bool:
+    """True when the probed YUV picture is full range: a `yuvj` format, or any other YUV format
+    tagged `pc` (VP9 and AV1 full range decode as plain `yuv420p` tagged pc, 10-bit full range as
+    `yuv420p10le` tagged pc). An RGB picture is not: bt709_matrix_filter() makes it limited YUV."""
+    v = (meta or {}).get("video") or {}
+    if is_rgb(meta) or not v.get("pix_fmt"):
+        return False
+    return str(v["pix_fmt"]).startswith("yuvj") or v.get("color_range") == "pc"
+
+
+def limited_range_filter(meta: Optional[Dict[str, Any]]) -> Optional[str]:
+    """The filter that takes a full-range SDR YUV picture (is_full_range) to limited range, or None
+    for any other picture (limited, RGB, HDR/BT.2020, no probe).
+
+    A tool that puts several pictures in one frame or one stream (concat, xfade, xstack, overlay)
+    passes their samples through as they are, so a full-range clip beside a limited one was shown
+    with the other's range: C03028 came out C9251B (#410). The input range is left to `scale`,
+    which reads it from each frame (FFmpeg 6.1 already converts a full-range non-`yuvj` frame to
+    limited at any resize, so a stated `in_range=pc` would convert some frames twice); only the
+    output range is stated. A `yuvj` format is full range by name, so it is also given its limited
+    name (`format=`), or swscale would write full range under the limited tag."""
+    v = (meta or {}).get("video") or {}
+    if v.get("bt2020_or_hdr") or not is_full_range(meta):
+        return None
+    pf = str(v["pix_fmt"])
+    return "scale=out_range=tv" + (f",format=yuv{pf[4:]}" if pf.startswith("yuvj") else "")
+
+
+def as_limited(meta: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+    """`meta` as it reads after limited_range_filter(): the same probe with a limited-range format and
+    tag, for the code that plans what is drawn on the converted picture (drawn_stream_format)."""
+    if not limited_range_filter(meta):
+        return meta
+    v = dict((meta or {}).get("video") or {})
+    pf = str(v["pix_fmt"])
+    v.update(pix_fmt="yuv" + pf[4:] if pf.startswith("yuvj") else pf, color_range="tv")
+    return {**(meta or {}), "video": v}
+
+
 def drawn_stream_format(meta: Optional[Dict[str, Any]]) -> "Tuple[str, bool]":
     """(pix_fmt, full range) of the picture a tool draws on, for rgb_island(): the probed source's own
     8-bit planar YUV format (an RGB source has become yuv444p, BT.709 limited, through
@@ -161,7 +200,7 @@ def drawn_stream_format(meta: Optional[Dict[str, Any]]) -> "Tuple[str, bool]":
     if is_rgb(meta):
         return "yuv444p", False
     pf = str(v.get("pix_fmt") or "yuv420p")
-    full = pf.startswith("yuvj") or v.get("color_range") == "pc"
+    full = is_full_range(meta)
     if pf not in ("yuv420p", "yuv422p", "yuv444p", "yuvj420p", "yuvj422p", "yuvj444p"):
         pf = "yuv420p"
     return pf, full

package/scripts/_common/decision.py

@@ -14,8 +14,8 @@ import argparse
 from fractions import Fraction
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Sequence, Tuple
-from _common.color import (bt709_label_filter, bt709_matrix_args, bt709_matrix_filter, bt709_tag_args, drawn_stream_format,
-                           is_neutral_color, rgb_island, rgb_to_bt709_filter, _sdr_bt709)
+from _common.color import (as_limited, bt709_label_filter, bt709_matrix_args, bt709_matrix_filter, bt709_tag_args, drawn_stream_format,
+                           is_neutral_color, limited_range_filter, rgb_island, rgb_to_bt709_filter, _sdr_bt709)
 from _common.emit import die, record_fallback, refuse, warn
 from _common.runner import CODECS, STATE, ffmpeg_encoders, ffmpeg_list_error, ffmpeg_version, hw_platform_reason
 
@@ -199,17 +199,60 @@ def parse_time(value: str, fps: Optional[float] = None) -> float:
     return total
 
 
-def time_arg(value: str, flag: str, fps: Optional[float] = None) -> float:
+def time_arg(value: str, flag: str, fps: Optional[float] = None,
+             source: Optional[Dict[str, Any]] = None) -> float:
     """parse_time() for a command-line flag: SMPTE hh:mm:ss:ff resolves with the input's fps when
     the caller has one, and every parse failure is a `kind: input` refusal naming the flag (so
-    `--json` callers get a failure document, never a traceback)."""
+    `--json` callers get a failure document, never a traceback). `source` is the probe of the
+    input the time is in when that is not the first one (a B-roll's --from, an overlay layer's
+    --place range): the SMPTE hint then names that input's start timecode and length."""
     try:
-        return parse_time(value, fps)
+        seconds = parse_time(value, fps)
     except MissingFpsError as e:
         die(f"{flag} {value!r}: {e}")
     except ValueError as e:
         die(f"{flag} {value!r}: {e} (use seconds, mm:ss, hh:mm:ss.ms, or hh:mm:ss:ff at the source's fps or with an explicit @fps suffix)")
-    return 0.0  # unreachable
+    _remember_smpte_hint(value, flag, fps, seconds, source)
+    return seconds
+
+
+def _remember_smpte_hint(value: str, flag: str, fps: Optional[float], seconds: float,
+                         source: Optional[Dict[str, Any]] = None) -> None:
+    """An hh:mm:ss:ff time counts from the file's first frame (00:00:00:00), not from a camera's
+    start timecode (docs/design-decisions.md, time grammar). When one reads past the end of a
+    source that carries a start timecode it was almost certainly typed off the source's own
+    burned-in or NLE timecode: keep a hint naming the frame it would be from the source's start,
+    which die() adds to the refusal a tool then raises for the out-of-range time (#411). The
+    grammar itself, and what a valid time means, are unchanged. A time in another input than the
+    first is judged against that input's own timecode and length (#416 review)."""
+    if source is not None:
+        own = (source.get("timecode") or {}).get("value")
+        tc = (own, source.get("duration")) if own else None
+    else:
+        tc = getattr(STATE, "source_timecode", None)
+    text = value.strip().rpartition("@")[0] if "@" in value else value.strip()
+    if not tc or len(text.split(":")) != 4:
+        return
+    start_tc, duration = tc
+    rate = fps
+    if "@" in value:
+        try:
+            rate = float(value.rpartition("@")[2])
+        except ValueError:
+            return
+    try:
+        start = parse_time(re.sub(r"[;.](\d+)$", r":\1", start_tc), rate)
+    except ValueError:
+        return
+    if not duration or seconds <= duration or seconds < start:
+        return
+    within = seconds - start
+    where = (f"{flag} {text} is {fmt_smpte_time(within, rate)} from the file's start"
+             if within <= duration else f"{flag} {text} is past the end of this {duration:.3f} s file even so")
+    prefix = (f"hh:mm:ss:ff times count from the file's first frame (00:00:00:00), not from the source's "
+              f"start timecode {start_tc}: ")
+    before = STATE.smpte_hint[len(prefix):] + "; " if STATE.smpte_hint and STATE.smpte_hint.startswith(prefix) else ""
+    STATE.smpte_hint = prefix + before + where
 
 
 def signed_time_arg(value: str, flag: str, fps: Optional[float] = None) -> float:
@@ -291,6 +334,97 @@ def escape_filter_path(path: str, *, bind: bool = True) -> str:
     return p
 
 
+# ------------------------------------------------------- both streams on one clock (#409)
+#
+# ffmpeg shifts every stream of an input by one constant (the file's start_time), so a filter graph
+# sees a sound that starts 0.3 s after its picture at 0.3. A per-stream `PTS-STARTPTS` moved that
+# sound 0.3 s early. cut.py's re-cut is the reference: both streams are cut on the same bounds,
+# shifted by the same constant, and the audio is padded to the origin
+# (docs/design-decisions.md, "Both streams of a segment shift by one constant").
+
+def stream_starts(meta: Optional[Dict[str, Any]]) -> Tuple[float, float]:
+    """Where the video and the audio start on the clock a filter graph reads the input on (each
+    stream's start_time minus the file's); 0.0 for a stream whose start is unknown."""
+    from _common.emit import file_origin
+    meta = meta or {}
+    origin = file_origin(meta)
+    out = []
+    for kind in ("video", "audio"):
+        start = (meta.get(kind) or {}).get("start_time")
+        out.append(float(start) - origin if isinstance(start, (int, float)) else 0.0)
+    return out[0], out[1]
+
+
+def frame_rate(meta: Optional[Dict[str, Any]]) -> float:
+    """The video's frame rate as cut.py's grid takes it: r_frame_rate, else fps; 0.0 when unknown."""
+    v = (meta or {}).get("video") or {}
+    try:
+        num, _, den = str(v.get("r_frame_rate") or "").partition("/")
+        rate = float(num) / float(den or 1)
+    except (ValueError, ZeroDivisionError):
+        rate = 0.0
+    if not 0 < rate <= 240:  # a time base (90000/1), not a rate
+        rate = float(v.get("fps") or 0.0)
+    return rate
+
+
+def frame_durations(meta: Optional[Dict[str, Any]], rate: float) -> str:
+    """An `fps` filter at the video's own rate (r_frame_rate as a fraction when it is one), the
+    last filter of a graph whose frames sit on that rate's grid: it moves none of them, and gives
+    each frame its duration back. From FFmpeg 7.0 setpts sets every frame's duration to 0 and
+    leaves the frame rate unknown, so the last frame of a graph that ends after a setpts (av_trim)
+    was written with no duration and the picture read a frame short (3.967 s for 120 frames)."""
+    v = (meta or {}).get("video") or {}
+    try:
+        q = Fraction(str(v.get("r_frame_rate") or ""))
+    except (ValueError, ZeroDivisionError):
+        q = None
+    if q is not None and abs(float(q) - rate) < 1e-6:
+        return f"fps={q.numerator}/{q.denominator}"
+    return f"fps={rate:.6f}"
+
+
+def grid_at_or_after(t: float, v0: float, rate: float) -> float:
+    """The time of the first frame at or after `t` on a constant-rate grid starting at `v0`."""
+    if not rate:
+        return t
+    return v0 + math.ceil((t - v0) * rate - 1e-6) / rate
+
+
+def av_trim(start: float, end: Optional[float], rate: float = 0.0, fill_gaps: bool = False) -> Tuple[str, str]:
+    """The video and the audio filters that cut one segment [start, end) of the graph clock out of
+    both streams and shift both by the same constant, so an offset between them survives; `end`
+    None runs to the stream's end. The picture's trim sits half a frame before each bound (the
+    bounds are frame times: grid_at_or_after), so no FFmpeg version rounds a boundary frame in or
+    out; the audio is padded to the segment's origin when it starts later. `fill_gaps` also fills
+    every later gap in the sound with silence, however short (aresample's default only fills one
+    longer than 0.1 s and stretches the sound by a sample a second for the rest)."""
+    half = 0.5 / rate if rate else 0.0
+    pad = "aresample=async=1:min_hard_comp=0.001:first_pts=0" if fill_gaps else "aresample=async=1:first_pts=0"
+    vend = f":end={end - half:.6f}" if end is not None else ""
+    aend = f":end={end:.6f}" if end is not None else ""
+    return (f"trim=start={start - half:.6f}{vend},setpts=PTS-{start:.6f}/TB",
+            f"atrim=start={start:.6f}{aend},asetpts=PTS-{start:.6f}/TB,{pad}")
+
+
+def av_clip_length(meta: Optional[Dict[str, Any]], fps: float) -> float:
+    """The one length a clip holds once both streams start at its first frame (av_trim from the
+    video's start): the video's, or where the sound ends when it runs more than a frame past the
+    picture (narration is never cut; an AAC tail adds no frame). The container duration is only the
+    fallback when the video's length is unknown (a pending input)."""
+    meta = meta or {}
+    v = (meta.get("video") or {}).get("duration")
+    a = (meta.get("audio") or {}).get("duration")
+    if not v:
+        return meta.get("duration") or 0.0
+    if a:
+        v0, a0 = stream_starts(meta)
+        a = a + a0 - v0  # where the sound ends, counted from the first frame
+    if a and fps and a > v + 1.0 / fps:
+        return a
+    return v
+
+
 def cfr_args(meta: Optional[Dict[str, Any]], fps: Optional[float] = None) -> List[str]:
     """Force a constant frame rate on output when the source looks VFR (or fps is given).
 
@@ -661,6 +795,28 @@ def label_chain(meta: Optional[Dict[str, Any]], line_meta: Optional[Dict[str, An
     return f + "," if f else ""
 
 
+def range_chain(meta: Optional[Dict[str, Any]], line_meta: Optional[Dict[str, Any]]) -> str:
+    """For a picture that a mixing filter (concat, xfade, xstack, overlay) puts beside or under
+    another, encoded through video_args(line_meta): the conversion to limited range its chain
+    takes after its matrix_chain()/label_chain() ("<filter>," -- limited_range_filter), or "" (a
+    limited, RGB or HDR picture, or a line that does not tag BT.709). Every SDR picture such a
+    tool mixes is then limited range, whatever each one was: the filters mix samples, not colours."""
+    if STATE.codec == "prores" or ((line_meta or {}).get("video") or {}).get("bt2020_or_hdr"):
+        return ""
+    f = limited_range_filter(meta)
+    return f + "," if f else ""
+
+
+def layer_base_chain(meta: Optional[Dict[str, Any]]) -> str:
+    """The chain in front of the picture `meta` probes where converted RGB layers (rgb_chain_to_bt709:
+    a still, an emoji PNG, a box of chroma) are overlaid on it: an untagged picture's BT.709 label
+    (label_chain) and, for a full-range one, its conversion to the limited range the layers are
+    made in (range_chain). "" when the line converts no layer (HDR, prores)."""
+    if not rgb_chain_to_bt709(meta):
+        return ""
+    return label_chain(meta, meta) + range_chain(meta, meta)
+
+
 def rgb_chain_to_bt709(line_meta: Optional[Dict[str, Any]], pix_fmt: str = "yuva420p") -> str:
     """For a picture the tool's own graph has made RGB(A) -- a still's `format=rgba` chain
     (overlay.py --image, an emoji PNG) or an RGBA composite (waveform.py's --image plate) -- that
@@ -695,14 +851,25 @@ def drawn_chain(colour_chain: str, meta: Optional[Dict[str, Any]], colours: Sequ
 
     Unchanged: a chain whose colours are all greys (the same YUV under every matrix: the default
     black pads and white text), a line that does not tag BT.709 (HDR, prores). `labelled`: the
-    caller's graph already labels this picture (label_chain()) earlier in the same chain."""
+    caller's graph already labels this picture (label_chain()) earlier in the same chain.
+
+    Before 7.1 `ff_draw` also takes the range from the pixel format alone: full for `yuvj`, limited
+    for every other, so on a full-range picture in a plain format (VP9/AV1 full range, 10-bit full
+    range) even black and white were drawn limited (pad black read 101010, #410), and 6.1's scale
+    has often made such a picture limited before the drawing anyway. There the picture is first
+    taken to limited range (range_chain(), which reads the range from the frames), and the
+    drawing, the colours and rgb_island() all work in limited range. 7.1+ draws in the link's
+    range and is left as it is."""
     line = meta if line_meta == "same" else line_meta
+    pre = ""
+    if ffmpeg_version() < (7, 1) and not str(((meta or {}).get("video") or {}).get("pix_fmt") or "").startswith("yuvj"):
+        pre = range_chain(meta, line)
     if not draws_chroma(colours, line):
-        return colour_chain
+        return pre + colour_chain
     if ffmpeg_version() >= (7, 1):
         return ("" if labelled else label_chain(meta, line)) + colour_chain
-    pix_fmt, full = drawn_stream_format(meta)
-    return rgb_island(colour_chain, neutral_chain, pix_fmt, full, tag)
+    pix_fmt, full = drawn_stream_format(as_limited(meta) if pre else meta)
+    return pre + rgb_island(colour_chain, neutral_chain, pix_fmt, full, tag)
 
 
 def source_codec_video_args(meta: Optional[Dict[str, Any]], crf: int = 18, preset: str = "medium",

package/scripts/_common/emit.py

@@ -79,6 +79,8 @@ def die(msg: str, code: int = 1, kind: str = "input", *, ctx: "Optional[Context]
 
     `error_extra` goes inside `error` (refuse() passes `reason` and `details` there); the
     collector's records (warn() and friends) are merged into the document as emit() merges them."""
+    if extra.get("hint") is None and kind == "input" and getattr(ctx or STATE, "smpte_hint", None):
+        extra["hint"] = (ctx or STATE).smpte_hint  # an hh:mm:ss:ff flag read past a timecoded source's end (#411)
     hint = neutralize(extra.pop("hint", None))
     msg = neutralize(msg)
     ctx = ctx or STATE  # 1.10: the optional per-request Context (2.0 makes it required); STATE is the default instance