mediasoup-client Documentation

The Device is the central entry point for mediasoup-client. It represents the client-side capabilities and manages the creation of transports.

• Device.load({ routerRtpCapabilities }): This method initializes the device with the capabilities of the remote mediasoup router. This is a prerequisite for any media operations.
• Device.createSendTransport(options): Creates a local representation of a server-side send transport. The options must include parameters like id, iceParameters, iceCandidates, dtlsParameters, and sctpParameters obtained from the server.
• Transport Events: Transports are not fully functional until their event handlers are wired to your signaling server. The most critical events are:
  • connect: Triggered when the transport needs to exchange DTLS parameters to establish a secure connection.
  • produce: Triggered when a producer (like a video track) is being created and needs to send its RTP parameters to the server.
  • producedata: Triggered when a data producer (DataChannel) is being created.

The Transport class is the primary interface for managing WebRTC connections in mediasoup-client. It handles both media (RTP) and data (SCTP) flows. A transport can be either a sending transport (direction: 'send') or a receiving transport (direction: 'recv').

Key capabilities include:

• Media Production: Create Producer instances to send audio or video tracks.
• Media Consumption: Create Consumer instances to receive remote audio or video tracks.
• Data Communication: Create DataProducer and DataConsumer instances for SCTP-based data channels.
• Connection Management: Monitor connection states, ICE gathering, and restart ICE connections.

// Conceptual usage pattern
const transport = new Transport({
  direction: 'send',
  id: 'my-transport-id',
  iceParameters: { ... },
  iceCandidates: [ ... ],
  dtlsParameters: { ... },
  // ... other required options
});

// Listen for connection events
transport.on('connect', ({ dtlsParameters }, callback, error) => {
  // Handle connection
});

The Consumer class represents a remote media track being received by the client. It provides control over the media stream (pausing/resuming) and allows you to monitor the lifecycle of the track through events.

Key capabilities include:

• Controlling playback: Use .pause() to disable the track and .resume() to re-enable it.
• Monitoring state: Access properties like .id, .producerId, .kind, and .track.
• Retrieving statistics: Use .getStats() to get an RTCStatsReport for the associated receiver.
• Lifecycle management: Call .close() to manually terminate the consumer and clean up the track.

// Example conceptual usage
const consumer = new Consumer({
  id: 'consumer-id',
  localId: 'local-id',
  producerId: 'producer-id',
  track: mediaStreamTrack,
  rtpParameters: rtpParams
});

consumer.on('trackended', () => {
  console.log('Remote track ended');
});

consumer.pause();
// ... later
consumer.resume();

To use mediasoup-client, you typically follow this lifecycle:

1. Instantiate a Device.
2. Load the device with router RTP capabilities retrieved from your signaling server.
3. Create a Transport (Send or Receive) using parameters provided by the server.
4. Set up event handlers for the transport (connect, produce, producedata) to communicate local parameters back to the server via your signaling layer.
5. Use the transport to produce media tracks or data channels.

import { Device } from 'mediasoup-client';
import mySignaling from './my-signaling'; // Your signaling implementation

// 1. Create a device
const device = new Device();

// 2. Load the device with router RTP capabilities from the server
const routerRtpCapabilities = await mySignaling.request('getRouterCapabilities');
await device.load({ routerRtpCapabilities });

// 3. Check capabilities
if (!device.canProduce('video')) {
	console.warn('cannot produce video');
}

// 4. Create a transport
const { id, iceParameters, iceCandidates, dtlsParameters, sctpParameters } =
	await mySignaling.request('createTransport', {
		sctpCapabilities: device.sctpCapabilities,
	});

const sendTransport = device.createSendTransport({
	id,
	iceParameters,
	iceCandidates,
	dtlsParameters,
	sctpParameters,
});

// 5. Set up event handlers
sendTransport.on('connect', async ({ dtlsParameters }, callback, errback) => {
	try {
		await mySignaling.request('transport-connect', {
			transportId: sendTransport.id,
			dtlsParameters,
		});
		callback();
	} catch (error) {
		errback(error);
	}
});

sendTransport.on('produce', async ({ kind, rtpParameters, appData }, callback, errback) => {
	try {
		const { id } = await mySignaling.request('produce', {
			transportId: sendTransport.id,
			kind,
			rtpParameters,
			appData,
		});
		callback({ id });
	} catch (error) {
		errback(error);
	}
});

// 6. Produce media
const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const webcamTrack = stream.getVideoTracks()[0];
const webcamProducer = await sendTransport.produce({ track: webcamTrack });

// Produce data (DataChannel)
const dataProducer = await sendTransport.produceData({
	ordered: true,
	label: 'foo',
});