视频覆盖层
将未经剪辑的样片转化为一组动画叠加层,这些叠加层会精确地落在说话者说出每一句台词的画面上,同时生成一个 Resolve 导入文件。
在此处设置您的品牌
在 scripts/scene.html 中编辑一次即可(顶部的 :root 块)。其他所有内容都将从这些设置中读取。
| 设置 | CSS 变量 | 默认值 |
|---|---|---|
| 强调色 | --brand-accent (+ --brand-accent-rgb 作为 r,g,b) | #4a90e2 |
| 浅色文字颜色 | --brand-light (+ --brand-light-rgb) | #f2f2f2 |
| 深色墨水颜色 | --brand-ink | #0d131a |
| 显示字体(标题、数字) | --font-display | 'Anton','Bebas Neue',Impact,sans-serif |
| 正文字体 | --font-body | 'Inter',-apple-system,sans-serif |
显示字体必须本地安装(例如,在 ~/Library/Fonts 中),因为片段会在无头 Chrome 中离线渲染。Anton 和 Bebas Neue 在 Google Fonts 上是免费的。代码中的名称 BLUE 仅表示“强调色”。
品牌风格:场景内文字。 没有卡片。文字位于房间里说话者头部旁边,大标题位于头部两侧,问题在说出时逐字打出。始终使用您的品牌颜色和显示字体。
最重要的一条规则: 将图形保持在说话者头部后方或侧面。不要在脸部前面放置任何内容,也不要使用背景颜色。图表也放置在说话者旁边的墙上。所有内容都是蒙版的,因此手势会经过图形前面。
一次运行产生: N 个透明的 .mov 片段、PLACEMENT.txt、两个 .fcpxml 文件和一个简短的 PREVIEW.mp4。
默认没有声音。 除非被要求,否则不要添加音乐或音效。
样式默认值(可按需调整)
- 在内容被说出之前,没有任何东西出现。 将每个片段锚定到短语的词级时间戳,再加上约 0.12 秒,使其刚好在词语之后出现。段落级计时会被视为过早。
- 简短。 2.5 到 6.5 秒。大多数约 3 秒。它应该像社交媒体视频一样来回切换,而不是静止不动。
- 位于头部后方或侧面,切勿覆盖说话者。 没有卡片、无背景、无变暗。这废除了之前的角落标签、所有
full-*卡片和define类型。 - 仍然展示机制。 在用一个句子说明之前,先展示图表。使用场景内图表类型(
dots、flow、bars、compare、math),这些图表位于说话者旁边的墙上。 - 拆分任何有两个部分的内容。 旧方法和新方法是两个片段。10% 和 20% 是两个片段。三个选项是三个片段,每个片段在它被命名时出现。
- 每一行都精确落在其词语上。 列表、旁白和打出的文字带有基于词级时间戳的每行偏移(
at、t),而不是均匀间隔。scripts/plan.example.py展示了如何操作:引用短语,命名提示词,然后执行查找。 - 良好的混合比例(约 11 分钟内 48 个片段):大约四分之一的场景内图表(主要是
flow),然后是side、pair、type、list2、num。将pair保留给关键句。 - 大标题位于头部周围,而不是后方。
pair类型将每行在一个词边界处分成两半,分布在头部两侧,间隙为 1.9 倍脸部框宽度(包括头发和耳朵),缩放后确保两半都保持在屏幕上。因此,每个pair行都需要 2 个以上的词(例如“ONE HOUR”,而不是“HOUR”):单个词无法拆分并最终被隐藏。data中的"around": false会恢复居中的外观。轮廓线的宽度为 150px,带有 5px 描边和浅色强调色填充(35%),以确保清晰可读。
在开始之前:剪辑是否已锁定?
叠加层锚定在精确的词语上,因此之后的任何重新修剪都会移动所有片段。如果用户提供的是原始素材,或者剪辑尚未锁定,请先运行 paper-edit 技能,然后将叠加层放置在它生成的时间线上。
流水线
1. 获取剪辑并探测它
要求从 Resolve 导出一个文件(例如,导出到 ~/Movies/),或者如果要先进行纸面编辑,则提供 <YOUR_FOOTAGE_DRIVE> 上的原始素材。视频文件即可;无需单独导出音频。当 Resolve 打开时,通过 MCP 读取时间线,而不是要求导出。
ffprobe -v error -show_entries format=duration -show_entries stream=codec_type,r_frame_rate -of default=nw=1 "<file>"
记下帧率(渲染器默认使用 23.976 = 24000/1001;如需其他帧率,请更改 render.mjs 中的 FPSN/FPSD),并询问时间线是从 00:00:00:00 还是 01:00:00:00 开始(Resolve 的默认值是 01)。
2. 使用词级时间戳进行转录
ffmpeg -y -i "<file>" -ac 1 -ar 16000 -c:a pcm_s16le cut.wav
whisper-cli -m ~/.cache/whisper-models/ggml-small.en.bin -f cut.wav -oj -ml 1 -sow -of cut
-ml 1 -sow 为每个片段生成一个词元,这使得精确锚定成为可能。然后,通过匹配 cut.json 中的词元序列来找到每个短语的开始时间(transcription[].offsets.from 以毫秒为单位)。
3. 挑选时机
首先通读整个转录文本。目标是大约每 15 秒视频一个片段。对于每个片段:锚定短语、一个类型和最短的时长,以便让动画能够落地和呼吸。
将内容基于实际所说的内容,而不是书面笔记。如果笔记说“30分钟”,但在镜头前说的是“大约半小时”,则以录像为准,并向用户标记差异。
4. 编写 clips.json
复制 scripts/clips.example.json 作为模板。每个片段一个对象:
{"id":"06-math-10","start":52.96,"dur":3.6,"type":"dots","cue":"\"if 10 out of 100 meals are home cooked\"",
"data":{"lit":10,"pct":"10%","count":"10 meals"}}
将其放置在技能文件夹之外(临时路径即可),并使用 CLIPS= 传递它。start 是原始短语时间(秒);渲染器自身会添加 0.12 秒的前置时间。id 的顺序决定了文件的顺序,因此请对它们进行编号。
5. 渲染一个干净的剪辑(场景内类型需要)
场景内类型会读取头部位置,并从一份没有叠加层的剪辑副本中抠出说话者。从 Resolve 渲染锁定的时间线,禁用每个叠加层片段,使用 H.264 1080p,输出到临时路径。在 API 中,Resolve 19 中的 SetTrackEnable 对 V2 无效;请对轨道上的每个片段使用 item.SetClipEnabled(False)。原始素材必须在线,因此素材驱动器必须已挂载;如果未挂载,请让用户连接它并等待挂载,而不是渲染完成的主版本(旧的叠加层会被烘焙进去)。
6. 渲染
cd <skill>/scripts && npm i # 仅首次执行,安装 puppeteer-core
swiftc -O person.swift -o person # 仅首次执行,蒙版和头部查找器
TITLE="<video name>" CLIPS=/path/to/clips.json FOOTAGE=/path/to/clean.mp4 OUT_DIR="$HOME/Movies/<video-name>-overlays" node render.mjs
# 仅渲染一个或少数几个片段:
ONLY=06-math-10,07-math-30 OUT_DIR=... node render.mjs
大约每秒钟的叠加层需要 10 到 15 秒的挂钟时间(pair 较慢,因为它会对每一帧进行蒙版处理)。将其后台运行并稍后检查是合适的做法。它会在最后写入 PLACEMENT.txt 和两个 .fcpxml 文件。
在完整渲染之前,始终在真实素材上进行验证。 node proof.mjs <clean.mp4> <clips.json> out.jpg [email protected] [email protected] ... 会在实际镜头中为每个片段渲染一帧(前缀@片段内的秒数),包含蒙版,平铺到一张图像中。仔细检查。出界的文字、穿过眼睛的标题、繁忙背景上的文字:这些在代码中不可见,但在图像中一目了然。对于图表,在灰色背景上合成仍然可以。
验证帧:先提取为 PNG。 将带有 -ss 的 qtrle .mov 直接叠加到 lavfi 颜色源上会生成空白帧。先提取帧(ffmpeg -ss 2.8 -i clip.mov -frames:v 1 f.png),然后再合成 PNG。
在 Resolve 中放置: 将锁定的时间线复制为 YouTube Final,将 mov 文件导入到 Overlays 素材箱中,并使用 AppendToTimeline 为每个片段设置 trackIndex: 2 和来自 PLACEMENT.txt 中 IN 时间码的 recordFrame(((h*3600+m*60+s)*24+ff),因此 01:00:00:00 = 86400)。逐行解析 PLACEMENT.txt(line.split()[0] 是 id,[1] 是时间码)。全局正则表达式可能会将类似“60-second”的提示文字误读为片段 id 并窃取下一行的时间码,导致某个片段被静默地遗漏。检查已放置的数量是否等于片段数量。
7. 预览,然后交付
在真实素材上构建一个 10-15 秒的预览,以便用户在执行之前进行判断:
ffmpeg -y -ss <t> -t 11 -i "<cut>" -itsoffset <a> -i "<clip1>.mov" -itsoffset <b> -i "<clip2>.mov" \
-filter_complex "[0:v][1:v]overlay=0:0:eof_action=pass[v1];[v1][2:v]overlay=0:0:eof_action=pass[vo];[vo]scale=1280:-2[v]" \
-map "[v]" -map 0:a -c:v libx264 -crf 20 -preset veryfast -c:a aac PREVIEW.mp4
原始音频会随素材一起提供,预览只需要这个。
然后给出导入步骤(文件 > 导入 > 时间线 > 导入 AAF、EDL、XML,选择 starts-01 文件,将片段复制到素材上方的一个轨道上,起始点为 01:00:00:00)。
直接在 Resolve 内部工作(当 Resolve 打开时首选)
如果安装了 resolve MCP 服务器(例如第三方的 barckley75/resolve-claude-mcp),它可以与 Resolve Studio 的脚本 API 通信。如果 paper-edit 技能附带了一个 ensure_resolve.sh,请先运行它,以便在 Resolve 关闭时启动它。使用 偏好设置 > 系统 > 常规 > 使用本地进行外部脚本编写,优先于导出和导入的步骤。
它改变了什么:
- 不再需要导出的剪辑。 读取打开的时间线以获取其真实的时间码、帧率、开始时间码和剪辑布局,然后将叠加层锚定到该时间线上。这解决了“每次重新修剪时间码都会变化”的问题。
- 无需手动导入。 直接将渲染好的
.mov片段放置到一个视频轨道上。 - 更好的时机选择。 看到已存在的剪辑点的位置意味着叠加层可以与剪辑点对齐,而不是与之冲突。
- 当叠加层就位后,它还可以启动渲染。
使用它的规则:
- 先读取再写入。 首先确认项目名称、时间线名称、开始时间码和帧率,并向用户复述。
- 绝不写入主时间线。 首先复制它,在副本上工作,这样错误不会造成任何损失。
- 除非常规工具无法完成工作,否则避免使用
execute_resolve_code。 它会在用户的项目中运行任意的 Python 代码。如果它是唯一的方法,请先展示代码。 - 仅限本地会话。 Resolve 必须在此 Mac 上运行,因此这在云环境或计划任务中永远无法工作。在那里回退到 FCPXML 方法。
- FCPXML 路径仍然有效,并且仍然是后备方案。 继续生成这两个文件;这只会花费几秒钟。
音频转录: 某些 Resolve MCP 服务器带有自己的 mlx-whisper 转录功能,但上面的 whisper.cpp 步骤在此流水线中已经过验证。
片段类型
以下所有内容对于新视频均已弃用(保留以便重新剪辑旧视频)。请使用下一节中的场景内类型。全屏类型会绘制一个纯黑的背景,带有柔和的强调色发光效果,因此它们会完全遮住说话者。角落标签位于左下角。
| 类型 | 用途 | data |
|---|---|---|
full-dots | 已弃用,请使用 dots | lit、pct、count |
full-flow | 已弃用,请使用 flow | label、steps[]、good |
full-compare | 已弃用,请使用 compare | title、left{label,value,sub}、right{...,hi}、vs |
full-bars | 已弃用,请使用 bars | title、bars[{label,value,value_label,hi}] |
full-math | 已弃用,请使用 math | parts[](运算符 x = + → 以强调色渲染),sub |
full-pack | 已弃用,请使用 bars 或 side | name、note、size 0-1、hi |
full-stat | 已弃用,请使用 pair | label、value、sub、hi |
full-title | 已弃用,请使用 pair 或 type | title(允许 <br>)、size、sub |
full-list | 已弃用,请使用 list2 | title、items[]、step 秒 |
chip | 已弃用,请使用 side 或 num | num、title、sub、hi |
chip-stack | 已弃用,请使用 list2 | items[] |
已弃用的类型仍然可以渲染,用于重新剪辑旧视频。
场景内类型(默认)
无卡片,文字位于房间里说话者头部旁边,大标题位于头部周围。
| 类型 | 用途 | data |
|---|---|---|
pair | 关键句标题:头部上方轮廓线,前额高度处的实线 | top、bottom、outline(top/bottom) |
side | 头部旁边的 2-3 行短文字,每行落在其词语上 | lines[]、accent(索引,大号 + 强调色),at[] |
type | 引述或问题,随着它被说出逐词打出 | words[{w,t,hi,br}] |
define | 已弃用:会使画面变暗。请使用 side 或 pair | word、sub |
num | 轮廓数字绘制出来,旁边有文字(例如“01 plan the week”) | num、lines[] |
list2 | 项目在头部左侧和/或右侧构建 | left[]、right[]、at[](按顺序,左侧优先) |
场景内图表(相同的墙面放置和蒙版):
| 类型 | 用途 | data |
|---|---|---|
dots | 每 100 个的比率,说话者旁边的网格填充 | lit、pct、count |
flow | 一个流程,步骤从上到下链接,最后一个使用强调色 | label、steps[]、at[] 可选 |
bars | 按大小排列的两个或三个数字 | title、bars[{label,value,value_label,hi}] |
compare | 两个选项,头部两侧各一个 | left{label,value,sub}、right{...,hi} |
math | 一个方程式在墙上垂直读出,运算符引导每一行 | parts[]、sub |
at 和 t 是从片段开始起的秒数;根据词级时间戳构建它们,以便每一行落在其词语上。
这些需要 FOOTAGE=,即没有叠加层的剪辑(从 Resolve 渲染时间线,禁用叠加层片段)。渲染器会读取每个片段的面部框和背景亮度网格,以便文字找到空的墙面,如果会溢出画面则翻转侧边或缩小,并在浅色背景上使用深色文字,深色背景上使用浅色文字。它会从每个场景内片段的每一帧中抠出说话者(使用 Apple Vision 人物分割,person.swift),因此标题位于头部后方,手势经过图形前面。编译一次:swiftc -O person.swift -o person。如果没有 FOOTAGE 变量,图形会有一个灰色背景,这会破坏沉浸感。
布局规则
pair 的默认行为是环绕头部。它从 data 中的 top 和 bottom 行构建一个标题,并尝试找到它们之间的最佳分割点,以将两半放置在头部两侧。如果 data 包含 "around": false,则标题将像普通 pair 一样居中。
对于 side,行被放置在头部旁边。它们永远不会覆盖脸部。
对于 type,单词出现在头部上方的一个框中,并从左向右填充。
对于 list2,项目在头部左侧和右侧构建。
对于场景内图表,它们被放置在头部旁边,就好像它们挂在墙上一样。它们永远不会覆盖脸部。
提示
- 使用
scripts/plan.example.py作为如何规划剪辑的模型。它展示了如何引用短语、命名提示词以及执行查找。 - 使用
node proof.mjs在真实素材上验证帧。 - 使用
ffmpeg从片段中提取帧,以便在合成之前检查它们。 - 如果 Resolve 打开,请使用 MCP 与其交互。
- 始终生成两个 .fcpxml 文件,以便在没有 Resolve 的情况下也能进行导入。