人工智能AI 应用语音音频本地部署桌面应用【免费下载链接】auto-subsOn-device subtitle generation that connects directly to DaVinci Resolve, Premiere, and After Effects.项目地址https://gitcode.com/gh_mirrors/au/auto-subs点击查看免费下载本文基于本仓库内附的《Fusion 8 Scripting Guide Reference Manual》快照章节04-object-model.md撰写并结合仓库中 AutoSubs 的 DaVinci Resolve/Fusion 自动化脚本autosubs_core.lua给出源码级印证。FusionScriptFusion 的脚本接口支持 Lua 与 Python虽然只是真实应用的一种简化抽象但理解其对象模型是编写一切 DaVinci Resolve / Fusion 自动化脚本的基础。本文围绕 Fusion 的核心对象层级——Fusion 实例、Composition、Tool算子、Inputs/Outputs、Attributes、Object Data 与 Metadata——逐层拆解其职责、常用 API 与典型操作并结合 AutoSubs 项目中真实使用的 Lua 服务端代码展示这套对象模型如何在生产环境中驱动字幕生成与批量样式化。读完本文你将能够独立编写与 Fusion 交互的脚本管理合成、定位与操纵工具、读写输入输出、制作关键帧动画以及用 Object Data 在合成中持久化自定义脚本状态。文档来源与权威性说明本仓库将《Fusion 8 Scripting Guide Reference Manual》从 PDF 转换为 Markdown 并按主题/类拆分为独立文件存放在 .agents/skills/davinci-resolve-fusion/references/fusion-manual/ 目录下。按 skill 约定见 SKILL.md这是一份较旧的快照可能过时或不准确DaVinci Resolve 脚本 API 的权威来源是references/resolve-api.txt官方 README.txt 快照且以本机安装的实时文件为准对于真实可用的用法优先参考已验证的代码——AutoSubs 的 Lua 服务端autosubs_core.lua即被 skill 文档点名为生产级参考实现Fusion 对象模型、样条、工具、GUI 等 ResolveDocs 未覆盖的 Fusion 专属概念则参考本手册。因此本文中凡涉及 Fusion 对象模型本文主题的内容以该章节为主涉及 Resolve API 的内容均以仓库源码为准。概述Fusion 由什么对象组成Fusion 由不同类型type的对象组成常见对象类型包括Operator算子又称Tool工具——如 Blur、Merge、Loader 等流上可见的处理节点Link链接——算子上的Input / Output对象在属性面板properties view或 FlowView 中呈现Composition合成——承载整套工具网络的特殊对象Fusion——应用实例本身FileTypes——Loader 可读取的文件格式对象。大多数对象包含一组Attributes属性用于描述对象的状态与能力此外对象还可能携带Data数据一种特殊形式的元数据。每个对象都必须以特定类型与功能注册到 Fusion 内部的Registry注册表中。这意味着在创建实例之前就可以从注册表读取关于每个对象/工具的元信息。不过 FusionScript 日常打交道最多的还是应用、合成、工具、输入输出这些实例本身。常见对象依赖关系从用户视角看Fusion 中最常打交道的对象依赖关系可以简化为一条链Fusion → Composition (collection) → Tool (collection) → Inputs (collection) 其中部分为 MainInputsFlowView 上的输入连接 → TypeText / Number / Image / Data3D → Outputs (collection) 其中部分为 MainOutputsFlowView 上的输出连接 → TypeText / Number / Image / Data3D / other这一视图高度简化忽略了 LUT、Viewer 等许多界面特性但它抓住了用户日常处理的核心数据结构合成中包含工具工具之间通过带数据类型的输入输出相连。后续所有章节都是围绕这条链上的每一层展开的。Fusion 实例Application一切访问的起点是Fusion 对象它代表一个正在运行的 Fusion 实例。Fusion 对象能够创建、打开、关闭合成Composition存储应用级设置、偏好Preferences与持久化元数据在单个实例中同时管理多个合成GUI 中以 Tab 布局呈现。常用入口方法-- 所有当前已加载的合成 local comps fusion:GetCompList() -- 当前激活的合成 local comp fusion.CurrentComp -- 属性访问 local comp fusion:GetCurrentComp() -- 方法访问 -- 加载已有合成locked 参数决定是否以锁定模式打开 local comp fusion:LoadComp(path, locked) -- 创建空白合成locked, auto-close, hidden 三个可选参数 local comp fusion:NewComp(locked, auto-close, hidden) -- 退出 Fusion 实例 fusion:Quit()值得注意的执行模型当你在 Fusion 内运行脚本时脚本并非绑定在 Fusion 实例内执行而是由 Fusion 派生出一个FuScript进程来求值脚本并与运行中的 Fusion 实例通信。脚本退出时FuScript 进程通常也会随之停止。这一点同样适用于外部脚本环境参见手册 03-scripting-and-debugging.md 与 run-script.sh。Fusion 对象还携带一组描述自身状态的属性详见 classes/fusion.md例如FUSIONS_FileNameFusion 可执行文件路径、FUSIONS_Version/FUSIONI_VersionHi/Lo版本号、FUSIONI_SerialHi/Lo授权序列号、FUSIONS_MachineType、FUSIONI_NumProcessors、FUSIONB_IsPost是否 Post 授权等可作为脚本运行时环境探测的依据。Composition 实例Composition合成同样可以存储设置、属性与持久化元数据。Fusion 实例持有全局设置而每个合成可以有独立的设置集——偏好设置对话框正是模拟了这一行为要么修改适用于每个新合成的全局设置要么修改当前打开合成的个体设置。日常脚本中应优先访问合成设置以包含针对当前合成的覆盖项例如用于解析 Fusion 相对路径系统的PathMapping路径映射。合成还支持以下能力保存与关闭、创建 Undo / 执行 Undo / Redo / 清除全部 Undo、发起播放与渲染。锁定合成避免重渲染与弹窗comp:Lock()可将合成置于非交互批处理模式抑制任何可能弹出的对话框并阻止因控件变更触发的重渲染直到comp:Unlock()恢复交互模式。只要你在操纵合成就应尽可能先加锁这既能避免 Loader 等工具弹出文件对话框也能显著加快脚本执行解锁前不会花时间渲染。锁状态可用comp:IsLocked()查询。工具查询与选择状态合成可查询、设置当前激活工具local tool comp.ActiveTool -- 获取当前激活工具 comp:SetActiveTool(tool) -- 设置当前激活工具 local allTools comp:GetToolList() -- 所有工具 local selectedTools comp:GetToolList(true) -- 仅选中的工具Fusion 工具存在三种选择状态未选中、已选中、已选中且激活。拖选出来的工具呈蓝色选中最后点击的工具呈黄色激活且激活工具自动包含在选中集中。利用该机制可以实现精细操作——例如想把一个工具的设置复制到其他工具时可拖选所有目标工具再点击源工具将其激活然后执行复制。选择行为属于 FlowView而非工具实例可通过以下方式触发flow comp.CurrentFrame.FlowView flow:Select(Blur1, true) -- 将 Blur1 加入选择集 flow:Select(Blur2, false) -- 将 Blur2 移出选择集 flow:Select() -- 全部取消选择偏好设置Fusion 与 Composition 都有GetPrefs()与SetPrefs()分别存储 Fusion 全局偏好与合成的本地副本。如果在其中找不到某个设置可以再去 Attributes后文详述中查找。Tool 实例算子Tool 是特定类型的具名算子Operator。内部实现上工具是流上可见的 Operator 子集可以是 Creator如 Background、Text、Filter如 Blur、3D 工具等。另一类 Operator 是Modifier修改器——它类似工具但处理的是 Number/Text 数据而非图像数据同样可以连接到 Inputs 与其他 Modifier。为叙述简便下文统称 Tools但技术同样适用于其他 Operator 类型。名称、类型与关键属性只读访问名称与类型tool.Name与tool.ID。可读写的名称存储在属性TOOLS_Name中属性TOOLB_NameSet标记名称是否被手动修改过——若未手动命名部分工具会在其节点名称旁显示额外信息例如 Loader 会显示素材文件名。其他重要属性包括TOOLB_PassThroughPassThrough 状态与TOOLB_Locked锁定状态。与选择状态类似工具在 FlowView 上的位置不属于工具实例而属于 flowflow comp.CurrentFrame.FlowView flow:GetPos(Blur1) -- 打印 Blur1 的位置 flow:SetPos(Blur1, 5, 1) -- 将 Blur1 位置设为 x5, y1若需批量重排大量工具逐个SetPos会较慢。可以使用队列批处理-- 将全部工具重排为一列 flow comp.CurrentFrame.FlowView flow:QueueSetPos() for i, tool in ipairs(comp:GetToolList()) do flow:QueueSetPos(tool, 0, i) end flow:FlushSetPosQueue()工具的完整属性清单可参见 classes/operator.md除TOOLS_Name、TOOLB_Locked、TOOLB_PassThrough外还包括TOOLB_NameSet、TOOLS_RegID、TOOLB_Visible是否流上可见修改器为不可见、TOOLNT_EnabledRegion_Start/End启用区间、图像格式类属性TOOLI_ImageWidth/Height/Depth等以及 Loader/Saver 的素材 clip 属性表TOOLST_Clip_Name、TOOLIT_Clip_Width等。MainInputs 与 MainOutputs工具普遍拥有 Inputs 与 Outputs。**属性输入Property Inputs**由属性面板中的控件表示如 ColorCorrector 的 Gain 滑块**主输入MainInputs**则是 FlowView 上连接工具的输入连线。Outputs 与之类似但多数工具在 FlowView 上只有一个 MainOutput例外如 Fusion Studio 的 Stereo Splitter。一个输入/输出是否为流上连接点是在 Plugin/Fuse 开发时通过将其定义为 MainInput/MainOutput 决定的。查询可见的 MainInputs/MainOutputstool:FindMainInput(i) -- 第 i 个 MainInputi 从 1 开始 tool:FindMainOutput(i) -- 第 i 个 MainOutput若给定索引无结果方法返回nil。下面的片段遍历活动工具的全部 MainInputs 与 MainOutputstool comp.ActiveTool if tool ~ nil then print(tool.Name) local i 1 while true do local out tool:FindMainInput(i) if out nil then break end print(string.format(\tMainInput %d: %s, i, out.Name)) i i 1 end i 1 while true do local out tool:FindMainOutput(i) if out nil then break end print(string.format(\tMainOutput %d: %s, i, out.Name)) i i 1 end endInputs 与 Outputs除 MainInput/MainOutput 外工具还有其他 Inputs 与 Outputs。非隐藏的 Input 可在属性面板中表现为输入控件——同一底层数据类型可以通过不同控件呈现例如 Number 数据类型可能用滑块、复选框、下拉列表或多按钮等不同控件访问。查询输入/输出的底层数据类型local dtype inp:GetAttrs(INPS_DataType) -- 输入的数据类型 local dtype outp:GetAttrs(OUTS_DataType) -- 输出的数据类型控件让用户在属性面板中修改底层数据类型的值可选的预览控件preview control允许直接在 Viewer 中修改值。写入输入值脚本中可通过直接赋值、带时间索引的赋值或tool:SetInput(...)修改输入值代码说明Merge1.Angle 10将 Angle 设为 10Merge1.Angle[5] 20在第 5 帧将 Angle 设为 20Merge1:SetInput(Angle, 20, 5)与上面等价只有在输入已做动画时指定时间才有意义。SetInput只支持整数、浮点数、字符串这类简单数据类型。读取输入值代码说明print(Merge1.Angle)获取 Angle 的 Input 句柄print(Merge1.Angle[TIME_UNDEFINED])获取 Angle 的值print(Merge1.Angle[5])获取第 5 帧的 Angle 值Merge1:GetInput(Angle, 5)与上面等价注意Merge1.Angle直接读取返回的是输入句柄而非值取值必须带时间索引或TIME_UNDEFINED。查询全部 Inputs/Outputs所有 Input无论是否 MainInput可用tool:GetInputList()列出所有 Output 用tool:GetOutputList()列出两者都可选传数据类型过滤器。此外若已知名称输入/输出可直接作为工具的属性访问——把鼠标悬停在输入上状态栏会显示其名称例如访问 BrightnessContrast 工具的 Gain 输入BrightnessContrast1.Gain。连接关系输入可以连接到输出inp:ConnectTo(output) -- 将 input 连接到 output inp:ConnectTo() -- 断开 input inp:GetConnectedOutput() -- 获取 input 当前连接的 output outp:GetConnectedOutputs() -- 获取 output 连接的所有 inputs注意复数连接拓扑约束一个 Output 可以连接多个 Input但一个 Input 只能有一条来自 Output 的连接。Input 与 Output 共享同一个父类Link因此都可通过GetTool()回溯到所属工具详见 classes/link.md。输入除了直接连接到底层数据类型外还可以连接到同数据类型相同 DataType的其他输入、修改器或动画。由于这一切在内部都实现为连接当上游 Input 需要求值时其所有下游连接输出都会被查询——由此支持包含大量交叉依赖的复杂连接网络。动画BezierSpline 与关键帧通过脚本制作输入动画第一步是添加BezierSpline贝塞尔样条——一种可在样条编辑器中查看的动画曲线是工具动画属性信息的存储容器。以 Merge 的 Blend 属性为例Merge1.Blend BezierSpline({})此后在特定时间设置输入值即可创建关键帧。若属性是Point 数据类型则应改用Path({})函数添加基于贝塞尔曲线的路径。在 100 帧区间内将 blend 从 1 动画到 0Merge1.Blend[1] 1 Merge1.Blend[100] 0收集 BezierSpline 上的全部关键帧local spline, splineout, splinedata -- 获取连接到 Blend 输入的样条输出 splineout Merge1.Blend:GetConnectedOutput() -- 用 GetTool() 拿到 Bezier Spline 修改器本身 if splineout then spline splineout:GetTool() -- 用 GetKeyFrames() 获取样条数据表 splinedata spline:GetKeyFrames() -- 转储数据 dump(splinedata) end返回的数据是一个嵌套表外层每个条目对应一个关键帧键为关键帧的时间子表包含关键帧的值以及可选的左右手柄子表LH/RH各含手柄 X 与 Y 两个条目。删除关键帧把该时间的值设为nil。Merge1.Blend[comp.CurrentTime] nil注意如果这是样条上唯一的关键帧该点不会被删除——样条任何时刻都至少保有一个点。彻底删除动画、使输入恢复静态值则把整个输入置为nilMerge1.Blend nil关于关键帧与手柄的更多细节包括.setting宏文件中手柄坐标是绝对坐标、而SetKeyFrames()中为相对坐标这一关键陷阱可参见 animation.md。Attributes对象能力与状态的描述Attributes 存储关于某种类型能力的信息以及构成对象状态的一些通用标志。例如对 Tool 而言属性包括对象类型名、在合成中的名称、工具栏缩写、PassThrough 与选择状态等。Attributes 可读取但不保证全部可写——修改工具的 PassThrough 状态是合理的而修改其类型则没有意义。每种 Operator 类型拥有不同的属性集且不能自行添加自定义属性如需自定义状态应使用图像流元数据或 Object Data。读取属性用GetAttrs()。它由 Object 超类提供因此几乎所有对象都有 Attributes——遇到需要查找对象功能或数据的场景GetAttrs()是首选入口Merge1:GetAttrs() -- 转储全部 Tool Attributes Merge1.Blend:GetAttrs() -- 输入也有属性 Merge1:GetAttrs(TOOLB_Locked) -- 只显示锁定状态属性标签命名规则标签由三部分组成类型前缀 类型字符 下划线 属性名。例如 Tool 内多数属性前缀为TOOLInput 为INPComposition 为COMP等。类型字符含义如下类型字符含义SString字符串BBoolean布尔NNumber浮点数IInteger整数HHandle句柄NTNumber Table数字表ITInteger Table整数表STString Table字符串表BTBoolean Table布尔表例TOOLB_Locked 类型前缀TOOL 类型字符Bboolean 属性名Locked。写入 Attributes用SetAttrs({})修改属性传入的表中以标签为键、新值为值可一次修改多个属性但并非所有属性都可改。下面的示例一次完成重命名与锁定Merge1:SetAttrs({TOOLS_Name MyMerge, TOOLB_Locked true})Object Data随对象持久化的自定义数据Data 是一种特殊的元数据存储在应用偏好或合成文件中。与从图像数据流如 OpenEXR读取并在工具间传递的 Metadata 不同Object Data 不随数据流传递而是与当前应用、合成或工具的实例状态保持一致——因此它是把自定义脚本状态可靠保存在合成中的理想方案。场景示例记住上次使用的路径假设一个带 GUI 的脚本需要记住上次使用的路径避免用户每次重复选择。方案一用全局变量每次运行检查是否已设置if globals.mytool_lastpath then path mytool_lastpath else path default/path end -- ... 使用路径的对话框 globals.mytool_lastpath path但 Fusion 关闭后变量即消失。这种策略只适合会话间不太可能变化的数据如当前已加载工具的缓存列表。方案二存入 Fusion 偏好使每个新合成都能引用上次路径即使 Fusion 关闭重开也依然有效local last_path fusion:GetData(mytool.lastpath) if last_path then path last_path else path default/path end -- ... 使用路径的对话框 fusion:SetData(mytool.lastpath, path)方案三存入合成让每个合成持有各自的路径——只需把fusion替换为composition或其他符合语义的上下文对象。点号命名即子表点号并非随意使用——点代表一个子表因此可以把多个变量甚至嵌套表放在同一个命名空间下例如以工作室域名作为根名、用子表组织工具及各自的设置fusion:SetData(MyStudioInc.MyCompTool.DoMagic, true) fusion:SetData(MyStudioInc.MyRenderSettings.RemoteNames, clients)Object Data 存储在何处对于Fusion 实例数据保存在Fusion8.prefs的Global.Script.GlobalData下对于Composition、Tool 等对象数据随对象保存在.comp文件中。由于这些都是 Lua 表可以直接用文本编辑器打开.comp文件查看你写入的 Object Data。注意Tool ObjectData 的一大优势是直接存储在工具内部——把工具复制粘贴到另一个合成时数据会随之传递。不过新建的工具默认没有任何 ObjectData需要通过 EventSuite 或类似机制兜底处理这一默认情况。AutoSubs 的实战印证用 Object Data 标记字幕工具AutoSubs 的 Lua 服务端 autosubs_core.lua 正是把 Object Data 用于生产场景的实例为每条字幕 clip 对应的 Fusion 工具打上转录本、片段序号与说话人标签供后续批量样式化时回溯匹配-- autosubs_core.lua: tag_subtitle_tool约第 1366-1370 行 local function tag_subtitle_tool(tool, transcriptId, segmentIndex, speakerId) tool:SetData(AutoSubsTranscriptId, tostring(transcriptId)) tool:SetData(AutoSubsSegmentIndex, segmentIndex) tool:SetData(AutoSubsSpeakerId, speakerId ~ nil and tostring(speakerId) or ) end批量样式化时再读回这些标签配合名称/ID 定位工具第 1405-1422 行local autosubsTool comp:FindTool(AutoSubs) local template comp:FindTool(Template) or comp:FindToolByID(TextPlus) local styleTool autosubsTool or template ... local taggedTranscript styleTool:GetData(AutoSubsTranscriptId) local segmentIndex tonumber(styleTool:GetData(AutoSubsSegmentIndex)) local speakerId styleTool:GetData(AutoSubsSpeakerId) ... local currentText template:GetInput(Text)这里同时用到了多个前文概念comp:FindTool(AutoSubs)/comp:FindToolByID(TextPlus)按名称与注册 ID 定位工具见 classes/composition.mdstyleTool:GetData(...)读取 Object Datatemplate:GetInput(Text)读取输入值。此外在字体批量替换时通过styleTool:SetInput(Font, fontSwap.to)第 2236 行写入输入——与本文“写入输入值”一节的方法完全对应。Metadata图像流元数据勿与 Object Data 混淆Object Data 很容易与常规的Image Metadata图像元数据混淆但二者有本质区别Image Metadata 只能被脚本读取不能被脚本修改——它绑定在图像流本身只有 Fuses 或 Plugins 才能直接改变图像流及其元数据读取元数据需要将 Output 求值到查询元数据的那一帧Object Data 则依赖对象实例而非底层数据流因此无需求值。在带有有效输入素材的 Loader 上访问元数据Loader1.Output[comp.CurrentTime].Metadata.Filename在 SimpleExpression简单表达式中无需手动求值表达式会在当前时间自动求值。例如放在文本字段的 Expression 字段中Loader1.Output.Metadata.Filename总结对象模型的导航路径把本文的核心脉络浓缩为一张速查表便于后续编写脚本时快速定位层级关键对象/方法典型用途Fusion 实例fusion:GetCompList()、fusion:GetCurrentComp()、fusion:NewComp()、fusion:LoadComp()、fusion:Quit()管理合成、存储全局偏好与 Object DataCompositioncomp:GetToolList()、comp.ActiveTool、comp:Lock()/Unlock()/IsLocked()、comp:FindTool()、comp:FindToolByID()查询/操纵工具、控制交互模式、保存/撤销/渲染Tool/Operatortool.Name、tool.ID、tool:GetAttrs()、tool:SetAttrs()识别与配置工具状态Inputs/Outputstool:GetInputList()、tool:FindMainInput(i)、inp:ConnectTo()、inp:GetConnectedOutput()、tool:SetInput()/tool:GetInput()读写参数、建立连接动画BezierSpline({})、Path({})、spline:GetKeyFrames()关键帧与手柄动画持久化fusion:GetData()/SetData()、comp:GetData()/SetData()、tool:GetData()/SetData()随对象保存自定义脚本状态继续深入时可查阅手册索引 00-index.md 按需跳转到对应类文件fusion.md、composition.md、operator.md、link.md 等或直接查看 AutoSubs 的 autosubs_core.lua 学习其在 Resolve 时间线、媒体池与 Fusion 宏驱动上的完整生产用法该 Lua 文件由 resolve_bridge.rs 嵌入并驱动配套的 mock_resolve_test.lua 提供了可复现的测试环境。请始终记得本文开头的前提Fusion 8 手册快照可能过时凡与 Resolve API 冲突之处以本仓库的 resolve-api.txt 与真实运行代码为准。赞分享人工智能AI 应用语音音频本地部署桌面应用【免费下载链接】auto-subsOn-device subtitle generation that connects directly to DaVinci Resolve, Premiere, and After Effects.项目地址https://gitcode.com/gh_mirrors/au/auto-subs点击查看免费下载相关推荐Fusion 脚本开发实战深入解析 DaVinci Resolve 的 Composition 对象模型Fusion 脚本开发实战深入解析 DaVinci Resolve 的 Composition 对象模型 本篇技术指南以 Blackmagic Fusion人工智能AI 应用语音音频本地部署桌面应用Fusion Operator 类完全指南AutoSubs 项目中的工具对象模型与脚本化操作Fusion Operator 类完全指南AutoSubs 项目中的工具对象模型与脚本化操作 导读 Operator 是 DaVinci Resolve /人工智能AI 应用语音音频本地部署桌面应用Fusion 脚本语言深度指南Lua 与 Python 的选型、安装与跨语言调用AutoSubs 实战视角Fusion 脚本语言深度指南Lua 与 Python 的选型、安装与跨语言调用AutoSubs 实战视角 导读 本指南围绕 Fusion 的 Fusio人工智能AI 应用语音音频本地部署桌面应用上一篇效率革命Taskwarrior-TUI 终端任务管理完全指南下一篇Intel® Extension for PyTorch* 开源项目文档指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考