mediasoup.errors

Provides access to the errors module.

mediasoup.Server(settings)

Returns a new Server instance.

Usage example:

const server = mediasoup.Server(
  {
    logLevel            : "warn",
    rtcIPv4             : "1.2.3.4",
    rtcIPv6             : false,
    dtlsCertificateFile : "/home/foo/dtls-cert.pem",
    dtlsPrivateKeyFile  : "/home/foo/dtls-key.pem"
  });

ServerSettings

ServerUpdateableSettings

server.closed

• Read only

A boolean indicating whether the server has been closed.

server.numWorkers

• Read only

The number of available workers (it matches numWorkers in ServerSettings if given).

server.close()

Closes the server, including all its rooms, and triggers a close event.

server.updateSettings(settings)

Updates the server settings in runtime. Just a subset of the full ServerSettings can be updated.

server.Room(mediaCodecs, [options])

Creates and returns a new Room instance.

options allows the following items:

Usage example:

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

const room = server.Room(mediaCodecs);

server.on(“close”)

Emitted when the server is closed.

server.on(“newroom”, fn(room))

Emitted when a new room is created.

RoomMediaCodec

AudioLevelInfo

room.id

• Read only

Unique identifier (Number).

room.closed

• Read only

A Boolean indicating whether the room has been closed.

room.rtpCapabilities

• Read only.

An Object with the RTP capabilities of the room, miming the syntax of RTCRtpCapabilities in ORTC.

room.peers

• Read only

An Array with the list of Peer instances in the room.

room.close([appData])

Closes the room, including all its peers, and triggers a close event.

room.getPeerByName(name)

Retrieves the Peer with the given name, or undefined if not found.

room.receiveRequest(request)

Provide the room with a mediasoup protocol request payload (commonly generated by mediasoup-client).

The method returns a Promise resolving to a mediasoup protocol response payload that must be sent back to the request originator.

Usage example:

// Here we assume a custom WebSocket based signaling protocol.
// * request: A mediasoup protocol request payload with target: "room".
// * accept: A function to tell our signaling protocol to accept the request.
// * reject: A function to tell our signaling protocol to reject the request.
function handleRequestFromMediasoupClient(request, accept, reject)
{
  switch (request.method)
  {
    case "queryRoom":
    {
      mediasoupRoom.receiveRequest(request)
        .then((response) => accept(response))
        .catch((error) => reject(500, error.toString()));

      break;
    }

    case "join":
    {
      const { peerName, spy } = request;

      // Here we may want to check whether `spy` is `true` and allow or reject
      // this join request based on app logic/policy.

      mediasoupRoom.receiveRequest(request)
        .then((response) =>
        {
          // Get the new mediasoup Peer instance.
          const peer = mediasoupRoom.getPeerByName(peerName);

          console.info("new peer joined the room: %o", peer);

          accept(response);
        })
        .catch((error) => reject(500, error.toString()));

      break;
    }
  }
}

room.createActiveSpeakerDetector()

Creates and returns a new ActiveSpeakerDetector.

room.createRtpStreamer(producer, options)

Returns a Promise resolving to a new RtpStreamer associated to the given producer.

room.on(“close”, fn(appData))

Emitted when the room is closed.

room.on(“newpeer”, fn(peer))

Emitted when a new peer is created.

room.on(“audiolevels”, fn(audioLevelInfos))

Emitted every few milliseconds. It provides information regarding the audio level of each audio producer in the room.

peer.name

• Read only

The name (String) of the peer.

peer.closed

• Read only

A Boolean indicating whether the peer has been closed.

peer.appData

• Read-write

Custom data set by the application. When the peer is created via the mediasoup protocol, the appData is filled with the corresponding field in the join request.

peer.rtpCapabilities

• Read only

An Object with the RTP capabilities of the peer, miming the syntax of RTCRtpCapabilities in ORTC.

peer.transports

• Read only

An Array with the list of WebRtcTransport instances associated to the peer in the order in which they were created.

peer.producers

• Read only

An Array with the list of Producer instances associated to the peer in the order in which they were created.

peer.consumers

• Read only

An Array with the list of Consumer instances associated to the peer in the order in which they were created.

peer.close([appData])

Closes the peer, including all its transports, producers and consumers, and triggers a close event.

peer.getTransportById(id)

Retrieves the WebRtcTransport with the given id, or undefined if not found.

peer.getProducerById(id)

Retrieves the Producer with the given id, or undefined if not found.

peer.getConsumerById(id)

Retrieves the Consumer with the given id, or undefined if not found.

peer.receiveRequest(request)

Provide the peer with a mediasoup protocol request payload (commonly generated by mediasoup-client).

The method returns a Promise resolving to a mediasoup protocol response payload that must be sent back to the request originator.

peer.receiveNotification(notification)

Provide the peer with a mediasoup protocol notification payload (commonly generated by mediasoup-client).

The method does not return anything.

peer.on(“close”, fn(originator, appData))

Emitted when the peer is closed.

peer.on(“notify”, fn(notification))

Emitted when a new mediasoup protocol notification must be sent by the Node.js application to the associated mediasoup-client.

peer.on(“newtransport”, fn(webrtcTransport))

Emitted when a new webrtcTransport is created.

peer.on(“newproducer”, fn(producer))

Emitted when a new producer is created.

peer.on(“newconsumer”, fn(consumer))

Emitted when a new consumer is created.

IceParameters

IceCandidate

IceSelectedTuple

LocalDtlsParameters

LocalDtlsFingerprints

Map of DTLS algorithms (as defined in the “Hash function Textual Names” registry initially specified in RFC 4572 Section 8) and their corresponding certificate fingerprint values (in lowercase hex string as expressed utilizing the syntax of “fingerprint” in RFC 4572 Section 5).

RemoteDtlsParameters

RemoteDtlsFingerprint

IceState

DtlsRole

DtlsState

MirroringOptions

webrtcTransport.id

• Read only

Unique identifier (Number).

webrtcTransport.closed

• Read only

A Boolean indicating whether the webrtcTransport has been closed.

webrtcTransport.appData

• Read-write

Custom data set by the application. When the webrtcTransport is created via the mediasoup protocol, the appData is filled with the corresponding field in the createTransport request.

webrtcTransport.direction

• Read only

A String (“send” or “recv”) representing the direction of the media over this webrtcTransport.

webrtcTransport.iceRole

• Read only

String indicating the ICE role of the webrtcTransport. Due to the ICE Lite design, this is always “controlled”.

webrtcTransport.iceLocalParameters

• Read only

Local IceParameters of the webrtcTransport.

webrtcTransport.iceLocalCandidates

• Read only

Sequence of local IceCandidate Objects associated to this webrtcTransport.

webrtcTransport.iceState

• Read only

The current IceState of the webrtcTransport.

webrtcTransport.iceSelectedTuple

• Read only

The selected IceSelectedTuple indicating information about the selected ICE candidate pair.

It is undefined if ICE is not yet established (no working candidate pair was found).

webrtcTransport.dtlsLocalParameters

• Read only

LocalDtlsParameters of the webrtcTransport.

webrtcTransport.dtlsState

• Read only

The current DtlsState of the webrtcTransport.

webrtcTransport.dtlsRemoteCert

• Read only

The remote certificate in PEM format (String). It is set once dtlsState becomes “connected”.

webrtcTransport.close([appData])

Closes the webrtcTransport and triggers a close event.

webrtcTransport.setMaxBitrate(bitrate)

Set maximum bitrate for media streams sent by the remote endpoint over this webrtcTransport. Returns a Promise that resolves to this webrtcTransport.

Usage example:

peer.on('newtransport', (webrtcTransport) =>
{
  if (webrtcTransport.direction === 'send')
    webrtcTransport.setMaxBitrate(250000);
});

webrtcTransport.getStats()

Returns a Promise resolving to an array of Objects containing RTC stats related to the webrtcTransport.

webrtcTransport.startMirroring(options)

Enables RTP/RTCP mirroring. The selected RTP/RTCP over this webrtcTransport will be sent to the given address (see options).

webrtcTransport.stopMirroring()

Stops RTP/RTCP mirroring.

webrtcTransport.on(“close”, fn(originator, appData))

Emitted when the webrtcTransport is closed.

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

Emitted when the ICE selected tuple changes.

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

Emitted when the ICE state changes.

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

Emitted when the DTLS state changes.

RemoteParameters

plainRtpTransport.id

• Read only

Unique identifier (Number).

plainRtpTransport.closed

• Read only

A Boolean indicating whether the plainRtpTransport has been closed.

plainRtpTransport.tuple

• Read only

The 5-Tuple indicating information about the connection.

plainRtpTransport.localIP

• Read only

The local IP address (String) of the transport.

plainRtpTransport.localPort

• Read only

The local port (Number) of the transport.

plainRtpTransport.close()

Closes the plainRtpTransport.

plainRtpTransport.setRemoteParameters(parameters)

Set the remote IP address and port for the plainRtpTransport.

producer.id

• Read only

Unique identifier (Number).

producer.closed

• Read only

A Boolean indicating whether the producer has been closed.

producer.appData

• Read-write

Custom data set by the application. When the producer is created via the mediasoup protocol, the appData is filled with the corresponding field in the createProducer request.

producer.kind

• Read only

The media kind (“audio” or “video”) handled by the producer.

producer.peer

• Read only

The Peer owner of this producer.

producer.transport

• Read only

The Transport assigned to this producer.

producer.rtpParameters

• Read only

An Object with the effective RTP parameters of the producer, miming the syntax of RTCRtpParameters in ORTC.

producer.locallyPaused

• Read only

Boolean indicating whether this producer has been locally paused (in mediasoup).

producer.remotelyPaused

• Read only

Boolean indicating whether this producer has been remotely paused (by the remote client).

producer.paused

• Read only

Boolean indicating whether this producer has been locally or remotely paused.

producer.preferredProfile

• Read only

String indicating the preferred RTP profile set via producer.setPreferredProfile().

producer.close([appData])

Closes the producer and triggers a close event.

producer.pause([appData])

Pauses the producer locally, meaning that no RTP will be relayed to its associated consumers.

producer.resume([appData])

Resumes the producer locally, meaning that RTP will be relayed again to its associated consumers (unless the producer was also remotely paused).

producer.setPreferredProfile(profile)

Set the given RTP profile as the desired profile for all its associated consumers.

For more information, check the Glossary section.

producer.getStats()

Returns a Promise resolving to an array of Objects containing RTC stats related to the producer.

producer.on(“close”, fn(originator, appData))

Emitted when the producer is closed.

producer.on(“pause”, fn(originator, appData))

Emitted when the producer is locally or remotely paused.

producer.on(“resume”, fn(originator, appData))

Emitted when the producer is locally or remotely resumed.

consumer.id

• Read only

Unique identifier (Number).

consumer.closed

• Read only

A Boolean indicating whether the consumer has been closed.

consumer.appData

• Read-write

Custom data set by the application.

consumer.kind

• Read only

The media kind (“audio” or “video”) handled by the consumer.

consumer.peer

• Read only

The Peer owner of this consumer (if any).

consumer.transport

• Read only

The Transport assigned to this consumer.

consumer.rtpParameters

• Read only

An Object with the effective RTP parameters of the consumer, miming the syntax of RTCRtpParameters in ORTC.

consumer.source

• Read only

The RTP source of this consumer. Typically it corresponds to a Producer.

consumer.enabled

• Read only

Boolean indicating whether this consumer has been enabled (so the endpoint can receive RTP). Being enabled also means that a transport has been assigned to this consumer.

consumer.locallyPaused

• Read only

Boolean indicating whether this consumer has been locally paused (in mediasoup).

consumer.remotelyPaused

• Read only

Boolean indicating whether this consumer has been remotely paused (by the remote client).

consumer.sourcePaused

• Read only

Boolean indicating whether the source of this consumer has been paused.

consumer.paused

• Read only

Boolean indicating whether this consumer has been locally or remotely paused, or its source has been paused.

consumer.preferredProfile

• Read only

String indicating the preferred RTP profile set via consumer.setPreferredProfile().

consumer.effectiveProfile

• Read only

String indicating the effective current RTP profile of this consumer.

consumer.close([appData])

Closes the consumer and triggers a close event.

consumer.pause([appData])

Pauses the consumer locally, meaning that no RTP will be relayed to the remote client.

consumer.resume([appData])

Resumes the consumer locally, meaning that RTP will be relayed again to the remote client (unless the consumer was also remotely paused).

consumer.setPreferredProfile(profile)

Set the given RTP profile as the desired profile. No profile higher than the given one will become effective profile for this consumer.

For more information, check the Glossary section.

consumer.requestKeyFrame()

Request a RTCP PLI to the RTP source (if supported).

consumer.getStats()

Returns a Promise resolving to an array of Objects containing RTC stats related to the consumer.

consumer.on(“close”, fn(originator, appData))

Emitted when the consumer is closed.

consumer.on(“pause”, fn(originator, appData))

Emitted when the consumer is locally or remotely paused.

consumer.on(“resume”, fn(originator, appData))

Emitted when the consumer is locally or remotely resumed.

consumer.on(“effectiveprofilechange”, fn(profile))

Emitted when the effective profile changes.

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

Emitted when a transport is given to this consumer.

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

Emitted when the associated transport is closed.

activeSpeakerDetector.close()

Closes the activeSpeakerDetector and triggers a close event.

activeSpeakerDetector.on(“close”, fn())

Emitted when the activeSpeakerDetector is closed.

activeSpeakerDetector.on(“activespeakerchange”, fn(peer, producer))

Emitted when a new active speaker is detected.

RtpStreamerOptions

rtpStreamer.consumer

• Read only

The generated Consumer instance.

rtpStreamer.transport

• Read only

The generated PlainRtpTransport instance.

rtpStreamer.close()

Closes the rtpStreamer, including its consumer and transport, and triggers a close event.

rtpStreamer.on(“close”, fn())

Emitted when the rtpStreamer is closed.

errors.InvalidStateError

This error happens when an API method is called on an Object in invalid state (for example when such an Object is closed).