davinci-resolve-mcp 2.67.0 → 2.68.0

package/src/utils/captions.py

@@ -0,0 +1,323 @@
+"""Caption generation from word timings: SRT / WebVTT under broadcast rules.
+
+Turning a transcript into captions is not line-wrapping. A caption that is
+technically synchronised but breaks mid-clause, orphans a word, or sits on
+screen for nine seconds fails QC and is unreadable, so the rules a human
+captioner follows are encoded here rather than left to the caller:
+
+- a character cap per line, and a cap on lines per block;
+- a maximum and a **minimum** block duration — a 4-frame flash is unreadable
+  even though it is perfectly in sync;
+- breaks preferred at sentence ends, then at clause boundaries, then at long
+  pauses, and only then on length alone;
+- timings snapped to the words actually spoken, never interpolated;
+- a minimum gap between blocks so consecutive captions do not visually merge;
+- no single-word orphan line.
+
+## Reading rate is a cap, not a target
+
+Blocks are extended toward `min_block_seconds` when the words are quick, but
+never past the next block's start. A caption that overruns its successor is
+worse than a short one.
+
+## Frame rates
+
+SRT and WebVTT both carry wall-clock timestamps, so nothing here needs a frame
+rate. Retiming across rates is a separate concern and deliberately not folded
+in — a caption file that has been silently conformed is very hard to debug.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, List, Optional, Sequence
+
+#: Broadcast-conventional defaults. Every one is overridable per call.
+DEFAULT_MAX_CHARS_PER_LINE = 42
+DEFAULT_MAX_LINES = 2
+DEFAULT_MAX_BLOCK_SECONDS = 7.0
+DEFAULT_MIN_BLOCK_SECONDS = 0.833  # ~20 frames at 24fps; below this is a flash
+DEFAULT_MIN_GAP_SECONDS = 0.084  # ~2 frames, so blocks do not visually merge
+#: A silence at least this long is a natural caption break.
+DEFAULT_PAUSE_BREAK_SECONDS = 0.6
+
+_SENTENCE_END_RE = re.compile(r"[.!?]['\"”’)]*$")
+_CLAUSE_END_RE = re.compile(r"[,;:—-]['\"”’)]*$")
+
+FORMATS = ("srt", "vtt")
+
+
+class CaptionError(ValueError):
+    """Invalid caption parameters — refused rather than silently clamped."""
+
+
+def _word_time(word: Dict[str, Any], key: str, fallback: str) -> Optional[float]:
+    value = word.get(key, word.get(fallback))
+    return float(value) if isinstance(value, (int, float)) else None
+
+
+def _clean(word: Dict[str, Any]) -> str:
+    return str(word.get("word") or "").strip()
+
+
+def _wrap(text: str, max_chars: int, max_lines: int) -> Optional[List[str]]:
+    """Greedy wrap; None when it will not fit in `max_lines`.
+
+    Returning None rather than truncating is deliberate — silently dropping
+    words from a caption is the worst possible failure for accessibility.
+    """
+    lines: List[str] = []
+    current = ""
+    for token in text.split():
+        candidate = f"{current} {token}".strip()
+        if len(candidate) <= max_chars:
+            current = candidate
+            continue
+        if current:
+            lines.append(current)
+        current = token
+        if len(current) > max_chars:
+            return None  # a single token longer than the line cap
+    if current:
+        lines.append(current)
+    return lines if len(lines) <= max_lines else None
+
+
+def _no_orphan(lines: List[str]) -> List[str]:
+    """Rebalance so no line is a lone word when a neighbour could give one up."""
+    if len(lines) < 2:
+        return lines
+    if len(lines[-1].split()) == 1 and len(lines[-2].split()) > 2:
+        head = lines[-2].split()
+        lines = lines[:-2] + [" ".join(head[:-1]), f"{head[-1]} {lines[-1]}"]
+    return lines
+
+
+def _break_score(word: Dict[str, Any], gap_after: float, pause_break: float) -> int:
+    """Higher is a better place to end a caption block."""
+    text = _clean(word)
+    if _SENTENCE_END_RE.search(text):
+        return 3
+    if gap_after >= pause_break:
+        return 2
+    if _CLAUSE_END_RE.search(text):
+        return 1
+    return 0
+
+
+def build_blocks(
+    words: Sequence[Dict[str, Any]],
+    *,
+    max_chars_per_line: int = DEFAULT_MAX_CHARS_PER_LINE,
+    max_lines: int = DEFAULT_MAX_LINES,
+    max_block_seconds: float = DEFAULT_MAX_BLOCK_SECONDS,
+    min_block_seconds: float = DEFAULT_MIN_BLOCK_SECONDS,
+    min_gap_seconds: float = DEFAULT_MIN_GAP_SECONDS,
+    pause_break_seconds: float = DEFAULT_PAUSE_BREAK_SECONDS,
+) -> List[Dict[str, Any]]:
+    """Group words into caption blocks obeying every rule above."""
+    if max_chars_per_line < 8:
+        raise CaptionError("max_chars_per_line below 8 cannot hold readable text")
+    if max_lines < 1:
+        raise CaptionError("max_lines must be at least 1")
+    if min_block_seconds > max_block_seconds:
+        raise CaptionError("min_block_seconds cannot exceed max_block_seconds")
+
+    timed = [
+        w for w in words
+        if _clean(w) and _word_time(w, "start_seconds", "start") is not None
+    ]
+    if not timed:
+        return []
+
+    capacity = max_chars_per_line * max_lines
+    blocks: List[Dict[str, Any]] = []
+    current: List[Dict[str, Any]] = []
+
+    def flush() -> None:
+        if not current:
+            return
+        text = " ".join(_clean(w) for w in current)
+        lines = _wrap(text, max_chars_per_line, max_lines)
+        if lines is None:
+            lines = [text[:max_chars_per_line]]
+        blocks.append({
+            "start_seconds": _word_time(current[0], "start_seconds", "start"),
+            "end_seconds": (
+                _word_time(current[-1], "end_seconds", "end")
+                or _word_time(current[-1], "start_seconds", "start")
+            ),
+            "lines": _no_orphan(lines),
+            "word_count": len(current),
+        })
+        current.clear()
+
+    for index, word in enumerate(timed):
+        current.append(word)
+        following = timed[index + 1] if index + 1 < len(timed) else None
+        if following is None:
+            break
+
+        this_end = _word_time(word, "end_seconds", "end") or _word_time(word, "start_seconds", "start")
+        next_start = _word_time(following, "start_seconds", "start")
+        gap = max(0.0, (next_start or 0.0) - (this_end or 0.0))
+
+        text_now = " ".join(_clean(w) for w in current)
+        text_next = f"{text_now} {_clean(following)}"
+        block_start = _word_time(current[0], "start_seconds", "start") or 0.0
+        would_be_long = ((next_start or 0.0) - block_start) > max_block_seconds
+        would_not_fit = len(text_next) > capacity or _wrap(text_next, max_chars_per_line, max_lines) is None
+
+        score = _break_score(word, gap, pause_break_seconds)
+        # Sentence ends and real pauses always break. A block that spans a
+        # silence leaves text on screen through it, which is the thing captioners
+        # break on — and short blocks are already made readable by the
+        # min_block_seconds extension below, so no length guard is needed here.
+        # Clause breaks (score 1) are only a preference and never force a flush.
+        if would_not_fit or would_be_long or score >= 2:
+            flush()
+    flush()
+
+    # Extend short blocks toward the readable minimum, never into the next one.
+    for index, block in enumerate(blocks):
+        limit = (
+            blocks[index + 1]["start_seconds"] - min_gap_seconds
+            if index + 1 < len(blocks)
+            else block["end_seconds"] + min_block_seconds
+        )
+        if block["end_seconds"] - block["start_seconds"] < min_block_seconds:
+            block["end_seconds"] = max(block["end_seconds"], min(block["start_seconds"] + min_block_seconds, limit))
+        # Enforce the inter-block gap even when no extension happened.
+        if index + 1 < len(blocks):
+            block["end_seconds"] = min(block["end_seconds"], blocks[index + 1]["start_seconds"] - min_gap_seconds)
+        block["end_seconds"] = max(block["end_seconds"], block["start_seconds"] + 1e-3)
+        block["start_seconds"] = round(block["start_seconds"], 3)
+        block["end_seconds"] = round(block["end_seconds"], 3)
+        block["duration_seconds"] = round(block["end_seconds"] - block["start_seconds"], 3)
+    return blocks
+
+
+# ── serialisation ────────────────────────────────────────────────────────────
+
+
+def _timestamp(seconds: float, *, comma: bool) -> str:
+    seconds = max(0.0, float(seconds))
+    hours, rest = divmod(seconds, 3600.0)
+    minutes, secs = divmod(rest, 60.0)
+    millis = int(round((secs - int(secs)) * 1000))
+    if millis == 1000:  # rounding carried into the next second
+        secs, millis = int(secs) + 1, 0
+    sep = "," if comma else "."
+    return f"{int(hours):02d}:{int(minutes):02d}:{int(secs):02d}{sep}{millis:03d}"
+
+
+def to_srt(blocks: Sequence[Dict[str, Any]]) -> str:
+    out: List[str] = []
+    for index, block in enumerate(blocks, start=1):
+        out.append(str(index))
+        out.append(
+            f"{_timestamp(block['start_seconds'], comma=True)} --> "
+            f"{_timestamp(block['end_seconds'], comma=True)}"
+        )
+        out.extend(block["lines"])
+        out.append("")
+    return "\n".join(out)
+
+
+def to_vtt(blocks: Sequence[Dict[str, Any]]) -> str:
+    out: List[str] = ["WEBVTT", ""]
+    for block in blocks:
+        out.append(
+            f"{_timestamp(block['start_seconds'], comma=False)} --> "
+            f"{_timestamp(block['end_seconds'], comma=False)}"
+        )
+        out.extend(block["lines"])
+        out.append("")
+    return "\n".join(out)
+
+
+def render(blocks: Sequence[Dict[str, Any]], fmt: str) -> str:
+    if fmt not in FORMATS:
+        raise CaptionError(f"unknown caption format {fmt!r}; valid: {', '.join(FORMATS)}")
+    return to_srt(blocks) if fmt == "srt" else to_vtt(blocks)
+
+
+# ── chapters ─────────────────────────────────────────────────────────────────
+
+
+def chapters_from_blocks(
+    blocks: Sequence[Dict[str, Any]],
+    *,
+    min_spacing_seconds: float = 30.0,
+    max_title_chars: int = 60,
+) -> List[Dict[str, Any]]:
+    """Derive chapters from caption blocks by topic-shift heuristic.
+
+    A long pause landing on a sentence start is the cheapest usable signal for
+    "new topic". This is explicitly a heuristic — it produces a starting point
+    an editor renames, not a finished chapter list.
+
+    The first chapter is always forced to 00:00 because that is a hard
+    requirement of the YouTube description format, not a stylistic choice.
+    """
+    if not blocks:
+        return []
+    chapters: List[Dict[str, Any]] = [{
+        "start_seconds": 0.0,
+        "title": " ".join(blocks[0]["lines"])[:max_title_chars].strip(),
+    }]
+    for previous, block in zip(blocks, blocks[1:]):
+        gap = block["start_seconds"] - previous["end_seconds"]
+        if gap < DEFAULT_PAUSE_BREAK_SECONDS:
+            continue
+        if block["start_seconds"] - chapters[-1]["start_seconds"] < min_spacing_seconds:
+            continue
+        chapters.append({
+            "start_seconds": round(block["start_seconds"], 3),
+            "title": " ".join(block["lines"])[:max_title_chars].strip(),
+        })
+    return chapters
+
+
+def chapters_to_youtube(chapters: Sequence[Dict[str, Any]]) -> str:
+    """YouTube description text. Always starts at 00:00 or YouTube ignores it."""
+    lines = []
+    for chapter in chapters:
+        total = int(chapter["start_seconds"])
+        hours, rest = divmod(total, 3600)
+        minutes, secs = divmod(rest, 60)
+        stamp = f"{hours}:{minutes:02d}:{secs:02d}" if hours else f"{minutes}:{secs:02d}"
+        lines.append(f"{stamp} {chapter['title']}".rstrip())
+    return "\n".join(lines)
+
+
+def generate(
+    words: Sequence[Dict[str, Any]],
+    *,
+    fmt: str = "srt",
+    with_chapters: bool = False,
+    **options: Any,
+) -> Dict[str, Any]:
+    """Word timings → caption text plus the block list and optional chapters."""
+    if fmt not in FORMATS:
+        raise CaptionError(f"unknown caption format {fmt!r}; valid: {', '.join(FORMATS)}")
+    blocks = build_blocks(words, **options)
+    if not blocks:
+        return {
+            "success": False,
+            "error": "No timed words to caption.",
+            "remediation": "Run transcription for this clip first, then retry.",
+        }
+    result: Dict[str, Any] = {
+        "success": True,
+        "format": fmt,
+        "text": render(blocks, fmt),
+        "blocks": blocks,
+        "block_count": len(blocks),
+        "duration_seconds": round(blocks[-1]["end_seconds"], 3),
+    }
+    if with_chapters:
+        chapters = chapters_from_blocks(blocks)
+        result["chapters"] = chapters
+        result["chapters_youtube"] = chapters_to_youtube(chapters)
+    return result

package/src/utils/colorimetry.py

@@ -0,0 +1,196 @@
+"""Display-referred colour science: sRGB ↔ linear ↔ XYZ ↔ CIE Lab (D65), ΔE2000.
+
+Pure numpy, no third-party colour library, so the conversions can be unit-tested
+against published reference values rather than trusted.
+
+Everything here is **display-referred**. RGB is float in [0, 1] with an sRGB
+transfer function; Lab is L* in [0, 100] with a/b roughly [-128, 128]. Feeding
+log or scene-referred RGB (ACEScct, S-Log3, LogC) through these functions
+produces numbers that look plausible and mean nothing — `image_qc` is the layer
+that refuses that case, and it refuses rather than converting silently because
+the correct conversion depends on a transform this module cannot know.
+
+ΔE2000 is implemented rather than ΔE76 because ΔE76 badly under-weights hue
+error in the blues and over-weights chroma error in saturated colours, and any
+number a human reads as "how close is this" should not carry that distortion.
+The implementation is validated against the Sharma/Wu/Dalal (2005) test set,
+which is specifically constructed to exercise the hue-rotation and chroma
+discontinuities where naive implementations disagree.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+# sRGB (IEC 61966-2-1) companding thresholds.
+_SRGB_THRESH = 0.04045
+_SRGB_LIN_THRESH = 0.0031308
+
+# sRGB primaries → XYZ (D65).
+_RGB2XYZ = np.array(
+    [
+        [0.4124564, 0.3575761, 0.1804375],
+        [0.2126729, 0.7151522, 0.0721750],
+        [0.0193339, 0.1191920, 0.9503041],
+    ],
+    dtype=np.float64,
+)
+_XYZ2RGB = np.linalg.inv(_RGB2XYZ)
+
+#: D65 reference white, derived from the matrix rather than quoted.
+#:
+#: The usual rounded literal [0.95047, 1.0, 1.08883] is *not* exactly the white
+#: this matrix produces from RGB 1,1,1 — they disagree in the 6th decimal, which
+#: leaves sRGB white landing at L* = 100.0000039 with a non-zero a*/b*. Deriving
+#: it keeps the two constants consistent by construction, so white is exactly
+#: neutral and the Lab round-trip closes.
+_D65 = _RGB2XYZ @ np.ones(3, dtype=np.float64)
+
+# CIE Lab constants, in the exact-rational form (CIE 15:2004) rather than the
+# rounded 0.008856 / 903.3 that older references use — the rounded pair puts a
+# small discontinuity at the linear/cube-root join.
+_LAB_EPS = 216.0 / 24389.0  # (6/29)^3
+_LAB_KAPPA = 24389.0 / 27.0  # (29/3)^3
+
+
+def srgb_to_linear(rgb: np.ndarray) -> np.ndarray:
+    rgb = np.asarray(rgb, dtype=np.float64)
+    return np.where(rgb <= _SRGB_THRESH, rgb / 12.92, ((rgb + 0.055) / 1.055) ** 2.4)
+
+
+def linear_to_srgb(rgb: np.ndarray) -> np.ndarray:
+    rgb = np.asarray(rgb, dtype=np.float64)
+    return np.where(
+        rgb <= _SRGB_LIN_THRESH,
+        rgb * 12.92,
+        1.055 * np.power(np.clip(rgb, 0.0, None), 1.0 / 2.4) - 0.055,
+    )
+
+
+def linear_to_xyz(rgb_lin: np.ndarray) -> np.ndarray:
+    return np.asarray(rgb_lin, dtype=np.float64) @ _RGB2XYZ.T
+
+
+def xyz_to_linear(xyz: np.ndarray) -> np.ndarray:
+    return np.asarray(xyz, dtype=np.float64) @ _XYZ2RGB.T
+
+
+def _f_forward(t: np.ndarray) -> np.ndarray:
+    return np.where(t > _LAB_EPS, np.cbrt(t), (_LAB_KAPPA * t + 16.0) / 116.0)
+
+
+def _f_inverse(f: np.ndarray) -> np.ndarray:
+    f3 = f**3
+    return np.where(f3 > _LAB_EPS, f3, (116.0 * f - 16.0) / _LAB_KAPPA)
+
+
+def xyz_to_lab(xyz: np.ndarray) -> np.ndarray:
+    scaled = np.asarray(xyz, dtype=np.float64) / _D65
+    fx, fy, fz = (_f_forward(scaled[..., i]) for i in range(3))
+    return np.stack([116.0 * fy - 16.0, 500.0 * (fx - fy), 200.0 * (fy - fz)], axis=-1)
+
+
+def lab_to_xyz(lab: np.ndarray) -> np.ndarray:
+    lab = np.asarray(lab, dtype=np.float64)
+    fy = (lab[..., 0] + 16.0) / 116.0
+    fx = fy + lab[..., 1] / 500.0
+    fz = fy - lab[..., 2] / 200.0
+    return np.stack([_f_inverse(fx) * _D65[0], _f_inverse(fy) * _D65[1], _f_inverse(fz) * _D65[2]], axis=-1)
+
+
+def srgb_to_lab(rgb: np.ndarray) -> np.ndarray:
+    return xyz_to_lab(linear_to_xyz(srgb_to_linear(rgb)))
+
+
+def lab_to_srgb(lab: np.ndarray, *, clip: bool = True) -> np.ndarray:
+    rgb = linear_to_srgb(xyz_to_linear(lab_to_xyz(lab)))
+    return np.clip(rgb, 0.0, 1.0) if clip else rgb
+
+
+def delta_e76(lab_a: np.ndarray, lab_b: np.ndarray) -> np.ndarray:
+    """Plain Euclidean distance in Lab. Kept for cheap internal comparisons only.
+
+    Not for anything a human reads as a quality figure — use `delta_e2000`.
+    """
+    a = np.asarray(lab_a, dtype=np.float64)
+    b = np.asarray(lab_b, dtype=np.float64)
+    return np.sqrt(np.sum((a - b) ** 2, axis=-1))
+
+
+def delta_e2000(
+    lab_a: np.ndarray, lab_b: np.ndarray, *, k_l: float = 1.0, k_c: float = 1.0, k_h: float = 1.0
+) -> np.ndarray:
+    """CIEDE2000 colour difference (CIE 142:2001).
+
+    Validated against the Sharma/Wu/Dalal (2005) test set — see
+    `tests/test_colorimetry.py`. The awkward parts are the two hue-difference
+    branches, which must use the 180°/360° wrap conventions exactly as specified;
+    getting them subtly wrong still passes most casual test pairs.
+    """
+    a = np.asarray(lab_a, dtype=np.float64)
+    b = np.asarray(lab_b, dtype=np.float64)
+    l1, a1, b1 = a[..., 0], a[..., 1], a[..., 2]
+    l2, a2, b2 = b[..., 0], b[..., 1], b[..., 2]
+
+    c1 = np.hypot(a1, b1)
+    c2 = np.hypot(a2, b2)
+    c_bar = (c1 + c2) / 2.0
+    g = 0.5 * (1.0 - np.sqrt(c_bar**7 / (c_bar**7 + 25.0**7)))
+
+    a1p, a2p = (1.0 + g) * a1, (1.0 + g) * a2
+    c1p, c2p = np.hypot(a1p, b1), np.hypot(a2p, b2)
+
+    # Hue angles in degrees; undefined (0) when chroma is zero, per the standard.
+    h1p = np.degrees(np.arctan2(b1, a1p)) % 360.0
+    h2p = np.degrees(np.arctan2(b2, a2p)) % 360.0
+    h1p = np.where(c1p == 0, 0.0, h1p)
+    h2p = np.where(c2p == 0, 0.0, h2p)
+
+    dlp = l2 - l1
+    dcp = c2p - c1p
+
+    # Δh′: zero when either chroma is zero, else wrapped to (-180, 180].
+    dhp = h2p - h1p
+    dhp = np.where(dhp > 180.0, dhp - 360.0, dhp)
+    dhp = np.where(dhp < -180.0, dhp + 360.0, dhp)
+    dhp = np.where(c1p * c2p == 0, 0.0, dhp)
+    dhp_term = 2.0 * np.sqrt(c1p * c2p) * np.sin(np.radians(dhp) / 2.0)
+
+    lp_bar = (l1 + l2) / 2.0
+    cp_bar = (c1p + c2p) / 2.0
+
+    # H̄′: the mean hue, which needs the wrap handled separately from Δh′ — the
+    # sum/2 convention differs from the difference convention above.
+    h_sum = h1p + h2p
+    h_abs = np.abs(h1p - h2p)
+    hp_bar = np.where(
+        c1p * c2p == 0,
+        h_sum,
+        np.where(
+            h_abs <= 180.0,
+            h_sum / 2.0,
+            np.where(h_sum < 360.0, (h_sum + 360.0) / 2.0, (h_sum - 360.0) / 2.0),
+        ),
+    )
+
+    t = (
+        1.0
+        - 0.17 * np.cos(np.radians(hp_bar - 30.0))
+        + 0.24 * np.cos(np.radians(2.0 * hp_bar))
+        + 0.32 * np.cos(np.radians(3.0 * hp_bar + 6.0))
+        - 0.20 * np.cos(np.radians(4.0 * hp_bar - 63.0))
+    )
+
+    d_theta = 30.0 * np.exp(-(((hp_bar - 275.0) / 25.0) ** 2))
+    r_c = 2.0 * np.sqrt(cp_bar**7 / (cp_bar**7 + 25.0**7))
+    s_l = 1.0 + (0.015 * (lp_bar - 50.0) ** 2) / np.sqrt(20.0 + (lp_bar - 50.0) ** 2)
+    s_c = 1.0 + 0.045 * cp_bar
+    s_h = 1.0 + 0.015 * cp_bar * t
+    r_t = -np.sin(np.radians(2.0 * d_theta)) * r_c
+
+    return np.sqrt(
+        (dlp / (k_l * s_l)) ** 2
+        + (dcp / (k_c * s_c)) ** 2
+        + (dhp_term / (k_h * s_h)) ** 2
+        + r_t * (dcp / (k_c * s_c)) * (dhp_term / (k_h * s_h))
+    )