samuelgursky / resolve-edit

Resolve Timeline Edit

Bridges editorial craft to this repo's tools. Open the right manual; don't
re-derive it here.

• Craft / story — docs/guides/editorial-decision-guide.md. The global
  editor / assistant-editor skills add editorial philosophy and cutting-room
  practice; use them for why to cut, not tool mechanics.

• Live tool mechanics — docs/kernels/timeline-edit-kernel.md (the timeline
  edit-kernel boundary: duplicate/copy/move, range ops, item-state copy).

• Offline timeline / changelist — resolve-advanced/README.md → drt
  (timeline file authoring) and editorial (interchange + turnover).

Two servers

What this build cannot do (check before you offer it)

The scripting API changes per patch release, so "Resolve 21" is not a usable
label. Read resolve_control get_version → build.unavailable_on_this_build
before offering a gated surface; check_version_support asks about one named
symbol. Gated in this domain:

An empty unavailable_on_this_build means nothing recorded is missing, not
that everything exists — most of the API has never been version-bisected. A
symbol with no gate returns unknown, which means probe it. Probe with
name in dir(obj), never bare hasattr: on a Resolve object hasattr returns
True for every name, real or invented, so it can only say yes.

Distinguish gated from absent. A gated surface arrives with a newer build;
an absent one never does, and upgrading will not help. **Clip speed / retime is
absent on every build** — see the edit-kernel essentials below before you offer
set_retime for it.

Live edit-kernel essentials

• Duplicate/relocate: duplicate_clips (modes same_time/offset/
  at_playhead/track_above/after_source/next_gap), copy_clips (alias),
  move_clips (duplicate-then-delete). include_linked=True carries linked audio.

• Ranges: copy_range, duplicate_range, overwrite_range, lift_range.
  No public razor/split — partial overlaps in lift_range are blocked unless
  allow_partial_item_delete=True (whole-item delete, not a trim).

• Item state copy: copy_properties (transform/crop/composite/audio/retime/
  markers/flags/grades/takes/keyframes …); scope with a group list.

• Reading the user's selection is best-effort and version-dependent. The
  selection helper duck-probes three method names; the documented one,
  Timeline.GetSelectedClips, is 21.0.4+ (issue #131), so on older builds
  selection resolves by luck or not at all. Never build a destructive operation
  on "the selected clips" without reading back what you actually got — an empty
  or partial selection is indistinguishable from a small one.

• There is no clip-speed API at any version. set_retime sets retime
  quality only (RetimeProcess, MotionEstimation) and returns True for
  doing so, which reads as if the retime succeeded. Setting a % speed, reversing
  a clip, and speed ramps are all unreachable — `SetProperty('Speed'|'PlaybackSpeed'|
  'RetimeSpeed'|'ClipSpeed')returnsFalseand the matchingGetProperty`
  returns None on every build measured. Say so and route the user to the UI;
  do not offer set_retime as if it answered the question (issue #132).

• **Routing to the UI is where issue #132 actually went wrong — and it was not
  a tool lie.** Having been told to hand off, the assistant improvised the
  handoff: it sent the user hunting for a dropdown "in the lower left of the
  clip" and never mentioned the keyframe tray. That direction came from nowhere
  in this repo. **This repo verifies API behavior, not UI geography, and has no
  mechanism to version-guard a UI claim** — Resolve's controls move between
  builds, pages and layouts, and every ledger entry here is stamped with the
  build it was measured on precisely because unstamped claims rot. So:
  never improvise UI geography. Say what the user needs to do ("set the
  clip's speed / build the speed ramp in Resolve's own retime controls") and say
  plainly that you cannot see their screen. Do not invent where a control
  sits, what it looks like, which corner of a clip to click, or a menu path or
  keyboard shortcut recalled from general knowledge — an invented location costs
  the user more than "I don't know where it is on your build" ever does, and it
  reads as authoritative because everything else you told them was measured.
  The line is improvised vs. written down here. A UI pointer that already
  exists in these skills (e.g. the playback-frame-rate path in
  resolve-rough-cut) was authored and reviewed deliberately — use it verbatim.
  If no pointer exists, that is not an invitation to supply one: name the
  operation and point at Blackmagic's manual for their build. The same rule
  covers every other "do it in the UI" handoff in these skills.

• edit_engine drives higher-level selects/tighten/swap flows
  (plan → confirm → execute); tighten variants can carry audio via keep_ranges
  mirror / include_audio. For a full dead-air pass over **one long single-take
  recording** — transcribe → plan → review → execute, with the source/record
  coordinate trap spelled out — use the resolve-tighten-recording skill.

Show the gaps before cutting them (edit_engine)

• plan_dead_space_markers(timeline_name?, tightness?) — the review gate.
  Same calibrated detection as plan_silence_ripple, but it proposes markers
  instead of assembling a variant, so a human sees every gap before agreeing to
  lose it. **Use this whenever the ask is "mark the dead space so I can review
  and approve"** — that is a request for this verb, not for a tighten. Red =
  confident, Yellow = the gate only just cleared its separation floor. Nothing
  is written; pair the marker specs with timeline_markers.

• tightness on the dead-space planner: generous (default) | balanced |
  tight. Default is deliberately the loosest. A first assembly is supposed to
  be long — trimming a generous cut is fast and visible, while recovering
  material the machine already discarded is slow and invisible. Move to tight
  only when the editor asks for it.

• Guard bands are floored regardless of tightness: a removed gap always leaves
  frames before it (the outgoing word's decay) and after it (the incoming word's
  attack). tight removes more gaps, never more speech.

Word-level editing and spoken search (edit_engine)

Silence-driven tightening cannot remove an audible "um" mid-phrase or a
stammered restart. These work on the words instead and are complementary to
plan_silence_ripple, not a replacement.

• plan_transcript_tighten(clip_ref) — fillers, false starts and long
  pauses, at word boundaries. Emits the same keep_ranges shape the variant
  assembler already takes, and every removal states its reason, so the plan
  can be argued with rather than only accepted. False starts are a flagged
  heuristic: tight repeats only, so "no, no, no" as emphasis survives.

• search_spoken_content(query, mode) — phrase / all_words / regex across
  every transcribed clip, returning timestamped hits with context plus
  selects (in/out with handles). A lexical axis; find_similar is the
  semantic-visual one. Use both — a shoot should be searchable either way.
  Deterministic order (clip name, then time), so an identical search gives an
  identical selects list.

• Needs transcript_words: run transcription, then strata backfill. Both
  actions say so rather than returning an empty plan.

Offline editorial (editorial actions)

• parse_interchange — EDL / OTIO / XMEML (AAF = an honest refuse, not a fake).

• turnover_changelist — moved / retimed / trimmed / replaced / new / gone between
  two cuts PLUS the junction diff (transitions added / dropped / changed, fade
  in/out, span deltas — carrier lines and BL fade legs never read as sources),
  with timing silent-lie guards (it flags what it cannot verify).

• conform_manifest, marker_roundtrip.

Use these to answer "what changed between v3 and v4" or to hand a conform an
accurate change list without opening either timeline in Resolve. For carrying
a conform across a re-edit, see the resolve-conform skill.

Source-media safety (AGENTS.md)

Edit operations reference existing Media Pool items — they never transcode,
render, proxy, or create derivatives of source media. Keep it that way. Treat
generated probe reports as local scratch artifacts, not committed files.