[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-92515":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":15,"stars7d":15,"stars30d":16,"stars90d":15,"forks30d":15,"starsTrendScore":15,"compositeScore":17,"rankGlobal":10,"rankLanguage":10,"license":18,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":21,"hasPages":19,"topics":22,"createdAt":10,"pushedAt":10,"updatedAt":26,"readmeContent":27,"aiSummary":28,"trendingCount":15,"starSnapshotCount":15,"syncStatus":29,"lastSyncTime":30,"discoverSource":31},92515,"motion-previs-studio","wassermanproductions\u002Fmotion-previs-studio","wassermanproductions","Open-source desktop app for AI-film motion, depth, pose, and camera-move previsualization.","https:\u002F\u002Fwassermanproductions.com",null,"TypeScript",279,40,101,0,135,54.84,"Apache License 2.0",false,"main",true,[23,24,25],"aiprevis","aivideocreation","previsualization","2026-07-22 04:02:06","\u003Cp align=\"center\">\n  \u003Cimg src=\"docs\u002Flogo.png\" alt=\"Motion Previs Studio\" width=\"180\" \u002F>\n\u003C\u002Fp>\n\n# Motion Previs Studio v4\n\nDeveloped and created by **Sam Wasserman**.\n\n- [WassermanProductions.com](https:\u002F\u002Fwassermanproductions.com)\n- [Wasserman.ai](https:\u002F\u002Fwasserman.ai)\n\nOpen-source under the [Apache License 2.0](LICENSE). Please preserve the [NOTICE](NOTICE) file and cite Sam Wasserman when using or building on this work.\n\nMotion Previs Studio v4 is a standalone desktop app for turning source video shots into AI-film previsualization and control-reference bundles. It is built for filmmakers who want more precision before generating AI video: select a reference shot, extract pose, depth, camera movement, masks, edges, and control layers, then export a production pack for Seedance, ComfyUI, Blender, Runway, Kling, and similar workflows.\n\nThis repository contains the v4 source code. Local signed app bundles and generated build artifacts are intentionally not committed.\n\n## New in v4\n\n- **OpenPose \u002F BODY_25 export.** Every bundle now ships a deterministic `openpose_pose.mp4` skeleton video plus per-frame `openpose_keypoints.json` in the standard OpenPose BODY_25 layout (75 numbers per person), for AI-video pipelines and ControlNet graphs that expect OpenPose input.\n- **Subject-masked optical-flow camera solve.** The camera move is solved with Lucas-Kanade optical flow and a RANSAC similarity fit, masking out the tracked subject so the reference camera pan\u002Ftilt\u002Fzoom\u002Froll is recovered from the background rather than the actor.\n- **Deterministic frame encoding.** Control videos are encoded frame-by-frame through ffmpeg (no `captureStream`, no wall-clock timers), so exports are reproducible.\n- **Security hardening.** Custom `mps:\u002F\u002F` protocol with `webSecurity` on, an IPC allowlist, and a path allowlist for all file access.\n- **Send to Blockout.** After export, hand a Reference or Depth clip straight to a running [Blockout](https:\u002F\u002Fgithub.com\u002Fwassermanproductions\u002Fblockout) session as a ghost underlay — one click, no files to shuffle.\n- **Real per-stage progress and cancel.** A live Prepare → Pose → Camera → Encode → Bundle rail with a working Cancel that aborts cleanly between frames.\n- **Project save \u002F restore.** Sessions (media path, trim, settings, mode, last bundle) are written to the workspace and offered back for restore on relaunch; settings persist.\n- **720p export option.** Scale control layers so the short edge is 720 for Seedance-style targets, or keep the source long-edge scaling.\n- **One Reference Mode control.** A single segmented control — Camera only · Actor motion · Object motion · Full scene — with one-line explainers, replacing the old overlapping selectors.\n- **Branding + quick-start help.** App logo on the welcome and header, an in-app credit footer, and a skimmable `?` quick-start overlay.\n- **Agent control (MCP).** A localhost-only, token-gated control server + zero-dependency MCP bridge lets Claude Code, Codex, or Hermes drive a running app — import a shot, set the range\u002Fmode\u002Fsettings, run analysis, export the pack, and hand a clip to Blockout. See [`mcp\u002FREADME.md`](mcp\u002FREADME.md).\n\n## Screenshots\n\n### Shot Bible and Production Pack\n\n![Motion Previs Studio shot bible and production pack](docs\u002Fscreenshots\u002Fstudio-shot-bible-production-pack.png)\n\n### Source Analysis Workspace\n\n![Motion Previs Studio source analysis workspace](docs\u002Fscreenshots\u002Fstudio-source-analysis-workspace.png)\n\n### Live Reference Analysis\n\n![Motion Previs Studio live YouTube reference analysis](docs\u002Fscreenshots\u002Fstudio-live-youtube-analysis.jpg)\n\n## What It Does\n\n- Imports local video files with Electron file access.\n- Imports YouTube-compatible and direct web video URLs through `yt-dlp`.\n- Lets you select a precise shot range before processing.\n- Uses `ffmpeg` to normalize the selected clip and create fast local control passes.\n- Uses MediaPipe Pose Landmarker locally in the renderer to extract 2D and world-space pose landmarks.\n- Adds adjustable pose settings for model choice, detection confidence, tracking confidence, smoothing, temporal gap filling, sample FPS, and max people.\n- Solves subject-independent camera move keyframes from global frame motion, so you can reuse the camera move without reusing the original actor, car, object, or environment.\n- Adds Shot Plan, Reference Mode, Control Layers, Export Presets, and Quality readiness controls for AI-film preproduction.\n- Shows working previews for reference video, camera path, colored 2D skeleton overlays, 3D stick-figure previs, depth, edges, masks, and pose diagnostics.\n- Exports a bundle folder and ZIP designed for downstream AI-video and Blender workflows.\n\n## Workflow\n\n1. Import a local clip or paste a compatible video URL.\n2. Choose the shot range you want to analyze.\n3. Pick the reference mode:\n   - `Camera only`: keep just the camera move and timing; replace the subject and world.\n   - `Actor motion`: preserve body\u002Fpose motion plus the camera move.\n   - `Object motion`: preserve an object or vehicle path plus the camera move.\n   - `Full scene`: preserve camera, blocking, subject motion, and depth rhythm.\n4. Select the control layers you want included.\n5. Run analysis (cancel any time; each stage reports real progress).\n6. Review pose, depth, camera, diagnostics, and quality metrics.\n7. Export the Production Pack, then optionally Send to Blockout as a ghost reference.\n\n## Exported Production Pack\n\nEach export can include:\n\n- `reference.mp4`\n- `depth.mp4`\n- `ai_depth.mp4` when the local AI depth pass is available\n- `edges.mp4`\n- `lineart.mp4`\n- `motion_mask.mp4`\n- `normals_proxy.mp4`\n- `animatic.mp4`\n- `contact_sheet.jpg`\n- `pose_high_contrast.webm`\n- `pose_high_contrast.mp4`\n- `openpose_pose.mp4` — OpenPose BODY_25 skeleton video\n- `openpose_keypoints.json` — per-frame OpenPose BODY_25 keypoints\n- `combined_reference_depth_pose.mp4`\n- `pose_landmarks.json`\n- pose analysis settings and diagnostics in `pose_landmarks.json`, `model_presets.json`, and `bundle_manifest.json`\n- `camera_motion.json`\n- `blender_import_pose.py`\n- `blender_import_camera.py`\n- `blender_import_scene.py`\n- `comfyui_manifest.json`\n- `seedance_prompt.md`\n- `prompt_pack.md`\n- `shot_bible.json`\n- `quality_report.json`\n- `model_presets.json`\n- `control_layers_manifest.json`\n- `bundle_manifest.json`\n\n## Camera-Only Mode\n\nCamera-only mode is designed for cases where you like the movement of the reference shot but do not want to keep the same subject, vehicle, object, or environment. The app exports `camera_motion.json` and camera-specific prompt guidance so downstream tools can preserve pan, tilt, zoom, roll, timing, and shot rhythm while replacing the source content.\n\n## Agent Control (MCP)\n\nA running app can be driven by an AI agent (Claude Code, Codex, Hermes, or any MCP client) exactly like its sibling [Blockout](https:\u002F\u002Fgithub.com\u002Fwassermanproductions\u002Fblockout). The main process runs a localhost-only, token-gated HTTP control server that advertises itself via `~\u002F.config\u002Fmotion-previs\u002Fcontrol.json`, and a zero-dependency stdio MCP bridge (`mcp\u002Fmotion-previs-mcp.mjs`) forwards tool calls to it.\n\nThe agent gets 11 tools: `get_state`, `import_file`, `import_url`, `set_range`, `set_mode`, `set_settings`, `run_analysis`, `export_pack`, `list_bundle`, `send_to_blockout`, and `screenshot`. The workflow is import → set range\u002Fmode → `run_analysis` → poll `get_state` until done → `export_pack` → `send_to_blockout`.\n\nConnect it in one line:\n\n```bash\nclaude mcp add motion-previs -- node \"\u002FABSOLUTE\u002FPATH\u002Fmotion-previs-studio\u002Fmcp\u002Fmotion-previs-mcp.mjs\"\n```\n\nFull setup (Claude Code, Codex, Hermes, generic clients), the tool table, and a worked session are in [`mcp\u002FREADME.md`](mcp\u002FREADME.md). The app must be running for the tools to respond; the server binds `127.0.0.1` only and every request carries a bearer token, so nothing is exposed off-machine.\n\n## Tech Stack\n\n- Electron desktop app\n- React + TypeScript renderer\n- Vite build pipeline\n- Three.js 3D preview\n- MediaPipe Pose Landmarker\n- FFmpeg \u002F FFprobe\n- yt-dlp for compatible web-video imports\n- Playwright for desktop smoke and screenshot automation\n\n## Development\n\n```bash\nnpm install\nnpm run dev\n```\n\n`npm install` runs `scripts\u002Fprepare-mediapipe-assets.cjs`, which populates generated runtime assets under `public\u002Fmediapipe`, `public\u002Fmodels`, and `public\u002Fbin`. These generated assets are ignored by git and can be recreated with:\n\n```bash\nnpm run prepare-assets\n```\n\n## Build\n\n```bash\nnpm run build\nnpm run dist:dir\n```\n\nThe unpacked v4 desktop app is written to `release\u002Fmac-*` on macOS. Use `npm run dist` to create DMG\u002FZIP installers.\n\n## QA\n\n```bash\nnpm run verify           # smoke checks\nnpm run verify:quality   # unified quality-score sync check\nnpm run verify:engines   # engine\u002Fruntime checks\nnpm run verify:e2e       # headless Electron export (asserts OpenPose mp4 + keypoints in the bundle)\nnpm run verify:all       # verify + build + verify:e2e\nnpm run screenshots\n```\n\nThe screenshot command writes GitHub-ready images to `docs\u002Fscreenshots\u002F`.\n\n## Sharing Notes\n\nThe current local macOS build can run on this machine and can be shared with trusted testers, but it is not yet Apple Developer ID signed or notarized. For broad public sharing, the next packaging step is to add a real Apple Developer certificate, sign the app, notarize it with Apple, and then build the distributable DMG\u002FZIP.\n\n## Open Source and Attribution\n\nThis project uses Apache-2.0 because it is permissive, standard, and includes a patent grant plus NOTICE preservation. Forks and derivative works must preserve copyright, license, and applicable attribution notices when redistributed.\n\nStandard open-source licenses cannot force every fork to display a prominent in-app credit badge or marketing credit. If you need that kind of mandatory public-facing credit, use a custom source-available license instead of a standard open-source license. For this open-source release, the repo includes:\n\n- `LICENSE`: Apache License 2.0.\n- `NOTICE`: Sam Wasserman \u002F Wasserman Productions \u002F Wasserman.ai attribution notice.\n- `CITATION.cff`: GitHub-compatible citation metadata.\n\n## Future Ideas\n\n- Add a true shot-board view for multiple clips in one project.\n- Add batch processing for entire reference folders.\n- Add ControlNet preset templates for common ComfyUI graphs.\n- Add a direct Blender export that creates a `.blend` file automatically.\n- Add team\u002Fproject metadata and production notes per shot.\n- Add signed and notarized release builds for easier public distribution.\n\n## Attribution\n\nMotion Previs Studio v4 was developed and created by **Sam Wasserman** for **Wasserman Productions** and **Wasserman.ai**.\n\n- [WassermanProductions.com](https:\u002F\u002Fwassermanproductions.com)\n- [Wasserman.ai](https:\u002F\u002Fwasserman.ai)\n","Motion Previs Studio 是一款开源桌面应用，专为影视制作中 AI 视频生成前的精细化预可视化（previs）设计。它支持从源视频帧中高精度提取人物姿态（OpenPose BODY_25 格式）、深度图、摄像机运动参数（基于背景掩码的光流解算）、语义遮罩与边缘控制层，并打包为兼容 Seedance、ComfyUI、Runway、Kling 等主流 AI 视频工具的标准化控制参考包。项目采用 TypeScript 开发，具备确定性帧编码、IPC 安全沙箱、项目状态持久化及一键发送至 Blockout 等工程化特性。适用于导演、VFX 艺术家和 AI 影视工作流工程师在生成前快速验证镜头构图、运镜逻辑与角色动线。",2,"2026-07-09 02:30:12","CREATED_QUERY"]