# Motion Previs Studio masks the subject out before it solves the camera move

> A cross-platform Electron desktop app that turns a reference shot into pose, depth, camera, mask and edge control layers, exported as a production pack for AI video tools and Blender. The camera solve, the OpenPose export and the deterministic encoding are the three pieces that matter.

**wassermanproductions/motion-previs-studio** — Open-source desktop app for AI-film motion, depth, pose, and camera-move previsualization.uggested Donation of $30 if you you can to help me keep making these tools.https://ko-fi.com/samwasserman

- Repository: https://github.com/wassermanproductions/motion-previs-studio
- Website: https://wassermanproductions.com
- Stars: 361 · Forks: 53
- Language: JavaScript
- License: Apache-2.0
- Published: 2026-09-17 · Updated: 2026-09-17 · Language: en
- Canonical page: https://hysenlabs.com/projects/wassermanproductions-motion-previs-studio

## The subject is masked out before the camera is solved

The camera solve is the part of this app that differs from a motion tracker, and the mechanism is stated plainly. Camera move is recovered with Lucas-Kanade optical flow and a RANSAC similarity fit, with the tracked subject masked out first.

That masking is what makes the result reusable. Because pan, tilt, zoom and roll are read from the background rather than from the actor, the same camera path can be applied to a different subject, car, object or environment. The feature list phrases this as subject-independent camera move keyframes solved from global frame motion.

The practical consequence is a limit as well as a benefit. The method needs background texture to measure against. A tight close-up with a soft or uniform backdrop gives the flow solver nothing to fit, and no setting in the app changes that, since the mask removes the subject rather than solving around the background.

Everything else in the pipeline, including ffmpeg normalisation of the selected range and the local control passes, feeds this solve rather than competing with it.

## Every bundle now carries a BODY_25 skeleton

The v4 release added an export aimed squarely at downstream pipelines rather than at human viewing. Every bundle ships a deterministic openpose_pose.mp4 skeleton video and a per-frame openpose_keypoints.json in the standard OpenPose BODY_25 layout, which is 75 numbers per person.

The reason is compatibility. Pipelines and ControlNet graphs that already expect OpenPose input can consume these files without a conversion step, and because the encoding is deterministic rather than interactive, two exports of the same clip produce the same skeleton.

That determinism is a project-wide decision rather than a property of this one file. Control videos are encoded frame by frame through ffmpeg with no captureStream call and no wall-clock timers, so a run does not depend on how fast the machine happened to be. For a previs tool whose output is meant to be compared across attempts, removing timing from the encode path is what makes the comparison meaningful.

## One Reference Mode control replaced overlapping selectors

Four reference modes decide what a pack preserves, and v4 replaced the earlier overlapping selectors with a single segmented control: Camera only, Actor motion, Object motion and Full scene, each with a one-line explainer.

The modes differ in what is thrown away. Camera only keeps the camera move and timing and replaces both subject and world. Actor motion preserves body movement as well as the camera move. Object motion preserves an object or vehicle path with the camera. Full scene keeps camera, blocking, subject motion and depth rhythm together.

That choice is the largest single decision in the workflow, and it is made at step three of seven, after importing and before selecting control layers.

Export scaling is the other new control: a 720p option scales control layers so the short edge is 720 for Seedance-style targets, or the original source long-edge scaling is kept. The progress rail also reports per stage along Prepare, Pose, Camera, Encode and Bundle, with a Cancel that aborts cleanly between frames.

## An MCP bridge lets an agent drive the running app

The app can be controlled from outside by an agent, which is the most unusual feature in v4. A localhost-only, token-gated control server sits alongside a zero-dependency MCP bridge, and Claude Code, Codex or Hermes can use it to import a shot, set the range, mode and settings, run the analysis, export the pack and hand a clip to Blockout.

The scope is deliberately bounded in two ways. It binds to localhost, and it requires a token, so the bridge is not a network service waiting to be found. That matters for an app that reads local video and writes bundle folders.

The same idea appears in the interface. After export, Send to Blockout passes a Reference or Depth clip straight into a running Blockout session as a ghost underlay, described as one click with no files to shuffle.

Blockout is one of two sibling apps. The other, Stem Studio, splits a finished mix back into dialogue, music and effects stems. The three are presented as standalone tools that chain in order: measure a reference here, block and export the shot in Blockout, then split the mix once the edit is done.

## The macOS install is one line, Windows is an installer and a click

Installation differs sharply by platform, and the macOS route is the shortest. On Apple Silicon, pasting one line into Terminal downloads the latest build, installs it into Applications and opens it, with no security warnings:

```bash
curl -fsSL https://raw.githubusercontent.com/wassermanproductions/motion-previs-studio/main/install.sh | bash
```

On Windows 11 the win-x64.exe installer is downloaded from GitHub Releases, and SmartScreen may appear, in which case the documented path is More info then Run anyway.

There is a specific trap on macOS for anyone who downloads the .dmg through a browser instead. Unsigned browser downloads are quarantined, so the system reports that the app is damaged even when it is not. Dragging it to Applications and running one command clears the attribute:

```bash
xattr -cr "/Applications/Motion Previs Studio v4.app"
```

The reason signed bundles are not committed is stated in the repository: this repository contains the v4 source, and local signed app bundles and generated build artifacts are intentionally left out. A comment at the top of the README also records that the project was modified for cross-platform Windows support in 2026, with details in MODIFICATIONS.md.

## package.json is marked private and the build verifies itself

The manifest identifies the project as motion-previs-studio at version 4.1.0, licensed Apache-2.0, written as an ES module with electron/main.cjs as the entry point. It also carries private set to true, so this is not a package intended for publication to a registry; the distributable is the desktop build, not an npm artefact.

The scripts show how a release is assembled and checked. dev runs Vite on a loopback host and waits for port 5173 before launching Electron against it. build prepares app metadata, runs tsc and then the Vite build. dist:dir and dist hand off to electron-builder.

The packaging scripts are the interesting part. package:mac prepares the ffmpeg assets, builds, runs verify:assets and verify:redistribution, then invokes electron-builder with the macOS configuration and --publish never. package:win generates icons first, then does the same verification pass with the Windows configuration and an NSIS target for x64. Verification is therefore a gate on release rather than an afterthought, with separate checks for assets and for redistribution.

Version 4.1.0 was released on 2026-07-10, a macOS media tool build asset tag followed on 2026-07-11, and a Windows 11 prerelease of 4.1.0 followed on 2026-07-12. The last commit on main is dated 2026-07-20.

## What a bundle contains and who the citations point at

An export can carry a reference clip, a depth video, an AI depth video when the local AI depth pass is available, edges, lineart, a motion mask, a normals proxy, an animatic and a contact sheet, delivered as both a bundle folder and a ZIP so it can be dropped into another tool. The named downstream targets are Seedance, ComfyUI, Blender, Runway and Kling.

The processing behind those files is described in enough detail to be checked. Video arrives as a local file through Electron file access or as a YouTube-compatible or direct web URL through yt-dlp. The chosen range is normalised with ffmpeg, and MediaPipe Pose Landmarker runs locally in the renderer to produce 2D and world-space landmarks, with settings for model choice, detection confidence, tracking confidence, smoothing, temporal gap filling, sample FPS and maximum people.

Sessions persist, covering the media path, trim, settings, mode and last bundle, and are offered back for restore on relaunch.

The licensing terms ask for something specific: preserve the NOTICE file and cite Sam Wasserman when using or building on the work. Alongside it the repository carries CITATION.cff, THIRD_PARTY_NOTICES.md and an ASSET_MANIFEST.json.

## Conclusion

Motion Previs Studio fits a filmmaker who already has a reference shot and wants its camera move and body motion as control layers rather than as a finished render. It does not fit anyone who needs the generated video itself, since the output is a pack of control files for another tool. Two things to settle before using it: the reference mode decides what survives, because Camera only and Full scene produce very different packs from the same clip, and the optical flow solve assumes a background worth measuring. On Windows expect the SmartScreen step, and on macOS avoid the browser download in favour of the installer line.

## FAQ

### How does Motion Previs Studio separate the camera move from the actor?

The camera move is solved with Lucas-Kanade optical flow and a RANSAC similarity fit while the tracked subject is masked out, so pan, tilt, zoom and roll are recovered from the background rather than the actor.

### What does the OpenPose export in Motion Previs Studio contain?

Every bundle ships a deterministic openpose_pose.mp4 skeleton video and a per-frame openpose_keypoints.json in the OpenPose BODY_25 layout, which is 75 numbers per person, for pipelines and ControlNet graphs expecting OpenPose input.

### What files make up an exported Motion Previs Studio production pack?

It can include reference.mp4, depth.mp4, ai_depth.mp4 when the local AI depth pass is available, edges.mp4, lineart.mp4, motion_mask.mp4, normals_proxy.mp4, animatic.mp4 and contact_sheet.jpg, delivered as a bundle folder and a ZIP.

### Can Claude Code or Codex drive Motion Previs Studio?

Yes. A localhost-only, token-gated control server with a zero-dependency MCP bridge lets them import a shot, set range, mode and settings, run analysis, export the pack and hand a clip to Blockout. The details are in mcp/README.md.

### How is Motion Previs Studio installed on macOS and Windows?

On Apple Silicon a one-line installer piped to bash downloads the build, installs it to Applications and opens it. On Windows 11 you take win-x64.exe from GitHub Releases and may need More info then Run anyway in SmartScreen. A browser-downloaded macOS .dmg is quarantined and needs the xattr -cr command on the app to clear it.

### Which other apps does Motion Previs Studio chain with?

Blockout, for grey-box previs and exporting video, depth, stills and a prompt, and Stem Studio, which splits a finished mix into dialogue, music and effects stems. Each works on its own and they chain in that order.

## Sources

- [License: Apache-2.0](https://github.com/wassermanproductions/motion-previs-studio/blob/main/LICENSE)
- [Project website](https://wassermanproductions.com)
- [README](https://github.com/wassermanproductions/motion-previs-studio/blob/main/README.md)
- [Releases](https://github.com/wassermanproductions/motion-previs-studio/releases)
- [wassermanproductions/motion-previs-studio on GitHub](https://github.com/wassermanproductions/motion-previs-studio)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/wassermanproductions-motion-previs-studio