@twilio/video-node-sdk

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 a Node.js process push and receive decoded video and audio frames in real time.

Note: this is a beta release of the Twilio Media SDK for Node.js. It is provided for evaluation purposes only. During the beta period this SDK is not HIPAA eligible.

• Overview
• Quickstart
• Work with media frames
• Best practices
• Differences from the JavaScript SDK
• Troubleshooting
• API reference
• Changelog

Requirements

The native binary is prebuilt and bundled, so there is no build step.

• Node.js >= 24.0.0
• Linux x86-64 with glibc: Ubuntu 24.04+ or Debian 13+
• macOS 26+ on arm64 (Apple Silicon), for local development only. The macOS build is not supported in production.

The binary is built for Linux x86-64 and macOS arm64 only. Intel Macs, Linux arm64, Alpine and other musl-based distros, and Windows are not supported.

On Linux the addon is linked against glibc and requires:

Requirement	Minimum
glibc	2.38
libstdc++ (GLIBCXX)	3.4.30
C++ ABI (CXXABI)	1.3.13

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.

On macOS, npm cannot check the OS version, so on a release older than macOS 26 npm install succeeds and the SDK fails when it loads the addon.

The addon is built with N-API, so it does not need rebuilding for each Node.js release.

Load the SDK on the main thread. Importing it in a worker_thread throws UnsupportedPlatformError; frames can still be transferred to a worker for processing.

Installation

npm install @twilio/video-node-sdk

connect() takes a standard Twilio Video Access Token with a VideoGrant, the same token format the JavaScript SDK uses. Generate one with the twilio helper library; see User Identity and Access Tokens.

Quick start

const { connect, createLocalVideoTrack } = require('@twilio/video-node-sdk');

async function main() {
  const videoTrack = createLocalVideoTrack('virtual-camera');

  const room = await connect(token, {
    name: 'my-room',
    videoTracks: [videoTrack],
  });

  console.log('Connected to Room:', room.name, room.sid);

  // Push I420 video frames. Frames written before connect() resolves are dropped.
  videoTrack.write({
    format: 'I420',
    width: 1280,
    height: 720,
    y: { data: yPlane, stride: 1280, width: 1280, height: 720 },
    u: { data: uPlane, stride: 640, width: 640, height: 360 },
    v: { data: vPlane, stride: 640, width: 640, height: 360 },
  });

  async function trackSubscribed(track) {
    if (track.kind !== 'video') return;
    try {
      // Frames that arrive while you process one are queued, and the SDK drops
      // them if the queue fills. The loop ends by itself when the track is
      // unsubscribed or the Room disconnects.
      for await (const frame of track.frames()) {
        console.log(`${frame.width}x${frame.height} @ ${frame.timestamp}us`);
        frame.close?.();
      }
    } catch (err) {
      // Nothing awaits this function, so an error that escapes here becomes an
      // unhandled rejection and stops the process.
      console.error('Frame loop failed:', err);
    }
  }

  function participantConnected(participant) {
    participant.on('trackSubscribed', trackSubscribed);

    participant.tracks.forEach(publication => {
      if (publication.isSubscribed) {
        trackSubscribed(publication.track);
      }
    });
  }

  // participantConnected does not fire for participants already in the Room, and a
  // track can finish subscribing before the trackSubscribed listener is attached.
  // Seed from room.participants and check isSubscribed on each publication.
  room.participants.forEach(participantConnected);
  room.on('participantConnected', participantConnected);

  room.on('disconnected', () => {
    room.dispose();
  });
}

main().catch(err => {
  console.error('Error:', err);
  process.exit(1);
});

Call room.dispose() when you are done with a Room. Until you do, the Node.js process does not exit; disconnect() leaves the Room but does not release its native resources. See LIFECYCLE.md.

Further reading

• FRAME_CONTRACT.md: buffer ownership, backpressure and drop semantics, timestamps, and publish invariants.
• LIFECYCLE.md: what each object owns, what disconnect() and dispose() release, and event ordering during teardown.
• SECURITY-PRIVACY.md: what the SDK does with decoded media, and which obligations remain with the application.

Examples

The examples/ directory has runnable examples, with setup steps: a virtual camera, a video mirror, audio push, data tracks, a voice agent, and two computer-vision examples.

Community Contributions and Support

This repository is publicly available and maintained by Twilio under a limited external contribution model.

Due to limited maintenance capacity, external pull requests are not currently accepted.

GitHub Issues may be used to report reproducible bugs or provide feature feedback about this SDK. Issues are reviewed on a best-effort basis, with no SLA or guaranteed response.

GitHub Issues are not an official Twilio support channel. For production issues, general usage questions, or account-specific assistance, please contact Twilio Support. If you have a Twilio account manager, you may also escalate through them.

Do not share Personally Identifiable Information (PII) or sensitive account information, including access tokens, API keys, and credentials, in issues, logs, or screenshots.

Report security vulnerabilities privately through Twilio's Vulnerability Disclosure Program, rather than public GitHub Issues.

See CONTRIBUTING.md for reporting guidance.

License

See LICENSE.md.