ffmpeg-skill 2.24.1 → 3.0.0

package/references/scripts.md

@@ -127,14 +127,15 @@ own clock, `null` when unknown). `--compact` gives one line per file.
 
 ### cut.py — cut / join segments
 ```
-cut.py INPUT [--start T] [--end T | --duration T] [--segments A-B,C-D,... | --remove A-B,C-D,...] [--accurate] [--declick-ms 20 | --no-declick] [--edit-list] [--keep-hevc] [--vfr-guard average|sampled|off] [-o OUT]
+cut.py INPUT [--start T] [--end T | --duration T] [--segments A-B,C-D,... | --remove A-B,C-D,...] [--accurate] [--declick-ms 20 | --no-declick] [--edit-list | --no-edit-list] [--keep-hevc | --no-keep-hevc] [--vfr-guard sampled|average|off] [-o OUT]
 cut.py INPUT --start T --end T --snap beats [--snap-tolerance 0.12] [--snap-source FILE] [--min-confidence 0.5]
 ```
 Times accept `12.5`, `1:30`, `00:01:30.250`. Default is `-c copy` (snaps to
 keyframes, instant, lossless); if the snapped result deviates more than
 `--tolerance` (0.5 s) from the request, that segment is re-encoded automatically
 (CRF 18: x264, or x265 Main10 with the source's own tags for an HDR or BT.2020 source;
-`--keep-hevc` re-encodes an SDR HEVC source (not BT.2020: that keeps its Main10 line and colour tags) as x265 8-bit BT.709, on VideoToolbox under `--hw`;
+an SDR HEVC source (not BT.2020: that keeps its Main10 line and colour tags) stays HEVC as x265 8-bit BT.709, on VideoToolbox under `--hw`,
+by default since 3.0.0 (`--keep-hevc`; `--no-keep-hevc` uses x264 as 2.x did);
 `--codec` overrides all of them). `--accurate` always re-encodes; `--tolerance -1` never does for a keyframe snap
 (a `--segments` join of open-GOP video, one whose later B-frame `.mp4`/`.mov` segment starts
 between keyframes, or one that fails its check, still re-cuts).
@@ -142,16 +143,16 @@ Multiple segments are concatenated in the order given. `--remove A-B,...` (2.24)
 the result was "lossless stream copy" or "re-encoded"; when the snap forced a
 re-encode, the result's `lossless_alternative` names the nearest keyframe
 `--start` that would stream-copy instead, so the trade can be offered.
-A single `.mp4`/`.mov` stream copy shifts its timestamps to zero
-(`-avoid_negative_ts make_zero`), so the picture starts at the keyframe.
-`--edit-list` keeps its MP4 edit list instead, so the picture starts at
-`--start`: `edit_list` and `stored_preroll_seconds` say so, `notes` warns that a
+A single `.mp4`/`.mov` stream copy keeps its MP4 edit list by default since
+3.0.0 (`--edit-list`), so the picture starts at `--start`; `--no-edit-list`
+shifts its timestamps to zero instead (`-avoid_negative_ts make_zero`, 2.x's
+default), so the picture starts at the keyframe. With the edit list: `edit_list` and `stored_preroll_seconds` say so, `notes` warns that a
 player which ignores edit lists shows the pre-roll, and the copy's length is
 judged by its video (a copy that starts where asked but ends past `--tolerance`
 re-encodes without offering another `--start`). `av_start_skew_seconds` is
 audio start minus video start; a stream copy gets a note when it is more than
 max(2 frames, 0.1 s) away from the source's own offset where the picture starts
-(the keyframe the copy began from; `--start` under `--edit-list`). It is
+(the keyframe the copy began from; `--start` with an edit list). It is
 reported, not repaired. `-ss`/`-t` are passed to the microsecond; `--accurate`
 seeks a second early and trims on the output side, so frames just before a
 keyframe are kept. An `--accurate` re-encode of a video does not pass
@@ -163,26 +164,28 @@ the next source frame and may keep up to one frame of timestamp. A `.mp4`/`.mov`
 edit list hides the priming. A source whose audio starts after its picture keeps
 that offset. An audio-only `--accurate` cut
 still uses `make_zero`; that priming is what `precision: codec_frame` counts
-in the length. `keyframe_snapped` is true for every stream copy (`precision`
-`packet`); `start_snapped` is measured: true when a copied picture starts more
+in the length. Since 3.0.0 `keyframe_snapped` equals `start_snapped` (2.x: true
+for every stream copy, `precision` `packet`); `start_snapped` is measured: true when a copied picture starts more
 than a frame from `--start`, or when its start could not be measured (an unknown start is
 never claimed exact); `null` under `--dry-run`.
 `reencode_reason` lists every cause of a re-encode (`requested`, `codec`, `vfr`,
 `vfr_inconclusive`, `pcm_container`, `copy_failed`, `stream_lost`, `tolerance`, `concat_fallback`);
-`--segments` adds `segment_precision`, and `least_exact_precision` is the least exact one.
+`--segments` adds `segment_precision`; `precision` and `least_exact_precision` are the least exact one
+(since 3.0.0; 2.x's `precision` was the whole run's, `packet` only when nothing re-encoded).
 A `--segments` video copy join adds `join_check` (`packets`, `expected_packets`,
 `max_step_seconds`, `audio_offset_ms` per part, `audio_parts_checked`, `ok`: the
 written file measured against the source) and `segment_end_snap_seconds` (where
 each part's end moved to its keyframe).
 
-**VFR guard (`--vfr-guard`).** `average` (default): a source whose nominal and
-average frame rates differ (`variable_frame_rate_suspected`) re-encodes as
-`--accurate` (reason `vfr`), and `cut.py` then samples its packet timestamps (up
-to five 6 s windows; no decoding) into `vfr_check` (`measured`: `sampled_cfr`,
-`vfr` or `inconclusive`, plus `guard`); a `sampled_cfr` there adds a note naming
-`--vfr-guard sampled`. `sampled` samples before every copy and re-encodes only on
-`vfr` / `inconclusive` (reasons `vfr` / `vfr_inconclusive`), so a phone clip at
-29.98 against a nominal 30 copies; `off` samples and keeps the copy with a note.
+**VFR guard (`--vfr-guard`).** `sampled` (default since 3.0.0): `cut.py` samples
+the packet timestamps before every copy (up to five 6 s windows; no decoding) into
+`vfr_check` (`measured`: `sampled_cfr`, `vfr` or `inconclusive`, plus `guard`) and
+re-encodes only on `vfr` / `inconclusive` (reasons `vfr` / `vfr_inconclusive`), so a
+phone clip at 29.98 against a nominal 30 copies. `average` (2.x's default): a source
+whose nominal and average frame rates differ (`variable_frame_rate_suspected`)
+re-encodes as `--accurate` (reason `vfr`), and is then sampled into `vfr_check`; a
+`sampled_cfr` there adds a note naming `--vfr-guard sampled`. `off` samples and
+keeps the copy with a note.
 Irregular timing between the windows is not seen; `--accurate` is always available.
 
 A source with no B-frames (iPhone "Most Compatible" H.264) cuts its parts as

package/scripts/_common/drawtext.py

@@ -10,7 +10,7 @@ import shutil
 import subprocess
 from typing import Dict, List, Optional
 from _common.decision import escape_filter_path
-from _common.runner import STATE, _DRAWTEXT_PENDING, _drawtext_tmpdir, ffmpeg_exe, ffmpeg_release, ffmpeg_version, require_tool
+from _common.runner import STATE, _DRAWTEXT_PENDING, _drawtext_tmpdir, ffmpeg_exe, ffmpeg_release, require_tool
 
 
 def _on_windows() -> bool:
@@ -79,12 +79,9 @@ def drawtext_fontfile(path: str) -> str:
 
 
 def drawtext_boxborderw(vertical: int, horizontal: int) -> str:
-    """drawtext's per-side `boxborderw=top|right|bottom|left` (and the two-value `v|h` form)
-    arrived in FFmpeg 6.1; 5.x and 6.0 reject the `|` with "Error setting option boxborderw"
-    (found by the FFmpeg 5.1.1 CI job, #146). Older builds get the larger single value."""
-    if ffmpeg_version() >= (6, 1):
-        return f"{vertical}|{horizontal}"
-    return str(max(vertical, horizontal))
+    """drawtext's per-side `boxborderw` in its two-value `v|h` form (FFmpeg 6.1+, the floor since
+    3.0.0; 2.x gave 5.x and 6.0 the larger single value, which they needed)."""
+    return f"{vertical}|{horizontal}"
 
 
 # --------------------------------------------------------------------------- shaping (1.15)
@@ -184,9 +181,8 @@ def is_multiline(text: "Optional[str]") -> bool:
 
 def drawtext_center_align() -> str:
     """`:text_align=C` for a centred drawtext, so each line of a multi-line label is centred on
-    its own. The option arrived in FFmpeg 6.1 (5.x and 6.0 reject it); there the block is still
-    centred as a whole by its x expression, with its lines left-aligned inside it."""
-    return ":text_align=C" if ffmpeg_version() >= (6, 1) else ""
+    its own (FFmpeg 6.1+, the floor since 3.0.0)."""
+    return ":text_align=C"
 
 
 def drawtext_clean(text: "Optional[str]") -> str:

package/scripts/_common/probe.py

@@ -135,6 +135,34 @@ def verify_output(path: str) -> Dict[str, Any]:
     return meta
 
 
+_TIMECODE = re.compile(r"^(\d{2}):([0-5]\d):([0-5]\d)([:;.])(\d{2,3})$")
+
+
+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 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."""
+    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"))
+    for entry, source in candidates:
+        value = _tag(entry, "timecode")
+        m = _TIMECODE.match(value.strip()) if isinstance(value, str) else None
+        if m:
+            return {"value": value.strip(), "drop_frame": m.group(4) in ";.", "source": source}
+    return {"value": None, "drop_frame": None, "source": None}
+
+
 def probe(path: str, role: str = "input") -> Dict[str, Any]:
     """Return a compact, script-friendly description of a media file.
 
@@ -230,6 +258,8 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
             "title": (ch.get("tags") or {}).get("title"),
         } for n, ch in enumerate(raw.get("chapters") or [])],
         "tags": {k.lower(): v for k, v in (fmt.get("tags") or {}).items() if k.lower() in ("title", "artist", "album", "comment", "date", "genre")},
+        # the source's start timecode (a camera's 10:00:00:00), for an edit list or an NLE relink
+        "timecode": start_timecode(streams, fmt, video),
         # every subtitle stream in file order: index n here is `-map 0:s:n`
         "subtitle_stream_details": [{
             "index": n,
@@ -434,7 +464,7 @@ def measure_frame_timing(path: str, duration: Optional[float], start: float = 0.
     time_base = None
     for i, t in enumerate(timing_window_starts(duration or 0.0, start)):
         proc = run([ffprobe, "-v", "error", "-select_streams", "V:0", "-show_packets",
-                    "-show_entries", "packet=pts,dts:stream=time_base", "-of", "json",
+                    "-show_entries", "packet=pts,dts,flags:stream=time_base", "-of", "json",
                     "-read_intervals", f"{t if i else ''}%{t + TIMING_WINDOW_SECONDS:.3f}", path], quiet=True, check=False)
         try:
             doc = json.loads(proc.stdout) if proc.returncode == 0 else None
@@ -444,8 +474,16 @@ def measure_frame_timing(path: str, duration: Optional[float], start: float = 0.
             return {"measured": "inconclusive", "windows": len(windows), "deltas": 0}
         time_base = time_base or ((doc.get("streams") or [{}])[0] or {}).get("time_base")
         tick = float(_fraction(str(time_base)) or 0) if time_base else 0.0
-        windows.append([p for p in complete_pts(doc.get("packets") or [])
-                        if isinstance(p, int) and p * tick >= t - 1e-6])
+        packets = doc.get("packets") or []
+        floor = t - 1e-6
+        if i:
+            # a seek into MPEG-TS lands mid-GOP, not on a keyframe: a frame stored before the
+            # landing point is missing, which read as a dropped frame (a constant TS measured
+            # `vfr`). Judge a seeked window from its first keyframe's presentation on.
+            key = next((p.get("pts") for p in packets if "K" in str(p.get("flags", "")) and isinstance(p.get("pts"), int)), None)
+            if key is not None:
+                floor = max(floor, key * tick - 1e-6)
+        windows.append([p for p in complete_pts(packets) if isinstance(p, int) and p * tick >= floor])
     return classify_frame_timing(windows, time_base)
 
 

package/scripts/_common/runner.py

@@ -105,6 +105,7 @@ ERROR_RETRYABLE = False
 
 
 _FFMPEG_VERSION: "Optional[Tuple[int, int]]" = None
+_FFMPEG_VERSION_IS_RELEASE = False   # ffmpeg_version() read a release number, not the libavutil major
 
 
 def ffmpeg_version() -> "Tuple[int, int]":
@@ -114,7 +115,7 @@ def ffmpeg_version() -> "Tuple[int, int]":
     ship from the same build. Used only to pick between two spellings of an option where FFmpeg
     changed behaviour between releases (the tools otherwise never branch on the version: doctor's
     capability listing is the source of truth for what a build can do)."""
-    global _FFMPEG_VERSION
+    global _FFMPEG_VERSION, _FFMPEG_VERSION_IS_RELEASE
     if _FFMPEG_VERSION is None:
         _FFMPEG_VERSION = (0, 0)
         try:
@@ -123,6 +124,7 @@ def ffmpeg_version() -> "Tuple[int, int]":
             m = re.search(r"ffprobe version\s+n?(\d+)\.(\d+)", out)
             if m:
                 _FFMPEG_VERSION = (int(m.group(1)), int(m.group(2)))
+                _FFMPEG_VERSION_IS_RELEASE = True
             else:
                 # git / vendor builds print "N-115000-g..." or a date, never major.minor; the
                 # libavutil major is still there and maps one-to-one onto the FFmpeg major
@@ -271,6 +273,21 @@ def found_exe(name: str) -> str:
 def require_tool(name: str) -> str:
     """Return the absolute path of ffmpeg/ffprobe or exit with install steps."""
     path = ffmpeg_exe(name)[0] if name in ("ffmpeg", "ffprobe") else safe_which(name)
+    if path and name in ("ffmpeg", "ffprobe"):
+        # 3.0.0 removed FFmpeg 5.x (deprecated in 2.14.0) and the workarounds that kept it running:
+        # an older build that reports its version is refused before it can fail some other way.
+        # (0, 0) is an unreadable version and is not refused; a git/vendor build gives only the
+        # libavutil major, which cannot tell 6.0 from 6.1, so it is refused only below 6. The
+        # version is ffprobe's (ffmpeg is never run for it: --dry-run promises no ffmpeg run);
+        # both ship from one build, and doctor reads each binary's own.
+        found = ffmpeg_version()
+        if found != (0, 0) and (found[0] < MIN_FFMPEG[0] or (_FFMPEG_VERSION_IS_RELEASE and found < MIN_FFMPEG)):
+            system = platform.system()
+            hint = INSTALL_HINTS.get(system, "  See https://ffmpeg.org/download.html")
+            refuse("missing_tool", "ffmpeg_unsupported",
+                   f"FFmpeg {found[0]}.{found[1]} (read from ffprobe -version) is not supported since ffmpeg-skill 3.0.0 (5.x was deprecated in "
+                   f"2.14.0): use FFmpeg 6.1+. Install it for {system}:\n{hint}",
+                   code=127, version=f"{found[0]}.{found[1]}", required="6.1")
     if path:
         return path
     system = platform.system()
@@ -283,6 +300,9 @@ def require_tool(name: str) -> str:
     return ""  # unreachable
 
 
+MIN_FFMPEG = (6, 1)   # requirements.ffmpeg since 3.0.0 (_contract.MIN_FFMPEG is the same floor)
+
+
 X264_PRESETS = ("ultrafast", "superfast", "veryfast", "faster", "fast", "medium", "slow", "slower", "veryslow", "placebo")
 
 

package/scripts/_contract.py

@@ -33,7 +33,7 @@ from typing import Any, Dict, List, Optional
 HERE = Path(__file__).resolve().parent
 ROOT = HERE.parent
 SKILL_ID = "ffmpeg-skill"
-CONTRACT_VERSION = "1.0"
+CONTRACT_VERSION = "2.0"
 # `doctor`'s own introspection calls (-filters/-encoders/-bsfs/-version) are meant to be fast,
 # bounded, non-media operations; a hang here would silently freeze the one tool meant to report
 # whether the machine is broken. Media-processing scripts (cut, fit, ...) are NOT bounded this
@@ -79,7 +79,7 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
                   video_required=False, audio_only=True, visual=False, verify=[], produces_artifact=False, idempotency="bit_exact", deterministic=True),
     "cut": dict(role="execution", inputs=["video or audio asset"], outputs=["cut video/audio artifact (same container family, or audio extracted when -o has an audio extension)"],
                 required=FF, optional=[{"capability": X264, "when": "re-encode: --accurate, VFR source, or a keyframe farther than --tolerance"},
-                                       dict(HDR_X265, when=HDR_X265["when"] + "; with --keep-hevc on an HEVC source"), {"capability": AAC, "when": "re-encode of a video container"}] + AUDIO_OUT,
+                                       dict(HDR_X265, when=HDR_X265["when"] + "; on an SDR HEVC source (the default since 3.0.0; --no-keep-hevc uses x264)"), {"capability": AAC, "when": "re-encode of a video container"}] + AUDIO_OUT,
                 video_required=False, audio_only=True, visual=False, verify=["probe"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "fit": dict(role="execution", inputs=["video asset"], outputs=["video artifact at the requested duration / aspect / fps"],
                 required=FF + [X264, AAC], optional=[HDR_X265, {"capability": "filter:minterpolate", "when": "--smooth interpolate"},
@@ -412,6 +412,7 @@ DIAGNOSTICS_SCHEMA = {
 # error.reason: a stable code for why a refusal happened, beside `kind` (which says what class of
 # failure it is). Every refuse() call in scripts/ names one of these (a test reads the sources).
 ERROR_REASONS = {
+    "ffmpeg_unsupported": "kind missing_tool: the ffmpeg/ffprobe on PATH reports a version older than 6.1, which 3.0.0 no longer supports (5.x was deprecated in 2.14.0); details: {version, required}",
     "output_exists": "an output already exists and --overwrite was not given; details.outputs: [{path, resolved, size, mtime_ns}]",
     "output_is_input": "the output resolves to the same file as an input; details: {output, input, resolved}",
     "output_is_directory": "the output path is a directory; details: {output}",
@@ -641,21 +642,21 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
         extra = {"expected_duration": {"type": "number", "description": "seconds requested"},
                  "duration_error_ms": {"type": ["number", "null"], "description": "written minus requested, measured by ffprobe (null under --dry-run)"},
                  "precision": {"enum": ["packet", "sample", "codec_frame", "frame"],
-                               "description": "the whole run's: packet only when nothing re-encoded, the --segments join included (stream copy on a packet/keyframe boundary); sample: decoded audio trimmed to the sample, lossless output; codec_frame: sample-trimmed then framed by a lossy encoder (priming delay adds to the length); frame: re-encoded video"},
+                               "description": "since 3.0.0 the least exact segment's (as least_exact_precision; 2.x: the whole run's, packet only when nothing re-encoded): packet: stream copy on a packet/keyframe boundary; sample: decoded audio trimmed to the sample, lossless output; codec_frame: sample-trimmed then framed by a lossy encoder (priming delay adds to the length); frame: re-encoded video"},
                  "least_exact_precision": {"enum": ["packet", "sample", "codec_frame", "frame"],
                                            "description": "the least exact segment's precision (the order packet, codec_frame, frame, sample); differs from precision only for an audio-only --segments join of copied and re-encoded parts"},
-                 "keyframe_snapped": {"type": "boolean", "description": "precision is packet: the run is a stream copy end to end, which lands on keyframes and packets. Whether a copied start really moved is start_snapped"},
+                 "keyframe_snapped": {"type": ["boolean", "null"], "description": "since 3.0.0 equal to start_snapped: a copied start really moved (2.x: precision was packet, the run a stream copy end to end)"},
                  "start_snapped": {"type": ["boolean", "null"], "description": "measured: true when a copied segment's picture starts more than one frame from its requested start (the keyframe the copy's seek lands on, measured with the seek ffmpeg makes); false when every start is where asked (an MP4 edit list hides the pre-roll, the start is a keyframe, an audio-only copy, or everything re-encoded); null when a copied start was not measured (--dry-run)"},
                  "reencoded": {"type": "boolean"},
                  "reencode_reason": {"type": "array", "items": {"enum": ["requested", "codec", "vfr", "vfr_inconclusive", "pcm_container", "copy_failed", "stream_lost", "tolerance", "concat_fallback"]},
                                      "description": "why anything was re-encoded, distinct values in first-seen order ([] when nothing was): requested (--accurate), codec (--codec), vfr (a variable-frame-rate source forced --accurate), vfr_inconclusive (its frame timing could not be measured), pcm_container (compressed audio into a .wav), copy_failed (the stream copy errored), stream_lost (the copy wrote no video or no audio, as an MPEG-TS copy with no keyframe in its window does), tolerance (a keyframe snap past --tolerance), concat_fallback (--segments parts could not be joined by stream copy)"},
                  "segment_precision": {"type": ["array", "null"], "items": {"enum": ["packet", "sample", "codec_frame", "frame"]},
                                        "description": "--segments only: each segment's precision in order; least_exact_precision is the least exact of them (null for a single segment)"},
-                 "edit_list": {"type": "boolean", "description": "--edit-list on a single MP4/MOV stream copy: it kept the edit list it wrote instead of -avoid_negative_ts make_zero, so the keyframe's pre-roll is stored but hidden and the picture and the sound start at the requested time (false for every other path, the default included)"},
+                 "edit_list": {"type": "boolean", "description": "a single MP4/MOV stream copy kept the edit list it wrote instead of -avoid_negative_ts make_zero, so the keyframe's pre-roll is stored but hidden and the picture and the sound start at the requested time (the default since 3.0.0; false under --no-edit-list and for every other path)"},
                  "stored_preroll_seconds": {"type": ["number", "null"], "description": "with edit_list: seconds decoded from the keyframe the copy's seek lands on up to the requested start and hidden by the edit list (a player that ignores edit lists shows them); null otherwise"},
-                 "av_start_skew_seconds": {"type": ["number", "null"], "description": "the output's audio start minus its video start (null when either is missing or under --dry-run); reported, never repaired: on a stream copy only, a warning in notes when it is more than max(2 frames, 0.1 s) away from the source's own skew where the copy's picture starts (the keyframe it began from; the requested start under --edit-list), naming --accurate (and --edit-list for a single MP4/MOV copy whose start snapped)"},
-                 "notes": {"type": "array", "items": {"type": "string"}, "description": "stored pre-roll behind an --edit-list edit list, or an --edit-list copy judged by its video; an A/V start skew with its remedies; a source the default --vfr-guard average took for VFR whose sampled timing is constant (naming --vfr-guard sampled), or a sampled measurement that forced or (--vfr-guard off) skipped a re-encode; a --segments segment ended with the video, or held on its last frame for its sound; a --segments join re-cut because the source uses open GOPs, because a later B-frame .mp4/.mov segment starts between keyframes, or because its join check failed"},
-                 "vfr_check": {"type": "object", "description": "the sampled frame timing of a video input that could still stream-copy: under --vfr-guard average (the default) only when its nominal and average frame rates differ, which re-encodes it (reason vfr) whatever the sample says; under sampled or off on every such input (absent for audio-only input or output, --accurate, --codec, or a --dry-run input a plan has not written yet): {heuristic: true, measured, method: \"sampled\", guard, windows, deltas}. measured is sampled_cfr (every packet interval in up to five 6 s windows within a tick, at least 1 ms and at most half a frame, of its window's median, and the windows agree; the file-start window's first interval is ignored), vfr (under sampled, forces a re-encode, reason vfr) or inconclusive (fewer than 20 intervals or ffprobe failed; under sampled, reason vfr_inconclusive). --vfr-guard off keeps the copy either way, with a note. Variable timing between the windows is not seen"},
+                 "av_start_skew_seconds": {"type": ["number", "null"], "description": "the output's audio start minus its video start (null when either is missing or under --dry-run); reported, never repaired: on a stream copy only, a warning in notes when it is more than max(2 frames, 0.1 s) away from the source's own skew where the copy's picture starts (the keyframe it began from; the requested start with an edit list), naming --accurate (and the edit list for a single MP4/MOV copy whose start snapped under --no-edit-list)"},
+                 "notes": {"type": "array", "items": {"type": "string"}, "description": "stored pre-roll behind an edit list, or an edit-list copy judged by its video; an A/V start skew with its remedies; a source --vfr-guard average took for VFR whose sampled timing is constant (naming --vfr-guard sampled), or a sampled measurement that forced or (--vfr-guard off) skipped a re-encode; a --segments segment ended with the video, or held on its last frame for its sound; a --segments join re-cut because the source uses open GOPs, because a later B-frame .mp4/.mov segment starts between keyframes, or because its join check failed"},
+                 "vfr_check": {"type": "object", "description": "the sampled frame timing of a video input that could still stream-copy: under --vfr-guard average (2.x's default) only when its nominal and average frame rates differ, which re-encodes it (reason vfr) whatever the sample says; under sampled (the default since 3.0.0) or off on every such input (absent for audio-only input or output, --accurate, --codec, or a --dry-run input a plan has not written yet): {heuristic: true, measured, method: \"sampled\", guard, windows, deltas}. measured is sampled_cfr (every packet interval in up to five 6 s windows within a tick, at least 1 ms and at most half a frame, of its window's median, and the windows agree; the file-start window's first interval is ignored, and a seeked window is read from its first keyframe on, because a seek lands mid-GOP and the frames before it are not a full run), vfr (under sampled, forces a re-encode, reason vfr) or inconclusive (fewer than 20 intervals or ffprobe failed; under sampled, reason vfr_inconclusive). --vfr-guard off keeps the copy either way, with a note. Variable timing between the windows is not seen"},
                  "lossless_alternative": {"type": ["string", "null"], "description": "when a lossless cut re-encoded because of the keyframe snap: the --start that would stream-copy instead, and how far it is from the request"},
                  "join_check": {"type": ["object", "null"], "description": "--segments video stream-copy join: the written file measured by demuxing, {packets, expected_packets, max_step_seconds, audio_offset_ms, audio_parts_checked, ok}. expected_packets counts the source's video packets from each part's start keyframe to its end (or the end of the video); max_step_seconds is the largest presentation step (null when vfr_check measured anything but sampled_cfr, e.g. a --vfr-guard off join of variable timing, which checks the count only), and each step at a join must be the step its parts predict within 1 ms; audio_offset_ms is, per part, its sound's shift minus its picture's (+ = sound late) from audio packets matched by CRC32 to the source stream shaped like the joined audio (FFmpeg's default selection may copy one other than a:0; an MPEG-TS source's AAC is hashed without its ADTS headers) (null for a part with no unique match, e.g. digital silence; null as a whole when the source has no audio or the video check failed), and audio_parts_checked counts the measured parts; ok is the conjunction (counts, steps, every measured part within 5 ms), and false means the join was re-cut from the source (concat_fallback) and this is the failed measurement. null for a single segment, audio, --dry-run, --accurate/--codec/a forced re-encode, a segment that re-encoded, or a join that fell back before a copy join was attempted (open GOPs, a later B-frame segment starting between keyframes, parts that differ, a concat error)"},
                  "declick_ms": {"type": ["number", "null"], "description": "--segments joined by the re-encode (--accurate, a forced re-encode or concat_fallback): the fade in ms asked for on each side of every join, so butted cuts do not click (20 by default, --declick-ms; 0 under --no-declick; the file's own start and end are not faded). Each fade is capped at half its segment, so a segment shorter than twice this is faded for half its length. null when there is no join to fade: a single segment, a source with no audio, or a stream-copy join, whose sound is copied and not faded"},
@@ -1007,30 +1008,29 @@ def ffmpeg_security(versions: Dict[str, Optional[str]], sources: Optional[Dict[s
     return out
 
 
-# 2.10.9 deprecates Python 3.9 (docs/contract.md "Deprecation policy"; DEPRECATED below). The same
-# line is printed by bin/install.js (PY39_DEPRECATION there; a test keeps the two equal).
-PY39_DEPRECATION = ("warning: Python 3.9 is deprecated since ffmpeg-skill 2.10.9 (CPython 3.9 reached end of life "
-                    "in October 2025 and gets no security fixes); it still works in 2.x and support ends in 3.0.0: use Python 3.10+.")
+# 3.0.0 removed Python 3.9 (deprecated in 2.10.9) and FFmpeg 5.x (deprecated in 2.14.0): REMOVED
+# below. doctor reports a floor it is below in `unsupported` and as `ok: false`; bin/install.js
+# refuses Python below 3.10 and prints the same FFmpeg line (a test keeps the lines equal); every
+# tool refuses an FFmpeg it can read as older than 6.1 (runner.require_tool).
+MIN_PYTHON = (3, 10)
+MIN_FFMPEG = (6, 1)
+PYTHON_UNSUPPORTED = ("error: Python {v} is not supported since ffmpeg-skill 3.0.0 (3.9 was deprecated in 2.10.9; "
+                      "CPython 3.9 is end of life): use Python 3.10+.")
+FFMPEG_UNSUPPORTED = ("error: FFmpeg {v} is not supported since ffmpeg-skill 3.0.0 (5.x was deprecated in 2.14.0): "
+                      "use FFmpeg 6.1+.")
 
 
-def python_deprecation(version_info: Optional[tuple] = None) -> Optional[str]:
-    """The deprecation line for this interpreter, or None when it is not a deprecated one."""
+def python_unsupported(version_info: Optional[tuple] = None) -> Optional[str]:
+    """The unsupported-interpreter line for this Python, or None when it is 3.10 or later."""
     vi = tuple(version_info if version_info is not None else sys.version_info)[:2]
-    return PY39_DEPRECATION if vi == (3, 9) else None
+    return PYTHON_UNSUPPORTED.format(v=f"{vi[0]}.{vi[1]}") if vi < MIN_PYTHON else None
 
 
-# 2.14.0 deprecates FFmpeg 5.x the same way (DEPRECATED below): 2.x keeps running on it and CI keeps
-# its 5.1.1 job, and the line names 3.0.0 as the release that raises the floor to 6.1. bin/install.js
-# prints it too (FFMPEG5_DEPRECATION there; a test keeps the two equal).
-FFMPEG5_DEPRECATION = ("warning: FFmpeg 5.x is deprecated since ffmpeg-skill 2.14.0 (the 5.x branches date from 2022; "
-                       "Ubuntu 24.04 ships 6.1); it still works in 2.x and support ends in 3.0.0: use FFmpeg 6.1+.")
-
-
-def ffmpeg_deprecation(version: Optional[str]) -> Optional[str]:
-    """The deprecation line for this ffmpeg's version token, or None (not 5.x, or not a release
-    number: a git snapshot gets no line, as with the security advisory)."""
+def ffmpeg_unsupported(version: Optional[str]) -> Optional[str]:
+    """The unsupported-FFmpeg line for this version token, or None (6.1 or later, or not a release
+    number: a git snapshot is not refused, as with the security advisory)."""
     v = _parse_ffmpeg_version(version)
-    return FFMPEG5_DEPRECATION if v and v[0] == 5 else None
+    return FFMPEG_UNSUPPORTED.format(v=f"{v[0]}.{v[1]}") if v and tuple(v[:2]) < MIN_FFMPEG else None
 
 
 def _exe_report() -> Dict[str, Any]:
@@ -1289,6 +1289,13 @@ def doctor() -> Dict[str, Any]:
               "not CRF-equivalent (the result's `encoder`/`hw` say so)" for cap, alt in sorted(covered.items())]
     versions = {"ffmpeg": _version_line("ffmpeg"), "ffprobe": _version_line("ffprobe")}
     exes = _exe_report()
+    # 3.0.0: below the requirements floor is a broken install, not an advisory
+    unsupported = [line for line in (python_unsupported(), ffmpeg_unsupported(versions["ffmpeg"])) if line]
+    probe_line = ffmpeg_unsupported(versions["ffprobe"])
+    if probe_line:
+        probe_line = probe_line.replace("error: FFmpeg ", "error: ffprobe ", 1)
+        if probe_line not in unsupported:
+            unsupported.append(probe_line)
     return {
         "version": skill_version(),
         "python": ".".join(str(x) for x in sys.version_info[:3]),
@@ -1304,8 +1311,9 @@ def doctor() -> Dict[str, Any]:
         "detection": {k: {"status": v["status"], "count": len(v["names"]), "detail": v["detail"]} for k, v in listings.items()},
         "errors": errors,
         **({"notes": notes} if notes else {}),
-        "ok": not missing_required and not unknown_required,
-        "tools": _tool_usability(state, drawtext_crashed, covered),
+        "unsupported": unsupported,
+        "ok": not missing_required and not unknown_required and not unsupported,
+        "tools": _tool_usability(state, drawtext_crashed, covered, unsupported),
         "covered_by": covered,
         "gpu_encoders": _gpu_encoders(listings["encoders"]),
         "hw": _hw_default(),
@@ -1428,22 +1436,31 @@ def _capability_fix_hint(cap: str, drawtext_crashed: bool = False) -> str:
     return f"'{cap}' is not available; see docs/contract.md"
 
 
-def _tool_usability(state: Dict[str, str], drawtext_crashed: bool = False, covered: Optional[Dict[str, str]] = None) -> Dict[str, Dict[str, Any]]:
+def _tool_usability(state: Dict[str, str], drawtext_crashed: bool = False, covered: Optional[Dict[str, str]] = None,
+                    unsupported: Optional[List[str]] = None) -> Dict[str, Dict[str, Any]]:
     """Per-tool usable/missing/unknown, folded from the same capability `state` doctor already
     computed. Answers "can I run this tool on this machine today", not just "what capabilities
     exist" -- a caller reading only `available`/`missing` still has to cross-reference each tool's
     own required-capability list by hand to answer that. A required capability in `covered`
-    (libx264 replaced by VideoToolbox on this machine) blocks nothing; the tool lists it in `covered_by`."""
+    (libx264 replaced by VideoToolbox on this machine) blocks nothing; the tool lists it in `covered_by`.
+    A Python or FFmpeg below the 3.0.0 floor (`unsupported`) makes every tool unusable: each one
+    refuses to start on it."""
     covered = covered or {}
     tools: Dict[str, Dict[str, Any]] = {}
     for name, meta in TOOL_META.items():
         required = list(meta["required"])
         missing = [c for c in required if state.get(c) == "missing" and c not in covered]
         unknown = [c for c in required if state.get(c) == "unknown"]
-        entry: Dict[str, Any] = {"usable": "no" if missing else ("unknown" if unknown else "yes")}
+        entry: Dict[str, Any] = {"usable": "no" if missing or unsupported else ("unknown" if unknown else "yes")}
+        fixes = []
         if missing:
             entry["missing"] = missing
-            entry["fix"] = "; ".join(dict.fromkeys(_capability_fix_hint(c, drawtext_crashed) for c in missing))
+            fixes += [_capability_fix_hint(c, drawtext_crashed) for c in missing]
+        if unsupported:
+            entry["unsupported"] = list(unsupported)
+            fixes.append("install Python 3.10+ and FFmpeg 6.1+ (ffmpeg and ffprobe from one build)")
+        if fixes:
+            entry["fix"] = "; ".join(dict.fromkeys(fixes))
         if unknown:
             entry["unknown"] = unknown
         via = {c: covered[c] for c in required if c in covered}
@@ -1592,25 +1609,13 @@ def tool_spec(name: str, version: str) -> Dict[str, Any]:
 # ----------------------------------------------------------------------------- deprecations
 # What the next major removes, announced here per docs/contract.md's three-step deprecation policy:
 # step 1 (this list, --help text and the CHANGELOG) in a minor, step 2 keeps it working, step 3
-# removes it in the major. `where` says which surface a caller sees it on. Empty at 2.0.0: all
-# five 1.10.0 deprecations were settled by it (REMOVED below).
-DEPRECATED: List[Dict[str, str]] = [
-    # CPython 3.9 reached end of life in October 2025. Raising the floor is a break, so 2.x keeps
-    # running on it (CI still tests 3.9) and doctor / bin/install.js print PY39_DEPRECATION.
-    {"what": "running on Python 3.9 (the requirements.python floor)",
-     "since": "2.10.9", "removed_in": "3.0.0", "where": "behaviour",
-     "replacement": "Python 3.10 or later; on 3.9, doctor and the npx installer print a one-line warning"},
-    # FFmpeg 5.x: the 5.x branches date from 2022 and keep version-specific workarounds alive.
-    # 2.x keeps running on 5.0+ (CI still tests 5.1.1) and doctor / bin/install.js print
-    # FFMPEG5_DEPRECATION; 3.0.0 raises requirements.ffmpeg to 6.1.
-    {"what": "running on FFmpeg 5.x (the requirements.ffmpeg floor)",
-     "since": "2.14.0", "removed_in": "3.0.0", "where": "behaviour",
-     "replacement": "FFmpeg 6.1 or later; on 5.x, doctor and the npx installer print a one-line warning"},
-]
+# removes it in the major. `where` says which surface a caller sees it on. Empty at 2.0.0 and at
+# 3.0.0: every deprecation announced in 1.x and 2.x was settled by its major (REMOVED below).
+DEPRECATED: List[Dict[str, str]] = []
 
-# What 2.0.0 removed or changed, with the version that deprecated each: the "Removed" half of the
-# policy's step 3, kept in the contract so a caller migrating from 1.x can diff it instead of reading
-# a CHANGELOG. docs/contract.md's "What 2.0 changed" table is written from this list.
+# What each major removed or changed, with the version that deprecated each: the "Removed" half of
+# the policy's step 3, kept in the contract so a caller migrating can diff it instead of reading a
+# CHANGELOG. docs/contract.md's "What 2.0 changed" and "What 3.0 changed" tables are written from it.
 REMOVED: List[Dict[str, str]] = [
     {"what": "--crf as an alias of --quality on every re-encoding tool that takes --quality (export.py keeps --crf: its preset chooses the encoder)",
      "since": "1.10.0", "removed_in": "2.0.0", "where": "cli",
@@ -1627,6 +1632,12 @@ REMOVED: List[Dict[str, str]] = [
     {"what": "the result_v2 preview key and FFMPEG_SKILL_RESULT_V2 (the v1 top-level keys it was to replace were un-deprecated: they are the 2.0 shape)",
      "since": "1.10.0", "removed_in": "2.0.0", "where": "json",
      "replacement": "the top-level keys, unchanged from 1.x; --json-brief for a short document"},
+    {"what": "running on Python 3.9 (the requirements.python floor)",
+     "since": "2.10.9", "removed_in": "3.0.0", "where": "behaviour",
+     "replacement": "Python 3.10 or later; the npx installer skips an older interpreter and doctor reports it as unsupported (ok: false)"},
+    {"what": "running on FFmpeg 5.x (the requirements.ffmpeg floor)",
+     "since": "2.14.0", "removed_in": "3.0.0", "where": "behaviour",
+     "replacement": "FFmpeg 6.1 or later; every tool refuses an older one it can read (kind: missing_tool), and doctor reports it as unsupported"},
 ]
 
 
@@ -1844,7 +1855,7 @@ def build(detect: bool = True) -> Dict[str, Any]:
             },
             "not_provided": ["AI reasoning", "decisions", "production plans", "project IR", "approvals", "network access", "transcription engine"],
         },
-        "requirements": {"python": ">=3.9 (standard library only; 3.9 deprecated since 2.10.9, removed in 3.0.0; 3.10+ recommended)", "ffmpeg": ">=5.0 (5.x deprecated since 2.14.0, removed in 3.0.0; 6.1+ recommended)", "ffprobe": ">=5.0", "node": ">=16 (npx installer only)"},
+        "requirements": {"python": ">=3.10 (standard library only)", "ffmpeg": ">=6.1", "ffprobe": ">=6.1", "node": ">=16 (npx installer only)"},
         "execution": {
             "shell": False,
             "arbitrary_executables": False,
@@ -1908,7 +1919,7 @@ def build(detect: bool = True) -> Dict[str, Any]:
                                       "hidden .<output>.ffskill-audit.jsonl beside the output, and a cache event's .ffskill-audit.jsonl in the "
                                       "cache directory (render.py --cache DIR) or the batch's output_dir. Never written under --dry-run; a write that "
                                       "fails is a diagnostics.warnings entry (audit_log_unwritable), never a failure"},
-            "error_kinds": {"input": "missing or unsuitable input, bad arguments", "ffmpeg": "ffmpeg/ffprobe returned an error (message carries the last stderr lines)", "output": "ffmpeg exited 0 but the artifact is missing, empty or unreadable (an empty file is removed)", "missing_tool": "ffmpeg or ffprobe not on PATH", "timeout": "one ffmpeg/ffprobe run exceeded --timeout (default 1800 s, FFMPEG_SKILL_TIMEOUT) and was killed; partial output removed; exit 124", "verification": "the tool ran but its result failed the requested check: check.py platform rows (checks attached), render.py's check stage (output written, check attached), batch.py items (results attached), verify.py steps (files attached), color.py --retag (output written, but ffprobe does not read the requested colour tags on it); exit 1", "interrupted": "the tool received SIGINT or SIGTERM: the running ffmpeg (or sibling script) was stopped and its partial output removed; exit 130 or 143"},
+            "error_kinds": {"input": "missing or unsuitable input, bad arguments", "ffmpeg": "ffmpeg/ffprobe returned an error (message carries the last stderr lines)", "output": "ffmpeg exited 0 but the artifact is missing, empty or unreadable (an empty file is removed)", "missing_tool": "ffmpeg or ffprobe not on PATH, or older than the supported 6.1 (error.reason ffmpeg_unsupported)", "timeout": "one ffmpeg/ffprobe run exceeded --timeout (default 1800 s, FFMPEG_SKILL_TIMEOUT) and was killed; partial output removed; exit 124", "verification": "the tool ran but its result failed the requested check: check.py platform rows (checks attached), render.py's check stage (output written, check attached), batch.py items (results attached), verify.py steps (files attached), color.py --retag (output written, but ffprobe does not read the requested colour tags on it); exit 1", "interrupted": "the tool received SIGINT or SIGTERM: the running ffmpeg (or sibling script) was stopped and its partial output removed; exit 130 or 143"},
             "success_criterion": "exit 0 AND the output exists AND is non-empty AND ffprobe reads a stream from it; only then is status completed printed and the output probe attached",
         },
         "capabilities": caps,
@@ -1926,12 +1937,10 @@ def main() -> int:
     args = ap.parse_args()
     if args.command == "doctor":
         d = doctor()
-        # Advisories, never failures: on stderr in both modes, so `doctor --json`'s stdout stays one
-        # JSON document. The FFmpeg ones are also in the document (`ffmpeg_security.warnings`); the
-        # Python 3.9 deprecation is stderr-only, as every deprecation warning is (docs/contract.md
-        # "Deprecation policy" step 1), and machine-readable in `contract --json`'s `deprecated`;
-        # so is the FFmpeg 5.x one.
-        for line in [python_deprecation(), ffmpeg_deprecation(d.get("ffmpeg"))] + d["ffmpeg_security"]["warnings"]:
+        # On stderr in both modes, so `doctor --json`'s stdout stays one JSON document: an
+        # unsupported Python or FFmpeg (also in the document as `unsupported`, and part of `ok`)
+        # and the FFmpeg security advisories (`ffmpeg_security.warnings`, never part of `ok`).
+        for line in d["unsupported"] + d["ffmpeg_security"]["warnings"]:
             if line:
                 print(line, file=sys.stderr)
         if args.json:
@@ -1969,7 +1978,8 @@ def main() -> int:
         if d["ok"]:
             return 0
         # 1: something required is missing; 2: nothing proven missing but a required capability is unknown
-        return 1 if d["missing"] else 2
+        # an unsupported Python/FFmpeg is a known failure, like a missing capability (not "unknown")
+        return 1 if d["missing"] or d.get("unsupported") else 2
     print(json.dumps(build(detect=not args.static), indent=2, sort_keys=True, ensure_ascii=False))
     return 0