Broken link to RTCSessionDescriptionInit, RTCLocalSessionDescriptionInit

[bc-lee]

MDN URL

https://developer.mozilla.org/en-US/docs/Web/API/RTCSessionDescription

What specific section or headline is this issue about?

No response

What information was incorrect, unhelpful, or incomplete?

The page for RTCPeerConnection.createAnswer has a broken link to RTCSessionDescriptionInit because there is no separate page for it

Actually there is a bigger issue here. MDN needs to clarify the relationship between RTCSessionDescription, RTCSessionDescriptionInit, and RTCLocalSessionDescriptionInit.

What did you expect to see?

A page for RTCSessionDescriptionInit, also a separate page for RTCLocalSessionDescriptionInit would be nice. Also clarify the relationship between RTCSessionDescription, RTCSessionDescriptionInit, and RTCLocalSessionDescriptionInit.

Do you have any supporting links, references, or citations?

https://w3c.github.io/webrtc-pc

Do you have anything more you want to share?

Here is my understanding of this issue (since this is long, I will use a collapsible section):

Details

Relevant WebIDL definitions for RTCSessionDescription, RTCSessionDescriptionInit, and RTCLocalSessionDescriptionInit (from https://w3c.github.io/webrtc-pc):

[Exposed=Window]
interface RTCSessionDescription {
  constructor(RTCSessionDescriptionInit descriptionInitDict);
  readonly attribute RTCSdpType type;
  readonly attribute DOMString sdp;
  [Default] RTCSessionDescriptionInit toJSON();
};

dictionary RTCSessionDescriptionInit {
  required RTCSdpType type;
  DOMString sdp = "";
};

dictionary RTCLocalSessionDescriptionInit {
  RTCSdpType type;
  DOMString sdp = "";
};

[Exposed=Window]
interface RTCPeerConnection : EventTarget  {
...
  Promise<RTCSessionDescriptionInit> createOffer(optional RTCOfferOptions options = {});
  Promise<RTCSessionDescriptionInit> createAnswer(optional RTCAnswerOptions options = {});

  Promise<undefined> setLocalDescription(optional RTCLocalSessionDescriptionInit description = {});
  readonly attribute RTCSessionDescription? localDescription;
  readonly attribute RTCSessionDescription? currentLocalDescription;
  readonly attribute RTCSessionDescription? pendingLocalDescription;
  Promise<undefined> setRemoteDescription(RTCSessionDescriptionInit description);
  readonly attribute RTCSessionDescription? remoteDescription;
  readonly attribute RTCSessionDescription? currentRemoteDescription;
  readonly attribute RTCSessionDescription? pendingRemoteDescription;
...
}

Understanding RTCSessionDescription:

• Core Interface: RTCSessionDescription is the fundamental interface representing a session description in WebRTC signaling.
• Properties: It has two essential properties:
  • type: Specifies the SDP type (e.g., "offer", "answer", "pranswer", or "rollback").
  • sdp: Contains the actual SDP string, which is meaningless for the "rollback" type.

RTCSessionDescriptionInit and RTCLocalSessionDescriptionInit

These names closely resemble RTCSessionDescription, but they serve a different purpose. Here's a breakdown:

• Dictionaries, Not Classes: Unlike RTCSessionDescription (an interface), these are dictionaries. You don't need a specific instance to create them; any conforming object will suffice.
• Arguments for Setting Session Descriptions: They are primarily used as arguments for the RTCPeerConnection.setLocalDescription() and RTCPeerConnection.setRemoteDescription() methods, allowing you to set session descriptions without creating a full-fledged RTCSessionDescription object.
• Return Values for Creating SDP: RTCSessionDescriptionInit is also the return type for RTCPeerConnection.createOffer() and RTCPeerConnection.createAnswer(), which generate SDP strings. These generated SDPs are typically used for either setting a local description or sending them to a remote peer.

Why Separate Interfaces?

The separation between RTCSessionDescriptionInit and RTCLocalSessionDescriptionInit might seem unnecessary and confusing at first. Here's the reasoning:

• Evolution of WebRTC: WebRTC has been around for over a decade and is constantly evolving. Initially, RTCPeerConnection.setLocalDescription() always required both an SDP string and a type.
• Parameterless setLocalDescription: A few years ago, this method was updated to allow omitting any arguments. This feature, sometimes called "parameterless setLocalDescription," is part of the "Perfect Negotiation" functionality. It enables users to skip the separate calls to RTCPeerConnection.createOffer() and RTCPeerConnection.setLocalDescription(). They can simply use the parameterless version of setLocalDescription().
• RTCLocalSessionDescriptionInit for Flexibility: To accommodate this change, RTCLocalSessionDescriptionInit was introduced. Unlike RTCSessionDescriptionInit, it doesn't even require a type property. In WebIDL, if you call RTCPeerConnection.setLocalDescription() without any arguments, it's equivalent to calling RTCPeerConnection.setLocalDescription({}). This can be seen as a way to enhance WebIDL's flexibility.

In Summary:

• RTCSessionDescription: Core interface representing a session description.
• RTCSessionDescriptionInit: Dictionary used to create session descriptions and as a return type for createOffer() and createAnswer().
• RTCLocalSessionDescriptionInit: Dictionary specifically used for setting local session descriptions, allowing omission of the type property.

MDN metadata

Page report details

• Folder: en-us/web/api/rtcsessiondescription
• MDN URL: https://developer.mozilla.org/en-US/docs/Web/API/RTCSessionDescription
• GitHub URL: https://github.com/mdn/content/blob/main/files/en-us/web/api/rtcsessiondescription/index.md
• Last commit: acfe8c9
• Document last modified: 2023-07-07T07:19:19.000Z