DaVinci Resolve Studio （达芬奇）脚本 API 说明文档（翻译版）python版

在本安装包中，您将找到 DaVinci Resolve Studio 脚本 API（应用程序编程接口）的简要介绍。除本 README.txt 文件外，该安装包还包含多个文件夹，其中包含用于脚本访问的基础导入模块（如 DaVinciResolve.py）以及部分代表性示例脚本。

从 v16.2.0 版本开始，SetLUT() 和 SetCDL() 函数接收的 nodeIndex（节点索引）参数由 “0 基索引” 改为 “1 基索引”，即参数取值范围为 1 ≤ nodeIndex ≤ 总节点数。

一、概述

与 Blackmagic Fusion 脚本相同，DaVinci Resolve Studio 支持用户使用 Lua 和 Python 编程语言编写脚本。默认情况下，脚本可通过以下方式调用：

• Fusion 页面中的 “控制台” 窗口；
• 命令行。

您可在 Resolve 偏好设置中修改脚本调用权限：仅允许通过控制台调用，或允许通过本地网络调用。请注意：当允许从 Resolve 应用程序外部进行脚本访问时，需关注潜在的安全风险。

二、前置条件

要使用 DaVinci Resolve 脚本功能，需为所有用户安装以下任一环境：

• Lua 5.1
• 64 位 Python 3.6 及以上版本
• 64 位 Python 2.7 版本

三、脚本使用方法

DaVinci Resolve 必须处于运行状态，脚本才能被调用。

1. 从外部文件夹执行脚本

若要从外部文件夹执行 Resolve 脚本，脚本需先知晓 API 的存放位置。您可能需要设置以下环境变量，确保 Python 安装环境能正确加载所需依赖，不同系统的配置方式如下：

（1）Mac OS X 系统

bash

RESOLVE_SCRIPT_API="/Library/Application Support/Blackmagic Design/DaVinci Resolve/Developer/Scripting" RESOLVE_SCRIPT_LIB="/Applications/DaVinci Resolve/DaVinci Resolve.app/Contents/Libraries/Fusion/fusionscript.so" PYTHONPATH="$PYTHONPATH:$RESOLVE_SCRIPT_API/Modules/" 

（2）Windows 系统

cmd

RESOLVE_SCRIPT_API="%PROGRAMDATA%\Blackmagic Design\DaVinci Resolve\Support\Developer\Scripting" RESOLVE_SCRIPT_LIB="C:\Program Files\Blackmagic Design\DaVinci Resolve\fusionscript.dll" PYTHONPATH="%PYTHONPATH%;%RESOLVE_SCRIPT_API%\Modules\" 

（3）Linux 系统

bash

RESOLVE_SCRIPT_API="/opt/resolve/Developer/Scripting" RESOLVE_SCRIPT_LIB="/opt/resolve/libs/Fusion/fusionscript.so" PYTHONPATH="$PYTHONPATH:$RESOLVE_SCRIPT_API/Modules/" 

注：对于标准 ISO 格式的 Linux 安装，上述路径可能需修改为 /home/resolve（而非 /opt/resolve）。

2. 从菜单或控制台执行脚本

与 Fusion 脚本类似，Resolve 脚本也可通过软件菜单或控制台调用：

• 放在 “Utility” 文件夹：所有页面均可看到；
• 放在 “Comp” 或 “Tool” 文件夹：仅 Fusion 页面可见；
• 放在 “Edit”“Color”“Deliver” 等文件夹：仅对应页面可见（“Deliver” 文件夹下的脚本还会在渲染任务列表中显示）。
• 控制台调用：交互式 “控制台” 窗口可快速执行简单脚本命令（如查询 / 修改属性、测试脚本），支持 Python 2.7、Python 3.6 和 Lua 语言，输入命令后会立即执行。有关控制台的详细使用方法，请参考《DaVinci Resolve 用户手册》。

菜单调用（推荐）：DaVinci Resolve 启动时，会扫描以下目录的子文件夹，并将发现的脚本在 “工作区” 应用菜单的 “脚本” 选项下列出。您可根据需求将脚本放在对应子文件夹中，实现 “特定页面可见”：不同系统的脚本存放路径如下：

3. 示例脚本：创建简单项目

以下 Python 脚本示例演示了如何创建一个基础项目：

python

运行

#!/usr/bin/env python # 导入 DaVinci Resolve 脚本模块 import DaVinciResolveScript as dvr_script # 连接到 Resolve 应用 resolve = dvr_script.scriptapp("Resolve") # 获取 Fusion 对象（用于访问 Fusion 脚本功能） fusion = resolve.Fusion() # 获取项目管理器对象 projectManager = resolve.GetProjectManager() # 创建名为“Hello World”的项目 projectManager.CreateProject("Hello World") 

说明：resolve 对象是 Resolve 脚本的基础入口（原生对象），可通过以下方式查看其可脚本化属性：Lua 语言：使用表格迭代（table iteration）和 getmetatable 函数；Python 语言：使用 dir()、help() 等函数。其中 fusion 对象是重要的可脚本化对象，可通过它访问所有 Fusion 脚本功能。

四、以无头模式运行 DaVinci Resolve

DaVinci Resolve 可通过命令行参数 -nogui 以 “无头模式”（无用户界面）启动。在此模式下，软件界面会被禁用，但所有脚本 API 仍可正常工作。

五、DaVinci Resolve API 详解

以下介绍部分常用 API 函数（*）。与 resolve 对象类似，每个对象的属性和函数均可通过上述 “查看属性” 的方式查询。

1. Resolve 对象（软件全局入口）

2. ProjectManager 对象（项目管理器）

3. 其他核心对象 API 概览

除上述对象外，文档还详细定义了 Project（项目）、MediaStorage（媒体存储）、MediaPool（媒体池）、Timeline（时间线）、TimelineItem（时间线片段）等核心对象的 API，以下为各对象的核心功能总结：

六、数据结构说明

除基础数据类型（如整数、字符串）外，Resolve Python API 主要使用 列表（List） 和 字典（Dict） 两种数据结构：

• 列表：用 [元素1, 元素2, ...] 表示，如 [1, 2, 3]；
• 字典：用 {键1: 值1, 键2: 值2, ...} 表示，如 {"name": "项目1", "frameRate": 24}。

由于 Lua 语言不原生支持列表和字典，其 API 用 “表格（Table）” 模拟这两种结构：

• 列表 → 带索引的表格：{ [1] = 元素1, [2] = 元素2, ... }；
• 字典 → 带键的表格：{ 键1 = 值1, 键2 = 值2, ... }。

七、关键补充说明

1. 关键帧模式说明

Resolve.GetKeyframeMode() 和 Resolve.SetKeyframeMode() 函数中的 “关键帧模式（keyframeMode）” 为枚举值，对应含义如下：

2. 缓存模式说明

Graph.GetNodeCacheMode() 和 Graph.SetNodeCacheMode() 函数中的 “缓存模式（cache_value）” 为枚举值，对应含义如下：

3. 云项目设置说明

ProjectManager 的 CreateCloudProject()、LoadCloudProject() 等函数需传入 {cloudSettings} 字典参数，包含以下键（默认值已标注）：

注：LoadCloudProject() 仅支持上述前 3 个键，且同一系统首次加载时会应用所有 3 个设置，后续加载仅需指定 “项目名称”。

4. 音频同步设置说明

MediaPool.AutoSyncAudio() 函数需传入 {audioSyncSettings} 字典参数，用于设置音视频自动同步规则，包含以下键（默认值已标注）：

5. 项目 / 剪辑属性说明

Project.GetSetting()、MediaPoolItem.GetClipProperty() 等函数用于获取 / 设置 “项目设置” 或 “剪辑属性”（对应软件 UI 中的 “项目设置” 和 “剪辑属性” 对话框），操作规则如下：

• 获取属性：调用函数时传入属性键（如 project.GetSetting("timelineFrameRate")），可获取单个属性值；若不传入参数（或传入 None / 空字符串），可获取所有可查询属性的 “键 - 值” 快照（但效率较低，建议按键查询）。
• 设置属性：调用函数时传入 “属性键 + 值”（如 project.SetSetting("timelineFrameRate", "24")），需通过返回值（Bool）确认是否设置成功。

部分属性有固定枚举值，例如：

• 项目属性 “superScale”（超缩放）：0 = 自动、1 = 无缩放、2=2 倍缩放、3=3 倍缩放、4=4 倍缩放；
• 剪辑属性 “Cloud Sync”（云同步）：-1 = 默认、0 = 排队下载、1 = 下载中、2 = 下载成功等。

6. 音频映射说明

MediaPoolItem.GetAudioMapping() 和 TimelineItem.GetSourceAudioChannelMapping() 函数返回音频映射信息（JSON 格式字符串），包含嵌入式音频、链接音频、轨道映射等信息。例如，某素材包含 “1 个立体声嵌入式轨道 + 2 个链接轨道（7.1 声道、5.1 声道）”，返回结果格式如下：

json

{ "embedded_audio_channels": 2, // 所有轨道的嵌入式音频总声道数 "linked_audio": { // 链接音频信息列表 "1": { // 第1个链接音频（7.1声道） "channels": 8, // 声道数 "offset": -100, // 音频偏移（媒体0帧对应文件100帧） "path": "链接音频文件路径" }, "2": { // 第2个链接音频（5.1声道） "channels": 6, "offset": 200, // 媒体0帧对应文件200帧（前200帧为黑场） "path": "链接音频文件路径" } }, "track_mapping": { // 轨道映射（对应软件“音频剪辑属性”界面） "1": { // 第1个轨道（立体声） "channel_idx": [1, 3], // 声道索引（1=嵌入式第1声道，3=第1个链接音频第1声道） "mute": true, // 是否静音 "type": "Stereo" // 轨道类型（声道数与“channel_idx”长度一致） }, "2": { // 第2个轨道（7.1声道） "channel_idx": [3,4,5,6,7,8,9,10], "mute": true, "type": "7.1" }, "3": { // 第3个轨道（5.1声道） "channel_idx": [1,1,1,1,15,16], "mute": false, "type": "5.1" } } } 

7. 自动字幕设置说明

Timeline.CreateSubtitlesFromAudio() 函数需传入 {autoCaptionSettings} 字典参数，用于设置从音频生成字幕的规则，包含以下键（默认值已标注）：

8. 渲染设置说明

Project.SetRenderSettings() 函数需传入 {settings} 字典参数，用于配置渲染规则，核心键如下：

9. 时间线导出属性说明

Timeline.Export(fileName, exportType, exportSubtype) 函数用于导出时间线为工程文件，参数说明如下：

• exportType（导出类型）：枚举值，如 resolve.EXPORT_AAF（AAF 格式）、resolve.EXPORT_EDL（EDL 格式）、resolve.EXPORT_FCPXML_1_10（FCPXML 1.10 格式）等；
• exportSubtype（导出子类型）：部分导出类型必填，例如：
  • 导出 AAF 时：可选 resolve.EXPORT_AAF_NEW（新建）或 resolve.EXPORT_AAF_EXISTING（更新现有）；
  • 导出 EDL 时：可选 resolve.EXPORT_CDL（包含 CDL 调色）、resolve.EXPORT_SDL（包含 SDL 信息）等。

注：从 DaVinci Resolve 18.1 开始，不再支持 EXPORT_FCPXML_1_3 到 EXPORT_FCPXML_1_7 等旧版 FCPXML 格式。

10. 时间线片段属性说明

TimelineItem.SetProperty() 和 TimelineItem.GetProperty() 函数用于设置 / 获取时间线片段的属性，部分核心属性及取值范围如下：

11. LUT 导出说明

TimelineItem.ExportLUT(exportType, path) 函数用于导出片段的 LUT 调色文件，exportType（导出类型）为枚举值，对应含义如下：

注：若导出路径未指定后缀或后缀错误，函数会自动添加正确后缀（.cube 或 .vlt）。

八、废弃与不支持的 API 函数

1. 废弃函数（不建议使用，有替代方案）

2. 不支持的函数（完全无法使用）