ffmpeg-skill 3.7.0 → 3.8.1

package/README.md

@@ -269,7 +269,7 @@ These are the rules the skill file gives the agent and the code enforces.
 |---|---|
 | `export.py` | Presets `youtube`, `youtube4k`, `reels`, `tiktok`, `shorts`, `linkedin`, `facebook`, `x`, `youtube-hdr` (HEVC Main10, source HDR tags kept), `youtube-av1`, `prores`, `dnxhr-lb`/`sq`/`hq`/`hqx`/`444`, the alpha masters `prores4444`/`prores4444xq`/`qtrle`/`vp9-alpha`/`hap-alpha` (alpha read back), `key-fill` (a switcher's fill + key pair), `h265`, `gif`, `copy`, all tagged BT.709 unless they carry HDR or are an editing master (`prores`, `dnxhr-*`: the source's tags kept, codec, profile and pixel format read back) (a BT.601-matrix or RGB source is converted to BT.709, not relabelled); `--normalize` meets the platform's loudness in the same call (`render.py` turns it on by default for platform presets) ; `--max-mb MB` fits the file under a size limit by a two-pass encode and measures it ; `--preset copy --repair` remuxes a damaged file (timestamps regenerated, corrupt packets dropped) and counts the errors before and after |
 | `proxy.py` | Small, low-bitrate proxy for downstream AI analysis/preview/editing decisions — resize by `--width`/`--scale`, proxy-grade `--quality` (default 30), `--fps`, `--no-audio`; not a delivery preset |
-| `check.py` | PASS / WARN / FAIL against YouTube, Shorts, Reels, TikTok, X, LinkedIn, Facebook, broadcast and podcast specs, from the same delivery table the export presets and templates read (podcast also reports chapter markers and channel count), with the fix for each failure and a `format` / `judgement` kind per row; `--content` adds black-frame, frozen-frame, silence, short audio-dropout, single-frame-flash and flat-first-frame rows ; `--compare REF` measures SSIM/PSNR against a reference, and with `--expect-changed SPAN\|none` fails when the picture changed outside the spans the caller declared; `--levels bt709\|ebu-r103` counts the luma and chroma samples outside the broadcast legal range, per clip and per window, with min/max Y/U/V; `--expect-identity` checks that the file is the one a run reported writing (`output_identity`) |
+| `check.py` | PASS / WARN / FAIL against YouTube, Shorts, Reels, TikTok, X, LinkedIn, Facebook, broadcast and podcast specs, from the same delivery table the export presets and templates read (podcast also reports chapter markers and channel count), with the fix for each failure and a `format` / `judgement` kind per row; a length or file size over the table's upload limit is a WARN marked `basis: guidance` (platforms change these, the uploader checks the current one), while `--max-duration` / `--max-mb` state the caller's own limit and FAIL when a `--platform` is named (with none, an over-length is WARN like every judgement row); `--content` adds black-frame, frozen-frame, silence, short audio-dropout, single-frame-flash and flat-first-frame rows ; `--compare REF` measures SSIM/PSNR against a reference, and with `--expect-changed SPAN\|none` fails when the picture changed outside the spans the caller declared; `--levels bt709\|ebu-r103` counts the luma and chroma samples outside the broadcast legal range, per clip and per window, with min/max Y/U/V; `--expect-identity` checks that the file is the one a run reported writing (`output_identity`) |
 | `report.py` | Single-file HTML delivery report: before/after sheets, media facts, loudness, compliance, the commands run; `--pack` renders a social pack table |
 
 **Orchestration**

package/SKILL.md

@@ -34,6 +34,7 @@ Every step in full: `references/workflow.md`.
    A delivery request is one `render.py --template`; three or more steps: a `render.py` project.
 5. **Check** with `check.py OUTPUT --platform X --expect-identity S:M` (the writer's `output_identity`):
    fix format rows; fix duration, aspect, fps or loudness only when the request implies it. Mention WARNs.
+   A `basis: guidance` WARN (length, size) is the table's upload limit: the uploader checks the current one.
 6. **Verify** from the writer's `--json` probe or `probe.py`: exit 0 and the requested numbers, or it failed.
 7. **Keep originals:** never overwrite a source; `--overwrite` only for this job's files or ones the user
    asked to replace.

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.7.0`) | any release |
+| `skill.version` | the npm / package.json version (`3.8.1`) | 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.7.0", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "3.8.1", "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"},
@@ -225,7 +225,14 @@ The workflow in `SKILL.md` is "probe first, verify last". The contract states it
 `requires_visual_verification` is `true` exactly for the tools that change the picture
 (fit, caption, overlay, graphics, color, join, multicam, render). Audio-only tools and
 audio-only inputs never need `look`; the report line is `Look: not needed`. `check`
-rows carry `kind: format` (fix it) or `kind: judgement` (decide with the user).
+rows carry `kind: format` (fix it) or `kind: judgement` (decide with the user), and `basis`:
+`requirement` (the row can FAIL) or `guidance`. The `duration` and `file size` rows are `basis: guidance`
+when their limit is the platform table's upload limit (`scripts/_platforms.py`, dated
+`UPLOAD_LIMITS_AS_OF`): over it, or not measurable against it, is WARN with a `reason` naming the
+table's date, never FAIL, and does not make `check` exit non-zero. Platforms change upload limits
+and whoever uploads checks the current one. A limit the caller states (`--max-duration`, `--max-mb`)
+is the caller's requirement: `basis: requirement`, FAIL when over or not measured (with no `--platform`
+named, `duration` is WARN as every judgement row is).
 The `audio` row FAILs (WARN when no loudness target applies) when the track is present but silent (peak at or below -50 dBFS, from
 the loudness pass or, when loudness is skipped, one volumedetect pass). `check --content`
 (opt-in; render.py `"check": {"content": true}`) adds `black`, `frozen` and `silence` rows
@@ -772,7 +779,7 @@ silence a tool reported as fine while another measurement disagreed):
 
 | key | tool | what it holds |
 |---|---|---|
-| `verification[]` step `duration` | `export.py` (a preset with a platform maximum, without `--allow-long`) | the written file's length against the maximum, measured as `check.py` measures it (the container's duration, `tolerance` 0). A length that cannot be read fails the step with `reason: not_measured` |
+| `verification[]` step `duration` | `export.py` (a preset with a platform maximum, without `--allow-long`) | the written file's length against the maximum, measured as `check.py` measures it (the container's duration, `tolerance` 0). A length that cannot be read fails the step with `reason: not_measured`. The step verifies the trim `export.py` itself made; `check.py` reports the same table limit as guidance (WARN) |
 | `verification[]` step `duration` (`property: audio_duration`) | `loudness.py` | the output's sound against the input's, to one AAC frame (at least 0.03 s): a levels pass changes no timing. A length that cannot be read fails the step with `reason: not_measured` |
 | `inputs_duration`, `transition_shortening`; step `duration`'s `inputs_total` | `join.py` | the clips' own total and how much the transitions took out of it. `expected_duration` is derived from the transition the join applied, so it cannot show that on its own |
 | `frame_rate`, `clip_frames`, `transition_frames` | `join.py` (video join; added after 3.6.2) | the join's rate as an exact fraction (`"30000/1001"`), the whole frames of it each clip holds (its sound is cut to the samples those frames last), and the frames each transition overlaps (`--duration` rounded to whole frames, at least 1; `0` for `--transition none`). Lengths and xfade offsets are counted in these frames, never in rounded seconds (#455, #468); `inputs_duration` and `expected_duration` are derived from them. A pending `--dry-run` input counts 0 frames |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "3.7.0",
+  "version": "3.8.1",
   "mcpName": "io.github.kajisho5/ffmpeg-skill",
   "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": [

package/references/scripts.md

@@ -58,8 +58,11 @@ Every row names the constant or flag it comes from, and a test holds the table t
 <!-- thresholds:end -->
 
 Delivery targets per platform (`scripts/_platforms.py`). A file passes loudness within the
-platform's tolerance of its target, and true peak at or below its ceiling plus 0.1 dB. `export.py`
-holds the written length to the maximum with no tolerance, as `check.py` does.
+platform's tolerance of its target, and true peak at or below its ceiling plus 0.1 dB. The
+maximum length (and the file size `check.py` reads from the same table) is an upload limit: the
+table's as of `_platforms.UPLOAD_LIMITS_AS_OF`, guidance rather than a requirement, because
+platforms change it and whoever uploads checks the current one. `check.py` WARNs over it;
+`export.py` trims to it unless `--allow-long` and holds the written length to it with no tolerance.
 
 <!-- platforms:start -->
 | platform | loudness | tolerance | true peak | max duration |
@@ -1240,6 +1243,15 @@ step before reporting a deliverable; fix FAILs, mention WARNs. Without
 `--platform` the youtube spec is assumed and the judgement rows (duration,
 aspect, fps, resolution, loudness, true peak) come back as WARN with a `notes`
 line, not FAIL: name the platform when the file is a delivery for it.
+Every row carries `basis`: `requirement` or `guidance`. The `duration` and `file size` rows are
+`guidance` when the limit is the platform table's: a file over it (or whose length or size could
+not be measured) is WARN, not FAIL, with a `reason` that names the table's date
+(`_platforms.UPLOAD_LIMITS_AS_OF`), and it does not make the exit code non-zero by itself. Upload
+limits change often and belong to whoever uploads, who checks the platform's current one; the
+encoding rows (codec, aspect, resolution, fps, pixel format, colour, loudness, true peak) are
+unchanged. `--max-duration S` and `--max-mb N` state the caller's own limit, on any platform
+including `custom`: those rows are `requirement` and FAIL when over or not measured (with no
+`--platform` at all, `duration` is WARN like the other judgement rows).
 `--platform podcast` adds two informational rows: `channels` (PASS for mono or
 stereo, WARN above — podcast players downmix 5.1 unpredictably) and `chapters`
 (PASS when the container carries at least one marker, WARN `none` otherwise —
@@ -2189,7 +2201,8 @@ overhead) in place of its CRF, and the encode runs in two passes. The written si
 overshot. Refused for a preset that does not encode with x264 (and under `--hw`), with `--crf`,
 for a source with no duration, and when the budget leaves under 100 kb/s for the picture.
 Scales into the preset frame (pad by default), tags BT.709 (a BT.601-matrix or RGB source is converted to it, as by every re-encode), sets `+faststart`,
-trims to platform maximums (Reels 90 s, X 140 s) unless `--allow-long`, and says
+trims to the table's platform maximums (Reels 90 s, X 140 s; the table's as of its date, and
+platforms change them) unless `--allow-long`, and says
 so: `trimmed: {from, to}` and a `notes` line. It
 does not touch levels: for youtube / youtube4k / reels / x the written file is
 measured and the result's `loudness` (and a `notes` line) says when it is

package/references/workflow.md

@@ -10,7 +10,7 @@ lines per step; every rule below still applies.
 2. **Prefer lossless.** If the request can be met without re-encoding (plain cuts on keyframes, remuxing, audio-only changes), do not re-encode. `cut.py` and `loudness.py` stream-copy video by default; `--accurate` on `cut.py` only for frame-exact cuts.
 3. **Plan with `--dry-run --json`, then execute.** Trust `--json`, not a dry run's summary line, for any number in the plan (a dimension there can be a placeholder). Use before long encodes, to report facts.
 4. **Chain in a sensible order.** A delivery request with no other editing is one template run (`render.py --template NAME INPUT`), not a hand-built chain. Otherwise: colour (HDR→SDR / LUT) → cut → join → silence → fit → caption/overlay → sync → audio → loudness → export. Frame changes before captions, so text is sized for the final frame. Re-encode as few times as possible: intermediates at CRF 18, `export.py` last. **Three or more steps: `render.py` with a project.json.**
-5. **Check the deliverable.** Before reporting, run `check.py OUTPUT --platform X --expect-identity S:M` (the writer's `output_identity`; templates already check); never check after a failed write. Format rows (codec, pixel format, size, true peak, colour tags, VFR) are safe to fix. Judgement rows change content: duration (cut loses material), aspect (crop loses edges), fps (drops motion), loudness (ambience must not be boosted) — fix only when the request implies the answer, else state the choice and its cost. Mention WARNs.
+5. **Check the deliverable.** Before reporting, run `check.py OUTPUT --platform X --expect-identity S:M` (the writer's `output_identity`; templates already check); never check after a failed write. Format rows (codec, pixel format, size, true peak, colour tags, VFR) are safe to fix. Judgement rows change content: duration (cut loses material), aspect (crop loses edges), fps (drops motion), loudness (ambience must not be boosted) — fix only when the request implies the answer, else state the choice and its cost. Mention WARNs. A `duration` or `file size` WARN with `basis: guidance` is the table's upload limit, not a requirement: platforms change these, the uploader checks the current one.
 6. **Verify the output.** Confirm duration, resolution, fps and audio match the request, from the writing tool's `--json`/`--json-brief` probe or `probe.py`, and report those numbers ("final.mp4: 59.98 s, 1080x1920, 30 fps, AAC stereo"). A step is done only when the script exited 0 and the output probes as expected: a non-zero exit, a missing or empty file, or a probe that contradicts the request is a failure reported with the script's error message.
 7. **Keep the user's originals.** Never overwrite the source; write new files next to input or where asked. An existing output path is refused (`kind: input`); add `--overwrite` only for a file this job made or the user asked to replace.
 8. **Look at the picture.** Whenever the picture changed (captions, overlays, graphics, crop/pad, resize, colour, transitions, a `join.py` scaling a clip to the first clip's frame, `color.py --to-sdr`) run `look.py OUTPUT --tiles 3x2` (or `--at T` for one frame) and view the PNG (4x3 for whole-clip layout). Not finished until `Look:` names that PNG — a probe cannot see a caption on a face. Audio-only: `Look: not needed`. What to look for splits like `check.py`'s rows in step 5:

package/scripts/_common/__init__.py

@@ -63,7 +63,7 @@ from _common.runner import (
     STATE, _timed_out, _unwatch, _watch, X264_PRESETS
 )
 from _common.emit import (
-    absorb_stage, audit, _brief, _BRIEF_DROP, _brief_summary, _CURRENT_CTX, die, emit, info, note, _plan_at_exit, _plan_inputs,
+    absorb_stage, audit, _brief, input_length, _BRIEF_DROP, _brief_summary, _CURRENT_CTX, die, emit, info, note, _plan_at_exit, _plan_inputs,
     _plan_unbound_inputs, _PLAN_STRIP, PLAN_VERSION, print_json, record_fallback, record_skip, refuse, _set_current_ctx, warn,
     write_plan
 )
@@ -74,7 +74,7 @@ from _common.probe import (
     display_size, pixel_aspect, square_pixels, square_pixels_note
 )
 from _common.decision import (
-    aac_args, add_pad_fill_args, aspect_ratio, audio_codec_for, AUDIO_CODECS, brand_caption_style, BRAND_DEFAULTS,
+    aac_args, add_pad_fill_args, conform_filter, conform_to_length, conform_output_t, aspect_ratio, audio_codec_for, AUDIO_CODECS, brand_caption_style, BRAND_DEFAULTS,
     description_block, _evidence_rank, fmt_chapter_time, propose_chapters,
     frame_flow, label_shot_flow, MOTION_GRID, MOTION_SEARCH, MOTION_STATIC_PX, MOTION_PAN_SPREAD,
     filler_spans, FILLER_WORDS, FILLER_AMBIGUOUS, FILLER_DISCOURSE_MARKERS, FILLER_MAX_WORD,

package/scripts/_common/decision.py

@@ -15,7 +15,7 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional, Sequence, Tuple
 from _common.color import (as_limited, bt709_label_filter, bt709_matrix_args, bt709_matrix_filter, bt709_tag_args, drawn_stream_format,
                            is_neutral_color, limited_range_filter, rgb_island, rgb_to_bt709_filter, _sdr_bt709)
-from _common.emit import die, record_fallback, refuse, warn
+from _common.emit import die, input_length, record_fallback, refuse, warn
 from _common.runner import read_json
 from _common.runner import CODECS, STATE, ffmpeg_encoders, ffmpeg_list_error, ffmpeg_version, hw_platform_reason
 
@@ -431,6 +431,30 @@ def av_trim(start: float, end: Optional[float], rate: float = 0.0, fill_gaps: bo
             f"atrim=start={start:.6f}{aend},asetpts=PTS-{start:.6f}/TB,{pad}")
 
 
+def conform_filter(samples: int, rate: int) -> str:
+    """Pad with silence or trim to exactly `samples` at `rate` (#478): counted in samples, not in
+    seconds written to the millisecond, which left a result up to 24 samples (48 kHz) off. The
+    aformat pins the rate the count is in, so a resampler FFmpeg inserts sits ahead of the count."""
+    head = f"aformat=sample_rates={rate}," if rate else ""
+    return f"{head}apad=whole_len={samples},atrim=end_sample={samples}"
+
+
+def conform_to_length(length: float, rate: int) -> str:
+    """Pad with silence or trim a track to `length` seconds of a timeline that starts at 0, to the
+    sample (#478, #493). The count is of samples, and sound that starts after 0 keeps its start
+    (apad and atrim=end_sample do not move timestamps): N samples from 0.3 s end 0.3 s past
+    `length`. The trim on the timestamp ends it there; half a sample of slack keeps the Nth sample
+    of a track that starts at 0. audio.py, grid.py, broll.py and multicam.py end their sound with
+    this; `atrim=duration={length:.3f}` cut 59244 samples (48 kHz) to 59232."""
+    return conform_filter(round(length * rate), rate) + f",atrim=end={length + 0.5 / rate:.6f}"
+
+
+def conform_output_t(length: float, rate: int) -> str:
+    """The output `-t` beside conform_to_length(): `-t {length:.3f}` would cut the conformed sound
+    back to the millisecond, so the limit sits half a sample past the last one."""
+    return f"{length + 0.5 / rate:.6f}"
+
+
 def av_clip_length(meta: Optional[Dict[str, Any]], fps: float) -> float:
     """The one length a clip holds once both streams start at its first frame (av_trim from the
     video's start): the video's, or where the sound ends when it runs more than a frame past the
@@ -440,7 +464,7 @@ def av_clip_length(meta: Optional[Dict[str, Any]], fps: float) -> float:
     v = (meta.get("video") or {}).get("duration")
     a = (meta.get("audio") or {}).get("duration")
     if not v:
-        return meta.get("duration") or 0.0
+        return input_length(meta)  # a file that states no length at all is refused, not 0 s long (#491)
     if a:
         v0, a0 = stream_starts(meta)
         a = a + a0 - v0  # where the sound ends, counted from the first frame

package/scripts/_common/emit.py

@@ -647,6 +647,29 @@ def stream_length(meta: Dict[str, Any], kind: str) -> Optional[float]:
     return None
 
 
+LENGTH_UNREAD_HINT = ("remux the file so its container states a length (export.py INPUT --preset copy -o remuxed.mkv), "
+                      "then run this on the remux")
+
+
+def input_length(meta: Optional[Dict[str, Any]], path: Optional[str] = None) -> float:
+    """An input's length in seconds, for a tool that computes with it (#491). A file that states
+    no length (Matroska written to a pipe: ffprobe prints N/A for the container and every stream)
+    probes as duration None, and `meta.get("duration") or 0.0` read that as a clip 0 s long: a
+    speed factor of 0.00x, "--at 1 is outside the clip (0..0.000)", a reverse of no frames. Unread
+    is not zero, so this refuses, as check.py's duration row says "could not measure". A dry run's
+    pending input (probe()'s stub, duration 0.0), a stated length of 0 and a still picture (one
+    image read by an image demuxer has no length to state) pass through as before."""
+    meta = meta or {}
+    length = meta.get("duration")
+    fmt = meta.get("format") or ""
+    still = fmt == "image2" or fmt.endswith("_pipe")  # probe._is_still()'s rule, on the probe document
+    if length is None and not meta.get("dry_run") and not still:
+        die(f"the length of {path or meta.get('file') or 'the input'} could not be read: neither its container nor "
+            "its streams state one, and this operation is computed from the input's length",
+            kind="input", hint=LENGTH_UNREAD_HINT)
+    return float(length or 0.0)
+
+
 def stream_end(meta: Dict[str, Any], kind: str) -> Optional[float]:
     """Where one stream ends on the file's timeline: its start plus its own length."""
     length = stream_length(meta, kind)

package/scripts/_contract.py

@@ -638,7 +638,7 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
                  "levels": {"type": "object", "description": "--levels only: {standard, reference, bit_depth, legal {y, c}: inclusive legal code ranges at the file's depth, window_seconds, frames, out_of_range_pct {y, u, v, chroma}: share of samples outside them (chroma: Cb and Cr samples together), brng_pct (signalstats BRNG: pixels with any component outside the fixed BT.601/709 nominal range), worst_frame {time, y_pct, chroma_pct}, min {y, u, v}, max {y, u, v}, windows: the same per --levels-window seconds ({start, end, ...})}"},
                  "change_scope": {"type": "object", "description": "--expect-changed only, when the two files could be compared: {declared [{start, end, rect}], observed [{start, end, frames, rect [x, y, w, h], peak}]: every span with a tile above the floor, undeclared: the same for the tiles no declaration covers, declared_unchanged: declared spans in which nothing changed, floor, tile [columns, rows], frames, quiet_peak: the largest tile at or under the floor}. Times are this file's presentation times in seconds, rectangles are displayed pixels"},
                  "notes": {"type": "array", "items": {"type": "string"}, "description": "present when no --platform was named (youtube was assumed and judgement rows are WARN), when --compare paired a different number of frames than the reference has, or when --expect-changed compared two files that are not encoded alike"},
-                 "checks": {"type": "array", "items": {"type": "object", "properties": {"check": {"type": "string", "description": "row name; --content adds black, frozen and silence; --compare adds similarity; --expect-changed adds change_scope; --levels adds legal levels; --expect-identity adds identity; audio FAILs when the track is present but silent (peak <= -50 dBFS). A value that could not be read is \"could not measure\", never a PASS: duration FAILs (WARN without a length limit) when the file states no length, and black, frozen and silence are then WARN rows; loudness is WARN for audio shorter than one 400 ms block; --tp without --lufs (custom) measures the true peak row"}, "status": {"enum": ["PASS", "WARN", "FAIL"]}, "value": {}, "expected": {}, "fix": {"type": "string"}, "kind": {"enum": ["format", "judgement"]}}}}}
+                 "checks": {"type": "array", "items": {"type": "object", "properties": {"check": {"type": "string", "description": "row name; --content adds black, frozen and silence; --compare adds similarity; --expect-changed adds change_scope; --levels adds legal levels; --expect-identity adds identity; audio FAILs when the track is present but silent (peak <= -50 dBFS). A value that could not be read is \"could not measure\", never a PASS: duration FAILs under a --max-duration the caller stated (WARN under the platform table's limit or without one) when the file states no length, and black, frozen and silence are then WARN rows; loudness is WARN for audio shorter than one 400 ms block; --tp without --lufs (custom) measures the true peak row"}, "status": {"enum": ["PASS", "WARN", "FAIL"]}, "value": {}, "expected": {}, "fix": {"type": "string"}, "kind": {"enum": ["format", "judgement"]}, "basis": {"enum": ["requirement", "guidance"], "description": "where the expected value comes from. guidance: the duration and file size rows when their limit is the platform table's upload limit (scripts/_platforms.py, dated UPLOAD_LIMITS_AS_OF); such a row is PASS or WARN, never FAIL, is not counted in failed, and its reason says the uploader checks the platform's current limit. requirement: every other row, and the same two rows under --max-duration / --max-mb (the caller's own limit), which FAIL"}}}}}
     elif name == "caption":
         extra = {"transcription": {"type": "object", "description": "with --transcribe: {engine, model, language, routing (why auto chose it), detected_language when auto detected it}; when auto ran the English-only Parakeet model on English assumed, notes says so"},
                  "caption": {"type": "object", "description": "cue layout: shifted / wrapped / rebalanced / split / extended / dropped counts, plus wrap ('phrase' or 'measured'), phrase_breaks (1.16), broken_inside_word -- atoms hard-sliced at the column edge because they did not fit alone even at the size floor (1.18.4) -- and overlong -- now residual: a single character alone wider than the column. Burn mode: cues_burned -- non-blank cues that overlap [0, duration] and are drawn -- and cues_outside -- non-blank cues wholly outside it (2.2.6); a burn with no visible cue is refused, kind input. --ass: ass_malformed -- Dialogue lines that could not be read and are not counted -- and with --offset ass_shifted / ass_unshifted -- lines moved, and lines whose timestamps could not be read, copied as they were (each count above 0 is also a diagnostics.warnings entry)"},
@@ -1820,7 +1820,9 @@ MCP_PROMPTS: List[Dict[str, Any]] = [
                      "`check.py <output> --platform {platform}` before calling it done -- format rows (codec, pixel "
                      "format, size, true peak, colour tags, VFR) are safe to fix; judgement rows (duration, aspect, "
                      "fps, loudness) change content, so fix them only when the request implies the answer, otherwise "
-                     "state the choice and its cost. Mention WARNs; do not chase them."),
+                     "state the choice and its cost. Mention WARNs; do not chase them. A duration or file size WARN with "
+                     "basis guidance is the table's upload limit, which platforms change: report it, the uploader "
+                     "checks the current one."),
     },
     {
         "name": "podcast", "description": "Turn an audio recording into a loudness-normalised podcast episode with chapters.",
@@ -2053,7 +2055,7 @@ def build(detect: bool = True) -> Dict[str, Any]:
             "verify_last": "run the tools named in each ToolSpec.verification after it wrote an artifact",
             "visual": "when requires_visual_verification is true, run ffmpeg-skill/look on the output and inspect the PNG",
             "audio_only": "audio-only inputs and audio-only tools never need ffmpeg-skill/look",
-            "check_rows": "ffmpeg-skill/check rows carry kind=format (fix) or kind=judgement (decide with the user)",
+            "check_rows": "ffmpeg-skill/check rows carry kind=format (fix) or kind=judgement (decide with the user), and basis=requirement (can FAIL) or basis=guidance (the platform table's upload length/size limit: WARN at most, the uploader checks the current limit)",
         },
         "json_output": {
             "success": {"status": "completed", "exit_code": 0, "stdout": "one JSON document (output_schema)"},

package/scripts/_platforms.py

@@ -12,7 +12,9 @@ the description bar. This module is the single table the delivery tools read:
         "fps":     the frame rate a delivery is conformed to (None = leave alone),
         "spec":    check.py's compliance row values (max_duration, aspects,
                    min_height, fps_max, codecs, max_bytes, lufs, lufs_tol, tp,
-                   sdr_only) -- the keys check.py's SPECS has always had,
+                   sdr_only) -- the keys check.py's SPECS has always had;
+                   max_duration and max_bytes are upload limits, guidance as of
+                   UPLOAD_LIMITS_AS_OF rather than a requirement (#485),
         "safe":    the fraction of the frame each edge's UI covers
                    (top/bottom/left/right, 0..1) -- nothing readable goes there,
         "caption": the caption defaults a template uses (size as a fraction of the
@@ -62,6 +64,20 @@ _CAP_WIDE = {"size": 0.0694, "position": "bottom", "box": False, "outline": 2, "
 # by up to that much, so a tighter rule fails a file on measurement noise.
 TP_TOLERANCE_DB = 0.1
 
+# Upload limits are guidance (#485). A platform's maximum length and file size change often and
+# differ by account; whoever uploads reads the current ones. The `max_duration` and `max_bytes`
+# below are this table's as of the date here, the day the table as a whole was last decided --
+# not a date each number was read from the platform. check.py reports a file over one of them as
+# WARN with `basis: guidance`, never FAIL; the encoding values (codecs, aspects, fps, loudness,
+# true peak) are the format a delivery is held to and stay requirements.
+UPLOAD_LIMITS_AS_OF = "2026-10-30"
+
+
+def upload_limit_note(platform: str) -> str:
+    """Why a row measured against this table's length or size limit is guidance, in one clause."""
+    return (f"the limit is this tool's table for {platform} as of {UPLOAD_LIMITS_AS_OF}; platforms change "
+            "upload limits, so whoever uploads checks the current one")
+
 PLATFORMS: Dict[str, Dict[str, Any]] = {
     "tiktok": {
         "title": "TikTok",

package/scripts/audio.py

@@ -30,6 +30,7 @@ from typing import Any, Dict, List
 from _common.probe import SILENT_PEAK_DBFS
 from _common import STATE, add_common, dry_run_input_pending, require_tool, apply_common, audio_codec_for, db_to_linear, default_output, die, emit, ffmpeg_base, info, is_audio_output, measured_level_dbfs, probe, run, run_keeping_subtitles, fmt_secs
 from _common.emit import warn
+from _common.decision import conform_filter, conform_to_length
 
 # --downmix: ITU-R BS.775 fold-down, renormalised by pan's '<' (see main()).
 DOWNMIX_PAN = "pan=stereo|FL<FL+0.707*FC+0.707*BL+0.707*SL|FR<FR+0.707*FC+0.707*BR+0.707*SR"
@@ -254,14 +255,6 @@ def property_step(name: str, expected: int, measured: Any) -> Dict[str, Any]:
     return {"step": name, "expected": expected, "measured": value, "ok": value == expected}
 
 
-def conform_filter(samples: int, rate: int) -> str:
-    """Pad with silence or trim to exactly `samples` at `rate` (#478): counted in samples, not in
-    seconds written to the millisecond, which left a result up to 24 samples (48 kHz) off. The
-    aformat pins the rate the count is in, so a resampler FFmpeg inserts sits ahead of the count."""
-    head = f"aformat=sample_rates={rate}," if rate else ""
-    return f"{head}apad=whole_len={samples},atrim=end_sample={samples}"
-
-
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input")
@@ -564,12 +557,9 @@ def main() -> int:
     elif main_dur and (args.replace or args.music or keep_video):
         if rate:
             conform_samples = round(main_dur * rate)
-            # The count is of samples, and sound that starts after the picture keeps its start
-            # (apad and atrim=end_sample do not move timestamps): N samples from 0.3 s end 0.3 s
-            # past the picture. The trim on the timestamp, which is what this was before #478,
-            # ends it with the picture; half a sample of slack keeps the Nth sample of a track
-            # that starts at 0.
-            post.append(conform_filter(conform_samples, rate) + f",atrim=end={main_dur + 0.5 / rate:.6f}")
+            # counted in samples and ended on the timestamp, so sound that starts after the picture
+            # still ends with it (conform_to_length, shared with grid, broll and multicam since #493)
+            post.append(conform_to_length(main_dur, rate))
         else:
             # a dry run's pending input: no rate to count in yet; the real run counts samples
             post.append(f"apad,atrim=0:{main_dur:.6f}")

package/scripts/broll.py

@@ -21,10 +21,14 @@ import argparse
 import sys
 from typing import Any, Dict, List
 
-from _common.decision import av_trim, frame_rate, grid_at_or_after, stream_starts
+from _common.decision import av_trim, conform_output_t, conform_to_length, frame_rate, grid_at_or_after, stream_starts
 from _common import STATE, add_common, aac_args, apply_common, cfr_args, as_limited, default_output, die, draws_chroma, drawn_chain, emit, ffmpeg_base, info, time_arg, label_chain, matrix_chain, overlay_format, range_chain, probe, run, validate_color, video_args, X264_PRESETS, fmt_secs
 from _common.emit import note, record_fallback
 from _common.probe import display_size, square_pixels, square_pixels_note
+from _common.emit import input_length
+
+
+MIX_RATE = 48000  # every layer of a b/mix sound is resampled to it before the mix
 
 
 def main() -> int:
@@ -57,7 +61,7 @@ def main() -> int:
     meta_a = probe(args.input)
     if not meta_a.get("video"):
         die("A-roll has no video stream")
-    dur_a = meta_a.get("duration") or 0.0
+    dur_a = input_length(meta_a)
     # the cutaway is scaled onto the frame ffmpeg has already rotated, not the stored one, and
     # onto a non-square-pixel A-roll squared at its display aspect (#411)
     w, h = display_size(meta_a["video"])
@@ -98,7 +102,7 @@ def main() -> int:
             die(f"cutaway {i + 1}: --at {at:g}s is past the end of the A-roll ({dur_a:.3f}s)")
         if dur_a and at + length > dur_a + 0.01:
             die(f"cutaway {i + 1}: {at:g}s + {length:g}s runs past the end of the A-roll ({dur_a:.3f}s)")
-        dur_b = meta_b.get("duration") or 0.0
+        dur_b = input_length(meta_b)
         if dur_b and start_b + length > dur_b + 0.01 and not STATE.dry_run:
             die(f"cutaway {i + 1}: {path} has only {dur_b - start_b:.3f}s from {start_b:g}s, {length:g}s asked for")
         if cutaways and at < cutaways[-1]["at"] + cutaways[-1]["length"]:
@@ -161,7 +165,11 @@ def main() -> int:
                 parts.append(f"[{i + 1}:a:0]{av_trim(first, first + c['length'])[1]},"
                              f"aformat=sample_rates=48000:channel_layouts=stereo,adelay={int(c['at'] * 1000)}|{int(c['at'] * 1000)}[ab{i}]")
                 layers.append(f"[ab{i}]")
-            parts.append(f"{''.join(layers)}amix=inputs={len(layers)}:normalize=0:dropout_transition=0,atrim=duration={dur_a:.3f}[aout]")
+            # the mix ends with the A-roll, to the sample (#493): every layer is 48 kHz, so the count
+            # is in that rate. `atrim=duration={:.3f}` and `-t {:.3f}` cut it to the millisecond. A
+            # dry run's pending A-roll has no length to count, and keeps the old filter.
+            tail = conform_to_length(dur_a, MIX_RATE) if dur_a > 0 else f"atrim=duration={dur_a:.3f}"
+            parts.append(f"{''.join(layers)}amix=inputs={len(layers)}:normalize=0:dropout_transition=0,{tail}[aout]")
             aout = "[aout]"
 
     cmd += ["-filter_complex", ";".join(parts), "-map", vout]
@@ -174,7 +182,7 @@ def main() -> int:
         cmd += aac_args()
     else:
         cmd += ["-an"]
-    cmd += ["-t", f"{dur_a:.3f}", output]
+    cmd += ["-t", conform_output_t(dur_a, MIX_RATE) if aout == "[aout]" and dur_a > 0 else f"{dur_a:.3f}", output]
     run(cmd)
 
     result = probe(output, role="output")

package/scripts/check.py

@@ -3,7 +3,11 @@
 
 Checks duration, frame size / aspect, fps, codec, pixel format, colour tags,
 file size, integrated loudness and true peak against the chosen platform
-and prints a PASS/WARN/FAIL table. Exit code 1 when anything FAILs. Each
+and prints a PASS/WARN/FAIL table. Exit code 1 when anything FAILs. A length
+or file size over the platform table's limit is WARN (`basis: guidance`): upload
+limits change and the uploader checks the current one; --max-duration / --max-mb
+state the caller's own limit, which FAILs when a --platform is named (with none,
+an over-length is WARN, as every judgement row is). Each
 row's `fix` is the command that resolves it; a few of the less obvious FAILs
 (video codec, pixel format, HDR colour, loudness) also carry a plain-language
 `reason` -- "QuickTime and iOS commonly reject video that isn't 8-bit 4:2:0",
@@ -43,7 +47,7 @@ import sys
 from fractions import Fraction
 from typing import Any, Dict, List, Optional, Tuple
 
-from _platforms import PLATFORMS, PLATFORM_CHOICES, TP_TOLERANCE_DB, spec_of, resolve as resolve_platform
+from _platforms import PLATFORMS, PLATFORM_CHOICES, TP_TOLERANCE_DB, spec_of, upload_limit_note, resolve as resolve_platform
 from _common.probe import (CHANGE_FLOOR, CHANGE_GRID, change_mask_tiles, change_tiles, LEGAL_RANGE_CHOICES, measure_signal_range, COMPARE_SSIM_WARN, CONTENT_FLAT_STD, SILENT_PEAK_DBFS, compare_pictures, detect_content,
                            detect_flashes, first_frame_stats, presentation_times, measured_level_dbfs)
 from _common.emit import file_identity
@@ -361,11 +365,11 @@ def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input")
     ap.add_argument("--platform", choices=PLATFORM_CHOICES, default=None, help="delivery spec to check against (default: youtube, with judgement rows reported as WARN because no platform was named)")
-    ap.add_argument("--max-duration", type=float, help="override max duration in seconds")
+    ap.add_argument("--max-duration", type=float, help="the caller's own maximum length in seconds: over it FAILs when a --platform is named, WARNs with none (the platform table's limit is guidance, WARN)")
     ap.add_argument("--aspect", help="override allowed aspect (e.g. 9:16 or 16:9,1:1)")
     ap.add_argument("--lufs", type=float, help="override loudness target")
     ap.add_argument("--tp", type=float, help="override true-peak ceiling")
-    ap.add_argument("--max-mb", type=float, help="override max file size in MB")
+    ap.add_argument("--max-mb", type=float, help="the caller's own maximum file size in MB: over it FAILs (the platform table's limit is guidance, WARN)")
     ap.add_argument("--no-loudness", action="store_true", help="skip the loudness measurement (faster)")
     ap.add_argument("--content", action="store_true",
                     help="also check the content (one decode pass, plus an audio-only and a video-only one): black, frozen, silence, dropouts, flashes and first frame rows")
@@ -448,6 +452,11 @@ def main() -> int:
 
     # first frame / flashes: a fade from black or a strobe can be the edit, so neither is a mechanical fix
     JUDGEMENT = {"duration", "aspect", "loudness", "true peak", "fps", "resolution", "first frame", "flashes"}
+    # #485: the rows whose limit is the platform table's upload limit rather than one the caller
+    # stated (--max-duration, --max-mb). Those are guidance: WARN at worst, never counted as failed.
+    guidance = {name for name, stated, limit in (("duration", args.max_duration, spec["max_duration"]),
+                                                 ("file size", args.max_mb, spec["max_bytes"]))
+                if stated is None and limit}
 
     def row(name: str, status: str, value: Any, expect: Any, fix: str = "", reason: str = "") -> None:
         # "format" rows are safe to fix mechanically; "judgement" rows change the content
@@ -456,12 +465,19 @@ def main() -> int:
         # person would ask "so what?" about) is why it matters in plain terms, not the spec clause.
         if status == "FAIL" and not named and name in JUDGEMENT:
             status = "WARN"
+        # "basis" is where the expected value comes from: "requirement" (the delivery format, or a
+        # limit the caller stated) can FAIL; "guidance" (the table's upload limit) cannot.
+        basis = "guidance" if name in guidance else "requirement"
+        if basis == "guidance" and status != "PASS":
+            status = "WARN"
+            reason = (reason + "; " if reason else "") + upload_limit_note(args.platform)
         rows.append({"check": name, "status": status, "value": value, "expected": expect, "fix": fix,
                      "reason": reason if status != "PASS" else "",
-                     "kind": "judgement" if name in JUDGEMENT else "format"})
+                     "kind": "judgement" if name in JUDGEMENT else "format", "basis": basis})
 
     # A113: a length ffprobe did not report is not a length of 0 s that fits under every limit.
-    # The row says it was not measured (FAIL under a length limit, WARN without one), and the
+    # The row says it was not measured (FAIL under a length limit the caller stated, WARN under the
+    # platform table's or without one), and the
     # --content rows that are shares of the running time say so too instead of disappearing.
     dur_read = meta.get("duration")
     dur = dur_read or 0.0
@@ -770,6 +786,8 @@ def main() -> int:
             line = f"  {r['status']:4s} {r['check']:{width}s}  {r['value']}  (expected {r['expected']})"
             if r["status"] != "PASS" and r["kind"] == "judgement":
                 line += "  [judgement]"
+            if r["status"] != "PASS" and r["basis"] == "guidance":
+                line += "  [guidance]"
             if r["status"] != "PASS" and r["reason"]:
                 line += f"  ({r['reason']})"
             if r["status"] != "PASS" and r["fix"]:

package/scripts/export.py

@@ -52,10 +52,10 @@ from _common.decision import hw_preset_video, restate_last_swap
 from _common.emit import note, record_fallback, record_skip, warn
 from _common.probe import PROBED_AUDIO, PROBED_VIDEO, probed_maps, square_pixels, square_pixels_note
 from _common.runner import ffmpeg_encoders, guard_sidecar, remember_written, replace_checked, replace_checked_together, reserve_sibling, run_analysis as _run_analysis, subtitle_codec_for
-from _common.emit import file_identity
+from _common.emit import file_identity, input_length
 from check import SPECS as PLATFORMS, measure_loudness
 from _common.probe import SILENT_PEAK_DBFS, shorter_than_a_loudness_block
-from _platforms import ALIASES as _ALIASES, PLATFORMS as PLATFORM_TABLE, TP_TOLERANCE_DB, resolve as resolve_platform
+from _platforms import ALIASES as _ALIASES, PLATFORMS as PLATFORM_TABLE, TP_TOLERANCE_DB, UPLOAD_LIMITS_AS_OF, resolve as resolve_platform
 # Frame and duration limit come from the one platform table (scripts/_platforms.py) rather than
 # from a literal restated here: before 1.14 they were typed twice and the facebook preset had
 # already drifted (no duration cap against the table's 14400 s).
@@ -443,7 +443,7 @@ def size_video_args(args, video: List[str], p: Dict, meta: Dict, has_audio: bool
             + (" (--hw puts it on VideoToolbox, which has no two-pass mode)" if STATE.hw else ""))
     if not math.isfinite(args.max_mb) or args.max_mb <= 0:
         die(f"--max-mb must be a positive number of MiB, got {args.max_mb:g}")
-    dur = float(meta.get("duration") or 0.0)
+    dur = input_length(meta)  # the bitrate is the size over the length: no stated length is refused (#491)
     if p["max"] and not args.allow_long:
         dur = min(dur, float(p["max"]))
     if dur <= 0:
@@ -679,7 +679,8 @@ def main() -> int:
         # kept subtitle track is cut at the same point (a cue after it is not written)
         trimmed = {"from": round(float(meta["duration"]), 3), "to": round(float(p["max"]), 3)}
         note(f"trimmed from {trimmed['from']:.3f}s to the {args.preset} maximum of {p['max']:.0f}s "
-             "(use --allow-long to keep full length)")
+             f"(this tool's table as of {UPLOAD_LIMITS_AS_OF}, and platforms change it: "
+             "use --allow-long to keep full length)")
         cmd += ["-t", f"{p['max']:.3f}"]
     damage_before = media_damage(args.input) if args.repair and not STATE.dry_run else None
     with tempfile.TemporaryDirectory(prefix="ffskill_2pass_") as passdir:

package/scripts/fit.py

@@ -42,6 +42,7 @@ from typing import List
 from _common.decision import SEEK_MARGIN, delivered_rate, frame_rate, grid_at_or_after, stream_starts
 from _common.timeline import exact_rate, output_timecode_args
 from _common import video_args, STATE, add_common, apply_common, emit, aac_args, aspect_ratio, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, pad_filters, add_pad_fill_args, X264_PRESETS, time_arg, fmt_secs, frame_size, display_size, square_pixels, square_pixels_note, note
+from _common.emit import input_length
 BLUR_DARKEN = 0.15  # how much --fit blur dims the blurred background copy (eq brightness)
 
 
@@ -157,6 +158,10 @@ def main() -> int:
         target = time_arg(args.duration, "--duration", meta["video"].get("fps") if meta.get("video") else None)
         if target <= 0:
             die("target duration must be > 0")
+        # speed and trim are both computed from the source's length: one that states none is refused
+        # (#491). Not under --dry-run, where render.py plans a clip's speed stage on the source in
+        # place of a cut that does not exist yet and records the stand-in itself (A97)
+        src_dur = (meta.get("duration") or 0.0) if STATE.dry_run else input_length(meta)
         if args.method == "speed":
             if src_dur <= 0 and STATE.dry_run:
                 src_dur = target  # planning against an intermediate that does not exist yet

package/scripts/freeze.py

@@ -21,6 +21,7 @@ import sys
 
 from _common.decision import av_trim, frame_durations, frame_rate, grid_at_or_after, stream_starts
 from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, video_args, X264_PRESETS, MissingFpsError, time_arg, fmt_secs, run
+from _common.emit import input_length
 
 
 def main() -> int:
@@ -43,7 +44,7 @@ def main() -> int:
     meta = probe(args.input)
     if not meta.get("video"):
         die("input has no video stream")
-    dur = meta.get("duration") or 0.0
+    dur = input_length(meta)
     fps = meta["video"].get("fps") or 30.0
     if args.at is not None:
         at = time_arg(args.at, "--at", (meta.get("video") or {}).get("fps"))

package/scripts/graphics.py

@@ -49,6 +49,7 @@ from _common.fonts import font_choice, record_font_choice
 from _common.probe import display_size, square_pixels, square_pixels_note
 from _ass_overlay import text_overlay_ass, EMOJI_SENTINEL
 from _common import drawtext_fontfile  # noqa: E402
+from _common.emit import input_length  # noqa: E402
 
 # where the template's text chain goes in a filter_complex it builds (graphics.main fills it in)
 TEXT = "@TEXT@"
@@ -201,7 +202,7 @@ def main(force_route: Optional[str] = None) -> int:
         info(f"--platform {args.platform}: safe margins top {m_top} / bottom {m_bottom} / left {m_left} / right {m_right} px")
     fps = meta["video"].get("fps")
     s = time_arg(args.start, "--start", fps) if args.start else 0.0
-    e = time_arg(args.end, "--end", fps) if args.end else dur
+    e = time_arg(args.end, "--end", fps) if args.end else input_length(meta)  # no --end is the clip's end (#491)
     # the picture's own length first: sound that runs on keeps the container open past the last frame
     picture_len = meta["video"].get("duration") or dur
     if picture_len and s >= picture_len:

package/scripts/grid.py

@@ -34,6 +34,8 @@ from _common.emit import note, record_fallback  # noqa: E402
 from _common.fonts import script_font_for_text  # noqa: E402
 from _common.probe import square_pixels  # noqa: E402
 from _common.wrap import text_width_em  # noqa: E402
+from _common.emit import input_length  # noqa: E402
+from _common.decision import conform_output_t, conform_to_length  # noqa: E402
 
 LABEL_MARGIN = 10
 
@@ -114,7 +116,7 @@ def main() -> int:
     if args.audio_from is not None and not metas[args.audio_from].get("audio"):
         die(f"--audio-from {args.audio_from}: {args.inputs[args.audio_from]} has no audio stream")
 
-    durations = [m.get("duration") or 0.0 for m in metas]
+    durations = [input_length(m) for m in metas]
     target_duration = max(durations) if args.pad else min(durations)
 
     # each label is drawn with a font that covers its own script, as every other text-drawing tool
@@ -188,12 +190,24 @@ def main() -> int:
     cw, ch = args.cell_width + args.gap, args.cell_height + args.gap
     layout = "|".join(f"{c * cw}_{r * ch}" for r in range(args.rows) for c in range(args.cols))
     parts.append("".join(f"[v{i}]" for i in range(n)) + f"xstack=inputs={n}:layout={layout}:fill={args.background}[out]")
-    if args.audio_from is not None and args.pad and durations[args.audio_from] < target_duration:
+    # The sound ends with the grid, to the sample (#493): padded when its clip is shorter than a
+    # --pad grid, trimmed when it is longer. `apad,atrim=duration={:.3f}` and the output's
+    # `-t {:.3f}` both cut it to the millisecond (59244 samples at 48 kHz came out as 59232). A dry
+    # run's pending input has no rate to count in yet, and keeps the old filter, as audio.py does.
+    audio_rate = (metas[args.audio_from]["audio"].get("sample_rate") or 0) if args.audio_from is not None else 0
+    conformed = bool(audio_rate and target_duration > 0)
+    audio_source = None
+    if conformed:
+        parts.append(f"[{args.audio_from}:a:0]{conform_to_length(target_duration, audio_rate)}[aout]")
+        audio_source = "[aout]"
+    elif args.audio_from is not None and args.pad and durations[args.audio_from] < target_duration:
         parts.append(f"[{args.audio_from}:a:0]apad,atrim=duration={target_duration:.3f}[aout]")
+        audio_source = "[aout]"
+    elif args.audio_from is not None:
+        audio_source = f"{args.audio_from}:a:0"
     cmd += ["-filter_complex", ";".join(parts), "-map", "[out]"]
 
-    if args.audio_from is not None:
-        audio_source = "[aout]" if (args.pad and durations[args.audio_from] < target_duration) else f"{args.audio_from}:a:0"
+    if audio_source:
         cmd += ["-map", audio_source]
     # A grid is an 8-bit SDR composite by design (a comparison/contact artefact, not a
     # deliverable); an HDR input is flattened like look.py's contact sheet flattens it. Say so
@@ -206,7 +220,7 @@ def main() -> int:
         cmd += aac_args()
     else:
         cmd += ["-an"]
-    cmd += ["-t", f"{target_duration:.3f}", output]
+    cmd += ["-t", conform_output_t(target_duration, audio_rate) if conformed else f"{target_duration:.3f}", output]
     run(cmd)
 
     result = probe(output, role="output")

package/scripts/join.py

@@ -50,6 +50,7 @@ from _common.emit import note, warn
 from _common.decision import av_clip_length, av_trim, stream_starts
 from _common.probe import display_size, square_pixels, square_pixels_note
 from _common.timeline import exact_rate
+from _common.emit import input_length
 
 TRANSITIONS = ["fade", "dissolve", "wipeleft", "wiperight", "wipeup", "wipedown", "slideleft", "slideright",
                "circleopen", "circleclose", "fadeblack", "fadewhite", "smoothleft", "smoothright", "radial", "none"]
@@ -704,6 +705,8 @@ def main() -> int:
             skipped=skipped)
     validate_color(args.pad_color, "--pad-color")
     metas = [probe(p) for p in args.inputs]
+    for p, m in zip(args.inputs, metas):
+        input_length(m, p)  # every clip is placed by its length: one that states none is refused, not 0 s (#491)
     # A pending input's probe is the dry-run stub, whose (0x0) video stream says nothing about the
     # file an earlier step will write. Its extension stands in: a step names its output for what
     # it holds, so an audio extension (.wav, .m4a, .aiff, ... -- every audio file this skill

package/scripts/look.py

@@ -25,6 +25,7 @@ from _common import ffmpeg_filters, filter_missing_hint  # noqa: E402
 from _common.emit import note, record_fallback  # noqa: E402
 from _common.color import bt709_label_filter, bt2020_sdr_to_bt709_chain, hdr_to_sdr_chain, is_bt2020_sdr  # noqa: E402
 from _common.probe import PROBED_VIDEO, display_size, square_pixels, square_pixels_note  # noqa: E402
+from _common.emit import input_length  # noqa: E402
 
 # --guides: broadcast safe areas as outlines, in fractions of the frame (a tile as much as a frame).
 # Action and title safe are SMPTE ST 2046-1's 93 % and 90 % of a 16:9 picture; the 4:3 centre cut
@@ -363,6 +364,7 @@ def main() -> int:
         except ValueError:
             die("--tiles must look like 4x3")
         n = cols * rows
+        dur = input_length(meta)  # the sheet is spread over the length: none stated is refused with the way out (#491)
         if not dur:
             die("cannot build a contact sheet without a known duration")
         frames_avail = int((meta["video"].get("fps") or 0) * dur) or 1

package/scripts/loop.py

@@ -36,6 +36,7 @@ from _common import STATE, concat_list_line, add_common, aac_args, apply_common,
 from _common.emit import warn
 from _common.decision import av_trim
 from _common.probe import decode_gray_frames, decode_pcm_mono
+from _common.emit import input_length
 
 
 # The loop filter's size is capped at 32767 frames, so one boomerang cycle (2N-2 frames) must fit.
@@ -248,7 +249,7 @@ def main() -> int:
     meta = probe(args.input)
     if not meta.get("video"):
         die("input has no video stream")
-    src_dur = meta.get("duration") or 0.0
+    src_dur = input_length(meta)  # no stated length: refused with the way out (#491)
     if src_dur <= 0:
         die("input has no measurable duration to loop")
     has_audio = bool(meta.get("audio")) and not args.boomerang

package/scripts/metadata.py

@@ -33,6 +33,7 @@ from typing import Any, Dict, List, Optional
 from _common import (guard_sidecar, add_common, apply_common, default_output, description_block, detect_scenes, detect_silences,
                      die, emit, ffmpeg_base, fmt_chapter_time, info, propose_chapters, time_arg, probe, run,
                      STATE, read_text_or_die)
+from _common.emit import input_length
 
 CHAPTER_CONTAINERS = {".mp4", ".m4v", ".m4a", ".mov", ".mkv", ".mka", ".webm"}
 TAG_KEYS = ("title", "artist", "album", "comment", "date", "genre")
@@ -230,7 +231,8 @@ def main() -> int:
         die(f"{out_ext or 'this'} container cannot hold chapter markers; write to one of "
             f"{', '.join(sorted(CHAPTER_CONTAINERS))} (the streams are copied, so choose the matching family: .mp4/.mov/.m4a for MPEG-4, .mkv/.mka/.webm for Matroska)")
 
-    duration = meta.get("duration") or 0.0
+    # the last chapter ends at the file's end and --auto-chapters spaces them over its length (#491)
+    duration = input_length(meta) if (args.chapters or args.auto_chapters) else (meta.get("duration") or 0.0)
     chapters: Optional[List[Dict[str, Any]]] = parse_chapters(args.chapters, duration) if args.chapters else None
     auto: Optional[Dict[str, Any]] = None
     notes: List[str] = []

package/scripts/multicam.py

@@ -34,8 +34,9 @@ from typing import Dict, List, Tuple
 
 from _common import guard_sidecar, label_chain, matrix_chain, range_chain, video_args, aac_args, add_common, apply_common, default_output, die, emit, ffmpeg_base, info, time_arg, probe, run, x264_args, X264_PRESETS, fmt_secs, decode_pcm_mono, rms_envelope, STATE
 from _common.emit import note, record_fallback, record_skip, warn
-from _common.decision import av_trim, rebase_project_paths
+from _common.decision import av_trim, conform_output_t, conform_to_length, rebase_project_paths
 from _common.probe import display_size, square_pixels, square_pixels_note
+from _common.emit import input_length
 from sync import measure_offset
 
 ENERGY_WINDOW_S = 0.25  # --switch energy: loudness measured over this window on the reference timeline
@@ -187,8 +188,8 @@ def main() -> int:
         ratio = 1.0
         skipped_reason = None
         if args.fix_drift:
-            ref_dur = metas[0]["duration"] or 0.0
-            sec_dur = probe(p)["duration"] or 0.0
+            ref_dur = input_length(metas[0])
+            sec_dur = input_length(probe(p))
             overlap_end = min(ref_dur, sec_dur + off)
             window = 60.0
             head_len = min(args.analyze_seconds, overlap_end)
@@ -242,7 +243,7 @@ def main() -> int:
 
     if args.min_shot <= 0:
         die(f"--min-shot must be positive, got {args.min_shot:g}")
-    ref_dur = metas[0]["duration"] or 0.0
+    ref_dur = input_length(metas[0])
     energy_mode = args.switch == "energy"
     if energy_mode:
         cuts = energy_switch(args.inputs, metas, offsets, ratios, ref_dur, args.min_shot)
@@ -339,12 +340,17 @@ def main() -> int:
         afx += [f"asetrate={sr * ratios[a]:.6f}", f"aresample={sr}"]
     if offsets[a] > 0:
         afx.append(f"adelay={int(round(offsets[a] * 1000))}:all=1")
-    afx += [f"atrim=0:{ref_dur:.3f}", "aformat=sample_rates=48000:channel_layouts=stereo"]
+    # the sound ends with the reference, to the sample (#493), counted at the 48 kHz it is written
+    # in; `atrim=0:{:.3f}` and `-t {:.3f}` cut it to the millisecond. A dry run's pending reference
+    # has no length to count, and keeps the old filter.
+    conformed = ref_dur > 0
+    afx += [conform_to_length(ref_dur, 48000) if conformed else f"atrim=0:{ref_dur:.3f}",
+            "aformat=sample_rates=48000:channel_layouts=stereo"]
     parts.append(f"[{a}:a]{','.join(afx)}[aout]")
 
     output = args.output or default_output(args.inputs[0], "multicam", "mp4")
     cmd += ["-filter_complex", ";".join(parts), "-map", "[vout]", "-map", "[aout]"]
-    cmd += video_args(metas[0], args.crf, args.preset, convert_matrix=False) + aac_args() + ["-t", f"{ref_dur:.3f}", output]
+    cmd += video_args(metas[0], args.crf, args.preset, convert_matrix=False) + aac_args() + ["-t", conform_output_t(ref_dur, 48000) if conformed else f"{ref_dur:.3f}", output]
 
     if args.write_project:
         # Same cut decision as the combined render above (project_clips was built alongside the

package/scripts/render.py

@@ -393,6 +393,9 @@ def render_pack(names: List[str], args) -> int:
                      "size_bytes": size, "duration": probe_doc.get("duration"),
                      # a destination whose check did not run is "not checked", not "pass" (the class of A113)
                      "check": ("pass" if chk.get("ok") else ("%d FAIL" % chk["failed"]) if chk.get("failed") else ("not checked" if ok else "failed")),
+                     # #485: a destination over the table's upload limit passes its check with a
+                     # WARN; the pack keeps which, so the row is not a bare "pass"
+                     "guidance": guidance_warns(chk),
                      "ok": bool(ok)})
         outputs.append(out)
         if not ok:
@@ -406,7 +409,8 @@ def render_pack(names: List[str], args) -> int:
     for r in rows:
         dur = f"{r['duration']:.2f} s" if r.get("duration") else "-"
         mb = f"{r['size_bytes'] / 1024 / 1024:.1f} MB" if r.get("size_bytes") else "-"
-        lines.append(f"| {r['platform']} | {r['file']} | {mb} | {dur} | {r['check']} |")
+        verdict = r["check"] + (f" (upload-limit guidance: {'; '.join(r['guidance'])})" if r.get("guidance") else "")
+        lines.append(f"| {r['platform']} | {r['file']} | {mb} | {dur} | {verdict} |")
     lines += ["", f"{len(rows)} destinations from one edit ({os.path.basename(args.input)}).",
               "Rendered by ffmpeg-skill; `report.py --pack` turns this table into an HTML report."]
     if not STATE.dry_run:
@@ -1090,7 +1094,9 @@ def execute_plan(plan: Dict[str, Any], path: str) -> int:
         failed_rows = [r["check"] for r in (check_result or {}).get("checks", []) if r.get("status") == "FAIL"]
         info(f"plan done: {output}, but the {check_result.get('platform') or 'content'} check failed" + (f": {', '.join(failed_rows)}" if failed_rows else ""))
     else:
-        info(f"plan done: {output}")
+        advised = guidance_warns(check_result)
+        info(f"plan done: {output}" + (" — upload-limit guidance, the uploader checks the current limit: "
+                                       + "; ".join(advised) if advised else ""))
     # the tool's own steps (export's loudness, ...) come in through absorb_stage() above, tagged
     # with `stage`, so `verified` is theirs and the check's together
     emit(output, plan=path, plan_sha256=digest, unbound_inputs=unbound, tool=tool, stages=[tool] + (["check"] if check_result else []), check=check_result, tool_result=doc,
@@ -1188,6 +1194,14 @@ def _has_sound(current: str, proj: Dict[str, Any], rel: Any) -> bool:
     return False
 
 
+def guidance_warns(check_doc: Optional[Dict[str, Any]]) -> List[str]:
+    """The rows of a check result that are over the platform table's upload limit (#485): WARN,
+    `basis: guidance`. The check passes with them, so each place that says a check passed names
+    them, with the limit, for whoever uploads to compare with the platform's current one."""
+    return [f"{r['check']}={r['value']} (expected {r['expected']})" for r in (check_doc or {}).get("checks", [])
+            if r.get("basis") == "guidance" and r.get("status") == "WARN"]
+
+
 def planned_clip_length(clip: Dict[str, Any], src: str, index: int) -> float:
     """A dry run's length of clip `index` before its speed stage: the source's measured length,
     or its in..out range of it (the cut a real run measures does not exist yet). Only when neither
@@ -1820,7 +1834,10 @@ def main() -> int:
             info(f"check: could not run check.py — {err.get('message') if isinstance(err, dict) else err}")
             exit_code = 1
         else:
-            info(f"check: OK for {check_label}")
+            # #485: over the table's upload limit is a WARN the check passes with; say it here too
+            advised = guidance_warns(check_result)
+            info(f"check: OK for {check_label}" + (" — upload-limit guidance, the uploader checks the current limit: "
+                                                   + "; ".join(advised) if advised else ""))
         stages_done.append("check")
     elif "check" in proj:
         record_skip('the check stage names neither "platform" nor "content": true, so nothing was checked',

package/scripts/scenes.py

@@ -32,6 +32,7 @@ from _common.emit import note, record_fallback  # noqa: E402
 from _common.color import bt709_label_filter  # noqa: E402
 from _common.probe import PROBED_VIDEO, square_pixels  # noqa: E402
 from _common import dry_run_input_pending  # noqa: E402
+from _common.emit import input_length  # noqa: E402
 
 SHOT_FPS = 4.0          # frames/second sampled for --shots' flow estimate
 SHOT_W, SHOT_H = 48, 27  # decode size for --shots (16:9-ish; enough blocks, still a few KB/shot)
@@ -176,7 +177,7 @@ def main() -> int:
             die("--beats needs an audio stream; this file has none", kind="input")
         if args.beat_step <= 0:
             die("--beat-step must be greater than 0", kind="input")
-    dur = meta.get("duration") or 0.0
+    dur = input_length(meta)
     cuts = [0.0] if (audio_only or pending) else detect_scenes(args.input, args.threshold, args.min_scene, dur, args.ratio)
     has_audio = bool(meta.get("audio")) and not pending
     bounds = cuts + [dur]

package/scripts/silence.py

@@ -35,6 +35,7 @@ from _common.emit import refuse
 from _common import detect_silences as detect, STATE, add_common, apply_common, default_output, die, emit, info, is_audio_output, print_json, probe, X264_PRESETS, measured_level_dbfs, fmt_secs
 from _common.decision import frame_rate, stream_starts
 from _common.probe import PROBED_AUDIO
+from _common.emit import input_length
 
 
 
@@ -657,7 +658,7 @@ def main() -> int:
     meta = probe(args.input)
     if not meta.get("audio"):
         die("input has no audio stream to analyse")
-    duration = meta.get("duration") or 0.0
+    duration = input_length(meta)
     breaths: List[Tuple[float, float]] = []
     if args.speech_aware:
         silences, breaths = speech_aware_silences(args.input, args.threshold, args.min_silence)

package/scripts/speedramp.py

@@ -21,6 +21,7 @@ from typing import List, Tuple
 
 from _common.decision import av_trim, frame_durations, frame_rate, grid_at_or_after, stream_starts
 from _common import add_common, apply_common, aac_args, default_output, die, emit, ffmpeg_base, info, probe, run, video_args, X264_PRESETS, fmt_secs, time_arg
+from _common.emit import input_length
 
 MAX_SPEED = 20.0
 MIN_SPEED = 0.05
@@ -72,7 +73,7 @@ def main() -> int:
     meta = probe(args.input)
     if not meta.get("video"):
         die("input has no video stream")
-    dur = meta.get("duration") or 0.0
+    dur = input_length(meta)
     if abs(segments[0][0] - 0.0) > 0.01:
         die(f"segments must start at 0, first segment starts at {segments[0][0]:g}")
     if abs(segments[-1][1] - dur) > 0.5:

package/scripts/sync.py

@@ -38,6 +38,7 @@ from _common.emit import record_skip, warn
 from _common.decision import SEEK_MARGIN, frame_rate, grid_at_or_after, stream_starts
 from _common.timeline import output_timecode_args
 from _common.runner import default_selection_maps
+from _common.emit import input_length
 
 SR = 8000  # decode sample rate
 
@@ -227,8 +228,8 @@ def measure_one(reference: str, path: str, args) -> Dict:
     # the head to measure over) or low_confidence (the tail did not correlate); None when applied
     skipped_reason = None
     if args.fix_drift:
-        ref_dur = probe(reference)["duration"] or 0.0
-        sec_dur = probe(path)["duration"] or 0.0
+        ref_dur = input_length(probe(reference))
+        sec_dur = input_length(probe(path))
         overlap_end = min(ref_dur, sec_dur + offset)
         head_len = min(args.analyze_seconds, overlap_end)
         tail_start = overlap_end - args.drift_window