@twilio/video-node-sdk 1.0.0-rc.1 → 1.0.0-rc.2

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 CHANGED
@@ -1,7 +1,7 @@
1
- This SDK is currently in beta, and Linux x86-64 is the only supported platform.
1
+ This SDK is currently in beta. It supports Linux x86-64 and macOS 26+ on x86-64.
2
2
  See the [README](README.md) for details.
3
3
 
4
- # 1.0.0-beta.1 (In Progress)
4
+ # 1.0.0-rc.2 (September 23, 2026)
5
5
 
6
6
  ## Breaking Changes
7
7
 
@@ -172,14 +172,19 @@ change what is sent or when. Video publish still carries the timestamp through
172
172
  to the encoded frame. This documents existing behavior; nothing changed in the
173
173
  publish path.
174
174
 
175
- - `trackSubscribed` and `trackUnsubscribed` now pass the track's `RemoteTrackPublication`.
176
- Listeners receive `(track, publication)` on a `RemoteParticipant` and
177
- `(track, publication, participant)` on a `Room`, matching twilio-video.js. Update any
178
- listener that took `(track, participant)` on a Room. On `trackUnsubscribed` the publication
179
- reports `isSubscribed: false` and its `track` is `undefined`, as documented for
180
- `RemoteTrackPublication`; the unsubscribed track is the event's first argument.
181
- - An event listener that throws now surfaces the error instead of being silently ignored. An
182
- application relying on the previous behavior will start seeing `uncaughtException`.
175
+ ### The package ships linux-x64 and darwin-x64 prebuilds
176
+
177
+ The darwin-x64 prebuild is built and tested in CI alongside linux-x64. It requires macOS
178
+ 26 or later and an x64 Node, so on Apple Silicon Node must run under Rosetta. npm cannot check
179
+ the macOS version, so on an older macOS the install succeeds and loading the addon fails.
180
+
181
+ ### `trackSubscribed` and `trackUnsubscribed` pass a `RemoteTrackPublication`
182
+
183
+ Listeners receive `(track, publication)` on a `RemoteParticipant` and
184
+ `(track, publication, participant)` on a `Room`, matching twilio-video.js. Update any listener
185
+ that took `(track, participant)` on a Room. On `trackUnsubscribed` the publication reports
186
+ `isSubscribed: false` and its `track` is `undefined`, as documented for
187
+ `RemoteTrackPublication`; the unsubscribed track is the event's first argument.
183
188
 
184
189
  ### Remote track events carry a `RemoteTrackPublication`
185
190
 
@@ -200,6 +205,13 @@ participant.on('trackPublished', pub => {
200
205
  });
201
206
  ```
202
207
 
208
+ ### An event listener that throws is no longer ignored
209
+
210
+ The error is reported as an `uncaughtException`, and events queued behind it are retained, so
211
+ an application that handles `uncaughtException` still receives them. Previously such an error
212
+ produced no output at all, which was indistinguishable from an event that was never emitted. An
213
+ application relying on that behavior will start seeing `uncaughtException`.
214
+
203
215
  ### `disconnected` passes the Room first
204
216
 
205
217
  Listeners receive `(room, error?)` instead of `(error?)`, matching twilio-video.js.
@@ -272,10 +284,6 @@ localParticipant.on('trackPublicationFailed', (error, localTrack) => { ... });
272
284
  connects, rather than one thread hop later, which is after the subscription has already
273
285
  completed. Rejoining participants were the most affected: the first join often reported its
274
286
  tracks and later ones silently did not.
275
- - An exception thrown by an event listener is no longer swallowed. It is reported as an
276
- `uncaughtException`, and events queued behind it are retained so an application that handles
277
- `uncaughtException` still receives them. Previously such an error produced no output at all,
278
- which was indistinguishable from an event that was never emitted.
279
287
  - `trackUnsubscribed` is now emitted for every track a participant was still publishing when they
280
288
  disconnected. It could previously be lost because it and `participantDisconnected` were
281
289
  delivered on independent internal queues with no guaranteed order between them.
package/README.md CHANGED
@@ -8,20 +8,19 @@ Server-side Node.js SDK for Twilio Video Group Rooms with raw media frame access
8
8
 
9
9
  ## Installation
10
10
 
11
- Install the provided `.tgz` file directly:
12
-
13
11
  ```bash
14
- npm install ./twilio-video-node-sdk-<version>.tgz
12
+ npm install @twilio/video-node-sdk
15
13
  ```
16
14
 
17
- The native binary is prebuilt and bundled — no build step required. Import it as `@twilio/video-node-sdk`.
15
+ The native binary is prebuilt and bundled — no build step required.
18
16
 
19
17
  **Requirements:**
20
18
 
21
19
  - Node.js >= 24.0.0
22
- - Linux x86-64, glibc >= 2.34 (Ubuntu 22.04+, Debian 12+)
20
+ - Linux x86-64, glibc >= 2.34 (Ubuntu 22.04+, Debian 12+), or
21
+ - macOS 26+ on x86-64 (Intel, or Apple Silicon with Node running under Rosetta)
23
22
 
24
- Linux x86-64 is the only supported platform for the beta. Alpine/musl, arm64 and Windows are not supported, and macOS is development-only. See [Platform Support](#platform-support) for the full ABI requirements.
23
+ Alpine/musl, native arm64 and Windows are not supported. See [Platform Support](#platform-support) for the full requirements.
25
24
 
26
25
  ### Access Token
27
26
 
@@ -520,7 +519,7 @@ Interleaved 16-bit signed little-endian PCM in a single `Buffer`.
520
519
  ## Platform Support
521
520
 
522
521
  - **Node.js** >= 24.0.0
523
- - **OS** Linux x86-64
522
+ - **OS** Linux x86-64, macOS 26+ x86-64
524
523
  - **Distros** Ubuntu 22.04+ and Debian 12+.
525
524
  - **CPU** x86-64 only. There is no arm64 build, so on Apple Silicon Node must run under Rosetta.
526
525
 
@@ -534,7 +533,9 @@ The prebuilt native addon is linked against glibc and requires:
534
533
 
535
534
  It also links `libX11.so.6`, which WebRTC requires unconditionally. Install your distro's X11 client library (`libx11-6` on Debian and Ubuntu) even on headless servers.
536
535
 
537
- Alpine and other musl-based distros are not supported: the addon is glibc-only. Windows is not supported. macOS x64 builds and runs for local development, but is not a supported target and is not tested as one. See [DEVELOPER_GUIDE.md](DEVELOPER_GUIDE.md).
536
+ On macOS the prebuilt addon requires macOS 26 or later. npm cannot check the macOS version, so on an older release `npm install` succeeds and the SDK fails when it loads the addon.
537
+
538
+ Alpine and other musl-based distros are not supported: the addon is glibc-only. Windows is not supported.
538
539
 
539
540
  ## Examples
540
541
 
package/dist/index.cjs CHANGED
@@ -1394,9 +1394,10 @@ function getPrebuiltPath(platformDir) {
1394
1394
  return node_path.default.join(ROOT, "prebuilds", platformDir, `twilio_video_sdk_node-${platformDir}.node`);
1395
1395
  }
1396
1396
  /**
1397
- * Platforms the native addon is built for, derived from the `os` and `cpu`
1398
- * fields npm itself enforces at install time. Deriving rather than restating
1399
- * them means the runtime check cannot drift from what the package declares.
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.
1400
1401
  */
1401
1402
  const SUPPORTED_PLATFORMS = (PKG.os ?? ["darwin", "linux"]).flatMap((o) => (PKG.cpu ?? ["x64"]).map((c) => `${o}-${c}`));
1402
1403
  function loadAddon() {
@@ -1416,7 +1417,7 @@ function loadAddon() {
1416
1417
  } catch (cause) {
1417
1418
  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 });
1418
1419
  }
1419
- if (!SUPPORTED_PLATFORMS.includes(platformDir)) throw new UnsupportedPlatformError(`${platformDir} is not a supported platform. This SDK supports linux-x64; the native addon can also load on ${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."));
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."));
1420
1421
  const depsPresent = node_fs.default.existsSync(node_path.default.join(ROOT, "deps", "twilio-video"));
1421
1422
  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)."));
1422
1423
  }
package/dist/index.mjs CHANGED
@@ -1369,9 +1369,10 @@ function getPrebuiltPath(platformDir) {
1369
1369
  return path.join(ROOT, "prebuilds", platformDir, `twilio_video_sdk_node-${platformDir}.node`);
1370
1370
  }
1371
1371
  /**
1372
- * Platforms the native addon is built for, derived from the `os` and `cpu`
1373
- * fields npm itself enforces at install time. Deriving rather than restating
1374
- * them means the runtime check cannot drift from what the package declares.
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.
1375
1376
  */
1376
1377
  const SUPPORTED_PLATFORMS = (PKG.os ?? ["darwin", "linux"]).flatMap((o) => (PKG.cpu ?? ["x64"]).map((c) => `${o}-${c}`));
1377
1378
  function loadAddon() {
@@ -1391,7 +1392,7 @@ function loadAddon() {
1391
1392
  } catch (cause) {
1392
1393
  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 });
1393
1394
  }
1394
- if (!SUPPORTED_PLATFORMS.includes(platformDir)) throw new UnsupportedPlatformError(`${platformDir} is not a supported platform. This SDK supports linux-x64; the native addon can also load on ${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."));
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."));
1395
1396
  const depsPresent = fs.existsSync(path.join(ROOT, "deps", "twilio-video"));
1396
1397
  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)."));
1397
1398
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@twilio/video-node-sdk",
3
- "version": "1.0.0-rc.1",
3
+ "version": "1.0.0-rc.2",
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": {
@@ -22,16 +22,12 @@
22
22
  }
23
23
  },
24
24
  "scripts": {
25
- "install": "node scripts/install.js",
26
25
  "build": "node scripts/build.js",
27
26
  "build:debug": "cmake-js build --debug",
28
27
  "build:release": "cmake-js build --CDCMAKE_BUILD_TYPE=Release",
29
28
  "rebuild": "cmake-js rebuild",
30
29
  "clean": "cmake-js clean",
31
30
  "package": "node scripts/prebuild.js",
32
- "upload": "node scripts/upload.js",
33
- "upload:darwin": "node scripts/upload.js darwin-x64",
34
- "upload:linux": "node scripts/upload.js linux-x64",
35
31
  "fetch-deps": "node scripts/fetch-deps.js",
36
32
  "build:ts": "tsdown",
37
33
  "docs": "typedoc",
@@ -43,7 +39,7 @@
43
39
  "format": "prettier --write .",
44
40
  "format:check": "prettier --check .",
45
41
  "prepare": "husky",
46
- "test:unit:pure": "vitest run test/frame_stream.test.ts test/remote_track.test.ts test/errors.test.ts test/room.test.ts test/participant.test.ts",
42
+ "test:unit:pure": "vitest run test/frame_stream.test.ts test/remote_track.test.ts test/errors.test.ts test/room.test.ts test/participant.test.ts test/changelog_section.test.ts",
47
43
  "typecheck": "tsc --noEmit -p tsconfig.test.json",
48
44
  "test:soak": "node test/soak.mjs",
49
45
  "typecheck:examples": "tsc --noEmit -p examples/tsconfig.json",
@@ -69,8 +65,6 @@
69
65
  "files": [
70
66
  "dist",
71
67
  "prebuilds",
72
- "scripts/install.js",
73
- "scripts/common.js",
74
68
  "package.json",
75
69
  "CHANGELOG.md",
76
70
  "FRAME_CONTRACT.md",
package/scripts/common.js DELETED
@@ -1,66 +0,0 @@
1
- 'use strict';
2
-
3
- const path = require('path');
4
-
5
- const ADDON_NAME = 'twilio_video_sdk_node.node';
6
- const ROOT = path.join(__dirname, '..');
7
-
8
- function getPlatformDir(override) {
9
- if (override) {
10
- return override;
11
- }
12
- return `${process.platform}-${process.arch}`;
13
- }
14
-
15
- /**
16
- * Platforms the native addon is built for, derived from the `os` and `cpu`
17
- * fields npm enforces at install time. Derived rather than restated so this
18
- * cannot drift from what the package declares; lib/index.ts derives the same
19
- * list for its runtime check.
20
- */
21
- function getSupportedPlatforms(pkg) {
22
- return (pkg.os || ['darwin', 'linux']).flatMap(o => (pkg.cpu || ['x64']).map(c => `${o}-${c}`));
23
- }
24
-
25
- function getPrebuiltName(platformDir) {
26
- return `${ADDON_NAME.replace('.node', '')}-${platformDir}.node`;
27
- }
28
-
29
- function getPrebuiltPath(platformDir) {
30
- return path.join(ROOT, 'prebuilds', platformDir, getPrebuiltName(platformDir));
31
- }
32
-
33
- function getGitHubInfo(pkg) {
34
- let repoUrl = process.env.GITHUB_REPOSITORY || pkg.repository?.url;
35
- if (!repoUrl) {
36
- return null;
37
- }
38
-
39
- repoUrl = repoUrl.replace(/^git\+/, '').replace(/\.git$/, '');
40
- const match = repoUrl.match(/https?:\/\/([^/]+)\/(.+)$/);
41
- if (!match) {
42
- return null;
43
- }
44
-
45
- return {
46
- host: match[1],
47
- repo: match[2],
48
- version: pkg.version,
49
- tag: pkg.version,
50
- };
51
- }
52
-
53
- function log(prefix, msg) {
54
- console.log(`[${prefix}] ${msg}`);
55
- }
56
-
57
- module.exports = {
58
- ADDON_NAME,
59
- ROOT,
60
- getPlatformDir,
61
- getPrebuiltName,
62
- getPrebuiltPath,
63
- getSupportedPlatforms,
64
- getGitHubInfo,
65
- log,
66
- };
@@ -1,95 +0,0 @@
1
- #!/usr/bin/env node
2
-
3
- 'use strict';
4
-
5
- const fs = require('fs');
6
- const path = require('path');
7
- const { execFileSync } = require('child_process');
8
- const {
9
- ADDON_NAME,
10
- ROOT,
11
- getPlatformDir,
12
- getPrebuiltPath,
13
- getPrebuiltName,
14
- getSupportedPlatforms,
15
- getGitHubInfo,
16
- log,
17
- } = require('./common');
18
-
19
- const platformDir = getPlatformDir();
20
- const prebuiltPath = getPrebuiltPath(platformDir);
21
- const releasePath = path.join(ROOT, 'build', 'Release', ADDON_NAME);
22
- const debugPath = path.join(ROOT, 'build', 'Debug', ADDON_NAME);
23
-
24
- function exit(msg, code = 1) {
25
- console.error(`[install] ${msg}`);
26
- process.exit(code);
27
- }
28
-
29
- if (process.env.TWILIO_VIDEO_NODE_SKIP_DOWNLOAD === '1') {
30
- log('install', 'Skipping download (TWILIO_VIDEO_NODE_SKIP_DOWNLOAD=1)');
31
- process.exit(0);
32
- }
33
-
34
- if (fs.existsSync(prebuiltPath)) {
35
- log('install', `Prebuilt found: ${prebuiltPath}`);
36
- process.exit(0);
37
- }
38
-
39
- if (fs.existsSync(releasePath) || fs.existsSync(debugPath)) {
40
- log('install', 'Local build found, skipping download');
41
- process.exit(0);
42
- }
43
-
44
- const pkg = require(path.join(ROOT, 'package.json'));
45
-
46
- if (process.env.TWILIO_VIDEO_NODE_ALLOW_GH_DOWNLOAD !== '1') {
47
- exit(
48
- `No prebuilt binary for ${platformDir} in this package. ` +
49
- 'This SDK supports linux-x64; the addon can also be built for ' +
50
- `${getSupportedPlatforms(pkg).join(', ')} ` +
51
- '(there is no arm64 build, so on Apple Silicon run Node under Rosetta with ' +
52
- '`arch -x86_64 node`). Contact the Twilio Video team for access to other platforms.',
53
- );
54
- }
55
-
56
- const ghInfo = getGitHubInfo(pkg);
57
-
58
- if (!ghInfo) {
59
- exit('No repository info. Set GITHUB_REPOSITORY or add repository field to package.json');
60
- }
61
-
62
- const assetName = getPrebuiltName(platformDir);
63
- const repo = `${ghInfo.host}/${ghInfo.repo}`;
64
-
65
- log('install', `Downloading ${assetName} from ${repo} ${ghInfo.tag}...`);
66
-
67
- fs.mkdirSync(path.dirname(prebuiltPath), { recursive: true });
68
-
69
- try {
70
- execFileSync(
71
- 'gh',
72
- [
73
- 'release',
74
- 'download',
75
- ghInfo.tag,
76
- '--repo',
77
- repo,
78
- '--pattern',
79
- assetName,
80
- '--dir',
81
- path.dirname(prebuiltPath),
82
- ],
83
- { stdio: ['ignore', 'pipe', 'pipe'] },
84
- );
85
-
86
- if (!fs.existsSync(prebuiltPath)) {
87
- exit(`Asset ${assetName} not found in release ${ghInfo.tag}`);
88
- }
89
-
90
- const size = fs.statSync(prebuiltPath).size;
91
- log('install', `Downloaded ${(size / 1024 / 1024).toFixed(1)} MB`);
92
- } catch (err) {
93
- const stderr = err.stderr?.toString() || err.message;
94
- exit(`Download failed: ${stderr.trim()}`);
95
- }