@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.ts
CHANGED
|
@@ -1,90 +1,307 @@
|
|
|
1
|
-
import
|
|
2
|
-
import
|
|
3
|
-
import React, { ReactNode } from 'react';
|
|
1
|
+
import * as react from 'react';
|
|
2
|
+
import { ReactNode, CSSProperties, VideoHTMLAttributes } from 'react';
|
|
4
3
|
|
|
5
4
|
/**
|
|
6
|
-
*
|
|
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.
|
|
7
11
|
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
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.
|
|
10
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
|
+
}
|
|
11
156
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
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
|
+
}
|
|
88
305
|
/** One OpenAPI operation (the `post` of an event/webhook path item). */
|
|
89
306
|
interface ModelSchemaOperation {
|
|
90
307
|
operationId?: string;
|
|
@@ -105,12 +322,12 @@ interface ModelSchemaPathItem {
|
|
|
105
322
|
[key: string]: unknown;
|
|
106
323
|
}
|
|
107
324
|
/**
|
|
108
|
-
* The model's OpenAPI 3.1 schema, returned by
|
|
109
|
-
* `
|
|
110
|
-
*
|
|
111
|
-
*
|
|
112
|
-
*
|
|
113
|
-
*
|
|
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.
|
|
114
331
|
*/
|
|
115
332
|
interface ModelSchema {
|
|
116
333
|
openapi: string;
|
|
@@ -121,7 +338,7 @@ interface ModelSchema {
|
|
|
121
338
|
};
|
|
122
339
|
paths?: Record<string, ModelSchemaPathItem>;
|
|
123
340
|
webhooks?: Record<string, ModelSchemaPathItem>;
|
|
124
|
-
|
|
341
|
+
'x-reactor'?: {
|
|
125
342
|
tracks?: Array<{
|
|
126
343
|
name: string;
|
|
127
344
|
kind: string;
|
|
@@ -131,441 +348,245 @@ interface ModelSchema {
|
|
|
131
348
|
components?: Record<string, unknown>;
|
|
132
349
|
[key: string]: unknown;
|
|
133
350
|
}
|
|
134
|
-
|
|
135
351
|
/**
|
|
136
|
-
*
|
|
137
|
-
*
|
|
138
|
-
*
|
|
139
|
-
*
|
|
140
|
-
* from scalar arguments. The runtime resolves each reference to bytes
|
|
141
|
-
* before dispatching the event to the model handler.
|
|
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.
|
|
142
356
|
*/
|
|
143
|
-
|
|
144
|
-
readonly uploadId: string;
|
|
145
|
-
readonly name: string;
|
|
146
|
-
readonly mimeType: string;
|
|
147
|
-
readonly size: number;
|
|
148
|
-
constructor(uploadId: string, name: string, mimeType: string, size: number);
|
|
149
|
-
}
|
|
150
|
-
|
|
151
|
-
type ReactorStatus = "disconnected" | "connecting" | "waiting" | "ready";
|
|
357
|
+
type ModerationAction = 'warn' | 'terminate';
|
|
152
358
|
/**
|
|
153
|
-
*
|
|
154
|
-
* -
|
|
155
|
-
* -
|
|
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`.
|
|
156
363
|
*/
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
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. */
|
|
161
374
|
message: string;
|
|
162
|
-
timestamp: number;
|
|
163
|
-
recoverable: boolean;
|
|
164
|
-
component: "api" | "gpu";
|
|
165
|
-
retryAfter?: number;
|
|
166
|
-
}
|
|
167
|
-
declare class ConflictError extends Error {
|
|
168
|
-
constructor(message: string);
|
|
169
|
-
}
|
|
170
|
-
declare class AbortError extends Error {
|
|
171
|
-
constructor(message: string);
|
|
172
|
-
}
|
|
173
|
-
/** Matches both our custom AbortError and the native DOMException thrown by fetch(). */
|
|
174
|
-
declare function isAbortError(error: unknown): boolean;
|
|
175
|
-
declare class SessionLostError extends Error {
|
|
176
|
-
constructor(message: string);
|
|
177
|
-
}
|
|
178
|
-
declare function isSessionLostError(error: unknown): boolean;
|
|
179
|
-
interface ReactorState$1 {
|
|
180
|
-
status: ReactorStatus;
|
|
181
|
-
lastError?: ReactorError;
|
|
182
375
|
}
|
|
183
376
|
/**
|
|
184
|
-
*
|
|
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.
|
|
185
384
|
*/
|
|
186
|
-
interface
|
|
187
|
-
/**
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
* immediately after the connection is established, causing the backend to
|
|
192
|
-
* begin streaming those tracks — this preserves the pre-multi-connection
|
|
193
|
-
* behaviour where output tracks flow automatically on connect. Set to false
|
|
194
|
-
* to keep recvonly tracks paused on connect and resume them individually via
|
|
195
|
-
* `resumeTrack()` (e.g. multi-connection apps that only subscribe to a
|
|
196
|
-
* subset of peers).
|
|
197
|
-
*
|
|
198
|
-
* A track that arrives after that is resumed on its own, so one track
|
|
199
|
-
* appearing never disturbs another the caller has paused.
|
|
200
|
-
*/
|
|
201
|
-
autoResumeTracks?: boolean;
|
|
202
|
-
/**
|
|
203
|
-
* Attach to a session that already exists (e.g. one created by a backend)
|
|
204
|
-
* instead of creating a new one. When set, `connect()` skips `POST /sessions`
|
|
205
|
-
* and brings up the transport directly against this id. The JWT passed to
|
|
206
|
-
* `connect()` must be valid for the account that owns the session.
|
|
207
|
-
*/
|
|
208
|
-
sessionId?: string;
|
|
209
|
-
/**
|
|
210
|
-
* Use a specific WebRTC connection id instead of minting one. When omitted
|
|
211
|
-
* (default), the transport registers a fresh connection (`POST .../connections`)
|
|
212
|
-
* and the server mints the id. When set, the transport skips registration and
|
|
213
|
-
* sends its SDP offer directly to that connection — so the id must already have
|
|
214
|
-
* been registered under this session (e.g. a backend called `POST .../connections`
|
|
215
|
-
* and handed the id to this client) and must still be open.
|
|
216
|
-
*
|
|
217
|
-
* `connect()` rejects if the id is invalid (out of the server's accepted range)
|
|
218
|
-
* or if no open connection with that id exists for the session.
|
|
219
|
-
*/
|
|
220
|
-
connectionId?: number;
|
|
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;
|
|
221
390
|
}
|
|
222
391
|
/**
|
|
223
|
-
*
|
|
224
|
-
*
|
|
225
|
-
*
|
|
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()`).
|
|
226
395
|
*
|
|
227
|
-
*
|
|
228
|
-
*
|
|
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.
|
|
229
402
|
*/
|
|
230
403
|
interface ConnectionTimings {
|
|
231
|
-
/** POST /sessions round-trip time */
|
|
232
404
|
sessionCreationMs: number;
|
|
233
|
-
/** Total time spent in transport.connect() (signaling, negotiation, etc.) */
|
|
234
405
|
transportConnectingMs: number;
|
|
235
|
-
/** End-to-end: connect() invocation → status "ready" */
|
|
406
|
+
/** End-to-end: connect() invocation → status "ready". */
|
|
236
407
|
totalMs: number;
|
|
237
408
|
}
|
|
238
409
|
interface ConnectionStats {
|
|
239
410
|
/** ICE candidate-pair round-trip time in milliseconds */
|
|
240
|
-
rtt?: number;
|
|
411
|
+
rtt?: number | undefined;
|
|
241
412
|
/** ICE candidate type: "host", "srflx", "prflx", or "relay" (TURN) */
|
|
242
|
-
candidateType?: string;
|
|
413
|
+
candidateType?: string | undefined;
|
|
243
414
|
/** Estimated available incoming bitrate in bits/second */
|
|
244
|
-
availableIncomingBitrate?: number;
|
|
415
|
+
availableIncomingBitrate?: number | undefined;
|
|
245
416
|
/** Estimated available outgoing bitrate in bits/second */
|
|
246
|
-
availableOutgoingBitrate?: number;
|
|
247
|
-
/** Real-time
|
|
248
|
-
incomingBitrate?: number;
|
|
249
|
-
/** Real-time
|
|
250
|
-
outgoingBitrate?: number;
|
|
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;
|
|
251
422
|
/** Received video frames per second */
|
|
252
|
-
framesPerSecond?: number;
|
|
423
|
+
framesPerSecond?: number | undefined;
|
|
253
424
|
/** Ratio of packets lost (0-1) */
|
|
254
|
-
packetLossRatio?: number;
|
|
425
|
+
packetLossRatio?: number | undefined;
|
|
255
426
|
/** Network jitter in seconds (from inbound-rtp) */
|
|
256
|
-
jitter?: number;
|
|
427
|
+
jitter?: number | undefined;
|
|
257
428
|
/** Timing breakdown of the initial connection handshake (set once, persisted until disconnect) */
|
|
258
|
-
connectionTimings?: ConnectionTimings;
|
|
429
|
+
connectionTimings?: ConnectionTimings | undefined;
|
|
259
430
|
timestamp: number;
|
|
260
431
|
}
|
|
261
|
-
|
|
432
|
+
/** Discriminator on a {@link Clip}. `"snap"` from `requestClip()`, `"recording"` from `requestRecording()`. */
|
|
433
|
+
type ClipKind = 'snap' | 'recording';
|
|
262
434
|
/**
|
|
263
|
-
*
|
|
264
|
-
* payload of a `runtimeMessage` with `type === "moderation"`.
|
|
435
|
+
* A finished (or soon-available) clip, from `requestClip()` / `requestRecording()`.
|
|
265
436
|
*
|
|
266
|
-
*
|
|
267
|
-
*
|
|
268
|
-
*
|
|
269
|
-
*
|
|
270
|
-
* session will be ended shortly after this message is dispatched.
|
|
271
|
-
*/
|
|
272
|
-
type ModerationAction = "warn" | "terminate";
|
|
273
|
-
/**
|
|
274
|
-
* Inner payload of a `runtimeMessage` with `type === "moderation"`.
|
|
275
|
-
*
|
|
276
|
-
* Surfaces a content-moderation outcome to the client app. Fires on
|
|
277
|
-
* any moderatable input (free-text fields, file uploads) that the
|
|
278
|
-
* configured moderation policy flags. Apps receive it by subscribing
|
|
279
|
-
* to the existing `runtimeMessage` event and filtering on `type`:
|
|
280
|
-
*
|
|
281
|
-
* reactor.on("runtimeMessage", (m) => {
|
|
282
|
-
* if (m?.type === "moderation") {
|
|
283
|
-
* const payload = m.data as ModerationEvent;
|
|
284
|
-
* // ...render banner, log, etc.
|
|
285
|
-
* }
|
|
286
|
-
* });
|
|
287
|
-
*/
|
|
288
|
-
interface ModerationEvent {
|
|
289
|
-
/** Severity tier — `"warn"` continues the session, `"terminate"` ends it. */
|
|
290
|
-
action: ModerationAction;
|
|
291
|
-
/**
|
|
292
|
-
* Modality of the flagged input. `"text"` for string fields,
|
|
293
|
-
* `"image"` for `UploadedFile` payloads with an image MIME type.
|
|
294
|
-
*/
|
|
295
|
-
input_kind: "text" | "image";
|
|
296
|
-
/**
|
|
297
|
-
* Name of the inbound command/event whose payload was flagged
|
|
298
|
-
* (e.g. `"set_prompt"`, `"set_image"`, `"fileUploaded"`).
|
|
299
|
-
*/
|
|
300
|
-
command: string;
|
|
301
|
-
/** Category labels that flagged (e.g. `["sexual"]`, `["violence/graphic"]`). */
|
|
302
|
-
categories: string[];
|
|
303
|
-
/** Short human-readable summary suitable for UI rendering. */
|
|
304
|
-
message: string;
|
|
305
|
-
}
|
|
306
|
-
|
|
307
|
-
/**
|
|
308
|
-
* Lazy resolver for the Coordinator bearer token. The SDK calls this
|
|
309
|
-
* immediately before each authenticated HTTP request, so short-lived
|
|
310
|
-
* tokens (Clerk session JWTs, etc.) are refreshed transparently.
|
|
311
|
-
* Returning `""` suppresses the `Authorization` header entirely.
|
|
312
|
-
*/
|
|
313
|
-
type JwtResolver = () => string | Promise<string>;
|
|
314
|
-
/** Static token, or a {@link JwtResolver} invoked per request. */
|
|
315
|
-
type JwtSource = string | JwtResolver;
|
|
316
|
-
/** Wrap a {@link JwtSource} into a {@link JwtResolver}. */
|
|
317
|
-
declare function normalizeJwtSource(source: JwtSource): JwtResolver;
|
|
318
|
-
|
|
319
|
-
/**
|
|
320
|
-
* Stateless primitives for the Reactor recording feature.
|
|
321
|
-
*
|
|
322
|
-
* This module owns:
|
|
323
|
-
* - Public-facing {@link Clip} type, {@link RecordingError} class, and
|
|
324
|
-
* the `RuntimeRecordingMessageType` enum.
|
|
325
|
-
* - Wire schemas (`ClipReadyPayloadSchema`, `ClipFailedPayloadSchema`)
|
|
326
|
-
* plus `clipFromPayload` to convert snake_case wire payloads into
|
|
327
|
-
* camelCase `Clip` objects.
|
|
328
|
-
* - HTTP helpers `fetchPlaylist` (deadline-driven polling) and
|
|
329
|
-
* `parsePlaylist` (HLS `.m3u8` parser).
|
|
330
|
-
* - The `downloadClipAsFile` helper that streams the referenced
|
|
331
|
-
* fMP4 chunks, remuxes them into a flat social-media-ready MP4
|
|
332
|
-
* via `mp4box` (PTS=0, faststart, `major_brand=isom`), and
|
|
333
|
-
* returns a Blob for browser download.
|
|
334
|
-
*
|
|
335
|
-
* Stateful pieces (FIFO promise correlator, in-flight request
|
|
336
|
-
* lifecycle, integration with Reactor's event bus) live in the
|
|
337
|
-
* `RecordingClient` class in `core/RecordingClient.ts`.
|
|
338
|
-
*
|
|
339
|
-
* Wire contract is documented end-to-end in the *Video Recording
|
|
340
|
-
* Feature* Notion page; the runtime side ships in
|
|
341
|
-
* `reactor_runtime/recording/`.
|
|
342
|
-
*/
|
|
343
|
-
|
|
344
|
-
/**
|
|
345
|
-
* Names of the runtime-scoped messages used by the recording feature.
|
|
346
|
-
* Outbound names are sent via `Reactor.sendCommand(name, …, "runtime")`;
|
|
347
|
-
* inbound names appear as `message.type` on `runtimeMessage` events.
|
|
348
|
-
*/
|
|
349
|
-
declare const RuntimeRecordingMessageType: {
|
|
350
|
-
readonly REQUEST_CLIP: "requestClip";
|
|
351
|
-
readonly REQUEST_RECORDING: "requestRecording";
|
|
352
|
-
readonly CLIP_READY: "clipReady";
|
|
353
|
-
readonly CLIP_FAILED: "clipFailed";
|
|
354
|
-
};
|
|
355
|
-
/** Discriminator on a {@link Clip}. `"snap"` from `requestClip`, `"recording"` from `requestRecording`. */
|
|
356
|
-
type ClipKind = "snap" | "recording";
|
|
357
|
-
/**
|
|
358
|
-
* Resolved outcome of a {@link Reactor.requestClip} / {@link Reactor.requestRecording} call.
|
|
359
|
-
*
|
|
360
|
-
* The runtime returns immediately on every request — it does *not*
|
|
361
|
-
* block until the in-progress chunk has been finalised. The response
|
|
362
|
-
* is a *promise*: `endMarker` reflects wall-clock at request time
|
|
363
|
-
* and may point inside a chunk ffmpeg is still writing. The
|
|
364
|
-
* `/clips` manifest endpoint returns `202 Retry-After` while that
|
|
365
|
-
* chunk is in flight; the SDK polls until `200`.
|
|
366
|
-
*
|
|
367
|
-
* - `startMarker` / `endMarker` / `nowMarker` are session-relative
|
|
368
|
-
* seconds since recorder start.
|
|
369
|
-
* - `predictedReadyAtMs` is a **Unix epoch in milliseconds** — the
|
|
370
|
-
* runtime's estimate of when the boundary chunk will be servable
|
|
371
|
-
* by `/clips`. Compare against `Date.now()` to drive a "ready in
|
|
372
|
-
* Ns" indicator. It is only an estimate: the SDK polls `/clips`
|
|
373
|
-
* until the manifest is actually ready and does not give up when
|
|
374
|
-
* this epoch passes (see {@link fetchPlaylist} for the polling and
|
|
375
|
-
* cancellation model).
|
|
376
|
-
* - `playlistUrl` is short-lived in production (the embedded chunk
|
|
377
|
-
* URLs are presigned for a few minutes). Re-issuing the request
|
|
378
|
-
* produces a fresh URL with fresh presigning.
|
|
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.
|
|
379
441
|
*/
|
|
380
442
|
interface Clip {
|
|
381
443
|
sessionId: string;
|
|
382
444
|
kind: ClipKind;
|
|
445
|
+
/** Session-relative seconds since recorder start. */
|
|
383
446
|
startMarker: number;
|
|
384
447
|
endMarker: number;
|
|
385
448
|
nowMarker: number;
|
|
449
|
+
/** Unix epoch in milliseconds. */
|
|
386
450
|
predictedReadyAtMs: number;
|
|
451
|
+
/** Absolute HLS manifest URL — short-lived; re-issuing the request produces a fresh one. */
|
|
387
452
|
playlistUrl: string;
|
|
388
453
|
}
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
/** `clipFailed.data` payload — short reason string from the runtime. */
|
|
417
|
-
declare const ClipFailedPayloadSchema: z.ZodObject<{
|
|
418
|
-
reason: z.ZodDefault<z.ZodString>;
|
|
419
|
-
}, z.core.$loose>;
|
|
420
|
-
type ClipFailedPayload = z.infer<typeof ClipFailedPayloadSchema>;
|
|
421
|
-
/** Options for {@link clipFromPayload}. */
|
|
422
|
-
interface ParseClipOptions {
|
|
423
|
-
/**
|
|
424
|
-
* Coordinator base URL. When set, resolves `payload.playlist_url`
|
|
425
|
-
* against this base — used to convert the runtime's path-only
|
|
426
|
-
* playlist URL (``/clips?session_id=…``) into an absolute URL the
|
|
427
|
-
* browser/SDK can fetch. Also handles the legacy case where an
|
|
428
|
-
* older runtime emits an absolute URL bound to its own
|
|
429
|
-
* ``0.0.0.0`` listener: the host/port are rewritten onto the
|
|
430
|
-
* coordinator.
|
|
431
|
-
*/
|
|
432
|
-
coordinatorBaseUrl?: string;
|
|
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;
|
|
433
481
|
}
|
|
482
|
+
type ReactorEventName = keyof ReactorEventMap;
|
|
483
|
+
|
|
434
484
|
/**
|
|
435
|
-
*
|
|
436
|
-
*
|
|
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`).
|
|
437
495
|
*/
|
|
438
|
-
|
|
496
|
+
|
|
439
497
|
/**
|
|
440
|
-
*
|
|
441
|
-
*
|
|
442
|
-
*
|
|
443
|
-
*
|
|
444
|
-
* * **Path-only / relative target** (no scheme — e.g. the
|
|
445
|
-
* runtime's current ``/clips?session_id=…`` shape): joined
|
|
446
|
-
* against ``base`` via ``new URL(target, base)``, preserving
|
|
447
|
-
* path, query, and fragment.
|
|
448
|
-
* * **Absolute target** (``http://…`` / ``https://…``, e.g. a legacy
|
|
449
|
-
* runtime emitting a URL bound to its own ``0.0.0.0`` listener):
|
|
450
|
-
* scheme, hostname, and port are replaced with ``base``'s,
|
|
451
|
-
* preserving path, query, and fragment.
|
|
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.
|
|
452
502
|
*
|
|
453
|
-
*
|
|
454
|
-
*
|
|
455
|
-
* a session over a malformed clip envelope.
|
|
503
|
+
* `code` is a stable, machine-readable identifier; `reason` is the raw
|
|
504
|
+
* string behind it (an HTTP status, a parse complaint, …).
|
|
456
505
|
*/
|
|
457
|
-
declare
|
|
458
|
-
|
|
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. */
|
|
459
512
|
interface ParsedPlaylist {
|
|
460
513
|
initUrl: string;
|
|
461
514
|
segmentUrls: string[];
|
|
462
515
|
}
|
|
463
516
|
/**
|
|
464
|
-
* Suggested grace period for callers that opt into a
|
|
465
|
-
*
|
|
466
|
-
*
|
|
467
|
-
* supplied. Provided so callers who do want the old ~15 s ceiling can
|
|
468
|
-
* ask for it by name rather than hard-coding a magic number.
|
|
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.
|
|
469
520
|
*/
|
|
470
521
|
declare const DEFAULT_PLAYLIST_POLL_SLACK_MS = 15000;
|
|
471
522
|
interface FetchPlaylistOptions {
|
|
472
523
|
/**
|
|
473
|
-
* Unix epoch (ms) when the runtime predicts the boundary chunk will
|
|
474
|
-
*
|
|
475
|
-
*
|
|
476
|
-
* deadline. Use it to drive a "ready in Ns" indicator.
|
|
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.
|
|
477
527
|
*/
|
|
478
528
|
predictedReadyAtMs?: number;
|
|
479
529
|
/**
|
|
480
|
-
* Opt-in grace period that turns polling into a
|
|
481
|
-
*
|
|
482
|
-
*
|
|
483
|
-
*
|
|
484
|
-
* caller aborts via `signal`. See {@link DEFAULT_PLAYLIST_POLL_SLACK_MS}
|
|
485
|
-
* for a sensible value if you want the old ~15 s ceiling.
|
|
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`.
|
|
486
534
|
*/
|
|
487
535
|
slackMs?: number;
|
|
488
|
-
/**
|
|
489
|
-
* Hard cap on the per-poll wait. The server's `Retry-After` header is
|
|
490
|
-
* honored but clamped. Default 2000 ms keeps pending UI snappy.
|
|
491
|
-
*/
|
|
536
|
+
/** Hard cap on the per-poll wait. `Retry-After` is honored but clamped. Default 2000 ms. */
|
|
492
537
|
maxRetryDelayMs?: number;
|
|
493
|
-
/** Floor on the per-poll wait so
|
|
538
|
+
/** Floor on the per-poll wait so a cheap network doesn't hot-loop. Default 200 ms. */
|
|
494
539
|
minRetryDelayMs?: number;
|
|
495
540
|
/**
|
|
496
541
|
* Opt-in cap on the number of `202` responses tolerated before
|
|
497
|
-
* `CLIP_NOT_READY`. Omit (the default) to poll indefinitely
|
|
498
|
-
* for a simple attempt-count ceiling when you don't have a
|
|
499
|
-
* `predictedReadyAtMs` to anchor a `slackMs` deadline.
|
|
542
|
+
* `CLIP_NOT_READY`. Omit (the default) to poll indefinitely.
|
|
500
543
|
*/
|
|
501
544
|
maxRetries?: number;
|
|
502
545
|
/**
|
|
503
|
-
* Aborts in-flight fetches and the inter-poll sleep
|
|
504
|
-
*
|
|
505
|
-
* wait that is taking too long (a timeout, a user "cancel", a React
|
|
506
|
-
* unmount).
|
|
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).
|
|
507
548
|
*/
|
|
508
549
|
signal?: AbortSignal;
|
|
509
550
|
/**
|
|
510
|
-
* Coordinator JWT
|
|
511
|
-
*
|
|
512
|
-
* (HttpRuntime), leave undefined.
|
|
551
|
+
* Coordinator JWT, attached as `Authorization: Bearer <jwt>` on the
|
|
552
|
+
* manifest GET. Omit in local mode (HttpRuntime).
|
|
513
553
|
*/
|
|
514
554
|
jwt?: string;
|
|
515
555
|
}
|
|
516
556
|
/**
|
|
517
|
-
* Fetch
|
|
518
|
-
*
|
|
557
|
+
* Fetch `playlistUrl`, polling on `202 Accepted` — returned while the
|
|
558
|
+
* boundary chunk is still uploading.
|
|
519
559
|
*
|
|
520
|
-
*
|
|
521
|
-
*
|
|
522
|
-
*
|
|
523
|
-
*
|
|
524
|
-
*
|
|
525
|
-
* to cancel, or opt into a ceiling with `slackMs` / `maxRetries`.
|
|
526
|
-
*
|
|
527
|
-
* - `200` → returns the manifest body.
|
|
528
|
-
* - `410` / `404` → throws `CLIP_GONE`.
|
|
529
|
-
* - `5xx`/other → throws `PLAYLIST_FETCH_FAILED` (no retry).
|
|
530
|
-
* - `202` past an opt-in `slackMs` deadline or `maxRetries` cap →
|
|
531
|
-
* throws `CLIP_NOT_READY`.
|
|
532
|
-
* - aborted `signal` → rejects with the fetch/`sleep` `AbortError`.
|
|
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`.
|
|
533
565
|
*/
|
|
534
566
|
declare function fetchPlaylist(playlistUrl: string, options?: FetchPlaylistOptions): Promise<string>;
|
|
535
567
|
/**
|
|
536
|
-
* Parse an HLS `.m3u8` body into the init segment URL plus the ordered
|
|
537
|
-
*
|
|
538
|
-
* playlist URL itself.
|
|
568
|
+
* Parse an HLS `.m3u8` body into the init segment URL plus the ordered media
|
|
569
|
+
* segment URLs, resolving relative URLs against `playlistUrl` itself.
|
|
539
570
|
*/
|
|
540
571
|
declare function parsePlaylist(manifestBody: string, playlistUrl: string): ParsedPlaylist;
|
|
541
572
|
/**
|
|
542
|
-
* Wrap an HLS manifest body in a `blob:` URL suitable for `<video src>`
|
|
543
|
-
*
|
|
544
|
-
*
|
|
545
|
-
* chunk URLs
|
|
546
|
-
*
|
|
547
|
-
*
|
|
548
|
-
* ``playlistUrl`` first. Without this rewrite the browser would
|
|
549
|
-
* resolve them against the ``blob:`` URL's effective base — the page's
|
|
550
|
-
* origin — and a local-dev frontend on (e.g.) port 3000 would issue
|
|
551
|
-
* chunk fetches against its own dev server instead of the
|
|
552
|
-
* HttpRuntime's ``/clips/chunks/...`` endpoint on port 8080. In
|
|
553
|
-
* production / kind-cluster mode the manifest already carries absolute
|
|
554
|
-
* presigned S3 URLs and `resolveAgainst` is a no-op on them.
|
|
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.
|
|
555
579
|
*
|
|
556
|
-
* Caller owns the returned URL — revoke it via `URL.revokeObjectURL`
|
|
557
|
-
*
|
|
558
|
-
*
|
|
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.
|
|
559
583
|
*/
|
|
560
584
|
declare function createPlayableManifestUrl(manifestBody: string, playlistUrl: string): string;
|
|
561
585
|
interface DownloadClipOptions {
|
|
562
|
-
/**
|
|
563
|
-
*
|
|
564
|
-
* referenced inside the manifest are S3 presigned URLs and are
|
|
565
|
-
* fetched unauthenticated.
|
|
566
|
-
*/
|
|
586
|
+
/** Coordinator JWT for the manifest GET. The chunks it references are S3
|
|
587
|
+
* presigned URLs, fetched unauthenticated. */
|
|
567
588
|
jwt?: string;
|
|
568
|
-
/**
|
|
589
|
+
/** Cancels both the playlist poll and any in-flight chunk fetches. */
|
|
569
590
|
signal?: AbortSignal;
|
|
570
591
|
/** Called after each chunk completes — useful for progress UI. */
|
|
571
592
|
onProgress?: (info: {
|
|
@@ -575,627 +596,597 @@ interface DownloadClipOptions {
|
|
|
575
596
|
}) => void;
|
|
576
597
|
}
|
|
577
598
|
/**
|
|
578
|
-
*
|
|
579
|
-
*
|
|
580
|
-
* `filename`
|
|
581
|
-
* Pass `filename: null` to skip the download trigger and just
|
|
582
|
-
* receive the Blob.
|
|
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.
|
|
583
602
|
*
|
|
584
|
-
*
|
|
585
|
-
* AAC packets pass through unchanged — so `start_time=0`,
|
|
586
|
-
* `+faststart`, and `major_brand=isom` come for free without any
|
|
587
|
-
* re-encode cost. See {@link maybeRemux} for the fallback
|
|
588
|
-
* semantics on the rare parse failure.
|
|
603
|
+
* See {@link assembleClipBlob} for the remux and memory-bound caveats.
|
|
589
604
|
*/
|
|
590
605
|
declare function downloadClipAsFile(clip: Clip, filename?: string | null, options?: DownloadClipOptions): Promise<Blob>;
|
|
591
606
|
|
|
592
607
|
/**
|
|
593
|
-
*
|
|
594
|
-
* inbound `clipReady` / `clipFailed` runtime messages and the
|
|
595
|
-
* lifecycle hooks (subscribe on construct, reject pending requests
|
|
596
|
-
* on disconnect). Reactor exposes thin delegations for the common
|
|
597
|
-
* case; this class is exported for advanced consumers and isolated
|
|
598
|
-
* testing.
|
|
608
|
+
* A live connection to a Reactor model.
|
|
599
609
|
*/
|
|
600
|
-
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
/**
|
|
617
|
-
*
|
|
618
|
-
*
|
|
619
|
-
|
|
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.
|
|
620
649
|
*/
|
|
621
|
-
|
|
622
|
-
/** Current connection status — guards `requestClip` before it goes on the wire. */
|
|
623
|
-
getStatus: () => ReactorStatus;
|
|
650
|
+
connect(jwt?: JwtSource, options?: ConnectOptions): Promise<void>;
|
|
624
651
|
/**
|
|
625
|
-
*
|
|
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.
|
|
626
657
|
*
|
|
627
|
-
*
|
|
628
|
-
*
|
|
629
|
-
*
|
|
630
|
-
* production (Coordinator on the SDK's ``apiUrl``). We always
|
|
631
|
-
* resolve against the ``Reactor``'s coordinator URL — there is no
|
|
632
|
-
* remote-vs-local divergence on the read path.
|
|
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.
|
|
633
661
|
*
|
|
634
|
-
*
|
|
635
|
-
*
|
|
636
|
-
*
|
|
637
|
-
* to rewrite the host onto the coordinator — see
|
|
638
|
-
* ``rewriteUrlHost`` in ``utils/recording.ts``.
|
|
639
|
-
*/
|
|
640
|
-
getCoordinatorBaseUrl: () => string | undefined;
|
|
641
|
-
}
|
|
642
|
-
declare class RecordingClient {
|
|
643
|
-
private readonly host;
|
|
644
|
-
private pendingClipRequests;
|
|
645
|
-
/** Timeout applied per request; configurable for tests. */
|
|
646
|
-
private readonly requestTimeoutMs;
|
|
647
|
-
/** Cleanup handles for the host event subscriptions. */
|
|
648
|
-
private readonly unsubscribers;
|
|
649
|
-
constructor(host: RecordingClientHost, options?: {
|
|
650
|
-
requestTimeoutMs?: number;
|
|
651
|
-
});
|
|
652
|
-
/**
|
|
653
|
-
* Request a clip covering the last `durationSeconds` of the live
|
|
654
|
-
* session. See {@link Reactor.requestClip}.
|
|
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.
|
|
655
665
|
*/
|
|
656
|
-
|
|
657
|
-
/**
|
|
658
|
-
* Request a clip covering the entire session up to "now". See
|
|
659
|
-
* {@link Reactor.requestRecording}.
|
|
660
|
-
*/
|
|
661
|
-
requestRecording(): Promise<Clip>;
|
|
666
|
+
disconnect(recoverable?: boolean): Promise<void>;
|
|
662
667
|
/**
|
|
663
|
-
*
|
|
664
|
-
*
|
|
665
|
-
*
|
|
666
|
-
* (
|
|
667
|
-
* HttpRuntime, `options.jwt` should be omitted.
|
|
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.
|
|
668
672
|
*/
|
|
669
|
-
|
|
673
|
+
reconnect(options?: ConnectOptions): Promise<void>;
|
|
670
674
|
/**
|
|
671
|
-
*
|
|
672
|
-
* `<video src>` / `hls.js`. The player reads the manifest from
|
|
673
|
-
* browser memory; chunk URLs inside are presigned S3 GETs.
|
|
675
|
+
* Sends a command to the model and resolves with its correlated reply.
|
|
674
676
|
*
|
|
675
|
-
*
|
|
676
|
-
*
|
|
677
|
-
*
|
|
678
|
-
|
|
679
|
-
|
|
680
|
-
|
|
681
|
-
*
|
|
682
|
-
* `
|
|
683
|
-
|
|
684
|
-
|
|
685
|
-
|
|
686
|
-
*
|
|
687
|
-
*
|
|
688
|
-
*
|
|
689
|
-
*
|
|
690
|
-
*
|
|
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.
|
|
691
700
|
*/
|
|
692
|
-
|
|
701
|
+
sendCommand<T extends object = Record<string, unknown>>(command: string, data?: NotFunction<T>, scope?: MessageScope): Promise<ReactorMessage | undefined>;
|
|
693
702
|
/**
|
|
694
|
-
*
|
|
695
|
-
*
|
|
696
|
-
*
|
|
697
|
-
|
|
698
|
-
|
|
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;
|
|
699
739
|
/**
|
|
700
|
-
*
|
|
701
|
-
*
|
|
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.
|
|
702
747
|
*/
|
|
703
|
-
|
|
704
|
-
private onStatusChanged;
|
|
705
|
-
/** Reject every in-flight request with a typed disconnect error. */
|
|
706
|
-
private rejectPending;
|
|
707
|
-
}
|
|
708
|
-
|
|
709
|
-
declare const DEFAULT_BASE_URL = "https://api.reactor.inc";
|
|
710
|
-
declare const OptionsSchema: z.ZodObject<{
|
|
711
|
-
apiUrl: z.ZodDefault<z.ZodString>;
|
|
712
|
-
modelName: z.ZodString;
|
|
713
|
-
local: z.ZodDefault<z.ZodBoolean>;
|
|
714
|
-
modelTracks: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
715
|
-
name: z.ZodString;
|
|
716
|
-
kind: z.ZodEnum<{
|
|
717
|
-
video: "video";
|
|
718
|
-
audio: "audio";
|
|
719
|
-
}>;
|
|
720
|
-
direction: z.ZodEnum<{
|
|
721
|
-
recvonly: "recvonly";
|
|
722
|
-
sendonly: "sendonly";
|
|
723
|
-
}>;
|
|
724
|
-
}, z.core.$strip>>>;
|
|
725
|
-
}, z.core.$strip>;
|
|
726
|
-
type Options = z.input<typeof OptionsSchema>;
|
|
727
|
-
|
|
728
|
-
type EventHandler = (...args: any[]) => void;
|
|
729
|
-
declare class Reactor {
|
|
730
|
-
private coordinatorClient;
|
|
731
|
-
private transportClient;
|
|
732
|
-
private status;
|
|
733
|
-
private coordinatorUrl;
|
|
734
|
-
private lastError?;
|
|
735
|
-
private model;
|
|
736
|
-
private sessionExpiration?;
|
|
737
|
-
private local;
|
|
738
|
-
private sessionId?;
|
|
748
|
+
publishTrack(name: string, track: MediaStreamTrack): Promise<void>;
|
|
739
749
|
/**
|
|
740
|
-
*
|
|
741
|
-
*
|
|
742
|
-
*
|
|
743
|
-
*
|
|
744
|
-
* lifecycle, so on disconnect/teardown/error an adopting client tears
|
|
745
|
-
* down its own transport but leaves the session alive.
|
|
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.
|
|
746
754
|
*/
|
|
747
|
-
|
|
748
|
-
private retryingSessionLoss;
|
|
749
|
-
private connectStartTime?;
|
|
750
|
-
private connectionTimings?;
|
|
751
|
-
private schema?;
|
|
752
|
-
private tracks;
|
|
753
|
-
private presetTracks?;
|
|
754
|
-
private autoResumeTracks;
|
|
755
|
-
private sessionResponse?;
|
|
756
|
-
private jwtResolver?;
|
|
757
|
-
/** Per-Reactor recording client. See {@link RecordingClient}. */
|
|
758
|
-
readonly recording: RecordingClient;
|
|
759
|
-
constructor(options: Options);
|
|
760
|
-
private eventListeners;
|
|
755
|
+
unpublishTrack(name: string): Promise<void>;
|
|
761
756
|
/**
|
|
762
|
-
*
|
|
763
|
-
*
|
|
764
|
-
*
|
|
765
|
-
* own `getJwt` prop is omitted.
|
|
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()`.
|
|
766
760
|
*/
|
|
767
|
-
|
|
768
|
-
on(event: ReactorEvent, handler: EventHandler): void;
|
|
769
|
-
off(event: ReactorEvent, handler: EventHandler): void;
|
|
770
|
-
emit(event: ReactorEvent, ...args: any[]): void;
|
|
761
|
+
pauseTrack(name: string): Promise<void>;
|
|
771
762
|
/**
|
|
772
|
-
*
|
|
763
|
+
* Bounds what one sender may spend, in bits per second.
|
|
773
764
|
*
|
|
774
|
-
*
|
|
775
|
-
*
|
|
776
|
-
*
|
|
777
|
-
|
|
778
|
-
|
|
779
|
-
/**
|
|
780
|
-
* Uploads a file to the session's object store and returns a {@link FileRef}.
|
|
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.
|
|
781
770
|
*
|
|
782
|
-
*
|
|
783
|
-
*
|
|
784
|
-
*
|
|
785
|
-
*
|
|
786
|
-
* (fires `@file_uploaded` on the model if registered)
|
|
787
|
-
* 4. Return a `FileRef` to pass into {@link sendCommand}
|
|
771
|
+
* ```ts
|
|
772
|
+
* await reactor.publishTrack('camera', cameraTrack);
|
|
773
|
+
* await reactor.setTrackBitrate('camera', { maxBps: 8_000_000 });
|
|
774
|
+
* ```
|
|
788
775
|
*
|
|
789
|
-
*
|
|
790
|
-
*
|
|
791
|
-
*
|
|
792
|
-
|
|
793
|
-
|
|
794
|
-
|
|
795
|
-
}): Promise<FileRef>;
|
|
796
|
-
/**
|
|
797
|
-
* Request a clip covering the last `durationSeconds` of the live
|
|
798
|
-
* session. Capped server-side at `recording.clip_max_seconds`
|
|
799
|
-
* (default 5 minutes). Resolves with a {@link Clip} whose
|
|
800
|
-
* `playlistUrl` can be handed to any HLS-capable player.
|
|
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()`.
|
|
801
782
|
*
|
|
802
|
-
*
|
|
803
|
-
*
|
|
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.
|
|
804
801
|
*/
|
|
805
802
|
requestClip(durationSeconds: number): Promise<Clip>;
|
|
806
|
-
/**
|
|
807
|
-
* Request a clip covering the entire session up to "now". Same
|
|
808
|
-
* mechanics as {@link requestClip} with `start = 0`; only the
|
|
809
|
-
* resolved {@link Clip.kind} discriminator differs.
|
|
810
|
-
*/
|
|
803
|
+
/** Requests a clip covering the entire session up to now. See `requestClip()`. */
|
|
811
804
|
requestRecording(): Promise<Clip>;
|
|
812
|
-
/**
|
|
813
|
-
* Stream the chunks referenced by `clip.playlistUrl` and trigger a
|
|
814
|
-
* native browser download of the assembled fragmented-MP4 Blob.
|
|
815
|
-
* Pass `filename: null` to skip the download trigger and receive
|
|
816
|
-
* the Blob (useful for non-DOM consumers and tests).
|
|
817
|
-
*/
|
|
805
|
+
/** Thin delegation to the standalone `downloadClipAsFile()` — see its own doc comment. */
|
|
818
806
|
downloadClipAsFile(clip: Clip, filename?: string | null, options?: DownloadClipOptions): Promise<Blob>;
|
|
819
807
|
/**
|
|
820
|
-
*
|
|
821
|
-
*
|
|
822
|
-
*
|
|
823
|
-
|
|
824
|
-
|
|
825
|
-
|
|
826
|
-
pauseTrack(name: string): void;
|
|
827
|
-
resumeTrack(name: string): void;
|
|
828
|
-
/** Whether `name` is a track this client receives rather than sends. */
|
|
829
|
-
private isRecvonly;
|
|
830
|
-
/**
|
|
831
|
-
* Reconnects to an existing session with a fresh transport.
|
|
832
|
-
*/
|
|
833
|
-
reconnect(options?: ConnectOptions): Promise<void>;
|
|
834
|
-
/**
|
|
835
|
-
* Connects to the coordinator, creates a session, then establishes
|
|
836
|
-
* the transport using server-declared capabilities. `jwtToken` may
|
|
837
|
-
* be a static string or a {@link JwtSource} resolver; pass a
|
|
838
|
-
* resolver when the token is short-lived so each Coordinator HTTP
|
|
839
|
-
* hop sees a fresh value.
|
|
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.
|
|
840
814
|
*
|
|
841
|
-
*
|
|
842
|
-
*
|
|
843
|
-
*
|
|
844
|
-
*
|
|
845
|
-
*
|
|
846
|
-
*/
|
|
847
|
-
connect(jwtToken?: JwtSource, options?: ConnectOptions): Promise<void>;
|
|
848
|
-
/**
|
|
849
|
-
* Sets up event handlers for the transport client.
|
|
850
|
-
* Each handler captures the client reference to ignore stale events.
|
|
851
|
-
*/
|
|
852
|
-
private setupTransportHandlers;
|
|
853
|
-
/**
|
|
854
|
-
* Disconnects from both the transport and the coordinator.
|
|
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.
|
|
855
820
|
*/
|
|
856
|
-
|
|
857
|
-
|
|
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. */
|
|
858
848
|
getStatus(): ReactorStatus;
|
|
859
|
-
|
|
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. */
|
|
860
858
|
getLastError(): ReactorError | undefined;
|
|
861
|
-
/**
|
|
862
|
-
*
|
|
863
|
-
* received over the runtime channel shortly after the session becomes
|
|
864
|
-
* ready. `undefined` until the `schemaReceived` event has fired.
|
|
865
|
-
*/
|
|
866
|
-
getSchema(): ModelSchema | undefined;
|
|
867
|
-
getSessionInfo(): SessionResponse | undefined;
|
|
859
|
+
/** The most recent WebRTC connection stats, polled every `STATS_INTERVAL_MS`
|
|
860
|
+
* while "ready" — see `statsUpdate`. `undefined` before the first sample. */
|
|
868
861
|
getStats(): ConnectionStats | undefined;
|
|
869
|
-
/** Timing breakdown from the most recent connect()
|
|
862
|
+
/** Timing breakdown from the most recent `connect()`/`reconnect()`
|
|
863
|
+
* handshake — see `ConnectionTimings`. */
|
|
870
864
|
getConnectionTimings(): ConnectionTimings | undefined;
|
|
871
|
-
|
|
872
|
-
|
|
873
|
-
|
|
874
|
-
private
|
|
875
|
-
private
|
|
876
|
-
|
|
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;
|
|
877
921
|
}
|
|
878
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. */
|
|
879
938
|
interface ReactorState {
|
|
880
939
|
status: ReactorStatus;
|
|
881
|
-
|
|
882
|
-
|
|
883
|
-
|
|
884
|
-
*
|
|
885
|
-
|
|
886
|
-
|
|
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`). */
|
|
887
951
|
tracks: Record<string, MediaStreamTrack>;
|
|
888
|
-
|
|
889
|
-
|
|
890
|
-
|
|
891
|
-
/**
|
|
892
|
-
|
|
893
|
-
|
|
894
|
-
*
|
|
895
|
-
|
|
896
|
-
* provider-level settings like `autoResumeTracks` are honoured for
|
|
897
|
-
* both autoConnect and manual connect calls.
|
|
898
|
-
*/
|
|
899
|
-
connectOptions?: ConnectOptions;
|
|
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;
|
|
900
960
|
}
|
|
901
961
|
interface ReactorActions {
|
|
902
|
-
|
|
903
|
-
|
|
904
|
-
|
|
905
|
-
|
|
906
|
-
|
|
907
|
-
|
|
908
|
-
|
|
909
|
-
|
|
910
|
-
|
|
911
|
-
unpublish(name: string): Promise<void>;
|
|
912
|
-
/**
|
|
913
|
-
* Ask the runtime to stop processing a recvonly track. Top-level
|
|
914
|
-
* alias for `internal.reactor.pauseTrack(…)` — lifted onto the store
|
|
915
|
-
* so consumers don't have to reach through `internal.reactor`. See
|
|
916
|
-
* {@link Reactor.pauseTrack}.
|
|
917
|
-
*/
|
|
918
|
-
pauseTrack(name: string): void;
|
|
919
|
-
/**
|
|
920
|
-
* Ask the runtime to resume a previously paused recvonly track.
|
|
921
|
-
* Top-level alias for `internal.reactor.resumeTrack(…)`. See
|
|
922
|
-
* {@link Reactor.resumeTrack}.
|
|
923
|
-
*/
|
|
924
|
-
resumeTrack(name: string): void;
|
|
925
|
-
reconnect(options?: ConnectOptions): Promise<void>;
|
|
926
|
-
uploadFile(file: File | Blob, options?: {
|
|
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?: {
|
|
927
971
|
name?: string;
|
|
928
|
-
})
|
|
929
|
-
|
|
930
|
-
|
|
931
|
-
|
|
932
|
-
* lifted onto the store so consumers don't have to reach through
|
|
933
|
-
* `internal.reactor` for the common case. See
|
|
934
|
-
* {@link Reactor.requestClip}.
|
|
935
|
-
*/
|
|
936
|
-
requestClip(durationSeconds: number): Promise<Clip>;
|
|
937
|
-
/**
|
|
938
|
-
* Capture the entire session up to "now" as a clip. Top-level
|
|
939
|
-
* alias for `internal.reactor.requestRecording()`. See
|
|
940
|
-
* {@link Reactor.requestRecording}.
|
|
941
|
-
*/
|
|
942
|
-
requestRecording(): Promise<Clip>;
|
|
943
|
-
/**
|
|
944
|
-
* Stream the chunks referenced by `clip.playlistUrl` and trigger a
|
|
945
|
-
* native browser download of the assembled MP4. Top-level alias
|
|
946
|
-
* for `internal.reactor.downloadClipAsFile(…)`. See
|
|
947
|
-
* {@link Reactor.downloadClipAsFile}.
|
|
948
|
-
*/
|
|
949
|
-
downloadClipAsFile(clip: Clip, filename?: string | null, options?: DownloadClipOptions): Promise<Blob>;
|
|
972
|
+
}) => Promise<FileRef>;
|
|
973
|
+
requestClip: (durationSeconds: number) => Promise<Clip>;
|
|
974
|
+
requestRecording: () => Promise<Clip>;
|
|
975
|
+
downloadClipAsFile: (clip: Clip, filename?: string | null, options?: DownloadClipOptions) => Promise<Blob>;
|
|
950
976
|
}
|
|
951
|
-
interface
|
|
977
|
+
interface ReactorInternal {
|
|
978
|
+
/** Escape hatch: the underlying `Reactor` instance, for anything the
|
|
979
|
+
* selector state / action bindings above don't cover. */
|
|
952
980
|
reactor: Reactor;
|
|
953
981
|
}
|
|
954
982
|
type ReactorStore = ReactorState & ReactorActions & {
|
|
955
|
-
internal:
|
|
983
|
+
internal: ReactorInternal;
|
|
956
984
|
};
|
|
957
|
-
interface ReactorInitializationProps extends Options {
|
|
958
|
-
/** Token source for the underlying {@link Reactor} — see {@link JwtSource}. */
|
|
959
|
-
jwtToken?: JwtSource;
|
|
960
|
-
/** Default connect options applied when `connect()` is called without explicit options. */
|
|
961
|
-
connectOptions?: ConnectOptions;
|
|
962
|
-
}
|
|
963
985
|
|
|
964
|
-
/**
|
|
965
|
-
*
|
|
966
|
-
*
|
|
967
|
-
*/
|
|
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. */
|
|
968
989
|
interface ReactorConnectOptions extends ConnectOptions {
|
|
969
|
-
/**
|
|
990
|
+
/** Connect automatically once a Reactor is built — initial mount, or any
|
|
991
|
+
* later rebuild. Default `false`. */
|
|
970
992
|
autoConnect?: boolean;
|
|
971
993
|
}
|
|
972
|
-
interface ReactorProviderProps
|
|
973
|
-
|
|
974
|
-
|
|
975
|
-
|
|
976
|
-
|
|
977
|
-
|
|
978
|
-
|
|
979
|
-
|
|
980
|
-
|
|
981
|
-
*
|
|
982
|
-
*
|
|
983
|
-
*/
|
|
984
|
-
|
|
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;
|
|
985
1008
|
children?: ReactNode;
|
|
986
1009
|
}
|
|
987
|
-
|
|
988
|
-
|
|
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;
|
|
989
1049
|
|
|
990
1050
|
interface ReactorViewProps {
|
|
991
|
-
/**
|
|
992
|
-
*
|
|
993
|
-
* Must match a track name declared in the server capabilities.
|
|
994
|
-
* Check the model's documentation for available track names.
|
|
995
|
-
* Defaults to `"main_video"`.
|
|
996
|
-
*/
|
|
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"`. */
|
|
997
1053
|
track?: string;
|
|
998
|
-
/**
|
|
999
|
-
*
|
|
1000
|
-
* (e.g. `"main_audio"`). The audio is mixed into the same `<video>` element.
|
|
1001
|
-
* Check the model's documentation for available track names.
|
|
1002
|
-
*/
|
|
1054
|
+
/** Name of a recvonly audio track to mix into the same `<video>` element
|
|
1055
|
+
* alongside `track`. */
|
|
1003
1056
|
audioTrack?: string;
|
|
1004
1057
|
width?: number;
|
|
1005
1058
|
height?: number;
|
|
1006
1059
|
className?: string;
|
|
1007
|
-
style?:
|
|
1008
|
-
videoObjectFit?: NonNullable<
|
|
1009
|
-
/**
|
|
1010
|
-
*
|
|
1011
|
-
*
|
|
1012
|
-
* `<video>` element within browser autoplay policies; `false`
|
|
1013
|
-
* when an `audioTrack` is set. Pass an explicit value to
|
|
1014
|
-
* override either default.
|
|
1015
|
-
*/
|
|
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. */
|
|
1016
1065
|
muted?: boolean;
|
|
1017
1066
|
}
|
|
1018
|
-
declare function ReactorView({ track, audioTrack, width, height, className, style, videoObjectFit, muted, }: ReactorViewProps):
|
|
1067
|
+
declare function ReactorView({ track, audioTrack, width, height, className, style, videoObjectFit, muted, }: ReactorViewProps): react.JSX.Element;
|
|
1019
1068
|
|
|
1020
1069
|
interface WebcamStreamProps {
|
|
1021
|
-
/**
|
|
1022
|
-
*
|
|
1023
|
-
* Must match a track name declared in the server capabilities.
|
|
1024
|
-
* Check the model's documentation for available track names.
|
|
1025
|
-
*/
|
|
1070
|
+
/** Name of the sendonly video track to publish the webcam to. Must match a
|
|
1071
|
+
* track name declared in the model's capabilities. */
|
|
1026
1072
|
track: string;
|
|
1027
|
-
/**
|
|
1028
|
-
*
|
|
1029
|
-
*
|
|
1030
|
-
* `MediaTrackConstraints` to control sample rate / device / echo
|
|
1031
|
-
* cancellation. Requires {@link audioTrack} so the SDK knows
|
|
1032
|
-
* which sendonly track to publish the mic to. Default `false`.
|
|
1033
|
-
*/
|
|
1073
|
+
/** Capture and publish the microphone alongside the webcam. `true` for
|
|
1074
|
+
* default constraints, or explicit `MediaTrackConstraints`. Requires
|
|
1075
|
+
* `audioTrack`. Defaults to `false`. */
|
|
1034
1076
|
audio?: boolean | MediaTrackConstraints;
|
|
1035
|
-
/**
|
|
1036
|
-
*
|
|
1037
|
-
* Ignored when {@link audio} is `false` (the default); required
|
|
1038
|
-
* otherwise.
|
|
1039
|
-
*/
|
|
1077
|
+
/** Name of the sendonly audio track to publish the mic to. Ignored unless
|
|
1078
|
+
* `audio` is set. */
|
|
1040
1079
|
audioTrack?: string;
|
|
1041
1080
|
className?: string;
|
|
1042
|
-
style?:
|
|
1081
|
+
style?: CSSProperties;
|
|
1082
|
+
/** Read once, at mount — changing this after mount doesn't re-request
|
|
1083
|
+
* `getUserMedia`. Matches v2. */
|
|
1043
1084
|
videoConstraints?: MediaTrackConstraints;
|
|
1044
1085
|
showWebcam?: boolean;
|
|
1045
|
-
videoObjectFit?: NonNullable<
|
|
1046
|
-
/**
|
|
1047
|
-
*
|
|
1048
|
-
* or `PermissionDeniedError`.
|
|
1049
|
-
*/
|
|
1086
|
+
videoObjectFit?: NonNullable<VideoHTMLAttributes<HTMLVideoElement>['style']>['objectFit'];
|
|
1087
|
+
/** Fires once `getUserMedia` is rejected with `NotAllowedError` or
|
|
1088
|
+
* `PermissionDeniedError`. */
|
|
1050
1089
|
onPermissionDenied?: () => void;
|
|
1051
|
-
/**
|
|
1052
|
-
*
|
|
1053
|
-
* video and audio when {@link audio} is enabled). Re-fires
|
|
1054
|
-
* after a reconnect.
|
|
1055
|
-
*/
|
|
1090
|
+
/** Fires after the local media has been published (video, and audio when
|
|
1091
|
+
* `audio` is enabled). Re-fires after a reconnect. */
|
|
1056
1092
|
onPublished?: () => void;
|
|
1057
|
-
/**
|
|
1058
|
-
*
|
|
1059
|
-
* publish / unpublish rejections. Permission denials route to
|
|
1060
|
-
* {@link onPermissionDenied} instead.
|
|
1061
|
-
*/
|
|
1093
|
+
/** Fires on non-permission `getUserMedia` failures and on publish/unpublish
|
|
1094
|
+
* rejections. Permission denials route to `onPermissionDenied` instead. */
|
|
1062
1095
|
onError?: (error: Error) => void;
|
|
1063
1096
|
}
|
|
1064
|
-
declare function WebcamStream({ track, audio, audioTrack, className, style, videoConstraints, showWebcam, videoObjectFit, onPermissionDenied, onPublished, onError, }: WebcamStreamProps):
|
|
1097
|
+
declare function WebcamStream({ track, audio, audioTrack, className, style, videoConstraints, showWebcam, videoObjectFit, onPermissionDenied, onPublished, onError, }: WebcamStreamProps): react.JSX.Element;
|
|
1065
1098
|
|
|
1066
1099
|
/**
|
|
1067
|
-
* Video preview for a captured {@link Clip}.
|
|
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.
|
|
1068
1109
|
*
|
|
1069
|
-
*
|
|
1070
|
-
*
|
|
1071
|
-
*
|
|
1072
|
-
* dynamically imported, so bundlers give it a chunk of its own that
|
|
1073
|
-
* an app importing this component fetches on first play and one that
|
|
1074
|
-
* never renders a player drops entirely. On iOS before 17.1 the clip
|
|
1075
|
-
* is assembled into a single MP4 and played from memory instead: the
|
|
1076
|
-
* whole clip is fetched before it starts, and it plays. Failures
|
|
1077
|
-
* surface in an inline error overlay, and the same clip stays
|
|
1078
|
-
* downloadable via {@link useClipDownload} /
|
|
1079
|
-
* {@link ClipDownloadButton}.
|
|
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`.
|
|
1080
1113
|
*
|
|
1081
|
-
*
|
|
1082
|
-
*
|
|
1083
|
-
*
|
|
1084
|
-
*
|
|
1085
|
-
*
|
|
1086
|
-
*
|
|
1087
|
-
* Unlike {@link ReactorView} / {@link WebcamStream} this component
|
|
1088
|
-
* **does not require a ``ReactorProvider``** in the tree. It
|
|
1089
|
-
* operates on the ``Clip`` value alone, so it stays usable after
|
|
1090
|
-
* ``reactor.disconnect()`` and works with clips loaded from
|
|
1091
|
-
* fixtures, server logs, or any other source. When a
|
|
1092
|
-
* ``ReactorProvider`` is mounted above, an omitted ``getJwt``
|
|
1093
|
-
* inherits the provider's resolver.
|
|
1094
|
-
*
|
|
1095
|
-
* @example Compose with the download button (explicit `getJwt`):
|
|
1096
|
-
* ```tsx
|
|
1097
|
-
* <div>
|
|
1098
|
-
* <ClipPlayer clip={clip} getJwt={() => jwt} />
|
|
1099
|
-
* <ClipDownloadButton clip={clip} getJwt={() => jwt} />
|
|
1100
|
-
* </div>
|
|
1101
|
-
* ```
|
|
1102
|
-
*
|
|
1103
|
-
* @example Local dev (HttpRuntime, no auth on /clips):
|
|
1104
|
-
* ```tsx
|
|
1105
|
-
* <ClipPlayer clip={clip} />
|
|
1106
|
-
* ```
|
|
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.
|
|
1107
1119
|
*/
|
|
1108
1120
|
interface ClipPlayerProps {
|
|
1109
|
-
/**
|
|
1110
|
-
*
|
|
1111
|
-
* the player re-fetches the manifest and re-attaches the player.
|
|
1112
|
-
*/
|
|
1121
|
+
/** The captured clip to play. Re-fetches the manifest and re-attaches the
|
|
1122
|
+
* player when this changes by reference. */
|
|
1113
1123
|
clip: Clip;
|
|
1114
1124
|
/**
|
|
1115
|
-
* Lazy resolver for the Coordinator JWT used on the
|
|
1116
|
-
*
|
|
1117
|
-
* picked up automatically.
|
|
1118
|
-
*
|
|
1119
|
-
* - **Production:** required outside a ``<ReactorProvider>``;
|
|
1120
|
-
* optional inside one (inherits the provider's resolver).
|
|
1121
|
-
* - **Local-dev (HttpRuntime):** omit — ``/clips`` is auth-free.
|
|
1125
|
+
* Lazy resolver for the Coordinator JWT used on the manifest GET, called
|
|
1126
|
+
* at request time so token refreshes are picked up automatically.
|
|
1122
1127
|
*
|
|
1123
|
-
*
|
|
1124
|
-
*
|
|
1125
|
-
*
|
|
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.
|
|
1126
1131
|
*/
|
|
1127
1132
|
getJwt?: () => string | Promise<string>;
|
|
1128
1133
|
/**
|
|
1129
|
-
* Opt into a
|
|
1130
|
-
*
|
|
1131
|
-
*
|
|
1132
|
-
*
|
|
1133
|
-
*
|
|
1134
|
-
* (both abort the in-flight poll). Set a value when you want a hard
|
|
1135
|
-
* ceiling (e.g. ``120_000`` for a two-minute cap). Forwarded
|
|
1136
|
-
* directly to {@link fetchPlaylist}'s ``slackMs`` option — see that
|
|
1137
|
-
* helper for the polling semantics.
|
|
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.
|
|
1138
1139
|
*/
|
|
1139
1140
|
slackMs?: number;
|
|
1140
|
-
/** Play automatically once the manifest is attached. Default
|
|
1141
|
+
/** Play automatically once the manifest is attached. Default `true`. */
|
|
1141
1142
|
autoPlay?: boolean;
|
|
1142
|
-
/**
|
|
1143
|
-
*
|
|
1144
|
-
*
|
|
1145
|
-
* the user can unmute via the native ``<video controls>``.
|
|
1146
|
-
*/
|
|
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. */
|
|
1147
1146
|
muted?: boolean;
|
|
1148
1147
|
className?: string;
|
|
1149
|
-
style?:
|
|
1150
|
-
/**
|
|
1151
|
-
*
|
|
1152
|
-
*
|
|
1153
|
-
* failures, a plain ``Error`` for hls.js / native playback or
|
|
1154
|
-
* missing-peer-dep cases.
|
|
1155
|
-
*/
|
|
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. */
|
|
1156
1152
|
onError?: (error: Error) => void;
|
|
1157
1153
|
}
|
|
1158
|
-
declare function ClipPlayer({ clip, getJwt, slackMs, autoPlay, muted, className, style, onError, }: ClipPlayerProps):
|
|
1154
|
+
declare function ClipPlayer({ clip, getJwt, slackMs, autoPlay, muted, className, style, onError, }: ClipPlayerProps): react.JSX.Element;
|
|
1159
1155
|
|
|
1160
1156
|
/**
|
|
1161
1157
|
* State machine for an in-progress clip download.
|
|
1162
1158
|
*
|
|
1163
|
-
* -
|
|
1164
|
-
*
|
|
1165
|
-
* -
|
|
1166
|
-
*
|
|
1167
|
-
*
|
|
1168
|
-
*
|
|
1169
|
-
*
|
|
1170
|
-
* for surfacing inline. ``RecordingError`` instances are formatted
|
|
1171
|
-
* as ``"<CODE>: <reason>"`` for grep-ability.
|
|
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>"`.
|
|
1172
1166
|
*/
|
|
1173
1167
|
type ClipDownloadState = {
|
|
1174
|
-
kind:
|
|
1168
|
+
kind: 'idle';
|
|
1175
1169
|
} | {
|
|
1176
|
-
kind:
|
|
1170
|
+
kind: 'downloading';
|
|
1177
1171
|
fetched: number;
|
|
1178
1172
|
total: number;
|
|
1179
1173
|
} | {
|
|
1180
|
-
kind:
|
|
1174
|
+
kind: 'error';
|
|
1181
1175
|
message: string;
|
|
1182
1176
|
};
|
|
1183
1177
|
interface UseClipDownloadOptions {
|
|
1184
|
-
/**
|
|
1185
|
-
*
|
|
1186
|
-
*
|
|
1187
|
-
*
|
|
1188
|
-
* it or re-upload it. Default ``"reactor-clip.mp4"``.
|
|
1189
|
-
*/
|
|
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"`. */
|
|
1190
1182
|
filename?: string | null;
|
|
1191
1183
|
/**
|
|
1192
|
-
* Lazy resolver for the Coordinator JWT used on the
|
|
1193
|
-
*
|
|
1194
|
-
*
|
|
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.
|
|
1195
1187
|
*
|
|
1196
|
-
* Optional inside a
|
|
1197
|
-
*
|
|
1198
|
-
* {@link ClipPlayerProps.getJwt}.
|
|
1188
|
+
* Optional inside a `ReactorProvider` (inherits the provider's resolver)
|
|
1189
|
+
* and in local-dev mode.
|
|
1199
1190
|
*/
|
|
1200
1191
|
getJwt?: () => string | Promise<string>;
|
|
1201
1192
|
}
|
|
@@ -1203,158 +1194,73 @@ interface UseClipDownloadResult {
|
|
|
1203
1194
|
/** Current state of the most recent download attempt. */
|
|
1204
1195
|
state: ClipDownloadState;
|
|
1205
1196
|
/**
|
|
1206
|
-
* Trigger a download.
|
|
1207
|
-
*
|
|
1208
|
-
*
|
|
1209
|
-
*
|
|
1210
|
-
*
|
|
1211
|
-
* Errors are caught and surfaced via {@link state} — the returned
|
|
1212
|
-
* Promise still resolves to ``undefined`` rather than rejecting,
|
|
1213
|
-
* because the typical caller is a click handler that doesn't await.
|
|
1214
|
-
* Use ``state.kind === "error"`` to drive failure UI.
|
|
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.
|
|
1215
1201
|
*/
|
|
1216
1202
|
download: () => Promise<Blob | undefined>;
|
|
1217
|
-
/** Reset to
|
|
1203
|
+
/** Reset to `idle`. Does *not* cancel an in-flight download. */
|
|
1218
1204
|
reset: () => void;
|
|
1219
1205
|
}
|
|
1220
1206
|
/**
|
|
1221
|
-
* Headless download primitive for a {@link Clip}.
|
|
1222
|
-
*
|
|
1223
|
-
*
|
|
1224
|
-
*
|
|
1225
|
-
*
|
|
1226
|
-
* {@link ClipPlayer}'s built-in download button — when you need
|
|
1227
|
-
* custom placement or styling, set ``showDownloadButton={false}`` on
|
|
1228
|
-
* the player and call this hook directly.
|
|
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.
|
|
1229
1212
|
*
|
|
1230
|
-
*
|
|
1231
|
-
*
|
|
1232
|
-
* memoized children without forcing re-renders.
|
|
1233
|
-
*
|
|
1234
|
-
* @example Render a download button anywhere in your tree:
|
|
1235
|
-
* ```tsx
|
|
1236
|
-
* function ClipCard({ clip }: { clip: Clip }) {
|
|
1237
|
-
* const jwt = useReactor((s) => s.jwtToken);
|
|
1238
|
-
* const { state, download } = useClipDownload(clip, {
|
|
1239
|
-
* filename: `snap-${clip.sessionId}.mp4`,
|
|
1240
|
-
* getJwt: jwt ? () => jwt : undefined,
|
|
1241
|
-
* });
|
|
1242
|
-
* return (
|
|
1243
|
-
* <button onClick={download} disabled={state.kind === "downloading"}>
|
|
1244
|
-
* {state.kind === "downloading"
|
|
1245
|
-
* ? `${state.fetched}/${state.total}`
|
|
1246
|
-
* : state.kind === "error"
|
|
1247
|
-
* ? "Retry"
|
|
1248
|
-
* : "Download"}
|
|
1249
|
-
* </button>
|
|
1250
|
-
* );
|
|
1251
|
-
* }
|
|
1252
|
-
* ```
|
|
1213
|
+
* `download`/`reset` are stable callback identities across renders, so
|
|
1214
|
+
* they're safe to pass through memoized children without forcing re-renders.
|
|
1253
1215
|
*/
|
|
1254
1216
|
declare function useClipDownload(clip: Clip, options?: UseClipDownloadOptions): UseClipDownloadResult;
|
|
1255
1217
|
|
|
1256
1218
|
/**
|
|
1257
|
-
* Standalone download button for a captured {@link Clip}.
|
|
1258
|
-
*
|
|
1259
|
-
*
|
|
1260
|
-
*
|
|
1261
|
-
*
|
|
1262
|
-
*
|
|
1263
|
-
* menu items, post-download blob handling) call that hook directly.
|
|
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.
|
|
1264
1225
|
*
|
|
1265
|
-
* Styling is intentionally minimal
|
|
1266
|
-
*
|
|
1267
|
-
*
|
|
1268
|
-
*
|
|
1269
|
-
*
|
|
1270
|
-
* @example Default label, state-aware:
|
|
1271
|
-
* ```tsx
|
|
1272
|
-
* <ClipDownloadButton clip={clip} getJwt={() => jwt} />
|
|
1273
|
-
* ```
|
|
1274
|
-
*
|
|
1275
|
-
* @example Custom label that follows the state:
|
|
1276
|
-
* ```tsx
|
|
1277
|
-
* <ClipDownloadButton clip={clip} getJwt={() => jwt}>
|
|
1278
|
-
* {(s) => (s.kind === "downloading" ? `${s.fetched}/${s.total}` : "Save MP4")}
|
|
1279
|
-
* </ClipDownloadButton>
|
|
1280
|
-
* ```
|
|
1281
|
-
*
|
|
1282
|
-
* @example Static label:
|
|
1283
|
-
* ```tsx
|
|
1284
|
-
* <ClipDownloadButton clip={clip} getJwt={() => jwt}>Save</ClipDownloadButton>
|
|
1285
|
-
* ```
|
|
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.
|
|
1286
1230
|
*/
|
|
1287
1231
|
interface ClipDownloadButtonProps {
|
|
1288
1232
|
/** The clip to download. */
|
|
1289
1233
|
clip: Clip;
|
|
1290
|
-
/**
|
|
1291
|
-
*
|
|
1292
|
-
* (inherits the provider's resolver) and in local-dev mode. See
|
|
1293
|
-
* {@link ClipPlayerProps.getJwt}.
|
|
1294
|
-
*/
|
|
1234
|
+
/** Lazy JWT resolver. Optional inside a `ReactorProvider` (inherits the
|
|
1235
|
+
* provider's resolver) and in local-dev mode. See `ClipPlayerProps.getJwt`. */
|
|
1295
1236
|
getJwt?: () => string | Promise<string>;
|
|
1296
|
-
/** Filename for the saved MP4.
|
|
1237
|
+
/** Filename for the saved MP4. Default `"reactor-clip.mp4"`. */
|
|
1297
1238
|
filename?: string;
|
|
1298
1239
|
/**
|
|
1299
|
-
* Inner content of the button.
|
|
1240
|
+
* Inner content of the button. Three forms:
|
|
1300
1241
|
*
|
|
1301
|
-
* -
|
|
1302
|
-
*
|
|
1303
|
-
* -
|
|
1304
|
-
* -
|
|
1305
|
-
*
|
|
1306
|
-
*/
|
|
1307
|
-
children?:
|
|
1308
|
-
/** Forwarded to the underlying
|
|
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>`. */
|
|
1309
1250
|
className?: string;
|
|
1310
|
-
/** Forwarded to the underlying
|
|
1311
|
-
|
|
1312
|
-
|
|
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. */
|
|
1313
1256
|
disabled?: boolean;
|
|
1314
|
-
/**
|
|
1315
|
-
* Fires when the download completes with the assembled MP4 ``Blob``.
|
|
1316
|
-
*/
|
|
1257
|
+
/** Fires when the download completes with the assembled MP4 Blob. */
|
|
1317
1258
|
onSuccess?: (blob: Blob) => void;
|
|
1318
|
-
/**
|
|
1319
|
-
*
|
|
1320
|
-
*
|
|
1321
|
-
* plain error message otherwise.
|
|
1322
|
-
*/
|
|
1259
|
+
/** Fires when the download fails. Message mirrors the in-button state —
|
|
1260
|
+
* `"<CODE>: <reason>"` for `RecordingError`s, the plain error message
|
|
1261
|
+
* otherwise. */
|
|
1323
1262
|
onError?: (error: Error) => void;
|
|
1324
1263
|
}
|
|
1325
|
-
declare function ClipDownloadButton({ clip, getJwt, filename, children, className, style, disabled, onSuccess, onError, }: ClipDownloadButtonProps):
|
|
1326
|
-
|
|
1327
|
-
/**
|
|
1328
|
-
* Generic hook for accessing selected parts of the Reactor store.
|
|
1329
|
-
*
|
|
1330
|
-
* @param selector - A function that selects part of the store state.
|
|
1331
|
-
* @returns The selected slice from the store.
|
|
1332
|
-
*/
|
|
1333
|
-
declare function useReactor<T>(selector: (state: ReactorStore) => T): T;
|
|
1334
|
-
/**
|
|
1335
|
-
* Hook for receiving model application messages.
|
|
1336
|
-
*
|
|
1337
|
-
* Only fires for messages sent by the model via `get_ctx().send()`.
|
|
1338
|
-
* Internal platform-level messages (e.g. capabilities) are NOT delivered here.
|
|
1339
|
-
*
|
|
1340
|
-
* @param handler - Callback invoked with each application message payload.
|
|
1341
|
-
*/
|
|
1342
|
-
declare function useReactorMessage(handler: (message: any) => void): void;
|
|
1343
|
-
/**
|
|
1344
|
-
* Hook for receiving internal platform-level (runtime) messages.
|
|
1345
|
-
*
|
|
1346
|
-
* This is intended for advanced use cases that need access to the runtime
|
|
1347
|
-
* control layer, such as capabilities negotiation. Model application messages
|
|
1348
|
-
* sent via `get_ctx().send()` are NOT delivered through this hook — use
|
|
1349
|
-
* {@link useReactorMessage} for those.
|
|
1350
|
-
*
|
|
1351
|
-
* @param handler - Callback invoked with each runtime message payload.
|
|
1352
|
-
*/
|
|
1353
|
-
declare function useReactorInternalMessage(handler: (message: any) => void): void;
|
|
1354
|
-
/**
|
|
1355
|
-
* Hook that returns the current connection stats (RTT, etc.).
|
|
1356
|
-
* Updates every ~2s while connected. Returns undefined when disconnected.
|
|
1357
|
-
*/
|
|
1358
|
-
declare function useStats(): ConnectionStats | undefined;
|
|
1264
|
+
declare function ClipDownloadButton({ clip, getJwt, filename, children, className, style, disabled, onSuccess, onError, }: ClipDownloadButtonProps): react.JSX.Element;
|
|
1359
1265
|
|
|
1360
|
-
export {
|
|
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 };
|