mediasoup-client for WebRTC

Common errors

• TypeError: Cannot read properties of undefined (reading 'sctpCapabilities')

  cause `device.load()` has not been called or completed successfully before attempting to access `device.sctpCapabilities` or create a transport.
  fix Ensure `await device.load({ routerRtpCapabilities });` is called and has resolved with valid capabilities from the server before proceeding to create transports or access device properties.

• Mediasoup-client: `Device` not loaded

  cause Attempting to create a `SendTransport` or `RecvTransport` instance, or perform other operations requiring a loaded device, when `device.load()` has not been successfully invoked.
  fix Always call `await device.load({ routerRtpCapabilities });` and wait for its completion before performing any operations that depend on the `Device` being initialized with router capabilities.

• DOMException: Failed to execute 'setRemoteDescription' on 'RTCPeerConnection': Failed to set remote answer sdp.

  cause This generic WebRTC error often indicates a mismatch in RTP capabilities negotiated between the client and the mediasoup server during the signaling phase, or incorrect SDP provided by the signaling server.
  fix Thoroughly review the `routerRtpCapabilities` retrieved from the server, ensure `device.load()` is using the correct data, and verify that the `dtlsParameters` and other transport-related parameters exchanged via your signaling server are accurate and consistent with the mediasoup server's expectations.

• Error: Transport has already been connected

  cause The `sendTransport.on('connect')` event handler's `callback()` function was invoked multiple times, or the `connect` event itself was triggered more than once for the same transport instance due to a signaling race condition.
  fix Ensure that your signaling server logic handles transport connection idempotently. The `callback()` should only be called once per `connect` event. Implement safeguards on the client or server to prevent duplicate connection requests.

Warnings

• breaking `mediasoup-client` v3 is strictly compatible ONLY with `mediasoup` (server) v3. Attempting to use it with a v2 `mediasoup` server will lead to incompatibility issues and errors.
  Fix: Ensure your mediasoup server instance is also running version 3 or later. Downgrade `mediasoup-client` if you must use a v2 server.
• breaking The `Peer` abstraction was removed in `mediasoup-client` v3. Applications must now directly manage `Device`, `Transport`, `Producer`, and `Consumer` entities.
  Fix: Refactor existing v2 code to interact directly with `Device` for loading capabilities, and then create `SendTransport` and `RecvTransport` instances, followed by `Producer` and `Consumer` for media handling.
• breaking The signatures for `sendTransport.on('produce')` and `sendTransport.on('producedata')` event handlers, specifically their `callback` and `errback` arguments, have changed in v3.
  Fix: Review the official `mediasoup-client` v3 documentation and update your event handler implementations to match the new `callback` and `errback` parameter types and expected return values.
• gotcha `mediasoup-client` is signaling-agnostic and requires developers to implement their own signaling layer (e.g., via WebSockets) to communicate with the `mediasoup` server. The `mySignaling` object in examples is a placeholder.
  Fix: Design and implement a robust signaling mechanism (e.g., using `socket.io` or plain WebSockets) that can exchange the necessary SDP offers/answers, ICE candidates, and mediasoup-specific parameters between the client and server.
• gotcha While primarily a browser library, `mediasoup-client` can be used in Node.js environments but explicitly requires Node.js version 22 or higher as per its `engines` field.
  Fix: Ensure your Node.js development and deployment environments meet the `engines.node` requirement (>=22). Use a Node.js version manager like `nvm` to easily switch or upgrade versions.

Install

• npm install mediasoup-client npm
• yarn add mediasoup-client yarn
• pnpm add mediasoup-client pnpm

Imports

• Device
  wrong:

  const Device = require('mediasoup-client').Device;

  correct:

  import { Device } from 'mediasoup-client';

  The primary entry point for client-side WebRTC logic. mediasoup-client is primarily an ESM-first library, and ships TypeScript types.
• Producer
  wrong:

  import { MediaProducer } from 'mediasoup-client';

  correct:

  import { Producer } from 'mediasoup-client';

  Represents a local track being sent to the mediasoup server. This is a type, the instance is created via `sendTransport.produce()`.
• DataProducer
  wrong:

  import { DataChannelProducer } from 'mediasoup-client';

  correct:

  import { DataProducer } from 'mediasoup-client';

  Represents a local DataChannel being sent to the mediasoup server. This is a type, the instance is created via `sendTransport.produceData()`.

Quickstart

This quickstart initializes a mediasoup-client Device, loads it with router capabilities, establishes a WebRTC send transport through a custom signaling layer, and then demonstrates producing both a webcam video stream and a DataChannel.

import { Device } from 'mediasoup-client';
import mySignaling from './my-signaling'; // Our own signaling stuff.

// Create a device (use browser auto-detection).
const device = new Device();

// Communicate with our server app to retrieve router RTP capabilities.
const routerRtpCapabilities = await mySignaling.request(
	'getRouterCapabilities'
);

// Load the device with the router RTP capabilities.
await device.load({ routerRtpCapabilities });

// Check whether we can produce video to the router.
if (!device.canProduce('video')) {
	console.warn('cannot produce video');

	// Abort next steps.
}

// Create a transport in the server for sending our media through it.
const { id, iceParameters, iceCandidates, dtlsParameters, sctpParameters } =
	await mySignaling.request('createTransport', {
		sctpCapabilities: device.sctpCapabilities,
	});

// Create the local representation of our server-side transport.
const sendTransport = device.createSendTransport({
	id,
	iceParameters,
	iceCandidates,
	dtlsParameters,
	sctpParameters,
});

// Set transport "connect" event handler.
sendTransport.on('connect', async ({ dtlsParameters }, callback, errback) => {
	// Here we must communicate our local parameters to our remote transport.
	try {
		await mySignaling.request('transport-connect', {
			transportId: sendTransport.id,
			dtlsParameters,
		});

		// Done in the server, tell our transport.
		callback();
	} catch (error) {
		// Something was wrong in server side.
		errback(error);
	}
});

// Set transport "produce" event handler.
sendTransport.on(
	'produce',
	async ({ kind, rtpParameters, appData }, callback, errback) => {
		// Here we must communicate our local parameters to our remote transport.
		try {
			const { id } = await mySignaling.request('produce', {
				transportId: sendTransport.id,
				kind,
				rtpParameters,
				appData,
			});

			// Done in the server, pass the response to our transport.
			callback({ id });
		} catch (error) {
			// Something was wrong in server side.
			errback(error);
		}
	}
);

// Set transport "producedata" event handler.
sendTransport.on(
	'producedata',
	async (
		{ sctpStreamParameters, label, protocol, appData },
		callback,
		errback
	) => {
		// Here we must communicate our local parameters to our remote transport.
		try {
			const { id } = await mySignaling.request('produceData', {
				transportId: sendTransport.id,
				sctpStreamParameters,
				label,
				protocol,
				appData,
			});

			// Done in the server, pass the response to our transport.
			callback({ id });
		} catch (error) {
			// Something was wrong in server side.
			errback(error);
		}
	}
);

// Produce our webcam video.
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',
});