Reality Relay
Request access

Reality Relay SDK · 0.1 alpha

Developers/API Reference

The verified
developer surface.

Classes, functions, contracts, events and error codes available in the current private JavaScript alpha.

Browse the API Read the guides

CLASS

RuntimeEngine

The process-local orchestrator for registered Scenes, Spaces and live Sessions.

new RuntimeEngine()Verified
on(type, listener)

Subscribe to one event or "*". Returns an unsubscribe function.

registerEndpoint(profile, adapter)

Validate and register a unique Space endpoint.

registerScene(manifest)

Validate and store a normalized Scene Manifest.

listEndpoints()

Return cloned endpoint profiles.

listScenes()

Return cloned Scene Manifests.

getSession(sessionId)

Return a cloned Session or null.

startSession(input)

Negotiate, connect, configure, prepare and optionally autoplay.

play(sessionId)

Play a ready or paused Session.

pause(sessionId)

Pause a playing Session.

switchScene(sessionId, sceneId)

Recheck compatibility, prepare and resume when required.

setParameter(sessionId, name, value)

Apply a live parameter when supported by the adapter.

sendInteraction(sessionId, type, payload)

Emit a structured interaction.received event.

stop(sessionId)

Stop and disconnect. Safe when already stopped.

health()

Return endpoint health and active Session count.

CLASSES · INTERFACE

Endpoint adapters

EndpointAdapter

Required methods: connect, configure, prepare, play, pause and stop. Optional methods: disconnect, setParameter and health.

InMemoryEndpointAdapter

Reference implementation for development and conformance tests. Records ordered commands and deterministic state; never controls physical hardware.

RuntimeError

Structured contract and lifecycle error with stable code and machine-readable details.

FUNCTIONS

Scene and Space contracts

validateSceneManifest(scene)

Validate content type, required fields and normalized grounding.

validateEndpointProfile(profile)

Validate Space mode, capabilities and integer native resolution.

evaluateSceneCompatibility(endpoint, scene)

Return a frozen report with required, available and missing capabilities, mode and resolution.

const report = evaluateSceneCompatibility(endpoint, scene);

{
  compatible: false,
  endpointId: "portrait-space",
  sceneId: "expert-scene",
  missingCapabilities: ["grounded_content"]
}

FUNCTIONS

Presence validation

validatePresenceProfile(profile)

Validate calibration ID, safe area and mode-specific grounding requirements.

evaluatePresenceAnalysis(profile, analysis)

Return blocked, review or passed with explicit issues.

Current blocker families cover canvas, safe area, full-body framing, contact line, support plane, shadow attachment, shadow band, floating shadow, background and shadow stability.

CLASS · FUNCTIONS

AI-video planning

PresenceVideoGenerationService

Register providers, create and submit plans, refresh jobs and review processed candidates.

DeterministicVideoProvider

No-cost simulator. Jobs are marked simulated and are not publication evidence.

validatePresenceBrief(brief)

Validate creator intent and generation constraints.

compilePresenceVideoPrompt(brief, profile)

Compile positive and negative prompt constraints.

compilePresenceVideoPlan(input)

Create the provider-independent display plan and required checks.

validateVideoGenerationProvider(provider)

Validate provider modes, outputs and lifecycle methods.

CONSTANTS

Stable alpha values

CONTENT_TYPES

video, image, live_stream, scene_3d, digital_human, ai_agent

ENDPOINT_MODES

hld, light_field, standard_preview, physical_ai

VIDEO_GENERATION_MODES

text_to_video, image_to_video

DISPLAY_MASTER

9:16 · 1080 × 1920 · 24 fps · MP4 · H.264 · yuv420p

EVENTS

Immutable lifecycle signals

interface RuntimeEvent<T> {
  type: string;
  detail: T;
  timestamp: string;
}
endpoint.registeredscene.registeredsession.preparingsession.readysession.playingsession.pausedsession.scene_changedsession.parameter_changedinteraction.receivedsession.stoppingsession.stoppedsession.failed

ERROR CODES

Branch on code, not message.

INVALID_MANIFEST

Scene or required shared field is invalid.

INVALID_GROUNDING

Grounded presentation lacks calibrated values.

INVALID_ENDPOINT

Space mode, resolution or capabilities are invalid.

INVALID_ADAPTER

Required lifecycle methods are missing.

INCOMPATIBLE_ENDPOINT

Required Scene capabilities are absent.

ENDPOINT_BUSY

Another active Session owns the Space.

INVALID_STATE

Operation is not valid in the current lifecycle state.

UNSUPPORTED_OPERATION

Adapter lacks an optional requested feature.

INVALID_PRESENCE_PROFILE

Presence Profile is invalid.

INVALID_ANALYSIS

Presence analysis input is missing or invalid.

JSON SCHEMA · DRAFT 2020-12

Machine-readable contracts.

The SDK package includes schemas for editor validation, CI and partner adapters:

@reality-relay/sdk/schemas/scene-manifest.json @reality-relay/sdk/schemas/endpoint-profile.json @reality-relay/sdk/schemas/presence-profile.json
Alpha compatibility

Breaking changes may occur between alpha versions. The physical HLD adapter, hosted control plane, public authentication and production generation providers remain planned—not current API promises.

Put the API to work

Build one compatible
presence Session.

Read the guides