@twilio/video-node-sdk 1.0.0-beta.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/CHANGELOG.md +409 -0
- package/FRAME_CONTRACT.md +204 -0
- package/LICENSE.md +3 -0
- package/LIFECYCLE.md +123 -0
- package/README.md +617 -0
- package/SECURITY-PRIVACY.md +25 -0
- package/dist/index.cjs +1822 -0
- package/dist/index.d.cts +1671 -0
- package/dist/index.d.mts +1671 -0
- package/dist/index.mjs +1740 -0
- package/package.json +111 -0
- package/prebuilds/darwin-x64/twilio_video_sdk_node-darwin-x64.node +0 -0
- package/prebuilds/linux-x64/twilio_video_sdk_node-linux-x64.node +0 -0
package/dist/index.d.mts
ADDED
|
@@ -0,0 +1,1671 @@
|
|
|
1
|
+
import { EventEmitter } from "node:events";
|
|
2
|
+
|
|
3
|
+
//#region lib/types.d.ts
|
|
4
|
+
declare namespace Track {
|
|
5
|
+
/** A Track SID (`MT...`), unique per published track. */
|
|
6
|
+
type SID = string;
|
|
7
|
+
}
|
|
8
|
+
declare namespace Participant {
|
|
9
|
+
/** A Participant SID (`PA...`), unique per participant in a room. */
|
|
10
|
+
type SID = string;
|
|
11
|
+
/** A Participant's application-defined identity string. */
|
|
12
|
+
type Identity = string;
|
|
13
|
+
}
|
|
14
|
+
/** A single plane (Y, U, or V) of a decoded I420 video frame. `stride` is the byte width of each row, which may exceed `width`. */
|
|
15
|
+
interface I420Plane {
|
|
16
|
+
/** The plane's samples, `stride * height` bytes long. */
|
|
17
|
+
data: Buffer;
|
|
18
|
+
/** Bytes per row, at least `width` and possibly padded for alignment. */
|
|
19
|
+
stride: number;
|
|
20
|
+
/** Plane width in samples. Half the frame width for the U and V planes. */
|
|
21
|
+
width: number;
|
|
22
|
+
/** Plane height in samples. Half the frame height for the U and V planes. */
|
|
23
|
+
height: number;
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* An I420 video frame to push into a {@link LocalVideoTrack} via its `write`
|
|
27
|
+
* method. Uses the same planar layout as the delivered {@link VideoFrame}, so a
|
|
28
|
+
* received frame can be re-published without reshaping it.
|
|
29
|
+
*
|
|
30
|
+
* Each plane's `data` must be at least `stride * height` bytes (`ceil(height / 2)`
|
|
31
|
+
* for the 2x-subsampled `u`/`v` planes). `width` and `height` must be positive
|
|
32
|
+
* and even; odd dimensions are rejected with a `RangeError`.
|
|
33
|
+
*
|
|
34
|
+
* Buffers are copied synchronously during `write()`, so the caller may reuse or
|
|
35
|
+
* free them as soon as it returns.
|
|
36
|
+
*/
|
|
37
|
+
interface VideoFrameInput {
|
|
38
|
+
/** Always `'I420'`. Optional; rejected if present and not `'I420'`. */
|
|
39
|
+
format?: 'I420';
|
|
40
|
+
/** Frame width in pixels. Must be positive and even. */
|
|
41
|
+
width: number;
|
|
42
|
+
/** Frame height in pixels. Must be positive and even. */
|
|
43
|
+
height: number;
|
|
44
|
+
/** Luminance plane. */
|
|
45
|
+
y: I420Plane;
|
|
46
|
+
/** Blue-difference chrominance plane, half resolution in each dimension. */
|
|
47
|
+
u: I420Plane;
|
|
48
|
+
/** Red-difference chrominance plane, half resolution in each dimension. */
|
|
49
|
+
v: I420Plane;
|
|
50
|
+
/**
|
|
51
|
+
* Presentation time in **microseconds**. Defaults to the current monotonic
|
|
52
|
+
* time when omitted, which is correct for an application-paced live source.
|
|
53
|
+
*/
|
|
54
|
+
timestamp?: number;
|
|
55
|
+
/** Clockwise rotation to apply on display, in degrees. Defaults to `0`. */
|
|
56
|
+
rotation?: 0 | 90 | 180 | 270;
|
|
57
|
+
}
|
|
58
|
+
/** A decoded I420 video frame delivered by {@link RemoteVideoTrack.frames}. `frameId` increments per frame. */
|
|
59
|
+
interface VideoFrame {
|
|
60
|
+
/** Always `'I420'`. The only pixel format this SDK delivers. */
|
|
61
|
+
format: 'I420';
|
|
62
|
+
/** Frame width in pixels. */
|
|
63
|
+
width: number;
|
|
64
|
+
/** Frame height in pixels. */
|
|
65
|
+
height: number;
|
|
66
|
+
/** Luminance plane. */
|
|
67
|
+
y: I420Plane;
|
|
68
|
+
/** Blue-difference chrominance plane, half resolution in each dimension. */
|
|
69
|
+
u: I420Plane;
|
|
70
|
+
/** Red-difference chrominance plane, half resolution in each dimension. */
|
|
71
|
+
v: I420Plane;
|
|
72
|
+
/** Local receive time, in **microseconds** on a monotonic clock. */
|
|
73
|
+
timestamp: number;
|
|
74
|
+
/** When the sender captured the frame, in microseconds, if the sender reported it. */
|
|
75
|
+
captureTimestamp?: number;
|
|
76
|
+
/** RTP timestamp from the packet that carried this frame, if available. */
|
|
77
|
+
rtpTimestamp?: number;
|
|
78
|
+
/** SDK-generated monotonic per-track counter, for gap and drop detection. */
|
|
79
|
+
frameId: number;
|
|
80
|
+
/** Clockwise rotation to apply on display, in degrees. */
|
|
81
|
+
rotation?: 0 | 90 | 180 | 270;
|
|
82
|
+
/**
|
|
83
|
+
* Optional deterministic-release hint. Not required for correctness - the
|
|
84
|
+
* frame is an owned copy and GC reclaims it - but calling it releases the
|
|
85
|
+
* plane buffers promptly. Idempotent; reading plane data after `close()`
|
|
86
|
+
* throws.
|
|
87
|
+
*/
|
|
88
|
+
close?(): void;
|
|
89
|
+
}
|
|
90
|
+
/** A PCM audio frame to push into a {@link LocalAudioTrack} via its `write` method. `pcm` is int16 mono samples at 48 kHz; `frames` is the sample count. */
|
|
91
|
+
interface AudioFrameInput {
|
|
92
|
+
/** Interleaved signed 16-bit little-endian samples, `frames * 2` bytes long. Copied synchronously by `write()`. */
|
|
93
|
+
pcm: Buffer;
|
|
94
|
+
/** Number of samples per channel in {@link AudioFrameInput.pcm}. */
|
|
95
|
+
frames: number;
|
|
96
|
+
/** Presentation time in **microseconds**. Defaults to "now" when omitted. */
|
|
97
|
+
timestamp?: number;
|
|
98
|
+
}
|
|
99
|
+
/** A PCM audio frame delivered by {@link RemoteAudioTrack.frames}. Always `PCM_S16LE`; `frameId` increments per frame. */
|
|
100
|
+
interface AudioFrame {
|
|
101
|
+
/** Always `'PCM_S16LE'`. The only sample format this SDK delivers. */
|
|
102
|
+
format: 'PCM_S16LE';
|
|
103
|
+
/** Samples per second. */
|
|
104
|
+
sampleRate: number;
|
|
105
|
+
/** Number of interleaved channels in {@link AudioFrame.pcm}. */
|
|
106
|
+
channels: number;
|
|
107
|
+
/** Number of samples per channel in {@link AudioFrame.pcm}. */
|
|
108
|
+
frames: number;
|
|
109
|
+
/** Interleaved signed 16-bit little-endian samples. */
|
|
110
|
+
pcm: Buffer;
|
|
111
|
+
/** Local receive time, in **microseconds** on a monotonic clock. */
|
|
112
|
+
timestamp: number;
|
|
113
|
+
/** When the sender captured the frame, in microseconds, if reported. */
|
|
114
|
+
captureTimestamp?: number;
|
|
115
|
+
/** RTP timestamp from the packet that carried this frame, if available. */
|
|
116
|
+
rtpTimestamp?: number;
|
|
117
|
+
/** SDK-generated monotonic per-track counter, for gap and drop detection. */
|
|
118
|
+
frameId: number;
|
|
119
|
+
/** Optional deterministic-release hint. Idempotent; reading `pcm` after `close()` throws. */
|
|
120
|
+
close?(): void;
|
|
121
|
+
}
|
|
122
|
+
/**
|
|
123
|
+
* How a bounded frame queue behaves when it is full.
|
|
124
|
+
*
|
|
125
|
+
* - `latest` keeps only the most recent frame; older frames are dropped. Right
|
|
126
|
+
* for live video, where a stale frame has no value.
|
|
127
|
+
* - `queue` buffers up to `maxQueue` frames and drops when full. Right for
|
|
128
|
+
* audio, where a small buffer smooths receiver jitter and gaps degrade
|
|
129
|
+
* transcription.
|
|
130
|
+
*/
|
|
131
|
+
type BackpressureMode = 'latest' | 'queue';
|
|
132
|
+
/** Per-call delivery policy for {@link RemoteVideoTrack.frames} / {@link RemoteAudioTrack.frames}. */
|
|
133
|
+
interface FrameDeliveryOptions {
|
|
134
|
+
/** Defaults to `latest` for video, `queue` for audio. */
|
|
135
|
+
mode?: BackpressureMode;
|
|
136
|
+
/** Queue bound. Defaults to 1 for `latest`, 10 for `queue`. Capped at 1024. */
|
|
137
|
+
maxQueue?: number;
|
|
138
|
+
/** Which frame to shed when full. Only meaningful for `mode: 'queue'`. Defaults to `oldest`. */
|
|
139
|
+
drop?: 'oldest' | 'newest';
|
|
140
|
+
}
|
|
141
|
+
/**
|
|
142
|
+
* Receive-side statistics for one remote track. `framesDropped` sums frames
|
|
143
|
+
* shed by the JS policy queue and frames shed at the native transfer boundary,
|
|
144
|
+
* so it is the total the consumer never saw.
|
|
145
|
+
*/
|
|
146
|
+
interface DeliveryStats {
|
|
147
|
+
/** Frames handed to the consumer. */
|
|
148
|
+
framesDelivered: number;
|
|
149
|
+
/** Cumulative frames dropped by backpressure, across both queues. */
|
|
150
|
+
framesDropped: number;
|
|
151
|
+
/** Current combined queue occupancy. */
|
|
152
|
+
queueDepth: number;
|
|
153
|
+
/** The configured bound for the JS policy queue. */
|
|
154
|
+
maxQueue: number;
|
|
155
|
+
/** Timestamp of the most recently delivered frame, in microseconds. */
|
|
156
|
+
lastTimestamp?: number;
|
|
157
|
+
}
|
|
158
|
+
/**
|
|
159
|
+
* Publish-side statistics for one local track.
|
|
160
|
+
*
|
|
161
|
+
* Video publish is synchronous - `write()` hands the frame straight to the
|
|
162
|
+
* encoder - so there is no SDK-side send queue and `sendQueueDepth`/`maxQueue`
|
|
163
|
+
* are `0`; a `framesDropped` there means libwebrtc's adapter rejected the
|
|
164
|
+
* frame. Audio publish does have a bounded queue, drained at 10 ms, so its
|
|
165
|
+
* depth and bound are real.
|
|
166
|
+
*
|
|
167
|
+
* For audio, `framesWritten`, `framesDropped`, `lastTimestamp` and
|
|
168
|
+
* `timestampRegressions` count this track's own `write()` calls, while
|
|
169
|
+
* `sendQueueDepth` and `maxQueue` describe the audio device shared by every
|
|
170
|
+
* local audio track in the process. With one local audio track - the normal
|
|
171
|
+
* case - the distinction does not arise.
|
|
172
|
+
*/
|
|
173
|
+
interface WriteStats {
|
|
174
|
+
/** Frames accepted. */
|
|
175
|
+
framesWritten: number;
|
|
176
|
+
/**
|
|
177
|
+
* Frames `write()` returned `false` for: for video, rejected by libwebrtc's
|
|
178
|
+
* adapter; for audio, they did not fit in the bounded publish queue.
|
|
179
|
+
*/
|
|
180
|
+
framesDropped: number;
|
|
181
|
+
/** Current buffered frames. Always `0` for video. */
|
|
182
|
+
sendQueueDepth: number;
|
|
183
|
+
/** Queue bound. Always `0` for video. For audio, the bound in 10 ms chunks. */
|
|
184
|
+
maxQueue: number;
|
|
185
|
+
/** Timestamp of the most recently accepted frame, in microseconds. */
|
|
186
|
+
lastTimestamp?: number;
|
|
187
|
+
/**
|
|
188
|
+
* Frames accepted whose `timestamp` did not advance past the previous one.
|
|
189
|
+
*
|
|
190
|
+
* Counted, not rejected: a producer may legitimately restart (looping a
|
|
191
|
+
* file), and silently reordering or discarding would hide a real problem.
|
|
192
|
+
* A rising count on a live source means the timestamps being supplied are
|
|
193
|
+
* wrong, which will show up downstream as jitter.
|
|
194
|
+
*/
|
|
195
|
+
timestampRegressions: number;
|
|
196
|
+
}
|
|
197
|
+
/** Raw-frame source configuration for a {@link LocalVideoTrack}. */
|
|
198
|
+
interface RawVideoSourceOptions {
|
|
199
|
+
/** Always `'raw'`. Reserved for future source kinds (encoded, file, stream). */
|
|
200
|
+
type: 'raw';
|
|
201
|
+
/** Always `'I420'`. */
|
|
202
|
+
format: 'I420';
|
|
203
|
+
/** Encoder width hint, in pixels. */
|
|
204
|
+
width: number;
|
|
205
|
+
/** Encoder height hint, in pixels. */
|
|
206
|
+
height: number;
|
|
207
|
+
/** Encoder frame-rate hint. */
|
|
208
|
+
fps?: number;
|
|
209
|
+
}
|
|
210
|
+
/** Raw-frame source configuration for a {@link LocalAudioTrack}. */
|
|
211
|
+
interface RawAudioSourceOptions {
|
|
212
|
+
/** Always `'raw'`. */
|
|
213
|
+
type: 'raw';
|
|
214
|
+
/** Always `'PCM_S16LE'`. */
|
|
215
|
+
format: 'PCM_S16LE';
|
|
216
|
+
/** Always 48000. WebRTC audio is 48 kHz internally. */
|
|
217
|
+
sampleRate: 48000;
|
|
218
|
+
/** Always 1. */
|
|
219
|
+
channels: 1;
|
|
220
|
+
/**
|
|
221
|
+
* Publish queue bound, in 10 ms chunks. Defaults to 50 (~500 ms).
|
|
222
|
+
*
|
|
223
|
+
* A {@link LocalAudioTrack.write} is accepted only if it fits whole within
|
|
224
|
+
* this bound; otherwise nothing is buffered and `write()` returns `false`.
|
|
225
|
+
* A single `write()` larger than the bound can never fit and is always
|
|
226
|
+
* rejected, so size this to the largest burst you intend to publish.
|
|
227
|
+
*
|
|
228
|
+
* @remarks
|
|
229
|
+
* The publish queue lives in the process-wide audio device shared by every
|
|
230
|
+
* local audio track, so this setting is **not per-track**: the most recent
|
|
231
|
+
* value passed to any `createLocalAudioTrack` applies to all of them.
|
|
232
|
+
*/
|
|
233
|
+
maxQueue?: number;
|
|
234
|
+
}
|
|
235
|
+
/** Options for {@link createLocalVideoTrack}. */
|
|
236
|
+
interface CreateLocalVideoTrackOptions {
|
|
237
|
+
/** Track name, unique across the local participant's published tracks. Defaults to a generated name such as `video-0`. */
|
|
238
|
+
name?: string;
|
|
239
|
+
/** Raw-frame source configuration, including encoder sizing hints. */
|
|
240
|
+
source?: RawVideoSourceOptions;
|
|
241
|
+
}
|
|
242
|
+
/** Options for {@link createLocalAudioTrack}. */
|
|
243
|
+
interface CreateLocalAudioTrackOptions {
|
|
244
|
+
/** Track name, unique across the local participant's published tracks. Defaults to a generated name such as `audio-0`. */
|
|
245
|
+
name?: string;
|
|
246
|
+
/** Raw-frame source configuration, including the publish queue bound. */
|
|
247
|
+
source?: RawAudioSourceOptions;
|
|
248
|
+
}
|
|
249
|
+
/** Options for {@link createLocalTracks}. Each key accepts a boolean to toggle the kind, or a per-track options object. */
|
|
250
|
+
interface CreateLocalTracksOptions {
|
|
251
|
+
/** Whether to create an audio track, or the options to create it with. Defaults to `true`. */
|
|
252
|
+
audio?: boolean | CreateLocalAudioTrackOptions;
|
|
253
|
+
/** Whether to create a video track, or the options to create it with. Defaults to `true`. */
|
|
254
|
+
video?: boolean | CreateLocalVideoTrackOptions;
|
|
255
|
+
}
|
|
256
|
+
/** Native media-factory options for creating a video track. */
|
|
257
|
+
interface VideoTrackOptions {
|
|
258
|
+
/** Track name, unique across the local participant's published tracks. */
|
|
259
|
+
name?: string;
|
|
260
|
+
}
|
|
261
|
+
/** Native media-factory options for creating an audio track. */
|
|
262
|
+
interface AudioTrackOptions {
|
|
263
|
+
/** Track name, unique across the local participant's published tracks. */
|
|
264
|
+
name?: string;
|
|
265
|
+
}
|
|
266
|
+
/** A custom ICE (STUN/TURN) server. `username`/`credential` are required for TURN. */
|
|
267
|
+
interface IceServer {
|
|
268
|
+
/** STUN or TURN server URLs, such as `turn:global.turn.twilio.com:3478`. */
|
|
269
|
+
urls: string[];
|
|
270
|
+
/** Username for a TURN server that requires authentication. */
|
|
271
|
+
username?: string;
|
|
272
|
+
/** Credential for a TURN server that requires authentication. */
|
|
273
|
+
credential?: string;
|
|
274
|
+
}
|
|
275
|
+
/** ICE transport configuration for {@link ConnectOptions}. `transportPolicy: 'relay'` forces all traffic through TURN. */
|
|
276
|
+
interface IceOptions {
|
|
277
|
+
/**
|
|
278
|
+
* Which candidates to gather. `'relay'` forces all media through TURN,
|
|
279
|
+
* which is useful for testing restrictive networks. Defaults to `'all'`.
|
|
280
|
+
*/
|
|
281
|
+
transportPolicy?: 'all' | 'relay';
|
|
282
|
+
/** Servers to use for candidate gathering, replacing the Twilio defaults. */
|
|
283
|
+
iceServers?: IceServer[];
|
|
284
|
+
}
|
|
285
|
+
/** Maximum send bitrates, in bits per second. Omitted fields leave the corresponding limit unchanged. */
|
|
286
|
+
interface EncodingParameters {
|
|
287
|
+
/** Ceiling on outgoing audio bitrate, in bits per second. */
|
|
288
|
+
maxAudioBitrate?: number;
|
|
289
|
+
/** Ceiling on outgoing video bitrate, in bits per second. */
|
|
290
|
+
maxVideoBitrate?: number;
|
|
291
|
+
}
|
|
292
|
+
/** Audio codecs that may be negotiated, in preference order. */
|
|
293
|
+
type AudioCodec = 'opus' | 'PCMU';
|
|
294
|
+
/** Video codec that may be negotiated. */
|
|
295
|
+
type VideoCodec = 'VP8';
|
|
296
|
+
/** Video encoding strategy. Currently only `auto` (server-driven) is supported. */
|
|
297
|
+
type VideoEncodingMode = 'auto';
|
|
298
|
+
/** Bandwidth-profile layout hint describing how remote video is arranged on screen. */
|
|
299
|
+
type BandwidthProfileMode = 'collaboration' | 'grid' | 'presentation';
|
|
300
|
+
/** How the SDK switches off remote video tracks under bandwidth pressure. */
|
|
301
|
+
type TrackSwitchOffMode = 'detected' | 'predicted' | 'disabled';
|
|
302
|
+
/** Whether track switch-off is driven automatically or controlled manually by the app. */
|
|
303
|
+
type ClientTrackSwitchOffControl = 'auto' | 'manual';
|
|
304
|
+
/** Whether render-dimension content preferences are derived automatically or set manually. */
|
|
305
|
+
type VideoContentPreferencesMode = 'auto' | 'manual';
|
|
306
|
+
/** Video portion of a {@link BandwidthProfileOptions}, controlling subscription bandwidth and switch-off behavior. */
|
|
307
|
+
interface VideoBandwidthProfileOptions {
|
|
308
|
+
/** How available bandwidth is divided between subscribed video tracks. */
|
|
309
|
+
mode?: BandwidthProfileMode;
|
|
310
|
+
/** Ceiling on the total incoming video bitrate, in bits per second. */
|
|
311
|
+
maxSubscriptionBitrate?: number;
|
|
312
|
+
/** When the server may stop delivering a subscribed video track to save bandwidth. */
|
|
313
|
+
trackSwitchOffMode?: TrackSwitchOffMode;
|
|
314
|
+
/** Whether the SDK or the application decides which tracks are switched off. */
|
|
315
|
+
clientTrackSwitchOffControl?: ClientTrackSwitchOffControl;
|
|
316
|
+
/**
|
|
317
|
+
* Whether the SDK or the application chooses render dimensions.
|
|
318
|
+
* {@link RemoteVideoTrack.setContentPreferences} takes effect only under `'manual'`.
|
|
319
|
+
*/
|
|
320
|
+
contentPreferencesMode?: VideoContentPreferencesMode;
|
|
321
|
+
}
|
|
322
|
+
/** Bandwidth-profile options passed to {@link connect} to manage subscriber-side bandwidth. */
|
|
323
|
+
interface BandwidthProfileOptions {
|
|
324
|
+
/** Bandwidth settings for subscribed video tracks. */
|
|
325
|
+
video?: VideoBandwidthProfileOptions;
|
|
326
|
+
}
|
|
327
|
+
/**
|
|
328
|
+
* Network-quality reporting verbosity. `0` disables, `1` enables minimal
|
|
329
|
+
* reporting.
|
|
330
|
+
*/
|
|
331
|
+
type NetworkQualityVerbosity = 0 | 1;
|
|
332
|
+
/** Per-side network-quality reporting verbosities, passed via {@link ConnectOptions.networkQuality}. */
|
|
333
|
+
interface NetworkQualityConfiguration {
|
|
334
|
+
/** Local participant verbosity. Only `1` is valid; to disable reporting, pass `networkQuality: false`. */
|
|
335
|
+
local?: 1;
|
|
336
|
+
/** Remote participant verbosity. `0` disables reporting for remote participants. */
|
|
337
|
+
remote?: NetworkQualityVerbosity;
|
|
338
|
+
}
|
|
339
|
+
/** Options for {@link connect}. All fields are optional; omitted feature toggles fall back to Room/server defaults. */
|
|
340
|
+
interface ConnectOptions {
|
|
341
|
+
/** Room name to connect to. When omitted, the Room SID is used as its name. */
|
|
342
|
+
name?: string;
|
|
343
|
+
/** Local video tracks to publish on join. */
|
|
344
|
+
videoTracks?: LocalVideoTrack[];
|
|
345
|
+
/** Local audio tracks to publish on join. */
|
|
346
|
+
audioTracks?: LocalAudioTrack[];
|
|
347
|
+
/** Local data tracks to publish on join. */
|
|
348
|
+
dataTracks?: LocalDataTrack[];
|
|
349
|
+
/** Enable Twilio Insights telemetry for this Room. */
|
|
350
|
+
enableInsights?: boolean;
|
|
351
|
+
/** Automatically subscribe to remote participants' tracks. When `false`, tracks must be subscribed to explicitly. */
|
|
352
|
+
enableAutomaticSubscription?: boolean;
|
|
353
|
+
/** Enable dominant-speaker detection, which powers {@link Room.dominantSpeaker} and the `dominantSpeakerChanged` event. */
|
|
354
|
+
enableDominantSpeaker?: boolean;
|
|
355
|
+
/**
|
|
356
|
+
* Enable network-quality reporting. Pass `true` for default verbosity
|
|
357
|
+
* (`local=1`, `remote=0`) or an object to set verbosities individually.
|
|
358
|
+
* Setting `false` (or omitting) disables reporting.
|
|
359
|
+
*/
|
|
360
|
+
networkQuality?: boolean | NetworkQualityConfiguration;
|
|
361
|
+
/** Preferred audio codecs in descending priority. */
|
|
362
|
+
preferredAudioCodecs?: AudioCodec[];
|
|
363
|
+
/** Preferred video codecs in descending priority. */
|
|
364
|
+
preferredVideoCodecs?: VideoCodec[];
|
|
365
|
+
/** How outgoing video encodings are selected. */
|
|
366
|
+
videoEncodingMode?: VideoEncodingMode;
|
|
367
|
+
/** Limits on incoming media, controlling how subscribed tracks share bandwidth. */
|
|
368
|
+
bandwidthProfile?: BandwidthProfileOptions;
|
|
369
|
+
/** Subscribe to live transcriptions, delivered via the Room's `transcription` event. */
|
|
370
|
+
receiveTranscriptions?: boolean;
|
|
371
|
+
/** Signaling region to connect through (e.g. `us1`, `gll` for lowest-latency). */
|
|
372
|
+
region?: string;
|
|
373
|
+
/** Overrides for ICE candidate gathering and transport policy. */
|
|
374
|
+
iceOptions?: IceOptions;
|
|
375
|
+
/** Initial send-bitrate limits; equivalent to calling {@link LocalParticipant.setEncodingParameters} after connect. */
|
|
376
|
+
encodingParameters?: EncodingParameters;
|
|
377
|
+
/**
|
|
378
|
+
* Milliseconds to wait for the Room to connect before giving up. On expiry
|
|
379
|
+
* the promise rejects with a `RoomConnectTimeoutError` and the partially
|
|
380
|
+
* built Room is disposed. Defaults to 30000. Pass `0` to wait indefinitely.
|
|
381
|
+
*/
|
|
382
|
+
connectionTimeout?: number;
|
|
383
|
+
}
|
|
384
|
+
/** The kind of media a track carries. */
|
|
385
|
+
type TrackKind = 'video' | 'audio' | 'data';
|
|
386
|
+
/** A local video track that the application feeds with I420 frames. Create via {@link createLocalVideoTrack}. */
|
|
387
|
+
interface LocalVideoTrack {
|
|
388
|
+
/** Track name, unique across the local participant's published tracks. */
|
|
389
|
+
readonly name: string;
|
|
390
|
+
/** Always `'video'`. */
|
|
391
|
+
readonly kind: 'video';
|
|
392
|
+
/** Whether the track is enabled; setting `false` publishes black/silent media without unpublishing. */
|
|
393
|
+
enabled: boolean;
|
|
394
|
+
/**
|
|
395
|
+
* Push an I420 frame into the track.
|
|
396
|
+
*
|
|
397
|
+
* Buffers are copied synchronously, so the caller may reuse or free them as
|
|
398
|
+
* soon as this returns.
|
|
399
|
+
*
|
|
400
|
+
* Throws `TypeError`/`RangeError` on invalid input (bad plane shape,
|
|
401
|
+
* non-finite integers, non-numeric timestamp, invalid rotation, plane buffer
|
|
402
|
+
* smaller than `stride * height`). Throws `Error` if the track is not bound
|
|
403
|
+
* to a source.
|
|
404
|
+
*
|
|
405
|
+
* Returns `true` when the frame was forwarded to the encoder sink. Returns
|
|
406
|
+
* `false` when the frame was dropped - most commonly because the encoder sink
|
|
407
|
+
* has not attached yet (frames written before `connect()` resolves), but also
|
|
408
|
+
* when libwebrtc's adapter rate-limits or rejects the frame's resolution.
|
|
409
|
+
* Every `false` is counted in {@link LocalVideoTrack.getWriteStats}.
|
|
410
|
+
*/
|
|
411
|
+
write(frame: VideoFrameInput): boolean;
|
|
412
|
+
/** Publish-side counters for this track. */
|
|
413
|
+
getWriteStats(): WriteStats;
|
|
414
|
+
}
|
|
415
|
+
/** A local audio track that the application feeds with PCM samples. Create via {@link createLocalAudioTrack}. */
|
|
416
|
+
interface LocalAudioTrack {
|
|
417
|
+
/** Track name, unique across the local participant's published tracks. */
|
|
418
|
+
readonly name: string;
|
|
419
|
+
/** Always `'audio'`. */
|
|
420
|
+
readonly kind: 'audio';
|
|
421
|
+
/** Whether the track is enabled; setting `false` publishes silence without unpublishing. */
|
|
422
|
+
enabled: boolean;
|
|
423
|
+
/**
|
|
424
|
+
* Push a PCM audio frame into the track.
|
|
425
|
+
*
|
|
426
|
+
* Format is fixed at **48 kHz mono S16LE** — `AudioFrameInput` exposes no
|
|
427
|
+
* sampleRate/channels fields, and `pcm` is interpreted as int16 mono samples.
|
|
428
|
+
*
|
|
429
|
+
* Samples are copied synchronously, so the caller may reuse or free `pcm` as
|
|
430
|
+
* soon as this returns.
|
|
431
|
+
*
|
|
432
|
+
* Throws `TypeError`/`RangeError` on invalid input (missing/non-Buffer `pcm`,
|
|
433
|
+
* non-integer `frames`, `pcm` shorter than `frames`, non-numeric timestamp).
|
|
434
|
+
* Throws `Error` if the track is not bound to a source.
|
|
435
|
+
*
|
|
436
|
+
* Returns `true` when the samples were enqueued, `false` when they did not
|
|
437
|
+
* fit in the bounded publish queue. A rejected write buffers nothing, so a
|
|
438
|
+
* write is never partially published; a single write larger than
|
|
439
|
+
* `source.maxQueue` can never fit. Every `false` is counted in
|
|
440
|
+
* {@link LocalAudioTrack.getWriteStats}.
|
|
441
|
+
*
|
|
442
|
+
* `timestamp` is observability-only on this path: audio publish is FIFO, so
|
|
443
|
+
* it feeds {@link WriteStats.lastTimestamp} and
|
|
444
|
+
* {@link WriteStats.timestampRegressions} without changing what is sent.
|
|
445
|
+
*/
|
|
446
|
+
write(frame: AudioFrameInput): boolean;
|
|
447
|
+
/** Publish-side counters for this track. */
|
|
448
|
+
getWriteStats(): WriteStats;
|
|
449
|
+
/** Drop any buffered, not-yet-sent audio samples. Use to discard stale audio before resuming. */
|
|
450
|
+
clearBuffer(): void;
|
|
451
|
+
}
|
|
452
|
+
/**
|
|
453
|
+
* Options for {@link createLocalDataTrack}. `maxPacketLifeTime` and
|
|
454
|
+
* `maxRetransmits` are mutually exclusive; setting either makes delivery
|
|
455
|
+
* unreliable. Defaults are reliable, ordered delivery.
|
|
456
|
+
*/
|
|
457
|
+
interface LocalDataTrackOptions {
|
|
458
|
+
/** Track name, unique across the local participant's published tracks. Defaults to a generated name such as `data-0`. */
|
|
459
|
+
name?: string;
|
|
460
|
+
/** Max time (ms) to attempt retransmitting a message before dropping it. Mutually exclusive with `maxRetransmits`. */
|
|
461
|
+
maxPacketLifeTime?: number | null;
|
|
462
|
+
/** Max number of retransmit attempts per message. Mutually exclusive with `maxPacketLifeTime`. */
|
|
463
|
+
maxRetransmits?: number | null;
|
|
464
|
+
/** Whether messages are delivered in order. Defaults to `true`. */
|
|
465
|
+
ordered?: boolean;
|
|
466
|
+
}
|
|
467
|
+
/** A local data track for sending string or binary messages. Create via {@link createLocalDataTrack}. */
|
|
468
|
+
interface LocalDataTrack {
|
|
469
|
+
/** Track name, unique across the local participant's published tracks. */
|
|
470
|
+
readonly name: string;
|
|
471
|
+
/** Always `'data'`. */
|
|
472
|
+
readonly kind: 'data';
|
|
473
|
+
/**
|
|
474
|
+
* The maximum period of time in milliseconds in which retransmissions will be
|
|
475
|
+
* sent, as passed to {@link createLocalDataTrack}, or `null` when unset.
|
|
476
|
+
*/
|
|
477
|
+
readonly maxPacketLifeTime: number | null;
|
|
478
|
+
/**
|
|
479
|
+
* The maximum number of times a message is retransmitted before being given
|
|
480
|
+
* up on, as passed to {@link createLocalDataTrack}, or `null` when unset.
|
|
481
|
+
*/
|
|
482
|
+
readonly maxRetransmits: number | null;
|
|
483
|
+
/** Whether delivery is reliable (neither retransmit limit set). */
|
|
484
|
+
readonly reliable: boolean;
|
|
485
|
+
/** Whether messages are delivered in the order they were sent. */
|
|
486
|
+
readonly ordered: boolean;
|
|
487
|
+
/**
|
|
488
|
+
* Send a message to all subscribed remote participants.
|
|
489
|
+
*
|
|
490
|
+
* The returned promise **always resolves** - never rejects - so a
|
|
491
|
+
* fire-and-forget `send()` cannot produce an unhandled rejection. Await it
|
|
492
|
+
* only when the outcome matters.
|
|
493
|
+
*
|
|
494
|
+
* @throws {RangeError} Synchronously, if the message exceeds 64 KB
|
|
495
|
+
* (`kMaxMessageSize`). Oversize messages are never transmitted.
|
|
496
|
+
* @throws {TypeError} Synchronously, if `data` is not a string or Buffer.
|
|
497
|
+
*/
|
|
498
|
+
send(data: string | Buffer): Promise<DataTrackSendResult>;
|
|
499
|
+
}
|
|
500
|
+
/**
|
|
501
|
+
* Outcome of a {@link LocalDataTrack.send}. `ok` is `false` when the message
|
|
502
|
+
* could not be sent or queued - most often because the send buffer had no room
|
|
503
|
+
* for it.
|
|
504
|
+
*/
|
|
505
|
+
interface DataTrackSendResult {
|
|
506
|
+
/** Whether the message was sent or queued for sending. */
|
|
507
|
+
ok: boolean;
|
|
508
|
+
/** Identifier for this send, unique within the track. */
|
|
509
|
+
messageId: number;
|
|
510
|
+
/** Why the send failed. Present only when `ok` is `false`. */
|
|
511
|
+
error?: string;
|
|
512
|
+
}
|
|
513
|
+
/** Desired render dimensions for a remote video track, used to right-size the publisher's encoding. */
|
|
514
|
+
interface VideoRenderDimensions {
|
|
515
|
+
/** Desired width in pixels. Must be a positive integer. */
|
|
516
|
+
width: number;
|
|
517
|
+
/** Desired height in pixels. Must be a positive integer. */
|
|
518
|
+
height: number;
|
|
519
|
+
}
|
|
520
|
+
/** Per-track content preferences for a {@link RemoteVideoTrack}, applied via `setContentPreferences`. */
|
|
521
|
+
interface VideoContentPreferences {
|
|
522
|
+
/** Dimensions the application intends to render this track at. */
|
|
523
|
+
renderDimensions?: VideoRenderDimensions;
|
|
524
|
+
}
|
|
525
|
+
/** Width/height in pixels reported in track stats. */
|
|
526
|
+
interface StatsVideoDimensions {
|
|
527
|
+
/** Frame width in pixels. */
|
|
528
|
+
width: number;
|
|
529
|
+
/** Frame height in pixels. */
|
|
530
|
+
height: number;
|
|
531
|
+
}
|
|
532
|
+
/** Stats common to every track. `timestamp` is in milliseconds since the Unix epoch; `trackSid` is the Track SID (`MT...`). */
|
|
533
|
+
interface TrackStats {
|
|
534
|
+
/** Name of the codec negotiated for this track, such as `opus` or `VP8`. */
|
|
535
|
+
codec: string;
|
|
536
|
+
/** Packets lost on this track over the connection's lifetime. */
|
|
537
|
+
packetsLost: number;
|
|
538
|
+
/** RTP synchronization source identifier for this track's stream. */
|
|
539
|
+
ssrc: string;
|
|
540
|
+
/** When this snapshot was taken, in milliseconds since the Unix epoch. */
|
|
541
|
+
timestamp: number;
|
|
542
|
+
/** SID of the track these stats describe. */
|
|
543
|
+
trackSid: Track.SID;
|
|
544
|
+
}
|
|
545
|
+
/** Send-side stats for a local track. `roundTripTime` is in seconds. */
|
|
546
|
+
interface LocalTrackStats extends TrackStats {
|
|
547
|
+
/** Bytes sent for this track over the connection's lifetime. */
|
|
548
|
+
bytesSent: number;
|
|
549
|
+
/** Packets sent for this track over the connection's lifetime. */
|
|
550
|
+
packetsSent: number;
|
|
551
|
+
/** Most recent round-trip time to the server, in seconds. */
|
|
552
|
+
roundTripTime: number;
|
|
553
|
+
}
|
|
554
|
+
/** Receive-side stats for a remote track. */
|
|
555
|
+
interface RemoteTrackStats extends TrackStats {
|
|
556
|
+
/** Bytes received for this track over the connection's lifetime. */
|
|
557
|
+
bytesReceived: number;
|
|
558
|
+
/** Packets received for this track over the connection's lifetime. */
|
|
559
|
+
packetsReceived: number;
|
|
560
|
+
}
|
|
561
|
+
/** Send-side audio stats. `audioLevel` is the linear input level; `jitter` is in milliseconds. */
|
|
562
|
+
interface LocalAudioTrackStats extends LocalTrackStats {
|
|
563
|
+
/** Linear input level of the audio being sent. */
|
|
564
|
+
audioLevel: number;
|
|
565
|
+
/** Variation in packet arrival timing, in milliseconds. */
|
|
566
|
+
jitter: number;
|
|
567
|
+
}
|
|
568
|
+
/** Send-side video stats. `captureDimensions`/`captureFrameRate` describe input, `dimensions`/`frameRate` describe what is encoded. */
|
|
569
|
+
interface LocalVideoTrackStats extends LocalTrackStats {
|
|
570
|
+
/** Dimensions of the frames written into the track, before encoding. */
|
|
571
|
+
captureDimensions: StatsVideoDimensions;
|
|
572
|
+
/** Dimensions of the frames actually encoded and sent. */
|
|
573
|
+
dimensions: StatsVideoDimensions;
|
|
574
|
+
/** Rate at which frames are written into the track, in frames per second. */
|
|
575
|
+
captureFrameRate: number;
|
|
576
|
+
/** Rate at which frames are encoded and sent, in frames per second. */
|
|
577
|
+
frameRate: number;
|
|
578
|
+
/** Frames encoded for this track over the connection's lifetime. */
|
|
579
|
+
framesEncoded: number;
|
|
580
|
+
}
|
|
581
|
+
/** Receive-side audio stats. `audioLevel` is the linear output level; `jitter` is in milliseconds. */
|
|
582
|
+
interface RemoteAudioTrackStats extends RemoteTrackStats {
|
|
583
|
+
/** Linear output level of the audio being received. */
|
|
584
|
+
audioLevel: number;
|
|
585
|
+
/** Variation in packet arrival timing, in milliseconds. */
|
|
586
|
+
jitter: number;
|
|
587
|
+
}
|
|
588
|
+
/** Receive-side video stats describing the decoded stream. */
|
|
589
|
+
interface RemoteVideoTrackStats extends RemoteTrackStats {
|
|
590
|
+
/** Dimensions of the decoded frames. */
|
|
591
|
+
dimensions: StatsVideoDimensions;
|
|
592
|
+
/** Rate at which frames are received and decoded, in frames per second. */
|
|
593
|
+
frameRate: number;
|
|
594
|
+
}
|
|
595
|
+
/** A stats snapshot for one peer connection, returned by {@link Room.getStats}. */
|
|
596
|
+
interface StatsReport {
|
|
597
|
+
/** Identifier of the peer connection these stats came from. */
|
|
598
|
+
peerConnectionId: string;
|
|
599
|
+
/** Send-side stats, one entry per published audio track. */
|
|
600
|
+
localAudioTrackStats: LocalAudioTrackStats[];
|
|
601
|
+
/** Send-side stats, one entry per published video track. */
|
|
602
|
+
localVideoTrackStats: LocalVideoTrackStats[];
|
|
603
|
+
/** Receive-side stats, one entry per subscribed audio track. */
|
|
604
|
+
remoteAudioTrackStats: RemoteAudioTrackStats[];
|
|
605
|
+
/** Receive-side stats, one entry per subscribed video track. */
|
|
606
|
+
remoteVideoTrackStats: RemoteVideoTrackStats[];
|
|
607
|
+
}
|
|
608
|
+
/** A {@link Room}'s connection state. */
|
|
609
|
+
type RoomState = 'connecting' | 'connected' | 'reconnecting' | 'disconnected';
|
|
610
|
+
/** Native SDK log verbosity, from `off` (silent) to `all` (most verbose). Set via {@link setLogLevel}. */
|
|
611
|
+
type LogLevel = 'off' | 'fatal' | 'error' | 'warning' | 'info' | 'debug' | 'trace' | 'all';
|
|
612
|
+
/** A participant's connection state within a {@link Room}. */
|
|
613
|
+
type ParticipantState = 'connected' | 'reconnecting' | 'disconnected';
|
|
614
|
+
//#endregion
|
|
615
|
+
//#region lib/errors.d.ts
|
|
616
|
+
/**
|
|
617
|
+
* Base class for all errors the SDK surfaces from Twilio. Carries a numeric
|
|
618
|
+
* Twilio error `code` alongside the standard `Error` message. Subclasses pin a
|
|
619
|
+
* specific code; an unmatched code is represented by a plain `TwilioError`.
|
|
620
|
+
*
|
|
621
|
+
* Errors raised by the SDK itself rather than by Twilio - a failed native
|
|
622
|
+
* binding load, an unsupported runtime, a connect timeout - carry
|
|
623
|
+
* {@link SDK_LOCAL_CODE} (`0`) and are identified by their class, since Twilio
|
|
624
|
+
* has not allocated codes for conditions the service never sees.
|
|
625
|
+
*/
|
|
626
|
+
declare class TwilioError extends Error {
|
|
627
|
+
/** The Twilio error code identifying the failure. See {@link ErrorCode} for known values. */
|
|
628
|
+
readonly code: number;
|
|
629
|
+
constructor(code: number, message?: string);
|
|
630
|
+
}
|
|
631
|
+
/**
|
|
632
|
+
* The `code` carried by errors the SDK raises locally. These conditions never
|
|
633
|
+
* reach Twilio, so no service code describes them; match on the error class
|
|
634
|
+
* instead.
|
|
635
|
+
*/
|
|
636
|
+
declare const SDK_LOCAL_CODE = 0;
|
|
637
|
+
/**
|
|
638
|
+
* Constructor shape shared by every generated {@link TwilioError} subclass:
|
|
639
|
+
* constructible with an optional message override, and carrying the Twilio
|
|
640
|
+
* numeric `code` as a static.
|
|
641
|
+
*/
|
|
642
|
+
interface TwilioErrorClass {
|
|
643
|
+
new (message?: string): TwilioError;
|
|
644
|
+
/** The Twilio numeric error code every instance of this class carries. */
|
|
645
|
+
readonly code: number;
|
|
646
|
+
}
|
|
647
|
+
declare const AccessTokenInvalidError_base: TwilioErrorClass;
|
|
648
|
+
/** The access token passed to {@link connect} is malformed or otherwise invalid. Code `20101`. */
|
|
649
|
+
declare class AccessTokenInvalidError extends AccessTokenInvalidError_base {}
|
|
650
|
+
declare const AccessTokenHeaderInvalidError_base: TwilioErrorClass;
|
|
651
|
+
/** The access token's header is invalid. Code `20102`. */
|
|
652
|
+
declare class AccessTokenHeaderInvalidError extends AccessTokenHeaderInvalidError_base {}
|
|
653
|
+
declare const AccessTokenIssuerInvalidError_base: TwilioErrorClass;
|
|
654
|
+
/** The access token's issuer or subject is invalid. Code `20103`. */
|
|
655
|
+
declare class AccessTokenIssuerInvalidError extends AccessTokenIssuerInvalidError_base {}
|
|
656
|
+
declare const AccessTokenExpiredError_base: TwilioErrorClass;
|
|
657
|
+
/** The access token has expired. Code `20104`. */
|
|
658
|
+
declare class AccessTokenExpiredError extends AccessTokenExpiredError_base {}
|
|
659
|
+
declare const AccessTokenNotYetValidError_base: TwilioErrorClass;
|
|
660
|
+
/** The access token is not yet valid. Code `20105`. */
|
|
661
|
+
declare class AccessTokenNotYetValidError extends AccessTokenNotYetValidError_base {}
|
|
662
|
+
declare const AccessTokenGrantsInvalidError_base: TwilioErrorClass;
|
|
663
|
+
/** The access token has no Video grant. Code `20106`. */
|
|
664
|
+
declare class AccessTokenGrantsInvalidError extends AccessTokenGrantsInvalidError_base {}
|
|
665
|
+
declare const AccessTokenSignatureInvalidError_base: TwilioErrorClass;
|
|
666
|
+
/** The access token signature is invalid. Code `20107`. */
|
|
667
|
+
declare class AccessTokenSignatureInvalidError extends AccessTokenSignatureInvalidError_base {}
|
|
668
|
+
declare const SignalingConnectionError_base: TwilioErrorClass;
|
|
669
|
+
/** The client cannot establish or maintain the signaling connection. Code `53000`. */
|
|
670
|
+
declare class SignalingConnectionError extends SignalingConnectionError_base {}
|
|
671
|
+
declare const SignalingConnectionDisconnectedError_base: TwilioErrorClass;
|
|
672
|
+
/** The signaling connection was disconnected. Code `53001`. */
|
|
673
|
+
declare class SignalingConnectionDisconnectedError extends SignalingConnectionDisconnectedError_base {}
|
|
674
|
+
declare const SignalingConnectionTimeoutError_base: TwilioErrorClass;
|
|
675
|
+
/** The signaling connection timed out. Code `53002`. */
|
|
676
|
+
declare class SignalingConnectionTimeoutError extends SignalingConnectionTimeoutError_base {}
|
|
677
|
+
declare const RoomConnectFailedError_base: TwilioErrorClass;
|
|
678
|
+
/** Connecting to the Room failed. Code `53104`. */
|
|
679
|
+
declare class RoomConnectFailedError extends RoomConnectFailedError_base {}
|
|
680
|
+
declare const RoomMaxParticipantsExceededError_base: TwilioErrorClass;
|
|
681
|
+
/** The Room already holds its maximum number of participants. Code `53105`. */
|
|
682
|
+
declare class RoomMaxParticipantsExceededError extends RoomMaxParticipantsExceededError_base {}
|
|
683
|
+
declare const RoomNotFoundError_base: TwilioErrorClass;
|
|
684
|
+
/** {@link connect} targeted a Room that does not exist and cannot be created. Code `53106`. */
|
|
685
|
+
declare class RoomNotFoundError extends RoomNotFoundError_base {}
|
|
686
|
+
declare const RoomCompletedError_base: TwilioErrorClass;
|
|
687
|
+
/** The Room has already completed. Code `53118`. */
|
|
688
|
+
declare class RoomCompletedError extends RoomCompletedError_base {}
|
|
689
|
+
declare const ParticipantMaxTracksExceededError_base: TwilioErrorClass;
|
|
690
|
+
/** Publishing would exceed the Room's maximum simultaneously published tracks. Code `53203`. */
|
|
691
|
+
declare class ParticipantMaxTracksExceededError extends ParticipantMaxTracksExceededError_base {}
|
|
692
|
+
declare const ParticipantDuplicateIdentityError_base: TwilioErrorClass;
|
|
693
|
+
/** Another participant is already connected with this identity. Code `53205`. */
|
|
694
|
+
declare class ParticipantDuplicateIdentityError extends ParticipantDuplicateIdentityError_base {}
|
|
695
|
+
declare const TrackInvalidError_base: TwilioErrorClass;
|
|
696
|
+
/** The track is invalid. Code `53300`. */
|
|
697
|
+
declare class TrackInvalidError extends TrackInvalidError_base {}
|
|
698
|
+
declare const TrackNameInvalidError_base: TwilioErrorClass;
|
|
699
|
+
/** The track name is invalid. Code `53301`. */
|
|
700
|
+
declare class TrackNameInvalidError extends TrackNameInvalidError_base {}
|
|
701
|
+
declare const TrackNameTooLongError_base: TwilioErrorClass;
|
|
702
|
+
/** The track name is too long. Code `53302`. */
|
|
703
|
+
declare class TrackNameTooLongError extends TrackNameTooLongError_base {}
|
|
704
|
+
declare const TrackNameCharsInvalidError_base: TwilioErrorClass;
|
|
705
|
+
/** The track name contains invalid characters. Code `53303`. */
|
|
706
|
+
declare class TrackNameCharsInvalidError extends TrackNameCharsInvalidError_base {}
|
|
707
|
+
declare const MediaClientLocalDescFailedError_base: TwilioErrorClass;
|
|
708
|
+
/** The client could not create a local media description. Code `53400`. */
|
|
709
|
+
declare class MediaClientLocalDescFailedError extends MediaClientLocalDescFailedError_base {}
|
|
710
|
+
declare const MediaServerLocalDescFailedError_base: TwilioErrorClass;
|
|
711
|
+
/** The server could not create a local media description. Code `53401`. */
|
|
712
|
+
declare class MediaServerLocalDescFailedError extends MediaServerLocalDescFailedError_base {}
|
|
713
|
+
declare const MediaClientRemoteDescFailedError_base: TwilioErrorClass;
|
|
714
|
+
/** The client could not apply a remote media description. Code `53402`. */
|
|
715
|
+
declare class MediaClientRemoteDescFailedError extends MediaClientRemoteDescFailedError_base {}
|
|
716
|
+
declare const MediaServerRemoteDescFailedError_base: TwilioErrorClass;
|
|
717
|
+
/** The server could not apply a remote media description. Code `53403`. */
|
|
718
|
+
declare class MediaServerRemoteDescFailedError extends MediaServerRemoteDescFailedError_base {}
|
|
719
|
+
declare const MediaNoSupportedCodecError_base: TwilioErrorClass;
|
|
720
|
+
/**
|
|
721
|
+
* No codec the peers both support could be negotiated. Surfaced through
|
|
722
|
+
* `trackSubscriptionFailed` when a remote track cannot be decoded - notably an
|
|
723
|
+
* H.264-only track, which this SDK does not decode. Code `53404`.
|
|
724
|
+
*/
|
|
725
|
+
declare class MediaNoSupportedCodecError extends MediaNoSupportedCodecError_base {}
|
|
726
|
+
declare const MediaConnectionError_base: TwilioErrorClass;
|
|
727
|
+
/** The media connection failed or media activity ceased. Code `53405`. */
|
|
728
|
+
declare class MediaConnectionError extends MediaConnectionError_base {}
|
|
729
|
+
/**
|
|
730
|
+
* The native addon could not be loaded for this platform.
|
|
731
|
+
*
|
|
732
|
+
* Hand-written rather than generated, because it is the only error that takes a
|
|
733
|
+
* `cause`. The static `code` is declared so it satisfies the same
|
|
734
|
+
* {@link TwilioErrorClass} contract as every generated subclass.
|
|
735
|
+
*/
|
|
736
|
+
declare class NativeBindingLoadError extends TwilioError {
|
|
737
|
+
/** The code every instance carries: {@link SDK_LOCAL_CODE}. */
|
|
738
|
+
static readonly code = 0;
|
|
739
|
+
constructor(message?: string, options?: {
|
|
740
|
+
cause?: unknown;
|
|
741
|
+
});
|
|
742
|
+
}
|
|
743
|
+
declare const UnsupportedPlatformError_base: TwilioErrorClass;
|
|
744
|
+
/** The current platform, architecture, or Node version is not supported. */
|
|
745
|
+
declare class UnsupportedPlatformError extends UnsupportedPlatformError_base {}
|
|
746
|
+
declare const RoomConnectTimeoutError_base: TwilioErrorClass;
|
|
747
|
+
/** {@link connect} did not settle within `connectionTimeout`. */
|
|
748
|
+
declare class RoomConnectTimeoutError extends RoomConnectTimeoutError_base {}
|
|
749
|
+
declare const DataTrackSendError_base: TwilioErrorClass;
|
|
750
|
+
/** A `LocalDataTrack.send()` message could not be delivered. */
|
|
751
|
+
declare class DataTrackSendError extends DataTrackSendError_base {}
|
|
752
|
+
/**
|
|
753
|
+
* Build a `TwilioError` (or matching subclass) from a numeric error code.
|
|
754
|
+
* For a registered code the subclass's canonical message is used and any
|
|
755
|
+
* supplied `message` is ignored. For an unregistered code the supplied
|
|
756
|
+
* `message` is preserved.
|
|
757
|
+
*/
|
|
758
|
+
declare function twilioErrorFromCode(code: number, message?: string): TwilioError;
|
|
759
|
+
//#endregion
|
|
760
|
+
//#region lib/typed_emitter.d.ts
|
|
761
|
+
/**
|
|
762
|
+
* A Node.js `EventEmitter` narrowed to a specific set of events.
|
|
763
|
+
*
|
|
764
|
+
* The listener methods accept only the event names declared in `Events`, and
|
|
765
|
+
* infer each listener's parameters from that event's signature, so a misspelled
|
|
766
|
+
* event name or a listener with the wrong arguments is a compile-time error.
|
|
767
|
+
* Every other `EventEmitter` method is inherited unchanged and stays untyped.
|
|
768
|
+
*
|
|
769
|
+
* This class is not instantiated directly. It is the base class for {@link Room},
|
|
770
|
+
* {@link LocalParticipant}, and {@link RemoteParticipant}.
|
|
771
|
+
*
|
|
772
|
+
* @typeParam Events - The event map this emitter accepts.
|
|
773
|
+
*/
|
|
774
|
+
declare class TypedEventEmitter<Events extends { [K in string]: (...args: any[]) => void }> extends EventEmitter {
|
|
775
|
+
/**
|
|
776
|
+
* Add a listener invoked every time `event` is emitted.
|
|
777
|
+
*
|
|
778
|
+
* @param event - The event to listen for.
|
|
779
|
+
* @param listener - Called with the event's arguments.
|
|
780
|
+
* @returns This emitter, for chaining.
|
|
781
|
+
*/
|
|
782
|
+
on<K extends keyof Events & string>(event: K, listener: Events[K]): this;
|
|
783
|
+
/**
|
|
784
|
+
* Add a listener invoked at most once, then removed.
|
|
785
|
+
*
|
|
786
|
+
* @param event - The event to listen for.
|
|
787
|
+
* @param listener - Called with the event's arguments.
|
|
788
|
+
* @returns This emitter, for chaining.
|
|
789
|
+
*/
|
|
790
|
+
once<K extends keyof Events & string>(event: K, listener: Events[K]): this;
|
|
791
|
+
/**
|
|
792
|
+
* Remove a previously added listener. The `listener` must be the same
|
|
793
|
+
* function reference that was registered.
|
|
794
|
+
*
|
|
795
|
+
* @param event - The event the listener was registered for.
|
|
796
|
+
* @param listener - The listener to remove.
|
|
797
|
+
* @returns This emitter, for chaining.
|
|
798
|
+
*/
|
|
799
|
+
off<K extends keyof Events & string>(event: K, listener: Events[K]): this;
|
|
800
|
+
/**
|
|
801
|
+
* Alias for {@link TypedEventEmitter.off}.
|
|
802
|
+
*
|
|
803
|
+
* @param event - The event the listener was registered for.
|
|
804
|
+
* @param listener - The listener to remove.
|
|
805
|
+
* @returns This emitter, for chaining.
|
|
806
|
+
*/
|
|
807
|
+
removeListener<K extends keyof Events & string>(event: K, listener: Events[K]): this;
|
|
808
|
+
/**
|
|
809
|
+
* Alias for {@link TypedEventEmitter.on}.
|
|
810
|
+
*
|
|
811
|
+
* @param event - The event to listen for.
|
|
812
|
+
* @param listener - Called with the event's arguments.
|
|
813
|
+
* @returns This emitter, for chaining.
|
|
814
|
+
*/
|
|
815
|
+
addListener<K extends keyof Events & string>(event: K, listener: Events[K]): this;
|
|
816
|
+
}
|
|
817
|
+
//#endregion
|
|
818
|
+
//#region lib/remote_track.d.ts
|
|
819
|
+
/** Events emitted by {@link RemoteVideoTrack} and {@link RemoteAudioTrack}. */
|
|
820
|
+
type RemoteMediaTrackEvents = {
|
|
821
|
+
/**
|
|
822
|
+
* Frames were dropped by the backpressure policy. Coalesced: `count` is the
|
|
823
|
+
* number dropped since the last event, `sinceLastUs` the microseconds elapsed
|
|
824
|
+
* since it (`0` for the first event).
|
|
825
|
+
*/
|
|
826
|
+
frameDropped: (count: number, sinceLastUs: number) => void;
|
|
827
|
+
};
|
|
828
|
+
/** Shared frames()/getStats() plumbing for the two media track kinds. */
|
|
829
|
+
declare abstract class RemoteMediaTrack<N extends NativeRemoteVideoTrack$1 | NativeRemoteAudioTrack$1, F extends {
|
|
830
|
+
timestamp: number;
|
|
831
|
+
}> extends TypedEventEmitter<RemoteMediaTrackEvents> {
|
|
832
|
+
private stream;
|
|
833
|
+
private lastStats;
|
|
834
|
+
protected abstract readonly frameKind: 'video' | 'audio';
|
|
835
|
+
protected abstract readonly planeKeys: readonly string[];
|
|
836
|
+
/** Track name, as set by the publisher. */
|
|
837
|
+
get name(): string;
|
|
838
|
+
/** This track's SID (`MT...`). */
|
|
839
|
+
get sid(): Track.SID;
|
|
840
|
+
/** Whether the publisher currently has the track enabled. */
|
|
841
|
+
get enabled(): boolean;
|
|
842
|
+
/**
|
|
843
|
+
* Receive decoded frames by async iteration. Awaiting each frame applies
|
|
844
|
+
* backpressure: while the consumer is busy, frames arriving behind it are
|
|
845
|
+
* subject to the drop policy in `options`.
|
|
846
|
+
*
|
|
847
|
+
* A track supports a single receiver. An application that needs to do several
|
|
848
|
+
* things with one stream fans out inside its own loop.
|
|
849
|
+
*
|
|
850
|
+
* The iterator completes when the track is unsubscribed or the Room
|
|
851
|
+
* disconnects, so a `for await` loop exits on its own.
|
|
852
|
+
*
|
|
853
|
+
* @throws {Error} If a receiver is already active on this track.
|
|
854
|
+
* @throws {TypeError} If `mode` or `drop` is invalid.
|
|
855
|
+
* @throws {RangeError} If `maxQueue` is out of range.
|
|
856
|
+
*/
|
|
857
|
+
frames(options?: FrameDeliveryOptions): AsyncIterableIterator<F>;
|
|
858
|
+
/**
|
|
859
|
+
* Per-track receive statistics. Counts both frames shed by the JS policy
|
|
860
|
+
* queue and frames shed at the native transfer boundary.
|
|
861
|
+
*/
|
|
862
|
+
getStats(): DeliveryStats;
|
|
863
|
+
}
|
|
864
|
+
/** A remote participant's video track. Read frames with {@link RemoteVideoTrack.frames}. */
|
|
865
|
+
declare class RemoteVideoTrack extends RemoteMediaTrack<NativeRemoteVideoTrack$1, VideoFrame> {
|
|
866
|
+
/** Discriminant for narrowing a {@link RemoteTrack} union. */
|
|
867
|
+
readonly kind: "video";
|
|
868
|
+
protected readonly frameKind: "video";
|
|
869
|
+
protected readonly planeKeys: readonly ["y", "u", "v"];
|
|
870
|
+
/**
|
|
871
|
+
* Whether the SDK has switched this track off under bandwidth pressure. While
|
|
872
|
+
* switched off, no frames are delivered.
|
|
873
|
+
*/
|
|
874
|
+
get isSwitchedOff(): boolean;
|
|
875
|
+
/** Tell the publisher what resolution this subscriber actually needs. */
|
|
876
|
+
setContentPreferences(preferences: VideoContentPreferences): void;
|
|
877
|
+
}
|
|
878
|
+
/** A remote participant's audio track. Read frames with {@link RemoteAudioTrack.frames}. */
|
|
879
|
+
declare class RemoteAudioTrack extends RemoteMediaTrack<NativeRemoteAudioTrack$1, AudioFrame> {
|
|
880
|
+
/** Discriminant for narrowing a {@link RemoteTrack} union. */
|
|
881
|
+
readonly kind: "audio";
|
|
882
|
+
protected readonly frameKind: "audio";
|
|
883
|
+
protected readonly planeKeys: readonly ["pcm"];
|
|
884
|
+
}
|
|
885
|
+
/** Events emitted by {@link RemoteDataTrack}. */
|
|
886
|
+
type RemoteDataTrackEvents = {
|
|
887
|
+
/**
|
|
888
|
+
* A message from the publisher. `string` for text, `Buffer` for binary.
|
|
889
|
+
*
|
|
890
|
+
* @param data - The message.
|
|
891
|
+
* @param track - The track it arrived on, so one listener can serve several.
|
|
892
|
+
*/
|
|
893
|
+
message: (data: string | Buffer, track: RemoteDataTrack) => void;
|
|
894
|
+
};
|
|
895
|
+
/**
|
|
896
|
+
* A remote participant's data track. Messages arrive as `message` events.
|
|
897
|
+
*/
|
|
898
|
+
declare class RemoteDataTrack extends TypedEventEmitter<RemoteDataTrackEvents> {
|
|
899
|
+
/** Discriminant for narrowing a {@link RemoteTrack} union. */
|
|
900
|
+
readonly kind: "data";
|
|
901
|
+
private attached;
|
|
902
|
+
/** Track name, as set by the publisher. */
|
|
903
|
+
get name(): string;
|
|
904
|
+
/** This track's SID (`MT...`). */
|
|
905
|
+
get sid(): Track.SID;
|
|
906
|
+
/**
|
|
907
|
+
* How long the publisher retries an undelivered message, in milliseconds, or
|
|
908
|
+
* `null` when unset. A publisher's `65535` reads back as `null`.
|
|
909
|
+
*/
|
|
910
|
+
get maxPacketLifeTime(): number | null;
|
|
911
|
+
/**
|
|
912
|
+
* How many times the publisher retransmits before giving up, or `null` when
|
|
913
|
+
* unset. A publisher's `65535` reads back as `null`.
|
|
914
|
+
*/
|
|
915
|
+
get maxRetransmits(): number | null;
|
|
916
|
+
/** Whether delivery is reliable: the publisher set neither retransmit limit. */
|
|
917
|
+
get reliable(): boolean;
|
|
918
|
+
/** Whether the publisher sends messages in order. */
|
|
919
|
+
get ordered(): boolean;
|
|
920
|
+
/**
|
|
921
|
+
* Wires the native message callback the first time someone listens, so an
|
|
922
|
+
* unobserved track does not pay for message delivery. Every listener-adding
|
|
923
|
+
* method routes through here; `on()` alone is not enough, because
|
|
924
|
+
* `addListener()` and the `prepend*` methods reach `EventEmitter` directly.
|
|
925
|
+
*/
|
|
926
|
+
private ensureMessageSink;
|
|
927
|
+
/**
|
|
928
|
+
* Add a listener invoked every time `event` is emitted.
|
|
929
|
+
*
|
|
930
|
+
* @param event - The event to listen for.
|
|
931
|
+
* @param listener - Called with the event's arguments.
|
|
932
|
+
* @returns This track, for chaining.
|
|
933
|
+
*/
|
|
934
|
+
on<K extends keyof RemoteDataTrackEvents & string>(event: K, listener: RemoteDataTrackEvents[K]): this;
|
|
935
|
+
/**
|
|
936
|
+
* Add a listener invoked at most once, then removed.
|
|
937
|
+
*
|
|
938
|
+
* @param event - The event to listen for.
|
|
939
|
+
* @param listener - Called with the event's arguments.
|
|
940
|
+
* @returns This track, for chaining.
|
|
941
|
+
*/
|
|
942
|
+
once<K extends keyof RemoteDataTrackEvents & string>(event: K, listener: RemoteDataTrackEvents[K]): this;
|
|
943
|
+
/**
|
|
944
|
+
* Alias for {@link RemoteDataTrack.on}.
|
|
945
|
+
*
|
|
946
|
+
* @param event - The event to listen for.
|
|
947
|
+
* @param listener - Called with the event's arguments.
|
|
948
|
+
* @returns This track, for chaining.
|
|
949
|
+
*/
|
|
950
|
+
addListener<K extends keyof RemoteDataTrackEvents & string>(event: K, listener: RemoteDataTrackEvents[K]): this;
|
|
951
|
+
/**
|
|
952
|
+
* Add a listener at the front of the listener array.
|
|
953
|
+
*
|
|
954
|
+
* @param event - The event to listen for.
|
|
955
|
+
* @param listener - Called with the event's arguments.
|
|
956
|
+
* @returns This track, for chaining.
|
|
957
|
+
*/
|
|
958
|
+
prependListener<K extends keyof RemoteDataTrackEvents & string>(event: K, listener: RemoteDataTrackEvents[K]): this;
|
|
959
|
+
/**
|
|
960
|
+
* Add a one-shot listener at the front of the listener array.
|
|
961
|
+
*
|
|
962
|
+
* @param event - The event to listen for.
|
|
963
|
+
* @param listener - Called with the event's arguments.
|
|
964
|
+
* @returns This track, for chaining.
|
|
965
|
+
*/
|
|
966
|
+
prependOnceListener<K extends keyof RemoteDataTrackEvents & string>(event: K, listener: RemoteDataTrackEvents[K]): this;
|
|
967
|
+
}
|
|
968
|
+
/** Any remote track kind. */
|
|
969
|
+
type RemoteTrack = RemoteVideoTrack | RemoteAudioTrack | RemoteDataTrack;
|
|
970
|
+
//#endregion
|
|
971
|
+
//#region lib/track_publication.d.ts
|
|
972
|
+
/**
|
|
973
|
+
* A snapshot of a published track's metadata. Base class for the local and
|
|
974
|
+
* remote publication types; instances are immutable point-in-time views rebuilt
|
|
975
|
+
* each time a participant's track collection is read.
|
|
976
|
+
*/
|
|
977
|
+
declare class TrackPublication {
|
|
978
|
+
/** The published track's SID (`MT...`), unique per track. */
|
|
979
|
+
readonly trackSid: Track.SID;
|
|
980
|
+
/** The track name set at creation; defaults to the track's ID when unnamed. */
|
|
981
|
+
readonly trackName: string;
|
|
982
|
+
/** Whether this publication is a `video`, `audio`, or `data` track. */
|
|
983
|
+
readonly kind: TrackKind;
|
|
984
|
+
/** Whether the track was enabled at the time this snapshot was taken. */
|
|
985
|
+
readonly isTrackEnabled: boolean;
|
|
986
|
+
}
|
|
987
|
+
/** Any kind of local track the SDK can publish. */
|
|
988
|
+
type LocalTrack = LocalVideoTrack | LocalAudioTrack | LocalDataTrack;
|
|
989
|
+
/** A publication of a {@link LocalTrack}, returned by {@link LocalParticipant}'s track collections. */
|
|
990
|
+
declare class LocalTrackPublication extends TrackPublication {
|
|
991
|
+
#private;
|
|
992
|
+
/** The published local track, or `null` if the SDK could not resolve the instance for this publication. */
|
|
993
|
+
track: LocalTrack | null;
|
|
994
|
+
/**
|
|
995
|
+
* Unpublish the underlying track from the room. Idempotent: a second call is
|
|
996
|
+
* a no-op. The publication's {@link track} remains readable after unpublishing.
|
|
997
|
+
*
|
|
998
|
+
* @returns This publication.
|
|
999
|
+
*/
|
|
1000
|
+
unpublish(): this;
|
|
1001
|
+
}
|
|
1002
|
+
/** A {@link LocalTrackPublication} narrowed to a video track. */
|
|
1003
|
+
declare class LocalVideoTrackPublication extends LocalTrackPublication {
|
|
1004
|
+
/** Always `'video'` for this publication type. */
|
|
1005
|
+
readonly kind: 'video';
|
|
1006
|
+
/** The published track, or `null` if the SDK could not resolve the instance. */
|
|
1007
|
+
track: LocalVideoTrack | null;
|
|
1008
|
+
}
|
|
1009
|
+
/** A {@link LocalTrackPublication} narrowed to an audio track. */
|
|
1010
|
+
declare class LocalAudioTrackPublication extends LocalTrackPublication {
|
|
1011
|
+
/** Always `'audio'` for this publication type. */
|
|
1012
|
+
readonly kind: 'audio';
|
|
1013
|
+
/** The published track, or `null` if the SDK could not resolve the instance. */
|
|
1014
|
+
track: LocalAudioTrack | null;
|
|
1015
|
+
}
|
|
1016
|
+
/** A {@link LocalTrackPublication} narrowed to a data track. */
|
|
1017
|
+
declare class LocalDataTrackPublication extends LocalTrackPublication {
|
|
1018
|
+
/** Always `'data'` for this publication type. */
|
|
1019
|
+
readonly kind: 'data';
|
|
1020
|
+
/** The published track, or `null` if the SDK could not resolve the instance. */
|
|
1021
|
+
track: LocalDataTrack | null;
|
|
1022
|
+
}
|
|
1023
|
+
/** A publication of a remote participant's track, returned by {@link RemoteParticipant}'s track collections. */
|
|
1024
|
+
declare class RemoteTrackPublication extends TrackPublication {
|
|
1025
|
+
/** Whether the local client is subscribed to this track. */
|
|
1026
|
+
readonly isSubscribed: boolean;
|
|
1027
|
+
/** The subscribed remote track, or `undefined` until subscription completes (or if unsubscribed). */
|
|
1028
|
+
readonly track: RemoteTrack | undefined;
|
|
1029
|
+
}
|
|
1030
|
+
/** A {@link RemoteTrackPublication} narrowed to a video track. */
|
|
1031
|
+
declare class RemoteVideoTrackPublication extends RemoteTrackPublication {
|
|
1032
|
+
/** Always `'video'` for this publication type. */
|
|
1033
|
+
readonly kind: 'video';
|
|
1034
|
+
/** The subscribed track, or `undefined` until subscription completes (or if unsubscribed). */
|
|
1035
|
+
readonly track: RemoteVideoTrack | undefined;
|
|
1036
|
+
}
|
|
1037
|
+
/** A {@link RemoteTrackPublication} narrowed to an audio track. */
|
|
1038
|
+
declare class RemoteAudioTrackPublication extends RemoteTrackPublication {
|
|
1039
|
+
/** Always `'audio'` for this publication type. */
|
|
1040
|
+
readonly kind: 'audio';
|
|
1041
|
+
/** The subscribed track, or `undefined` until subscription completes (or if unsubscribed). */
|
|
1042
|
+
readonly track: RemoteAudioTrack | undefined;
|
|
1043
|
+
}
|
|
1044
|
+
/** A {@link RemoteTrackPublication} narrowed to a data track. */
|
|
1045
|
+
declare class RemoteDataTrackPublication extends RemoteTrackPublication {
|
|
1046
|
+
/** Always `'data'` for this publication type. */
|
|
1047
|
+
readonly kind: 'data';
|
|
1048
|
+
/** The subscribed track, or `undefined` until subscription completes (or if unsubscribed). */
|
|
1049
|
+
readonly track: RemoteDataTrack | undefined;
|
|
1050
|
+
}
|
|
1051
|
+
//#endregion
|
|
1052
|
+
//#region lib/local_participant.d.ts
|
|
1053
|
+
/** Listener signatures for every event a {@link LocalParticipant} can emit. */
|
|
1054
|
+
type LocalParticipantEvents = {
|
|
1055
|
+
/**
|
|
1056
|
+
* A local track finished publishing and remote participants can now subscribe
|
|
1057
|
+
* to it.
|
|
1058
|
+
*
|
|
1059
|
+
* @param publication - The resulting publication, including the track's
|
|
1060
|
+
* server-assigned SID.
|
|
1061
|
+
*/
|
|
1062
|
+
trackPublished: (publication: LocalTrackPublication) => void;
|
|
1063
|
+
/**
|
|
1064
|
+
* Publishing a local track failed. The track is not published, and remote
|
|
1065
|
+
* participants never see it.
|
|
1066
|
+
*
|
|
1067
|
+
* @param error - Why publishing failed.
|
|
1068
|
+
* @param localTrack - The track that failed to publish, or `undefined` if the
|
|
1069
|
+
* failure could not be attributed to a track this participant still holds.
|
|
1070
|
+
* Resolved by name, since a failed publication has no SID. If the name was
|
|
1071
|
+
* re-published while the failure was in flight, this is the newer track.
|
|
1072
|
+
*/
|
|
1073
|
+
trackPublicationFailed: (error: TwilioError, localTrack?: LocalTrack) => void;
|
|
1074
|
+
/**
|
|
1075
|
+
* The local participant's network quality changed. Emitted only when the Room
|
|
1076
|
+
* was joined with network quality enabled for the local participant.
|
|
1077
|
+
*
|
|
1078
|
+
* @param level - Quality from 0 (worst) to 5 (best).
|
|
1079
|
+
*/
|
|
1080
|
+
networkQualityLevelChanged: (level: number) => void;
|
|
1081
|
+
};
|
|
1082
|
+
/**
|
|
1083
|
+
* The local client's participant in a {@link Room}, reachable via
|
|
1084
|
+
* {@link Room.localParticipant}. Use it to publish and unpublish local tracks.
|
|
1085
|
+
* Track names must be unique across this participant's published tracks.
|
|
1086
|
+
*/
|
|
1087
|
+
declare class LocalParticipant extends TypedEventEmitter<LocalParticipantEvents> {
|
|
1088
|
+
private _publishedTracks;
|
|
1089
|
+
private _unpublishFn;
|
|
1090
|
+
/** This participant's identity, taken from the `identity` grant in the access token. */
|
|
1091
|
+
get identity(): Participant.Identity;
|
|
1092
|
+
/** This participant's SID (`PA...`), assigned by Twilio on connect. */
|
|
1093
|
+
get sid(): Participant.SID;
|
|
1094
|
+
/** Current connection state of the local participant within the Room. */
|
|
1095
|
+
get state(): ParticipantState;
|
|
1096
|
+
/**
|
|
1097
|
+
* Network quality score from `0` (worst) to `5` (best), or `null` when
|
|
1098
|
+
* network-quality reporting was not enabled at {@link connect}. Updated by
|
|
1099
|
+
* the `networkQualityLevelChanged` event.
|
|
1100
|
+
*/
|
|
1101
|
+
get networkQualityLevel(): number | null;
|
|
1102
|
+
/** The geographic region (e.g. `us1`) of the signaling server this participant is connected to. */
|
|
1103
|
+
get signalingRegion(): string;
|
|
1104
|
+
/** Published video tracks, keyed by Track SID (`MT...`). A fresh map is built on each access. */
|
|
1105
|
+
get videoTracks(): Map<Track.SID, LocalVideoTrackPublication>;
|
|
1106
|
+
/** Published audio tracks, keyed by Track SID (`MT...`). A fresh map is built on each access. */
|
|
1107
|
+
get audioTracks(): Map<Track.SID, LocalAudioTrackPublication>;
|
|
1108
|
+
/** Published data tracks, keyed by Track SID (`MT...`). A fresh map is built on each access. */
|
|
1109
|
+
get dataTracks(): Map<Track.SID, LocalDataTrackPublication>;
|
|
1110
|
+
/** All published tracks (video, audio, and data) merged into one map, keyed by Track SID (`MT...`). */
|
|
1111
|
+
get tracks(): Map<Track.SID, LocalTrackPublication>;
|
|
1112
|
+
/**
|
|
1113
|
+
* Publish a local track to the Room. Returns synchronously; the actual
|
|
1114
|
+
* publication is confirmed later by the `trackPublished` event or, on
|
|
1115
|
+
* failure, `trackPublicationFailed`.
|
|
1116
|
+
*
|
|
1117
|
+
* @returns `true` if the native publish was accepted, `false` otherwise.
|
|
1118
|
+
* @throws {Error} If a different track instance is already published under the same name.
|
|
1119
|
+
*/
|
|
1120
|
+
publishTrack(track: LocalVideoTrack | LocalAudioTrack | LocalDataTrack): boolean;
|
|
1121
|
+
/**
|
|
1122
|
+
* Stop publishing a local track. The track object itself is not stopped and
|
|
1123
|
+
* may be re-published.
|
|
1124
|
+
*
|
|
1125
|
+
* @returns `true` if the track was published and is now unpublished, `false` otherwise.
|
|
1126
|
+
*/
|
|
1127
|
+
unpublishTrack(track: LocalVideoTrack | LocalAudioTrack | LocalDataTrack): boolean;
|
|
1128
|
+
/**
|
|
1129
|
+
* Guards the name-keying of `_publishedTracks`.
|
|
1130
|
+
* @throws {Error} If a different track instance is already published under `track.name`.
|
|
1131
|
+
*/
|
|
1132
|
+
private _assertUniqueName;
|
|
1133
|
+
/**
|
|
1134
|
+
* Builds the publication for `trackPublished`, resolving the track instance by
|
|
1135
|
+
* name when known and falling back to the payload so a publish is never dropped.
|
|
1136
|
+
*/
|
|
1137
|
+
private _resolvePublishedTrack;
|
|
1138
|
+
/**
|
|
1139
|
+
* Publish several tracks in order, returning one result per track. Stops and
|
|
1140
|
+
* rethrows if any track's name collides (see {@link LocalParticipant.publishTrack}),
|
|
1141
|
+
* so tracks before the failing one may already be published.
|
|
1142
|
+
*
|
|
1143
|
+
* @returns The per-track results, index-aligned with `tracks`.
|
|
1144
|
+
* @throws {Error} If a different track instance is already published under the same name.
|
|
1145
|
+
*/
|
|
1146
|
+
publishTracks(tracks: (LocalVideoTrack | LocalAudioTrack | LocalDataTrack)[]): boolean[];
|
|
1147
|
+
/**
|
|
1148
|
+
* Unpublish several tracks, returning one result per track.
|
|
1149
|
+
*
|
|
1150
|
+
* @returns The per-track results, index-aligned with `tracks`.
|
|
1151
|
+
*/
|
|
1152
|
+
unpublishTracks(tracks: (LocalVideoTrack | LocalAudioTrack | LocalDataTrack)[]): boolean[];
|
|
1153
|
+
/**
|
|
1154
|
+
* Set the maximum send bitrates for published audio and video. Applies to all
|
|
1155
|
+
* current and future published tracks; omitted fields keep their current limit.
|
|
1156
|
+
*/
|
|
1157
|
+
setEncodingParameters(params?: EncodingParameters): void;
|
|
1158
|
+
/** Release this participant's cached publications and event listeners. Called by {@link Room.dispose}. */
|
|
1159
|
+
dispose(): void;
|
|
1160
|
+
}
|
|
1161
|
+
//#endregion
|
|
1162
|
+
//#region lib/remote_participant.d.ts
|
|
1163
|
+
/**
|
|
1164
|
+
* Listener signatures for every event a {@link RemoteParticipant} can emit.
|
|
1165
|
+
*
|
|
1166
|
+
* The track events here are also re-emitted by the {@link Room}, with the
|
|
1167
|
+
* participant appended as the last argument. See {@link RoomEvents}.
|
|
1168
|
+
* `networkQualityLevelChanged` is not re-emitted, so it must be listened for on
|
|
1169
|
+
* each participant.
|
|
1170
|
+
*/
|
|
1171
|
+
type RemoteParticipantEvents = {
|
|
1172
|
+
/**
|
|
1173
|
+
* One of this participant's tracks was subscribed to and is now delivering
|
|
1174
|
+
* media or messages.
|
|
1175
|
+
*
|
|
1176
|
+
* A participant already publishing when {@link connect} resolved emits this
|
|
1177
|
+
* afterwards. Subscriptions that completed before the listener was attached
|
|
1178
|
+
* are not replayed; they appear in {@link RemoteParticipant.tracks} with
|
|
1179
|
+
* `isSubscribed` set to `true`.
|
|
1180
|
+
*
|
|
1181
|
+
* @param track - The subscribed track.
|
|
1182
|
+
* @param publication - The publication the track was subscribed from.
|
|
1183
|
+
*/
|
|
1184
|
+
trackSubscribed: (track: RemoteVideoTrack | RemoteAudioTrack | RemoteDataTrack, publication: RemoteTrackPublication) => void;
|
|
1185
|
+
/**
|
|
1186
|
+
* One of this participant's tracks was unsubscribed from and stops delivering
|
|
1187
|
+
* media. Its frame and message callbacks will not fire again.
|
|
1188
|
+
*
|
|
1189
|
+
* @param track - The unsubscribed track.
|
|
1190
|
+
* @param publication - The publication the track was unsubscribed from.
|
|
1191
|
+
*/
|
|
1192
|
+
trackUnsubscribed: (track: RemoteVideoTrack | RemoteAudioTrack | RemoteDataTrack, publication: RemoteTrackPublication) => void;
|
|
1193
|
+
/**
|
|
1194
|
+
* This participant published a track. Subscription follows separately, and
|
|
1195
|
+
* `trackSubscribed` reports it.
|
|
1196
|
+
*
|
|
1197
|
+
* @param publication - The new publication. Its `track` is set only once
|
|
1198
|
+
* subscription completes.
|
|
1199
|
+
*/
|
|
1200
|
+
trackPublished: (publication: RemoteTrackPublication) => void;
|
|
1201
|
+
/**
|
|
1202
|
+
* This participant unpublished a track.
|
|
1203
|
+
*
|
|
1204
|
+
* @param publication - The publication that was removed.
|
|
1205
|
+
*/
|
|
1206
|
+
trackUnpublished: (publication: RemoteTrackPublication) => void;
|
|
1207
|
+
/**
|
|
1208
|
+
* This participant unmuted a track they publish.
|
|
1209
|
+
*
|
|
1210
|
+
* @param publication - The publication whose track was enabled.
|
|
1211
|
+
*/
|
|
1212
|
+
trackEnabled: (publication: RemoteTrackPublication) => void;
|
|
1213
|
+
/**
|
|
1214
|
+
* This participant muted a track they publish. The track stays subscribed but
|
|
1215
|
+
* stops delivering media.
|
|
1216
|
+
*
|
|
1217
|
+
* @param publication - The publication whose track was disabled.
|
|
1218
|
+
*/
|
|
1219
|
+
trackDisabled: (publication: RemoteTrackPublication) => void;
|
|
1220
|
+
/**
|
|
1221
|
+
* Subscribing to one of this participant's tracks failed. The track stays
|
|
1222
|
+
* unsubscribed.
|
|
1223
|
+
*
|
|
1224
|
+
* @param error - Why the subscription failed.
|
|
1225
|
+
* @param publication - Identifies the track that could not be subscribed to.
|
|
1226
|
+
*/
|
|
1227
|
+
trackSubscriptionFailed: (error: TwilioError, publication: RemoteTrackPublication) => void;
|
|
1228
|
+
/**
|
|
1229
|
+
* The server stopped delivering a subscribed video track, typically to stay
|
|
1230
|
+
* within the Room's bandwidth profile. The track stays subscribed and its
|
|
1231
|
+
* `isSwitchedOff` reads `true`.
|
|
1232
|
+
*
|
|
1233
|
+
* @param track - The track that was switched off.
|
|
1234
|
+
*/
|
|
1235
|
+
videoTrackSwitchedOff: (track: RemoteVideoTrack) => void;
|
|
1236
|
+
/**
|
|
1237
|
+
* The server resumed delivering a video track that was switched off.
|
|
1238
|
+
*
|
|
1239
|
+
* @param track - The track that was switched on.
|
|
1240
|
+
*/
|
|
1241
|
+
videoTrackSwitchedOn: (track: RemoteVideoTrack) => void;
|
|
1242
|
+
/**
|
|
1243
|
+
* This participant's network quality changed. Emitted only when the Room was
|
|
1244
|
+
* joined with network quality enabled for remote participants.
|
|
1245
|
+
*
|
|
1246
|
+
* @param level - Quality from 0 (worst) to 5 (best).
|
|
1247
|
+
*/
|
|
1248
|
+
networkQualityLevelChanged: (level: number) => void;
|
|
1249
|
+
};
|
|
1250
|
+
/**
|
|
1251
|
+
* A remote participant in a {@link Room}, reachable via {@link Room.participants}.
|
|
1252
|
+
* Emits track subscription and state events listed in {@link RemoteParticipantEvents}.
|
|
1253
|
+
* Instances are managed by the Room; consumers do not construct or dispose them.
|
|
1254
|
+
*/
|
|
1255
|
+
declare class RemoteParticipant extends TypedEventEmitter<RemoteParticipantEvents> {
|
|
1256
|
+
/** This participant's identity, as set in the `identity` grant of their access token. */
|
|
1257
|
+
get identity(): Participant.Identity;
|
|
1258
|
+
/** This participant's SID (`PA...`), unique within the Room. */
|
|
1259
|
+
get sid(): Participant.SID;
|
|
1260
|
+
/** Current connection state of this participant within the Room. */
|
|
1261
|
+
get state(): ParticipantState;
|
|
1262
|
+
/**
|
|
1263
|
+
* Network quality score from `0` (worst) to `5` (best), or `null` when remote
|
|
1264
|
+
* network-quality reporting was not enabled at {@link connect}. Updated by the
|
|
1265
|
+
* `networkQualityLevelChanged` event.
|
|
1266
|
+
*/
|
|
1267
|
+
get networkQualityLevel(): number | null;
|
|
1268
|
+
/** This participant's published video tracks, keyed by Track SID (`MT...`). A fresh map is built on each access. */
|
|
1269
|
+
get videoTracks(): Map<Track.SID, RemoteVideoTrackPublication>;
|
|
1270
|
+
/** This participant's published audio tracks, keyed by Track SID (`MT...`). A fresh map is built on each access. */
|
|
1271
|
+
get audioTracks(): Map<Track.SID, RemoteAudioTrackPublication>;
|
|
1272
|
+
/** This participant's published data tracks, keyed by Track SID (`MT...`). A fresh map is built on each access. */
|
|
1273
|
+
get dataTracks(): Map<Track.SID, RemoteDataTrackPublication>;
|
|
1274
|
+
/** All of this participant's published tracks (video, audio, and data) merged into one map, keyed by Track SID (`MT...`). */
|
|
1275
|
+
get tracks(): Map<Track.SID, RemoteTrackPublication>;
|
|
1276
|
+
/** Release this participant's event listeners. Called by the {@link Room} on `participantDisconnected` and {@link Room.dispose}. */
|
|
1277
|
+
dispose(): void;
|
|
1278
|
+
}
|
|
1279
|
+
//#endregion
|
|
1280
|
+
//#region lib/room.d.ts
|
|
1281
|
+
/**
|
|
1282
|
+
* Listener signatures for every event a {@link Room} can emit.
|
|
1283
|
+
*
|
|
1284
|
+
* The track events at the end of this map are emitted by each
|
|
1285
|
+
* {@link RemoteParticipant} and re-emitted here, with the participant that
|
|
1286
|
+
* emitted them appended as the last argument. Listening here handles every
|
|
1287
|
+
* participant's tracks in one place, instead of attaching listeners to each
|
|
1288
|
+
* participant.
|
|
1289
|
+
*/
|
|
1290
|
+
type RoomEvents = {
|
|
1291
|
+
/**
|
|
1292
|
+
* The local participant left the Room, either by calling
|
|
1293
|
+
* {@link Room.disconnect} or because the server ended the session.
|
|
1294
|
+
*
|
|
1295
|
+
* @param room - The Room that was left.
|
|
1296
|
+
* @param error - Why the Room ended, or omitted after a local
|
|
1297
|
+
* {@link Room.disconnect}.
|
|
1298
|
+
*/
|
|
1299
|
+
disconnected: (room: Room, error?: TwilioError) => void;
|
|
1300
|
+
/**
|
|
1301
|
+
* The Room could not be joined. Terminal: no further events follow.
|
|
1302
|
+
*
|
|
1303
|
+
* Used internally by {@link connect}, which rejects with this error and
|
|
1304
|
+
* disposes the partially built Room. Application code never receives a Room
|
|
1305
|
+
* on which this can still fire, so failures are handled by catching the
|
|
1306
|
+
* rejection from {@link connect}.
|
|
1307
|
+
*
|
|
1308
|
+
* @param error - Why the connection attempt failed.
|
|
1309
|
+
*/
|
|
1310
|
+
connectFailure: (error: TwilioError) => void;
|
|
1311
|
+
/**
|
|
1312
|
+
* The signaling or media connection dropped and the SDK is trying to restore
|
|
1313
|
+
* it. Media is interrupted until `reconnected` fires.
|
|
1314
|
+
*
|
|
1315
|
+
* @param error - Why the connection dropped, when the SDK can attribute it.
|
|
1316
|
+
*/
|
|
1317
|
+
reconnecting: (error?: TwilioError) => void; /** The connection was restored after `reconnecting`. Media resumes. */
|
|
1318
|
+
reconnected: () => void;
|
|
1319
|
+
/**
|
|
1320
|
+
* A remote participant joined the Room.
|
|
1321
|
+
*
|
|
1322
|
+
* Not emitted for participants already in the Room when {@link connect}
|
|
1323
|
+
* resolved. Those are part of the Room's starting state: read them from
|
|
1324
|
+
* {@link Room.participants}.
|
|
1325
|
+
*
|
|
1326
|
+
* @param participant - The participant that joined.
|
|
1327
|
+
*/
|
|
1328
|
+
participantConnected: (participant: RemoteParticipant) => void;
|
|
1329
|
+
/**
|
|
1330
|
+
* A remote participant left the Room. Their tracks are unsubscribed first.
|
|
1331
|
+
*
|
|
1332
|
+
* @param participant - The participant that left.
|
|
1333
|
+
*/
|
|
1334
|
+
participantDisconnected: (participant: RemoteParticipant) => void;
|
|
1335
|
+
/**
|
|
1336
|
+
* A remote participant lost their connection and is trying to restore it.
|
|
1337
|
+
*
|
|
1338
|
+
* @param participant - The participant that is reconnecting.
|
|
1339
|
+
*/
|
|
1340
|
+
participantReconnecting: (participant: RemoteParticipant) => void;
|
|
1341
|
+
/**
|
|
1342
|
+
* A remote participant restored their connection.
|
|
1343
|
+
*
|
|
1344
|
+
* @param participant - The participant that reconnected.
|
|
1345
|
+
*/
|
|
1346
|
+
participantReconnected: (participant: RemoteParticipant) => void;
|
|
1347
|
+
/**
|
|
1348
|
+
* The loudest participant changed. Emitted only when the Room was joined with
|
|
1349
|
+
* `enableDominantSpeaker: true`.
|
|
1350
|
+
*
|
|
1351
|
+
* @param participant - The new dominant speaker, or `null` when no one is
|
|
1352
|
+
* speaking.
|
|
1353
|
+
*/
|
|
1354
|
+
dominantSpeakerChanged: (participant: RemoteParticipant | null) => void; /** Recording started for this Room. */
|
|
1355
|
+
recordingStarted: () => void; /** Recording stopped for this Room. */
|
|
1356
|
+
recordingStopped: () => void;
|
|
1357
|
+
/**
|
|
1358
|
+
* A transcription result arrived. Emitted only when the Room was joined with
|
|
1359
|
+
* `receiveTranscriptions: true`.
|
|
1360
|
+
*
|
|
1361
|
+
* @param transcriptionJson - The raw transcription payload, as a JSON string.
|
|
1362
|
+
*/
|
|
1363
|
+
transcription: (transcriptionJson: string) => void;
|
|
1364
|
+
/**
|
|
1365
|
+
* A remote track was subscribed to and is now delivering media or messages.
|
|
1366
|
+
*
|
|
1367
|
+
* A participant who was already publishing emits this after {@link connect}
|
|
1368
|
+
* resolves. Subscriptions that completed before the listener was attached are
|
|
1369
|
+
* not replayed; they appear in `participant.tracks` with `isSubscribed` set to
|
|
1370
|
+
* `true`.
|
|
1371
|
+
*
|
|
1372
|
+
* @param track - The subscribed track.
|
|
1373
|
+
* @param publication - The publication the track was subscribed from.
|
|
1374
|
+
* @param participant - The participant publishing it.
|
|
1375
|
+
*/
|
|
1376
|
+
trackSubscribed: (track: RemoteVideoTrack | RemoteAudioTrack | RemoteDataTrack, publication: RemoteTrackPublication, participant: RemoteParticipant) => void;
|
|
1377
|
+
/**
|
|
1378
|
+
* A remote track was unsubscribed from and stops delivering media. Its frame
|
|
1379
|
+
* and message callbacks will not fire again.
|
|
1380
|
+
*
|
|
1381
|
+
* @param track - The unsubscribed track.
|
|
1382
|
+
* @param publication - The publication the track was unsubscribed from.
|
|
1383
|
+
* @param participant - The participant that was publishing it.
|
|
1384
|
+
*/
|
|
1385
|
+
trackUnsubscribed: (track: RemoteVideoTrack | RemoteAudioTrack | RemoteDataTrack, publication: RemoteTrackPublication, participant: RemoteParticipant) => void;
|
|
1386
|
+
/**
|
|
1387
|
+
* Subscribing to a remote track failed. The track stays unsubscribed.
|
|
1388
|
+
*
|
|
1389
|
+
* @param error - Why the subscription failed.
|
|
1390
|
+
* @param publication - Identifies the track that could not be subscribed to.
|
|
1391
|
+
* @param participant - The participant publishing it.
|
|
1392
|
+
*/
|
|
1393
|
+
trackSubscriptionFailed: (error: TwilioError, publication: RemoteTrackPublication, participant: RemoteParticipant) => void;
|
|
1394
|
+
/**
|
|
1395
|
+
* A remote participant published a track. Subscription follows separately,
|
|
1396
|
+
* and `trackSubscribed` reports it.
|
|
1397
|
+
*
|
|
1398
|
+
* @param publication - The new publication. Its `track` is set only once
|
|
1399
|
+
* subscription completes.
|
|
1400
|
+
* @param participant - The participant that published it.
|
|
1401
|
+
*/
|
|
1402
|
+
trackPublished: (publication: RemoteTrackPublication, participant: RemoteParticipant) => void;
|
|
1403
|
+
/**
|
|
1404
|
+
* A remote participant unpublished a track.
|
|
1405
|
+
*
|
|
1406
|
+
* @param publication - The publication that was removed.
|
|
1407
|
+
* @param participant - The participant that unpublished it.
|
|
1408
|
+
*/
|
|
1409
|
+
trackUnpublished: (publication: RemoteTrackPublication, participant: RemoteParticipant) => void;
|
|
1410
|
+
/**
|
|
1411
|
+
* A remote participant unmuted a track they publish.
|
|
1412
|
+
*
|
|
1413
|
+
* @param publication - The publication whose track was enabled.
|
|
1414
|
+
* @param participant - The participant publishing it.
|
|
1415
|
+
*/
|
|
1416
|
+
trackEnabled: (publication: RemoteTrackPublication, participant: RemoteParticipant) => void;
|
|
1417
|
+
/**
|
|
1418
|
+
* A remote participant muted a track they publish. The track stays subscribed
|
|
1419
|
+
* but stops delivering media.
|
|
1420
|
+
*
|
|
1421
|
+
* @param publication - The publication whose track was disabled.
|
|
1422
|
+
* @param participant - The participant publishing it.
|
|
1423
|
+
*/
|
|
1424
|
+
trackDisabled: (publication: RemoteTrackPublication, participant: RemoteParticipant) => void;
|
|
1425
|
+
/**
|
|
1426
|
+
* The server stopped delivering a subscribed video track, typically to stay
|
|
1427
|
+
* within the Room's bandwidth profile. The track stays subscribed and its
|
|
1428
|
+
* `isSwitchedOff` reads `true`.
|
|
1429
|
+
*
|
|
1430
|
+
* @param track - The track that was switched off.
|
|
1431
|
+
* @param participant - The participant publishing it.
|
|
1432
|
+
*/
|
|
1433
|
+
videoTrackSwitchedOff: (track: RemoteVideoTrack, participant: RemoteParticipant) => void;
|
|
1434
|
+
/**
|
|
1435
|
+
* The server resumed delivering a video track that was switched off.
|
|
1436
|
+
*
|
|
1437
|
+
* @param track - The track that was switched on.
|
|
1438
|
+
* @param participant - The participant publishing it.
|
|
1439
|
+
*/
|
|
1440
|
+
videoTrackSwitchedOn: (track: RemoteVideoTrack, participant: RemoteParticipant) => void;
|
|
1441
|
+
};
|
|
1442
|
+
/**
|
|
1443
|
+
* A connected Group Room. Obtained by awaiting {@link connect}; the SDK never
|
|
1444
|
+
* constructs one directly for consumers. Emits the lifecycle, participant, and
|
|
1445
|
+
* track events listed in {@link RoomEvents}. Call {@link Room.dispose} when done
|
|
1446
|
+
* to release native resources and listeners.
|
|
1447
|
+
*/
|
|
1448
|
+
declare class Room extends TypedEventEmitter<RoomEvents> {
|
|
1449
|
+
private _localParticipant;
|
|
1450
|
+
private _remoteParticipantCache;
|
|
1451
|
+
private _seededTracks;
|
|
1452
|
+
/** The name passed to {@link connect}, or the Room SID if no name was given. */
|
|
1453
|
+
get name(): string;
|
|
1454
|
+
/** This Room's SID (`RM...`), unique per room instance. */
|
|
1455
|
+
get sid(): Room.SID;
|
|
1456
|
+
/** Current connection state. Transitions are mirrored by the corresponding lifecycle events. */
|
|
1457
|
+
get state(): RoomState;
|
|
1458
|
+
/** The geographic region (e.g. `us1`) where the Room's media is being processed. */
|
|
1459
|
+
get mediaRegion(): string;
|
|
1460
|
+
/** Whether the Room is currently being recorded. Tracks the `recordingStarted`/`recordingStopped` events. */
|
|
1461
|
+
get isRecording(): boolean;
|
|
1462
|
+
/**
|
|
1463
|
+
* The participant currently speaking loudest, or `null` when no one is
|
|
1464
|
+
* dominant. Only populated when the Room was connected with dominant-speaker
|
|
1465
|
+
* detection enabled. Updated by the `dominantSpeakerChanged` event.
|
|
1466
|
+
*/
|
|
1467
|
+
get dominantSpeaker(): RemoteParticipant | null;
|
|
1468
|
+
/** The {@link LocalParticipant} representing this client. Lazily created and cached on first access. */
|
|
1469
|
+
get localParticipant(): LocalParticipant;
|
|
1470
|
+
/**
|
|
1471
|
+
* The remote participants currently connected, keyed by Participant SID
|
|
1472
|
+
* (`PA...`). A fresh map is returned on each access; the {@link RemoteParticipant}
|
|
1473
|
+
* instances are cached, so repeated reads return the same objects.
|
|
1474
|
+
*/
|
|
1475
|
+
get participants(): Map<Participant.SID, RemoteParticipant>;
|
|
1476
|
+
/** @deprecated Use `participants` instead. */
|
|
1477
|
+
get remoteParticipants(): RemoteParticipant[];
|
|
1478
|
+
/**
|
|
1479
|
+
* Sample current media statistics, one {@link StatsReport} per underlying
|
|
1480
|
+
* peer connection.
|
|
1481
|
+
*
|
|
1482
|
+
* @returns A promise that rejects if the Room is already `disconnected`.
|
|
1483
|
+
*/
|
|
1484
|
+
getStats(): Promise<StatsReport[]>;
|
|
1485
|
+
/**
|
|
1486
|
+
* Leave the Room. Triggers the `disconnected` event once teardown completes;
|
|
1487
|
+
* does not release the JS-side wrapper — call {@link Room.dispose} for that.
|
|
1488
|
+
*/
|
|
1489
|
+
disconnect(): void;
|
|
1490
|
+
/**
|
|
1491
|
+
* Disconnect (if still connected) and release all native resources, cached
|
|
1492
|
+
* participant wrappers, and event listeners. The Room is unusable afterward.
|
|
1493
|
+
*/
|
|
1494
|
+
dispose(): void;
|
|
1495
|
+
/**
|
|
1496
|
+
* Wraps every participant already in the Room, so their track events are
|
|
1497
|
+
* observable from the moment the Room connects.
|
|
1498
|
+
*/
|
|
1499
|
+
private _seedExistingParticipants;
|
|
1500
|
+
private _bubbleTrackEvents;
|
|
1501
|
+
private _wrapRemoteParticipant;
|
|
1502
|
+
}
|
|
1503
|
+
declare namespace Room {
|
|
1504
|
+
/** A Room SID (`RM...`), unique per room instance. */
|
|
1505
|
+
type SID = string;
|
|
1506
|
+
}
|
|
1507
|
+
//#endregion
|
|
1508
|
+
//#region lib/frame_stream.d.ts
|
|
1509
|
+
/**
|
|
1510
|
+
* Upper bound on any configured queue depth. A misconfigured `maxQueue` must
|
|
1511
|
+
* not be able to exhaust memory: at 720p an I420 frame is ~1.3 MB, so 1024
|
|
1512
|
+
* frames is already well past any useful buffering.
|
|
1513
|
+
*
|
|
1514
|
+
* `_attachFrameSink` clamps to the same value natively
|
|
1515
|
+
* (`remote_video_track_wrap.cpp`, `remote_audio_track_wrap.cpp`). That clamp is
|
|
1516
|
+
* a backstop only - validation happens here - but the two have to move
|
|
1517
|
+
* together if this ever changes.
|
|
1518
|
+
*/
|
|
1519
|
+
declare const MAX_QUEUE_CEILING = 1024;
|
|
1520
|
+
//#endregion
|
|
1521
|
+
//#region lib/index.d.ts
|
|
1522
|
+
/**
|
|
1523
|
+
* Connect to a Twilio Group Room. The returned promise resolves once the Room
|
|
1524
|
+
* emits `connected`, and rejects with a {@link TwilioError} if it emits
|
|
1525
|
+
* `connectFailure` first (the partially-built Room is disposed on failure).
|
|
1526
|
+
*
|
|
1527
|
+
* @param token - A Twilio access token with a Video grant.
|
|
1528
|
+
* @param options - Room name, tracks to publish on join, and feature toggles.
|
|
1529
|
+
* @returns A promise resolving to the connected {@link Room}.
|
|
1530
|
+
* @throws {TypeError} (as a rejection) If `token` is not a non-empty string, or `options` is not an object.
|
|
1531
|
+
* @throws {RangeError} (as a rejection) If `options.networkQuality` verbosities are out of range.
|
|
1532
|
+
*
|
|
1533
|
+
* @example
|
|
1534
|
+
* const audioTrack = createLocalAudioTrack('mic');
|
|
1535
|
+
* const room = await connect(token, { name: 'my-room', audioTracks: [audioTrack] });
|
|
1536
|
+
*/
|
|
1537
|
+
declare function connect(token: string, options?: ConnectOptions): Promise<Room>;
|
|
1538
|
+
/**
|
|
1539
|
+
* Create a {@link LocalVideoTrack}. The track is a sink for caller-supplied
|
|
1540
|
+
* frames, delivered via {@link LocalVideoTrack.write}. Frames pushed before
|
|
1541
|
+
* the room emits `connected` are silently dropped.
|
|
1542
|
+
*
|
|
1543
|
+
* @param options - A track name, or a {@link CreateLocalVideoTrackOptions} object.
|
|
1544
|
+
* @returns The created {@link LocalVideoTrack}.
|
|
1545
|
+
* @throws {TypeError} If `options.name` is provided and is not a non-empty string.
|
|
1546
|
+
*
|
|
1547
|
+
* @example
|
|
1548
|
+
* // Create a track and connect with it.
|
|
1549
|
+
* const videoTrack = createLocalVideoTrack('camera');
|
|
1550
|
+
* const room = await connect(token, { videoTracks: [videoTrack] });
|
|
1551
|
+
*
|
|
1552
|
+
* @example
|
|
1553
|
+
* // Add video to an already-connected room.
|
|
1554
|
+
* const videoTrack = createLocalVideoTrack({ name: 'camera' });
|
|
1555
|
+
* room.localParticipant.publishTrack(videoTrack);
|
|
1556
|
+
*/
|
|
1557
|
+
declare function createLocalVideoTrack(options?: string | CreateLocalVideoTrackOptions): LocalVideoTrack;
|
|
1558
|
+
/**
|
|
1559
|
+
* Create a {@link LocalAudioTrack}. The track is a sink for caller-supplied
|
|
1560
|
+
* PCM samples, delivered via {@link LocalAudioTrack.write}. Audio input is
|
|
1561
|
+
* fixed at **48 kHz mono S16LE**.
|
|
1562
|
+
*
|
|
1563
|
+
* @param options - A track name, or a {@link CreateLocalAudioTrackOptions} object.
|
|
1564
|
+
* @returns The created {@link LocalAudioTrack}.
|
|
1565
|
+
* @throws {TypeError} If `options.name` is provided and is not a non-empty string.
|
|
1566
|
+
*
|
|
1567
|
+
* @example
|
|
1568
|
+
* // Create a track and connect with it.
|
|
1569
|
+
* const audioTrack = createLocalAudioTrack('microphone');
|
|
1570
|
+
* const room = await connect(token, { audioTracks: [audioTrack] });
|
|
1571
|
+
*
|
|
1572
|
+
* @example
|
|
1573
|
+
* // Add audio to an already-connected room.
|
|
1574
|
+
* const audioTrack = createLocalAudioTrack({ name: 'microphone' });
|
|
1575
|
+
* room.localParticipant.publishTrack(audioTrack);
|
|
1576
|
+
*/
|
|
1577
|
+
declare function createLocalAudioTrack(options?: string | CreateLocalAudioTrackOptions): LocalAudioTrack;
|
|
1578
|
+
/**
|
|
1579
|
+
* Create a {@link LocalDataTrack} for sending arbitrary string or binary
|
|
1580
|
+
* messages. The track defaults to reliable, ordered delivery; pass
|
|
1581
|
+
* `maxRetransmits` or `maxPacketLifeTime` to make it unreliable.
|
|
1582
|
+
*
|
|
1583
|
+
* @param options - A track name, or a {@link LocalDataTrackOptions} object.
|
|
1584
|
+
* @returns The created {@link LocalDataTrack}.
|
|
1585
|
+
* @throws {TypeError} If `options` is not a string or object, if `name` is not a non-empty string,
|
|
1586
|
+
* or if `ordered` is not a boolean.
|
|
1587
|
+
* @throws {Error} If both `maxRetransmits` and `maxPacketLifeTime` are set.
|
|
1588
|
+
* @throws {RangeError} If either `maxRetransmits` or `maxPacketLifeTime` is not an integer in [0, 65535].
|
|
1589
|
+
*
|
|
1590
|
+
* @example
|
|
1591
|
+
* // Reliable, ordered messaging.
|
|
1592
|
+
* const dataTrack = createLocalDataTrack('chat');
|
|
1593
|
+
* room.localParticipant.publishTrack(dataTrack);
|
|
1594
|
+
* dataTrack.send('hello');
|
|
1595
|
+
*
|
|
1596
|
+
* @example
|
|
1597
|
+
* // Unreliable, time-bounded delivery.
|
|
1598
|
+
* const dataTrack = createLocalDataTrack({ name: 'telemetry', maxPacketLifeTime: 1000 });
|
|
1599
|
+
*/
|
|
1600
|
+
declare function createLocalDataTrack(options?: LocalDataTrackOptions | string): LocalDataTrack;
|
|
1601
|
+
/**
|
|
1602
|
+
* Create {@link LocalAudioTrack}s and {@link LocalVideoTrack}s. By default,
|
|
1603
|
+
* returns both a {@link LocalAudioTrack} and a {@link LocalVideoTrack}. If
|
|
1604
|
+
* either `audio` or `video` is provided, the unspecified kind is omitted.
|
|
1605
|
+
* Each key accepts a boolean or a per-track options object.
|
|
1606
|
+
*
|
|
1607
|
+
* @param options - Track selection and per-track configuration.
|
|
1608
|
+
* @returns A promise that resolves with the created local tracks, or rejects
|
|
1609
|
+
* with a `TypeError` if a per-track option fails validation.
|
|
1610
|
+
*
|
|
1611
|
+
* @example
|
|
1612
|
+
* // Create both audio and video tracks.
|
|
1613
|
+
* const tracks = await createLocalTracks();
|
|
1614
|
+
*
|
|
1615
|
+
* @example
|
|
1616
|
+
* // Create only an audio track and connect with it.
|
|
1617
|
+
* const tracks = await createLocalTracks({ audio: true });
|
|
1618
|
+
* const room = await connect(token, { audioTracks: tracks });
|
|
1619
|
+
*
|
|
1620
|
+
* @example
|
|
1621
|
+
* // Create both with custom names.
|
|
1622
|
+
* const tracks = await createLocalTracks({
|
|
1623
|
+
* audio: { name: 'microphone' },
|
|
1624
|
+
* video: { name: 'camera' },
|
|
1625
|
+
* });
|
|
1626
|
+
*/
|
|
1627
|
+
declare function createLocalTracks(options?: CreateLocalTracksOptions): Promise<(LocalAudioTrack | LocalVideoTrack)[]>;
|
|
1628
|
+
/**
|
|
1629
|
+
* Known Twilio error codes, mapping a descriptive name to its numeric code.
|
|
1630
|
+
* Match against {@link TwilioError.code} to identify a failure without
|
|
1631
|
+
* depending on the error message.
|
|
1632
|
+
*/
|
|
1633
|
+
declare const ErrorCode: Readonly<{
|
|
1634
|
+
/** The Access Token provided to the Twilio API was invalid. */readonly ACCESS_TOKEN_INVALID: 20101; /** The Access Token's header is invalid. */
|
|
1635
|
+
readonly ACCESS_TOKEN_HEADER_INVALID: 20102; /** The Access Token's issuer or subject is invalid. */
|
|
1636
|
+
readonly ACCESS_TOKEN_ISSUER_INVALID: 20103; /** The Access Token has expired, or its expiration date is invalid. */
|
|
1637
|
+
readonly ACCESS_TOKEN_EXPIRED: 20104; /** The Access Token's not-before time is in the future. */
|
|
1638
|
+
readonly ACCESS_TOKEN_NOT_YET_VALID: 20105; /** The Access Token's grants were invalid, unparseable, or did not permit the requested operation. */
|
|
1639
|
+
readonly ACCESS_TOKEN_GRANT_INVALID: 20106; /** The Access Token's signature did not verify. */
|
|
1640
|
+
readonly ACCESS_TOKEN_SIGNATURE_INVALID: 20107; /** A signaling connection error not covered by a more specific code. */
|
|
1641
|
+
readonly SIGNALING_CONNECTION_ERROR: 53000; /** The signaling connection was unexpectedly disconnected. */
|
|
1642
|
+
readonly SIGNALING_CONNECTION_DISCONNECTED: 53001; /** The signaling connection timed out. */
|
|
1643
|
+
readonly SIGNALING_CONNECTION_TIMEOUT: 53002; /** The operation was attempted on a Room that does not exist. */
|
|
1644
|
+
readonly ROOM_NOT_FOUND: 53106; /** The Room could not be connected to, for a reason not covered by a more specific code. */
|
|
1645
|
+
readonly ROOM_CONNECT_FAILED: 53104; /** The Room is already at its participant limit. */
|
|
1646
|
+
readonly ROOM_MAX_PARTICIPANTS_EXCEEDED: 53105; /** The Room has been completed, and the requested operation cannot be performed on it. */
|
|
1647
|
+
readonly ROOM_COMPLETED: 53118; /** The participant has reached its maximum number of published tracks. */
|
|
1648
|
+
readonly PARTICIPANT_MAX_TRACKS_EXCEEDED: 53203; /** The participant was disconnected because another joined with the same identity. */
|
|
1649
|
+
readonly PARTICIPANT_DUPLICATE_IDENTITY: 53205; /** The track is invalid, for a reason not covered by a more specific code. */
|
|
1650
|
+
readonly TRACK_INVALID: 53300; /** The track name is invalid, for a reason not covered by a more specific code. */
|
|
1651
|
+
readonly TRACK_NAME_INVALID: 53301; /** The track name exceeds the maximum length. */
|
|
1652
|
+
readonly TRACK_NAME_TOO_LONG: 53302; /** The track's name contains characters that are not allowed. */
|
|
1653
|
+
readonly TRACK_NAME_CHARS_INVALID: 53303; /** The client could not create or apply its local media description. */
|
|
1654
|
+
readonly MEDIA_CLIENT_LOCAL_DESC_FAILED: 53400; /** The server could not create or apply its local media description. */
|
|
1655
|
+
readonly MEDIA_SERVER_LOCAL_DESC_FAILED: 53401; /** The client could not apply the remote media description it received. */
|
|
1656
|
+
readonly MEDIA_CLIENT_REMOTE_DESC_FAILED: 53402; /** The server could not apply the client's media description. */
|
|
1657
|
+
readonly MEDIA_SERVER_REMOTE_DESC_FAILED: 53403; /** The client and server share no supported codec. */
|
|
1658
|
+
readonly MEDIA_NO_SUPPORTED_CODEC: 53404; /** The media connection failed, or media activity ceased. */
|
|
1659
|
+
readonly MEDIA_CONNECTION_ERROR: 53405;
|
|
1660
|
+
}>;
|
|
1661
|
+
/** The version of the underlying native rtc-cpp engine (distinct from this package's version). */
|
|
1662
|
+
declare function getVersion(): string;
|
|
1663
|
+
/**
|
|
1664
|
+
* Set the verbosity of the native SDK's logging. Process-global and effective
|
|
1665
|
+
* immediately for all current and future Rooms.
|
|
1666
|
+
*
|
|
1667
|
+
* @param level - A {@link LogLevel} name or its equivalent native numeric level.
|
|
1668
|
+
*/
|
|
1669
|
+
declare function setLogLevel(level: LogLevel | number): void;
|
|
1670
|
+
//#endregion
|
|
1671
|
+
export { AccessTokenExpiredError, AccessTokenGrantsInvalidError, AccessTokenHeaderInvalidError, AccessTokenInvalidError, AccessTokenIssuerInvalidError, AccessTokenNotYetValidError, AccessTokenSignatureInvalidError, type AudioCodec, type AudioFrame, type AudioFrameInput, type AudioTrackOptions, type BackpressureMode, type BandwidthProfileMode, type BandwidthProfileOptions, type ClientTrackSwitchOffControl, type ConnectOptions, type CreateLocalAudioTrackOptions, type CreateLocalTracksOptions, type CreateLocalVideoTrackOptions, DataTrackSendError, type DataTrackSendResult, type DeliveryStats, type EncodingParameters, ErrorCode, type FrameDeliveryOptions, type I420Plane, type IceOptions, type IceServer, type LocalAudioTrack, LocalAudioTrackPublication, type LocalAudioTrackStats, type LocalDataTrack, type LocalDataTrackOptions, LocalDataTrackPublication, LocalParticipant, type LocalParticipantEvents, type LocalTrack, LocalTrackPublication, type LocalTrackStats, type LocalVideoTrack, LocalVideoTrackPublication, type LocalVideoTrackStats, type LogLevel, MAX_QUEUE_CEILING, MediaClientLocalDescFailedError, MediaClientRemoteDescFailedError, MediaConnectionError, MediaNoSupportedCodecError, MediaServerLocalDescFailedError, MediaServerRemoteDescFailedError, NativeBindingLoadError, type NetworkQualityConfiguration, type NetworkQualityVerbosity, type Participant, ParticipantDuplicateIdentityError, ParticipantMaxTracksExceededError, type ParticipantState, type RawAudioSourceOptions, type RawVideoSourceOptions, RemoteAudioTrack, RemoteAudioTrackPublication, type RemoteAudioTrackStats, RemoteDataTrack, type RemoteDataTrackEvents, RemoteDataTrackPublication, type RemoteMediaTrackEvents, RemoteParticipant, type RemoteParticipantEvents, type RemoteTrack, RemoteTrackPublication, type RemoteTrackStats, RemoteVideoTrack, RemoteVideoTrackPublication, type RemoteVideoTrackStats, Room, RoomCompletedError, RoomConnectFailedError, RoomConnectTimeoutError, type RoomEvents, RoomMaxParticipantsExceededError, RoomNotFoundError, type RoomState, SDK_LOCAL_CODE, SignalingConnectionDisconnectedError, SignalingConnectionError, SignalingConnectionTimeoutError, type StatsReport, type StatsVideoDimensions, type Track, TrackInvalidError, type TrackKind, TrackNameCharsInvalidError, TrackNameInvalidError, TrackNameTooLongError, TrackPublication, type TrackStats, type TrackSwitchOffMode, TwilioError, type TwilioErrorClass, TypedEventEmitter, UnsupportedPlatformError, type VideoBandwidthProfileOptions, type VideoCodec, type VideoContentPreferences, type VideoContentPreferencesMode, type VideoEncodingMode, type VideoFrame, type VideoFrameInput, type VideoRenderDimensions, type VideoTrackOptions, type WriteStats, connect, createLocalAudioTrack, createLocalDataTrack, createLocalTracks, createLocalVideoTrack, getVersion, setLogLevel, twilioErrorFromCode };
|