davinci-resolve-mcp 2.68.1 → 2.69.0

package/src/utils/rhythm_audit.py

@@ -0,0 +1,252 @@
+"""Rhythm — criterion #3 of the Rule of Six, and the largest measurable slice at 10%.
+
+The naive reading of "rhythm" is *consistency*, and a tool built on that reading
+would flag every variation and reward metronomic cutting. That is backwards.
+An editor of long standing states the actual principle:
+
+    "You set up a rhythm... and then you need to break that rhythm, because
+    that's what gets people's attention."
+
+    **The break is where meaning lives.**
+
+So there are two findings here, and they are opposites:
+
+1. **Monotony** — a long metronomic stretch. The pattern was established and
+   never broken, so nothing is emphasised and attention drifts.
+2. **An unmotivated break** — the pattern broke somewhere nothing was happening.
+   A break is an emphasis; emphasising nothing spends the audience's attention
+   on noise.
+
+A break that lands on a story beat is neither. It is the craft working, and this
+module reports it as a **PASS with evidence**, not as an absence of findings.
+Silence about the thing that went right is how a tool teaches people that it
+only ever complains.
+
+## On cuts per minute
+
+Dialogue scenes are often observed to land around 14–16 cuts per minute, and the
+observation was always **descriptive, not prescriptive**. It is reported here as
+a comparison and never as a target. Celebrated features have shipped at well
+under a thousand cuts in their entirety — extraordinarily sparse — and are not
+wrong. Any reading of this number as something to hit would make the tool
+actively harmful.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Mapping, Optional, Sequence
+
+from src.utils import rule_of_six as _six
+
+#: Commonly observed density for dialogue scenes. Descriptive, NOT a
+#: target — see the module docstring.
+DIALOGUE_CPM_RANGE = (14.0, 16.0)
+
+#: Coefficient of variation below which a run of shots reads as metronomic.
+#: Deliberately generous: real editing is uneven, and flagging mild regularity
+#: would bury the genuinely mechanical stretches.
+MONOTONY_CV_THRESHOLD = 0.15
+#: Shortest run that can be called monotonous. Four similar shots is a pattern;
+#: three is a coincidence.
+MONOTONY_MIN_RUN = 6
+
+#: How far a shot length must depart from the local norm to count as a break.
+BREAK_RATIO = 1.8
+#: How close a break must sit to a story beat to count as motivated, in seconds.
+BREAK_BEAT_TOLERANCE_S = 2.0
+
+
+def shot_lengths(items: Sequence[Mapping[str, Any]], fps: float) -> List[Dict[str, Any]]:
+    """Ordered shot durations in seconds, with their timeline positions."""
+    rows: List[Dict[str, Any]] = []
+    ordered = sorted(
+        (i for i in items
+         if i.get("timeline_start_frame") is not None
+         and i.get("timeline_end_frame") is not None),
+        key=lambda i: i["timeline_start_frame"],
+    )
+    for item in ordered:
+        frames = int(item["timeline_end_frame"]) - int(item["timeline_start_frame"])
+        if frames <= 0:
+            continue
+        rows.append({
+            "name": item.get("item_name"),
+            "start_frame": int(item["timeline_start_frame"]),
+            "seconds": round(frames / fps, 3),
+        })
+    return rows
+
+
+def _cv(values: Sequence[float]) -> float:
+    """Coefficient of variation — spread relative to length, so it is scale-free."""
+    if len(values) < 2:
+        return 0.0
+    mean = sum(values) / len(values)
+    if mean <= 0:
+        return 0.0
+    variance = sum((v - mean) ** 2 for v in values) / len(values)
+    return (variance ** 0.5) / mean
+
+
+def find_monotony(shots: Sequence[Mapping[str, Any]]) -> List[Dict[str, Any]]:
+    """Runs of near-identical shot lengths — a pattern that never breaks."""
+    findings: List[Dict[str, Any]] = []
+    start = 0
+    while start < len(shots):
+        end = start + 1
+        while end < len(shots):
+            window = [float(s["seconds"]) for s in shots[start:end + 1]]
+            if _cv(window) > MONOTONY_CV_THRESHOLD:
+                break
+            end += 1
+        run = shots[start:end]
+        if len(run) >= MONOTONY_MIN_RUN:
+            lengths = [float(s["seconds"]) for s in run]
+            findings.append({
+                "criterion": "rhythm",
+                "scope": "sequence",
+                "at": run[0]["start_frame"],
+                "summary": f"{len(run)} consecutive shots of near-identical length",
+                "detail": (
+                    f"{len(run)} shots averaging {sum(lengths) / len(lengths):.2f}s with "
+                    f"almost no variation. A pattern was established and never broken, so "
+                    f"nothing in this stretch is emphasised. The break is where meaning "
+                    f"lives; there is no break here."
+                ),
+                "evidence": {"shot_count": len(run), "lengths": [round(x, 2) for x in lengths]},
+            })
+            start = end
+        else:
+            start += 1
+    return findings
+
+
+def find_breaks(
+    shots: Sequence[Mapping[str, Any]],
+    beats: Sequence[float],
+    fps: float,
+) -> Dict[str, List[Dict[str, Any]]]:
+    """Pattern breaks, split by whether anything motivated them.
+
+    `beats` are story-beat times in seconds — sentence boundaries, markers,
+    whatever the caller has. A break landing near one is craft.
+    """
+    motivated: List[Dict[str, Any]] = []
+    unmotivated: List[Dict[str, Any]] = []
+    for index in range(2, len(shots)):
+        prior = [float(s["seconds"]) for s in shots[max(0, index - 4):index]]
+        if len(prior) < 2:
+            continue
+        local_norm = sum(prior) / len(prior)
+        length = float(shots[index]["seconds"])
+        if local_norm <= 0:
+            continue
+        ratio = length / local_norm
+        if ratio < BREAK_RATIO and ratio > 1.0 / BREAK_RATIO:
+            continue
+        at_seconds = float(shots[index]["start_frame"]) / fps
+        near = [b for b in beats if abs(float(b) - at_seconds) <= BREAK_BEAT_TOLERANCE_S]
+        record = {
+            "criterion": "rhythm",
+            "scope": "scene",
+            "at": shots[index]["start_frame"],
+            "shot": shots[index]["name"],
+            "length_seconds": round(length, 2),
+            "local_norm_seconds": round(local_norm, 2),
+            "ratio": round(ratio, 2),
+            "direction": "longer" if ratio > 1 else "shorter",
+        }
+        if near:
+            record["summary"] = "rhythm break lands on a story beat"
+            record["detail"] = (
+                f"Shot runs {round(ratio, 1)}x the local norm and coincides with a beat "
+                f"at {near[0]:.1f}s. This is the pattern being broken deliberately — "
+                "emphasis where something is happening."
+            )
+            motivated.append(record)
+        else:
+            record["summary"] = "rhythm break with nothing to emphasise"
+            record["detail"] = (
+                f"Shot runs {round(ratio, 1)}x the local norm but no story beat sits "
+                f"within {BREAK_BEAT_TOLERANCE_S}s. A break is emphasis; emphasising "
+                "nothing spends the audience's attention on noise. Check whether this "
+                "is a beat we cannot see, or a shot that simply ran long."
+            )
+            unmotivated.append(record)
+    return {"motivated": motivated, "unmotivated": unmotivated}
+
+
+def cuts_per_minute(shots: Sequence[Mapping[str, Any]]) -> Optional[Dict[str, Any]]:
+    """Cut density, reported only ever as a comparison."""
+    total = sum(float(s["seconds"]) for s in shots)
+    if total <= 0 or len(shots) < 2:
+        return None
+    cpm = len(shots) / (total / 60.0)
+    low, high = DIALOGUE_CPM_RANGE
+    if cpm < low:
+        relation = "sparser than"
+    elif cpm > high:
+        relation = "denser than"
+    else:
+        relation = "within"
+    return {
+        "cuts_per_minute": round(cpm, 1),
+        "observed_dialogue_range": list(DIALOGUE_CPM_RANGE),
+        "relation": relation,
+        "note": (
+            f"{round(cpm, 1)} cuts/min, {relation} the 14-16 commonly observed in "
+            "dialogue scenes. That range is DESCRIPTIVE, NOT PRESCRIPTIVE — a comparison, "
+            "not a target. Celebrated features have shipped at a small fraction of that "
+            "density and are not wrong."
+        ),
+    }
+
+
+def assess(
+    items: Sequence[Mapping[str, Any]],
+    *,
+    fps: float,
+    story_beats: Optional[Sequence[float]] = None,
+) -> Dict[str, Any]:
+    """Evaluate the rhythm criterion. Returns a `rule_of_six` criterion result."""
+    shots = shot_lengths(items, fps)
+    if len(shots) < 3:
+        return {
+            "state": _six.STATE_PASS,
+            "detail": "too few shots to have a rhythm — nothing to assess",
+            "findings": [],
+            "shots": shots,
+            "insufficient_data": True,
+        }
+
+    beats = list(story_beats or [])
+    monotony = find_monotony(shots)
+    breaks = find_breaks(shots, beats, fps)
+    findings = monotony + breaks["unmotivated"]
+
+    lengths = [float(s["seconds"]) for s in shots]
+    detail_bits = [
+        f"{len(shots)} shots, {min(lengths):.1f}-{max(lengths):.1f}s, "
+        f"variation {_cv(lengths):.2f}"
+    ]
+    if breaks["motivated"]:
+        # Say what went right. A tool that only ever complains teaches its
+        # reader that a clean report means it did not look.
+        detail_bits.append(
+            f"{len(breaks['motivated'])} rhythm breaks land on story beats — "
+            "the pattern is being broken deliberately"
+        )
+    if not beats:
+        detail_bits.append(
+            "no story beats supplied, so breaks could NOT be judged motivated or not"
+        )
+
+    return {
+        "state": _six.STATE_FLAG if findings else _six.STATE_PASS,
+        "detail": "; ".join(detail_bits),
+        "findings": findings,
+        "motivated_breaks": breaks["motivated"],
+        "shots": shots,
+        "cut_density": cuts_per_minute(shots),
+        "beats_supplied": len(beats),
+    }

package/src/utils/rule_of_six.py

@@ -0,0 +1,217 @@
+"""The Rule of Six, as an audit that knows what it cannot see.
+
+The classical formulation weights its own criteria, which makes them unusually
+codifiable and sets
+exactly one trap:
+
+    emotion 51% · story 23% · rhythm 10% · eye-trace 7% · 2D plane 5% · 3D space 4%
+
+**The weighting is almost perfectly inverted against measurability.** Everything
+a machine can compute is the bottom four, and it sums to 26%.
+
+Two conclusions are available and both are wrong. "Don't build it" throws away
+real value — a cut that is technically clean is precisely the cut where a human
+should spend attention on emotion instead of hunting for a stage-line violation.
+"Approximate the top two" is far worse: face-based affect inference scoring the
+51% would be confidently wrong exactly where being wrong costs most, and would
+train its reader to stop looking.
+
+So this computes the bottom four and **abstains loudly** on the top two.
+Emotion and story appear in every single audit, carrying their weights, marked
+`NOT_ASSESSED`, and cannot be suppressed.
+
+## Three states that must never collapse
+
+- `NOT_ASSESSED` — permanent. Emotion and story. No future release changes this.
+- `NOT_IMPLEMENTED` — a criterion this build does not compute yet.
+- `PASS` / `FLAG` — actually evaluated.
+
+Collapsing the first two would let the tool grow *quieter* as it grew more
+capable, which is backwards. Collapsing either into `PASS` is the
+`unverified ≠ clean` failure this codebase has spent a lot of effort avoiding.
+
+## Two ordering axes
+
+The iron rule of the formulation: **always sacrifice lower priorities to preserve higher
+ones.** A cut that breaks 3D continuity to serve rhythm is *correct*, and a tool
+that nags about the 4% above the 10% has inverted the craft. So `CRITERION_WEIGHTS`
+is the ordering key — not detectability, which is the order most editing tools
+accidentally use because continuity errors are the easiest thing to find.
+
+A second, orthogonal rule from the same tradition is just as real: **"movie first, scene
+second, moment third"** — sacrifice a moment to save a scene, a scene to save
+the film. That is a *scope* ranking, not a criterion ranking, and a finding that
+threatens the sequence outranks one that threatens a single cut regardless of
+which criterion it belongs to. Both axes are in the sort.
+
+## No composite score
+
+There is deliberately no field any caller could mistake for an overall cut
+quality number. Averaging four criteria worth 26% into one number implies the
+number describes the cut. It describes a quarter of it, and the least important
+quarter. Per-criterion or nothing.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Mapping, Optional, Sequence
+
+#: The Rule of Six weights, verbatim. The ordering key for every
+#: finding in this program.
+CRITERION_WEIGHTS = {
+    "emotion": 0.51,
+    "story": 0.23,
+    "rhythm": 0.10,
+    "eye_trace": 0.07,
+    "two_d_plane": 0.05,
+    "three_d_space": 0.04,
+}
+
+#: Human-readable, in weighted order.
+CRITERION_LABELS = {
+    "emotion": "Emotion — what should the audience feel at this moment?",
+    "story": "Story — does the cut advance the narrative?",
+    "rhythm": "Rhythm — is this the rhythmically right moment?",
+    "eye_trace": "Eye-trace — does the cut respect where the eye is focused?",
+    "two_d_plane": "2D plane — does it honour screen geography?",
+    "three_d_space": "3D space — does it maintain physical continuity?",
+}
+
+#: Permanently unmeasurable. Not a TODO. No release changes this.
+UNMEASURABLE = ("emotion", "story")
+
+#: Scope axis: sacrifice a moment to save a scene, a scene to save the
+#: film. Lower sorts first.
+SCOPE_RANK = {"movie": 0, "sequence": 1, "scene": 2, "moment": 3}
+
+STATE_PASS = "PASS"
+STATE_FLAG = "FLAG"
+STATE_NOT_ASSESSED = "NOT_ASSESSED"
+STATE_NOT_IMPLEMENTED = "NOT_IMPLEMENTED"
+
+
+def _criterion_row(name: str, state: str, *, detail: str) -> Dict[str, Any]:
+    return {
+        "criterion": name,
+        "label": CRITERION_LABELS[name],
+        "weight": CRITERION_WEIGHTS[name],
+        "state": state,
+        "detail": detail,
+    }
+
+
+def abstention_rows() -> List[Dict[str, Any]]:
+    """The 74% this tool does not and will not measure.
+
+    Present in every audit. Not suppressible — the whole design rests on the
+    reader seeing them.
+    """
+    return [
+        _criterion_row(
+            "emotion", STATE_NOT_ASSESSED,
+            detail=(
+                "51% of this decision, and not measurable. No affect inference is "
+                "performed and none is planned: a number here would be believed and "
+                "would be wrong in the cases that matter most."
+            ),
+        ),
+        _criterion_row(
+            "story", STATE_NOT_ASSESSED,
+            detail="23% of this decision, and not measurable.",
+        ),
+    ]
+
+
+def coverage(rows: Sequence[Mapping[str, Any]]) -> Dict[str, Any]:
+    """How much of the decision this audit actually looked at."""
+    assessed = [r for r in rows if r["state"] in (STATE_PASS, STATE_FLAG)]
+    weight = sum(float(r["weight"]) for r in assessed)
+    return {
+        "assessed_criteria": len(assessed),
+        "total_criteria": len(CRITERION_WEIGHTS),
+        "weight_assessed": round(weight, 2),
+        "weight_unmeasurable": round(sum(CRITERION_WEIGHTS[c] for c in UNMEASURABLE), 2),
+        "statement": (
+            f"{len(assessed)} of {len(CRITERION_WEIGHTS)} criteria assessed, covering "
+            f"{round(weight * 100)}% of the decision. The remaining "
+            f"{round((1 - weight) * 100)}% includes emotion (51%) and story (23%), "
+            "which are not measurable and are your call."
+        ),
+    }
+
+
+def sort_findings(findings: Sequence[Mapping[str, Any]]) -> List[Dict[str, Any]]:
+    """Order by scope then by criterion weight, never by count.
+
+    Sorting by how many of each kind were found — the intuitive default — would
+    bury a single rhythm problem under fifty continuity nits, which is precisely
+    the inversion the iron rule forbids.
+    """
+    return sorted(
+        findings,
+        key=lambda f: (
+            SCOPE_RANK.get(str(f.get("scope") or "moment"), 9),
+            -CRITERION_WEIGHTS.get(str(f.get("criterion") or ""), 0.0),
+            str(f.get("at") or ""),
+        ),
+    )
+
+
+def audit(
+    *,
+    timeline_name: Optional[str] = None,
+    criterion_results: Optional[Mapping[str, Mapping[str, Any]]] = None,
+    findings: Optional[Sequence[Mapping[str, Any]]] = None,
+) -> Dict[str, Any]:
+    """Assemble a Rule of Six audit from whichever criteria have been computed.
+
+    `criterion_results` maps a measurable criterion name to
+    `{"state": PASS|FLAG, "detail": str}`. Anything absent is reported as
+    `NOT_IMPLEMENTED` — never as a pass.
+    """
+    computed = dict(criterion_results or {})
+    rows: List[Dict[str, Any]] = []
+
+    for name in CRITERION_WEIGHTS:
+        if name in UNMEASURABLE:
+            continue
+        result = computed.get(name)
+        if result is None:
+            rows.append(_criterion_row(
+                name, STATE_NOT_IMPLEMENTED,
+                detail="not computed by this build — absence of a finding is not a pass",
+            ))
+            continue
+        state = str(result.get("state") or STATE_FLAG).upper()
+        if state not in (STATE_PASS, STATE_FLAG):
+            raise ValueError(
+                f"criterion {name!r} returned state {state!r}; a computed criterion "
+                f"must be {STATE_PASS} or {STATE_FLAG}"
+            )
+        rows.append(_criterion_row(name, state, detail=str(result.get("detail") or "")))
+
+    all_rows = abstention_rows() + rows
+    all_rows.sort(key=lambda r: -CRITERION_WEIGHTS[r["criterion"]])
+
+    ordered = sort_findings(findings or [])
+    return {
+        "success": True,
+        "kind": "rule_of_six_audit",
+        "timeline_name": timeline_name,
+        "criteria": all_rows,
+        "coverage": coverage(all_rows),
+        "findings": ordered,
+        "finding_count": len(ordered),
+        "ordering": (
+            "Findings are ordered by scope (movie > sequence > scene > moment) then "
+            "by criterion weight — never by how many of each kind were found. The "
+            "established rule is to sacrifice lower priorities to preserve higher ones, "
+            "so a rhythm problem (10%) always outranks a screen-geography one (5%)."
+        ),
+        "note": (
+            "Emotion (51%) and story (23%) are NOT ASSESSED and never will be. A "
+            "clean report here means the measurable quarter is clean — which is "
+            "exactly the point at which the 74% that matters becomes worth your "
+            "attention. There is deliberately no overall score."
+        ),
+    }

package/src/utils/setup_sheet.py

@@ -0,0 +1,121 @@
+"""One frame per setup — the cutting-room wall of stills.
+
+The practice is to pin a representative frame from every setup around the
+cutting room, so
+the whole film is visible at a glance rather than only through the keyhole of a
+timeline. It is a different way of seeing the same material: scale and shape
+become obvious, repetition becomes obvious, and a sequence that is all one size
+becomes obvious in a way scrubbing never makes it.
+
+`timeline.thumbnail_contact_sheet` already renders frames — but per **shot**,
+which on a 200-shot timeline produces 200 thumbnails and reproduces the keyhole
+at higher resolution. The practice is per **setup**: one frame for each
+distinct camera position, so twenty images stand for the whole film.
+
+## Two decisions worth stating
+
+**Which frame.** From the middle of the *longest* usage of that setup. Heads and
+tails catch fades, slates and handles; the longest usage is the one the audience
+spends most time in, so it is the one that should represent it.
+
+**What order.** By first appearance, so the sheet reads in the same direction
+the film does. Sorting alphabetically or by duration would produce a tidier grid
+that tells you nothing about shape.
+
+## The grouping is a proxy and says so
+
+Resolve does not expose "lighting setup". Reel name is used where present and
+the containing folder otherwise — both usually track a camera roll, which
+usually tracks a setup. Usually. An editor regrouping by eye will beat this, and
+the output says so rather than presenting the grouping as fact.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, List, Mapping, Sequence
+
+
+def setup_key(item: Mapping[str, Any]) -> str:
+    """Best available proxy for "which camera setup is this"."""
+    reel = item.get("reel_name")
+    if reel:
+        return str(reel)
+    path = item.get("media_path")
+    if path:
+        folder = os.path.basename(os.path.dirname(str(path)))
+        if folder:
+            return folder
+    return "ungrouped"
+
+
+def select_representatives(
+    items: Sequence[Mapping[str, Any]],
+    *,
+    fps: float = 24.0,
+) -> Dict[str, Any]:
+    """One representative frame per setup, ordered by first appearance."""
+    if not items:
+        return {"success": False, "error": "No timeline items supplied"}
+
+    groups: Dict[str, List[Mapping[str, Any]]] = {}
+    unusable: List[Dict[str, Any]] = []
+    for item in items:
+        start = item.get("timeline_start_frame")
+        end = item.get("timeline_end_frame")
+        if start is None or end is None or int(end) <= int(start):
+            unusable.append({
+                "item": item.get("item_name"),
+                "reason": "no usable timeline range — NOT represented on the sheet",
+            })
+            continue
+        groups.setdefault(setup_key(item), []).append(item)
+
+    representatives: List[Dict[str, Any]] = []
+    for setup, members in groups.items():
+        longest = max(
+            members,
+            key=lambda i: int(i["timeline_end_frame"]) - int(i["timeline_start_frame"]),
+        )
+        start = int(longest["timeline_start_frame"])
+        end = int(longest["timeline_end_frame"])
+        # Middle of the longest usage: heads and tails catch fades, slates and
+        # handles, none of which represent the shot.
+        middle = start + (end - start) // 2
+        source_start = int(longest.get("source_start_frame") or 0)
+        first_appearance = min(int(m["timeline_start_frame"]) for m in members)
+        representatives.append({
+            "setup": setup,
+            "item_name": longest.get("item_name"),
+            "media_path": longest.get("media_path"),
+            "timeline_frame": middle,
+            "source_frame": source_start + (middle - start),
+            "source_seconds": round((source_start + (middle - start)) / fps, 3) if fps else None,
+            "shot_count": len(members),
+            "first_appearance_frame": first_appearance,
+            "longest_usage_frames": end - start,
+        })
+
+    representatives.sort(key=lambda r: r["first_appearance_frame"])
+    return {
+        "success": True,
+        "kind": "setup_sheet",
+        "setup_count": len(representatives),
+        "shot_count": sum(r["shot_count"] for r in representatives),
+        "representatives": representatives,
+        "unusable": unusable,
+        "grouping_basis": (
+            "reel name where present, else containing folder — a PROXY for lighting "
+            "setup. Resolve does not expose setup directly. An editor regrouping by "
+            "eye will beat this."
+        ),
+        "note": (
+            f"{len(representatives)} setups standing for "
+            f"{sum(r['shot_count'] for r in representatives)} shots, ordered by first "
+            "appearance so the sheet reads in the direction the film does. Each frame "
+            "comes from the middle of that setup's longest usage — heads and tails "
+            "catch fades, slates and handles."
+            + (f" {len(unusable)} items had no usable range and are NOT on the sheet."
+               if unusable else "")
+        ),
+    }