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.