# 验证：参考视频（Ref2VA video reference）端到端跑通

**状态**：代码已写完（2026-08-20 夜），**完全没有在真实 GPU 上跑过**。本地 Mac 开发机没有卡，
也没装 DiffSynth-Studio，`_references()` 里视频这段是纯读 pipeline 源码写的，语法和上传校验
本地测过，生成效果没测过。

## 改了什么

- `minimax-h3/api.py`：`GenReq` 加 `reference_video_urls`（最多 3 段）。`_references()` 把参考
  视频下载到临时文件，调 `diffsynth.utils.data.audio_video.read_video_audio()` 解码+对齐音轨，
  读不到音轨就用 `"video"`（静音）类型，读到了用 `"video_audio"` 类型。
- `h3-console/server.py`：`/v1/assets` 加 mp4/mov/webm 支持，200MB 上限，轻量魔数校验。
- `h3-console/static/index.html`：参考图 tab 加视频多选上传 + URL 直填两条路径。

## ⚠️ 最大的不确定性：视频解码分辨率的选择

`read_video_audio(path, height, width, num_frames, fps=24)` 的 `height`/`width`/`num_frames`
现在传的是**输出视频自己的分辨率和帧数**（跟 `_keyframes()` 处理首末帧图片的方式一致）。这是
没验证过的简单假设——pipeline 其实另外暴露了 `ref_video_short_edge`/`ref_video_max_pixels`
两个参数，专门用来做参考视频自己的归一化（`worker()` 里已经按默认值传给 `pipe()` 了，只是从
没真正生效过，因为这条链路从没跑过）。

## 验证步骤

1. 部署到服务器（`server.py`/`api.py` 都要重启，跟着 README 的安全重启法：`ss` 按端口找 PID
   kill，不要 `pkill -f`；重启前确认 `/v1/backends` 四张卡都空闲）。
2. 找一段几秒钟的短视频（比如已有的某条历史生成产物），通过 h3-console 的参考图 tab 上传，
   提交一个 R2V 任务。
3. 确认任务能跑完（不是在 `_references()` 这步就报错——先验证代码本身没有语法/接口层面的
   bug，这一步失败大概率是 `read_video_audio`/pipeline 调用姿势不对）。
4. 跑完了看输出：参考视频里的角色/风格/运镜是不是真的被锁住了。如果锁不住（生成结果跟没给
   参考视频差不多），先怀疑上面那条"解码分辨率假设"，试试把 `read_video_audio` 的
   `height`/`width` 换成按 `ref_video_short_edge` 算出来的值,而不是输出分辨率。
5. 如果视频带音轨，确认走的是 `"video_audio"` 分支，产出的音频里能听出参考视频的声音特征
   （不是纯粹被输出侧的文本/音频生成盖过去）。

## 参考

代码和排查思路的完整记录见顶层 `CHANGELOG.md`「2026-08-20（夜，又续七）— Ref2VA 加参考视频/
URL 直填，本地开发，⚠️ 没有 GPU 没测过」。