kelvinmacaco/short-build

短视频组装

属于 short-start 流程的一部分。媒体细节参见 short-media，动画细节参见 short-animation，检查和渲染参见 short-review。辅助工具：hyperframes、hyperframes-cli 和 media-use。

请先阅读项目的 RULES.md 和 ROTEIRO.md。项目的 kit.json 必须包含 handle（创作者选择的 @）。如果为空或为 "@SEU_CANAL"，在继续之前先询问创作者。

1. 旁白

• 将 mp3 复制到 assets\audio\narracao_raw.mp3。
• 使用 silencedetect=n=-40dB:d=0.6 检测长停顿。缩短落入钩子中的停顿，如果语气充满活力，则缩短大于 0.8 秒的停顿。使用 tools\ffmpeg_recipes.md 中的拼接方法。
• 使用 build\transcribe.py 进行转录，生成 assets\audio\narracao_words.json，其中包含每个单词的时间。
• 均衡：python -I -X utf8 build\level_voice.py <mp3> <words.json> video\assets\audio\narracao.mp3。
• 将 template\video\ 中的 hyperframes.json、package.json、meta.json、AGENTS.md 和 CLAUDE.md 复制到 video\。调整 meta.json 中的 id。

2. 媒体

• 在嵌入式浏览器中，于 pexels.com 页面上运行 tools\pexels_search.js，一次进行多次搜索。
• 下载缩略图，使用 ffmpeg tile 拼贴成一张表，在选择之前先查看。
• 丢弃标志、商标、球队球衣以及与旁白不匹配的内容。
• 使用 curl -L -A "Mozilla/5.0" -e https://www.pexels.com/ 下载到 assets\video\stock\。
• 音轨：来自 Pixabay，仅选择未标记 "Content ID Registered" 的曲目，保存到 video\assets\audio\musica.mp3。
• 音效：参见 tools\sfx\README.md；保存在 video\assets\sfx\。
• 使用食谱剪辑片段（垂直 1080×1920 或电视窗口 1000×750），输出到 video\assets\video\。制作钩子的反转片段用于循环。
• 不要调用名为 cut 的 shell 函数，因为这会隐藏系统的 cut 命令。

3. 场景（build\generate.py）

• 从 template\build\generate.py 开始，该文件带有注释。使用 SCENES = [(名称, 开始, 结束)]，其中时间与单词的时间戳对应；每个场景内的时间是局部的（0 = 场景开始）。
• 使用 lib_short 中的组件：
  • 文本：kline/words_js/slam/punch/shake/label；
  • 数字：使用 onUpdate 的计数器；
  • 点赞和分享：like_block/plane_svg；
  • 交互：comment_card/follow_card/step_badge。
• 每个场景都有动画。 如果列表要求进度，制作一个主题指示器作为覆盖场景（例如：库中的 pavio_scene，一个导火索随着每个项目燃烧并在高潮处爆炸）。
• 字幕： write_captions(WORDS, TOTAL, SKIP, alt_from, alt_top)。SKIP 覆盖场景排版已经显示旁白的部分。
• 索引： write_index(TOTAL, SCENES, SFX, dur_voz, 0.1, handle=HANDLE)。HANDLE 来自 kit.json，通过 build.ps1 传递。
• @ 标志放在字幕下方 (WM_TOP)。不要手动定位标志。
• 循环： 最后一个场景以钩子的第 0 帧反转片段结束，并使用相同的标题。
• 结尾与视频基调一致： 对于沉重、黑暗、缓慢的视频，不要有爆裂。
• HyperFrames 规则：
  • class="clip" + data-start/data-duration；
  • 不要动画化剪辑本身的 visibility 或 opacity，只能动画化内部元素；
  • 在后续的 fromTo 中使用 immediateRender:false；
  • 每个 <audio> 都有独立的 id 和 track；
  • 视频始终 muted；
  • SVG 线条使用 pathLength="1" 实现绘制效果。

4. 生成、检查并渲染

• 在 build\build.ps1 中调整 $alvos：包含视频拍摄的场景，.fv（全屏）和 .tv（电视窗口）。
• 运行 powershell -ExecutionPolicy Bypass -File build\build.ps1 -Duracao <TOTAL>。切勿将输出通过管道传递给 Select-Object -First。
• npx --yes hyperframes@<版本> check --json：修复错误。预期中可能保留的问题：
  • 半透明标志的对比度；
  • 循环标题过短。
• 拍摄快照（snapshot -o <文件夹> --no-end --at "..."）并查看联系表。检查：
  • 文本超出屏幕；
  • 字幕难以辨认；
  • 元素被遮挡；
  • 场景静止。
• 使用 render --quality standard -o renders\<名称>_master.mp4 渲染，并用 ebur128=peak=true 测量（目标：约 -13.5 LUFS，峰值低于 -2 dBTP）。
• 使用 x264 CRF 19、AAC 192k 和 +faststart 复制到桌面。
• 检查循环：将第 0 帧和最后一帧并排比较（hstack），必须相同。
• 编写 video\REVIEW.md，记录决策、测量值以及仅凭肉眼判断的内容（"没人听到声音"）。

5. 交付

发送视频、标题（TikTok 和 YouTube，各带 5 个 #）、描述和置顶评论。提醒发布时间，并索要 48 小时后的截图。