The top-level exported module.

// Using ES6 import.
import * as mediasoupClient from "mediasoup-client";

// Or using destructuring assignment:
import {
  types,
  version,
  Device,
  detectDevice,
  parseScalabilityMode,
  debug
} from "mediasoup-client";

// Using CommonJS.
const mediasoupClient = require("mediasoup-client");

// Or using destructuring assignment:
const {
  types,
  version,
  Device,
  detectDevice,
  parseScalabilityMode,
  debug
} = require("mediasoup-client");

mediasoupClient.types

An Object holding all classes and TypeScript types exported by mediasoup-client.

@type Object, read only

import { types as mediasoupTypes } from "mediasoup-client";

let producer: mediasoupTypes.Producer;
let rtpParameters: mediasoupTypes.RtpParameters;

// or alternatively:

import { Producer, RtpParameters } from "mediasoup-client/lib/types";

let producer: Producer;
let rtpParameters: RtpParameters;

mediasoupClient.version

The mediasoup-client version.

@type String, read only

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

mediasoupClient.debug

Exposes the debug dependency used by mediasoup-client. Useful if you need to enable/disable debug namespaces programatically.

mediasoupClient.Device

The main Device class.

@type Device, read only

const device = new mediasoupClient.Device();

mediasoupClient.detectDevice(userAgent)

Performs current browser/device detection and returns the corresponding mediasoup-client WebRTC handler name (or nothing if the browser/device is not supported).

@async

@returns BuiltinHandlerName | undefined

const handlerName = mediasoupClient.detectDevice();

if (handlerName) {
  console.log("detected handler: %s", handlerName);
} else {
  console.warn("no suitable handler found for current browser/device");
}

mediasoupClient.parseScalabilityMode(scalabilityMode)

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

@returns Object:

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

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

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

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

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

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

A device represents an endpoint that connects to a mediasoup Router to send and/or receive media.

DeviceOptions

const device = new mediasoupClient.Device({ handlerName: "Chrome67" });

DeviceSctpCapabilities

BuiltinHandlerName

new Device(options)

Creates a new device.

@throws UnsupportedError, if the current browser/device is not supported.

let device;

try
{
  device = new mediasoupClient.Device();
}
catch (error)
{
  if (error.name === 'UnsupportedError')
    console.warn('browser not supported');
}

device.handlerName

The selected handler class name.

@returns String, read only

console.log(device.handlerName);
// => "Chrome74"

device.loaded

Whether the device has been loaded (see the load() method).

@returns Boolean

device.rtpCapabilities

The device RTP capabilities, generated by combining both the underlying WebRTC capabilities and the router RTP capabilities (see the load() method).

@returns RtpCapabilities, read only

@throws InvalidStateError, if device not loaded

device.sctpCapabilities

The device SCTP capabilities.

@returns DeviceSctpCapabilities, read only

@throws InvalidStateError, if device not loaded

device.observer

See the Observer Events section below.

@type EventEmitter, read only

device.load({ routerRtpCapabilities })

Loads the device with the RTP capabilities of the mediasoup router. This is how the device knows about the allowed media codecs and other settings.

@async

@throws InvalidStateError, if device already loaded

@throws TypeError, if invalid arguments

await device.load({ routerRtpCapabilities });
// Now the device is ready.

device.canProduce(kind)

Whether the device can produce media of the given kind. This depends on the media codecs enabled in the mediasoup router and the media capabilities of the browser/device.

@returns Boolean

@throws InvalidStateError, if device not loaded

@throws TypeError, if invalid kind

if (device.canProduce("video"))
{
  // Do getUserMedia() and produce video.
}

device.createSendTransport(options)

Creates a new WebRTC transport to send media. The transport must be previously created in the mediasoup router via router.createWebRtcTransport().

@returns Transport

@throws InvalidStateError, if device not loaded

@throws TypeError, if invalid arguments

const transport = device.createSendTransport(
  {
    id             : "0b38d662-ea00-4c70-9ae3-b675d6a89e09",
    iceParameters  : { ... },
    iceCandidates  : [ ... ],
    dtlsParameters : { ... },
    sctpParameters : { ... }
  });

device.createRecvTransport(options)

Creates a new WebRTC transport to receive media. The transport must be previously created in the mediasoup router via router.createWebRtcTransport().

@returns Transport

@throws InvalidStateError, if device not loaded

@throws TypeError, if invalid arguments

const transport = device.createRecvTransport(
  {
    id             : "152f60cd-10ac-443b-8529-6474ecba2e44",
    iceParameters  : { ... },
    iceCandidates  : [ ... ],
    dtlsParameters : { ... },
    sctpParameters : { ... }
  });

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

Emitted when a new transport is created.

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

A Transport instance in mediasoup-client represents the local side of a WebRtcTransport in mediasoup server. It connects a mediasoup-client Device with a mediasoup Router at media level and enables the sending of media (by means of Producer instances) or the receiving of media (by means of Consumer instances).

Internally, the transport holds a WebRTC RTCPeerConnection instance.

TransportOptions

TransportProduceParameters

TransportProduceDataParameters

transport.id

Transport identifier. It matches the id of the server side transport.

@type String, read only

transport.closed

Whether the transport is closed.

@type Boolean, read only

transport.direction

The direction of this transport. “send” means that this is a WebRTC transport for sending media. “recv” means that this is a WebRTC transport for receiving media.

@type String, read only

transport.iceGatheringState

The current ICE gathering state of the local peerconnection.

@type RTCIceGatheringState, read only

transport.connectionState

The current connection state of the local peerconnection.

@type RTCPeerConnectionState, read only

transport.appData

Custom data Object provided by the application in the transport constructor. The app can modify its content at any time.

@type Object

transport.appData.foo = "bar";

transport.observer

See the Observer Events section below.

@type EventEmitter, read only

transport.close()

Closes the transport, including all its producers and consumers.

transport.getStats()

Gets the local transport statistics by calling getStats() in the underlying RTCPeerConnection instance.

@async

@returns RTCStatsReport

transport.restartIce({ iceParameters })

Instructs the underlying peerconnection to restart ICE by providing it with new remote ICE parameters.

@async

await transport.restartIce({ iceParameters: { ... } });

transport.updateIceServers({ iceServers })

Provides the underlying peerconnection with a new list of TURN servers.

@async

await transport.updateIceServers({ iceServers: [ ... ] });

transport.produce(options)

Instructs the transport to send an audio or video track to the mediasoup router.

@async

@returns Producer

// Send webcam video with 3 simulcast streams.
const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const videoTrack = stream.getVideoTracks()[0];
const producer = await transport.produce(
  {
    track       : videoTrack,
    encodings   :
    [
      { maxBitrate: 100000 },
      { maxBitrate: 300000 },
      { maxBitrate: 900000 }
    ],
    codecOptions :
    {
      videoGoogleStartBitrate : 1000
    }
  });

transport.consume(options)

Instructs the transport to receive an audio or video track from the mediasoup router.

@async

@returns Consumer

// Let's assume we have created a video consumer in server side and signal its
// parameters to the client app.
mySignaling.on('newConsumer', async (data) =>
{
  const consumer = await transport.consume(
    {
      id            : data.id,
      producerId    : data.producerId,
      kind          : data.kind,
      rtpParameters : data.rtpParameters
    });

  // Render the remote video track into a HTML video element.
  const { track } = consumer;

  videoElem.srcObject = new MediaStream([ track ]);
});

transport.produceData(options)

Instructs the transport to send data via DataChannel to the mediasoup router.

@async

@returns DataProducer

const producer = await transport.produceData();

transport.consumeData(options)

Instructs the transport to receive data via DataChannel from the mediasoup router.

@async

@returns DataConsumer

// Let's assume we have created a data consumer in server side and signal its
// parameters to the client app.
mySignaling.on('newDataConsumer', async (data) =>
{
  const consumer = await transport.consumeData(
    {
      id                   : data.id,
      producerId           : data.producerId,
      sctpStreamParameters : data.sctpStreamParameters
      label                : data.label
      protocol             : data.protocol
    });
});

transport.on(“connect”, fn({ dtlsParameters }, callback(), errback(error))

Emitted when the transport is about to establish the ICE+DTLS connection and needs to exchange information with the associated server side transport.

transport.on("connect", async ({ dtlsParameters }, callback, errback) =>
{
  // Signal local DTLS parameters to the server side transport.
  try
  {
    await mySignaling.send(
      "transport-connect",
      {
        transportId    : transport.id, 
        dtlsParameters : dtlsParameters
      });

    // Tell the transport that parameters were transmitted.
    callback();
  }
  catch (error)
  {
    // Tell the transport that something was wrong.
    errback(error);
  }
});

transport.on(“produce”, fn(parameters, callback({ id }), errback(error))

Emitted when the transport needs to transmit information about a new producer to the associated server side transport. This event occurs before the produce() method completes.

transport.on("produce", async (parameters, callback, errback) =>
{
  // Signal parameters to the server side transport and retrieve the id of 
  // the server side new producer.
  try
  {
    const data = await mySignaling.send(
      "transport-produce",
      {
        transportId   : transport.id, 
        kind          : parameters.kind,
        rtpParameters : parameters.rtpParameters,
        appData       : parameters.appData
      });

    // Let's assume the server included the created producer id in the response
    // data object.
    const { id } = data;

    // Tell the transport that parameters were transmitted and provide it with the
    // server side producer's id.
    callback({ id });
  }
  catch (error)
  {
    // Tell the transport that something was wrong.
    errback(error);
  }
});

transport.on(“producedata”, fn(parameters, callback({ id }), errback(error))

Emitted when the transport needs to transmit information about a new data producer to the associated server side transport. This event occurs before the produceData() method completes.

transport.on("producedata", async (parameters, callback, errback) =>
{
  // Signal parameters to the server side transport and retrieve the id of 
  // the server side new producer.
  try
  {
    const data = await mySignaling.send(
      "transport-producedata",
      {
        transportId          : transport.id, 
        sctpStreamParameters : parameters.sctpStreamParameters,
        label                : parameters.label,
        protocol             : parameters.protocol
      });

    // Let's assume the server included the created producer id in the response
    // data object.
    const { id } = data;

    // Tell the transport that parameters were transmitted and provide it with the
    // server side producer's id.
    callback({ id });
  }
  catch (error)
  {
    // Tell the transport that something was wrong.
    errback(error);
  }
});

transport.on(“icegatheringstatechange”, fn(iceGatheringState))

Emitted when the local transport ICE gathering state changes.

transport.on(“connectionstatechange”, fn(connectionState))

Emitted when the local transport connection state changes.

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);
});

A producer represents an audio or video source that will be transmitted to the mediasoup router through a WebRTC transport.

ProducerOptions

const clonedTrack = track.clone();
const producer = await transport.produce(clonedTrack, ...);

ProducerCodecOptions

OnRtpSenderCallback

Invoked synchronously immediately after a new RTCRtpSender is created. This allows for creating encoded streams in browsers supporting it.

type OnRtpSenderCallback = (rtpSender: RTCRtpSender) => void;

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.rtpSender

The associated WebRTC RTCRtpSender for this producer. It may be undefined for non modern WebRTC implementations.

@type RTCRtpSender|Undefined, read only

producer.track

The audio or video track being transmitted.

@type MediaStreamTrack, read only

producer.rtpParameters

Producer RTP parameters. These parameters are internally built by the library and conform to the syntax and requirements of mediasoup, thus they can be transmitted to the server to invoke transport.produce() with them.

@type RtpSendParameters, read only

producer.paused

Whether the producer is paused.

@type Boolean, read only

producer.maxSpatialLayer

In case of simulcast, this value determines the highest stream (from 0 to N-1) being transmitted. See the setMaxSpatialLayer() method for more about this.

@type Number, read only

producer.appData

Custom data Object provided by the application in the producer factory method. The app can modify its content at any time.

@type Object

producer.observer

See the Observer Events section below.

@type EventEmitter, read only

producer.close()

Closes the producer. No more media is transmitted. The producer's track is internally stopped by calling stop() on it, meaning that it becomes no longer usable.

producer.getStats()

Gets the local RTP sender statistics by calling getStats() in the underlying RTCRtpSender instance.

@async

@returns RTCStatsReport

producer.pause()

Pauses the producer (no RTP is sent to the server).

producer.resume()

Resumes the producer (RTP is sent again to the server).

producer.replaceTrack({ track })

Replaces the audio or video track being transmitted. No negotiation with the server is needed.

@async

const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const newVideoTrack = stream.getVideoTracks()[0];

await producer.replaceTrack({ track: newVideoTrack });

producer.setMaxSpatialLayer(spatialLayer)

In case of simulcast, this method limits the highest RTP stream being transmitted to the server.

@async

// Assuming `encodings` array has 3 entries, let's enable just the first and
// second streams (indexes 0 and 1).
await producer.setMaxSpatialLayer(1);

producer.setRtpEncodingParameters(params)

Add parameters to all encodings in the RTCRtpSender of the producer. Use with caution.

@async

// Set IP DSCP field.
await producer.setRtpEncodingParameters({ networkPriority: 'high' });

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

Emitted when the transport this producer belongs to is closed for whatever reason. The producer itself is also closed.

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

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

Emitted when the audio/video track being transmitted is externally stopped. This may happen, for instance, if the associated microphone or webcam source is disconnected. This is a good chance for the application to close/pause the producer or replace its track.

producer.on("trackended", () =>
{
  console.log("track ended");
});

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(“trackended”, fn())

Emitted when the audio/video track being transmitted is externally stopped. This may happen, for instance, if the associated microphone or webcam source is disconnected. This is a good chance for the application to close/pause the producer or replace its track.

A consumer represents an audio or video remote source being transmitted from the mediasoup router to the client application through a WebRTC transport.

ConsumerOptions

micConsumer = await transport.consume({ streamId: `${remotePeerId}-mic-webcam` });
webcamConsumer = await transport.consume({ streamId: `${remotePeerId}-mic-webcam` });
screensharingConsumer = await transport.consume({ streamId: `${remotePeerId}-screensharing` });

OnRtpReceiverCallback

Invoked synchronously immediately after a new RTCRtpReceiver is created. This allows for creating encoded streams in browsers supporting it.

type OnRtpReceiverCallback = (rtpReceiver: RTCRtpReceiver) => void;

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.

@type Boolean, read only

consumer.kind

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

@type MediaKind, read only

consumer.rtpReceiver

The associated WebRTC RTCRtpReceiver for this consumer. It may be undefined for non modern WebRTC implementations.

@type RTCRtpReceiver|Undefined, read only

consumer.track

The remote audio or video track.

@type MediaStreamTrack, read only

consumer.rtpParameters

Consumer RTP parameters.

@type RtpReceiveParameters, read only

consumer.paused

Whether the consumer is paused.

@type Boolean, read only

consumer.appData

Custom data Object provided by the application in the consumer factory method. The app can modify its content at any time.

@type Object

consumer.observer

See the Observer Events section below.

@type EventEmitter, read only

consumer.close()

Closes the consumer.

consumer.getStats()

Gets the local RTP receiver statistics by calling getStats() in the underlying RTCRtpReceiver instance.

@async

@returns RTCStatsReport

consumer.pause()

Pauses the consumer. Internally the library sets track.enabled = false in the remote track.

consumer.resume()

Resumes the consumer Internally the library sets track.enabled = true in the remote track.

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

Emitted when the transport this consumer belongs to is closed for whatever reason. The consumer itself is also closed.

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

consumer.on(“trackended”, fn())

Emitted when the audio/video track being received is externally stopped.

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

Emitted when the consumer is closed for whatever reason.

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

Emitted when the consumer or its associated producer is paused and, as result, the consumer becomes paused.

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

Emitted when the consumer or its associated producer is resumed and, as result, the consumer is no longer paused.

consumer.observer.on(“trackended”, fn())

Emitted when the audio/video track being received is externally stopped.

A data producer represents a data source that will be transmitted to the mediasoup router through a WebRTC transport.

DataProducerOptions

dataProducer.id

Data producer identifier.

@type String, read only

dataProducer.closed

Whether the data producer is closed.

@type Boolean, read only

dataProducer.sctpStreamParameters

The SCTP stream parameters.

@type SctpStreamParameters, read only

dataProducer.readyState

The DataChannel ready state.

@type RtcDataChannelState, read only

dataProducer.label

The DataChannel label.

@type String , read only

dataProducer.protocol

The DataChannel sub-protocol.

@type String , read only

dataProducer.bufferedAmount

The number of bytes of application data (UTF-8 text and binary data) that have been queued using send().

@type Number , read only

dataProducer.bufferedAmountLowThreshold

Threshold at which the buffered amount of bytes is considered to be low.

@type Number

dataProducer.appData

Custom data Object provided by the application in the data producer factory method. The app can modify its content at any time.

@type Object

dataProducer.observer

See the Observer Events section below.

@type EventEmitter, read only

dataProducer.close()

Closes the data producer. No more media is transmitted.

dataProducer.send(data)

Sends the given data over the corresponding DataChannel.

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

Emitted when the transport this data producer belongs to is closed for whatever reason. The data producer itself is also closed.

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

dataProducer.on(“open”)

Emitted when the underlying DataChannel is open.

dataProducer.on(“error”, fn(error))

Emitted when the underlying DataChannel fails to connect.

dataProducer.on(“close”)

Emitted when the underlying DataChannel is closed for unknown reasons.

dataProducer.on(“bufferedamountlow”)

Emitted when the DataChannel buffered ammount of bytes decreases from above the ` bufferedAmountLowThreshold` value.

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

Emitted when the producer is closed for whatever reason.

A data consumer represents a data source being transmitted from the mediasoup router to the client application through a WebRTC transport.

DataConsumerOptions

dataConsumer.id

Data consumer identifier.

@type String, read only

dataConsumer.dataProducerId

The associated data producer identifier.

@type String, read only

dataConsumer.closed

Whether the data consumer is closed.

@type Boolean, read only

dataConsumer.sctpStreamParameters

The SCTP stream parameters.

@type SctpStreamParameters, read only

dataConsumer.readyState

The DataChannel ready state.

@type RtcDataChannelState, read only

dataConsumer.label

The DataChannel label.

@type String , read only

dataConsumer.protocol

The DataChannel sub-protocol.

@type String , read only

dataConsumer.binaryType

The DataChannel binary type: 'blob' or 'arrayBuffer'.

@type String

dataConsumer.appData

Custom data Object provided by the application in the data consumer factory method. The app can modify its content at any time.

@type Object

dataConsumer.observer

See the Observer Events section below.

@type EventEmitter, read only

dataConsumer.close()

Closes the data consumer.

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

Emitted when the transport this data consumer belongs to is closed for whatever reason. The data consumer itself is also closed.

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

dataConsumer.on(“open”)

Emitted when the underlying DataChannel is open.

dataConsumer.on(“error”, fn(error))

Emitted when the underlying DataChannel fails to connect.

dataConsumer.on(“close”)

Emitted when the underlying DataChannel is closed for unknown reasons.

dataConsumer.on(“message”, fn(data))

Emitted when a DataChannel message is received.

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

Emitted when the data consumer is closed for whatever reason.

Most entities in mediasoup-client expose a observer property (a Node.js EventEmitter) that can be used by third party libraries to monitor everything related to mediasoup.

The observer API should not be directly used by the application itself, but by separate modules or libraries that the application integrate into its code. Such a module or library may, for example, monitor all the creation and closure of transports, producers, consumers, etc. It could also monitor events generated by producers and consumers (“pause”, “resume”, etc).

Usage example:

const mediasoupClient = require("mediasoup-client");

const mediasoupClientDevice = new mediasoupClientTypes.Device();

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

  transport.observer.on("close", () => 
  {
    console.log("transport closed [transport.id:%s]", transport.id);
  });

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

    producer.observer.on("close", () => 
    {
      console.log("producer closed [producer.id:%s]", producer.id);
    });
  });

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

    consumer.observer.on("close", () => 
    {
      console.log("consumer closed [consumer.id:%s]", consumer.id);
    });
  });

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

    dataProducer.observer.on("close", () => 
    {
      console.log("data producer closed [dataProducer.id:%s]", dataProducer.id);
    });
  });

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

    dataConsumer.observer.on("close", () => 
    {
      console.log("data consumer closed [dataConsumer.id:%s]", dataConsumer.id);
    });
  });
});