Skip to main content

​
FileRef

A reference to an uploaded file, returned by uploadFile(). Pass into sendCommand() to attach files to a command.
Definition
class FileRef {
  readonly uploadId: string; // Upload identifier
  readonly name: string; // Filename
  readonly mimeType: string; // MIME type (e.g. "image/jpeg")
  readonly size: number; // File size in bytes
}
See File Uploads for usage examples.

​
ReactorStatus

The connection state of a Reactor instance.
Definition
type ReactorStatus =
  | "disconnected" // No active connection
  | "connecting" // Connecting to the API
  | "waiting" // Waiting for a GPU to be assigned
  | "ready"; // Connected to the model, can send and receive

​
ReactorState

Definition
interface ReactorState {
  status: ReactorStatus;
  lastError?: ReactorError;
}

​
ConnectOptions

Options passed to connect(), reconnect(), and the React provider’s connectOptions prop.
Definition
interface ConnectOptions {
  maxAttempts?: number; // Max SDP polling attempts before giving up. Default: 6.
  autoResumeTracks?: boolean; // Subscribe to output tracks on connect. Default: true.
  sessionId?: string; // Adopt an existing session instead of creating one.
  connectionId?: number; // Adopt a pre-registered WebRTC connection id.
}
  • maxAttempts caps how many times the SDK polls the server for its SDP answer (its reply in the WebRTC connection handshake) before the connect fails.
  • autoResumeTracks (default true) subscribes to every output (recvonly) track as soon as the connection is established, so output reaches your client on connect. The model emits frames the whole time the session runs; this only controls whether your client receives them. Set it to false to start unsubscribed and subscribe per track with resumeTrack().
  • sessionId attaches to a session that already exists, for example one created by your backend, instead of creating a new one. The token passed to connect() must be valid for the account that owns the session. Only the session’s creator can terminate it. A client that adopts the session leaves it running when it disconnects. See Sessions.
  • connectionId joins the session using a specific WebRTC connection id already registered for it, for example one your backend created and handed to this client. When omitted, the SDK registers a fresh connection and the server mints the id. connect() rejects if the id is unknown or already closed.

​
ReactorError

Definition
interface ReactorError {
  code: string;
  message: string;
  timestamp: number; // Unix timestamp
  recoverable: boolean;
  component: "api" | "gpu";
  retryAfter?: number; // Suggested retry delay in seconds
}

​
Error codes

CodeComponentRecoverableDescription
CONNECTION_FAILEDapiYesFailed to establish a connection
GPU_CONNECTION_ERRORgpuYesConnection to GPU dropped
MESSAGE_SEND_FAILEDgpuYesFailed to send a message
TRACK_PUBLISH_FAILEDgpuYesFailed to publish a media track
RECONNECTION_FAILEDgpuYesFailed to reconnect to existing session

​
TrackCapability

Describes a media track declared in the model’s capabilities. Track capabilities are provided by the server after session creation. You do not need to declare tracks on the client.
Definition
interface TrackCapability {
  name: string;
  kind: "video" | "audio";
  direction: "recvonly" | "sendonly";
}
Track names are defined by the model and handled automatically by the SDK.

​
Capabilities

The model’s capabilities, received after session creation.
Definition
interface Capabilities {
  protocol_version: string;
  tracks: TrackCapability[];
  commands?: CommandCapability[];
  emission_fps?: number | null;
}
Access via reactor.getCapabilities() or the capabilitiesReceived event.

​
Clip

A captured clip returned by requestClip() and requestRecording(). Pass it to ClipPlayer, ClipDownloadButton, or useClipDownload to play or save it.
Definition
interface Clip {
  sessionId: string;
  kind: "snap" | "recording";
  startMarker: number; // Session-relative seconds.
  endMarker: number; // Session-relative seconds.
  nowMarker: number; // Session-relative seconds at request time.
  predictedReadyAtMs: number; // Unix epoch (ms) when the clip is expected to be playable.
  playlistUrl: string; // Short-lived URL pointing at the clip.
}
A Clip is temporary. The URL it carries expires after 24 hours, so save the bytes locally if you need them later. See Recordings for usage.

​
RecordingError

Thrown by the recording APIs when a clip request, playback, or download fails.
Definition
class RecordingError extends Error {
  readonly code: RecordingErrorCode;
  readonly reason: string;
}

​
Error codes

CodeDescription
RECORDER_DISABLEDThe model does not have recording enabled, or recording crashed on the server.
INVALID_DURATIONrequestClip was called with a non-positive or non-finite duration.
DISCONNECTEDThe session disconnected before the server answered, or the request was issued while disconnected.
REQUEST_TIMEOUTThe server did not acknowledge the request in time.
CLIP_GONEThe clip is no longer available (it has aged out, or the session is unknown).
CLIP_NOT_READYThe clip was still being finalised past the expected grace window.
PLAYLIST_FETCH_FAILEDNetwork error while fetching the clip.
CHUNK_FETCH_FAILEDOne of the clip’s segments failed to download.
INVALID_PLAYLISTThe clip metadata was malformed.
DOWNLOAD_UNSUPPORTEDdownloadClipAsFile() was called outside a browser with a non-null filename. Pass filename: null to receive the Blob instead.
INTERNAL_ERRORCatch-all for unexpected SDK or server failures.

​
ClipDownloadState

State of an in-progress download, returned by useClipDownload.
Definition
type ClipDownloadState =
  | { kind: "idle" }
  | { kind: "downloading"; fetched: number; total: number }
  | { kind: "error"; message: string };
total is 0 until the SDK knows how many segments to fetch. message is suitable for inline display.

​
ConnectionStats

WebRTC connection statistics returned by useStats() and the statsUpdate event.
Definition
interface ConnectionStats {
  timestamp: number; // When stats were collected (Unix ms)
  rtt?: number; // Round-trip time in milliseconds
  framesPerSecond?: number; // Received video frames per second
  jitter?: number; // Network jitter in seconds
  packetLossRatio?: number; // Packet loss ratio (0 to 1)
  candidateType?: string; // ICE candidate type: "host", "srflx", "prflx", or "relay"
  availableOutgoingBitrate?: number; // Available outgoing bitrate in bits/second
  connectionTimings?: ConnectionTimings; // Timing breakdown of the initial handshake
}

interface ConnectionTimings {
  sessionCreationMs: number; // POST /sessions round-trip
  transportConnectingMs: number; // Transport connect (signaling, negotiation)
  totalMs: number; // End-to-end connect() → "ready"
}