The top-level exported module.

// Using ES6 import:
import * as mediasoup from "mediasoup";

// Or using destructuring assignment:
import {
  types,
  version,
  observer,
  createWorker,
  getSupportedRtpCapabilities,
  parseScalabilityMode
} from "mediasoup";

// Using CommonJS:
const mediasoup = require("mediasoup");

// Or using destructuring assignment:
const {
  types,
  version,
  observer,
  createWorker,
  getSupportedRtpCapabilities,
  parseScalabilityMode
} = require("mediasoup");

LogEventListeners

mediasoup.types

It exposes all public TypeScript types exported by mediasoup.

@type Object, read only

import { types as mediasoupTypes } from "mediasoup";

let worker: mediasoupTypes.Worker;
let rtpParameters: mediasoupTypes.RtpParameters;

// or alternatively:

import { Worker, RtpParameters } from "mediasoup/node/lib/types";

let worker: Worker;
let rtpParameters: RtpParameters;

In addition to those types it also exports AppData TypeScript type, which can be used to specify the custom appData content of each mediasoup entity.

export type AppData =
{
  [key: string]: unknown;
};

mediasoup.version

The mediasoup version.

@type String, read only

console.log(mediasoup.version);
// => "3.0.0"

mediasoup.workerBin

The absolute path to the mediasoup-worker binary.

@type String, read only

console.log(mediasoup.workerBin);
// => "/home/deploy/media-server-app/node_modules/mediasoup/worker/out/Release/mediasoup-worker"

mediasoup.observer

An event emitter that allows the application (or third party libraries) monitor Worker instances created by the application. See the Observer Events section below.

@type EventEmitter, read only

mediasoup.setLogEventListeners(listeners)

Set event listeners for mediasoup generated logs. If called with no arguments then no events will be emitted.

mediasoup.setLogEventListeners(
  {
    ondebug: undefined,
    onwarn: (namespace, log) => {
      MyEnterpriseLogger.warn(`${namespace} ${log}`);
    },
    onerror: (namespace, log, error) => {
      if (error) {
        MyEnterpriseLogger.error(`${namespace} ${log}: ${error}`);
      } else {
        MyEnterpriseLogger.error(`${namespace} ${log}`);
      }
    }
  });

mediasoup.createWorker<WorkerAppData>(settings)

Creates a new worker with the given settings.

@async

@returns Worker

const worker = await mediasoup.createWorker<{ foo: number }>(
  {
    logLevel            : "warn",
    dtlsCertificateFile : "/home/foo/dtls-cert.pem",
    dtlsPrivateKeyFile  : "/home/foo/dtls-key.pem",
    appData             : { foo: 123 }
  });

mediasoup.getSupportedRtpCapabilities()

Returns a cloned copy of the mediasoup supported RTP capabilities, specifically the content of the mediasoup/node/src/supportedRtpCapabilities.ts file.

@returns RtpCapabilities

const rtpCapabilities = mediasoup.getSupportedRtpCapabilities();

console.log(rtpCapabilities);
// => { codecs: [...], headerExtensions: [...] }

mediasoup.parseScalabilityMode(scalabilityMode)

Parses the given scalabilityMode string according to the rules in webrtc-svc.

@returns ScalabilityMode:

• spatialLayers {@type Number} Number of spatial layers (by default 1).

• temporalLayers {@type Number} Number of temporal layers (by default 1).

mediasoup.parseScalabilityMode("L2T3");
// => { spatialLayers: 2, temporalLayers: 3 }

mediasoup.parseScalabilityMode("S3T3");
// => { spatialLayers: 3, temporalLayers: 3 }

mediasoup.parseScalabilityMode("L4T7_KEY_SHIFT");
// => { spatialLayers: 4, temporalLayers: 7 }

mediasoup.parseScalabilityMode(undefined);
// => { spatialLayers: 1, temporalLayers: 1 }

mediasoup.observer.on(“newworker”, fn(worker))

Emitted when a new worker is created.

mediasoup.observer.on("newworker", (worker) =>
{
  console.log("new worker created [pid:%d]", worker.pid);
});

A worker represents a mediasoup C++ subprocess that runs in a single CPU core and handles Router instances.

WorkerSettings

WorkerUpdateableSettings

WorkerResourceUsage

An object with the fields of the uv_rusage_t struct.

WorkerLogLevel

WorkerLogTag

worker.pid

The PID of the worker subprocess.

@type Number, read only

console.log(worker.pid);
// => 86665

worker.closed

Whether the worker is closed.

@type Boolean, read only

console.log(worker.closed);
// => false

worker.died

Whether the worker unexpectedly died. This flag is set when 'died' event fires.

@type Boolean, read only

worker.subprocessClosed

Whether the worker subprocessed is closed. It becomes true once the worker subprocess is completely closed and 'subprocessclose' event fires.

@type Boolean, read only

worker.appData

Custom data provided by the application in the worker factory method. The app can modify it at any time.

@type AppData

worker.observer

See the Observer Events section below.

@type EventEmitter, read only

worker.close()

Closes the worker. Triggers a “workerclose” event in all its routers.

worker.getResourceUsage()

Provides resource usage of the worker subprocess.

@async

@returns WorkerResourceUsage

const usage = await worker.getResourceUsage();

// =>
{
  ru_idrss: 0,
  ru_inblock: 0,
  ru_isrss: 0,
  ru_ixrss: 0,
  ru_majflt: 0,
  ru_maxrss: 46047232,
  ru_minflt: 11446,
  ru_msgrcv: 23641,
  ru_msgsnd: 40005,
  ru_nivcsw: 27926,
  ru_nsignals: 0,
  ru_nswap: 0,
  ru_nvcsw: 0,
  ru_oublock: 0,
  ru_stime: 1026,
  ru_utime: 3066
}

worker.updateSettings(settings)

Updates the worker settings in runtime. Just a subset of the worker settings can be updated.

@async

await worker.updateSettings({ logLevel: "warn" });

worker.createRouter<RouterAppData>(options)

Creates a new router.

@async

@returns Router

const mediaCodecs =
[
  {
    kind        : "audio",
    mimeType    : "audio/opus",
    clockRate   : 48000,
    channels    : 2
  },
  {
    kind       : "video",
    mimeType   : "video/H264",
    clockRate  : 90000,
    parameters :
    {
      "packetization-mode"      : 1,
      "profile-level-id"        : "42e01f",
      "level-asymmetry-allowed" : 1
    }
  }
];

const router = await worker.createRouter({ mediaCodecs });

worker.createWebRtcServer<WebRtcServerAppData>(options)

Creates a new WebRTC server.

@async

@returns WebRtcServer

const webRtcServer = await worker.createWebRtcServer(
  {
    listenInfos :
    [
      {
        protocol : 'udp',
        ip       : '9.9.9.9',
        port     : 20000
      },
      {
        protocol : 'tcp',
        ip       : '9.9.9.9',
        port     : 20000
      }
    ]
  });

worker.on(“died”, fn(error))

Emitted when the worker subprocess unexpectedly dies.

worker.on("died", (error) =>
{
  console.error("mediasoup worker died!: %o", error);
});

worker.on(“subprocessclose”, fn())

Emitted when the worker subprocess has closed completely. This event is emitted asynchronously once worker.close() has been called (or after 'died' event in case the worker subprocess abnormally died).

worker.on(“listenererror”, fn(eventName, error))

Emitted when an event listener given by the application throws. The exception is silently ignored internally to not break the internal state. By listening to this event, the application can be aware of exceptions happening in its given event listeners.

worker.observer.on(“close”, fn())

Emitted when the worker is closed for whatever reason.

worker.observer.on(“newrouter”, fn(router))

Emitted when a new router is created.

worker.observer.on("newrouter", (router) =>
{
  console.log("new router created [id:%s]", router.id);
});

worker.observer.on(“newwebrtcserver”, fn(router))

Emitted when a new router is created.

worker.observer.on("newwebrtcserver", (webRtcServer) =>
{
  console.log("new WebRTC server created [id:%s]", webRtcServer.id);
});

A router enables injection, selection and forwarding of media streams through Transport instances created on it.

RouterOptions

PipeToRouterOptions

PipeToRouterResult

router.id

Router identifier.

@type String, read only

console.log(router.id);
// => "15177e19-5665-4eba-9a6a-c6cf3db16259"

router.closed

Whether the router is closed.

@type Boolean, read only

router.rtpCapabilities

An Object with the RTP capabilities of the router. These capabilities are typically needed by mediasoup clients to compute their sending RTP parameters.

@type RtpCapabilities, read only

router.appData

Custom data provided by the application in the worker factory method. The app can modify it at any time.

@type AppData

router.observer

See the Observer Events section below.

@type EventEmitter, read only

router.close()

Closes the router. Triggers a “routerclose” event in all its transports and also “routerclose” event in all its RTP observers.

router.createWebRtcTransport<WebRtcTransportAppData>(options)

Creates a new WebRTC transport.

@async

@returns WebRtcTransport

const transport = await router.createWebRtcTransport(
  {
    webRtcServer : webRtcServer
    enableUdp    : true,
    enableTcp    : false
  });

const transport = await router.createWebRtcTransport(
  {
    listenInfos :
    [
      {
        protocol         : "udp", 
        ip               : "192.168.0.111", 
        announcedAddress : "88.12.10.41"
      }
    ]
  });

router.createPlainTransport<PlainTransportAppData>(options)

Creates a new plain transport.

@async

@returns PlainTransport

const transport = await router.createPlainTransport(
  {
    listenInfo : { protocol: "udp", ip: "a1:22:aA::08" },
    rtcpMux    : true,
    comedia    : true
  });

router.createPipeTransport<PipeTransportAppData>(options)

Creates a new pipe transport.

@async

@returns PipeTransport

const transport = await router.createPipeTransport(
  {
    listenInfo : { protocol: "udp", ip: "192.168.1.33" },
  });

router.createDirectTransport<DirectTransportAppData>(options)

Creates a new direct transport.

@async

@returns DirectTransport

const transport = await router.createDirectTransport();

router.pipeToRouter(options)

Pipes the given media or data producer into another router in the same host. It creates an underlying PipeTransport (if not previously created) that interconnects both routers.

This is specially useful to expand broadcasting capabilities (one to many) by interconnecting different routers that run in separate workers (so in different CPU cores).

@async

@returns PipeToRouterResult

// Have two workers.
const worker1 = await mediasoup.createWorker();
const worker2 = await mediasoup.createWorker();

// Create a router in each worker.
const router1 = await worker1.createRouter({ mediaCodecs });
const router2 = await worker2.createRouter({ mediaCodecs });

// Produce in router1.
const transport1 = await router1.createWebRtcTransport({ ... });
const producer1 = await transport1.produce({ ... });

// Pipe producer1 into router2.
await router1.pipeToRouter({ producerId: producer1.id, router: router2 });

// Consume producer1 from router2.
const transport2 = await router2.createWebRtcTransport({ ... });
const consumer2 = await transport2.consume({ producerId: producer1.id, ... });

router.createActiveSpeakerObserver<ActiveSpeakerObserverAppData>(options)

Creates a new active speaker observer.

@async

@returns ActiveSpakerObserver

const activeSpeakerObserver = await router.createActiveSpeakerObserver(
  {
    interval   : 500
  });

router.createAudioLevelObserver<AudioLevelObserverAppData>(options)

Creates a new audio level observer.

@async

@returns AudioLevelObserver

const audioLevelObserver = await router.createAudioLevelObserver(
  {
    maxEntries : 1,
    threshold  : -70,
    interval   : 2000
  });

router.canConsume({ producerId, rtpCapabilities })

Whether the given RTP capabilities are valid to consume the given producer.

@returns Boolean

if (router.canConsume({ producerId, rtpCapabilities }))
{
  // Consume the producer by calling transport.consume({ producerId, rtpCapabilities }).
}

router.updateMediaCodecs(mediaCodecs)

Updates the media codecs of the router. Once invoked, resulting router.rtpCapabilities change.

@returns Boolean

if (router.updateMediaCodecs({ producerId, rtpCapabilities }))
{
  // Consume the producer by calling transport.consume({ producerId, rtpCapabilities }).
}

router.on(“workerclose”, fn())

Emitted when the worker this router belongs to is closed for whatever reason. The router itself is also closed. A “routerclose” event is triggered in all its transports and a “routerclose” event is triggered in all its RTP observers.

router.on("workerclose", () =>
{
  console.log("worker closed so router closed");
});

router.on(“listenererror”, fn(eventName, error))

Emitted when an event listener given by the application throws. The exception is silently ignored internally to not break the internal state. By listening to this event, the application can be aware of exceptions happening in its given event listeners.

router.observer.on(“close”, fn())

Emitted when the router is closed for whatever reason.

router.observer.on(“newtransport”, fn(transport))

Emitted when a new transport is created.

router.observer.on("newtransport", (transport) =>
{
  console.log("new transport created [id:%s]", transport.id);
});

router.observer.on(“newrtpobserver”, fn(rtpObserver))

Emitted when a new RTP observer is created.

router.observer.on("newrtpobserver", (rtpObserver) =>
{
  console.log("new RTP observer created [id:%s]", rtpObserver.id);
});

A WebRTC server brings the ability to listen on a single UDP/TCP port to WebRtcTransports. Instead of passing listenInfos to router.createWebRtcTransport() pass webRtcServer with an instance of a WebRtcServer so the new WebRTC transport will not listen on its own IP:port(s) but will have its network traffic handled by the WebRTC server instead.

webRtcServer.id

WebRTC server identifier.

@type String, read only

webRtcServer.closed

Whether the WebRTC server is closed.

@type Boolean, read only

webRtcServer.appData

Custom data provided by the application in the worker factory method. The app can modify it at any time.

@type AppData

webRtcServer.observer

See the Observer Events section below.

@type EventEmitter, read only

webRtcServer.close()

Closes the WebRTC server. Triggers a “listenserverclose” event in all WebRTC transports using this WebRTC server.

webRtcServer.on(“workerclose”, fn())

Emitted when the worker this WebRTC server belongs to is closed for whatever reason. The WebRTC server itself is also closed. A “listenserverclose” event is triggered in all WebRTC transports using this WebRTC server.

webRtcServer.on("workerclose", () =>
{
  console.log("worker closed so webRtcServer closed");
});

webRtcServer.on(“listenererror”, fn(eventName, error))

Emitted when an event listener given by the application throws. The exception is silently ignored internally to not break the internal state. By listening to this event, the application can be aware of exceptions happening in its given event listeners.

webRtcServer.observer.on(“close”, fn())

Emitted when the WebRTC server is closed for whatever reason.

webRtcServer.observer.on(“webrtctransporthandled”, fn(webRtcTransport))

Emitted when a new WebRTC transport that uses this WebRTC server is created.

webRtcServer.observer.on(“webrtctransportunhandled”, fn(webRtcTransport))

Emitted when a new WebRTC transport that uses this WebRTC server is closed. It's also emitted for all WebRTC transports handled by this WebRTC server when the latter is closed.

@abstract

A transport connects an endpoint with a mediasoup router and enables transmission of media in both directions by means of Producer, Consumer, DataProducer and DataConsumer instances created on it.

mediasoup implements the following transport classes:

• WebRtcTransport
• PlainTransport
• PipeTransport
• DirectTransport

TransportListenInfo

TransportListenIp

TransportPortRange

TransportSocketFlags

TransportTuple

TransportTraceEventData

TransportType

TransportTraceEventType

SctpState

These are properties common to all transport classes. Each transport class may define new ones.

transport.id

Transport identifier.

@type String, read only

transport.closed

Whether the transport is closed.

@type Boolean, read only

transport.type

Transport type.

@type TransportType, read only

transport.appData

Custom data provided by the application in the worker factory method. The app can modify it at any time.

@type AppData

transport.appData.foo = "bar";

transport.appData = { foo: "bar", bar: 123 };

transport.observer

See the Observer Events section below.

@type EventEmitter, read only

These are methods common to all transport classes. Each transport class may define new ones.

transport.close()

Closes the transport. Triggers a “transportclose” event in all its producers and also “transportclose” event in all its consumers.

transport.getStats()

Returns current RTC statistics of the transport. Each transport class produces a different set of statistics.

@async

@abstract

@returns Array<Object>

transport.connect()

Provides the transport with the remote endpoint's transport parameters. Each transport class requires specific arguments in this method. Check the connect() method in each one of them.

@async

@abstract

transport.setMaxIncomingBitrate(bitrate)

Set maximum incoming bitrate for media streams sent by the remote endpoint over this transport.

@async

await transport.setMaxIncomingBitrate(3500000);

transport.setMaxOutgoingBitrate(bitrate)

Set maximum outgoing bitrate for media streams sent by mediasoup to the remote endpoint over this transport. By calling this method, the estimated outgoing bitrate is overridden if given value is lower than the estimated one.

@async

await transport.setMaxOutgoingBitrate(2000000);

transport.setMinOutgoingBitrate(bitrate)

Set minimum outgoing bitrate for media streams sent by mediasoup to the remote endpoint over this transport. By calling this method, the estimated outgoing bitrate is overridden if given value is higher than the estimated one.

@async

await transport.setMinOutgoingBitrate(1000000);

transport.produce<ProducerAppData>(options)

Instructs the router to receive audio or video RTP (or SRTP depending on the transport class). This is the way to inject media into mediasoup.

@async

@returns Producer

const producer = await transport.produce(
  {
    kind          : "video",
    rtpParameters :
    {
      mid    : "1",
      codecs :
      [
        {
          mimeType    : "video/VP8",
          payloadType : 101,
          clockRate   : 90000,
          rtcpFeedback :
          [
            { type: "nack" },
            { type: "nack", parameter: "pli" },
            { type: "ccm", parameter: "fir" },
            { type: "goog-remb" }
          ]
        },
        {
          mimeType    : "video/rtx",
          payloadType : 102,
          clockRate   : 90000,
          parameters  : { apt: 101 }
        }
      ],
      headerExtensions :
      [
        {
          id  : 2, 
          uri : "urn:ietf:params:rtp-hdrext:sdes:mid"
        },
        { 
          id  : 3, 
          uri : "urn:ietf:params:rtp-hdrext:sdes:rtp-stream-id"
        },
        { 
          id  : 5, 
          uri: "urn:3gpp:video-orientation" 
        },
        { 
          id  : 6, 
          uri : "http://www.webrtc.org/experiments/rtp-hdrext/abs-send-time"
        }
      ],
      encodings :
      [
        { rid: "r0", active: true, maxBitrate: 100000 },
        { rid: "r1", active: true, maxBitrate: 300000 },
        { rid: "r2", active: true, maxBitrate: 900000 }
      ],
      rtcp :
      {
        cname : "Zjhd656aqfoo"
      }
    }
  });

transport.consume<ConsumerAppData>(options)

Instructs the router to send audio or video RTP (or SRTP depending on the transport class). This is the way to extract media from mediasoup.

@async

@returns Consumer

const consumer = await transport.consume(
  {
    producerId      : "a7a955cf-fe67-4327-bd98-bbd85d7e2ba3",
    rtpCapabilities :
    {
      codecs :
      [
        {
          mimeType             : "audio/opus",
          kind                 : "audio",
          clockRate            : 48000,
          preferredPayloadType : 100,
          channels             : 2
        },
        {
          mimeType             : "video/H264",
          kind                 : "video",
          clockRate            : 90000,
          preferredPayloadType : 101,
          rtcpFeedback         :
          [
            { type: "nack" },
            { type: "nack", parameter: "pli" },
            { type: "ccm", parameter: "fir" },
            { type: "goog-remb" }
          ],
          parameters :
          {
            "level-asymmetry-allowed" : 1,
            "packetization-mode"      : 1,
            "profile-level-id"        : "4d0032"
          }
        },
        {
          mimeType             : "video/rtx",
          kind                 : "video",
          clockRate            : 90000,
          preferredPayloadType : 102,
          rtcpFeedback         : [],
          parameters           :
          {
            apt : 101
          }
        }
      ],
      headerExtensions :
      [
        {
          kind             : "video",
          uri              : "http://www.webrtc.org/experiments/rtp-hdrext/abs-send-time", // eslint-disable-line max-len
          preferredId      : 4,
          preferredEncrypt : false
        },
        {
          kind             : "audio",
          uri              : "urn:ietf:params:rtp-hdrext:ssrc-audio-level",
          preferredId      : 8,
          preferredEncrypt : false
        },
        {
          kind             : "video",
          uri              : "urn:3gpp:video-orientation",
          preferredId      : 9,
          preferredEncrypt : false
        },
        {
          kind             : "video",
          uri              : "urn:ietf:params:rtp-hdrext:toffset",
          preferredId      : 10,
          preferredEncrypt : false
        }
      ]
    }
  });

transport.produceData<DataProducerAppData>(options)

Instructs the router to receive data messages. Those messages can be delivered by an endpoint via SCTP protocol (AKA DataChannel in WebRTC) or can be directly sent from the Node.js application if the transport is a DirectTransport.

@async

@returns DataProducer

// Using SCTP:
const dataProducer = await transport.produceData(
  {
    sctpStreamParameters :
    {
      streamId : 4,
      ordered  : true
    },
    label : 'foo'
  });

// Using a direct transport:
const dataProducer = await transport.produceData();

transport.consumeData<DataConsumerAppData>(options)

Instructs the router to send data messages to the endpoint via SCTP protocol (AKA DataChannel in WebRTC) or directly to the Node.js process if the transport is a DirectTransport.

@async

@returns DataConsumer

const dataConsumer = await transport.consumeData(
  {
    dataProducerId : "a7a955cf-fe67-4327-bd98-bbd85d7e2ba4"
  });

transport.enableTraceEvent(types)

Instructs the transport to emit “trace” events. For monitoring purposes. Use with caution.

@async

await transport.enableTraceEvent([ "probation" ]);

transport.on("trace", (trace) =>
{
  // trace.type can just be "probation".
});

These are events common to all transport classes. Each transport class may define new ones.

transport.on(“routerclose”, fn())

Emitted when the router this transport belongs to is closed for whatever reason. The transport itself is also closed. A “transportclose” event is triggered in all its producers and a “transportclose” event is triggered in all its consumers.

transport.on("routerclose", () =>
{
  console.log("router closed so transport closed");
});

transport.on(“listenserverclose”, fn())

Just emitted in WebRTC transports when the WebRTC server the transport uses is closed for whatever reason. The transport itself is also closed. A “transportclose” event is triggered in all its producers and a “transportclose” event is triggered in all its consumers.

transport.on("listenserverclose", () =>
{
  console.log("WebRTC server closed so transport closed");
});

transport.on(“trace”, fn(trace))

See enableTraceEvent() method.

transport.on("trace", (trace) =>
{
  console.log(trace);
});

transport.on(“listenererror”, fn(eventName, error))

Emitted when an event listener given by the application throws. The exception is silently ignored internally to not break the internal state. By listening to this event, the application can be aware of exceptions happening in its given event listeners.

These are observer events common to all transport classes. Each transport class may define new ones.

transport.observer.on(“close”, fn())

Emitted when the transport is closed for whatever reason.

transport.observer.on(“newproducer”, fn(producer))

Emitted when a new producer is created.

transport.observer.on("newproducer", (producer) =>
{
  console.log("new producer created [id:%s]", producer.id);
});

transport.observer.on(“newconsumer”, fn(consumer))

Emitted when a new consumer is created.

transport.observer.on("newconsumer", (consumer) =>
{
  console.log("new consumer created [id:%s]", consumer.id);
});

transport.observer.on(“newdataproducer”, fn(dataProducer))

Emitted when a new data producer is created.

transport.observer.on("newdataproducer", (dataProducer) =>
{
  console.log("new data producer created [id:%s]", dataProducer.id);
});

transport.observer.on(“newdataconsumer”, fn(dataConsumer))

Emitted when a new data consumer is created.

transport.observer.on("newdataconsumer", (dataConsumer) =>
{
  console.log("new data consumer created [id:%s]", dataConsumer.id);
});

transport.observer.on(“trace”, fn(trace))

Same as the trace event.

@inherits Transport

A WebRTC transport represents a network path negotiated by both, a WebRTC endpoint and mediasoup, via ICE and DTLS procedures. A WebRTC transport may be used to receive media, to send media or to both receive and send. There is no limitation in mediasoup. However, due to their design, mediasoup-client and libmediasoupclient require separate WebRTC transports for sending and receiving.

WebRtcTransportOptions

IceParameters

IceCandidate

DtlsParameters

DtlsFingerprint

The hash function algorithm (as defined in the “Hash function Textual Names” registry initially specified in RFC 4572 Section 8) and its corresponding certificate fingerprint value (in lowercase hex string as expressed utilizing the syntax of “fingerprint” in RFC 4572 Section 5).

IceState

DtlsRole

DtlsState

See also Transport Properties.

webRtcTransport.iceRole

Local ICE role. Due to the mediasoup ICE Lite design, this is always “controlled”.

@type String, read only

webRtcTransport.iceParameters

Local ICE parameters.

@type IceParameters, read only

webRtcTransport.iceCandidates

Local ICE candidates.

@type Array<IceCandidate>, read only

webRtcTransport.iceState

Current ICE state.

@type IceState, read only

webRtcTransport.iceSelectedTuple

The selected transport tuple if ICE is in “connected” or “completed” state. It is undefined if ICE is not established (no working candidate pair was found).

@type TransportTuple, read only

webRtcTransport.dtlsParameters

Local DTLS parameters.

@type DtlsParameters, read only

webRtcTransport.dtlsState

Current DTLS state.

@type DtlsState, read only

webRtcTransport.dtlsRemoteCert

The remote certificate in PEM format. It is set once the DTLS state becomes “connected”.

@type String, read only

webRtcTransport.sctpParameters

Local SCTP parameters. Or undefined if SCTP is not enabled.

@type SctpParameters, read only

webRtcTransport.sctpState

Current SCTP state. Or undefined if SCTP is not enabled.

@type SctpState, read only

See also Transport Methods.

webRtcTransport.getStats()

Returns current RTC statistics of the WebRTC transport.

@async

@override

@returns Array<ProducerStat>

webRtcTransport.connect({ dtlsParameters })

Provides the WebRTC transport with the endpoint parameters.

@async

@overrides

await webRtcTransport.connect(
  {
    dtlsParameters :
    {
      role         : "server",
      fingerprints :
      [
        {
          algorithm : "sha-256",
          value     : "E5:F5:CA:A7:2D:93:E6:16:AC:21:09:9F:23:51:62:8C:D0:66:E9:0C:22:54:2B:82:0C:DF:E0:C5:2C:7E:CD:53"
        }
      ]
    }
  });

webRtcTransport.restartIce()

Restarts the ICE layer by generating new local ICE parameters that must be signaled to the remote endpoint.

@async

@returns IceParameters

const iceParameters = await webRtcTransport.restartIce();

// Send the new ICE parameters to the endpoint.

See also Transport Events.

webRtcTransport.on(“icestatechange”, fn(iceState))

Emitted when the transport ICE state changes.

webRtcTransport.on("icestatechange", (iceState) =>
{
  console.log("ICE state changed to %s", iceState);
});

webRtcTransport.on(“iceselectedtuplechange”, fn(iceSelectedTuple))

Emitted after ICE state becomes “completed” and when the ICE selected tuple changes.

webRtcTransport.on(“dtlsstatechange”, fn(dtlsState))

Emitted when the transport DTLS state changes.

webRtcTransport.on(“sctpstatechange”, fn(sctpState))

Emitted when the transport SCTP state changes.

See also Transport Observer Events.

webRtcTransport.observer.on(“icestatechange”, fn(iceState))

Same as the icestatechange event.

webRtcTransport.observer.on(“iceselectedtuplechange”, fn(iceSelectedTuple))

Same as the iceselectedtuplechange event.

webRtcTransport.observer.on(“dtlsstatechange”, fn(dtlsState))

Same as the dtlsstatechange event.

webRtcTransport.observer.on(“sctpstatechange”, fn(sctpState))

Same as the sctpstatechange event.

@inherits Transport

A plain transport represents a network path through which RTP, RTCP (optionally secured with SRTP) and SCTP (DataChannel) is transmitted.

PlainTransportOptions

See also Transport Properties.

plainTransport.tuple

The transport tuple. If RTCP-mux is enabled (rtcpMux is set), this tuple refers to both RTP and RTCP.

@type TransportTuple, read only

plainTransport.rtcpTuple

The transport tuple for RTCP. If RTCP-mux is enabled (rtcpMux is set), its value is undefined.

@type TransportTuple, read only

plainTransport.sctpParameters

Local SCTP parameters. Or undefined if SCTP is not enabled.

@type SctpParameters, read only

plainTransport.sctpState

Current SCTP state. Or undefined if SCTP is not enabled.

@type SctpState, read only

plainTransport.srtpParameters

Local SRTP parameters representing the crypto suite and key material used to encrypt sending RTP and SRTP. Note that, if comedia mode is set, these local SRTP parameters may change after calling connect() with the remote SRTP parameters (to override the local SRTP crypto suite with the one given in connect()).

@type SrtpParameters, read only

See also Transport Methods.

plainTransport.getStats()

Returns current RTC statistics of the WebRTC transport.

@async

@override

@returns Array<PlainTransportStat>

plainTransport.connect({ ip, port, rtcpPort, srtpParameters })

Provides the plain transport with the endpoint parameters.

• If comedia is enabled in this plain transport and SRTP is not, connect() must not be called.
• If comedia is enabled and SRTP is also enabled (enableSrtp was set in the router.createPlainTransport() options) then connect() must be called with just the remote srtpParameters.
• If comediap is disabled, connect() must be eventually called with remote ip, port, optional rtcpPort (if RTCP-mux is not enabled) and optional srtpParameters (if SRTP is enabled).

@async

@overrides

// Calling connect() on a PlainTransport created with comedia and rtcpMux set.
await plainTransport.connect(
  {
    ip   : '1.2.3.4',
    port : 9998
  });

// Calling connect() on a PlainTransport created with comedia unset and rtcpMux
// also unset.
await plainTransport.connect(
  {
    ip       : '1.2.3.4',
    port     : 9998,
    rtcpPort : 9999
  });

// Calling connect() on a PlainTransport created with comedia set and
// enableSrtp enabled.
await plainTransport.connect(
  {
    srtpParameters :
    {
      cryptoSuite : 'AES_CM_128_HMAC_SHA1_80',
      keyBase64   : 'ZnQ3eWJraDg0d3ZoYzM5cXN1Y2pnaHU5NWxrZTVv'
    }
  });

// Calling connect() on a PlainTransport created with comedia unset, rtcpMux
// set and enableSrtp enabled.
await plainTransport.connect(
  {
    ip             : '1.2.3.4',
    port           : 9998,
    srtpParameters :
    {
      cryptoSuite : 'AEAD_AES_256_GCM',
      keyBase64   : 'YTdjcDBvY2JoMGY5YXNlNDc0eDJsdGgwaWRvNnJsamRrdG16aWVpZHphdHo='
    }
  });

See also Transport Events.

plainTransport.on(“tuple”, fn(tuple))

Emitted after the remote RTP origin has been discovered. Just emitted if comedia mode was set.

plainTransport.on(“rtcptuple”, fn(rtcpTuple))

Emitted after the remote RTCP origin has been discovered. Just emitted if comedia mode was set and rtcpMux was not.

plainTransport.on(“sctpstatechange”, fn(sctpState))

Emitted when the transport SCTP state changes.

See also Transport Observer Events.

plainTransport.observer.on(“tuple”, fn(tuple))

Same as the tuple event.

plainTransport.observer.on(“rtcptuple”, fn(rtcpTuple))

Same as the rtcpTuple event.

plainTransport.observer.on(“sctpstatechange”, fn(sctpState))

Same as the sctpstatechange event.

@inherits Transport

A pipe transport represents a network path through which RTP, RTCP (optionally secured with SRTP) and SCTP (DataChannel) is transmitted. Pipe transports are intented to intercommunicate two Router instances collocated on the same host or on separate hosts.

PipeTransportOptions

See also Transport Properties.

pipeTransport.tuple

The transport tuple. It refers to both RTP and RTCP since pipe transports use RTCP-mux by design.

@type TransportTuple, read only

pipeTransport.sctpParameters

Local SCTP parameters. Or undefined if SCTP is not enabled.

@type SctpParameters, read only

pipeTransport.sctpState

Current SCTP state. Or undefined if SCTP is not enabled.

@type SctpState, read only

pipeTransport.srtpParameters

Local SRTP parameters representing the crypto suite and key material used to encrypt sending RTP and SRTP. Those parameters must be given to the paired pipeTransport in the connect() method.

@type SrtpParameters, read only

See also Transport Methods.

pipeTransport.getStats()

Returns current RTC statistics of the pipe transport.

@async

@override

@returns Array<PipeTransportStat>

pipeTransport.connect({ ip, port })

Provides the pipe RTP transport with the remote parameters.

@async

@overrides

await pipeTransport.connect(
  {
    ip             : '1.2.3.4',
    port           : 9999,
    srtpParameters :
    {
      cryptoSuite : 'AEAD_AES_256_GCM',
      keyBase64   : 'YTdjcDBvY2JoMGY5YXNlNDc0eDJsdGgwaWRvNnJsamRrdG16aWVpZHphdHo='
    }
  });

See also Transport Events.

pipeTransport.on(“sctpstatechange”, fn(sctpState))

Emitted when the transport SCTP state changes.

See also Transport Observer Events.

pipeTransport.observer.on(“sctpstatechange”, fn(sctpState))

Same as the sctpstatechange event.

@inherits Transport

A direct transport represents a direct connection between the mediasoup Node.js process and a Router instance in a mediasoup-worker subprocess.

A direct transport can be used to directly send and receive data messages from/to Node.js by means of DataProducers and DataConsumers of type 'direct' created on a direct transport. Direct messages sent by a DataProducer in a direct transport can be consumed by endpoints connected through a SCTP capable transport (WebRtcTransport, PlainTransport, PipeTransport) and also by the Node.js application by means of a DataConsumer created on a DirectTransport (and vice-versa: messages sent over SCTP/DataChannel can be consumed by the Node.js application by means of a DataConsumer created on a DirectTransport).

A direct transport can also be used to inject and directly consume RTP and RTCP packets in Node.js by using the producer.send(rtpPacket) and consumer.on('rtp') API (plus directTransport.sendRtcp(rtcpPacket) and directTransport.on('rtcp') API).

DirectTransportOptions

See also Transport Properties.

See also Transport Methods.

directTransport.getStats()

Returns current RTC statistics of the direct transport.

@async

@override

@returns Array<DirectTransportStat>

directTransport.connect()

It's a no-op. There is no need to call this method on direct transports (they are always connected).

@async

@overrides

directTransport.setMaxIncomingBitrate(options)

@async

@overrides

directTransport.setMaxOutgoingBitrate(options)

@async

@overrides

directTransport.setMinOutgoingBitrate(options)

@async

@overrides

See also Transport Events.

directTransport.on(“rtcp”, fn(rtcpPacket))

Emitted when the direct transport receives a RTCP packet from its router.

directTransport.on("rtcp", (rtcpPacket) =>
{
  // Do stuff with the binary RTCP packet.
});

See also Transport Observer Events.

A producer represents an audio or video source being injected into a mediasoup router. It's created on top of a transport that defines how the media packets are carried.

ProducerOptions

ProducerScore

ProducerVideoOrientation

As documented in WebRTC Video Processing and Codec Requirements.

ProducerTraceEventData

ProducerType

ProducerTraceEventType

producer.id

Producer identifier.

@type String, read only

producer.closed

Whether the producer is closed.

@type Boolean, read only

producer.kind

The media kind (“audio” or “video”).

@type MediaKind, read only

producer.rtpParameters

Producer RTP parameters.

@type RtpSendParameters, read only

producer.type

Producer type.

@type ProducerType, read only

producer.paused

Whether the producer is paused.

@type Boolean, read only

producer.score

The score of each RTP stream being received, representing their tranmission quality.

@type Array<ProducerScore>, read only

producer.appData

Custom data provided by the application in the worker factory method. The app can modify it at any time.

@type AppData

producer.observer

See the Observer Events section below.

@type EventEmitter, read only

producer.close()

Closes the producer. Triggers a “producerclose” event in all its associated consumers.

producer.getStats()

Returns current RTC statistics of the producer.

@async

@returns Array<ProducerStat>

producer.pause()

Pauses the producer (no RTP is sent to its associated consumers). Triggers a “producerpause” event in all its associated consumers.

@async

producer.resume()

Resumes the producer (RTP is sent again to its associated consumers). Triggers a “producerresume” event in all its associated consumers.

@async

producer.enableTraceEvent(types)

Instructs the producer to emit “trace” events. For monitoring purposes. Use with caution.

@async

await producer.enableTraceEvent([ "rtp", "pli" ]);

producer.on("trace", (trace) =>
{
  // trace.type can be "rtp" or "pli".
});

producer.send(rtpPacket)

Sends a RTP packet from the Node.js process.

const producer = await directTransport.produce(
  {
    kind          : "audio", 
    rtpParameters : { ... },
  });

// Send a RTP packet.
producer.send(rtpPacket);

producer.on(“transportclose”, fn())

Emitted when the transport this producer belongs to is closed for whatever reason. The producer itself is also closed. A “producerclose” event is triggered in all its associated consumers.

producer.on("transportclose", () =>
{
  console.log("transport closed so producer closed");
});

producer.on(“score”, fn(score))

Emitted when the producer score changes.

producer.on(“videoorientationchange”, fn(videoOrientation))

Emitted when the video orientation changes. This is just possible if the “urn:3gpp:video-orientation” RTP extension has been negotiated in the producer RTP parameters.

producer.on(“trace”, fn(trace))

See enableTraceEvent() method.

producer.on("trace", (trace) =>
{
  console.log(trace);
});

producer.on(“listenererror”, fn(eventName, error))

Emitted when an event listener given by the application throws. The exception is silently ignored internally to not break the internal state. By listening to this event, the application can be aware of exceptions happening in its given event listeners.

producer.observer.on(“close”, fn())

Emitted when the producer is closed for whatever reason.

producer.observer.on(“pause”, fn())

Emitted when the producer is paused.

producer.observer.on(“resume”, fn())

Emitted when the producer is resumed.

producer.observer.on(“score”, fn(score))

Same as the score event.

producer.observer.on(“videoorientationchange”, fn(videoOrientation))

Same as the videoorientationchange event.

producer.observer.on(“trace”, fn(trace))

Same as the trace event.

A consumer represents an audio or video source being forwarded from a mediasoup router to an endpoint. It's created on top of a transport that defines how the media packets are carried.

ConsumerOptions

ConsumerLayers

ConsumerScore

ConsumerTraceEventData

ConsumerType

ConsumerTraceEventType

consumer.id

Consumer identifier.

@type String, read only

consumer.producerId

The associated producer identifier.

@type String, read only

consumer.closed

Whether the consumer is closed.

consumer.kind

The media kind (“audio” or “video”).

@type MediaKind, read only

consumer.rtpParameters

Consumer RTP parameters.

@type RtpReceiveParameters, read only

consumer.type

Consumer type.

@type ConsumerType, read only

consumer.paused

Whether the consumer is paused. It does not take into account whether the associated producer is paused.

@type Boolean, read only

consumer.producerPaused

Whether the associated producer is paused.

@type Boolean, read only

consumer.score

The score of the RTP stream being sent, representing its tranmission quality.

@type ConsumerScore, read only

consumer.preferredLayers

Preferred spatial and temporal layers (see setPreferredLayers() method). For simulcast and SVC consumers, undefined otherwise.

@type ConsumerLayers|Undefined, read only

consumer.currentLayers

Currently active spatial and temporal layers (for simulcast and SVC consumers only). It's undefined if no layers are being sent to the consuming endpoint at this time (or if the consumer is consuming from a simulcast or svc producer).

@type ConsumerLayers|Undefined, read only

consumer.priority

Consumer priority (see setPriority() method).

@type Number, read only

consumer.appData

Custom data provided by the application in the worker factory method. The app can modify it at any time.

@type AppData

consumer.observer

See the Observer Events section below.

@type EventEmitter, read only

consumer.close()

Closes the consumer.

consumer.getStats()

Returns current RTC statistics of the consumer.

@async

@returns Array<ConsumerStat>

consumer.pause()

Pauses the consumer (no RTP is sent to the consuming endpoint).

@async

consumer.resume()

Resumes the consumer (RTP is sent again to the consuming endpoint).

@async

consumer.setPreferredLayers(preferredLayers)

Sets the preferred (highest) spatial and temporal layers to be sent to the consuming endpoint. Just valid for simulcast and SVC consumers.

@async

await consumer.setPreferredLayers({ spatialLayer: 3 });

consumer.setPriority(priority)

Sets the priority for this consumer. It affects how the estimated outgoing bitrate in the transport (obtained via transport-cc or REMB) is distributed among all video consumers, by priorizing those with higher priority.

@async

await consumer.setPriority(2);

consumer.unsetPriority()

Unsets the priority for this consumer (it sets it to its default value 1).

@async

await consumer.unsetPriority();

consumer.requestKeyFrame()

Request a key frame to the associated producer. Just valid for video consumers.

@async

consumer.enableTraceEvent(types)

Instructs the consumer to emit “trace” events. For monitoring purposes. Use with caution.

@async

await consumer.enableTraceEvent([ "rtp", "pli", "fir" ]);

consumer.on("trace", (trace) =>
{
  // trace.type can be "rtp" or "pli" or "fir".
});