mediasoup

/ home / Documentation / v3 / libmediasoupclient / API

libmediasoupclient v3 API

mediasoupclient

The main C++ namespace exposed by the libmediasoupclient library.

#include "libmediasoupclient/mediasoupclient.hpp"

Classes

mediasoupclient::Device

The Device class.

@returns Device

auto* device = new mediasoupclient::Device();

Functions

mediasoupclient::Version()

The libmediasoupclient version.

@returns std::string

mediasoupclient::Version();
// "1.0.0"

mediasoupclient::Initialize()

libmediasoupclient initialization. Initializes libwebrtc.

mediasoupclient::Initialize();

mediasoupclient::Cleanup()

libmediasoupclient cleanup. Cleans up libwebrtc.

mediasoupclient::Cleanup();

mediasoupclient::parseScalabilityMode(scalabilityMode)

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

Argument Type Description Required Default
scalabilityMode const std::string& Scalability mode. Yes  

@returns nlohmann::json:

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

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

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

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

Device

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

This is the entry point for C++ client side applications.

Dictionaries

PeerConnection::Options

Field Type Description Required Default
config webrtc::PeerConnectionInterface::RTCConfiguration PeerConnection configuration. No  
factory webrtc::PeerConnectionFactoryInterface* PeerConnection factory. No  

Constructor

new Device()

Creates a new device.

auto* device = new mediasoupclient::Device();

Methods

device.GetRtpCapabilities()

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

@async blocks current thread

@returns const nlohmann::json& RtpCapabilities

@throws mediasoupclient::Exception, if device not loaded

These RTP capabilities must be given to the mediasoup router in order to consume a remote stream. Check the Communication Between Client and Server section for more details.

device.IsLoaded()

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

@returns bool

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.

Argument Type Description Required Default
routerRtpCapabilities const nlohmann::json& RtpCapabilities The mediasoup router RTP capabilities. Yes  

@throws mediasoupclient::Exception, if device already loaded

The router RTP capabilities are exposed via the router.rtpCapabilities getter. Check the Communication Between Client and Server section for more details.

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

Argument Type Description Required Default
kind const std::string& “audio” or “video”. Yes  

@returns bool

@throws mediasoupclient::Exception, if device not loaded

@throws mediasoupclient::Exception, if invalid kind

if (device.CanProduce("video"))
{
  // Produce video.
}

device.CreateSendTransport(listener, id, iceParameters, iceCandidates, dtlsParameters, peerConectionOptions, appData = {})

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

Argument Type Description Required Default
listener SendTransport::Listener The identifier of the server side transport. Yes  
id const std::string& The identifier of the server side transport. Yes  
iceParameters const nlohmann::json& IceParameters ICE parameters of the server side transport. Yes  
iceCandidates const nlohmann::json& Array<IceCandidate> ICE candidates of the server side transport. Yes  
dtlsParameters const nlohmann::json& DtlsParameters DTLS parameters of the server side transport. Yes  
peerConnectionOptions PeerConnection::Options PeerConnection options. No  
appData nlohmann::json Custom application data. No { }

@returns SendTransport*

auto* sendTransportListener = new MySendTransportListener();

// This will block the current thread until completion.
auto* sendTransport = device.CreateSendTransport(
  sendTransportListener,
  id,
  iceParameters,
  iceCandidates,
  dtlsParameters);

device.CreateRecvTransport(listener, id, iceParameters, iceCandidates, dtlsParameters, peerConectionOptions, appData = {})

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

Argument Type Description Required Default
listener RecvTransport::Listener The identifier of the server side transport. Yes  
id const std::string& The identifier of the server side transport. Yes  
iceParameters const nlohmann::json& IceParameters ICE parameters of the server side transport. Yes  
iceCandidates const nlohmann::json& Array<IceCandidate> ICE candidates of the server side transport. Yes  
dtlsParameters const nlohmann::json& DtlsParameters DTLS parameters of the server side transport. Yes  
peerConnectionOptions PeerConnection::Options PeerConnection options. No  
appData nlohmann::json Custom application data. No { }

@returns RecvTransport*

auto* recvTransportListener = new MyRecvTransportListener();

// This will block the current thread until completion.
auto* recvTransport = device.CreateRecvTransport(
  recvTransportListener,
  id,
  iceParameters,
  iceCandidates,
  dtlsParameters);

Transport

A WebRTC transport connects a mediasoupclient 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.

Methods

transport.GetId()

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

@returns const std::string&

transport.GetConnectionState()

The current connection state of the local peerconnection.

@returns const std::string& RTCPeerConnectionState

transport.GetStats()

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

@async blocks current thread

@returns nlohmann::json& RTCStatsReport

transport.GetAppData()

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

@returns const nlohmann::json&

transport.IsClosed()

Whether the transport is closed.

@returns bool

transport.Close()

Closes the transport, including all its producers and consumers.

This method should be called when the server side transport has been closed (and vice-versa).

transport.RestartIce(iceParameters)

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

Argument Type Description Required Default
iceParameters const nlohmann::json& IceParameters New ICE parameters of the server side transport. Yes  

@async blocks current thread

This method must be called after restarting ICE in server side via webRtctransport.restartIce().

transport.RestartIce(iceParameters);

transport.UpdateIceServers(iceServers)

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

Argument Type Description Required Default
iceServers const nlohmann::json& Array<RTCIceServer> List of TURN servers to provide the local peerconnection with. No [ ]

This method is specially useful if the TURN server credentials have changed.

transport.updateIceServers(iceServers);

Transport::Listener

@abstract

This is an abstract class inherited by SendTransport::Listener and RecvTransport::Listener.

Events

TransportListener::OnConnect(transport, dtlsParameters)

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

Argument Type Description
transport Transport* Transport instance.
dtlsParameters const nlohmann::json& DtlsParameters Local DTLS parameters.

@returns std::future<void> when the transport is created in server side mediasoup

In server side, the application should call webRtcTransport.connect().

std::future<void> MyTransportListener::OnConnect(
  mediasoupclient::Transport transport,
  const json& dtlsParameters
)
{
	std::promise<void> promise;

	json body =
	{
		{ "transportId",    transport->GetId() },
		{ "dtlsParameters", dtlsParameters     }
	};

	// Signal local DTLS parameters to the server side transport.
	mySignaling.send("transport-connect", body);

	// [...] Let's assume code execution continues once we get a success response
	// from the server.

	// Fullfill the promise and return its future.
	promise.set_value();

	return promise.get_future();
}

listener.OnConnectionStateChange(transport, connectionState)

Emitted when the local transport connection state changes.

Argument Type Description
transport Transport* Transport instance.
connectionState const std::string& RTCPeerConnectionState Transport connection state.

SendTransport

@inherits Transport

A WebRTC send transport connects a mediasoupclient Device with a mediasoup Router at media level and enables the sending of media (by means of Producer instances).

Internally, the transport holds a WebRTC RTCPeerConnection instance.

Methods

sendTransport.Produce(listener, track, encodings, codecOptions, appData)

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

Argument Type Description Required Default
listener Producer::Listener Producer listener. Yes  
track webrtc::MediaStreamTrackInterface* An audio or video track. Yes  
encodings const std::vector<webrtc::RtpEncodingParameters>* Encoding settings. No  
codecOptions ProducerCodecOptions Per codec specific options. No [ ]
appData nlohmann::json Custom application data. No { }

@async blocks current thread

@returns Producer

If video simulcast is desired, encodings array must be filled with more than one encodings. Each encoding represents a simulcast RTP stream:

  • The order of the encodings is important. The entry with index 0 represents the simulcast stream with lowest bitrate. The entry with index N-1 (being N the number of entries) represents the simulcast stream with highest bitrate. Take this into account when writting per encoding settings such as maxBitrate, maxFramerate or scaleResolutionDownBy.
  • rid field must not be set. The library will internally add it if the underlying browser supports RID.
  • active field must not be set. The library will internally set it to true.
// Send opus audio track with specific codec options.
if (device.CanProduce("audio"))
{
	auto* audioTrack = myUtils::createAudioTrack();

	json codecOptions =
	{
		{ "opusStereo", true },
		{ "opusDtx",    true }
	};

	auto* audioProducerListener = new MyProducerListener();
	auto* audioProducer = sendTransport->Produce(
		audioProducerListener, 
		audioTrack, 
		nullptr, 
		&codecOptions);
}

// Send video track with 3 simulcast streams.
if (device.CanProduce("video"))
{
	auto* videoTrack = myUtils::createVideoTrack();

	std::vector<webrtc::RtpEncodingParameters> encodings;
	
	encodings.emplace_back(webrtc::RtpEncodingParameters());
	encodings.emplace_back(webrtc::RtpEncodingParameters());
	encodings.emplace_back(webrtc::RtpEncodingParameters());

	auto* videoProducerListener = new MyProducerListener();

	// This will block the current thread until completion.
	auto* videoProducer = sendTransport->Produce(
		videoProducerListener,
		videoTrack,
		&encodings,
		nullptr);
}

Before this method completes, the local transport will call “OnProduce” method in the listener. The application must define this method, signal those parameters to the server, and invoke transport.produce() on the corresponding WebRTC transport.

Check the Communication Between Client and Server section for more details.

SendTransport::Listener

@inherits Transport::Listener

@abstract

This is an abstract class which must be implemented and used according to the API.

Events

SendTransportListener::OnProduce(transport, kind, rtpParameters, appData)

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.

Argument Type Description
transport SendTransport* SendTransport instance.
kind const std::string& Producer's media kind (“audio” or “video”).
rtpParameters nlohmann::json RtpSendParameters Producer's RTP parameters.
appData const nlohmann::json& Custom application data as given in the transport.produce() method.

@returns std::future<std::string> ID of the producer created in server side mediasoup

In server side, the application should call transport.produce().

std::future<std::string> MySendTransportListener::OnProduce(
  mediasoupclient::Transport* transport,
  const std::string& kind,
  json rtpParameters,
  const json& appData
)
{
	std::promise<std::string> promise;

	json body =
	{
		{ "transportId",   transport->GetId() },
		{ "kind",          kind               },
		{ "rtpParameters", rtpParameters      },
		{ "appData",       appData            }
	};

	json response = mySignaling.send("transport-produce", body);

  // [...] Let's assume code execution continues once we get a success response
  // from the server.

  // Read the id in the response.
	auto idIt = response.find("id");
	if (idIt == response.end() || !idIt->is_string())
  {
		promise.set_exception(
      std::make_exception_ptr("'id' missing/invalid in response"));
  }

  // Fullfill the promise with the id in the response and return its future.
	promise.set_value(idIt->get<std::string>());

	return promise.get_future();
}

RecvTransport

@inherits Transport

A WebRTC receive transport connects a mediasoupclient Device with a mediasoup Router at media level and enables the reception of media (by means of Consumer instances).

Internally, the transport holds a WebRTC RTCPeerConnection instance.

Methods

recvTransport.Consume(listener, id, producerId, kind, rtpParameters, appData)

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

Argument Type Description Required Default
listener Consumer::Listener Consumer listener. Yes  
id const std::string& The identifier of the server side consumer. Yes  
producerId const std::string& The identifier of the server side producer being consumed. Yes  
kind const std::string& Media kind (“audio” or “video”). Yes  
rtpParameters const nlohmann::json* RtpReceiveParameters Receive RTP parameters. Yes  
appData nlohmann::json Custom application data. No { }

@async blocks current thread

@returns Consumer

auto* consumerListener = new MyConsumerListener();

// This will block the current thread until completion.
auto* consumer = recvTransport->Consume(
  consumerListener,
  id, 
  producerId, 
  kind,	
  rtpParameters);

RecvTransport::Listener

@inherits Transport::Listener

@abstract

This is an abstract class which must be implemented and used according to the API.

Producer

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

Dictionaries

ProducerCodecOptions

Field Type Description Required Default
opusStereo bool Enable OPUS stereo (if the audio source is stereo). No libwebrtc default.
opusFec bool Enable OPUS in band FEC. No libwebrtc default.
opusDtx bool Enable OPUS discontinuous transmission. No libwebrtc default.
opusMaxPlaybackRate Unsigned number Set OPUS maximum playbak rate. No libwebrtc default.
videoGoogleStartBitrate Unsigned number Set video initial bitrate. No  
videoGoogleMaxBitrate Unsigned number Set video maximum bitrate. No  
videoGoogleMinBitrate Unsigned number Set video minimum bitrate. No  

Methods

producer.GetId()

Producer identifier.

@returns const std::string&

producer.GetKind()

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

@returns std::string

producer.GetTrack()

The audio or video track being transmitted.

@returns webrtc::MediaStreamTrackInterface*

producer.GetRtpParameters()

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.

@returns const nlohmann::json& RtpSendParameters

Check the Communication Between Client and Server section for more details.

producer.GetMaxSpatialLayer()

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.

@returns const uint8_t

producer.GetStats()

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

@async blocks current thread

@returns nlohmann::json RTCStatsReport

producer.GetAppData()

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

@returns const nlohmann::json&

producer.IsClosed()

Whether the producer is closed.

@returns bool

producer.IsPaused()

Whether the producer is paused.

@returns bool

producer.Close()

Closes the producer. No more media is transmitted.

This method should be called when the server side producer has been closed (and vice-versa).

producer.Pause()

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

This method should be called when the server side producer has been paused (and vice-versa).

producer.Resume()

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

This method should be called when the server side producer has been resumed (and vice-versa).

producer.ReplaceTrack(track)

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

Argument Type Description Required Default
track webrtc::MediaStreamTrackInterface* An audio or video track. Yes  
producer.ReplaceTrack(newVideoTrack);

producer.SetMaxSpatialLayer(spatialLayer)

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

Argument Type Description Required Default
spatialLayer uint8_t The index of the entry in encodings representing the highest RTP stream that will be transmitted. Yes  
// Assuming `encodings` array has 3 entries, let's enable just the first and
// second streams (indexes 0 and 1).
producer.setMaxSpatialLayer(1);

Producer::Listener

@abstract

This is an abstract class which must be implemented and used according to the API.

Events

ProducerListener::OnTransportClose(producer)

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

Argument Type Description Required Default
producer Producer* The producer instance executing this method. Yes  
void MyProducerListener::OnTransportClose(mediasoupclient::Producer* producer)
{
	std::cout << "transport closed" << std::endl;
}

Consumer

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

Methods

consumer.GetId()

Consumer identifier.

@returns const std::string&

consumer.GetProducerId()

The associated producer identifier.

@returns const std::string&

consumer.GetKind()

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

@returns const std::string&

consumer.GetRtpParameters()

Consumer RTP parameters.

@returns const nlohmann::json& RtpReceiveParameters

Check the Communication Between Client and Server section for more details.

consumer.GetTrack()

The remote audio or video track.

@returns webrtc::MediaStreamTrackInterface*

consumer.GetStats()

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

@async blocks current thread

@returns nlohmann::json RTCStatsReport

consumer.GetAppData()

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

@returns const nlohmann::json&

consumer.IsClosed()

Whether the consumer is closed.

@returns bool

consumer.IsPaused()

Whether the consumer is paused.

@returns bool

consumer.Close()

Closes the consumer.

This method should be called when the server side consumer has been closed (and vice-versa).

consumer.Pause()

Pauses the consumer. Internally the library executes track->set_enabled(false) in the remote track.

This method should be called when the server side consumer has been paused (and vice-versa).

consumer.Resume()

Resumes the consumer Internally the library executes track->set_enabled(true) in the remote track.

This method should be called when the server side consumer has been resumed (and vice-versa).

Consumer::Listener

@abstract

This is an abstract class which must be implemented and used according to the API.

Events

ConsumerListener::OnTransportClose(consumer)

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

Argument Type Description Required Default
consumer Consumer* The consumer instance executing this method. Yes  
void MyConsumerListener::OnTransportClose(mediasoupclient::Consumer* consumer)
{
	std::cout << "transport closed" << std::endl;
}

Logger

C++ namespace (within the mediasoupclient namespace) responsible for logging.

Enums

LogLevel

Value Description
“LOG_DEBUG” Logs debug level and above.
“LOG_WARN” Logs warning level and above.
“LOG_ERROR” Logs error level.
“LOG_NONE” Logs nothing.

Classes

Logger::LogHandlerInterface

See LogHandlerInterface.

Functions

Logger::SetLogLevel(level)

Sets log level.

Argument Type Description Required Default
level LogLevel The log level to be used for logging. Yes  

Logger::SetHandler(handler)

Sets log handler.

Argument Type Description Required Default
level LogHandlerInterface* The log handler to be used. Yes  

Logger::SetDefaultHandler()

Sets the default log handler, which prints all log messages to stdout.

Logger::LogHandlerInterface

@abstract

This is an abstract class which can be implemented and provided to libmediasoupclient via Logger::SetHandler().

Events

LogHandlerInterface::OnLog(level, payload, len)

Executed for every log.

Argument Type Description Required Default
level LogLevel The level this log message belongs to. Yes  
payload char* The log message. Yes  
len size_t The log message length. Yes  
void MyLogHandler::OnLog(LogLevel level, char* payload, size_t len)
{
	std::cout << payload << std::endl;
}

nlohmann::json

libmediasoupclient uses the JSON for Modern C++ library and exposes its nlohmann::json C++ namespace.

The application must use it to construct JSON objects and pass them to the libmediasoupclient API when required.

#include "nlohmann/json.hpp"