Required dependencies

npm install user@example.com
# If installing from source rather than npm:
npm install debug flatbuffers h264-profile-level-id node-fetch supports-color tar

No additional native build steps are required when using the prebuilt npm package — mediasoup downloads prebuilt worker binaries automatically. If building from source, a C++ toolchain (gcc/clang, Python 3, make) is required and npm install will compile the worker binary.

Project setup

1. Copy the source/ directory into your project, e.g. src/mediasoup/.
2. Ensure tsconfig.json includes the source directory and has these compiler options:

   {
     "compilerOptions": {
       "target": "ES2020",
       "module": "commonjs",
       "moduleResolution": "node",
       "strict": true,
       "esModuleInterop": true,
       "resolveJsonModule": true
     },
     "include": ["src/**/*"]
   }
   

3. Set the worker binary path if overriding the default:

   export MEDIASOUP_WORKER_BIN=/path/to/custom/mediasoup-worker
   

4. Import from the source entry point:

   import * as mediasoup from './mediasoup/index';
   

5. Ensure Node.js >= 18 is used; the worker subprocess requires it.

Public API

createWorker

import { createWorker } from './mediasoup/index';
import type { WorkerSettings } from './mediasoup/WorkerTypes';

const worker = await createWorker<WorkerSettings>({
  logLevel: 'warn',
  rtcMinPort: 10000,
  rtcMaxPort: 10100,
});

Creates and starts a mediasoup-worker subprocess. Returns a Worker instance. Call once per CPU core for parallelism; monitor the 'died' event to detect crashes.

observer

import { observer } from './mediasoup/index';

observer.on('newworker', (worker) => {
  console.log('new worker created, pid:', worker.pid);
});

A global EnhancedEventEmitter that emits 'newworker' whenever a Worker is created. Use it for centralized lifecycle monitoring across all workers in the process.

getSupportedRtpCapabilities

import { getSupportedRtpCapabilities } from './mediasoup/index';
import type { RouterRtpCapabilities } from './mediasoup/rtpParametersTypes';

const caps: RouterRtpCapabilities = getSupportedRtpCapabilities();

Returns the RTP capabilities built into this mediasoup build. Pass these (or a subset) to router.createRouter() as mediaCodecs. Use to discover which codecs are available before configuring a Router.

parseScalabilityMode

import { parseScalabilityMode } from './mediasoup/scalabilityModesUtils';

const mode = parseScalabilityMode('L3T3_KEY');
// { spatialLayers: 3, temporalLayers: 3, ksvc: true }

Parses a scalability mode string (e.g., from SDP) into structured layer counts. Use when inspecting or validating SVC encoding parameters on Producers.

Working examples

Scenario - Basic WebRTC room with one producer and one consumer

Create a Worker, Router, two WebRTC Transports (send and receive), a Producer, and a Consumer. This is the core pattern for a video call participant.

import * as mediasoup from './mediasoup/index';

async function main() {
  const worker = await mediasoup.createWorker({
    logLevel: 'warn',
    rtcMinPort: 40000,
    rtcMaxPort: 49999,
  });

  worker.on('died', (error) => {
    console.error('mediasoup worker died', error);
    process.exit(1);
  });

  const router = await worker.createRouter({
    mediaCodecs: [
      {
        kind: 'audio',
        mimeType: 'audio/opus',
        clockRate: 48000,
        channels: 2,
      },
      {
        kind: 'video',
        mimeType: 'video/VP8',
        clockRate: 90000,
      },
    ],
  });

  // Transport for the sending peer
  const sendTransport = await router.createWebRtcTransport({
    listenInfos: [{ protocol: 'udp', ip: '0.0.0.0', announcedAddress: '1.2.3.4' }],
    enableUdp: true,
    enableTcp: true,
  });

  // Transport for the receiving peer
  const recvTransport = await router.createWebRtcTransport({
    listenInfos: [{ protocol: 'udp', ip: '0.0.0.0', announcedAddress: '1.2.3.4' }],
    enableUdp: true,
    enableTcp: true,
  });

  console.log('send transport id:', sendTransport.id);
  console.log('recv transport id:', recvTransport.id);
}

main().catch(console.error);

Scenario - Audio level monitoring with AudioLevelObserver

Attach an AudioLevelObserver to a Router to detect who is speaking. Emit the active speaker to your signaling layer.

import * as mediasoup from './mediasoup/index';

async function setupAudioLevelObserver(
  router: mediasoup.types.Router
) {
  const audioLevelObserver = await router.createAudioLevelObserver({
    maxEntries: 1,
    threshold: -80,
    interval: 800,
  });

  audioLevelObserver.on('volumes', (volumes) => {
    for (const { producer, volume } of volumes) {
      console.log(`producer ${producer.id} volume: ${volume} dBvo`);
    }
  });

  audioLevelObserver.on('silence', () => {
    console.log('silence detected');
  });

  return audioLevelObserver;
}

Scenario - Pipe media between two Routers on different Workers

Scale across CPU cores by piping a Producer from one Router to another using pipeToRouter.

import * as mediasoup from './mediasoup/index';

async function scaleAcrossWorkers() {
  const worker1 = await mediasoup.createWorker({ rtcMinPort: 40000, rtcMaxPort: 41000 });
  const worker2 = await mediasoup.createWorker({ rtcMinPort: 41001, rtcMaxPort: 42000 });

  const mediaCodecs = [
    { kind: 'video' as const, mimeType: 'video/VP8', clockRate: 90000 },
  ];

  const router1 = await worker1.createRouter({ mediaCodecs });
  const router2 = await worker2.createRouter({ mediaCodecs });

  // Assume producerOnRouter1 already exists
  // const { pipeProducer } = await router1.pipeToRouter({
  //   producerId: producerOnRouter1.id,
  //   router: router2,
  // });
  // Now create consumers from pipeProducer on router2

  console.log('router1 id:', router1.id);
  console.log('router2 id:', router2.id);

  await worker1.close();
  await worker2.close();
}

scaleAcrossWorkers().catch(console.error);

File walkthrough

• index.ts: Public entry point; re-exports createWorker, version, observer, getSupportedRtpCapabilities, parseScalabilityMode, and all types.
• Worker.ts / WorkerTypes.ts: Spawns the C++ worker subprocess via WorkerImpl; exposes createRouter and resource management.
• Router.ts / RouterTypes.ts: Central routing entity; creates all transport types and RTP observers; implements pipeToRouter.
• Transport.ts / TransportTypes.ts: Abstract base containing produce, consume, produceData, consumeData shared by all transport subtypes.
• WebRtcTransport.ts / WebRtcTransportTypes.ts: Handles ICE negotiation, DTLS, and SRTP for browser peers.
• PlainTransport.ts / PlainTransportTypes.ts: Plain UDP/TCP RTP transport for non-WebRTC tools.
• PipeTransport.ts / PipeTransportTypes.ts: Low-overhead internal transport for Router-to-Router media piping.
• DirectTransport.ts / DirectTransportTypes.ts: In-process data-only transport for Node.js DataConsumer/DataProducer.
• Producer.ts / ProducerTypes.ts: Represents an inbound media stream; tracks RTP parameters and stats.
• Consumer.ts / ConsumerTypes.ts: Represents an outbound media stream; supports simulcast layer selection.
• DataProducer.ts / DataProducerTypes.ts: Inbound SCTP data stream abstraction.
• DataConsumer.ts / DataConsumerTypes.ts: Outbound SCTP data stream abstraction.
• ActiveSpeakerObserver.ts / ActiveSpeakerObserverTypes.ts: Emits 'dominantspeaker' events based on audio activity.
• AudioLevelObserver.ts / AudioLevelObserverTypes.ts: Periodically emits 'volumes' with dBvo levels per Producer.
• RtpObserver.ts / RtpObserverTypes.ts: Shared base class for observer add/remove producer lifecycle.
• Channel.ts: Internal FlatBuffers-based IPC channel; not used directly by application code.
• ortc.ts: RTP capability matching, codec validation, and encoding mapping utilities used by Router and Transport.
• errors.ts: Exports UnsupportedError and InvalidStateError for error handling in application code.
• enhancedEvents.ts: Typed EnhancedEventEmitter providing type-safe .on(), .off(), .emit().
• Logger.ts: Namespaced debug logger wrapping the debug npm package.
• rtpParametersTypes.ts: Core type definitions for RtpCapabilities, RtpParameters, MediaKind, etc.
• sctpParametersTypes.ts: SctpCapabilities and SctpStreamParameters type definitions.
• srtpParametersTypes.ts: SrtpParameters and SrtpCryptoSuite type definitions.
• scalabilityModesUtils.ts: Exports parseScalabilityMode for SVC string parsing.
• supportedRtpCapabilities.ts: Static object listing all codecs and header extensions mediasoup supports.
• utils.ts: Internal clone, generate ID, and other utility functions.
• fbsUtils.ts / rtpParametersFbsUtils.ts / rtpStreamStatsFbsUtils.ts / sctpParametersFbsUtils.ts / srtpParametersFbsUtils.ts: FlatBuffers serialization/deserialization helpers for worker IPC.
• types.ts / indexTypes.ts / extras.ts: Aggregate type re-exports for the public API surface.

Common pitfalls and fixes

• Worker binary not found at startup: Set MEDIASOUP_WORKER_BIN env var or ensure the npm postinstall script completed; run npm rebuild mediasoup to recompile.
• Port range exhausted / no available UDP port: Widen rtcMinPort/rtcMaxPort in createWorker options and open those ports in your firewall/security group.
• announcedAddress not set in Docker/cloud: Always set announcedAddress in listenInfos to the public IP; the default 0.0.0.0 is unreachable by remote peers.
• ESM/CJS interop errors when importing: mediasoup ships CJS; if your project is "type": "module", use createRequire or set "moduleResolution": "node16" with "module": "Node16" in tsconfig.json.
• Consumer created before transport connected: Call transport.connect() with DTLS parameters before producing/consuming, otherwise media will not flow and the consumer will remain in transportclose state.
• Multiple workers not load-balanced: createWorker does not auto-balance; maintain a worker pool and assign Routers to workers in round-robin or by CPU load.

Vibe-coding prompt template

I have the mediasoup Node.js SFU library source in `source/` (mediasoup@3.19.22, Node.js TypeScript).
I also have `USAGE.md` which documents the real API, imports, and working examples.

My project is a Node.js TypeScript backend using Express. I need you to:

1. Read `USAGE.md` fully before writing any code.
2. Install all required dependencies listed in the "Required dependencies" section.
3. Add the `source/` directory to my project under `src/mediasoup/` and update `tsconfig.json` as described in "Project setup".
4. Create `src/mediaServer.ts` that:
   - Creates a mediasoup Worker with a port range of 40000-49999
   - Creates a Router with Opus audio and VP8 video codecs
   - Exports a function `createWebRtcTransportPair()` that creates send and receive WebRtcTransports
   - Sets up an AudioLevelObserver and logs active speaker events
5. Wire `src/mediaServer.ts` into my existing `src/server.ts` Express app so that the Worker starts on app boot.
6. Show me only real imports from `source/index.ts` and `source/WorkerTypes.ts` — do not invent any API.
7. Follow the patterns in the "Working examples" section of USAGE.md exactly.

Upstream package: user@example.com
Source root: source/ (maps to mediasoup node/src)

License and credit

mediasoup is released under the ISC License. See the LICENSE file in the upstream repository or source/ if present.

Upstream project: mediasoup on npm — maintained by Iñaki Baz Castillo, José Luis Millán, and Nazar Mokynskyi at versatica/mediasoup.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Self-Hosted WebRTC P2P Video Conferencing Platform

PHP, Laravel & Business Scripts

Free