Video Media SDK for Node.js quickstart

This quickstart shows how to connect to a Video Room from a Node.js server, publish a video track by pushing raw frames, and receive decoded frames from remote Participants. To learn what the SDK is and how it differs from the client-side SDKs, see the Overview.

Prerequisites

To use the Video Media SDK, you need the following prerequisites:

Create a Twilio account.
Install Node.js version 24.0.0 or later on Linux x64 or macOS x64. On an Apple Silicon Mac, run an x64 build of Node.js under Rosetta. To learn more, see system requirements.
Create an API key SID and secret.
View how to create an API Key
Twilio ConsoleLegacy Console

Go to the Twilio Console. The Let's get building page appears.

Click API keys and Auth tokens. The API keys & auth tokens page appears with the Auth Tokens tab selected.

Scroll to your Account SID.

Click the copy button next to your Account SID.

Run the following command, replacing YOUR_ACCOUNT_SID with your Account SID.

macOS TerminalWindows command linePowerShell
export TWILIO_ACCOUNT_SID=YOUR_ACCOUNT_SID

This command creates an environment variable on your development system for your account SID.

To display the Auth Token, click the eye button in the Primary auth token box.

Highlight and copy the Auth Token.

Run the following command, replacing YOUR_AUTH_TOKEN with your Authentication Token.

macOS TerminalWindows command linePowerShell
export TWILIO_AUTH_TOKEN=YOUR_AUTH_TOKEN

This command creates an environment variable on your development system for your auth token.

Install the SDK

Install the SDK npm packages.
1
npm install @twilio/video-node
2
npm install @twilio/video-node-sdk

In your app, add the import statement for the SDK:

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

Create an Access Token

The connect() function takes a standard Twilio Video Access Token with a VideoGrant, the same token format the JavaScript SDK uses. Generate an Access Token on your server with the twilio helper library.

Create an access token example

1const twilio = require('twilio');
2
3function generateToken(identity, roomName) {
4  const token = new twilio.jwt.AccessToken(
5    process.env.TWILIO_ACCOUNT_SID,
6    process.env.TWILIO_API_KEY,
7    process.env.TWILIO_API_SECRET,
8    { identity, ttl: 3600 },
9  );
10  token.addGrant(new twilio.jwt.AccessToken.VideoGrant({ room: roomName }));
11  return token.toJwt();
12}

(warning)

Treat an API Key like a password

Keep your API key secret on the server. Never ship Twilio credentials in client-side code or commit the controls to source control.

Connect to a Room

Create a local video track then pass it to connect(). The call resolves once the Room connects.

Connect to a Room example

1const { connect, createLocalVideoTrack } = require('@twilio/video-node-sdk');
2
3const videoTrack = createLocalVideoTrack('virtual-camera');
4
5const room = await connect(generateToken('node-participant', 'my-room'), {
6  name: 'my-room',
7  videoTracks: [videoTrack],
8});
9
10console.log('Connected to Room:', room.name, room.sid);

Send video frames

Unlike the client-side SDKs, a local track lacks a camera. To supply raw I420 video frames, call the write() method on the track. Each call takes the y, u, and v planes as Buffer objects, along with their strides and the frame dimensions.

Send video example

1videoTrack.write({
2  y: yPlane, // Buffer
3  u: uPlane, // Buffer
4  v: vPlane, // Buffer
5  yStride: 1280,
6  uStride: 640,
7  vStride: 640,
8  width: 1280,
9  height: 720,
10});

(information)

Connect before you send

Resolve connect(), then send frames. Any frames before that resolution get dropped. Start your send loop after the await returns.

To learn about I420 video planes and strides and PCM audio, see Work with media frames.

Receive media from remote Participants

Remote media arrives as raw decoded frames. Listen for trackSubscribed, then register an onFrame() callback on each video or audio track.

Receive media example

1function trackSubscribed(track) {
2  if (track.kind === 'video') {
3    track.onFrame(frame => {
4      console.log(`Received ${frame.width}x${frame.height} frame`);
5    });
6  }
7}
8
9function participantConnected(participant) {
10  participant.on('trackSubscribed', trackSubscribed);
11
12  // A track can finish subscribing before this listener is attached.
13  participant.tracks.forEach(publication => {
14    if (publication.isSubscribed) {
15      trackSubscribed(publication.track);
16    }
17  });
18}
19
20// participantConnected doesn't fire for Participants already in the Room, so
21// seed from room.participants, then listen for Participants who join later.
22room.participants.forEach(participantConnected);
23room.on('participantConnected', participantConnected);

Run a working example

The SDK repository includes runnable examples. The virtual_camera.js example decodes an MP4 with ffmpeg and sends its frames into a Room.

1git clone https://github.com/twilio/twilio-video-node.git
2cd twilio-video-node
3cp .env.example .env
4# Edit .env and set TWILIO_ACCOUNT_SID, TWILIO_API_KEY, and TWILIO_API_SECRET.
5node examples/virtual_camera.js my-room

To review every example, see the examples directory.

Next steps

Work with media frames: Learn the I420 video and PCM audio frame formats in depth.
Differences from the JavaScript SDK: Map what you know from the browser SDK to the server.
Best practices: Pace frames, manage resources, and troubleshoot common issues.