wassermanproductions/blockout

当你为视频生成器提供一个明确无误的动态参考（一个准确展示你所期望的镜头运动和角色走位的粗略 3D 渲染）时，它们能生成效果显著提升的作品。Blockout 是将“我脑海中已有画面”转化为“生成器绝不会出错”的最快途径。它可以导出视频 + 深度通道 + 静帧 + 量身定制的提示词，让 **Seedance 2.0, Veo 3.1, Kling, LTX 2.3, 和 Wan 2.2** 能够精准执行。 它有意**不**充当一款 3D 美术工具。真实比例的灰盒模特与车辆、真实的镜头物理计算以及走位调度工具就是它的全部。其保真度目标是*清晰明确，而非华丽美观*。 - 🎬 **真实的镜头光学** — 支持 Super 16 / 35 / Full Frame / 65mm 传感器，真实焦距，关键帧缩放，焦点转换，画幅遮罩。 - 🚶 **基于标记的调度** — 镜头与演员共享同一心智模型；支持可编辑的路径、每标记的缓动控制、步态以及速度合理性警告。 - 🎥 **覆盖模型** — 场景（scene）拥有走位调度，镜头（shot）拥有摄像机。无需重新调度，即可从五个角度拍摄同一动作。 - 👥 **一键生成群演** — 舞蹈表演、格斗、徒步或汽车追逐：选择规模和风格，点击地面，整个编排好的演员阵容就会准确地在那里就位。之后只需一键即可重塑整个群演组的风格。 - ✨ **Animate 标签页** — 64 种角色动作（格斗、舞蹈、坐下/喝水/跳跃、打牌、水枪）和 25 种动作路径（飞机降落、直升机盘旋、汽车追逐、碎片掉落）随时可一键应用。 - 🎛️ **27 种经典运镜** — 环绕、摇臂、无人机跟随、眩晕式的滑动变焦（Dolly-zoom）—— 全部围绕你的主体构建，并在其移动时跟随拍摄。 - 📦 **确定性导出** — 相同的项目在每次运行时都会渲染出逐字节相同的帧。播放性能绝不会影响输出结果。 - 🤖 **可由 Agent 驱动** — 内置的 MCP 服务器允许 Claude Code、Codex 或任何 MCP 客户端为你进行场景布置和拍摄。 ## 60 秒工作流 1. **STAGE（布置）** — 拖入 50 多种环境套件之一（市区、住宅街道、超市、电影院、火车车厢、带泳池的后院、航拍天空……），从素材库中放置人物 / 动物 / 车辆 / 家具 / 道具，并为你的主体打上标签（“THIEF”，红色）。 2. **SHOOT（拍摄）** — 选择一名演员，按下 `M`，点击地面放置带编号的标记；演员就会在你的时间轴上依次走过这些点。设置摄像机构图（或点击 **MS**，在你当前的镜头下自动构图一个中景），放置摄像机机位点，选择一种拍摄设备 —— 滑轨、斯坦尼康、手持、摇臂、无人机、车载摇臂。拖动播放头、重新调整时间、播放。 3. **DELIVER（交付）** — 选择你的生成器，点击 **Export shot package**： ``` Shot-1A/export-…/ ├── 1A_reference.mp4 # the motion reference (deterministic render) ├── 1A_depth.mp4 # depth pass for ComfyUI control workflows ├── 1A_normal.mp4 # optional normal pass ├── stills/ # frame at every camera mark + first/last + top-down blocking diagram ├── prompt.txt # generated from your actual blocking, tailored per generator ├── comfyui-workflow.json # pre-wired depth-conditioning workflow (Wan/LTX profiles) ├── metadata.json # machine-readable marks/lenses/timings └── README.txt ``` 此外还有各场景工具：**分镜导出**（拼接所有镜头）、**联系表**，以及 **Blender 移交**（包含动画摄像机的 `.glb` 文件 + 一键导入脚本）。 ## 截图导览 | | | |---|---| |  |  | | **Stage** — 一键生成整个编排好的群演阵容。二十名舞者，混合风格，每一位表演者均可独立编辑。 | **Shoot** — 透过拍摄镜头观看，*Follow Behind*（背后跟随）无人机运镜紧跟一架爬升的飞机，且锁定 aim（瞄准）该飞机。 | |  |  | | **Choreograph（调度）** — 一场双人格斗被布局为标记药丸的时间轴轨道；选中一名格斗者即可在检查器中编辑其路径。 | **Light（布光）** — 一个带有泳池、蹦床、烤架、小孩和狗的后院，沐浴在黄金时刻的光线中。六种布光预设，每种只需一键。 | ### Deliver（交付）  选择目标生成器，Blockout 会根据你*实际的*走位调度 —— 镜头、传感器、设备以及每个主体的运动 —— 编写提示词，然后打包参考视频、深度通道、静帧以及预先连接好的 ComfyUI 工作流。 ## 功能导览 ### Stage（布景） 50 多套灰盒环境套件以及包含人物、动物、车辆、家具和道具的完整素材库 —— 全部基于真实世界比例，且全部由代码程序化生成。使用彩色标注为各主体添加标签，将物体贴合到地面，并将任何布景保存为可重用的全局**预设**（如晚餐场景、驾驶设定），以便在任何项目中作为起点使用。 ### Shoot（拍摄） 如同真实片场般的覆盖（Coverage）模式：**场景（scene）**拥有走位调度，每个**镜头（shot）**拥有一台摄像机。在共享的时间轴上放置摄像机和演员标记，选择一种设备（滑轨 / 斯坦尼康 / 手持 / 摇臂 / 无人机 / 车载摇臂），当某段行走的推算速度达到 6 m/s 时，你会收到**速度合理性警告**。自动构图预设（双人镜头、过肩镜头、反打、俯拍、低角度、倾斜镜头）会根据你标记的主体来放置摄像机。通过将现有视频（包括深度图）作为时间轴同步的**参考底图**透叠在视口上，让你可以直观地用肉眼比对并匹配走位调度。 ### Deliver（交付） 数据驱动的**生成器配置文件**为每个模型定义了时长、分辨率、参考模式和提示词模板；添加新的生成器只需修改配置即可。导出是**确定性**的 —— 时间轴以精确的 fps 步进并离线渲染，因此同一项目在每次运行时都会导出逐字节相同的帧。项目实际上是一个包含格式化输出且键顺序稳定的 JSON 文件夹：你可以对其进行 diff、分支管理或代码审查。 ### 序列与预设 只需一个操作即可布置一整个编排好的群演阵容 —— 选择 **舞蹈表演 / 格斗 / 徒步追逐 / 汽车追逐**，设定人数（2–60）和风格，然后**准确点击你希望他们出现的位置**：表演者*及其*编排动作就会在那里生成，并面向摄像机。布置好的序列只是一个*起点*：按住 Shift 键并拖动该群组（拖动时，他们的编排动作会随之移动），**✨ Animate 标签页**可以一键替换所有人的舞蹈风格或路径。非角色表演者也有运动路径预设：飞机起飞 / 降落 / 掠过，直升机盘旋，鸟类俯冲，掉落的碎片，投掷物。对于摄像机，你可以应用 **27 种经典运镜**之一 —— 环绕、摇臂、无人机跟随、快速摇摄、眩晕式的滑动变焦（dolly-zoom） —— 每一种都围绕你的主体构建，并在其移动时跟随拍摄。 ### Agent 控制 Blockout 内置了 **MCP 服务器**，使得 AI agent 可以驱动正在运行的应用程序 —— 布置实体、调度走位标记、重新构图、拖动时间轴以及获取视口截图 —— 就像你手动操作一样。完整的 agent 集成指南请参阅 **[mcp/README.md](mcp/README.md)**。 ## 安装 从 GitHub Releases **下载**发布版 DMG (macOS)，或从源码构建： ``` git clone cd blockout npm install npm run dev # development, hot reload # 或 npm run build && npm start # production build ``` 环境要求：**Node 22+**，以及用于导出的 **ffmpeg**（在打包时通过 `ffmpeg-static` 内置；如果未内置则会回退到系统环境下的 `ffmpeg` —— 可通过 `brew install ffmpeg` 安装）。 打包的 DMG 文件未签名。在你自己的机器上，右键点击 → 打开即可绕过 Gatekeeper。如需更广泛地分发，请在 [electron-builder.yml](electron-builder.yml) 中设置 Developer ID `identity` 并进行公证。 ## Agent 控制 (MCP) 将 **Claude Code、Codex、Hermes 或任何 MCP 客户端**指向内置的 MCP 服务器，它就可以布置场景、调度走位标记、调整摄像机构图、拖动时间轴并获取视口截图。只需一行代码即可将其注册到 Claude Code 中： ``` claude mcp add blockout -- node /Users/eklpse1/Desktop/blockout/mcp/blockout-mcp.mjs ``` 发现和授权过程是全自动的 —— 应用程序在启动时会将仅限本地主机的端口和 Bearer token 写入 `~/.config/blockout/control.json`，无依赖的桥接程序会读取该文件。目前共有 **26 个工具**（从 `get_state` 和 `add_entity` 到 `spawn_sequence`、`apply_camera_move` 和 `screenshot`）。 👉 **完整的设置、完整的工具表格以及实际操作演示：[mcp/README.md](mcp/README.md)。** ## 脚本命令 | 命令 | 作用 | |---|---| | `npm run dev` | 开启热重载运行 | | `npm run typecheck` / `npm run lint` | 严格的 TS + ESLint 检查 | | `npm test` | 引擎单元测试 (Vitest) | | `npm run smoke` | 构建并执行完整的端到端冒烟测试：启动应用，布置场景，导出真实的资源包，使用 ffprobe 验证，并检查字节确定性 | | `npm run package` | 构建 macOS DMG (`release/`) | ## 项目结构 请参阅 [docs/DESIGN.md](docs/DESIGN.md)（产品与架构）、[docs/ROADMAP.md](docs/ROADMAP.md)（构建计划与 QA 方案）以及 [AGENTS.md](AGENTS.md)（说明 AI agent 应如何构建 / 运行 / 修改此应用）。确定性的核心代码位于 `src/engine/` —— 纯粹的 TypeScript，不依赖 DOM，且完全经过单元测试；`state(t)` 是一个纯函数，由播放器、视频导出、静帧提取和 glTF 烘焙共同共享。 ## 许可证与致谢 **Apache License 2.0** —— 详见 [LICENSE](LICENSE)。无论是商业用途还是其他用途，均可免费使用、修改、分叉并在此基础上进行开发。 **需要保留署名：** 根据 [NOTICE](NOTICE) 文件 (Apache 2.0 §4(d))，任何使用、分叉或重新分发都必须保留 NOTICE 文件，并在其文档及“关于/制作人员”界面中注明出处 **Sam Wasserman ([wassermanproductions.com](https://wassermanproductions.com))**。 所有 3D 资产均由代码程序化生成 —— 不涉及任何外部资产许可。 由 **Sam Wasserman** 创建 —— [wassermanproductions.com](https://wassermanproductions.com) · [wasserman.ai](https://wasserman.ai)。

标签：3D动画, AI影视制作, MITM代理, 动作编排, 桌面应用, 自动化攻击, 视觉预览, 视频生成, 镜头调度