@reactor-team/js-sdk 2.12.4 → 3.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +174 -168
- package/dist/index.cjs +2580 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +1266 -0
- package/dist/index.d.ts +981 -1075
- package/dist/index.js +1722 -4079
- package/dist/index.js.map +1 -1
- package/dist/wasm/README.md +151 -0
- package/dist/wasm/package.json +21 -0
- package/dist/wasm/reactor_wasm.d.ts +439 -0
- package/dist/wasm/reactor_wasm.js +1465 -0
- package/dist/wasm/reactor_wasm_bg.wasm +0 -0
- package/dist/wasm/reactor_wasm_bg.wasm.d.ts +54 -0
- package/package.json +35 -53
- package/LICENSE +0 -201
- package/NOTICE +0 -5
- package/dist/index.d.mts +0 -1360
- package/dist/index.mjs +0 -4805
- package/dist/index.mjs.map +0 -1
package/dist/index.d.cts
ADDED
|
@@ -0,0 +1,1266 @@
|
|
|
1
|
+
import * as react from 'react';
|
|
2
|
+
import { ReactNode, CSSProperties, VideoHTMLAttributes } from 'react';
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* Every Reactor failure carries `code`, `recoverable`, `status`, `operation`,
|
|
6
|
+
* `retry_after_ms` and `timestamp_ms` — `reactor-core`'s canonical shape,
|
|
7
|
+
* shared by every SDK on it. `timestamp`/`retryAfter` are kept alongside
|
|
8
|
+
* under their previous names for compatibility — see their own doc comments
|
|
9
|
+
* below — rather than dropped, since this package's public API may only
|
|
10
|
+
* grow.
|
|
11
|
+
*
|
|
12
|
+
* There is **one class**, not two: the `error` event payload and a rejected
|
|
13
|
+
* call's error are the same shape and the same instance type.
|
|
14
|
+
*
|
|
15
|
+
* `ReactorError` is the base of a typed hierarchy keyed by `code` —
|
|
16
|
+
* `reactor-core`'s own per-failure-kind classification — so `instanceof
|
|
17
|
+
* UnauthorizedError` and `code === 'UNAUTHORIZED'` are equivalent, one just
|
|
18
|
+
* typed. Codes are open-ended (the platform can send its own), so an
|
|
19
|
+
* unrecognized one falls back to the base class itself rather than
|
|
20
|
+
* throwing.
|
|
21
|
+
*/
|
|
22
|
+
/** Fields a `ReactorError` constructor accepts, all optional — an
|
|
23
|
+
* unrecognized code still constructs cleanly on the base class, and a
|
|
24
|
+
* purely local failure (no payload at all) still constructs cleanly too. */
|
|
25
|
+
interface ReactorErrorOptions {
|
|
26
|
+
code?: string | undefined;
|
|
27
|
+
recoverable?: boolean | undefined;
|
|
28
|
+
status?: number | undefined;
|
|
29
|
+
operation?: string | undefined;
|
|
30
|
+
retry_after_ms?: number | undefined;
|
|
31
|
+
timestamp_ms?: number | undefined;
|
|
32
|
+
}
|
|
33
|
+
declare class ReactorError extends Error {
|
|
34
|
+
/** The code this class stands for. `ReactorError` itself is the fallback,
|
|
35
|
+
* so it claims none and takes whatever the payload reported. */
|
|
36
|
+
static readonly code: string;
|
|
37
|
+
/** `reactor-core`'s own canonical code for this failure — the same value
|
|
38
|
+
* used to pick this instance's class (see the typed subclasses below for
|
|
39
|
+
* the vocabulary). Open-ended: an unrecognized code still constructs the
|
|
40
|
+
* base class, with `code` set to whatever was reported. */
|
|
41
|
+
readonly code: string;
|
|
42
|
+
/** Whether the same call could succeed later. */
|
|
43
|
+
readonly recoverable: boolean;
|
|
44
|
+
/** The HTTP status, when the failure came from one. */
|
|
45
|
+
readonly status: number | undefined;
|
|
46
|
+
/** Which call failed, e.g. "connect", "sendCommand". */
|
|
47
|
+
readonly operation: string | undefined;
|
|
48
|
+
/** Backoff hint the platform sent. */
|
|
49
|
+
readonly retry_after_ms: number | undefined;
|
|
50
|
+
/** When `reactor-core` reported this failure. For a purely local one (no
|
|
51
|
+
* payload at all — see {@link ReactorErrorOptions}), this is synthesized
|
|
52
|
+
* as the construction time instead, since there's nothing to report —
|
|
53
|
+
* not a value read off the wire. */
|
|
54
|
+
readonly timestamp_ms: number;
|
|
55
|
+
/** Same value as `retry_after_ms`, under its previous name. Kept for
|
|
56
|
+
* compatibility — prefer `retry_after_ms`. */
|
|
57
|
+
readonly retryAfter: number | undefined;
|
|
58
|
+
/** Same value as `timestamp_ms`, under its previous name. Kept for
|
|
59
|
+
* compatibility — prefer `timestamp_ms`. */
|
|
60
|
+
readonly timestamp: number;
|
|
61
|
+
constructor(message: string, options?: ReactorErrorOptions);
|
|
62
|
+
}
|
|
63
|
+
/** The request never got a reply — DNS, TLS, a refused socket. */
|
|
64
|
+
declare class NetworkError extends ReactorError {
|
|
65
|
+
static readonly code = "NETWORK_ERROR";
|
|
66
|
+
}
|
|
67
|
+
/** 401 or 403: the token is missing, expired, or not scoped for this call. */
|
|
68
|
+
declare class UnauthorizedError extends ReactorError {
|
|
69
|
+
static readonly code = "UNAUTHORIZED";
|
|
70
|
+
}
|
|
71
|
+
/** 404: no such model, session or upload. */
|
|
72
|
+
declare class NotFoundError extends ReactorError {
|
|
73
|
+
static readonly code = "NOT_FOUND";
|
|
74
|
+
}
|
|
75
|
+
/** 409: the session is in a state that does not allow this — usually a
|
|
76
|
+
* session left orphaned by a previous run that went away without
|
|
77
|
+
* disconnecting. */
|
|
78
|
+
declare class ConflictError extends ReactorError {
|
|
79
|
+
static readonly code = "CONFLICT";
|
|
80
|
+
}
|
|
81
|
+
/** 429: too many requests. `retry_after_ms` carries the server's
|
|
82
|
+
* `Retry-After` when it sent one; `undefined` means back off on your own
|
|
83
|
+
* terms rather than retrying immediately. */
|
|
84
|
+
declare class RateLimitedError extends ReactorError {
|
|
85
|
+
static readonly code = "RATE_LIMITED";
|
|
86
|
+
}
|
|
87
|
+
/** A 4xx other than the ones above: the request itself was wrong. */
|
|
88
|
+
declare class BadRequestError extends ReactorError {
|
|
89
|
+
static readonly code = "BAD_REQUEST";
|
|
90
|
+
}
|
|
91
|
+
/** 5xx: the coordinator failed, and the same request may work later. */
|
|
92
|
+
declare class ServerError extends ReactorError {
|
|
93
|
+
static readonly code = "SERVER_ERROR";
|
|
94
|
+
}
|
|
95
|
+
/** This client and the platform disagree on the protocol — upgrade the SDK. */
|
|
96
|
+
declare class VersionMismatchError extends ReactorError {
|
|
97
|
+
static readonly code = "VERSION_MISMATCH";
|
|
98
|
+
}
|
|
99
|
+
/** A reply arrived and could not be understood. */
|
|
100
|
+
declare class DecodeError extends ReactorError {
|
|
101
|
+
static readonly code = "DECODE_FAILED";
|
|
102
|
+
}
|
|
103
|
+
/** The operation is not allowed from the state the client is in — most often
|
|
104
|
+
* a call that needs a live session, made before `connect()` or after the
|
|
105
|
+
* status left `"ready"`. */
|
|
106
|
+
declare class InvalidStateError extends ReactorError {
|
|
107
|
+
static readonly code = "INVALID_STATE";
|
|
108
|
+
}
|
|
109
|
+
/** The session reached a state it cannot leave. Start a new one. */
|
|
110
|
+
declare class SessionTerminalError extends ReactorError {
|
|
111
|
+
static readonly code = "SESSION_TERMINAL";
|
|
112
|
+
}
|
|
113
|
+
/** The payload exceeds what the data channel accepts — send large content
|
|
114
|
+
* with `uploadFile()` and pass the `FileRef` instead of embedding it
|
|
115
|
+
* inline in a command. */
|
|
116
|
+
declare class MessageTooLargeError extends ReactorError {
|
|
117
|
+
static readonly code = "MESSAGE_TOO_LARGE";
|
|
118
|
+
}
|
|
119
|
+
/** The media transport failed. */
|
|
120
|
+
declare class TransportError extends ReactorError {
|
|
121
|
+
static readonly code = "TRANSPORT_ERROR";
|
|
122
|
+
}
|
|
123
|
+
/** The connection went away, either dropped mid-request or lost after being
|
|
124
|
+
* established. `reconnect()` is the way back. */
|
|
125
|
+
declare class DisconnectedError extends ReactorError {
|
|
126
|
+
static readonly code = "DISCONNECTED";
|
|
127
|
+
}
|
|
128
|
+
/** The operation was sent and nothing came back in time. */
|
|
129
|
+
declare class RequestTimeoutError extends ReactorError {
|
|
130
|
+
static readonly code = "REQUEST_TIMEOUT";
|
|
131
|
+
}
|
|
132
|
+
/** The operation was abandoned before it finished. */
|
|
133
|
+
declare class AbortedError extends ReactorError {
|
|
134
|
+
static readonly code = "ABORTED";
|
|
135
|
+
}
|
|
136
|
+
/**
|
|
137
|
+
* A `requestClip()`/`requestRecording()` call failed because the model's
|
|
138
|
+
* recorder is disabled or has crashed.
|
|
139
|
+
*
|
|
140
|
+
* Unlike every other code here, `RECORDER_DISABLED` isn't platform-sent —
|
|
141
|
+
* `reactor-core` produces it by matching known reason strings on an
|
|
142
|
+
* otherwise free-text `ClipFailed` message, as a stopgap until that message
|
|
143
|
+
* carries a structured reason (tracked as REA-5403). Treat it as best-effort:
|
|
144
|
+
* a clip failure for the same underlying reason may still arrive as the
|
|
145
|
+
* base `ReactorError` (`code: "INTERNAL_ERROR"`) if the reason text ever
|
|
146
|
+
* changes upstream.
|
|
147
|
+
*
|
|
148
|
+
* `recoverable` is `false`: the recorder being disabled or crashed isn't
|
|
149
|
+
* something retrying the same `requestClip()`/`requestRecording()` call can
|
|
150
|
+
* fix — it needs an operator to re-enable or restart the recorder on the
|
|
151
|
+
* model side first.
|
|
152
|
+
*/
|
|
153
|
+
declare class RecorderDisabledError extends ReactorError {
|
|
154
|
+
static readonly code = "RECORDER_DISABLED";
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
/**
|
|
158
|
+
* Reference to a file uploaded via `Reactor.uploadFile()`. Pass it back as a
|
|
159
|
+
* top-level value in `sendCommand()`'s `data` and it's extracted and sent as
|
|
160
|
+
* a separate upload reference rather than embedded in the JSON payload —
|
|
161
|
+
* see `extractFileRefs()`.
|
|
162
|
+
*/
|
|
163
|
+
declare class FileRef {
|
|
164
|
+
readonly uploadId: string;
|
|
165
|
+
readonly name: string;
|
|
166
|
+
readonly mimeType: string;
|
|
167
|
+
readonly size: number;
|
|
168
|
+
constructor(uploadId: string, name: string, mimeType: string, size: number);
|
|
169
|
+
}
|
|
170
|
+
/**
|
|
171
|
+
* Structural check for anything shaped like a `FileRef`, for callers who'd
|
|
172
|
+
* rather duck-type than rely on `instanceof` (e.g. across two copies of this
|
|
173
|
+
* package bundled into the same page). `extractFileRefs()` uses this too,
|
|
174
|
+
* for the same reason.
|
|
175
|
+
*/
|
|
176
|
+
declare function isFileRef(value: unknown): value is FileRef;
|
|
177
|
+
|
|
178
|
+
/**
|
|
179
|
+
* The `reactor-wasm` contract, mirrored by hand.
|
|
180
|
+
*
|
|
181
|
+
* `crates/reactor-wasm` generates the real `reactor_wasm.d.ts` at
|
|
182
|
+
* `mise run build:wasm` time (see `crates/reactor-wasm/src/types.rs` and
|
|
183
|
+
* `client.rs`), but that output isn't committed — the JS SDK depends on a
|
|
184
|
+
* build step, not a checked-in file. This file re-states that same contract
|
|
185
|
+
* so `sdks/js` type-checks on a fresh checkout too, before anyone has run the
|
|
186
|
+
* wasm build. Node resolution always prefers a real, installed module over an
|
|
187
|
+
* ambient ad-hoc declaration, so once `reactor_wasm.js`/`.d.ts` exist next to
|
|
188
|
+
* this at runtime, they're what actually loads — this file only fills the gap
|
|
189
|
+
* until then.
|
|
190
|
+
*
|
|
191
|
+
* Keep in sync with the two files above. Field naming follows the wire, not
|
|
192
|
+
* JavaScript: payloads that come out of the core keep snake_case
|
|
193
|
+
* (`protocol_version`, `retry_after_ms`, `playlist_url`, ...); only the
|
|
194
|
+
* options this crate defines itself are camelCase.
|
|
195
|
+
*/
|
|
196
|
+
type ReactorStatus = 'disconnected' | 'connecting' | 'waiting' | 'ready';
|
|
197
|
+
type TrackKind = 'audio' | 'video';
|
|
198
|
+
type TrackDirection = 'recvonly' | 'sendonly';
|
|
199
|
+
interface ClientOptions {
|
|
200
|
+
modelName: string;
|
|
201
|
+
apiUrl?: string;
|
|
202
|
+
local?: boolean;
|
|
203
|
+
sdkType?: string;
|
|
204
|
+
sdkVersion?: string;
|
|
205
|
+
autoResumeTracks?: boolean;
|
|
206
|
+
extraArgs?: Record<string, unknown>;
|
|
207
|
+
heartbeatIntervalMs?: number;
|
|
208
|
+
readyTimeoutMs?: number;
|
|
209
|
+
controlRequestTimeoutMs?: number;
|
|
210
|
+
clipRequestTimeoutMs?: number;
|
|
211
|
+
maxSessionAttempts?: number;
|
|
212
|
+
maxSdpAttempts?: number;
|
|
213
|
+
sdpBackoffInitialMs?: number;
|
|
214
|
+
sdpBackoffMaxMs?: number;
|
|
215
|
+
sdpBackoffMultiplier?: number;
|
|
216
|
+
modelTracks?: TrackCapability[];
|
|
217
|
+
logLevel?: 'off' | 'error' | 'warn' | 'info' | 'debug' | 'trace';
|
|
218
|
+
}
|
|
219
|
+
interface ConnectOptions {
|
|
220
|
+
sessionId?: string;
|
|
221
|
+
connectionId?: number;
|
|
222
|
+
autoResumeTracks?: boolean;
|
|
223
|
+
maxAttempts?: number;
|
|
224
|
+
}
|
|
225
|
+
/** A token, or a resolver called before every authenticated request.
|
|
226
|
+
* Returning "" sends no Authorization header. */
|
|
227
|
+
type JwtSource = string | (() => string | Promise<string>);
|
|
228
|
+
interface TrackCapability {
|
|
229
|
+
name: string;
|
|
230
|
+
kind: TrackKind;
|
|
231
|
+
direction: TrackDirection;
|
|
232
|
+
}
|
|
233
|
+
interface TrackMappingEntry extends TrackCapability {
|
|
234
|
+
mid: string;
|
|
235
|
+
}
|
|
236
|
+
interface CommandCapability$1 {
|
|
237
|
+
name: string;
|
|
238
|
+
description?: string;
|
|
239
|
+
schema?: unknown;
|
|
240
|
+
}
|
|
241
|
+
interface Capabilities$1 {
|
|
242
|
+
protocol_version: string;
|
|
243
|
+
tracks: TrackCapability[];
|
|
244
|
+
commands?: CommandCapability$1[];
|
|
245
|
+
emission_fps?: number;
|
|
246
|
+
}
|
|
247
|
+
interface SessionInfo {
|
|
248
|
+
session_id: string;
|
|
249
|
+
state: string;
|
|
250
|
+
model?: {
|
|
251
|
+
name: string;
|
|
252
|
+
version?: string;
|
|
253
|
+
};
|
|
254
|
+
cluster?: string;
|
|
255
|
+
server_info?: {
|
|
256
|
+
server_version: string;
|
|
257
|
+
};
|
|
258
|
+
selected_transport?: {
|
|
259
|
+
protocol: string;
|
|
260
|
+
version: string;
|
|
261
|
+
};
|
|
262
|
+
capabilities?: Capabilities$1;
|
|
263
|
+
[key: string]: unknown;
|
|
264
|
+
}
|
|
265
|
+
interface ReactorMessage {
|
|
266
|
+
type: string;
|
|
267
|
+
data: unknown;
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
/** The session resource, as the coordinator reports it — see
|
|
271
|
+
* `Reactor.getSessionInfo()`. */
|
|
272
|
+
type SessionResponse = SessionInfo;
|
|
273
|
+
/**
|
|
274
|
+
* Scope tag for `sendCommand()`. This SDK has no generic runtime-scope
|
|
275
|
+
* channel — see `Reactor`'s private `sendRuntimeScopedCommand()` for what
|
|
276
|
+
* `"runtime"` actually does here (routes a couple of recognized commands to
|
|
277
|
+
* their direct equivalents, warns and falls through to a normal send for
|
|
278
|
+
* anything else).
|
|
279
|
+
*/
|
|
280
|
+
type MessageScope = 'application' | 'runtime';
|
|
281
|
+
/** Any object, except a function. */
|
|
282
|
+
type NotFunction<T> = T extends (...args: never[]) => unknown ? never : T;
|
|
283
|
+
/** One command the model declares in its capabilities. */
|
|
284
|
+
interface CommandCapability {
|
|
285
|
+
name: string;
|
|
286
|
+
description?: string;
|
|
287
|
+
schema?: unknown;
|
|
288
|
+
}
|
|
289
|
+
/**
|
|
290
|
+
* The runtime's declared capabilities for the session — negotiated tracks,
|
|
291
|
+
* and the command set when the model exposes one. Pushed once available (no
|
|
292
|
+
* explicit request needed) — see `Reactor.getCapabilities()`/
|
|
293
|
+
* `capabilitiesReceived`.
|
|
294
|
+
*
|
|
295
|
+
* camelCase — the wasm binding's own wire shape is snake_case
|
|
296
|
+
* (`protocol_version`, `emission_fps`), translated at the boundary in
|
|
297
|
+
* `internal/capabilities.ts` rather than exposed directly here.
|
|
298
|
+
*/
|
|
299
|
+
interface Capabilities {
|
|
300
|
+
protocolVersion: string;
|
|
301
|
+
tracks: TrackCapability[];
|
|
302
|
+
commands?: CommandCapability[];
|
|
303
|
+
emissionFps?: number;
|
|
304
|
+
}
|
|
305
|
+
/** One OpenAPI operation (the `post` of an event/webhook path item). */
|
|
306
|
+
interface ModelSchemaOperation {
|
|
307
|
+
operationId?: string;
|
|
308
|
+
summary?: string;
|
|
309
|
+
description?: string;
|
|
310
|
+
requestBody?: {
|
|
311
|
+
required?: boolean;
|
|
312
|
+
content?: Record<string, {
|
|
313
|
+
schema?: Record<string, unknown>;
|
|
314
|
+
}>;
|
|
315
|
+
};
|
|
316
|
+
responses?: Record<string, unknown>;
|
|
317
|
+
[key: string]: unknown;
|
|
318
|
+
}
|
|
319
|
+
/** An OpenAPI path item; the runtime only populates `post`. */
|
|
320
|
+
interface ModelSchemaPathItem {
|
|
321
|
+
post?: ModelSchemaOperation;
|
|
322
|
+
[key: string]: unknown;
|
|
323
|
+
}
|
|
324
|
+
/**
|
|
325
|
+
* The model's OpenAPI 3.1 schema, returned by `requestSchema()`/cached by
|
|
326
|
+
* `getSchema()`. A pass-through of the runtime's document, not a shape this
|
|
327
|
+
* SDK reshapes: client-triggerable events live under `paths` as
|
|
328
|
+
* `POST /events/<name>` operations, outbound model messages under
|
|
329
|
+
* `webhooks`, and media tracks under `x-reactor.tracks`. Read the parts you
|
|
330
|
+
* need.
|
|
331
|
+
*/
|
|
332
|
+
interface ModelSchema {
|
|
333
|
+
openapi: string;
|
|
334
|
+
info: {
|
|
335
|
+
title: string;
|
|
336
|
+
version: string;
|
|
337
|
+
description?: string;
|
|
338
|
+
};
|
|
339
|
+
paths?: Record<string, ModelSchemaPathItem>;
|
|
340
|
+
webhooks?: Record<string, ModelSchemaPathItem>;
|
|
341
|
+
'x-reactor'?: {
|
|
342
|
+
tracks?: Array<{
|
|
343
|
+
name: string;
|
|
344
|
+
kind: string;
|
|
345
|
+
direction: string;
|
|
346
|
+
}>;
|
|
347
|
+
};
|
|
348
|
+
components?: Record<string, unknown>;
|
|
349
|
+
[key: string]: unknown;
|
|
350
|
+
}
|
|
351
|
+
/**
|
|
352
|
+
* Severity tier of a content-moderation event delivered as the inner
|
|
353
|
+
* payload of a `runtimeMessage` with `type === "moderation"`. `"warn"`
|
|
354
|
+
* continues the session (informational only); `"terminate"` ends it shortly
|
|
355
|
+
* after the message is dispatched.
|
|
356
|
+
*/
|
|
357
|
+
type ModerationAction = 'warn' | 'terminate';
|
|
358
|
+
/**
|
|
359
|
+
* Inner payload of a `runtimeMessage` with `type === "moderation"`. Surfaces
|
|
360
|
+
* a content-moderation outcome to the client app on any moderatable input
|
|
361
|
+
* (free-text fields, file uploads) the configured policy flags — subscribe
|
|
362
|
+
* via `reactor.on("runtimeMessage", ...)` and filter on `type`.
|
|
363
|
+
*/
|
|
364
|
+
interface ModerationEvent {
|
|
365
|
+
action: ModerationAction;
|
|
366
|
+
/** Modality of the flagged input. `"text"` for string fields, `"image"`
|
|
367
|
+
* for file-upload payloads with an image MIME type. */
|
|
368
|
+
input_kind: 'text' | 'image';
|
|
369
|
+
/** Name of the inbound command/event whose payload was flagged. */
|
|
370
|
+
command: string;
|
|
371
|
+
/** Category labels that flagged (e.g. `["sexual"]`, `["violence/graphic"]`). */
|
|
372
|
+
categories: string[];
|
|
373
|
+
/** Short human-readable summary suitable for UI rendering. */
|
|
374
|
+
message: string;
|
|
375
|
+
}
|
|
376
|
+
/**
|
|
377
|
+
* `Reactor` construction options. Only `modelName` is required.
|
|
378
|
+
*
|
|
379
|
+
* Everything but `jwt` passes straight through to the wasm binding's
|
|
380
|
+
* `ClientOptions` — see `crates/reactor-wasm/src/types.rs` for what each
|
|
381
|
+
* field does. `jwt` lives here instead because the binding takes it as a
|
|
382
|
+
* second constructor argument, not a field; `Reactor` accepts one options
|
|
383
|
+
* object and splits it internally.
|
|
384
|
+
*/
|
|
385
|
+
interface ReactorOptions extends ClientOptions {
|
|
386
|
+
/** A token, or a resolver called before every authenticated request.
|
|
387
|
+
* Omit for an unauthenticated local runtime. Replaceable later by passing
|
|
388
|
+
* a new one to `connect()`. */
|
|
389
|
+
jwt?: JwtSource;
|
|
390
|
+
}
|
|
391
|
+
/**
|
|
392
|
+
* Timing breakdown of the `connect()` handshake, recorded once per connection
|
|
393
|
+
* and included in every subsequent `ConnectionStats` update. All durations
|
|
394
|
+
* are in milliseconds (from `performance.now()`).
|
|
395
|
+
*
|
|
396
|
+
* `sessionCreationMs` covers session creation/adoption (the binding's
|
|
397
|
+
* `"connecting"` phase); `transportConnectingMs` covers the session-ready
|
|
398
|
+
* wait and transport handshake together (the `"waiting"` phase) — that
|
|
399
|
+
* handshake happens entirely inside `reactor-core`, so this can only split
|
|
400
|
+
* on the phase boundaries the binding's status events expose, not on the
|
|
401
|
+
* finer steps within each one.
|
|
402
|
+
*/
|
|
403
|
+
interface ConnectionTimings {
|
|
404
|
+
sessionCreationMs: number;
|
|
405
|
+
transportConnectingMs: number;
|
|
406
|
+
/** End-to-end: connect() invocation → status "ready". */
|
|
407
|
+
totalMs: number;
|
|
408
|
+
}
|
|
409
|
+
interface ConnectionStats {
|
|
410
|
+
/** ICE candidate-pair round-trip time in milliseconds */
|
|
411
|
+
rtt?: number | undefined;
|
|
412
|
+
/** ICE candidate type: "host", "srflx", "prflx", or "relay" (TURN) */
|
|
413
|
+
candidateType?: string | undefined;
|
|
414
|
+
/** Estimated available incoming bitrate in bits/second */
|
|
415
|
+
availableIncomingBitrate?: number | undefined;
|
|
416
|
+
/** Estimated available outgoing bitrate in bits/second */
|
|
417
|
+
availableOutgoingBitrate?: number | undefined;
|
|
418
|
+
/** Real-time incoming bitrate in bits/second */
|
|
419
|
+
incomingBitrate?: number | undefined;
|
|
420
|
+
/** Real-time outgoing bitrate in bits/second */
|
|
421
|
+
outgoingBitrate?: number | undefined;
|
|
422
|
+
/** Received video frames per second */
|
|
423
|
+
framesPerSecond?: number | undefined;
|
|
424
|
+
/** Ratio of packets lost (0-1) */
|
|
425
|
+
packetLossRatio?: number | undefined;
|
|
426
|
+
/** Network jitter in seconds (from inbound-rtp) */
|
|
427
|
+
jitter?: number | undefined;
|
|
428
|
+
/** Timing breakdown of the initial connection handshake (set once, persisted until disconnect) */
|
|
429
|
+
connectionTimings?: ConnectionTimings | undefined;
|
|
430
|
+
timestamp: number;
|
|
431
|
+
}
|
|
432
|
+
/** Discriminator on a {@link Clip}. `"snap"` from `requestClip()`, `"recording"` from `requestRecording()`. */
|
|
433
|
+
type ClipKind = 'snap' | 'recording';
|
|
434
|
+
/**
|
|
435
|
+
* A finished (or soon-available) clip, from `requestClip()` / `requestRecording()`.
|
|
436
|
+
*
|
|
437
|
+
* The runtime returns immediately on every request — it does not block until
|
|
438
|
+
* the in-progress chunk finalizes. `predictedReadyAtMs` is the runtime's own
|
|
439
|
+
* estimate of when `playlistUrl` becomes fetchable; `fetchPlaylist()` and
|
|
440
|
+
* `downloadClipAsFile()` poll past it until the manifest is actually ready.
|
|
441
|
+
*/
|
|
442
|
+
interface Clip {
|
|
443
|
+
sessionId: string;
|
|
444
|
+
kind: ClipKind;
|
|
445
|
+
/** Session-relative seconds since recorder start. */
|
|
446
|
+
startMarker: number;
|
|
447
|
+
endMarker: number;
|
|
448
|
+
nowMarker: number;
|
|
449
|
+
/** Unix epoch in milliseconds. */
|
|
450
|
+
predictedReadyAtMs: number;
|
|
451
|
+
/** Absolute HLS manifest URL — short-lived; re-issuing the request produces a fresh one. */
|
|
452
|
+
playlistUrl: string;
|
|
453
|
+
}
|
|
454
|
+
interface ReactorEventMap {
|
|
455
|
+
statusChanged: (status: ReactorStatus) => void;
|
|
456
|
+
sessionIdChanged: (sessionId: string | undefined) => void;
|
|
457
|
+
error: (error: ReactorError) => void;
|
|
458
|
+
/** Application-scope payload from the model. */
|
|
459
|
+
message: (message: ReactorMessage) => void;
|
|
460
|
+
/** Platform-scope payload, same name as the Python SDK's `runtime_message`. */
|
|
461
|
+
runtimeMessage: (message: ReactorMessage) => void;
|
|
462
|
+
/** The model's command schema, fired once the auto-request on `"ready"`
|
|
463
|
+
* lands — see `getSchema()`. */
|
|
464
|
+
schemaReceived: (schema: ModelSchema) => void;
|
|
465
|
+
/** The runtime's declared capabilities, fired once available — see
|
|
466
|
+
* `getCapabilities()`. */
|
|
467
|
+
capabilitiesReceived: (capabilities: Capabilities) => void;
|
|
468
|
+
/** Fired when the model side of a track's media becomes available.
|
|
469
|
+
* `Reactor` resolves the wasm binding's raw `(name, mid)` through
|
|
470
|
+
* `getTrackByName`/`getStreamByName` before emitting, so callers don't
|
|
471
|
+
* need an extra step. `reactor-core` only ever dispatches this once the
|
|
472
|
+
* track is already resolvable (it drops the underlying event entirely
|
|
473
|
+
* otherwise), so `track`/`stream` are always real values here, never
|
|
474
|
+
* `undefined`; `mid` rides along as an extra escape hatch for callers
|
|
475
|
+
* that want the binding's own identifier (e.g. for
|
|
476
|
+
* `getTrackByMid`/`getStreamByMid`). */
|
|
477
|
+
trackReceived: (name: string, track: MediaStreamTrack, stream: MediaStream, mid: string | undefined) => void;
|
|
478
|
+
/** Fired every `STATS_INTERVAL_MS` while the session is "ready" — see
|
|
479
|
+
* `getStats()`. */
|
|
480
|
+
statsUpdate: (stats: ConnectionStats) => void;
|
|
481
|
+
}
|
|
482
|
+
type ReactorEventName = keyof ReactorEventMap;
|
|
483
|
+
|
|
484
|
+
/**
|
|
485
|
+
* Browser-side primitives for turning a `Clip` (from `requestClip()` /
|
|
486
|
+
* `requestRecording()`) into playable or downloadable media.
|
|
487
|
+
*
|
|
488
|
+
* `Clip.playlistUrl` names an HLS media playlist — `#EXT-X-VERSION:7`
|
|
489
|
+
* fragmented MP4, an `#EXT-X-MAP` init segment followed by `.m4s` media
|
|
490
|
+
* fragments — that the caller fetches and assembles; Reactor itself doesn't
|
|
491
|
+
* host clips. This module owns fetching and parsing that playlist
|
|
492
|
+
* (`fetchPlaylist` / `parsePlaylist`), wrapping it for a `<video>` element or
|
|
493
|
+
* `hls.js` (`createPlayableManifestUrl`), and assembling the referenced
|
|
494
|
+
* chunks into a flat, downloadable MP4 (`downloadClipAsFile`).
|
|
495
|
+
*/
|
|
496
|
+
|
|
497
|
+
/**
|
|
498
|
+
* Error thrown when a clip's playlist or chunks can't be fetched, parsed, or
|
|
499
|
+
* assembled into a file. Scoped to this module — a failure in
|
|
500
|
+
* `requestClip()` / `requestRecording()` themselves surfaces as a
|
|
501
|
+
* `ReactorError`, since those go through `reactor-core`'s own error channel.
|
|
502
|
+
*
|
|
503
|
+
* `code` is a stable, machine-readable identifier; `reason` is the raw
|
|
504
|
+
* string behind it (an HTTP status, a parse complaint, …).
|
|
505
|
+
*/
|
|
506
|
+
declare class RecordingError extends Error {
|
|
507
|
+
readonly code: 'CLIP_GONE' | 'CLIP_NOT_READY' | 'PLAYLIST_FETCH_FAILED' | 'CHUNK_FETCH_FAILED' | 'INVALID_PLAYLIST' | 'DOWNLOAD_UNSUPPORTED';
|
|
508
|
+
readonly reason: string;
|
|
509
|
+
constructor(code: 'CLIP_GONE' | 'CLIP_NOT_READY' | 'PLAYLIST_FETCH_FAILED' | 'CHUNK_FETCH_FAILED' | 'INVALID_PLAYLIST' | 'DOWNLOAD_UNSUPPORTED', reason: string);
|
|
510
|
+
}
|
|
511
|
+
/** Segments referenced by an HLS manifest, in playback order. */
|
|
512
|
+
interface ParsedPlaylist {
|
|
513
|
+
initUrl: string;
|
|
514
|
+
segmentUrls: string[];
|
|
515
|
+
}
|
|
516
|
+
/**
|
|
517
|
+
* Suggested grace period for callers that opt into a bounded wait by passing
|
|
518
|
+
* it as `FetchPlaylistOptions.slackMs`. Not a default — `fetchPlaylist()`
|
|
519
|
+
* polls indefinitely unless a bound is supplied.
|
|
520
|
+
*/
|
|
521
|
+
declare const DEFAULT_PLAYLIST_POLL_SLACK_MS = 15000;
|
|
522
|
+
interface FetchPlaylistOptions {
|
|
523
|
+
/**
|
|
524
|
+
* Unix epoch (ms) when the runtime predicts the boundary chunk will be
|
|
525
|
+
* servable — pass `clip.predictedReadyAtMs`. On its own this doesn't stop
|
|
526
|
+
* polling; it only anchors the optional `slackMs` deadline.
|
|
527
|
+
*/
|
|
528
|
+
predictedReadyAtMs?: number;
|
|
529
|
+
/**
|
|
530
|
+
* Opt-in grace period that turns polling into a bounded wait: a stuck
|
|
531
|
+
* `202` produces `CLIP_NOT_READY` once `max(predictedReadyAtMs, pollStart)
|
|
532
|
+
* + slackMs` passes. Omit (the default) to poll indefinitely until the
|
|
533
|
+
* manifest is ready or the caller aborts via `signal`.
|
|
534
|
+
*/
|
|
535
|
+
slackMs?: number;
|
|
536
|
+
/** Hard cap on the per-poll wait. `Retry-After` is honored but clamped. Default 2000 ms. */
|
|
537
|
+
maxRetryDelayMs?: number;
|
|
538
|
+
/** Floor on the per-poll wait so a cheap network doesn't hot-loop. Default 200 ms. */
|
|
539
|
+
minRetryDelayMs?: number;
|
|
540
|
+
/**
|
|
541
|
+
* Opt-in cap on the number of `202` responses tolerated before
|
|
542
|
+
* `CLIP_NOT_READY`. Omit (the default) to poll indefinitely.
|
|
543
|
+
*/
|
|
544
|
+
maxRetries?: number;
|
|
545
|
+
/**
|
|
546
|
+
* Aborts in-flight fetches and the inter-poll sleep — the primary way to
|
|
547
|
+
* end an unbounded wait (a timeout, a user cancel, a component unmount).
|
|
548
|
+
*/
|
|
549
|
+
signal?: AbortSignal;
|
|
550
|
+
/**
|
|
551
|
+
* Coordinator JWT, attached as `Authorization: Bearer <jwt>` on the
|
|
552
|
+
* manifest GET. Omit in local mode (HttpRuntime).
|
|
553
|
+
*/
|
|
554
|
+
jwt?: string;
|
|
555
|
+
}
|
|
556
|
+
/**
|
|
557
|
+
* Fetch `playlistUrl`, polling on `202 Accepted` — returned while the
|
|
558
|
+
* boundary chunk is still uploading.
|
|
559
|
+
*
|
|
560
|
+
* - `200` → the manifest body.
|
|
561
|
+
* - `410` / `404` → `CLIP_GONE`.
|
|
562
|
+
* - other → `PLAYLIST_FETCH_FAILED` (no retry).
|
|
563
|
+
* - `202` past an opt-in `slackMs` deadline or `maxRetries` cap → `CLIP_NOT_READY`.
|
|
564
|
+
* - aborted `signal` → rejects with the fetch/sleep `AbortError`.
|
|
565
|
+
*/
|
|
566
|
+
declare function fetchPlaylist(playlistUrl: string, options?: FetchPlaylistOptions): Promise<string>;
|
|
567
|
+
/**
|
|
568
|
+
* Parse an HLS `.m3u8` body into the init segment URL plus the ordered media
|
|
569
|
+
* segment URLs, resolving relative URLs against `playlistUrl` itself.
|
|
570
|
+
*/
|
|
571
|
+
declare function parsePlaylist(manifestBody: string, playlistUrl: string): ParsedPlaylist;
|
|
572
|
+
/**
|
|
573
|
+
* Wrap an HLS manifest body in a `blob:` URL suitable for `<video src>` or
|
|
574
|
+
* `hls.js`. Bypasses "the player can't set an Authorization header": the
|
|
575
|
+
* manifest is served from memory, and its chunk URLs are already-signed S3
|
|
576
|
+
* GETs. Path-only chunk URLs in the body are absolutized against
|
|
577
|
+
* `playlistUrl` first — without that, the browser would resolve them against
|
|
578
|
+
* the `blob:` URL's own origin instead of the runtime's.
|
|
579
|
+
*
|
|
580
|
+
* Caller owns the returned URL — revoke it via `URL.revokeObjectURL` when
|
|
581
|
+
* playback tears down. Browser-only; throws `INVALID_PLAYLIST` outside a DOM
|
|
582
|
+
* environment.
|
|
583
|
+
*/
|
|
584
|
+
declare function createPlayableManifestUrl(manifestBody: string, playlistUrl: string): string;
|
|
585
|
+
interface DownloadClipOptions {
|
|
586
|
+
/** Coordinator JWT for the manifest GET. The chunks it references are S3
|
|
587
|
+
* presigned URLs, fetched unauthenticated. */
|
|
588
|
+
jwt?: string;
|
|
589
|
+
/** Cancels both the playlist poll and any in-flight chunk fetches. */
|
|
590
|
+
signal?: AbortSignal;
|
|
591
|
+
/** Called after each chunk completes — useful for progress UI. */
|
|
592
|
+
onProgress?: (info: {
|
|
593
|
+
fetched: number;
|
|
594
|
+
total: number;
|
|
595
|
+
bytes: number;
|
|
596
|
+
}) => void;
|
|
597
|
+
}
|
|
598
|
+
/**
|
|
599
|
+
* Fetch the chunks `clip.playlistUrl` references, remux them into a flat
|
|
600
|
+
* MP4, and (when `filename` is non-null) trigger a browser `<a download>`.
|
|
601
|
+
* Pass `filename: null` to skip the download trigger and just get the Blob.
|
|
602
|
+
*
|
|
603
|
+
* See {@link assembleClipBlob} for the remux and memory-bound caveats.
|
|
604
|
+
*/
|
|
605
|
+
declare function downloadClipAsFile(clip: Clip, filename?: string | null, options?: DownloadClipOptions): Promise<Blob>;
|
|
606
|
+
|
|
607
|
+
/**
|
|
608
|
+
* A live connection to a Reactor model.
|
|
609
|
+
*/
|
|
610
|
+
declare class Reactor implements Disposable {
|
|
611
|
+
private readonly clientOptions;
|
|
612
|
+
private jwt;
|
|
613
|
+
private client;
|
|
614
|
+
private clientPromise;
|
|
615
|
+
private disposed;
|
|
616
|
+
private _lastError;
|
|
617
|
+
private schema;
|
|
618
|
+
/** Bumped on every `refreshSchema()` call — lets a call detect it's been
|
|
619
|
+
* superseded by a newer one even when `client` itself hasn't changed
|
|
620
|
+
* (e.g. two "ready" transitions on the same reused client). */
|
|
621
|
+
private schemaRefreshId;
|
|
622
|
+
private capabilities;
|
|
623
|
+
private stats;
|
|
624
|
+
private connectionTimings;
|
|
625
|
+
private statsPollHandle;
|
|
626
|
+
/** Bumped on every `startStatsPolling()`/`stopStatsPolling()` call — lets an
|
|
627
|
+
* in-flight `getStats()` recognize it's stale once it resolves, even if
|
|
628
|
+
* `this.client` hasn't changed in the meantime. */
|
|
629
|
+
private statsPollGeneration;
|
|
630
|
+
/** Set on the "connecting" status transition, cleared once `connectionTimings`
|
|
631
|
+
* is finalized on "ready" — see `handleStatusChanged()`. */
|
|
632
|
+
private connectStartTime;
|
|
633
|
+
private waitingStartTime;
|
|
634
|
+
private readonly emitter;
|
|
635
|
+
/** Serializes connect()/reconnect()/disconnect() (and the free() inside
|
|
636
|
+
* disconnect()/[Symbol.dispose]) against each other. Calling into the
|
|
637
|
+
* client concurrently with one of these (e.g. a user clicking Disconnect
|
|
638
|
+
* mid-connect) races its internal state and can throw ("attempted to
|
|
639
|
+
* take ownership of Rust value while it was borrowed") or corrupt it
|
|
640
|
+
* outright. */
|
|
641
|
+
private readonly queue;
|
|
642
|
+
constructor(options: ReactorOptions);
|
|
643
|
+
/**
|
|
644
|
+
* `jwt`, when given, replaces whatever `new Reactor({ jwt })` was given —
|
|
645
|
+
* including on a client that's still around from a recoverable
|
|
646
|
+
* `disconnect(true)`.
|
|
647
|
+
*
|
|
648
|
+
* Throws if already connected or connecting; call `disconnect()` first.
|
|
649
|
+
*/
|
|
650
|
+
connect(jwt?: JwtSource, options?: ConnectOptions): Promise<void>;
|
|
651
|
+
/**
|
|
652
|
+
* Ends the connection. By default (`recoverable = false`) this also frees
|
|
653
|
+
* the wasm resource graph — the pump/dispatcher/heartbeat tasks and the
|
|
654
|
+
* peer connection — in one step. Pass `recoverable: true` to keep the
|
|
655
|
+
* wasm client alive so a later `connect()`/`reconnect()` doesn't have to
|
|
656
|
+
* reload wasm and reconstruct it from scratch.
|
|
657
|
+
*
|
|
658
|
+
* Note this only governs the *local* resource graph — the binding's own
|
|
659
|
+
* `disconnect()` always ends the session server-side regardless of this
|
|
660
|
+
* flag, so `recoverable` isn't a way to keep the session itself alive.
|
|
661
|
+
*
|
|
662
|
+
* Queued behind any in-flight `connect()`/`reconnect()` — see `queue`'s
|
|
663
|
+
* docs for why calling into the client concurrently with one of those is
|
|
664
|
+
* unsafe.
|
|
665
|
+
*/
|
|
666
|
+
disconnect(recoverable?: boolean): Promise<void>;
|
|
667
|
+
/**
|
|
668
|
+
* Only `options.maxAttempts` has an effect here — the rest of
|
|
669
|
+
* `ConnectOptions` (session adoption, connection id, auto-resume) only
|
|
670
|
+
* makes sense when establishing a session in the first place, same as v2's
|
|
671
|
+
* `reconnect()` always ignored them.
|
|
672
|
+
*/
|
|
673
|
+
reconnect(options?: ConnectOptions): Promise<void>;
|
|
674
|
+
/**
|
|
675
|
+
* Sends a command to the model and resolves with its correlated reply.
|
|
676
|
+
*
|
|
677
|
+
* `undefined` means the handler acknowledged the command but sent no
|
|
678
|
+
* reply body. The binding's own typed signature promises `undefined` for
|
|
679
|
+
* that case, but its serializer (serde_wasm_bindgen's `json_compatible`
|
|
680
|
+
* mode) actually hands back `null` — normalized here so callers can rely
|
|
681
|
+
* on the documented type instead of the binding's serialization quirk.
|
|
682
|
+
*
|
|
683
|
+
* A `FileRef` (from `uploadFile`) may be passed as a top-level value in
|
|
684
|
+
* `data` alongside regular parameters — it is extracted and sent as a
|
|
685
|
+
* separate upload reference rather than embedded in the JSON payload.
|
|
686
|
+
*
|
|
687
|
+
* Unlike every other method here, this never rejects — a failure (the
|
|
688
|
+
* session isn't `"ready"`, the send itself fails, …) is reported through
|
|
689
|
+
* `getLastError()`/the `error` event instead, resolving with `undefined`.
|
|
690
|
+
* This is a JS-only compatibility shim, kept because callers routinely
|
|
691
|
+
* fire-and-forget `sendCommand(...)` without `await`/`catch`, and a
|
|
692
|
+
* rejection nobody handles is an unhandled-rejection warning at best. It
|
|
693
|
+
* is deliberately not applied to `publishTrack`/`uploadFile`/etc., which
|
|
694
|
+
* throw normally.
|
|
695
|
+
*
|
|
696
|
+
* `scope` is forwarded to `sendRuntimeScopedCommand()` — see there for
|
|
697
|
+
* what `"runtime"` actually does.
|
|
698
|
+
*
|
|
699
|
+
* `data` accepts any object, except a function.
|
|
700
|
+
*/
|
|
701
|
+
sendCommand<T extends object = Record<string, unknown>>(command: string, data?: NotFunction<T>, scope?: MessageScope): Promise<ReactorMessage | undefined>;
|
|
702
|
+
/**
|
|
703
|
+
* Handles `sendCommand(command, data, "runtime")` — this SDK has no
|
|
704
|
+
* generic runtime-scope channel. `reactor-core`'s `send_command` is a
|
|
705
|
+
* single channel; `requestSchema`/clip requests/heartbeat are each their
|
|
706
|
+
* own dedicated RPC instead of a scoped envelope, so there's nothing
|
|
707
|
+
* generic to route a scope through at the wire level.
|
|
708
|
+
*
|
|
709
|
+
* `requestSchema` and `requestCapabilities` route to their direct
|
|
710
|
+
* equivalents below, neither of which returns a `ReactorMessage` the way a
|
|
711
|
+
* normal `sendCommand()` reply would, so both resolve `undefined`; the
|
|
712
|
+
* actual data surfaces through `getSchema()`/`schemaReceived` and
|
|
713
|
+
* `getCapabilities()`/`capabilitiesReceived` as it already does. Anything
|
|
714
|
+
* else has no runtime-scope destination to route to — rather than silently
|
|
715
|
+
* doing nothing, it falls through as a normal application-scope send, with
|
|
716
|
+
* a console warning.
|
|
717
|
+
*/
|
|
718
|
+
private sendRuntimeScopedCommand;
|
|
719
|
+
/** Requests the model's command schema directly. Most callers don't need
|
|
720
|
+
* this — it's already fetched once and cached as soon as the session
|
|
721
|
+
* reaches `"ready"`; use `getSchema()` for that. Resolves `undefined`
|
|
722
|
+
* when the model doesn't expose a schema — the binding replies with a
|
|
723
|
+
* wire `null` in that case rather than omitting the field. */
|
|
724
|
+
requestSchema(): Promise<ModelSchema | undefined>;
|
|
725
|
+
/** The model's command schema (an OpenAPI document), cached from the
|
|
726
|
+
* `requestSchema()` call fired automatically on `"ready"`. `undefined`
|
|
727
|
+
* until that reply has landed. */
|
|
728
|
+
getSchema(): ModelSchema | undefined;
|
|
729
|
+
/** The runtime's declared capabilities (negotiated tracks, and the
|
|
730
|
+
* command set when the model exposes one) — pushed once available, no
|
|
731
|
+
* explicit request needed. `undefined` until `capabilitiesReceived`
|
|
732
|
+
* fires. */
|
|
733
|
+
getCapabilities(): Capabilities | undefined;
|
|
734
|
+
/** The session resource, as the coordinator reports it — id, state,
|
|
735
|
+
* model, cluster, server info, and (once negotiated) `capabilities`.
|
|
736
|
+
* A live read straight off the wasm client, not cached — reflects
|
|
737
|
+
* whatever's current. `undefined` before a client exists. */
|
|
738
|
+
getSessionInfo(): SessionResponse | undefined;
|
|
739
|
+
/**
|
|
740
|
+
* Publishes a local `MediaStreamTrack` under `name` — the counterpart to a
|
|
741
|
+
* `sendonly` track the model declares. Awaitable. Queued behind
|
|
742
|
+
* connect()/disconnect()/reconnect() (unlike `sendCommand()`): a track
|
|
743
|
+
* operation awaits its own control round-trip, and a concurrent
|
|
744
|
+
* disconnect() freeing the wasm client mid-await would otherwise resume
|
|
745
|
+
* into a freed client — the same class of use-after-free `queue` exists to
|
|
746
|
+
* prevent for connect/disconnect/reconnect themselves.
|
|
747
|
+
*/
|
|
748
|
+
publishTrack(name: string, track: MediaStreamTrack): Promise<void>;
|
|
749
|
+
/**
|
|
750
|
+
* Unlike every other track method, this doesn't reject — a failure is
|
|
751
|
+
* reported through the `error` event instead, since this is commonly the
|
|
752
|
+
* last call in a `finally` block, and raising there would replace
|
|
753
|
+
* whatever exception was already propagating.
|
|
754
|
+
*/
|
|
755
|
+
unpublishTrack(name: string): Promise<void>;
|
|
756
|
+
/**
|
|
757
|
+
* Stops a received track: the receiver goes inactive and the runtime stops
|
|
758
|
+
* producing it. Awaitable, and queued behind connect()/disconnect()/
|
|
759
|
+
* reconnect() for the same reason as `publishTrack()`.
|
|
760
|
+
*/
|
|
761
|
+
pauseTrack(name: string): Promise<void>;
|
|
762
|
+
/**
|
|
763
|
+
* Bounds what one sender may spend, in bits per second.
|
|
764
|
+
*
|
|
765
|
+
* This is the ceiling that actually caps a video encoder, and it is easy to
|
|
766
|
+
* hit without knowing it exists: with nothing set, a Chromium-based browser
|
|
767
|
+
* derives a sender's maximum from the frame size alone, and that maximum is
|
|
768
|
+
* 2500 kbps for anything above 960x540. A 720p or 1080p publish caps at
|
|
769
|
+
* 2.5 Mbps until this raises it, however good the connection is.
|
|
770
|
+
*
|
|
771
|
+
* ```ts
|
|
772
|
+
* await reactor.publishTrack('camera', cameraTrack);
|
|
773
|
+
* await reactor.setTrackBitrate('camera', { maxBps: 8_000_000 });
|
|
774
|
+
* ```
|
|
775
|
+
*
|
|
776
|
+
* A ceiling is permission, not a target: the encoder still spends only what
|
|
777
|
+
* the congestion controller allocated and what the picture needs. What
|
|
778
|
+
* raising it buys is headroom for the moments that would otherwise clip.
|
|
779
|
+
*
|
|
780
|
+
* Needs a connected client, and a published track — there is no sender to
|
|
781
|
+
* bound before `publishTrack()`.
|
|
782
|
+
*
|
|
783
|
+
* Omit a bound to leave it at the browser default. `minBps` is non-standard —
|
|
784
|
+
* Chromium honours it, other engines ignore it.
|
|
785
|
+
*
|
|
786
|
+
* There is no connection-wide counterpart: browsers expose no equivalent of
|
|
787
|
+
* the native SDKs' `setBitrate`, and a method that quietly did nothing would
|
|
788
|
+
* be worse than its absence.
|
|
789
|
+
*/
|
|
790
|
+
setTrackBitrate(name: string, bounds?: {
|
|
791
|
+
minBps?: number;
|
|
792
|
+
maxBps?: number;
|
|
793
|
+
}): Promise<void>;
|
|
794
|
+
/** Resumes a track previously stopped with `pauseTrack()`. */
|
|
795
|
+
resumeTrack(name: string): Promise<void>;
|
|
796
|
+
/**
|
|
797
|
+
* Requests a clip covering the last `durationSeconds` of the session.
|
|
798
|
+
* `reactor-core` correlates the reply itself (and enforces `"ready"`), so
|
|
799
|
+
* this is a thin delegation, same as `requestSchema()`. See
|
|
800
|
+
* `downloadClipAsFile()` to turn the result into a file.
|
|
801
|
+
*/
|
|
802
|
+
requestClip(durationSeconds: number): Promise<Clip>;
|
|
803
|
+
/** Requests a clip covering the entire session up to now. See `requestClip()`. */
|
|
804
|
+
requestRecording(): Promise<Clip>;
|
|
805
|
+
/** Thin delegation to the standalone `downloadClipAsFile()` — see its own doc comment. */
|
|
806
|
+
downloadClipAsFile(clip: Clip, filename?: string | null, options?: DownloadClipOptions): Promise<Blob>;
|
|
807
|
+
/**
|
|
808
|
+
* Uploads a file to the session's object store, resolving with a
|
|
809
|
+
* `FileRef` to pass as a top-level value in a `sendCommand()`'s `data`
|
|
810
|
+
* (see `extractFileRefs`). The binding itself takes `(file, name?)`
|
|
811
|
+
* positionally and already applies the right defaulting — a bare
|
|
812
|
+
* `Blob`'s name falls back to `"upload"`, and an empty/missing mime type
|
|
813
|
+
* to `"application/octet-stream"` — so there's nothing to wrap here.
|
|
814
|
+
*
|
|
815
|
+
* Queued behind connect()/disconnect()/reconnect(), same as the track
|
|
816
|
+
* ops: this awaits its own round-trip, and a concurrent disconnect()
|
|
817
|
+
* freeing the wasm client mid-upload would otherwise resume into a freed
|
|
818
|
+
* client — the same use-after-free class of race the queue exists to
|
|
819
|
+
* prevent.
|
|
820
|
+
*/
|
|
821
|
+
uploadFile(file: File | Blob, options?: {
|
|
822
|
+
name?: string;
|
|
823
|
+
}): Promise<FileRef>;
|
|
824
|
+
/** All tracks the model declared, whether or not media has arrived for —
|
|
825
|
+
* or been published to — them yet. Empty before a client exists. */
|
|
826
|
+
tracks(): TrackCapability[];
|
|
827
|
+
/** Same as `tracks()`, plus each entry's negotiated `mid` — the id
|
|
828
|
+
* `trackReceived`'s `mid` argument and the `getXByMid` escape hatches key
|
|
829
|
+
* on. Only populated once SDP negotiation has assigned mids. */
|
|
830
|
+
trackMapping(): TrackMappingEntry[];
|
|
831
|
+
pausedTracks(): string[];
|
|
832
|
+
/** Drops to the raw `RTCPeerConnection` for anything this class doesn't
|
|
833
|
+
* wrap directly. `undefined` before a client exists. */
|
|
834
|
+
getPeerConnection(): RTCPeerConnection | undefined;
|
|
835
|
+
getTrackByMid(mid: string): MediaStreamTrack | undefined;
|
|
836
|
+
getStreamByMid(mid: string): MediaStream | undefined;
|
|
837
|
+
getTrackByName(name: string): MediaStreamTrack | undefined;
|
|
838
|
+
getStreamByName(name: string): MediaStream | undefined;
|
|
839
|
+
/**
|
|
840
|
+
* Supports `using reactor = new Reactor(...)`: releases the wasm resource
|
|
841
|
+
* graph and drops every registered event handler for good. Unlike a plain
|
|
842
|
+
* `disconnect()`, this instance is unusable afterward — construct a new
|
|
843
|
+
* `Reactor` instead of trying to `connect()` again.
|
|
844
|
+
*/
|
|
845
|
+
[Symbol.dispose](): void;
|
|
846
|
+
/** The wasm binding's own terser `status()` name can be added alongside
|
|
847
|
+
* this later if it turns out to be worth it. */
|
|
848
|
+
getStatus(): ReactorStatus;
|
|
849
|
+
/** See `getStatus()`. */
|
|
850
|
+
getSessionId(): string | undefined;
|
|
851
|
+
/** The `jwt` this instance was constructed (or last `connect()`ed) with —
|
|
852
|
+
* lets a component composed inside a `ReactorProvider` (e.g. `ClipPlayer`)
|
|
853
|
+
* authenticate its own requests without the caller repeating the resolver. */
|
|
854
|
+
getJwtResolver(): JwtSource | undefined;
|
|
855
|
+
/** The most recent `ReactorError`, from either an `error` event or a
|
|
856
|
+
* rejected call — whichever landed last. `undefined` until the first
|
|
857
|
+
* failure. */
|
|
858
|
+
getLastError(): ReactorError | undefined;
|
|
859
|
+
/** The most recent WebRTC connection stats, polled every `STATS_INTERVAL_MS`
|
|
860
|
+
* while "ready" — see `statsUpdate`. `undefined` before the first sample. */
|
|
861
|
+
getStats(): ConnectionStats | undefined;
|
|
862
|
+
/** Timing breakdown from the most recent `connect()`/`reconnect()`
|
|
863
|
+
* handshake — see `ConnectionTimings`. */
|
|
864
|
+
getConnectionTimings(): ConnectionTimings | undefined;
|
|
865
|
+
on<Name extends keyof ReactorEventMap>(event: Name, handler: ReactorEventMap[Name]): void;
|
|
866
|
+
off<Name extends keyof ReactorEventMap>(event: Name, handler: ReactorEventMap[Name]): void;
|
|
867
|
+
once<Name extends keyof ReactorEventMap>(event: Name, handler: ReactorEventMap[Name]): void;
|
|
868
|
+
private getOrCreateClient;
|
|
869
|
+
private createClient;
|
|
870
|
+
/** Fired once per `"ready"` transition — see `getSchema()`. `getSchema()`
|
|
871
|
+
* isn't guaranteed populated by the time a `statusChanged` "ready" handler
|
|
872
|
+
* runs (this fetch is async and dispatched separately), so callers that
|
|
873
|
+
* need the schema as soon as it lands should listen for `schemaReceived`
|
|
874
|
+
* instead of reading `getSchema()` synchronously off `statusChanged`.
|
|
875
|
+
*
|
|
876
|
+
* Guards against a stale reply: if `disconnect()`/a later `connect()`
|
|
877
|
+
* replaces `client` before this resolves, or a newer `refreshSchema()`
|
|
878
|
+
* call for the same client wins the race, the result is discarded rather
|
|
879
|
+
* than clobbering `this.schema` (or emitting `schema`) with old data.
|
|
880
|
+
*
|
|
881
|
+
* A rejection here (e.g. the session drops mid-request) surfaces like any
|
|
882
|
+
* other binding failure, through the same `error` event as `onError`. */
|
|
883
|
+
private refreshSchema;
|
|
884
|
+
/** The binding replies with a wire `null` (not an omitted field) when the
|
|
885
|
+
* model doesn't expose a schema — normalized to `undefined` so callers
|
|
886
|
+
* get the same "no schema" sentinel `getSchema()` already uses instead
|
|
887
|
+
* of a document they could otherwise dereference. */
|
|
888
|
+
private normalizeSchema;
|
|
889
|
+
/** Frees the wasm resource graph, if one exists, and clears the cached
|
|
890
|
+
* schema. Reusable — unlike `[Symbol.dispose]`, this doesn't set the
|
|
891
|
+
* permanent `disposed` flag, so a later `connect()`/`reconnect()` lazily
|
|
892
|
+
* builds a fresh client.
|
|
893
|
+
*
|
|
894
|
+
* Only called from within `disconnect()`'s queued task, so `client.free()`
|
|
895
|
+
* is safe to call directly here — the queue already guarantees no other
|
|
896
|
+
* operation is running concurrently against it. */
|
|
897
|
+
private freeClient;
|
|
898
|
+
/** Tracks `connectionTimings` off the binding's own "connecting" → "waiting"
|
|
899
|
+
* → "ready" status sequence (see `ReactorStatus`), and starts/stops stats
|
|
900
|
+
* polling around the "ready" window. */
|
|
901
|
+
private handleStatusChanged;
|
|
902
|
+
private startStatsPolling;
|
|
903
|
+
private stopStatsPolling;
|
|
904
|
+
/** Called on every `disconnect()` and on `[Symbol.dispose]`. Leaves
|
|
905
|
+
* `client`/`schema` alone — that's `freeClient()`'s job, run separately
|
|
906
|
+
* when `disconnect()` isn't recoverable. `capabilities` is cleared here
|
|
907
|
+
* regardless, though: unlike the schema, it isn't re-fetched on demand,
|
|
908
|
+
* so a recoverable disconnect that skips `freeClient()` would otherwise
|
|
909
|
+
* leave `getCapabilities()` returning the previous session's stale
|
|
910
|
+
* tracks/commands until a new `capabilitiesReceived` lands. */
|
|
911
|
+
private resetConnectionState;
|
|
912
|
+
/** Wraps `cause` and records it as the most recent failure, for a call
|
|
913
|
+
* that's about to throw rather than emit — see `getLastError()`'s doc
|
|
914
|
+
* comment. */
|
|
915
|
+
private captureError;
|
|
916
|
+
/** Wraps `cause`, records it as the most recent failure, and fires the
|
|
917
|
+
* `error` event — the one place recording and emitting happen together,
|
|
918
|
+
* so `getLastError()` never drifts from what listeners were told. */
|
|
919
|
+
private emitError;
|
|
920
|
+
private assertNotDisposed;
|
|
921
|
+
}
|
|
922
|
+
|
|
923
|
+
/** Lazy resolver for a Coordinator/runtime bearer token, called immediately
|
|
924
|
+
* before each authenticated request — see `JwtSource`. */
|
|
925
|
+
type JwtResolver = () => string | Promise<string>;
|
|
926
|
+
/**
|
|
927
|
+
* Wraps a `JwtSource` into a `JwtResolver`: a static string becomes a
|
|
928
|
+
* resolver that always returns it, a resolver passes through unchanged.
|
|
929
|
+
* Useful for feeding a source that may be either form (e.g. a
|
|
930
|
+
* `ReactorProvider`'s `jwtToken`) into a `getJwt` prop that expects a
|
|
931
|
+
* resolver.
|
|
932
|
+
*/
|
|
933
|
+
declare function normalizeJwtSource(source: JwtSource): JwtResolver;
|
|
934
|
+
|
|
935
|
+
/** State kept reactive for `useReactor` selectors. Stats/schema/capabilities
|
|
936
|
+
* aren't mirrored here — reach them through the `internal.reactor` escape
|
|
937
|
+
* hatch. */
|
|
938
|
+
interface ReactorState {
|
|
939
|
+
status: ReactorStatus;
|
|
940
|
+
sessionId: string | undefined;
|
|
941
|
+
lastError: ReactorError | undefined;
|
|
942
|
+
/** Most recent app-scope `message` payload; `runtimeMessage` isn't mirrored
|
|
943
|
+
* here — subscribe on `internal.reactor` for that. */
|
|
944
|
+
lastMessage: ReactorMessage | undefined;
|
|
945
|
+
/** Media tracks received from the model, keyed by track name. Reset to
|
|
946
|
+
* `{}` on every "disconnected" status transition — a fresh connection
|
|
947
|
+
* invalidates whatever arrived under the previous one. Append-only within
|
|
948
|
+
* a session: a track pausing/unpublishing mid-session doesn't remove its
|
|
949
|
+
* entry, so a stale `MediaStreamTrack` can linger until the next
|
|
950
|
+
* disconnect. Matches v2's identical behavior (`core/store.ts`). */
|
|
951
|
+
tracks: Record<string, MediaStreamTrack>;
|
|
952
|
+
/** The `jwt` the store was created with — see `createReactorStore`'s
|
|
953
|
+
* `options.jwt`. Set once at creation, not resynced afterward. */
|
|
954
|
+
jwtToken: JwtSource | undefined;
|
|
955
|
+
/** The `defaultConnectOptions` the store was created with — set once at
|
|
956
|
+
* creation, not resynced afterward. Lets a component read the
|
|
957
|
+
* provider-level defaults (e.g. `autoResumeTracks`) without threading
|
|
958
|
+
* them through props of its own. */
|
|
959
|
+
connectOptions: ConnectOptions | undefined;
|
|
960
|
+
}
|
|
961
|
+
interface ReactorActions {
|
|
962
|
+
connect: (jwt?: JwtSource, options?: ConnectOptions) => Promise<void>;
|
|
963
|
+
disconnect: (recoverable?: boolean) => Promise<void>;
|
|
964
|
+
reconnect: (options?: ConnectOptions) => Promise<void>;
|
|
965
|
+
sendCommand: <T extends object = Record<string, unknown>>(command: string, data?: NotFunction<T>, scope?: MessageScope) => Promise<ReactorMessage | undefined>;
|
|
966
|
+
publish: (name: string, track: MediaStreamTrack) => Promise<void>;
|
|
967
|
+
unpublish: (name: string) => Promise<void>;
|
|
968
|
+
pauseTrack: (name: string) => Promise<void>;
|
|
969
|
+
resumeTrack: (name: string) => Promise<void>;
|
|
970
|
+
uploadFile: (file: File | Blob, options?: {
|
|
971
|
+
name?: string;
|
|
972
|
+
}) => Promise<FileRef>;
|
|
973
|
+
requestClip: (durationSeconds: number) => Promise<Clip>;
|
|
974
|
+
requestRecording: () => Promise<Clip>;
|
|
975
|
+
downloadClipAsFile: (clip: Clip, filename?: string | null, options?: DownloadClipOptions) => Promise<Blob>;
|
|
976
|
+
}
|
|
977
|
+
interface ReactorInternal {
|
|
978
|
+
/** Escape hatch: the underlying `Reactor` instance, for anything the
|
|
979
|
+
* selector state / action bindings above don't cover. */
|
|
980
|
+
reactor: Reactor;
|
|
981
|
+
}
|
|
982
|
+
type ReactorStore = ReactorState & ReactorActions & {
|
|
983
|
+
internal: ReactorInternal;
|
|
984
|
+
};
|
|
985
|
+
|
|
986
|
+
/** `connectOptions` for the provider — adds `autoConnect` to the core
|
|
987
|
+
* `ConnectOptions`. Live, same as every other `ReactorProviderProps` field —
|
|
988
|
+
* see `ReactorProvider`'s doc comment. */
|
|
989
|
+
interface ReactorConnectOptions extends ConnectOptions {
|
|
990
|
+
/** Connect automatically once a Reactor is built — initial mount, or any
|
|
991
|
+
* later rebuild. Default `false`. */
|
|
992
|
+
autoConnect?: boolean;
|
|
993
|
+
}
|
|
994
|
+
interface ReactorProviderProps {
|
|
995
|
+
apiUrl?: string | undefined;
|
|
996
|
+
modelName: string;
|
|
997
|
+
local?: boolean | undefined;
|
|
998
|
+
/** Media tracks to declare up front, so the transport can prepare the SDP
|
|
999
|
+
* offer in parallel with session polling instead of waiting to discover
|
|
1000
|
+
* them from the model's schema. */
|
|
1001
|
+
modelTracks?: TrackCapability[] | undefined;
|
|
1002
|
+
/** Static token, or a resolver called before every authenticated request
|
|
1003
|
+
* — see `JwtSource`. Required for `autoConnect` against a non-local
|
|
1004
|
+
* runtime; can also be supplied later via an explicit `connect()` call
|
|
1005
|
+
* instead. */
|
|
1006
|
+
jwtToken?: JwtSource | undefined;
|
|
1007
|
+
connectOptions?: ReactorConnectOptions | undefined;
|
|
1008
|
+
children?: ReactNode;
|
|
1009
|
+
}
|
|
1010
|
+
/**
|
|
1011
|
+
* Owns a `Reactor` instance and exposes it to `useReactor` below.
|
|
1012
|
+
*
|
|
1013
|
+
* `apiUrl`/`modelName`/`local`/`modelTracks`/`jwtToken`/`connectOptions`
|
|
1014
|
+
* (including `autoConnect`) are live: changing any of them tears down the
|
|
1015
|
+
* current `Reactor` (`disconnect()` then `[Symbol.dispose]()`) and builds a
|
|
1016
|
+
* fresh one — the same way `useLiveKitRoom` rebuilds its `Room` when its
|
|
1017
|
+
* construction `options` change. `Reactor` has no equivalent of LiveKit's
|
|
1018
|
+
* `token`/`serverUrl` split (reconnecting the *same* instance with new
|
|
1019
|
+
* credentials) or its live `connect` boolean (toggling the same `Room`'s
|
|
1020
|
+
* connection without rebuilding it) — its constructor bundles everything, so
|
|
1021
|
+
* any change, `autoConnect` included, means a fresh instance rather than
|
|
1022
|
+
* reconnecting/disconnecting the existing one. Pass a stable `jwtToken`
|
|
1023
|
+
* (e.g. via `useCallback` for a resolver) and stable `modelTracks`/
|
|
1024
|
+
* `connectOptions` references if you don't want an unrelated parent render to
|
|
1025
|
+
* rebuild the connection — object/array props are compared by reference
|
|
1026
|
+
* (`modelTracks`/`connectOptions` via a `JSON.stringify` snapshot, same as
|
|
1027
|
+
* `useLiveKitRoom` does for its own `options`).
|
|
1028
|
+
*
|
|
1029
|
+
* Unmounting tears down the same way — see `Reactor.disconnect()`/
|
|
1030
|
+
* `[Symbol.dispose]()` for what that frees.
|
|
1031
|
+
*/
|
|
1032
|
+
declare function ReactorProvider({ apiUrl, modelName, local, modelTracks, jwtToken, connectOptions, children, }: ReactorProviderProps): react.JSX.Element;
|
|
1033
|
+
|
|
1034
|
+
/** Reads from the nearest `ReactorProvider`'s store, with a shallow-equality
|
|
1035
|
+
* check on the selector's result — so a selector returning a fresh object
|
|
1036
|
+
* each call doesn't cause a re-render on every unrelated store update. */
|
|
1037
|
+
declare function useReactor<T>(selector: (state: ReactorStore) => T): T;
|
|
1038
|
+
/** Subscribes to app-scope `message` payloads sent by the model via
|
|
1039
|
+
* `get_ctx().send()`. `handler` is kept in a ref so identity churn on
|
|
1040
|
+
* every render doesn't retrigger the subscription effect. */
|
|
1041
|
+
declare function useReactorMessage(handler: (message: ReactorMessage) => void): void;
|
|
1042
|
+
/** Subscribes to platform-scope `runtimeMessage` payloads (moderation,
|
|
1043
|
+
* clip/recording lifecycle, ...) — see `useReactorMessage` for app-scope
|
|
1044
|
+
* payloads instead. */
|
|
1045
|
+
declare function useReactorInternalMessage(handler: (message: ReactorMessage) => void): void;
|
|
1046
|
+
/** The most recent `statsUpdate` sample; `undefined` until the first one
|
|
1047
|
+
* arrives, and reset back to `undefined` on unmount or reactor change. */
|
|
1048
|
+
declare function useStats(): ConnectionStats | undefined;
|
|
1049
|
+
|
|
1050
|
+
interface ReactorViewProps {
|
|
1051
|
+
/** Name of the recvonly video track to render. Must match a track name
|
|
1052
|
+
* declared in the model's capabilities. Defaults to `"main_video"`. */
|
|
1053
|
+
track?: string;
|
|
1054
|
+
/** Name of a recvonly audio track to mix into the same `<video>` element
|
|
1055
|
+
* alongside `track`. */
|
|
1056
|
+
audioTrack?: string;
|
|
1057
|
+
width?: number;
|
|
1058
|
+
height?: number;
|
|
1059
|
+
className?: string;
|
|
1060
|
+
style?: CSSProperties;
|
|
1061
|
+
videoObjectFit?: NonNullable<VideoHTMLAttributes<HTMLVideoElement>['style']>['objectFit'];
|
|
1062
|
+
/** Defaults to `true` when no `audioTrack` is set (keeps the element within
|
|
1063
|
+
* browser autoplay policies), `false` otherwise. Pass an explicit value to
|
|
1064
|
+
* override either default. */
|
|
1065
|
+
muted?: boolean;
|
|
1066
|
+
}
|
|
1067
|
+
declare function ReactorView({ track, audioTrack, width, height, className, style, videoObjectFit, muted, }: ReactorViewProps): react.JSX.Element;
|
|
1068
|
+
|
|
1069
|
+
interface WebcamStreamProps {
|
|
1070
|
+
/** Name of the sendonly video track to publish the webcam to. Must match a
|
|
1071
|
+
* track name declared in the model's capabilities. */
|
|
1072
|
+
track: string;
|
|
1073
|
+
/** Capture and publish the microphone alongside the webcam. `true` for
|
|
1074
|
+
* default constraints, or explicit `MediaTrackConstraints`. Requires
|
|
1075
|
+
* `audioTrack`. Defaults to `false`. */
|
|
1076
|
+
audio?: boolean | MediaTrackConstraints;
|
|
1077
|
+
/** Name of the sendonly audio track to publish the mic to. Ignored unless
|
|
1078
|
+
* `audio` is set. */
|
|
1079
|
+
audioTrack?: string;
|
|
1080
|
+
className?: string;
|
|
1081
|
+
style?: CSSProperties;
|
|
1082
|
+
/** Read once, at mount — changing this after mount doesn't re-request
|
|
1083
|
+
* `getUserMedia`. Matches v2. */
|
|
1084
|
+
videoConstraints?: MediaTrackConstraints;
|
|
1085
|
+
showWebcam?: boolean;
|
|
1086
|
+
videoObjectFit?: NonNullable<VideoHTMLAttributes<HTMLVideoElement>['style']>['objectFit'];
|
|
1087
|
+
/** Fires once `getUserMedia` is rejected with `NotAllowedError` or
|
|
1088
|
+
* `PermissionDeniedError`. */
|
|
1089
|
+
onPermissionDenied?: () => void;
|
|
1090
|
+
/** Fires after the local media has been published (video, and audio when
|
|
1091
|
+
* `audio` is enabled). Re-fires after a reconnect. */
|
|
1092
|
+
onPublished?: () => void;
|
|
1093
|
+
/** Fires on non-permission `getUserMedia` failures and on publish/unpublish
|
|
1094
|
+
* rejections. Permission denials route to `onPermissionDenied` instead. */
|
|
1095
|
+
onError?: (error: Error) => void;
|
|
1096
|
+
}
|
|
1097
|
+
declare function WebcamStream({ track, audio, audioTrack, className, style, videoConstraints, showWebcam, videoObjectFit, onPermissionDenied, onPublished, onError, }: WebcamStreamProps): react.JSX.Element;
|
|
1098
|
+
|
|
1099
|
+
/**
|
|
1100
|
+
* Video preview for a captured {@link Clip}. Streams the clip with `hls.js`
|
|
1101
|
+
* wherever Media Source Extensions exist — every current browser, iOS
|
|
1102
|
+
* Safari 17.1 and later included. `hls.js` is dynamically imported, so
|
|
1103
|
+
* bundlers give it a chunk of its own that an app importing this component
|
|
1104
|
+
* fetches on first play, and one that never renders a player drops
|
|
1105
|
+
* entirely. Where Media Source Extensions don't exist — iOS before 17.1 —
|
|
1106
|
+
* the clip is assembled into a single MP4 and played from memory instead.
|
|
1107
|
+
* Failures surface in an inline error overlay; the chunks remain
|
|
1108
|
+
* downloadable via {@link useClipDownload}/`ClipDownloadButton` either way.
|
|
1109
|
+
*
|
|
1110
|
+
* Preview only — this component doesn't render a download UI. Compose it
|
|
1111
|
+
* with `ClipDownloadButton`, or build a custom download surface around
|
|
1112
|
+
* `useClipDownload`.
|
|
1113
|
+
*
|
|
1114
|
+
* Unlike `ReactorView`/`WebcamStream`, this doesn't require a
|
|
1115
|
+
* `ReactorProvider` in the tree — it operates on the `Clip` value alone, so
|
|
1116
|
+
* it stays usable after `reactor.disconnect()` and works with clips loaded
|
|
1117
|
+
* from fixtures or any other source. When a `ReactorProvider` is mounted
|
|
1118
|
+
* above, an omitted `getJwt` inherits the provider's resolver.
|
|
1119
|
+
*/
|
|
1120
|
+
interface ClipPlayerProps {
|
|
1121
|
+
/** The captured clip to play. Re-fetches the manifest and re-attaches the
|
|
1122
|
+
* player when this changes by reference. */
|
|
1123
|
+
clip: Clip;
|
|
1124
|
+
/**
|
|
1125
|
+
* Lazy resolver for the Coordinator JWT used on the manifest GET, called
|
|
1126
|
+
* at request time so token refreshes are picked up automatically.
|
|
1127
|
+
*
|
|
1128
|
+
* Required outside a `ReactorProvider` in production; optional inside one
|
|
1129
|
+
* (inherits the provider's resolver). Omit in local-dev mode (HttpRuntime)
|
|
1130
|
+
* — the manifest endpoint there is auth-free.
|
|
1131
|
+
*/
|
|
1132
|
+
getJwt?: () => string | Promise<string>;
|
|
1133
|
+
/**
|
|
1134
|
+
* Opt into a bounded wait: give up polling the manifest with
|
|
1135
|
+
* `CLIP_NOT_READY` once `max(clip.predictedReadyAtMs, pollStart) + slackMs`
|
|
1136
|
+
* passes. Unset by default — the player polls indefinitely until the clip
|
|
1137
|
+
* is ready, stopping only when it unmounts or `clip` changes. Forwarded
|
|
1138
|
+
* directly to `fetchPlaylist()`'s `slackMs` option.
|
|
1139
|
+
*/
|
|
1140
|
+
slackMs?: number;
|
|
1141
|
+
/** Play automatically once the manifest is attached. Default `true`. */
|
|
1142
|
+
autoPlay?: boolean;
|
|
1143
|
+
/** Start muted. Default `true` — browser autoplay policies block
|
|
1144
|
+
* audio-bearing video from playing without a user gesture; the user can
|
|
1145
|
+
* unmute via the native controls. */
|
|
1146
|
+
muted?: boolean;
|
|
1147
|
+
className?: string;
|
|
1148
|
+
style?: CSSProperties;
|
|
1149
|
+
/** Fires when the player enters its inline error state. A `RecordingError`
|
|
1150
|
+
* for manifest-fetch failures, a plain `Error` for hls.js/element playback
|
|
1151
|
+
* failures. */
|
|
1152
|
+
onError?: (error: Error) => void;
|
|
1153
|
+
}
|
|
1154
|
+
declare function ClipPlayer({ clip, getJwt, slackMs, autoPlay, muted, className, style, onError, }: ClipPlayerProps): react.JSX.Element;
|
|
1155
|
+
|
|
1156
|
+
/**
|
|
1157
|
+
* State machine for an in-progress clip download.
|
|
1158
|
+
*
|
|
1159
|
+
* - `idle`: no download in flight (initial state, and what the hook returns
|
|
1160
|
+
* to after a successful save).
|
|
1161
|
+
* - `downloading`: chunks are being fetched. `fetched`/`total` count the
|
|
1162
|
+
* chunks (init segment + media segments) — useful for a progress bar.
|
|
1163
|
+
* `total` is 0 until the manifest is parsed and the chunk count is known.
|
|
1164
|
+
* - `error`: most recent attempt failed; `message` is suitable for
|
|
1165
|
+
* surfacing inline. `RecordingError`s are formatted as `"<CODE>: <reason>"`.
|
|
1166
|
+
*/
|
|
1167
|
+
type ClipDownloadState = {
|
|
1168
|
+
kind: 'idle';
|
|
1169
|
+
} | {
|
|
1170
|
+
kind: 'downloading';
|
|
1171
|
+
fetched: number;
|
|
1172
|
+
total: number;
|
|
1173
|
+
} | {
|
|
1174
|
+
kind: 'error';
|
|
1175
|
+
message: string;
|
|
1176
|
+
};
|
|
1177
|
+
interface UseClipDownloadOptions {
|
|
1178
|
+
/** Filename used when the browser save dialog opens. Pass `null` to skip
|
|
1179
|
+
* the `<a download>` trigger entirely — the returned Blob is still
|
|
1180
|
+
* resolved so the caller can `URL.createObjectURL` it or re-upload it.
|
|
1181
|
+
* Default `"reactor-clip.mp4"`. */
|
|
1182
|
+
filename?: string | null;
|
|
1183
|
+
/**
|
|
1184
|
+
* Lazy resolver for the Coordinator JWT used on the manifest GET. Called
|
|
1185
|
+
* on every {@link UseClipDownloadResult.download} invocation, so token
|
|
1186
|
+
* refreshes are picked up automatically.
|
|
1187
|
+
*
|
|
1188
|
+
* Optional inside a `ReactorProvider` (inherits the provider's resolver)
|
|
1189
|
+
* and in local-dev mode.
|
|
1190
|
+
*/
|
|
1191
|
+
getJwt?: () => string | Promise<string>;
|
|
1192
|
+
}
|
|
1193
|
+
interface UseClipDownloadResult {
|
|
1194
|
+
/** Current state of the most recent download attempt. */
|
|
1195
|
+
state: ClipDownloadState;
|
|
1196
|
+
/**
|
|
1197
|
+
* Trigger a download. Resolves with the assembled fragmented-MP4 Blob, or
|
|
1198
|
+
* `undefined` if a download was already in flight (a no-op in that case)
|
|
1199
|
+
* or the attempt failed. Errors are surfaced via {@link state} rather than
|
|
1200
|
+
* a rejection — check `state.kind === "error"` to drive failure UI.
|
|
1201
|
+
*/
|
|
1202
|
+
download: () => Promise<Blob | undefined>;
|
|
1203
|
+
/** Reset to `idle`. Does *not* cancel an in-flight download. */
|
|
1204
|
+
reset: () => void;
|
|
1205
|
+
}
|
|
1206
|
+
/**
|
|
1207
|
+
* Headless download primitive for a {@link Clip}. Wraps `downloadClipAsFile`
|
|
1208
|
+
* in a React state machine so the consumer can render any button they want,
|
|
1209
|
+
* anywhere they want, and still get progress + error feedback. Used
|
|
1210
|
+
* internally by `ClipDownloadButton` — reach for this hook directly when you
|
|
1211
|
+
* need custom placement or styling.
|
|
1212
|
+
*
|
|
1213
|
+
* `download`/`reset` are stable callback identities across renders, so
|
|
1214
|
+
* they're safe to pass through memoized children without forcing re-renders.
|
|
1215
|
+
*/
|
|
1216
|
+
declare function useClipDownload(clip: Clip, options?: UseClipDownloadOptions): UseClipDownloadResult;
|
|
1217
|
+
|
|
1218
|
+
/**
|
|
1219
|
+
* Standalone download button for a captured {@link Clip}. Drops anywhere in
|
|
1220
|
+
* your UI — modal headers, list rows, hover menus, floating action buttons
|
|
1221
|
+
* — and is responsible for nothing more than triggering a download and
|
|
1222
|
+
* reflecting its state. Wraps `useClipDownload` internally; for completely
|
|
1223
|
+
* custom UIs (progress bars, menu items, post-download blob handling) call
|
|
1224
|
+
* that hook directly.
|
|
1225
|
+
*
|
|
1226
|
+
* Styling is intentionally minimal — override via `className`/`style`, or
|
|
1227
|
+
* replace the inner content with the `children` render-prop. No CSS file is
|
|
1228
|
+
* shipped; every default style is inline so it loses to anything the
|
|
1229
|
+
* consumer provides.
|
|
1230
|
+
*/
|
|
1231
|
+
interface ClipDownloadButtonProps {
|
|
1232
|
+
/** The clip to download. */
|
|
1233
|
+
clip: Clip;
|
|
1234
|
+
/** Lazy JWT resolver. Optional inside a `ReactorProvider` (inherits the
|
|
1235
|
+
* provider's resolver) and in local-dev mode. See `ClipPlayerProps.getJwt`. */
|
|
1236
|
+
getJwt?: () => string | Promise<string>;
|
|
1237
|
+
/** Filename for the saved MP4. Default `"reactor-clip.mp4"`. */
|
|
1238
|
+
filename?: string;
|
|
1239
|
+
/**
|
|
1240
|
+
* Inner content of the button. Three forms:
|
|
1241
|
+
*
|
|
1242
|
+
* - Omitted — renders a default label that follows the state
|
|
1243
|
+
* (`"Download"` / `"Downloading 3/8…"` / etc.).
|
|
1244
|
+
* - `ReactNode` — static label, no state-driven text.
|
|
1245
|
+
* - `(state) => ReactNode` — state-aware render function, for custom
|
|
1246
|
+
* progress strings, spinners, etc.
|
|
1247
|
+
*/
|
|
1248
|
+
children?: ReactNode | ((state: ClipDownloadState) => ReactNode);
|
|
1249
|
+
/** Forwarded to the underlying `<button>`. */
|
|
1250
|
+
className?: string;
|
|
1251
|
+
/** Forwarded to the underlying `<button>` — merges after the defaults so
|
|
1252
|
+
* each property overrides. */
|
|
1253
|
+
style?: CSSProperties;
|
|
1254
|
+
/** Forwarded to the underlying `<button>`. ORed with the internal
|
|
1255
|
+
* "downloading" state. */
|
|
1256
|
+
disabled?: boolean;
|
|
1257
|
+
/** Fires when the download completes with the assembled MP4 Blob. */
|
|
1258
|
+
onSuccess?: (blob: Blob) => void;
|
|
1259
|
+
/** Fires when the download fails. Message mirrors the in-button state —
|
|
1260
|
+
* `"<CODE>: <reason>"` for `RecordingError`s, the plain error message
|
|
1261
|
+
* otherwise. */
|
|
1262
|
+
onError?: (error: Error) => void;
|
|
1263
|
+
}
|
|
1264
|
+
declare function ClipDownloadButton({ clip, getJwt, filename, children, className, style, disabled, onSuccess, onError, }: ClipDownloadButtonProps): react.JSX.Element;
|
|
1265
|
+
|
|
1266
|
+
export { AbortedError, BadRequestError, type Capabilities, type Clip, ClipDownloadButton, type ClipDownloadButtonProps, type ClipDownloadState, type ClipKind, ClipPlayer, type ClipPlayerProps, type CommandCapability, ConflictError, type ConnectOptions, type ConnectionStats, type ConnectionTimings, DEFAULT_PLAYLIST_POLL_SLACK_MS, DecodeError, DisconnectedError, type DownloadClipOptions, type FetchPlaylistOptions, FileRef, InvalidStateError, type JwtResolver, type JwtSource, type MessageScope, MessageTooLargeError, type ModelSchema, type ModelSchemaOperation, type ModelSchemaPathItem, type ModerationAction, type ModerationEvent, NetworkError, NotFoundError, RateLimitedError, Reactor, type ReactorActions, type ReactorConnectOptions, ReactorError, type ReactorEventMap, type ReactorEventName, type ReactorMessage, type ReactorOptions, ReactorProvider, type ReactorProviderProps, type ReactorState, type ReactorStatus, type ReactorStore, ReactorView, type ReactorViewProps, RecorderDisabledError, RecordingError, RequestTimeoutError, ServerError, type SessionResponse, SessionTerminalError, type TrackCapability, type TrackDirection, type TrackKind, type TrackMappingEntry, TransportError, UnauthorizedError, type UseClipDownloadOptions, type UseClipDownloadResult, VersionMismatchError, WebcamStream, type WebcamStreamProps, createPlayableManifestUrl, downloadClipAsFile, fetchPlaylist, isFileRef, normalizeJwtSource, parsePlaylist, useClipDownload, useReactor, useReactorInternalMessage, useReactorMessage, useStats };
|