Track

A reactor::Track is a handle onto one named media slot the model declared — not something you construct yourself. Ask for it by name with client.track(name), or find it by filtering client.tracks() when you don’t know the name:

auto camera = client.track("camera");        // sendonly video
camera.publish().get();
camera.push_frame({bgra.data(), bgra.size()}, 1280, 720);

auto output = client.track("main_video");    // recvonly video
auto frames = output.on_frame([](const reactor::VideoFrame& frame) {
  render(frame.bgra, frame.width, frame.height);
});

One type covers both directions and both kinds, because the operations are the same operations either way. There is no push_video_frame / push_audio_frame split and no on_video_frame / on_audio_frame split at the class level. Video and audio share push_frame() and on_frame(), and the overload has to match the track’s kind.

A handle, not an owner: it holds the client weakly, so a track parked in a capture thread cannot keep the session — and the native handle — alive for the life of that thread. Using one after the client is gone throws InvalidStateError.

Calling a method the track’s kind or direction does not allow throws, on purpose: push_frame() on a recvonly track, on_frame() on a sendonly one, pause() on a sendonly track. Each of those would otherwise reach the native layer, find nothing to do, and return — so a caller pushing at 30fps would see a model receiving nothing and no reason why.

Properties

`name()`

Signature

const std::string& name() const noexcept;

The declared name. Never changes.

`kind()`

Signature

std::optional<TrackKind> kind() const;

TrackKind::Video or TrackKind::Audio, or empty before the session has declared its tracks.

`direction()`

Signature

std::optional<TrackDirection> direction() const;

TrackDirection::SendOnly or TrackDirection::RecvOnly, or empty before the session has declared them. SendOnly is from this client’s point of view: this client sends, the model receives.

`mid()`

Signature

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

The SDP media id, once the track has been received. Read from the client rather than remembered here: it is reported as tracks arrive and is renegotiated on a reconnect.

`paused()`

Signature

bool paused() const;

Whether this track is paused right now. Read from the session, not cached, so it stays right across a reconnect — recvonly tracks resume automatically once connected, and a Track holding a stale true would go on claiming otherwise.

`published()`

Signature

bool published() const;

Whether this sendonly slot is activated. Kept by the SDK rather than read back, because the session does not record it: publish is a control request and unpublish a notification, and neither leaves anything to query.

It is cleared whenever the status leaves Ready. A reconnect resumes recvonly tracks and nothing else, so a slot published before one is not published after it — publish again. See reconnect().

Sending

`publish()`

Activates this sendonly slot, so the model has something to receive on.

Signature

std::future<void> publish();

Publishing is what puts a sender behind the slot: pushing before it would drop the frame, and this SDK refuses rather than letting it. Throws on a recvonly track, and on a session that is not Ready.

Example

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

`unpublish()`

Deactivates the slot. Synchronous, unlike the other track methods — there is no round trip, only a local state change and a fire-and-forget notification.

Signature

void unpublish();

Throws when the notification could not be made; the track then stays published, so a retry is possible.

`push_frame()`

Pushes a frame into this sendonly track. Choose the tab matching kind() to see the complete signature and arguments for that track.

Video
Audio

For TrackKind::Video.

Signature

void push_frame(Bytes bgra, std::uint32_t width, std::uint32_t height,
                const FrameOptions& options = {});

Argument	Type	Description
`bgra`	`Bytes`	BGRA pixels: exactly `width * height * 4` bytes. The SDK checks the buffer length.
`width`	`std::uint32_t`	Frame width in pixels.
`height`	`std::uint32_t`	Frame height in pixels.
`options`	`FrameOptions`	Optional metadata and capture time; defaults to `{}`. See FrameOptions.

Example

camera.push_frame({bgra.data(), bgra.size()}, 1280, 720);

For TrackKind::Audio.

Signature

void push_frame(Samples pcm, std::uint32_t sample_rate = 48'000, std::uint32_t channels = 1);

Argument	Type	Description
`pcm`	`Samples`	Interleaved signed 16-bit PCM. `pcm.size` counts samples, not bytes, and must divide evenly by `channels`.
`sample_rate`	`std::uint32_t`	Optional sample rate in Hz. One of 8000, 16000, 24000, 32000, 44100 or 48000. WebRTC resamples it locally. Defaults to 48000.
`channels`	`std::uint32_t`	Optional channel count. Mono (1) or stereo (2). Defaults to 1.

Example

mic_track.push_frame({samples.data(), samples.size()}, 16'000, 1);

Push at the rate you capture at. The SDK collects the samples into 10 ms blocks, and drops a partial block when the format changes or the session ends.

Throws InvalidStateError if the arguments do not match the track’s kind, on a recvonly track, before publish(), or once the session has left Ready. Invalid video buffer dimensions, an empty PCM buffer, an unsupported sample rate or channel count, or a PCM sample count that does not divide evenly by channels throw BadRequestError.

`FrameOptions`

Definition

struct FrameOptions {
  Bytes user_data;
  std::optional<std::int64_t> capture_time_us;
};

Field	Type	Description
`user_data`	`Bytes`	Bytes the far end reads as this frame’s metadata. Sent as-is — JSON, protobuf or anything else is between you and the model — and dropped silently by a peer that did not declare it reads them, so tagging is safe whatever the far end supports. See Frame Metadata.
`capture_time_us`	`std::optional<std::int64_t>`	When this frame was captured, read from `reactor::time_micros()`. Left empty, the frame is stamped as it is pushed, so several tracks capturing one moment arrive microseconds apart.

Example

reactor::Track::FrameOptions options;
options.user_data = {tag.data(), tag.size()};
options.capture_time_us = reactor::time_micros();
camera.push_frame({bgra.data(), bgra.size()}, 1280, 720, options);

`set_bitrate()`

Bounds what this one sender may spend, in bits per second.

Signature

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

Argument	Type	Description
`bounds`	`Bitrate`	Sender bitrate limits in bits per second. Set `min_bps`, `max_bps`, or both.

Definition

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

This is the ceiling that actually caps a video encoder, and it is easy to hit without knowing it exists: with nothing set, WebRTC derives a sender’s maximum from the frame size alone, and that maximum is 2500 kbps for anything above 960x540. 720p, 1080p and 4K all cap at 2.5 Mbps.

Example

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

Reactor::set_bitrate() is the other ceiling — the whole connection’s budget. The two are conjunctive, so raising only one changes nothing.A ceiling is permission, not a target: the encoder still spends only what the congestion controller allocated and what the picture needs. What raising it buys is headroom for the moments that would otherwise clip.

Throws on a recvonly track — the sender behind an incoming track is the far end’s, and nothing here can bound it — and on a session that is not Ready.

Receiving

`on_frame()`

Registers one handler for decoded frames from this recvonly track. The argument is always handler; kind() determines the frame type it receives.

Video
Audio

For TrackKind::Video.

Signature

Subscription on_frame(std::function<void(const VideoFrame&)> handler);

Argument	Type	Description
`handler`	`std::function<void(const VideoFrame&)>`	Receives a borrowed VideoFrame.

Example

auto frames = output.on_frame([](const reactor::VideoFrame& frame) {
  render(frame.bgra, frame.width, frame.height);
});

For TrackKind::Audio.

Signature

Subscription on_frame(std::function<void(const AudioFrame&)> handler);

Argument	Type	Description
`handler`	`std::function<void(const AudioFrame&)>`	Receives a borrowed AudioFrame.

Example

auto audio = speech.on_frame([](const reactor::AudioFrame& frame) {
  play(frame.samples, frame.num_samples, frame.sample_rate);
});

Only this track’s frames reach the handler. Copy any frame data you need to keep after it returns. Throws InvalidStateError on a sendonly track or if the handler’s frame type does not match the track’s kind.

Hold the returned Subscription. Discarding it unregisters the handler immediately.

`VideoFrame`

Definition

struct VideoFrame {
  std::string_view track_name;
  const std::uint8_t* bgra;
  std::uint32_t width;
  std::uint32_t height;
  std::uint64_t frame_id;
  std::uint64_t timestamp_us;
  Bytes user_data;

  std::size_t size_bytes() const noexcept;   // width * height * 4
  bool has_metadata() const noexcept;
};

Field	Type	Description
`track_name`	`std::string_view`	The track this arrived on. Every recvonly video track decodes into one callback, so on a session with several this is what tells them apart.
`bgra`	`const std::uint8_t*`	BGRA pixels: `width * height * 4` bytes, which `size_bytes()` returns.
`frame_id`	`std::uint64_t`	The sender’s frame counter, or 0 when the frame carried no metadata trailer.
`timestamp_us`	`std::uint64_t`	The sender’s capture time in microseconds, or 0 with no trailer. Read in the engine’s clock (`time_micros()`), not the system’s.
`user_data`	`Bytes`	Whatever the sender tagged this frame with — bytes, not text. Empty when the frame carried no trailer, which is the normal case for a model that does not tag.

The pixels are borrowed for the duration of the handler and no longer. The library frees them when the handler returns, so anything you keep has to be copied — a pointer stored here is a use-after-free that reproduces under load and not in tests. The same goes for user_data and track_name.

The handler runs inline on the library’s delivery thread, deliberately. Blocking in it is the backpressure: while it runs, the library keeps only the newest frame and drops the ones in between. Handing frames to a queue of your own trades a bounded drop for unbounded latency and memory.This is why media handlers do not go through Options::executor, and control-event handlers do.

`AudioFrame`

Definition

struct AudioFrame {
  std::string_view track_name;
  const std::int16_t* samples;
  std::uint32_t num_samples;   // total, across all channels
  std::uint32_t sample_rate;
  std::uint32_t channels;

  std::uint32_t frames() const noexcept;   // num_samples / channels
};

Borrowed and inline, exactly as VideoFrame. The audio queue is short and keeps its backlog rather than dropping, because there the queue is the jitter buffer and a hole in it is audible — so a slow handler here costs latency instead of frames. frames() is samples per channel, which is what a playback device asks for.

Pausing

`pause()`

Signature

std::future<void> pause();

Stops this recvonly track. Nothing is generated while paused, which on a video track is visible only as a frozen frame. Throws InvalidStateError on a sendonly track, audio or video: pausing controls what you receive, and nothing here can stop the far end from sending.

`resume()`

Signature

std::future<void> resume();

Starts it again. Throws on a sendonly track, as pause() does.

`TrackList`

The tracks a session declared, filterable — for discovery, and for a caller who would rather not hardcode a name. Returned by client.tracks().

Signature

TrackList with_kind(TrackKind kind) const;
TrackList with_direction(TrackDirection direction) const;
Track one() const;

bool empty() const noexcept;
std::size_t size() const noexcept;
const Track& operator[](std::size_t index) const;

Method	Argument	Type	Description
`with_kind()`	`kind`	`TrackKind`	Keep tracks of this media kind.
`with_direction()`	`direction`	`TrackDirection`	Keep tracks with this direction.
`operator[]`	`index`	`std::size_t`	Zero-based index into the filtered list.

Filters chain in either order, and it iterates:

Example

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

for (const auto& track : client.tracks()) {
  std::cout << track.name() << '\n';
}

one() throws NotFoundError when the list is empty and InvalidStateError when it holds more than one — a filter that matched several and a caller that wanted one is a question with no answer, and picking the first would answer it wrongly and silently.

`TrackKind` and `TrackDirection`

Definition

enum class TrackKind : std::uint8_t { Video, Audio };

enum class TrackDirection : std::uint8_t { SendOnly, RecvOnly };

Both convert to and from their wire spellings:

Signature

std::string_view to_string(TrackKind kind) noexcept;
std::string_view to_string(TrackDirection direction) noexcept;

std::optional<TrackKind> track_kind_from_string(std::string_view text) noexcept;
std::optional<TrackDirection> track_direction_from_string(std::string_view text) noexcept;

Function	Argument	Type	Description
`to_string()`	`kind`	`TrackKind`	Media kind to convert to its wire spelling.
`to_string()`	`direction`	`TrackDirection`	Direction to convert to its wire spelling.
`track_kind_from_string()`	`text`	`std::string_view`	Wire spelling of the media kind.
`track_direction_from_string()`	`text`	`std::string_view`	Wire spelling of the direction.

The parsers return empty for a value this build does not recognise, rather than guessing.

Get Started

Concepts

SDK Reference

Resources

Properties

`name()`

`kind()`

`direction()`

`mid()`

`paused()`

`published()`

Sending

`publish()`

`unpublish()`

`push_frame()`

`FrameOptions`

`set_bitrate()`

Receiving

`on_frame()`

`VideoFrame`

`AudioFrame`

Pausing

`pause()`

`resume()`

`TrackList`

`TrackKind` and `TrackDirection`

​Properties

​name()

​kind()

​direction()

​mid()

​paused()

​published()

​Sending

​publish()

​unpublish()

​push_frame()

​FrameOptions

​set_bitrate()

​Receiving

​on_frame()

​VideoFrame

​AudioFrame

​Pausing

​pause()

​resume()

​TrackList

​TrackKind and TrackDirection

Properties

`name()`

`kind()`

`direction()`

`mid()`

`paused()`

`published()`

Sending

`publish()`

`unpublish()`

`push_frame()`

`FrameOptions`

`set_bitrate()`

Receiving

`on_frame()`

`VideoFrame`

`AudioFrame`

Pausing

`pause()`

`resume()`

`TrackList`

`TrackKind` and `TrackDirection`