@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/dist/index.mjs CHANGED
@@ -1,8 +1,9 @@
1
1
  import { createRequire } from "node:module";
2
2
  import fs from "node:fs";
3
+ import { EventEmitter } from "node:events";
3
4
  import path from "node:path";
4
5
  import { fileURLToPath } from "node:url";
5
- import { EventEmitter } from "node:events";
6
+ import { isMainThread } from "node:worker_threads";
6
7
  //#region lib/errors.ts
7
8
  /**
8
9
  * Base class for all errors the SDK surfaces from Twilio. Carries a numeric
@@ -104,7 +105,11 @@ var MediaServerRemoteDescFailedError = class extends defineError("MediaServerRem
104
105
  /**
105
106
  * No codec the peers both support could be negotiated. Surfaced through
106
107
  * `trackSubscriptionFailed` when a remote track cannot be decoded - notably an
107
- * H.264-only track, which this SDK does not decode. Code `53404`.
108
+ * H.264-only track before {@link enableH264} has been called. Also surfaced
109
+ * through the local participant's `trackPublicationFailed` when a video track,
110
+ * from `publishTrack` or passed to `connect()`, is published to a Room whose
111
+ * video codecs exclude every codec this SDK can encode: VP8, plus H.264 once
112
+ * enabled. Code `53404`.
108
113
  */
109
114
  var MediaNoSupportedCodecError = class extends defineError("MediaNoSupportedCodecError", 53404, "No supported codec") {};
110
115
  /** The media connection failed or media activity ceased. Code `53405`. */
@@ -112,8 +117,8 @@ var MediaConnectionError = class extends defineError("MediaConnectionError", 534
112
117
  /**
113
118
  * The native addon could not be loaded for this platform.
114
119
  *
115
- * Hand-written rather than generated, because it is the only error that takes a
116
- * `cause`. The static `code` is declared so it satisfies the same
120
+ * Hand-written rather than generated, like {@link H264LibraryLoadError}, because
121
+ * it takes a `cause`. The static `code` is declared so it satisfies the same
117
122
  * {@link TwilioErrorClass} contract as every generated subclass.
118
123
  */
119
124
  var NativeBindingLoadError = class extends TwilioError {
@@ -128,7 +133,27 @@ var NativeBindingLoadError = class extends TwilioError {
128
133
  });
129
134
  }
130
135
  };
131
- /** The current platform, architecture, or Node version is not supported. */
136
+ /**
137
+ * {@link enableH264} could not load the OpenH264 library: the file is missing
138
+ * or can't be loaded, or it isn't OpenH264 2.7.x. The message carries the
139
+ * dynamic loader's text, and `cause` the underlying error.
140
+ */
141
+ var H264LibraryLoadError = class extends TwilioError {
142
+ /** The code every instance carries: {@link SDK_LOCAL_CODE}. */
143
+ static code = 0;
144
+ constructor(message, options) {
145
+ super(0, message || "Failed to load the OpenH264 library");
146
+ this.name = "H264LibraryLoadError";
147
+ if (options && "cause" in options) Object.defineProperty(this, "cause", {
148
+ value: options.cause,
149
+ configurable: true
150
+ });
151
+ }
152
+ };
153
+ /**
154
+ * The current platform, architecture, or Node version is not supported, or the
155
+ * SDK was imported in a `worker_thread`.
156
+ */
132
157
  var UnsupportedPlatformError = class extends defineError("UnsupportedPlatformError", 0, "Unsupported platform") {};
133
158
  /** {@link connect} did not settle within `connectionTimeout`. */
134
159
  var RoomConnectTimeoutError = class extends defineError("RoomConnectTimeoutError", 0, "Timed out connecting to the Room") {};
@@ -336,6 +361,19 @@ var RemoteAudioTrackPublication = class extends RemoteTrackPublication {};
336
361
  var RemoteDataTrackPublication = class extends RemoteTrackPublication {};
337
362
  //#endregion
338
363
  //#region lib/local_participant.ts
364
+ /** @internal Counts `track` as published in the Room that owns `dataTracks`, unless released. */
365
+ function markPublished(dataTracks, track) {
366
+ const dataTrack = track;
367
+ if (track.kind !== "data" || dataTracks.released || dataTracks.published.get(dataTrack)) return;
368
+ dataTracks.published.set(dataTrack, true);
369
+ dataTrack._attachRoom();
370
+ }
371
+ function markUnpublished(dataTracks, track) {
372
+ const dataTrack = track;
373
+ if (!dataTracks.published.get(dataTrack)) return;
374
+ dataTracks.published.set(dataTrack, false);
375
+ dataTrack._detachRoom();
376
+ }
339
377
  /**
340
378
  * The local client's participant in a {@link Room}, reachable via
341
379
  * {@link Room.localParticipant}. Use it to publish and unpublish local tracks.
@@ -345,11 +383,16 @@ var LocalParticipant = class extends TypedEventEmitter {
345
383
  /** @internal */
346
384
  _native;
347
385
  _publishedTracks = /* @__PURE__ */ new Map();
386
+ _dataTracks;
348
387
  _unpublishFn = (track) => this.unpublishTrack(track);
349
388
  /** @internal */
350
- constructor(nativeParticipant, seededTracks = []) {
389
+ constructor(nativeParticipant, seededTracks = [], dataTracks = {
390
+ published: /* @__PURE__ */ new Map(),
391
+ released: false
392
+ }) {
351
393
  super();
352
394
  this._native = nativeParticipant;
395
+ this._dataTracks = dataTracks;
353
396
  for (const track of seededTracks) {
354
397
  this._assertUniqueName(track);
355
398
  this._publishedTracks.set(track.name, track);
@@ -359,6 +402,10 @@ var LocalParticipant = class extends TypedEventEmitter {
359
402
  const trackName = data?.trackName;
360
403
  const failedTrack = trackName ? this._publishedTracks.get(trackName) : void 0;
361
404
  if (trackName) this._publishedTracks.delete(trackName);
405
+ if (failedTrack?.kind === "data") {
406
+ markUnpublished(this._dataTracks, failedTrack);
407
+ failedTrack._settlePendingIfUnpublished("Data track publication failed before the send completed");
408
+ }
362
409
  this.emit(event, liftTwilioError(data), failedTrack);
363
410
  } else if (event === "trackPublished") {
364
411
  const pub = this._resolvePublishedTrack(data);
@@ -436,7 +483,10 @@ var LocalParticipant = class extends TypedEventEmitter {
436
483
  publishTrack(track) {
437
484
  this._assertUniqueName(track);
438
485
  const result = this._native.publishTrack(track);
439
- if (result) this._publishedTracks.set(track.name, track);
486
+ if (result) {
487
+ this._publishedTracks.set(track.name, track);
488
+ markPublished(this._dataTracks, track);
489
+ }
440
490
  return result;
441
491
  }
442
492
  /**
@@ -447,7 +497,10 @@ var LocalParticipant = class extends TypedEventEmitter {
447
497
  */
448
498
  unpublishTrack(track) {
449
499
  const result = this._native.unpublishTrack(track);
450
- if (result) this._publishedTracks.delete(track.name);
500
+ if (result) {
501
+ this._publishedTracks.delete(track.name);
502
+ markUnpublished(this._dataTracks, track);
503
+ }
451
504
  return result;
452
505
  }
453
506
  /**
@@ -1196,6 +1249,10 @@ var Room = class extends TypedEventEmitter {
1196
1249
  _localParticipant = null;
1197
1250
  _remoteParticipantCache = /* @__PURE__ */ new Map();
1198
1251
  _seededTracks;
1252
+ _dataTracks = {
1253
+ published: /* @__PURE__ */ new Map(),
1254
+ released: false
1255
+ };
1199
1256
  /**
1200
1257
  * @internal `onConnected` fires once for the native connect signal, which is
1201
1258
  * already consumed by {@link connect} before the Room is handed to the caller.
@@ -1204,8 +1261,15 @@ var Room = class extends TypedEventEmitter {
1204
1261
  super();
1205
1262
  this._native = nativeRoom;
1206
1263
  this._seededTracks = seededTracks;
1264
+ for (const track of seededTracks) markPublished(this._dataTracks, track);
1207
1265
  this._native.setEventCallback((event, data) => {
1208
1266
  if (event === "connected") {
1267
+ queueMicrotask(() => {
1268
+ if (!this._native.localParticipant) return;
1269
+ try {
1270
+ this.localParticipant;
1271
+ } catch {}
1272
+ });
1209
1273
  this._seedExistingParticipants();
1210
1274
  onConnected?.();
1211
1275
  onConnected = void 0;
@@ -1218,6 +1282,7 @@ var Room = class extends TypedEventEmitter {
1218
1282
  }
1219
1283
  } else if (event === "disconnected") {
1220
1284
  this._tracks.releaseAllRemoteTracks();
1285
+ this._releaseDataTracks("Room disconnected before the send completed");
1221
1286
  this.emit(event, this, data ? liftTwilioError(data) : void 0);
1222
1287
  } else if (ROOM_ERROR_EVENTS.has(event)) this.emit(event, liftTwilioError(data));
1223
1288
  else if (ROOM_OPTIONAL_ERROR_EVENTS.has(event)) this.emit(event, data ? liftTwilioError(data) : void 0);
@@ -1254,9 +1319,9 @@ var Room = class extends TypedEventEmitter {
1254
1319
  if (!native) return null;
1255
1320
  return this._wrapRemoteParticipant(native);
1256
1321
  }
1257
- /** The {@link LocalParticipant} representing this client. Lazily created and cached on first access. */
1322
+ /** The {@link LocalParticipant} representing this client. Created when the Room connects, or on first access if sooner, and cached. */
1258
1323
  get localParticipant() {
1259
- if (!this._localParticipant) this._localParticipant = new LocalParticipant(this._native.localParticipant, this._seededTracks);
1324
+ if (!this._localParticipant) this._localParticipant = new LocalParticipant(this._native.localParticipant, this._seededTracks, this._dataTracks);
1260
1325
  return this._localParticipant;
1261
1326
  }
1262
1327
  /**
@@ -1308,10 +1373,25 @@ var Room = class extends TypedEventEmitter {
1308
1373
  for (const participant of this._remoteParticipantCache.values()) participant.dispose();
1309
1374
  this._remoteParticipantCache.clear();
1310
1375
  this._tracks.releaseAllRemoteTracks();
1376
+ this._releaseDataTracks("Room was disposed before the send completed");
1311
1377
  this._native.dispose();
1312
1378
  this.removeAllListeners();
1313
1379
  }
1314
1380
  /**
1381
+ * Detaches this Room's data tracks, stops counting any published later, and
1382
+ * settles the sends of any now in no Room. The engine reports sends only
1383
+ * through a Room, so they would otherwise never settle and would hold the
1384
+ * process open.
1385
+ */
1386
+ _releaseDataTracks(reason) {
1387
+ for (const [track, published] of this._dataTracks.published) {
1388
+ if (published) track._detachRoom();
1389
+ track._settlePendingIfUnpublished(reason);
1390
+ }
1391
+ this._dataTracks.published.clear();
1392
+ this._dataTracks.released = true;
1393
+ }
1394
+ /**
1315
1395
  * Wraps every participant already in the Room, so their track events are
1316
1396
  * observable from the moment the Room connects.
1317
1397
  */
@@ -1335,33 +1415,12 @@ var Room = class extends TypedEventEmitter {
1335
1415
  }
1336
1416
  };
1337
1417
  //#endregion
1338
- //#region lib/index.ts
1339
- /**
1340
- * Server-side Node.js SDK for Twilio Video Group Rooms with raw media frame
1341
- * access.
1342
- *
1343
- * {@link connect} joins a Group Room and resolves with a {@link Room}. From
1344
- * there, {@link Room.localParticipant} publishes tracks and
1345
- * {@link Room.participants} exposes the remote participants whose tracks can be
1346
- * subscribed to. Local tracks come from {@link createLocalVideoTrack},
1347
- * {@link createLocalAudioTrack}, {@link createLocalDataTrack}, and
1348
- * {@link createLocalTracks}.
1349
- *
1350
- * Video frames are I420 planar and audio is 48 kHz mono S16LE PCM, in both
1351
- * directions. Timestamps are plain numbers of **microseconds**. Receive frames
1352
- * with `for await (const frame of track.frames())`; awaiting each frame is what
1353
- * applies backpressure. Call {@link Room.dispose} when finished to release
1354
- * native resources.
1355
- *
1356
- *
1357
- * @packageDocumentation
1358
- */
1418
+ //#region lib/native.ts
1359
1419
  const __filename_ = fileURLToPath(import.meta.url);
1360
1420
  const __dirname_ = path.dirname(__filename_);
1361
1421
  const nativeRequire = createRequire(import.meta.url);
1362
1422
  const ROOT = fs.existsSync(path.join(__dirname_, "..", "package.json")) ? path.join(__dirname_, "..") : path.join(__dirname_, "..", "..");
1363
- const PKG = JSON.parse(fs.readFileSync(path.join(ROOT, "package.json"), "utf-8"));
1364
- const SDK_VERSION = PKG.version;
1423
+ const SDK_VERSION = JSON.parse(fs.readFileSync(path.join(ROOT, "package.json"), "utf-8")).version;
1365
1424
  function getPlatformDir() {
1366
1425
  return `${process.platform}-${process.arch}`;
1367
1426
  }
@@ -1369,15 +1428,27 @@ function getPrebuiltPath(platformDir) {
1369
1428
  return path.join(ROOT, "prebuilds", platformDir, `twilio_video_sdk_node-${platformDir}.node`);
1370
1429
  }
1371
1430
  /**
1372
- * Platforms the published package ships a prebuild for, derived from the `os`
1373
- * and `cpu` fields npm itself enforces at install time. Deriving rather than
1374
- * restating them means the runtime check cannot drift from what the package
1375
- * declares.
1431
+ * Platforms the published package ships a prebuild for. The `os` and `cpu`
1432
+ * fields in package.json list operating systems and architectures separately,
1433
+ * so npm also installs the combinations that have no prebuild.
1376
1434
  */
1377
- const SUPPORTED_PLATFORMS = (PKG.os ?? ["darwin", "linux"]).flatMap((o) => (PKG.cpu ?? ["x64"]).map((c) => `${o}-${c}`));
1435
+ const SUPPORTED_PLATFORMS = ["linux-x64", "darwin-arm64"];
1436
+ /**
1437
+ * The native library references glibc 2.38 symbols. Older systems load the
1438
+ * addon, then the process dies with a symbol lookup error when that code runs.
1439
+ */
1440
+ const MIN_GLIBC_MINOR = 38;
1441
+ /** The runtime glibc version on Linux, or undefined elsewhere and on musl. */
1442
+ function glibcVersion() {
1443
+ if (process.platform !== "linux") return void 0;
1444
+ return process.report.getReport().header.glibcVersionRuntime;
1445
+ }
1378
1446
  function loadAddon() {
1447
+ if (!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.");
1379
1448
  const platformDir = getPlatformDir();
1380
1449
  const prebuiltPath = getPrebuiltPath(platformDir);
1450
+ const glibc = glibcVersion();
1451
+ 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+).`);
1381
1452
  for (const buildType of ["Release", "Debug"]) {
1382
1453
  const localPath = path.join(ROOT, "build", buildType, "twilio_video_sdk_node.node");
1383
1454
  if (!fs.existsSync(localPath)) continue;
@@ -1392,11 +1463,34 @@ function loadAddon() {
1392
1463
  } catch (cause) {
1393
1464
  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 });
1394
1465
  }
1395
- 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 ")}. ` + (process.platform === "darwin" && process.arch === "arm64" ? "There is no arm64 build. On Apple Silicon, run Node under Rosetta so process.arch reports x64 (install once with `softwareupdate --install-rosetta`, then use an x64 Node)." : "Contact the Twilio Video team for access to other platforms."));
1466
+ 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.`);
1396
1467
  const depsPresent = fs.existsSync(path.join(ROOT, "deps", "twilio-video"));
1397
1468
  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)."));
1398
1469
  }
1470
+ /** The loaded native addon. Internal; not exported from the package entry point. */
1399
1471
  const addon = loadAddon();
1472
+ //#endregion
1473
+ //#region lib/index.ts
1474
+ /**
1475
+ * Server-side Node.js SDK for Twilio Video Group Rooms with raw media frame
1476
+ * access.
1477
+ *
1478
+ * {@link connect} joins a Group Room and resolves with a {@link Room}. From
1479
+ * there, {@link Room.localParticipant} publishes tracks and
1480
+ * {@link Room.participants} exposes the remote participants whose tracks can be
1481
+ * subscribed to. Local tracks come from {@link createLocalVideoTrack},
1482
+ * {@link createLocalAudioTrack}, {@link createLocalDataTrack}, and
1483
+ * {@link createLocalTracks}.
1484
+ *
1485
+ * Video frames are I420 planar and audio is 48 kHz mono S16LE PCM, in both
1486
+ * directions. Timestamps are plain numbers of **microseconds**. Receive frames
1487
+ * with `for await (const frame of track.frames())`; awaiting each frame is what
1488
+ * applies backpressure. Call {@link Room.dispose} when finished to release
1489
+ * native resources.
1490
+ *
1491
+ *
1492
+ * @packageDocumentation
1493
+ */
1400
1494
  /**
1401
1495
  * Default {@link ConnectOptions.connectionTimeout}. Long enough to absorb a slow
1402
1496
  * signaling round trip and ICE gathering on a congested network, short enough
@@ -1411,6 +1505,7 @@ const DEFAULT_CONNECTION_TIMEOUT_MS = 3e4;
1411
1505
  const DISPOSE_GRACE_MS = 5e3;
1412
1506
  /** Upper bound for a data track's `maxPacketLifeTime`/`maxRetransmits`; both are `unsigned short` in RTCDataChannelInit. */
1413
1507
  const MAX_DATA_TRACK_LIMIT = 65535;
1508
+ const MAX_VIDEO_DIMENSION = 16383;
1414
1509
  let defaultFactory = null;
1415
1510
  function getDefaultMediaFactory() {
1416
1511
  if (!defaultFactory) defaultFactory = new addon.MediaFactory();
@@ -1425,6 +1520,8 @@ function getDefaultMediaFactory() {
1425
1520
  * @param options - Room name, tracks to publish on join, and feature toggles.
1426
1521
  * @returns A promise resolving to the connected {@link Room}.
1427
1522
  * @throws {TypeError} (as a rejection) If `token` is not a non-empty string, or `options` is not an object.
1523
+ * @throws {TypeError} (as a rejection) If `options.preferredVideoCodecs` includes `H264` and
1524
+ * {@link enableH264} hasn't succeeded.
1428
1525
  * @throws {RangeError} (as a rejection) If `options.networkQuality` verbosities are out of range.
1429
1526
  *
1430
1527
  * @example
@@ -1464,6 +1561,7 @@ function connect(token, options = {}) {
1464
1561
  platformVersion: process.version.replace(/^v/, ""),
1465
1562
  deviceArchitecture: process.arch
1466
1563
  };
1564
+ if (!h264Enabled && Array.isArray(options.preferredVideoCodecs) && options.preferredVideoCodecs.includes("H264")) return Promise.reject(/* @__PURE__ */ new TypeError("H264 requires enableH264() before connect()"));
1467
1565
  internalOpts.mediaFactory = getDefaultMediaFactory();
1468
1566
  return new Promise((resolve, reject) => {
1469
1567
  const nativeRoom = addon.connect(token, internalOpts);
@@ -1578,6 +1676,7 @@ function validateVideoSource(source) {
1578
1676
  const v = source[key];
1579
1677
  if (!Number.isInteger(v) || v <= 0) throw new RangeError(`source.${key} must be a positive integer; got ${String(v)}`);
1580
1678
  if (v % 2 !== 0) throw new RangeError(`source.${key} must be even; got ${String(v)}`);
1679
+ if (v > MAX_VIDEO_DIMENSION) throw new RangeError(`source.${key} must be at most ${MAX_VIDEO_DIMENSION}; got ${String(v)}`);
1581
1680
  }
1582
1681
  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)}`);
1583
1682
  }
@@ -1696,36 +1795,62 @@ async function createLocalTracks(options = {}) {
1696
1795
  * depending on the error message.
1697
1796
  */
1698
1797
  const ErrorCode = Object.freeze({
1798
+ /** The Access Token provided to the Twilio API was invalid. */
1699
1799
  ACCESS_TOKEN_INVALID: 20101,
1800
+ /** The Access Token's header is invalid. */
1700
1801
  ACCESS_TOKEN_HEADER_INVALID: 20102,
1802
+ /** The Access Token's issuer or subject is invalid. */
1701
1803
  ACCESS_TOKEN_ISSUER_INVALID: 20103,
1804
+ /** The Access Token has expired, or its expiration date is invalid. */
1702
1805
  ACCESS_TOKEN_EXPIRED: 20104,
1806
+ /** The Access Token's not-before time is in the future. */
1703
1807
  ACCESS_TOKEN_NOT_YET_VALID: 20105,
1808
+ /** The Access Token's grants were invalid, unparseable, or did not permit the requested operation. */
1704
1809
  ACCESS_TOKEN_GRANT_INVALID: 20106,
1810
+ /** The Access Token's signature did not verify. */
1705
1811
  ACCESS_TOKEN_SIGNATURE_INVALID: 20107,
1812
+ /** A signaling connection error not covered by a more specific code. */
1706
1813
  SIGNALING_CONNECTION_ERROR: 53e3,
1814
+ /** The signaling connection was unexpectedly disconnected. */
1707
1815
  SIGNALING_CONNECTION_DISCONNECTED: 53001,
1816
+ /** The signaling connection timed out. */
1708
1817
  SIGNALING_CONNECTION_TIMEOUT: 53002,
1818
+ /** The operation was attempted on a Room that does not exist. */
1709
1819
  ROOM_NOT_FOUND: 53106,
1820
+ /** The Room could not be connected to, for a reason not covered by a more specific code. */
1710
1821
  ROOM_CONNECT_FAILED: 53104,
1822
+ /** The Room is already at its participant limit. */
1711
1823
  ROOM_MAX_PARTICIPANTS_EXCEEDED: 53105,
1824
+ /** The Room has been completed, and the requested operation cannot be performed on it. */
1712
1825
  ROOM_COMPLETED: 53118,
1826
+ /** The participant has reached its maximum number of published tracks. */
1713
1827
  PARTICIPANT_MAX_TRACKS_EXCEEDED: 53203,
1828
+ /** The participant was disconnected because another joined with the same identity. */
1714
1829
  PARTICIPANT_DUPLICATE_IDENTITY: 53205,
1830
+ /** The track is invalid, for a reason not covered by a more specific code. */
1715
1831
  TRACK_INVALID: 53300,
1832
+ /** The track name is invalid, for a reason not covered by a more specific code. */
1716
1833
  TRACK_NAME_INVALID: 53301,
1834
+ /** The track name exceeds the maximum length. */
1717
1835
  TRACK_NAME_TOO_LONG: 53302,
1836
+ /** The track's name contains characters that are not allowed. */
1718
1837
  TRACK_NAME_CHARS_INVALID: 53303,
1838
+ /** The client could not create or apply its local media description. */
1719
1839
  MEDIA_CLIENT_LOCAL_DESC_FAILED: 53400,
1840
+ /** The server could not create or apply its local media description. */
1720
1841
  MEDIA_SERVER_LOCAL_DESC_FAILED: 53401,
1842
+ /** The client could not apply the remote media description it received. */
1721
1843
  MEDIA_CLIENT_REMOTE_DESC_FAILED: 53402,
1844
+ /** The server could not apply the client's media description. */
1722
1845
  MEDIA_SERVER_REMOTE_DESC_FAILED: 53403,
1846
+ /** The client and server share no supported codec. */
1723
1847
  MEDIA_NO_SUPPORTED_CODEC: 53404,
1848
+ /** The media connection failed, or media activity ceased. */
1724
1849
  MEDIA_CONNECTION_ERROR: 53405
1725
1850
  });
1726
- /** The version of the underlying native rtc-cpp engine (distinct from this package's version). */
1851
+ /** The version of this package, such as `1.0.0`. */
1727
1852
  function getVersion() {
1728
- return addon.getVersion();
1853
+ return SDK_VERSION;
1729
1854
  }
1730
1855
  /**
1731
1856
  * Set the verbosity of the native SDK's logging. Process-global and effective
@@ -1736,5 +1861,48 @@ function getVersion() {
1736
1861
  function setLogLevel(level) {
1737
1862
  addon.setLogLevel(level);
1738
1863
  }
1864
+ const H264_PATENT_WARNING = "H.264 enabled via user-provided library. The developer is responsible for obtaining all applicable patent licenses.";
1865
+ let h264Enabled = false;
1866
+ /**
1867
+ * Load an OpenH264 2.7.x library so Rooms can negotiate H.264. Process-wide.
1868
+ *
1869
+ * Call it before the first {@link connect} or `createLocal*Track()` call: the
1870
+ * media factory those create reads the library once, so a later call throws.
1871
+ * Once enabled, H.264 is offered after VP8, and `preferredVideoCodecs` may
1872
+ * name `H264`. It stays enabled for the life of the process. Calling it again
1873
+ * before the first connect or track loads the given library instead.
1874
+ *
1875
+ * A frame larger than 1280x720 (3600 macroblocks) is scaled down to fit H.264
1876
+ * level 3.1, keeping its aspect ratio.
1877
+ *
1878
+ * Every successful call writes a patent-licensing notice with `console.warn`.
1879
+ *
1880
+ * @param options - The library path, and the required licensing confirmation.
1881
+ * @throws {TypeError} If `confirmPatentLicensingCompliance` isn't `true`, or
1882
+ * `openh264Path` isn't a non-empty string without NUL characters. Nothing is loaded.
1883
+ * @throws {Error} If called after the first connect() or createLocal*Track().
1884
+ * @throws {H264LibraryLoadError} If the library can't be loaded or isn't OpenH264 2.7.x.
1885
+ */
1886
+ function enableH264(options) {
1887
+ if (typeof options !== "object" || options === null) throw new TypeError("enableH264() options must be an object");
1888
+ if (options.confirmPatentLicensingCompliance !== true) throw new TypeError("enableH264() requires confirmPatentLicensingCompliance: true. The developer is responsible for obtaining all applicable patent licenses.");
1889
+ const { openh264Path } = options;
1890
+ if (typeof openh264Path !== "string" || openh264Path === "") throw new TypeError("openh264Path must be a non-empty string");
1891
+ if (openh264Path.includes("\0")) throw new TypeError("openh264Path must not contain a NUL character");
1892
+ if (defaultFactory) throw new Error("enableH264() must be called before the first connect() or createLocal*Track() call");
1893
+ try {
1894
+ addon.loadOpenH264(openh264Path);
1895
+ } catch (cause) {
1896
+ let message = cause.message;
1897
+ if (message.includes(`${openh264Path}: `) && message.includes("No such file or directory") && fs.existsSync(openh264Path)) message += ". The file exists, so it may be built for a different architecture or C library.";
1898
+ throw new H264LibraryLoadError(message, { cause });
1899
+ }
1900
+ h264Enabled = true;
1901
+ console.warn(H264_PATENT_WARNING);
1902
+ }
1903
+ /** Whether an {@link enableH264} call has succeeded in this process. */
1904
+ function isH264Enabled() {
1905
+ return h264Enabled;
1906
+ }
1739
1907
  //#endregion
1740
- export { AccessTokenExpiredError, AccessTokenGrantsInvalidError, AccessTokenHeaderInvalidError, AccessTokenInvalidError, AccessTokenIssuerInvalidError, AccessTokenNotYetValidError, AccessTokenSignatureInvalidError, DataTrackSendError, ErrorCode, LocalAudioTrackPublication, LocalDataTrackPublication, LocalParticipant, LocalTrackPublication, LocalVideoTrackPublication, MAX_QUEUE_CEILING, MediaClientLocalDescFailedError, MediaClientRemoteDescFailedError, MediaConnectionError, MediaNoSupportedCodecError, MediaServerLocalDescFailedError, MediaServerRemoteDescFailedError, NativeBindingLoadError, ParticipantDuplicateIdentityError, ParticipantMaxTracksExceededError, RemoteAudioTrack, RemoteAudioTrackPublication, RemoteDataTrack, RemoteDataTrackPublication, RemoteParticipant, RemoteTrackPublication, RemoteVideoTrack, RemoteVideoTrackPublication, Room, RoomCompletedError, RoomConnectFailedError, RoomConnectTimeoutError, RoomMaxParticipantsExceededError, RoomNotFoundError, SDK_LOCAL_CODE, SignalingConnectionDisconnectedError, SignalingConnectionError, SignalingConnectionTimeoutError, TrackInvalidError, TrackNameCharsInvalidError, TrackNameInvalidError, TrackNameTooLongError, TrackPublication, TwilioError, TypedEventEmitter, UnsupportedPlatformError, connect, createLocalAudioTrack, createLocalDataTrack, createLocalTracks, createLocalVideoTrack, getVersion, setLogLevel, twilioErrorFromCode };
1908
+ export { AccessTokenExpiredError, AccessTokenGrantsInvalidError, AccessTokenHeaderInvalidError, AccessTokenInvalidError, AccessTokenIssuerInvalidError, AccessTokenNotYetValidError, AccessTokenSignatureInvalidError, DataTrackSendError, ErrorCode, H264LibraryLoadError, LocalAudioTrackPublication, LocalDataTrackPublication, LocalParticipant, LocalTrackPublication, LocalVideoTrackPublication, MAX_QUEUE_CEILING, MediaClientLocalDescFailedError, MediaClientRemoteDescFailedError, MediaConnectionError, MediaNoSupportedCodecError, MediaServerLocalDescFailedError, MediaServerRemoteDescFailedError, NativeBindingLoadError, ParticipantDuplicateIdentityError, ParticipantMaxTracksExceededError, RemoteAudioTrack, RemoteAudioTrackPublication, RemoteDataTrack, RemoteDataTrackPublication, RemoteParticipant, RemoteTrackPublication, RemoteVideoTrack, RemoteVideoTrackPublication, Room, RoomCompletedError, RoomConnectFailedError, RoomConnectTimeoutError, RoomMaxParticipantsExceededError, RoomNotFoundError, SDK_LOCAL_CODE, SignalingConnectionDisconnectedError, SignalingConnectionError, SignalingConnectionTimeoutError, TrackInvalidError, TrackNameCharsInvalidError, TrackNameInvalidError, TrackNameTooLongError, TrackPublication, TwilioError, TypedEventEmitter, UnsupportedPlatformError, connect, createLocalAudioTrack, createLocalDataTrack, createLocalTracks, createLocalVideoTrack, enableH264, getVersion, isH264Enabled, setLogLevel, twilioErrorFromCode };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@twilio/video-node-sdk",
3
- "version": "1.0.0-rc.3",
3
+ "version": "1.0.0-rc.4",
4
4
  "description": "Twilio Video Media Streams SDK for Node.js - Server-side access to decoded video/audio frames",
5
5
  "homepage": "https://github.com/twilio/twilio-video-node#readme",
6
6
  "bugs": {
@@ -32,9 +32,11 @@
32
32
  "build:ts": "tsdown",
33
33
  "docs": "typedoc",
34
34
  "test": "vitest run",
35
- "test:unit": "vitest run --exclude '**/integration.test.ts' --exclude '**/node_modules/**'",
35
+ "test:unit": "vitest run --exclude '**/integration.test.ts' --exclude 'test/browser/**' --exclude '**/node_modules/**'",
36
36
  "test:integration": "vitest run test/integration.test.ts",
37
- "test:coverage": "vitest run --coverage --exclude '**/integration.test.ts' --exclude '**/node_modules/**'",
37
+ "test:h264": "vitest run test/h264/integration.test.ts",
38
+ "test:browser": "vitest run test/browser/",
39
+ "test:coverage": "vitest run --coverage --exclude '**/integration.test.ts' --exclude 'test/browser/**' --exclude '**/node_modules/**'",
38
40
  "lint": "eslint .",
39
41
  "format": "prettier --write .",
40
42
  "format:check": "prettier --check .",
@@ -49,17 +51,20 @@
49
51
  "@eslint/js": "^10.0.1",
50
52
  "@types/node": "^22.0.0",
51
53
  "@vitest/coverage-v8": "^4.0.18",
52
- "cmake-js": "^7.3.0",
54
+ "cmake-js": "^8.0.0",
53
55
  "eslint": "^10.0.2",
54
56
  "husky": "^9.1.7",
55
57
  "lint-staged": "^16.2.7",
56
58
  "node-addon-api": "^8.0.0",
59
+ "playwright-core": "1.64.0",
57
60
  "prettier": "^3.8.1",
58
61
  "tsdown": "^0.21.1",
59
62
  "twilio": "^5.12.1",
63
+ "twilio-video": "2.36.1",
60
64
  "typedoc": "^0.28.20",
61
65
  "typescript": "^5.0.0",
62
66
  "typescript-eslint": "^8.57.0",
67
+ "vite": "^7.3.7",
63
68
  "vitest": "^4.0.18"
64
69
  },
65
70
  "files": [
@@ -69,7 +74,8 @@
69
74
  "CHANGELOG.md",
70
75
  "FRAME_CONTRACT.md",
71
76
  "LIFECYCLE.md",
72
- "SECURITY-PRIVACY.md"
77
+ "SECURITY-PRIVACY.md",
78
+ "THIRD_PARTY_NOTICES"
73
79
  ],
74
80
  "engines": {
75
81
  "node": ">=24.0.0"
@@ -79,7 +85,8 @@
79
85
  "linux"
80
86
  ],
81
87
  "cpu": [
82
- "x64"
88
+ "x64",
89
+ "arm64"
83
90
  ],
84
91
  "keywords": [
85
92
  "twilio",
@@ -107,5 +114,8 @@
107
114
  "repository": {
108
115
  "type": "git",
109
116
  "url": "https://github.com/twilio/twilio-video-node.git"
117
+ },
118
+ "overrides": {
119
+ "uri-js": "npm:fast-uri@^4.2.3"
110
120
  }
111
121
  }