vstoos/vlog-film

Vlog film

将用户文件夹中的素材变成一部完成版YouTube影片，然后根据用户的反馈进行迭代修改，直到用户满意。该流水线基于“Yaris farewell”影片（24分钟，乌克兰语语音，iPhone + Sony行车记录仪）；references/example_yaris.py 是该影片的完整项目文件，是了解完成版编辑效果的最佳指南。

开始之前

• 设置。 <skill>/config.json 保存了机器的路径（ffmpeg、melt、安装了WhisperX和torch的Python、车牌模型、音乐文件夹、编码器、语音语言）。如果缺少该文件，或者某个脚本因缺少工具而失败，请运行 python <skill>/setup/setup.py（仅检查）并向用户显示缺少的内容；在用户同意后运行 python <skill>/setup/setup.py --install。使用config.json中的 "python" 运行以下每个脚本，因为WhisperX和torch都安装在那个Python环境中。
• 用户。 如果 <skill>/user.md 存在，请读取它：它说明了用户是谁、使用哪种语言回复以及用户的固定偏好。如果没有该文件：使用用户的语言回复，保持回复简短，用 mm:ss 表示用户应该查看的影片时间。
• 在下面的命令中，$K 是 <skill>/scripts，python 是已配置的Python。

项目布局

素材保留在用户放置的原始位置；最终的mp4、YouTube描述、缩略图和字幕也放在那里，因为用户会在那里查找。工作文件放在项目文件夹中（例如 C:/Data/<name>-video/）：

<name>-video/
  project.py        路径、EDL、HOOK、音乐、取景、make_stills()   (复制 references/project_template.py)
  transcripts/      <clip>.json 由 transcribe_all.py 生成
  film/             渲染后的插入片段、<clip>_blur.mov、<name>.mlt、<name>.mp4
  film_check/       联系表、测试wav、检查帧（临时文件）
  edit_notes.md     用户的审阅笔记以及针对每条笔记的执行操作
  subs/, thumbnail/, route/

工作流程

1. 盘点

1. python $K/scan_meta.py <footage> film_check/meta.json：每个文件的时间、时长、GPS。按时间排序后，这即为故事顺序。
2. 先查看再决定：对素材使用 python $K/contact_sheet.py <out.png> 6 <clips...> 生成平铺图，对照片生成平铺图；自己查看图像。注意纵向素材（旋转 -90/90 的）、显示车牌的素材、行车记录仪文件、屏幕录制。行程日期内的Tesla行车记录仪/Sentry事件：参考 references/teslacam.md（查找事件，通过 teslacam_grade.py 调整色彩）。
3. python $K/transcribe_all.py <footage> transcripts：对每个说话的素材生成带有单词时间戳的WhisperX转录（可恢复，语言来自config）。全部阅读；它们是故事的原始材料。

2. 故事和EDL

在构建之前，先用几行向用户提出结构建议：预告片、各个部分、哪些照片、地图或静态图片用于说明哪段对话。典型结构：

• 预告片 (HOOK)：来自整个行程的4-6个简短有力的短语，每个都是一个完整的想法。
• 标题卡放在路景素材上，然后是由4-10秒的路景插入（配乐）分隔的对话块。
• 当对话中提到某物时插入相关内容：提及燃料时插入收据，提及检查时插入检查台，每段行程开始时插入路线图。
• 语音上的图片（B-roll、手机截图、说话者继续说话时的字幕）：使用 burn_in.py 将它们嵌入到说话的素材中，然后在filmkit中使用（它仅在说话时显示该素材）。纵向图片（截图、纵向素材、纵向照片）以完整帧高放置在说话者脸部的自由一侧，由人脸检测确定，以确保脸部可见；手机的时钟和按钮无论如何都会填充顶部和底部。横向图片则覆盖整个帧。
• 路景插入应展示故事在那一刻需要的内容（进入加油站的岔路（在“我们停下来”之前），机场场景之前的机场停车场），而不是任何高速公路：在合适时刻查看路景素材的联系表。
• 结束卡：在路景素材上持续20秒，文本在顶部，中部留空供YouTube片尾图块使用；如果用户有推荐链接，则在此处放置。

从 references/project_template.py 编写 project.py；EDL项目类型、字幕、音乐键和每个素材的选项都在那里有文档说明。对话范围来自转录时间。

3. 构建和渲染

python $K/blur_plates.py <footage> <project>/film [--faces] IMG_0089 ...   # 车牌；--faces：也包括人脸
python $K/burn_in.py film/IMG_0089_blur.mov film/IMG_0089_over.mov spec.json   # 语音上的图片（如果有）
python $K/filmkit.py <project>/project.py                        # 渲染插入片段，写入 film/<name>.mlt
python $K/render_final.py <project>/film <name> <footage>/<Name>_HLG.mp4   # 耗时较长：在后台运行

在执行繁重的GPU任务（渲染、WhisperX、配音）之前，运行 nvidia-smi：显卡编号在会话之间会改变，并且在不同工具之间也可能不同，其他任务可能占用某块显卡（参考 references/lessons.md，“GPU和硬件编码器”部分）。 filmkit.py --no-media 仅重写 .mlt 文件（耗时仅数秒）。渲染过程会打印响度、时长、编解码器/HDR标签以及绿色帧计数：预期值约为 -14 LUFS、Main 10、arib-std-b67、bt2020、0个绿色帧。

4. 在告知用户完成之前进行验证

使用WhisperX进行监听，而不是依赖EDL：对于每个新更改的剪切部分，从完成的mp4中剪出相同的秒数并进行转录（python $K/transcribe_window.py <wav> <offset>）。第一遍转录常常在短语结束位置出错，尤其是数字，因此根据它们进行的剪切会砍掉结尾（例如“не 144, а 147”丢失了“а 147”）。同时测量相邻片段的响度（ffmpeg -ss A -t N -i film.mp4 -af ebur128 -f null -），并查看每个新插入片段的一帧。其他陷阱及其修复方法：参考 references/lessons.md。

5. 审阅轮次

用户观看并通过影片时间发送笔记。对于每条笔记：

1. python $K/timeline.py film/<name>.mlt 12:22 会显示素材名称和源素材秒数。
2. 检查源素材（转录一个窗口、测量响度、查看帧）。告诉用户实际内容，引用原始词语；用户的记忆有时会与录音不同。
3. 修改EDL并在 edit_notes.md 中记录（影片时间、素材和秒数、说了什么、更改内容）。

在用户仍在观看时，收集笔记，不要重新构建：最后一次性构建可以节省长时间的渲染。当用户说可以构建时，重新构建一次，按照步骤4验证每个更改过的位置，更新章节。

6. 交付物

references/youtube.md：包含章节的描述（使用 timeline.py）、缩略图（使用 make_thumb.py）、字幕（对完成影片使用 make_subs.py，手动修正，然后逐个提示进行翻译，同时屏幕上的文字通过 onscreen_subs.py 作为独立的字幕进行翻译）、YouTube自动配音。用户可以通过手机使用 python $K/media_server.py --port 8765 <footage> <project>/film 观看渲染结果（仅限LAN/VPN；只读；也可访问 github.com/vstoos/media-server）。

7. 配音音轨

对于用户希望听到而不是阅读的语言：参考 references/dubbing.md。语音使用Higgs TTS 3（自2026年11月6日起为默认设置），并使用用户在该语言中保存的参考语音（C:/Data/voices，传递 -）；每个带有Higgs音轨的影片描述都会注明“Boson AI's Higgs Audio”。字幕通过 dub.py gen 处理，dub_check.py 逐个片段捕捉模型的缺陷，dub_regen.py 替换失败的部分，dub.py mix 构建音轨并打印出需要监听的内容。在 say.json 中修复发音。对静默素材（行车记录仪素材）的旁白采用相同的路径，使用乌克兰语，写为字幕。不要仅凭检查就判定配音干净：用户的耳朵是最后一道关卡。

隐私

车牌：用户不对普通交通车辆进行模糊处理（波兰；浮动框会破坏路景）。仅在素材显示该驾驶员可能存在违规或危险驾驶时对车牌进行模糊处理，这样影片就不会被用来针对他人提出投诉；路景插入通过项目中的 CLIP_SRC 原样使用。模糊员工、路人和儿童的人脸（使用 blur_plates.py --faces；检查帧，汽车漆面反射可能欺骗检测）；路线图从公共场所开始，绝不从用户家开始；未经要求，不得将他人（尤其是儿童）的脸部放在缩略图上。

参考文件

• references/project_template.py：带注释的项目文件，供复制使用；EDL语法说明。
• references/example_yaris.py：完成的Yaris影片，所有特性均已使用。
• references/lessons.md：HDR、音频、剪切和取景陷阱，以及有效的修复方法。
• references/teslacam.md：Tesla行车记录仪/Sentry素材（HW3）：在保存的事件中查找事件，以及色彩校正（scripts/teslacam_grade.py）。
• references/youtube.md：描述、章节、缩略图、字幕、配音、片尾画面。
• references/dubbing.md：用户克隆语音的独立音轨，以及自动故障检查。
• references/example_make_route.py：来自Yaris影片的动画路线图（Sentinel-2瓦片 + OSRM道路）；对于新行程，调整其常量（范围、城市、图钉、路段）。