@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.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 node_events = require("node:events");
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, which this SDK does not decode. Code `53404`.
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, because it is the only error that takes a
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
- /** The current platform, architecture, or Node version is not supported. */
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) this._publishedTracks.set(track.name, track);
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) this._publishedTracks.delete(track.name);
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. Lazily created and cached on first access. */
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/index.ts
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 PKG = JSON.parse(node_fs.default.readFileSync(node_path.default.join(ROOT, "package.json"), "utf-8"));
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, derived from the `os`
1398
- * and `cpu` fields npm itself enforces at install time. Deriving rather than
1399
- * restating them means the runtime check cannot drift from what the package
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 = (PKG.os ?? ["darwin", "linux"]).flatMap((o) => (PKG.cpu ?? ["x64"]).map((c) => `${o}-${c}`));
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 ")}. ` + (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."));
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 the underlying native rtc-cpp engine (distinct from this package's version). */
1876
+ /** The version of this package, such as `1.0.0`. */
1752
1877
  function getVersion() {
1753
- return addon.getVersion();
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;