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 = {});
Reactor(std::string model, Options options);

Parameter	Type	Description
`model`	`std::string`	Required. The model to connect to, as `owner/name`. A bare name resolves under `reactor/`.
`key`	`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`	`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`	`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}};

The third constructor takes no credential at all, for a local runtime that needs none.

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.

reactor::fetch_jwt() mints that token without a client or a session, so a backend can hand one to somebody else. FetchJwtOptions scopes it: models (unset with sessions, it mints an unscoped token), max_sessions and max_session_duration_seconds for what the holder may open, and expires_after for how long the token lives. sessions binds the token to sessions that already exist, by id. Without models and max_sessions, that token acts only on those sessions and cannot create new ones.

Argument	Type	Description
`key`	`const ApiKey&`	API key to exchange for a token.
`options`	`const FetchJwtOptions&`	Optional token scope and lifetime; defaults to `{}`.

Example

reactor::FetchJwtOptions token_options;
token_options.models = std::vector<std::string>{"reactor/helios"};
token_options.max_sessions = 1;

auto key = reactor::ApiKey{std::getenv("REACTOR_API_KEY")};
auto token = reactor::fetch_jwt(key, token_options).get();

`Options`

Definition

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

Parameter	Type	Description
`api_url`	`std::string`	The coordinator. `reactor::LOCAL_API_URL` is `http://localhost:8080`, for a local runtime. Default: `https://api.reactor.inc`.
`local`	`bool`	Speak a dev coordinator’s local-development protocol, accept its self-signed certificate, and skip the API-key exchange. An `api_url` left at its default becomes `reactor::LOCAL_API_URL`. A custom one is kept as it is. Default: `false`.
`executor`	`Executor`	Where control-event handlers run. Empty — the default — means the SDK’s own dispatcher thread.
`auto_resume_tracks`	`bool`	Resume every recvonly track on connect and on reconnect. Set it to `false` to leave those tracks paused until you call `Track::resume()` on the ones you want. Default: `true`.

`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() runs inline on the library’s delivery thread, for video and audio both, 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 = {});

Argument	Type	Description
`options`	`ConnectOptions`	Optional session and connection to adopt; defaults to `{}`. Fields are listed below.

Definition

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

Parameter	Type	Description
`session_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.
`connection_id`	`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 unless auto_resume_tracks is false. 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 = {});

Parameter	Type	Description
`command`	`std::string`	Required. The command name. Must match a command the model defines.
`args`	`Json`	The payload. `reactor::Json` is an alias for `nlohmann::json`.
`uploads`	`std::map<std::string, FileRef>`	Files to pass as named parameters — see `upload_file()`.

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 fails with MESSAGE_TOO_LARGE. 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);

Argument	Type	Description
`path`	`std::string`	Path to the local file to upload.

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();

A parameter that takes one file is 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.A parameter that takes several has no named slot. Put the references in args instead: a FileRef converts to Json as the upload reference the model reads.

auto first = client.upload_file("a.png").get();
auto second = client.upload_file("b.png").get();
client.send_command("set_images", {{"images", reactor::Json::array({first, second})}}).get();

`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);

Argument	Type	Description
`data`	`Bytes`	File contents, borrowed for this call.
`name`	`std::string`	File name, such as `frame.png`.
`mime_type`	`std::string`	Media type, such as `image/png`.

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);

Argument	Type	Description
`duration_seconds`	`double`	Length of the clip, counting back from the current point in the session.

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);

Argument	Type	Description
`name`	`const std::string&`	Name of the track declared by the model.

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);

Argument	Type	Description
`bounds`	`Bitrate`	Connection bitrate limits and initial target, in bits per second. Fields are listed below.

Definition

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

Parameter	Type	Description
`min_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.
`start_bps`	`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.
`max_bps`	`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

Each method takes one handler callback. Its argument type is listed in the table below. 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
`on_capabilities_received`	`const Json&`	The model’s capabilities arrived
`on_session_id_changed`	`const std::optional<std::string>&`	The session id was set or cleared

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);
Subscription on_capabilities_received(std::function<void(const Json&)> handler);
Subscription on_session_id_changed(std::function<void(const std::optional<std::string>&)> handler);

Register the last two before connect() to catch the first capabilities and the first session id. Capabilities are delivered after the declared tracks are refreshed, so tracks() is already current inside that 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() — 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_frame({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()`