用途
render-hook-replacement 用于对选定视频执行一次硬切开头的替换：只更换片头，正片、结尾和原有烧录字幕均来自原视频。提供的钩子片段采用免费的本地拼接；简短文本可生成免费的动画卡片；生成式画面或配音属于可选项，需要单独估价并获批准。
主要能力
- 支持 supplied-clip 与文本动画卡片两种免费钩子；钩子几何尺寸和帧率会归一化到原片。
- 保留原片正片的每一帧，并逐帧比对（PSNR ≥45dB，帧数/顺序一致）。
- 保留原片正片音频（正常速度与增益，不交叉淡化、不添加背景音），按相同采样位置比对（归一化 RMS 误差 ≤0.08，相关性 ≥0.99；静音时绝对 RMS 误差 ≤0.0001）。
- 支持单独的 SRT 或带时间 JSON 字幕文件；被保留的字幕按实测时长差整体平移，跨越剪切点的字幕需提供实测词时间，避免被移除的片头文案残留到正片。
- 输出完整 MP4 和版本 1 编辑清单，记录 source.sha256、hook_end_sec、body_start_sec、replacement_duration_sec、new_body_start_sec、duration_delta_sec、输出路径/哈希/时长、字幕产物及四项保留性校验结果。
- 配套 replace_pack.py 可在同一源哈希下按 variants 批量生成多个标签的完整 MP4/清单及 pack-manifest.json，单个失败不影响其他成功产物。
使用方式
环境要求 Python 3.10+，可用的 ffmpeg/ffprobe（含 libx264 与 AAC）；在任何付费步骤前需先测试二进制本身。配置 JSON 参照 config.example.json，路径相对该配置解析。关键配置项：
- source.path：选定的原始文件；可选 source.sha256 冻结字节；project_id/render_id 为不透明标识，会写入清单。
- hook_end_sec：正数开头边界，须为正片留出内容；若语音跨越边界，应选择实测的词或静音边界，脚本不会静默纠正。
- hook.path：提供的视频（任意尺寸/帧率）；或 hook.text、duration_sec、font_path 及可选 #RRGGBB 颜色（文本需 Pillow 和明确提供的授权字体）。
- 可选 words:[{start,end,word}] 或包含 source_sha256 的 word_times JSON；剪切穿越已测词将失败。
- 可选 captions:{path,output_path}。
- output:{path,manifest_path?}：新的 .mp4 路径；现有输出及所有输入受保护不可覆盖。
预检命令：
python3 scripts/replace_hook.py --preflight --config /path/to/source-config.json
该预检只需 source/cut 与可选 words/captions，验证运行时编码器和支持的源形态，不写媒体、不触发付费任务。正式渲染：
python3 scripts/replace_hook.py --config /path/to/config.json
脚本以浏览器兼容的 High-profile libx264 CRF 12 编码，保留原片正片音频为 AAC 256k，并在发布文件前检查源完整性。
免费演示：
python3 scripts/make_demo.py --out-dir demo python3 scripts/replace_hook.py --config demo/config.json python3 -m unittest discover -s tests -v
演示以中性素材将 2.4 秒替换为 1.5 秒并保留原正片/结尾；--font /path/to/licensed.ttf 可给素材加烧录字幕，设置 HOOK_TEST_FONT 可测试动态文本路线。演示不发起网络请求或付费调用，是时间基准素材而非客户广告或目录上传。
适用场景
适用于只调整片头、同时严格保留正片内容与音轨的广告、宣传片或其他短视频的钩子替换。
限制
- 原片须为 CFR、未旋转、方形像素、8-bit yuv420p、视频起始时间为 0；其他源需先创建单独审批的归一化源版本并冻结，不得静默重制选定原片。
- 原片音频/容器尾部超出最后一帧视频超过 2ms 会阻塞渲染，需先制作带末帧保持的已审核源版本；渲染器不会裁剪该旁白/音乐尾部却宣称已保留。
- 输出在人工观看完整视频、试听拼接与结尾、核对新钩子文案和品牌事实后，才可记录 review:{status:'passed',source_sha256,output_sha256,checked_at}；不得复用其他输出的评审记录。
- 生成式钩子本身属于独立工作，需先阅读所选生成能力、仅报价所需新片头、获批后再将完成片段绑定到本工具。
- 高质量正片编码可能产生较大文件。