Skip to content

Latest commit

 

History

History
66 lines (53 loc) · 3.05 KB

protocol.md

File metadata and controls

66 lines (53 loc) · 3.05 KB

MotionStage v1 Protocol Overview

Session states

  1. Discovered
  2. TransportConnected
  3. HelloExchanged
  4. Authenticated
  5. Registered
  6. SceneSynced
  7. Active
  8. Closed

Handshake

  1. Client discovers _motionstage._udp.local service.
  2. Client opens QUIC transport.
  3. Server sends ServerHello.
  4. Client sends ClientHello.
  5. Client sends RegisterRequest.
  6. Server returns RegisterAccepted with a new session_id or RegisterRejected.
  7. Session syncs scene state and enters Active.

Control and motion payloads are sent in versioned wire envelopes (protocol_major, protocol_minor) so minor-version gates are enforced at transport decode time.

Control messages (v1.3)

  • VideoSignal(SignalMessage) routes SDP/ICE between active devices or to the server-owned WebRTC peer.
  • DrainSignals requests queued signaling messages for the active device.
  • SignalsBatch(Vec<SignalMessage>) returns the drained queue payload.
  • CreateVideoOffer { stream_id, track_id } asks the server to create an SDP offer for the requesting device.
  • VideoOffer(SdpMessage) returns an SDP offer/answer generated by server-side WebRTC state.
  • ResetSceneToBaseline { scene_id } resets scene attribute current_value fields to default_value.
  • CommitSceneBaseline { scene_id } copies scene attribute current_value into default_value.
  • CommitObjectBaseline { scene_id, object_id } copies one object's attribute current_value into default_value.
  • BaselineActionApplied { action, changed_attributes } acknowledges baseline actions with deterministic change counts.
  • Error { code, reason } provides explicit protocol-level errors instead of silently ignoring unsupported messages.

Mapping and motion

  • Motion-source clients advertise output attributes during ClientHello.
  • Motion samples are only accepted for explicitly registered mappings.
  • Mapping modifications are denied in Recording mode.
  • Lease and heartbeat policy govern reclaim behavior when a device disconnects.
  • Relative composition is server-authoritative for transform-capable targets:
    • scalar/vec: output = baseline + delta
    • quatf: output = normalize(baseline * delta)
    • mat4f: output = baseline * delta
  • Non-composable types retain absolute assignment behavior.
  • Reset/commit baseline actions are explicit control operations and are never coupled to mode transitions.
  • component_mask transforms are applied before filter chains:
    • scalar -> vector component(s)
    • vector component -> scalar
    • vector subset copy -> vector target

Video

  • DCC/camera is authoritative for stream descriptor (width, height, fps).
  • HDR profile in v1: HDR10 (BT.2020, PQ, 10-bit).
  • Non-HDR subscribers receive on-demand SDR tone-mapped stream.
  • WebRTC media sessions are server-owned peers; SDP/ICE signaling is exchanged over QUIC control integration paths.

Recording compatibility

  • CMTRK2 is the canonical format and includes marker events (ModeTransition, mapping graph markers) plus frame data.
  • CMTRK1 remains readable for backward compatibility.