Watch/download the full engine matrix MP4
Montara
本地优先的视频工作室 OS。
一个 Timeline IR。多个渲染器。真实的 MP4。诚实的 provider 和 runtime 门控。
快速开始 |
Montara 是什么 |
目前测试内容 |
Providers |
目录结构 |
路线图 |
架构
Montara 是一个开放的、Agent 就绪的视频制作系统，用于制作解说视频、
短视频、软件演示、纪录片、预告片、动态图形，并最终从
一个可编辑的单一事实来源：**Timeline IR**，制作长篇电影。
这个想法简单却又宏大：
如今，Montara 已经能够渲染真实的本地 MP4，导出编辑器文件，运行
Python 媒体引擎，验证多种 provider 的请求结构，并发布公开演示
产物。更大的野心是将同样的 IR 和 pipeline 系统从
30 秒的短视频扩展到 12 分钟的纪录片乃至数小时的电影。这种长篇
野心属于路线图的一部分，并不意味着如今每个长片工作流都已经
经过了完全的生产测试。
## Montara 是什么
Montara 建立在几个坚定的原则之上：
| 原则 | 含义 |
| --- | --- |
| **单一 Timeline IR** | 场景计划、剪辑决策、导入的编辑器片段和生成的资产最终都汇聚为一个 JSON timeline。 |
| **本地优先** | 在没有任何 API key 的情况下，Montara 仍然可以使用 FFmpeg、字幕卡片、本地/系统语音路径和确定性兜底方案来创建可观看的 MP4。 |
| **可插拔 Provider** | 云端 provider 采用 BYOK 模式。Montara 会构建并审计请求规范，但实时的付费调用需要明确的 opt-in。 |
| **渲染器诚实** | FFmpeg 是通用的基础。Remotion、HyperFrames、Blender、Three.js、Manim、Motion Canvas、Revideo、Playwright 和本地模型 runtime 仅在可用时才会被使用。 |
| **Agent 就绪** | 人类、Codex、Cursor、本地模型或 Montara 自己的 orchestrator 都可以读取相同的 `skills/`，通过相同的 CLI 进行操作，并留下可验证的产物。 |
| **对编辑器友好** | 渲染可以导出 EDL、OTIO 和 FCPXML，以便在 Premiere、Resolve 或 Final Cut 中继续工作。 |
| **纪录片级别的诚实** | 声明、地图、音乐提示、转录剪切点和源素材都被视为质量关卡，而非主观感觉。 |
## 它的目标是制作什么
Montara 被设计为一个通用的视频生产基底，而不是一个单一格式的
演示应用。
| 格式 | 目前的实际情况 |
| --- | --- |
| 动画解说视频 | 已通过 `montara make`、Timeline IR、FFmpeg/Remotion 兜底机制进行测试，并验证了 MP4。 |
| YouTube Shorts / Reels | 已通过短视频辅助工具、竖屏输出配置、基于转录的剪切门控以及演示产物进行测试。 |
| 纪录片蒙太奇 | 已使用离线 fixture 语料库和 60 秒的开源素材证明进行了测试。实时的发布素材取决于源适配器和授权审查。 |
| 屏幕演示 / 产品操作指南 | 已通过捕获产物提取和浏览器捕获 CLI 界面进行测试。实时的 Playwright 录制受 runtime 门控。 |
| 动态排版 | 在 runtime 存在时，HyperFrames 的严格冒烟测试受 validate 门控；Motion Canvas 的原生证明目前仍受 runtime 门控。 |
| 角色动画 | 在 HyperFrames 存在时，从 SVG/GSAP 绑定到 HyperFrames 最终 MP4 的过程受 validate 门控。 |
| 3D / 数学 / 电影场景 | Three.js、Blender、Manim、Revideo、Motion Canvas 适配器已存在；原生证明的质量取决于已安装的 runtime。 |
| 长篇纪录片和电影 | IR、pipelines、语料库、provider 和 runtime 层都是为此设计的。完整的 12 分钟/1 小时制作工作流仍需更长格式的验证、镜头连续性检查、资产预算和更重的 QA。 |
## 快速开始
前置条件：
- Node.js 18+；对于某些 runtime 工具，推荐使用 Node 22+
- `pnpm`
- `PATH` 中包含 FFmpeg 和 ffprobe
- Python 3.10+，用于 Python 媒体引擎
```
git clone https://github.com/abhinavshrivastava950/Montara.git
cd Montara
pnpm install
python -m pip install -r requirements/dev.txt
copy .env.example .env
pnpm run montara doctor
pnpm run montara start
```
Windows 快捷方式：
```
scripts\setup.bat
```
`pnpm run montara start` 会首先运行 `doctor`，因此在渲染开始前就能
捕获缺失的 FFmpeg 或工作区依赖。使用 `pnpm run montara doctor
--fix` 获取引导式安装命令，或使用 `pnpm run montara doctor --fix --yes`
运行项目本地的安装步骤。
对 PowerShell 友好的命令：
```
pnpm run montara doctor
pnpm run montara status --json --out out/montara-status.json
pnpm run montara make --pipeline animated-explainer --seconds 20 "Explain Montara's Timeline IR"
```
基础本地路径不需要 API key。仅在你想要测试的 provider 中添加 key。
## 工作室流程
`montara start` 是面向初学者的入口：
```
Montara is started.
What can I do for you today?
1. Create videos
2. Edit videos
How would you like to make your video?
1. Instagram Reel
2. YouTube Short
3. YouTube video
4. Documentary
5. Animated explainer
6. Screen demo
```
非交互式示例：
```
pnpm run montara start --non-interactive create \
--kind documentary \
--niche geopolitics \
--topic "Why chokepoints still shape global trade" \
--seconds 60
```
## 公开演示库
该仓库在 `demos/` 目录下包含了一套更精简的公开演示集。这些是
首选展示的演示。旧的低动态文本卡片片段已从公开
库中移除，因为它们不能代表该引擎的野心。
| 演示 | 证明了什么 | 已检查产物使用的 API | 预览 |
| --- | --- | --- | --- |
| 完整引擎矩阵 | 一个精美的章节式视频，涵盖了 FFmpeg、Remotion、HyperFrames、Blender、Three.js、Manim、Revideo、Motion Canvas 和 Playwright，并带有受 runtime 门控引擎的状态标签 | 无 | [预览 GIF](demos/previews/01-engine-matrix-preview.gif) / [原始 MP4](https://raw.githubusercontent.com/abhinavshrivastava950/Montara/main/demos/01-engine-matrix.mp4) / [海报](demos/posters/01-engine-matrix-poster.jpg) |
| 纪录片工作室证明 | Remotion 纪录片 UI、d3-geo 地图动画、源素材标签、电影级证据构图，以及 FFmpeg 混流/探测/海报输出 | 无 | [原始 MP4](https://raw.githubusercontent.com/abhinavshrivastava950/Montara/main/demos/02-documentary-studio.mp4) / [海报](demos/posters/02-documentary-studio-poster.jpg) |
引擎矩阵的设定是刻意诚实的：它演示了 FFmpeg 和 Remotion 作为
本地渲染路径，并展示了 HyperFrames、Blender、Three.js、Manim、Revideo、
Motion Canvas 和 Playwright 及其实际发布的适配器/探测/runtime
状态。当未安装该 runtime 时，它不会伪造原生的 Blender、Manim、Revideo 或 Motion Canvas
渲染。
重新生成公开演示：
```
pnpm demos:generate
```
生成器仅使用 `.env` 中存在的 key。它不需要付费的
语音/音乐 API；`MONTARA_TTS_PROVIDER=system` 是默认的演示语音路径。
## 目前已测试的内容
来自当前公开优化分支的最新本地门控快照：
| 门控 | 结果 |
| --- | --- |
| `pnpm typecheck` | 在此公开优化轮次中通过 |
| `pnpm verify` | 在此公开优化轮次中 324 个通过，0 个失败 |
| `pnpm validate` | 在此公开优化轮次中 101 个通过，0 个失败 |
| `pnpm run montara stage1-audit --json --out out/stage1-audit.json` | 在此公开优化轮次中 4/4 个部分，21/21 项检查通过 |
| `python -m pytest tests` | 未在此重新运行，因为可用的 Python 3.13 解释器没有安装 `pytest`；上次记录的 Stage 4 门控结果是 399 个通过，8 个跳过 |
这些测试涵盖：
- Timeline IR 验证、编辑操作、渲染路径和编辑器桥接导出/导入
- FFmpeg 真实 MP4 渲染和渲染后 QA
- 安装时的 Remotion 原生冒烟测试和未安装时的 FFmpeg 兜底
- 可用时 HyperFrames 的动态排版和角色绑定路径
- provider 请求构建器、脱敏处理、dry-run/live-audit 管道
- 视频/图像/语音/音乐的本地兜底方案
- 用于纪录片蒙太奇的语料库/搜索/合成工作流
- Playwright/捕获命令界面和 Python 捕获测试
- 纪录片证据门控和确保转录安全的短视频剪切
尚未完全测试的内容：
- 每个云端 provider 的真实实时 key 确认
- 完整的长篇电影工作流
- 每个 renderer 在每个 OS 上的已安装 runtime 原生证明
- 超出可选 CLIP/signalstats 路径的 BLIP/默认本地视觉字幕功能
- 公开的 SDK 和 GUI/WARCUT 产品界面
## Provider 层面
Montara 暴露了许多 provider 路径，但它对“受支持”一词非常
谨慎：
- **离线已验证：** 请求结构、脱敏、兜底行为和 dry-run
账本已通过测试。
- **实时已确认：** 最近使用过真实 key，并记录了经过脱敏处理的
产物。
- **受 Runtime 门控：** 仅在您安装了本地 runtime 或模型时才有效。
- **已规划：** 架构中已留有位置，但不应将其作为已发布功能来推销。
当前的注册表面：
| 类别 | Providers / runtimes | 目前的实际情况 |
| --- | --- | --- |
| 云端视频 | Kling, Runway Gen-4.5, Google Veo 3.1, xAI Grok Video, Higgsfield, MiniMax, HeyGen | 请求构建器 + 脱敏 fixtures；真实 key 确认仍需 BYOK 后续跟进 |
| 本地视频 | 通过 ComfyUI 的 WAN, Hunyuan, CogVideo, LTX | runtime 管理器和请求界面；实际质量取决于本地 GPU/模型 |
| 素材视频 | Pexels, Pixabay, Wikimedia | Pexels/Pixabay key 路径；Wikimedia 无需 key 的网络 opt-in |
| 云端图像 | BFL FLUX.2, Google Gemini image, xAI Grok image, OpenAI Images, Recraft | 请求构建器 + 脱敏 fixtures；根据 key 进行实时确认 |
| 本地/素材图像 | 通过 ComfyUI/A1111 的 Stable Diffusion, Manim 帧, Pexels, Pixabay, Unsplash | 受 runtime/素材门控 |
| TTS | 系统语音, Piper, ElevenLabs, Google TTS, Python 工具中的 Doubao Speech | 已测试系统/本地兜底方案；云端请求构建器和工具需要 key |
| 音乐/SFX | tone-score 兜底, Suno, ElevenLabs Music, ElevenLabs SFX | 兜底方案已测试；云端路径受 BYOK/live-audit 门控 |
| STT/字幕 | 存在 key 时的 Groq Whisper，安装后的 faster-whisper | Groq 路径已实现；本地 faster-whisper 仍受 runtime 门控 |
在花钱之前，请运行：
```
pnpm run montara providers audit --out out/provider-audit-fixtures.json
pnpm run montara providers live-audit --out out/provider-live-audit.json
pnpm run montara providers smoke flux --category image --json
```
实时调用需要：
```
MONTARA_LIVE_PROVIDER_SMOKE=1
```
加上 provider key 和 `--live`。
## 环境
将 `.env.example` 复制到 `.env`。该示例文件故意列出了超出
演示最低要求的内容，以便创始人、评估者或 Agent 能看到 provider 的全貌。
留空的值是安全的；当缺少 key 时，Montara 会回退到本地。
切勿提交 `.env`、身份验证状态文件、模型权重、客户媒体或私有的
生成输出。
## 核心命令
```
pnpm run montara doctor
pnpm run montara status --json --out out/montara-status.json
pnpm run montara stage1-audit --json --out out/stage1-audit.json
pnpm run montara start
pnpm run montara plan "Make a 45-second explainer about why the sky is blue"
pnpm run montara make --brain --seconds 20 "Make a local-first documentary cold open"
pnpm run montara render out/timeline.json
pnpm run montara import out/edit.fcpxml
pnpm run montara export out/timeline.json --to otio out/edit.otio
pnpm run montara analyze https://example.com/reference-video
pnpm run montara understand source.mp4 --vision auto
pnpm run montara reel source.mp4 out/short.mp4 --style cinematic
pnpm run montara capture login --url https://example.com
pnpm run montara capture --url https://example.com out/browser-capture.mp4
pnpm run montara corpus sources
pnpm run montara runtimes status --json --out out/runtimes-status.json
pnpm run montara providers live-audit --out out/provider-live-audit.json
```
## 引擎与 Runtimes
| 引擎/runtime | 角色 | 当前状态 |
| --- | --- | --- |
| FFmpeg | 通用组装、编码、探测、音频、缩略图、短视频 | 可用的本地基础 |
| Remotion | React 动态图形、解说/纪录片合成 | 安装了 composer 依赖时，原生冒烟测试受 validate 门控；`REMOTION_ENABLED=1` 开启 opt-in |
| HyperFrames | HTML/CSS/GSAP 动态排版和角色 SVG 绑定 | 当 `npx hyperframes` 可解析时受 validate 门控 |
| Blender | 外部 3D 渲染 | 适配器已存在；原生版本受 runtime 门控 |
| Three.js | headless/WebGL 3D 证明 | 适配器已存在；受 runtime 门控/兜底路径 |
| Manim | 数学/图表动画 | 适配器已存在；受 runtime 门控 |
| Revideo | MIT 合成兜底目标 | 选择器/探测器已存在；已安装的 MP4 证明待定 |
| Motion Canvas | 动态排版目标 | 适配器/探测器已存在；已安装的 MP4 证明待定 |
| Play | 浏览器捕获、登录 storageState | CLI 和测试已存在；实时的浏览器功能受 runtime 门控 |
| ComfyUI / A1111 | 本地图像/视频模型服务器 | 外部 runtime 管理器，dry-run 安装/启动指南 |
| Piper / faster-whisper / Transformers.js | 本地 TTS、STT、CLIP 式视觉 | runtime 清单和可选路径 |
Montara 绝不打包模型权重。请将 runtime、缓存和模型许可证
保留在仓库之外。
## 架构
```
idea/source/reference
-> research / understand / hear
-> pipeline skills
-> ScenePlan / edit decisions
-> Timeline IR
-> renderer adapter
-> MP4 + QA + self-review
-> optional EDL / OTIO / FCPXML
```
位于仓库根目录的 Python 引擎（`tools/`、`lib/`、`pipeline_defs/`、`schemas/`）
通过 `engine_bridge.py` 和 TypeScript CLI 驱动。TypeScript 部分
拥有 IR、provider 注册表、渲染适配器、门控和公共命令
界面。
## 仓库目录结构
根目录刻意保持精简。对 runtime 至关重要的入口点保留在
顶层，而参考文档和辅助脚本则存放在各自的文件夹中。
| 路径 | 存放内容 |
| --- | --- |
| `README.md`、`PLAN.md`、`AGENTS.md`、`AGENT_GUIDE.md` | 首次阅读的项目和 Agent 契约 |
| `packages/` | TypeScript 工作区：CLI、IR、renderers、providers、质量关卡 |
| `tools/`、`lib/`、`schemas/`、`pipeline_defs/`、`skills/` | Python 媒体引擎和共享技能层；出于桥接兼容性考虑保留在根目录 |
| `remotion-composer/` | 原生 Remotion 合成项目和演示合成 |
| `scripts/` | 验证、校验、演示生成和旧版演示渲染辅助工具 |
| `docs/` | 架构、provider 文档、prompt 库、归属说明、发布日志 |
| `demos/` | 仅包含已提交的公开 MP4、海报和演示清单 |
| `out/`、`projects/`、`.python-packages/`、`.pnpm-store/` | 本地生成的/runtime 状态；已被忽略 |
## 路线图
已经稳固的部分：
- Timeline IR 核心
- FFmpeg 渲染基础
- 编辑器导出/导入
- Stage 1 parity 审计
- provider 请求 fixtures 和实时就绪账本
- 公开演示库
- 纪录片证据门控
- `montara make --brain` 的本地大脑兜底路径
仍需加强的部分：
- 针对长尾云端 provider 的真实 BYOK 实时冒烟测试
- Motion Canvas 和 Revideo 的已安装 runtime MP4 证明
- 完整的缓存本地 CLIP/BLIP 视觉验证
- 具备连续性和预算 QA 的更长的纪录片/电影规模工作流
- 公开 SDK
- `montara serve` Web GUI
- 基于相同 IR 的 WARCUT 桌面 GUI
## 仓库规范
有意纳入版本控制：
- 源代码、技能、文档、schemas、测试
- `demos/` 中的公开演示 MP4/海报
- 演示清单和可重现的生成脚本
有意忽略：
- `.env`、身份验证状态、服务帐号文件、API token
- `out/`、`projects/`、临时输出、私有生成的媒体
- 模型权重、ONNX/GGUF 文件、runtime 缓存
- 演示临时工作区 `demos/.work/` 和演示生成日志
## 重要文档
- [PLAN.md](PLAN.md)：总体构建计划和分阶段路线图
- [CONTRIBUTING.md](CONTRIBUTING.md)：人类开发者设置和 PR 指南
- [AGENT_GUIDE.md](AGENT_GUIDE.md)：助手的操作契约
- [docs/CAPABILITY-SNAPSHOT.md](docs/CAPABILITY-SNAPSHOT.md)：当前可用的功能
- [docs/MONTARA-PARITY.md](docs/MONTARA-PARITY.md)：parity/护城河检查清单
- [docs/PROVIDER-AUDIT.md](docs/PROVIDER-AUDIT.md)：provider fixture 和实时冒烟测试策略
- [docs/DEMOS.md](docs/DEMOS.md)：证明账本
- [docs/PROMPT_GALLERY.md](docs/PROMPT_GALLERY.md)：测试真实路径的 prompts
- [docs/PROJECT_CONTEXT.md](docs/PROJECT_CONTEXT.md)：架构约定
## 致谢
从概念上感谢 `calesthio/OpenMontage` 和 Claude video-skills
生态系统，它们帮助塑造了本地优先的视频 Agent 方向。Montara 的
公开 Timeline IR、TypeScript 工作区、CLI、runtime 门控和演示打包
均作为 Montara 独立构建。
## 许可证
Montara 采用 AGPL-3.0 协议。请参阅 [LICENSE](LICENSE)、[NOTICE](NOTICE) 和
[docs/ATTRIBUTION.md](docs/ATTRIBUTION.md)。
切勿提交密钥、私有客户媒体、第三方模型权重，或
其许可证不允许公开分发的 provider 输出。