WebRTC

https://www.w3.org/TR/webrtc
Admin
WebRTC is a set of ECMAScript APIs that enable real-time communication in browsers, allowing media...
Tokens:136,647
Snippets:827
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### Simulcast example with sendEncodings

Source: https://www.w3.org/TR/webrtc

Simulcast example: a client sends multiple RTP encodings to a server. The start() function creates a peer connection, gets local media, and adds transceivers with sendEncodings for three RIDs (q, h, f) with scaleResolutionDownBy values.

```javascript
const signaling = new SignalingChannel(); // handles JSON.stringify/parse
const constraints = {audio: true, video: true};
const configuration = {'iceServers': [{'urls': 'stun:stun.example.org'}]};
let pc;

// call start() to initiate
async function start() {
  pc = new RTCPeerConnection(configuration);

  // let the "negotiationneeded" event trigger offer generation
  pc.onnegotiationneeded = async () => {
    try {
      await pc.setLocalDescription();
      // send the offer to the other peer
      signaling.send({description: pc.localDescription});
    } catch (err) {
      console.error(err);
    }
  };

  try {
    // get a local stream, show it in a self-view and add it to be sent
    const stream = await navigator.mediaDevices.getUserMedia(constraints);
    selfView.srcObject = stream;
    pc.addTransceiver(stream.getAudioTracks()[0], {direction: 'sendonly'});
    pc.addTransceiver(stream.getVideoTracks()[0], {
      direction: 'sendonly',
      sendEncodings: [
        {rid: 'q', scaleResolutionDownBy: 4.0}
        {rid: 'h', scaleResolutionDownBy: 2.0},
        {rid: 'f'},
      ]
    });
  } catch (err) {
    console.error(err);
  }
}
```

--------------------------------

### Advanced Peer-to-peer Example with Warm-up - Initialization

Source: https://www.w3.org/TR/webrtc

Initializes variables for an advanced peer-to-peer example with warm-up. Declares the signaling channel, constraints, configuration, and variables for the peer connection, audio, video, and a started flag. This is the first part of the advanced example.

```javascript
const signaling = new SignalingChannel(); // handles JSON.stringify/parse
const constraints = {audio: true, video: true};
const configuration = {iceServers: [{urls: 'stun:stun.example.org'}]};
let pc;
let audio;
let video;
let started = false;
```

--------------------------------

### Legacy WebRTC warmup and start functions

Source: https://www.w3.org/TR/webrtc

Legacy interface extensions for WebRTC: warmup() prepares the connection before media is ready, start() begins media transmission, and addCameraMicWarmedUp() replaces tracks on an already-warmed connection. The signaling.onmessage handler processes start, description, and candidate messages, creating an answerer if needed.

```javascript
// Call warmup() before media is ready, to warm-up ICE, DTLS, and media.
async function warmup(isAnswerer) {
  pc = new RTCPeerConnection(configuration);
  if (!isAnswerer) {
    audio = pc.addTransceiver('audio');
    video = pc.addTransceiver('video');
  }

  // send any ice candidates to the other peer
  pc.onicecandidate = ({candidate}) => signaling.send({candidate});

  // let the "negotiationneeded" event trigger offer generation
  pc.onnegotiationneeded = async () => {
    try {
      await pc.setLocalDescription();
      // send the offer to the other peer
      signaling.send({description: pc.localDescription});
    } catch (err) {
      console.error(err);
    }
  };

  pc.ontrack = async ({track, transceiver}) => {
    try {
      // once media for the remote track arrives, show it in the video element
      event.track.onunmute = () => {
        // don't set srcObject again if it is already set.
        if (!remoteView.srcObject) {
          remoteView.srcObject = new MediaStream();
        }
        remoteView.srcObject.addTrack(track);
      }

      if (isAnswerer) {
        if (track.kind == 'audio') {
          audio = transceiver;
        } else if (track.kind == 'video') {
          video = transceiver;
        }
        if (started) await addCameraMicWarmedUp();
      }
    } catch (err) {
      console.error(err);
    }
  };

  try {
    // get a local stream, show it in a self-view and add it to be sent
    selfView.srcObject = await navigator.mediaDevices.getUserMedia(constraints);
    if (started) await addCameraMicWarmedUp();
  } catch (err) {
    console.error(err);
  }
}

// call start() after warmup() to begin transmitting media from both ends
function start() {
  signaling.send({start: true});
  signaling.onmessage({data: {start: true}});
}

// add camera and microphone to already warmed-up connection
async function addCameraMicWarmedUp() {
  const stream = selfView.srcObject;
  if (audio && video && stream) {
    await Promise.all([
      audio.sender.replaceTrack(stream.getAudioTracks()[0]),
      video.sender.replaceTrack(stream.getVideoTracks()[0]),
    ]);
  }
}

signaling.onmessage = async ({data: {start, description, candidate}}) => {
  if (!pc) warmup(true);

  try {
    if (start) {
      started = true;
      await addCameraMicWarmedUp();
    } else if (description) {
      await pc.setRemoteDescription(description);
      // if we got an offer, we need to reply with an answer
      if (description.type == 'offer') {
        await pc.setLocalDescription();
        signaling.send({description: pc.localDescription});
      }
    } else {
      await pc.addIceCandidate(candidate);
    }
  } catch (err) {
    console.error(err);
  }
};
```

--------------------------------

### Example of a stats application

Source: https://www.w3.org/TR/webrtc-stats

This example demonstrates how to use the getStats() method on a sender to monitor packet loss and identify the cause of poor audio quality.

```APIDOC
## [EXAMPLE] Stats Application

### Description
This example shows how to use the getStats() method to compare baseline and current statistics reports to determine if packet loss is the cause of poor audio quality.

### Code Example
```javascript
var baselineReport, currentReport;
var sender = pc.getSenders()[0];

sender.getStats().then(function (report) {
    baselineReport = report;
})
.then(function() {
    return new Promise(function(resolve) {
        setTimeout(resolve, aBit); // ... wait a bit
    });
})
.then(function() {
    return sender.getStats();
})
.then(function (report) {
    currentReport = report;
    processStats();
})
.catch(function (error) {
  console.log(error.toString());
});

function processStats() {
    // compare the elements from the current report with the baseline
    for (let now of currentReport.values()) {
        if (now.type != "outbound-rtp")
            continue;

        // get the corresponding stats from the baseline report
        let base = baselineReport.get(now.id);

        if (base) {
            remoteNow = currentReport.get(now.remoteId);
            remoteBase = baselineReport.get(base.remoteId);

            var packetsSent = now.packetsSent - base.packetsSent;
            var packetsReceived = remoteNow.packetsReceived - remoteBase.packetsReceived;

            // if intervalFractionLoss is > 0.3, we've probably found the culprit
            var intervalFractionLoss = (packetsSent - packetsReceived) / packetsSent;
        }
    });
}
```
```

--------------------------------

### Simple Peer-to-peer Example with RTCPeerConnection

Source: https://www.w3.org/TR/webrtc

Sets up a basic WebRTC peer connection with STUN configuration, handles ICE candidates, negotiationneeded for offer generation, and processes incoming offers/answers/candidates. Requires a SignalingChannel that handles JSON stringify/parse. The example shows how to add local media tracks and display remote streams.

```javascript
const signaling = new SignalingChannel(); // handles JSON.stringify/parse
const constraints = {audio: true, video: true};
const configuration = {iceServers: [{urls: 'stun:stun.example.org'}]};
const pc = new RTCPeerConnection(configuration);

// send any ice candidates to the other peer
pc.onicecandidate = ({candidate}) => signaling.send({candidate});

// let the "negotiationneeded" event trigger offer generation
pc.onnegotiationneeded = async () => {
  try {
    await pc.setLocalDescription();
    // send the offer to the other peer
    signaling.send({description: pc.localDescription});
  } catch (err) {
    console.error(err);
  }
};

pc.ontrack = ({track, streams}) => {
  // once media for a remote track arrives, show it in the remote video element
  track.onunmute = () => {
    // don't set srcObject again if it is already set.
    if (remoteView.srcObject) return;
    remoteView.srcObject = streams[0];
  };
};

// call start() to initiate
function start() {
  addCameraMic();
}

// add camera and microphone to connection
async function addCameraMic() {
  try {
    // get a local stream, show it in a self-view and add it to be sent
    const stream = await navigator.mediaDevices.getUserMedia(constraints);
    for (const track of stream.getTracks()) {
      pc.addTrack(track, stream);
    }
    selfView.srcObject = stream;
  } catch (err) {
    console.error(err);
  }
}

signaling.onmessage = async ({data: {description, candidate}}) => {
  try {
    if (description) {
      await pc.setRemoteDescription(description);
      // if we got an offer, we need to reply with an answer
      if (description.type == 'offer') {
        if (!selfView.srcObject) {
          // blocks negotiation on permission (not recommended in production code)
          await addCameraMic();
        }
        await pc.setLocalDescription();
        signaling.send({description: pc.localDescription});
      }
    } else if (candidate) {
      await pc.addIceCandidate(candidate);
    }
  } catch (err) {
    console.error(err);
  }
};
```

--------------------------------

### Example RTCIceServer array

Source: https://www.w3.org/TR/webrtc

Example array of RTCIceServer objects showing a STUN server and a TURN server with username and credential. The TURN server uses both turns: and turn: URIs.

```JavaScript
[
  {urls: 'stun:stun1.example.net'},
  {urls: ['turns:turn.example.org', 'turn:turn.example.net'],
    username: 'user',
    credential: 'myPassword',
];
```

--------------------------------

### Example of a stats application

Source: https://www.w3.org/TR/webrtc-stats

This example demonstrates how to use the getStats() method on a sender to monitor packet loss over time. It retrieves baseline and current reports, then calculates the interval fraction loss to identify potential network issues.

```APIDOC
## [EXAMPLE] Stats Application

### Description
This example shows how to use the WebRTC getStats() API to monitor packet loss. It retrieves a baseline report, waits a bit, retrieves a current report, and then compares the two to calculate packet loss.

### Code Example
```javascript
var baselineReport, currentReport;
var sender = pc.getSenders()[0];

sender.getStats().then(function (report) {
    baselineReport = report;
})
.then(function() {
    return new Promise(function(resolve) {
        setTimeout(resolve, aBit); // ... wait a bit
    });
})
.then(function() {
    return sender.getStats();
})
.then(function (report) {
    currentReport = report;
    processStats();
})
.catch(function (error) {
  console.log(error.toString());
});

function processStats() {
    // compare the elements from the current report with the baseline
    for (let now of currentReport.values()) {
        if (now.type != "outbound-rtp")
            continue;

        // get the corresponding stats from the baseline report
        let base = baselineReport.get(now.id);

        if (base) {
            remoteNow = currentReport.get(now.remoteId);
            remoteBase = baselineReport.get(base.remoteId);

            var packetsSent = now.packetsSent - base.packetsSent;
            var packetsReceived = remoteNow.packetsReceived - remoteBase.packetsReceived;

            // if intervalFractionLoss is > 0.3, we've probably found the culprit
            var intervalFractionLoss = (packetsSent - packetsReceived) / packetsSent;
        }
    });
}
```
```

--------------------------------

### Example of a stats application

Source: https://www.w3.org/TR/webrtc-stats

This example demonstrates how to use the getStats() method on a sender to monitor packet loss. It takes a baseline report, waits, then takes a current report and compares them to calculate packet loss.

```APIDOC
## [EXAMPLE] Stats Application

### Description
This example shows how to use the WebRTC getStats() API to monitor packet loss and identify potential issues with audio quality.

### Code Example
```javascript
var baselineReport, currentReport;
var sender = pc.getSenders()[0];

sender.getStats().then(function (report) {
    baselineReport = report;
})
.then(function() {
    return new Promise(function(resolve) {
        setTimeout(resolve, aBit); // ... wait a bit
    });
})
.then(function() {
    return sender.getStats();
})
.then(function (report) {
    currentReport = report;
    processStats();
})
.catch(function (error) {
  console.log(error.toString());
});

function processStats() {
    // compare the elements from the current report with the baseline
    for (let now of currentReport.values()) {
        if (now.type != "outbound-rtp")
            continue;

        // get the corresponding stats from the baseline report
        let base = baselineReport.get(now.id);

        if (base) {
            remoteNow = currentReport.get(now.remoteId);
            remoteBase = baselineReport.get(base.remoteId);

            var packetsSent = now.packetsSent - base.packetsSent;
            var packetsReceived = remoteNow.packetsReceived - remoteBase.packetsReceived;

            // if intervalFractionLoss is > 0.3, we've probably found the culprit
            var intervalFractionLoss = (packetsSent - packetsReceived) / packetsSent;
        }
    });
}
```
```

--------------------------------

### Simulcast encoding parameters example

Source: https://www.w3.org/TR/webrtc

Configures three simulcast encodings with different resolutions, disabling the higher layers initially. Note the missing comma after the first object, which is a syntax error in the original example.

```javascript
// Example of 3-layer spatial simulcast with all but the lowest resolution layer disabled
var encodings = [
  {rid: 'q', active: true, scaleResolutionDownBy: 4.0}
  {rid: 'h', active: false, scaleResolutionDownBy: 2.0},
  {rid: 'f', active: false},
];
```

--------------------------------

### Example of a stats application for packet loss detection

Source: https://www.w3.org/TR/webrtc-stats

A stats application example that checks for packet loss by comparing baseline and current RTCP stats. It uses getStats() on the first sender, waits briefly, and then processes the reports. The example assumes a variable 'aBit' and a function 'processStats' that calculates intervalFractionLoss; if it exceeds 0.3, packet loss is likely the cause.

```javascript
var baselineReport, currentReport;
var sender = pc.getSenders()[0];

sender.getStats().then(function (report) {
    baselineReport = report;
})
.then(function() {
    return new Promise(function(resolve) {
        setTimeout(resolve, aBit); // ... wait a bit
    });
})
.then(function() {
    return sender.getStats();
})
.then(function (report) {
    currentReport = report;
    processStats();
})
.catch(function (error) {
  console.log(error.toString());
});

function processStats() {
    // compare the elements from the current report with the baseline
    for (let now of currentReport.values()) {
        if (now.type != "outbound-rtp")
            continue;

        // get the corresponding stats from the baseline report
        let base = baselineReport.get(now.id);

        if (base) {
            remoteNow = currentReport.get(now.remoteId);
            remoteBase = baselineReport.get(base.remoteId);

            var packetsSent = now.packetsSent - base.packetsSent;
            var packetsReceived = remoteNow.packetsReceived - remoteBase.packetsReceived;

            // if intervalFractionLoss is > 0.3, we've probably found the culprit
            var intervalFractionLoss = (packetsSent - packetsReceived) / packetsSent;
        }
    });
}
```

--------------------------------

### Configure identity provider with setIdentityProvider

Source: https://www.w3.org/TR/webrtc-identity

Configures the identity provider for the peer connection. This is the minimal setup required to enable identity assertions.

```javascript
pc.setIdentityProvider('example.com');
```

--------------------------------

### Perfect negotiation example with polite/impolite roles

Source: https://www.w3.org/TR/webrtc

Implements the perfect negotiation pattern to manage signaling without glare. Uses a polite boolean to designate roles: polite peer rolls back on incoming offers, impolite peer ignores offers that collide. Handles ICE candidates, negotiationneeded, and incoming messages with proper state tracking.

```javascript
const signaling = new SignalingChannel(); // handles JSON.stringify/parse
const constraints = {audio: true, video: true};
const configuration = {iceServers: [{urls: 'stun:stun.example.org'}]};
const pc = new RTCPeerConnection(configuration);

// call start() anytime on either end to add camera and microphone to connection
async function start() {
  try {
    const stream = await navigator.mediaDevices.getUserMedia(constraints);
    for (const track of stream.getTracks()) {
      pc.addTrack(track, stream);
    }
    selfView.srcObject = stream;
  } catch (err) {
    console.error(err);
  }
}

pc.ontrack = ({track, streams}) => {
  // once media for a remote track arrives, show it in the remote video element
  track.onunmute = () => {
    // don't set srcObject again if it is already set.
    if (remoteView.srcObject) return;
    remoteView.srcObject = streams[0];
  };
};

// - The perfect negotiation logic, separated from the rest of the application ---

// keep track of some negotiation state to prevent races and errors
let makingOffer = false;
let ignoreOffer = false;
let isSettingRemoteAnswerPending = false;

// send any ice candidates to the other peer
pc.onicecandidate = ({candidate}) => signaling.send({candidate});

// let the "negotiationneeded" event trigger offer generation
pc.onnegotiationneeded = async () => {
  try {
    makingOffer = true;
    await pc.setLocalDescription();
    signaling.send({description: pc.localDescription});
  } catch (err) {
     console.error(err);
  } finally {
    makingOffer = false;
  }
};

signaling.onmessage = async ({data: {description, candidate}}) => {
  try {
    if (description) {
      // An offer may come in while we are busy processing SRD(answer).
      // In this case, we will be in "stable" by the time the offer is processed
      // so it is safe to chain it on our Operations Chain now.
      const readyForOffer =
          !makingOffer &&
          (pc.signalingState == "stable" || isSettingRemoteAnswerPending);
      const offerCollision = description.type == "offer" && !readyForOffer;

      ignoreOffer = !polite && offerCollision;
      if (ignoreOffer) {
        return;
      }
      isSettingRemoteAnswerPending = description.type == "answer";
      await pc.setRemoteDescription(description); // SRD rolls back as needed
      isSettingRemoteAnswerPending = false;
      if (description.type == "offer") {
        await pc.setLocalDescription();
        signaling.send({description: pc.localDescription});
      }
    } else if (candidate) {
      try {
        await pc.addIceCandidate(candidate);
      } catch (err) {
        if (!ignoreOffer) throw err; // Suppress ignored offer's candidates
      }
    }
  } catch (err) {
    console.error(err);
  }
}
```

--------------------------------

### Create RTCDataChannel for peer-to-peer chat

Source: https://www.w3.org/TR/webrtc

Creates an RTCDataChannel for a simple chat application. It sets up a peer connection, handles ICE candidates and negotiationneeded events, and uses a negotiated data channel with id 0. The signaling.onmessage handler starts the connection if not already started and processes incoming descriptions and candidates.

```javascript
const signaling = new SignalingChannel(); // handles JSON.stringify/parse
const configuration = {iceServers: [{urls: 'stun:stun.example.org'}]};
let pc, channel;

// call start() to initiate
function start() {
  pc = new RTCPeerConnection(configuration);

  // send any ice candidates to the other peer
  pc.onicecandidate = ({candidate}) => signaling.send({candidate});

  // let the "negotiationneeded" event trigger offer generation
  pc.onnegotiationneeded = async () => {
    try {
      await pc.setLocalDescription();
      // send the offer to the other peer
      signaling.send({description: pc.localDescription});
    } catch (err) {
      console.error(err);
    }
  };

  // create data channel and setup chat using "negotiated" pattern
  channel = pc.createDataChannel('chat', {negotiated: true, id: 0});
  channel.onopen = () => input.disabled = false;
  channel.onmessage = ({data}) => showChatMessage(data);

  input.onkeydown = ({key}) => {
    if (key != 'Enter') return;
    channel.send(input.value);
  }
}

signaling.onmessage = async ({data: {description, candidate}}) => {
  if (!pc) start();

  try {
    if (description) {
      await pc.setRemoteDescription(description);
      // if we got an offer, we need to reply with an answer
      if (description.type == 'offer') {
        await pc.setLocalDescription();
        signaling.send({description: pc.localDescription});
      }
    } else if (candidate) {
      await pc.addIceCandidate(candidate);
    }
  } catch (err) {
    console.error(err);
  }
};
```

--------------------------------

### createAnswer

Source: https://www.w3.org/TR/webrtc

Creates an SDP answer for the remote configuration, providing the local session description.

```APIDOC
## createAnswer

### Description
The `createAnswer` method generates an SDP answer with the supported configuration for the session that is compatible with the parameters in the remote configuration. Like `createOffer`, the returned blob of SDP contains descriptions of the local `MediaStreamTrack`s attached to this `RTCPeerConnection`, the codec/RTP/RTCP options negotiated for this session, and any candidates that have been gathered by the ICE Agent. The options parameter may be supplied to provide additional control over the generated answer.

### Method
createAnswer

### Parameters
- **options** (optional) - Additional control over the generated answer.

### Returns
Returns a Promise that resolves with an RTCSessionDescription containing the SDP answer.

### Exceptions
- `InvalidStateError` - If the RTCPeerConnection is closed or the signaling state is not "have-remote-offer" or "have-local-pranswer".
- `OperationError` - If the answer could not be generated due to system resource failure.
```

--------------------------------

### RTCPeerConnection.constructor()

Source: https://www.w3.org/TR/webrtc

Creates a new RTCPeerConnection instance. Validates provided certificates, initializes the ICE agent, and sets up all internal state slots for the connection.

```APIDOC
## RTCPeerConnection.constructor()

### Description
Creates a new RTCPeerConnection instance. Validates provided certificates, initializes the ICE agent, and sets up all internal state slots for the connection.

### Method
Constructor

### Parameters
#### Configuration
- **certificates** (sequence<RTCCertificate>) - Optional - A list of certificates to use for the connection. If empty, new certificates are generated.

### Exceptions
- **UnknownError** - Thrown if any step fails for a reason not specified.
- **InvalidAccessError** - Thrown if a certificate has expired or its origin does not match the document origin.

### Steps
1. If any step fails for an unspecified reason, throw an UnknownError.
2. Create a new RTCPeerConnection object.
3. Initialize the [[DocumentOrigin]] internal slot to the relevant settings object's origin.
4. Let configuration be the first argument.
5. If certificates is non-empty, for each certificate:
   - If certificate.expires is less than the current time, throw InvalidAccessError.
   - If certificate.[[Origin]] is not same origin with connection.[[DocumentOrigin]], throw InvalidAccessError.
   - Store the certificate.
6. Otherwise, generate new RTCCertificate instances (may be asynchronous).
7. Initialize the ICE Agent.
8. Set the [[Configuration]] internal slot to null and apply the configuration.
9. Set [[IsClosed]] to false.
10. Set [[NegotiationNeeded]] to false.
11. Set [[SctpTransport]] to null.
12. Set [[DataChannels]] to an empty ordered set.
13. Set [[Operations]] to an empty list.
14. Set [[UpdateNegotiationNeededFlagOnEmptyChain]] to false.
15. Set [[LastCreatedOffer]] to "".
16. Set [[LastCreatedAnswer]] to "".
17. Set [[EarlyCandidates]] to an empty list.
18. Set [[SignalingState]] to "stable".
19. Set [[IceConnectionState]] to "new".
20. Set [[IceGatheringState]] to "new".
21. Set [[ConnectionState]] to "new".
22. Set [[PendingLocalDescription]] to null.
23. Set [[CurrentLocalDescription]] to null.
24. Set [[PendingRemoteDescription]] to null.
25. Set [[CurrentRemoteDescription]] to null.
26. Set [[LocalIceCredentialsToReplace]] to an empty set.
27. Return the connection.
```

--------------------------------

### Configure identity provider with options using setIdentityProvider

Source: https://www.w3.org/TR/webrtc-identity

Configures the identity provider with a username hint and a peer identity. The usernameHint suggests the user's identity, and peerIdentity specifies the expected identity of the remote peer.

```javascript
pc.setIdentityProvider('example.com', {
  usernameHint: 'alice@example.com',
  peerIdentity: 'bob@example.net'
});
```

--------------------------------

### Append tones to DTMF tone buffer

Source: https://www.w3.org/TR/webrtc

Appends tones to the DTMF tone buffer safely. It inserts '123' and then appends '456' to the existing buffer before playout has started.

```javascript
if (sender.dtmf.canInsertDTMF) {
  sender.dtmf.insertDTMF('123');
  // append more tones to the tone buffer before playout has begun
  sender.dtmf.insertDTMF(sender.dtmf.toneBuffer + '456');
```
Tokens:
Raw