morrimoz/talking-head-clip-review

人物访谈片段审阅（Talking-head clip review）

将原始的人物访谈素材转变为已批准的精选片段，无需任何人手动逐帧浏览。Agent负责转录、对齐和提出建议。用户在一个页面上进行批准。然后Agent组装出完全批准的内容。

转录过程保留在本地机器上。原始视频永远不会被修改。

硬性规则

• 永远不要修改、移动或重新导出原始视频。所有处理都是基于入/出点以及派生文件。
• 永远不要删除用户的素材或清空回收站。如果磁盘空间紧张，请告知用户并让他们自己处理。
• 在临时文件夹中工作。只有预览、海报、审阅页面和精选片段才放在媒体文件旁边。
• 不要编造措辞。片段文本来自转录。可选的短语修正通过--fix传递的JSON映射（参见references/term-corrections.example.json）。不要应用示例文件。
• 根据实际录制检查摄像头上说出来的事实（时间、数字、“10分钟前”），然后再选择它们。
• 在保留的片段中，不得有视线看监视器、麦克风碰撞、咔嗒声或呼吸声。在任何重新编辑后，重新运行注视检测（步骤5）并听取每个编辑点，而不仅仅是在第一次选择时。静音或剪切噪音，而不是其旁边的单词。
• 补录和重新录制的台词必须与主拍摄的语气、音量和房间环境相匹配（相同的麦克风、增益、距离、均衡器和降噪）。标识出听起来会发闷或发紧的台词，而不是将其交付出去。
• 在写给用户的任何内容中使用连字符，而不是破折号。
• 单词边界是硬性限制，即使提示要求紧密裁剪或视线修剪。片段在Whisper的词级时间戳前后各包含0.15秒的前滚和0.25秒的后滚（Whisper的词边界通常偏早或偏晚），并进行限制，使其永远不会侵入相邻单词。停顿和视线修剪仅在单词之间的间隙内进行，并在每个单词旁边保持至少0.1秒。如果视线偏离与一个正在说的单词重叠，则保留该单词并标记它（away_words，在片段串接中显示红色边框），永远不要剪切它。使用build_review.py --gaze-trim进行边缘修剪，而不是编写自己的修剪脚本。手动设置的exact_spans也会被推回到单词边缘。

设置（每台机器只需一次）

运行 scripts/check_deps.sh。它需要 ffmpeg、ffprobe、python3 和一个 Whisper 后端。Swift 对于注视步骤是可选的。安装步骤：references/setup.md

目录布局

WORK/                      临时文件夹，例如 ./talk/
  tx/<take>.wav|json|txt   16 kHz 单声道音频，包含词级时间戳的 whisper JSON，可读的转录文本
  picks.json               节拍 + 候选片段（由Agent编辑）
  picks_resolved.json      精确到词的跨度、文本、时长（由生成）
  pose.json                视线偏离间隔（可选，macOS）
REVIEW/                   放在媒体文件旁边，例如 ./review/
  previews/<take>.mp4      用于页面的 540p H.264 副本
  posters/<beat>-<i>.jpg
  "<标题> - take review.html"
  "<标题> - picks stringout (540p).mp4"
SELECTS/                   selects.json, selects.csv, selects.edl, selects.mp4

以作品名称命名剧集，例如 launch-01。保持拍摄键名简短（A、B、C）并在picks.json中将其映射到文件名。

步骤

1. 盘点。 对每条拍摄使用 ffprobe（时长、大小、帧率、旋转）。手机素材通常是可变帧率且竖屏的。预览和渲染会将其标准化。询问哪些文件是用于剪辑的调色导出，哪些是需要忽略的相机原始文件。
2. 转录。 python3 scripts/transcribe.py --out WORK/tx TAKE...。如果 Whisper 包不在默认的 python3 上，请使用 check_deps.sh 报告的解释器。如果文件仍在导出中，则在后台使用 --watch FOLDER --expect N：它会等待每个文件停止增长至少30秒。在 Apple Silicon 上的推荐模型：mlx-community/whisper-large-v3-turbo，词级时间戳，关闭 condition_on_previous_text。当语音不是英语时设置 --lang。
3. 草拟选择。
   • 模式 (a)，单脚本的多条拍摄：编写 WORK/script.txt，每行一个脚本行或话题点（如果你想要ID，可以用 id | name | text 格式）。运行 python3 scripts/segment.py takes --tx WORK/tx --script WORK/script.txt --out WORK/picks.json A=take-a B=take-b ...。它会找到每条拍摄中每个脚本行的每一次尝试（基于模糊词窗口匹配，因此重新开始会作为单独的候选出现），并预先勾选最流畅的一个。
   • 模式 (b)，单个长视频：python3 scripts/segment.py single --tx WORK/tx --out WORK/picks.json A=long-take 会在1.2秒或更长的停顿处以及句子结尾处进行切割，生成4-40秒的片段。
   • 然后亲自阅读.txt转录文件。修复入/出点，为重新开始和故障添加 cut: [[a,b]]，合并或拆分节拍，并为每个候选片段写出真实的 why（清晰、重新开始、错误单词、与屏幕录制匹配）。优先选择与匹配的屏幕录制一起拍摄的片段。自动评分仅用于打破平局。
4. 构建页面。 python3 scripts/build_review.py --work WORK --media SRC --out REVIEW --title "launch-01" --stringout。跨度在单词间隔超过0.6秒处拆分，并使用 silencedetect -35dB / 0.35s 收紧。在一个候选片段上添加 keep_pauses: true 以跳过该步骤。填充标志：--pre 0.15 --tail 0.25 --guard 0.1。仅当你有一个真实的短语映射时，才传递 --fix path/to/corrections.json。在浏览器中打开HTML。视频在点击时加载，因此页面打开很快。
5. 可选，macOS：注视分析。 python3 scripts/gaze.py --work WORK --review REVIEW，然后使用 --stringout --gaze-trim 重新运行步骤4。视线偏离的帧在片段串接中会有红色边框。之后用屏幕素材覆盖它们，并保留音频。
6. 人工审阅。 告知用户需要做什么：播放、使用/跳过、备注，然后“保存决策（JSON）”。它会下载 <slug>-decisions.json。“复制为文本”是备选方案。未触摸的卡片保留建议。
7. 应用备注。 读取决策JSON。将每条备注转换为 picks.json 中的编辑操作：cut、in/out、audio_only: true、grade: "eq=gamma=1.28:brightness=0.03"、optional: true。首先备份（cp picks.json picks.before-notes.json）。重新运行步骤4，并总结每条备注以及你做了什么。
8. 组装。 python3 scripts/assemble.py --work WORK --media SRC --decisions /path/to/<slug>-decisions.json --out SELECTS --render。你会得到一个帧精确的全分辨率 selects.mp4、一个 CMX3600 selects.edl（可通过导入用于 Premiere、Resolve、Final Cut）、selects.csv 和包含视线偏离范围和备注的 selects.json。
9. 验证。 听取每个编辑点（没有剪掉第一个或最后一个音节、没有视线偏离、没有噪音）。使用 ffprobe 检查渲染时长与 selects.json 中的总和是否一致，并制作一个联系表：ffmpeg -i selects.mp4 -vf "fps=1/6,scale=180:-1,tile=10x3" -frames:v 1 sheet.jpg。查看它，然后报告时长、更改了什么以及仍需要用户做什么。

picks.json 形状

{"episode":"launch-01","mode":"takes","takes":{"A":"take-a","B":"take-b"},
 "beats":[{"id":"01a","name":"Hook","script":"...","cands":[
   {"take":"B","in":0.82,"out":21.2,"pick":true,"why":"清晰，与屏幕匹配。","cut":[[51.4,53.82]],
    "note":"","audio_only":false,"grade":null,"optional":false,"signals":{"dur":20.1,"wpm":162,"fillers":0,"repeats":0}}]}]}

提示

• 使用转录JSON抽查任何单词的时间。在备注附近转储 word@start-end 是定位切割位置的最快方法。
• 如果 ffmpeg 没有 drawtext，则使用 drawbox 或 hue 标记帧，而不是文字。
• 大渲染：首先检查可用磁盘空间。4K素材加起来很快。