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

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,21 @@
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.3 (September 24, 2026)
5
+
6
+ ## Documentation
7
+
8
+ ### API reference on GitHub Pages
9
+
10
+ The API reference for each release is published at https://twilio.github.io/twilio-video-node/,
11
+ which opens the latest version.
12
+
13
+ ### `SECURITY-PRIVACY.md` ships in the package
14
+
15
+ It describes what the SDK does with decoded media and which obligations remain with the
16
+ application.
17
+
18
+ # 1.0.0-rc.2 (September 23, 2026)
5
19
 
6
20
  ## Breaking Changes
7
21
 
@@ -172,14 +186,19 @@ change what is sent or when. Video publish still carries the timestamp through
172
186
  to the encoded frame. This documents existing behavior; nothing changed in the
173
187
  publish path.
174
188
 
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`.
189
+ ### The package ships linux-x64 and darwin-x64 prebuilds
190
+
191
+ The darwin-x64 prebuild is built and tested in CI alongside linux-x64. It requires macOS
192
+ 26 or later and an x64 Node, so on Apple Silicon Node must run under Rosetta. npm cannot check
193
+ the macOS version, so on an older macOS the install succeeds and loading the addon fails.
194
+
195
+ ### `trackSubscribed` and `trackUnsubscribed` pass a `RemoteTrackPublication`
196
+
197
+ Listeners receive `(track, publication)` on a `RemoteParticipant` and
198
+ `(track, publication, participant)` on a `Room`, matching twilio-video.js. Update any listener
199
+ that took `(track, participant)` on a Room. On `trackUnsubscribed` the publication reports
200
+ `isSubscribed: false` and its `track` is `undefined`, as documented for
201
+ `RemoteTrackPublication`; the unsubscribed track is the event's first argument.
183
202
 
184
203
  ### Remote track events carry a `RemoteTrackPublication`
185
204
 
@@ -200,6 +219,13 @@ participant.on('trackPublished', pub => {
200
219
  });
201
220
  ```
202
221
 
222
+ ### An event listener that throws is no longer ignored
223
+
224
+ The error is reported as an `uncaughtException`, and events queued behind it are retained, so
225
+ an application that handles `uncaughtException` still receives them. Previously such an error
226
+ produced no output at all, which was indistinguishable from an event that was never emitted. An
227
+ application relying on that behavior will start seeing `uncaughtException`.
228
+
203
229
  ### `disconnected` passes the Room first
204
230
 
205
231
  Listeners receive `(room, error?)` instead of `(error?)`, matching twilio-video.js.
@@ -272,10 +298,6 @@ localParticipant.on('trackPublicationFailed', (error, localTrack) => { ... });
272
298
  connects, rather than one thread hop later, which is after the subscription has already
273
299
  completed. Rejoining participants were the most affected: the first join often reported its
274
300
  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
301
  - `trackUnsubscribed` is now emitted for every track a participant was still publishing when they
280
302
  disconnected. It could previously be lost because it and `participantDisconnected` were
281
303
  delivered on independent internal queues with no guaranteed order between them.
package/README.md CHANGED
@@ -4,24 +4,25 @@
4
4
 
5
5
  Server-side Node.js SDK for Twilio Video Group Rooms with raw media frame access. Built on a native C++ addon over WebRTC, it lets you push and receive decoded video and audio frames from Node.js on realtime.
6
6
 
7
+ [API reference](https://twilio.github.io/twilio-video-node/latest/)
8
+
7
9
  **Note: this is a beta release of the Twilio Media SDK for Node.js. It is provided for evaluation purposes only and should not be used with production traffic. During the beta period this SDK is not HIPAA eligible.**
8
10
 
9
11
  ## Installation
10
12
 
11
- Install the provided `.tgz` file directly:
12
-
13
13
  ```bash
14
- npm install ./twilio-video-node-sdk-<version>.tgz
14
+ npm install @twilio/video-node-sdk
15
15
  ```
16
16
 
17
- The native binary is prebuilt and bundled — no build step required. Import it as `@twilio/video-node-sdk`.
17
+ The native binary is prebuilt and bundled — no build step required.
18
18
 
19
19
  **Requirements:**
20
20
 
21
21
  - Node.js >= 24.0.0
22
- - Linux x86-64, glibc >= 2.34 (Ubuntu 22.04+, Debian 12+)
22
+ - Linux x86-64, glibc >= 2.34 (Ubuntu 22.04+, Debian 12+), or
23
+ - macOS 26+ on x86-64 (Intel, or Apple Silicon with Node running under Rosetta)
23
24
 
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.
25
+ Alpine/musl, native arm64 and Windows are not supported. See [Platform Support](#platform-support) for the full requirements.
25
26
 
26
27
  ### Access Token
27
28
 
@@ -520,7 +521,7 @@ Interleaved 16-bit signed little-endian PCM in a single `Buffer`.
520
521
  ## Platform Support
521
522
 
522
523
  - **Node.js** >= 24.0.0
523
- - **OS** Linux x86-64
524
+ - **OS** Linux x86-64, macOS 26+ x86-64
524
525
  - **Distros** Ubuntu 22.04+ and Debian 12+.
525
526
  - **CPU** x86-64 only. There is no arm64 build, so on Apple Silicon Node must run under Rosetta.
526
527
 
@@ -534,7 +535,9 @@ The prebuilt native addon is linked against glibc and requires:
534
535
 
535
536
  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
537
 
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).
538
+ 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.
539
+
540
+ Alpine and other musl-based distros are not supported: the addon is glibc-only. Windows is not supported.
538
541
 
539
542
  ## Examples
540
543
 
@@ -0,0 +1,25 @@
1
+ # Security and privacy
2
+
3
+ What this SDK does with decoded media, and which obligations remain with the application. [README.md](README.md) covers usage, and [LIFECYCLE.md](LIFECYCLE.md) covers object ownership and teardown.
4
+
5
+ This document describes SDK behavior. It is not legal advice and does not establish Twilio's obligations under any agreement.
6
+
7
+ ## Where decoded media goes
8
+
9
+ The SDK decodes subscribed audio and video in the Node process and delivers the decoded frames to the application. Video frames carry raw, uncompressed planes; audio frames carry uncompressed PCM. Both reach the application as ordinary JavaScript objects in the process heap, readable by any code in the process.
10
+
11
+ This differs from Twilio's browser and mobile Video SDKs, which run on an end user's own device and deliver media to a rendering surface. Here, decoded media is present in application memory on whatever host runs the process.
12
+
13
+ Once a frame reaches the application, what happens to it is the application's responsibility: how it is processed, where it is written, whether it is forwarded to another service, and who can read it. The SDK applies no restriction to a delivered frame and has no view of what the application does with it.
14
+
15
+ ## Protected health information
16
+
17
+ The SDK provides no PHI-aware primitives: no tagging, redaction, retention control, encryption-at-rest helper, or access control for the decoded media described above. If an application requires these capabilities, they must be implemented outside the SDK.
18
+
19
+ ## Retention
20
+
21
+ The SDK does not persist media. Frames are delivered to the application and released; nothing is written to disk. The only filesystem access is reading `package.json` and locating the prebuilt native addon at load time.
22
+
23
+ Observed: no media write path exists in either the JavaScript or the native layer.
24
+
25
+ Any persistence of media, or of data derived from media, is created by the application and retained under its own policy.
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.3",
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,12 +65,11 @@
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",
77
- "LIFECYCLE.md"
71
+ "LIFECYCLE.md",
72
+ "SECURITY-PRIVACY.md"
78
73
  ],
79
74
  "engines": {
80
75
  "node": ">=24.0.0"
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
- }