ffmpeg-skill 3.1.6 → 3.1.8

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.8`) | 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.8", "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"},
@@ -204,6 +204,11 @@ One entry per tool under `tools`, sorted by id. Tool ids are stable:
 | `execution` (writes a new artifact) | cut, fit, caption, overlay, graphics, multicam, audio, join, color, export, render, batch |
 | `verification` (checks or shows an artifact) | check, look, verify, report |
 
+`batch` writes one artifact per input only when a recipe step names `{out}` (or the recipe is a
+render project): a recipe in which no step does (a QC pass of `check.py`/`probe.py`) writes none,
+and each `results` row carries `written: false` beside its usual `output` path, which stays a
+string (#415).
+
 ### Verification policy
 
 The workflow in `SKILL.md` is "probe first, verify last". The contract states it per tool:
@@ -786,8 +791,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 +872,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:
 
 ```
@@ -879,6 +887,14 @@ caller never parses the prose:
 A tool that runs another (`render.py` stages and plans) forwards the child's `reason` and
 `details` in its own `error`. Both are absent on a failure that is not a refusal, like `hint`.
 
+A `timeout` or `interrupted` failure exits 124, or 130/143, whether the tool or a child tool it ran
+was stopped (`export.py --normalize`'s loudness pass, `render.py`'s stages, check, executed plan and
+pack destinations, `waveform.py`'s title and captions pass the child's code on). Its message ends "nothing was written" only when
+that is so: once a tool has written its deliverable and runs a further step on it
+(`export.py --normalize`, `render.py`'s chapters and check stages), the message names the file,
+says it is kept without the step that was stopped, and the document carries it as `output`
+(3.1.6, #415).
+
 **Diagnostics.** What a run decided on its own -- a warning, a fallback it took, a step it
 skipped -- is recorded as it happens (a stderr line too) and lands in the document as
 `diagnostics: {warnings, fallbacks, skipped}`, each entry `{code, message, ...facts}`; it is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "3.1.6",
+  "version": "3.1.8",
   "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
@@ -1235,10 +1240,18 @@ above the cap is clamped with a note, not refused, and both `jobs` and
   earlier has no such record and is processed again once, `entry_unverifiable`).
   A `.ffskill_cache.json` that does not parse is started empty with a
   `batch_cache_reset` warning and a line in `output_dir/.ffskill-audit.jsonl`.
-- With `--jobs > 1` each item gets its own work subdirectory
-  `<workdir>/<index>-<stem>/`, because step file names are stem-derived and two
-  sources sharing a stem would otherwise write over each other. `--jobs 1` (the
-  default) keeps the flat layout and is 1.16's path exactly.
+- Each item's intermediates go in a new directory of its own under the work
+  directory (`<workdir>/<index>-<random>/`), removed with them when the item
+  ends, whatever the outcome (3.1.6, #415): step file names are stem-derived, so
+  `clip.mp4` and `clip.mov` sharing a directory, or a rerun meeting an earlier
+  run's files, were refused as someone else's. A step that names no `{out}`
+  (`check.py`) passes its input on; when the last step writes nothing, the last
+  file written is delivered as the item's output, under its own extension (`.mp4`
+  for a video source) unless the recipe sets `ext`. A recipe in which no step names
+  `{out}` (a QC pass: `check.py`/`probe.py` on every file) writes nothing: each
+  row has `written: false` (`output` keeps its path string), a note says so, and `ok` follows the steps' exit codes.
+  Final names that differ only in case are a
+  collision (they are one file on macOS and Windows).
 - `--watch` composes: each pass is parallel, passes are sequential.
 
 ### caption.py --transcribe — optional local speech-to-text

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/decision.py

@@ -114,9 +114,21 @@ def frame_size(ratio: Optional[Fraction], width: Optional[int], height: Optional
 SVT_PRESET = {"ultrafast": 12, "superfast": 11, "veryfast": 10, "faster": 9, "fast": 8, "medium": 6, "slow": 4, "slower": 3, "veryslow": 2, "placebo": 1}
 
 
+# Source containers the tools' own encoders (x264/x265/SVT-AV1 and AAC) cannot be written into: WebM
+# takes only VP8/VP9/AV1 and Vorbis/Opus. A default output name keeps the source's extension
+# except for these, whose default is .mp4 (#415): the dry run planned `clip_loudnorm.webm` and the
+# real run then failed in the muxer.
+NO_DEFAULT_ENCODE_EXT = {".webm"}
+
+
 def default_output(input_path: str, suffix: str, ext: Optional[str] = None) -> str:
     p = Path(input_path)
-    new_ext = ext if ext else p.suffix.lstrip(".") or "mp4"
+    if ext:
+        new_ext = ext
+    elif p.suffix.lower() in NO_DEFAULT_ENCODE_EXT:
+        new_ext = "mp4"
+    else:
+        new_ext = p.suffix.lstrip(".") or "mp4"
     return str(p.with_name(f"{p.stem}_{suffix}.{new_ext}"))
 
 

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}