Resolve scripting: what actually works (Resolve Studio 21)

Check the API for the installed version before trusting memory: the scripting docs ship with Resolve, and functions move (some changed between 20 and 21).

Golden rules

• Only add. New timelines (never overwrite: "name v2"), imports into bins, clips on free tracks. Never touch the creator's template or their timelines/media. Never switch/create/close projects.
• Verify every write by reading it back. Many setters return True and do nothing.
• Save the project at the end of each step.

Building the timeline

• Find bins by name recursively. Import files once (reuse the media pool item if the same path is already imported).
• Copy the template with DuplicateTimeline(name), move it into the timelines bin, then empty every track (unlock locked tracks temporarily). The copy keeps the track FX chain (voice treatment on A1, music treatment on A2) - that's why we copy instead of creating.
• Frame rate mismatch footage vs template: stop and ask. If they choose the footage rate: useCustomSettings=1, timelineFrameRate, timelinePlaybackFrameRate.
• Custom frame (e.g. 4:3 2880x2160): set timelineResolutionWidth/Height and the output resolution, then input mismatch behaviour scaleToCrop ("scale full frame with crop"). The default scaleToFit letterboxes. Read it back.
• AppendToTimeline: endFrame is exclusive. For audio-only media, start/end frames count in the clip's own frame rate (a WAV reports 23.976), not the timeline's.
• Audio duration from timecode: at 23.976, a timecode counts 24 frames per second. seconds = ((h*3600+m*60+s)*round(fps) + f) / fps. Using 23.976 per second lost 16 frames on an 11-minute music bed.
• Check after laying: piece count on V1 and A1, each duration, no gaps.

Picture

• Zoom: item.SetProperty("ZoomX", z) and "ZoomY" (centre anchored). Works in 21.
• Grades: Timeline.ApplyGradeFromDRX fails in 21. Use each item's graph: item.GetNodeGraph().ApplyGradeFromDRX(path, 0). It occasionally fails on one piece and works on a retry: try twice, then count graded pieces (node count) and report.
• Never put a log look on non-log footage. Read the profile from the camera's sidecar XML, not from luma guesses.
• SetClipColor("Green") on B-roll pieces.

Audio

• Normalize: Timeline.NormalizeAudioLevel(items, {normalizationMode, targetLevel, targetLoudness, setLevelMode}) with resolve.NORMALIZE_AUDIO_SET_LEVEL_INDEPENDENT. See voice-and-audio for values.
• Per clip: AudioVolume (dB), SetVoiceIsolationState({"isEnabled": True, "amount": 50}), Dialogue Leveler properties. EQ is not scriptable; Fairlight presets can be applied if the user saved some.
• Silent track trap: a template's music track had a track-level AI Music Remixer switched on (and a Stereo Width insert). Anything placed on that track rendered as silence while the same file played on another track. The API can't read or toggle it; it's in the Edit page → select the track header → Inspector → Audio. If music is silent, check that first.

Diagnosing audio the reliable way

When "there's no sound", don't guess. Render a few seconds of audio from Resolve and compare it with the source file:

• Project render: SetCurrentRenderFormatAndCodec("mov", "ProRes422LT"), SetRenderSettings({SelectAllFrames: False, MarkIn, MarkOut, TargetDir, CustomName, ExportVideo: False, ExportAudio: True, AudioCodec: "lpcm"}), AddRenderJob().
• From an external script, rendering only starts with StartRendering([job], False) (isInteractiveMode False). Other forms return False and the job stays "Ready".
• Render into a folder without spaces (a path with spaces left the job unstarted).
• Wait on GetRenderJobStatus(job) until "Complete", not on IsRenderingInProgress() (it can be False before rendering begins).
• Correlate the rendered audio with the source (mono, 8 kHz, best lag): ~0.9 = present, ~0.0 = missing. Least-squares gain tells how much of an SFX is in the mix.
• Restore the Deliver settings afterwards (format, whole timeline, video+audio on, output folder): your test changes the creator's export settings.
• AddRenderJob jumps to the Deliver page; SetTrackEnable only works on the Edit page (on other pages it returns True and does nothing). Go back with OpenPage("edit").
• Timeline export (Timeline.Export(path, EXPORT_DRT)) is a zip of XML with per-track fields; deeper mixer state is a compressed binary. Useful for diffing a working vs broken track.

Subtitles

• MediaPool.AppendToTimeline with an imported .srt ignores recordFrame and appends the subtitles after the end of the timeline. Passing start/end frames for it crashed Resolve 21.1.
• Use File > Import > Subtitle in the UI (the creator clicks it, or computer-use). It places the first cue at the playhead and shifts the rest relative to it, so make the SRT's first cue start at 00:00:00,000, or everything lands early.
• Subtitle track style can't be set by script; read it from a DRT export if you need to record it.

Overlays and media cache

• Re-rendered files with the same name can keep playing stale cached frames: give each new render a new name (-v2) and replace the clip.
• Place overlays on the first free unlocked track from V2 up; never on V1.

Reading the timeline the creator edited

Before music, captions or graphics, map the timeline as it is now: walk V1 items (name, start, left offset) to find where each kept word and each B-roll landed. They trim and delete things; follow their version.