Python SDK types

`FileRef`

A reference to an uploaded file, returned by upload_file(). Pass into send_command() to attach files to a command.

Definition

@dataclass(frozen=True)
class FileRef:
    upload_id: str    # Upload identifier
    name: str         # Filename
    mime_type: str    # MIME type (e.g. "image/jpeg")
    size: int         # File size in bytes

See File Uploads for usage examples.

`ReactorStatus`

Connection state enum. A str subclass, so it compares equal to the plain string too (ReactorStatus.READY == "ready").

Definition

from reactor_sdk import ReactorStatus

class ReactorStatus(str, Enum):
    DISCONNECTED = "disconnected"  # No active connection
    CONNECTING   = "connecting"    # Negotiating with the Reactor Platform
    WAITING      = "waiting"       # Waiting for a GPU to be assigned
    READY        = "ready"         # Connected to the model

`ReactorError`

Raised when a native operation fails — connect(), send_command(), upload_file(), request_clip(), and similarly for any other async method backed by the native library — and the payload of the "error" event / on_error. The same class either way: what on_error hands you is not a separate type that happens to agree with the exception, it is the exception. It is also the base class of a small hierarchy: every code in the error codes table below has its own subclass, so you can catch a specific failure by class instead of parsing .code.

Definition

class ReactorError(Exception):
    code: str = "INTERNAL_ERROR"

    def __init__(
        self,
        message: str,
        *,
        code: str | None = None,
        recoverable: bool = False,
        status: int | None = None,
        operation: str | None = None,
        retry_after_ms: float | None = None,
        timestamp_ms: float | None = None,
    ) -> None: ...

Argument	Type	Description
`code`	`str`	Required. A stable, matchable code — see Error codes below, or a code the platform sent for a request it rejected and this package doesn’t have a class for.
`message`	`str`	Required. The human-readable explanation.
`recoverable`	`bool`	Whether the same call could succeed later. `True` is about the moment — a timeout, a 5xx, a transport that dropped — so waiting or reconnecting is worth something. `False` is about the request itself.
`status`	`int`	The HTTP status, when the failure came from one; `None` otherwise.
`operation`	`str`	Which call failed, e.g. `"connect"`, `"send_command"`. `None` for a failure that isn’t tied to a specific call, like a transport that dropped on its own.
`retry_after_ms`	`float`	A backoff hint in milliseconds, when the platform sent one.
`timestamp_ms`	`float`	When this happened. Only ever set on the `on_error` event — a raised exception is already happening now, so there’s nothing this would tell you that catching it doesn’t.

Example

from reactor_sdk import ReactorError, UnauthorizedError, ConflictError

try:
    await reactor.connect()
except UnauthorizedError:
    token = await refresh()          # a specific, actionable failure
except ConflictError:
    ...                              # a previous run left the session orphaned
except ReactorError as error:
    if error.recoverable:
        await asyncio.sleep((error.retry_after_ms or 1000) / 1000)
        await reactor.reconnect()
    else:
        raise

Every class in the error codes table below imports from reactor_sdk directly. except ReactorError still catches every one of them, so existing broad except blocks keep working.

ConflictError and VersionMismatchError are real, current exceptions — don’t confuse them with the identically-named classes from the older aiortc-based py-sdk, which this package is not. Their codes and fields follow the table below, not that earlier library’s shape.

There is no component field. Earlier releases split codes by which tier of the platform failed (api, gpu); that field was removed because it wasn’t something a caller could act on, and it was possible for the same failure to be reported under two different codes depending on which tier noticed it first. Match on code alone.

Error codes

Every code in the table below has a matching exception class — the same code, the same fields, whether you catch it as an exception or receive it through on_error.

Code	Exception class	Recoverable	Description
`INVALID_STATE`	`InvalidStateError`	No	The call is not allowed from the state the client is in — most often one needing a live session, made before `connect()` or after `ready` was lost.
`DISCONNECTED`	`DisconnectedError`	Yes	The connection went away: dropped while a request was in flight, or lost after it had been established. `reconnect()` is the way back.
`NETWORK_ERROR`	`NetworkError`	Yes	The request never got a reply — DNS, TLS, a refused socket.
`REQUEST_TIMEOUT`	`RequestTimeoutError`	Yes	Sent, and nothing came back in time.
`TRANSPORT_ERROR`	`TransportError`	Yes	The media transport failed.
`UNAUTHORIZED`	`UnauthorizedError`	No	The token is missing, expired, or not scoped for this (HTTP 401 / 403).
`NOT_FOUND`	`NotFoundError`	No	No such model, session or upload (HTTP 404).
`CONFLICT`	`ConflictError`	No	The session is in a state that does not allow this (HTTP 409) — usually one left orphaned by a run that went away without disconnecting.
`RATE_LIMITED`	`RateLimitedError`	Yes	Too many requests (HTTP 429).
`BAD_REQUEST`	`BadRequestError`	No	The request itself was wrong — a 4xx other than the above, or an argument rejected here before it was sent.
`SERVER_ERROR`	`ServerError`	Yes	The platform failed, and the same request may work later (HTTP 5xx).
`VERSION_MISMATCH`	`VersionMismatchError`	No	This client and the platform disagree on the protocol (HTTP 426 / 501). Upgrade `reactor-sdk`.
`DECODE_FAILED`	`DecodeError`	No	A reply arrived and could not be understood.
`SESSION_TERMINAL`	`SessionTerminalError`	No	The session reached a state it cannot leave. Start a new one.
`MESSAGE_TOO_LARGE`	`MessageTooLargeError`	No	The payload exceeds what the data channel accepts. Use `upload_file()` instead.
`ABORTED`	`AbortedError`	No	The operation was abandoned before it finished.
`RECORDER_DISABLED`	`RecorderDisabledError`	No	A clip/recording request failed because the model’s recorder is disabled or has crashed.

Codes are open-ended. A command or a control request the model itself rejects reports the platform’s own code, which this list cannot enumerate — that raises the base ReactorError with code set to whatever arrived. Match on error.code for anything not in the table; never assume an unrecognized code means the error was malformed.

`TrackKind` / `TrackDirection`

Enums describing a Track. Both are str subclasses, so they compare equal to the plain string too.

Definition

from reactor_sdk import TrackKind, TrackDirection

class TrackKind(str, Enum):
    VIDEO = "video"
    AUDIO = "audio"

class TrackDirection(str, Enum):
    SENDONLY = "sendonly"  # Client input: you push frames into it
    RECVONLY = "recvonly"  # Model output: you receive frames from it

See Track for the object these describe.

`TrackList`

The type of reactor.tracks — a list[Track] subclass with filters that chain, for finding the track you mean without hardcoding its name.

Definition

class TrackList(list[Track]):
    def with_kind(self, kind: TrackKind | str) -> TrackList: ...
    def with_direction(self, direction: TrackDirection | str) -> TrackList: ...
    def one(self) -> Track: ...

Everything a list does keeps working — iterate, index, len() — and the filters return another TrackList, so they compose in either order:

Example

reactor.tracks                                              # every track
reactor.tracks.with_kind(TrackKind.VIDEO)                   # or "video"
reactor.tracks.with_direction(TrackDirection.RECVONLY)      # or "recvonly"

# The one you mean, with an error naming the candidates if there is not exactly one.
output = reactor.tracks.with_direction("recvonly").with_kind("video").one()

A track whose kind or direction the session hasn’t declared yet matches neither filter — there is nothing to match it against until the model’s capabilities arrive, shortly after connect(). one() raises ValueError if zero or more than one track matches, naming the candidates so the filter can be narrowed.

`Clip`

Returned by request_clip() / request_recording().

Definition

@dataclass(frozen=True)
class Clip:
    session_id: str
    kind: str
    start_marker: float
    end_marker: float
    now_marker: float
    predicted_ready_at_ms: float
    playlist_url: str

playlist_url is an HLS manifest — see Recordings for how to preview or download it.

`ConnectionStats`

Returned by get_stats().

Definition

@dataclass(frozen=True)
class ConnectionStats:
    rtt_ms: float | None                # from the candidate pair carrying the media
    jitter_s: float | None              # on the received video stream
    packet_loss_ratio: float | None     # cumulative, 0.0 to 1.0
    incoming_bitrate_bps: float | None  # measured over the window since the last call
    outgoing_bitrate_bps: float | None  # the same window, on the same terms
    available_incoming_bitrate_bps: float | None  # what the path can carry, not what flows
    available_outgoing_bitrate_bps: float | None
    target_bitrate_bps: float | None    # what the encoders aim at, summed
    frames_per_second: float | None     # on the received video stream
    candidate_type: str | None          # "host", "srflx", "prflx", or "relay"
    relay_protocol: str | None          # "udp", "tcp", or "tls" when relayed
    candidate_pair_state: str | None
    packets_received: int
    packets_lost: int
    packets_sent: int
    bytes_received: int
    bytes_sent: int
    timestamp_ms: float                 # when the sample was taken, in Unix ms
    inbound: list[InboundStream]
    outbound: list[OutboundStream]
    candidate_pairs: list[CandidatePair]

An unmeasured field is None, never zero. A missing RTT does not mean a zero-latency link. candidate_type reads "relay" when the media goes through a TURN server, which is the first thing to check when latency is bad. The SDK measures the two bitrates on the candidate pair that carries the media, over the window since the previous call. Both read None on the first call after connecting, again after a reconnect, and until ICE selects a pair. A call made less than 200 ms after the last one also reads None for them. Everything else is on every call. The SDK reads jitter_s, packet_loss_ratio and frames_per_second from the received video stream. With no video stream, the first two fall back to the receive streams there are, and frames_per_second is None. All four types import from reactor_sdk.

`InboundStream`

One receive stream’s counters, as the WebRTC engine reports them. Read from ConnectionStats.inbound.

Definition

@dataclass(frozen=True)
class InboundStream:
    ssrc: int
    kind: str | None            # "audio", "video", or None if the engine reported no kind
    packets_received: int
    packets_lost: int           # signed: duplicates can take it negative
    bytes_received: int
    jitter_s: float
    nack_count: int
    total_decode_time_s: float  # cumulative
    frames_per_second: float    # video only; 0.0 until a window is measured
    frames_decoded: int
    frames_dropped: int
    frame_width: int            # decoded frame size; 0 for audio
    frame_height: int

`OutboundStream`

One send stream’s counters. Read from ConnectionStats.outbound.

Definition

@dataclass(frozen=True)
class OutboundStream:
    ssrc: int
    kind: str | None                # "audio", "video", or None
    packets_sent: int
    retransmitted_packets_sent: int
    bytes_sent: int
    target_bitrate_bps: float       # what the encoder aims at
    frames_per_second: float        # video only; 0.0 until a window is measured
    frames_sent: int
    frame_width: int                # encoded frame size; 0 for audio
    frame_height: int
    round_trip_time_s: float
    total_round_trip_time_s: float
    fraction_lost: float            # 0.0 to 1.0
    packets_lost: int               # signed

The last four come from the far end’s report about this client, so they stay at 0.0 until it sends one. A zero there means “not measured yet”.

`CandidatePair`

One ICE candidate pair. Read from ConnectionStats.candidate_pairs.

Definition

@dataclass(frozen=True)
class CandidatePair:
    current_round_trip_time_s: float
    total_round_trip_time_s: float
    priority: int
    state: str                      # "succeeded", "waiting", "in-progress", "failed", "cancelled"
    nominated: bool                 # whether ICE selected this pair
    writable: bool
    available_outgoing_bitrate_bps: float
    available_incoming_bitrate_bps: float
    bytes_sent: int                 # everything the pair carried, RTCP and data channel included
    bytes_received: int
    packets_sent: int
    packets_received: int
    local_candidate_type: str | None    # "host", "srflx", "prflx", "relay", or None
    local_relay_protocol: str | None    # "udp", "tcp", "tls", or None when not relayed

A connection gathers many pairs, and exactly one is nominated. Only that pair carries traffic, and the rest report zeros. Read nominated rather than an average across the list.

`AuthError`

Raised by fetch_jwt() when an API key cannot be exchanged for a token — including automatically, inside connect(), when the Reactor constructor was given api_key rather than jwt.

Definition

class AuthError(RuntimeError):
    pass

`fetch_jwt()`

Exchanges an API key for a JWT. Used internally by connect() when the constructor was given api_key; call directly only if you need the token itself.

Signature

fetch_jwt(
    api_key: str,
    api_url: str = DEFAULT_API_URL,
    *,
    models: list[str] | None = None,
    max_sessions: int | None = None,
    max_session_duration_seconds: int | None = None,
    expires_after: int | None = None,
) -> str

Argument	Type	Description
`api_key`	`str`	Required. Your Reactor API key (`rk_...`).
`api_url`	`str`	The API URL. Defaults to the same production Reactor API endpoint the `Reactor` constructor itself defaults to — pass it explicitly only to mint a token against a different one.
`models`	`list[str]`	Scope the token to only create/operate sessions on these models. Omit for an unscoped token with the full permissions the key’s roles allow.
`max_sessions`	`int`	Caps how many sessions a scoped token may create. Ignored for unscoped tokens.
`max_session_duration_seconds`	`int`	Force-terminates every session the token creates after this many seconds (1 to 86 400, i.e. up to 24 hours), independent of the token’s own expiry. Ignored for unscoped tokens; the server rejects an out-of-range value at mint rather than clamping it. See Rate limits.
`expires_after`	`int`	Token lifetime in seconds; the server clamps this to its own ceiling.

Returns the token as a str. Raises AuthError if the exchange fails for any reason, including a response with no token.

In most cases you don’t need this directly. Pass api_key to the Reactor constructor and the SDK handles the exchange automatically during connect().

`download_clip()`

Fetches every segment a Clip’s playlist_url names and concatenates them. Reactor does not host clips, so this — not a URL you can hand to a player directly — is how you get one onto disk or into memory. See Recordings for the full flow.

Signature

await download_clip(
    clip: Clip,
    path: str | os.PathLike | None = None,
    *,
    on_progress: Callable[[int, int], None] | None = None,
) -> bytes | None

Argument	Type	Description
`clip`	`Clip`	Required. A `Clip` from `request_clip()` / `request_recording()`.
`path`	`str \| os.PathLike`	Stream the download straight here instead of returning it. Omitting this returns the assembled bytes instead — see the Note below on which one to reach for.
`on_progress`	`Callable[[int, int], None]`	Called after each segment finishes, as `on_progress(done, total)`. Runs on the worker thread the fetch was dispatched to, not the event loop — fine for a counter or a log line, not a place to touch anything that isn’t thread-safe.

Example

clip = await reactor.request_clip(10)

await download_clip(clip, "clip.ts")   # streamed straight to the file, returns None
data = await download_clip(clip)       # no path: returns the assembled bytes instead

Given path, streams each segment straight to the file and returns None — nothing beyond one segment is ever held in memory. This is the one to reach for with request_recording(), which has no upper bound on a session’s length. Without path, assembles and returns the full bytes instead, which does mean holding the whole clip in memory: fine for a short request_clip() result, not the default choice for a long recording.

Built on urllib.request — the fetch itself is synchronous, dispatched to a thread internally (asyncio.to_thread) so the call above is the whole thing, not something you wrap yourself. Raises urllib.error.URLError (a fetch failed) or urllib.error.HTTPError (a non-2xx response — playlist_url and its segments expire) for a failure, and ValueError if the playlist names no segments at all.

Returns interleaved MPEG-TS bytes, not an MP4 — playable as-is by most players (ffplay, VLC, mpv), but remux with ffmpeg -i clip.ts -c copy clip.mp4 first if you specifically need that container.

Get Started

Concepts

SDK Reference

Resources

Python SDK types

`FileRef`

`ReactorStatus`

`ReactorError`

Error codes

`TrackKind` / `TrackDirection`

`TrackList`

`Clip`

`ConnectionStats`

`InboundStream`

`OutboundStream`

`CandidatePair`

`AuthError`

`fetch_jwt()`

`download_clip()`

​FileRef

​ReactorStatus

​ReactorError

​Error codes

​TrackKind / TrackDirection

​TrackList

​Clip

​ConnectionStats

​InboundStream

​OutboundStream

​CandidatePair

​AuthError

​fetch_jwt()

​download_clip()

`FileRef`

`ReactorStatus`

`ReactorError`

Error codes

`TrackKind` / `TrackDirection`

`TrackList`

`Clip`

`ConnectionStats`

`InboundStream`

`OutboundStream`

`CandidatePair`

`AuthError`

`fetch_jwt()`

`download_clip()`