ffmpeg-skill 3.1.6 → 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.6`) | 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.6", "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:
 
 ```

package/package.json

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

@@ -659,7 +659,8 @@ 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.
 
@@ -852,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/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/fonts.py

@@ -61,6 +61,13 @@ def resolve_font(font_name: str) -> "Dict[str, object]":
         # common CJK system fonts when the request looks CJK (so Japanese text does not render as
         # boxes in Arial), and Arial only as the last resort.
         wanted = _family_key(font_name)
+        # The family's own file first, from the table of what Windows installs under which file
+        # name (#414): "Malgun Gothic" is malgun.ttf and "Times New Roman" times.ttf, which no
+        # file-name prefix finds -- the prefix rule resolved them to YuGothM.ttc and arial.ttf and
+        # reported a font that is installed as substituted.
+        for name in windows_family_files(wanted):
+            if (fonts / name).is_file():
+                return {"file": str(fonts / name), "family": font_name, "substituted": False, "via": "windows_fonts"}
         try:
             files = sorted(fonts.iterdir()) if fonts.is_dir() else []
         except OSError:
@@ -199,6 +206,25 @@ WINDOWS_FONTS = {
 }
 
 
+# Latin families Windows installs that WINDOWS_FONTS (a per-script table) does not name, by the
+# file each one is installed as: a file name that does not start with the family's name
+WINDOWS_LATIN_FONTS = [("arial.ttf", "Arial"), ("times.ttf", "Times New Roman"), ("cour.ttf", "Courier New"),
+                       ("segoeui.ttf", "Segoe UI"), ("tahoma.ttf", "Tahoma"), ("verdana.ttf", "Verdana"),
+                       ("georgia.ttf", "Georgia"), ("calibri.ttf", "Calibri"), ("cambria.ttc", "Cambria"),
+                       ("consola.ttf", "Consolas"), ("trebuc.ttf", "Trebuchet MS"), ("comic.ttf", "Comic Sans MS"),
+                       ("impact.ttf", "Impact"), ("seguiemj.ttf", "Segoe UI Emoji")]
+
+
+def windows_family_files(wanted_key: str) -> "List[str]":
+    """The Windows Fonts file names of the family whose _family_key() is `wanted_key`, best first,
+    from WINDOWS_FONTS and WINDOWS_LATIN_FONTS ([] for a family neither names)."""
+    out: "List[str]" = []
+    for name, family in [e for entries in WINDOWS_FONTS.values() for e in entries] + WINDOWS_LATIN_FONTS:
+        if wanted_key and _family_key(family) == wanted_key and name not in out:
+            out.append(name)
+    return out
+
+
 _SCRIPT_RANGES = (
     ("ko", ((0x1100, 0x11FF), (0x3130, 0x318F), (0xA960, 0xA97F), (0xAC00, 0xD7FF))),   # Hangul syllables + Jamo
     ("kana", ((0x3040, 0x309F), (0x30A0, 0x30FF), (0x31F0, 0x31FF), (0xFF66, 0xFF9F))),  # hiragana/katakana

package/scripts/_common/probe.py

@@ -146,23 +146,40 @@ def _tag(entry: Dict[str, Any], key: str) -> Optional[str]:
     return next((v for k, v in (entry.get("tags") or {}).items() if k.lower() == key), None)
 
 
+def _nominal_fps(video: Optional[Dict[str, Any]]) -> Optional[int]:
+    """The integer timecode rate of the picture (30 for 29.97), from avg_frame_rate, else
+    r_frame_rate: the order probe()'s `fps` uses, which the timeline export validates against."""
+    for key in ("avg_frame_rate", "r_frame_rate"):
+        try:
+            num, _, den = str((video or {}).get(key) or "").partition("/")
+            rate = float(num) / float(den or 1)
+        except (ValueError, ZeroDivisionError):
+            continue
+        if 0 < rate <= 240:
+            return int(round(rate))
+    return None
+
+
 def start_timecode(streams: List[Dict[str, Any]], fmt: Dict[str, Any],
                    video: Optional[Dict[str, Any]]) -> Dict[str, Any]:
     """The first well-formed `timecode` tag, from the video stream, then a `tmcd` data stream,
     then the container: {value, drop_frame, source}. `drop_frame` is the `;` (or `.`) separator
     before the frames field; `source` is `stream:<ffprobe index>` or `format`. None when no
-    source carries one (all three null). A tag that is not HH:MM:SS[:;.]FF is skipped, not
-    repaired."""
+    source carries one (all three null). A tag that is not HH:MM:SS[:;.]FF, or whose frames field
+    the picture's rate cannot reach, is skipped, not repaired."""
     candidates = []
     if video is not None:
         candidates.append((video, f"stream:{video.get('index')}"))
     candidates += [(s, f"stream:{s.get('index')}") for s in streams
                    if s.get("codec_type") == "data" and str(s.get("codec_tag_string", "")).lower() == "tmcd"]
     candidates.append((fmt, "format"))
+    nominal = _nominal_fps(video)
     for entry, source in candidates:
         value = _tag(entry, "timecode")
         m = _TIMECODE.match(value.strip()) if isinstance(value, str) else None
-        if m:
+        # a frames field the picture's rate cannot reach (frame 29 at 25 fps) is no timecode
+        # either: the next candidate (a tmcd track's own tag) may still hold a real one (#427)
+        if m and not (nominal and int(m.group(5)) >= nominal):
             return {"value": value.strip(), "drop_frame": m.group(4) in ";.", "source": source}
     return {"value": None, "drop_frame": None, "source": None}
 

package/scripts/_common/runner.py

@@ -1486,6 +1486,40 @@ def _has_non_av_streams(cmd: Sequence[str]) -> bool:
     return not kinds or bool(kinds & {"subtitle", "data", "attachment"})
 
 
+# eia_608 (a QuickTime c608 caption track) decodes to text, so it converts like one (ffmpeg 6.1)
+TEXT_SUBTITLES = frozenset({"mov_text", "subrip", "srt", "ass", "ssa", "webvtt", "text", "eia_608"})
+MP4_FAMILY = frozenset({"mp4", "m4v", "mov"})
+
+
+def subtitle_codec_for(codec: str, out_ext: str) -> str:
+    """The -c:s for one source subtitle stream going into a container with extension `out_ext`
+    (no dot): copy when the container holds it as it is, else the container's own text format --
+    mov_text in MPEG-4, srt in Matroska for a mov_text track, webvtt in WebM. A bitmap track is
+    returned as copy; subtitle_container_holds() says whether that copy can work."""
+    out_ext = out_ext.lstrip(".").lower()
+    if out_ext == "mov" and codec == "eia_608":
+        return "copy"  # QuickTime holds a c608 track as it is; .mp4 has no tag for it
+    if out_ext in MP4_FAMILY and codec in TEXT_SUBTITLES and codec != "mov_text":
+        return "mov_text"
+    if out_ext == "mkv" and codec == "mov_text":
+        return "srt"
+    if out_ext == "webm" and codec in TEXT_SUBTITLES and codec != "webvtt":
+        return "webvtt"
+    return "copy"
+
+
+def subtitle_container_holds(codec: str, out_ext: str) -> bool:
+    """Whether a subtitle stream of `codec` can be written to an `out_ext` container at all,
+    converted by subtitle_codec_for() where it must be: Matroska takes any, MPEG-4 a text track or
+    DVD bitmaps, WebM only text (as WebVTT)."""
+    out_ext = out_ext.lstrip(".").lower()
+    if out_ext in MP4_FAMILY:
+        return codec in TEXT_SUBTITLES or codec == "dvd_subtitle"
+    if out_ext == "webm":
+        return codec in TEXT_SUBTITLES
+    return True
+
+
 def run_keeping_subtitles(cmd: List[str], output: str) -> 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/_common/timeline.py

@@ -23,6 +23,7 @@ under `not_exported`, never silently dropped.
 import json
 import math
 import os
+import re
 from fractions import Fraction
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
@@ -110,6 +111,48 @@ def _picture(meta: Dict[str, Any]) -> Optional[Tuple[int, int]]:
     return (w, h)
 
 
+_TC = re.compile(r"^(\d{2}):(\d{2}):(\d{2})[:;.](\d{2,3})$")
+
+
+def _drop_frame(drop: Optional[bool], rate: Fraction) -> bool:
+    """Drop-frame counting applies to the NTSC rates only (29.97 and 59.94)."""
+    return bool(drop) and rate.denominator == 1001 and round(float(rate)) in (30, 60)
+
+
+def start_tc_frames(tc: Dict[str, Any], rate: Fraction) -> int:
+    """A source's start timecode (probe()'s `timecode`: {value, drop_frame}) as a frame count at
+    its own `rate`, drop-frame counted where it is one; 0 when the source has none (#414). A
+    label that does not exist at that rate (frame 29 at 25 fps, or a frame drop-frame counting
+    skips) is read as none, as probe() skips a malformed tag, rather than as a shifted start."""
+    m = _TC.match(str((tc or {}).get("value") or "").strip())
+    if not m:
+        return 0
+    h, mi, se, fr = (int(g) for g in m.groups())
+    nominal = int(round(float(rate)))
+    if mi > 59 or se > 59 or fr >= nominal:
+        return 0
+    frames = ((h * 60 + mi) * 60 + se) * nominal + fr
+    if _drop_frame(tc.get("drop_frame"), rate):
+        if se == 0 and mi % 10 and fr < nominal // 15:
+            return 0
+        minutes = h * 60 + mi
+        frames -= (nominal // 15) * (minutes - minutes // 10)
+    return frames
+
+
+def _tc_label(frames: int, rate: Fraction, drop: bool) -> str:
+    """`frames` as hh:mm:ss:ff at the nominal integer rate; drop-frame (`;`) for an NTSC source
+    whose own timecode is drop-frame, so the label is the one the media itself shows."""
+    nominal = int(round(float(rate)))
+    if not _drop_frame(drop, rate):
+        return _tc(frames, nominal)
+    d = nominal // 15
+    per_10, per_min = nominal * 600 - d * 9, nominal * 60 - d
+    tens, rem = divmod(frames, per_10)
+    frames += d * 9 * tens + (d * ((rem - d) // per_min) if rem > d else 0)
+    return _tc(frames, nominal)[:-3] + ";" + _tc(frames, nominal)[-2:]
+
+
 def build(proj: Dict[str, Any], probes: Dict[str, Dict[str, Any]], rel) -> Dict[str, Any]:
     """The editor-neutral timeline: every time in frames at `rate`.
 
@@ -172,6 +215,14 @@ def build(proj: Dict[str, Any], probes: Dict[str, Dict[str, Any]], rel) -> Dict[
         if start < 0:
             raise TimelineError(f"clips[{i}].in must not be negative, got {c['in']!r}")
         end = _seconds(c["out"], f"clips[{i}].out", clip_fps) if c.get("out") is not None else dur
+        # as cut.py reads them (#414): an in at or past the media's end is refused, an out past it
+        # is the media's end -- the render clamps it there, so the timeline does too, and says so
+        if dur > 0 and start >= dur:
+            raise TimelineError(f"clips[{i}].in ({start:g}s) is at or past the end of {os.path.basename(src)} ({dur:.3f}s)")
+        if dur > 0 and end > dur + 1e-6:
+            notes.append(f"clips[{i}].out ({end:g}s) is past the end of {os.path.basename(src)} ({dur:.3f}s): "
+                         "the clip ends at the media's end, as the render cuts it")
+            end = dur
         if end <= start:
             raise TimelineError(f"clip {i}: out ({end:g}) is not after in ({start:g})")
         speed = _number(c.get("speed") or 1.0, f"clips[{i}].speed")
@@ -182,8 +233,17 @@ def build(proj: Dict[str, Any], probes: Dict[str, Dict[str, Any]], rel) -> Dict[
         if reframe:
             reframed.append(os.path.basename(src))
         src_in, src_out = fr(start), fr(end)
+        # the source's own clock (#414): its frame rate, and its start timecode as a frame count at
+        # that rate. EDL source timecodes are counted at it (a 25 fps clip in a 29.97 sequence has
+        # no frame :29); FCPXML and OTIO start the media at it, so a conform finds the frames.
+        clip_rate = exact_rate(float(clip_fps)) if clip_fps else rate
+        tc = meta.get("timecode") or {}
+        tc_start = start_tc_frames(tc, clip_rate)
         clips.append({"index": i, "src": os.path.abspath(src), "name": os.path.basename(src),
                       "src_in": src_in, "src_out": src_out, "speed": speed,
+                      "in_seconds": Fraction(start).limit_denominator(1000000), "rate": clip_rate,
+                      "tc_start": tc_start, "tc_seconds": Fraction(tc_start) / clip_rate,
+                      "drop_frame": _drop_frame(tc.get("drop_frame"), clip_rate),
                       "length": int(round((src_out - src_in) / speed)),
                       "media_frames": fr(dur), "has_video": bool(meta.get("video")),
                       "has_audio": bool(meta.get("audio")),
@@ -219,12 +279,24 @@ def build(proj: Dict[str, Any], probes: Dict[str, Dict[str, Any]], rel) -> Dict[
     markers: List[Dict[str, Any]] = []
     chapters = proj.get("chapters")
     if isinstance(chapters, list):
+        total_seconds = Fraction(total) / rate
+        previous: Optional[float] = None
         for j, ch in enumerate(chapters):
             # read as render.py's chapters stage reads it (metadata.py): a chapter list carries
-            # no fps, so hh:mm:ss:ff needs its @fps there and here alike
-            at = fr(_seconds(ch.get("at", 0), f"chapters[{j}].at", None))
-            if 0 <= at < total:
-                markers.append({"at": at, "title": str(ch.get("title") or "")})
+            # no fps, so hh:mm:ss:ff needs its @fps there and here alike. What metadata.py refuses
+            # is refused here too, never dropped (#414): a chapter at or past the end, or one that
+            # does not come after the one before it.
+            at_s = _seconds(ch.get("at", 0), f"chapters[{j}].at", None)
+            if at_s < 0:
+                raise TimelineError(f"chapters[{j}].at must not be negative, got {ch.get('at')!r}")
+            if previous is not None and at_s <= previous:
+                raise TimelineError(f"chapters[{j}]: the chapter at {at_s:g}s does not come after the previous one "
+                                    f"at {previous:g}s (metadata.py refuses it too)")
+            if at_s >= total_seconds:
+                raise TimelineError(f"chapters[{j}]: the chapter at {at_s:g}s starts at or after the end of the "
+                                    f"timeline ({float(total_seconds):.3f}s); metadata.py refuses it too")
+            previous = at_s
+            markers.append({"at": min(fr(at_s), total - 1), "title": str(ch.get("title") or "")})
     elif chapters:
         notes.append("chapters given as a file are not exported as markers; write them inline as [{at, title}]")
 
@@ -283,27 +355,38 @@ def to_edl(tl: Dict[str, Any]) -> str:
     ends = starts[1:] + [tl["total"]]
     lines = [f"TITLE: {tl['name']}", "FCM: NON-DROP FRAME", ""]
     n = 0
-    prev_src_end = 0
+    prev_src_end = ""
+    rate = tl["rate"]
+
+    def src_tc(c: Dict[str, Any], seq_frames: int) -> str:
+        """The source timecode `seq_frames` (sequence frames of source media) after the clip's in
+        point: counted at the clip's own rate from its own start timecode (#414)."""
+        own = c.get("rate") or rate
+        seconds = c.get("in_seconds", Fraction(c["src_in"]) / rate) + Fraction(seq_frames) / rate
+        return _tc_label(int(round(seconds * own)) + c.get("tc_start", 0), own, c.get("drop_frame", False))
+
     for i, c in enumerate(clips):
         n += 1
         chan = "B" if c["has_audio"] and c["has_video"] else ("V" if c["has_video"] else "A")
         rec_in, rec_out = hour + starts[i], hour + ends[i]
-        s_in = c["src_in"]
-        s_out = s_in + int(round((ends[i] - starts[i]) * c["speed"]))
+        s_in = src_tc(c, 0)
+        s_out = src_tc(c, int(round((ends[i] - starts[i]) * c["speed"])))
         if i > 0 and d:
-            lines.append(f"{n:03d}  AX       {chan:<5} C        {_tc(prev_src_end, fps_int)} {_tc(prev_src_end, fps_int)} "
+            lines.append(f"{n:03d}  AX       {chan:<5} C        {prev_src_end} {prev_src_end} "
                          f"{_tc(rec_in, fps_int)} {_tc(rec_in, fps_int)}")
-            lines.append(f"{n:03d}  AX       {chan:<5} D    {d:03d} {_tc(s_in, fps_int)} {_tc(s_out, fps_int)} "
+            lines.append(f"{n:03d}  AX       {chan:<5} D    {d:03d} {s_in} {s_out} "
                          f"{_tc(rec_in, fps_int)} {_tc(rec_out, fps_int)}")
             lines.append(f"* FROM CLIP NAME: {clips[i - 1]['name']}")
             lines.append(f"* TO CLIP NAME: {c['name']}")
         else:
-            lines.append(f"{n:03d}  AX       {chan:<5} C        {_tc(s_in, fps_int)} {_tc(s_out, fps_int)} "
+            lines.append(f"{n:03d}  AX       {chan:<5} C        {s_in} {s_out} "
                          f"{_tc(rec_in, fps_int)} {_tc(rec_out, fps_int)}")
             lines.append(f"* FROM CLIP NAME: {c['name']}")
         lines.append(f"* SOURCE FILE: {c['src']}")
         if abs(c["speed"] - 1.0) > 1e-6:
-            lines.append(f"M2   AX       {fps_int * c['speed']:05.1f}                {_tc(s_in, fps_int)}")
+            # the speed in source frames per second, at the rate the source labels are counted in
+            own_fps = int(round(float(c.get("rate") or rate)))
+            lines.append(f"M2   AX       {own_fps * c['speed']:05.1f}                {s_in}")
         lines.append("")
         prev_src_end = s_out
     if tl["music"]:
@@ -326,6 +409,11 @@ def _t(frames: int, rate: Fraction) -> str:
     return f"{value.numerator}s" if value.denominator == 1 else f"{value.numerator}/{value.denominator}s"
 
 
+def _ts(value: Fraction) -> str:
+    """A rational FCPXML time from seconds."""
+    return f"{value.numerator}s" if value.denominator == 1 else f"{value.numerator}/{value.denominator}s"
+
+
 def _url(path: str) -> str:
     # pathlib builds the percent-encoded file:// URL itself (and the drive-letter form on
     # Windows): no network-library import in scripts/, not even for quoting (see the no-fetch test)
@@ -361,12 +449,14 @@ def to_fcpxml(tl: Dict[str, Any]) -> str:
             return seq_fmt
         return fmt(c["picture"][0], c["picture"][1], _t(1, exact_rate(float(c["fps"]))) if c["fps"] else fd)
 
-    def asset(path: str, name: str, frames: int, has_video: bool, has_audio: bool, format_id: str = "") -> str:
+    def asset(path: str, name: str, frames: int, has_video: bool, has_audio: bool, format_id: str = "",
+              start: Fraction = Fraction(0)) -> str:
         if path in ids:
             return ids[path]
         rid = f"r{len(ids) + 1}"
         ids[path] = rid
-        res.append(f'    <asset id="{rid}" name="{q(name)}" start="0s" duration="{_t(frames, rate)}" '
+        # the media starts at its own start timecode (#414): a clip's start is counted from there
+        res.append(f'    <asset id="{rid}" name="{q(name)}" start="{_ts(start)}" duration="{_t(frames, rate)}" '
                    f'hasVideo="{int(has_video)}" hasAudio="{int(has_audio)}"'
                    + (f' format="{format_id}"' if has_video else "") + ' audioSources="1" audioChannels="2">\n'
                    f'      <media-rep kind="original-media" src="{q(_url(path))}"/>\n    </asset>')
@@ -377,7 +467,8 @@ def to_fcpxml(tl: Dict[str, Any]) -> str:
     markers = list(tl["markers"])
     for i, c in enumerate(tl["clips"]):
         cid = clip_fmt(c)
-        rid = asset(c["src"], c["name"], c["media_frames"], c["has_video"], c["has_audio"], cid)
+        base = c.get("tc_seconds", Fraction(0))
+        rid = asset(c["src"], c["name"], c["media_frames"], c["has_video"], c["has_audio"], cid, base)
         if i > 0 and d:
             spine.append(f'        <transition name="Cross Dissolve" offset="{_t(c["record_in"] - c["trim_head"], rate)}" '
                          f'duration="{_t(d, rate)}"/>')
@@ -386,14 +477,15 @@ def to_fcpxml(tl: Dict[str, Any]) -> str:
         if abs(c["speed"] - 1.0) > 1e-6:
             # timeMap maps clip-local time to source time; two linear points give a constant speed
             inner.append("          <timeMap>")
-            inner.append(f'            <timept time="0s" value="{_t(src_start, rate)}" interp="linear"/>')
+            inner.append(f'            <timept time="0s" value="{_ts(base + Fraction(src_start) / rate)}" interp="linear"/>')
             inner.append(f'            <timept time="{_t(c["visible"], rate)}" '
-                         f'value="{_t(src_start + int(round(c["visible"] * c["speed"])), rate)}" interp="linear"/>')
+                         f'value="{_ts(base + Fraction(src_start + int(round(c["visible"] * c["speed"]))) / rate)}" interp="linear"/>')
             inner.append("          </timeMap>")
             start_attr = "0s"
         else:
-            start_attr = _t(src_start, rate)
-        local0 = src_start if abs(c["speed"] - 1.0) <= 1e-6 else 0
+            start_attr = _ts(base + Fraction(src_start) / rate)
+        # the clip's local time: the source's (from its start timecode), or 0 under a timeMap
+        local0 = base + Fraction(src_start) / rate if abs(c["speed"] - 1.0) <= 1e-6 else Fraction(0)
         # the FCPXML 1.10 DTD's order inside an asset-clip: timeMap, then the adjust-* elements
         # (adjust-conform), then anchored items (the music bed), then markers. Anything out of
         # that order does not validate, and Final Cut validates what it imports against that DTD.
@@ -404,13 +496,14 @@ def to_fcpxml(tl: Dict[str, Any]) -> str:
         if i == 0 and tl["music"]:
             m = tl["music"]
             mid = asset(m["src"], m["name"], m["media_frames"], False, True)
-            inner.append(f'          <asset-clip ref="{mid}" lane="-1" offset="{_t(local0, rate)}" name="{q(m["name"])}" '
+            inner.append(f'          <asset-clip ref="{mid}" lane="-1" offset="{_ts(local0)}" name="{q(m["name"])}" '
                          f'start="0s" duration="{_t(m["length"], rate)}" audioRole="music"/>')
         for mk in [m for m in markers if c["record_in"] <= m["at"] < c["record_in"] + c["visible"]]:
-            inner.append(f'          <chapter-marker start="{_t(local0 + mk["at"] - c["record_in"], rate)}" '
+            inner.append(f'          <chapter-marker start="{_ts(local0 + Fraction(mk["at"] - c["record_in"]) / rate)}" '
                          f'duration="{fd}" value="{q(mk["title"])}"/>')
         head = (f'        <asset-clip ref="{rid}" offset="{_t(c["record_in"], rate)}" name="{q(c["name"])}" '
-                f'start="{start_attr}" duration="{_t(c["visible"], rate)}" format="{cid}" tcFormat="NDF"')
+                f'start="{start_attr}" duration="{_t(c["visible"], rate)}" format="{cid}" '
+                f'tcFormat="{"DF" if c.get("drop_frame") else "NDF"}"')
         spine.append(head + (">\n" + "\n".join(inner) + "\n        </asset-clip>" if inner else "/>"))
     out = ['<?xml version="1.0" encoding="UTF-8"?>', "<!DOCTYPE fcpxml>", '<fcpxml version="1.10">',
            "  <resources>", *res, "  </resources>", "  <library>", f'    <event name="{q(tl["name"])}">',
@@ -444,15 +537,17 @@ def to_otio(tl: Dict[str, Any]) -> str:
                           # OTIO: in_offset is the part before the cut, out_offset the part after
                           "in_offset": _rt(c["trim_head"], rate), "out_offset": _rt(tl["clips"][i - 1]["trim_tail"], rate)})
         src_start = c["src_in"] + int(round(c["trim_head"] * c["speed"]))
+        # the media's range starts at its start timecode (#414), in timeline frames
+        base = c.get("tc_seconds", Fraction(0)) * rate
         clip = {"OTIO_SCHEMA": "Clip.2", "name": c["name"], "metadata": {}, "enabled": True,
                 # OTIO's own convention: source_range starts at the media's in point and lasts the
                 # clip's length on the timeline; a LinearTimeWarp says how fast the media runs
                 # through it (core OTIO does not rescale durations by effects).
-                "source_range": _range(src_start, c["visible"], rate),
+                "source_range": _range(base + src_start, c["visible"], rate),
                 "effects": [], "markers": [],
                 "media_references": {"DEFAULT_MEDIA": {
                     "OTIO_SCHEMA": "ExternalReference.1", "name": c["name"], "metadata": {},
-                    "target_url": _url(c["src"]), "available_range": _range(0, c["media_frames"], rate),
+                    "target_url": _url(c["src"]), "available_range": _range(base, c["media_frames"], rate),
                     "available_image_bounds": None}},
                 "active_media_reference_key": "DEFAULT_MEDIA"}
         if abs(c["speed"] - 1.0) > 1e-6:

package/scripts/_contract.py

@@ -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"):
@@ -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/caption.py

@@ -54,6 +54,7 @@ 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)
@@ -145,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:
@@ -887,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"):
@@ -1130,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
@@ -1380,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:
@@ -1392,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"
@@ -1424,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)] + \
@@ -1435,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] = []
@@ -1453,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
@@ -1510,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 "
@@ -1521,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 {}),
@@ -1587,7 +1670,8 @@ 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 = display_size(meta["video"])

package/scripts/export.py

@@ -42,6 +42,7 @@ from _common import STATE, run_analysis, add_common, apply_common, bt709_label_f
 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.runner import subtitle_codec_for
 from check import SPECS as PLATFORMS, measure_loudness
 from _platforms import ALIASES as _ALIASES, PLATFORMS as PLATFORM_TABLE, TP_TOLERANCE_DB, resolve as resolve_platform
 # Frame and duration limit come from the one platform table (scripts/_platforms.py) rather than
@@ -142,19 +143,10 @@ def _loudness_unmeasured(extra: Dict[str, object], notes: List[str], platform: s
 
 # Text subtitle codecs ffmpeg can convert to the container's own text track: mov_text is the one
 # text track MP4/MOV hold, Matroska holds SubRip/ASS/WebVTT as they are but not mov_text.
-_TEXT_SUBTITLES = frozenset({"mov_text", "subrip", "srt", "ass", "ssa", "webvtt", "text"})
-_MP4_FAMILY = frozenset({"mp4", "m4v", "mov"})
-
-
-def _subtitle_codec(codec: str, out_ext: str) -> str:
-    """The -c:s for one source subtitle stream: copy when the output container holds it as it is,
-    else the container's own text format (a bitmap track is tried as a copy; a container that
-    refuses it is the fallback below)."""
-    if out_ext in _MP4_FAMILY and codec in _TEXT_SUBTITLES and codec != "mov_text":
-        return "mov_text"
-    if out_ext == "mkv" and codec == "mov_text":
-        return "srt"
-    return "copy"
+# the -c:s for one source subtitle stream (#380), shared with caption.py --mode mux (#414): copy
+# when the output container holds it as it is, else the container's own text format (a bitmap
+# track is tried as a copy; a container that refuses it is the fallback below)
+_subtitle_codec = subtitle_codec_for
 
 
 def _data_streams(path: str) -> List[Dict[str, object]]:

package/scripts/silence.py

@@ -83,10 +83,29 @@ def speech_aware_silences(path: str, threshold: float, min_silence: float) -> "T
     return boundaries, breaths
 
 
+def inside_margin(silences: List[Tuple[float, float]], duration: float, margin: float) -> List[Tuple[float, float]]:
+    """Each silence with --margin kept on both sides: the stretch actually removed. A silence too
+    short to hold two margins removes nothing (it is dropped, never turned inside out).
+
+    The margin is applied to the silences alone, before they are merged with filler spans (#414):
+    a filler word's span is the word itself plus --filler-pad, and taking a 0.2 s margin off each
+    side of it turned every word narrower than 2 x --margin inside out -- kept, and still counted
+    as removed."""
+    out: List[Tuple[float, float]] = []
+    for s, e in silences:
+        a = s + margin
+        b = duration if e == float("inf") else min(duration, e - margin)
+        if b > a:
+            out.append((a, b))
+    return out
+
+
 def keep_ranges(silences: List[Tuple[float, float]], duration: float, margin: float, min_keep: float) -> List[Tuple[float, float]]:
     keeps: List[Tuple[float, float]] = []
     cursor = 0.0
     for s, e in sorted(silences):
+        if e != float("inf") and e - margin <= s + margin:
+            continue  # narrower than two margins: nothing of it is removed (#414)
         s_adj = max(cursor, s + margin)
         if s_adj - cursor >= min_keep:
             keeps.append((cursor, s_adj))
@@ -503,6 +522,9 @@ def main() -> int:
     media_out = None if (args.list or args.filler_list) else (args.output or default_output(args.input, "tight"))
     guard_sidecar(args.edl, args.input, args.words, args.filler_words, siblings=(media_out,))
 
+    if not math.isfinite(args.margin) or args.margin < 0:
+        # nan made inside_margin() drop every silence and re-encode the whole file unchanged
+        die(f"--margin must be a finite number of seconds, 0 or more (got {args.margin:g})", kind="input")
     if args.filler_pad < 0:
         die("--filler-pad cannot be negative: a negative pad turns each word's span inside out "
             "(end before start) and the span is then silently dropped, so nothing is removed",
@@ -525,8 +547,10 @@ def main() -> int:
     filler_info, filler_ranges = resolve_filler(args, meta) if args.filler else (None, [])
     # One sorted, merged removal list through the graph the tool already has: filler removal IS
     # time-range removal, so it reuses keep_ranges() and the same select chain.
-    removals = merge_spans(list(silences) + list(filler_ranges))
-    keeps = keep_ranges(removals, duration, args.margin, args.min_keep)
+    # --margin is kept around the silences only (inside_margin), not around filler spans, whose
+    # own trim is --filler-pad (#414); the merged list then goes through with no further margin.
+    removals = merge_spans(inside_margin(silences, duration, args.margin) + list(filler_ranges))
+    keeps = keep_ranges(removals, duration, 0.0, args.min_keep)
     # what the render holds (on a picture, each bound on its nearest frame): the report, the EDL
     # and the time map all describe these, so a re-cut or a sum of `keep` is the rendered edit
     video_out = bool(meta.get("video")) and not (media_out and is_audio_output(media_out))
@@ -540,7 +564,7 @@ def main() -> int:
     # the silences alone; everything removed is `removed_seconds_total`.
     silence_only = removed
     if args.filler:
-        silence_keeps = keep_ranges(merge_spans(list(silences)), duration, args.margin, args.min_keep)
+        silence_keeps = keep_ranges(merge_spans(inside_margin(silences, duration, args.margin)), duration, 0.0, args.min_keep)
         silence_only = max(0.0, duration - sum(e - s for s, e in rendered_ranges(silence_keeps, meta, duration, video_out)))
     kinds = silence_kinds(args.input, silences, duration, args.threshold)
     summary = {
@@ -649,8 +673,9 @@ def main() -> int:
         return 0
     if not keeps or not held:
         die("nothing would be kept; raise --threshold (e.g. -45) or check the audio")
-    if not silences or removed < 0.05:
-        info("no removable silence found; output would equal the input")
+    if removed < 0.05:
+        # what the render removes, filler spans included: --filler alone has no silences at all
+        info(f"no removable {'filler' if filler_only else 'silence or filler' if args.filler else 'silence'} found; output would equal the input")
 
     output = args.output or default_output(args.input, "tight")
     # the join of more than 32 ranges concats a list of chunks, so its last command never names the