@twilio/video-node-sdk 1.0.0-rc.3 → 1.0.0-rc.4
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 +99 -13
- package/FRAME_CONTRACT.md +20 -12
- package/LICENSE.md +226 -2
- package/LIFECYCLE.md +1 -1
- package/README.md +71 -530
- package/SECURITY-PRIVACY.md +1 -1
- package/THIRD_PARTY_NOTICES +2667 -0
- package/dist/index.cjs +212 -41
- package/dist/index.d.cts +151 -29
- package/dist/index.d.mts +151 -29
- package/dist/index.mjs +210 -42
- package/package.json +16 -6
- package/prebuilds/{darwin-x64/twilio_video_sdk_node-darwin-x64.node → darwin-arm64/twilio_video_sdk_node-darwin-arm64.node} +0 -0
- package/prebuilds/linux-x64/twilio_video_sdk_node-linux-x64.node +0 -0
package/dist/index.cjs
CHANGED
|
@@ -23,11 +23,12 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
|
|
|
23
23
|
//#endregion
|
|
24
24
|
let node_fs = require("node:fs");
|
|
25
25
|
node_fs = __toESM(node_fs);
|
|
26
|
+
let node_events = require("node:events");
|
|
26
27
|
let node_path = require("node:path");
|
|
27
28
|
node_path = __toESM(node_path);
|
|
28
29
|
let node_module = require("node:module");
|
|
29
30
|
let node_url = require("node:url");
|
|
30
|
-
let
|
|
31
|
+
let node_worker_threads = require("node:worker_threads");
|
|
31
32
|
//#region lib/errors.ts
|
|
32
33
|
/**
|
|
33
34
|
* Base class for all errors the SDK surfaces from Twilio. Carries a numeric
|
|
@@ -129,7 +130,11 @@ var MediaServerRemoteDescFailedError = class extends defineError("MediaServerRem
|
|
|
129
130
|
/**
|
|
130
131
|
* No codec the peers both support could be negotiated. Surfaced through
|
|
131
132
|
* `trackSubscriptionFailed` when a remote track cannot be decoded - notably an
|
|
132
|
-
* H.264-only track
|
|
133
|
+
* H.264-only track before {@link enableH264} has been called. Also surfaced
|
|
134
|
+
* through the local participant's `trackPublicationFailed` when a video track,
|
|
135
|
+
* from `publishTrack` or passed to `connect()`, is published to a Room whose
|
|
136
|
+
* video codecs exclude every codec this SDK can encode: VP8, plus H.264 once
|
|
137
|
+
* enabled. Code `53404`.
|
|
133
138
|
*/
|
|
134
139
|
var MediaNoSupportedCodecError = class extends defineError("MediaNoSupportedCodecError", 53404, "No supported codec") {};
|
|
135
140
|
/** The media connection failed or media activity ceased. Code `53405`. */
|
|
@@ -137,8 +142,8 @@ var MediaConnectionError = class extends defineError("MediaConnectionError", 534
|
|
|
137
142
|
/**
|
|
138
143
|
* The native addon could not be loaded for this platform.
|
|
139
144
|
*
|
|
140
|
-
* Hand-written rather than generated,
|
|
141
|
-
* `cause`. The static `code` is declared so it satisfies the same
|
|
145
|
+
* Hand-written rather than generated, like {@link H264LibraryLoadError}, because
|
|
146
|
+
* it takes a `cause`. The static `code` is declared so it satisfies the same
|
|
142
147
|
* {@link TwilioErrorClass} contract as every generated subclass.
|
|
143
148
|
*/
|
|
144
149
|
var NativeBindingLoadError = class extends TwilioError {
|
|
@@ -153,7 +158,27 @@ var NativeBindingLoadError = class extends TwilioError {
|
|
|
153
158
|
});
|
|
154
159
|
}
|
|
155
160
|
};
|
|
156
|
-
/**
|
|
161
|
+
/**
|
|
162
|
+
* {@link enableH264} could not load the OpenH264 library: the file is missing
|
|
163
|
+
* or can't be loaded, or it isn't OpenH264 2.7.x. The message carries the
|
|
164
|
+
* dynamic loader's text, and `cause` the underlying error.
|
|
165
|
+
*/
|
|
166
|
+
var H264LibraryLoadError = class extends TwilioError {
|
|
167
|
+
/** The code every instance carries: {@link SDK_LOCAL_CODE}. */
|
|
168
|
+
static code = 0;
|
|
169
|
+
constructor(message, options) {
|
|
170
|
+
super(0, message || "Failed to load the OpenH264 library");
|
|
171
|
+
this.name = "H264LibraryLoadError";
|
|
172
|
+
if (options && "cause" in options) Object.defineProperty(this, "cause", {
|
|
173
|
+
value: options.cause,
|
|
174
|
+
configurable: true
|
|
175
|
+
});
|
|
176
|
+
}
|
|
177
|
+
};
|
|
178
|
+
/**
|
|
179
|
+
* The current platform, architecture, or Node version is not supported, or the
|
|
180
|
+
* SDK was imported in a `worker_thread`.
|
|
181
|
+
*/
|
|
157
182
|
var UnsupportedPlatformError = class extends defineError("UnsupportedPlatformError", 0, "Unsupported platform") {};
|
|
158
183
|
/** {@link connect} did not settle within `connectionTimeout`. */
|
|
159
184
|
var RoomConnectTimeoutError = class extends defineError("RoomConnectTimeoutError", 0, "Timed out connecting to the Room") {};
|
|
@@ -361,6 +386,19 @@ var RemoteAudioTrackPublication = class extends RemoteTrackPublication {};
|
|
|
361
386
|
var RemoteDataTrackPublication = class extends RemoteTrackPublication {};
|
|
362
387
|
//#endregion
|
|
363
388
|
//#region lib/local_participant.ts
|
|
389
|
+
/** @internal Counts `track` as published in the Room that owns `dataTracks`, unless released. */
|
|
390
|
+
function markPublished(dataTracks, track) {
|
|
391
|
+
const dataTrack = track;
|
|
392
|
+
if (track.kind !== "data" || dataTracks.released || dataTracks.published.get(dataTrack)) return;
|
|
393
|
+
dataTracks.published.set(dataTrack, true);
|
|
394
|
+
dataTrack._attachRoom();
|
|
395
|
+
}
|
|
396
|
+
function markUnpublished(dataTracks, track) {
|
|
397
|
+
const dataTrack = track;
|
|
398
|
+
if (!dataTracks.published.get(dataTrack)) return;
|
|
399
|
+
dataTracks.published.set(dataTrack, false);
|
|
400
|
+
dataTrack._detachRoom();
|
|
401
|
+
}
|
|
364
402
|
/**
|
|
365
403
|
* The local client's participant in a {@link Room}, reachable via
|
|
366
404
|
* {@link Room.localParticipant}. Use it to publish and unpublish local tracks.
|
|
@@ -370,11 +408,16 @@ var LocalParticipant = class extends TypedEventEmitter {
|
|
|
370
408
|
/** @internal */
|
|
371
409
|
_native;
|
|
372
410
|
_publishedTracks = /* @__PURE__ */ new Map();
|
|
411
|
+
_dataTracks;
|
|
373
412
|
_unpublishFn = (track) => this.unpublishTrack(track);
|
|
374
413
|
/** @internal */
|
|
375
|
-
constructor(nativeParticipant, seededTracks = []
|
|
414
|
+
constructor(nativeParticipant, seededTracks = [], dataTracks = {
|
|
415
|
+
published: /* @__PURE__ */ new Map(),
|
|
416
|
+
released: false
|
|
417
|
+
}) {
|
|
376
418
|
super();
|
|
377
419
|
this._native = nativeParticipant;
|
|
420
|
+
this._dataTracks = dataTracks;
|
|
378
421
|
for (const track of seededTracks) {
|
|
379
422
|
this._assertUniqueName(track);
|
|
380
423
|
this._publishedTracks.set(track.name, track);
|
|
@@ -384,6 +427,10 @@ var LocalParticipant = class extends TypedEventEmitter {
|
|
|
384
427
|
const trackName = data?.trackName;
|
|
385
428
|
const failedTrack = trackName ? this._publishedTracks.get(trackName) : void 0;
|
|
386
429
|
if (trackName) this._publishedTracks.delete(trackName);
|
|
430
|
+
if (failedTrack?.kind === "data") {
|
|
431
|
+
markUnpublished(this._dataTracks, failedTrack);
|
|
432
|
+
failedTrack._settlePendingIfUnpublished("Data track publication failed before the send completed");
|
|
433
|
+
}
|
|
387
434
|
this.emit(event, liftTwilioError(data), failedTrack);
|
|
388
435
|
} else if (event === "trackPublished") {
|
|
389
436
|
const pub = this._resolvePublishedTrack(data);
|
|
@@ -461,7 +508,10 @@ var LocalParticipant = class extends TypedEventEmitter {
|
|
|
461
508
|
publishTrack(track) {
|
|
462
509
|
this._assertUniqueName(track);
|
|
463
510
|
const result = this._native.publishTrack(track);
|
|
464
|
-
if (result)
|
|
511
|
+
if (result) {
|
|
512
|
+
this._publishedTracks.set(track.name, track);
|
|
513
|
+
markPublished(this._dataTracks, track);
|
|
514
|
+
}
|
|
465
515
|
return result;
|
|
466
516
|
}
|
|
467
517
|
/**
|
|
@@ -472,7 +522,10 @@ var LocalParticipant = class extends TypedEventEmitter {
|
|
|
472
522
|
*/
|
|
473
523
|
unpublishTrack(track) {
|
|
474
524
|
const result = this._native.unpublishTrack(track);
|
|
475
|
-
if (result)
|
|
525
|
+
if (result) {
|
|
526
|
+
this._publishedTracks.delete(track.name);
|
|
527
|
+
markUnpublished(this._dataTracks, track);
|
|
528
|
+
}
|
|
476
529
|
return result;
|
|
477
530
|
}
|
|
478
531
|
/**
|
|
@@ -1221,6 +1274,10 @@ var Room = class extends TypedEventEmitter {
|
|
|
1221
1274
|
_localParticipant = null;
|
|
1222
1275
|
_remoteParticipantCache = /* @__PURE__ */ new Map();
|
|
1223
1276
|
_seededTracks;
|
|
1277
|
+
_dataTracks = {
|
|
1278
|
+
published: /* @__PURE__ */ new Map(),
|
|
1279
|
+
released: false
|
|
1280
|
+
};
|
|
1224
1281
|
/**
|
|
1225
1282
|
* @internal `onConnected` fires once for the native connect signal, which is
|
|
1226
1283
|
* already consumed by {@link connect} before the Room is handed to the caller.
|
|
@@ -1229,8 +1286,15 @@ var Room = class extends TypedEventEmitter {
|
|
|
1229
1286
|
super();
|
|
1230
1287
|
this._native = nativeRoom;
|
|
1231
1288
|
this._seededTracks = seededTracks;
|
|
1289
|
+
for (const track of seededTracks) markPublished(this._dataTracks, track);
|
|
1232
1290
|
this._native.setEventCallback((event, data) => {
|
|
1233
1291
|
if (event === "connected") {
|
|
1292
|
+
queueMicrotask(() => {
|
|
1293
|
+
if (!this._native.localParticipant) return;
|
|
1294
|
+
try {
|
|
1295
|
+
this.localParticipant;
|
|
1296
|
+
} catch {}
|
|
1297
|
+
});
|
|
1234
1298
|
this._seedExistingParticipants();
|
|
1235
1299
|
onConnected?.();
|
|
1236
1300
|
onConnected = void 0;
|
|
@@ -1243,6 +1307,7 @@ var Room = class extends TypedEventEmitter {
|
|
|
1243
1307
|
}
|
|
1244
1308
|
} else if (event === "disconnected") {
|
|
1245
1309
|
this._tracks.releaseAllRemoteTracks();
|
|
1310
|
+
this._releaseDataTracks("Room disconnected before the send completed");
|
|
1246
1311
|
this.emit(event, this, data ? liftTwilioError(data) : void 0);
|
|
1247
1312
|
} else if (ROOM_ERROR_EVENTS.has(event)) this.emit(event, liftTwilioError(data));
|
|
1248
1313
|
else if (ROOM_OPTIONAL_ERROR_EVENTS.has(event)) this.emit(event, data ? liftTwilioError(data) : void 0);
|
|
@@ -1279,9 +1344,9 @@ var Room = class extends TypedEventEmitter {
|
|
|
1279
1344
|
if (!native) return null;
|
|
1280
1345
|
return this._wrapRemoteParticipant(native);
|
|
1281
1346
|
}
|
|
1282
|
-
/** The {@link LocalParticipant} representing this client.
|
|
1347
|
+
/** The {@link LocalParticipant} representing this client. Created when the Room connects, or on first access if sooner, and cached. */
|
|
1283
1348
|
get localParticipant() {
|
|
1284
|
-
if (!this._localParticipant) this._localParticipant = new LocalParticipant(this._native.localParticipant, this._seededTracks);
|
|
1349
|
+
if (!this._localParticipant) this._localParticipant = new LocalParticipant(this._native.localParticipant, this._seededTracks, this._dataTracks);
|
|
1285
1350
|
return this._localParticipant;
|
|
1286
1351
|
}
|
|
1287
1352
|
/**
|
|
@@ -1333,10 +1398,25 @@ var Room = class extends TypedEventEmitter {
|
|
|
1333
1398
|
for (const participant of this._remoteParticipantCache.values()) participant.dispose();
|
|
1334
1399
|
this._remoteParticipantCache.clear();
|
|
1335
1400
|
this._tracks.releaseAllRemoteTracks();
|
|
1401
|
+
this._releaseDataTracks("Room was disposed before the send completed");
|
|
1336
1402
|
this._native.dispose();
|
|
1337
1403
|
this.removeAllListeners();
|
|
1338
1404
|
}
|
|
1339
1405
|
/**
|
|
1406
|
+
* Detaches this Room's data tracks, stops counting any published later, and
|
|
1407
|
+
* settles the sends of any now in no Room. The engine reports sends only
|
|
1408
|
+
* through a Room, so they would otherwise never settle and would hold the
|
|
1409
|
+
* process open.
|
|
1410
|
+
*/
|
|
1411
|
+
_releaseDataTracks(reason) {
|
|
1412
|
+
for (const [track, published] of this._dataTracks.published) {
|
|
1413
|
+
if (published) track._detachRoom();
|
|
1414
|
+
track._settlePendingIfUnpublished(reason);
|
|
1415
|
+
}
|
|
1416
|
+
this._dataTracks.published.clear();
|
|
1417
|
+
this._dataTracks.released = true;
|
|
1418
|
+
}
|
|
1419
|
+
/**
|
|
1340
1420
|
* Wraps every participant already in the Room, so their track events are
|
|
1341
1421
|
* observable from the moment the Room connects.
|
|
1342
1422
|
*/
|
|
@@ -1360,33 +1440,12 @@ var Room = class extends TypedEventEmitter {
|
|
|
1360
1440
|
}
|
|
1361
1441
|
};
|
|
1362
1442
|
//#endregion
|
|
1363
|
-
//#region lib/
|
|
1364
|
-
/**
|
|
1365
|
-
* Server-side Node.js SDK for Twilio Video Group Rooms with raw media frame
|
|
1366
|
-
* access.
|
|
1367
|
-
*
|
|
1368
|
-
* {@link connect} joins a Group Room and resolves with a {@link Room}. From
|
|
1369
|
-
* there, {@link Room.localParticipant} publishes tracks and
|
|
1370
|
-
* {@link Room.participants} exposes the remote participants whose tracks can be
|
|
1371
|
-
* subscribed to. Local tracks come from {@link createLocalVideoTrack},
|
|
1372
|
-
* {@link createLocalAudioTrack}, {@link createLocalDataTrack}, and
|
|
1373
|
-
* {@link createLocalTracks}.
|
|
1374
|
-
*
|
|
1375
|
-
* Video frames are I420 planar and audio is 48 kHz mono S16LE PCM, in both
|
|
1376
|
-
* directions. Timestamps are plain numbers of **microseconds**. Receive frames
|
|
1377
|
-
* with `for await (const frame of track.frames())`; awaiting each frame is what
|
|
1378
|
-
* applies backpressure. Call {@link Room.dispose} when finished to release
|
|
1379
|
-
* native resources.
|
|
1380
|
-
*
|
|
1381
|
-
*
|
|
1382
|
-
* @packageDocumentation
|
|
1383
|
-
*/
|
|
1443
|
+
//#region lib/native.ts
|
|
1384
1444
|
const __filename_ = (0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href);
|
|
1385
1445
|
const __dirname_ = node_path.default.dirname(__filename_);
|
|
1386
1446
|
const nativeRequire = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href);
|
|
1387
1447
|
const ROOT = node_fs.default.existsSync(node_path.default.join(__dirname_, "..", "package.json")) ? node_path.default.join(__dirname_, "..") : node_path.default.join(__dirname_, "..", "..");
|
|
1388
|
-
const
|
|
1389
|
-
const SDK_VERSION = PKG.version;
|
|
1448
|
+
const SDK_VERSION = JSON.parse(node_fs.default.readFileSync(node_path.default.join(ROOT, "package.json"), "utf-8")).version;
|
|
1390
1449
|
function getPlatformDir() {
|
|
1391
1450
|
return `${process.platform}-${process.arch}`;
|
|
1392
1451
|
}
|
|
@@ -1394,15 +1453,27 @@ function getPrebuiltPath(platformDir) {
|
|
|
1394
1453
|
return node_path.default.join(ROOT, "prebuilds", platformDir, `twilio_video_sdk_node-${platformDir}.node`);
|
|
1395
1454
|
}
|
|
1396
1455
|
/**
|
|
1397
|
-
* Platforms the published package ships a prebuild for
|
|
1398
|
-
*
|
|
1399
|
-
*
|
|
1400
|
-
* declares.
|
|
1456
|
+
* Platforms the published package ships a prebuild for. The `os` and `cpu`
|
|
1457
|
+
* fields in package.json list operating systems and architectures separately,
|
|
1458
|
+
* so npm also installs the combinations that have no prebuild.
|
|
1401
1459
|
*/
|
|
1402
|
-
const SUPPORTED_PLATFORMS =
|
|
1460
|
+
const SUPPORTED_PLATFORMS = ["linux-x64", "darwin-arm64"];
|
|
1461
|
+
/**
|
|
1462
|
+
* The native library references glibc 2.38 symbols. Older systems load the
|
|
1463
|
+
* addon, then the process dies with a symbol lookup error when that code runs.
|
|
1464
|
+
*/
|
|
1465
|
+
const MIN_GLIBC_MINOR = 38;
|
|
1466
|
+
/** The runtime glibc version on Linux, or undefined elsewhere and on musl. */
|
|
1467
|
+
function glibcVersion() {
|
|
1468
|
+
if (process.platform !== "linux") return void 0;
|
|
1469
|
+
return process.report.getReport().header.glibcVersionRuntime;
|
|
1470
|
+
}
|
|
1403
1471
|
function loadAddon() {
|
|
1472
|
+
if (!node_worker_threads.isMainThread) throw new UnsupportedPlatformError("@twilio/video-node-sdk can only be loaded on the main thread, not in a worker_thread. Import it on the main thread; frames can still be transferred to a worker for processing.");
|
|
1404
1473
|
const platformDir = getPlatformDir();
|
|
1405
1474
|
const prebuiltPath = getPrebuiltPath(platformDir);
|
|
1475
|
+
const glibc = glibcVersion();
|
|
1476
|
+
if (glibc !== void 0 && Number(glibc.split(".")[1]) < MIN_GLIBC_MINOR) throw new UnsupportedPlatformError(`glibc ${glibc} is too old. This SDK needs glibc 2.${MIN_GLIBC_MINOR} or later (Ubuntu 24.04+, Debian 13+).`);
|
|
1406
1477
|
for (const buildType of ["Release", "Debug"]) {
|
|
1407
1478
|
const localPath = node_path.default.join(ROOT, "build", buildType, "twilio_video_sdk_node.node");
|
|
1408
1479
|
if (!node_fs.default.existsSync(localPath)) continue;
|
|
@@ -1417,11 +1488,34 @@ function loadAddon() {
|
|
|
1417
1488
|
} catch (cause) {
|
|
1418
1489
|
throw new NativeBindingLoadError(`The prebuilt binary at ${prebuiltPath} failed to load. This usually means it was built for a different Node ABI (this is Node ${process.version}, modules ${process.versions.modules}) or a required system library is missing. Rebuild from source with \`npm run build\`.`, { cause });
|
|
1419
1490
|
}
|
|
1420
|
-
if (!SUPPORTED_PLATFORMS.includes(platformDir)) throw new UnsupportedPlatformError(`${platformDir} is not a supported platform. This SDK ships a prebuilt addon for ${SUPPORTED_PLATFORMS.join(" and ")}.
|
|
1491
|
+
if (!SUPPORTED_PLATFORMS.includes(platformDir)) throw new UnsupportedPlatformError(`${platformDir} is not a supported platform. This SDK ships a prebuilt addon for ${SUPPORTED_PLATFORMS.join(" and ")}. Contact the Twilio Video team for access to other platforms.`);
|
|
1421
1492
|
const depsPresent = node_fs.default.existsSync(node_path.default.join(ROOT, "deps", "twilio-video"));
|
|
1422
1493
|
throw new NativeBindingLoadError(`No prebuilt binary for ${platformDir}, and no local build in build/Release or build/Debug. ` + (depsPresent ? "Build it with `npm run build`." : "Fetch the native dependencies first with `npm run fetch-deps`, then build with `npm run build`. On Linux the build also needs the X11 development packages (see DEVELOPER_GUIDE.md)."));
|
|
1423
1494
|
}
|
|
1495
|
+
/** The loaded native addon. Internal; not exported from the package entry point. */
|
|
1424
1496
|
const addon = loadAddon();
|
|
1497
|
+
//#endregion
|
|
1498
|
+
//#region lib/index.ts
|
|
1499
|
+
/**
|
|
1500
|
+
* Server-side Node.js SDK for Twilio Video Group Rooms with raw media frame
|
|
1501
|
+
* access.
|
|
1502
|
+
*
|
|
1503
|
+
* {@link connect} joins a Group Room and resolves with a {@link Room}. From
|
|
1504
|
+
* there, {@link Room.localParticipant} publishes tracks and
|
|
1505
|
+
* {@link Room.participants} exposes the remote participants whose tracks can be
|
|
1506
|
+
* subscribed to. Local tracks come from {@link createLocalVideoTrack},
|
|
1507
|
+
* {@link createLocalAudioTrack}, {@link createLocalDataTrack}, and
|
|
1508
|
+
* {@link createLocalTracks}.
|
|
1509
|
+
*
|
|
1510
|
+
* Video frames are I420 planar and audio is 48 kHz mono S16LE PCM, in both
|
|
1511
|
+
* directions. Timestamps are plain numbers of **microseconds**. Receive frames
|
|
1512
|
+
* with `for await (const frame of track.frames())`; awaiting each frame is what
|
|
1513
|
+
* applies backpressure. Call {@link Room.dispose} when finished to release
|
|
1514
|
+
* native resources.
|
|
1515
|
+
*
|
|
1516
|
+
*
|
|
1517
|
+
* @packageDocumentation
|
|
1518
|
+
*/
|
|
1425
1519
|
/**
|
|
1426
1520
|
* Default {@link ConnectOptions.connectionTimeout}. Long enough to absorb a slow
|
|
1427
1521
|
* signaling round trip and ICE gathering on a congested network, short enough
|
|
@@ -1436,6 +1530,7 @@ const DEFAULT_CONNECTION_TIMEOUT_MS = 3e4;
|
|
|
1436
1530
|
const DISPOSE_GRACE_MS = 5e3;
|
|
1437
1531
|
/** Upper bound for a data track's `maxPacketLifeTime`/`maxRetransmits`; both are `unsigned short` in RTCDataChannelInit. */
|
|
1438
1532
|
const MAX_DATA_TRACK_LIMIT = 65535;
|
|
1533
|
+
const MAX_VIDEO_DIMENSION = 16383;
|
|
1439
1534
|
let defaultFactory = null;
|
|
1440
1535
|
function getDefaultMediaFactory() {
|
|
1441
1536
|
if (!defaultFactory) defaultFactory = new addon.MediaFactory();
|
|
@@ -1450,6 +1545,8 @@ function getDefaultMediaFactory() {
|
|
|
1450
1545
|
* @param options - Room name, tracks to publish on join, and feature toggles.
|
|
1451
1546
|
* @returns A promise resolving to the connected {@link Room}.
|
|
1452
1547
|
* @throws {TypeError} (as a rejection) If `token` is not a non-empty string, or `options` is not an object.
|
|
1548
|
+
* @throws {TypeError} (as a rejection) If `options.preferredVideoCodecs` includes `H264` and
|
|
1549
|
+
* {@link enableH264} hasn't succeeded.
|
|
1453
1550
|
* @throws {RangeError} (as a rejection) If `options.networkQuality` verbosities are out of range.
|
|
1454
1551
|
*
|
|
1455
1552
|
* @example
|
|
@@ -1489,6 +1586,7 @@ function connect(token, options = {}) {
|
|
|
1489
1586
|
platformVersion: process.version.replace(/^v/, ""),
|
|
1490
1587
|
deviceArchitecture: process.arch
|
|
1491
1588
|
};
|
|
1589
|
+
if (!h264Enabled && Array.isArray(options.preferredVideoCodecs) && options.preferredVideoCodecs.includes("H264")) return Promise.reject(/* @__PURE__ */ new TypeError("H264 requires enableH264() before connect()"));
|
|
1492
1590
|
internalOpts.mediaFactory = getDefaultMediaFactory();
|
|
1493
1591
|
return new Promise((resolve, reject) => {
|
|
1494
1592
|
const nativeRoom = addon.connect(token, internalOpts);
|
|
@@ -1603,6 +1701,7 @@ function validateVideoSource(source) {
|
|
|
1603
1701
|
const v = source[key];
|
|
1604
1702
|
if (!Number.isInteger(v) || v <= 0) throw new RangeError(`source.${key} must be a positive integer; got ${String(v)}`);
|
|
1605
1703
|
if (v % 2 !== 0) throw new RangeError(`source.${key} must be even; got ${String(v)}`);
|
|
1704
|
+
if (v > MAX_VIDEO_DIMENSION) throw new RangeError(`source.${key} must be at most ${MAX_VIDEO_DIMENSION}; got ${String(v)}`);
|
|
1606
1705
|
}
|
|
1607
1706
|
if (source.fps !== void 0 && (!Number.isInteger(source.fps) || source.fps <= 0)) throw new RangeError(`source.fps must be a positive integer; got ${String(source.fps)}`);
|
|
1608
1707
|
}
|
|
@@ -1721,36 +1820,62 @@ async function createLocalTracks(options = {}) {
|
|
|
1721
1820
|
* depending on the error message.
|
|
1722
1821
|
*/
|
|
1723
1822
|
const ErrorCode = Object.freeze({
|
|
1823
|
+
/** The Access Token provided to the Twilio API was invalid. */
|
|
1724
1824
|
ACCESS_TOKEN_INVALID: 20101,
|
|
1825
|
+
/** The Access Token's header is invalid. */
|
|
1725
1826
|
ACCESS_TOKEN_HEADER_INVALID: 20102,
|
|
1827
|
+
/** The Access Token's issuer or subject is invalid. */
|
|
1726
1828
|
ACCESS_TOKEN_ISSUER_INVALID: 20103,
|
|
1829
|
+
/** The Access Token has expired, or its expiration date is invalid. */
|
|
1727
1830
|
ACCESS_TOKEN_EXPIRED: 20104,
|
|
1831
|
+
/** The Access Token's not-before time is in the future. */
|
|
1728
1832
|
ACCESS_TOKEN_NOT_YET_VALID: 20105,
|
|
1833
|
+
/** The Access Token's grants were invalid, unparseable, or did not permit the requested operation. */
|
|
1729
1834
|
ACCESS_TOKEN_GRANT_INVALID: 20106,
|
|
1835
|
+
/** The Access Token's signature did not verify. */
|
|
1730
1836
|
ACCESS_TOKEN_SIGNATURE_INVALID: 20107,
|
|
1837
|
+
/** A signaling connection error not covered by a more specific code. */
|
|
1731
1838
|
SIGNALING_CONNECTION_ERROR: 53e3,
|
|
1839
|
+
/** The signaling connection was unexpectedly disconnected. */
|
|
1732
1840
|
SIGNALING_CONNECTION_DISCONNECTED: 53001,
|
|
1841
|
+
/** The signaling connection timed out. */
|
|
1733
1842
|
SIGNALING_CONNECTION_TIMEOUT: 53002,
|
|
1843
|
+
/** The operation was attempted on a Room that does not exist. */
|
|
1734
1844
|
ROOM_NOT_FOUND: 53106,
|
|
1845
|
+
/** The Room could not be connected to, for a reason not covered by a more specific code. */
|
|
1735
1846
|
ROOM_CONNECT_FAILED: 53104,
|
|
1847
|
+
/** The Room is already at its participant limit. */
|
|
1736
1848
|
ROOM_MAX_PARTICIPANTS_EXCEEDED: 53105,
|
|
1849
|
+
/** The Room has been completed, and the requested operation cannot be performed on it. */
|
|
1737
1850
|
ROOM_COMPLETED: 53118,
|
|
1851
|
+
/** The participant has reached its maximum number of published tracks. */
|
|
1738
1852
|
PARTICIPANT_MAX_TRACKS_EXCEEDED: 53203,
|
|
1853
|
+
/** The participant was disconnected because another joined with the same identity. */
|
|
1739
1854
|
PARTICIPANT_DUPLICATE_IDENTITY: 53205,
|
|
1855
|
+
/** The track is invalid, for a reason not covered by a more specific code. */
|
|
1740
1856
|
TRACK_INVALID: 53300,
|
|
1857
|
+
/** The track name is invalid, for a reason not covered by a more specific code. */
|
|
1741
1858
|
TRACK_NAME_INVALID: 53301,
|
|
1859
|
+
/** The track name exceeds the maximum length. */
|
|
1742
1860
|
TRACK_NAME_TOO_LONG: 53302,
|
|
1861
|
+
/** The track's name contains characters that are not allowed. */
|
|
1743
1862
|
TRACK_NAME_CHARS_INVALID: 53303,
|
|
1863
|
+
/** The client could not create or apply its local media description. */
|
|
1744
1864
|
MEDIA_CLIENT_LOCAL_DESC_FAILED: 53400,
|
|
1865
|
+
/** The server could not create or apply its local media description. */
|
|
1745
1866
|
MEDIA_SERVER_LOCAL_DESC_FAILED: 53401,
|
|
1867
|
+
/** The client could not apply the remote media description it received. */
|
|
1746
1868
|
MEDIA_CLIENT_REMOTE_DESC_FAILED: 53402,
|
|
1869
|
+
/** The server could not apply the client's media description. */
|
|
1747
1870
|
MEDIA_SERVER_REMOTE_DESC_FAILED: 53403,
|
|
1871
|
+
/** The client and server share no supported codec. */
|
|
1748
1872
|
MEDIA_NO_SUPPORTED_CODEC: 53404,
|
|
1873
|
+
/** The media connection failed, or media activity ceased. */
|
|
1749
1874
|
MEDIA_CONNECTION_ERROR: 53405
|
|
1750
1875
|
});
|
|
1751
|
-
/** The version of
|
|
1876
|
+
/** The version of this package, such as `1.0.0`. */
|
|
1752
1877
|
function getVersion() {
|
|
1753
|
-
return
|
|
1878
|
+
return SDK_VERSION;
|
|
1754
1879
|
}
|
|
1755
1880
|
/**
|
|
1756
1881
|
* Set the verbosity of the native SDK's logging. Process-global and effective
|
|
@@ -1761,6 +1886,49 @@ function getVersion() {
|
|
|
1761
1886
|
function setLogLevel(level) {
|
|
1762
1887
|
addon.setLogLevel(level);
|
|
1763
1888
|
}
|
|
1889
|
+
const H264_PATENT_WARNING = "H.264 enabled via user-provided library. The developer is responsible for obtaining all applicable patent licenses.";
|
|
1890
|
+
let h264Enabled = false;
|
|
1891
|
+
/**
|
|
1892
|
+
* Load an OpenH264 2.7.x library so Rooms can negotiate H.264. Process-wide.
|
|
1893
|
+
*
|
|
1894
|
+
* Call it before the first {@link connect} or `createLocal*Track()` call: the
|
|
1895
|
+
* media factory those create reads the library once, so a later call throws.
|
|
1896
|
+
* Once enabled, H.264 is offered after VP8, and `preferredVideoCodecs` may
|
|
1897
|
+
* name `H264`. It stays enabled for the life of the process. Calling it again
|
|
1898
|
+
* before the first connect or track loads the given library instead.
|
|
1899
|
+
*
|
|
1900
|
+
* A frame larger than 1280x720 (3600 macroblocks) is scaled down to fit H.264
|
|
1901
|
+
* level 3.1, keeping its aspect ratio.
|
|
1902
|
+
*
|
|
1903
|
+
* Every successful call writes a patent-licensing notice with `console.warn`.
|
|
1904
|
+
*
|
|
1905
|
+
* @param options - The library path, and the required licensing confirmation.
|
|
1906
|
+
* @throws {TypeError} If `confirmPatentLicensingCompliance` isn't `true`, or
|
|
1907
|
+
* `openh264Path` isn't a non-empty string without NUL characters. Nothing is loaded.
|
|
1908
|
+
* @throws {Error} If called after the first connect() or createLocal*Track().
|
|
1909
|
+
* @throws {H264LibraryLoadError} If the library can't be loaded or isn't OpenH264 2.7.x.
|
|
1910
|
+
*/
|
|
1911
|
+
function enableH264(options) {
|
|
1912
|
+
if (typeof options !== "object" || options === null) throw new TypeError("enableH264() options must be an object");
|
|
1913
|
+
if (options.confirmPatentLicensingCompliance !== true) throw new TypeError("enableH264() requires confirmPatentLicensingCompliance: true. The developer is responsible for obtaining all applicable patent licenses.");
|
|
1914
|
+
const { openh264Path } = options;
|
|
1915
|
+
if (typeof openh264Path !== "string" || openh264Path === "") throw new TypeError("openh264Path must be a non-empty string");
|
|
1916
|
+
if (openh264Path.includes("\0")) throw new TypeError("openh264Path must not contain a NUL character");
|
|
1917
|
+
if (defaultFactory) throw new Error("enableH264() must be called before the first connect() or createLocal*Track() call");
|
|
1918
|
+
try {
|
|
1919
|
+
addon.loadOpenH264(openh264Path);
|
|
1920
|
+
} catch (cause) {
|
|
1921
|
+
let message = cause.message;
|
|
1922
|
+
if (message.includes(`${openh264Path}: `) && message.includes("No such file or directory") && node_fs.default.existsSync(openh264Path)) message += ". The file exists, so it may be built for a different architecture or C library.";
|
|
1923
|
+
throw new H264LibraryLoadError(message, { cause });
|
|
1924
|
+
}
|
|
1925
|
+
h264Enabled = true;
|
|
1926
|
+
console.warn(H264_PATENT_WARNING);
|
|
1927
|
+
}
|
|
1928
|
+
/** Whether an {@link enableH264} call has succeeded in this process. */
|
|
1929
|
+
function isH264Enabled() {
|
|
1930
|
+
return h264Enabled;
|
|
1931
|
+
}
|
|
1764
1932
|
//#endregion
|
|
1765
1933
|
exports.AccessTokenExpiredError = AccessTokenExpiredError;
|
|
1766
1934
|
exports.AccessTokenGrantsInvalidError = AccessTokenGrantsInvalidError;
|
|
@@ -1771,6 +1939,7 @@ exports.AccessTokenNotYetValidError = AccessTokenNotYetValidError;
|
|
|
1771
1939
|
exports.AccessTokenSignatureInvalidError = AccessTokenSignatureInvalidError;
|
|
1772
1940
|
exports.DataTrackSendError = DataTrackSendError;
|
|
1773
1941
|
exports.ErrorCode = ErrorCode;
|
|
1942
|
+
exports.H264LibraryLoadError = H264LibraryLoadError;
|
|
1774
1943
|
exports.LocalAudioTrackPublication = LocalAudioTrackPublication;
|
|
1775
1944
|
exports.LocalDataTrackPublication = LocalDataTrackPublication;
|
|
1776
1945
|
exports.LocalParticipant = LocalParticipant;
|
|
@@ -1817,6 +1986,8 @@ exports.createLocalAudioTrack = createLocalAudioTrack;
|
|
|
1817
1986
|
exports.createLocalDataTrack = createLocalDataTrack;
|
|
1818
1987
|
exports.createLocalTracks = createLocalTracks;
|
|
1819
1988
|
exports.createLocalVideoTrack = createLocalVideoTrack;
|
|
1989
|
+
exports.enableH264 = enableH264;
|
|
1820
1990
|
exports.getVersion = getVersion;
|
|
1991
|
+
exports.isH264Enabled = isH264Enabled;
|
|
1821
1992
|
exports.setLogLevel = setLogLevel;
|
|
1822
1993
|
exports.twilioErrorFromCode = twilioErrorFromCode;
|