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. Overrides the default URL, including when local is true.

boolean

default:"false"

If true, uses http://localhost:8080 as the default API URL. Set apiUrl to use a different host or port.

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 and waits for the model’s correlated reply.

Signature

reactor.sendCommand(command: string, data?: object, scope?: MessageScope): Promise<ReactorMessage | undefined>

string

required

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

object

The command payload. Shape depends on the command.

"application" | "runtime"

default:"\"application\""

Kept for compatibility. "runtime" only has a destination for internal SDK commands (requestSchema); anything else sent with it falls through to a normal application-scope send.

The SDK carries a payload over 256 KiB, up to 64 MiB, when the runtime accepts data-channel chunking. A runtime that does not accept it keeps the 256 KiB limit, and a larger payload reports MESSAGE_TOO_LARGE.

Example

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

Resolves with the model’s reply ({ type, data }), bounded by a timeout, or undefined if the handler acknowledged the command without sending one back. A call site that never awaits the returned promise is unaffected — it fires and moves on exactly as before.

This method never rejects. A failure — the connection isn’t "ready", the send itself fails — is reported through getLastError() and the error event instead of a thrown/rejected error, so a fire-and-forget call site never produces an unhandled rejection.

Pass FileRef values from uploadFile() as parameters. A FileRef can sit at the top level of data, or inside an array or object for a parameter that takes several files. 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.

`setTrackBitrate()`

Direction: client → model. Sets bitrate bounds on a track you publish. With no bound set, a Chromium-based browser caps a sender above 960x540 at 2500 kbps, even on a fast connection. Raise maxBps to give a 720p or 1080p publish more room.

Signature

reactor.setTrackBitrate(name: string, bounds?: { minBps?: number; maxBps?: number }): Promise<void>

string

required

The name of a track you already published with publishTrack().

number

Ceiling in bits per second. Omit it to keep the browser default.

number

Floor in bits per second. Chromium honors this one. Other browsers ignore it.

Example

await reactor.publishTrack("webcam", track);
await reactor.setTrackBitrate("webcam", { maxBps: 8_000_000 });

Raising the ceiling does not make the encoder send more. It still sends only what the picture needs and what the connection allows.

`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): Promise<void>

string

required

The name of the output track to unsubscribe from.

Resolves once the unsubscribe is applied — await it rather than assuming it happened by the next line.

`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): Promise<void>

string

required

The name of the output track to subscribe to.

Resolves once the subscribe is applied — await it rather than assuming it happened by the next line.

`tracks()`

Returns the track declarations negotiated for the current connection.

Signature

reactor.tracks(): TrackCapability[]

Empty before a connection exists. See TrackCapability.

`trackMapping()`

Same as tracks(), plus each entry’s negotiated mid — the id used by getTrackByMid() / getStreamByMid().

Signature

reactor.trackMapping(): TrackMappingEntry[]

See TrackMappingEntry.

`pausedTracks()`

Returns the names of output (recvonly) tracks currently unsubscribed via pauseTrack().

Signature

reactor.pausedTracks(): string[]

`getTrackByName()` / `getStreamByName()`

Resolves a named track to the actual MediaStreamTrack (or the MediaStream containing it).

Signature

reactor.getTrackByName(name: string): MediaStreamTrack | undefined
reactor.getStreamByName(name: string): MediaStream | undefined

string

required

The track name, as declared in the model’s capabilities.

`getTrackByMid()` / `getStreamByMid()`

Resolves a track by its negotiated SDP media-section id (mid) instead of its declared name — the id trackReceived and trackMapping() carry alongside the name.

Signature

reactor.getTrackByMid(mid: string): MediaStreamTrack | undefined
reactor.getStreamByMid(mid: string): MediaStream | undefined

string

required

The track’s negotiated mid.

`getSchema()`

Returns the model’s command schema, or undefined before it has been fetched. Fetched automatically once the connection reaches "ready"; most callers should read this instead of requesting it directly.

Signature

reactor.getSchema(): ModelSchema | undefined

See schemaReceived for the corresponding event.

`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

`once()`

Registers an event listener that fires at most once, then removes itself.

Signature

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

`getStatus()`

Returns the current connection status.

Signature

reactor.getStatus(): ReactorStatus

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

`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 received. Resets to undefined on disconnect, though nothing pushes that transition as an event — re-check the snapshot after a statusChanged to "disconnected" rather than trusting a value from before it.

Signature

reactor.getCapabilities(): Capabilities | undefined

This is a translated, camelCase Capabilities — a different shape from getSessionInfo()?.capabilities below, which is the server’s raw wire format. Prefer this method (and the capabilitiesReceived event) over reading capabilities off getSessionInfo().

`getSessionInfo()`

Returns the full session response from the Reactor Platform exactly as the server sent it (snake_case field names, e.g. session_id, capabilities.protocol_version), or undefined if not connected.

Signature

reactor.getSessionInfo(): SessionResponse | 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()`

`setTrackBitrate()`

`pauseTrack()`

`resumeTrack()`

`tracks()`

`trackMapping()`

`pausedTracks()`

`getTrackByName()` / `getStreamByName()`

`getTrackByMid()` / `getStreamByMid()`

`getSchema()`

`on()`

`off()`

`once()`

`getStatus()`

`getSessionId()`

`getLastError()`

`getCapabilities()`

`getSessionInfo()`

`getStats()`

​Constructor

​new Reactor()

​Methods

​connect()

​disconnect()

​reconnect()

​sendCommand()

​uploadFile()

​requestClip()

​requestRecording()

​downloadClipAsFile()

​publishTrack()

​unpublishTrack()

​setTrackBitrate()

​pauseTrack()

​resumeTrack()

​tracks()

​trackMapping()

​pausedTracks()

​getTrackByName() / getStreamByName()

​getTrackByMid() / getStreamByMid()

​getSchema()

​on()

​off()

​once()

​getStatus()

​getSessionId()

​getLastError()

​getCapabilities()

​getSessionInfo()

​getStats()

Constructor

`new Reactor()`

Methods

`connect()`

`disconnect()`

`reconnect()`

`sendCommand()`

`uploadFile()`

`requestClip()`

`requestRecording()`

`downloadClipAsFile()`

`publishTrack()`

`unpublishTrack()`

`setTrackBitrate()`

`pauseTrack()`

`resumeTrack()`

`tracks()`

`trackMapping()`

`pausedTracks()`

`getTrackByName()` / `getStreamByName()`

`getTrackByMid()` / `getStreamByMid()`

`getSchema()`

`on()`

`off()`

`once()`

`getStatus()`

`getSessionId()`

`getLastError()`

`getCapabilities()`

`getSessionInfo()`

`getStats()`