ffmpeg-skill 3.8.9 → 3.8.11

package/scripts/_common/wrap.py

@@ -145,11 +145,14 @@ JA_PARTICLES = "はがをにでとのへもや"              # a break AFTER one
 # text on each side of a candidate break -- putting them in the character string above turned
 # か, ら, ま, で, よ and り into one-character particles of their own, which none of them is.
 JA_PARTICLE_WORDS = ("から", "まで", "より")
-JA_SENTENCE_END = "。、！？」』）"                  # a break AFTER one of these is preferred
+JA_SENTENCE_END = "。、！？」』），；："            # a break AFTER one of these is preferred (A54: ，；： too)
 # Characters that may never start a line: small kana, the prolonged sound mark, closing brackets
 # and the Japanese punctuation that hangs on the end of the line before it.
-JA_NO_LINE_START = "ぁぃぅぇぉっゃゅょァィゥェォッャュョーヽヾゝゞ、。！？）」』】〕》’”％"
-JA_NO_LINE_END = "（「『【〔《‘“"                   # ... and the ones that may never end a line
+# A54 (#457): the fullwidth comma, semicolon, colon and full stop Chinese uses, and the closing
+# brackets of both, are on the same table: a line that opens with '，' is the same fault as one
+# that opens with '、'.
+JA_NO_LINE_START = "ぁぃぅぇぉっゃゅょァィゥェォッャュョーヽヾゝゞ、。！？）」』】〕》’”％，；：．〉］｝〗"
+JA_NO_LINE_END = "（「『【〔《‘“〈［｛〖"           # ... and the ones that may never end a line
 
 # R4. Function words belong to the phrase that FOLLOWS them: an article or preposition begins the
 # noun phrase it governs, so a break before one is the good break (the word opens the next line
@@ -365,7 +368,7 @@ def _function_words(lang: "Optional[str]") -> "frozenset":
     """R4's table for this language. An unknown or absent language gets the union of the six sets:
     a token that appears in several of them is the same kind of word in each, which is why the
     rule is a penalty and not a refusal."""
-    key = (lang or "").strip().lower().split("-")[0]
+    key = (lang or "").strip().lower().replace("_", "-").split("-")[0]
     if key in FUNCTION_WORDS:
         return frozenset(FUNCTION_WORDS[key])
     return _FUNCTION_WORDS_ANY
@@ -404,7 +407,7 @@ def break_penalty(prev_char: str, next_char: str, lang: "Optional[str]" = None,
     single-character table applies."""
     if not prev_char or not next_char:
         return PENALTY_NEUTRAL
-    script = (lang or "").strip().lower().split("-")[0]
+    script = (lang or "").strip().lower().replace("_", "-").split("-")[0]
     if script not in ("ja", "zh"):
         # A kana on either side settles it: only Japanese has them, and char_script() reads a bare
         # Han character as Chinese, which used to switch the particle rules off for exactly the
@@ -494,14 +497,15 @@ def _gaps(lines: "List[str]", gaps: "Optional[List[bool]]") -> "List[bool]":
 
 
 def _fix_orphans(lines: "List[str]", max_em: float,
-                 gaps: "Optional[List[bool]]" = None) -> "List[str]":
+                 gaps: "Optional[List[bool]]" = None, kinsoku: bool = False) -> "List[str]":
     """No last line that is a single stranded atom.
 
     Greedy wrapping leaves one character alone whenever the line before it filled exactly: eval 14
     produced a Thai cue ending in a lone `ล` and a Japanese one ending in a lone `行`. While the
     last line is one atom narrower than ORPHAN_MIN_EM, the last atom of the line above moves down
     onto it -- but only while the result still fits and the line above does not become an orphan
-    itself, so a two-word cue is never made worse."""
+    itself, so a two-word cue is never made worse. `kinsoku` (phrase mode) moves a punctuation
+    mark down only with the character it closes (_kinsoku_atoms)."""
     lines = list(lines)
     gaps = _gaps(lines, gaps)
     for _ in range(len(lines)):
@@ -510,7 +514,7 @@ def _fix_orphans(lines: "List[str]", max_em: float,
         tail = _atoms(lines[-1])
         if len(tail) != 1 or text_width_em(lines[-1]) >= ORPHAN_MIN_EM:
             break
-        prev = _atoms(lines[-2])
+        prev = _kinsoku_atoms(_atoms(lines[-2])) if kinsoku else _atoms(lines[-2])
         if len(prev) < 2:
             break
         moved, spaced = prev[-1]
@@ -532,14 +536,15 @@ def _fix_weak_lines(lines: "List[str]", max_em: float,
     1.15 only ever looked at the last line, so a stranded digit or kana in the middle of a
     three-line cue survived. Walking upward from the last line, while a line is weak the last atom
     of the line above moves down onto it -- with 1.15's two guards intact (the result must still
-    fit, and the line above must not itself become weak), so the line count never changes."""
+    fit, and the line above must not itself become weak), so the line count never changes. A
+    punctuation mark moves down only with the character it closes (_kinsoku_atoms, A54)."""
     lines = list(lines)
     gaps = _gaps(lines, gaps)
     for i in range(len(lines) - 1, 0, -1):
         for _ in range(len(lines)):
             if not _is_weak_line(lines[i]):
                 break
-            prev = _atoms(lines[i - 1])
+            prev = _kinsoku_atoms(_atoms(lines[i - 1]))
             if len(prev) < 2:
                 break
             moved, spaced = prev[-1]
@@ -633,9 +638,36 @@ def _rebalance_phrase(lines: "List[str]", max_em: float, lang: "Optional[str]",
     return out, moved
 
 
+def _kinsoku_atoms(atoms: "List[Tuple[str, bool]]") -> "List[Tuple[str, bool]]":
+    """The atom list with each no-line-start character joined to the atom before it, and each
+    no-line-end character to the atom after it, where no space stands between them.
+
+    The phrase passes only ever choose among breaks that fit, so a forbidden break the greedy fill
+    had already taken stayed whenever no pass reconsidered it: a cue of three lines or more, or
+    the pieces of a cue split past --max-lines, opened a line with '、', '，' or '。' (A54, #457).
+    Joined, the fill carries the character before the punctuation onto the next line with it."""
+    split: "List[Tuple[str, bool]]" = []
+    for atom, spaced in atoms:
+        # the atomiser reads a run of CJK punctuation as one Latin word ('。（'): part it where a
+        # closing mark meets an opening one, so each half can join its own neighbour
+        start = 0
+        for k in range(1, len(atom)):
+            if atom[k - 1] in JA_NO_LINE_START and atom[k] in JA_NO_LINE_END:
+                split.append((atom[start:k], spaced if start == 0 else False))
+                start = k
+        split.append((atom[start:], spaced if start == 0 else False))
+    out: "List[Tuple[str, bool]]" = []
+    for atom, spaced in split:
+        if out and not spaced and (atom[0] in JA_NO_LINE_START or out[-1][0][-1] in JA_NO_LINE_END):
+            out[-1] = (out[-1][0] + atom, out[-1][1])
+        else:
+            out.append((atom, spaced))
+    return out
+
+
 def _greedy_chunks(raw: str, max_em: float, *, slice_overlong: bool = False,
                    sliced: "Optional[List[int]]" = None,
-                   gaps: "Optional[List[bool]]" = None) -> "List[str]":
+                   gaps: "Optional[List[bool]]" = None, kinsoku: bool = False) -> "List[str]":
     """The greedy fill on its own: the line count every mode must keep.
 
     `slice_overlong` (off by default -- only caption.py's final burn-in pass turns it on, never
@@ -647,7 +679,10 @@ def _greedy_chunks(raw: str, max_em: float, *, slice_overlong: bool = False,
     `broken_inside_word` without re-deriving it from the output lines.
 
     `gaps`, when given, is filled with one flag per break: did a space stand there in `raw`? The
-    passes in _balance() carry it, so a break they move keeps (or drops) exactly that space."""
+    passes in _balance() carry it, so a break they move keeps (or drops) exactly that space.
+
+    `kinsoku` (phrase mode) never breaks before a no-line-start or after a no-line-end character
+    (_kinsoku_atoms); `measured` keeps 1.15's fill."""
     current = ""
     current_gap = False   # did a space stand before `current`'s first atom
     chunk: "List[str]" = []
@@ -671,7 +706,7 @@ def _greedy_chunks(raw: str, max_em: float, *, slice_overlong: bool = False,
                 return pieces[-1], False
         return atom, spaced
 
-    for atom, spaced in _atoms(raw):
+    for atom, spaced in (_kinsoku_atoms(_atoms(raw)) if kinsoku else _atoms(raw)):
         if not current:
             current, current_gap = start_line(atom, spaced)
             continue
@@ -699,7 +734,7 @@ def _balance(chunk: "List[str]", max_em: float, mode: str, lang: "Optional[str]"
         fixed = _fix_orphans(chunk, max_em, gaps)
         rebalanced = _rebalance(fixed, max_em, list(gaps) if gaps is not None else None)
     else:
-        fixed = _fix_weak_lines(_fix_orphans(chunk, max_em, gaps), max_em, gaps)
+        fixed = _fix_weak_lines(_fix_orphans(chunk, max_em, gaps, kinsoku=True), max_em, gaps)
         later = list(gaps) if gaps is not None else None
         rebalanced, _moved = _rebalance_phrase(fixed, max_em, lang, later)
         rebalanced = _fix_weak_lines(rebalanced, max_em, later)
@@ -729,7 +764,8 @@ def wrap_text(text: str, max_em: float, *, balance: bool = True, mode: str = "ph
         if not raw.strip():
             continue
         gaps: "List[bool]" = []
-        chunk = _greedy_chunks(raw, max_em, slice_overlong=slice_overlong, sliced=sliced, gaps=gaps)
+        chunk = _greedy_chunks(raw, max_em, slice_overlong=slice_overlong, sliced=sliced, gaps=gaps,
+                               kinsoku=mode == "phrase")
         lines.extend(_balance(chunk, max_em, mode, lang, gaps) if balance else chunk)
     return lines or [text]
 def wrap_variants(text: str, max_em: float, *, mode: str = "phrase",
@@ -750,11 +786,17 @@ def wrap_variants(text: str, max_em: float, *, mode: str = "phrase",
         if not raw.strip():
             continue
         gaps: "List[bool]" = []
-        chunk = _greedy_chunks(raw, max_em, slice_overlong=slice_overlong, sliced=sliced, gaps=gaps)
+        chunk = _greedy_chunks(raw, max_em, slice_overlong=slice_overlong, sliced=sliced, gaps=gaps,
+                               kinsoku=mode == "phrase")
         greedy.extend(chunk)
         wrapped.extend(_balance(list(chunk), max_em, mode, lang, gaps))
-        measured.extend(chunk if mode == "measured"
-                        else _balance(list(chunk), max_em, "measured", None, gaps))
+        if mode == "measured":
+            measured.extend(chunk)
+        else:
+            # 1.15's wrap fills without the kinsoku joins (A54), so it is filled on its own
+            plain_gaps: "List[bool]" = []
+            plain = _greedy_chunks(raw, max_em, slice_overlong=slice_overlong, gaps=plain_gaps)
+            measured.extend(_balance(plain, max_em, "measured", None, plain_gaps))
     if not greedy:
         greedy = [text]
     return (wrapped or [text], greedy, measured or [text])

package/scripts/_contract.py

@@ -489,7 +489,7 @@ DIAGNOSTIC_CODES = {
     "emoji_not_drawn": ("warnings", "caption.py / graphics.py --emoji auto: no glyph, colour path or PNG asset draws these emoji here (doctor fonts.emoji mode none), so they were left out of the drawn text; also graphics.py --text-render drawtext, which has no font fallback; {count, reason}"),
     "emoji_mono_drawn_in_colour": ("warnings", "caption.py / graphics.py --emoji mono on a build whose libass draws the emoji face in colour: nothing makes the glyph monochrome, so the result's emoji.mode is color (graphics.py --text-render drawtext draws none: mode none, emoji_not_drawn)"),
     "hdr10_metadata_dropped": ("warnings", "a PQ output measured without the source's HDR10 mastering-display and/or content-light metadata (an encoder with no option for it, e.g. prores_ks or libaom on FFmpeg before 7); {dropped, codec}"),
-    "source_items_dropped": ("warnings", "the written file lacks a subtitle track, chapters, a cover picture or surround channels the first input carried (source_carry lists everything kept and dropped, tags included); not repeated for a subtitle track the tool already reports through dropped_non_av_streams; {dropped}"),
+    "source_items_dropped": ("warnings", "the written file lacks a subtitle track, chapters, a cover picture, surround channels, attached files or a second video stream the first input carried (source_carry lists everything kept and dropped, tags included); not repeated for a subtitle track the tool already reports through dropped_non_av_streams; {dropped}"),
     "audio_tracks_dropped": ("warnings", "the source has more audio tracks than the output kept (the tools write one; cut.py also reports dropped_audio_streams). Not compared when two or more inputs have sound (grid --audio-from, a mix): which source the output carries is the tool's choice; {source, kept, dropped}"),
     "grid_no_drawtext": ("fallbacks", "grid.py --label auto on a build without the drawtext filter: the cells were not labelled, as with --label none"),
     "scenes_sheet_no_drawtext": ("fallbacks", "scenes.py --sheet on a build without the drawtext filter: the sheet was drawn without timecode stamps, as with --no-timecode"),
@@ -689,7 +689,7 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
                                "levels": {"type": "object", "description": "--analyze only, on an input with a video stream: picture levels sampled at 2 fps over the first 20 s, on an 8-bit scale inferred from the values measured (a 10-bit or deeper picture whose luma never passes code 255 is read as 8-bit and left unscaled) {scale, y_min, y_max, y_avg, y_low_p5, y_high_p95, saturation_avg, looks_like_log, note}; {error} when no frame was analysed. Measured under --dry-run too"}},
                 "additionalProperties": True}
     base = {"status": {"enum": ["completed"]}, "output": {"type": ["string", "null"], "description": "path written, or null"},
-            "dry_run": {"type": "boolean"}, "commands": {"type": "array", "items": {"type": "string"}, "description": "the ffmpeg command lines this run planned or ran to write its output (render.py and waveform.py: their stages' too); a measurement pass is listed only where the tool records it (e.g. loudness.py pass 1, check.py, stabilize.py pass 1), and batch.py lists none of its steps' (each results row's step documents carry their own)"},
+            "dry_run": {"type": "boolean"}, "commands": {"type": "array", "items": {"type": "string"}, "description": "the ffmpeg command lines this run planned or ran to write its output (render.py and waveform.py: their stages' too), shell-quoted; a line that names a file the tool wrote for the run and removed when it exited (such as a concat list, an ffmetadata file, a drawtext text file, a two-pass log or a stage's intermediate) cannot be run again as printed; a measurement pass is listed only where the tool records it (e.g. loudness.py pass 1, check.py, stabilize.py pass 1), and batch.py lists none of its steps' (each results row's step documents carry their own)"},
             "probe": {"type": "object", "description": "probe of the output when a file was written"},
             "output_identity": {"type": "object", "description": "2.24: {size, mtime_ns} of the file this run wrote, absent under --dry-run; pass it to check.py --expect-identity SIZE:MTIME_NS so the check grades this file and not whatever later sits at the path"},
             "encoder": {"type": "string", "description": "the video encoder the last ffmpeg command used (after any GPU->CPU fallback; under --dry-run the planned one; render.py and waveform.py: their stages' commands included), `copy` for a stream copy; absent when no command encoded video"},
@@ -698,7 +698,7 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
             "verified": {"type": "boolean", "description": "true only when the artifact was written, probed, and every self-check the tool ran (verification) met its target; false under --dry-run"},
             "verification": {"type": "array", "items": {"type": "object", "properties": {"step": {"type": "string"}, "ok": {"type": "boolean"}, "stage": {"type": "string"}, "property": {"type": "string"}, "expected": {}, "measured": {}, "delta": {}, "tolerance": {}, "provenance": {"enum": ["specification", "user_specified", "independent_measurement", "input_premeasurement"]}, "attribution": {"enum": ["artifact", "reference", "instrument", "provenance", "unresolved"]}}}, "description": "what the tool itself verified: probe, plus loudness (loudness.py, export platform presets; ok false with reason not_measured when it could not be read), check (render), report.py's sections (loudness, compliance, contact_sheet) and batch.py's items (item). render.py also lists every stage's own steps beyond its artifact probe, tagged with `stage` (a cached stage's as recorded), so its `verified` is the conjunction of every stage's. Since 2.18 a step may carry the property it measured with expected, measured, delta, tolerance and the provenance of the expected value; cut, join and export add a `streams` step comparing the output's video/audio streams with the input's; a step with ok false carries `attribution` (unresolved until a tool knows the cause)"},
             "unverified": {"type": "array", "items": {"type": "string"}, "description": "2.18: the properties of the output this tool did not measure (the unverified range), e.g. caption's rendered_placement; `verified` covers the measured properties only"},
-            "source_carry": {"type": "object", "description": "what the first input carried besides its picture and sound, compared with the written file: {kept: [...], dropped: [...]} over subtitles, chapters, cover_art, audio_channels (a surround source only), creation_time, audio_language, timecode (kept only when the written start timecode is the label of the frame the output starts on: the source's own, or moved there by a tool that moved the picture's start; a join of several ranges writes none). Present only when the source had at least one of them; absent under --dry-run, for a still or GIF output, and when two or more inputs have a picture or sound. A report, not a check: `verified` does not depend on it. A dropped subtitles/chapters/cover_art/audio_channels also records a source_items_dropped warning"},
+            "source_carry": {"type": "object", "description": "what the first input carried besides its picture and sound, compared with the written file: {kept: [...], dropped: [...]} over subtitles, chapters, cover_art, audio_channels (a surround source only), attachments (Matroska attached files, such as a subtitle track's fonts), video_streams (a source with more than one playable picture), creation_time, audio_language, timecode (kept only when the written start timecode is the label of the frame the output starts on: the source's own, or moved there by a tool that moved the picture's start; a join of several ranges writes none). Present only when the source had at least one of them; absent under --dry-run, for a still or GIF output, and when two or more inputs have a picture or sound (render.py: a project whose clips are one file, with no music, replacement, effects track or video layer, is compared with that file). A report, not a check: `verified` does not depend on it. A dropped subtitles/chapters/cover_art/audio_channels/attachments/video_streams also records a source_items_dropped warning"},
             "diagnostics": DIAGNOSTICS_SCHEMA}
     extra: Dict[str, Any] = {}
     if name == "check":

package/scripts/background.py

@@ -22,6 +22,35 @@ from _common.emit import note
 from _common import STATE,  add_common, apply_common, die, draws_chroma, emit, ffmpeg_base, info, parse_time, probe, rgb_chain_to_bt709, run, validate_color, video_args, X264_PRESETS, time_arg, fmt_secs
 
 
+def gradient_source(w: int, h: int, fps: float, c0: str, c1: str, angle: float) -> str:
+    """The `gradients` source for a `w`x`h` gradient at `angle` degrees (0 = left to right, 90 =
+    top to bottom) that runs from the frame's first corner along that direction to its last: c0
+    on the corner the direction starts from, c1 on the one opposite.
+
+    `gradients` takes its two points inside its own frame: a coordinate below -1 is refused and
+    one outside 0..w-1 / 0..h-1 is replaced by a seeded random one. The points were (0, 0) and the
+    width along the angle, so every angle outside 0-90 failed as kind ffmpeg (135 put x1 at -45:
+    A169), and inside it the far point was past the frame (x1 = w at 0, y1 = w at 90) and drawn
+    from the seed instead. A line of any direction that crosses the whole frame fits inside a
+    square canvas as wide as the frame's diagonal, so the gradient is drawn there, through the
+    centre, over the frame's extent along the direction (w|cos| + h|sin|), and the frame is cropped
+    from the middle."""
+    rad = math.radians(angle)
+    c, s = math.cos(rad), math.sin(rad)
+    side = 2 * math.ceil((math.hypot(w, h) + 4) / 2)  # even, so the centred crop is whole pixels
+    half = (w * abs(c) + h * abs(s)) / 2
+    mid = side / 2
+    x0, y0, x1, y1 = (round(mid - half * c), round(mid - half * s), round(mid + half * c), round(mid + half * s))
+    # gradients defaults to seed=-1 (a random seed picked fresh each run) and speed=0.01 (a
+    # slow rotation applied every frame), so without pinning both, this "static" background
+    # was neither reproducible between runs nor actually static across its own duration --
+    # violating the bit_exact/deterministic contract _contract.py declares for this tool.
+    # speed's own valid range bottoms out at 1e-05 (0 is refused), so that's the closest to
+    # motionless the filter allows.
+    return (f"gradients=size={side}x{side}:rate={fps:g}:c0={c0}:c1={c1}:x0={x0}:y0={y0}:x1={x1}:y1={y1}"
+            f":seed=0:speed=1e-05,crop={w}:{h}:{(side - w) // 2}:{(side - h) // 2}")
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("-o", "--output", required=True, help="output file")
@@ -66,16 +95,7 @@ def main() -> int:
             die(f"--gradient needs two colours as C1:C2, got '{args.gradient}'")
         validate_color(c0, "--gradient")
         validate_color(c1, "--gradient")
-        rad = math.radians(args.angle)
-        x1 = round(args.width * math.cos(rad))
-        y1 = round(args.width * math.sin(rad))
-        # gradients defaults to seed=-1 (a random seed picked fresh each run) and speed=0.01 (a
-        # slow rotation applied every frame), so without pinning both, this "static" background
-        # was neither reproducible between runs nor actually static across its own duration --
-        # violating the bit_exact/deterministic contract _contract.py declares for this tool.
-        # speed's own valid range bottoms out at 1e-05 (0 is refused), so that's the closest to
-        # motionless the filter allows.
-        src_filter = f"gradients=size={args.width}x{args.height}:rate={args.fps:g}:c0={c0}:c1={c1}:x0=0:y0=0:x1={x1}:y1={y1}:seed=0:speed=1e-05"
+        src_filter = gradient_source(args.width, args.height, args.fps, c0, c1, args.angle)
         colours = [c0, c1]
     else:
         validate_color(args.color, "--color")

package/scripts/broll.py

@@ -105,9 +105,15 @@ def main() -> int:
         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"]:
-            die(f"cutaway {i + 1} at {at:g}s overlaps the previous one (ends {cutaways[-1]['at'] + cutaways[-1]['length']:g}s)")
         cutaways.append({"path": path, "at": at, "length": length, "from": start_b, "has_audio": bool(meta_b.get("audio")), "meta": meta_b})
+    # overlap is a property of the windows in time, not of the order they were given in: compared
+    # against the one given before it, a later window listed first was called overlapping (A179)
+    order = sorted(range(len(cutaways)), key=lambda k: cutaways[k]["at"])
+    for prev, k in zip(order, order[1:]):
+        end_prev = cutaways[prev]["at"] + cutaways[prev]["length"]
+        if cutaways[k]["at"] < end_prev:
+            die(f"cutaway {k + 1} at {cutaways[k]['at']:g}s overlaps cutaway {prev + 1} "
+                f"({cutaways[prev]['at']:g}s to {end_prev:g}s)")
     if args.audio != "a" and not all(c["has_audio"] for c in cutaways):
         die("--audio b/mix needs audio on every B-roll clip")