工作室演示视频
构建一段时长约 90–180 秒的旁白演示视频,内容关于用户指定的任何产品——macOS 应用、网站、CLI 等均可进行屏幕录制。唯一固定的部分是旁白后端:video-studio-mlx Studio API(POST /studio/tts),它会克隆一个声音并验证每一句台词。演示的主体是任意的,每次都会改变。请记住这种分离:不要假设演示目标就是 video-studio-mlx 本身(那只是 references/ 目录中的示例)。
核心原则:旁白优先,精确时长锚定
在录制任何画面之前先生成旁白。/studio/tts 会返回每个片段的精确时长以及逐词时间戳——这些将驱动整个时间线和所有焦点效果。然后,充分录制素材,并将每个剪辑片段适配到其对应的旁白片段。先剪辑片段再录制语音会导致脆弱的重新计时。
你通常无法播放或听到输出内容。请将其视为硬性约束:通过提取视频帧进行验证,并通过在完成文件上运行 ASR(自动语音识别)来验证音频内容和同步。所有构建都必须能够以这种方式进行检查。
工作流程
- 编写逐场景的故事板——包括旁白文本、画面动作、字幕,以及(每个场景下)旁白中提及的元素,以便焦点可以指向它们。目标语速约为 2.1 词/秒(约 170 词 ≈ 80 秒)。复制
references/storyboard.example.json到<work>/storyboard.json。措辞要确保每个被命名的元素在该场景的画面中都实际可见且顺序正确。为听觉而写:按照词语的发音方式来拼写,而不是书写方式——展开缩写和首字母缩略词(例如,使用 "regular expression" 而不是 "regex",使用 "version three" 而不是 "v3"),避免使用裸露符号(~,/,&),在不确定时用单词书写数字和单位。TTS(文本转语音)系统会按字面文本朗读,ASR 也会据此验证,因此仅用于书写的缩写既会导致发音错误,也会使词错率(WER)失真。 - 生成旁白——运行
scripts/generate_narration.py <storyboard.json>。将每个场景 POST 到/studio/tts,从一个固定的声音(用户的ref_audio,或下面描述的voice指令设计的声音)克隆每个场景的声音,进行 ASR 验证,并写入narration/manifest.json,包含每个片段的duration_s、wer和逐词words。(参见references/studio-api.md。) - 录制目标——为应用的/网站的每个场景录制一个剪辑片段(参见录制部分),以及一个命名元素矩形映射,用于指示焦点将指向的元素。
- 合成——运行
scripts/compose.py <storyboard.json>:将画面素材放置在渐变背景的框架内,使用 Pillow 生成字幕,对英雄镜头进行缓慢缩放,应用基于旁白时间戳的焦点效果(缩放 + 指示圈),用 xfade 过渡场景,将旁白放置在计算好的时间线上,最后进行混流。 - 验证——为每个场景生成胶片条;在焦点效果对应的目标词语时间点提取一帧,确认高亮区域在正确的命名元素上;对两到三个片段进行 ASR 验证,确认正确的台词落在正确的场景上。
前置条件
- Studio API 可达(默认
http://127.0.0.1:8100)。设置、声音克隆以及对齐/单词时间戳的约定在references/studio-api.md中。 - 一个 3–15 秒的参考 wav 文件(24 kHz 单声道)及其精确转录文本用于声音克隆——先用
/asr确认转录文本的准确性(克隆质量取决于音频↔文本的对齐,而非“推荐”长度)。 - 整个视频使用同一个声音。 每个场景都是一个独立的
/studio/tts调用,因此只有在每次调用都克隆同一个共享参考声音时,声音才能保持一致。如果用户提供了参考声音,则从中克隆;否则,在故事板中设置一个voice指令设计,generate_narration.py会预先设计一个剪辑片段,并从此片段克隆每个场景的声音(会缓存,因此重新运行会保持相同的声音)。如果两者都没有,每个场景将独立合成,音色会在场景间漂移——对于正式视频应避免这种情况。 - 需要 ffmpeg,并包含
avfoundation(macOS 录制)、zoompan、xfade、gblur。drawtext经常缺失(没有 libfreetype)——字幕使用 Pillow 渲染。 - 对于网站目标:需要 Playwright(或 Puppeteer)进行确定性录制和元素边框获取。
录制目标
每个场景需要目标产品的两样东西:
- 一个屏幕录制的剪辑片段(录制时长要超过旁白——点击后的结果和加载动画可能需要几秒钟),以及
- 一个命名元素矩形映射:对于旁白中将命名的每个元素,其在画面像素中的矩形坐标(即合成剪辑所使用的坐标空间)。
目标的 UI 框架决定了如何获取这些信息。两种后端:
macOS 应用 —— AppleScript + ffmpeg avfoundation
- 录制
avfoundation "Capture screen N"并实时裁剪到应用窗口。进行一次探测(录制约 1.5 秒,提取一帧,确认crop=W:H:X:Y)。显示器是 Retina 屏幕,因此物理裁剪 = DPR × 逻辑尺寸(DPR 通常为 2)。 - 使用系统事件(System Events)驱动。针对这个应用的工具包找到可靠的原始操作——它们因应用而异。 需要注意的常见问题:
- SwiftUI/AppKit 列表中的坐标点击通常无效;应改用 AX
select/AXPress来操作元素。 - 分段控件暴露为
AXRadioButton;通过角色查询它们。 - 在视图切换后立即进行 AX 查询可能会遇到竞态条件(返回空结果)——请重试,或者完全避免在会话中进行导航。
- 如果导航不稳定,以所需状态重新启动应用(通过启动参数/环境变量/应用支持的 URL 方案),然后只触发一个镜头前的操作。这种方式廉价且确定。
- SwiftUI/AppKit 列表中的坐标点击通常无效;应改用 AX
- 使用
-capture_cursor 0(AX 操作不会移动指针,因此光标会保持在画面外)。如果需要在画面中显示光标,可以在后期合成一个(参见“焦点效果”部分)。 - 元素映射: 查询每个元素的 AX
position+size,并转换为画面像素:(全局坐标 − 窗口原点) × DPR。如果工具包隐藏了字段的矩形坐标,可以从带网格的画面帧中测量。当画面帧和过时的 AX 数字不一致时(例如滚动状态不同),以画面帧为准;验证每个焦点帧。
网站 —— Playwright(推荐,优于屏幕录制)
- 使用
recordVideo录制;设置recordVideo.size等于viewport,并在合成前将 webm 标准化为你所需的帧率。 - 坐标空间(第一陷阱): Playwright 以视口大小进行录制,因此当
recordVideo.size == viewport时,画面像素 == CSS 像素。deviceScaleFactor: 2仅用于锐化渲染——它不会缩放录制的视频,而recordVideo.size大于视口只会用黑色填充额外区域(页面保持在左上角以 1× 显示,不会放大填充)。因此,boundingBox()直接给出画面像素——不要乘以 DPR。(如果你曾经以不同尺寸录制,请按recordedSize / viewport缩放矩形。)务必验证:在录制所有场景之前,先在提取的帧上叠加一个已知的矩形进行验证——错误的 DPR 假设会静默地将每个焦点指示圈放在错误的位置。 - 在固定的滚动位置捕获所有矩形: 先完成所有滚动,等待稳定,然后读取所有
boundingBox(),再保持稳定。指示圈存在于画面坐标中,并且必须在镜头缩放/平移时保持固定。如果你想要自动焦点,可以从页面时钟发出交互轨道。 - 首先稳定页面:禁用 CSS 动画/
prefers-reduced-motion、关闭 Cookie 横幅、隐藏滚动条,并waitForLoadState('networkidle')以确保没有内容在录制时突然弹出。如果应用支持,可以通过addInitScript在导航前注入localStorage实现自动认证。 - 动画效果:对于长页面,可以捕获全页截图并进行平移(垂直 Ken Burns 效果),而不是录制抖动不停的实时滚动。
真实模型画面——展示真实输出,隐藏等待时间。 当某个场景必须实时运行一个慢速模型(如真实字幕/聊天/推理),请录制真实流程,但对等待时间进行时间扭曲:标记每个 点击 → 结果 时间窗口(从页面启动开始的单调时钟),然后仅使用 ffmpeg(trim+setpts+concat;操作部分保持 1× 速度)压缩这些窗口,并冻结最后一帧(tpad=stop_mode=clone),以便任何场景持续时间都能在结果上播放出来。首先用一个一次性请求预热模型——冷启动加载时间可能是热调用的 10–40 倍(例如,一个视觉模型:冷启动约 38 秒 → 热调用约 5 秒)。在扭曲后的剪辑片段上措辞并计时旁白;保持这些场景的普通播放(操作本身提供了动态感)。完整配方和代码片段:references/playwright-recording.md。
一个完整的 macOS 示例(精确选择器、环境钩子、裁剪矩形、元素矩形和一体化录制脚本)位于 references/video-studio-mlx-app.md——该示例恰好演示了托管 Studio API 的同一个应用,但请将其具体内容视为说明;你的目标应用将有自己的一套。
合成(scripts/compose.py)
配置驱动,与目标无关。每个场景被制作成一个标准化的 1080p 剪辑片段:画面素材缩放后放置在一个带阴影的暗色渐变背景卡片内,一个 Pillow 生成的字幕(步骤说明使用底栏药丸样式,英雄镜头使用大标题+副标题背景幕),剪辑片段和字幕淡入淡出,然后是一个共享的最终调色(色彩调整 + S 曲线 + 冷色阴影 + 暗角 + 胶片颗粒 + 去条带),使不同的录制素材读起来像一部导演的电影(设置 "grade": false 可禁用它,或传递一个块来调整 strength/tint 参数)。英雄场景会获得一种电影化处理:在静态画面上加一个缓动(ease-out)的漂移 Ken Burns 推进效果,卡片后面放置一个磨砂深色的背景底板,以及一个分步的标题-然后-副标题淡入效果。剪辑片段之间使用逐场景的 xfade 过渡(默认 fade;可按场景设置 transition/xfade_dur——过渡到英雄镜头时使用 fadeblack 效果不错)。音频:旁白通过 adelay 放置到主时间线上,并通过 amix 混合(normalize=0);可选的背景音乐会在人声下进行侧链闪避,最终混音会通过 loudnorm 标准化到 −16 LUFS(仅人声时也进行标准化)。
焦点效果——基于旁白时间戳(缩放和指示圈跟随词语)
焦点必须指向旁白正在命名的内容,并且恰好在其被说出的时候——因此它是作为 短语 → 元素 来编写的,根据词语时间戳计时,从不手动设定秒数,也从不固定到单个元素贯穿整个场景。一个场景声明一个 view(使用哪个元素矩形映射)和一个 focus 列表(元素/视图名称随你的目标应用而异):
"view": "main",
"focus": [
{ "say": "search", "element": "search_field" },
{ "say": "results", "element": "result_list" },
{ "say": "generate", "element": "primary_button", "zoom": 1.7 }
]
合成器解析流程:
- 何时触发 —
resolve_phrase在片段的words中找到与say匹配的连续词语序列,并返回 [start,end]。重复词语不会引起歧义:词语列表是按位置索引的——通过occurrence选择(默认为首次出现)。在剪辑片段时间线lead + word_start处播放。 - 指向哪里 —
element是场景对应view的elements.json中的一个矩形(或使用map:key来引用共享映射,例如一个持久的侧边栏)。 - 镜头运动 — 多关键帧
zoompan(focus_camera),基于绝对on值的平滑步进。在两个焦点之间,默认情况下直接滑动从一个目标到下一个目标;仅当下一个目标既远(超出前一个缩放视口)且时间间隔足够长(focus_gap_full,约 2.2 秒)时,它才会返回到全视图——因此,相邻/已可见的元素只会稍稍平移,而不是突兀地缩小/放大再缩小。平移是恒定速度(时长 = 距离 ÷focus_pan_speedpx/s,受focus_move_min下限约束):摄影机保持之前的构图,然后以固定的 px/s 速度滑动,正好在下一个词开始时到达——近距和远距平移感觉一致,而不是“先慢后快”。设置"focus_pan": true可强制全程直接滑动。 - 指示圈 — 在镜头缩放之前于画面坐标中绘制,因此当镜头缩放/平移时,它会始终粘在元素上;在短语前后淡入淡出。
- 缩放和指示圈是解耦的,并且缩放会自动适配进行裁剪(
fit_zoom):缩放会被降低,以便高亮元素始终完全可见;一个宽大的目标会降级为仅指示圈(z=1),以免被裁剪。默认情况下不要将它们配对——两者都只是为了引导视线;根据目标元素的大小选择合适的方式。设置ring:false可实现不带指示圈的柔和缩放。
支持数据和扩展:
- 元素映射(
elements.json):每个视图下以画面像素为单位的命名矩形。请参阅“录制”部分了解如何获取它们;通过检查每个焦点帧进行验证。 - 录制尺寸要大于最终展示尺寸,以便缩放时保持清晰——摄影机将原始画面裁剪到舞台上显示的尺寸,因此约 1.7× 缩放仍有真实像素。在 macOS 上,Retina 录制已经进行了过采样。在网页上,
deviceScaleFactor并不会放大录制的视频(参见“录制”部分)——要获得过采样,请以大于舞台上卡片尺寸的viewport/recordVideo.size进行录制(例如,以 1920 宽录制,放入约 1456 的卡片中),而不是通过提高 DPR。 - 录制器可以发射一个交互轨道(
emit_track.py),以便track_to_effects自动为每次点击派生缩放+指示圈效果;内联的focus是精确路径。该结构对使用相同矩形和词语时间的cursor/spotlight覆盖层是开放的。
设计说明(为何使用短语→元素,而非 API 端的提示标记): 词语时间戳已经是一个基于位置的列表,因此合成器拥有“哪个元素/哪个出现”的所有权——Studio API 保持为一个干净的原始服务(音频 + 词语时间),可用于演示任何产品。画面素材必须在那个时刻实际显示(未滚动/静态)所命名的元素;请据此措辞旁白。
时间线计算(保持视频和音频一致)
- 场景时长
d_i = narration_i + pad_i(pad≈ 步骤场景 2 秒 / 英雄场景 3.4 秒)。 - 主时间线上场景的开始时间按过渡累积计算:
start_0 = 0,start_i = start_(i−1) + d_(i−1) − T_i,其中T_i是进入场景i的 xfade 过渡时长(按场景设置的xfade_dur,默认为xfade;下限受相邻两个剪辑片段的限制)。当所有T_i = T时,公式简化为Σ d_(<i) − i·T。 - 将场景
i的旁白放置在start_i + lead处(lead约 0.8 秒,在进入交叉淡入之后)——使用相同的重新计算的start_i,因此音频保持同步。确保tin_i + d_i ≤源剪辑片段的长度。
验证(……)
(注:由于输入内容在“Verification (yo…”处截断,markdown 翻译无法包含完整内容。但前面所有已给出的内容均已按规则翻译。)