该技能面向使用 DaVinci Resolve Studio 21 脚本 API 以代码构建剪辑的编辑者,强调以已安装版本的 API 文档为准,不依赖记忆,因为部分函数在 20 与 21 之间发生变化。
核心原则:只新增,不覆盖,新时间线以 “name v2” 命名,导入素材至素材箱,片段放在空闲轨道,不触碰创作者的模板、时间线与媒体,不切换、创建或关闭项目;每次写入后回读验证,因为许多设置函数返回 True 却不生效;每步结束时保存项目。
构建时间线:按名称递归查找素材箱,同一路径文件只导入一次并复用素材池项;用 DuplicateTimeline(name) 复制模板,移入时间线素材箱后清空各轨道(必要时临时解锁),以保留轨道 FX 链(A1 人声处理、A2 音乐处理)。素材与模板帧率不匹配时应停止并询问;选择素材帧率时使用 useCustomSettings=1、timelineFrameRate、timelinePlaybackFrameRate。自定义画幅需设置 timelineResolutionWidth/Height 与输出分辨率,输入不匹配行为设为 scaleToCrop,默认 scaleToFit 会加黑边,设置后需回读。AppendToTimeline 的 endFrame 为排他值;纯音频媒体的起止帧按片段自身帧率计算(WAV 报告 23.976)。从时间码计算音频时长时,23.976 下每秒计 24 帧,公式为 seconds = ((h3600+m60+s)*round(fps) + f) / fps。铺设后检查 V1 与 A1 的片段数量、各自时长与无空隙。
画面:用 item.SetProperty("ZoomX", z) 与 "ZoomY" 实现中心锚定缩放;21 中 Timeline.ApplyGradeFromDRX 失效,改用各片段 item.GetNodeGraph().ApplyGradeFromDRX(path, 0),偶发失败可重试两次后统计已调色片段数(节点数)并报告。不要对非 log 素材套用 log 风格,配置文件从摄像机 sidecar XML 读取。B-roll 片段可用 SetClipColor("Green") 标记。
音频:用 Timeline.NormalizeAudioLevel(items, {normalizationMode, targetLevel, targetLoudness, setLevelMode}) 并配合 resolve.NORMALIZE_AUDIO_SET_LEVEL_INDEPENDENT 做归一化;逐片段可设 AudioVolume(dB)、SetVoiceIsolationState({"isEnabled": True, "amount": 50}) 与 Dialogue Leveler 属性;EQ 无法脚本化,但可应用用户保存的 Fairlight 预设。注意静音轨道陷阱:模板音乐轨若开启轨道级 AI Music Remixer 或 Stereo Width 插入,放在该轨上的任何文件都会被渲染为静音,而 API 无法读取或切换该开关,需在编辑页选中轨道头→检查器→音频中检查。
音频诊断:出现无声音时,渲染数秒音频与源文件对比。项目渲染先设 SetCurrentRenderFormatAndCodec("mov", "ProRes422LT") 与 SetRenderSettings({SelectAllFrames: False, MarkIn, MarkOut, TargetDir, CustomName, ExportVideo: False, ExportAudio: True, AudioCodec: "lpcm"}),再 AddRenderJob();外部脚本仅 StartRendering([job], False)(isInteractiveMode 为 False)能启动渲染,其他形式返回 False 且任务停留 Ready;渲染到无空格路径,等待 GetRenderJobStatus(job) 为 Complete 而非依赖 IsRenderingInProgress();以单声道 8 kHz 最佳延迟做相关性判断(约 0.9 表示存在,约 0.0 表示缺失),最小二乘增益可估算音效在混音中的比例。测试后恢复 Deliver 设置。AddRenderJob 会跳转交付页,SetTrackEnable 仅编辑页有效,需用 OpenPage("edit") 返回。Timeline.Export(path, EXPORT_DRT) 可导出含逐轨字段的 XML zip 用于对比正常与异常轨道。
字幕:MediaPool.AppendToTimeline 导入 .srt 会忽略 recordFrame 并追加到时间线末尾,传入起止帧曾使 Resolve 21.1 崩溃;应在 UI 中用 文件 > 导入 > 字幕,首条字幕从 00:00:00,000 开始,否则整体提前;字幕轨样式无法脚本设置,可从 DRT 导出读取记录。
叠加层与媒体缓存:同名重渲染文件可能播放过期缓存帧,应每次新命名(-v2)并替换片段;叠加层放在 V2 起的首个空闲未锁轨道,绝不放在 V1。读取创作者已编辑的时间线时,处理音乐、字幕或图形前先遍历 V1 片段(名称、起点、左偏移),按创作者版本定位保留词与 B-roll 位置。
适用场景为基于模板的自动化剪辑构建与音频问题排查;限制包括 API 覆盖不全(EQ、字幕样式、轨道级 AI 处理)、部分调用返回成功但不生效、需人工确认帧率与字幕导入。