Reactor Class

Reactor is the base class for every model on the platform. It speaks raw JSON over the wire: open a session, send commands by name, and receive generic message events. Typed model SDKs like HeliosModel extend Reactor with named, schema-matched methods over the same wire protocol. See the SDK Reference overview for how the two layers relate, and the Model API Reference for the commands and events a specific model accepts.

Constructor

`new Reactor()`

Creates a client for the given model. Call connect() afterward to open the session.

Signature

new Reactor(options: ReactorOptions)

string

required

The name of the model to connect to.

string

default:"https://api.reactor.inc"

The API URL.

boolean

default:"false"

If true, connects to a local runtime at http://localhost:8080. Ignores apiUrl.

Example

import { Reactor } from "@reactor-team/js-sdk";

const reactor = new Reactor({
  modelName: "your-model-name",
});

Methods

`connect()`

Establishes a connection to the Reactor Platform, waits for GPU assignment, and opens a WebRTC connection to the model.

Signature

reactor.connect(jwtToken?: string, options?: ConnectOptions): Promise<void>

string

Token for authentication. See Authentication.

ConnectOptions

Connection behavior options.

number

default:"6"

Maximum SDP polling attempts before giving up.

boolean

default:"true"

When true, every output (recvonly) track starts streaming as soon as the connection is established. Set to false to leave output tracks paused on connect and start them individually with resumeTrack().

string

Attach 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. A client that adopts a session leaves it running on disconnect; its creator owns the lifecycle.

number

Join 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.

`disconnect()`

Closes the connection. Safe to call multiple times.

Signature

reactor.disconnect(recoverable?: boolean): Promise<void>

boolean

default:"false"

If true, the session is kept alive on the server and can be resumed with reconnect(). If false, the session is terminated.

`reconnect()`

Reconnects to an existing session after a recoverable disconnect. Requires an active sessionId from a previous connection.

Signature

reactor.reconnect(options?: ConnectOptions): Promise<void>

ConnectOptions

Connection behavior options (e.g. maxAttempts).

`sendCommand()`

Sends a command to the model over the WebRTC data channel.

Signature

reactor.sendCommand(command: string, data: any): Promise<void>

string

required

The command name. Must match a command defined on the model.

object

required

The command payload. Shape depends on the command.

Example

await reactor.sendCommand("set_prompt", { prompt: "a mountain landscape" });

Pass FileRef values from uploadFile() as parameters. See File Uploads for details.

`uploadFile()`

Uploads a file and returns a FileRef that can be passed into sendCommand().

Signature

reactor.uploadFile(file: File | Blob, options?: { name?: string }): Promise<FileRef>

File | Blob

required

The file to upload.

string

Custom filename. Defaults to file.name for File objects, or "upload" for Blob objects.

Example

const ref = await reactor.uploadFile(imageFile);
await reactor.sendCommand("set_image", { image: ref });

Can only be called when the status is "ready".

`requestClip()`

Captures the last durationSeconds of the live session and resolves with a Clip.

Signature

reactor.requestClip(durationSeconds: number): Promise<Clip>

number

required

How many seconds back from “now” to capture. Capped server-side (5 minutes by default).

Example

const clip = await reactor.requestClip(10);

Throws a RecordingError on invalid input, timeout, or disconnection. See Recordings.

Can only be called when the status is "ready".

`requestRecording()`

Captures the entire session, from the start of recording up to “now”, and resolves with a Clip.

Signature

reactor.requestRecording(): Promise<Clip>

Example

const clip = await reactor.requestRecording();

Behaves like requestClip() but covers the full session. See Recordings.

Can only be called when the status is "ready".

`downloadClipAsFile()`

Downloads a Clip as a single MP4. Triggers a browser download when filename is set, or returns the Blob when filename is null.

Signature

reactor.downloadClipAsFile(
  clip: Clip,
  filename?: string | null,
  options?: DownloadClipOptions
): Promise<Blob>

Clip

required

The clip to download.

string | null

default:"\"reactor-clip.mp4\""

Filename to save. Pass null to skip the browser download and just receive the Blob.

string

JWT to authenticate the request. Required against https://api.reactor.inc. See Authentication.

AbortSignal

Cancels both the metadata fetch and the segment downloads.

(info: { fetched: number; total: number; bytes: number }) => void

Called after each segment completes. Use for progress UI.

Example

const clip = await reactor.requestClip(10);
await reactor.downloadClipAsFile(clip, "highlight.mp4", { jwt });

Reactor does not host clips. The URL on clip.playlistUrl expires after 24 hours, so download the bytes if you need them later. See Recordings.

`publishTrack()`

Direction: client → model. Publishes a media track to the model. The track name must match a sendonly track declared in the model’s capabilities. Publishing is required and explicit: the model receives nothing on the track until you call this, and connecting alone never starts sending. Only one connection may publish a given input track at a time.

Signature

reactor.publishTrack(name: string, track: MediaStreamTrack): Promise<void>

string

required

Track name. Must match a sendonly track name from the model’s capabilities.

MediaStreamTrack

required

A MediaStreamTrack from getUserMedia(), getDisplayMedia(), etc.

Example

const stream = await navigator.mediaDevices.getUserMedia({ video: true });
await reactor.publishTrack("webcam", stream.getVideoTracks()[0]);

`unpublishTrack()`

Direction: client → model. Stops publishing a track to the model, freeing the input track for another connection to publish.

Signature

reactor.unpublishTrack(name: string): Promise<void>

string

required

The name of the track to stop publishing.

`pauseTrack()`

Direction: model → client. Unsubscribes from an output (recvonly) track so your client stops receiving it. The model keeps emitting frames to the track regardless; this only controls whether they reach you. Pair with autoResumeTracks: false to choose exactly which outputs you receive.

Signature

reactor.pauseTrack(name: string): void

string

required

The name of the output track to unsubscribe from.

`resumeTrack()`

Direction: model → client. Subscribes to an output (recvonly) track so your client starts receiving it. This is a subscription, not a request to start generation: the model is already emitting frames, and there is no first-come ownership, so connections subscribe to the same output independently.

Signature

reactor.resumeTrack(name: string): void

string

required

The name of the output track to subscribe to.

`on()`

Registers an event listener.

Signature

reactor.on(event: ReactorEvent, handler: (...args: any[]) => void): void

See Events for all available event types.

Example

reactor.on("statusChanged", (status) => console.log(status));
reactor.on("message", (msg) => console.log(msg));

`off()`

Removes an event listener.

Signature

reactor.off(event: ReactorEvent, handler: (...args: any[]) => void): void

`getStatus()`

Returns the current connection status.

Signature

reactor.getStatus(): ReactorStatus

Returns "disconnected", "connecting", "waiting", or "ready".

`getState()`

Returns the current status and last error.

Signature

reactor.getState(): ReactorState

`getSessionId()`

Returns the current session ID, or undefined if not connected.

Signature

reactor.getSessionId(): string | undefined

`getLastError()`

Returns the most recent error, or undefined if no errors have occurred.

Signature

reactor.getLastError(): ReactorError | undefined

`getCapabilities()`

Returns the model’s capabilities (tracks, commands, emission FPS), or undefined if not yet connected.

Signature

reactor.getCapabilities(): Capabilities | undefined

`getSessionInfo()`

Returns the full session response from the Reactor Platform, or undefined if not connected.

Signature

reactor.getSessionInfo(): SessionInfo | undefined

`getStats()`

Returns the current WebRTC connection statistics, or undefined if not connected.

Signature

reactor.getStats(): ConnectionStats | undefined

Get Started

Concepts

SDK Reference

Resources

Constructor

`new Reactor()`

Methods

`connect()`

`disconnect()`

`reconnect()`

`sendCommand()`

`uploadFile()`

`requestClip()`

`requestRecording()`

`downloadClipAsFile()`

`publishTrack()`

`unpublishTrack()`

`pauseTrack()`

`resumeTrack()`

`on()`

`off()`

`getStatus()`

`getState()`

`getSessionId()`

`getLastError()`

`getCapabilities()`

`getSessionInfo()`

`getStats()`

​Constructor

​new Reactor()

​Methods

​connect()

​disconnect()

​reconnect()

​sendCommand()

​uploadFile()

​requestClip()

​requestRecording()

​downloadClipAsFile()

​publishTrack()

​unpublishTrack()

​pauseTrack()

​resumeTrack()

​on()

​off()

​getStatus()

​getState()

​getSessionId()

​getLastError()

​getCapabilities()

​getSessionInfo()

​getStats()

Constructor

`new Reactor()`

Methods

`connect()`

`disconnect()`

`reconnect()`

`sendCommand()`

`uploadFile()`

`requestClip()`

`requestRecording()`

`downloadClipAsFile()`

`publishTrack()`

`unpublishTrack()`

`pauseTrack()`

`resumeTrack()`

`on()`

`off()`

`getStatus()`

`getState()`

`getSessionId()`

`getLastError()`

`getCapabilities()`

`getSessionInfo()`

`getStats()`