mediasoup

/ home / Documentation / mediasoup protocol

mediasoup protocol

Although mediasoup does not implement a signaling protocol, both the client (mediasoup-client) and the server (mediasoup) must exchange messages. Those messages can be request/response pairs or notifications, and can be sent in both directions.

Those messages can be serialized to JSON bodies for network transmission, but may be converted into JavaScripts Objects (JSON.parse()) before they are given to the corresponding API methods in both mediasoup and mediasoup-client.

The exact definition of the message payloads that must be exchanged is documented in the MEDIASOUP_PROTOCOL.md file included in the mediasoup-client source code.

The application developer does not need to know in depth about these messages, but can intercept them for advanced usages.

Request/response pairs and notifications

mediasoup-client can generate both requests and notifications to be sent to mediasoup, while mediasoup just generates notifications and responses for mediasoup-client.

It's up to the application how to correlate those requests and their associated responses, for example by enveloping the request and its response into a signaling transaction that uses a id field to match them.

Message target

Both requests and notifications sent by mediasoup-client have a target key whose value can be “room” or “peer”:

It's up to the application how to correlate those requests and their associated responses, for example by enveloping the request and its response into a signaling transaction that uses a id field to match them.

Message examples

Those real messages are directly taken from the MEDIASOUP_PROTOCOL.md file included in the mediasoup-client source code. Here they are represented in JSON format.

mediasoup-client request sent to the mediasoup Room

{
  "method": "queryRoom",
  "target": "room"
}
{
  "rtpCapabilities": {},
  "mandatoryCodecPayloadTypes": []
}

mediasoup-client request sent to the mediasoup Peer

{
  "method": "createTransport",
  "target": "peer",
  "id": 1111,
  "options": {},
  "dtlsParameters": {},
  "appData": "foo"
}
{
  "iceParameters": {},
  "iceCandidates": [],
  "dtlsParameters": {}
}

mediasoup-client notification sent to the mediasoup Peer

{
  "method": "leave",
  "target": "peer",
  "notification": true,
  "appData": 1234
}

mediasoup notification sent to the mediasoup-client Peer

{
  "method": "transportStats",
  "target": "peer",
  "notification": true,
  "id": 3333,
  "stats": []
}