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

#include "libmediasoupclient/mediasoupclient.hpp"

mediasoupclient::Device

The Device class.

@returns Device

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

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.

@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 }

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

PeerConnection::Options

new Device()

Creates a new device.

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

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

device.IsLoaded()

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

@returns bool

device.Load(routerRtpCapabilities, peerConnectionOptions = nullptr)

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.

@throws mediasoupclient::Exception, if device already loaded

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.

@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, peerConnectionOptions = nullptr, appData = {})

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

@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, peerConnectionOptions = nullptr, appData = {})

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

@returns RecvTransport*

auto* recvTransportListener = new MyRecvTransportListener();

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

A Transport instance in libmediasoupclient represents the local side of a WebRtcTransport in mediasoup server. 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.

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.

transport.RestartIce(iceParameters)

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

@async blocks current thread

transport.RestartIce(iceParameters);

transport.UpdateIceServers(iceServers)

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

transport.updateIceServers(iceServers);

@abstract

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

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.

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

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.

	// Fulfil 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.

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

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

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

@async blocks current thread

@returns Producer

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

sendTransport.ProduceData(listener, label, protocol, order, maxRetransmits, maxPacketLifeTime, appData)

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

@async blocks current thread

@returns DataProducer

@inherits Transport::Listener

@abstract

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

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.

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

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

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

	return promise.get_future();
}

SendTransportListener::OnProduceData(transport, sctpStreamParameters, label, protocol, appData)

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.

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

std::future<std::string> MySendTransportListener::OnProduceData(
		SendTransport* transport,
		const nlohmann::json& sctpStreamParameters,
		const std::string& label,
		const std::string& protocol,
		const nlohmann::json& appData);
)
{
	std::promise<std::string> promise;

	json body =
	{
		{ "transportId",          transport->GetId()   },
		{ "sctpStreamParameters", sctpStreamParameters },
		{ "label",                label                },
		{ "protocol",             protocol             },
		{ "appData",              appData              }
	};

	json response = mySignaling.send("transport-produce-data", 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"));
  }

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

	return promise.get_future();
}

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

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

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

@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.ConsumeData(listener, id, producerId, label, protocol, appData)

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

@async blocks current thread

@returns DataConsumer

auto* consumerListener = new MyConsumerListener();

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

@inherits Transport::Listener

@abstract

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

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

ProducerCodecOptions

@type nlohmann::json

producer.GetId()

Producer identifier.

@returns const std::string&

producer.GetKind()

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

@returns std::string MediaKind

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

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.

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.

producer.ReplaceTrack(newVideoTrack);

producer.SetMaxSpatialLayer(spatialLayer)

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

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

@abstract

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

ProducerListener::OnTransportClose(producer)

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

void MyProducerListener::OnTransportClose(mediasoupclient::Producer* producer)
{
	std::cout << "transport closed" << std::endl;
}

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

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& MediaKind

consumer.GetRtpParameters()

Consumer RTP parameters.

@returns const nlohmann::json& RtpReceiveParameters

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.

consumer.Pause()

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

consumer.Resume()

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

@abstract

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

ConsumerListener::OnTransportClose(consumer)

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

void MyConsumerListener::OnTransportClose(mediasoupclient::Consumer* consumer)
{
	std::cout << "transport closed" << std::endl;
}

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

dataProducer.GetId()

Producer identifier.

@returns const std::string&

dataProducer.GetSctpStreamParameters()

The SCTP stream parameters.

@returns const SctpStreamParameters.

dataProducer.GetReadyState()

The DataChannel ready state.

@type webrtc::DataChannelInterface::DataState

dataProducer.GetLabel()

The DataChannel label.

@returns std::string, read only

dataProducer.GetProtocol()

The DataChannel sub-protocol.

@returns std::string, read only

dataProducer.GetBufferedAmount()

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

@returns uint64_t, read only

dataProducer.GetAppData

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

@returns const nlohmann::json&

dataProducer.IsClosed()

Whether the data producer is closed.

@returns bool

dataProducer.Close()

Closes the data producer. No more data is transmitted.

dataProducer.Send(buffer)

Sends the given data over the corresponding DataChannel. If the data can't be sent at the SCTP level (due to congestion control), it's buffered at the data channel level, up to a maximum of 16MB. If Send is called while this buffer is full, the data channel will be closed abruptly.

So, it's important to use GetBufferedAmount and OnBufferedAmountChange to ensure the data channel is used efficiently but without filling this buffer.

@abstract

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

DataProducerListener::OnOpen(producer)

Executed when the underlying DataChannel is open.

DataProducerListener::OnClose(producer)

Executed when the underlying DataChannel is closed for unknown reasons.

DataProducerListener::OnBufferAmountChange(producer, sentDataSize)

Executed when the DataChannel buffered amount of bytes changes.

DataProducerListener::OnTransportClose(producer)

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

void MyProducerListener::OnTransportClose(mediasoupclient::Producer* producer)
{
	std::cout << "transport closed" << std::endl;
}

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

dataConsumer.GetId()

Consumer identifier.

@returns const std::string&

dataConsumer.GetDataProducerId()

The associated data producer identifier.

@returns const std::string&

dataConsumer.GetSctpStreamParameters()

The SCTP stream parameters.

@returns const SctpStreamParameters.

dataConsumer.GetReadyState()

The DataChannel ready state.

@type webrtc::DataChannelInterface::DataState

dataConsumer.GetLabel()

The DataChannel label.

@returns std::string, read only

dataConsumer.GetProtocol()

The DataChannel sub-protocol.

@returns std::string, read only

dataConsumer.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&

dataConsumer.IsClosed()

Whether the consumer is closed.

@returns bool

dataConsumer.Close()

Closes the dataConsumer.

@abstract

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

DataConsumerListener::OnConnecting(consumer)

Executed when the underlying DataChannel is connecting.

DataConsumerListener::OnOpen(producer)

Executed when the underlying DataChannel is open.

DataConsumerListener::OnClosing(consumer)

Executed when the underlying DataChannel is closing.

DataConsumerListener::OnClose(producer)

Executed when the underlying DataChannel is closed for unknown reasons.

DataConsumerListener::OnTransportClose(consumer)

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

void MyConsumerListener::OnTransportClose(mediasoupclient::DataConsumer* consumer)
{
	std::cout << "transport closed" << std::endl;
}

DataConsumerListener::OnMessage(dataConsumer, buffer)

Executed when a DataChannel message is received.

void MyConsumerListener::OnMessage(DataConsumer* dataConsumer, const webrtc::DataBuffer& buffer)
{
	if (dataConsumer->GetLabel() == "chat")
	{
		std::string message = std::string(buffer.data.data<char>(), buffer.data.size());
		std::cout << "received chat message: " << message << std::endl;
	}
}

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

LogLevel

Logger::LogHandlerInterface

See LogHandlerInterface.

Logger::SetLogLevel(level)

Sets log level.

Logger::SetHandler(handler)

Sets log handler.

Logger::SetDefaultHandler()

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

@abstract

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

LogHandlerInterface::OnLog(level, payload, len)

Executed for every log.

void MyLogHandler::OnLog(LogLevel level, char* payload, size_t len)
{
	std::cout << payload << std::endl;
}

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

#include "nlohmann/json.hpp"