MM·H3 工作台 · MiniMax H3 Video Timeline Workbench

A local, single-host video-generation timeline studio for the MiniMax H3 open model: arrange shots on a multi-shot timeline, feed prompts / parameters / reference media, and call a local MiniMax H3 inference backend to render each shot with inline preview.

中文 | English

---

中文

项目简介

MM·H3 工作台是一个面向开发者的本地视频生成时间线工作台：在多镜头时间线上编排项目，输入提示词 / 参数 / 参考素材，调用本地 MiniMax H3（H3-Base）推理服务逐镜头生成视频并即时预览成片。

前端按官方三份 ComfyUI 工作流拆分为三个模式页——文生 T2V（/）、图生 I2V（/i2v，首帧 / 末帧 / 首尾帧）、多模态参考 R2V（/r2v），由 FastAPI + Jinja2 单端口服务端渲染（backend/templates/），顶栏一键切换；明暗双主题，响应式布局。

它只是一个 UI / 队列客户端：依赖一个本机可达的 MiniMax H3 推理后端（进程内 comfy 内核、外部 vllm-omni OpenAI 兼容端点，或 diffusers 进程内管线三选一）。2K（H3-Regenerate-2K）官方尚未开源，UI 中对应选项已禁用。

核心特性

• 三模式页：T2V / I2V（首·末·首尾帧 + 图像槽位）/ R2V（参考素材管理器 + 标签速查），顶栏切换互跳、当前页高亮。
• 官方参数规格：六种宽高比 + 768P 短边（上限 768×1344、32 倍数）实时像素换算；时长 4–15s 整数秒（默认 8s）按 17k+5 帧网格显示帧数；噪声种子留空即随机。
• 多模态参考（REF2VA）：图 ≤9 / 视频 ≤3 / 音频 ≤3，混合 ≤12；参考保真度 match/max；提示词按官方标签（<Picture N> / <Video N> / <Audio N>、<d>[语言]）引导书写。
• 输入校验：格式 / 大小 / 数量上限 / 音频须配图或视频 / 音视频每段 2–15s、同类合计 ≤15s，超限 422 且不留孤儿文件。
• 生成队列与状态流转：任务状态机、断点续跑、历史库回看、多项目管理、推理引擎运行时切换。
• 展示壳与主题：剧场红 / 放映机青绿双展示壳，首访引导 + 本地持久化，顶栏外观菜单随时切换。

界面展示

主界面（文生 T2V 工作台）——顶栏三模式切换、左侧提示词坞、中央放映机预览、右侧镜头参数、底部多镜头时间线：

结果回投区（等待生成）——完整工作台视图：左侧提示词坞、中央放映机结果区（当前为空态，显示「等待生成·结果帧回投」，带 REC / 时间码 / 24FPS·768P 角标与播放控制条）、右侧镜头参数与底部多镜头时间线：

镜头参数面板——画面比例、实时分辨率换算、时长 / 帧数、种子、Steps，以及官方模板规格（Sampler / Scheduler / 输出规格）：

时间线与队列状态栏——多镜头缩略条、总时长统计，状态栏实时显示连接状态、QUEUE 待处理·进行中计数、应用版本与当前推理引擎：

组件架构——浏览器（Jinja2 SSR）→ FastAPI 单端口（页面 + API + SQLite + 队列）→ 三选一推理后端 → 本地权重：

快速开始

受支持运行时：Python 3.12 与 Node 22（与 CI 同版本）。本仓库是 UI / 队列客户端，不内置、不下载模型权重；真实推理前需自行准备 MiniMax H3 权重（见下文「系统要求」）。仅启动界面与跑通 UI 不需要 GPU。

1. 克隆后必做（本地门禁，一次性）

sh .githooks/install.sh             # 启用本仓库钩子
sh .githooks/install.sh --check     # 只读自检：未启用则退出码 1 并说明失效了哪些防线

core.hooksPath 是本地 git 配置，不随克隆传播。未启用时，gitleaks 密钥扫描、DCO 签名与推送前预检都不会执行。

2. 安装依赖

python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt

3. 启动

Windows 一键启动（自动探测 Python → 启动 FastAPI → 打开浏览器）：

start.bat

跨平台手动启动：

python -m uvicorn backend.main:app --port 18080

页面地址：http://127.0.0.1:18080/（T2V）、/i2v（I2V）、/r2v（R2V）。端口可用环境变量 MMH3_PORT 覆盖。

4. 最小验证（不触发推理）

curl -s http://127.0.0.1:18080/api/health | python -m json.tool
# status=ok、model_loaded=false 即说明 UI 与 API 已就绪（此时未加载任何权重）

浏览器打开 http://127.0.0.1:18080/，接受用户协议后即可浏览三模式页、参数面板与时间线——不点击「生成当前镜头」就不会发起推理。

Docker 部署（可选，适合 Linux / GPU 服务器）

sudo scripts/preflight.sh                       # 目录与模型文件权限预检
python scripts/check_compose_mounts.py          # 检查 5 个 compose 挂载源
docker compose up -d --build                    # 构建并启动
curl -s http://127.0.0.1:18080/api/health       # 健康检查

镜像不含 comfy_kernel/（ComfyUI 内核，GPL-3.0）；经 compose 部署时自动以只读方式挂载。compose 默认仅绑定 127.0.0.1:18080，切勿改为 0.0.0.0 后裸奔——本工作台 API 无内置认证。

系统要求与兼容性

• 运行时：Python 3.12、Node 22；SQLite（随 Python 自带）。
• 界面 / 开发：任意现代浏览器，无需 GPU 即可启动 UI 与跑测试。
• 真实推理（三选一，经 MMH3_INFERENCE_BACKEND 切换）：
  • comfy（默认）：进程内 vendored ComfyUI 内核，加载本地单文件权重。
  • vllm-omni（目标）：外部 vllm-omni 服务（Apache-2.0，OpenAI 兼容 /v1/videos），消费者级 GPU recipe（4090/5090 已验证）；需配置 MMH3_VLLM_OMNI_ENDPOINT。
  • diffusers（回退）：进程内 ModularPipeline，需 diffusers 格式权重目录。
• 模型权重：本地路径经 MMH3_MODEL_PATH 指定，留空则从 HuggingFace MiniMaxAI/MiniMax-H3 拉取；国内优先魔搭 MiniMax/MiniMax-H3。显存有限建议 int8 pruned 权重 + MMH3_QUANTIZATION。
• 已知边界：2K（H3-Regenerate-2K）与 H3-Context-IR 官方未开源，前端选项已禁用或为本地轻量替代；参考视频同步音轨、采样器覆盖在 diffusers 后端会降级（详见仓库 README 历史版与 docs/）。

使用示例

• 文生视频：在 / 页新建项目 → 时间线「+ 加镜头」→ 左侧写提示词（≤7000 字符）→ 右侧选比例 / 时长 / 种子 → 「生成当前镜头」。
• 图生视频：切到 /i2v，选首帧 / 末帧 / 首尾帧模式并上传图像，可开启「跟随首帧尺寸」。
• 多模态参考：切到 /r2v，上传 ≤12 个混合参考素材（图 / 视频 / 音频），按 <Picture N> / <Video N> / <Audio N> 标签书写提示词。
• 跑测试：

python -m pytest tests/ -q          # 后端单测（公式一致性、上传校验、时长校验）
npm run test:frontend                # 前端 jsdom 交互断言

常见问题（FAQ）

1. 启动后点生成没反应 / 报后端错误？ 本工作台不含权重。请先确认已按「系统要求」准备好推理后端与权重，并访问 /api/health 查看 dependency.reachable 与 model_loaded。
2. 端口 18080 被占用？ 用 MMH3_PORT=其它端口 python -m uvicorn backend.main:app --port 其它端口 覆盖。
3. 为什么没有 2K / 1080p 选项？ H3-Regenerate-2K 尚未随官方开源，UI 已禁用；当前 H3-Base 原生上限 0.98MP（16:9 → 1344×768）。
4. 可以直接对外暴露公网吗？ 不建议。API 无内置认证；如需外网访问，请置于反向代理之后并加鉴权。
5. Windows 下 Docker 容器读不到权重？ 参考 pwsh scripts/convert_model_junctions.ps1（默认 dry-run，需约 213GB 磁盘峰值）。

文档与治理

• 架构决策：docs/adr/（单端口 FastAPI、内嵌 comfy 内核、vllm-omni 引擎、版本治理）。
• 合规与安全：docs/GPL_COMPLIANCE.md、docs/MODEL_LICENSE.md、docs/SECURITY.md、docs/THIRD_PARTY_NOTICES.md。
• 运维：docs/SRE_RUNBOOK.md、docs/rollback_sop.md。
• 治理规范：ReSerendipity/.github/governance。

贡献、安全与支持

• 贡献请遵循组织级贡献指南（Conventional Commits + DCO 签名），欢迎 PR。
• 安全问题请按 docs/SECURITY.md 披露，勿公开开 Issue。

许可证

项目代码采用 Apache License 2.0 开源；MiniMax H3 模型权重遵循 MiniMax 官方社区许可（含地域条款），商用 / 再分发 / 微调前请阅读 docs/MODEL_LICENSE.md 与官方协议。

---

English

Introduction

MM·H3 Workbench is a local, single-host video-generation timeline studio for the open MiniMax H3 model: arrange shots on a multi-shot timeline, feed prompts / parameters / reference media, and call a local MiniMax H3 inference backend to render each shot with inline preview.

The frontend splits the three official ComfyUI workflows into mode pages — T2V (/), I2V (/i2v, first / last / both frames) and R2V (/r2v, multimodal reference manager) — served by a FastAPI + Jinja2 single-port backend (backend/templates/), with light/dark themes and a responsive layout.

It is a UI/queue client only: it depends on a locally reachable MiniMax H3 inference backend — an in-process comfy kernel, an external vllm-omni OpenAI-compatible endpoint, or an in-process diffusers pipeline. 2K (H3-Regenerate-2K) is not yet open-sourced by MiniMax and stays disabled in the UI.

Key Features

• Three mode pages: T2V / I2V (first·last·both frames + image slots) / R2V (reference-asset manager + tag cheat-sheet), with top-bar switching and active-tab highlight.
• Official parameter spec: six aspect ratios + 768P short edge (max 768×1344, multiple of 32) with live pixel conversion; 4–15s integer duration (default 8s) on the 17k+5 frame grid; blank seed = random.
• Multimodal reference (REF2VA): up to 9 images / 3 videos / 3 audios, ≤12 mixed; reference fidelity match/max; prompts guided by official tags (<Picture N> / <Video N> / <Audio N>).
• Input validation: format / size / count limits, audio must accompany image or video, clips 2–15s each and ≤15s per kind — rejected with 422 and no orphan files.
• Generation queue & state machine: task status flow, checkpoint resume, history playback, multi-project management, runtime engine switch.
• Display shells & themes: cinema-red / projector-teal shells, first-run guide, persisted locally, switchable from the appearance menu.

Screenshots

Main workbench (T2V) — top mode tabs, left prompt dock, center projector preview, right shot parameters, bottom multi-shot timeline:

Result playback area (waiting for generation) — full workbench view: left prompt dock, center projector result area (currently empty, showing "waiting for generation"; with REC / timecode / 24FPS·768P badges and a transport bar), right shot-parameter panel and bottom multi-shot timeline:

Shot parameter panel — aspect ratio, live resolution conversion, duration / frame count, seed, steps, and official-template spec (Sampler / Scheduler / output format):

Timeline & queue status bar — shot thumbnails, total duration, and a status bar showing connection, QUEUE pending·running count, app version and active inference engine:

Component architecture — browser (Jinja2 SSR) → FastAPI single port (pages + API + SQLite + queue) → one of three inference backends → local weights:

Quick Start

Supported runtimes: Python 3.12 and Node 22 (matching CI). This repo is a UI/queue client and ships no model weights. Real inference requires you to prepare MiniMax H3 weights first (see System Requirements). Booting the UI and running tests needs no GPU.

1. One-time local gates

sh .githooks/install.sh             # install repo hooks
sh .githooks/install.sh --check     # read-only self-check (exit 1 if hooks are missing)

core.hooksPath is local-only and does not propagate on clone; without it, gitleaks secret scanning and DCO signing are not enforced.

2. Install dependencies

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

3. Run

Windows one-click:

start.bat

Cross-platform manual:

python -m uvicorn backend.main:app --port 18080

Pages: http://127.0.0.1:18080/ (T2V), /i2v (I2V), /r2v (R2V). Override the port with MMH3_PORT.

4. Minimal smoke check (no inference)

curl -s http://127.0.0.1:18080/api/health | python -m json.tool
# status=ok with model_loaded=false means UI + API are up (no weights loaded yet)

Open http://127.0.0.1:18080/, accept the EULA, and browse all three mode pages, the parameter panel and the timeline — no inference starts until you click "Generate".

Docker (optional, for Linux / GPU servers)

sudo scripts/preflight.sh
python scripts/check_compose_mounts.py
docker compose up -d --build
curl -s http://127.0.0.1:18080/api/health

The image does not bundle comfy_kernel/ (GPL-3.0); compose mounts it read-only. Compose binds 127.0.0.1:18080 only — never expose it on 0.0.0.0 without a reverse proxy and auth, as the API has no built-in authentication.

System Requirements & Compatibility

• Runtimes: Python 3.12, Node 22; SQLite (bundled with Python).
• UI / development: any modern browser; no GPU needed to boot the UI or run tests.
• Real inference (pick one via MMH3_INFERENCE_BACKEND):
  • comfy (default): in-process vendored ComfyUI kernel loading a local single-file weight.
  • vllm-omni (target): external vllm-omni service (Apache-2.0, OpenAI-compatible /v1/videos), consumer-GPU recipe (4090/5090 verified); set MMH3_VLLM_OMNI_ENDPOINT.
  • diffusers (fallback): in-process ModularPipeline needing a diffusers-format weights directory.
• Weights: set MMH3_MODEL_PATH to a local path, otherwise it pulls from HuggingFace MiniMaxAI/MiniMax-H3; in China use the ModelScope mirror MiniMax/MiniMax-H3. For limited VRAM, use the int8 pruned weights and set MMH3_QUANTIZATION.
• Known limits: 2K (H3-Regenerate-2K) and H3-Context-IR are not yet open-sourced and are disabled or lightly approximated in the UI; reference-video synced audio and sampler overrides degrade on the diffusers backend.

Usage Examples

• Text-to-video: on / create a project → "+ Add shot" on the timeline → write a prompt (≤7000 chars) on the left → pick aspect / duration / seed on the right → "Generate current shot".
• Image-to-video: switch to /i2v, choose first / last / both-frames mode and upload images; enable "follow first-frame size" as needed.
• Multimodal reference: switch to /r2v, upload ≤12 mixed reference assets (image / video / audio) and write prompts with <Picture N> / <Video N> / <Audio N> tags.
• Tests:

python -m pytest tests/ -q          # backend unit tests (formulas, upload validation, duration)
npm run test:frontend                # frontend jsdom interaction tests

FAQ

1. Generate does nothing / backend errors? This workbench ships no weights. Prepare an inference backend and weights per System Requirements, then check /api/health for dependency.reachable and model_loaded.
2. Port 18080 is taken? Override with MMH3_PORT=<port> python -m uvicorn backend.main:app --port <port>.
3. Why no 2K / 1080p option? H3-Regenerate-2K is not yet open-sourced; H3-Base tops out at 0.98MP (16:9 → 1344×768).
4. Can I expose this to the public internet? Not without care — the API has no auth. Put it behind a reverse proxy with authentication first.
5. Docker on Windows cannot see weights? See pwsh scripts/convert_model_junctions.ps1 (dry-run by default; ~213GB peak disk needed).

Docs & Governance

• Architecture decisions: docs/adr/ (single-port FastAPI, embedded comfy kernel, vllm-omni engine, version governance).
• Compliance & security: docs/GPL_COMPLIANCE.md, docs/MODEL_LICENSE.md, docs/SECURITY.md, docs/THIRD_PARTY_NOTICES.md.
• Operations: docs/SRE_RUNBOOK.md, docs/rollback_sop.md.
• Governance: ReSerendipity/.github/governance.

Contributing, Security & Support

• Follow the org contributing guide (Conventional Commits + DCO sign-off). PRs welcome.
• For security issues, please disclose per docs/SECURITY.md rather than opening a public issue.

License

Project code is released under Apache License 2.0. MiniMax H3 model weights are governed by the MiniMax Community License (including territory terms); read docs/MODEL_LICENSE.md and the official terms before commercial use, redistribution, or fine-tuning.