ffmpeg-skill 2.24.1 → 3.1.0

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,11 @@ 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 = {
+    "disk_full": "kind ffmpeg: ffmpeg reported \"No space left on device\" while writing; the hint says to free space or write elsewhere; details: {}",
+    "filter_missing": "kind ffmpeg: this ffmpeg build lacks a filter the command used (\"No such filter\"); details: {name}; the hint points at doctor",
+    "input_incomplete": "kind ffmpeg: the input has no index (\"moov atom not found\"): a recording cut off or a copy not finished; --repair cannot rebuild it; details: {}",
+    "input_unreadable": "kind ffmpeg: ffmpeg could not read the input as media (\"Invalid data found when processing input\"); details: {}",
+    "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}",
@@ -432,7 +437,8 @@ ERROR_REASONS = {
     "plan_unknown_tool": "render.py PLAN: the plan names no tool render.py can run; details: {plan, plan_sha256, checked_at, tool, audit_log}",
     "plan_cwd_missing": "render.py PLAN: the directory the plan was made in is gone; details: {plan, plan_sha256, checked_at, cwd, audit_log}",
     "plan_argv_invalid": "render.py PLAN: argv is not a list; details: {plan, plan_sha256, checked_at, argv_type, audit_log}",
-    "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}",
+    "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}",
 }
 
@@ -641,21 +647,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 +1013,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 +1294,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 +1316,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 +1441,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 +1614,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 +1637,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 +1860,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 +1924,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 +1942,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 +1983,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
 

package/scripts/cut.py

@@ -13,15 +13,16 @@ WAV), -o out.m4a writes AAC; an audio extension on a video input drops the
 picture (mp4 -> wav extraction). The result reports `precision`
 (packet / sample / codec_frame / frame) and the measured duration error, plus
 `mode` (copy / accurate / hybrid -- "hybrid" means a lossless cut silently
-re-encoded because the keyframe snap exceeded --tolerance), `keyframe_snapped`
-(a stream copy end to end), `start_snapped` (measured: a copied start moved past a frame),
+re-encoded because the keyframe snap exceeded --tolerance), `keyframe_snapped` and
+`start_snapped` (measured: a copied start moved past a frame; equal since 3.0.0),
 `reencode_reason`, `requested_start`/`requested_end` (or `requested_segments` for --segments),
 `requested_duration`, `output_duration` and `duration_delta_seconds` -- so a
 caller never has to trust "it probably cut where I asked" on faith.
 
-A single-segment .mp4/.mov copy shifts its timestamps to zero (-avoid_negative_ts
-make_zero), so the picture starts at the keyframe; --edit-list keeps the MP4 edit
-list instead, which hides the keyframe's pre-roll so the picture starts at --start.
+A single-segment .mp4/.mov copy keeps the MP4 edit list (the default since 3.0.0),
+which hides the keyframe's pre-roll so the picture starts at --start; --no-edit-list
+shifts its timestamps to zero instead (-avoid_negative_ts make_zero, every 2.x
+release's default), so the picture starts at the keyframe.
 An --accurate re-encode of a video does not: make_zero moved the picture by the
 AAC priming (about 21 ms, and further when a B-frame's decode time is negative)
 while the sound stayed at 0. A start that lands on a frame keeps that frame at 0.
@@ -29,14 +30,16 @@ A start between frames begins on the next frame and may keep up to one frame of
 timestamp. The MP4 edit list hides the encoder priming, and a source whose audio
 starts late keeps that offset.
 
-A re-encode uses x264 for an SDR source and x265 Main10 for an HDR or BT.2020 one, as every
-editing tool does; --keep-hevc re-encodes an SDR HEVC source as HEVC (x265 8-bit BT.709, or
-VideoToolbox under --hw), so a trimmed phone clip keeps its codec. --codec overrides both.
+A re-encode keeps an SDR HEVC source HEVC (x265 8-bit BT.709, or VideoToolbox under --hw;
+the default since 3.0.0), so a trimmed phone clip keeps its codec; --no-keep-hevc uses x264
+as every 2.x release did. Other SDR sources get x264 and an HDR or BT.2020 one x265 Main10,
+as every editing tool does. --codec overrides all of these.
 
-A source whose nominal and average frame rates differ is taken for variable-frame-rate and
-re-encoded, as --accurate (--vfr-guard average, the default); its sampled packet timing is
-reported in `vfr_check`. --vfr-guard sampled re-encodes only when that sampled timing is
-variable or too short to judge, and --vfr-guard off keeps the copy with a note.
+The VFR guard samples a video's packet timing (`vfr_check`) and re-encodes, as --accurate,
+only when it is variable or too short to judge (--vfr-guard sampled, the default since
+3.0.0). --vfr-guard average is every 2.x release's: a source whose nominal and average frame
+rates differ is taken for variable-frame-rate and re-encoded. --vfr-guard off keeps the copy
+with a note.
 
 Examples:
   python3 cut.py input.mp4 --start 00:00:10 --end 00:00:25
@@ -173,11 +176,10 @@ def least_exact(precisions: List[str]) -> str:
 def report_precision(meta: dict, dst: str, reencoded: bool, outcomes: List[dict]) -> dict:
     """The run's precision keys from its segments' outcomes.
 
-    precision         main's formula, unchanged: precision_of() for the whole run, so `packet` only
-                      when nothing re-encoded (the join included)
-    keyframe_snapped  precision == "packet": the run is a stream copy end to end, which lands on
-                      keyframes and packets. Kept with its 2.x meaning; whether a copied START
-                      really moved is start_snapped
+    precision         since 3.0.0, the least exact segment's precision (least_exact_precision);
+                      2.x reported precision_of() for the whole run
+    keyframe_snapped  since 3.0.0, start_snapped (a copied start really moved); 2.x reported
+                      "the run is a stream copy end to end" (precision_of() == "packet")
     start_snapped     measured: true when a copied segment's picture starts more than a frame from
                       its requested start; false when every start is where asked (an edit list, a
                       start on a keyframe, an audio-only copy's packet seek) or everything
@@ -186,7 +188,6 @@ def report_precision(meta: dict, dst: str, reencoded: bool, outcomes: List[dict]
                       an audio-only --segments join of copied and re-encoded parts (a video join
                       re-cuts every segment when any part re-encodes)
     segment_precision each segment's, for --segments (null for one segment)"""
-    precision = precision_of(meta, dst, reencoded)
     snaps = [o.get("start_snapped") for o in outcomes]
     if any(s is True for s in snaps):
         start_snapped = True
@@ -194,8 +195,11 @@ def report_precision(meta: dict, dst: str, reencoded: bool, outcomes: List[dict]
         start_snapped = None
     else:
         start_snapped = False
-    return {"precision": precision, "keyframe_snapped": precision == "packet", "start_snapped": start_snapped,
-            "least_exact_precision": least_exact([o["precision"] for o in outcomes]),
+    least = least_exact([o["precision"] for o in outcomes])
+    # 3.0.0: `precision` is the least exact segment's and `keyframe_snapped` says whether a copied
+    # start really moved (2.x: the run-level formula, and "the run is a stream copy end to end")
+    return {"precision": least, "keyframe_snapped": start_snapped, "start_snapped": start_snapped,
+            "least_exact_precision": least,
             "segment_precision": [o["precision"] for o in outcomes] if len(outcomes) > 1 else None}
 
 
@@ -1308,13 +1312,24 @@ def main() -> int:
                     help="the inverse of --segments: drop these ranges and keep the rest, joined in order "
                          "(e.g. '1:20-2:05,10:00-10:30'); overlapping ranges merge")
     ap.add_argument("--accurate", action="store_true", help="always re-encode for frame-accurate (video) / sample-accurate (audio) cuts (default: lossless -c copy, re-encoding only when the keyframe snap exceeds --tolerance)")
-    ap.add_argument("--edit-list", action="store_true", help="a single-segment .mp4/.mov stream copy keeps the MP4 edit list that hides the keyframe's pre-roll, so the picture starts at --start (default: -avoid_negative_ts make_zero, the picture starts at the keyframe); a player that ignores edit lists shows the pre-roll")
-    ap.add_argument("--keep-hevc", action="store_true", help="a re-encode of an SDR HEVC source stays HEVC (x265 8-bit BT.709; VideoToolbox under --hw) instead of x264 (default: x264 for SDR, x265 Main10 for HDR); --codec overrides it")
-    ap.add_argument("--vfr-guard", choices=["average", "sampled", "off"], default="average",
-                    help="what keeps a variable-frame-rate source from a stream copy (default average: a nominal rate "
-                         "that differs from the average re-encodes, as --accurate, and the sampled frame timing is "
-                         "reported; sampled: re-encode only when sampled packet timestamps are variable or too few "
-                         "to judge; off: measure and keep the copy, with a note)")
+    el = ap.add_mutually_exclusive_group()
+    el.add_argument("--edit-list", action="store_true",
+                    help="a single-segment .mp4/.mov stream copy keeps the MP4 edit list that hides the keyframe's pre-roll, "
+                         "so the picture starts at --start (the default since 3.0.0); a player that ignores edit lists shows the pre-roll")
+    el.add_argument("--no-edit-list", action="store_true",
+                    help="shift the copy's timestamps instead (-avoid_negative_ts make_zero, every 2.x release's default): "
+                         "the picture starts at the keyframe before --start")
+    kh = ap.add_mutually_exclusive_group()
+    kh.add_argument("--keep-hevc", action="store_true",
+                    help="a re-encode of an SDR HEVC source stays HEVC (x265 8-bit BT.709; VideoToolbox under --hw); "
+                         "the default since 3.0.0; --codec overrides it")
+    kh.add_argument("--no-keep-hevc", action="store_true",
+                    help="re-encode an SDR HEVC source with x264, as every 2.x release did (HDR still gets x265 Main10)")
+    ap.add_argument("--vfr-guard", choices=["average", "sampled", "off"], default="sampled",
+                    help="what keeps a variable-frame-rate source from a stream copy (default sampled since 3.0.0: re-encode "
+                         "only when sampled packet timestamps are variable or too few to judge; average, every 2.x "
+                         "release's default: a nominal rate that differs from the average re-encodes, as --accurate, "
+                         "and the sampled timing is reported; off: measure and keep the copy, with a note)")
     ap.add_argument("--tolerance", type=float, default=0.5, help="max seconds a lossless cut may deviate before re-encoding kicks in (default 0.5, -1 = never for a "
                          "keyframe snap; a --segments join is still re-cut for open GOPs, a later B-frame .mp4/.mov "
                          "segment starting between keyframes, or a failed join check)")
@@ -1340,7 +1355,9 @@ def main() -> int:
     args = ap.parse_args()
     apply_common(args)
     global KEEP_HEVC
-    KEEP_HEVC = args.keep_hevc
+    # 3.0.0 defaults: keep HEVC and the edit list unless the --no- form is given (--edit-list and
+    # --keep-hevc stay accepted, and now say what happens anyway)
+    KEEP_HEVC = not args.no_keep_hevc
 
     meta = probe(args.input)
     total = meta.get("duration") or 0.0
@@ -1492,7 +1509,7 @@ def main() -> int:
     join_check = None
     if len(segments) == 1:
         outcomes.append(cut_one(args.input, segments[0][0], segments[0][1], output, args.accurate, args.crf, args.preset, args.tolerance, meta,
-                                edit_list_ok=args.edit_list))
+                                edit_list_ok=not args.no_edit_list))
     elif hold_needed or args.accurate:
         # Straight to one encode through the concat filter. A held frame needs the re-cut (no part
         # can carry it into a copy join); and when every part re-encodes anyway, encoding each on

package/scripts/render.py

@@ -1048,6 +1048,22 @@ def export_timeline(proj: Dict[str, Any], rel, dest: str) -> int:
     return 0
 
 
+def _has_sound(current: str, proj: Dict[str, Any], rel: Any) -> bool:
+    """Whether the render carries sound at this point: measured on the intermediate when it
+    exists, otherwise (a dry run) from the sources: a clip with an audio stream, music or a
+    replacement track."""
+    if os.path.exists(current) and not STATE.dry_run:   # a dry run may find an earlier render's file there
+        return bool((probe(current).get("audio") or {}).get("codec"))
+    au = proj.get("audio") or {}
+    if au.get("music") or au.get("replace"):
+        return True
+    for c in proj.get("clips") or []:
+        src = rel(c["src"]) if isinstance(c, dict) and c.get("src") else None
+        if not src or not os.path.exists(src) or (probe(src).get("audio") or {}).get("codec"):
+            return True
+    return False
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("project", nargs="?", help="project.json, or a plan.json written by <tool> --plan")
@@ -1543,6 +1559,11 @@ def main() -> int:
 
     # ---- loudness
     ld = proj.get("loudness")
+    if ld and not _has_sound(current, proj, rel):
+        # a template's loudness stage on a silent source (screen recording, timelapse, drone) used
+        # to fail the render after the picture stages had run, while the dry run said it would work
+        record_skip("the loudness stage is not run: the video has no audio", "loudness_no_audio", stage="loudness")
+        ld = None
     if ld:
         nxt = str(work / f"loudnorm{mid}")
         argv = [current, "-o", nxt]