Skip to content

multicam-setup-guide.md

Latest commit

 

History

History
138 lines (112 loc) · 4.86 KB

multicam-setup-guide.md

File metadata and controls

138 lines (112 loc) · 4.86 KB
Raw

Multicam Setup Helper Guide

The multicam setup helper prepares source-safe Resolve timelines for multicam workflows. It is a workflow helper, not a native multicam API wrapper: DaVinci Resolve's public scripting API does not expose creating native multicam clips, switching multicam angles, or flattening multicam edits.

The current Resolve UI workflow is documented in the installed DaVinci Resolve 20 Manual, Edit > Chapter 42, "Multicam Editing." In Resolve, native multicam creation and "Convert Compound Clips (Timelines) to Multicam Clips" are Media Pool context-menu operations.

What The Helper Does

media_pool(action="setup_multicam_timeline") creates a new prep timeline that references existing Media Pool clips:

  • One camera angle per video track.
  • Optional matching audio tracks.
  • Track names from angle names or clip names.
  • Exact AppendToTimeline([{clipInfo}]) placement with source ranges and record frames.
  • Dry-run planning before touching Resolve project state.

The helper never modifies, transcodes, proxies, renders, relinks, replaces, or creates derivatives of source media.

What It Does Not Do

  • It does not create a native multicam clip.
  • It does not run Resolve's "Create Multicam Clip Using Selected Clips" dialog.
  • It does not switch angles in an edited multicam clip.
  • It does not flatten multicam clips.
  • It does not perform waveform/audio correlation internally. Use media_analysis(action="detect_sync_events") as a separate read-only analysis layer when 2-pops or slate claps should feed this helper.

Sync Modes

stack_start : Places every angle at the same record frame. Use this when clips are already trimmed to the same sync point or you want a simple visual stack.

source_timecode : Reads each angle's source_timecode parameter or Resolve clip Start TC metadata and computes offsets from timeline_start_timecode. Use this for jam-synced cameras or externally prepared timecode metadata.

record_frame : Uses explicit per-angle record_frame values. Use this for manual sync, external alignment tools, or future FFmpeg/ffprobe audio-analysis results.

Minimal Example

{
  "action": "setup_multicam_timeline",
  "params": {
    "name": "Interview Multicam Prep",
    "clip_ids": ["clip-a-id", "clip-b-id"],
    "sync_mode": "stack_start",
    "include_audio": true,
    "dry_run": true
  }
}

Run the same call with dry_run=false or omit dry_run to create the timeline.

Timecode Example

{
  "action": "setup_multicam_timeline",
  "params": {
    "name": "Concert Multicam Prep",
    "sync_mode": "source_timecode",
    "timeline_start_timecode": "01:00:00:00",
    "start_timecode": "01:00:00:00",
    "include_audio": true,
    "angles": [
      {
        "clip_id": "cam-a-id",
        "angle_name": "Camera A",
        "source_timecode": "01:00:03:12"
      },
      {
        "clip_id": "cam-b-id",
        "angle_name": "Camera B",
        "source_timecode": "01:00:06:04"
      }
    ]
  }
}

The helper also accepts start_frame, end_frame, duration_frames, record_offset, track_index, and audio_track_index per angle for more explicit control.

After The Timeline Is Created

  1. Open the setup timeline and verify sync by scrubbing visible action, slate, clap, or reference audio.
  2. Duplicate the setup timeline if you want a preserved editable source, because Resolve's conversion to multicam is one-way.
  3. In the Media Pool, right-click the setup timeline.
  4. Choose "Convert Compound Clips (Timelines) to Multicam Clips."
  5. Edit the created native multicam clip into the working timeline.
  6. Use Resolve's Multicam viewer, keyboard shortcuts, angle switching, and optional flattening tools for the edit.

Agent Workflow

When asked to prepare multicam:

  1. Gather clip IDs with media_pool(action="probe_media_pool") or media_pool(action="get_selected").
  2. Prefer a dry_run call first.
  3. Explain which sync mode is being used and what evidence supports it.
  4. Create the setup timeline only after the plan is coherent.
  5. Report the resulting timeline name/id and remind the user that native conversion is a Resolve UI step.

For audio-derived alignment, first run a separate source-safe analysis pass against source paths with media_analysis(action="detect_sync_events"). Use the returned alignment.suggestions[].suggested_record_offset_frames values as per-angle record_offset values, then call this helper with sync_mode="record_frame".

If sync markers would help the user verify the setup, show the returned marker suggestions and ask first. Only after approval, call media_analysis(action="add_sync_event_markers", params={"confirm": true, ...}) to write Media Pool item markers.

Do not install FFmpeg automatically. If ffmpeg or ffprobe is missing, report that the optional audio-analysis layer is unavailable and suggest installing FFmpeg before retrying that feature.