Skip to content
Back to search

video-editing

SkillWorks with Claude CodeGitHub

"Xiaohongshu/RED-tuned short-form video workflow for voice-over, talking-head, tutorials, interviews, podcasts, screen recordings, chroma key, B-roll, captions, and generated assets. Covers source ingest and conformance, hard and ping-pong loops, edit routing and runtime profiles, transcription and semantic review, multi-take and multicam sync/speaker switching, stabilization/dead-air cleanup, highlights/shorts, story/source/authorization gates, B-roll and generated-asset planning/review, storyboard animatics and shot handoffs, audio design/mix/loudness, captions, color/speed/J-L cuts, local upscale/interpolation review, reversible revisions, render/QA, multi-platform and size exports, publish packages, NLE handoff, and Remotion."

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/maxazure/video-editing-skill with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/maxazure/video-editing-skill'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/maxazure--video-editing-skill/badge.svg)](/listings/maxazure--video-editing-skill)

HTML

<a href="/listings/maxazure--video-editing-skill"><img src="/api/listings/maxazure--video-editing-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

必装

| 依赖 | 用途 | 装法 | |---|---|---| | `ffmpeg` | 一切视频/音频处理 | macOS: `brew install ffmpeg` · Linux: `apt install ffmpeg` | | `python3` ≥3.10 | 跑脚本 | 系统 / pyenv / brew | | Whisper | 语音识别 | 见下表 |

Whisper 引擎(按平台选一种)

| 平台 | 推荐引擎 | 安装命令 | |---|---|---| | **Apple Silicon (M1/M2/M3/M4)** | `mlx-whisper` | `pip install mlx-whisper` | | **NVIDIA GPU (CUDA)** | `faster-whisper` | `pip install faster-whisper` | | **Intel / AMD / CPU only** | `faster-whisper` (CPU) | `pip install faster-whisper` | | **后备** | `openai-whisper` | `pip install openai-whisper` |

中国用户走清华镜像:

pip install mlx-whisper -i https://pypi.tuna.tsinghua.edu.cn/simple

NVIDIA GPU 配置详见本文末尾的 [Linux GPU 配置](#linux-gpu-配置) 段。

可选

| 依赖 | 启用 | 缺时回落 | |---|---|---| | `Pillow` | 章节卡 PNG 渲染(auto_chapter_cards) | 不能跑章节卡 | | `librosa` | BGM 真实节拍检测 | 用 120 bpm 固定网格 | | `pyyaml` | profile YAML 读取加速 | 用内置 fallback parser | | `spacy + zh_core_web_sm` | 高级 B-roll 命名实体识别(V3.2+ 路线图) | 用关键词列表匹配 |

AI 图像生成(gpt-image-2)

| 运行环境 | 路径 | 凭证 | |---|---|---| | **Codex CLI**(推荐) | 用 Codex 内置 `imagegen` 工具,自动路由 gpt-image-2 | **无需** OpenAI API key | | **Claude Code / 其他** | 用 OpenAI Python SDK(`openai.images.generate`),或任何能调 gpt-image-1.5/2 的工具 | 需要 `OPENAI_API_KEY` |

生图优先使用 Codex 内置 `image_gen` 工具,即 OpenAI GPT Image 2(`gpt-image-2`)。

本 skill 只负责**产出提示词**(`imagegen_hint.py`)+ **提供模板库**(`prompts/imagegen_templates.yaml`)—— 不内置 OpenAI 客户端。在 Codex 里 agent 直接调内置 `imagegen`;其他环境用户自行接入。

完整规则详见 [docs/prompts/19-imagegen.md](docs/prompts/19-imagegen.md)。

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 2,893 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: video-editing
  3. description: "Xiaohongshu/RED-tuned short-form video workflow for voice-over, talking-head, tutorials, interviews, podcasts, screen recordings, chroma key, B-roll, captions, and generated assets. Covers source ingest and conformance, hard and ping-pong loops, edit routing and runtime profiles, transcription and semantic review, multi-take and multicam sync/speaker switching, stabilization/dead-air cleanup, highlights/shorts, story/source/authorization gates, B-roll and generated-asset planning/review, storyboard animatics and shot handoffs, audio design/mix/loudness, captions, color/speed/J-L cuts, local upscale/interpolation review, reversible revisions, render/QA, multi-platform and size exports, publish packages, NLE handoff, and Remotion."
  4. metadata: { "openclaw": { "emoji": "🎬", "os": ["darwin", "linux", "win32"], "requires": { "bins": ["ffmpeg", "python3"] }, "install": [{ "id": "ffmpeg-brew", "kind": "brew", "formula": "ffmpeg", "bins": ["ffmpeg"], "label": "Install FFmpeg (brew)" }] } }
  5. ---
  6. # Video Editing Skill — 视频剪辑技能(V3)
  7. 适配 **小红书 / 抖音 / 微信视频号** 三大主流平台。一条 **从素材导入 → 口播 → 重组故事 → 平台守门 → 自动丰富 → 渲染 → 三平台导出 → 标题文案** 的端到端流水线,按各平台的算法、比例、时长、审核规则调过参——不只是剪辑工具。
  8. ## V3 完整流水线(一图看懂)
  9. ```
  10. 口播音频 + 无声素材
  11. │
  12. ├─→ project_bootstrap.py 原始素材目录 → source inventory / project.md
  13. ├─→ edit_brief_plan.py 用户一句话需求 → 本地脚本 runbook / gates
  14. ├─→ runtime_preflight.py workflow profile → FFmpeg/Node 命令、编码器、filters / live gate
  15. ├─→ interlace_conform.py 交错/telecine 采样 → progressive 工作副本 / 全长 A/B gate
  16. ├─→ frame_rate_conform.py 手机/录屏 VFR → 全量 PTS 检测 / CFR 工作副本 / live gate
  17. ├─→ black_edge_trim.py 首尾黑场 + 静音覆盖 → CFR 工作副本 / 原片边界 proof + live gate
  18. ├─→ program_breaks.py 内部黑场与全音轨静音重叠 → 只读分段候选 / 复核时间点
  19. ├─→ border_crop.py 画面内持续黑边 → 逐时点 cropdetect 证据 / 保守裁切建议
  20. ├─→ motion_center.py 局部像素运动中心 → 只读构图复核时间点
  21. ├─→ loop_fill.py 短片 → 次数/固定时长 hard repeat / 真实接缝 proof + 完整审片 gate
  22. ├─→ ping_pong_loop.py 短动作 → 端帧去重正放/倒放 / 折返+循环双 proof / live gate
  23. ├─→ clip_assembly.py 多源片段 → 单次画布/CFR/SAR/音频归一 / 全接缝 proof + live gate
  24. ├─→ edit_style_profile.py 个人/品牌创意方向、节奏与渲染/文案默认值 → 可移植 profile
  25. ├─→ production_authorization.py
  26. │ 确切素材/动作/provider/权利依据 → 显式授权 + live gate
  27. ├─→ transcribe.py 转写 + 词级时间戳 + 口误标记
  28. ├─→ transcript_silence_qa.py 原始转写 vs 实测静音 → 幻觉疑点供回听
  29. ├─→ transcript_lookup.py 原话检索 / 时间窗口读取 → 少量带源时间码的结果
  30. ├─→ visual_transcript_index.py
  31. │ 现有关键帧 + 附近原话 → 带源哈希的 JSON/Markdown 复核索引
  32. ├─→ semantic_transcript_review.py
  33. │ 全篇前后文审校包 / 最小补丁验证 / 人工 choices gate
  34. ├─→ transcript_review.py 本地同步媒体 HTML 校稿 / CPS 提示 / review.txt 回写
  35. ├─→ takes_pack.py 多 take / Scribe transcript → phrase-level 阅读视图
  36. │ speaker / audio_event 编辑节拍
  37. ├─→ script_alignment.py 已审目标稿 → 多 take 原话候选 / choices / render_config
  38. │ 词/段边界 / 透明分数 / 歧义与缺素材 gate
  39. ├─→ audio_sync.py 外录音轨自动对齐 / 替换音轨计划
  40. ├─→ multicam_sync.py 多机位 → 参考时间线 / 时钟漂移证据 / 对齐预览 gate
  41. ├─→ multicam_switch.py 已同步机位 → 归一化说话者音频 / 自动导播草稿 / 完整审片 gate
  42. ├─→ scene_boundaries.py fixed/adaptive 视觉切点 + 逐切点 evidence
  43. ├─→ visual_dedupe.py 多来源场景 → 感知哈希重复组 / 保留建议 / review gate
  44. ├─→ video_understanding.py 抽样帧 + 可选 YOLO 检测 / tracks / scene_tags
  45. ├─→ video_stabilization.py 手持素材 → source-bound 后端计划 / 工作副本 / 全长 A/B gate
  46. ├─→ chroma_key.py 绿幕/蓝幕 → composite + matte 代表帧 / 人工 review / 完整渲染 gate
  47. ├─→ highlight_picker.py 长视频精华候选 / brief-query 定向找片段
  48. ├─→ audio_boundary_snap.py 已选片段 → 词/句末/静音边界校正
  49. ├─→ shorts_batch.py 精华候选 → per-short render_config / render + QA job sheet
  50. ├─→ rough_cut.py ASR 粗剪:去纯口头禅 / 相邻重复句
  51. ├─→ hook_variants.py 前三秒 hook 批量角度 / 推荐排序 / 风险检查
  52. ├─→ rewrite_script.py LLM 重组 5 段式(hook/pain/turn/value/cta)
  53. ├─→ content_guard.py 80+ 条平台雷区 lint
  54. ├─→ source_receipts.py 事实 claim → URL/截图 source deck + publish gate
  55. ├─→ beat_sync.py BGM beat-grid → 可审计剪辑骨架,或吸附已有切点
  56. ├─→ speed_ramp.py impact ranges → source-bound 局部变速计划 / 验证 / apply
  57. ├─→ freeze_punch.py impact frame → 定格替换窗口 / punch crop / unchanged audio timeline gate
  58. ├─→ auto_enrich.py B-roll / 章节卡 / 贴纸 / 强调点 / BGM 卡点 / imagegen 提示词
  59. │ └─→ Codex imagegen gpt-image-2 自动生图(抽象概念配图)
  60. ├─→ audio_cue_sheet.py BGM / SFX 音频设计清单 / 生成审批 gate
  61. ├─→ audio_cue_mix.py cue sheet + 最终旁白 → 本地/程序化 SFX 单轨 / 1× review gate
  62. ├─→ storyboard_plan.py 分镜 shot cards / 生成路由 / 连续性锚点
  63. ├─→ storyboard_animatic.py 每镜静帧 + 可选旁白 → timed MP4 / 1× review / live gate
  64. ├─→ photo_montage.py 有序照片 → 轻微缩放/叠化/可选配乐 MP4 + 源绑定收据
  65. ├─→ sequence_handoff.py 相邻镜头 receive/handoff / edit type / 轴线方向 / live gate
  66. ├─→ reference_story_formula.py
  67. │ 参考片时间码情绪机制 → 目标分镜 content anchors / live gate
  68. ├─→ provider_capability.py provider/surface/model 能力合同 / 核验日期 / live gate
  69. ├─→ video_prompt_pack.py Dreamina/Veo/LTX/Wan/Sora 提示词包 / 审批 + capability gate
  70. ├─→ reference_frame_preflight.py
  71. │ 首帧/style key 尺寸/方向/透明背景/画幅 gate
  72. ├─→ generation_task_log.py 异步生成任务台账 / submit_id / 下载 gate
  73. ├─→ generated_clip_review.py 生成片段 contact sheet / 常识物理 / 连续性 / 重生 gate
  74. ├─→ generation_chain_handoff.py
  75. │ 已审上一镜末帧 → 下一镜精确首帧 / 顺序生成 live gate
  76. ├─→ generated_motion_window.py
  77. │ 短生成片 0.25s freeze → active intervals / 人工裁切 / live gate
  78. ├─→ scoped_video_edit_review.py
  79. │ 原片 vs 局部 AI 编辑结果 / change-only + preserve invariants / A-B gate
  80. ├─→ generated_sequence_review.py
  81. │ 已审片段相邻尾帧/首帧/预览 / 跨镜头连续性 gate
  82. ├─→ final_audio_storyboard.py
  83. │ 锁定视觉 EDL + 原 storyboard → 最终声音分镜 / voice ledger / live gate
  84. ├─→ narration_loudness_qa.py 最终独立旁白 + 精确短语范围 → LUFS/spread/dBTP/LRA live gate
  85. ├─→ caption_speech_qa.py subtitle_pack + 独立人声轨 → 孤立/错位/越界字幕 live gate
  86. ├─→ subtitle_glyph_qa.py subtitle_pack + 显式字体 → 逐字符 cmap 覆盖 / 缺字 live gate
  87. ├─→ generation_lessons.py 已审片段 → provider/model scoped 提示词经验库
  88. ├─→ storyboard_assets.py 素材任务清单 / ready 预检 / paid 额度提醒
  89. │ 可选 media_library.py recommend 排名 B-roll 候选
  90. ├─→ stock_material_plan.py 远程 stock 搜索规划
  91. │ Pexels / Pixabay / Coverr 查询计划 + 素材登记提示
  92. ├─→ screen_focus.py 录屏点击/热点 → 自动聚焦计划
  93. ├─→ pip_overlay.py 录屏 + facecam → PIP 小窗计划
  94. ├─→ color_grade.py bounded 调色 plan / render_final 单次编码接入
  95. ├─→ lut_grade.py 外部 .cube LUT 校验 / SHA-256 绑定 / 单次编码接入
  96. ├─→ jump_cut.py 自适应去停顿 + 20% 删除预算 + 可审计 cut list + 30ms 防爆音 fade
  97. ├─→ multimodal_dead_air.py 静音 AND 静帧 → source-bound 保守删段 / 单次编码 / live gate
  98. ├─→ audio_transition.py 显式 J-cut/L-cut → source handle / hash / 1× 试听 gate
  99. ├─→ edit_revision.py 文本剪辑 artifact → source-bound 审批 / 成组 apply / undo / redo
  100. ├─→ edit_recipe.py 已审 render_config → typed-slot 可移植配方 / 新素材绑定回放
  101. ├─→ edit_preflight.py render_config/enrich_plan/cut list 渲染前预检 gate
  102. ├─→ platform_safe_area_qa.py 字幕/PIP/CTA/marker → 平台 UI 安全区 gate + SVG guide
  103. ├─→ subtitle_style_preview.py 真实源帧 → 最终 ASS 预设对比 JPEG / 选择 / live gate
  104. ├─→ render_final.py 单次编码渲染(可选口播降噪 + enrich_plan/focus_events/pip_overlays + Heavy 字幕 + 响度规范化 + BGM ducking)
  105. │ 可选 --versioned-output 防覆盖旧成片
  106. ├─→ subtitle_render_review.py 最终 MP4 + subtitle_pack → 高风险字幕 1× clips / 原尺寸帧 / 完整审片 live gate
  107. ├─→ render_qa.py 渲染后黑屏/静帧/静音/尺寸质检 + review packet
  108. ├─→ stream_coverage_qa.py 最终 MP4 → decoded 音视频首尾 PTS / 帧数 / 容器覆盖 live gate
  109. ├─→ encode_quality_qa.py 同时间线 master vs 重编码件 → SSIM/PSNR / 最差帧 / live gate
  110. ├─→ audio_channel_qa.py 成片声道活动/起始/平衡/相位/mono fold-down live gate
  111. ├─→ audio_dropout_qa.py 最终人声/混音短促近静音候选 / 1× WAV 听审 live gate
  112. ├─→ flash_safety_qa.py 成片亮度/饱和红 flash → 1s/5s 风险窗口 / live gate
  113. ├─→ temporal_artifact_qa.py 单帧/少数帧 return-to-state spike → 三帧证据 / 人工 audit / live gate
  114. ├─→ shot_color_qa.py 成片镜头亮度/对比/色度/饱和度/broadcast-range + 切点跳变 gate
  115. ├─→ retention_rhythm_qa.py 成片 hook 活动 / 长镜头 / 注意力空窗 / 节奏 gate
  116. ├─→ reference_edit_rhythm.py 参考片 vs 成片 hard-cut 结构 / contact sheets / live gate
  117. ├─→ speech_continuity_qa.py 成片二次 ASR → 切点复读 / 近重复 take / 句内口吃 gate
  118. ├─→ lip_sync_review.py 最终 master → 1×/0.25× 口型证据 / 人工 audit / live gate
  119. ├─→ review_proxy.py 低码率完整审片 MP4 / 可见时间码 / faststart
  120. ├─→ timeline_view.py 源素材删除段 / 成片输出切点 filmstrip + waveform 复盘图
  121. ├─→ edit_compare.py 原片连续时钟 vs 最终像素 / 删段置黑 / 映射验证
  122. ├─→ subtitle_pack.py SRT/VTT/ASS/JSON 字幕交付包(speed/offset 对齐)
  123. ├─→ soft_subtitles.py 已审 SRT → MP4 可开关字幕轨 / 无损复制音视频 / live 收据
  124. ├─→ chapter_mux.py 已审章节 JSON → MP4 可跳转章节 / 无损复制音视频 / live 收据
  125. ├─→ metadata_scrub.py 分享前清除 MP4 容器标签/章节/额外轨,保留音视频流
  126. ├─→ hls_vod.py 已审 SDR MP4 → 单码率 HLS 点播目录 / 分片+收据 live verify
  127. ├─→ subtitle_readability_qa.py
  128. │ 最终字幕 CPS / 时长 / 行长 / 重叠 / 媒体越界 gate
  129. ├─→ import_capcut_subtitles.py
  130. │ 剪映/CapCut 自动字幕 → transcript / gap cut list
  131. ├─→ srt_edit_plan.py SRT + keep/drop 编辑指令 → render_config / cut list
  132. ├─→ project_resume.py 续跑上下文包 / agent handoff / 可选 CLAUDE.md
  133. ├─→ review_dashboard.py 静态 HTML/JSON 人工复核面板 / gate review queue
  134. ├─→ export_edl.py render_config / cut list → EDL + manifest
  135. ├─→ export_fcpxml.py render_config / cut list → FCPXML + manifest
  136. ├─→ export_otio.py render_config / cut list → OTIO + manifest
  137. ├─→ framing_preview.py master → 各平台 cover/contain/blur 真实帧 / 选择 / live gate
  138. ├─→ multi_export.py 已审画幅策略 → 小红书 3:4 / 抖音 9:16 / 视频号 ≤60s
  139. ├─→ hdr_sdr.py PQ/HLG HDR → source-bound Rec.709 SDR / 完整解码 gate
  140. ├─→ video_enhancement.py Lanczos 放大 + 可选运动补帧 / 全长 A-B + 带声复核 gate
  141. ├─→ delivery_encode.py source-bound 两遍 H.264/AAC / 硬大小上限 / 完整解码 gate
  142. ├─→ gif_preview.py 视频短摘录 → 调色板 GIF / 源绑定收据 / 完整解码
  143. ├─→ logo_overlay.py 已审 MP4 + PNG Logo → 四角叠加 / 源绑定收据 / 完整解码
  144. ├─→ generate_caption.py 标题 + 200-500 字正文 + 3-6 tags + 发布时段
  145. ├─→ cover_variants.py 2-4 套封面 / feed-size 预览 / 最终选择 gate
  146. ├─→ approval_receipt.py 已复核交付件 → SHA-256 收据 / stale approval gate
  147. └─→ publish_package.py 平台视频/封面/字幕/章节/文案上传包 + gate 状态
  148. ```
  149. **每天做一条短视频的完整提示词模板**:[docs/prompts/15-xhs-daily-tech-video.md](docs/prompts/15-xhs-daily-tech-video.md)(推荐入口)。
  150. 生图优先使用 Codex 内置 `image_gen` 工具,即 OpenAI GPT Image 2(`gpt-image-2`)。
  151. ## V3 新增脚本一览(按调用顺序)
  152. | 脚本 | 职责 | 关键 CLI |
  153. |---|---|---|
  154. | `project_bootstrap.py` | 原始素材目录 → 项目结构 / source inventory / project.md | `--source raw_dir` `--project-dir work/day61` `--mode copy|hardlink` `--strict` |
  155. | `runtime_preflight.py` | workflow profile → 本机 FFmpeg/Node 命令、编码器、filters、环境漂移 live gate | `list-profiles` / `analyze --profile ... --output --strict` / `verify --report --strict` |
  156. | `edit_brief_plan.py` | 自然语言剪辑需求 → 本地脚本 runbook / 命令 / manifest gate | `--brief` `--brief-file` `--source-media` `--platform` `--markdown` `--strict` |
  157. | `interlace_conform.py` | 交错/telecine 多段检测 → bwdif/yadif progressive 工作副本、全长 A/B 人工确认与 live gate | `analyze` / `plan --mode frame|field --parity` / `apply` / `confirm` / `verify --strict` |
  158. | `frame_rate_conform.py` | 手机/录屏 VFR → decoded PTS cadence、精确 CFR 工作副本、帧数/音画起止与 live gate | `plan <source> --fps 30 --delivery` / `apply <plan>` / `verify <plan> --strict` |
  159. | `black_edge_trim.py` | 首尾 blackdetect + 静音覆盖 → source-bound CFR working copy、原片边界 proof 与人工 live gate | `plan --delivery --edge-proof` / `apply` / `confirm` / `verify --strict` |
  160. | `program_breaks.py` | 内部黑场与全部音轨静音的重叠 → 源绑定分段候选 JSON/Markdown;不自动切片 | `analyze <video> --output <report.json>` / `verify <report.json>` |
  161. | `loop_fill.py` | progressive CFR 短素材 → 按次数/目标时长重复、首个真实接缝 1× proof、完整审片与 live gate | `plan --times|--duration --delivery --seam-proof` / `apply` / `confirm` / `verify --strict` |
  162. | `ping_pong_loop.py` | progressive CFR 短动作 → 端帧去重的正放/倒放周期、折返/循环双 proof、缓存上限与 live gate | `plan --start --end --cycles|--duration --delivery --turnaround-proof --loop-seam-proof` / `apply` / `confirm` / `verify --strict` |
  163. | `clip_assembly.py` | 多源视频 → 单次画布/CFR/SAR/时间戳/音频归一、全接缝 1× proof 与 live gate | `plan <clips...> --delivery --boundary-proof` / `apply` / `confirm` / `verify --strict` |
  164. | `podcast_audiogram.py` | 纯音频摘录 + 静帧封面 + 相对摘录时间的 SRT → 带辅助波形的竖版 MP4 与源绑定收据 | `render <audio> <cover> <captions.srt> --start --duration --output --receipt` / `verify <receipt>` |
  165. | `gif_preview.py` | 视频短摘录 → 无声、调色板优化 GIF 和源绑定收据 | `render <video> --start --duration --output --receipt` / `verify <receipt>` |
  166. | `photo_montage.py` | 2–100 张照片 → 固定节奏、轻微缩放、叠化和可选配乐的 H.264 MP4;核验源照片、音乐与成片 | `render <photos...> --output --receipt [--music]` / `verify <receipt>` |
  167. | `logo_overlay.py` | 已审 MP4 + PNG Logo → 指定四角/宽度/透明度叠加,保留音轨并现场验证 | `render <video> <logo.png> --corner --width-fraction --opacity --margin --output --receipt` / `verify <receipt>` |
  168. | `frame_grid.py` | 秒级时间码定位最近解码帧;带可见格号的精确帧网格或单帧 PNG,附帧号/PTS 与源文件收据 | `locate <video> --at-seconds` / `grid <video> --start-frame --step --count --output --receipt` / `frame <video> --start-frame --output --receipt` / `verify <receipt>` |
  169. | `border_crop.py` | 对画面内上下/左右黑边逐时点采样;仅在全片及三段一致时建议裁切 | `analyze <video> --output <report.json>` / `verify <report.json>` |
  170. | `motion_center.py` | 无检测模型时逐时点标出局部运动中心;大范围变化不给焦点,供人工构图复核 | `analyze <video> --output <report.json>` / `verify <report.json>` |
  171. | `edit_style_profile.py` | 个人/品牌创意方向、剪辑节奏、渲染/文案默认值 → 无路径可移植 profile / digest 验证 / defaults-only 合并 | `template` / `create --spec` / `verify --profile --strict` / `apply --config --receipt` |
  172. | `production_authorization.py` | 外部上传、侵入性剪辑、付费生成、声音克隆、真人/IP 和发布 → source-bound 授权 gate | `prepare --scope --response-template` / `audit --request --response --strict` / `verify --report --strict` |
  173. | `transcript_review.py` | transcript → 文本或本地同步媒体 HTML 校稿 → reviewed transcript | `export` / `html --video --max-cps` / `apply --review --output` |
  174. | `transcript_lookup.py` | 只读原话检索或时间窗口读取,返回有界 JSON、源段 ID/时间码与 transcript SHA-256 | `<transcript.json> search <phrase> --limit` / `<transcript.json> span --start --end` |
  175. | `visual_transcript_index.py` | 现有关键帧与附近转写段配对,生成可核验的 JSON/Markdown 索引 | `build <keyframes.json> <transcript.json> --output --markdown` / `verify <index.json>` |
  176. | `tutorial_companion.py` | 已审教程章节 + 最终视频 + 时间码转写 → 每章截图与原话的 Markdown 伴读草稿、源绑定收据 | `build <video> <chapters.json> <transcript.json> --title --output [--at ch01=秒]` / `verify <bundle>/receipt.json` |
  177. | `semantic_transcript_review.py` | transcript → 前后文审校包 / 最小补丁审计 / 人工 choices / reviewed transcript | `prepare` / `audit --strict` / `apply --choices` |
  178. | `_internal_text_guard.py` | 拦截内部 token 进画面 | 内部模块,render_final 自动调 |
  179. | `content_guard.py` | 平台雷区 lint | `--script` `--title` `--caption` `--strict` |
  180. | `source_receipts.py` | 事实 claim → URL/截图 proof deck、Markdown/HTML 和发布 gate | `--claims source_claims.json` `--html` `--require-primary-source` `--strict` |
  181. | `takes_pack.py` | 多 take / 顶层 Scribe words → phrase-level Markdown/JSON,保留 speaker/audio events | `--transcript take1=...` `--transcripts-dir` `--json` `--break-gap` |
  182. | `script_alignment.py` | 已审目标稿 → 多 take 词/段边界候选、人工 choices、render_config 和 gate | `--target-script` `--transcript label=...` `--media label=...` `--choices` `--render-config` `--strict` |
  183. | `audio_sync.py` | scratch audio + 外录音轨 → offset / 替换音轨命令 / gate | `--reference-media` `--external-audio` `--replace-output` `--apply` `--strict` |
  184. | `multicam_sync.py` | 多机位 → offset/coverage/音轨选择/pairwise/可选时钟漂移/对齐预览 gate | `--reference-media` `--angle` `--manual-offset` `--measure-clock-drift` `--preview-output` `--apply-preview` `--strict` |
  185. | `multicam_switch.py` | ready 同步计划 + speaker-mapped 机位音轨 → source-bound 自动导播草稿、完整解码与人工 live gate | `plan --sync-plan --speaker --program-audio --delivery` / `apply` / `confirm` / `verify --strict` |
  186. | `rough_cut.py` | transcript 粗剪:去口头禅/重复句 | `--transcript` `--cut-list` / `--input` `--output` |
  187. | `scene_boundaries.py` | FFmpeg fixed/adaptive scene score → 场景边界 + cut evidence | `--method adaptive` `--adaptive-threshold` `--min-scene-score` `--min-scene-duration` |
  188. | `visual_dedupe.py` | 多来源场景三点感知哈希 → 重复组 / 保留建议 / review gate | `--manifest` / `<videos...>` `--hamming-threshold` `--include-same-source` `--strict` |
  189. | `video_understanding.py` | 抽样帧 + 可选 YOLO 物体检测 + 轻量 tracklets | `--detector yolo` `--scene-boundaries` `--external-detections` `--strict` |
  190. | `video_stabilization.py` | 源视频 → exact FFmpeg backend / source hash / 稳定工作副本 / 全长 A/B 复核 gate | `doctor` / `plan --decision` / `apply --comparison` / `confirm` / `verify --strict` |
  191. | `chroma_key.py` | 绿幕/蓝幕前景 + 图片/视频背景 → composite/matte 预览、四项人工 review、source-bound 完整渲染 gate | `prepare --foreground --background --output-video` / `review` / `apply` / `verify --strict` |
  192. | `highlight_picker.py` | 长视频精华候选 + brief/query 定向找片段 | `--transcript` `--brief`/`--query` `--scene-boundaries` `--render-config` |
  193. | `audio_boundary_snap.py` | selected highlights → 词级、句末和静音边界校正 + blocker | `--candidates` `--transcript` `--media` `--markdown` `--strict` |
  194. | `shorts_batch.py` | highlight_candidates → 多条短视频 render_config / render + QA job sheet | `--highlights` `--video` `--render-config-dir` `--output-dir` `--strict` |
  195. | `hook_variants.py` | transcript/clean_script → 8 个前三秒 hook 角度、风险检查和推荐排序 | `--transcript` `--topic` `--platform` `--output` `--markdown` `--strict` |
  196. | `rewrite_script.py` | LLM 5 段式重组 + 验证 | `--transcript` `--structure` `--hook-template` `--emit-prompt` / `--llm-output` |
  197. | `auto_broll.py` | B-roll 调度 | `--transcript` `--assets` `--max-single-shot` |
  198. | `media_library.py` | 本地素材库索引 + B-roll 候选推荐 + 素材来源登记 | `init` `scan` `search` `recommend --category broll --json` `import` `annotate` |
  199. | `stock_material_plan.py` | 主题/脚本 → Pexels/Pixabay/Coverr stock 查询计划 | `--subject` `--script` `--provider` `--media-library` `--output` `--markdown` |
  200. | `auto_chapter_cards.py` | 章节卡 PNG | `--script` `--audio` `--style` `--output-dir` |
  201. | `auto_stickers.py` | 情绪→贴纸 | `--transcript` `--min-interval` |
  202. | `auto_emphasis.py` | 问句/数字/转折/结论 → badge + subtle push-in cues | `--transcript` `--output` `--markdown` |
  203. | `beat_sync.py` | BGM → beat edit slots / Markdown review,或吸附已有切点 | `--bgm --generate-plan --beats-per-cut 4 --output ... --markdown ...` / `--cuts --window` |
  204. | `speed_ramp.py` | impact ranges → snap/ease/s-curve/hold 计划、digest 验证和本地事务式 apply | `plan <video> --ramp --hold --interpolate-fps` / `verify --strict` / `apply --output --receipt` |
  205. | `freeze_punch.py` | impact frame → source-bound 定格强调、轻微 anchor crop、时长/音频不变和成片 live gate | `plan <video> --freeze --delivery` / `apply <plan>` / `verify --strict` |
  206. | `auto_enrich.py` | 编排 B-roll / 贴纸 / 强调点 / 章节卡 / imagegen cues | `--transcript` `--clean-script` `--bgm` `--output` |
  207. | `imagegen_hint.py` | 检测抽象概念 → 产 gpt-image-2 提示词 | `--transcript` `--clean-script` `--codex-md` |
  208. | `audio_cue_sheet.py` | transcript → BGM/SFX cue、生成审批和音频门禁 | `--transcript` `--asset-root` `--require-local-music` `--require-local-sfx` `--strict` |
  209. | `audio_cue_mix.py` | audio cue sheet + 最终旁白 → 本地/程序化 SFX、48 kHz stereo 单轨、完整试听 live gate | `plan --cue-sheet --voice --delivery [--synthesize-missing]` / `apply` / `confirm` / `verify --strict` |
  210. | `final_audio_storyboard.py` | locked visual EDL + storyboard → 最终时间线声音分镜、voice ledger、omitted-story 决定和 live gate | `prepare --edl --storyboard` `audit --request --response` `verify --report --strict` |
  211. | `storyboard_plan.py` | transcript/clean_script → 分镜 shot cards + 生成路由 | `--transcript` `--clean-script` `--output` `--markdown` |
  212. | `reference_story_formula.py` | 参考视频 + timecoded transcript + 目标 storyboard → 情绪/叙事机制、逐镜 content anchor、复制排除策略与 source-bound live gate | `prepare --reference-video --reference-transcript --target-storyboard --response-template` / `audit --request --response` / `verify --report --strict` |
  213. | `storyboard_animatic.py` | storyboard + 每镜静帧 + 可选旁白 → source-bound timed MP4、完整 1× 复核与 live gate | `plan --panel SHOT=PATH --delivery` / `apply` / `confirm` / `verify --strict` |
  214. | `sequence_handoff.py` | storyboard → 相邻镜头接力、剪辑边界、180° 轴/方向、音频桥、edit handles 与 source-bound live gate | `prepare --storyboard --response-template` `audit --request --response` `verify --report --strict` |
  215. | `provider_capability.py` | exact provider/surface/model → 带日期的 mode/画幅/时长/分辨率/参考上限能力合同 live gate | `verify --bundle --max-age-days --output --markdown --strict` |
  216. | `video_prompt_pack.py` | storyboard_plan → 多 provider 视频生成提示词包 + 已审故事公式/边界/真实末帧接力 + 角色/品牌/style lock + paid approval/capability gate | `--storyboard-plan` `--project-dir` `--reference-story-formula` `--sequence-handoff` `--generation-chain-handoff` `--capability-profile` `--approved` `--strict` |
  217. | `reference_frame_preflight.py` | video_prompt_pack → 首帧/style key 存在性、解码、尺寸、方向、画幅、透明背景 gate | `--prompt-pack` `--require-style-reference` `--reference shot_id=...` `--strict` |
  218. | `generation_reference_preflight.py` | prompt pack + 图片/视频/音频 reference manifest + provider profile → 类型/数量/时长/模式/@标签角色 source-bound gate | `template --prompt-pack` / `analyze --references --capability-profile --strict` / `verify --report --strict` |
  219. | `generation_task_log.py` | 异步生成任务台账:submit_id/task id、轮询、下载、本地落盘 gate | `add` `update` `import-provider-decision` `report --strict` |
  220. | `generated_clip_review.py` | 生成视频片段 source-bound 视觉复核:contact sheet、评分、裁切范围、重生建议 | `prepare --clip/--asset-manifest` `audit --request --response` `verify --report --strict` |
  221. | `generation_chain_handoff.py` | 已审生成片 + 已审相邻边界 → 精确末帧 PNG、人工确认、下一镜 exact first-frame live gate | `prepare --clip-review --sequence-handoff --boundary` / `confirm --decision use_exact_start_frame` / `verify --strict` |
  222. | `generated_motion_window.py` | 短生成片全帧 freeze → active intervals、人工 trim/keep/reject、帧准确 working copy 与 live gate | `analyze <clip>` `confirm --decision` `apply --output` `verify --strict` |
  223. | `scoped_video_edit_review.py` | 原片 + 局部 AI 编辑结果 → 同时间点 A/B 证据、唯一变更目标、保护项逐项复核和 live gate | `prepare --source --edited --change --preserve` `audit --request --response` `verify --report --strict` |
  224. | `generated_sequence_review.py` | 已审生成片段跨镜头连续性复核:真实尾帧/首帧、并排图、无声边界预览和 live gate | `prepare --clip-review [--storyboard-plan]` `audit --request --response` `verify --report --strict` |
  225. | `generation_lessons.py` | 从 canonical generated-clip review 提取经明确批准的 provider/model/category 经验,并供下一次 prompt pack 选择 | `add --review --clip-id --lesson --approved-by [--supersedes]` `verify --strict` `select --provider [--model]` |
  226. | `storyboard_assets.py` | storyboard_plan → 素材清单 + ready/paid 预检 | `--storyboard-plan` `--asset-root` `--output` `--strict` |
  227. | `screen_focus.py` | 录屏点击/热点 → 聚焦 zoom enrich plan | `--events` `--event` `--screen-width` `--output` |
  228. | `pip_overlay.py` | 录屏 + facecam → PIP 摄像头小窗 enrich plan | `--camera` `--segment` `--sync-offset` `--output` |
  229. | `color_grade.py` | bounded 调色 plan + FFmpeg filter + 可选现有 master 复版 | `--preset` `--output` `--markdown` `--render-output` `--strict` |
  230. | `lut_grade.py` | 本地 `.cube` LUT → FFmpeg 实测可加载、文件 SHA-256 绑定的调色计划;渲染时现场复核 | `plan <look.cube> --output <plan.json>` / `verify <plan.json>`;`render_final.py --color-grade <plan.json>` |
  231. | `jump_cut.py` | 自适应静音检测 → 去停顿计划 / 删除预算 gate / 成片 + 切点音频 fade | `<input.mp4>` `--dry-run` `--cut-list cuts.json` `--strict` / `--output jumpcut.mp4` `--max-removal-ratio 0.20` `--allow-over-budget` |
  232. | `multimodal_dead_air.py` | 静音 + 静帧交集 → source-bound 死区计划 / live verify / 单次编码工作副本 | `plan --delivery --output --markdown --strict` / `verify --strict` / `apply --markdown` |
  233. | `audio_transition.py` | render_config → 显式 J-cut/L-cut source handle / hash / 单次编码 apply / receipt | `plan --transition AFTER_CLIP,TYPE,DURATION` / `apply --output` / `verify --receipt --strict` |
  234. | `edit_revision.py` | render_config/enrich_plan 等文本 artifact → source-bound proposal / 独立审批 / 成组 apply / undo / redo | `prepare --artifact --depends-on` / `audit --strict` / `apply --approval` / `status|undo|redo` |
  235. | `edit_recipe.py` | 已审 render_config → typed-slot 无路径配方 / digest 验证 / 绑定新素材回放 | `export --config --name` / `verify --recipe` / `replay --bind SLOT=PATH --receipt --strict` |
  236. | `edit_preflight.py` | render_config/enrich_plan/cut list 渲染前预检 gate | `--config render_config.json` `--enrich-plan enrich_plan.json` `--output edit_preflight.json` `--strict` |
  237. | `platform_safe_area_qa.py` | 字幕、badge、PIP、CTA、章节卡、marker → 平台 UI 遮挡 gate + SVG guide | `--config` `--enrich-plan` `--elements` `--platform xhs|douyin|wxch` `--guide` `--strict` |
  238. | `subtitle_style_preview.py` | 真实源帧 → `render_final.py` 最终 ASS 样式对比 JPEG、人工选择与 source/font/style live gate | `create --video --platform --preview-dir --require-selection` / `select --report --style` / `verify --strict` |
  239. | `render_final.py` | 单次编码渲染 + 可选个人风格默认值 / 口播降噪 / J-cut/L-cut / enrich_plan / 旁白驱动 BGM ducking | `--config render_config.json` `--style-profile work/edit_style_profile.json` `--audio-transition-plan audio_transition_plan.json` `--speech-denoise light` `--enrich-plan enrich_plan.json` `--bgm-ducking` `--output final.mp4` |
  240. | `subtitle_render_review.py` | 最终 MP4 + subtitle_pack → 高风险字幕上下文 clip / 中点原尺寸帧、完整 1× 人工审片与 source-bound live gate | `prepare --video --subtitle-pack --proof-dir` / `audit --request --response --strict` / `verify --report --strict` |
  241. | `render_qa.py` | 渲染后 QA:尺寸/音频/黑屏/静帧/静音 + review packet | `<video.mp4>` `--platform douyin` `--json qa.json` `--review-dir verify/qa` |
  242. | `stream_coverage_qa.py` | final MP4 → 全量解码、首尾 PTS、A/V 与容器覆盖、视频帧数 source-bound live gate | `analyze <video> --output --markdown [--expected-duration --expected-video-frames] --strict` / `verify --report --strict` |
  243. | `encode_quality_qa.py` | 同时间线参考 master vs 重编码件 → 全长 SSIM/PSNR、P05、最差帧时间码与双输入 live gate | `analyze <reference> <candidate> --output --markdown --strict` / `verify --report --strict` |
  244. | `video_enhancement.py` | 现有视频 → 本地 Lanczos 放大、可选 `minterpolate` 补帧、全长 A/B 与带声人工复核 live gate | `plan <video> --target-short-edge|--scale [--fps] --enhanced --comparison` / `apply` / `confirm` / `verify --strict` |
  245. | `flash_safety_qa.py` | final/platform video → 大面积亮度/饱和红 flash、滚动 1s/5s 风险窗口与 source-bound live gate | `analyze <video> --output --markdown --strict` / `verify --report --strict` |
  246. | `temporal_artifact_qa.py` | final/generated video → 单帧/少数帧局部突变筛查、before/suspect/after 证据与人工决定 live gate | `analyze <video> --evidence-dir --response-template --strict` / `audit --report --response` / `verify --strict` |
  247. | `shot_color_qa.py` | rendered master → 镜头亮度/对比/色度/饱和度/broadcast-range 与切点跳变 gate | `<video.mp4>` `--scene-boundaries` `--output shot_color_qa.json` `--markdown` `--strict` |
  248. | `retention_rhythm_qa.py` | 成片 hook 活动、长镜头、注意力空窗、等距/快切和字幕节奏风险 | `<video.mp4>` `--timed-text subtitles.json` `--output retention_rhythm_qa.json` `--strict` |
  249. | `reference_edit_rhythm.py` | 参考片 vs 成片 hard-cut 密度、镜头时长、结尾 hold、归一化切点与 contact-sheet source-bound 对照 | `analyze --reference --candidate --evidence-dir [--require-match]` / `verify --report --strict` |
  250. | `speech_continuity_qa.py` | 成片二次 transcript → 复读 / 近重复 take / 句内口吃 gate | `<final_transcript.json>` `--output speech_continuity_qa.json` `--markdown` `--strict` |
  251. | `lip_sync_review.py` | 最终 master → 完整短语 1× 带声 / 0.25× 静音 proof、口型人工 audit 与 source-bound live gate | `prepare --video --segment --anchor --proof-dir` / `audit --request --response --strict` / `verify --report --strict` |
  252. | `review_proxy.py` | master/platform MP4 → 低码率 timecoded 审片视频 + JSON/Markdown | `<video.mp4>` `--output verify/review_proxy.mp4` `--dry-run` `--no-timecode` |
  253. | `audio_master_report.py` | 成片响度报告:LUFS / true peak / LRA / 长静音 gate | `<video.mp4>` `--output audio_master_report.json` `--markdown audio_master_report.md` `--strict` |
  254. | `audio_channel_qa.py` | 最终 master → 声道活动、起始错位、L/R 平衡、相位相关与 mono fold-down source-bound live gate | `analyze <media> --output --markdown --strict` / `verify --report --strict` |
  255. | `audio_dropout_qa.py` | 最终人声/混音 → 20 ms 短近静音候选、1× WAV 证据、人工听审与 source-bound live gate | `analyze <media> --evidence-dir --response-template --strict` / `audit --response` / `verify --strict` |
  256. | `narration_loudness_qa.py` | 最终独立旁白逐短语一致性:target LUFS / segment spread / true peak / LRA source-bound live gate | `analyze <media> --segments <json> --output --markdown --strict` / `verify --report --strict` |
  257. | `caption_speech_qa.py` | subtitle_pack cue → 独立人声活动覆盖、头尾静音、内部停顿与时间线越界 source-bound live gate | `analyze <isolated-speech> --subtitle-pack <json> --output --markdown --strict` / `verify --report --strict` |
  258. | `subtitle_glyph_qa.py` | subtitle_pack + 项目内显式字体 → 逐字符 Unicode cmap 覆盖、缺字/fallback 清单与 source-bound live gate | `analyze --subtitle-pack --font [--fallback-font] --output --strict` / `verify --report --strict` |
  259. | `timeline_view.py` | 源素材删除段 / 成片输出切点可视化复盘图 | `<video.mp4>` `--at 42.5` `--output view.png` / `--rendered-cut-list cuts.json` `--output-dir verify/` |
  260. | `edit_compare.py` | 原片连续时钟 vs 最终像素双栏视频;删段置黑并验证映射 | `<source.mp4> <final.mp4>` `--cut-list` `--output-speed` `--output-offset` `--output` |
  261. | `subtitle_pack.py` | transcript/render_config → SRT/VTT/ASS/JSON 字幕包 | `--transcript work/transcript.json --output-dir output/subtitles` / `--config render_config.json --speed 1.25 --offset 2.0` |
  262. | `soft_subtitles.py` | 已审、与成片时间线对齐的 SRT → 可开关 `mov_text` MP4 字幕轨;复制原视频/音频流并验证内容与时间码 | `mux final.mp4 final.srt --language zho --output final-soft.mp4 --receipt soft-subtitles.json` / `verify soft-subtitles.json` |
  263. | `chapter_markers.py` | 已审章节 → JSON、FFmetadata、平台时间戳及浏览器 `kind="chapters"` WebVTT | `--chapters draft.json --duration 720 --output-dir output/chapters --strict` |
  264. | `chapter_mux.py` | `chapter_markers.py` 的已审 JSON → MP4 内嵌章节;复制音视频流,核对章节标题/时间与流哈希 | `mux final.mp4 chapters.json --output final-chapters.mp4 --receipt chapter-mux.json` / `verify chapter-mux.json` |
  265. | `metadata_scrub.py` | 分享版 MP4 清除容器和流标签、章节、额外轨;复制并核对音视频流 | `scrub final.mp4 --output share.mp4 --receipt metadata-scrub.json` / `verify metadata-scrub.json` |
  266. | `hls_vod.py` | 已审 H.264/AAC SDR MP4 → 单码率 VOD `index.m3u8` + TS 分片;核对独立关键帧、帧数、完整解码及文件哈希 | `package final.mp4 --output-dir output/hls --receipt verify/hls_vod.json` / `verify verify/hls_vod.json` |
  267. | `subtitle_readability_qa.py` | output-aligned 字幕 → CPS、时长、行长、重叠和媒体越界 gate | `<subtitle_pack.json>` `--media final.mp4` `--output subtitle_readability_qa.json` `--strict` |
  268. | `import_capcut_subtitles.py` | 剪映/CapCut 自动字幕或 SRT → transcript + gap cut list | `--draft <draft_dir>` / `--srt captions.srt` `--transcript work/capcut_transcript.json` `--cut-list work/capcut_gap_cut.json` |
  269. | `srt_edit_plan.py` | SRT + 人工/agent keep/drop 指令 → edit plan / render_config / cut list | `--srt captions.srt --guide edit_guide.md --source-media origin/talking.mp4 --render-config work/render_config.json --strict` |
  270. | `project_resume.py` | 本地 artifacts → 续跑上下文包 / agent handoff | `--project-dir work/day58 --markdown work/day58/project_resume.md --agent-note work/day58/CLAUDE.md` |
  271. | `review_dashboard.py` | 本地 artifacts → 静态 HTML/JSON review queue + gate snapshot | `--project-dir work/day58 --html work/day58/review_dashboard.html --strict` |
  272. | `export_edl.py` | NLE handoff:导出 EDL + manifest | `--config render_config.json --output edit.edl` / `--cut-list rough_cut.json --output rough.edl` |
  273. | `export_fcpxml.py` | NLE handoff:导出 FCPXML + manifest | `--config render_config.json --output edit.fcpxml` / `--cut-list rough_cut.json --output rough.fcpxml` |
  274. | `export_otio.py` | NLE handoff:导出 OpenTimelineIO `.otio` + manifest | `--config render_config.json --output edit.otio` / `--cut-list rough_cut.json --output rough.otio` |
  275. | `framing_preview.py` | master → 各平台 cover/contain/blur 真实帧预览、人工选择和 source/filter/preview live gate | `create --video --platforms --require-selection` / `select --platform --strategy` / `verify --strict` |
  276. | `multi_export.py` | 三平台导出,可消费已审画幅策略 | `<input.mp4>` `--platforms xhs douyin wxch` `--framing-preview work/framing_preview.json` |
  277. | `hdr_sdr.py` | PQ/HLG master → source-bound Hable tone-map / BT.709 limited tags / 完整解码 gate | `plan --delivery` / `apply` / `verify --strict` |
  278. | `delivery_encode.py` | master → 目标大小 H.264/AAC MP4 / source hash / 两遍码率 / 完整解码 gate | `plan --delivery --max-size-mib` / `apply` / `verify --strict` |
  279. | `generate_caption.py` | 标题/正文/tag | `--script` `--profile` `--output` |
  280. | `cover_variants.py` | 多套封面 A/B 方案、个人风格默认值、feed-size 预览、标题协同和最终选择 | `<video>` `--title` `--style-profile` `--caption` `--platform` `--render` `--select cover-c` `--strict` |
  281. | `approval_receipt.py` | 已复核视频/封面/文案/字幕/QA → SHA-256 收据和过期审批门禁 | `create --artifact ... --approved-by` / `verify --strict` |
  282. | `publish_package.py` | 发布上传包:平台视频、封面、字幕、章节、文案和 gate 状态 | `--project-dir` `--platforms` `--video xhs=...` `--strict` |
  283. | `profiles/__init__.py` | 受众档位加载 | `load_profile("tech_pro")` |
  284. ## V3 新增 render_final.py 标志位
  285. | 标志 | 默认 | 说明 |
  286. |---|---|---|
  287. | `--profile tech_pro` | 关 | 加载 [scripts/profiles/tech_pro.yaml](scripts/profiles/tech_pro.yaml) 的节奏/字幕/BGM 默认值 |
  288. | `--style-profile work/edit_style_profile.json` | 关 | 验证个人/品牌剪辑风格档案,仅填充 config 中缺失或 `null` 的受控字段 |
  289. | `--primary-speed 1.25` | 1.0 | 主输出速度。`--speed` 仍可加额外变种 |
  290. | `--no-loudnorm` | 不传 = 开启响度规范化 | 关闭 `dynaudnorm + acompressor + loudnorm` |
  291. | `--speech-denoise light|medium|strong` | off | 80 Hz 高通 + 6/9/12 dB `afftdn`,在变速/响度/BGM ducking 前清理稳态底噪;`--no-speech-denoise` 覆盖 config |
  292. | `--no-content-guard` | 不传 = 开启 lint | 关闭平台规则检查(不推荐) |
  293. | `--subtitle-style karaoke` | normal | 逐词卡拉 OK 字幕 |
  294. | `--enrich-plan work/enrich_plan.json` | 关 | 可重复传入;自动接入 B-roll / 章节卡 / 贴纸 / 生成图 / focus_events / pip_overlays |
  295. | `--color-grade work/color_grade.json` | 关 | 接入 `color_grade.py` 输出或 preset,放在字幕/HUD 前 |
  296. | `--bgm-ducking` | 关 | 用最终旁白轨触发 FFmpeg sidechain,动态压低 BGM;`--no-bgm-ducking` 可覆盖 config |
  297. | `--versioned-output` | 关 | 输出到下一个 `<name>_V<N>.mp4`,避免覆盖上一版成片 |
  298. ## V3 Day58 production 教训(已编码进默认行为)
  299. | 教训 | V3 怎么解决 |
  300. |---|---|
  301. | 顶部漏 `1.25x` 这种内部 token | `_internal_text_guard` 自动拒绝,规则在 [scripts/_internal_text_guard.py](scripts/_internal_text_guard.py) |
  302. | 字幕 Hiragino W3 太细 | `find_chinese_font()` 默认排序:Source Han Sans Heavy > Smiley Sans > STHeiti Medium > PingFang Semibold |
  303. | 加速后中段听不清 | render_final 默认 `dynaudnorm=f=250:g=15 + acompressor=threshold=-18dB:ratio=3 + loudnorm=I=-16:TP=-1.5:LRA=11` |
  304. | 1.25× 想做主输出但 `--speed` 还留 1.0× | 新增 `--primary-speed` 一等公民 |
  305. | 字幕里 Whisper 错词(ChatGPTT 等) | `rewrite_script.py` 走清稿优先,原 Whisper 词只供时间戳 |
  306. | 平台违规词被发现才知道(限流) | `content_guard.py` 渲染前自动 lint |
  307. ---
  308. # 旧版(V2)参考资料
  309. 下面是 V2 时代的工作流文档。仍然有效,但日常使用推荐先看 docs/prompts/15。
  310. ## Prerequisites(前置要求)
  311. 在执行任何操作之前,先运行环境检测:
  312. ```bash
  313. python3 scripts/utils.py
  314. ```
  315. 这会自动检测平台(macOS/Linux/WSL/Windows)、GPU 类型、可用编码器、Whisper 引擎,并给出诊断报告。
  316. ## Prerequisites(前置要求)
  317. 在执行任何操作之前,先运行环境检测:
  318. ```bash
  319. python3 scripts/utils.py
  320. ```
  321. 这会自动检测平台(macOS/Linux/WSL/Windows)、GPU 类型、可用编码器、Whisper 引擎,并给出诊断报告。
  322. 如果缺少依赖,提示用户安装:
  323. - **ffmpeg**: `brew install ffmpeg`(macOS)或 `apt install ffmpeg`(Linux/WSL)或下载 Windows 版本
  324. - **whisper**:
  325. - **Apple Silicon (M1/M2/M3/M4)**: `pip install mlx-whisper`(推荐,Metal 加速最快)
  326. - **NVIDIA / CPU**: `pip install faster-whisper`(推荐,速度快 4 倍)或 `pip install openai-whisper`
  327. - **中国用户**加速安装(Apple Silicon):`pip install mlx-whisper -i https://pypi.tuna.tsinghua.edu.cn/simple`
  328. 其他平台:`pip install faster-whisper -i https://pypi.tuna.tsinghua.edu.cn/simple`
  329. 如果项目根目录有 `.venv` 虚拟环境,运行 Python 脚本前先激活:
  330. ```bash
  331. source .venv/bin/activate # macOS/Linux/WSL
  332. # Windows: .venv\Scripts\activate
  333. ```
  334. ### 平台说明
  335. - **macOS (Apple Silicon)**: 自动使用 VideoToolbox 硬件编码加速;Whisper 引擎自动选 `mlx-whisper`(已安装),推荐 large-v3-turbo 模型(走 `mlx-community/whisper-large-v3-turbo`)
  336. - **字幕字体(短视频)**: 默认优先选 Heavy / Medium 字重的中文字体:用户库的 `Source Han Sans SC Heavy` / `Smiley Sans` > 系统 `STHeiti Medium` > `PingFang SC Semibold`。如果都没有,会自动从 [adobe-fonts/source-han-sans](https://github.com/adobe-fonts/source-han-sans) 下载 Heavy 字重缓存到 `~/.cache/video-editing/fonts/`。绝不再默认使用 Hiragino W3 这类细字
  337. - **macOS (Intel)**: 使用 VideoToolbox 编码,Whisper 使用 CPU 模式
  338. - **Linux**: 自动检测 NVIDIA GPU (NVENC)、Intel QSV、AMD AMF
  339. - **WSL**: 支持,自动检测 Windows 字体路径 (`/mnt/c/Windows/Fonts/`)
  340. - **Windows**: 建议使用 WSL2 环境运行;支持 QSV/AMF 硬件编码
  341. - **无独显 (集成显卡)**: Intel iGPU 使用 QSV 编码,AMD iGPU 使用 AMF 编码;Whisper 建议 medium 模型(而非 large)
  342. - **中国用户**: 自动检测中国区域,使用清华 pip 镜像和 HuggingFace 镜像下载模型,也可通过 `--mirror` 参数强制启用
  343. ### Linux GPU 配置指南(NVIDIA / Intel Arc)
  344. 在 Linux 上使用 GPU 加速 Whisper 语音识别时,不同显卡需要不同的配置方案。运行 `python3 scripts/utils.py` 会自动检测显卡型号并给出建议,但如果遇到问题,请参考以下方案。
  345. #### 方案 A:NVIDIA 40 系列显卡(RTX 4060 / 4070 / 4080 / 4090)
  346. 40 系列(Ada Lovelace 架构,Compute Capability 8.9)对 faster-whisper 支持最成熟,开箱即用。
  347. **安装步骤:**
  348. ```bash
  349. # 1. 安装 NVIDIA 驱动(535+)和 CUDA Toolkit 12.4+
  350. sudo apt install nvidia-driver-535 nvidia-cuda-toolkit
  351. # 或从 NVIDIA 官网安装最新驱动:https://www.nvidia.com/drivers
  352. # 2. 验证 CUDA
  353. nvidia-smi # 应显示驱动版本和 CUDA 版本
  354. # 3. 安装 faster-whisper(自动安装匹配的 CTranslate2)
  355. pip install faster-whisper>=1.1.0
  356. ```
  357. **配置说明:**
  358. - CUDA Toolkit: 12.4+(推荐 12.6)
  359. - CTranslate2: >= 4.5.0(自动随 faster-whisper 安装)
  360. - 计算精度: `float16`(默认), `int8_float16`, `int8` 均可使用
  361. - Whisper 模型: 推荐 `large-v3`(VRAM >= 6GB)
  362. - 无需特殊配置,`python3 scripts/transcribe.py` 会自动检测并使用 CUDA
  363. #### 方案 B:NVIDIA 50 系列显卡(RTX 5060 / 5060 Ti / 5070 / 5080 / 5090)
  364. 50 系列(Blackwell 架构,Compute Capability 12.0,sm_120)需要额外注意 CUDA 版本和计算精度设置。
  365. **已知问题:**
  366. CTranslate2 在 Blackwell 架构上使用 INT8 精度时会报错 `cuBLAS failed with status CUBLAS_STATUS_NOT_SUPPORTED`,
  367. 这是因为 Blackwell 的 INT8 Tensor Core 需要矩阵维度为 16 的倍数对齐。CTranslate2 >= 4.7.1 已修复此问题,
  368. 但为保险起见,本工具在检测到 50 系列显卡时会自动使用 `float16` 精度。
  369. **安装步骤:**
  370. ```bash
  371. # 1. 安装 NVIDIA 驱动(565+,必须支持 Blackwell)
  372. # 从 NVIDIA 官网下载最新驱动:https://www.nvidia.com/drivers
  373. # 或使用包管理器安装 565 以上版本
  374. sudo apt install nvidia-driver-565
  375. # 2. 安装 CUDA Toolkit 12.8+(Blackwell 最低要求)
  376. # 推荐从 NVIDIA 官网安装:https://developer.nvidia.com/cuda-downloads
  377. # 选择 Linux > x86_64 > Ubuntu > deb (network)
  378. # 3. 验证 CUDA
  379. nvidia-smi # 应显示 CUDA 12.8+
  380. # 4. 安装 faster-whisper 和最新 CTranslate2
  381. pip install faster-whisper>=1.1.0
  382. pip install --upgrade ctranslate2>=4.7.1 # 确保包含 Blackwell 修复
  383. # 5. 如果仍然报错,强制使用 float16 精度(本工具已自动处理)
  384. # 手动测试:
  385. python3 -c "
  386. from faster_whisper import WhisperModel
  387. model = WhisperModel('tiny', device='cuda', compute_type='float16')
  388. print('CUDA float16 OK')
  389. "
  390. ```
  391. **配置说明:**
  392. - CUDA Toolkit: >= 12.8(推荐 13.0+,最新为 13.2)
  393. - NVIDIA 驱动: >= 565
  394. - CTranslate2: >= 4.7.1(包含 INT8 padding 修复)
  395. - 计算精度: 推荐 `float16`(最稳定);`int8_float16` 在 CTranslate2 >= 4.7.1 上可能可用
  396. - 如果 `int8` 仍然报错,工具会自动降级到 `float16`
  397. - Whisper 模型: 推荐 `large-v3`(VRAM >= 6GB)
  398. - `utils.py` 会自动检测 50 系列显卡(通过 `nvidia-smi` 查询 GPU 名称中的 "RTX 50"),并选择安全的 `float16` 精度
  399. **排错:**
  400. 如果出现 `CUBLAS_STATUS_NOT_SUPPORTED` 错误:
  401. 1. 确认 CTranslate2 版本 >= 4.7.1:`python3 -c "import ctranslate2; print(ctranslate2.__version__)"`
  402. 2. 确认 CUDA 版本 >= 12.8:`nvidia-smi` 或 `nvcc --version`
  403. 3. 尝试手动指定 `--compute-type float16`(如果直接使用 transcribe.py 的话)
  404. 4. 确认驱动版本 >= 565:`nvidia-smi` 查看 Driver Version
  405. #### 方案 C:Intel Arc 独立显卡(A770 / A750 / B580)
  406. Intel Arc 显卡**不支持 CUDA**,因此 faster-whisper(依赖 CTranslate2/CUDA)无法直接在 Intel Arc 上 GPU 加速。
  407. 需要使用替代方案。
  408. **推荐方案:OpenVINO + Whisper(最易用)**
  409. ```bash
  410. # 1. 安装 OpenVINO
  411. pip install openvino openvino-genai
  412. # 2. 使用 OpenVINO GenAI 的 WhisperPipeline
  413. python3 -c "
  414. import openvino_genai as ov_genai
  415. pipe = ov_genai.WhisperPipeline('OpenVINO/whisper-large-v3-fp16-ov', device='GPU')
  416. result = pipe.generate('audio.wav', language='<|zh|>')
  417. print(result.texts[0])
  418. "
  419. # 3. 或使用 Hugging Face 预转换模型
  420. pip install optimum[openvino]
  421. # 从 HuggingFace 下载 OpenVINO 格式 Whisper 模型
  422. # https://huggingface.co/OpenVINO/whisper-medium-int8-ov
  423. ```
  424. **备选方案:whisper.cpp + SYCL(性能更好,配置更复杂)**
  425. ```bash
  426. # 1. 安装 Intel oneAPI Base Toolkit
  427. # https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
  428. wget -O- https://apt.repos.intel.com/intel-gpg-keys/GPG-PUB-KEY-INTEL-SW-PRODUCTS.PUB \
  429. | gpg --dearmor | sudo tee /usr/share/keyrings/oneapi-archive-keyring.gpg > /dev/null
  430. echo "deb [signed-by=/usr/share/keyrings/oneapi-archive-keyring.gpg] \
  431. https://apt.repos.intel.com/oneapi all main" \
  432. | sudo tee /etc/apt/sources.list.d/oneAPI.list
  433. sudo apt update && sudo apt install intel-oneapi-base-toolkit
  434. # 2. 编译 whisper.cpp(启用 SYCL 后端)
  435. source /opt/intel/oneapi/setvars.sh
  436. git clone https://github.com/ggml-org/whisper.cpp.git
  437. cd whisper.cpp
  438. cmake -B build -DWHISPER_SYCL=ON
  439. cmake --build build --config Release
  440. # 3. 下载 Whisper 模型并运行
  441. ./build/bin/whisper-cli -m models/ggml-large-v3.bin -f audio.wav -l zh
  442. ```
  443. **配置说明:**
  444. - Intel Arc 不支持 CUDA,faster-whisper 在 Intel Arc 上只能用 CPU 模式
  445. - OpenVINO 方案最简单,支持 Arc A770/A750/B580 和集成显卡
  446. - whisper.cpp + SYCL 性能更好(A770 上接近 NVIDIA 中端显卡水平),但需要 oneAPI 环境
  447. - B580(Battlemage 架构)的 SYCL 支持尚在优化中,A770 目前更稳定
  448. - 推荐 Whisper 模型: `medium`(12GB VRAM 的 A770)或 `small`(8GB VRAM 的 A750)
  449. - 如果用户有 Intel Arc 显卡,脚本会自动检测并使用 CPU 模式运行 faster-whisper(作为 fallback)
  450. #### GPU 配置速查表
  451. | 显卡系列 | 架构 | CUDA Toolkit | 驱动版本 | CTranslate2 | 计算精度 | Whisper 引擎 |
  452. |---------|------|-------------|---------|-------------|---------|-------------|
  453. | RTX 40xx | Ada Lovelace (sm_89) | >= 12.4 | >= 535 | >= 4.5.0 | float16 / int8 均可 | faster-whisper |
  454. | RTX 50xx | Blackwell (sm_120) | >= 12.8 | >= 565 | >= 4.7.1 | **float16**(推荐) | faster-whisper |
  455. | Intel Arc | Xe HPG / Battlemage | N/A | i915 | N/A | N/A | OpenVINO 或 whisper.cpp+SYCL |
  456. | Intel iGPU | 集成显卡 | N/A | i915 | N/A | int8 (CPU) | faster-whisper (CPU 模式) |
  457. | 无独显 | CPU | N/A | N/A | 任意版本 | int8 (CPU) | faster-whisper (CPU 模式) |
  458. ## Workflow(工作流程)
  459. ### Phase 0a: Project Bootstrap(项目启动 / 原始素材导入)
  460. 当用户给的是一个原始素材文件夹、下载目录或一组还没整理的素材时,先用 [project_bootstrap.py](./scripts/project_bootstrap.py) 建立稳定项目结构,而不是直接在外部原始路径上剪辑:
  461. ```bash
  462. python3 scripts/project_bootstrap.py \
  463. --source ~/Downloads/raw-shoot \
  464. --project-dir work/day61 \
  465. --title "Day61 launch edit" \
  466. --output work/day61/work/source_inventory.json \
  467. --markdown work/day61/work/source_inventory.md \
  468. --project-note work/day61/project.md \
  469. --strict
  470. ```
  471. 输出:
  472. - `origin/raw|broll|audio|bgm|images|assets|sidecars/`:项目内 working copy。
  473. - `work/source_inventory.json`:`project_bootstrap.v1`,记录外部 `source_path`、项目内 `project_path`、分类、动作和 next actions。
  474. - `work/source_inventory.md`:给人审的素材清单。
  475. - `project.md`:跨会话项目记忆。
  476. - `next_steps.md`:下一步命令清单。
  477. 默认 `--mode copy`,同名文件自动加后缀,不覆盖。大素材同盘可用 `--mode hardlink`,失败会回退 copy 并写入 warning。此脚本不转码、不渲染、不上传、不调用 LLM,也不提交任何生成任务。需要把素材导入作为 analysis gate 时,跑:
  478. ```bash
  479. python3 scripts/pipeline_manifest.py \
  480. --project-dir work/day61 \
  481. --target-stage analysis \
  482. --require source_inventory \
  483. --strict
  484. ```
  485. ### Phase 0aa: Runtime Preflight(按任务核验本机能力)
  486. 在打开媒体或启动渲染前,运行 [runtime_preflight.py](./scripts/runtime_preflight.py)。只转写、probe 或抽流用 `media_io`;会编码最终画面的任务用 `core_edit`,再按需要追加 `hls_vod / soft_subtitles / gif_preview / logo_overlay / podcast_audiogram / ping_pong_loop / multicam_switch / video_enhancement / storyboard_animatic / audio_cue_mix / generation_chain_handoff / captions / qa / edge_black_trim / hdr_sdr / stabilization / interlace / remotion`:
  487. ```bash
  488. python3 scripts/runtime_preflight.py analyze \
  489. --profile core_edit \
  490. --profile captions \
  491. --profile qa \
  492. --output work/runtime_preflight.json \
  493. --markdown work/runtime_preflight.md \
  494. --strict
  495. python3 scripts/runtime_preflight.py verify \
  496. --report work/runtime_preflight.json --strict
  497. python3 scripts/pipeline_manifest.py . \
  498. --require runtime_preflight --strict
  499. ```
  500. 必须分别对待 `missing` 和 `unknown`:前者表示可解析清单中明确没有组件,后者表示版本命令或 FFmpeg listing 失败、超时或不可解析;两者都停止当前 workflow。按 Markdown 的 action 修好环境后重新 `analyze`,不要手改 JSON。报告会绑定所选 profile、相关命令版本、FFmpeg component states 和 `report_id`;`pipeline_manifest.py` 现场复验,环境或报告漂移后旧结果立即失效。
  501. 这一步只做 introspection,不运行真实编码、GPU、字体或 provider job。通过后仍要执行项目输入 preflight、真实媒体 probe、完整解码和最终视听 QA。详见 [Runtime Preflight](./docs/prompts/115-runtime-preflight.md)。
  502. ### Phase 0ab: Interlace Conform(旧广播 / DV / DVD 条件 gate)
  503. 素材出现梳齿、`TFF/BFF`、`1080i/576i/480i` 或 telecine 线索时,先运行 `interlace_conform.py analyze`。它对头、中、尾执行 FFmpeg `idet`,分类为 progressive、真实 TFF/BFF 交错、telecine candidate 或 mixed/uncertain。telecine 必须停下来走 IVTC;progressive 保持原样;不确定素材只能在逐帧证据支持下使用 classification override。
  504. 确认是真实交错后,用 `plan --reviewed-by --note --delivery work/<name>-progressive.mp4 --comparison verify/<name>-interlace-compare.mp4` 绑定决定。默认优先 bwdif,yadif 是有 warning 的 fallback;`frame` 保持帧率,`field` 保留每个 field 的运动并精确加倍 rate。apply 通过 progressive field flag、live idet、尺寸/帧率/时长/音画起止和完整解码后才提升;随后完整 1× 看 A/B,并对 combing、motion、line detail、field order、audio sync 全部 `pass` 后 confirm。详见 [Interlace Conform](./docs/prompts/116-interlace-conform.md)。
  505. ### Phase 0ac: Frame-rate Conform(手机 / 录屏 VFR 可选)
  506. 当源素材已知是 VFR、`r_frame_rate` 与 `avg_frame_rate` 可疑,或多段裁切后出现累积音画漂移时,先创建项目内 CFR 工作副本:
  507. ```bash
  508. python3 scripts/frame_rate_conform.py plan origin/phone.mp4 \
  509. --fps 30 \
  510. --delivery work/phone-cfr.mp4 \
  511. --project-dir . \
  512. --output work/frame_rate_conform_plan.json \
  513. --markdown work/frame_rate_conform_plan.md
  514. python3 scripts/frame_rate_conform.py apply work/frame_rate_conform_plan.json
  515. python3 scripts/frame_rate_conform.py verify work/frame_rate_conform_plan.json --strict
  516. ```
  517. 脚本读取全部解码视频帧的 PTS 间隔,记录 variable/non-monotonic interval、精确目标有理帧率、源/输出 SHA-256、媒体合同和完整解码 receipt。apply 只有在输出帧间隔恒定、`frame_count ≈ duration × fps`、音画起止在容差内、显示尺寸/方向正确时才原子提升;之后所有转写、裁切、字幕、同步和渲染改用 `work/phone-cfr.mp4`。30/60 fps 需按真实运动和平台选择;升帧只复制画面,降帧会丢运动采样。HDR/BT.2020/>8-bit、明显既有音画 offset 或独立设备 clock drift 不在此工具的自动修复范围。详见 [Frame-rate Conform](./docs/prompts/112-frame-rate-conform.md)。
  518. ### Phase 0ad: Edge-black Trim(片头 / 片尾黑场可选)
  519. 采集卡、相机预录或转码文件的首尾出现黑场时,用 `black_edge_trim.py plan` 运行 FFmpeg `blackdetect`;默认还会用 `silencedetect` 核对确切移除范围至少 95% 为静音,只考虑接触时间线头尾的区间,中间黑场保持不变。
  520. ```bash
  521. python3 scripts/black_edge_trim.py plan origin/capture.mp4 \
  522. --delivery work/capture-edge-trimmed.mp4 \
  523. --edge-proof verify/capture-edge-proof.mp4 \
  524. --audio-policy silent_only \
  525. --project-dir . \
  526. --output work/black_edge_trim_plan.json \
  527. --markdown work/black_edge_trim_plan.md
  528. python3 scripts/black_edge_trim.py apply work/black_edge_trim_plan.json
  529. ```
  530. 脚本保留默认 0.08 秒视觉 padding,对音画执行相同 source-time trim,输出 H.264/yuv420p CFR 与可选 48 kHz AAC;媒体合同和完整解码通过后才原子提升。edge proof 来自原片,包含拟议删除区与紧邻内容。完整 1× 看完 proof 和 delivery,确认首尾帧、内容覆盖与声音连续后运行 `confirm`,再执行 `verify --strict`。确知黑画面里的声音也应删除时可显式使用 `--audio-policy allow_audible`,该 override 保留 warning。详见 [Edge-black Trim](./docs/prompts/119-black-edge-trim.md)。
  531. 长节目或录制母版需要找内部段落边界时,运行 `program_breaks.py analyze <video> --output work/program_breaks.json`;它只标出内部 `blackdetect` 与**每条音轨** `silencedetect` 同时成立的重叠区间,默认取重叠中点作复核时间。用 `verify <report.json>` 重扫源片并核对 JSON/Markdown。候选不是已批准的切点;逐处正常速度看听后再决定分段,尤其要检查淡入淡出、黑底字幕和有声过场。无音轨素材无法证明静音,会明确拒绝。
  532. ### Phase 0ae: Loop Fill(短背景 / 环境片填满固定时长)
  533. 需要把短视频重复到指定次数或固定 slot 时,用 `loop_fill.py plan` 绑定 progressive CFR 源片、目标、交付件和首个真实接缝 proof。它保留或显式丢弃源音频,重复时音画一起推进;不自动加 crossfade,也不会把任意首尾包装成无缝循环。
  534. ```bash
  535. python3 scripts/loop_fill.py plan origin/ambient.mp4 \
  536. --duration 00:30 \
  537. --audio-mode drop \
  538. --delivery work/ambient-30s.mp4 \
  539. --seam-proof verify/ambient-loop-seam.mp4 \
  540. --project-dir . \
  541. --output work/loop_fill_plan.json \
  542. --markdown work/loop_fill_plan.md
  543. python3 scripts/loop_fill.py apply work/loop_fill_plan.json
  544. ```
  545. 正常速度看完 seam proof 与完整 delivery;确认画面接缝、运动连续性、重复闪帧、声音接缝和 slot 覆盖后运行 `confirm`,再用 `verify --strict` 或 `pipeline_manifest.py --require loop_fill_plan --strict` 放行。VFR 先跑 `frame_rate_conform.py`,HDR/BT.2020/>8-bit 先确定 `hdr_sdr.py` 色彩路径。详见 [Loop Fill](./docs/prompts/117-loop-fill.md)。
  546. ### Phase 0af: Ping-pong Loop(短动作正放倒放循环)
  547. 手势、产品旋转或生成视频动作的首尾不闭合,又需要往返循环时,用 `ping_pong_loop.py`。先把动作范围限制在几秒内;FFmpeg `reverse` 会缓存全部选中帧,planner 会记录保守内存估算并在超过 `--max-working-set-mib` 时提前停止。
  548. ```bash
  549. python3 scripts/ping_pong_loop.py plan origin/gesture.mp4 \
  550. --start 1.2 --end 2.05 --cycles 4 \
  551. --delivery work/gesture-ping-pong.mp4 \
  552. --turnaround-proof verify/gesture-turnaround.mp4 \
  553. --loop-seam-proof verify/gesture-loop-seam.mp4 \
  554. --project-dir . \
  555. --output work/ping_pong_loop_plan.json \
  556. --markdown work/ping_pong_loop_plan.md
  557. python3 scripts/ping_pong_loop.py apply work/ping_pong_loop_plan.json
  558. ```
  559. 周期使用 `0…N-1,N-2…1`,主动排除折返点和周期末尾的重复端帧。源音频固定丢弃,视觉批准后再接 BGM/SFX。正常速度看完 turnaround proof、loop-seam proof 和完整 delivery,对折返运动、循环运动、重复停帧、构图与创意意图全部 `pass` 后运行 `confirm`,再用 `verify --strict` 或 `pipeline_manifest.py --require ping_pong_loop_plan --strict` 放行。详见 [Ping-pong Loop](./docs/prompts/128-ping-pong-loop.md)。
  560. ### Phase 0ag: Clip Assembly(多源视频安全拼接)
  561. 片头、主片、生成片和片尾来自不同画布、方向、帧率、SAR、时间戳、采样率或声道数时,用 `clip_assembly.py` 代替 concat copy。按最终播放顺序传入每条唯一源片;同一片重复使用 `loop_fill.py`。
  562. ```bash
  563. python3 scripts/clip_assembly.py plan \
  564. origin/intro.mp4 origin/main.mov origin/outro.mp4 \
  565. --width 1080 --height 1920 --fps 30 \
  566. --fit contain --audio-mode fill-silence \
  567. --delivery output/assembled.mp4 \
  568. --boundary-proof verify/clip-assembly-boundaries.mp4 \
  569. --project-dir . \
  570. --output work/clip_assembly_plan.json \
  571. --markdown work/clip_assembly_plan.md
  572. python3 scripts/clip_assembly.py apply work/clip_assembly_plan.json
  573. ```
  574. 脚本在一条 FFmpeg filter graph 内统一 PTS、画布、rotation、CFR、SAR 1:1、`yuv420p` 和 48 kHz stereo,再 hard cut 输出 H.264/AAC。至少一段有音频时,无音轨片段用等长静音保持 A/V coverage;完全不需要声音时用 `--audio-mode drop`。已有音轨与视频首尾失配或 HDR/BT.2020/>8-bit 会在 plan 阶段停止。
  575. apply 通过总时长、尺寸、帧率、decoded cadence、SAR、音画首尾和完整解码后才原子提升,并从确切交付件生成覆盖所有接缝的正常速度 proof。完整播放 delivery 和 proof 后,对 clip order、visual seams、frame continuity、audio seams、complete coverage 全部做出可观察结论,再 `confirm` 和 `verify --strict`。本工具不发明转场或语义连续性;需要 J-cut/L-cut 时走独立 audio transition 计划。详见 [Clip Assembly](./docs/prompts/118-clip-assembly.md)。
  576. ### Phase 0b: Production Authorization(按确切范围授权)
  577. 当流程涉及把素材交给外部服务、改变原始叙事顺序/删减范围、消耗生成额度、克隆真人声音、使用真人/未成年人/公众人物/品牌/IP,或直接发布时,在动作发生前先写 `production_authorization_scope.v1`。scope 必须命名项目内素材、具体动作、用途、exact provider/surface、可能的 cost/quota,以及适用的 rights subject;完整 schema 见 [Production Authorization](./docs/prompts/97-production-authorization.md)。
  578. ```bash
  579. python3 scripts/production_authorization.py prepare \
  580. --project-dir . \
  581. --scope work/production_authorization_scope.json \
  582. --output work/production_authorization_request.json \
  583. --markdown work/production_authorization_request.md \
  584. --response-template work/production_authorization_response.json \
  585. --strict
  586. # 逐项填写 approve/reject、note、rights basis 与 evidence_note 后:
  587. python3 scripts/production_authorization.py audit \
  588. --project-dir . \
  589. --request work/production_authorization_request.json \
  590. --response work/production_authorization_response.json \
  591. --output work/production_authorization.json \
  592. --markdown work/production_authorization.md \
  593. --strict
  594. python3 scripts/production_authorization.py verify \
  595. --project-dir . \
  596. --report work/production_authorization.json \
  597. --strict
  598. ```
  599. `prepare` 绑定 scope 与每个 source asset 的相对路径、大小和 SHA-256;`audit` 要求动作与权利项完整逐项决定;`verify` 现场重读 scope、素材、request、response 并重算 report。任一 provider、用途、成本说明、权利对象、素材字节或决定变化都会让旧报告失效。该 artifact 只记录本地、自报的复核范围,不执行上传/剪辑/生成/发布,也不替代身份认证、数字签名、真实授权文件或法律意见。
  600. ### Phase 0: Media Library Setup(素材库初始化)
  601. 首次使用时,帮助用户建立素材目录结构:
  602. ```bash
  603. python3 scripts/media_library.py init [project_dir]
  604. ```
  605. 这会创建以下目录结构:
  606. ```
  607. media/
  608. ├── raw/ — 原始素材(摄像机/手机直出的视频)
  609. ├── broll/ — B-roll 素材(城市街景、产品特写等)
  610. ├── bgm/ — 背景音乐(MP3/WAV/M4A)
  611. ├── assets/ — 叠加素材(水印 PNG、Logo 等)
  612. └── output/ — 输出目录
  613. ```
  614. **询问素材来源**:
  615. 1. 询问用户的视频文件位置(本地路径、外部设备或云端)
  616. 2. 建议将原始素材复制/移动到 `media/raw/` 目录
  617. 3. 询问是否有 B-roll、BGM 等辅助素材
  618. 4. 如果用户视频散落在多个目录,建议先集中到 `media/raw/`
  619. **扫描并建立索引**:
  620. ```bash
  621. python3 scripts/media_library.py scan [project_dir]
  622. ```
  623. 索引系统会自动:
  624. - 扫描所有视频/音频/图片文件
  625. - 提取时长、分辨率、帧率等元数据
  626. - 关联已有的 transcript 文件
  627. - 小型项目(< 200 文件)使用 JSON 索引(`media_index.json`)
  628. - 大型项目自动升级为 SQLite 索引(`media_index.db`)
  629. - 手动升级:`python3 scripts/media_library.py upgrade`
  630. **查看素材库状态**:
  631. ```bash
  632. python3 scripts/media_library.py status
  633. ```
  634. **搜索素材**:
  635. ```bash
  636. python3 scripts/media_library.py search "关键词"
  637. ```
  638. **推荐 B-roll 候选**:
  639. ```bash
  640. python3 scripts/media_library.py recommend "AI workflow dashboard" \
  641. --project-dir . \
  642. --category broll \
  643. --target-duration 3 \
  644. --target-aspect 9:16 \
  645. --json
  646. ```
  647. 推荐结果包含 `score`、`reasons`、`absolute_path`,用于人工/agent 先确认再写入 `render_config` 或 `enrich_plan`。默认过滤已经不存在的索引文件;需要清理 stale index 时可加 `--include-missing`。
  648. **本地素材不足时规划 stock 查询**:
  649. ```bash
  650. python3 scripts/stock_material_plan.py \
  651. --subject "AI workflow automation" \
  652. --script work/transcript.json \
  653. --provider pexels \
  654. --provider pixabay \
  655. --provider coverr \
  656. --media-library . \
  657. --output work/stock_material_plan.json \
  658. --markdown work/stock_material_plan.md
  659. ```
  660. `stock_material_plan.py` 只生成 `stock_material_plan.v1` 和 Markdown review,不联网、不下载、不消耗额度。它借鉴 MoneyPrinterTurbo 的 `video_terms` / Pexels / Pixabay / Coverr / `video_count` 素材规划方式,但保持本 skill 的 artifact-first 风格。
  661. **下载或客户给的素材确认授权后登记**:
  662. ```bash
  663. python3 scripts/media_library.py import /path/to/downloaded.mp4 \
  664. --project-dir . \
  665. --category broll \
  666. --copy \
  667. --provider pexels \
  668. --source-url "https://www.pexels.com/video/demo-123/" \
  669. --creator "Demo Creator" \
  670. --license "Pexels License" \
  671. --tag "workflow,dashboard"
  672. python3 scripts/media_library.py annotate media/broll/downloaded.mp4 \
  673. --project-dir . \
  674. --source-url "https://example.com/source" \
  675. --license "owned" \
  676. --tag "client-approved"
  677. ```
  678. 登记后的 `provider`、`source_url`、`creator`、`license` 会进入 `media_index.json/db`,后续由 `asset_provenance.py` 做发布门禁。
  679. ### Phase 0.25: Creator-owned Edit Style Profile(个人/品牌剪辑风格,可选)
  680. 当用户希望多个项目保持同一套创意方向、剪辑节奏、字幕/封面/调色/BGM 习惯和标题拼写时,先生成并人工编辑 spec,再创建可移植 profile:
  681. ```bash
  682. python3 scripts/edit_style_profile.py template \
  683. --output work/edit_style_profile_spec.json
  684. # 编辑 spec 中的真实偏好和 approval basis 后:
  685. python3 scripts/edit_style_profile.py create \
  686. --spec work/edit_style_profile_spec.json \
  687. --output work/edit_style_profile.json \
  688. --markdown work/edit_style_profile.md \
  689. --strict
  690. python3 scripts/edit_style_profile.py verify \
  691. --profile work/edit_style_profile.json \
  692. --strict
  693. ```
  694. 渲染时加 `render_final.py --style-profile work/edit_style_profile.json`;生成标题文案和封面时,分别给 `generate_caption.py` 和 `cover_variants.py` 加同一参数。Profile 只填充 config 中缺失或 `null` 的受控字段;项目 config 和显式 CLI(包括封面 `--style`)始终优先。它描述“通常怎么剪”,而 `edit_recipe.py` 保存“这条时间线怎么复刻”,两者不互相替代。Profile 的 digest 只能发现文件漂移,不是签名、身份认证或权利证明。完整用法见 [docs/prompts/98-edit-style-profile.md](docs/prompts/98-edit-style-profile.md)。
  695. ### Phase 0.5: Source Receipts(事实来源 proof deck,可选但推荐)
  696. 如果视频包含新闻、数据、产品事实、健康/金融/法律判断、来源页截图或“官方说法”,在进入分镜/发布前先把 claim 和证据落成 source receipts:
  697. ```bash
  698. python3 scripts/source_receipts.py \
  699. --claims work/source_claims.json \
  700. --project-dir . \
  701. --output work/source_receipts.json \
  702. --markdown work/source_receipts.md \
  703. --html work/source_receipts.html \
  704. --require-primary-source \
  705. --strict
  706. ```
  707. `source_receipts.py` 只验证已提供的 URL 和本地截图/证据文件;不联网抓取、不截图、不上传。`source_claims.json` 里的 `screenshot` / `source_file` 相对 claims JSON 所在目录解析。新闻、数据、金融、健康、法律等高风险 claim 必须有 `source_url`;需要视觉 proof card 时加 `--require-screenshot`。发布门禁可用 `pipeline_manifest.py --require source_receipts --strict` 强制检查,`summary.blocking > 0` 会阻塞。
  708. ### Phase 1: Audio Extraction(音频提取)
  709. 对每个输入视频文件,使用 [extract_audio.py](./scripts/extract_audio.py) 提取音频:
  710. ```bash
  711. python3 scripts/extract_audio.py "<video_path>"
  712. ```
  713. 输出:与视频同目录下的 `<video_name>_audio.wav` 文件。
  714. ### Phase 2: Speech Recognition(语音识别)
  715. 使用 [transcribe.py](./scripts/transcribe.py) 对音频进行语音识别,生成带时间戳的逐句文本:
  716. ```bash
  717. python3 scripts/transcribe.py "<audio_path>" --model auto --language zh --detect-fillers
  718. ```
  719. - `--model auto`:根据硬件自动选择最佳模型(NVIDIA GPU → large-v3,Apple Silicon → large-v3-turbo,集成显卡 → medium,纯 CPU → small)
  720. - 也可手动指定:`tiny`, `base`, `small`, `medium`, `large-v3`, `large-v3-turbo`
  721. - `--engine auto`:自动检测 faster-whisper(推荐)或 openai-whisper
  722. - `--mirror`:中国用户使用镜像源下载模型
  723. - `--language`:`zh`(中文),`en`(英文),`ja`(日文)等,也可省略让 whisper 自动检测
  724. - `--silence-threshold 1.0`:静音检测阈值(秒),默认 1.0。设为 0 关闭
  725. - `--word-timestamps`:启用逐词时间戳(卡拉OK字幕必需)
  726. - `--detect-fillers`:检测填充词(中文:嗯/呃/那个/就是说;英文:um/uh/like/you know),标记纯填充词片段为建议跳过
  727. 输出:与音频同目录下的 `<video_name>_transcript.json` 文件,格式如下:
  728. ```json
  729. {
  730. "segments": [
  731. {"id": 1, "start": 0.0, "end": 2.5, "text": "大家好"},
  732. {"id": 2, "start": 2.5, "end": 5.1, "text": "今天我们来聊一个话题"}
  733. ],
  734. "silences": [
  735. {"start": 15.2, "end": 18.5, "duration": 3.3, "before_segment": 5, "after_segment": 6}
  736. ],
  737. "filler_words": [
  738. {"segment_id": 3, "text": "嗯那个", "fillers_found": ["嗯", "那个"], "is_filler_only": true},
  739. {"segment_id": 7, "text": "就是说我觉得这个方案", "fillers_found": ["就是说"], "is_filler_only": false}
  740. ]
  741. }
  742. ```
  743. **静音检测**:transcribe.py 会自动分析相邻语音片段之间的间隙。超过阈值(默认 1 秒)的间隙会被标记为静音并输出到 `silences` 字段中。这些静音通常是说话人的停顿、卡壳或口误,在构建 render_config.json 选片时应注意避开这些区域。
  744. 对独立人声或没有持续音乐的口播音轨,再运行原始转写静音核对:
  745. ```bash
  746. python3 scripts/transcript_silence_qa.py analyze origin/talking_audio.wav \
  747. origin/talking_transcript.json --output verify/transcript_silence_qa.json
  748. python3 scripts/transcript_silence_qa.py verify verify/transcript_silence_qa.json
  749. ```
  750. 报告逐段记录实际静音秒数、占比及源文件哈希;默认 `-40 dBFS`、最短静音 `0.15s`,静音占比达到 `0.8` 标为 `review`。按标记时间码回听,再在转写审校中更正。它不会自动删字或改时间码;安静的人声可能被误标,音乐、环境声可能掩盖幻觉。`verify` 会重新测量并拒绝报告或输入漂移。
  751. 长 transcript 需要找某句原话时,用 `python3 scripts/transcript_lookup.py work/transcript.json search "产品发布时间" --limit 10`;要看源片某段文字,用 `python3 scripts/transcript_lookup.py work/transcript.json span --start 90 --end 120`。输出是有界 JSON,含源段 ID、源时间码和 transcript SHA-256;搜索忽略大小写、空格与标点,可跨间隔不超过 2 秒的相邻段。它只定位原话,不推断语义相似内容;切点和措辞仍需回看原媒体并校稿。
  752. ### Phase 2a: Video Keyframe Extraction(视频关键帧提取)
  753. 对于口播类视频(尤其是在户外行走中拍摄的、带有环境音的素材),仅靠音频转录无法了解视频的视觉内容。使用 [extract_keyframes.py](./scripts/extract_keyframes.py) 提取视频关键帧并生成时序图,以便全面理解视频内容:
  754. 拿到场景检测、字幕或审片时间码时,先运行 `frame_grid.py locate origin/clip.mp4 --at-seconds 20.4`,读取 `nearest.decoded_frame` 和相邻两帧的真实 PTS。再以该帧附近为 `--start-frame` 运行 `frame_grid.py grid origin/clip.mp4 --start-frame 240 --step 2 --count 16 --output verify/grid.png --receipt verify/grid.json`。PNG 中的 `CELL 1` 等标记与 JSON 的 `cell` 对应;找到目标后运行 `frame_grid.py frame origin/clip.mp4 --start-frame 250 --output verify/frame.png --receipt verify/frame.json` 导出确切帧。交接前用 `verify <receipt>` 核对源片、PNG 和映射收据。定位和抽帧都从头顺序解码,长片深处查询会耗时;网格最多 36 格,格图不能代替正常速度播放。
  755. ```bash
  756. python3 scripts/extract_keyframes.py "<video_path>"
  757. ```
  758. 参数说明:
  759. - `--max-frames 16`:最大关键帧数量(默认 16)
  760. - `--threshold 0.4`:场景变化检测灵敏度(0.0-1.0,越低提取越多关键帧,默认 0.4)
  761. - `--cols 4`:时序图网格列数(默认 4)
  762. - `--thumb-width 320`:缩略图宽度(默认 320px)
  763. - `--output-dir`:关键帧输出目录(默认 `<video_name>_keyframes/`)
  764. - `--no-storyboard`:仅提取关键帧,不合成时序图
  765. 输出:
  766. - `<video_name>_keyframes/` — 各关键帧 PNG 图片(带时间戳命名)
  767. - `<video_name>_storyboard.png` — 合成的时序图(网格布局 + 时间戳标注)
  768. - `<video_name>_keyframes.json` — 关键帧元数据(时间戳、帧号、文件路径)
  769. **为什么需要关键帧提取**:
  770. - 口播视频经常在走路中拍摄,画面中的场景变化(街道→公园→咖啡店)是重要的叙事线索
  771. - 时序图让 AI 可以同时看到音频内容(transcript)和视觉内容(keyframes),做出更好的选片判断
  772. - 可以发现纯音频分析无法捕捉的信息:肢体语言、表情变化、环境切换、产品展示等
  773. **典型工作流**:
  774. ```bash
  775. # 1. 提取音频并转录
  776. python3 scripts/extract_audio.py video.mp4
  777. python3 scripts/transcribe.py video_audio.wav --model auto --language zh --detect-fillers
  778. # 2. 提取关键帧生成时序图
  779. python3 scripts/extract_keyframes.py video.mp4
  780. # 3. 把每帧与前后 3 秒内的原话对齐,查看索引并核验来源
  781. python3 scripts/visual_transcript_index.py build video_keyframes.json video_transcript.json \
  782. --output work/visual_transcript_index.json --markdown work/visual_transcript_index.md
  783. python3 scripts/visual_transcript_index.py verify work/visual_transcript_index.json
  784. ```
  785. 索引每帧最多展示 8 段原话,并标明截断;`--radius` 可设 0.1–30 秒,`--max-segments` 可设 1–12。画面是抽样帧,原话是附近时间窗口,不能据此断言画面中出现了某件事,也不能代替原片完整播放。源视频、关键帧元数据、图片、转写或 Markdown 改动后需重新构建索引。
  786. 教程成片需要图文伴读稿时,先人工核对 `chapter_markers.py` 导出的章节标题、边界和说明,再运行 `tutorial_companion.py build output/master.mp4 output/chapters/chapters.json work/transcript.json --title "教程标题" --output output/companion`。每章默认在中点截取一张图;若中点为过场,用 `--at ch01=12.5` 指定该章内更合适的时间。`verify output/companion/receipt.json` 检查源片、章节、转写、截图和 Markdown 字节;生成状态只表示草稿已建立。逐章看图、听原片,确认截图确实展示该步骤、说明没有超出证据后再对外交付。伴读稿最多 24 章、每章列出 6 段原话,超出会标明遗漏数。
  787. **AI Agent 综合分析要点**:
  788. - 将关键帧时序图与转录文本对照,标注每个时间段的「说了什么 + 画面是什么」
  789. - 找出画面与语音最匹配的高质量片段(如:讲到"这家店"时画面正好对着店铺)
  790. - 识别画面模糊、遮挡、光线不佳的片段,建议跳过
  791. - 户外拍摄时,注意画面抖动严重的片段,在选片时降低优先级
  792. ### Phase 2a: Adaptive Scene Boundaries(自适应视觉场景边界)
  793. 长视频拆条、抽样理解或成片节奏分析前,优先为运动镜头生成自适应场景边界:
  794. ```bash
  795. python3 scripts/scene_boundaries.py video.mp4 \
  796. --method adaptive \
  797. --adaptive-threshold 3.0 \
  798. --min-scene-score 0.15 \
  799. --min-scene-duration 1.0 \
  800. --output work/scene_boundaries.json \
  801. --markdown work/scene_boundaries.md
  802. ```
  803. `adaptive` 把每帧 FFmpeg scene score 与前后邻域均值比较,可减少持续摇镜、运动或闪烁造成的密集误切;`boundary_evidence[]` 保留 score、adaptive ratio 和邻域均值,必须先看 Markdown 再交给 `highlight_picker.py --scene-boundaries`。需要复现旧流程或固定机位素材时,用 `--method fixed --threshold 0.35`。
  804. ### Phase 2b: Visual Dedupe(跨素材重复镜头复核)
  805. 多机位、多 take、重复转码或 B-roll 候选进入时间线前,用 `visual_dedupe.py` 对多个 source 的场景做三点感知哈希复核:
  806. ```bash
  807. python3 scripts/visual_dedupe.py \
  808. --manifest work/visual_dedupe_sources.json \
  809. --output work/visual_dedupe.json \
  810. --markdown work/visual_dedupe.md \
  811. --strict
  812. ```
  813. manifest 的 `sources[]` 为每个来源提供 `id`、`video`、可选 `scene_boundaries` 和 `quality_score`;相对路径以 manifest 目录为基准。脚本默认只比较不同来源,要求 10%/50%/90% 至少两个采样点匹配,并把 `quality_score`、分辨率和文件大小用于保留建议。它只输出 review artifact,绝不删除或移动源素材。发现重复组时,先人工查看 source range,再从下游 edit plan 排除确认重复的候选。
  814. ### Phase 2c: Video Understanding(抽样帧 + 可选 YOLO)
  815. 当素材里的人、手机、电脑屏幕、产品、车辆或其他动态对象会影响裁切、隐私遮挡或 B-roll 选择时,使用 [video_understanding.py](./scripts/video_understanding.py) 生成结构化视觉理解 artifact。默认不需要安装 detector;如果要运行 YOLO,先安装可选依赖 `ultralytics`。
  816. 需要在无检测模型时查看运动位置,可运行 `python3 scripts/motion_center.py analyze video.mp4 --output work/motion_center.json`,再用 `verify work/motion_center.json` 现场复测。报告按默认 2 fps 比较缩小后的相邻灰度帧;`local_motion` 给出 0–1 归一化中心,`static` 和 `global_change` 不给中心。像素运动可能来自背景或镜头移动,不能当作人物检测结果直接交给 `smart_reframe.py --detections`;先回看对应时间点,再决定构图。
  817. ```bash
  818. # 无 detector:只抽样帧并生成 review shell
  819. python3 scripts/video_understanding.py video.mp4 \
  820. --output work/video_understanding.json \
  821. --markdown work/video_understanding.md
  822. # 可选 YOLO:检测对象并生成 detections/tracks/scene_tags
  823. pip install ultralytics
  824. python3 scripts/video_understanding.py video.mp4 \
  825. --scene-boundaries work/scene_boundaries.json \
  826. --detector yolo \
  827. --model yolo11n.pt \
  828. --output work/video_understanding.json \
  829. --markdown work/video_understanding.md \
  830. --strict
  831. ```
  832. 输出:
  833. - `video_understanding.json` — `video_understanding.v1`,包含 `frames[]`、`detections[]`、`tracks[]`、`scene_tags[]`、`warnings[]`
  834. - `video_understanding.md` — 人工 review 表,列出抽样帧、检测数量、轨迹、标签和 warning
  835. 典型下游:
  836. ```bash
  837. python3 scripts/smart_reframe.py video.mp4 \
  838. --detections work/video_understanding.json \
  839. --platform douyin \
  840. --output work/reframe_douyin.json \
  841. --markdown work/reframe_douyin.md
  842. python3 scripts/privacy_redact.py \
  843. --video video.mp4 \
  844. --detections work/video_understanding.json \
  845. --output work/privacy_redaction.json \
  846. --markdown work/privacy_redaction.md
  847. ```
  848. 注意:内置 tracklets 是为口播剪辑做的轻量关联,不等同于逐帧多目标跟踪。对体育、车流、多人遮挡等高动态素材,可以用 Ultralytics `model.track(..., tracker="bytetrack.yaml")`、BoT-SORT 或 Norfair 生成更密集的检测/track 结果,再转换成同一份 `detections[]` / `tracks[]` JSON。
  849. ### Phase 2.5: Transcript Review(转录文字校验)
  850. 转录完成后,**必须**对所有 transcript.json 中的文字进行逐条审查,修正以下两类问题:
  851. **1. 语音识别错误(ASR errors)**:
  852. Whisper 常见的识别错误类型:
  853. - **专有名词/产品名**:如 "opencloud" → "OpenClaw"、"cloudcode" → "Claude Code"、"cloud ops" → "Claude Opus"
  854. - **同音字错误**:如 "小红树" → "小红书"、"检映" → "剪映"、"断耕" → "断更"、"懒得讲" → "懒得剪"
  855. - **英文拼写**:如 "scale" → "skill"、"箱子" → "视频"
  856. - **尾部幻觉**:Whisper 有时在安静片段末尾生成无意义的重复文字,应直接删除
  857. **2. 口误标记(Speaker errors)**:
  858. - **重复/卡壳**:说话人重复说同一句话或卡住后重新说,标记为可跳过
  859. - **乱码片段**:语音模糊导致识别为无意义文字的片段(如连续的单字碎片),标记为可跳过
  860. 专业术语、人名、同音字或中英混说较多时,先运行 `semantic_transcript_review.py prepare`,让当前 Agent/模型填写 provider-neutral response;再运行 `audit`。不要把模型 confidence 当批准:从 audit Markdown 复制绑定 `source_sha256 + review_id` 的 choices 模板,逐项 `approve` / `reject` 后才运行 `apply`。`audit` 会从源 transcript 推导完整覆盖率,并拒绝整句润色、非最小字符补丁、数字/标点变化、越界/重叠补丁和旧 transcript hash。成功 apply 后,把 `transcript_semantic_reviewed.json` 交给下面的同步媒体 HTML 继续听审;详见 [docs/prompts/79-semantic-transcript-review.md](docs/prompts/79-semantic-transcript-review.md)。
  861. ```bash
  862. python3 scripts/semantic_transcript_review.py prepare \
  863. --transcript work/transcript.json \
  864. --output work/semantic_review_request.json \
  865. --markdown work/semantic_review_request.md
  866. python3 scripts/semantic_transcript_review.py audit \
  867. --transcript work/transcript.json \
  868. --response work/semantic_review_response.json \
  869. --output work/transcript_semantic_review.json \
  870. --markdown work/transcript_semantic_review.md \
  871. --strict
  872. python3 scripts/semantic_transcript_review.py apply \
  873. --transcript work/transcript.json \
  874. --audit work/transcript_semantic_review.json \
  875. --choices work/semantic_review_choices.json \
  876. --output work/transcript_semantic_reviewed.json
  877. ```
  878. **校验流程**:
  879. 1. 用 `transcript_review.py html` 生成一个无外部依赖的本地页面;纯终端环境用 `export` 生成文本。
  880. 2. 页面里点击时间码对着媒体校稿;播放时当前段自动高亮。行内编辑支持本地自动保存、查找替换和 CPS 标黄。
  881. 3. 显式保存 `transcript_review.txt`,不要让页面或 agent 直接覆盖原始 transcript。
  882. 4. 用 `apply` 生成 `transcript_reviewed.json`;后续清稿、粗剪、分镜和字幕统一使用 reviewed 文件。
  883. 5. 对于口误/乱码片段,在展示片段列表时(Phase 3)标注为建议跳过。
  884. ```bash
  885. python3 scripts/transcript_review.py html \
  886. --transcript work/transcript.json \
  887. --video origin/talking.mp4 \
  888. --corrections work/corrections.json \
  889. --output work/transcript_review.html \
  890. --max-cps 20
  891. python3 scripts/transcript_review.py apply \
  892. --transcript work/transcript.json \
  893. --review work/transcript_review.txt \
  894. --output work/transcript_reviewed.json
  895. ```
  896. HTML 和媒体只在本机打开,不上传、不调用 LLM。浏览器不能直接写文件时会下载 `transcript_review.txt`;把它放回 `work/` 后再 apply。CPS 是预渲染提示,最终还要跑 `subtitle_readability_qa.py --strict`。
  897. **注意**:此步骤必须在 Phase 5(渲染)之前完成,因为字幕文字来源于 transcript.json。修正后再渲染,才能保证最终视频中的字幕文字正确。
  898. ### Phase 2.5a: Target Script Alignment(按确认稿装配原话,可选)
  899. 如果客户、编导或用户已经确认成片稿,而同一句话录了多个 take 或分散在不同素材里,先把目标稿按“一行一个完整 spoken unit”整理,再匹配 reviewed transcript:
  900. ```bash
  901. python3 scripts/script_alignment.py \
  902. --target-script work/target_script.md \
  903. --transcript take-a=work/take-a_transcript_reviewed.json \
  904. --transcript take-b=work/take-b_transcript_reviewed.json \
  905. --media take-a=origin/take-a.mp4 \
  906. --media take-b=origin/take-b.mp4 \
  907. --output work/script_alignment.json \
  908. --markdown work/script_alignment.md \
  909. --render-config work/render_config.json \
  910. --clean-script work/clean_script.md \
  911. --strict
  912. ```
  913. 脚本只做本地词面匹配,不调用 LLM、不改源文件、不判断表情/镜头/表演质量。它输出每句的稳定 candidate id、source time、原话和 sequence/coverage/ngram/length evidence;word timestamps 存在时优先收紧到词边界,只有 segment 时间戳时保守保留整段。低分、前两名过近、无候选、素材缺失或源时间重复占用会写 `summary.blocking` 并让 `--strict` 返回 2。
  914. 同文案多个 take 出现 `ambiguous_match` 时,必须看/听 Markdown 里的候选,把确认结果写成 `{"choices":{"target-001":"<candidate-id>"}}`,再用 `--choices work/script_alignment_choices.json` 重跑。人工 choice 只能解决词面低分/多解,不能绕过缺文件或时间重叠。`summary.blocking=0` 后再进入 `edit_preflight.py` / `render_final.py`;详细用法见 [docs/prompts/78-script-alignment.md](docs/prompts/78-script-alignment.md)。
  915. ### Phase 2.6: ASR Rough Cut(口头禅/重复句粗剪,可选)
  916. 如果 transcript 中纯口头禅、卡壳重说或相邻重复句较多,先用 [rough_cut.py](./scripts/rough_cut.py) 生成可审计粗剪计划:
  917. ```bash
  918. python3 scripts/rough_cut.py --transcript work/transcript.json --cut-list work/rough_cut.json
  919. ```
  920. 确认计划后可直接渲染粗剪版:
  921. ```bash
  922. python3 scripts/rough_cut.py \
  923. --transcript work/transcript.json \
  924. --input origin/talking.mp4 \
  925. --output output/talking.roughcut.mp4 \
  926. --cut-list work/rough_cut.json
  927. ```
  928. `rough_cut.py` 会输出 `decisions` / `removed_segments` / `keep_segments` / `speedup_ratio`。它不调用 LLM,不提交任何付费任务;只用 `transcribe.py --detect-fillers` 的 filler metadata 和相邻文本相似度做保守粗剪。渲染前用 `timeline_view.py --cut-list work/rough_cut.json` 看源素材删除段;渲染后用 `--rendered-cut-list work/rough_cut.json` 看成片实际拼接点。
  929. ### Phase 2.6b: Multimodal Dead-Air(静音 + 静帧保守去死区,可选)
  930. 如果纯音频 `jump_cut.py` 可能误删仍有表情、手势、产品展示或屏幕操作的停顿,改用音频静音与画面静帧的 AND gate:
  931. ```bash
  932. python3 scripts/multimodal_dead_air.py plan origin/talking.mp4 \
  933. --delivery work/talking-dead-air-tight.mp4 \
  934. --output work/multimodal_dead_air_plan.json \
  935. --markdown work/multimodal_dead_air_plan.md \
  936. --strict
  937. python3 scripts/multimodal_dead_air.py verify work/multimodal_dead_air_plan.json --strict
  938. DEAD_AIR_CUT_COUNT="$(python3 -c 'import json; print(len(json.load(open("work/multimodal_dead_air_plan.json"))["removed_segments"]))')"
  939. python3 scripts/timeline_view.py origin/talking.mp4 \
  940. --cut-list work/multimodal_dead_air_plan.json \
  941. --output-dir verify/dead-air-cuts \
  942. --limit "$DEAD_AIR_CUT_COUNT"
  943. python3 scripts/multimodal_dead_air.py apply work/multimodal_dead_air_plan.json \
  944. --markdown work/multimodal_dead_air_plan.md
  945. ```
  946. 默认只有静帧覆盖静音至少 60% 才入选,并且只删除二者交集;80ms padding、30ms 音频 fade 和 20% 删除预算继续生效。计划绑定源 SHA-256 和媒体契约,apply 使用临时 MP4,并在 H.264/AAC、`yuv420p`、尺寸、帧率、采样率、声道、时长和完整解码全部通过后原子提升。`timeline_view.py` 默认只看 20 个切点,因此必须像上面一样把本计划的实际删除段数传给 `--limit`;若计数为 0,停止并保留原片。它不理解表演、语义或有意留白;所有源切点仍须先看,输出仍须 1× 带声音完整复核。详见 [docs/prompts/88-multimodal-dead-air.md](docs/prompts/88-multimodal-dead-air.md)。
  947. ### Phase 3: User Interaction(用户交互)
  948. **展示片段列表给用户**,格式如下:
  949. ```
  950. 视频片段列表:
  951. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  952. # | 时间区间 | 内容
  953. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  954. 1 | 00:00.0 - 00:02.5 | 大家好
  955. 2 | 00:02.5 - 00:05.1 | 今天我们来聊一个话题
  956. 3 | 00:05.1 - 00:08.3 | 这个话题非常有意思
  957. ...
  958. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  959. 请选择要合成的片段(示例):
  960. - 连续范围:1-10
  961. - 多个片段:1,3,5,7
  962. - 混合选择:1-4,6,8-10
  963. ```
  964. 如果有多个视频文件,分别展示每个视频的片段列表,让用户跨视频选择。
  965. #### AI 智能选片建议
  966. 在展示片段列表时,AI agent 应基于以下维度为每个片段提供推荐评分(1-5 星):
  967. **吸引力评分维度**:
  968. 1. **Hook 强度**(前 3 秒):是否有吸引人的开头(提问、反直觉观点、情感触发)
  969. 2. **信息密度**:每秒传递的有效信息量(避免重复、废话)
  970. 3. **情感变化**:是否有情感起伏(幽默→严肃→惊喜)
  971. 4. **完整性**:片段是否构成完整叙事单元(有开头、展开、收尾)
  972. **自动跳过建议**:
  973. - transcript 中 `is_filler_only: true` 的片段(纯填充词)
  974. - 静音间隙 > 2 秒的相邻片段(卡壳后重说)
  975. - 转录文字与前一片段高度重复的片段(口误重说)
  976. **长视频自动拆短片**(视频 > 3 分钟时):
  977. AI agent 应分析 transcript 识别话题转换点(语义断裂、过渡词如"接下来"、"另外"),将片段按话题分组为独立短视频(每个 30-90 秒),并为每组计算整体吸引力评分:
  978. ```
  979. 推荐短视频拆分方案:
  980. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  981. 方案 | 片段范围 | 时长 | 主题 | 推荐指数
  982. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  983. A | #1-#8 | 45s | 痛点引入 | ★★★★★
  984. B | #9-#18 | 62s | 核心方法 | ★★★★☆
  985. C | #19-#25 | 38s | 实操演示 | ★★★☆☆
  986. D | #1-#25 | 2m25s | 完整版 | ★★★★☆
  987. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  988. ```
  989. 等待用户回复选择后,进入 Phase 4。
  990. 选择完成后、批量渲染前,建议用词级时间戳校正切点,避免候选范围落在词中间或半句结尾:
  991. ```bash
  992. python3 scripts/audio_boundary_snap.py \
  993. --candidates work/highlight_candidates.json \
  994. --transcript work/transcript.json \
  995. --media origin/long-talk.mp4 \
  996. --output work/audio_boundary_plan.json \
  997. --markdown work/audio_boundary_plan.md \
  998. --strict
  999. ```
  1000. 输出 `audio_boundary_plan.v1` 的 `selected[]` 可直接传给 `shorts_batch.py --highlights`。脚本只读本地候选、transcript 和可选媒体;它不渲染、不上传、不调用 provider。`--strict` 会在缺词级时间戳、非法时间段、源媒体缺失或安全边界超平台时长时返回 2。
  1001. ### Phase 4: Render Config(渲染配置)
  1002. 根据用户的选择,生成 `render_config.json` 配置文件。
  1003. **重要说明:渲染配置是项目级文件**
  1004. SKILL 中展示的 render_config.json 格式只是**模板/参考**,不要直接修改 Skill 仓库中的任何文件。每个视频项目应在**用户工作目录**下创建独立的渲染配置:
  1005. ```bash
  1006. # 在用户的视频项目工作目录下创建 script/ 文件夹
  1007. mkdir -p script/
  1008. # 在 script/ 下为每个视频项目创建独立的渲染配置文件
  1009. # 例如:script/render_config.json
  1010. ```
  1011. **目录结构示例**:
  1012. ```
  1013. ~/Videos/my-project/ ← 用户工作目录
  1014. ├── script/ ← 渲染配置目录(每个项目独立)
  1015. │ └── render_config.json ← 本项目的渲染配置
  1016. ├── media/
  1017. │ ├── raw/ ← 原始素材
  1018. │ ├── broll/
  1019. │ └── output/ ← 最终输出
  1020. ├── *_audio.wav ← 提取的音频
  1021. └── *_transcript.json ← 转录文件
  1022. ```
  1023. **渲染配置文件格式**(`script/render_config.json`):
  1024. ```json
  1025. {
  1026. "clips": [
  1027. {"video": "path/to/video1.MOV", "segment_id": 4, "transcript": "path/to/transcript1.json"},
  1028. {"video": "path/to/video1.MOV", "segment_id": 5, "transcript": "path/to/transcript1.json"},
  1029. {"video": "path/to/video2.MOV", "segment_id": 1, "transcript": "path/to/transcript2.json",
  1030. "broll": "path/to/cityscape.mp4", "broll_start": 5.0}
  1031. ],
  1032. "title": "封面标题文字",
  1033. "subtitle": "副标题/情感钩子(可选)",
  1034. "cover_style": "news",
  1035. "cover_duration": 2.0,
  1036. "cover_image": "path/to/custom_cover.png",
  1037. "cover_use_frame": false,
  1038. "video_overlay": "path/to/overlay.png",
  1039. "rec_blink": {
  1040. "dot_image": "path/to/dot.png",
  1041. "x": 55, "y": 66,
  1042. "period": 1.0
  1043. },
  1044. "end_cards": [
  1045. {"text": "感谢观看\n更多内容敬请期待", "duration": 3.5}
  1046. ],
  1047. "bgm": "path/to/background_music.mp3",
  1048. "bgm_volume": 0.15,
  1049. "bgm_fade_out": 3.0,
  1050. "bgm_ducking": true,
  1051. "bgm_ducking_threshold": 0.03,
  1052. "bgm_ducking_ratio": 8,
  1053. "bgm_ducking_attack_ms": 20,
  1054. "bgm_ducking_release_ms": 500,
  1055. "subtitle_style": "karaoke",
  1056. "subtitle_highlight_color": "#FFFF00",
  1057. "chapters": [
  1058. {"title": "章节名", "start": 0.0, "end": 30.0}
  1059. ],
  1060. "text_badges": [
  1061. {"text": "关键结论", "start": 12.0, "end": 13.5}
  1062. ],
  1063. "broll_overlays": [
  1064. {"video": "path/to/cityscape.mp4", "start": 8.0, "end": 10.0, "source_start": 2.0}
  1065. ],
  1066. "image_overlays": [
  1067. {"image": "path/to/generated.png", "start": 18.0, "end": 21.0, "fit": "cover"}
  1068. ],
  1069. "pip_overlays": [
  1070. {"video": "path/to/facecam.mp4", "start": 0.0, "end": 42.0, "position": "bottom_right", "sync_offset": 0.18}
  1071. ]
  1072. }
  1073. ```
  1074. **使用渲染配置**:
  1075. ```bash
  1076. # 渲染时指定 script/ 下的配置文件
  1077. python3 scripts/render_final.py --config script/render_config.json --output media/output/final.mp4
  1078. ```
  1079. **B-roll 替换**(`broll` 字段):
  1080. - 在 clip 中添加 `"broll": "path/to/video.mp4"` 可替换该片段的画面,同时保留原始音频
  1081. - `broll_start` 指定从 B-roll 视频的哪个时间点开始截取(默认 0.0)
  1082. - B-roll 视频会自动缩放/裁切以匹配主视频分辨率
  1083. - 适用场景:屏幕录制口播配城市街景、音频配音配画面等
  1084. **Auto-Enrich 自动接入**(推荐):
  1085. - 先运行 `auto_enrich.py --output work/enrich_plan.json`
  1086. - 渲染时加 `--enrich-plan work/enrich_plan.json`
  1087. - `broll[].suggested_asset` 会转成定时 B-roll video overlay;`chapter_cards[]`、`stickers[]` 和 `emphasis_cues[]` 会转成 ASS badge;`emphasis_cues[]` 还可生成无红框的轻微 center push-in;`chapter_cards[].png` / `imagegen[].image_path` / `imagegen[].generated_path` 会转成定时图片 overlay
  1088. - `pip_overlays[]` 会转成定时 facecam / camera 小窗;camera audio 默认忽略,主音频仍来自 render config
  1089. - 没有实际生成文件的 imagegen cue 只作为提示输出,不会阻塞渲染
  1090. - 合并后的可见文字仍会走 `_internal_text_guard` 和 `content_guard.py`
  1091. **Beat Edit Plan 节拍剪辑骨架**(音乐视频 / 卡点 montage 可选):
  1092. - 运行 `beat_sync.py --bgm origin/bgm.mp3 --generate-plan --duration 30 --beats-per-cut 4 --min-segment 0.75 --max-segment 3 --output work/beat_edit_plan.json --markdown work/beat_edit_plan.md`
  1093. - 输出 `beat_edit_plan.v1`:`cut_times[]`、program-time `segments[]`、逐切点 `boundary_evidence[]`、检测方法和 `summary`
  1094. - 默认每 4 拍提出一个切点;最短/最长镜头守卫会优先改选附近 beat,实在没有合适 beat 才插入 `duration_guard`
  1095. - `librosa` 不可用或读取失败时只生成固定 BPM 网格,并把状态标为 `review`;必须听音乐复核,不能把 fallback 当作真实节拍
  1096. - 计划只定义时间槽,不选择素材、不渲染、不改源文件;确认后再把镜头映射进 `render_config` / EDL / OTIO
  1097. - 已有 cut times 仍使用原命令 `beat_sync.py --bgm origin/bgm.mp3 --cuts work/cut_times.json --window 0.2`
  1098. **Speed Ramp 局部慢动作 / velocity edit**(动作、产品 reveal、游戏、montage 可选):
  1099. - 先逐帧找到 impact frame,再运行 `speed_ramp.py plan origin/action.mp4 --ramp 4.6,5.0,1,0.25,s_curve --hold 5.0,5.8,0.25 --ramp 5.8,6.2,0.25,1,ease --interpolate-fps 120 --output work/speed_ramp_plan.json --markdown work/speed_ramp_plan.md`
  1100. - `verify` 会重算 plan id、源文件 SHA-256、source/output coverage 和逐段 `duration / speed`;源片或 pieces 漂移立即阻塞
  1101. - `apply` 用同目录临时文件渲染,成功后才替换目标;默认不覆盖、不跟随 output symlink,也不能覆盖 source
  1102. - `--interpolate-fps` 是 FFmpeg motion interpolation,可能产生肢体 / 边缘伪影;极慢音频必须试听,必要时 plan 阶段加 `--mute-audio`
  1103. - 最终必须用 1×、带声音完整播放;变速后重新生成字幕 / timecoded artifacts、跑 render QA,并重新做最终审批。详见 `docs/prompts/83-speed-ramp.md`
  1104. **Freeze-Punch 关键帧定格强调**(表情峰值、动作落点、产品揭晓可选):
  1105. - 先逐帧确定 impact,再运行 `freeze_punch.py plan origin/reaction.mp4 --freeze 4.8,0.8,1.08,0.5,0.42 --delivery work/reaction-freeze-punched.mp4 --output work/freeze_punch_plan.json --markdown work/freeze_punch_plan.md`
  1106. - 它用 impact frame 替换其后的短画面窗口;音频和总时长保持不变,所以不会因本操作漂移字幕、章节或 cue 时间码
  1107. - pending plan 会阻塞;读完 Markdown 后运行 `apply`,再运行 `verify --strict`。apply 只有在 H.264/AAC、yuv420p、尺寸/fps/时长/音轨契约和全长解码通过后才原子提升输出并写回 hash
  1108. - 必须 1× 带音频检查 freeze 入口/出口、可见说话人冻嘴、动作跳跃、主体裁切和放大软化。源片/plan/成片漂移会让 live gate 失效;旧 QA、approval receipt 和 publish package 必须重做。详见 `docs/prompts/101-freeze-punch.md`
  1109. **J-cut / L-cut 声音先行 / 延续转场**(访谈、叙事、场景切换可选):
  1110. - 只在人工明确选定的边界运行:`audio_transition.py plan work/render_config.json --transition 1,j_cut,0.4 --transition 3,l_cut,0.5 --output work/audio_transition_plan.json --markdown work/audio_transition_plan.md`
  1111. - J-cut 使用下一 clip 入点之前的真实源音频 handle;L-cut 使用上一 clip 出点之后的 handle,并跳过下一 clip 等长的开头音频以恢复同步。handle 不足直接阻塞,不用静音伪造
  1112. - 计划绑定 render config、transcript、源片/B-roll SHA-256 和 canonical plan id;`verify` 会从 live inputs 重新编译,手改 digest 不能隐藏漂移
  1113. - 用 `audio_transition.py apply ... --output output/master.mp4 --receipt work/audio_transition_apply.json`,或给 `render_final.py` 加 `--audio-transition-plan`;字幕、overlay、BGM 和错位主音频仍在一次 FFmpeg 编码中完成
  1114. - 必须在 1× 用耳机和手机逐个试听改变的边界,确认无吞字、复读、双人声、click、泵动和环境底噪跳变。机器只能验证时序/hash,不能判断交叠对白是否合适。详见 [docs/prompts/86-audio-transition.md](docs/prompts/86-audio-transition.md)
  1115. **Audio Cue Mix 音效 cue 单轨混音**(`audio_cue_sheet.v1` 已审后运行):
  1116. - 用最终独立旁白执行 `audio_cue_mix.py plan --project-dir . --cue-sheet work/audio_cue_sheet.json --voice work/final_narration.wav --delivery work/audio_cue_mix.wav --output work/audio_cue_mix.json --markdown work/audio_cue_mix.md`;本地音效必须位于项目内并绑定 SHA-256/媒体契约
  1117. - 缺少 `transition_whoosh / emphasis_ping / success_chime / warning_tick` 时,可显式加 `--synthesize-missing` 使用确定性 FFmpeg recipe;未知类别、显式素材丢失、cue 越界或非法增益保持阻塞
  1118. - `apply` 统一 48 kHz stereo、trim/pad、短 fade、毫秒级 `adelay` 和受限增益;`amix normalize=0` 保持旁白电平,limiter 只做峰值保护,完整解码通过后才原子提升输出
  1119. - 完整 1× 听完后运行 `confirm`,逐项确认 `speech_intelligibility / cue_timing / sfx_level / creative_fit / clicks_or_clipping`;随后 `verify --strict`。cue sheet、旁白、音效、输出或 review 绑定漂移都会重新阻塞
  1120. - 该输出不含 BGM;音乐继续走 `render_final.py --bgm-ducking`,混入音乐后重新完整试听并运行最终音频 QA。详见 [docs/prompts/123-audio-cue-mix.md](docs/prompts/123-audio-cue-mix.md)
  1121. **Video Stabilization source-bound 手持防抖**(仅用于不想要的抖动):
  1122. - 先运行 `video_stabilization.py doctor`。`plan --backend auto` 优先两遍 `vidstab`;缺少该 filter 时会把单遍 `deshake` 明确写进计划并保留降级 warning,不会在 apply 时静默换后端
  1123. - 原片看过后,用 `plan origin/handheld.mp4 --decision stabilize --reviewed-by editor --output work/video_stabilization_plan.json --markdown work/video_stabilization_plan.md` 记录源 SHA-256、profile 和人工决定;有意手持 / pan 应改用 `--decision keep`
  1124. - `apply ... --output work/handheld-stabilized.mp4 --comparison verify/handheld-stabilization-compare.mp4` 只写新工作副本与全长左/右 A/B;随后必须 1× 看完整 comparison,再运行 `confirm --reviewed-by ... --note ...`
  1125. - `pipeline_manifest.py` 会实时检查源片、稳定版、comparison 的 hash 与复核状态。稳定化不能修复滚动快门、运动模糊或失焦;后续用工作副本,不覆盖 `origin/`。详见 `docs/prompts/84-video-stabilization.md`
  1126. **Video Enhancement 本地放大 / 补帧交付**(现有成片需要更高尺寸或帧率时运行):
  1127. - 先跑 `runtime_preflight.py analyze --profile video_enhancement ... --strict`,再用 `video_enhancement.py plan output/master.mp4 --target-short-edge 1080 --fps 60 --enhanced output/master-enhanced.mp4 --comparison verify/video-enhancement-ab.mp4 --output work/video_enhancement_plan.json --markdown work/video_enhancement_plan.md`
  1128. - `--target-short-edge` 同时适配横竖屏,也可改用 `--scale 2`;只补帧时省略尺寸参数。脚本只接受放大和不低于源 cadence 的目标,源 hash、显示尺寸、目标设置、filter、输出与 review 都进入 canonical plan
  1129. - `apply` 用 Lanczos 与可选 FFmpeg motion-compensated `minterpolate`,输出 H.264/AAC;尺寸、帧率、时长、音轨存在性和两份 MP4 的完整解码都通过后才原子提升
  1130. - 完整正常速度看 source-left/enhanced-right A/B,再单独带声看完整增强件;`confirm` 必须逐项给 `detail / edges / motion_cadence / audio_sync` 的 `pass|fail`。任一 fail 继续阻断
  1131. - Lanczos 只是确定性 resize,不能恢复源片不存在的细节;补帧可能在切点、遮挡、手、脸和高速运动产生 ghost/warp。需要 ML VSR 或生成式修复时另走经授权工具,并重新执行真实输出复核。详见 [docs/prompts/126-video-enhancement.md](docs/prompts/126-video-enhancement.md)
  1132. **Chroma Key 绿幕 / 蓝幕抠像与换背景**(仅用于明确纯色幕布):
  1133. - 先运行 `chroma_key.py prepare --project-dir . --foreground origin/presenter-green.mp4 --background origin/studio.png --output-video output/presenter-studio.mp4 --preview-dir verify/chroma_key --report work/chroma_key.json --markdown work/chroma_key.md`
  1134. - `prepare` 在默认 15%/50%/85% 时间点各生成 composite 与黑白 matte;检查头发/手/衣物边缘、主体缺口、绿/蓝溢色和背景透视/光色,必要时只改一项 `--similarity / --blend / --despill` 后重新预览
  1135. - 四项均确认后运行 `review --edge-quality pass --subject-integrity pass --spill-control pass --background-fit pass --reviewer ... --note ...`,再运行 `apply --strict` 和 `verify --strict`
  1136. - 图片背景保持,视频背景从第一帧循环且忽略其音轨;最终声音只沿用前景。源/背景/预览/filter/output 任一漂移都会让 live gate 失效
  1137. - 这不是无幕布 AI matting 或逐帧 roto;复杂透明物、反光、幕布皱褶或主体同色应重拍或交给专业 keyer。完整说明见 `docs/prompts/99-chroma-key.md`
  1138. **PIP Overlay 录屏摄像头小窗**(录屏教程可选):
  1139. - 运行 `pip_overlay.py --camera origin/facecam.mp4 --segment "0,18,bottom_right" --segment "18,42,top_right" --sync-offset 0.18 --output work/pip_overlay_plan.json --markdown work/pip_overlay_plan.md`
  1140. - 渲染时追加 `--enrich-plan work/pip_overlay_plan.json`;可和 `screen_focus_plan.json`、`enrich_plan.json` 重复传入
  1141. - 输出 `pip_overlay_plan.v1`,包含 `pip_overlays[]`、每段位置、source_start、sync offset、尺寸比例、透明度和淡入淡出
  1142. - `render_final.py` 会随 `--primary-speed` / `--speed` 同步压缩 camera 小窗时间线,避免变速输出时 PIP 和主画面错位
  1143. **Audio Sync 外录音频自动对齐**(相机内录 + 外录麦克风时推荐):
  1144. - 运行 `audio_sync.py --reference-media origin/camera.mp4 --external-audio origin/lav.wav --output work/audio_sync_plan.json --markdown work/audio_sync_plan.md --replace-output output/camera_lav_synced.mp4 --strict`
  1145. - 输出 `audio_sync_plan.v1`,包含 `alignment.offset_seconds`、`confidence`、`replace_audio.command`、Markdown 复核表和 `summary.blocking`
  1146. - 正数 offset 表示延迟外录音轨;负数 offset 表示裁掉外录音轨开头
  1147. - 确认计划后再加 `--apply` 执行 FFmpeg 替换音轨;脚本会 copy 原视频流、用同步后的外录音轨编码 AAC
  1148. - 如果自动估计低置信度,可用 `--offset 0.18` 这类手动偏移跳过估计;`pipeline_manifest.py` 会拦截低置信度或缺文件的 audio sync artifact
  1149. **Multicam Sync 多机位可逆同步计划**(两台以上设备录制同一事件时推荐):
  1150. - 运行 `multicam_sync.py --reference-media origin/cam-a.mp4 --angle origin/cam-b.mp4 --angle origin/cam-c.mp4 --measure-clock-drift --output work/multicam_sync_plan.json --markdown work/multicam_sync_plan.md --preview-output output/verify/multicam_sync_preview.mp4 --apply-preview --strict`
  1151. - 输出 `multicam_sync_plan.v1`:每路 offset/confidence、自动最响音轨、reference/source coverage、公共 overlap、pairwise 一致性、可选 drift probes/线性 fit 和 preview command
  1152. - 原片不修改、不重编码;只有 `--apply-preview` 会生成短网格预览。正 offset 表示该机位 `t=0` 位于参考时间线更晚的位置
  1153. - 多音轨相机可用 `--audio-stream "origin/cam-b.mp4=2"` 指定有效轨;无音轨/人工拍板用 `--manual-offset "origin/cam-c.mp4=1.24"`
  1154. - 漂移测量默认关闭;启用后默认取 5 个 20 秒窗口,至少 4 个共识 inlier 才拟合 `offset(R)=intercept+slope*R`,报告明确符号的 ppm、测量分辨率、累计漂移、残差和未应用的 `atempo/setpts` advisory factors
  1155. - 漂移证据只覆盖选择的参考/源音轨;不能据此自动断言视频 PTS 或其他音轨共享同一时钟
  1156. - 漂移超阈值或拟合不可靠会进入 review gate;脚本不自动校正,音画必须使用同一仿射映射。未启用时,30 分钟以上仍必须复核头/中/尾
  1157. - 详细使用与边界见 [docs/prompts/76-multicam-sync.md](docs/prompts/76-multicam-sync.md)
  1158. **Audio-guided Multicam Switch 按说话者音频生成导播草稿**(同步通过后可选):
  1159. - 运行 `multicam_switch.py plan --sync-plan work/multicam_sync_plan.json --speaker angle_00_cam-a=主持人 --speaker angle_01_cam-b=嘉宾 --program-audio angle_00_cam-a --delivery output/multicam_switch_draft.mp4 --output work/multicam_switch_plan.json --markdown work/multicam_switch_plan.md --strict`
  1160. - 每路音频分别按 P10 噪声底/P95 峰值归一;只有活动分数和领先 margin 同时达标才换机位,含糊窗口保持上一机位,短于 `--min-shot` 的闪切折回相邻镜头
  1161. - 高相关音频默认按共享混音/强串音阻断;`--allow-correlated-audio` 只保留显式 override warning,不能证明 speaker detection 可靠。广角、节目 master 或没有独立说话者音轨的机位不要映射成 speaker candidate
  1162. - `--program-audio` 指定连续节目声音,不随画面换麦。apply 统一画布/FPS/SAR 后硬切渲染,完成媒体合同与全量解码才提升输出
  1163. - 完整带声 1× 播放后,confirm 必须逐项记录 `speaker_selection / cut_timing / sync / audio_continuity`;源、同步计划、设置、输出或 review 漂移都会使 manifest gate 失效
  1164. - 详细使用与边界见 [docs/prompts/127-multicam-switch.md](docs/prompts/127-multicam-switch.md)
  1165. **Storyboard Plan 分镜与生成路由**(生成素材前推荐):
  1166. - 运行 `storyboard_plan.py --transcript work/transcript.json --clean-script work/clean_script.md --output work/storyboard_plan.json --markdown work/storyboard_plan.md`
  1167. - 输出每个 shot 的时间码、narration、first/motion/last-frame 描述、`codex_imagegen` / `dreamina_video` / `remotion_hyperframes` / `media_library_broll` 路由、fallback 和 continuity anchors
  1168. - 使用生成视频 provider 前先运行 `provider_capability.py verify --bundle work/provider_capabilities.json --max-age-days 30 --strict`,核对 exact UI/API surface、model、mode、画幅、时长、分辨率、参考上限和证据日期
  1169. - 可选运行 `video_prompt_pack.py --storyboard-plan work/storyboard_plan.json --asset-root work --style-reference work/imagegen/style-key.png --capability-profile work/provider_capabilities.json --require-capability-profile --resolution 720p --output work/video_prompt_pack.json --markdown work/video_prompt_pack.md --strict`,把分镜转成 Dreamina/即梦 Seedance、Veo、LTX、Wan、Sora 提示词包、共享 style lock、approval 和 capability gate
  1170. - image-to-video 提交前运行 `reference_frame_preflight.py --prompt-pack work/video_prompt_pack.json --output work/reference_frame_preflight.json --markdown work/reference_frame_preflight.md --require-style-reference --strict`,拦截缺失/损坏/方向冲突/严重画幅冲突参考帧
  1171. - 再运行 `storyboard_assets.py --storyboard-plan work/storyboard_plan.json --asset-root work --media-library . --output work/storyboard_assets.json --markdown work/storyboard_assets.md --strict`,渲染前确认素材 `ready`
  1172. - `dreamina_video` 只表示适合视频生成,不会自动提交任务;提交 Dreamina/即梦前必须确认,因为可能消耗 credits
  1173. - 生图优先使用 Codex 内置 `image_gen` 工具,即 OpenAI GPT Image 2(`gpt-image-2`)。
  1174. **Reference Story Formula 参考片故事公式迁移**(用户要求借鉴参考片情绪机制时运行):
  1175. - 把参考视频和其 timecoded transcript 放进项目,再运行 `reference_story_formula.py prepare --project-dir . --reference-video origin/reference.mp4 --reference-transcript origin/reference_transcript.json --target-storyboard work/storyboard_plan.json --output work/reference_story_formula_request.json --markdown work/reference_story_formula_request.md --response-template work/reference_story_formula_response.json --strict`
  1176. - 完整看参考片并填写每个 beat 的 `mechanism / viewer_state_before / viewer_state_after / trigger / camera_function / transferable_rule / do_not_copy`;每个 reference transcript segment 必须恰好属于一个有序 beat
  1177. - 为目标 storyboard 的每个 shot 填 `beat_id / content_anchor / viewer_shift / surface_change / visual_action`,顺序不能倒退;同时明确排除参考片 pixels、audio、wording、branding 和 specific plot
  1178. - 运行 `audit --request ... --response ... --output work/reference_story_formula.json --markdown work/reference_story_formula.md --strict`,再执行 `verify --report work/reference_story_formula.json --strict`。输入、response 或派生报告漂移会 fail closed;长原文重合进入可见 warning
  1179. - 给 `video_prompt_pack.py` 加 `--reference-story-formula work/reference_story_formula.json`。脚本会 live-verify 与当前 storyboard 的 byte binding,并给每条 prompt 注入对应的结构、目标内容锚点和禁止复制合同。它不证明版权、原创度、留存效果或生成质量。详见 [docs/prompts/125-reference-story-formula.md](docs/prompts/125-reference-story-formula.md)
  1180. **Storyboard Animatic 分镜时长预演**(付费生成或正式剪辑前推荐):
  1181. - 为每个 storyboard shot 准备一张已审静帧,再运行 `storyboard_animatic.py plan --project-dir . --storyboard work/storyboard_plan.json --panel shot_001=work/storyboard/shot_001.png --panel shot_002=work/storyboard/shot_002.png --delivery verify/storyboard_animatic.mp4 --output work/storyboard_animatic.json --markdown work/storyboard_animatic.md`
  1182. - `--panel SHOT_ID=PATH` 必须精确覆盖全部 shots;可选加 `--audio work/narration.wav`。工具绑定 storyboard、panels、音频的 SHA-256 和媒体元数据,按 shot starts 生成带镜头 ID/时间码的 CFR H.264 MP4
  1183. - 执行 `apply` 后完整 1× 播放,检查 `shot_order / timing_rhythm / panel_legibility / visual_continuity / audio_sync`,再运行 `confirm`;无音频时 `audio_sync=not_applicable`
  1184. - `verify --strict` 与 `pipeline_manifest.py --require storyboard_animatic --strict` 会现场重读全部输入、完整解码交付件并核对 review/output 绑定。Animatic 只验证静帧顺序和节奏,后续生成片与成片仍需各自 review。详见 [docs/prompts/121-storyboard-animatic.md](docs/prompts/121-storyboard-animatic.md)
  1185. **Sequence Handoff 生成前镜头接力与剪辑边界**(两条以上生成镜头时推荐):
  1186. - 运行 `sequence_handoff.py prepare --project-dir . --storyboard work/storyboard_plan.json --output work/sequence_handoff_request.json --markdown work/sequence_handoff_request.md --response-template work/sequence_handoff_response.json --strict`
  1187. - 逐相邻镜头复核 `carrier_type / offer_from / receive_in / edit_type / match_requirement`,同时声明 180° 轴、屏幕运动方向、音频桥、头尾 edit handles、风险、fallback 和具体 review note;自动建议只读 storyboard 文本,不能代替人的空间/动作判断
  1188. - 用 `audit --request work/sequence_handoff_request.json --response work/sequence_handoff_response.json --output work/sequence_handoff.json --markdown work/sequence_handoff.md --strict` 生成报告,再以 `verify --report work/sequence_handoff.json --strict` 现场重算;`revise`、缺字段、非法轴线/方向翻转、源分镜或决定漂移都 fail closed
  1189. - 最终 prompt pack 加 `--project-dir . --sequence-handoff work/sequence_handoff.json`;工具会先 live-verify,再将首镜 handoff-out、末镜 receive-in 和中间镜头的双向合同写进对应 provider prompt
  1190. - 文本合同不证明最终像素连续;生成后仍执行 `generated_clip_review.py` 和 `generated_sequence_review.py`,组装后正常速度复核所有边界。详见 [docs/prompts/120-sequence-handoff.md](docs/prompts/120-sequence-handoff.md)
  1191. **Video Prompt Pack + Reference Frame Preflight 视频生成提示词与参考帧门禁**(生成视频前推荐):
  1192. - 先按 [docs/prompts/96-provider-capability.md](docs/prompts/96-provider-capability.md) 建立 `provider_capabilities.json`,再运行 `provider_capability.py verify --bundle work/provider_capabilities.json --max-age-days 30 --strict`;profile 绑定 exact provider/surface/model 和来源,默认超过 30 天就阻塞
  1193. - 运行 `video_prompt_pack.py --project-dir . --storyboard-plan work/storyboard_plan.json --sequence-handoff work/sequence_handoff.json --asset-root work --character "same host" --brand-anchor "palette=charcoal,white,signal yellow" --style-reference work/imagegen/style-key.png --capability-profile work/provider_capabilities.json --require-capability-profile --resolution 720p --output work/video_prompt_pack.json --markdown work/video_prompt_pack.md --strict`
  1194. - 输出 `global.character_sheet_prompt`、`global.style_reference`、`global.sequence_handoff`、`items[].prompt`、`items[].sequence_handoff`、`items[].negative_prompt`、`items[].surface/model/resolution`、`items[].capability_profile`、`items[].capability_issues`、`items[].approval_status` 和 `summary.blocking`
  1195. - `--style-reference` 会把同一 style key 绑定到所有 shot,并在每条 provider prompt 加同一条 `STYLE LOCK`
  1196. - 参考图落盘后运行 `reference_frame_preflight.py --prompt-pack work/video_prompt_pack.json --output work/reference_frame_preflight.json --markdown work/reference_frame_preflight.md --require-style-reference --strict`
  1197. - `reference_frame_preflight.v1` 检查首帧/style key 是否存在、可解码、方向/画幅是否匹配、分辨率是否过低和透明背景;阻塞项接入 `pipeline_manifest.py`
  1198. - `--provider veo|ltx|wan|sora|dreamina_seedance` 可把同一分镜改写成指定模型提示词;`--animate-stills` 会把 `codex_imagegen` 参考图 route 转为 image-to-video 提示词
  1199. - `--strict` 会在 generated-video provider 还没 `--approved`,或 capability profile 缺失/过期/设置越界时返回 2;脚本不提交 provider 任务、不消耗 credits
  1200. - 生图优先使用 Codex 内置 `image_gen` 工具,即 OpenAI GPT Image 2(`gpt-image-2`)。
  1201. **Generation Reference Preflight 图片 / 视频 / 音频生成参考门禁**(使用多模态 reference 时必跑):
  1202. - provider profile 的 `reference_media` 要记录 frame/reference 是否互斥、是否支持 audio-only、总文件数,以及图片/视频/音频的扩展名、字节、单条时长和总时长上限;未核验的限制不得靠猜测补齐
  1203. - 先用 `generation_reference_preflight.py template --project-dir . --prompt-pack work/video_prompt_pack.json --output work/generation_references.json` 建清单;每个实际提交素材填写 `kind / path / role / exclude`,顺序就是各类型的 `@ImageN / @VideoN / @AudioN` 顺序
  1204. - 运行 `generation_reference_preflight.py analyze --project-dir . --prompt-pack work/video_prompt_pack.json --references work/generation_references.json --capability-profile work/provider_capabilities.json --output work/generation_reference_preflight.json --markdown work/generation_reference_preflight.md --strict`
  1205. - 报告会完整解码本地 reference,检查类型、扩展名、大小、单条/合计时长、数量、audio-only、frame/reference 模式互斥和 capability profile 绑定,并输出带明确角色与排除项的 `shots[].provider_prompt`
  1206. - 提交时使用 ready 报告里的有序素材清单和 `provider_prompt`;之后以 `verify --report ... --strict` 或 `pipeline_manifest.py --require generation_reference_preflight --strict` 现场复查。详见 [docs/prompts/122-generation-reference-preflight.md](docs/prompts/122-generation-reference-preflight.md)
  1207. **Generation Task Log 异步生成任务台账**(提交生成任务后推荐):
  1208. - 从 provider 决策生成待审批台账:`generation_task_log.py import-provider-decision --provider-decision work/provider_decision.json --log work/generation_tasks.json --markdown work/generation_tasks.md --strict`
  1209. - Dreamina/即梦提交后必须保存 `submit_id`:`generation_task_log.py add --log work/generation_tasks.json --provider dreamina --task-id <submit_id> --shot-id shot_002 --expected-path work/generated_video/shot_002.mp4 --status submitted`
  1210. - 下载完成后更新本地文件:`generation_task_log.py update --log work/generation_tasks.json --provider dreamina --task-id <submit_id> --status downloaded --asset-path work/generated_video/shot_002.mp4 --markdown work/generation_tasks.md`
  1211. - 输出 `generation_task_log.v1`,包含 `poll_command`、`download_command`、`readiness` 和 `summary.blocking`
  1212. - `completed` 但没有本地 `asset_path` 仍会阻塞;`pipeline_manifest.py` 会自动识别 `generation_tasks.json` 并把未清零任务列为 gate
  1213. **Generated Clip Review 生成视频片段复核**(生成结果下载后、组装前必跑):
  1214. - 先刷新 `storyboard_assets.json`,再运行 `generated_clip_review.py prepare --project-dir . --asset-manifest work/storyboard_assets.json --contact-sheet-dir verify/generated_clips --output work/generated_clip_review_request.json --markdown work/generated_clip_review_request.md --response-template work/generated_clip_review_response.json`
  1215. - reviewer 必须完整执行 1× 带声、0.25×、静音看画面、只听声音四遍检查;contact sheet 只是抽样导航,不能代替播放完整片段
  1216. - response 对每条 clip 记录 identity/wardrobe、action/end state、motion/anatomy/physics、camera、frame integrity、look consistency 六项 1–5 分,以及 hard-fail code、`keep_ranges` / `remove_ranges`、是否重生和具体 `prompt_fix`
  1217. - `pass` 要求加权分 ≥80 且无删段;`pass_with_edits` 要求 ≥65,并由 keep/remove 精确覆盖全片;常识/物理、身份、道具、文字水印、连续性或音画 hard fail 无论总分多高都必须 `fail`
  1218. - 填完 response 后运行 `generated_clip_review.py audit --request work/generated_clip_review_request.json --response work/generated_clip_review_response.json --output work/generated_clip_review.json --markdown work/generated_clip_review.md --strict`;任何 clip/contact sheet 漂移、缺审、非法区间或需重生都会阻塞
  1219. - 组装/发布前再运行 `generated_clip_review.py verify --report work/generated_clip_review.json --strict`,也可用 `pipeline_manifest.py --require generated_clip_review --strict`。reviewer label 不是身份认证或数字签名
  1220. **Generation Chain Handoff 已审生成片末帧接力**(同一场景连续生成时运行):
  1221. - 仅在 `sequence_handoff.v1` 已批准该相邻边界、上一镜 `generated_clip_review.v1` 为 `pass` 或 `pass_with_edits` 时使用;换场、时间跳跃、故意跳切和普通剪辑匹配不要强行接力
  1222. - 运行 `generation_chain_handoff.py prepare --project-dir . --clip-review work/generated_clip_review.json --sequence-handoff work/sequence_handoff.json --boundary boundary_001 --frame-output work/generation_chain/boundary_001_tail.png --output work/generation_chain_handoff.plan.json --markdown work/generation_chain_handoff.plan.md`;脚本枚举 decoded frames,从完整 clip 或最后一个 approved keep range 取确切末帧,并要求源帧/PNG 的 RGB24 像素摘要一致
  1223. - 看完上一镜和 PNG 后执行 `confirm --decision use_exact_start_frame --reviewed-by ... --same-scene-confirmed --tail-frame-accepted --original-anchors-preserved --notes ... --output work/generation_chain_handoff.json --strict`;尾帧不适合时用 `reject` 并返回分镜、生成或普通剪辑边界
  1224. - 提交下一镜前运行 `verify --plan work/generation_chain_handoff.json --strict`,再给 `video_prompt_pack.py` 加 `--generation-chain-handoff work/generation_chain_handoff.json`。目标镜头改为 `image_to_video`,已审末帧成为 exact first frame;prompt 同时保留原角色/产品/style anchors,并限制为一个主动作和一种机位行为
  1225. - 上游报告、clip、批准区间、frame index/PTS、PNG bytes/pixels、人工决定或 canonical artifact ID 漂移都会阻塞;每条新生成片仍需逐片 review,全部完成后再跑跨镜头 review。详见 [docs/prompts/124-generation-chain-handoff.md](docs/prompts/124-generation-chain-handoff.md)
  1226. **Generated Motion Window 生成视频有效运动窗口**(逐片视觉 review 之后、跨镜头组装前运行):
  1227. - contact sheet 可能漏掉 0.25–1 秒的冻结开头或短暂运动;对每条通过视觉复核的生成片运行 `generated_motion_window.py analyze work/generated_video/shot_001.mp4 --project-dir . --output work/generated_motion_window/shot_001.json --markdown work/generated_motion_window/shot_001.md`
  1228. - 脚本用本地 FFmpeg `freezedetect` 保存 `freezes[]` 与其补集 `active_intervals[]`,绑定 source SHA-256、媒体契约、参数和 canonical plan id;刚 analyze 固定阻塞,不能把 detector 建议当批准
  1229. - 完整 1× 播放源片后运行 `confirm ... --decision trim|keep|reject --reviewed-by ... --note ...`。`trim` 默认使用建议区间,也可显式 `--start/--end`;两个边界都必须落在 active interval 内
  1230. - `trim` 在 apply 前继续阻塞;`apply ... --output work/generated_motion_window/shot_001-active.mp4` 只写新 H.264/AAC、`yuv420p` working copy,验证时长/尺寸/fps/音轨并完整解码后才原子提升。原片、计划、检测证据或 output 漂移都会 fail closed
  1231. - 新 working copy 必须重新完整播放,并重跑 generated-clip review、sequence/final QA 和下游审批;`pipeline_manifest.py --require generated_motion_window --strict` 会逐个 live verify `work/generated_motion_window/*.json`。FFmpeg freeze 只衡量全帧相似度,不能判断动作意义、表演、身份、物理或产品质量。详见 [docs/prompts/102-generated-motion-window.md](docs/prompts/102-generated-motion-window.md)
  1232. **Scoped Video Edit Review 局部 AI 视频编辑范围复核**(换装/换背景/换包装/局部 VFX 等 edit mode 后必跑):
  1233. - 每次 provider call 只声明一个确切变化;运行 `scoped_video_edit_review.py prepare --project-dir . --source origin/source.mp4 --edited work/scoped_video_edit.mp4 --change-category wardrobe --change "change only the jacket from blue to red" --preserve subject_identity --preserve performance_motion --preserve camera_motion --preserve framing_composition --preserve source_audio --evidence-dir verify/scoped_video_edit --output work/scoped_video_edit_review_request.json --markdown work/scoped_video_edit_review_request.md --response-template work/scoped_video_edit_review_response.json`
  1234. - `prepare` 绑定原片/编辑结果 SHA-256 与媒体契约,生成范围内 15%/50%/85% 同时间点左右并排 JPEG,以及完整左右并排 H.264 preview;两条输入音轨存在时,preview 把 source/edited 分别保留为独立音轨
  1235. - reviewer 必须分别以 1×、带声完整看原片与编辑结果,再看完整 A/B scope preview;目标变化和每个 `--preserve` 只允许 `pass|fail|not_observable`,不能看不清仍猜 pass
  1236. - `audit --strict` 只在目标确实完成、全部保护项通过、三遍播放确认齐全、时长/尺寸/帧率未漂移时 ready;失败必须写具体 `repair_action`
  1237. - 组装/发布前运行 `verify --report work/scoped_video_edit_review.json --strict`,或 `pipeline_manifest.py --require scoped_video_edit_review --strict`。脚本不调用 provider、不上传素材、不消耗 credits;建议 prompt 是 provider-neutral contract,不能替代当前 surface 的 capability 核验。详见 `docs/prompts/100-scoped-video-edit-review.md`
  1238. **Generated Sequence Review 跨镜头连续性复核**(两条以上生成片段逐片通过后、组装前必跑):
  1239. - 运行 `generated_sequence_review.py prepare --project-dir . --clip-review work/generated_clip_review.json --storyboard-plan work/storyboard_plan.json --evidence-dir verify/generated_sequence --output work/generated_sequence_review_request.json --markdown work/generated_sequence_review_request.md --response-template work/generated_sequence_review_response.json`
  1240. - 脚本按 storyboard 顺序,为每个相邻边界提取批准范围内的上一镜尾帧、下一镜首帧、并排图和“尾部 + 头部”无声 1× preview;如果上游是 `pass_with_edits`,只使用批准的首个/最后一个 keep range
  1241. - 完整查看 preview 和 comparison 后,为 identity/wardrobe、prop state、spatial orientation、action end state、camera framing、lighting/palette 填 `match|intentional_change|mismatch|not_applicable`。至少两项必须真实评估;`mismatch` 必须 `fail`,给 failure code 和具体 `repair_action`
  1242. - 运行 `generated_sequence_review.py audit --request work/generated_sequence_review_request.json --response work/generated_sequence_review_response.json --output work/generated_sequence_review.json --markdown work/generated_sequence_review.md --strict`,组装/发布前再 `verify --report work/generated_sequence_review.json --strict`;clip、上游 review、storyboard 或任一 evidence bytes 漂移都会阻塞
  1243. - `pipeline_manifest.py --require generated_clip_review --require generated_sequence_review --strict` 可把逐片和跨镜头两层都设为门禁。preview 无声,不能替代最终 master 的完整声画复核;reviewer label 和 SHA-256 不是身份认证或签名
  1244. **Generation Lessons 生成视频经验闭环**(可选;只沉淀可泛化且人工明确批准的经验):
  1245. - 从已完成的 `generated_clip_review.json` 选定一条 clip,运行 `generation_lessons.py add --library work/generation_lessons.json --review work/generated_clip_review.json --clip-id shot_002 --category hand_contact --lesson "For hand-to-prop contact, isolate one interaction and keep the hand visible through release." --approved-by "<reviewer-label>" --model seedance-2.0`
  1246. - `add` 会实时重算 canonical review,允许“片段确实需要重生”这一预期 blocker,但拒绝 source/contact-sheet 漂移、漏审、非法 response、stored summary/report-id 篡改;entry 绑定 report/request/clip/contact-sheet SHA-256。`approved_by` 只是审计标签,不是身份认证或签名
  1247. - 复用前运行 `generation_lessons.py verify --library work/generation_lessons.json --strict`;按 provider/model/category 预览可用 `generation_lessons.py select --library work/generation_lessons.json --provider dreamina_seedance --model seedance-2.0 --limit 3 --output work/selected_generation_lessons.json --markdown work/selected_generation_lessons.md`
  1248. - 新证据与旧规则冲突时,不删除旧 entry;新建 lesson 并加 `--supersedes <old-lesson-id>`。旧 evidence 继续留在 library,但只要新 entry 也匹配当前 provider/model/category,`select` 就排除被替代规则
  1249. - 下一次生成提示词包显式加 `video_prompt_pack.py ... --lesson-library work/generation_lessons.json --lesson-model seedance-2.0 --lesson-limit 3`。provider 专属规则优先,未给 `--lesson-model` 时不会误用 model-specific 经验;脚本只追加人工批准的 `lesson`,不会自动把 clip-specific `prompt_fix` 当成通用规则,也不会自动重生或消费 credits
  1250. - 生图优先使用 Codex 内置 `image_gen` 工具,即 OpenAI GPT Image 2(`gpt-image-2`)。
  1251. - 详细说明见 [docs/prompts/89-generated-clip-review.md](docs/prompts/89-generated-clip-review.md)
  1252. **Storyboard Assets 素材清单与预检**(分镜后、渲染前推荐):
  1253. - 运行 `storyboard_assets.py --storyboard-plan work/storyboard_plan.json --asset-root work --media-library . --output work/storyboard_assets.json --markdown work/storyboard_assets.md`
  1254. - 输出每个 shot 的素材状态:`ready` / `candidate_found` / `needs_generation` / `needs_approval` / `needs_render` / `search_needed`
  1255. - 如果传入 `--media-library`,`media_library_broll` shot 会从素材索引里生成 `candidate_paths` + `candidate_scores`,按 tag、文件名、metadata、时长和画幅透明排名
  1256. - 加 `--strict` 时,任何素材未 ready 都会返回退出码 2,适合放在最终渲染前
  1257. - `needs_approval` 代表 Dreamina/即梦等可能消耗 credits 的任务,必须先确认再提交;生图优先使用 Codex 内置 `image_gen` 工具,即 OpenAI GPT Image 2(`gpt-image-2`)。
  1258. **自定义封面**(`cover_image`):
  1259. - 提供自定义封面 PNG 路径,优先于自动生成的封面
  1260. - 尺寸应与视频分辨率匹配(如 1080x1920)
  1261. **持续叠加层**(`video_overlay`):
  1262. - 提供透明 PNG 路径,在封面之后的整个视频上持续叠加显示
  1263. - 适用场景:品牌水印、系列标识(如 DAY 标签、数据指标)等
  1264. - PNG 必须包含 Alpha 通道(RGBA),透明区域不会遮挡视频
  1265. **闪烁圆点**(`rec_blink`):
  1266. - 在视频上叠加一个周期性闪烁的小圆点 PNG(如录像机 REC 标志)
  1267. - `dot_image`:圆点 PNG 路径(建议 12-16px,RGBA 格式)
  1268. - `x`, `y`:圆点在视频画面中的像素坐标
  1269. - `period`:闪烁周期(秒),默认 1.0(0.5 秒亮 + 0.5 秒灭)
  1270. **结尾卡片**(`end_cards`):
  1271. - 在视频末尾追加黑屏文字卡片,每张卡片有 300ms 淡入淡出
  1272. - `text`:卡片文字内容,用 `\n` 换行
  1273. - `duration`:每张卡片显示时长(秒),建议 3.0-4.0
  1274. - 文字居中显示,字号为正文字幕的 1.4 倍
  1275. **口播稳态底噪清理**(`speech_denoise`):
  1276. - 默认 `off`;只有空调、风扇、电流声、轻微房间底噪相对稳定时才启用 `"light"` / `"medium"` / `"strong"`
  1277. - CLI 可用 `--speech-denoise light`;配置已开启时可用 `--no-speech-denoise` 临时关闭
  1278. - 三档固定 80 Hz、2-pole 高通,FFT reduction 为 6/9/12 dB;`strong` 不会超过 12 dB
  1279. - 顺序固定为 `highpass → afftdn → atempo → dynaudnorm → acompressor → loudnorm → cover delay → BGM ducking/mix`
  1280. - 已做 VAD/noise gate、Adobe Podcast、Descript、RX 或机内强降噪的音轨通常保持 off;数字静音、噪声突变、多麦、瞬态敲击/咳嗽和混响必须另行处理
  1281. - 先渲染 10–20 秒 off/light/medium A/B,戴耳机正常速度试听辅音、尾音和停顿;渲染后继续运行 `audio_master_report.py --strict`
  1282. **背景音乐**(`bgm`):
  1283. - 提供背景音乐文件路径(MP3/M4A/WAV 等 FFmpeg 支持的格式)
  1284. - `bgm_volume`:BGM 音量(0.0-1.0),默认 0.15(人声为主,BGM 为辅)
  1285. - `bgm_fade_out`:结尾淡出时长(秒),默认 3.0
  1286. - `bgm_ducking: true` 或 CLI `--bgm-ducking`:用最终旁白轨作为 sidechain,旁白出现时自动压低 BGM;封面、停顿和片尾无旁白时音乐会自然恢复
  1287. - 默认 ducking 参数是 threshold `0.03`、ratio `8`、attack `20ms`、release `500ms`;只有试听或 `audio_master_report.py` 证据表明需要时才调整
  1288. - ducking 分支用 `amix normalize=0` 保留人声响度,并在混音末尾加 `alimiter=0.95` 防止峰值溢出;旧配置默认仍关闭,保持已有输出兼容
  1289. - BGM 自动循环播放直到视频结束,不需要预先剪辑长度
  1290. - 推荐免费可商用音乐源:Pixabay Music、Mixkit、YouTube Audio Library
  1291. - 选曲建议:口播/教程用轻柔纯音乐(无人声),节奏不要太强,避免抢人声
  1292. **字幕风格预设**(`subtitle_style`):
  1293. | 风格 | 效果 | 适用场景 |
  1294. |------|------|---------|
  1295. | `normal` | 白字黑描边(默认) | 适合所有场景 |
  1296. | `karaoke` | 逐词高亮 | 音乐/节奏感内容 |
  1297. | `bold_pop` | 粗描边高对比 | MrBeast/Hormozi 风格 |
  1298. | `pop_in` | 每条字幕入场缩放后回弹 | 节奏较快的短视频;短于 0.3 秒的字幕保持静态 |
  1299. | `neon` | 霓虹灯青紫色 | 科技/潮流内容 |
  1300. | `minimal` | 极简无描边 | 文艺/安静内容 |
  1301. | `yellow_pop` | 黄字黑描边 | 高可见度,户外/嘈杂画面 |
  1302. **卡拉OK字幕 / 逐词高亮**(`subtitle_style: "karaoke"`):
  1303. - 在 config 中设置 `"subtitle_style": "karaoke"` 启用逐词高亮字幕
  1304. - 需要先用 `--word-timestamps` 参数进行语音识别,获取逐词时间戳
  1305. - `subtitle_highlight_color`:当前词高亮颜色,默认 `"#FFFF00"`(黄色)
  1306. - `subtitle_base_color`:未说到的词底色,默认 `"#FFFFFF"`(白色)
  1307. - `subtitle_base_alpha`:底色透明度 hex,默认 `"80"`(半透明)
  1308. - 如果 transcript 中没有 word 级时间戳,会自动回退到按字符均匀分布(效果稍差)
  1309. - 也可通过 CLI 参数 `--subtitle-style karaoke` 覆盖 config
  1310. - 典型工作流:
  1311. ```bash
  1312. # 1. 转录时开启逐词时间戳
  1313. python3 scripts/transcribe.py audio.wav --model auto --language zh --word-timestamps
  1314. # 2. 渲染时选择 karaoke 字幕风格
  1315. python3 scripts/render_final.py --config render_config.json --output final.mp4 --subtitle-style karaoke
  1316. ```
  1317. **逐条弹入字幕**(`subtitle_style: "pop_in"`):用 `render_final.py --subtitle-style pop_in`,或在 render config 中设 `"subtitle_style": "pop_in"`。每条字幕按成片速度后的时长独立做 80% → 108% → 100% 缩放;短于 0.3 秒的字幕直接全尺寸显示。`subtitle_style_preview.py --styles pop_in` 的静帧只能检查最终字形、位置和对比度,须在最终 MP4 中按正常速度检查入场动画及安全区。
  1318. **音频源替代(M4A/独立音频)**:
  1319. - 如果有独立录制的音频文件(M4A 等),可先用 ffmpeg 转为带黑屏视频轨的 MP4:
  1320. ```bash
  1321. ffmpeg -f lavfi -i "color=c=black:s=1080x1920:r=30:d=60" -i audio.m4a -c:v libx264 -c:a aac -shortest audio.mp4
  1322. ```
  1323. - 然后在 clip 中用 `"video": "audio.mp4"` 提供音频源,用 `"broll"` 提供画面
  1324. - 这样可以将补录的配音与任意画面组合
  1325. **封面标题**:
  1326. 1. 如果用户提供了标题,直接使用。
  1327. 2. 如果用户没有特别要求,**站在观众角度**总结一个吸引人的标题(6-15 个字)。
  1328. 3. `subtitle` 可选,用于补充情感钩子或关键信息。
  1329. 4. **移动端优先**:封面在手机列表页里只是一个缩略图,标题必须先保证可读性,再考虑画面细节。
  1330. **封面文字排版规则**:
  1331. - 标题按**一行最多约 8 个汉字**来设计;超过时自动换行,不要把单行塞得过满。
  1332. - 英文/数字按**约半个汉字宽度**估算;例如 `AI`、`GPT-5` 之类不应把整行宽度挤爆。
  1333. - `subtitle` 字号默认按标题的**约 50%** 处理,只承担补充信息,不和主标题争抢视觉中心。
  1334. - 如果标题超过两行,优先**缩短文案**,不要继续缩小字号来硬塞。
  1335. - 做教程/工具类封面时,主标题尽量控制在 **4-8 个字**,副标题控制在 **6-12 个字**。
  1336. **封面风格**(`cover_style`)— 根据视频内容选择最合适的风格:
  1337. | 风格 | 适用场景 | 视觉效果 |
  1338. |------|---------|---------|
  1339. | `bold` | 教程、科普、技术 | 黑底 + 大号白色粗体字,简洁有力 |
  1340. | `news` | 热点、观点、争议 | 深色渐变底 + 白色标题 + 黄色副标题,冲击力强 |
  1341. | `frame` | Vlog、实拍、场景 | 视频首帧做背景 + 暗色遮罩 + 描边白字 |
  1342. | `gradient` | 生活、情感、艺术 | 紫粉渐变底 + 发光白字,温柔优雅 |
  1343. | `minimal` | 思考、文化、深度 | 纯黑底 + 细体白字,极简克制 |
  1344. | `white` | 教程、产品、品牌化内容 | 纯白底 + 深色字,现代感更强 |
  1345. | `techcard` | 屏幕录制、软件教程、AI 工具演示 | 左侧大标题 + 右侧画面卡片,兼顾信息量和可读性 |
  1346. AI agent 应根据视频主题和内容语气自动选择:
  1347. - 科技/工具类 → `bold` 或 `news`
  1348. - 争议/观点类 → `news`(白标题+黄副标题效果最抢眼)
  1349. - Vlog/实拍类 → `frame`
  1350. - 情感/生活类 → `gradient`
  1351. - 深度/文化类 → `minimal`
  1352. - 纯桌面录屏 / 软件教程 → `techcard` 优先;如果画面太杂,就退回 `bold` / `white`
  1353. **背景取帧规则**:
  1354. - 不要机械地使用第一帧。对于录屏教程,优先选择**信息密度更高**、界面更完整的一帧做背景或卡片图。
  1355. - 如果背景画面会影响标题识别,优先使用 `bold` / `white` / `minimal` 这类纯底风格。
  1356. - 单独预览封面时,可用 `scripts/generate_cover_image.py --frame-timestamp 00:10:00` 指定取帧时间。
  1357. **多封面 A/B 方案与最终选择**:
  1358. ```bash
  1359. python3 scripts/cover_variants.py output/final_xhs.mp4 \
  1360. --title "20分钟出片" \
  1361. --subtitle "AI剪辑完整流程" \
  1362. --caption output/caption.json \
  1363. --platform xhs \
  1364. --frame-timestamp 12.5 \
  1365. --output-dir output/covers \
  1366. --render \
  1367. --output work/cover_variants.json \
  1368. --markdown work/cover_variants.md
  1369. ```
  1370. 默认产出 3 套方案和 `*_preview.png` 小图。先按 feed-size 预览比较,再重跑并加 `--select cover-c --require-selection --strict` 记录最终封面。标题负责主题/关键词,封面负责结果/情绪/反差/证据;需要强制不重复时加 `--require-distinct-cover-text`。`pipeline_manifest.py --require cover_variants` 可把选择设为发布 gate。若需要 AI 生成或编辑封面底图,生图优先使用 Codex 内置 `image_gen` 工具,即 OpenAI GPT Image 2(`gpt-image-2`)。
  1371. **封面时长**(`cover_duration`):
  1372. - 默认 2.0 秒,将第一帧冻结并叠加封面
  1373. - 也可通过 `--cover-duration` 命令行参数覆盖
  1374. **章节划分**:
  1375. - 根据视频内容逻辑划分章节,建议 **不超过 4 个章节**
  1376. - 章节名要**简短**(2-4 个字),如:痛点、原因、方案、工具
  1377. - 章节时间需要根据选定片段的累计时长精确计算
  1378. ### Phase 4.8: Edit Revision(剪辑 artifact 可逆修订,可选)
  1379. 当用户要求修改 `render_config.json`、`enrich_plan.json`、caption 或字幕 sidecar,同时需要完整审稿、依赖防漂移和 undo/redo 时,先准备 proposal:
  1380. ```bash
  1381. python3 scripts/edit_revision.py prepare \
  1382. --project-dir . \
  1383. --artifact work/render_config.json \
  1384. --artifact work/enrich_plan.json \
  1385. --depends-on work/transcript_reviewed.json \
  1386. --title "收紧开头并调整 B-roll" \
  1387. --reason "已完成时间码审片,采用第二版开头。" \
  1388. --output work/edit_revision_proposal.json
  1389. ```
  1390. 只改 proposal 的 `artifacts[].proposed_content`,再运行 `audit`。合法 audit 的 `pending_approval` 在 `--strict` 下返回 2 是预期人工 gate;必须另存绑定相同 `review_id`、`decision: approve` 和非空 `approved_by_label` 的 approval JSON,`apply` 才会把多个文件作为一个 revision 成组写入并创建 `work/edit_revision_history.json`。运行期写入错误会尝试恢复旧 bytes,但跨文件不承诺操作系统级原子提交;进程异常后先跑 `status --strict`。status 会实时检查 artifact、已应用 dependency 和 content-addressed before/after blobs;外部手改、依赖漂移、symlink 或 blob 损坏时拒绝 undo/redo。原始媒体、代码、输出成片和 `verify/` 不在管理范围。详细流程见 [docs/prompts/80-edit-revision.md](docs/prompts/80-edit-revision.md)。
  1391. ### Phase 4.85: Portable Edit Recipe(可移植剪辑配方,可选)
  1392. 当用户要把已审 `render_config.json` 保存为模板,或换一批素材复刻同一时间线/字幕/BGM/overlay 结构时,先导出无路径 recipe:
  1393. ```bash
  1394. python3 scripts/edit_recipe.py export \
  1395. --config work/render_config.json \
  1396. --name fast-tech-explainer \
  1397. --description "快节奏科技口播" \
  1398. --output work/recipes/fast-tech-explainer_edit_recipe.json \
  1399. --markdown work/recipes/fast-tech-explainer_edit_recipe.md
  1400. ```
  1401. 导出前必须通过 source preflight;本地文件引用会变成 typed slots,同一路径只占一个槽位,recipe 不保存原路径。新项目打开 Markdown slot 表,为每槽各传一次 `--bind SLOT=PATH` 运行 `replay`,同时写 `--receipt` 和 `--markdown`;脚本会验证 portable digest、槽位集合、文件类型与存在性,记录新 binding hash,并对输出 config 再跑 preflight。默认不覆盖,只有明确目标正确时加 `--force`。recipe hash 不是签名或人工批准;回放后仍必须渲染并看完整成片。详细流程见 [docs/prompts/82-edit-recipe.md](docs/prompts/82-edit-recipe.md)。
  1402. ### Phase 4.9: Platform Safe Area QA(平台 UI 安全区门禁)
  1403. 在渲染或多平台导出前,按目标平台分别检查字幕、强调 badge、PIP 人像、CTA、章节卡和点击 marker 是否会进入顶部状态栏、底部文案区或右侧互动按钮栏:
  1404. ```bash
  1405. python3 scripts/platform_safe_area_qa.py \
  1406. --config work/render_config.json \
  1407. --enrich-plan work/enrich_plan.json \
  1408. --platform xhs \
  1409. --output verify/xhs_platform_safe_area_qa.json \
  1410. --markdown verify/xhs_platform_safe_area_qa.md \
  1411. --guide verify/xhs_platform_safe_area_guide.svg \
  1412. --strict
  1413. ```
  1414. 抖音和视频号派生版分别改用 `--platform douyin` / `--platform wxch`。脚本按 `render_final.py` 的默认 ASS、PIP 和 focus-marker 几何规则估算 bbox;renderer 之外的 CTA/Logo 可以通过 `--elements custom_elements.json` 提供像素或 normalized bbox。平台 App UI 变化时用 `--safe-left` / `--safe-top` / `--safe-right` / `--safe-bottom` 覆盖实测边距。
  1415. 这是本地、可审计的 layout gate:不上传、不调用 LLM、不做 OCR,不推断生成图或封面内部的主体/文字位置。已有整图章节卡会标记 `uncheckable`,需要打开 SVG guide 或渲染帧人工复核。`summary.blocking > 0` 会让 `--strict` 返回 2;需要设为生产线必需项时用 `pipeline_manifest.py --require platform_safe_area_qa --strict`。
  1416. ### Phase 4.95: Subtitle Style Preview(真实画面字幕样式预览)
  1417. 最终编码前先把真实 ASS 预设渲染到源片早/中/晚代表帧:
  1418. ```bash
  1419. python3 scripts/subtitle_style_preview.py create \
  1420. --project-dir . \
  1421. --video origin/talking.mp4 \
  1422. --platform xhs \
  1423. --text "这句字幕要覆盖中英文和数字 2026" \
  1424. --preview-dir verify/subtitle_styles \
  1425. --output work/subtitle_style_preview.json \
  1426. --markdown work/subtitle_style_preview.md \
  1427. --require-selection
  1428. python3 scripts/subtitle_style_preview.py select \
  1429. --report work/subtitle_style_preview.json \
  1430. --style normal
  1431. python3 scripts/subtitle_style_preview.py verify \
  1432. --report work/subtitle_style_preview.json \
  1433. --strict
  1434. ```
  1435. 默认比较 `normal` / `minimal` / `bold_pop`,并使用 `render_final.py` 的同一 ASS builder、字体、字号和目标画幅中心裁切。手机尺寸与全尺寸都要看;确认后把所选值传给 `render_final.py --subtitle-style`。源片、字体、样式定义或 JPEG bytes 变化会让旧选择失效。`karaoke` 预览只证明视觉样式,真实逐词节奏仍取决于词级时间戳;最终还要跑 safe-area、readability QA 和 1× 成片审片。详见 [docs/prompts/94-subtitle-style-preview.md](docs/prompts/94-subtitle-style-preview.md)。
  1436. ### Phase 5: Single-Pass Render(单次渲染)
  1437. 使用 [render_final.py](./scripts/render_final.py) 从原始视频**一次编码**生成最终视频:
  1438. ```bash
  1439. # 如没有在 Phase 0.25 生成 profile,删去 --style-profile。
  1440. python3 scripts/render_final.py --config render_config.json \
  1441. --style-profile work/edit_style_profile.json \
  1442. --enrich-plan work/enrich_plan.json \
  1443. --output final.mp4 --speed 1.25 1.5
  1444. ```
  1445. **核心原理**:
  1446. - **单视频**(最常见场景):使用 `select/aselect` + `between()` 表达式一次性筛选所有保留片段,FFmpeg 解码完整源视频但只编码选中的帧,配合 `-crf 18 -preset medium` 只编码一次
  1447. - **多视频混剪**:使用 `trim/atrim` 裁切 + `concat` 拼接(自动降级)
  1448. - 封面使用 `tpad` 冻结第一帧 + `adelay` 添加静音,字幕时间自动偏移,全部在**一次编码**中完成
  1449. - 章节时间轴不烧入视频,渲染完成后以文本形式输出,供用户手动粘贴到小红书等平台
  1450. 参数说明:
  1451. - `--config`:渲染配置 JSON 路径
  1452. - `--style-profile`:可选,验证后仅填充 config 中缺失的个人/品牌风格默认值
  1453. - `--enrich-plan`:可选,读取 `auto_enrich.py` 输出的 JSON,把 B-roll / 章节卡 / 贴纸 / 强调点 / 已生成图片 cue 自动接回渲染
  1454. - `--output`:输出文件路径
  1455. - `--speed 1.25 1.5`:同时输出变速版本(每个变速版本也是从原始视频直接编码,不是从已编码视频二次压缩)
  1456. - `--cover-duration 2.0`:封面冻结时长(秒),覆盖配置中的 `cover_duration`
  1457. - `--font-path`:自定义字体文件
  1458. - `--font-size`:字幕字号(默认 120,即竖屏宽度 1080 ÷ 9 = 120,每个汉字占屏幕宽度的 1/9,基于实际分辨率自动缩放)
  1459. - `--no-subtitles`、`--no-cover`:跳过对应功能
  1460. **输出**:
  1461. - `final.mp4`(原速)
  1462. - `final_1_25x.mp4`(1.25 倍速)
  1463. - `final_1_5x.mp4`(1.5 倍速)
  1464. - 渲染完成后终端输出章节时间轴文本,可直接复制到小红书
  1465. **多平台格式导出**:
  1466. ```bash
  1467. python3 scripts/render_final.py --config render_config.json --output final.mp4 \
  1468. --formats vertical square horizontal
  1469. ```
  1470. 同时输出:
  1471. - `final_vertical.mp4`(9:16 抖音/小红书/TikTok)
  1472. - `final_square.mp4`(1:1 Instagram)
  1473. - `final_horizontal.mp4`(16:9 YouTube/B站)
  1474. 裁切策略为中心裁切(center-crop),保持画面主体不变。
  1475. **自动功能**:
  1476. - 字幕自动检测语言、自动折行、竖屏优化定位
  1477. - 封面自动叠加标题文字(带描边和阴影),冻结首帧 1-2 秒
  1478. - 变速版本的字幕时间自动缩放
  1479. - B-roll 自动缩放裁切匹配主视频分辨率
  1480. - `--enrich-plan` 的定时 B-roll / image overlay 自动缩放裁切匹配主视频分辨率
  1481. - 结尾卡片自动拼接黑帧 + 静音 + 淡入淡出字幕
  1482. - 持续叠加层和闪烁圆点在封面之后自动启用
  1483. - 视频/音频时长自动对齐(`-shortest`),避免平台上传时的时长不匹配问题
  1484. ### Phase 5b: Export to JianYing / CapCut(导出剪映工程)
  1485. 如果用户希望在剪映中继续编辑(添加特效、调色、精修转场等),可以将剪辑方案**直接导出为剪映工程文件**,无需 ffmpeg 渲染:
  1486. ```bash
  1487. python3 scripts/export_capcut.py --config render_config.json --output ./my_draft
  1488. ```
  1489. **导出内容**:
  1490. - **视频轨道**:所有选定的片段按顺序排列在主视频轨道上,包含片头封面(冻结首帧或自定义封面图)
  1491. - **字幕轨道**:每个片段的转录文字作为独立字幕段落,位于画面下方
  1492. - **文字轨道**:封面标题、副标题、结尾卡片文字(与字幕分离,便于单独编辑)
  1493. - **音频轨道**:背景音乐(BGM),自动设置音量
  1494. - **转场**:片段之间自动添加淡入淡出转场(300ms)
  1495. - **B-roll**:支持 B-roll 替换画面(使用 broll 路径作为视频源)
  1496. 参数说明:
  1497. - `--config`:渲染配置 JSON 路径(与 render_final.py 共用同一个 render_config.json)
  1498. - `--output`:输出文件夹路径(会创建 draft_content.json 和 draft_meta_info.json)
  1499. - `--name`:项目名称(默认使用配置中的标题)
  1500. **使用方式**:
  1501. 1. 将导出的文件夹复制到剪映草稿目录:
  1502. - macOS: `~/Movies/JianyingPro/User Data/Projects/com.lveditor.draft/`
  1503. - Windows: `%APPDATA%/JianyingPro/User Data/Projects/com.lveditor.draft/`
  1504. 2. 打开剪映,在"草稿"列表中即可看到该项目
  1505. 3. 在剪映中可继续添加特效、调整转场、调色、导出等
  1506. **注意**:
  1507. - 导出的工程文件使用**绝对路径**引用视频/音频素材,确保素材文件不要移动位置
  1508. - 支持剪映专业版(JianyingPro);剪映 6+ 版本均可打开生成的草稿
  1509. - 此功能与 Phase 5(ffmpeg 渲染)**二选一**:如果用户只需要最终视频,用 render_final.py;如果需要进一步在剪映中编辑,用 export_capcut.py
  1510. 如果字幕已经在剪映/CapCut 里用 Auto Captions 生成并人工校对过,可以反向导入为本项目 transcript:
  1511. ```bash
  1512. python3 scripts/import_capcut_subtitles.py \
  1513. --draft ~/Movies/JianyingPro/User\ Data/Projects/com.lveditor.draft/day58 \
  1514. --transcript work/capcut_transcript.json \
  1515. --cut-list work/capcut_gap_cut.json \
  1516. --markdown work/capcut_subtitles.md \
  1517. --source-media origin/talking.mp4
  1518. ```
  1519. 也可以导入剪映导出的 SRT:
  1520. ```bash
  1521. python3 scripts/import_capcut_subtitles.py \
  1522. --srt exports/capcut_auto_captions.srt \
  1523. --transcript work/capcut_transcript.json \
  1524. --srt-output output/subtitles/capcut_clean.srt
  1525. ```
  1526. `--cut-list` 用字幕间隙生成 `keep_segments`,适合先用 `timeline_view.py --cut-list` 复核,再交给 `export_edl.py` 或后续粗剪流程。默认只读取 subtitle 材料;如果草稿把自动字幕存为普通文字轨,再加 `--include-overlays`。
  1527. 如果已经有 SRT 和人工/agent 写好的字幕编号编辑意见,用 `srt_edit_plan.py` 直接生成可复核剪辑方案:
  1528. `work/edit_guide.md` 示例:
  1529. ```md
  1530. title: 发布会高光
  1531. platform: xhs
  1532. keep 3-5: 先用产品发布和用户反应
  1533. drop 1-2: 铺垫太慢
  1534. keep 8: 补一句核心结论
  1535. ```
  1536. ```bash
  1537. python3 scripts/srt_edit_plan.py \
  1538. --srt exports/capcut_auto_captions.srt \
  1539. --guide work/edit_guide.md \
  1540. --source-media origin/talking.mp4 \
  1541. --output work/srt_edit_plan.json \
  1542. --render-config work/render_config.json \
  1543. --cut-list work/srt_edit_cut.json \
  1544. --markdown work/srt_edit_plan.md \
  1545. --strict
  1546. ```
  1547. `keep/include/use/select` 行按出现顺序生成最终输出顺序;`drop/skip/exclude/remove` 行写入 review。`--cut-list` 输出按原素材时间排序,适合 `timeline_view.py --cut-list` 看切点;真正的重排序输出看 `--render-config`。需要强制每个字幕编号都被审过时,加 `--require-all-reviewed --strict`。
  1548. ### Phase 5c: NLE Handoff EDL / FCPXML / OTIO(交给 Premiere / FCP / Resolve)
  1549. 如果用户不需要剪映草稿,而是要把自动剪辑方案交给专业剪辑软件做调色、混音、精剪或协作复核,可导出单轨 EDL、单 spine FCPXML 或 OpenTimelineIO `.otio`:
  1550. ```bash
  1551. python3 scripts/export_edl.py --config render_config.json --output work/edit.edl --fps 30
  1552. python3 scripts/export_edl.py --cut-list work/rough_cut.json --output work/rough_cut.edl --fps 30
  1553. python3 scripts/export_fcpxml.py --config render_config.json --output work/edit.fcpxml --fps 30 --width 1080 --height 1920
  1554. python3 scripts/export_fcpxml.py --cut-list work/rough_cut.json --output work/rough_cut.fcpxml --fps 30
  1555. python3 scripts/export_otio.py --config render_config.json --output work/edit.otio --fps 30
  1556. python3 scripts/export_otio.py --cut-list work/rough_cut.json --output work/rough_cut.otio --fps 30
  1557. ```
  1558. `export_edl.py` / `export_fcpxml.py` / `export_otio.py` 都会同时写 `<output>.json` manifest,保留绝对源路径、精确秒数、record/source timecode 和事件清单。`export_otio.py` 默认写 V1 + A1 两条 track,可用 `--no-audio-track` 只交接视频;复杂字幕、overlay、章节卡、B-roll 仍以 `render_final.py` / `export_capcut.py` 为准;NLE handoff 只负责轻量选段时间线。
  1559. ### Phase 5d: Final Audio Storyboard(视觉 EDL 锁定后重建声音)
  1560. 多段生成视频或连续短片先锁定视觉 EDL,再按最终 record timeline 重建旁白、对白、环境声、Foley 与音乐;不要把剪辑前整片 audio plan 原样套回删短画面。EDL 每个 event 的 label 应对应 `storyboard_plan.json` 的 shot id:
  1561. ```bash
  1562. python3 scripts/export_edl.py \
  1563. --config work/render_config.json \
  1564. --output work/locked_visual.edl \
  1565. --manifest work/locked_visual.edl.json \
  1566. --fps 30
  1567. python3 scripts/final_audio_storyboard.py prepare \
  1568. --project-dir . \
  1569. --edl work/locked_visual.edl.json \
  1570. --storyboard work/storyboard_plan.json \
  1571. --output work/final_audio_storyboard_request.json \
  1572. --markdown work/final_audio_storyboard_request.md \
  1573. --response-template work/final_audio_storyboard_response.json \
  1574. --strict
  1575. # 填完 response 后:
  1576. python3 scripts/final_audio_storyboard.py audit \
  1577. --project-dir . \
  1578. --request work/final_audio_storyboard_request.json \
  1579. --response work/final_audio_storyboard_response.json \
  1580. --output work/final_audio_storyboard.json \
  1581. --markdown work/final_audio_storyboard.md \
  1582. --strict
  1583. python3 scripts/final_audio_storyboard.py verify \
  1584. --project-dir . \
  1585. --report work/final_audio_storyboard.json \
  1586. --strict
  1587. ```
  1588. 每个 final section 必须明确 `single_track / sectioned_tracks / stems`、shared tone、voice、sound、music、stems 与原生声音保留理由;每个完全删除的 story beat 必须选择 `remove / rewrite_into_adjacent / offscreen_bridge`。重复 voiced line、漏审、时间映射或输入/response/report 漂移 fail closed。脚本不生成音频、不提交 provider、不消耗 credits;批准 JSON 仍要按实际音频工具改写成 timed cue sheet,付费生成前另行确认。详见 [docs/prompts/95-final-audio-storyboard.md](docs/prompts/95-final-audio-storyboard.md)。
  1589. 如果最终旁白由多次 TTS、分段录音或逐句后处理拼成,在混入 BGM/SFX 前对**最终独立旁白音轨**逐短语测量:
  1590. ```bash
  1591. python3 scripts/narration_loudness_qa.py analyze work/final_narration.wav \
  1592. --segments work/final_narration_segments.json \
  1593. --project-dir . \
  1594. --output verify/narration_loudness_qa.json \
  1595. --markdown verify/narration_loudness_qa.md \
  1596. --strict
  1597. python3 scripts/narration_loudness_qa.py verify \
  1598. --report verify/narration_loudness_qa.json \
  1599. --project-dir . \
  1600. --strict
  1601. ```
  1602. 默认每段目标 `-18 LUFS ±2 LU`、非例外段 spread `≤1 LU`、true peak `≤-2 dBTP`、LRA `≤5 LU`。创意例外必须逐段写 `reason + reviewer`,且不能绕过 peak ceiling;至少保留两段非例外短语才能判断 spread。报告绑定旁白、segment manifest、媒体契约、算法和现场复测。它不评判音色、发音、呼吸、接缝或表演,也不替代混音后 `audio_master_report.py` 的全片 `-16 LUFS` 检查。详见 [docs/prompts/105-narration-loudness-qa.md](docs/prompts/105-narration-loudness-qa.md)。
  1603. ### Phase 6: Post-render Validation(渲染后验证)
  1604. 渲染完成后,对最终视频执行验证流程:
  1605. **6a. 机器质检(先跑)**:
  1606. ```bash
  1607. python3 scripts/render_qa.py final.mp4 \
  1608. --platform douyin \
  1609. --json final_qa.json \
  1610. --review-dir verify/final_qa \
  1611. --review-clips
  1612. ```
  1613. `render_qa.py` 会检查容器元数据、平台尺寸、视频/音频流、黑屏、长静帧和长静音。对小红书派生文件使用 `--platform xhs`,对抖音/视频号使用 `--platform douyin` 或 `--platform wxch`。`--review-dir` 会写 `render_qa_review.json` / `.md`,`--review-clips` 会为可疑区间抽取短 MP4;如果只想快速查元数据,可加 `--no-filters`。
  1614. **6a00. 最终音视频轨覆盖(master 和每个重要平台版必跑)**:
  1615. ```bash
  1616. python3 scripts/stream_coverage_qa.py analyze final.mp4 \
  1617. --project-dir . \
  1618. --output verify/stream_coverage_qa.json \
  1619. --markdown verify/stream_coverage_qa.md \
  1620. --strict
  1621. python3 scripts/stream_coverage_qa.py verify \
  1622. --report verify/stream_coverage_qa.json \
  1623. --project-dir . --strict
  1624. ```
  1625. 该门禁完整解码成片,并对首条视频/音频流分别统计 decoded frame count、首帧 PTS、尾帧结束时间和 timeline digest;默认阻断音视频首尾偏移或各流未覆盖容器时间线。render plan 有确切时长/帧数时追加 `--expected-duration`、`--expected-video-frames`。AAC priming/discard 不使用 `nb_frames` 作硬门禁,视频帧数仍会核对。报告通过后完整 1× 播放确切交付文件。详见 [docs/prompts/114-stream-coverage-qa.md](docs/prompts/114-stream-coverage-qa.md)。
  1626. **6a0. 同时间线重编码画质(压缩 / 转码衍生件必跑)**:
  1627. ```bash
  1628. python3 scripts/encode_quality_qa.py analyze output/master.mp4 output/final_delivery.mp4 \
  1629. --project-dir . \
  1630. --output verify/encode_quality_qa.json \
  1631. --markdown verify/encode_quality_qa.md \
  1632. --strict
  1633. python3 scripts/encode_quality_qa.py verify \
  1634. --report verify/encode_quality_qa.json --project-dir . --strict
  1635. ```
  1636. 仅在 reference/candidate 保持同一时间线和同一构图时使用;fps 差超过 `0.01`、时长差超过 1 帧或显示画幅不同会直接拒绝。默认 mean SSIM `≥0.95`、P05 SSIM `≥0.88`、有限帧 mean PSNR `≥35 dB`;候选分辨率不同但画幅一致时才 Lanczos 归一并 WARN。按 Markdown 最差帧时间码 A/B 查看并完整 1× 播放,不能把指标当成人工画质批准。它不测音频,也不适用于 crop/grade/HDR/retime/interpolation;本实现不调用 `libvmaf`,不声称 VMAF。`pipeline_manifest.py --require encode_quality_qa --strict` 可设为发布 gate。详见 [docs/prompts/107-encode-quality-qa.md](docs/prompts/107-encode-quality-qa.md)。
  1637. **6a1. 音频声道完整性(最终 master 和重要平台版必跑)**:
  1638. ```bash
  1639. python3 scripts/audio_channel_qa.py analyze final.mp4 \
  1640. --project-dir . \
  1641. --output verify/audio_channel_qa.json \
  1642. --markdown verify/audio_channel_qa.md \
  1643. --strict
  1644. python3 scripts/audio_channel_qa.py verify \
  1645. --report verify/audio_channel_qa.json \
  1646. --project-dir . \
  1647. --strict
  1648. ```
  1649. `audio_channel_qa.py` 用本地 FFmpeg 固定窗口测量左右声道活动、起始偏移、能量平衡、相位相关和 mono fold-down 能量损失。mono 直接通过声道专项;stereo 会现场测量;多声道要求先定义明确 downmix。它不改音频,也不替代完整 1× stereo/mono 试听、`audio_master_report.py` 的响度/爆峰检查或同步复核。详见 [docs/prompts/106-audio-channel-qa.md](docs/prompts/106-audio-channel-qa.md)。
  1650. **6a2. 短促音频掉点(最终独立人声优先)**:
  1651. ```bash
  1652. python3 scripts/audio_dropout_qa.py analyze work/final_narration.wav \
  1653. --project-dir . \
  1654. --evidence-dir verify/audio_dropout_clips \
  1655. --output verify/audio_dropout_qa_scan.json \
  1656. --markdown verify/audio_dropout_qa_scan.md \
  1657. --response-template verify/audio_dropout_qa_response.json \
  1658. --strict
  1659. ```

Lines 2,001–2,893 are not shown. The link to the file on GitHub has every line.

README.md · README · 2,891 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Video Editing Skill — 视频剪辑技能
  2. 这是一个面向 **口播、教程、访谈、播客切片、录屏演示 / facecam demo** 的 AI 视频剪辑生产线:给它原始口播音频/视频、transcript、B-roll、摄像头小窗或素材目录,它可以把“还没整理的素材”推进到 **可发布的小红书 / 抖音 / 视频号短视频**。
  3. 它提供一条完整工作流:**项目启动/素材导入 → 本机工具链能力预检 → 交错/telecine 检测与逐行工作副本 → 手机/录屏 VFR 时基归一 → 静音首尾黑场裁切与边界复核 → 短素材 hard repeat 或端帧去重正放/倒放循环 → 多源片段归一拼接与全接缝复核 → 多机位同步与按说话者音频生成导播草稿 → 个人/品牌剪辑风格 → 生产授权 → 手持防抖 / 绿蓝幕换背景 → 转写 → 长视频择段 → 清稿 → 去口头禅/停顿 / 多模态死区 → 重组故事 → 事实来源 proof deck → 分镜 → 分镜静帧时长预演 → 生成前逐镜接力与剪辑边界审核 → B-roll/生图/生成视频规划 → 图片/视频/音频生成参考素材预检与角色绑定 → 生成片有效运动窗口 → 字幕与声音设计 → BGM/SFX cue 规划与 source-bound 音效单轨混音 → BGM 卡点 / 局部 speed ramp / 关键帧 freeze-punch / J-cut/L-cut → 可逆剪辑修订 / 可移植剪辑配方 → 锁定视觉 EDL 后重建最终声音分镜 → 最终旁白逐短语响度门禁 → 渲染前预检 / 真实画面字幕样式选择 / 字幕逐字符字体覆盖 → 单次编码渲染 → 质检 / 最终音视频轨覆盖 / 最终成片字幕像素复核 / 字幕与独立人声对齐 / 声道完整性 / 短促音频掉点 / 闪烁风险 / 单帧瞬态伪影筛查 / 最终成片唇形复核 → 多平台导出 / 本地视频放大与可选补帧 / 目标大小交付编码 / 重编码画质损失门禁 → 标题文案 → 续跑交接**。适配 **小红书 / 抖音 / 微信视频号** 的比例、节奏、字幕、文案和常见审核风险。
  4. ## 适合做什么
  5. - **把口播短视频从“素材堆”推进到“发布包”**:项目目录、source inventory、转写、清稿、分镜、素材清单、渲染配置、字幕 sidecar、QA、标题正文和标签都能落成可审计 artifact。
  6. - **针对中文社媒口播做过生产化调参**:Heavy CJK 字幕、1.25x 主输出、响度规范化、平台违禁词 lint、章节卡、贴纸、BGM/SFX cue、三平台导出都不是通用 demo。
  7. - **噪声口播可在单次编码内保守清理**:`render_final.py --speech-denoise light|medium|strong` 会在变速、压缩、响度规范化和 BGM ducking 前处理低频震动与稳态底噪;默认关闭,最大降噪限制为 12 dB。
  8. - **停顿删段可同时看声音和画面**:`multimodal_dead_air.py` 只有在静帧覆盖静音达到门槛时才提出候选,实际只删二者交集;源 hash、20% 删除预算、切点复盘、单次编码和完整解码都进入 gate。
  9. - **多机位先同步再剪辑**:`multicam_sync.py` 把两台以上相机/手机/录音设备对齐到同一参考时间线,记录每路 offset、置信度、有效音轨、公共重叠区间,并可用多窗口 probe 测量长片时钟漂移;原片不改、不重编码。
  10. - **同步通过后可生成按说话者切换的导播草稿**:`multicam_switch.py` 绑定 ready 同步计划和全部源字节,按每路自己的噪声底/峰值归一发言能量;证据含糊时保持上一机位,高相关共享混音默认阻断。草稿完成媒体合同、全量解码和带声四项人工复核后才放行。
  11. - **只有播客音频也能产出竖版短片**:`podcast_audiogram.py` 将指定音频摘录、静帧封面和逐句 SRT 合成字幕优先的 H.264/AAC MP4,声波只作辅助;源文件、字幕、设置与交付件绑定在可现场验证的收据中。
  12. - **已审视频可导出轻量动图预览**:`gif_preview.py` 从指定短摘录生成无声、调色板优化的 GIF,限制时长、尺寸、帧率和文件大小,并用收据绑定源片与导出件,适合在聊天或文档中预览动作。
  13. - **照片可直接剪成带音乐的短片**:`photo_montage.py` 按给定顺序导出轻微缩放、叠化和首尾淡变的 H.264 MP4,可选闪白叠化与配乐;收据绑定照片、音乐及成片字节,并核对实际帧数、时长和完整解码。
  14. - **已审成片可加品牌 Logo**:`logo_overlay.py` 把 PNG 按指定四角、相对宽度、透明度和边距叠到 MP4;复制原音轨、完整解码成片,并用收据绑定原片、Logo 与输出。
  15. - **切点附近可精确逐帧找画面**:`frame_grid.py locate` 从秒级时间码找到最近解码帧;PNG 网格直接标出 `CELL 1` 等格号,JSON 记录每格的真实帧号和 PTS,可进一步导出单帧并验证源片、PNG 与映射收据。
  16. - **已审 SRT 可封装成可开关的 MP4 字幕轨**:`soft_subtitles.py` 复制原视频/音频流,加入 `mov_text` 字幕,核对字幕往返、音视频流哈希与完整解码,并生成可现场验证的收据;适合支持软字幕的播放器交付。
  17. - **长视频章节可封装进 MP4**:`chapter_mux.py` 读取已审 `chapter_markers.py` JSON,在不重编码音视频的情况下写入可跳转章节,核对每章时间/标题、音视频流哈希与完整解码,并生成可现场验证的收据。
  18. - **教程成片可配图文伴读草稿**:`tutorial_companion.py` 读取已审章节、最终视频和时间码转写,逐章截取画面并列出说明与原话;可指定更合适的截图时间,收据核对源片、截图和 Markdown。
  19. - **网页视频可使用独立章节轨**:`chapter_markers.py` 同时导出 `chapters.vtt`,保留毫秒时间码、中文标题及无重叠章节区间,可作为 HTML 视频的 `kind="chapters"` 文本轨。
  20. - **公开分享前可清除 MP4 容器标签**:`metadata_scrub.py` 无损复制已审视频/可选音频,移除位置、拍摄时间等非结构性标签、章节及额外轨,再核对流哈希、时长、完整解码与现场文件收据。
  21. - **开始媒体工作前先证明本机能跑**:`runtime_preflight.py` 按 `media_io / core_edit / podcast_audiogram / ping_pong_loop / multicam_switch / video_enhancement / storyboard_animatic / audio_cue_mix / generation_chain_handoff / captions / qa / edge_black_trim / hdr_sdr / stabilization / interlace / remotion` profile 检查命令版本、编码器和 FFmpeg filters;明确区分 missing 与 unknown,并让环境或报告漂移在 manifest 中失效。
  22. - **旧电视 / DV 素材先分清 telecine 和真实交错**:`interlace_conform.py` 用 FFmpeg `idet` 多段采样;疑似 3:2 pulldown 会阻断直接去交错,真实 TFF/BFF 才能经 `bwdif` 或明确的 `yadif` fallback 生成逐行工作副本,并在完整 1× A/B 确认后放行。
  23. - **手机和录屏 VFR 可先变成可审计 CFR 工作副本**:`frame_rate_conform.py` 读取全部解码帧 PTS 间隔,绑定精确目标有理帧率;输出必须通过恒定 cadence、帧数、音画起止、显示方向、SHA-256 和完整解码验证,原片保持不变。
  24. - **片头片尾黑场会先核对声音再裁切**:`black_edge_trim.py` 只接受接触源时间线两端的 `blackdetect` 区间,默认要求实际移除范围至少 95% 被静音覆盖;保留视觉 padding,生成原片边界 proof 和新的 CFR 工作副本,完整 1× 视听确认后才放行。
  25. - **长片内部可找结构性分段候选**:`program_breaks.py` 找内部黑场与所有音轨静音的重叠,给出候选时间点及 JSON/Markdown 证据;只供看听复核,不自动切片或命名节目。
  26. - **画面内持续黑边可先检测再决定构图**:`border_crop.py` 每秒采样多帧并记录 FFmpeg `cropdetect` 的实际矩形;只有全片与前中后三段结果一致,且黑边达到像素门槛,才给出 `crop=w:h:x:y` 建议。报告可从源片重新检测验证,不直接改视频。
  27. - **无检测模型时也可查看运动落点**:`motion_center.py` 比较缩小后的相邻画面,逐时点报告局部像素运动中心;静止画面和大范围变化不提供焦点。结果用于回看和人工构图,不直接驱动裁切。
  28. - **现成 `.cube` LUT 可在最终单次编码中使用**:`lut_grade.py` 先让 FFmpeg 实测加载 LUT,再把文件 SHA-256 和插值模式写入计划;`render_final.py --color-grade` 在渲染前重验计划与 LUT,文件变化会阻断。
  29. - **原始转写可筛查静音里的可疑文字**:`transcript_silence_qa.py` 将逐段时间码与音轨实测静音交叉检查,标记需要回听的段落;报告绑定音频与转写文件,复核时会重新测量,不自动删除文字。
  30. - **短背景可以按次数或固定时长安全重复**:`loop_fill.py` 只接受 progressive CFR SDR 源片,音画一起循环或显式丢弃源音频;首个真实接缝和完整交付件都要正常速度复核,源片、输出、proof、设置或人工结论漂移都会让 manifest gate 失效。
  31. - **不闭合的短动作可以做端帧去重乒乓循环**:`ping_pong_loop.py` 把选区编译为 `0…N-1,N-2…1`,去掉普通正放+倒放在折返点和循环点产生的重复端帧;渲染前计算 `reverse` 缓存上限,输出无声 H.264 和折返/循环两条 proof,完整 1× 复核后才放行。
  32. - **不同规格的视频可以安全拼成一条**:`clip_assembly.py` 按最终顺序绑定每条源片,在一次编码中统一画布、rotation、CFR、SAR、像素格式、时间戳与 48 kHz stereo;无声片段可补等长静音,交付件和全部接缝 proof 都通过完整解码与 1× 人工复核后才放行。
  33. - **手持防抖保留原片和 A/B 证据**:`video_stabilization.py` 把源 SHA-256、确切 FFmpeg 后端和人工决定写进计划;apply 只生成新工作副本与全长左右对照,完整 1× 复核并 confirm 后 manifest 才放行。
  34. - **绿幕/蓝幕换背景先看 matte 再渲染**:`chroma_key.py` 在前景早/中/晚生成 composite 与黑白 matte,人工逐项确认边缘、主体完整性、溢色和背景匹配后才允许完整 H.264/AAC 输出;源、背景、预览、filter 或成片漂移都会让旧 review 失效。
  35. - **局部慢动作先计划再渲染**:`speed_ramp.py` 把显式 impact frame 周围的 `snap/ease/s_curve`、hold 和可选 FFmpeg 插帧编译成 source-bound 计划;源 hash 或 piece 时间映射漂移会阻塞,apply 采用同目录临时文件事务式落盘。
  36. - **动作落点可以定格并轻推近**:`freeze_punch.py` 用第一帧替换指定 source-time 窗口,保持总时长和原音频时间线不变;计划绑定源片、事件和输出字节,完整解码、成片漂移或尚未 apply 都会阻塞 manifest。
  37. - **上传大小限制变成硬门禁**:`delivery_encode.py` 依据源片时长计算两遍 H.264/AAC 码率,绑定源与输出 SHA-256;完整解码、音视频契约或硬大小上限任一失败都不会提升成交付件。
  38. - **压缩后“能播放”不再等于“画质够用”**:`encode_quality_qa.py` 对同时间线、同构图的 master 与重编码衍生件做全长 SSIM/PSNR 比较,保存平均值、P05 低尾部和最差帧时间码;两条视频、媒体契约、阈值或现场复测漂移都会让报告失效。
  39. - **现有视频可以走可审计的放大/补帧收尾**:`video_enhancement.py` 绑定源 SHA-256、目标短边或倍率、目标 FPS 和确切 FFmpeg filter;本地 Lanczos 与可选 `minterpolate` 输出只有通过尺寸/帧率/时长/音轨合同、完整解码、全长 A/B 和带声四项人工复核后才放行。它明确保留“resize 不等于 ML 细节恢复”的能力边界。
  40. - **专业声画错位不再靠手写 FFmpeg**:`audio_transition.py` 对明确边界规划 J-cut/L-cut,验证真实音频 handle、config/transcript/source hash 和 compiled timing;`render_final.py` 在同一次编码中完成画面硬切、音频 pre-lap/overhang、字幕、overlay 与 BGM。
  41. - **音效 cue 可以落成一条可审母轨**:`audio_cue_mix.py` 把 `audio_cue_sheet.v1`、最终旁白和本地/程序化 SFX 绑定后输出 48 kHz stereo 单轨;完整解码与 1× 五项试听通过前保持阻塞,输入或输出漂移会让 review 失效。
  42. - **连续生成可以用真实末帧接力**:`generation_chain_handoff.py` 从已审上一镜的完整片段或最后一个 approved keep range 选择确切 decoded 末帧,验证源帧/PNG 像素一致并经人工确认后,将它绑定为下一镜 exact first frame;原角色、产品和 style anchors 继续保留。
  43. - **事实型内容有 proof deck**:新闻、数据、产品事实或来源页截图可用 `source_receipts.py` 生成 URL/截图复核包,作为发布前 gate。
  44. - **高影响动作先绑定确切授权范围**:`production_authorization.py` 把外部上传、侵入性重排/删除、付费生成、声音克隆、真人/未成年人/公众人物/品牌/IP 权利和发布决定绑定到具体素材 SHA-256、用途与 provider/surface;scope 或源字节变化会让旧授权失效。
  45. - **最终审批绑定到具体文件字节**:`approval_receipt.py` 为人工看过的视频、封面、文案、字幕和 QA 报告记录 SHA-256;任何重渲染、替换、删除或 symlink 漂移都会让旧审批过期并阻塞发布。
  46. - **ASR 语义校稿不再只看单句**:`semantic_transcript_review.py` 为每条字幕附带全篇前后文,验证完整覆盖、源 transcript hash 和最小字符补丁;模型只能提建议,独立人工 choices 才能写 reviewed transcript。
  47. - **长片原话可以直接定位**:`transcript_lookup.py` 在带时间戳的 transcript 中查确切措辞或读取指定时间窗口,返回有限条源段 ID、时间码、上下文和源文件 SHA-256;无需把整份转写塞进对话。
  48. - **上游剪辑配置可以安全撤销/重做**:`edit_revision.py` 把 `render_config` / `enrich_plan` 等文本 artifact 的完整改动绑定到基础和依赖 SHA-256;独立审批后成组写入,外部漂移时拒绝 undo/redo 并阻塞 manifest。
  49. - **已审时间线可以换素材复用**:`edit_recipe.py` 把 `render_config.json` 的全部本地文件路径替换成类型化槽位,生成 content-addressed 可移植配方;回放必须完整绑定新素材、记录 SHA-256 并重新通过 `edit_preflight.py`。
  50. - **个人/品牌剪辑偏好可跨项目复用**:`edit_style_profile.py` 把创意方向、节奏、受控渲染默认值、封面风格、标题拼写与发布时段存成无本地路径的 profile;`render_final.py` / `generate_caption.py` / `cover_variants.py` 直接消费它,项目 config 和 CLI 始终优先。
  51. - **生成式素材有明确审批和台账**:Codex `image_gen` / GPT Image 2 提示词、Dreamina/Veo/LTX/Wan/Sora 视频提示词、provider 决策、`submit_id` 轮询下载和本地落盘 gate 都先记录再执行。
  52. - **生成 provider 参数先绑定具体入口再使用**:`provider_capability.py` 把 provider、UI/API surface、model、核验日期、证据和 mode/画幅/时长/分辨率/参考上限落成 profile;`video_prompt_pack.py` 会拒绝缺失、过期或设置越界的 profile。
  53. - **多模态生成参考素材先解码、限额和绑定角色**:`generation_reference_preflight.py` 把本地图片/视频/音频按 provider 顺序标成 `@ImageN / @VideoN / @AudioN`,要求每份素材只有明确角色与排除项;同时检查类型、扩展名、字节、单条/合计时长、数量、audio-only、frame/reference 互斥和 live profile/source 漂移。
  54. - **参考片的故事公式可以安全迁移**:`reference_story_formula.py` 把参考视频、timecoded transcript 和目标 storyboard 绑定起来,要求人工标注情绪机制、观众状态变化、触发点和逐镜 content anchor;原画面、音频、原话、品牌及具体情节全部进入显式复制排除合同,通过 live gate 后才注入 `video_prompt_pack.py`。
  55. - **多镜头生成前先逐边界设计接力**:`sequence_handoff.py` 把上一镜 offer、下一镜 receive、载体、edit type、180° 轴、屏幕方向、音频桥、头尾 handles、风险和 fallback 绑定到确切 storyboard;审核通过后 `video_prompt_pack.py` 会把双向接力合同写进对应 provider prompt。
  56. - **付费生成前先按真实时长看完整分镜**:`storyboard_animatic.py` 把 `storyboard_plan.v1`、每镜一张静帧和可选旁白绑定成带 shot/time 标签的 CFR MP4;完整 1× 检查顺序、节奏、可读性、连续性和音画对齐后才放行,分镜、panel、音频或输出漂移会让旧 review 失效。
  57. - **生成视频不会从冻帧起步**:`generated_motion_window.py` 以 0.25 秒 full-frame freeze evidence 找出 active intervals;人工确认 trim/keep/reject 后才生成新的 H.264/AAC 工作副本,source、检测参数、决定和输出字节都会 live verify。
  58. - **生成片段复核会反哺下一次提示词**:`generation_lessons.py` 只从 canonical clip review 提取人工明确批准的通用经验,绑定 source digests,并按 provider/model/category 精确筛选后交给 `video_prompt_pack.py`;不会把单片修复建议自动当成全局规则。
  59. - **字幕风格先在真实画面上选**:`subtitle_style_preview.py` 用最终 renderer 的同一 ASS builder、字体、字号和目标画幅,把 `normal / minimal / bold_pop` 渲染到源片早、中、晚代表帧;源片、字体、样式定义或 JPEG 漂移会让旧选择失效。
  60. - **生僻字、emoji 和多语言字幕不再赌系统 fallback**:`subtitle_glyph_qa.py` 读取最终 `subtitle_pack.v1` 与实际 TTF/OTF/TTC/OTC 的 Unicode cmap,逐字符记录主字体、显式 fallback 或 missing;字幕、字体、设置或派生覆盖结果漂移都会让旧报告失效。
  61. - **字幕最终有没有出现在成片像素里可以举证**:`subtitle_render_review.py` 从确切 final MP4 选择首尾、最长、最高 CPS、最短、中段与均匀分布 cue,导出 1× 上下文片段和中点原尺寸帧;通过要求完整正常速度审片,并逐样本确认文字存在、匹配、可读、没有裁切或遮挡。
  62. - **字幕不再只检查“能否读完”,还检查显示时是否有人声**:`caption_speech_qa.py` 把 `subtitle_pack.v1` cue 与最终独立对白/旁白轨的 FFmpeg audio-activity intervals 对照,阻断孤立、严重错位、头尾超出和音轨越界字幕;人声轨、字幕、阈值或现场测量漂移都会让旧报告失效。
  63. - **平台画幅处理先看真实 A/B 再导出**:`framing_preview.py` 为小红书 / 抖音 / 视频号逐平台比较 `cover / contain / blur`,把选择绑定到 master、显示方向、filter contract 和 JPEG 证据;`multi_export.py` 只消费现场验证通过的选择。
  64. - **最终成片会筛查大面积高频闪烁**:`flash_safety_qa.py` 用本地 FFmpeg 分析亮度与饱和红相反 transition,按滚动 1 秒 / 5 秒窗口输出风险区间;source、媒体契约、参数、算法或现场证据漂移都会让报告失效。它只做启发式风险分流,不冒充医疗或法规认证。
  65. - **长静帧和高频闪烁之间的单帧事故也有门禁**:`temporal_artifact_qa.py` 查找 1–3 帧突然偏离又回到近似原画面的局部 spike,为每个候选导出 `before / suspect / after` JPEG;必须完整 1× 播放并逐帧决定 `intentional_edit / artifact / uncertain`,后两者继续阻断。
  66. - **分段 TTS / 配音不会再被整片平均响度掩盖**:`narration_loudness_qa.py` 在最终独立旁白音轨上逐短语实测 LUFS / dBTP / LRA,并检查非例外段 spread;旁白、时间清单或现场 measurements 漂移会让旧报告失效,混音后仍要另跑全片 `audio_master_report.py`。
  67. - **最终声道错误不会被整片响度合格掩盖**:`audio_channel_qa.py` 现场检查左右声道活动、起始错位、能量平衡、相位相关和 mono fold-down 损失;source、媒体契约、阈值、算法或 measurements 漂移都会让旧报告失效。
  68. - **几十毫秒断音不会被长静音门槛漏掉**:`audio_dropout_qa.py` 用 20 ms 窗口查找活跃音频之间的短促近静音,导出正常速度 WAV 上下文;每个候选必须完整试听并标记为掉点、刻意停顿或不确定,源文件、测量、证据或 response 漂移都会阻断。
  69. - **MP4 能播放也要证明两条流完整**:`stream_coverage_qa.py` 完整解码最终文件,核对视频/音频首尾 PTS、各流对容器时间线的覆盖、视频 `nb_frames` 和可选的预期时长/帧数;重渲染、remux 或报告漂移都会让旧 gate 失效。
  70. - **数字人口型必须在最终成片上重新举证**:`lip_sync_review.py` 从最终 master 的完整短语导出 1× 带声和 0.25× 静音 proof clips,逐条复核爆破音闭唇、元音提前/滞后、讲话时冻嘴、说话人和音频质量;任何剪切、变速、换音或重编码都会让旧报告失效。
  71. - **参考片节奏先量化再借鉴**:`reference_edit_rhythm.py` 用同一套 hard-cut 检测比较参考片和成片的 cuts/minute、镜头时长、结尾 hold 与切点分布,同时绑定两条视频和 contact sheets;默认只提示差异,明确验收时才阻断。
  72. - **适合交给强推理模型做长流程代理执行**:在 [GPT-5.6 Sol](https://developers.openai.com/api/docs/models/gpt-5.6-sol)(OpenAI 当前旗舰;API 别名 `gpt-5.6` 指向 Sol)和 [Claude Opus 4.8](https://docs.anthropic.com/en/docs/about-claude/models) 这类面向复杂专业任务、agent 工作流的模型下,本 skill 对 **口播类短视频** 至少可以替代 **80% 的常规视频剪辑工作**。
  73. 这里的“80%”是按口播短视频生产来评估的:它已经覆盖素材整理、ASR、清稿、粗剪、字幕、B-roll/图像/生成视频规划、声音 cue、渲染前预检、渲染、质检、多平台导出和发布文案。剩下通常需要人工负责的是选题判断、最终审美取舍、品牌口吻、客户确认、复杂手工精修、调色混音和需要逐帧 keyframe 的高级特效。
  74. 模型说明:本仓库不会在脚本中硬编码 LLM 型号;这里推荐的是负责理解需求、编排脚本、调用工具和复核产物的 Agent 模型。OpenAI 官方将 `gpt-5.6-sol` 定位为 GPT-5.6 家族的旗舰型号;追求更低成本或更高吞吐时,可按运行环境选用 GPT-5.6 Terra 或 Luna。
  75. ## 项目现状与边界
  76. 做得比较完整的地方:
  77. - **定位清楚**:口播、教程、访谈、录屏和长视频切短视频是高重复剪辑场景,脚本化收益高。
  78. - **流水线完整**:从 transcript 到 publish gate 的 artifact 很全,失败点可复查,不依赖聊天上下文记忆。
  79. - **风险控制到位**:内容合规、素材授权、隐私遮挡、生成任务审批、渲染 QA、pipeline manifest 都有阻塞门禁。
  80. - **本地优先**:核心剪辑、渲染、质检不需要云端服务;外部生成任务只做规划、审批和台账。
  81. 需要用户知道的边界:
  82. - **不应包装成全类型剪辑替代品**:电影感剪辑、MV、广告大片、复杂调色混音和精细动效仍需要专业人工。
  83. - **AI 生成素材不等于自动可用**:Dreamina/Veo/Sora 等结果必须经过下载、授权、视觉连续性和 QA 检查。
  84. - **平台规则不是法律意见**:`content_guard.py` 能拦常见风险词,但最终发布仍要人审。
  85. - **README 和 SKILL 偏长**:功能很全,但新用户需要先走推荐入口,不适合从完整脚本文档硬读。
  86. ## 视频素材理解
  87. 当前版本已经加入可选的视频理解层:基础流程不依赖机器视觉模型,安装 `ultralytics` 后可以用 YOLO 对抽样帧做物体检测,并把结果整理成统一的 `video_understanding.v1`。
  88. - `extract_keyframes.py` 会抽关键帧和时序图,帮助 agent/用户快速看懂一段视频的视觉内容。
  89. - `scene_boundaries.py` 支持固定阈值和邻域自适应 FFmpeg scene score,输出逐切点证据,供长视频拆条、抽帧和 highlight snap 使用。
  90. - `visual_dedupe.py` 会读取多个来源及其 `scene_boundaries.v1`,对每个场景取 10%/50%/90% 三帧做感知哈希,找出跨素材重复镜头并生成保留建议;只输出复核计划,不删除源素材。
  91. - `video_understanding.py` 会按固定间隔和场景边界抽帧;`--detector yolo` 会运行 Ultralytics YOLO,输出 `frames[]`、`detections[]`、`tracks[]`、`scene_tags[]` 和 review Markdown。
  92. - `media_library.py` 会读取视频元数据、文件名、标签、素材来源和关联 transcript,用透明分数推荐本地 B-roll。
  93. - `smart_reframe.py` 可以读取 `video_understanding.json`,按人脸、人物、主体、物体等权重生成竖屏/方屏重构图计划。
  94. - `privacy_redact.py` 可以读取同一份检测框或人工框,对人脸、车牌、屏幕敏感区域生成 blur/pixelate/mask 计划。
  95. 这个设计是有意的:YOLO/RT-DETR/MediaPipe 等模型会带来模型下载、GPU/Metal/CUDA 兼容和速度问题;对大量口播视频来说,ASR + 关键帧 + 场景边界已经能覆盖主要剪辑决策。因此本项目把 YOLO 做成“需要时打开”的增强能力,而不是强制依赖。
  96. `video_understanding.py` 的工作方式:
  97. 1. 先用 FFmpeg 按场景边界和固定间隔抽帧,避免对每一帧跑模型。
  98. 2. 如果安装了 `ultralytics`,用 YOLO 检测 `person`、`phone`、`laptop`、`screen/tv`、`car`、`bottle/cup` 等短视频常见对象。
  99. 3. 用采样帧上的 bbox 做轻量 IoU/中心点关联,合并成 `tracks[]`,用于判断主体是否移动、是否大面积占画、是否适合自动重构图。
  100. 4. 输出统一的 `video_understanding.v1`:
  101. - `frames[]`:时间戳、关键帧路径、场景 id。
  102. - `detections[]`:label、bbox、confidence、source model。
  103. - `tracks[]`:主体轨迹、出现时间段、中心点、面积变化、运动强度。
  104. - `scene_tags[]`:人物、屏幕、产品、街景、车辆、手部演示等可检索标签。
  105. - `warnings[]`:未启用 detector、未检测到对象、低置信度检测等。
  106. 5. 下游复用这个 JSON:`smart_reframe.py` 做主体感知裁切,`privacy_redact.py` 做隐私遮挡,`media_library.py` 写入视觉标签,`storyboard_assets.py` 选择更匹配的 B-roll,`pipeline_manifest.py` 可把未复核的视觉检测列为 gate。
  107. 常用方式:
  108. ```bash
  109. # 可选:只有需要 YOLO 检测时安装
  110. pip install ultralytics
  111. python3 scripts/scene_boundaries.py origin/talking.mp4 \
  112. --method adaptive \
  113. --output work/scene_boundaries.json \
  114. --markdown work/scene_boundaries.md
  115. # 多机位/多条 B-roll 先分别生成 scene boundaries,再把来源写进 manifest。
  116. # manifest 内的相对路径以 manifest 所在目录为基准。
  117. python3 scripts/visual_dedupe.py \
  118. --manifest work/visual_dedupe_sources.json \
  119. --output work/visual_dedupe.json \
  120. --markdown work/visual_dedupe.md \
  121. --strict
  122. python3 scripts/video_understanding.py origin/talking.mp4 \
  123. --output work/video_understanding.json \
  124. --markdown work/video_understanding.md \
  125. --frames-dir work/video_frames \
  126. --scene-boundaries work/scene_boundaries.json \
  127. --detector yolo \
  128. --model yolo11n.pt \
  129. --sample-interval 2 \
  130. --max-frames 32 \
  131. --strict
  132. python3 scripts/smart_reframe.py origin/talking.mp4 \
  133. --detections work/video_understanding.json \
  134. --platform douyin \
  135. --output work/reframe_douyin.json \
  136. --markdown work/reframe_douyin.md
  137. ```
  138. 如果不想安装 YOLO,也可以只生成抽样帧和 review shell:
  139. ```bash
  140. python3 scripts/video_understanding.py origin/talking.mp4 \
  141. --output work/video_understanding.json \
  142. --markdown work/video_understanding.md
  143. ```
  144. 对于需要更细的逐帧动态跟踪的素材,可以把 Ultralytics `model.track(..., tracker="bytetrack.yaml")`、BoT-SORT 或 Norfair 的结果转换成同一份 `detections[]` / `tracks[]` JSON 再交给本项目。当前内置版本优先服务口播剪辑:抽帧检测 + 轻量轨迹已经足够支持主体裁切、隐私遮挡提示和 B-roll 标签。
  145. ```
  146. 口播音频 + 无声素材
  147. │
  148. ├─→ project_bootstrap.py 原始素材目录 → origin/work/output/verify/edit + source inventory
  149. ├─→ edit_brief_plan.py 用户一句话需求 → 本地脚本 runbook / commands / gates
  150. ├─→ runtime_preflight.py workflow profile → FFmpeg/Node 命令、编码器、filters / live gate
  151. ├─→ interlace_conform.py 交错/telecine 采样 → progressive 工作副本 / 全长 A/B gate
  152. ├─→ frame_rate_conform.py 手机/录屏 VFR → 全量 PTS 检测 / CFR 工作副本 / live gate
  153. ├─→ black_edge_trim.py 首尾黑场 + 静音覆盖 → CFR 工作副本 / 原片边界 proof + live gate
  154. ├─→ program_breaks.py 内部黑场 + 全音轨静音 → 分段候选 / 人工看听复核
  155. ├─→ loop_fill.py progressive CFR 短片 → 次数/目标时长 repeat / 接缝 proof + 完整审片 gate
  156. ├─→ ping_pong_loop.py 短动作 → 端帧去重正放/倒放 / 折返+循环双 proof / live gate
  157. ├─→ clip_assembly.py 多源片段 → 单次画布/CFR/SAR/音频归一 / 全接缝 proof + live gate
  158. ├─→ edit_style_profile.py 个人/品牌创意方向、节奏与渲染/文案默认值 → 可移植 profile
  159. ├─→ production_authorization.py
  160. │ 确切素材/动作/provider/权利依据 → 显式授权 + live gate
  161. ├─→ transcribe.py 转写 + 词级时间戳 + 口误标记
  162. ├─→ transcript_lookup.py 原话检索 / 时间窗口读取 → 有界时间码结果
  163. │ (mlx-whisper / faster-whisper / openai-whisper)
  164. ├─→ semantic_transcript_review.py
  165. │ 全篇前后文审校包 / 最小补丁验证 / 人工 choices gate
  166. ├─→ transcript_review.py 文本 round-trip / 本地同步视频 HTML 校稿
  167. │ 行内编辑 / 播放高亮 / 查找替换 / CPS 提示 / review.txt
  168. ├─→ takes_pack.py 多 take / Scribe transcript → phrase-level 阅读视图
  169. │ speaker / audio_event / takes_packed.md / takes_pack.json
  170. ├─→ script_alignment.py 已审目标稿 → 多 take 原话候选 / choices / render_config
  171. │ 词/段边界 / 透明分数 / 歧义与缺素材 gate
  172. ├─→ audio_sync.py 外录音轨自动对齐 / 替换音轨计划
  173. │ scratch audio + lav/recorder track → offset + gate
  174. ├─→ multicam_sync.py 多机位 → 同一参考时间线 / 公共重叠区间 / 对齐预览
  175. │ 最响音轨 / pairwise / 可选时钟漂移 / source-safe gate
  176. ├─→ multicam_switch.py ready 同步计划 → speaker-mapped 音频 / 自动导播草稿
  177. │ 归一化能量 / 共享混音拦截 / 完整解码与人工 review gate
  178. │
  179. ├─→ scene_boundaries.py fixed/adaptive 视觉切点 + 逐切点 evidence
  180. ├─→ visual_dedupe.py 多来源场景 → 感知哈希重复组 / 保留建议 / review gate
  181. ├─→ video_understanding.py 抽样帧 + 可选 YOLO 物体检测
  182. │ frames / detections / tracks / scene_tags
  183. ├─→ video_stabilization.py 手持素材 → source-bound 后端/决定/稳定工作副本
  184. │ 全长原片-vs-稳定版 A/B + confirm gate
  185. ├─→ chroma_key.py 绿幕/蓝幕前景 + 图片/视频背景 → composite/matte 代表帧
  186. │ 四项人工 review / 完整渲染 / source-bound live gate
  187. │
  188. ├─→ highlight_picker.py 长视频精华候选 / brief-query 定向找片段
  189. │ 输出 score / hook / reason / render_config
  190. ├─→ audio_boundary_snap.py 已选片段 → 词/句末/静音边界校正
  191. │ adjustment delta / blocker / shorts_batch 兼容输出
  192. ├─→ shorts_batch.py 精华候选 → 多条短视频渲染 job sheet
  193. │ per-short render_config / render command / QA command
  194. │
  195. ├─→ rough_cut.py ASR 粗剪 → 去纯口头禅 / 相邻重复句
  196. │ 输出可审计 cut list,可选单次 concat 渲染
  197. │
  198. ├─→ hook_variants.py transcript/clean_script → 8 个前三秒 hook 角度
  199. │ 推荐排序 / content guard 风险 / visual cue
  200. │
  201. ├─→ rewrite_script.py LLM 重组为 5 段式 (hook/pain/turn/value[]/cta)
  202. │ ↑ 8 hook 模板 + 5 CTA 模板 + 3 故事结构
  203. │
  204. ├─→ content_guard.py 80+ 条平台雷区 lint (HARD-BLOCK / SOFT-WARN)
  205. │ 极限词 / 导流 / 医美 / 财富诱导 ...
  206. │
  207. ├─→ source_receipts.py 事实 claim → URL/截图 source deck
  208. │ Markdown/HTML proof deck + publish gate
  209. │
  210. ├─→ beat_sync.py BGM beat-grid → 可审计 program-time 剪辑骨架
  211. │ 或把已有切点吸附到附近 beat
  212. ├─→ speed_ramp.py 局部慢动作 / velocity edit → source-bound 计划
  213. │ snap/ease/s-curve / 可选插帧 / 音频同步 / 事务式 apply
  214. ├─→ freeze_punch.py impact frame → 定格替换窗口 / 轻微 punch crop
  215. │ 总时长与原音频不变 / source-bound apply + live gate
  216. │
  217. ├─→ auto_enrich.py 调度 B-roll / 章节卡 / 贴纸 / 强调点 / BGM 卡点
  218. │ │ transition / entity match / emphasis cue / silence boundary / beat snap
  219. │ │
  220. │ └─→ imagegen_hint.py 抽象概念检测 → gpt-image-2 提示词
  221. │ ↓ (Codex 内置 imagegen 工具直接执行;无 API key)
  222. │ Codex imagegen 注意力机制 / 复利 / 信息茧房 等自动配图
  223. │
  224. ├─→ audio_cue_sheet.py transcript → BGM / SFX 音频设计清单
  225. ├─→ audio_cue_mix.py cue sheet + 最终旁白 → 本地/程序化 SFX 单轨 / 1× review gate
  226. │ 本地素材优先 / 生成审批 / pipeline gate
  227. │
  228. ├─→ storyboard_plan.py transcript/clean_script → shot cards
  229. │ 生成路由 / 连续性锚点 / Dreamina 额度提醒
  230. │
  231. ├─→ storyboard_animatic.py 每镜静帧 + 可选旁白 → timed MP4
  232. │ 镜头 ID/时间码 / 完整 1× review / source-bound live gate
  233. │
  234. ├─→ reference_story_formula.py
  235. │ 参考片情绪机制 → 目标镜头 content anchors / 复制排除 live gate
  236. │
  237. ├─→ sequence_handoff.py 相邻镜头 receive-in / handoff-out / edit boundary
  238. │ 180° 轴 / 屏幕方向 / 音频桥 / edit handles / live gate
  239. │
  240. ├─→ provider_capability.py exact provider/surface/model 能力合同
  241. │ 核验日期 / sources / modes / limits / live gate
  242. ├─→ video_prompt_pack.py Dreamina/Veo/LTX/Wan/Sora 提示词包
  243. │ 角色/品牌/style lock / paid approval + capability gate
  244. ├─→ reference_frame_preflight.py
  245. │ 首帧/style key 尺寸/方向/画幅/透明背景 gate
  246. ├─→ generation_reference_preflight.py
  247. │ 图片/视频/音频类型/限额/角色/@标签 / source-bound live gate
  248. │
  249. ├─→ generation_task_log.py 异步生成任务台账
  250. │ submit_id / 轮询 / 下载 / 本地落盘 gate
  251. ├─→ generated_clip_review.py 下载后的生成视频片段复核
  252. ├─→ generation_chain_handoff.py
  253. │ 已审上一镜末帧 → 下一镜精确首帧 / 顺序生成 live gate
  254. │ contact sheet / 常识物理 / 身份道具 / 裁切与重生 gate
  255. ├─→ generated_motion_window.py 生成片有效运动窗口
  256. │ 0.25s 冻帧检测 / 人工 trim|keep|reject / 新工作副本 live gate
  257. ├─→ scoped_video_edit_review.py 原片 vs 局部 AI 编辑结果
  258. │ change-only / preserve invariants / 同时间点 A-B + 双音轨 gate
  259. ├─→ generated_sequence_review.py 已审生成片段 → 相邻边界连续性复核
  260. │ 尾帧/首帧 / 无声预览 / 身份道具空间动作机位光色 gate
  261. ├─→ generation_lessons.py canonical clip review → 人工批准经验库
  262. │ provider/model/category scope → 下一次 prompt pack
  263. │
  264. ├─→ storyboard_assets.py shot cards → 素材任务清单 / ready 预检
  265. │ imagegen / Dreamina / motion / broll 状态表
  266. │ 可选接入 media_library.py recommend 排名候选素材
  267. │
  268. ├─→ stock_material_plan.py stock B-roll 搜索规划
  269. │ Pexels / Pixabay / Coverr 查询计划 + 素材登记提示
  270. │
  271. ├─→ screen_focus.py 录屏点击/热点 → focus_events 聚焦计划
  272. │ render_final 自动放大、标记、标签
  273. ├─→ pip_overlay.py 录屏 + facecam → pip_overlays 小窗计划
  274. │ render_final 单次编码合成 PIP camera
  275. │
  276. ├─→ jump_cut.py 自适应静音检测 → 20% 删除预算 → cut list → 去停顿成片 + 切点音频 fade
  277. │ └─→ timeline_view.py 源素材删除段 / 成片输出切点 filmstrip + waveform 人工复核图
  278. │
  279. ├─→ audio_transition.py 显式 J-cut/L-cut → source handle / hash / 单次编码 / 1× 试听 gate
  280. │
  281. ├─→ edit_revision.py render_config/enrich_plan 等文本 artifact 可逆修订
  282. │ source/dependency hash / 独立审批 / 成组 apply / undo / redo
  283. │
  284. ├─→ edit_recipe.py 已审 render_config → 无路径可移植配方 / 精确绑定回放
  285. │ typed slots / portable SHA-256 / replay receipt / preflight
  286. │
  287. ├─→ edit_preflight.py render_config/enrich_plan/cut list 渲染前预检
  288. │ 缺文件、空剪辑、非法时间段、危险参数 gate
  289. ├─→ platform_safe_area_qa.py 字幕/PIP/CTA/marker 平台 UI 安全区 gate
  290. │ JSON/Markdown/SVG 证据 + 多平台 profile
  291. │
  292. ├─→ subtitle_style_preview.py 真实源帧 → 最终 ASS 预设对比 JPEG / 选择 / live gate
  293. ├─→ subtitle_glyph_qa.py subtitle_pack + 显式字体 → 逐字符 cmap 覆盖 / 缺字 live gate
  294. │
  295. ├─→ render_final.py 单次编码渲染 + enrich_plan 自动接入
  296. │ B-roll / 章节卡 / 贴纸 / 生成图 / 点击聚焦 / PIP camera + 可选口播降噪 + Heavy 字幕 + 响度规范化 + BGM ducking
  297. │ 可选 --versioned-output:输出 _V<N>,避免覆盖旧成片
  298. │
  299. ├─→ subtitle_render_review.py 最终 MP4 + subtitle_pack → 高风险字幕 1× clips / 原尺寸帧 / 完整审片 live gate
  300. ├─→ render_qa.py 渲染后黑屏/静帧/静音/尺寸质检 + review packet
  301. ├─→ stream_coverage_qa.py 最终 MP4 decoded A/V 首尾 PTS / 帧数 / 容器覆盖 live gate
  302. ├─→ encode_quality_qa.py 同时间线 master vs 重编码件 → SSIM/PSNR / 最差帧 / live gate
  303. ├─→ audio_channel_qa.py 成片声道活动/起始/平衡/相位/mono fold-down live gate
  304. ├─→ audio_dropout_qa.py 最终人声/混音短促近静音候选 / 1× WAV 听审 live gate
  305. ├─→ flash_safety_qa.py 亮度/饱和红 flash → 1s/5s 风险窗口 / source-bound live gate
  306. ├─→ temporal_artifact_qa.py 单帧/少数帧 return-to-state spike → 三帧证据 / 人工 audit / live gate
  307. ├─→ shot_color_qa.py 成片镜头亮度/对比/色度/饱和度/broadcast-range + 切点跳变门禁
  308. ├─→ retention_rhythm_qa.py 成片 hook 活动 / 长镜头 / 注意力空窗 / 节奏门禁
  309. ├─→ reference_edit_rhythm.py 参考片 vs 成片 hard-cut 结构 / contact sheets / live gate
  310. ├─→ speech_continuity_qa.py 成片二次 ASR → 切点复读 / 近重复 take / 句内口吃 gate
  311. ├─→ lip_sync_review.py 最终 master → 1×/0.25× 对口型证据 / 人工审计 / live gate
  312. ├─→ review_proxy.py 低码率完整审片 MP4 / 可见时间码 / faststart
  313. ├─→ audio_master_report.py 成片响度 / true peak / LRA / 长静音发布 gate
  314. ├─→ narration_loudness_qa.py 最终独立旁白逐短语 LUFS / spread / dBTP / LRA live gate
  315. │ └─→ timeline_view.py QA 可疑区间可视化复盘
  316. │
  317. ├─→ subtitle_pack.py SRT / VTT / ASS / JSON 字幕交付包
  318. │ 支持 render_config 串接、加速倍率、片头 offset 对齐
  319. ├─→ subtitle_readability_qa.py
  320. │ 最终字幕 CPS / 时长 / 行长 / 重叠 / 媒体越界发布 gate
  321. │
  322. ├─→ import_capcut_subtitles.py
  323. │ 剪映/CapCut 自动字幕 → transcript / gap cut list
  324. ├─→ srt_edit_plan.py SRT + keep/drop 编辑指令 → render_config / cut list
  325. │
  326. ├─→ project_resume.py 续跑上下文包 / agent handoff / 可选 CLAUDE.md
  327. │
  328. ├─→ review_dashboard.py 静态 HTML/JSON 人工复核面板 / gate review queue
  329. │
  330. ├─→ export_edl.py render_config / cut list → EDL + manifest
  331. ├─→ export_fcpxml.py render_config / cut list → FCPXML + manifest
  332. ├─→ export_otio.py render_config / cut list → OTIO + manifest
  333. │ 交给 Premiere / Final Cut Pro / Resolve
  334. ├─→ final_audio_storyboard.py
  335. │ 锁定 EDL + 原 storyboard → 最终时间线声音分镜 / voice ledger / live gate
  336. │
  337. ├─→ framing_preview.py master → 各平台 cover/contain/blur 真实帧 / 选择 / live gate
  338. ├─→ multi_export.py 已审画幅策略 → 小红书 3:4 / 抖音 9:16 / 视频号 ≤60s
  339. ├─→ delivery_encode.py 硬大小上限 / 两遍 H.264 / 完整解码验证
  340. ├─→ generate_caption.py 标题 + 200-500 字正文 + 3-6 tags + 发布时段建议
  341. ├─→ cover_variants.py 2-4 套封面 A/B 方案 / 小尺寸预览 / 最终选择 gate
  342. ├─→ approval_receipt.py 已复核交付件 → SHA-256 收据 / stale approval gate
  343. └─→ publish_package.py 平台视频 / 已选封面 / 字幕 / 文案上传包
  344. ```
  345. > **适用场景**:daily 短视频、口播为主的内容(创业/AI/职场/效率/Vlog)、要发小红书/抖音/视频号
  346. > **不适用**:电影感剪辑、纯音乐 MV、需要精细 keyframe 控制的特效视频
  347. ---
  348. ## 60 秒上手
  349. ```bash
  350. # 1. 装好依赖(macOS Apple Silicon 为例)
  351. brew install ffmpeg
  352. pip install mlx-whisper Pillow
  353. # 2. 克隆
  354. git clone https://github.com/maxazure/video-editing-skill ~/projects/video-editing-skill
  355. cd ~/projects/video-editing-skill
  356. # 3. 按实际工作流检查本机命令、编码器和 FFmpeg filters
  357. python3 scripts/runtime_preflight.py analyze \
  358. --profile core_edit --profile captions --profile qa \
  359. --output work/runtime_preflight.json \
  360. --markdown work/runtime_preflight.md \
  361. --strict
  362. # 可选:查看 GPU / Whisper 建议
  363. python3 scripts/utils.py
  364. # 4. 跑一遍测试套件确认 OK
  365. pytest tests/ # 当前 1259 个测试,约 32 秒
  366. ```
  367. 每天做一条视频的完整模板:**[docs/prompts/15-xhs-daily-tech-video.md](docs/prompts/15-xhs-daily-tech-video.md)**
  368. ---
  369. ## 安装
  370. ### 必装
  371. | 依赖 | 用途 | 装法 |
  372. |---|---|---|
  373. | `ffmpeg` | 一切视频/音频处理 | macOS: `brew install ffmpeg` · Linux: `apt install ffmpeg` |
  374. | `python3` ≥3.10 | 跑脚本 | 系统 / pyenv / brew |
  375. | Whisper | 语音识别 | 见下表 |
  376. ### Whisper 引擎(按平台选一种)
  377. | 平台 | 推荐引擎 | 安装命令 |
  378. |---|---|---|
  379. | **Apple Silicon (M1/M2/M3/M4)** | `mlx-whisper` | `pip install mlx-whisper` |
  380. | **NVIDIA GPU (CUDA)** | `faster-whisper` | `pip install faster-whisper` |
  381. | **Intel / AMD / CPU only** | `faster-whisper` (CPU) | `pip install faster-whisper` |
  382. | **后备** | `openai-whisper` | `pip install openai-whisper` |
  383. 中国用户走清华镜像:
  384. ```bash
  385. pip install mlx-whisper -i https://pypi.tuna.tsinghua.edu.cn/simple
  386. ```
  387. NVIDIA GPU 配置详见本文末尾的 [Linux GPU 配置](#linux-gpu-配置) 段。
  388. ### 可选
  389. | 依赖 | 启用 | 缺时回落 |
  390. |---|---|---|
  391. | `Pillow` | 章节卡 PNG 渲染(auto_chapter_cards) | 不能跑章节卡 |
  392. | `librosa` | BGM 真实节拍检测 | 用 120 bpm 固定网格 |
  393. | `pyyaml` | profile YAML 读取加速 | 用内置 fallback parser |
  394. | `spacy + zh_core_web_sm` | 高级 B-roll 命名实体识别(V3.2+ 路线图) | 用关键词列表匹配 |
  395. ### AI 图像生成(gpt-image-2)
  396. | 运行环境 | 路径 | 凭证 |
  397. |---|---|---|
  398. | **Codex CLI**(推荐) | 用 Codex 内置 `imagegen` 工具,自动路由 gpt-image-2 | **无需** OpenAI API key |
  399. | **Claude Code / 其他** | 用 OpenAI Python SDK(`openai.images.generate`),或任何能调 gpt-image-1.5/2 的工具 | 需要 `OPENAI_API_KEY` |
  400. 生图优先使用 Codex 内置 `image_gen` 工具,即 OpenAI GPT Image 2(`gpt-image-2`)。
  401. 本 skill 只负责**产出提示词**(`imagegen_hint.py`)+ **提供模板库**(`prompts/imagegen_templates.yaml`)—— 不内置 OpenAI 客户端。在 Codex 里 agent 直接调内置 `imagegen`;其他环境用户自行接入。
  402. 完整规则详见 [docs/prompts/19-imagegen.md](docs/prompts/19-imagegen.md)。
  403. ---
  404. ## V3 核心能力
  405. ### 🧠 Semantic Transcript Review — 全篇上下文校稿
  406. [`scripts/semantic_transcript_review.py`](scripts/semantic_transcript_review.py) · [详细文档](docs/prompts/79-semantic-transcript-review.md)
  407. 专业术语、人名、同音字或中英混说较多时,先把 transcript 变成带 previous/next context 的 provider-neutral review packet。任何模型都只能填写 response;`audit` 从源 transcript 推导覆盖率,校验 SHA-256、精确字符范围、最小补丁、数字/标点不变、无重叠/越界,并给每条合法建议生成稳定 proposal id。只有独立 choices 文件绑定相同 `source_sha256 + review_id`,逐项 `approve` / `reject` 后,`apply` 才写 reviewed transcript。
  408. ```bash
  409. python3 scripts/semantic_transcript_review.py prepare \
  410. --transcript work/transcript.json \
  411. --output work/semantic_review_request.json \
  412. --markdown work/semantic_review_request.md
  413. python3 scripts/semantic_transcript_review.py audit \
  414. --transcript work/transcript.json \
  415. --response work/semantic_review_response.json \
  416. --output work/transcript_semantic_review.json \
  417. --markdown work/transcript_semantic_review.md \
  418. --strict
  419. python3 scripts/semantic_transcript_review.py apply \
  420. --transcript work/transcript.json \
  421. --audit work/transcript_semantic_review.json \
  422. --choices work/semantic_review_choices.json \
  423. --output work/transcript_semantic_reviewed.json
  424. ```
  425. 第一次 `audit --strict` 在存在合法建议时返回 2 是预期 gate:还缺人工 choices。成功 apply 会把同一 audit 更新为 `artifact_type=result`、`summary.blocking=0`,并重新分配改动 segment 的词级时间戳。模型 confidence 和 `reviewer` 都不是身份认证或音频事实证明;仍要把输出交给下一节的同步媒体 HTML 听审。
  426. ### 📝 Interactive Transcript Review — 边看视频边校稿
  427. [`scripts/transcript_review.py`](scripts/transcript_review.py) · [详细文档](docs/prompts/36-transcript-review.md)
  428. 转写后、清稿和渲染前,用一个无依赖的本地 HTML 页面逐段核对 ASR:点击时间码让视频跳到对应位置,播放时自动高亮当前 segment,文字可直接行内修改,并支持浏览器自动保存、全文查找替换、review 文本复制/保存和 CPS 阅读压力提示。页面不上传 transcript 或媒体,也不直接覆盖原 JSON;保存出的 `transcript_review.txt` 继续交给既有 `apply` 命令,保留原 segment 时间和可审计变更记录。
  429. ```bash
  430. python3 scripts/transcript_review.py html \
  431. --transcript work/transcript.json \
  432. --video origin/talking.mp4 \
  433. --corrections work/corrections.json \
  434. --output work/transcript_review.html \
  435. --max-cps 20
  436. open work/transcript_review.html
  437. python3 scripts/transcript_review.py apply \
  438. --transcript work/transcript.json \
  439. --review work/transcript_review.txt \
  440. --output work/transcript_reviewed.json
  441. ```
  442. 浏览器不支持直接写文件时会退回下载 `transcript_review.txt`;把它保存/移动到 `work/` 后再运行 `apply`。CPS 标黄只是预渲染提示,最终输出仍应运行 `subtitle_readability_qa.py --strict`。
  443. ### 🛡️ Content Guard — 平台雷区 lint
  444. [`scripts/content_guard.py`](scripts/content_guard.py) · [详细文档](docs/prompts/16-content-guard.md)
  445. 80+ 条 regex 检查 4 类硬性违规 + 3 类软性警告:
  446. | 级别 | 类别 | 例子 |
  447. |---|---|---|
  448. | 🚫 HARD | 广告法极限词 | 最 / 第一 / 唯一 / 万能 / 全网最低 / 遥遥领先 |
  449. | 🚫 HARD | 导流外站 | 微信 / VX / wx / +V / 加微 / QQ / 手机号 / 抖音 / 二维码 |
  450. | 🚫 HARD | 医美/医疗 | 治愈 / 根治 / 祛斑 / 抗衰 / 水光针 / 热玛吉 / 医生同款 |
  451. | 🚫 HARD | 财富诱导 | 年入 X 万 / 躺赚 / 财富自由 / 稳赚不赔 / 零成本 / 暴利 |
  452. | ⚠️ SOFT | 标题/正文 | 标题 >20 字、`!!!` 连用、emoji 占比 >30%、正文 >800 字 |
  453. 被 `render_final.py` / `rewrite_script.py` / `generate_caption.py` 自动调用——HARD 违规导出退出码 2。
  454. ### 📖 Story Engine — 让 AI 按小红书爆款公式重组
  455. [`scripts/rewrite_script.py`](scripts/rewrite_script.py) · [hook 模板](scripts/prompts/hook_templates.yaml) · [CTA 模板](scripts/prompts/cta_templates.yaml)
  456. - **8 个钩子模板**:反常识、痛点共鸣、数字成绩、悬念问句、身份标签、反差对比、利益承诺、场景代入
  457. - **5 个 CTA 模板**:按小红书 CES 权重(关注 8 > 评论/分享 4 > 收藏/点赞 1)排序
  458. - **3 种故事结构**:`pain_solve`(干货)/ `story_reversal`(故事)/ `listicle`(盘点)
  459. - **Hook Variants**:`hook_variants.py` 可先生成 8 个前三秒开头角度、风险检查、推荐排序和 visual cue,再把选中的 hook 放进清稿提示或 `clean_script.md`
  460. 不绑定任何 LLM 提供商——脚本输出 prompt,你可以交给 GPT-5.6 / Claude 等支持结构化 JSON 的模型,再把返回 JSON 喂回脚本验证 + 物化为 `clean_script.md`。
  461. ### 🎬 Auto-Enrich — 自动加 B-roll / 章节卡 / 贴纸 / 强调点 / 卡点
  462. [详细文档](docs/prompts/18-auto-enrich.md)
  463. | 模块 | 触发逻辑 |
  464. |---|---|
  465. | [`auto_broll.py`](scripts/auto_broll.py) | 转折词(但是/然而/关键是/重点来了)/ 实体匹配素材库 / 长镜头守卫 |
  466. | [`auto_chapter_cards.py`](scripts/auto_chapter_cards.py) | `## ` 章节标题 / 静音 ≥1.5s 边界 / Pillow PNG 渲染 |
  467. | [`beat_sync.py`](scripts/beat_sync.py) | BGM → `beat_edit_plan.v1` 时间槽 / Markdown review,或把已有切点做 ±200ms snap;缺 `librosa` 时显式标记固定网格 fallback |
  468. | [`speed_ramp.py`](scripts/speed_ramp.py) | 显式 impact ranges → `speed_ramp_plan.v1` / digest 验证 / 可选插帧 / 音频同步 / 事务式 FFmpeg apply |
  469. | [`freeze_punch.py`](scripts/freeze_punch.py) | impact frame → `freeze_punch_plan.v1` / 定格替换窗口 / anchor crop / 原音频时间线不变 / 事务式 apply + live gate |
  470. | [`video_stabilization.py`](scripts/video_stabilization.py) | 源 hash + exact FFmpeg backend → 稳定工作副本 / 全长 A/B 对照 / 人工确认 gate |
  471. | [`chroma_key.py`](scripts/chroma_key.py) | 绿幕/蓝幕前景 + 图片/视频背景 → composite/matte 预览 / 四项人工复核 / 完整渲染 gate |
  472. | [`auto_stickers.py`](scripts/auto_stickers.py) | 情绪关键词→emoji 池(excited 🚀✨🔥 / doubt 🤔 / data 📈 等) |
  473. | [`auto_emphasis.py`](scripts/auto_emphasis.py) | 问句 / 数字 claim / 转折 / 结论 / 风险提醒 / 停顿恢复 → `emphasis_cues[]` |
  474. | [`auto_enrich.py`](scripts/auto_enrich.py) | 编排上面模块,输出综合 plan JSON(含 emphasis 和 imagegen cues) |
  475. `render_final.py --enrich-plan work/enrich_plan.json` 会把 plan 里的 B-roll、章节卡、贴纸、强调点和已生成图片 cue 自动接回单次渲染;`emphasis_cues[]` 会转成 timed badge 和 marker-free center push-in。`--enrich-plan` 可重复传入,用来叠加 `screen_focus_plan.json` 这类独立计划。没有实际文件的 imagegen cue 会保留为提示,不会阻塞导出。
  476. 音乐视频、产品 montage 或明确要求“按 BGM 卡点”时,可先让 `beat_sync.py` 从音乐直接生成剪辑骨架:
  477. ```bash
  478. python3 scripts/beat_sync.py \
  479. --bgm origin/bgm.mp3 \
  480. --generate-plan \
  481. --duration 30 \
  482. --beats-per-cut 4 \
  483. --min-segment 0.75 \
  484. --max-segment 3 \
  485. --output work/beat_edit_plan.json \
  486. --markdown work/beat_edit_plan.md
  487. ```
  488. 默认每 4 拍提出一个 program-time 切点,最短/最长镜头守卫会改选附近 beat;找不到合适 beat 才写入 `duration_guard`。输出只定义 `cut_times[]`、`segments[]` 和逐切点 evidence,不选择素材、不渲染、不修改源文件。`detection.method=fallback_grid` 时状态为 `review`,必须实际听音乐复核;确认后再把素材映射进 `render_config`、EDL 或 OTIO。已有 cut times 继续使用 `--cuts ... --window 0.2`。
  489. ### 🧭 Video Stabilization — source-bound 手持防抖
  490. [`scripts/video_stabilization.py`](scripts/video_stabilization.py) · [详细文档](docs/prompts/84-video-stabilization.md)
  491. 手机、运动相机或手持相机出现不想要的高频抖动时,先检查本机后端并把决定写成计划:
  492. ```bash
  493. python3 scripts/video_stabilization.py doctor
  494. python3 scripts/video_stabilization.py plan origin/handheld.mp4 \
  495. --decision stabilize \
  496. --reviewed-by "editor" \
  497. --note "固定机位访谈中的高频手抖,不是有意摇摄" \
  498. --output work/video_stabilization_plan.json \
  499. --markdown work/video_stabilization_plan.md
  500. python3 scripts/video_stabilization.py apply work/video_stabilization_plan.json \
  501. --output work/handheld-stabilized.mp4 \
  502. --comparison verify/handheld-stabilization-compare.mp4 \
  503. --markdown work/video_stabilization_plan.md
  504. ```
  505. `--backend auto` 创建计划时优先两遍 `vidstabdetect + vidstabtransform`;本机缺少它们时才选择 FFmpeg 内置单遍 `deshake`,并把 fallback warning 永久保存在 artifact 中。apply 不会临场换算法,原片永不覆盖,输出还会验证 duration、尺寸和音频存在性。
  506. 用 1× 看完整左原片 / 右稳定版,检查人物、直线、画面四角、镜像边缘和有意 pan;可接受后运行 `confirm ... --reviewed-by "editor" --note "完整 A/B 已看..."`。确认前 `pipeline_manifest.py` 会阻塞,确认后仍实时验证源片、稳定版和 comparison 的 SHA-256。它不能修复滚动快门、运动模糊或失焦;稳定版只作为下游 working copy。
  507. ### 🟩 Chroma Key — source-bound 绿幕 / 蓝幕换背景
  508. [`scripts/chroma_key.py`](scripts/chroma_key.py) · [详细文档](docs/prompts/99-chroma-key.md)
  509. 绿幕、蓝幕或已知纯色幕布素材不再直接套一条 `chromakey` 命令。先绑定前景/背景和参数,并在代表时间点生成合成图与黑白 matte:
  510. ```bash
  511. python3 scripts/chroma_key.py prepare \
  512. --project-dir . \
  513. --foreground origin/presenter-green.mp4 \
  514. --background origin/studio.png \
  515. --output-video output/presenter-studio.mp4 \
  516. --preview-dir verify/chroma_key \
  517. --report work/chroma_key.json \
  518. --markdown work/chroma_key.md
  519. python3 scripts/chroma_key.py review \
  520. --report work/chroma_key.json \
  521. --reviewer "editor" \
  522. --note "早中晚 composite/matte 已看;头发、手、衣物、溢色和背景匹配可接受" \
  523. --edge-quality pass --subject-integrity pass \
  524. --spill-control pass --background-fit pass
  525. python3 scripts/chroma_key.py apply --report work/chroma_key.json --strict
  526. python3 scripts/chroma_key.py verify --project-dir . --report work/chroma_key.json --strict
  527. ```
  528. 默认 `similarity=0.10 / blend=0.08 / despill=0.50`,每次只改一项后重新 `prepare --force`。图片背景保持整段;视频背景从第一帧循环,音轨被忽略,最终声音只沿用前景。`pipeline_manifest.py --require chroma_key --strict` 可把它设为强制 gate。完整渲染后仍要 1× 看完快速动作、头发/手、同色衣物和背景循环接缝;这不是无幕布 AI matting 或逐帧 roto。
  529. ### ⚡ Speed Ramp — source-bound 局部慢动作 / velocity edit
  530. [`scripts/speed_ramp.py`](scripts/speed_ramp.py) · [详细文档](docs/prompts/83-speed-ramp.md)
  531. 动作、产品 reveal、游戏或 montage 需要突出少量 impact moment 时,先用逐帧播放器 / `timeline_view.py` 找 source-time 锚点,再创建计划:
  532. ```bash
  533. python3 scripts/speed_ramp.py plan origin/action.mp4 \
  534. --ramp 4.6,5.0,1,0.25,s_curve \
  535. --hold 5.0,5.8,0.25 \
  536. --ramp 5.8,6.2,0.25,1,ease \
  537. --interpolate-fps 120 \
  538. --output work/speed_ramp_plan.json \
  539. --markdown work/speed_ramp_plan.md
  540. python3 scripts/speed_ramp.py verify work/speed_ramp_plan.json --strict
  541. python3 scripts/speed_ramp.py apply work/speed_ramp_plan.json \
  542. --output work/action-speed-ramped.mp4 \
  543. --receipt work/speed_ramp_apply.json
  544. ```
  545. 计划把 `linear/ease/s_curve/snap` ramp 与 constant hold 编译成连续 source/output pieces,绑定源文件 SHA-256、fps、duration 和 canonical plan id;完整 coverage、速度范围、`source_duration / speed` 和 review contract 都会现场验证。低帧率极慢段会给出 native unique-fps warning;`--interpolate-fps` 使用 FFmpeg motion interpolation,不冒充 AI 生成补帧,也可能产生肢体 / 边缘伪影。apply 先写同目录临时 MP4,成功后才替换目标;默认拒绝覆盖、symlink 和原片自覆盖。
  546. 必须用 1×、带声音播放最终文件,检查 impact frame、曲线手感、插值伪影和极慢音频。局部变速会改变下游时间线:如果已有字幕、章节、cue 或 approval receipt,必须重新生成 / 审批;`pipeline_manifest.py --require speed_ramp_plan --strict` 可把 plan 设为显式 gate。
  547. ### 🥊 Freeze-Punch — source-bound 关键帧定格强调
  548. [`scripts/freeze_punch.py`](scripts/freeze_punch.py) · [详细文档](docs/prompts/101-freeze-punch.md)
  549. 表情峰值、动作落点、产品揭晓或节拍重音需要“定一下再继续”时,先逐帧找准 source-time。一个 `--freeze` 依次写 `起点秒数,持续秒数,缩放[,横向锚点,纵向锚点]`;可重复指定多个不重叠事件:
  550. ```bash
  551. python3 scripts/freeze_punch.py plan origin/reaction.mp4 \
  552. --freeze 4.80,0.80,1.08,0.50,0.42 \
  553. --freeze 9.25,0.45,1.04 \
  554. --delivery work/reaction-freeze-punched.mp4 \
  555. --output work/freeze_punch_plan.json \
  556. --markdown work/freeze_punch_plan.md
  557. python3 scripts/freeze_punch.py apply work/freeze_punch_plan.json
  558. python3 scripts/freeze_punch.py verify work/freeze_punch_plan.json --strict
  559. python3 scripts/pipeline_manifest.py . \
  560. --require freeze_punch_plan --strict
  561. ```
  562. 每个窗口都用窗口第一帧替换原画面,可选 `1.00–1.50×` anchor crop;它不会延长时间线,原音频连续播放,因此现有 source-time 字幕和 cue 不会因这一动作平移。计划创建后在 apply 前保持阻塞;apply 使用同目录临时 MP4、完整解码并原子提升交付件,再把输出 hash 和媒体契约写回同一个计划。源片、计划或交付件字节漂移都会让 live gate 失效。
  563. 必须用 1×、带声音逐个检查 freeze 入口/出口、动作跳跃、主体裁切、放大软化和可见说话人“冻嘴”。正在说话的正脸、需要保留动作连续性的镜头或需要改变总时长的 stylized hold 不应使用;后两类分别改用 speed ramp 或重新设计时间线。渲染后旧的成片 QA、approval receipt 和 publish package 必须重做。
  564. ### 🎧 J-cut / L-cut — source-bound 声画错位转场
  565. [`scripts/audio_transition.py`](scripts/audio_transition.py) · [详细文档](docs/prompts/86-audio-transition.md)
  566. 访谈、场景转换或叙事片需要“下一镜声音先进入”或“画面先切、上一镜声音继续”时,先完成 clip 选择,再逐边界试听并显式建计划:
  567. ```bash
  568. python3 scripts/audio_transition.py plan work/render_config.json \
  569. --transition 1,j_cut,0.40 \
  570. --transition 3,l_cut,0.55 \
  571. --output work/audio_transition_plan.json \
  572. --markdown work/audio_transition_plan.md
  573. python3 scripts/audio_transition.py apply work/audio_transition_plan.json \
  574. --output output/master.mp4 \
  575. --receipt work/audio_transition_apply.json
  576. python3 scripts/audio_transition.py verify work/audio_transition_plan.json \
  577. --receipt work/audio_transition_apply.json \
  578. --strict
  579. ```
  580. J-cut 读取下一 clip 画面入点之前的真实源音频,到视觉切点重新与画面对齐;L-cut 读取上一 clip 出点之后的真实源音频,并让下一 clip 的主音频从 overlap 之后恢复同步。没有足够 handle、L-cut 会意外吞掉下一句开头、config/transcript/source hash 漂移或 compiled timing 被修改都会阻塞。计划存在时,`pipeline_manifest.py` 会 live verify;`edit_brief_plan.py` 也能从“声音先行 / J-cut / 画面先切声音后走”自动路由。
  581. `apply` 通过 `render_final.py --audio-transition-plan` 把画面、错位主音频、字幕、overlay、BGM 和响度链留在同一次 FFmpeg 编码里,并写 source-bound receipt。计划、Markdown、成片和 receipt 默认都拒绝覆盖;有外部 enrich/调色/降噪等 CLI 参数时,应在原 `render_final.py` 命令上追加 plan,而不是丢掉参数改用 wrapper。机器验证不能判断交叠对白是否正确;每个改变边界必须以 1× 在耳机和手机扬声器上试听,确认没有吞字、复读、双人声、click、泵动或环境底噪跳变。
  582. ### 🧱 Project Bootstrap — 项目启动与素材导入
  583. [`scripts/project_bootstrap.py`](scripts/project_bootstrap.py) · [详细文档](docs/prompts/61-project-bootstrap.md)
  584. 借鉴 agent-native 视频工具的 folder-first / safe working copy / project memory 思路,但保持本项目本地 artifact-first:把原始素材目录整理成 `origin/`、`work/`、`output/`、`verify/`、`edit/`,并写出 `source_inventory.json`、`source_inventory.md`、`project.md` 和 `next_steps.md`。
  585. 常用:
  586. ```bash
  587. python3 scripts/project_bootstrap.py \
  588. --source ~/Downloads/raw-shoot \
  589. --project-dir work/day61 \
  590. --title "Day61 launch edit" \
  591. --output work/day61/work/source_inventory.json \
  592. --markdown work/day61/work/source_inventory.md \
  593. --project-note work/day61/project.md \
  594. --strict
  595. ```
  596. 默认 `--mode copy`,会按路径和扩展名把素材归入 `origin/raw`、`origin/broll`、`origin/audio`、`origin/bgm`、`origin/images`、`origin/assets` 或 `origin/sidecars`;同名文件自动加后缀,不覆盖已有文件。`pipeline_manifest.py` 会发现 `source_inventory.json`,需要把素材导入作为 analysis gate 时可加 `--require source_inventory`。脚本不转码、不渲染、不上传,也不调用 LLM 或生成服务。
  597. ### 🩺 Runtime Preflight — 本机工具链能力门禁
  598. [`scripts/runtime_preflight.py`](scripts/runtime_preflight.py) · [详细文档](docs/prompts/115-runtime-preflight.md)
  599. 新项目开始媒体处理前,按实际工作流确认本机能力,避免渲染到一半才发现缺少字幕、HDR、QA 或防抖 filter:
  600. ```bash
  601. python3 scripts/runtime_preflight.py list-profiles
  602. python3 scripts/runtime_preflight.py analyze \
  603. --profile core_edit \
  604. --profile captions \
  605. --profile qa \
  606. --output work/runtime_preflight.json \
  607. --markdown work/runtime_preflight.md \
  608. --strict
  609. python3 scripts/runtime_preflight.py verify \
  610. --report work/runtime_preflight.json --strict
  611. python3 scripts/pipeline_manifest.py . \
  612. --require runtime_preflight --strict
  613. ```
  614. 内置 profile 为 `media_io / core_edit / ping_pong_loop / multicam_switch / video_enhancement / storyboard_animatic / audio_cue_mix / generation_chain_handoff / captions / qa / edge_black_trim / hdr_sdr / stabilization / interlace / remotion`。`ping_pong_loop` 核对 endpoint-dedup filter graph 所需的 `fps/trim/setpts/split/reverse/concat/loop/setsar/format` 与 H.264 编码;`storyboard_animatic` 额外核对 panel scale/pad/crop、CFR、drawtext、concat、音频 trim/pad 和 H.264/AAC;`audio_cue_mix` 核对本地 SFX 与合成音效所需的音频 source/filter、延迟混合、限幅和 PCM/AAC 编码能力;`generation_chain_handoff` 核对 FFprobe、PNG encoder 和逐帧 `select` 提取能力;`missing` 表示可解析清单明确缺组件;`unknown` 表示版本命令或 FFmpeg 清单失败、超时或无法解析,两者都 fail closed。防抖 profile 接受两遍 `vidstabdetect + vidstabtransform` 或明确的单遍 `deshake` fallback;交错处理要求 `idet`,并接受 `bwdif` 或 `yadif`;其他 profile 的必需项全部逐项核验。
  615. 报告绑定所选 profile、Python/FFmpeg/FFprobe/Node 相关版本、FFmpeg component listing 状态、逐能力结果、修复建议与 canonical `report_id`。`verify` 会在当前机器重跑,版本、组件或报告内容漂移后旧 artifact 立即失效。`edit_brief_plan.py` 默认把本步骤排在实际媒体工作前:只转写/抽流使用 `media_io`,渲染使用 `core_edit`,再按字幕、QA、HDR、防抖、交错、Remotion 意图追加 profile。
  616. 该检查不执行真实编码、GPU session 或字体渲染,不能替代项目输入 preflight、媒体 probe、完整解码和最终视听 QA。本轮在当前开发机实测 `core_edit / captions / qa / stabilization / remotion` 可用;`hdr_sdr` 准确报告 `filter:zscale` 缺失并以 strict 退出 2,证明 profile 能在运行 HDR 转换前给出可行动 blocker。
  617. ### 📺 Interlace Conform — 交错 / telecine 检测与逐行工作副本
  618. [`scripts/interlace_conform.py`](scripts/interlace_conform.py) · [详细文档](docs/prompts/116-interlace-conform.md)
  619. 旧广播、DV、DVD/VOB 或采集卡素材出现梳齿、TFF/BFF 场序问题时,先检测再决定处理方式:
  620. ```bash
  621. python3 scripts/interlace_conform.py analyze origin/broadcast.mkv \
  622. --project-dir . \
  623. --output work/interlace_analysis.json \
  624. --markdown work/interlace_analysis.md
  625. python3 scripts/interlace_conform.py plan origin/broadcast.mkv \
  626. --project-dir . \
  627. --mode field \
  628. --parity auto \
  629. --reviewed-by editor \
  630. --note "运动区域持续梳齿,确认是 TFF 真实交错" \
  631. --delivery work/broadcast-progressive.mp4 \
  632. --comparison verify/broadcast-interlace-compare.mp4 \
  633. --output work/interlace_conform_plan.json \
  634. --markdown work/interlace_conform_plan.md
  635. python3 scripts/interlace_conform.py apply work/interlace_conform_plan.json
  636. ```
  637. `analyze` 在头、中、尾运行 `idet`,保存 repeated fields、single/multiple frame 统计、stream 场序、分类理由和限制。`telecine_candidate` 会停止并要求 IVTC;`progressive` 保留原片;`mixed_or_uncertain` 需要逐帧证据与显式 classification override。真实交错默认优先 `bwdif`,不可用时用带 warning 的 `yadif`。`frame` 模式保持帧率,`field` 模式精确加倍有理帧率以保留场时间运动。
  638. apply 只生成项目内 H.264/AAC progressive 工作副本和全长左右 A/B,验证输出场标记、live `idet`、目标帧率、尺寸、时长、音画起止、SHA-256 与全量解码。随后用 `confirm` 记录完整 1× 播放,以及 residual combing、motion smoothness、line detail、field order、audio sync 五项判断。任一项未通过或源片/输出/comparison/FFmpeg 能力漂移时,`pipeline_manifest.py --require interlace_conform_plan --strict` 会阻断。后续剪辑使用新工作副本,`origin/` 原片不覆盖。
  639. ### 🎞️ Frame-rate Conform — VFR 源素材归一
  640. [`scripts/frame_rate_conform.py`](scripts/frame_rate_conform.py) · [详细文档](docs/prompts/112-frame-rate-conform.md)
  641. 手机、屏幕录制或会议软件素材出现可变帧率,或切段后逐渐音画漂移时,先读取全部 decoded frame PTS 并生成新的 CFR 工作副本:
  642. ```bash
  643. python3 scripts/frame_rate_conform.py plan origin/phone.mp4 \
  644. --fps 30 \
  645. --delivery work/phone-cfr.mp4 \
  646. --project-dir . \
  647. --output work/frame_rate_conform_plan.json \
  648. --markdown work/frame_rate_conform_plan.md
  649. python3 scripts/frame_rate_conform.py apply work/frame_rate_conform_plan.json
  650. python3 scripts/frame_rate_conform.py verify work/frame_rate_conform_plan.json --strict
  651. python3 scripts/pipeline_manifest.py . --require frame_rate_conform_plan --strict
  652. ```
  653. 计划保存 source SHA-256、媒体合同、全部 PTS 间隔统计、精确目标有理帧率和 canonical encoding contract。apply 先写同目录临时 H.264/AAC MP4;只有 cadence 恒定且单调、帧数匹配 `duration × fps`、音画起止在容差内、显示尺寸/rotation 正确并完整解码成功时才原子提升。`29.97` 会规范成 `30000/1001`;30/60 fps 仍需按素材运动和平台选择。升帧只复制画面,降帧会丢运动采样。HDR/BT.2020/>8-bit 或明显既有音画 offset 会停止,避免静默改变色彩或同步决定。后续转写、切段、字幕和渲染都改用 `work/phone-cfr.mp4`。
  654. ### ⬛ Edge-black Trim — 首尾黑场安全裁切
  655. [`scripts/black_edge_trim.py`](scripts/black_edge_trim.py) · [详细文档](docs/prompts/119-black-edge-trim.md)
  656. 采集卡、相机预录或转码文件的首尾出现黑场时,可以在进入转写和剪辑前生成新的工作副本:
  657. ```bash
  658. python3 scripts/black_edge_trim.py plan origin/capture.mp4 \
  659. --delivery work/capture-edge-trimmed.mp4 \
  660. --edge-proof verify/capture-edge-proof.mp4 \
  661. --audio-policy silent_only \
  662. --project-dir . \
  663. --output work/black_edge_trim_plan.json \
  664. --markdown work/black_edge_trim_plan.md
  665. python3 scripts/black_edge_trim.py apply work/black_edge_trim_plan.json
  666. ```
  667. 计划用 FFmpeg `blackdetect` 找首尾区间,并在有音轨时用 `silencedetect` 计算确切移除范围的静音覆盖。默认只接受接触源时间线两端的黑场,要求至少 95% 静音,并在内容边界内保留 0.08 秒视觉 padding;中间黑场完整保留。检测结果、source SHA-256、完整 decoded cadence、精确 trim、proof windows 和参数都写进 canonical plan。
  668. apply 对音画使用同一 source-time trim,输出 H.264/yuv420p CFR 和可选 48 kHz stereo AAC。临时交付件与原片边界 proof 通过尺寸、方向、帧率、时长、音画首尾和 `ffmpeg -xerror` 完整解码后才原子提升。完整 1× 播放 proof 与 delivery,确认首尾可见帧、内容覆盖和音频连续,再运行 `confirm` 与 `verify --strict`。黑画面里的声音也确定应删除时可显式使用 `--audio-policy allow_audible`;该模式保留 warning,不能跳过听审。`pipeline_manifest.py --require black_edge_trim_plan --strict` 会现场重跑检测并核对输出、proof 和 review。
  669. ### 🎬 Program Breaks — 长片内部结构断点候选
  670. [`scripts/program_breaks.py`](scripts/program_breaks.py) 对长节目或录制母版中的内部黑场运行 `blackdetect`,对每条音轨运行 `silencedetect`,仅把黑场与**所有音轨静音**的重叠区间列为候选。默认排除距首尾小于 0.5 秒的黑场,重叠至少 0.2 秒;候选点取重叠中点。报告保存原片 SHA-256、每条音轨的静音区间、黑场区间、重叠证据和 Markdown 复核表。
  671. ```bash
  672. python3 scripts/program_breaks.py analyze origin/master.mp4 \
  673. --output work/program_breaks.json --markdown work/program_breaks.md
  674. python3 scripts/program_breaks.py verify work/program_breaks.json
  675. ```
  676. 可用 `--black-min`、`--silence-min`、`--min-overlap`、`--edge-guard`、`--pix-threshold`、`--picture-ratio`、`--silence-noise` 调整检测阈值。脚本只读源片,不剪切或命名节目;无音轨素材会拒绝。`verify` 重跑检测并核对源片、JSON 和 Markdown。候选时间点需逐处正常速度看听,淡入淡出、黑底字幕及有声过场尤其需要人工判断。
  677. ### ↔️ Ping-pong Loop — 短动作正放倒放循环
  678. [`scripts/ping_pong_loop.py`](scripts/ping_pong_loop.py) · [详细文档](docs/prompts/128-ping-pong-loop.md)
  679. 手势、产品旋转、粒子或生成视频里的短动作首尾不闭合时,可以用往返循环替代 hard repeat:
  680. ```bash
  681. python3 scripts/runtime_preflight.py analyze \
  682. --profile ping_pong_loop \
  683. --output work/runtime_preflight.json \
  684. --strict
  685. python3 scripts/ping_pong_loop.py plan origin/gesture.mp4 \
  686. --start 1.20 --end 2.05 --cycles 4 \
  687. --delivery work/gesture-ping-pong.mp4 \
  688. --turnaround-proof verify/gesture-turnaround.mp4 \
  689. --loop-seam-proof verify/gesture-loop-seam.mp4 \
  690. --project-dir . \
  691. --output work/ping_pong_loop_plan.json \
  692. --markdown work/ping_pong_loop_plan.md
  693. python3 scripts/ping_pong_loop.py apply work/ping_pong_loop_plan.json
  694. ```
  695. planner 先把秒数吸附到 decoded CFR 帧网格,再用 `0…N-1,N-2…1` 组成周期;倒放分支不重复首尾端帧,因此折返点和下一周期开头不会平白停一帧。FFmpeg `reverse` 会缓存选区全部解码帧,计划按 `width × height × frames × 4 bytes` 估算工作集,默认超过 2048 MiB 就要求缩短 `--start/--end` 或显式调整上限。源音频固定丢弃,避免静默输出倒放对白或环境声;视觉批准后再进入 BGM/SFX 混音。
  696. apply 输出无声 H.264/yuv420p delivery,以及分别覆盖正→倒折返点和周期尾→周期头的两条正常速度 proof。三份文件的尺寸、帧率、精确 decoded frame count、无音轨合同与完整解码全部通过后才原子提升。完整 1× 播放两条 proof 和 delivery,对 `turnaround_motion / loop_seam_motion / duplicate_hold / framing_integrity / creative_intent` 全部 `pass` 后执行 `confirm`,最后运行 `verify --strict` 与 `pipeline_manifest.py --require ping_pong_loop_plan --strict`。`--duration` 允许末周期被截短并保留 warning;希望交付文件本身是完整循环时使用 `--cycles`。
  697. ### 🧩 Clip Assembly — 多源片段归一拼接
  698. [`scripts/clip_assembly.py`](scripts/clip_assembly.py) · [详细文档](docs/prompts/118-clip-assembly.md)
  699. 片头、主片、生成片和片尾来自不同分辨率、方向、帧率、SAR、时间戳或音频规格时,用 source-bound 计划代替未检查的 concat copy:
  700. ```bash
  701. python3 scripts/clip_assembly.py plan \
  702. origin/intro.mp4 origin/main.mov origin/outro.mp4 \
  703. --width 1080 --height 1920 --fps 30 \
  704. --fit contain --audio-mode fill-silence \
  705. --delivery output/assembled.mp4 \
  706. --boundary-proof verify/clip-assembly-boundaries.mp4 \
  707. --project-dir . \
  708. --output work/clip_assembly_plan.json \
  709. --markdown work/clip_assembly_plan.md
  710. python3 scripts/clip_assembly.py apply work/clip_assembly_plan.json
  711. ```
  712. 脚本在一条 FFmpeg filter graph 内为每段重置 PTS、统一画布、rotation、CFR、SAR 1:1、`yuv420p` 和 48 kHz stereo,再 hard cut 成 H.264/AAC MP4;至少一段有声音时,无音轨片段默认补等长静音,也可用 `--audio-mode drop` 明确输出无声版。已有音轨与视频首尾失配、HDR/BT.2020/>8-bit、路径逃逸或重复源会在计划阶段停止。
  713. apply 只有在总时长、尺寸、帧率、decoded cadence、SAR、音画首尾、codec/pixel format、SHA-256 和 `-xerror` 全量解码通过后才原子提升交付件。它还会从确切输出按顺序抽取所有接缝窗口,生成一条正常速度 proof。完整看完 delivery 和 proof 后,用 `confirm` 记录 clip order、visual seams、frame continuity、audio seams、complete coverage,再用 `verify --strict` 或 `pipeline_manifest.py --require clip_assembly_plan --strict` 放行。该工具只做 hard cut,不判断语义连续性,也不替代 J-cut/L-cut 或最终完整审片。
  714. ### 🧭 Edit Brief Plan — 自然语言剪辑需求路由
  715. [`scripts/edit_brief_plan.py`](scripts/edit_brief_plan.py) · [详细文档](docs/prompts/64-edit-brief-plan.md)
  716. 借鉴 GitHub 上视频 skill / MCP 项目的“用户自然语言 → agent 选工具、排顺序、留 checkpoint”的优点,但保持本项目轻量:只做本地确定性路由,输出 `edit_brief_plan.v1` JSON 和 Markdown runbook,不调用 LLM、不渲染、不上传、不提交付费生成任务。
  717. 常用:
  718. ```bash
  719. python3 scripts/edit_brief_plan.py \
  720. --brief "把 origin/interview.mp4 剪成三条抖音短视频,去停顿,加B-roll、BGM和字幕,最后生成发布包" \
  721. --project-dir . \
  722. --output work/edit_brief_plan.json \
  723. --markdown work/edit_brief_plan.md \
  724. --strict
  725. ```
  726. 它会识别 `origin/interview.mp4` 这类源素材路径、目标平台、交错/telecine、VFR/CFR 源素材归一、hard repeat、正放倒放 ping-pong loop、多源视频拼接、手持防抖、绿幕/蓝幕换背景、目标脚本对齐、多 take、长视频拆条、批量短视频、字幕、B-roll、BGM、去停顿、J-cut/L-cut、生成素材、PIP、调色、QA、发布包等信号,并把它们映射到已有脚本,例如 `interlace_conform.py`、`frame_rate_conform.py`、`ping_pong_loop.py`、`clip_assembly.py`、`video_stabilization.py`、`chroma_key.py`、`script_alignment.py`、`highlight_picker.py`、`shorts_batch.py`、`jump_cut.py`、`audio_transition.py`、`auto_enrich.py`、`render_final.py`、`render_qa.py` 和 `publish_package.py`。交错路由会先生成 `work/source-progressive.mp4`;VFR 路由再把验证后的 `work/source-cfr.mp4` 传给后续步骤;ping-pong 路由保留动作区间占位符并替代普通 hard repeat;拼接路由留下按最终顺序填写的多源占位符,brief 没有明确 30/60/NTSC rate 时保留 `<target_fps>`。`pipeline_manifest.py` 会发现 `edit_brief_plan.json`;当 `summary.blocking > 0`(例如 brief 为空或显式 source 缺失)时会作为 blocker,也可以用 `--require edit_brief_plan` 把需求路由作为 analysis gate。
  727. ### 🛂 Production Authorization — 确切范围生产授权
  728. [`scripts/production_authorization.py`](scripts/production_authorization.py) · [详细文档](docs/prompts/97-production-authorization.md)
  729. 涉及外部上传、改变原始叙事顺序/删除内容、付费生成、声音克隆、真人/未成年人/公众人物/品牌/IP 或直接发布时,先把动作写成 `production_authorization_scope.v1`。每项包含具体项目内素材、用途、exact provider/surface、潜在 cost/quota 和权利对象;脚本不会从聊天、公开素材或含糊的“继续”推断同意。
  730. ```bash
  731. python3 scripts/production_authorization.py prepare \
  732. --project-dir . \
  733. --scope work/production_authorization_scope.json \
  734. --output work/production_authorization_request.json \
  735. --markdown work/production_authorization_request.md \
  736. --response-template work/production_authorization_response.json \
  737. --strict
  738. # 逐项填写 response 的 approve/reject、note、rights basis 和 evidence_note 后:
  739. python3 scripts/production_authorization.py audit \
  740. --project-dir . \
  741. --request work/production_authorization_request.json \
  742. --response work/production_authorization_response.json \
  743. --output work/production_authorization.json \
  744. --markdown work/production_authorization.md \
  745. --strict
  746. python3 scripts/production_authorization.py verify \
  747. --project-dir . \
  748. --report work/production_authorization.json \
  749. --strict
  750. ```
  751. `prepare` 绑定 scope 与源素材的路径、大小、SHA-256;`audit` 要求所有 action/right 完整决定,reject 或缺决定都会阻塞;`verify` 重读 scope、源素材、request、response 并重算报告。`pipeline_manifest.py --require production_authorization --strict` 可把它变成正式 gate。它只保存本地、自报的复核记录,不执行任何获批动作,也不是身份认证、数字签名、法律意见或真实授权文件的替代品。
  752. ### 👁️ Video Understanding — 抽样帧 + 可选 YOLO 检测
  753. [`scripts/video_understanding.py`](scripts/video_understanding.py) · [详细文档](docs/prompts/47-video-understanding.md)
  754. 为口播、访谈、产品演示和户外素材补上结构化视觉线索:先按时间和场景边界抽帧;需要时再用 Ultralytics YOLO 识别人、手机、电脑、屏幕、车辆、杯子等常见对象;最后输出可审计的 `video_understanding.v1`。
  755. 常用:
  756. ```bash
  757. python3 scripts/video_understanding.py origin/talk.mp4 \
  758. --output work/video_understanding.json \
  759. --markdown work/video_understanding.md
  760. pip install ultralytics
  761. python3 scripts/video_understanding.py origin/talk.mp4 \
  762. --scene-boundaries work/scene_boundaries.json \
  763. --detector yolo \
  764. --model yolo11n.pt \
  765. --output work/video_understanding.json \
  766. --markdown work/video_understanding.md \
  767. --strict
  768. ```
  769. 输出可以直接交给 `smart_reframe.py --detections` 做主体感知裁切,也可以交给 `privacy_redact.py --detections` 做隐私遮挡计划。`ultralytics` 不是必装依赖;没有 detector 时仍然能生成抽样帧和 review shell。
  770. ### 🧩 Takes Pack — 多 take phrase-level 阅读视图
  771. [`scripts/takes_pack.py`](scripts/takes_pack.py) · [详细文档](docs/prompts/60-takes-pack.md)
  772. 借鉴 `browser-use/video-use` 把 phrase-level transcript 作为主要阅读视图、并保留音频事件的做法,但保持本项目 artifact-first:只读本地 `transcript.json`,输出 `takes_packed.md` 和可选 `takes_pack.json`,不转写、不渲染、不调用 LLM。除现有 `segments[].words[]` 外,也可直接读取 ElevenLabs Scribe 风格的顶层 `words[]`;`speaker_id` 会参与分段,`audio_event` 会作为带时间码的笑声、掌声、叹气或音乐剪辑节拍保留。
  773. 常用:
  774. ```bash
  775. python3 scripts/takes_pack.py \
  776. --transcript take1=work/take1_transcript.json \
  777. --transcript take2=work/take2_transcript.json \
  778. --output work/takes_packed.md \
  779. --json work/takes_pack.json \
  780. --break-gap 0.5
  781. ```
  782. `takes_packed.md` 按 source 分组列出 `take1-003` 这类 phrase id、源时间码、speaker、segment ids、audio events 和压缩文本,适合先比较多个 take 的表达质量,也能避免在笑点、掌声或反应声中间误切。`takes_pack.json` 还会给每个事件保留 label/start/end;确认后的 time range 可继续交给 `highlight_picker.py`、`srt_edit_plan.py`、`render_config.json` 或 EDL/FCPXML/OTIO。`pipeline_manifest.py` 会发现 `takes_pack.json`,但默认不把它作为 blocker;需要强制多 take review 时可加 `--require takes_pack`。
  783. ### 🧭 Target Script Alignment — 按确认稿从多 take 装配原话
  784. [`scripts/script_alignment.py`](scripts/script_alignment.py) · [详细文档](docs/prompts/78-script-alignment.md)
  785. 客户、编导或 Agent 已经确认成片稿时,不必再靠人工逐条找时间码。`script_alignment.py` 把目标稿按行/句拆成 spoken units,在一份或多份 reviewed transcript 中搜索词级/segment 边界候选,输出稳定 candidate id、原话、source time、透明 score breakdown 和前三名备选;最终 `render_config.json` 按目标稿顺序排列,即使素材原始录制顺序不同也能重组。
  786. 第一次运行:
  787. ```bash
  788. python3 scripts/script_alignment.py \
  789. --target-script work/target_script.md \
  790. --transcript take-a=work/takes/take-a_transcript_reviewed.json \
  791. --transcript take-b=work/takes/take-b_transcript_reviewed.json \
  792. --media take-a=origin/take-a.mp4 \
  793. --media take-b=origin/take-b.mp4 \
  794. --output work/script_alignment.json \
  795. --markdown work/script_alignment.md \
  796. --render-config work/render_config.json \
  797. --clean-script work/clean_script.md \
  798. --strict
  799. ```
  800. 默认 65 分以下不采用、65-82 分要求 review;即使分数更高,只要前两名相差不超过 3 分,也会以 `ambiguous_match` 阻塞,避免同文案多个 take 被静默选错。人工看/听候选后,把 `target-001 -> candidate id` 写进 `--choices work/script_alignment_choices.json` 再跑一次。显式 choice 能解决低分/同分歧义,但不会绕过源素材缺失或时间段重复占用。该脚本不调用 LLM、不改源文件、不判断表演和画面质量;大幅同义改写仍需要人工语义判断或补录。`pipeline_manifest.py` 会发现此报告,只要 `summary.blocking > 0` 就阻塞,也支持 `--require script_alignment`。
  801. ### 🎞️ Adaptive Scene Boundaries — 运动镜头自适应切点
  802. [`scripts/scene_boundaries.py`](scripts/scene_boundaries.py) · [详细文档](docs/prompts/32-scene-boundaries.md)
  803. 固定 scene score 阈值对静态访谈很直接,但持续摇镜、游戏画面、手持走拍或高运动 B-roll 可能整段都高于阈值。`--method adaptive` 会读取每帧 FFmpeg scene score,把目标帧与前后邻域均值比较,同时保留绝对 `--min-scene-score` 门槛;真正的局部峰值才进入 `boundaries[]`,每个保留切点还会在 `boundary_evidence[]` 记录 score、adaptive ratio 和邻域均值。
  804. ```bash
  805. python3 scripts/scene_boundaries.py origin/long-talk.mp4 \
  806. --method adaptive \
  807. --adaptive-threshold 3.0 \
  808. --min-scene-score 0.15 \
  809. --min-scene-duration 1.0 \
  810. --output work/scene_boundaries.json \
  811. --markdown work/scene_boundaries.md
  812. ```
  813. 先看 Markdown 的 cut evidence,再把 JSON 交给 `highlight_picker.py --scene-boundaries`、`video_understanding.py --scene-boundaries` 或 `retention_rhythm_qa.py --scene-boundaries`。固定机位素材、旧项目复现或已经调好阈值的流程继续用 `--method fixed --threshold 0.35`,默认行为保持兼容。
  814. ### 🔎 Highlight Picker — 长视频精华候选 / brief 定向找片段
  815. [`scripts/highlight_picker.py`](scripts/highlight_picker.py) · [详细文档](docs/prompts/31-highlight-picker.md)
  816. 长视频拆短视频时,先从 `transcript.json` 生成可发布候选,输出透明 `score`、`signals`、`warnings`、`hook_text`、`reason` 和可选 `render_config`。默认模式会找 hook/value/duration 表现好的短视频片段;如果用户已经知道要找什么,加 `--brief` 或 `--query` 做 prompt-based clipping。
  817. 常用:
  818. ```bash
  819. python3 scripts/highlight_picker.py \
  820. --transcript work/long_transcript.json \
  821. --brief "产品发布 用户反应 价格对比" \
  822. --scene-boundaries work/scene_boundaries.json \
  823. --video origin/long-talk.mp4 \
  824. --output work/brief_highlights.json \
  825. --markdown work/brief_highlights.md \
  826. --render-config work/brief_render_config.json \
  827. --platform douyin \
  828. --num-clips 3 \
  829. --strict
  830. ```
  831. `--brief` 会把自然语言意图拆成英文关键词和中文短语片段,写入每条 candidate 的 `brief_match.score` 与 `matched_terms`,但仍保留原来的自包含结尾、弱 hook、时长偏离等 warning。适合“找产品 reveal / 用户强反应 / 教程关键步骤 / 失败教训”这类定向剪片。
  832. ### 🎧 Audio Boundary Snap — 词/句末/静音剪辑边界校正
  833. [`scripts/audio_boundary_snap.py`](scripts/audio_boundary_snap.py) · [详细文档](docs/prompts/65-audio-boundary-snap.md)
  834. 在 `highlight_picker.py` 已经选好内容以后,用 transcript 词级时间戳把每条 start/end 对齐到完整词,必要时把结尾扩到附近句号、问号或感叹号;如果 transcript 已有 `silences[]`,或提供 `--media` 让 FFmpeg 跑 `silencedetect`,还会优先把切点放到相邻静音区中点。每条调整都会保留原始时间、前后 delta、首尾词、reason、warning 和 blocker,不渲染也不改源文件。
  835. 常用:
  836. ```bash
  837. python3 scripts/audio_boundary_snap.py \
  838. --candidates work/highlight_candidates.json \
  839. --transcript work/long_transcript.json \
  840. --media origin/long-talk.mp4 \
  841. --output work/audio_boundary_plan.json \
  842. --markdown work/audio_boundary_plan.md \
  843. --strict
  844. python3 scripts/shorts_batch.py \
  845. --highlights work/audio_boundary_plan.json \
  846. --video origin/long-talk.mp4 \
  847. --output work/shorts_batch.json \
  848. --strict
  849. ```
  850. 支持 Whisper `segments[].words[]` 和 ElevenLabs Scribe 风格顶层 `words[]`,其中 spacing/audio event 不会当成词。没有词级时间戳、候选时间非法、源媒体缺失或安全边界超出平台时长时,`summary.blocking` 会非零;`pipeline_manifest.py --require audio_boundary_plan --strict` 可把它设为显式 gate。
  851. ### 🎞️ Shorts Batch — 多条精华短视频渲染 job sheet
  852. [`scripts/shorts_batch.py`](scripts/shorts_batch.py) · [详细文档](docs/prompts/63-shorts-batch.md)
  853. 借鉴 AI shorts 类项目“长视频一次上传,产出多条可追踪短视频”的做法,但保持本项目本地优先:读取 `highlight_picker.py` 的 `highlight_candidates.v1` 或 `audio_boundary_snap.py` 的 `audio_boundary_plan.v1`,为每条 selected highlight 写一份独立 `render_config`,并输出 `shorts_batch.v1` JSON、Markdown job sheet、`render_final.py` 命令和 `render_qa.py` 命令。脚本不渲染、不上传、不调用 LLM。
  854. 常用:
  855. ```bash
  856. python3 scripts/shorts_batch.py \
  857. --highlights work/highlight_candidates.json \
  858. --video origin/long-talk.mp4 \
  859. --output work/shorts_batch.json \
  860. --markdown work/shorts_batch.md \
  861. --render-config-dir work/shorts_render_configs \
  862. --output-dir output/shorts \
  863. --qa-dir verify/shorts \
  864. --basename day63 \
  865. --platform douyin \
  866. --strict
  867. ```
  868. 输出后先打开 `work/shorts_batch.md` 看每条 job 的 hook、ending 和 warnings;确认后逐条运行表内 `render_shell`,再运行 `qa_shell` 生成 QA JSON/复核包。`pipeline_manifest.py` 会发现 `shorts_batch.json`;当 batch 自身有 `summary.blocking > 0`(例如源视频缺失)时会作为可见 blocker。
  869. ### 🎨 Color Grade — 可审计调色计划
  870. [`scripts/color_grade.py`](scripts/color_grade.py) · [详细文档](docs/prompts/48-color-grade.md)
  871. 借鉴 agent 视频编辑工具对 color grading / filters 的重视,但保持本项目的单次编码原则:先生成 bounded `color_grade.v1` 调色计划和 Markdown review,最终由 `render_final.py --color-grade` 在字幕前接入同一条 FFmpeg filter graph。
  872. 常用:
  873. ```bash
  874. python3 scripts/color_grade.py \
  875. --preset screen \
  876. --output work/color_grade.json \
  877. --markdown work/color_grade.md
  878. python3 scripts/render_final.py \
  879. --config work/render_config.json \
  880. --color-grade work/color_grade.json \
  881. --output output/tutorial_master.mp4
  882. ```
  883. 内置 `natural`、`warm`、`cool`、`punchy`、`soft`、`cinematic`、`screen` 七个 preset;自定义 `brightness`、`contrast`、`saturation`、`gamma`、`temperature`、`tint`、`sharpness` 会被限制在保守范围内,`--strict` 在参数被 clamp 时返回 2。若主片已经渲染完,也可以用 `color_grade.py --input output/master.mp4 --render-output output/master_grade.mp4` 做单独复版;日常推荐仍是在 `render_final.py` 里一次编码完成。
  884. 已有 `.cube` 调色文件可用 [`scripts/lut_grade.py`](scripts/lut_grade.py) 验证并接入同一个 `--color-grade` 入口:
  885. ```bash
  886. python3 scripts/lut_grade.py plan assets/look.cube --output work/lut_grade.json
  887. python3 scripts/lut_grade.py verify work/lut_grade.json
  888. python3 scripts/render_final.py --config work/render_config.json \
  889. --color-grade work/lut_grade.json --output output/master.mp4
  890. ```
  891. 计划记录 LUT 绝对路径、大小、SHA-256 和插值方式(默认 `tetrahedral`,可用 `--interpolation` 调整);创建计划和渲染前都会用 FFmpeg 实测可加载性。文件或计划改动后需重新规划。为了避免 FFmpeg filtergraph 路径歧义,LUT 路径不能含冒号、逗号、分号、引号、反斜杠或方括号;先复制到路径简单的项目素材目录。LUT 改色需要人工看肤色、品牌色和过曝区域,并在最终成片运行 `shot_color_qa.py`。
  892. ### 🔬 Shot Color QA — 成片镜头色彩 / 曝光门禁
  893. [`scripts/shot_color_qa.py`](scripts/shot_color_qa.py) · [详细文档](docs/prompts/81-shot-color-qa.md)
  894. `color_grade.py` 负责渲染前的 bounded look,`shot_color_qa.py` 则在**最终编码文件**上按镜头复查实际结果。它用 FFmpeg `signalstats` 每秒默认抽 2 帧,对每个镜头聚合 `YLOW/YAVG/YHIGH`、U/V、`SATAVG` 和 `BRNG` 中位数,列出持续过暗/过亮、低对比、高饱和、broadcast-range 越界,以及相邻镜头的亮度/色度跳变。
  895. ```bash
  896. python3 scripts/shot_color_qa.py output/day81_master.mp4 \
  897. --output output/verify/day81_shot_color_qa.json \
  898. --markdown output/verify/day81_shot_color_qa.md \
  899. --strict
  900. # 已有 scene_boundaries.v1 时可复用同一场景时间轴
  901. python3 scripts/shot_color_qa.py output/day81_master.mp4 \
  902. --scene-boundaries work/scene_boundaries.json \
  903. --output output/verify/day81_shot_color_qa.json \
  904. --markdown output/verify/day81_shot_color_qa.md \
  905. --strict
  906. ```
  907. 视觉跳变默认只 WARN,因为地点、日夜、图形/实拍或刻意 look 的变化可能完全合理;非 full-range 输出的持续 `BRNG` 越界和未覆盖镜头默认 BLOCK。需要把极暗/极亮或跳变作为当前项目的强人工门禁,可加 `--fail-on-extremes` / `--fail-on-jumps`。Markdown 会为可疑切点生成 `timeline_view.py` 命令;确认后应回到源 timeline / 调色计划重渲染,避免对 master 反复压缩。`pipeline_manifest.py --require shot_color_qa --strict` 可强制发布前存在报告;这是 SDR 社媒输出的轻量统计,不是校准 scopes、HDR proof、白平衡/肤色判断或审美评分。
  908. ### 🎧 Audio Cue Sheet — BGM / SFX 音频设计清单
  909. [`scripts/audio_cue_sheet.py`](scripts/audio_cue_sheet.py) · [详细文档](docs/prompts/43-audio-cue-sheet.md)
  910. 借鉴 OpenMontage / vibeframe / Claude Code Video Toolkit 这类 agentic video 项目对 narration、music、SFX、成本和 review report 的一等公民设计,但保持本项目轻量:只读 transcript 和本地素材目录,不生成音乐、不提交 TTS、不消耗 provider credits。
  911. 常用:
  912. ```bash
  913. python3 scripts/audio_cue_sheet.py \
  914. --transcript work/transcript.json \
  915. --asset-root media/bgm \
  916. --asset-root media/sfx \
  917. --output work/audio_cue_sheet.json \
  918. --markdown work/audio_cue_sheet.md
  919. python3 scripts/audio_cue_sheet.py \
  920. --transcript work/transcript.json \
  921. --asset-root media \
  922. --require-local-music \
  923. --require-local-sfx \
  924. --output work/audio_cue_sheet.json \
  925. --markdown work/audio_cue_sheet.md \
  926. --strict
  927. ```
  928. 输出 `audio_cue_sheet.v1`:`voice_track` 记录主口播响度目标,`music[]` 给出全片 BGM mood / BPM / prompt / 本地候选或生成需求,`sfx[]` 根据“但是 / 重点 / 完成 / 风险”等触发词排 whoosh、ping、chime、warning tick。`--strict` 会在要求本地 BGM/SFX 但素材缺失时返回 2;`pipeline_manifest.py` 会自动识别 `audio_cue_sheet.json` 并把 `summary.blocking > 0` 列为 blocking gate。
  929. 选好 BGM 后,可让实际渲染兑现 cue sheet 里的 ducking 要求:
  930. ```json
  931. {
  932. "bgm": "media/bgm/tech-pulse.mp3",
  933. "bgm_volume": 0.15,
  934. "bgm_fade_out": 3.0,
  935. "bgm_ducking": true
  936. }
  937. ```
  938. 也可给 `render_final.py` 加 `--bgm-ducking` 临时启用。它会用最终旁白轨触发 FFmpeg `sidechaincompress`,在说话时动态压低 BGM,在封面、停顿和片尾无旁白时恢复;默认 threshold `0.03`、ratio `8`、attack `20ms`、release `500ms`。旧配置默认关闭以保持兼容,配置已开启时可用 `--no-bgm-ducking` 覆盖。详细参数与试听检查见 [背景音乐、旁白 Ducking 和片尾](docs/prompts/09-bgm-endcard.md)。
  939. ### Audio Cue Mix — 把 SFX cue 落成 source-bound 单轨
  940. [`scripts/audio_cue_mix.py`](scripts/audio_cue_mix.py) · [详细文档](docs/prompts/123-audio-cue-mix.md)
  941. `audio_cue_sheet.py` 负责规划,这一步负责实际混音。它绑定 cue sheet、最终独立旁白、本地音效和目标输出;缺少 `transition_whoosh / emphasis_ping / success_chime / warning_tick` 时,可显式使用 `--synthesize-missing` 走确定性 FFmpeg 配方。未知类别、素材丢失、cue 越过旁白末尾或非法增益都会阻塞。
  942. ```bash
  943. python3 scripts/audio_cue_mix.py plan \
  944. --project-dir . \
  945. --cue-sheet work/audio_cue_sheet.json \
  946. --voice work/final_narration.wav \
  947. --delivery work/audio_cue_mix.wav \
  948. --synthesize-missing \
  949. --output work/audio_cue_mix.json \
  950. --markdown work/audio_cue_mix.md
  951. python3 scripts/audio_cue_mix.py apply \
  952. --plan work/audio_cue_mix.json \
  953. --markdown work/audio_cue_mix.md
  954. python3 scripts/audio_cue_mix.py confirm \
  955. --plan work/audio_cue_mix.json \
  956. --reviewed-by editor \
  957. --note "完整试听;音效落点和电平都不遮挡人声。" \
  958. --full-playback completed \
  959. --speech-intelligibility pass \
  960. --cue-timing pass \
  961. --sfx-level pass \
  962. --creative-fit pass \
  963. --clicks-or-clipping pass \
  964. --markdown work/audio_cue_mix.md \
  965. --strict
  966. python3 scripts/audio_cue_mix.py verify \
  967. --plan work/audio_cue_mix.json \
  968. --markdown work/audio_cue_mix.md \
  969. --strict
  970. ```
  971. 每个音效会统一到 48 kHz stereo,按 cue trim/pad、短 fade、受限增益和毫秒级 `adelay` 进入时间线;`amix normalize=0` 不会因为音效数量增加而自动压低旁白,limiter 只做峰值保护。输出在完整解码后原子提升。必须正常速度听完整条旁白 + SFX,并确认人声清晰、落点、电平、创意适配和无 click/clipping;任何输入、计划、输出或 review 绑定漂移都会让 `pipeline_manifest.py --require audio_cue_mix --strict` 重新阻塞。
  972. 这条单轨不含 BGM;音乐继续走现有 `render_final.py --bgm-ducking`。混入音乐后仍需完整 1× 看听成片,并运行最终响度、声道和掉点 QA。
  973. ### 🎚️ Final Audio Storyboard — 锁定视觉 EDL 后重建声音
  974. [`scripts/final_audio_storyboard.py`](scripts/final_audio_storyboard.py) · [详细文档](docs/prompts/95-final-audio-storyboard.md)
  975. `audio_cue_sheet.py` 适合剪辑前从 transcript 规划音乐与 SFX;视觉选段被删短或重排后,最终声音必须改用 EDL 的 `record_start / record_end`。新脚本把 `export_edl.py` JSON manifest 与原 `storyboard_plan.v1` 绑定,要求每个 event label 映射到 storyboard shot,并对所有保留段与完全删除的 story beat 做明确声音决定。
  976. ```bash
  977. python3 scripts/final_audio_storyboard.py prepare \
  978. --project-dir . \
  979. --edl work/locked_visual.edl.json \
  980. --storyboard work/storyboard_plan.json \
  981. --output work/final_audio_storyboard_request.json \
  982. --markdown work/final_audio_storyboard_request.md \
  983. --response-template work/final_audio_storyboard_response.json \
  984. --strict
  985. # 填完 response:
  986. python3 scripts/final_audio_storyboard.py audit \
  987. --project-dir . \
  988. --request work/final_audio_storyboard_request.json \
  989. --response work/final_audio_storyboard_response.json \
  990. --output work/final_audio_storyboard.json \
  991. --markdown work/final_audio_storyboard.md \
  992. --strict
  993. python3 scripts/final_audio_storyboard.py verify \
  994. --project-dir . \
  995. --report work/final_audio_storyboard.json \
  996. --strict
  997. ```
  998. response 固定 `single_track / sectioned_tracks / stems` 策略、跨段 tone、最终时间线 section、voice ledger、stem 类型和原生声音保留理由。每个删掉的 beat 必须标成 `remove / rewrite_into_adjacent / offscreen_bridge`;重复 voiced line、漏填段落、时间字段手改、EDL/storyboard/source/response/report 漂移都会 fail closed。脚本不生成音频、不消费 credits,也不把 JSON 冒充 provider prompt;批准后仍应按目标音频工具的规则改写成 timed cue sheet。`pipeline_manifest.py --require final_audio_storyboard --strict` 可设为发布门禁。
  999. ### 🎞️ Storyboard Plan — 分镜、时长预演、故事公式、镜头接力与生成路由
  1000. [`scripts/storyboard_plan.py`](scripts/storyboard_plan.py) · [`scripts/storyboard_animatic.py`](scripts/storyboard_animatic.py) · [`scripts/reference_story_formula.py`](scripts/reference_story_formula.py) · [`scripts/sequence_handoff.py`](scripts/sequence_handoff.py) · [`scripts/video_prompt_pack.py`](scripts/video_prompt_pack.py) · [`scripts/generation_reference_preflight.py`](scripts/generation_reference_preflight.py) · [`scripts/storyboard_assets.py`](scripts/storyboard_assets.py) · [分镜文档](docs/prompts/24-storyboard-plan.md) · [时长预演文档](docs/prompts/121-storyboard-animatic.md) · [参考片故事公式文档](docs/prompts/125-reference-story-formula.md) · [镜头接力文档](docs/prompts/120-sequence-handoff.md) · [视频提示词包文档](docs/prompts/45-video-prompt-pack.md) · [多模态参考门禁文档](docs/prompts/122-generation-reference-preflight.md) · [素材清单文档](docs/prompts/25-storyboard-assets.md)
  1001. 借鉴 GitHub 上视频生成类项目的 storyboard / shot continuity / provider routing 思路,但保持本项目的轻量原则:脚本只做本地规划,不提交任何付费生成任务。
  1002. | 输出 | 说明 |
  1003. |---|---|
  1004. | `storyboard_plan.json` | 每个 shot 的时间码、source segments、section、narration、keywords、visual first/motion/last frame |
  1005. | `generation_route` | `codex_imagegen` / `dreamina_video` / `remotion_hyperframes` / `media_library_broll` + fallback + why |
  1006. | `continuity.anchors` | 系列色彩、比例、字幕安全区、上一镜头引用、关键词线索 |
  1007. | `storyboard_plan.md` | 适合人工 review 的 shot cards,含 prompt 和检查项 |
  1008. | `storyboard_animatic.json/mp4` | 绑定分镜、每镜静帧和可选旁白的 timed preview、完整播放决定与 live gate |
  1009. | `reference_story_formula.json` | 绑定参考片、timecoded transcript 与目标分镜的情绪/叙事机制、观众状态迁移、逐镜 content anchor、复制排除合同和 live gate |
  1010. | `sequence_handoff.json` | 每个相邻 shot 的 offer/receive、载体、edit type、轴线/方向、音频桥、edit handles、风险、fallback 与 source-bound review |
  1011. | `video_prompt_pack.json` | 每个 shot 的 Dreamina/即梦 Seedance、Veo、LTX、Wan、Sora 提示词、故事公式、接力合同、参考图路径、负面提示词和审批状态 |
  1012. | `reference_frame_preflight.json` | image-to-video 首帧和共享 style key 的存在性、解码、尺寸、方向、画幅、透明背景 gate |
  1013. | `generation_reference_preflight.json` | 图片/视频/音频 references 的有序标签、窄角色、排除项、媒体探测、provider 限额、source/profile 绑定与提交 prompt |
  1014. | `storyboard_assets.json` | 每个 shot 对应素材是否 ready、需要生成/审批/渲染/搜索;B-roll 可带 `candidate_scores` 排名理由 |
  1015. 常用:
  1016. ```bash
  1017. python3 scripts/storyboard_plan.py \
  1018. --transcript work/transcript.json \
  1019. --clean-script work/clean_script.md \
  1020. --output work/storyboard_plan.json \
  1021. --markdown work/storyboard_plan.md \
  1022. --max-shots 8 \
  1023. --target-aspect 9:16
  1024. python3 scripts/storyboard_animatic.py plan \
  1025. --project-dir . \
  1026. --storyboard work/storyboard_plan.json \
  1027. --panel shot_001=work/storyboard/shot_001.png \
  1028. --panel shot_002=work/storyboard/shot_002.png \
  1029. --audio work/narration.wav \
  1030. --delivery verify/storyboard_animatic.mp4 \
  1031. --output work/storyboard_animatic.json \
  1032. --markdown work/storyboard_animatic.md
  1033. python3 scripts/storyboard_animatic.py apply work/storyboard_animatic.json
  1034. # 完整 1× 播放后执行 confirm,再运行 verify --strict。
  1035. python3 scripts/reference_story_formula.py prepare \
  1036. --project-dir . \
  1037. --reference-video origin/reference.mp4 \
  1038. --reference-transcript origin/reference_transcript.json \
  1039. --target-storyboard work/storyboard_plan.json \
  1040. --beat-count 5 \
  1041. --output work/reference_story_formula_request.json \
  1042. --markdown work/reference_story_formula_request.md \
  1043. --response-template work/reference_story_formula_response.json \
  1044. --strict
  1045. # 完整看听参考片并填写 response 后,运行 audit 与 verify --strict。
  1046. python3 scripts/sequence_handoff.py prepare \
  1047. --project-dir . \
  1048. --storyboard work/storyboard_plan.json \
  1049. --output work/sequence_handoff_request.json \
  1050. --markdown work/sequence_handoff_request.md \
  1051. --response-template work/sequence_handoff_response.json \
  1052. --strict
  1053. # 填写 response 后运行 audit,再执行 verify --strict。
  1054. python3 scripts/video_prompt_pack.py \
  1055. --project-dir . \
  1056. --storyboard-plan work/storyboard_plan.json \
  1057. --reference-story-formula work/reference_story_formula.json \
  1058. --sequence-handoff work/sequence_handoff.json \
  1059. --provider dreamina_seedance \
  1060. --output work/video_prompt_pack.json \
  1061. --markdown work/video_prompt_pack.md \
  1062. --strict
  1063. # 多模态 reference 模式:先生成并填写 manifest,再做本地完整解码与 provider 限额检查。
  1064. python3 scripts/generation_reference_preflight.py template \
  1065. --project-dir . \
  1066. --prompt-pack work/video_prompt_pack.json \
  1067. --output work/generation_references.json
  1068. python3 scripts/generation_reference_preflight.py analyze \
  1069. --project-dir . \
  1070. --prompt-pack work/video_prompt_pack.json \
  1071. --references work/generation_references.json \
  1072. --capability-profile work/provider_capabilities.json \
  1073. --output work/generation_reference_preflight.json \
  1074. --markdown work/generation_reference_preflight.md \
  1075. --strict
  1076. python3 scripts/storyboard_assets.py \
  1077. --storyboard-plan work/storyboard_plan.json \
  1078. --asset-root work \
  1079. --media-library . \
  1080. --output work/storyboard_assets.json \
  1081. --markdown work/storyboard_assets.md
  1082. ```
  1083. 路由规则:抽象概念优先 `codex_imagegen`;数字/指标优先 `remotion_hyperframes`;动作/场景变化推荐 `dreamina_video` 但只标记为需确认,因为 Dreamina/即梦生成可能消耗 credits;其他先走本地素材库 B-roll。传 `--media-library <project_dir>` 时,`storyboard_assets.py` 会从 `media_index.json` / `media_index.db` 里按标签、文件名、时长和画幅推荐候选,并在 Markdown 表里显示分数。`storyboard_assets.py --strict` 会在素材未 ready 时返回退出码 2,适合渲染前拦截。生图优先使用 Codex 内置 `image_gen` 工具,即 OpenAI GPT Image 2(`gpt-image-2`)。
  1084. ### 🧠 Reference Story Formula — 参考片情绪机制迁移
  1085. [`scripts/reference_story_formula.py`](scripts/reference_story_formula.py) · [详细文档](docs/prompts/125-reference-story-formula.md)
  1086. 当 brief 要求借鉴参考广告、短片或 UGC 的“情绪公式”“叙事机制”时,先把参考视频、与时间线一致的 transcript 和目标 `storyboard_plan.v1` 绑定成 source-bound 请求。Reviewer 必须完整看听参考片,为每个 beat 填写 mechanism、观众前后状态、trigger、camera function、可迁移规则与 `do_not_copy`;每个目标 shot 还要填写新主题的 `content_anchor`、`viewer_shift`、`surface_change` 和可拍摄的 `visual_action`。
  1087. ```bash
  1088. python3 scripts/reference_story_formula.py prepare \
  1089. --project-dir . \
  1090. --reference-video origin/reference.mp4 \
  1091. --reference-transcript origin/reference_transcript.json \
  1092. --target-storyboard work/storyboard_plan.json \
  1093. --beat-count 5 \
  1094. --output work/reference_story_formula_request.json \
  1095. --markdown work/reference_story_formula_request.md \
  1096. --response-template work/reference_story_formula_response.json \
  1097. --strict
  1098. # 填写 response:每个 beat/shot 决定 approve,并确认五项 copy_policy。
  1099. python3 scripts/reference_story_formula.py audit \
  1100. --project-dir . \
  1101. --request work/reference_story_formula_request.json \
  1102. --response work/reference_story_formula_response.json \
  1103. --output work/reference_story_formula.json \
  1104. --markdown work/reference_story_formula.md \
  1105. --strict
  1106. python3 scripts/reference_story_formula.py verify \
  1107. --project-dir . \
  1108. --report work/reference_story_formula.json \
  1109. --strict
  1110. python3 scripts/video_prompt_pack.py \
  1111. --project-dir . \
  1112. --storyboard-plan work/storyboard_plan.json \
  1113. --reference-story-formula work/reference_story_formula.json \
  1114. --provider dreamina_seedance \
  1115. --approved \
  1116. --output work/video_prompt_pack.json \
  1117. --markdown work/video_prompt_pack.md \
  1118. --strict
  1119. ```
  1120. 五项 copy policy 固定排除 reference pixels、audio、words、branding 和 specific plot。全部 transcript segment 必须恰好出现一次并保持顺序;目标 shot 也必须完整映射,公式阶段只能向前推进或停留。脚本会提示达到 18 个规范化连续字符的原文重合,供人工改写判断;它不证明版权、原创度、留存效果或生成质量。`verify` 会现场重读全部输入、媒体参数、request/response 字节及 canonical ID。`pipeline_manifest.py --require reference_story_formula --strict` 可作为生成前门禁。
  1121. ### 🧭 Provider Capability Profile — 生成供应商能力契约
  1122. [`scripts/provider_capability.py`](scripts/provider_capability.py) · [详细文档](docs/prompts/96-provider-capability.md)
  1123. 同一模型在不同网页、App、API 或第三方入口的 mode、时长、画幅、分辨率和参考素材上限可能不同。先把 exact `provider + surface + model`、核验日期和来源写入 `work/provider_capabilities.json`,再验证:
  1124. ```bash
  1125. python3 scripts/provider_capability.py verify \
  1126. --bundle work/provider_capabilities.json \
  1127. --max-age-days 30 \
  1128. --output work/provider_capabilities_verification.json \
  1129. --markdown work/provider_capabilities_verification.md \
  1130. --strict
  1131. ```
  1132. 默认超过 30 天、未来日期、非法来源、重复 provider、无效 mode/duration/reference limit/reference media contract 都会阻塞;只有 community 来源时保留 warning,不冒充官方能力。多模态输入还应记录 `reference_media.frame_reference_exclusive / audio_only / total_files` 及三类媒体的扩展名、字节和时长限制。脚本不联网、不访问 provider、不提交任务。`pipeline_manifest.py --require provider_capabilities --strict` 会现场重新验证 freshness。
  1133. ### 🎥 Video Prompt Pack — 视频生成提示词包
  1134. [`scripts/video_prompt_pack.py`](scripts/video_prompt_pack.py) · [详细文档](docs/prompts/45-video-prompt-pack.md)
  1135. 借鉴 GitHub 上视频生成 skill 对多模型提示词、角色参考 sheet、image-to-video 和 provider 成本审批的做法,但保持本项目 artifact-first:只把 `storyboard_plan.json` 转成 `video_prompt_pack.v1` 和 Markdown review,不提交 Dreamina/Veo/LTX/Wan/Sora 任务,不消耗 credits。
  1136. 常用:
  1137. ```bash
  1138. python3 scripts/video_prompt_pack.py \
  1139. --project-dir . \
  1140. --storyboard-plan work/storyboard_plan.json \
  1141. --reference-story-formula work/reference_story_formula.json \
  1142. --asset-root work \
  1143. --character "same Chinese founder-host, navy jacket" \
  1144. --brand-anchor "palette=charcoal,white,signal yellow" \
  1145. --style-reference work/imagegen/style-key.png \
  1146. --output work/video_prompt_pack.json \
  1147. --markdown work/video_prompt_pack.md \
  1148. --strict
  1149. python3 scripts/video_prompt_pack.py \
  1150. --storyboard-plan work/storyboard_plan.json \
  1151. --asset-root work \
  1152. --provider dreamina_seedance \
  1153. --capability-profile work/provider_capabilities.json \
  1154. --require-capability-profile \
  1155. --resolution 720p \
  1156. --animate-stills \
  1157. --approved \
  1158. --output work/video_prompt_pack.json \
  1159. --markdown work/video_prompt_pack.md
  1160. ```
  1161. 输出 `global.character_sheet_prompt`、`global.style_reference`、`global.reference_story_formula`、`items[].prompt`、`items[].reference_story_formula`、`items[].negative_prompt`、`items[].surface/model/resolution`、`items[].capability_profile`、`items[].capability_issues`、`items[].approval_status` 和 `summary.blocking`。`--reference-story-formula` 会先 live-verify 报告及其 target storyboard 字节,再按 shot 注入已审机制、观众状态迁移、目标内容锚点、surface change、visual action 和复制排除合同;`--style-reference` 会把同一 style key 绑定到每个生成 shot,并给 provider prompt 追加统一 `STYLE LOCK`;重复传入 live-verified `--generation-chain-handoff` 会把已审上一镜末帧绑定到对应下一镜的 `reference`,强制使用 `image_to_video` 并记录 `items[].generation_chain_handoff`。启用 `--require-capability-profile` 后,缺 profile、profile 过期、mode/画幅/时长/分辨率不支持或参考图超限都会进入 `summary.capability_blocking`;`--strict` 同时要求 capability 和 paid approval blocker 清零。Dreamina/即梦、Veo、LTX、Wan、Sora 等视频生成可能消耗 credits,提交前先确认并保持小批量。
  1162. ### 🖼️ Reference Frame Preflight — 生成参考帧预检
  1163. [`scripts/reference_frame_preflight.py`](scripts/reference_frame_preflight.py) · [详细文档](docs/prompts/71-reference-frame-preflight.md)
  1164. 借鉴 HeyGen 的 Frame Check、Higgsfield 的共享 style key 和 Seedance 的多素材角色标注:paid provider 提交前,先检查 image-to-video 首帧与共享 style reference 是否真的可用。
  1165. ```bash
  1166. python3 scripts/reference_frame_preflight.py \
  1167. --prompt-pack work/video_prompt_pack.json \
  1168. --output work/reference_frame_preflight.json \
  1169. --markdown work/reference_frame_preflight.md \
  1170. --require-style-reference \
  1171. --strict
  1172. ```
  1173. 脚本检查路径存在性、可解码性、尺寸、横竖方向、目标画幅、短边分辨率和透明背景。缺文件、损坏文件、横竖方向冲突或严重画幅冲突会写入 `summary.blocking` 并让 `--strict` 返回 2;低分辨率和透明背景写 warning 与修正建议。默认 20% 画幅容差会接受常见 1024×1536 → 9:16 参考工作流;需要临时改路径时可重复传 `--reference shot_001=/path/to/approved.png`。产物会被 `pipeline_manifest.py` 自动纳入 gate。
  1174. ### 🎛️ Generation Reference Preflight — 图片 / 视频 / 音频生成参考门禁
  1175. [`scripts/generation_reference_preflight.py`](scripts/generation_reference_preflight.py) · [详细文档](docs/prompts/122-generation-reference-preflight.md)
  1176. 多模态 reference 要同时固定路径、顺序和用途。工具先从 prompt pack 建立逐 shot manifest,再要求每份实际提交素材填写 `kind / path / role / exclude`;列表顺序稳定映射为各类型的 `@ImageN / @VideoN / @AudioN`。`analyze` 会完整解码媒体并结合当前 surface 的 provider profile 检查类型、扩展名、字节、单条/总时长、每类/总数量、audio-only 支持和 exact frame/reference 互斥,最后输出可直接交接的有序素材清单与 `provider_prompt`。
  1177. ```bash
  1178. python3 scripts/generation_reference_preflight.py template \
  1179. --project-dir . \
  1180. --prompt-pack work/video_prompt_pack.json \
  1181. --output work/generation_references.json
  1182. # 填写 generation_references.json 后:
  1183. python3 scripts/generation_reference_preflight.py analyze \
  1184. --project-dir . \
  1185. --prompt-pack work/video_prompt_pack.json \
  1186. --references work/generation_references.json \
  1187. --capability-profile work/provider_capabilities.json \
  1188. --output work/generation_reference_preflight.json \
  1189. --markdown work/generation_reference_preflight.md \
  1190. --strict
  1191. python3 scripts/generation_reference_preflight.py verify \
  1192. --project-dir . \
  1193. --report work/generation_reference_preflight.json \
  1194. --strict
  1195. ```
  1196. 报告绑定 prompt pack、reference manifest、provider capability bundle 和每份 reference 的项目内路径、大小、SHA-256、媒体探测与完整解码结果。任一输入变化都会让旧报告失效。它不上传素材、不提交 provider、不判断权利或同意;外部上传、真人、品牌/IP 与付费生成继续使用 `production_authorization.py`。
  1197. ### 🧾 Generation Task Log — 异步生成任务台账
  1198. [`scripts/generation_task_log.py`](scripts/generation_task_log.py) · [详细文档](docs/prompts/46-generation-task-log.md)
  1199. 借鉴 PixVerse skills 的 task polling / asset download 能力和 Claude Code Video Toolkit 的跨会话项目状态管理,但保持本项目本地化:只记录异步生成任务状态,不提交 paid jobs。
  1200. 常用:
  1201. ```bash
  1202. python3 scripts/generation_task_log.py import-provider-decision \
  1203. --provider-decision work/provider_decision.json \
  1204. --log work/generation_tasks.json \
  1205. --markdown work/generation_tasks.md \
  1206. --strict
  1207. python3 scripts/generation_task_log.py add \
  1208. --log work/generation_tasks.json \
  1209. --provider dreamina \
  1210. --task-id "<submit_id>" \
  1211. --shot-id shot_002 \
  1212. --expected-path work/generated_video/shot_002.mp4 \
  1213. --status submitted \
  1214. --markdown work/generation_tasks.md \
  1215. --strict
  1216. python3 scripts/generation_task_log.py update \
  1217. --log work/generation_tasks.json \
  1218. --provider dreamina \
  1219. --task-id "<submit_id>" \
  1220. --status downloaded \
  1221. --asset-path work/generated_video/shot_002.mp4 \
  1222. --markdown work/generation_tasks.md
  1223. ```
  1224. 输出 `generation_task_log.v1`:`tasks[].provider_task_id` 保存 Dreamina `submit_id` / provider task id,`poll_command` / `download_command` 保存下一步命令,`readiness` 区分 `needs_approval` / `pending` / `processing` / `needs_download` / `missing_asset` / `failed` / `ready`。`--strict` 会在 `summary.blocking > 0` 时返回 2;`pipeline_manifest.py` 会自动识别 `generation_tasks.json` 并把未清零的异步任务列为 blocking gate。
  1225. ### 🎬 Generated Clip Review — 生成视频片段复核
  1226. [`scripts/generated_clip_review.py`](scripts/generated_clip_review.py) · [详细文档](docs/prompts/89-generated-clip-review.md)
  1227. 生成视频下载成功只说明 provider 任务完成,不代表片段可进入时间线。这个本地 gate 把每条生成 clip 的文件 hash、媒体契约和有界 contact sheet 绑定到复核 request,再审计 reviewer 对常识/物理、身份服装、动作终态、镜头、道具/画面完整性和 look 的评分、hard fail、可用裁切范围与重生建议。
  1228. ```bash
  1229. # 1. 从已刷新为 ready 的 storyboard_assets 提取生成视频并制作 contact sheets
  1230. python3 scripts/generated_clip_review.py prepare \
  1231. --project-dir . \
  1232. --asset-manifest work/storyboard_assets.json \
  1233. --contact-sheet-dir verify/generated_clips \
  1234. --output work/generated_clip_review_request.json \
  1235. --markdown work/generated_clip_review_request.md \
  1236. --response-template work/generated_clip_review_response.json
  1237. # 2. 完整看过 1× 带声、0.25×、静音画面和 audio-only 后填写 response,再审计
  1238. python3 scripts/generated_clip_review.py audit \
  1239. --request work/generated_clip_review_request.json \
  1240. --response work/generated_clip_review_response.json \
  1241. --output work/generated_clip_review.json \
  1242. --markdown work/generated_clip_review.md \
  1243. --strict
  1244. # 3. 组装/发布前重新核对 live clips、contact sheets 和 canonical audit
  1245. python3 scripts/generated_clip_review.py verify \
  1246. --report work/generated_clip_review.json \
  1247. --strict
  1248. ```
  1249. `pass` 要求加权分至少 80、故事清晰、没有 hard fail 且无需删段;`pass_with_edits` 要求至少 65,并让 `keep_ranges` / `remove_ranges` 无缝覆盖整条片段;身份断裂、错误/缺失动作、肢体或物理失败、多余主体、关键道具消失、生成文字/水印、连续性矛盾、音画矛盾和 explicit must-avoid 都会越过高分直接 `fail`,要求 `regenerate=true + prompt_fix`。clip/contact sheet 漂移、漏审、区间重叠/缺口和报告派生状态篡改都会 fail closed;`pipeline_manifest.py --require generated_clip_review --strict` 可设为发布门禁。reviewer label 不是身份认证或数字签名,contact sheet 也不能替代完整播放。
  1250. ### 🔗 Generation Chain Handoff — 已审生成片末帧接力
  1251. [`scripts/generation_chain_handoff.py`](scripts/generation_chain_handoff.py) · [详细文档](docs/prompts/124-generation-chain-handoff.md)
  1252. 两个生成镜头确实属于同一场景或一个连续动作 beat 时,先让上一镜通过 `generated_clip_review.py`,并让该边界通过 `sequence_handoff.py`。随后从上一镜完整片段或最后一个 approved keep range 提取真实末帧:
  1253. ```bash
  1254. python3 scripts/runtime_preflight.py analyze \
  1255. --profile generation_chain_handoff \
  1256. --output work/runtime_preflight.json \
  1257. --strict
  1258. python3 scripts/generation_chain_handoff.py prepare \
  1259. --project-dir . \
  1260. --clip-review work/generated_clip_review.json \
  1261. --sequence-handoff work/sequence_handoff.json \
  1262. --boundary boundary_001 \
  1263. --frame-output work/generation_chain/boundary_001_tail.png \
  1264. --output work/generation_chain_handoff.plan.json \
  1265. --markdown work/generation_chain_handoff.plan.md
  1266. ```
  1267. 工具用 FFprobe 枚举 decoded frames,选择批准范围内最后一个可解码帧,再按 exact frame index 导出 PNG;源帧和 PNG 都解码为 RGB24,像素 SHA-256 与字节数必须相同。看完上一镜和 PNG,确认同一场景、尾帧适合作为首帧、原始角色/产品/style references 继续保留后:
  1268. ```bash
  1269. python3 scripts/generation_chain_handoff.py confirm \
  1270. --project-dir . \
  1271. --plan work/generation_chain_handoff.plan.json \
  1272. --output work/generation_chain_handoff.json \
  1273. --decision use_exact_start_frame \
  1274. --reviewed-by "<reviewer-label>" \
  1275. --same-scene-confirmed \
  1276. --tail-frame-accepted \
  1277. --original-anchors-preserved \
  1278. --notes "同一场景连续动作;保留原角色、产品和风格锚点。" \
  1279. --markdown work/generation_chain_handoff.md \
  1280. --strict
  1281. python3 scripts/generation_chain_handoff.py verify \
  1282. --project-dir . \
  1283. --plan work/generation_chain_handoff.json \
  1284. --strict
  1285. python3 scripts/video_prompt_pack.py \
  1286. --project-dir . \
  1287. --storyboard-plan work/storyboard_plan.json \
  1288. --provider dreamina_seedance \
  1289. --sequence-handoff work/sequence_handoff.json \
  1290. --generation-chain-handoff work/generation_chain_handoff.json \
  1291. --character "<approved character identity>" \
  1292. --style-reference work/imagegen/style-key.png \
  1293. --approved \
  1294. --output work/video_prompt_pack.chained.json \
  1295. --markdown work/video_prompt_pack.chained.md \
  1296. --strict
  1297. ```
  1298. 目标镜头自动切到 `image_to_video`,reference 指向审核后的 PNG;prompt 明确继续真实姿态、物体状态、环境、光线和空间关系,同时让原身份/产品/style anchors 保持权威,并把短片限制为一个主动作和一种机位行为。换场、时间跳跃、故意跳切或普通剪辑匹配应使用 `reject` 或直接沿用 `sequence_handoff` 的剪辑方案。上游报告、clip、approved range、frame index/PTS、PNG bytes/pixels 或人工决定漂移都会让 `pipeline_manifest.py --require generation_chain_handoff --strict` 阻塞。脚本不上传素材、不调用 provider、不消费 credits;下一条生成片仍需逐片和跨镜头复核。
  1299. ### 🏃 Generated Motion Window — 生成片有效运动窗口
  1300. [`scripts/generated_motion_window.py`](scripts/generated_motion_window.py) · [详细文档](docs/prompts/102-generated-motion-window.md)
  1301. 短生成片常出现首帧延迟启动、尾帧冻结或中段卡住。这个 gate 用 FFmpeg `freezedetect` 以默认 0.25 秒阈值逐帧建立 full-frame freeze evidence,再取补集得到 active intervals;检测结果只提供证据,最终 `trim / keep / reject` 必须由完整 1× 播放后的人工决定。
  1302. ```bash
  1303. # 1. 分析原始生成片;新计划默认阻塞,不能直接进入时间线
  1304. python3 scripts/generated_motion_window.py analyze work/generated/shot_002.mp4 \
  1305. --project-dir . \
  1306. --output work/generated_motion_window/shot_002.json \
  1307. --markdown work/generated_motion_window/shot_002.md
  1308. # 2. 人工确认建议边界;可显式给 --start / --end,边界必须落在 active interval 内
  1309. python3 scripts/generated_motion_window.py confirm work/generated_motion_window/shot_002.json \
  1310. --decision trim \
  1311. --reviewed-by "<reviewer-label>" \
  1312. --note "Played the full clip at 1x; both boundaries begin on active motion."
  1313. # 3. 只写新的工作副本,再做 live verify / manifest gate
  1314. python3 scripts/generated_motion_window.py apply work/generated_motion_window/shot_002.json \
  1315. --output work/generated/shot_002-active.mp4
  1316. python3 scripts/generated_motion_window.py verify work/generated_motion_window/shot_002.json --strict
  1317. python3 scripts/pipeline_manifest.py . --require generated_motion_window --strict
  1318. ```
  1319. `confirm --decision keep` 用于人工确认有意的静止展示;它会放行但保留 warning。`reject` 会持续阻塞并要求修复或重生。只有 `trim` 会 re-encode 为新的 H.264/yuv420p 工作副本,并在源片有声音时保留 AAC;原始 provider 下载件始终不覆盖。计划绑定 source SHA-256、媒体契约、检测参数、canonical intervals、人工决定和输出字节;源片、检测证据、计划派生状态或输出漂移都会 fail closed。检测只识别近似 full-frame 静止,不能替代对局部肢体冻结、表情、物理、音画和故意 hold 的完整人工复核。
  1320. ### 🎯 Scoped Video Edit Review — 局部 AI 视频编辑范围复核
  1321. [`scripts/scoped_video_edit_review.py`](scripts/scoped_video_edit_review.py) · [详细文档](docs/prompts/100-scoped-video-edit-review.md)
  1322. 换背景、换装、换包装、局部 VFX 等 provider edit mode 需要回答“只改了目标,还是顺手把脸、动作、机位、构图、节奏或原声也改了”。这个 gate 把一个 `change only` 和至少两个 `preserve invariants` 绑定到 source/edited bytes,在同时间点生成三张左右并排 JPEG 和完整范围 A/B preview;两边有音轨时保留为两个独立 audio tracks。
  1323. ```bash
  1324. python3 scripts/scoped_video_edit_review.py prepare \
  1325. --project-dir . \
  1326. --source origin/presenter.mp4 \
  1327. --edited work/presenter-red-jacket.mp4 \
  1328. --change-category wardrobe \
  1329. --change "change only the jacket from blue to red" \
  1330. --preserve subject_identity \
  1331. --preserve performance_motion \
  1332. --preserve camera_motion \
  1333. --preserve framing_composition \
  1334. --preserve source_audio \
  1335. --evidence-dir verify/scoped_video_edit \
  1336. --output work/scoped_video_edit_review_request.json \
  1337. --markdown work/scoped_video_edit_review_request.md \
  1338. --response-template work/scoped_video_edit_review_response.json
  1339. # 分别完整看 source / edited / comparison,切换两条音轨并填写 response 后:
  1340. python3 scripts/scoped_video_edit_review.py audit \
  1341. --request work/scoped_video_edit_review_request.json \
  1342. --response work/scoped_video_edit_review_response.json \
  1343. --output work/scoped_video_edit_review.json \
  1344. --markdown work/scoped_video_edit_review.md \
  1345. --strict
  1346. python3 scripts/scoped_video_edit_review.py verify \
  1347. --report work/scoped_video_edit_review.json \
  1348. --strict
  1349. ```
  1350. 目标和每个保护项必须给 `pass|fail|not_observable + evidence`;任何 fail/不可观察、播放确认缺失、时长/尺寸/帧率或 bytes 漂移都会阻塞,失败必须写 `repair_action`。`pipeline_manifest.py --require scoped_video_edit_review --strict` 可设为组装/发布门禁。脚本不调用 provider、不上传、不消耗 credits;suggested prompt 只是 provider-neutral 范围合同。
  1351. ### 🎞️ Generated Sequence Review — 生成视频跨镜头连续性复核
  1352. [`scripts/generated_sequence_review.py`](scripts/generated_sequence_review.py) · [详细文档](docs/prompts/91-generated-sequence-review.md)
  1353. 逐片 `pass` 不等于组装后连续。这个第二层 gate 读取 live-verifiable `generated_clip_review.json`,按 storyboard 顺序为每个相邻 clip 提取已批准范围的真实尾帧/首帧、并排 JPEG 和“上一镜尾部 + 下一镜头部”的无声 1× MP4;再把 identity/wardrobe、prop state、spatial orientation、action end state、camera framing、lighting/palette 六项决定绑定到 clip、上游 review、storyboard 和 evidence bytes。
  1354. ```bash
  1355. # 1. 逐片 review 已通过后,生成相邻边界证据和 response 模板
  1356. python3 scripts/generated_sequence_review.py prepare \
  1357. --project-dir . \
  1358. --clip-review work/generated_clip_review.json \
  1359. --storyboard-plan work/storyboard_plan.json \
  1360. --evidence-dir verify/generated_sequence \
  1361. --output work/generated_sequence_review_request.json \
  1362. --markdown work/generated_sequence_review_request.md \
  1363. --response-template work/generated_sequence_review_response.json
  1364. # 2. 看完每个 preview + comparison 后填写 response,再审计
  1365. python3 scripts/generated_sequence_review.py audit \
  1366. --request work/generated_sequence_review_request.json \
  1367. --response work/generated_sequence_review_response.json \
  1368. --output work/generated_sequence_review.json \
  1369. --markdown work/generated_sequence_review.md \
  1370. --strict
  1371. # 3. 组装/发布前重算上游 review、clip、storyboard、evidence 和 canonical audit
  1372. python3 scripts/generated_sequence_review.py verify \
  1373. --report work/generated_sequence_review.json \
  1374. --strict
  1375. ```
  1376. 每项只允许 `match` / `intentional_change` / `mismatch` / `not_applicable`;至少两项必须真实评估。`mismatch` 必须 `fail`,同时给 failure code 和可执行 `repair_action`,不能用高分或一句“转场可接受”掩盖漂移;storyboard 明确设计的换场/换装/景别变化可以 `intentional_change` 通过,但保留 warning。`pass_with_edits` 上游片段只用首个/最后一个批准 `keep_range` 建边界,不会重新引入拒绝区间。任何 clip、上游 report、storyboard、frame/comparison/preview 漂移都会 fail closed;`pipeline_manifest.py --require generated_sequence_review --strict` 可设为组装/发布门禁。预览无声,不能替代最终 master 的完整声画复核;reviewer label 和 SHA-256 也不是身份认证或签名。
  1377. ### 🧠 Generation Lessons — 生成视频复核经验闭环
  1378. [`scripts/generation_lessons.py`](scripts/generation_lessons.py) · [详细文档](docs/prompts/90-generation-lessons.md)
  1379. 同类生成技能常把每次 QC 经验追加到一个自由文本文件,再要求下一次提示词读取。本项目把这条闭环收紧为显式 approval 和 scope:只有 canonical `generated_clip_review.json` 中结构有效的 clip 才能提供 evidence;operator 需另写一条可泛化 `lesson` 并给出 `approved_by` 标签。entry 会绑定 report/request/clip/contact-sheet 摘要、verdict、score、hard-fail codes 和原 `prompt_fix`,但 prompt pack 只自动复用人工批准的 `lesson`。
  1380. ```bash
  1381. # 1. 从一条已审 clip 沉淀 provider/model scoped 经验
  1382. python3 scripts/generation_lessons.py add \
  1383. --library work/generation_lessons.json \
  1384. --review work/generated_clip_review.json \
  1385. --clip-id shot_002 \
  1386. --category hand_contact \
  1387. --model seedance-2.0 \
  1388. --lesson "For hand-to-prop contact, isolate one interaction and keep the hand visible through release." \
  1389. --approved-by "<reviewer-label>" \
  1390. --markdown work/generation_lessons.md
  1391. # 2. 每次复用前验证;也可 select 先看实际命中的规则
  1392. python3 scripts/generation_lessons.py verify \
  1393. --library work/generation_lessons.json \
  1394. --strict
  1395. python3 scripts/generation_lessons.py select \
  1396. --library work/generation_lessons.json \
  1397. --provider dreamina_seedance \
  1398. --model seedance-2.0 \
  1399. --limit 3 \
  1400. --output work/selected_generation_lessons.json \
  1401. --markdown work/selected_generation_lessons.md
  1402. # 3. 显式注入下一次 provider prompt pack
  1403. python3 scripts/video_prompt_pack.py \
  1404. --storyboard-plan work/storyboard_plan.json \
  1405. --provider dreamina_seedance \
  1406. --lesson-library work/generation_lessons.json \
  1407. --lesson-model seedance-2.0 \
  1408. --lesson-limit 3 \
  1409. --approved \
  1410. --output work/video_prompt_pack.json \
  1411. --markdown work/video_prompt_pack.md
  1412. ```
  1413. 未传 `--lesson-model` 时只会命中 provider-wide (`model=*`) 经验,避免模型专属行为外溢;provider 精确经验优先于 global 经验。新证据推翻旧规则时,用新 entry 的 `--supersedes <old-lesson-id>` 保留历史但停止选择旧规则;未知 id、自引用或重复 id 会阻断。`add` 允许“该失败片段需要重生”这一预期 blocker,以便从失败中学习,但 source/contact-sheet 漂移、非法 response、漏审或 stored audit 篡改仍会拒绝。经验库 SHA-256 用于发现漂移,不是签名;`approved_by` 也不是身份认证。脚本不会调用生成 provider、不会自动重生、不会消费 credits,且每个 shot 默认最多注入 3 条经验。`pipeline_manifest.py --require generation_lessons --strict` 可把库完整性设为项目门禁。
  1414. 生图优先使用 Codex 内置 `image_gen` 工具,即 OpenAI GPT Image 2(`gpt-image-2`)。
  1415. ### 🗂️ Media Library Recommend — 本地 B-roll 候选推荐
  1416. [`scripts/media_library.py`](scripts/media_library.py)
  1417. 借鉴终端视频编辑工具里的 transcript-aware B-roll 选择思路,但只做本地索引和透明打分,不下载 stock、不调用外部视觉模型。推荐结果会保留 `score`、`reasons`、`absolute_path`,方便 agent 或人工先确认再接入 `render_config` / `enrich_plan`。
  1418. 常用:
  1419. ```bash
  1420. # 先建立或刷新素材库索引
  1421. python3 scripts/media_library.py init .
  1422. python3 scripts/media_library.py scan .
  1423. # 给某个分镜或口播段找 B-roll 候选
  1424. python3 scripts/media_library.py recommend "AI workflow dashboard" \
  1425. --project-dir . \
  1426. --category broll \
  1427. --target-duration 3 \
  1428. --target-aspect 9:16 \
  1429. --json
  1430. # 让 storyboard_assets 的素材预检表直接带候选排名
  1431. python3 scripts/storyboard_assets.py \
  1432. --storyboard-plan work/storyboard_plan.json \
  1433. --asset-root work \
  1434. --media-library . \
  1435. --output work/storyboard_assets.json \
  1436. --markdown work/storyboard_assets.md
  1437. # 本地素材不够时,先规划 stock 查询,不直接联网下载
  1438. python3 scripts/stock_material_plan.py \
  1439. --subject "AI workflow automation" \
  1440. --script work/transcript.json \
  1441. --provider pexels \
  1442. --provider pixabay \
  1443. --provider coverr \
  1444. --media-library . \
  1445. --output work/stock_material_plan.json \
  1446. --markdown work/stock_material_plan.md
  1447. # 下载/自有素材确认授权后,登记到素材库和 provenance 元数据
  1448. python3 scripts/media_library.py import /path/to/downloaded.mp4 \
  1449. --project-dir . \
  1450. --category broll \
  1451. --copy \
  1452. --provider pexels \
  1453. --source-url "https://www.pexels.com/video/demo-123/" \
  1454. --creator "Demo Creator" \
  1455. --license "Pexels License" \
  1456. --tag "workflow,dashboard"
  1457. ```
  1458. 打分规则:tag 命中权重大于文件名命中,其次是路径、metadata、关联 transcript;`category=broll`、视频类型、时长覆盖 cue、画幅接近目标比例会加分;默认过滤索引里已经不存在的文件,`--include-missing` 可用于清理 stale index。本地素材不足时,用 `stock_material_plan.py` 生成 Pexels / Pixabay / Coverr 查询计划;下载或客户给的素材再用 `media_library.py import` / `annotate` 写入 provider、source URL、creator、license 等元数据,供 `asset_provenance.py` 发布门禁复核。
  1459. ### 🔍 Screen Focus — 录屏点击聚焦
  1460. [`scripts/screen_focus.py`](scripts/screen_focus.py) · [详细文档](docs/prompts/28-screen-focus.md)
  1461. 借鉴 Screen Studio/Recordly/JianYing 类工具里的自动点击放大体验,但保持本项目的轻量方式:不录屏、不申请桌面权限,只把手工或工具导出的点击/热点事件转成可审计 `focus_events` enrich plan。
  1462. 常用:
  1463. ```bash
  1464. python3 scripts/screen_focus.py \
  1465. --events work/clicks.json \
  1466. --screen-width 1920 \
  1467. --screen-height 1080 \
  1468. --output work/screen_focus_plan.json \
  1469. --markdown work/screen_focus_plan.md
  1470. python3 scripts/render_final.py \
  1471. --config work/render_config.json \
  1472. --enrich-plan work/screen_focus_plan.json \
  1473. --output output/tutorial_master.mp4
  1474. ```
  1475. `focus_events[]` 支持像素或 0-1 坐标、`duration`、`zoom`、`transition`、`marker_color` 和 `label`;`render_final.py` 会在对应时间段淡入放大裁切画面,并把 label 合并为 timed badge,适合软件教程、产品演示和操作录屏。
  1476. ### 🎥 PIP Overlay — 录屏摄像头小窗
  1477. [`scripts/pip_overlay.py`](scripts/pip_overlay.py) · [详细文档](docs/prompts/51-pip-overlay.md)
  1478. 借鉴 Loop 这类录屏编辑工具把 screen、microphone 和 optional camera 合成一个短反馈闭环的做法,但保持本项目的 artifact-first 方式:先把 facecam/camera 录制转成 `pip_overlays[]` 计划,复核 Markdown 后再交给 `render_final.py --enrich-plan` 单次编码合成,不混入 camera audio。
  1479. 常用:
  1480. ```bash
  1481. python3 scripts/pip_overlay.py \
  1482. --camera origin/facecam.mp4 \
  1483. --segment "0,18,bottom_right" \
  1484. --segment "18,42,top_right" \
  1485. --sync-offset 0.18 \
  1486. --width-ratio 0.24 \
  1487. --output work/pip_overlay_plan.json \
  1488. --markdown work/pip_overlay_plan.md
  1489. python3 scripts/render_final.py \
  1490. --config work/render_config.json \
  1491. --enrich-plan work/screen_focus_plan.json \
  1492. --enrich-plan work/pip_overlay_plan.json \
  1493. --output output/tutorial_master.mp4
  1494. ```
  1495. `pip_overlays[]` 支持每段独立 `position`、`source_start`、`sync_offset`、`width_ratio`、`margin_ratio`、`opacity` 和 `transition`;`render_final.py` 会随 `--primary-speed` / `--speed` 同步压缩 camera 小窗时间线,避免变速输出时讲解人画面和主画面错位。
  1496. ### 🎙️ Audio Sync — 外录音频自动对齐
  1497. [`scripts/audio_sync.py`](scripts/audio_sync.py) · [详细文档](docs/prompts/56-audio-sync.md)
  1498. 借鉴 AICW Video 和 ffsubsync 把“同步”做成独立可复核能力的思路:先用相机/录屏 scratch audio 和外录 lav/recorder 音频估计 offset,输出 `audio_sync_plan.v1` 和 Markdown,再确认是否执行替换音轨。
  1499. 常用:
  1500. ```bash
  1501. python3 scripts/audio_sync.py \
  1502. --reference-media origin/camera.mp4 \
  1503. --external-audio origin/lav.wav \
  1504. --output work/audio_sync_plan.json \
  1505. --markdown work/audio_sync_plan.md \
  1506. --replace-output output/camera_lav_synced.mp4 \
  1507. --max-offset 5 \
  1508. --strict
  1509. # 复核 work/audio_sync_plan.md 后再执行
  1510. python3 scripts/audio_sync.py \
  1511. --reference-media origin/camera.mp4 \
  1512. --external-audio origin/lav.wav \
  1513. --output work/audio_sync_plan.json \
  1514. --markdown work/audio_sync_plan.md \
  1515. --replace-output output/camera_lav_synced.mp4 \
  1516. --apply \
  1517. --strict
  1518. ```
  1519. `alignment.offset_seconds` 为正表示延迟外录音轨;为负表示裁掉外录音轨开头。自动估计低置信度时 status 会变成 `review`,也可以用 `--offset 0.18` 手动指定偏移。`pipeline_manifest.py` 会发现 `audio_sync_plan.json` 并在低置信度或缺文件时阻塞发布 gate。
  1520. ### 🎥 Multicam Sync — 多机位可逆同步计划
  1521. [`scripts/multicam_sync.py`](scripts/multicam_sync.py) · [详细文档](docs/prompts/76-multicam-sync.md)
  1522. 两台以上设备录下同一场访谈、播客、活动或演示时,先选一台参考机位,再把其他机位对齐到它的时间线:
  1523. ```bash
  1524. python3 scripts/multicam_sync.py \
  1525. --reference-media origin/cam-a.mp4 \
  1526. --angle origin/cam-b.mp4 \
  1527. --angle origin/cam-c.mp4 \
  1528. --measure-clock-drift \
  1529. --output work/multicam_sync_plan.json \
  1530. --markdown work/multicam_sync_plan.md \
  1531. --preview-output output/verify/multicam_sync_preview.mp4 \
  1532. --apply-preview \
  1533. --strict
  1534. ```
  1535. 输出 `multicam_sync_plan.v1`,每路记录 `alignment.offset_seconds`、置信度、参考/源时间覆盖区间和实际采用的 `0:a:N`。多音轨相机会用中段 `mean_volume` 自动选择最响音轨,也可用 `--audio-stream "origin/cam-b.mp4=2"` 覆盖。三路以上自动对齐会额外直接比较非参考机位,若“参考机位推导 offset”与“机位间直接估计”相差超过阈值,就进入 review gate。`--manual-offset "origin/cam-c.mp4=1.24"` 可接入无音轨机位或已经人工确认的拍板点。
  1536. `--measure-clock-drift` 会在每个机位自己的可用重叠时长中默认抽取 5 个 20 秒窗口,按置信度筛 probe,再用稳健共识模型拟合 `offset(R)=intercept+slope*R`;至少需要 4 个跨越有效时段的 fit inlier。JSON/Markdown 保存每个 probe、`offset_slope_ppm`、测量/斜率分辨率、累计漂移、拟合残差和未应用的 `atempo/setpts` advisory factors;累计漂移超过 80 ms 或拟合不可靠会进入 review gate。可用 `--drift-probes`、`--drift-probe-seconds`、`--drift-search-seconds`、`--drift-threshold-ms` 调整。该能力默认关闭,只测当前选择的参考/源音轨;它不自动证明视频 PTS 或容器内其他音轨使用同一时钟,也不会自动校正。
  1537. 原片始终不修改;只有显式 `--apply-preview` 才会生成短网格预览。正 offset 表示该机位的 `t=0` 位于参考时间线更晚的位置,预览按 `source_local = reference_time - offset` 读取每路画面。未启用漂移测量时,30 分钟以上素材仍会警告并要求头/中/尾复核。`pipeline_manifest.py` 会发现该计划并拦截缺文件、低置信度、无公共重叠、pairwise 不一致或漂移 review。
  1538. ### 🎛 Multicam Switch — 按说话者音频生成导播草稿
  1539. [`scripts/multicam_switch.py`](scripts/multicam_switch.py) · [详细文档](docs/prompts/127-multicam-switch.md)
  1540. 同步计划 ready 后,可以把有明确说话者近讲/独立音轨的画面映射成候选机位:
  1541. ```bash
  1542. python3 scripts/multicam_switch.py plan \
  1543. --sync-plan work/multicam_sync_plan.json \
  1544. --speaker angle_00_cam-a=主持人 \
  1545. --speaker angle_01_cam-b=嘉宾 \
  1546. --program-audio angle_00_cam-a \
  1547. --delivery output/multicam_switch_draft.mp4 \
  1548. --output work/multicam_switch_plan.json \
  1549. --markdown work/multicam_switch_plan.md \
  1550. --strict
  1551. python3 scripts/multicam_switch.py apply work/multicam_switch_plan.json
  1552. ```
  1553. 每路音频用自己的 P10 噪声底和 P95 语音峰值归一,只有活动分数与领先 margin 同时达标才换机位;含糊窗口保持上一机位,短于 `--min-shot` 的闪切折回相邻镜头。各路电平包络高度相关时默认阻断,因为共享混音、自动增益或强串音会让“最响机位”失去说话者含义。声音固定来自 `--program-audio`,画面切换不会来回换麦。
  1554. apply 绑定同步计划、全部源 SHA-256、逐窗决策、source-time 映射和交付合同;草稿只有通过尺寸、帧率、时长、音轨与完整解码才落盘。带声完整播放后,用 `confirm` 逐项记录 `speaker_selection / cut_timing / sync / audio_continuity`,最后运行 `verify --strict` 和 `pipeline_manifest.py --require multicam_switch_plan --strict`。它输出可审草稿,不做声纹识别,也不替代人工导播判断。
  1555. ### 📝 Subtitle Pack — SRT/VTT/ASS 字幕交付
  1556. [`scripts/subtitle_pack.py`](scripts/subtitle_pack.py) · [详细文档](docs/prompts/29-subtitle-pack.md)
  1557. 借鉴 VideoLingo / Twick / ffsubsync 这类字幕工具对“可上传字幕文件、单行可读切分、时间线对齐”的重视,但保持本项目轻量:不重新转写、不调翻译/配音服务,只把现有 `transcript.json` 或 `render_config.json` 变成可校对、可上传的 sidecar 字幕包。
  1558. 常用:
  1559. ```bash
  1560. python3 scripts/subtitle_pack.py \
  1561. --transcript work/day58_transcript.json \
  1562. --output-dir output/subtitles \
  1563. --basename day58 \
  1564. --formats srt vtt ass json
  1565. python3 scripts/subtitle_pack.py \
  1566. --config work/render_config.json \
  1567. --output-dir output/subtitles \
  1568. --basename day58_master \
  1569. --speed 1.25 \
  1570. --offset 2.0
  1571. ```
  1572. `--transcript` 默认保留原始时间码;`--config` 默认按 `render_final.py` 的 clips 顺序串接时间线。`--speed` 对齐 `--primary-speed`,`--offset` 对齐封面/片头秒数;中文默认 18 字单行、英文默认 42 字单行,也可用 `--max-chars` 覆盖。
  1573. ### 🔎 Subtitle Readability QA — 最终字幕可读性门禁
  1574. [`scripts/subtitle_readability_qa.py`](scripts/subtitle_readability_qa.py) · [详细文档](docs/prompts/70-subtitle-readability-qa.md)
  1575. `subtitle_pack.py` 负责生成字幕,但生成成功不代表最终字幕一定可发布。`subtitle_readability_qa.py` 读取与 master 同速、同片头 offset 的 `subtitle_pack.v1` JSON,检查 cue 时间缺失/倒序、真实重叠、极短闪现、CPS、持续时间、行数、单行长度,并可用 `--media` 检查字幕是否超过成片结尾。
  1576. ```bash
  1577. python3 scripts/subtitle_readability_qa.py \
  1578. output/subtitles/day58_master.json \
  1579. --media output/day58_master.mp4 \
  1580. --output verify/subtitle_readability_qa.json \
  1581. --markdown verify/subtitle_readability_qa.md \
  1582. --strict
  1583. ```
  1584. 默认中文 18 字/行、英文 42 字符/行;18 CPS 以上、0.5 秒以下、7 秒以上或超过 2 行只 WARN,必须结合正常速度成片判断。时间无效、cue 重叠、超过媒体结尾、短于 0.15 秒或超过 25 CPS 会写入 `summary.blocking`,`--strict` 返回 2。报告存在且 blocking 非零时 `pipeline_manifest.py` 会阻塞;要强制具备报告可加 `--require subtitle_readability_qa`。本 gate 只读 timed text,不做 OCR,也不声称能判断字体、颜色、描边或画面安全区。
  1585. ### 🔤 Subtitle Glyph QA — 字幕逐字符字体覆盖门禁
  1586. [`scripts/subtitle_glyph_qa.py`](scripts/subtitle_glyph_qa.py) · [详细文档](docs/prompts/110-subtitle-glyph-qa.md)
  1587. 字幕时间、CPS 和样式预览都通过,不代表生僻字、emoji、繁体或多语言字符真的存在于最终字体。用 renderer 实际配置的项目内字体检查完整 `subtitle_pack.v1`:
  1588. ```bash
  1589. python3 scripts/subtitle_glyph_qa.py analyze \
  1590. --project-dir . \
  1591. --subtitle-pack output/subtitles/final.json \
  1592. --font 'fonts/NotoSansSC[wght].ttf' \
  1593. --output verify/subtitle_glyph_qa.json \
  1594. --markdown verify/subtitle_glyph_qa.md \
  1595. --strict
  1596. python3 scripts/subtitle_glyph_qa.py verify \
  1597. --project-dir . \
  1598. --report verify/subtitle_glyph_qa.json \
  1599. --strict
  1600. python3 scripts/pipeline_manifest.py . --require subtitle_glyph_qa --strict
  1601. ```
  1602. 脚本只用 Python 标准库解析 TTF/OTF/TTC/OTC 的 Unicode `cmap`,把字幕包、主字体、重复 `--fallback-font` 指定的显式 fallback、逐字符分配、missing 清单和 canonical report id 绑定起来。所有字体都没有的字符会阻断;显式 fallback 默认警告,`--require-primary` 可把 fallback 也设为阻断。系统隐式 fallback 不算证据。cmap 覆盖不证明 shaping、彩色 emoji、ASS 布局或视觉可读性,TTC/OTC 多 face 只按并集检查并警告;最终仍要完整 1× 看字幕和全分辨率抽帧。
  1603. ### 👁️ Subtitle Render Review — 最终成片字幕像素复核
  1604. [`scripts/subtitle_render_review.py`](scripts/subtitle_render_review.py) · [详细文档](docs/prompts/111-subtitle-render-review.md)
  1605. 字幕包、时长、CPS 和字体都合法,仍需确认最终编码像素没有漏字幕、旧文案、裁切、遮挡或手机尺寸下不可读。脚本从确切 final 选择首尾、最长文字、最高 CPS、最短时长、中段和均匀分布 cue,为每条生成带上下文的 1× clip 与字幕中点原尺寸 JPEG。
  1606. ```bash
  1607. python3 scripts/subtitle_render_review.py prepare \
  1608. --project-dir . \
  1609. --video output/final.mp4 \
  1610. --subtitle-pack output/subtitles/final.json \
  1611. --proof-dir verify/subtitle_render \
  1612. --output work/subtitle_render_review_request.json \
  1613. --markdown work/subtitle_render_review_request.md \
  1614. --response-template work/subtitle_render_review_response.json
  1615. # 正常速度完整看完 final,逐条填写 response 后:
  1616. python3 scripts/subtitle_render_review.py audit \
  1617. --request work/subtitle_render_review_request.json \
  1618. --response work/subtitle_render_review_response.json \
  1619. --output work/subtitle_render_review.json \
  1620. --markdown work/subtitle_render_review.md --strict
  1621. python3 scripts/subtitle_render_review.py verify \
  1622. --report work/subtitle_render_review.json --project-dir . --strict
  1623. python3 scripts/pipeline_manifest.py . --require subtitle_render_review --strict
  1624. ```
  1625. 每个样本只有 `visible / matches / readable / clear / repair_action=none` 才能通过;缺失、错字、不可读、裁切、遮挡与 `not_observable` 都会 fail closed。报告绑定 final、subtitle pack、proof bytes、媒体契约、采样设置、人工 response 与 canonical id,重渲染或替换证据后立即失效。该门禁不做 OCR 或自动可读性评分,默认抽样也不能替代从头到尾检查全部字幕;`reviewed_by` 只是自填标签,不是身份认证或数字签名。
  1626. ### 🗣️ Caption / Speech QA — 字幕与独立人声活动对齐
  1627. [`scripts/caption_speech_qa.py`](scripts/caption_speech_qa.py) · [详细文档](docs/prompts/109-caption-speech-qa.md)
  1628. 字幕 JSON 的顺序、时长、CPS 和媒体边界都合法,不代表它显示时真的有人在说话。对最终独立 dialogue/narration bus(或明确没有 BGM/SFX 的 speech-dominant 轨)运行:
  1629. ```bash
  1630. python3 scripts/caption_speech_qa.py analyze work/final_narration.wav \
  1631. --subtitle-pack output/subtitles/final.json \
  1632. --project-dir . \
  1633. --output verify/caption_speech_qa.json \
  1634. --markdown verify/caption_speech_qa.md \
  1635. --strict
  1636. python3 scripts/caption_speech_qa.py verify \
  1637. --report verify/caption_speech_qa.json \
  1638. --project-dir . --strict

Lines 2,001–2,891 are not shown. The link to the file on GitHub has every line.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.