# MiniMax H3 Director Cut Studio

一个本地 PySide6 桌面导演台：读取 ComfyUI H3 API、组织 9 Image + 3 Video + 3 Audio 素材池、分析媒体、编辑时间线，并生成或直接提交 MiniMax H3 Reference-to-Video prompt。

## 运行

直接双击 `run_h3_prompt_studio.bat`。启动器只使用项目内的 `ai_libraries_common/python_env/python.exe`，不依赖系统 Python 或 PATH。

旧 Tkinter 版仍保留在 `h3_prompt_studio.py`；默认启动的是新的 `director_cut_studio.py`。

## Director Cut 工作区

- **Project / Media**：自动从 API 建立最多 15 个实体素材槽。每张卡片可双击选择或直接拖入本机文件，也能再拖到时间线指定时间。Media Pool 像编辑软件的素材网格一样随面板宽度自由增减列数并自动缩放；卡片以 `P1 / V1 / A1` 显示简短标题，完整 API 标签仍保留在提示和 tooltip 中。
- **Program Monitor**：由 Timeline playhead 驱动的实时预览。普通单层视频使用低开销 VideoWidget；重叠视觉层、透明度、Blend Mode、淡入淡出或转场会自动切换为 QVideoSink + QPainter 多层实时合成。音频轨支持 Mute、Solo、Volume、后台 Pan 代理、播放速度和源入出点。
- **Inspector**：素材节点、文件、开始与结束时间。
- **Recognition / Activation**：Pillow / FFprobe、视频抽帧和波形生成全部在独立后台服务运行；离线 BLIP 支持 GPU 失败后自动切换 CPU。音频按 8 秒流式解码，总长度不超过当前 Timeline 时长，先做 VAD、再只对语音区间执行 Whisper，并以 FFT 估算节拍。素材卡片显示准备/识别进度，可取消后重新分析；worker 崩溃、超时或断管不会关闭主界面。
- **Director Cut Timeline**：启动时提供 V1–V3 与 A1–A3，可用 `+ V TRACK / + A TRACK` 动态增加 V4/V5…、A4/A5…。左侧 Track Header 是独立于 Graphics Scene 的固定面板，采用单行图标布局：轨道名、颜色、启用、锁定、显示/静音/Solo；点击设置图标才展开高度、Opacity、Blend Mode、Volume 和 Pan。移动、修剪或重建 clip 都不会删除轨道控件。Timeline 工具栏提供 Selection、Type、Prompt 与 Hand Tool；Hand Tool 拖动 Timeline 只移动视图，不改变播放头或 clip。Prompt Tool 点击 clip 后可写入专属导演提示词，该提示词会保存到项目、支持 Undo/Redo，并注入 H3 素材定义。Type Tool 可在视觉轨点击建立 Title clip，编辑文字、字号、颜色和起止时间；Selection Tool 可直接在 Program Monitor 拖动每个文字对象，位置使用百分比坐标保存。文字层可移动、删除、保存和 Undo/Redo，并在 Program Monitor 叠加预览。顶部提供缩放滑杆、`- / +` 按钮，也支持 `Ctrl + 鼠标滚轮`。
- **Project / Undo**：版本 3 项目保存为 `.h3director.json`，恢复 workflow、动态轨道、轨道混音/合成属性、Clip 属性、素材路径、Work Area、Skill 和 prompt；旧项目自动使用默认轨道迁移。新增轨道、轨道属性和 Clip 编辑均支持 Undo/Redo。
- **H3 Prompt**：固定 Default Skill 与可选 Special Skill 共同生成官方六段式 Ref2VA prompt。
- **ComfyUI**：可导出 Active API，或流式上传当前激活的本机素材后直接 Queue Prompt。

只有已经放入 Timeline 的素材才有资格连接到 H3。`AUTO` 依据 clip 与 Work Area 是否相交决定连接；`ACTIVE` 强制纳入当前生成，但仍要求 clip 已在 Timeline；`BYPASS` 强制断开。参考视频的画面与 `GetVideoComponents` 配套音轨会作为同一 clip 联动。

## 项目内 AI 运行环境

`ai_libraries_common` 当前约 7.5 GB，包含：

- Python 3.11.15 与 PySide6 6.11.2
- Pillow 12.2.0
- Torch 2.12.1 + CUDA 12.6 runtime
- Transformers 5.12.1
- FFmpeg / FFprobe 2026 build
- `Salesforce/blip-image-captioning-base` 完整离线权重
- `openai/whisper-small` 多语言离线语音识别权重

路径全部记录在 `ai_libraries_common/runtime_config.json`，使用项目相对路径，因此整个项目文件夹可以一起迁移。BLIP 使用开头 10%、中段 50%、结尾 90% 三帧理解视频变化；BLIP 与 Whisper 都使用常驻 worker，模型仅加载一次。FFmpeg 缩略图、三帧样本、波形与分析 cache 写入 `.director_cache`。

## 提示词生成方式

- **离线整理**：不联网、不翻译，保留输入语言，可靠地生成 `CUT / TRANSITION / END` 结构。
- **AI 英文润色**：调用一个 OpenAI-compatible 接口，将表单内容重写为紧凑的英文电影分镜提示词。

## 自动读取 ComfyUI workflow 素材

程序启动时会优先自动载入同目录下的
`video_minimax_h3_r2v_9image_3audio_3video_api.json`，也可以使用界面中的“载入 API…”选择其他 API-format JSON。

程序会：

- 按 `class_type` 寻找 H3、LoadImage、LoadVideo、LoadAudio 和 GetVideoComponents 节点，不依赖固定节点 ID。
- 沿 H3 输入连接自动映射 `<Picture N>`、`<Video N>`、视频配套音轨和 `<Audio N>`。
- 显示节点 ID、启用状态和 ComfyUI input 中的素材文件名。
- 自动把已连接的素材映射写入“参考素材”和“音频规则”栏。

最新模板被识别为最大素材池：9 张图片、3 段参考视频（各自包含配套音轨）和 3 条独立音频。

## Skill 菜单

Skill 目录分成两层：

```text
skill default/
└─ h3-prompt-writing/
   ├─ SKILL.md
   └─ references/ref-en.txt

skill special/
├─ minimalist-product-ad-generator/SKILL.md
├─ music-video-subtitle-generator/SKILL.md
└─ 任何未来新增的 Special Skill folder/SKILL.md
```

菜单 `Skills` 会自动建立两层绑定：

- 固定 Default（始终绑定）：读取 `skill default/h3-prompt-writing/SKILL.md` 和 Ref2VA guide，负责 MiniMax H3 官方写法与固定顺序的 `subject_definitions / summary / retention_analysis / detailed_description / overall_soundscape / non_diegetic_music` 六段结构。
- 可选 Special：`skill special` 下每一个含 `SKILL.md` 的子文件夹都会成为一个 Special 菜单项。Special 负责特别场景、风格与制作流程，但不能替代 Default 的 H3 格式。
- `None — 不附加特别场景`：只绑定 Default，不注入任何 Special 规则。这也是启动时的默认选择。

实际组合始终是 `Default + Special`，例如 `H3 Prompt Writing + Music Video Subtitle Generator`；选择 None 时为 `H3 Prompt Writing + None`。每次点击菜单都会重新读取对应 Skill 文件；点击“重新扫描 Skill folders”可立即发现新加入或删除的文件夹。使用“查看当前 Skill 原文…”可以同时核对 Default 与当前 Special 的原文。

## 素材时间范围与自动激活

API 载入后只建立 Media Pool，不会把 15 个元素自动铺满时间线。把需要的卡片拖入 V1–V3 或 A1–A3 后才建立 clip。当前 `Generation Work Area` 有开始/结束时间窗，只有 Timeline clip 与该时间窗相交时，AUTO 素材才会激活。

点击“导出 Active API…”时，程序会：

- 深拷贝原始 workflow，不覆盖模板。
- 保留当前时间窗相关素材的 H3 连接。
- 断开窗外或禁用素材的 H3 连接。
- 将视频画面与同一 `GetVideoComponents` 的配套音轨一起启用或停用。
- 把 Duration 节点改为当前 clip 的长度。
- 写入当前 H3 prompt。

注意：ComfyUI 的 API-format 导出只保存可执行图。处于 bypass/mute 状态的
LoadVideo 或 LoadAudio 节点可能被导出器直接移除；这种情况下 API JSON 中没有节点及文件名，程序会明确显示缺失警告。要让程序读取它们，请先在 ComfyUI 中启用节点，再重新导出 API-format JSON。

旧版 AI 模式需要填写：

- 完整 Endpoint，例如服务商提供的 `.../v1/chat/completions` 或 `.../v1/responses`
- 服务商要求的模型名称
- API Key（仅保存在当前进程内存，不写入磁盘）

也可在启动前设置 `H3_API_ENDPOINT`、`H3_API_MODEL`、`H3_API_KEY` 环境变量。

## 推荐填写方式

1. 在“故事简介”中说明人物、目标、场景和戏剧进展。
2. 在“参考素材与一致性”中明确每张图片的职责，例如 `<Picture 1>` 仅用于主人公身份，`<Picture 2>` 仅用于怪兽设计。
3. “镜头构思”每行写一个镜头，按发生顺序排列。
4. 不能改写的对白或画面文字使用 `镜头编号|文字`，例如 `1|GET READY`。
5. 用“必须保留／避免”锁定身份、服装、文字拼写，并禁止额外人物或镜头。

输出页仍可直接编辑。每次生成后，“结构检查”会检查 CUT 编号、转场数量、参考标签、结尾保持和提示词长度。

## 测试

```powershell
ai_libraries_common\python_env\python.exe -m unittest discover -v
```
