Reactor

reactor::Reactor is one session, and the tracks and commands on it. It speaks raw JSON over the wire: open a session, send commands by name, receive generic message events. It works against any model — for the commands and events a specific one accepts, see the Model API Reference, or ask the running model itself with request_schema().

#include <reactor/reactor.hpp>

reactor::Reactor client{"reactor/helios", reactor::ApiKey{std::getenv("REACTOR_API_KEY")}};

auto status = client.on_status([](reactor::Status s) {
  std::cout << reactor::to_string(s) << '\n';
});

client.connect().get();
client.send_command("set_prompt", {{"prompt", "a mountain landscape"}}).get();
client.disconnect().get();

Async calls return std::future<T>, and failures arrive as exceptions from .get() — the same typed hierarchy a synchronous call throws. See ReactorError.

Movable, not copyable — a session has one owner. Destroying a connected client releases the native handle, but a creator that goes away without disconnect() leaves the session orphaned, and the next run cannot start until it clears.

Constructors

Signature

Reactor(std::string model, ApiKey key, Options options = {});
Reactor(std::string model, Jwt jwt, Options options = {});

std::string

required

The model to connect to, as owner/name. A bare name resolves under reactor/.

ApiKey

An API key, exchanged for a session-scoped token when connecting. Scoped to this model, so a leak is worth a handful of sessions rather than everything the key can reach.

Jwt

A token minted elsewhere, used as it is. For a server that already holds one, or a client handed one by a backend that owns the key.

Options

Everything that is not the model or the credential — see below.

ApiKey and Jwt are distinct one-field structs rather than two std::string parameters, so the credential you meant is the credential that is used:

Example

reactor::Reactor server{"reactor/helios", reactor::ApiKey{std::getenv("REACTOR_API_KEY")}};
reactor::Reactor client{"reactor/helios", reactor::Jwt{token_from_your_backend}};

Never ship an API key to an end-user’s machine. Mint a short-lived JWT on your server and pass it as Jwt. See Authentication.

`Options`

Definition

struct Options {
  std::string api_url{DEFAULT_API_URL};   // https://api.reactor.inc
  bool local = false;
  Executor executor;
};

std::string

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

The coordinator. reactor::LOCAL_API_URL is http://localhost:8080, for a local runtime.

bool

default:"false"

Accept a dev coordinator’s self-signed certificate and speak its local-development protocol. Pair it with api_url = reactor::LOCAL_API_URL.

Executor

Where control-event handlers run. Empty — the default — means the SDK’s own dispatcher thread.

`Executor`

Signature

using Executor = std::function<void(std::function<void()>)>;

By default the SDK runs control-event handlers on one thread of its own, serialised, never on a library thread. Give it an executor and it hands that callable each event instead — for a host with a loop of its own (Qt, ASIO, a game loop) that would rather own when handlers run.

Example

reactor::Options options;
options.executor = [&queue](std::function<void()> event) { queue.post(std::move(event)); };

It is called from a library thread, so it must be safe to call from any thread.

Futures do not go through the executor. A promise is settled on the library’s own completion thread, so connect().get() on the same thread that would have run the executor cannot deadlock against it.

Media handlers do not go through it either. on_frame() and on_audio() run inline on the library’s delivery thread, on purpose — blocking in one is the backpressure. See VideoFrame.

Connecting

`connect()`

Creates — or adopts — a session and brings up the transport. Resolves when the session is Ready.

Signature

std::future<void> connect(ConnectOptions options = {});

Definition

struct ConnectOptions {
  std::optional<std::string> session_id;
  std::optional<std::uint32_t> connection_id;
};

std::optional<std::string>

Join a session that already exists rather than creating one. This is how a second client attaches to the same session. A session adopted this way is not ended by disconnect() — it keeps running for its owner.

std::optional<std::uint32_t>

Adopt a connection slot a backend already registered for this session. The connection-level analogue of session_id; most callers building one connection per session leave it unset. See Multiple connections per session.

Throws the typed failure: UnauthorizedError for a token problem, ConflictError for a session a previous run left orphaned.

Example

reactor::ConnectOptions options;
options.session_id = existing_session;
second_client.connect(options).get();

`reconnect()`

Cycles the connection without ending the session — after a transient failure, or deliberately from Ready.

Signature

std::future<void> reconnect();

It tears the live connection down itself, so there is no need to disconnect() first — and doing so would end the very session this is about to reuse. Throws when there is no session to reconnect to.

RecvOnly tracks resume automatically. SendOnly tracks do not: a track published before the reconnect is not published after it, so publish again for anything you were sending. Track::published() says which side of that you are on, and push_frame() throws rather than pushing into a slot with nothing behind it.

client.reconnect().get();
camera.publish().get();

`disconnect()`

Ends the session server-side and tears down the transport.

Signature

std::future<void> disconnect();

Not recoverable — there is no parameter that keeps the session alive instead. To disconnect and later resume the same session, call reconnect(). Only ends sessions this client created; one adopted via session_id is left running for its owner.

`status()`

Signature

Status status() const;

Where the session is now, as a Status. Readable before connect() — a client that never connected reports Disconnected rather than nothing.

`session_id()`

Signature

std::optional<std::string> session_id() const;

The session’s id, once there is a session.

Commands and uploads

`send_command()`

Sends a command to the model and waits for its correlated reply.

Signature

std::future<std::optional<Json>> send_command(
    std::string command,
    Json args = Json::object(),
    std::map<std::string, FileRef> uploads = {});

std::string

required

The command name. Must match a command the model defines.

Json

The payload. reactor::Json is an alias for nlohmann::json.

std::map<std::string, FileRef>

Files to pass as named parameters — see upload_file().

The reply is {type, data}, or empty when the handler ran and acknowledged the command without returning a message, as an auto-generated set_<field> setter does. Empty is not a failure and is not folded into one:

Example

auto reply = client.send_command("set_prompt", {{"prompt", "a mountain landscape"}}).get();
if (reply) {
  std::cout << reply->dump() << '\n';
}

To fire a command without waiting on the reply, keep the future and call .get() later — or drop it, which sends the command all the same. These futures are settled by a promise rather than by std::async, so dropping one neither blocks nor cancels; it only means a failure has nowhere to be thrown.

`upload_file()`

Uploads a local file and returns a FileRef to pass into a command.

Signature

std::future<FileRef> upload_file(std::string path);

Needs a Ready session — the upload is created against it. Throws NotFoundError when the path does not exist.

Example

auto ref = client.upload_file("photo.jpg").get();
client.send_command("set_image", {}, {{"image", ref}}).get();

Uploads are passed separately rather than embedded in args. The Python SDK finds a FileRef sitting in the arguments and pulls it out; C++ has no way to recognise one inside a Json, so it is named in the third parameter instead. Explicit costs a few characters and cannot silently miss one.

`upload_bytes()`

The same result as upload_file(), for a caller who has the bytes rather than a path — a frame just rendered, a buffer just decoded.

Signature

std::future<FileRef> upload_bytes(Bytes data, std::string name, std::string mime_type);

data is borrowed for the call only.

Example

auto ref = client.upload_bytes({png.data(), png.size()}, "frame.png", "image/png").get();

`request_schema()`

Signature

std::future<Json> request_schema();

The model’s command schema, as an OpenAPI document — the same schema published on the Model API Reference pages, fetched from the running model. What to read when a command is rejected: it is the model’s own account of what it accepts, which is more current than any documentation.

Recordings

`request_clip()`

Asks for a clip covering the last duration_seconds of the session.

Signature

std::future<Clip> request_clip(double duration_seconds);

Resolves when the platform has accepted the request, which is not the same as the clip being ready — Clip::download() is what waits for that.

Example

auto clip = client.request_clip(10.0).get();
clip.download("last-ten-seconds.mp4").get();

See Recordings for the full flow.

`request_recording()`

Signature

std::future<Clip> request_recording();

The same, covering the whole session up to now.

Tracks

`track()`

The track called name, as a Track — the only way to push frames into one, receive its frames, or pause it.

Signature

Track track(const std::string& name);

Example

auto camera = client.track("camera");
camera.publish().get();

Throws NotFoundError, listing what the session does declare, for a name that is not among them. Before the session has declared anything, any name is allowed: there is nothing yet to contradict, and the refusals that matter happen when a handler is registered or a frame is pushed.

`tracks()`

Every track the session declared, as a TrackList — for discovery, and for a caller who would rather not hardcode a name.

Signature

TrackList tracks();

Example

auto output = client.tracks()
                  .with_direction(reactor::TrackDirection::RecvOnly)
                  .with_kind(reactor::TrackKind::Video)
                  .one();

Empty until the model’s capabilities arrive, shortly after connect().

`set_bitrate()`

Bounds what the whole connection may allocate, in bits per second.

Signature

std::future<void> set_bitrate(Bitrate bounds);

Definition

struct Bitrate {
  std::optional<std::int32_t> min_bps;
  std::optional<std::int32_t> start_bps;
  std::optional<std::int32_t> max_bps;
};

std::optional<std::int32_t>

A floor for the congestion controller; it will not drop below this even on a poor estimate. A floor above what the link can sustain trades graceful degradation for a fixed send rate, so choose it deliberately.

std::optional<std::int32_t>

The initial encoder target. WebRTC starts at ~300 kbps and ramps, which is visible as a few seconds of soft video.

std::optional<std::int32_t>

A ceiling on the whole connection.

There are two bitrate ceilings and they are conjunctive — the lower one wins. This is the connection-wide one. Track::set_bitrate() bounds one sender’s share of it, and that is the one that lifts WebRTC’s 2.5 Mbps video default. Raising max_bps here alone will not make a video track exceed it.

reactor::Reactor::Bitrate budget;
budget.start_bps = 4'000'000;
budget.max_bps = 12'000'000;
client.set_bitrate(budget).get();

reactor::Track::Bitrate cap;
cap.max_bps = 8'000'000;
client.track("camera").set_bitrate(cap).get();

Throws on a session that is not Ready. The bounds outlive a reconnect.

`get_stats()`

A snapshot of the live connection: RTT, jitter, packet loss, bitrates, the transport ICE selected, and the WebRTC engine’s own per-stream counters.

Signature

std::future<ConnectionStats> get_stats();

Returns a ConnectionStats. Throws on a session that is not Ready.

Example

auto stats = client.get_stats().get();
if (stats.rtt_ms) {
  std::cout << *stats.rtt_ms << " ms, " << stats.candidate_type.value_or("unknown") << '\n';
}

Events

Every on_* returns a Subscription: an RAII token that unregisters the handler when it goes out of scope.

Discarding the return value unregisters immediately. client.on_status(...); as a statement registers a handler and cancels it on the same line. Hold the token, or call .detach() to say the handler should live as long as the client does. This is the one place the C++ surface diverges from the Python one, which offers off(event, handler) — two std::functions cannot be compared, so a token is the only honest removal.

Handler	Payload	Fires when
`on_status`	`Status`	The connection status changed
`on_message`	`const Json&`	The model sent an application message, as `{type, data}`
`on_runtime_message`	`const Json&`	The platform sent one — session lifecycle notices, clip readiness
`on_track`	`Track`	An incoming track was received
`on_error`	`const ReactorError&`	A failure arrived that no call was waiting on

Signature

Subscription on_status(std::function<void(Status)> handler);
Subscription on_message(std::function<void(const Json&)> handler);
Subscription on_runtime_message(std::function<void(const Json&)> handler);
Subscription on_track(std::function<void(Track)> handler);
Subscription on_error(std::function<void(const ReactorError&)> handler);

Example

auto messages = client.on_message([](const reactor::Json& message) {
  std::cout << message.value("type", "") << '\n';
});

auto errors = client.on_error([](const reactor::ReactorError& error) {
  if (error.recoverable()) { /* reconnect */ }
});

Model messages and platform messages are separate events because they are separate things: a caller reading only on_message never has to filter the platform’s out of it.

There is no client-wide frame event. Media is delivered per track, through Track::on_frame() and Track::on_audio() — a single handler fed every incoming track of a kind at once could not tell them apart.

on_error hands you a ReactorError, the same type a failed call throws. Match on code(), or branch on recoverable() when the specific code does not matter. See ReactorError.

`time_micros()`

The engine’s monotonic clock, in microseconds — the epoch a frame’s capture time is read in.

Signature

std::int64_t time_micros() noexcept;

Read it once per unit of produced media and stamp every track with that one value: tracks are synchronised by sharing a capture time, not by reaching the encoder at the same moment.

Example

const auto captured_at = reactor::time_micros();

reactor::Track::FrameOptions options;
options.capture_time_us = captured_at;
camera.push_frame({bgra.data(), bgra.size()}, 1280, 720, options);
microphone_track.push_audio({pcm.data(), pcm.size()});

Unrelated to the system clock — a UNIX timestamp is not a substitute.

Get Started

Concepts

SDK Reference

Resources

Constructors

`Options`

`Executor`

Connecting

`connect()`

`reconnect()`

`disconnect()`

`status()`

`session_id()`

Commands and uploads

`send_command()`

`upload_file()`

`upload_bytes()`

`request_schema()`

Recordings

`request_clip()`

`request_recording()`

Tracks

`track()`

`tracks()`

`set_bitrate()`

`get_stats()`

Events

`time_micros()`

​Constructors

​Options

​Executor

​Connecting

​connect()

​reconnect()

​disconnect()

​status()

​session_id()

​Commands and uploads

​send_command()

​upload_file()

​upload_bytes()

​request_schema()

​Recordings

​request_clip()

​request_recording()

​Tracks

​track()

​tracks()

​set_bitrate()

​get_stats()

​Events

​time_micros()

Constructors

`Options`

`Executor`

Connecting

`connect()`

`reconnect()`

`disconnect()`

`status()`

`session_id()`

Commands and uploads

`send_command()`

`upload_file()`

`upload_bytes()`

`request_schema()`

Recordings

`request_clip()`

`request_recording()`

Tracks

`track()`

`tracks()`

`set_bitrate()`

`get_stats()`

Events

`time_micros()`