davinci-resolve-mcp 2.68.1 → 2.69.0

package/src/utils/edit_handles.py

@@ -0,0 +1,206 @@
+"""Handle accounting for cut plans — the media beyond an edit point.
+
+A "handle" is source media that exists either side of what a timeline actually
+uses. Nobody sees it in the cut, and that is exactly why it gets forgotten and
+why forgetting it is expensive.
+
+Every downstream department needs it:
+
+- **Color** needs room to slip a shot a few frames, and dissolves consume real
+  media on both sides of the join.
+- **VFX** needs overlap to track into and out of — 8-24 frames is the usual ask.
+- **Sound** needs far more, 48-120 frames, because crossfades, room-tone fills
+  and dialogue overlaps all reach past the picture cut.
+
+An automatic tighten does not know any of this. It optimizes for removing
+silence, and a keep-range that begins on the first frame of a clip is, to that
+objective, a perfect result. It is also a turnover that cannot be dissolved,
+slipped, or crossfaded — and the discovery happens weeks later, in someone
+else's suite, after picture lock, when fixing it is at its most expensive.
+
+So this reports rather than blocks. Cutting to the very head or tail of a clip
+is often legitimate and unavoidable — the material simply ends there. What is
+not legitimate is finding out about it downstream. The contract is: no plan
+silently ships zero handles.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Iterable, List, Mapping, Optional
+
+#: Picture handles. The low end of what VFX and color conventionally ask for;
+#: below this a dissolve at the join has nothing to dissolve with.
+DEFAULT_PICTURE_HANDLE_FRAMES = 8
+#: Audio handles are much larger because crossfades, room tone and dialogue
+#: overlap all reach well past the picture cut. 48 frames is 2s at 24fps.
+DEFAULT_AUDIO_HANDLE_FRAMES = 48
+
+
+def handle_floor_for(track_type: Optional[str]) -> int:
+    """Frames of source media a keep range should leave spare on each side."""
+    if str(track_type or "").strip().lower() == "audio":
+        return DEFAULT_AUDIO_HANDLE_FRAMES
+    return DEFAULT_PICTURE_HANDLE_FRAMES
+
+
+def check_keep_range_handles(
+    keep_ranges: Iterable[Mapping[str, Any]],
+    *,
+    source_bounds: Mapping[Any, int],
+    picture_handle_frames: int = DEFAULT_PICTURE_HANDLE_FRAMES,
+    audio_handle_frames: int = DEFAULT_AUDIO_HANDLE_FRAMES,
+) -> Dict[str, Any]:
+    """Report keep ranges that leave too little source media either side.
+
+    `source_bounds` maps a clip id to that clip's total length in source frames.
+    A clip missing from it is reported as `unknown` rather than assumed fine —
+    an unmeasured handle is not a passing handle, and quietly treating it as one
+    is how a turnover ships broken.
+    """
+    violations: List[Dict[str, Any]] = []
+    unknown: List[Dict[str, Any]] = []
+    checked = 0
+
+    for rng in keep_ranges:
+        clip_id = rng.get("clip_id")
+        track_type = rng.get("track_type")
+        floor = audio_handle_frames if str(track_type or "").lower() == "audio" else picture_handle_frames
+        try:
+            start = int(rng.get("start_frame"))
+            end = int(rng.get("end_frame"))
+        except (TypeError, ValueError):
+            unknown.append({"clip_id": clip_id, "reason": "keep range has no usable frame bounds"})
+            continue
+
+        total = source_bounds.get(clip_id)
+        if total is None:
+            unknown.append({
+                "clip_id": clip_id,
+                "track_type": track_type,
+                "reason": "source length unknown — handles could NOT be verified",
+            })
+            continue
+
+        checked += 1
+        head = start
+        tail = int(total) - end
+        if head >= floor and tail >= floor:
+            continue
+        violations.append({
+            "clip_id": clip_id,
+            "track_type": track_type,
+            "start_frame": start,
+            "end_frame": end,
+            "head_frames": head,
+            "tail_frames": tail,
+            "required_frames": floor,
+            "short_at": (
+                "both" if head < floor and tail < floor
+                else "head" if head < floor else "tail"
+            ),
+        })
+
+    clean = not violations and not unknown
+    return {
+        "clean": clean,
+        "checked_range_count": checked,
+        "picture_handle_frames": picture_handle_frames,
+        "audio_handle_frames": audio_handle_frames,
+        "violation_count": len(violations),
+        "violations": violations,
+        "unverified": unknown,
+        "note": _summarize(violations, unknown, checked),
+    }
+
+
+def check_seconds_ranges(
+    keep_ranges: Iterable[Mapping[str, Any]],
+    *,
+    source_duration_seconds: Optional[float],
+    fps: float = 24.0,
+    picture_handle_frames: int = DEFAULT_PICTURE_HANDLE_FRAMES,
+) -> Dict[str, Any]:
+    """Handle check for seconds-based keep ranges (the word-level cut path).
+
+    The transcript planner works in seconds against a single clip rather than in
+    frames across many, so it needs its own entry point — but the same rule. A
+    word-level tighten that begins on the first syllable of a clip leaves a join
+    with nothing behind it, exactly like a silence-driven one does, and the fact
+    that it was decided from a transcript rather than a waveform does not give
+    sound anything to crossfade with.
+    """
+    floor_seconds = picture_handle_frames / fps if fps else 0.0
+    if source_duration_seconds is None:
+        return {
+            "clean": False,
+            "checked_range_count": 0,
+            "violations": [],
+            "unverified": [{"reason": "source duration unknown — handles could NOT be verified"}],
+            "required_seconds": round(floor_seconds, 3),
+            "note": "Source length unknown, so handles were not checked. Unverified is not clean.",
+        }
+
+    violations: List[Dict[str, Any]] = []
+    checked = 0
+    for rng in keep_ranges:
+        start = rng.get("start", rng.get("start_seconds"))
+        end = rng.get("end", rng.get("end_seconds"))
+        if start is None or end is None:
+            continue
+        checked += 1
+        head = float(start)
+        tail = float(source_duration_seconds) - float(end)
+        if head >= floor_seconds and tail >= floor_seconds:
+            continue
+        violations.append({
+            "start_seconds": round(float(start), 3),
+            "end_seconds": round(float(end), 3),
+            "head_seconds": round(head, 3),
+            "tail_seconds": round(tail, 3),
+            "required_seconds": round(floor_seconds, 3),
+            "short_at": (
+                "both" if head < floor_seconds and tail < floor_seconds
+                else "head" if head < floor_seconds else "tail"
+            ),
+        })
+    return {
+        "clean": not violations,
+        "checked_range_count": checked,
+        "violation_count": len(violations),
+        "violations": violations,
+        "unverified": [],
+        "required_seconds": round(floor_seconds, 3),
+        "note": (
+            f"All {checked} kept ranges leave at least {floor_seconds:.2f}s either side."
+            if not violations else
+            f"{len(violations)} of {checked} kept ranges sit within {floor_seconds:.2f}s of "
+            "the clip edge. Those joins cannot be dissolved or crossfaded. Often "
+            "unavoidable at the head or tail of a clip — but it must be known before "
+            "turnover, not discovered in the mix."
+        ),
+    }
+
+
+def _summarize(violations: List[Dict[str, Any]], unknown: List[Dict[str, Any]], checked: int) -> str:
+    if not violations and not unknown:
+        return (
+            f"All {checked} keep ranges leave usable handles. Dissolves, slips and "
+            "audio crossfades have media to work with at every join."
+        )
+    parts: List[str] = []
+    if violations:
+        heads = sum(1 for v in violations if v["short_at"] in ("head", "both"))
+        tails = sum(1 for v in violations if v["short_at"] in ("tail", "both"))
+        parts.append(
+            f"{len(violations)} of {checked} keep ranges are short of handles "
+            f"({heads} at the head, {tails} at the tail). These joins cannot be "
+            "dissolved or slipped downstream, and audio has no room to crossfade. "
+            "Often unavoidable when a shot runs to the end of its media — but it "
+            "must be known before turnover, not discovered in the mix."
+        )
+    if unknown:
+        parts.append(
+            f"{len(unknown)} keep ranges could NOT be checked (source length "
+            "unknown). Unverified is not the same as clean."
+        )
+    return " ".join(parts)

package/src/utils/edit_report.py

@@ -0,0 +1,360 @@
+"""Human-readable reports for edit plans.
+
+Every craft role that touches a cut keeps written artifacts as a primary
+deliverable — the assistant editor's ingest log and known-issues list, the
+assistant colorist's session-prep summary, the online editor's technical handoff
+document, the post supervisor's status report. None of them consider the work
+finished when the change is made; it is finished when someone else can see what
+was decided.
+
+This tool changes timelines and, until now, said very little about it. A JSON
+plan is not a report: `keep_ranges: [...]` with 340 entries tells an editor
+nothing, and the rational response to a machine you cannot audit is to re-check
+everything by hand — which is exactly the cost the tool was supposed to remove.
+One reviewer of the first public tutorial put it plainly after watching an
+automated pass: "I feel like at this stage I will be micromanaging Claude's
+edits longer than actually doing everything myself."
+
+So the contract is that a plan explains itself:
+
+- **What would change**, in seconds and shots, not frame arrays.
+- **Why**, per cut, in the vocabulary an editor already uses.
+- **What was deliberately left alone**, which is invisible in the output and is
+  the half people distrust most.
+- **What could not be checked** — never folded into "fine".
+- **What needs a human**, separated from what does not.
+
+Rendered as Markdown because it has to survive being pasted into a Slack
+message, an email to a post supervisor, or a review doc, none of which render
+JSON.
+"""
+
+from __future__ import annotations
+
+from typing import Any, List, Mapping, Optional, Sequence
+
+
+def _plural(count: int, singular: str, plural: Optional[str] = None) -> str:
+    """"1 item" / "2 items". A report that cannot count reads as careless."""
+    word = singular if count == 1 else (plural or singular + "s")
+    return f"{count} {word}"
+
+#: Confidence is reported by several unrelated subsystems — gate calibration,
+#: pause classification, false-start heuristics — each with its own vocabulary.
+#: A reader does not care which produced it; they care whether to look.
+CONFIDENCE_ORDER = {"high": 0, "computed": 0, "medium": 1, "low": 2, "unknown": 3}
+
+
+def confidence_band(value: Optional[str]) -> str:
+    """Normalize a subsystem's confidence word into one of high/medium/low."""
+    raw = str(value or "").strip().lower()
+    if raw in ("high", "computed", "certain"):
+        return "high"
+    if raw in ("medium", "moderate", "marginal"):
+        return "medium"
+    if raw in ("low", "heuristic", "uncertain"):
+        return "low"
+    return "unknown"
+
+
+def _fmt_seconds(value: Any) -> str:
+    try:
+        total = float(value)
+    except (TypeError, ValueError):
+        return "?"
+    if total < 60:
+        return f"{total:.1f}s"
+    minutes, seconds = divmod(total, 60)
+    return f"{int(minutes)}m {seconds:04.1f}s"
+
+
+def _fmt_tc(frame: Any, fps: float) -> str:
+    """Frames → HH:MM:SS:FF. Editors navigate by timecode, not frame counts."""
+    try:
+        f = int(frame)
+    except (TypeError, ValueError):
+        return "??:??:??:??"
+    rate = int(round(fps)) if fps and fps > 0 else 24
+    hours, rem = divmod(f, rate * 3600)
+    minutes, rem = divmod(rem, rate * 60)
+    seconds, frames = divmod(rem, rate)
+    return f"{hours:02d}:{minutes:02d}:{seconds:02d}:{frames:02d}"
+
+
+def _section(title: str, lines: Sequence[str]) -> List[str]:
+    if not lines:
+        return []
+    return [f"### {title}", "", *lines, ""]
+
+
+def render_plan_report(plan: Mapping[str, Any], *, max_detail_rows: int = 25) -> str:
+    """Render any edit-engine plan as a Markdown report a human can act on.
+
+    Unknown plan kinds still produce a useful report rather than an error — a
+    report that refuses to render is worse than a generic one, because the
+    fallback is reading raw JSON.
+    """
+    kind = str(plan.get("kind") or "plan")
+    fps = float(plan.get("timeline_fps") or 24.0)
+    timeline = plan.get("timeline_name") or "(unnamed timeline)"
+    out: List[str] = [f"# {kind.replace('_', ' ').title()} — {timeline}", ""]
+
+    out.extend(_headline(plan, kind, fps))
+    out.extend(_changes_section(plan, fps, max_detail_rows))
+    out.extend(_left_alone_section(plan))
+    out.extend(_unverified_section(plan))
+    out.extend(_needs_a_human_section(plan))
+
+    note = plan.get("note")
+    if note:
+        out.extend(["---", "", str(note), ""])
+    return "\n".join(out).rstrip() + "\n"
+
+
+def _headline(plan: Mapping[str, Any], kind: str, fps: float) -> List[str]:
+    bits: List[str] = []
+    if plan.get("marker_count") is not None:
+        bits.append(
+            f"**{plan['marker_count']} markers proposed**, "
+            f"{_fmt_seconds(plan.get('total_dead_seconds'))} of dead space total. "
+            "Nothing is cut and no marker is written yet."
+        )
+    if plan.get("lift_count") is not None:
+        bits.append(
+            f"**{plan['lift_count']} cuts proposed**, "
+            f"{_fmt_seconds(plan.get('estimated_removed_seconds'))} removed."
+        )
+    if plan.get("tightness"):
+        bits.append(
+            f"Tightness **{plan['tightness']}**"
+            + (" (the default — a first assembly is meant to run long)."
+               if plan["tightness"] == "generous" else ".")
+        )
+    return [*bits, ""] if bits else []
+
+
+def _cut_rows(plan: Mapping[str, Any], fps: float, limit: int) -> List[str]:
+    rows: List[str] = []
+    entries: List[Mapping[str, Any]] = list(plan.get("lifts") or []) or list(plan.get("markers") or [])
+    if not entries:
+        return rows
+    rows.append("| At | Length | Confidence | Why |")
+    rows.append("|---|---|---|---|")
+    ordered = sorted(entries, key=lambda e: e.get("timeline_start_frame") or 0)
+    for entry in ordered[:limit]:
+        start = entry.get("timeline_start_frame")
+        if entry.get("duration_frames") is not None:
+            length = float(entry["duration_frames"]) / (fps or 24.0)
+        else:
+            length = (
+                (entry.get("timeline_end_frame") or 0) - (start or 0)
+            ) / (fps or 24.0)
+        reason = (
+            entry.get("rationale")
+            or entry.get("note")
+            or entry.get("classification_reason")
+            or "—"
+        )
+        band = confidence_band(
+            entry.get("confidence")
+            or (entry.get("evidence") or {}).get("confidence")
+            or "high"
+        )
+        rows.append(
+            f"| `{_fmt_tc(start, fps)}` | {_fmt_seconds(length)} | {band} | "
+            f"{str(reason).replace('|', '/').strip()} |"
+        )
+    if len(ordered) > limit:
+        rows.append(f"| … | | | _{len(ordered) - limit} more not shown_ |")
+    return rows
+
+
+def _changes_section(plan: Mapping[str, Any], fps: float, limit: int) -> List[str]:
+    return _section("What would change", _cut_rows(plan, fps, limit))
+
+
+def _left_alone_section(plan: Mapping[str, Any]) -> List[str]:
+    """What was deliberately preserved.
+
+    This is the half people distrust, because it is invisible in the output: a
+    beat that was correctly kept looks exactly like a beat nobody considered.
+    """
+    lines: List[str] = []
+    preserved = plan.get("preserved") or []
+    for item in preserved:
+        lines.append(f"- {item}")
+    if plan.get("tightness") == "generous":
+        lines.append(
+            "- Short gaps were left in by design at this tightness. Re-run with "
+            "`tightness='balanced'` or `'tight'` to remove more."
+        )
+    if plan.get("breathing_room_preserved"):
+        lines.append(
+            f"- {plan['breathing_room_preserved']} pauses after a sentence were kept "
+            "as breathing room — the beat that lets a line land."
+        )
+    return _section("Deliberately left alone", lines)
+
+
+def _unverified_section(plan: Mapping[str, Any]) -> List[str]:
+    """Never fold "could not check" into "checked and fine"."""
+    lines: List[str] = []
+    for skip in plan.get("skipped") or []:
+        name = skip.get("item") or skip.get("clip_id") or "(unnamed)"
+        lines.append(f"- **{name}** — {skip.get('reason') or 'not analyzed'}")
+    handles = plan.get("handle_report") or {}
+    for unver in handles.get("unverified") or []:
+        lines.append(
+            f"- **{unver.get('clip_id')}** — {unver.get('reason')}"
+        )
+    if lines:
+        lines.append("")
+        lines.append(
+            "_These were **not** analyzed. That is not the same as clean._"
+        )
+    return _section("Not verified", lines)
+
+
+def _needs_a_human_section(plan: Mapping[str, Any]) -> List[str]:
+    lines: List[str] = []
+    handles = plan.get("handle_report") or {}
+    if handles.get("violation_count"):
+        lines.append(
+            f"- **Handles:** {handles['violation_count']} keep ranges are short of "
+            f"media at the join. {handles.get('note', '').strip()}"
+        )
+    entries = list(plan.get("lifts") or []) + list(plan.get("markers") or [])
+    low = [e for e in entries if confidence_band(e.get("confidence")) == "low"]
+    if low:
+        lines.append(
+            f"- **{_plural(len(low), 'low-confidence call')}** — review before accepting."
+        )
+    marginal = [
+        c for c in (plan.get("calibrations") or [])
+        if isinstance(c, dict) and c.get("usable") and not c.get("quiet_is_digital_silence")
+        and isinstance(c.get("separation_db"), (int, float)) and c["separation_db"] < 18
+    ]
+    if marginal:
+        lines.append(
+            f"- **{_plural(len(marginal), 'item')} had speech and room close together**, "
+            "so the silence gate is usable but not confident there."
+        )
+    if plan.get("warning"):
+        lines.append(f"- **Warning:** {plan['warning']}")
+    return _section("Needs a human", lines)
+
+
+#: Audit payloads that are not edit plans — they carry criteria and/or graded
+#: findings rather than cuts. Rendered by `render_audit_report`.
+AUDIT_KINDS = ("rule_of_six_audit", "conform_lint", "sound_density_audit", "setup_sheet")
+
+
+def render_audit_report(audit: Mapping[str, Any]) -> str:
+    """Render an audit as Markdown — criteria, findings, and what was not checked.
+
+    Audits differ from plans in that they propose no change, so the sections
+    differ too: there is no "what would change", and the load-bearing part is
+    what the audit *could not* look at. That section is mandatory here for the
+    same reason it is everywhere else in this codebase — a reader who cannot see
+    the gaps will read a short report as a clean one.
+    """
+    kind = str(audit.get("kind") or "audit")
+    title = kind.replace("_", " ").title()
+    where = audit.get("timeline_name") or audit.get("media_path") or ""
+    out: List[str] = [f"# {title}" + (f" — {where}" if where else ""), ""]
+
+    coverage = audit.get("coverage") or {}
+    if coverage.get("statement"):
+        out += [f"**{coverage['statement']}**", ""]
+
+    criteria = audit.get("criteria") or []
+    if criteria:
+        out += ["### Criteria", "", "| Weight | State | Criterion | |", "|---|---|---|---|"]
+        for row in criteria:
+            out.append(
+                f"| {float(row.get('weight', 0)) * 100:.0f}% | `{row.get('state')}` | "
+                f"{str(row.get('label') or row.get('criterion')).split(' — ')[0]} | "
+                f"{str(row.get('detail') or '').replace('|', '/')} |"
+            )
+        out.append("")
+
+    findings = audit.get("findings") or []
+    if findings:
+        out += ["### Findings", ""]
+        for finding in findings:
+            head = finding.get("summary") or finding.get("code") or "finding"
+            tag = finding.get("severity") or finding.get("criterion") or ""
+            out.append(f"- **{head}**" + (f" _({tag})_" if tag else ""))
+            if finding.get("detail"):
+                out.append(f"  {finding['detail']}")
+        out.append("")
+
+    out += _audit_not_checked(audit)
+
+    for key, heading in (("threshold_provenance", "Threshold"),
+                         ("method", "Method"),
+                         ("grouping_basis", "Grouping"),
+                         ("source_caveat", "Source"),
+                         ("ordering", "Ordering")):
+        if audit.get(key):
+            out += [f"_{heading}: {audit[key]}_", ""]
+
+    if audit.get("note"):
+        out += ["---", "", str(audit["note"]), ""]
+    return "\n".join(out).rstrip() + "\n"
+
+
+def _audit_not_checked(audit: Mapping[str, Any]) -> List[str]:
+    """Everything the audit did not or could not look at. Never optional."""
+    lines: List[str] = []
+    for entry in audit.get("not_checked") or []:
+        lines.append(f"- {entry}")
+    for entry in audit.get("unanalyzed") or audit.get("unusable") or []:
+        if isinstance(entry, Mapping):
+            lines.append(f"- **{entry.get('clip') or entry.get('item')}** — {entry.get('reason')}")
+        else:
+            lines.append(f"- {entry}")
+    not_implemented = [
+        r for r in (audit.get("criteria") or []) if r.get("state") == "NOT_IMPLEMENTED"
+    ]
+    if not_implemented:
+        lines.append(
+            "- Criteria not computed by this build: "
+            + ", ".join(str(r["criterion"]) for r in not_implemented)
+        )
+    if not lines:
+        return []
+    lines.append("")
+    lines.append("_Not looked at is not the same as clean._")
+    return _section("Not checked", lines)
+
+
+def render_any(payload: Mapping[str, Any], *, max_detail_rows: int = 25) -> str:
+    """Render a plan or an audit, whichever this is."""
+    if str(payload.get("kind") or "") in AUDIT_KINDS or payload.get("criteria"):
+        return render_audit_report(payload)
+    return render_plan_report(payload, max_detail_rows=max_detail_rows)
+
+
+def summarize_for_chat(plan: Mapping[str, Any]) -> str:
+    """One-line summary for a chat reply, where a full report is too much."""
+    kind = str(plan.get("kind") or "plan").replace("_", " ")
+    if plan.get("marker_count") is not None:
+        head = (
+            f"{plan['marker_count']} dead-space markers proposed "
+            f"({_fmt_seconds(plan.get('total_dead_seconds'))} total)"
+        )
+    elif plan.get("lift_count") is not None:
+        head = (
+            f"{plan['lift_count']} cuts proposed "
+            f"({_fmt_seconds(plan.get('estimated_removed_seconds'))} removed)"
+        )
+    else:
+        head = kind
+    caveats: List[str] = []
+    if plan.get("skipped"):
+        caveats.append(f"{_plural(len(plan['skipped']), 'item')} not analyzed")
+    handles = plan.get("handle_report") or {}
+    if handles.get("violation_count"):
+        caveats.append(f"{handles['violation_count']} short of handles")
+    return head + (f" — {', '.join(caveats)}" if caveats else "")