Skip to contentSkip to navigationSkip to topbar
Page tools
Useful for sharing or LLM
Accelerate development with AI
On this page
Looking for more inspiration?Visit the

Video Media SDK for Node.js overview

(new)

Public Beta

The Video Media SDK for Node.js is currently available as a Public Beta product and the information contained in this document is subject to change. This means that some features are not yet implemented and others may be changed before the product is declared as Generally Available. Public Beta products are not covered by the Twilio Support Terms or Twilio Service Level Agreement(link takes you to an external page).

The Video Media SDK for Node.js is not a US Health Insurance Portability and Accountability Act (HIPAA)(link takes you to an external page) Eligible Service or Payment Card Industry Data Security Standard (PCI DSS)(link takes you to an external page) compliant and should not be enabled in workflows that are subject to HIPAA or PCI.

The Video Media SDK for Node.js provides a server-side SDK for Twilio Video Group Rooms with raw media frame access. It lets a Node.js process join a Room and push and receive media frames. A media frame includes the decoded video, audio, and data track messages that flow through the Room one frame at a time. Twilio built the SDK on top of Web Real-Time Communication (WebRTC)(link takes you to an external page), so it doesn't require a browser or a device.

The SDK shares the Room, Participant, and Track model and event names with the Twilio Video JavaScript SDK. It connects with the same Access Token and VideoGrant format. If you know the JavaScript SDK, most concepts carry over.

To learn the differences between the client and server SDKs, see Differences from the JavaScript SDK.

The Video Media SDK for Node.js processes real-time media in a Room. It differs from the twilio-node helper library(link takes you to an external page), which calls the Twilio REST APIs. You can use both in the same app. You can create an Access Token with twilio-node and move media with the Media SDK.

To try an example, see the examples directory(link takes you to an external page) in the SDK repository.

System requirements

system-requirements page anchor

The SDK ships a prebuilt native binary. It requires Node.js version 24.0.0 or later running on x86-64, on one of the following platforms:

  • Linux on x86-64, with glibc version 2.34 or later (Ubuntu 22.04 or later, Debian 12 or later) and the libX11 library installed.
  • macOS 26 or later on x86-64, for local development.

On macOS, npm can't check the operating system version. On versions prior to macOS 26, npm install succeeds and the SDK fails when it loads the native binary.

Use macOS for local development only. Twilio doesn't support the macOS build in production.

The SDK doesn't provide an arm64 build for either platform. On x86-64, process.arch reports x64. Alpine and other musl-based distributions aren't supported.

(information)

Apple Silicon Macs

The SDK requires an x64 build of Node.js. Rosetta lets an x64 build run on Apple Silicon, but installing Rosetta doesn't change which build of Node.js you have. If your Node.js is an arm64 build, the SDK doesn't install.

To install an x64 build of Node.js on an Apple Silicon (M-series) Mac, follow these steps:

  1. In Terminal, install Rosetta: 
    /usr/sbin/softwareupdate --install-rosetta --agree-to-license
  2. Install an x64 build of Node.js version 24.0.0 or later. Open a shell that runs under Rosetta, and then install Node.js with nvm: 
    1
    arch -x86_64 zsh

    2
    nvm install 24
  3. Confirm that your Node.js install uses the x64 architecture: 
    node -e "console.log(process.arch)"
    A successful install returns x64. If this commands returns arm64, you're running an arm64 build:
    • If you have an arm64 build of Node.js 24, remove it, and then repeat steps 2 and 3: 
      1
      nvm deactivate

      2
      nvm uninstall 24

If npm install fails with npm error code EBADPLATFORM and reports "cpu":"arm64", you're running an arm64 build of Node.js. Follow the preceding steps to switch to an x64 build.

Known issues and limitations

known-issues-and-limitations page anchor

The SDK supports fewer codecs than the Twilio Video client SDKs:

  • Video: VP8 only. The SDK can't publish or subscribe to H.264 or VP9 video tracks.
  • Audio: Opus and PCMU only. The SDK doesn't support PCMA or G.722.

If you pass any other codec in preferredVideoCodecs or preferredAudioCodecs, connect() rejects with a TypeError. If a remote participant publishes an H.264 video track, the subscription fails with error 53404. To make sure the SDK receives video from every participant, set preferredVideoCodecs: ['VP8'] in your client apps. To fix codec errors, see Troubleshoot Node.js Media SDK issues.

Resources

resources page anchor