---

name: resolve-beat-fx description: >- Apply and verify scripted effects, retiming, beat markers, and vertical reframing on a DaVinci Resolve timeline. Use when an authored edit needs these helpers or its applied Fusion effects need auditing. For creative direction and reference interpretation use music-edit; for general Resolve operation use davinci-resolve. The supplied effects are optional building blocks, not a required TikTok or CapCut style.

resolve-beat-fx

Implement an authored treatment on a Resolve timeline. Choose targets, timing, and parameters from the footage and reference; the scripts' defaults are starting values. Use davinci-resolve for live MCP operation and davinci-resolve-scripting when raw API access is needed. Script paths below are relative to ~/.claude/skills/resolve-beat-fx/.

Discover the implementation path

Read the relevant script's --help and the installed MCP capability/docs surface before deciding how to apply an effect. A failed property setter is evidence about that call and version, not proof that a visual treatment is impossible. Try a supported Fusion composition, a baked selected range, or available UI control when the direct Edit-page operation is insufficient. Render the actual move before scaling it across the timeline.

These are code paths present in the skill, not a claim that every helper has been verified live in the current Resolve version. Read CONTRACT.md before changing helpers. Keep Resolve-side scripts in the compatible system Python process and heavy analysis in its own environment. Serialize mutations of the shared Resolve instance.

Vertical reframing

Use this path when 9:16 delivery is intended. Destination aspect is an editorial decision; the platform name alone does not require cropping a square or wide reference to vertical.

python3 ~/.claude/skills/resolve-beat-fx/scripts/reframe_plan.py \
  --clips 05-project/editplan.json --contact-sheet /tmp/reframe_sheet.png
python3 ~/.claude/skills/resolve-beat-fx/scripts/reframe_vertical.py \
  --plan /tmp/beatfx_reframe.json --stretch-tracks 3,4

Review and correct the plan between commands. The applier duplicates the current timeline to an owned beatfx-vertical-* copy at 1080x1920. Use --stretch-tracks only for identified full-frame overlay plates.

• Probe source dimensions. Scope films need different fill geometry from 16:9 sources; the helpers read source resolution rather than assuming it.
• Turn ZoomGang off before writing independent ZoomX/ZoomY values.
• The bundled applier uses static per-clip framing. When the subject moves out of that window, check current transform/keyframe controls or use a Fusion reframe; do not accept lost action because the helper is static.
• Luma saliency can chase lamps and explosions. --subject-color is an optional costume-color cue, not subject recognition. Inspect the range through motion and correct centres; a midpoint sheet alone cannot verify tracking.

Verify what actually rendered

Applier logs are not visual evidence. Resolve renders the active Fusion comp; adding a separate comp can mask effects in an earlier one. Inspect active vs present comps and their connections, then render the affected passage.

python3 ~/.claude/skills/resolve-beat-fx/scripts/audit_comps.py \
  --expect beatfx_rgbsplit:9 --grid /tmp/beatfx_grid.json --downbeats-only

The count above illustrates an explicitly authored expectation, not a target for effect density. The audit reports masked comps, missing expected coverage, and effects on flash/solid plates where they may have no visible effect. Use beat coverage checks for passages intended to cover those beats; sparse styling is not a defect. A structural audit still needs a rendered comparison.

• The audit's near-cut matching uses START-within-tolerance. A beat just before the incoming clip otherwise resolves by containment to the outgoing one; tests/test_audit_comps_offline.py covers this. For deliberately in-shot accents, check the intended item and comp-local event frame explicitly.
• RGB/glow on a white plate can be invisible. Confirm the chosen track and image content instead of assuming the topmost item is the intended shot.
• On Studio 21.0.3.7, ExportCurrentFrameAsStill returned byte-identical cached frames after comp/property changes. Use a short Deliver render for effect verification; if playback is stale, invalidate the affected render cache through the available controls before judging it.
• To stack effects, compose their tools into the active comp. Read actual tool names from GetToolList and use tool[input_id].SetExpression(expr); assuming design names or calling tool.SetExpression failed in the verified path.

Timing and ownership gotchas

• Raw API recordFrame includes timeline.GetStartFrame(); marker frame IDs are relative. The MCP wrappers observed on Studio 21.0.3.7 accepted relative record_frame, so check the current wrapper contract and read back placement.
• Schedule a cut, source action peak, and effect peak separately. Preserve intentional anticipation or delay; there is no universal post-cut offset.
• create_timeline_from_clips can bring source audio with the video. Prefer explicit mediaType selection where supported; inspect tracks after assembly and remove only source audio introduced by this operation when it is unwanted.
• Preserve originals and prior edit generations. Reapply only owned markers, nodes, or timelines; inspect current state before replacing an owned artifact that may have acquired user edits.