davinci-resolve-mcp 2.68.1 → 2.69.0

package/src/utils/split_edits.py

@@ -0,0 +1,180 @@
+"""Split edits — sound leads picture, made measurable.
+
+**The ear is faster than the eye.** Sound arrives at the audience ahead of
+picture and is processed ahead of it, which is why the classical advice is to
+consider the cut as a sound event first. Sound can pre-lap into the next scene and pull the
+audience forward, linger from the previous one and create resonance, or carry
+continuity across images that have none.
+
+The split edit is that principle made concrete, and it is one of the few classical
+positions that is a straightforward measurement:
+
+| Shape | What happens | Effect |
+|---|---|---|
+| **L-cut** | Audio from the *outgoing* shot continues under the incoming picture | Lingers; creates resonance and continuity |
+| **J-cut** | Audio from the *incoming* shot starts under the outgoing picture | Pre-laps; pulls the audience forward |
+| **Straight** | Audio and picture cut together | Neutral, and the NLE default |
+
+## Why the ratio is the finding
+
+A timeline of nothing but straight cuts is worth knowing about. It is what an
+NLE produces when nobody has thought about sound: every audio edit sitting
+exactly on its picture edit because that is where the software put it. It is
+rarely what an editor wants and almost never what a dialogue scene wants.
+
+**There is no correct ratio and this module does not suggest one.** It reports
+the distribution. An editor reads that instantly; a prescription would be
+nonsense across a montage, a dialogue two-hander and a documentary interview.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Mapping, Sequence
+
+#: Audio and picture edits within this many frames of each other are the same
+#: join. Wider than a frame or two because audio edits get nudged by hand and a
+#: two-frame offset is not a deliberate split edit.
+PAIRING_WINDOW_FRAMES = 48
+
+#: Below this the offset is a nudge, not an intent. A one-frame audio slip is
+#: not sound leading picture; it is somebody trimming.
+MIN_SPLIT_FRAMES = 3
+
+SHAPE_L = "L-cut"
+SHAPE_J = "J-cut"
+SHAPE_STRAIGHT = "straight"
+
+
+def _edit_points(items: Sequence[Mapping[str, Any]]) -> List[int]:
+    """Cut points on a track — every boundary where one item meets the next."""
+    frames = set()
+    for item in items:
+        for key in ("timeline_start_frame", "timeline_end_frame"):
+            value = item.get(key)
+            if value is not None:
+                frames.add(int(value))
+    return sorted(frames)
+
+
+def classify_joins(
+    video_items: Sequence[Mapping[str, Any]],
+    audio_items: Sequence[Mapping[str, Any]],
+    *,
+    fps: float = 24.0,
+    pairing_window: int = PAIRING_WINDOW_FRAMES,
+    min_split: int = MIN_SPLIT_FRAMES,
+) -> Dict[str, Any]:
+    """Pair each picture edit with the nearest audio edit and classify the shape.
+
+    An unpaired picture edit is reported as `unpaired`, **not** as a straight
+    cut: no audio edit anywhere near a picture cut usually means the audio runs
+    continuously across it, which is a different and much stronger form of sound
+    carrying picture than a straight cut is.
+    """
+    picture = _edit_points(video_items)
+    sound = _edit_points(audio_items)
+    joins: List[Dict[str, Any]] = []
+    unpaired: List[int] = []
+
+    for cut in picture:
+        if not sound:
+            unpaired.append(cut)
+            continue
+        nearest = min(sound, key=lambda s: abs(s - cut))
+        offset = nearest - cut
+        if abs(offset) > pairing_window:
+            unpaired.append(cut)
+            continue
+        if abs(offset) < min_split:
+            shape, meaning = SHAPE_STRAIGHT, "audio and picture cut together"
+        elif offset > 0:
+            # Audio edit is LATER than picture: outgoing sound continues under
+            # the incoming image.
+            shape, meaning = SHAPE_L, "outgoing audio continues under the new picture — lingers"
+        else:
+            # Audio edit is EARLIER: incoming sound starts under the outgoing
+            # image.
+            shape, meaning = SHAPE_J, "incoming audio starts under the old picture — pulls forward"
+        joins.append({
+            "picture_frame": cut,
+            "audio_frame": nearest,
+            "offset_frames": offset,
+            "offset_seconds": round(offset / fps, 3) if fps else None,
+            "shape": shape,
+            "meaning": meaning,
+        })
+
+    counts = {
+        shape: sum(1 for j in joins if j["shape"] == shape)
+        for shape in (SHAPE_L, SHAPE_J, SHAPE_STRAIGHT)
+    }
+    return {
+        "joins": joins,
+        "counts": counts,
+        "unpaired_picture_cuts": unpaired,
+        "paired_count": len(joins),
+    }
+
+
+def audit(
+    video_items: Sequence[Mapping[str, Any]],
+    audio_items: Sequence[Mapping[str, Any]],
+    *,
+    fps: float = 24.0,
+) -> Dict[str, Any]:
+    """Report the split-edit distribution across a timeline."""
+    if not video_items:
+        return {"success": False, "error": "No video items supplied"}
+    if not audio_items:
+        return {
+            "success": False,
+            "error": "No audio items supplied — split edits cannot be assessed",
+            "remediation": (
+                "Pass the timeline's audio track items. Without them this cannot "
+                "tell a straight cut from an unexamined one, and reporting 'all "
+                "straight' would be a fabrication."
+            ),
+        }
+
+    result = classify_joins(video_items, audio_items, fps=fps)
+    counts = result["counts"]
+    splits = counts[SHAPE_L] + counts[SHAPE_J]
+    paired = result["paired_count"]
+    findings: List[Dict[str, Any]] = []
+
+    if paired >= 8 and splits == 0:
+        findings.append({
+            "criterion": "rhythm",
+            "scope": "sequence",
+            "at": result["joins"][0]["picture_frame"] if result["joins"] else 0,
+            "summary": f"all {paired} joins are straight cuts — sound never leads picture",
+            "detail": (
+                "Every audio edit sits on its picture edit, which is where the NLE "
+                "puts them by default. The ear is faster than the eye: an L-cut lets "
+                "the outgoing line breathe under the new image, a J-cut pulls the "
+                "audience into the next scene before they see it. A dialogue "
+                "sequence with no split edits anywhere is usually one nobody has "
+                "listened to yet."
+            ),
+        })
+
+    return {
+        "success": True,
+        "kind": "split_edit_audit",
+        "paired_joins": paired,
+        "counts": counts,
+        "split_ratio": round(splits / paired, 3) if paired else None,
+        "unpaired_picture_cuts": len(result["unpaired_picture_cuts"]),
+        "joins": result["joins"],
+        "findings": findings,
+        "note": (
+            f"{counts[SHAPE_L]} L-cuts, {counts[SHAPE_J]} J-cuts, "
+            f"{counts[SHAPE_STRAIGHT]} straight across {paired} paired joins"
+            + (f"; {len(result['unpaired_picture_cuts'])} picture cuts had no audio "
+               "edit nearby, which usually means sound runs continuously across them"
+               if result["unpaired_picture_cuts"] else "")
+            + ". There is NO correct ratio and none is suggested — a montage, a "
+            "two-hander and an interview all want different distributions. This is "
+            "a reading, not a score."
+        ),
+    }

package/src/utils/take_ranking.py

@@ -0,0 +1,206 @@
+"""Ranking takes on what can actually be measured.
+
+Two people asked for this after watching an automated first pass — "can it
+determine which takes are worse or better when it comes to the script?" — and
+one answered his own question in the next comment: "I'd trust it even less to
+choose the right take."
+
+He is right, and the honest version of this feature says so out loud.
+
+**What this measures:** fluency. Filler density, stammered restarts, how long
+the speaker goes without stumbling, and — when a script is supplied — how much
+of the intended line actually got said. All countable, all reproducible, none of
+them a matter of opinion.
+
+**What this cannot measure:** whether the take is any good. In the editorial
+weighting every cutter works from, emotion is roughly half the decision and
+story most of the rest; fluency is not on the list at all. The take that lands
+is regularly the one that stumbles — the hesitation *is* the performance, the
+breath before the answer *is* the beat. A ranking that put the smoothest read on
+top and called it "best" would be confidently wrong in exactly the cases that
+matter most, and would train its user to stop looking.
+
+So this returns a **fluency ranking with its evidence**, never a "best take",
+and every result says which one it is. Use it to find the clean safety take, to
+spot the one where someone dried, or to skip the six warm-ups before the read
+got going — not to choose the performance. That is the editor's call and this
+module has nothing useful to say about it.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping, Optional, Sequence
+
+from src.utils import transcript_edit as _te
+
+#: Below this, a take is too short for rate-based metrics to mean anything —
+#: three fluent words is not evidence of fluency.
+MIN_MEANINGFUL_SECONDS = 3.0
+
+
+def _duration(words: Sequence[Mapping[str, Any]]) -> float:
+    spans = [s for s in (_te._word_span(w) for w in words) if s is not None]
+    if not spans:
+        return 0.0
+    return max(e for _, e in spans) - min(s for s, _ in spans)
+
+
+def _longest_fluent_run(words: Sequence[Mapping[str, Any]], disfluent_spans: Sequence[Dict[str, Any]]) -> float:
+    """Longest stretch with no filler and no restart in it."""
+    spans = [s for s in (_te._word_span(w) for w in words) if s is not None]
+    if not spans:
+        return 0.0
+    start, end = min(s for s, _ in spans), max(e for _, e in spans)
+    breaks = sorted(
+        (float(d["start_seconds"]), float(d["end_seconds"]))
+        for d in disfluent_spans
+        if d.get("start_seconds") is not None and d.get("end_seconds") is not None
+    )
+    longest, cursor = 0.0, start
+    for b_start, b_end in breaks:
+        longest = max(longest, b_start - cursor)
+        cursor = max(cursor, b_end)
+    return round(max(longest, end - cursor), 3)
+
+
+def _script_coverage(words: Sequence[Mapping[str, Any]], script: Optional[str]) -> Optional[Dict[str, Any]]:
+    """Fraction of the script's content words that appear in the take.
+
+    Bag-of-words on purpose: word order in a delivered read legitimately differs
+    from the page, and penalising that would rank paraphrase below a stumbling
+    literal reading. This answers "did they get through it", not "was it
+    word-perfect".
+    """
+    if not script or not script.strip():
+        return None
+    wanted = {_te.normalize_token(t) for t in script.split()}
+    wanted = {t for t in wanted if t and t not in _te.FILLER_WORDS}
+    if not wanted:
+        return None
+    said = {_te.normalize_token(w.get("word")) for w in words}
+    hit = wanted & said
+    return {
+        "covered": len(hit),
+        "script_words": len(wanted),
+        "ratio": round(len(hit) / len(wanted), 3),
+        "missing_sample": sorted(wanted - hit)[:12],
+    }
+
+
+def score_take(
+    words: Sequence[Mapping[str, Any]],
+    *,
+    label: str,
+    script: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Countable fluency metrics for one take. No judgement of performance."""
+    duration = _duration(words)
+    fillers = _te.detect_fillers(words)
+    false_starts = _te.detect_false_starts(words)
+    per_minute = (len(fillers) / (duration / 60.0)) if duration > 0 else 0.0
+    wpm = (len(words) / (duration / 60.0)) if duration > 0 else 0.0
+
+    result: Dict[str, Any] = {
+        "label": label,
+        "duration_seconds": round(duration, 2),
+        "word_count": len(words),
+        "words_per_minute": round(wpm, 1),
+        "filler_count": len(fillers),
+        "fillers_per_minute": round(per_minute, 2),
+        "false_start_count": len(false_starts),
+        "longest_fluent_run_seconds": _longest_fluent_run(words, list(fillers) + list(false_starts)),
+        "script_coverage": _script_coverage(words, script),
+        "reliable": duration >= MIN_MEANINGFUL_SECONDS,
+    }
+    if not result["reliable"]:
+        result["caveat"] = (
+            f"only {result['duration_seconds']}s of speech — too short for these "
+            "rates to mean anything; ranked last rather than dropped so it stays visible"
+        )
+    result["fluency_score"] = _fluency_score(result)
+    result["evidence"] = _evidence_line(result)
+    return result
+
+
+def _fluency_score(m: Mapping[str, Any]) -> float:
+    """0-100, higher = more fluent. Deliberately simple and explainable.
+
+    Not tuned or learned: a weighting nobody can read is not reviewable, and the
+    components are published alongside so a reader can disagree with the
+    arithmetic instead of having to trust it.
+    """
+    if not m["reliable"]:
+        return 0.0
+    score = 100.0
+    score -= min(40.0, float(m["fillers_per_minute"]) * 5.0)
+    score -= min(30.0, float(m["false_start_count"]) * 6.0)
+    coverage = m.get("script_coverage")
+    if coverage:
+        score -= (1.0 - float(coverage["ratio"])) * 30.0
+    return round(max(0.0, score), 1)
+
+
+def _evidence_line(m: Mapping[str, Any]) -> str:
+    bits = [
+        f"{m['filler_count']} fillers ({m['fillers_per_minute']}/min)",
+        f"{m['false_start_count']} restarts",
+        f"longest clean run {m['longest_fluent_run_seconds']}s",
+    ]
+    coverage = m.get("script_coverage")
+    if coverage:
+        bits.append(f"{int(coverage['ratio'] * 100)}% of script covered")
+    return "; ".join(bits)
+
+
+#: Attached to every ranking. Not a disclaimer to be skimmed — it is the
+#: difference between a useful tool and a misleading one.
+RANKING_CAVEAT = (
+    "This ranks FLUENCY, not quality. It counts fillers, restarts and script "
+    "coverage — all measurable. It cannot hear performance, and performance is "
+    "most of what makes a take the right one. The take that plays best is "
+    "regularly the least fluent one: the hesitation is often the acting. Use "
+    "this to find the clean safety take or to skip the warm-ups, not to choose "
+    "the read."
+)
+
+
+def rank_takes(
+    takes: Sequence[Mapping[str, Any]],
+    *,
+    script: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Rank takes by measurable fluency, with the evidence and the caveat.
+
+    Each take: `{"label": str, "words": [transcript_words rows]}`.
+    """
+    if not takes:
+        return {"success": False, "error": "No takes supplied"}
+
+    scored = [
+        score_take(t.get("words") or [], label=str(t.get("label") or f"take {i + 1}"), script=script)
+        for i, t in enumerate(takes)
+    ]
+    scored.sort(key=lambda s: (-s["fluency_score"], -s["longest_fluent_run_seconds"]))
+    for position, take in enumerate(scored, start=1):
+        take["rank"] = position
+
+    unreliable = [s["label"] for s in scored if not s["reliable"]]
+    return {
+        "success": True,
+        "kind": "take_ranking",
+        "ranked_by": "fluency",
+        "take_count": len(scored),
+        "takes": scored,
+        "most_fluent": scored[0]["label"] if scored else None,
+        "script_supplied": bool(script and script.strip()),
+        "unreliable_takes": unreliable,
+        "caveat": RANKING_CAVEAT,
+        "note": (
+            f"Ranked {len(scored)} takes by fluency. "
+            + (f"{len(unreliable)} {'take was' if len(unreliable) == 1 else 'takes were'} "
+               "too short to score reliably and sit at the bottom — not necessarily "
+               "bad, just unmeasurable. "
+               if unreliable else "")
+            + "The top entry is the most fluent, which is NOT the same as the best."
+        ),
+    }

package/src/utils/transcript_edit.py

@@ -151,19 +151,112 @@ def detect_fillers(words: Sequence[Dict[str, Any]]) -> List[Dict[str, Any]]:
     return out
 
 
+#: Terminal punctuation on the *preceding* word. A pause after one of these is
+#: where a thought ended, which is where an audience expects to breathe.
+_SENTENCE_FINAL_PUNCT = (".", "?", "!", "…")
+#: A pause here separates clauses — a real beat, but a smaller one.
+_CLAUSE_FINAL_PUNCT = (",", ";", ":", "—", "–")
+
+#: How much longer a *sentence-final* pause must be before it counts as dead air.
+#:
+#: A silence gate cannot tell these apart, because acoustically they are
+#: identical: 900 ms of room tone after "…and that changed everything." and
+#: 900 ms of room tone in the middle of "the thing is — uh — we had to leave"
+#: measure the same. Editorially they are opposites. The first is the beat that
+#: lets the line land; removing it is the single most common way an automated
+#: tighten makes a cut feel machine-made. The second is a stumble.
+#:
+#: So sentence-final pauses are not exempt — a four-second hole after a full
+#: stop is still dead air — they simply have to be much longer before we touch
+#: them. Clause-final sits between the two.
+BREATHING_ROOM_MULTIPLIER = 2.5
+CLAUSE_PAUSE_MULTIPLIER = 1.5
+
+
+def classify_pause(prev_word: Optional[Dict[str, Any]], next_word: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+    """Where a pause sits syntactically, which decides whether it is craft or noise.
+
+    Honest limit: this reads punctuation, so it is only as good as the
+    transcriber's. ASR output with no punctuation at all cannot be classified —
+    that returns `unpunctuated` with low confidence rather than silently
+    assuming every pause is removable, which would reintroduce exactly the
+    behaviour this function exists to prevent.
+    """
+    raw = str((prev_word or {}).get("word") or "").strip()
+    if not raw:
+        return {"position": "unknown", "is_breathing_room": False,
+                "multiplier": 1.0, "confidence": "low",
+                "reason": "no preceding word text"}
+    if raw.endswith(_SENTENCE_FINAL_PUNCT):
+        return {"position": "sentence_final", "is_breathing_room": True,
+                "multiplier": BREATHING_ROOM_MULTIPLIER, "confidence": "high",
+                "reason": f"pause follows end of sentence ({raw[-1]!r}) — breathing room"}
+    if raw.endswith(_CLAUSE_FINAL_PUNCT):
+        return {"position": "clause_final", "is_breathing_room": True,
+                "multiplier": CLAUSE_PAUSE_MULTIPLIER, "confidence": "medium",
+                "reason": f"pause follows a clause break ({raw[-1]!r})"}
+    # No terminal punctuation. If nothing in the transcript is punctuated at all
+    # we must not read that as "every pause is mid-sentence".
+    return {"position": "intra_clause", "is_breathing_room": False,
+            "multiplier": 1.0, "confidence": "high",
+            "reason": "pause falls inside a phrase — not a beat the writing asked for"}
+
+
+def transcript_is_punctuated(words: Sequence[Dict[str, Any]]) -> bool:
+    """Whether this transcript carries sentence punctuation at all.
+
+    Used to downgrade pause classification honestly: without punctuation every
+    pause looks intra-clause, and acting on that would strip every beat in the
+    programme.
+    """
+    for w in words:
+        raw = str((w or {}).get("word") or "").strip()
+        if raw.endswith(_SENTENCE_FINAL_PUNCT) or raw.endswith(_CLAUSE_FINAL_PUNCT):
+            return True
+    return False
+
+
 def detect_long_pauses(
-    words: Sequence[Dict[str, Any]], *, max_pause: float, handle: float, min_cut: float
+    words: Sequence[Dict[str, Any]],
+    *,
+    max_pause: float,
+    handle: float,
+    min_cut: float,
+    preserve_breathing_room: bool = True,
 ) -> List[Dict[str, Any]]:
     """Gaps between words longer than `max_pause`, trimmed by a handle each side.
 
     Word-boundary based, so unlike a silence gate this never cuts into a word
     that merely dipped below a threshold.
+
+    With `preserve_breathing_room` (the default), the threshold is scaled by the
+    pause's syntactic position — see `classify_pause`. A pause after a full stop
+    has to be markedly longer than one mid-phrase before it is proposed for
+    removal, because the first is usually deliberate and the second usually is
+    not. Set it False to treat every gap as equal, which is the older behaviour.
     """
     out: List[Dict[str, Any]] = []
-    spans = [s for s in (_word_span(w) for w in words) if s is not None]
-    for (_, prev_end), (next_start, _) in zip(spans, spans[1:]):
+    indexed = [(i, s) for i, s in enumerate(_word_span(w) for w in words) if s is not None]
+    punctuated = transcript_is_punctuated(words) if preserve_breathing_room else False
+    for (i_prev, (_, prev_end)), (_, (next_start, _)) in zip(indexed, indexed[1:]):
         gap = next_start - prev_end
-        if gap <= max_pause:
+        if preserve_breathing_room and punctuated:
+            classification = classify_pause(words[i_prev], None)
+        else:
+            classification = {
+                "position": "unpunctuated" if preserve_breathing_room else "unclassified",
+                "is_breathing_room": False,
+                "multiplier": 1.0,
+                "confidence": "low" if preserve_breathing_room else "high",
+                "reason": (
+                    "transcript carries no punctuation, so a pause cannot be placed "
+                    "syntactically — treated as removable, review before accepting"
+                    if preserve_breathing_room
+                    else "breathing-room preservation disabled by caller"
+                ),
+            }
+        effective_max = max_pause * float(classification["multiplier"])
+        if gap <= effective_max:
             continue
         start, end = prev_end + handle, next_start - handle
         if end - start >= min_cut:
@@ -171,7 +264,10 @@ def detect_long_pauses(
                 "start_seconds": round(start, 3),
                 "end_seconds": round(end, 3),
                 "pause_seconds": round(gap, 3),
-                "confidence": "high",
+                "confidence": classification["confidence"],
+                "pause_position": classification["position"],
+                "threshold_seconds": round(effective_max, 3),
+                "classification_reason": classification["reason"],
             })
     return out