MotionStage

Server-authoritative runtime for virtual camera and motion workflows.

What MotionStage Is

MotionStage provides a deterministic motion runtime where the server owns scene state, mapping, and recording behavior. It is designed for:

• virtual camera ingest from devices over QUIC
• real-time mapping and filter pipelines for scene attributes
• deterministic .cmtrk capture and export to USD/CHAN
• integration across Rust crates and Python-based DCC adapters

Why MotionStage Exists

Virtual production tooling is often expensive, fragmented, or built for large studios. MotionStage exists to make the same core workflow available to everyday artists, small teams, and indie creators.

The goal is practical access:

• capture and stream motion without studio-scale infrastructure
• keep data portable with open, deterministic recording and export paths
• let artists connect familiar DCC tools through clear SDK and adapter contracts
• make iterative VP workflows reproducible on normal development hardware

MotionStage focuses on the runtime layer so creators can spend less time wiring systems together and more time making shots.

Get Started

Interactive demo (fastest path)

cargo run -p motionstage-cli -- simulate --server-bind 127.0.0.1:0 --sample-hz 120

Then in motionstage-sim>:

start
record start recordings/demo.cmtrk
status
record stop
quit

This gives you a local runtime, live motion samples, and a recording exportable by integrator crates. simulate runs an embedded server and a simulated client that connects through the same QUIC handshake/control/datagram path used by real devices. --server-bind controls the embedded server bind address; it is not a remote server connect flag.

Simulated client to an existing server

cargo run -p motionstage-cli -- simulate --connect 127.0.0.1:7788 --output-attribute demo.position

This runs in client-only mode and does not start an embedded server. Ensure scene/mapping/mode are already configured on the target server. Source outputs are normalized to fully-qualified IDs: <device-id>.<attr>[.<component>].

You can also discover a server over mDNS:

# auto-connect when exactly one server is discoverable
cargo run -p motionstage-cli -- simulate --connect discover

# select a specific server by advertised discovery name
cargo run -p motionstage-cli -- simulate --connect discover:motionstage-blender

Server mode (for real clients)

cargo run -p motionstage-cli -- serve

This starts QUIC control/datagram ingest, mDNS discovery, and scheduler loops.

Runtime Flow

1. Device discovers and connects over QUIC.
2. Control handshake negotiates versions/features and opens a session.
3. Server applies mapping transforms and filters to incoming attributes.
4. Runtime publishes snapshots for downstream systems.
5. Recording mode persists .cmtrk (CMTRK2) events.
6. Export crates produce deterministic USD or CHAN output.

Docs

• Design and Architecture
• Concepts and Workflow
• DCC Integrators
• Device Integrators
• iOS Integrators
• Protocol Overview
• Hardening Gates
• Completion Matrix

Workspace Layout

• crates/motionstage-core: scene/mapping/mode model, transform/filter engine
• crates/motionstage-server: authoritative lifecycle, sessions, scheduling, recording
• crates/motionstage-protocol: wire contracts, role/features, control negotiation
• crates/motionstage-transport-quic: QUIC transport, control streams, motion datagrams
• crates/motionstage-discovery: mDNS advertisement/browser (_motionstage._udp.local)
• crates/motionstage-media: video descriptor model and signaling queue
• crates/motionstage-webrtc: server-owned WebRTC helpers
• crates/motionstage-recording: .cmtrk read/write/index (CMTRK1 + CMTRK2)
• crates/motionstage-export-usd: deterministic USD text exporter
• crates/motionstage-export-chan: deterministic CHAN exporter
• crates/motionstage-cli: serve and simulate workflows
• crates/motionstage-testkit: integration harness and soak helpers
• crates/motionstage-sdk-swift: C ABI bridge for iOS/Swift client apps
• python/motionstage_sdk: strict OOP delegate SDK backed by the native Rust bridge
• python/blender_adapter: reference Blender delegate adapter

Validate

cargo test --workspace
python -m pip install -e ./python
python -m pytest -q python/tests
./scripts/build-swift-ios.sh