Track

A Track is a handle onto one named media slot the model declared — not something you construct yourself. Obtain one from reactor.track(name) when you know its name, or by filtering reactor.tracks — a TrackList — when you don’t:

output = reactor.tracks.with_direction("recvonly").with_kind("video").one()

camera = await reactor.track("camera").publish()   # sendonly video
camera.push_frame(rgb_array)

output = reactor.track("output")       # recvonly video
@output.on_frame
def render(frame): ...
await output.pause()

One type covers both directions and both kinds — video and audio — because the operations are the same operations either way: push_frame() sends, on_frame() receives, pause()/resume() control a recvonly track. There is no push_video_frame / push_audio_frame split at the Track level, and no on_video_frame / on_audio_frame split: the track already knows its kind.

Push a frame, receive one, or pause/resume a recvonly track through this object. publish_track() / unpublish_track() also stay on Reactor directly — publish_track() hands back this same Track. See Reactor.track() for how to obtain one.

Calling a method the track’s direction doesn’t allow raises, on purpose — push_frame() on a recvonly track, on_frame() on a sendonly one, pause()/resume() on a sendonly track, and so on.

Properties

`name`

Signature

track.name -> str

The declared name of this track. Never changes.

`kind`

Signature

track.kind -> TrackKind | None

TrackKind.VIDEO or TrackKind.AUDIO, or None before the session has declared its tracks.

`direction`

Signature

track.direction -> TrackDirection | None

TrackDirection.SENDONLY or TrackDirection.RECVONLY, or None before the session has declared its tracks.

`mid`

Signature

track.mid -> str | None

The SDP media id, once the track has been received. None until then, and renegotiated across a reconnect.

`paused`

Signature

track.paused -> bool

Whether this track is currently paused. Read live from the session — a recvonly track is resumed automatically on reconnect, so this always reflects the current state rather than a cached one.

`published`

Signature

track.published -> bool

Whether this sendonly slot is currently activated. Always False for a recvonly track — there is nothing to activate on a slot that only receives. Unlike paused, this is not read live from the session: the session itself doesn’t record it (publish_track is a control request and unpublish_track a notification, neither leaves anything to query), so the Track tracks it locally. It goes back to False on its own when the connection leaves ready — see the note on publish() below.

Sending (`sendonly` tracks)

`publish()`

Activates this sendonly slot, so frames pushed into it go on the wire.

Signature

await track.publish() -> Track

Until this returns, push_frame() raises — an unpublished slot has no sender behind it, so the frames would be accepted and dropped rather than sent. Returns the track, so getting one and activating it can be a single line:

Example

camera = await reactor.track("camera").publish()
camera.push_frame(frame)

The activation lasts as long as the session does, not the connection: a reconnect resumes recvonly tracks automatically but does not restore a sendonly track’s publish, so publish again for anything you were sending after reactor.reconnect(). published says which side of that you’re on.

`unpublish()`

Deactivates this sendonly slot. Synchronous, unlike the other track methods — it never touches the network, only a local status check and a fire-and-forget notification.

Signature

track.unpublish() -> None

Unlike every other operation on Track, a failure here is logged, not raised — see the underlying Reactor.unpublish_track(). Unpublish is commonly the last call in a finally block; raising there would replace whatever exception was already propagating instead of adding to it. Check the logs (reactor_sdk at WARNING) if a track seems to have stayed published.

Calling it on a slot that is already not published does nothing — not even a notification to the session — deliberately: this is what that same finally block often calls after the failure that ended the session already cleared the publish, and raising there would replace the exception on its way out with this one.

`push_frame()`

Pushes one frame into this sendonly track. What data may be — and what else is needed — follows from the track’s kind. Each tab shows the parameters relevant to that frame type.

Raises InvalidStateError if the track isn’t published yet — an unpublished slot has no sender behind it, so a pushed frame would be accepted and dropped rather than sent. Call publish() first.

Video
Audio

Signature

track.push_frame(
    data: NDArray[np.uint8] | bytes,
    *,
    width: int | None = None,
    height: int | None = None,
    user_data: bytes | None = None,
) -> None

Argument	Type	Description
`data`	`NDArray[np.uint8] \| bytes`	RGB array `(height, width, 3)`, BGRA array `(height, width, 4)`, or raw BGRA bytes.
`width`, `height`	`int \| None`	Required for raw bytes; dimensions are inferred from an array. Defaults: `None`.
`user_data`	`bytes \| None`	Optional frame metadata. Default: `None`.

An RGB numpy array of shape (height, width, 3) — exactly what on_frame() delivers, needing nothing else:

Example

camera.push_frame(frame)

Or raw BGRA bytes, which need the dimensions the array would have carried:

Example

camera.push_frame(bgra, width=640, height=480)

Give exactly width * height * 4 bytes. A length that disagrees raises ValueError, because the native side reads the dimensions and not the length.A (height, width, 4) array is taken as BGRA already and sent untouched. Pass user_data to tag the frame; it reaches the model as that frame’s metadata, dropped unless the model declared that it reads tags. See Frame Metadata for the full round-trip pattern.

Signature

track.push_frame(
    data: NDArray[np.int16] | bytes,
    *,
    sample_rate: int = 48000,
    num_channels: int = 1,
    samples_per_channel: int | None = None,
) -> None

Argument	Type	Description
`data`	`NDArray[np.int16] \| bytes`	Interleaved signed 16-bit PCM.
`sample_rate`	`int`	Sample rate in Hz: 8000, 16000, 24000, 32000, 44100, or 48000. Default: `48000`.
`num_channels`	`int`	Channel count: 1 for mono or 2 for stereo. Default: `1`.
`samples_per_channel`	`int \| None`	Samples per channel. Inferred from the buffer length when `None` (the default).

Interleaved 16-bit PCM, as bytes or as a numpy int16 array. samples_per_channel is worked out from the length when not given:

Example

mic.push_frame(pcm, sample_rate=48000, num_channels=1)

WebRTC resamples locally, so push at your capture rate. Give exactly samples_per_channel * num_channels * 2 bytes. A rate or channel count outside the table, or a length that disagrees, raises ValueError.

An argument the track’s kind has no use for is refused rather than silently ignored, when ignoring it would throw away something the caller meant. user_data on an audio track raises TypeError — the wire format has no metadata trailer for audio, so a tag passed there would simply vanish. sample_rate on a video track is merely redundant and is let through.

`set_bitrate()`

Bounds what this sender may spend, in bits per second. Needs a connected client, and raises on a recvonly track.

Signature

await track.set_bitrate(*, min_bps: int | None = None, max_bps: int | None = None) -> None

Argument	Type	Description
`min_bps`	`int \| None`	Minimum sender bitrate in bits per second. Default: `None`.
`max_bps`	`int \| None`	Maximum sender bitrate in bits per second. Default: `None`.

This is the ceiling that caps a video encoder. With nothing set, WebRTC derives the maximum from the frame size alone. That maximum is 2.5 Mbps for anything above 960x540, so 720p, 1080p and 4K all cap there. A ceiling is permission rather than a target: the encoder still spends only what the congestion controller allows.

Example

await reactor.track("camera").set_bitrate(max_bps=8_000_000)

Reactor.set_bitrate() bounds the whole connection. The two apply together, so the lower of them wins.

Receiving (`recvonly` tracks)

`on_frame()`

Registers a handler for this track’s frames, converted to a NumPy array. Usable as a decorator. Only this track’s frames reach it — every media handler in this SDK is scoped to one track.

Video
Audio

Signature

track.on_frame(func: Callable) -> Callable

Argument	Type	Description
`func`	`Callable`	Handler receiving RGB frames as `NDArray[np.uint8]` with shape `(height, width, 3)`.

On a video track, the handler is given as many of (frame, frame_id, timestamp_us, user_data) as it declares parameters for, frame being an RGB array of shape (height, width, 3):

Example

@output.on_frame
def render(frame): ...

@output.on_frame
def render(frame, frame_id, timestamp_us, user_data): ...

Signature

track.on_frame(func: Callable) -> Callable

Argument	Type	Description
`func`	`Callable`	Handler receiving PCM frames as `NDArray[np.int16]` with shape `(samples, channels)`.

On an audio track, as many of (frame, sample_rate, num_channels), frame being an int16 array of shape (samples, channels):

Example

@speech.on_frame
def play(frame, sample_rate): ...

Requires numpy, which is not a hard dependency of this package. Use on_raw_frame() for the same frames without the conversion. Registering before the session has declared its tracks is allowed — the direction is checked once it’s known, and a handler that turns out to be on a sendonly track simply never fires (logged once as a warning).

`on_raw_frame()`

Registers a handler for this track’s frames as raw bytes — no NumPy conversion, no NumPy dependency. Usable as a decorator.

Signature

track.on_raw_frame(func: Callable) -> Callable

Argument	Type	Description
`func`	`Callable`	Handler for raw frames. Must accept all callback arguments listed below for the track kind.

The same routing as on_frame(), without the conversion — every argument the frame arrived with is passed straight through:

Example

@output.on_raw_frame
def forward(bgra, width, height, frame_id, timestamp_us, user_data): ...

@speech.on_raw_frame
def forward(pcm, num_samples, sample_rate, num_channels): ...

Every argument is passed — the handler must take them all.

`off_frame()`

Unregisters a handler registered with on_frame() or on_raw_frame().

Signature

track.off_frame(func: Callable) -> None

Argument	Type	Description
`func`	`Callable`	The same handler previously registered with `on_frame()` or `on_raw_frame()`.

Pausing (`recvonly` tracks)

`pause()`

Stops receiving this track. Frames stop arriving until resume().

Signature

await track.pause() -> None

`resume()`

Starts receiving this track again after pause().

Signature

await track.resume() -> None

Errors

Calling a method the track’s direction doesn’t support raises ValueError with a message naming the track, its actual direction, and what to call instead. Calling push_frame() or pause()/resume() before the session has declared any tracks raises RuntimeError telling you to wait for READY or register handlers first. See Reactor.track() for when tracks become resolvable.

Get Started

Concepts

SDK Reference

Resources

Properties

`name`

`kind`

`direction`

`mid`

`paused`

`published`

Sending (`sendonly` tracks)

`publish()`

`unpublish()`

`push_frame()`

`set_bitrate()`

Receiving (`recvonly` tracks)

`on_frame()`

`on_raw_frame()`

`off_frame()`

Pausing (`recvonly` tracks)

`pause()`

`resume()`

Errors

​Properties

​name

​kind

​direction

​mid

​paused

​published

​Sending (sendonly tracks)

​publish()

​unpublish()

​push_frame()

​set_bitrate()

​Receiving (recvonly tracks)

​on_frame()

​on_raw_frame()

​off_frame()

​Pausing (recvonly tracks)

​pause()

​resume()

​Errors

Properties

`name`

`kind`

`direction`

`mid`

`paused`

`published`

Sending (`sendonly` tracks)

`publish()`

`unpublish()`

`push_frame()`

`set_bitrate()`

Receiving (`recvonly` tracks)

`on_frame()`

`on_raw_frame()`

`off_frame()`

Pausing (`recvonly` tracks)

`pause()`

`resume()`

Errors