2.3.1 Events

oncandidate of type EventHandler,

This event handler, of event handler event type candidate, must be fired to allow a developer's JavaScript to receive a discovered ICE candidate (RTCIceCandidateDescription).

| Event Argument | Description | |--- | --- | |RTCIceCandidateDescription candidate |A local ICE candidate. |

onendofcandidates of type EventHandler,

This event handler, of event handler event type endofcandidates, must be fired to allow a developer's JavaScript to be notified when all candidate discoveries have completed.

Event arguments: none

onactivecandidate of type EventHandler,

This event handler, of event handler event type activecandidate, must be fired to allow a developer's JavaScript to be notified which active ICE candidate local/remote pairing the connection is using. This event could change over time as more optimal routes are discovered.

| Event Argument | Description | |--- | --- | |RTCIceCandidateDescription localCandidate |The connected local ICE candidate. | |RTCIceCandidateDescription remoteCandidate |The connected remote ICE candidate. |

onconnected of type EventHandler,

This event handler, of event handler event type connected, must be fired to allow a developer's JavaScript to be notified when the RTCConnection has been paired with its remote and the ICE connection has been established.

Event arguments: none

ondisconnected of type EventHandler,

This event handler, of event handler event type disconnected, must be fired to allow a developer's JavaScript to be notified when the RTCConnection has been disconnected.

Event arguments: none

onaddstream of type EventHandler,

This event handler, of event handler event type addstream, must be fired to allow a developer's JavaScript to be notified when a receiving MediaStream is added. It is fired when calling the receiveTrack method by passing as argument a RTCTrackDescription with a msid value which does not match the msid of other receiving tracks.

| Event Argument | Description | |--- | --- | |MediaStream stream |The MediaStream instance being added by the remote peer. |

onunknowntrack of type EventHandler,

This event handler, of event handler event type unknowntrack, must be fired to allow a developer's JavaScript to be notified when a track for which there is not RTCTrackDescription has been connected from the remote peer.

It is possible for a peer to receive a track for which its RTCTrackDescription has not yet been received (via wire signaling) or for which there won't be RTCTrackDescription at all. If an unknown track (for which there is no RTCTrackDescription) is connected this event fires by providing a collection of the RTP extension headers present in the RTP packets.

The offerer can then indicate, via custom wire signaling, those desired RTP extension header and values to the remote peer, and the remote peer starts sending tracks with the requested RTP extension headers, so the offerer can identify them when the unknowntrack event fires.

| Event Argument | Description | |--- | --- | |rtpExtHeaders |A collection of RTP extension header and value pairs. |

onadddtmfhandler of type EventHandler,

This event handler, of event handler event type adddtmfhandler, must be fired to allow a developer's JavaScript to be notified when a receiving RTCDTMFHandler is added. It is fired when calling the receiveTrack method by passing as argument the RTCTrackDescription of a receiving audio MediaStreamTrack including a "dtmf" codec.

| Event Argument | Description | |--- | --- | |RTCDTMFHandler handler |The RTCDTMFHandler instance being added by the remote peer. |

2.3.2 Methods

2.3.3 The RTCConnectionOptions Object

dictionary RTCConnectionOptions {
    sequence<RTCIceServer>?     iceServers
    RTCSocket?                  socket
};

2.3.4 The RTCIceServer Object

dictionary RTCIceServer {
    sequence<DOMString>         url;
    DOMString?                  credential;
};

[ { url:"stun:stun.example.net" } , { url:"turn:user@turn.example.org", credential:"myPassword"} ]

2.3.5 The RTCSocket Class

The RTCSocket class describes a local socket. A local socket can be reused within different RTCConnection instances (useful for media forking).

A RTCSocket can be retrieved from its RTCConnection by calling the getLocalSocket method on it.

2.3.6 The RTCConnectionSide Object

The RTCConnectionSide Object contains information for both sides of the connection. An RTCConnection has both a local RTCConnectionSide (whose attributes are readonly) and a remote RTCConnectionSide (whose attributes must be set by the JavaScript's developer before attempting the connection procedure (this is, before calling connect on the RTCConnection).

dictionary RTCConnectionSide {
    attribute RTCIceConnectionInfo  ice;
    attribute RTCDtlsConnectionInfo dtls;
};

2.3.7 The RTCIceConnectionInfo Object

dictionary RTCIceConnectionInfo {
    DOMString                   usernameFrag;
    DOMString                   password;
};

2.3.8 The RTCDtlsConnectionInfo Object

dictionary RTCDtlsConnectionInfo {
    attribute CertificateFingerprint   fingerprint;
};

dictionary CertificateFingerprint {
    getter ArrayBuffer (DOMString hashFunction);
};

2.3.9 The RTCIceCandidateDescription Object

dictionary RTCIceCandidateDescription {
    DOMString                           foundation;
    int                                 component;
    DOMString                           transport;
    int                                 priority;
    DOMString                           connectionAddress;
    int                                 connectionPort;
    DOMString                           type;
    DOMString                           relAddress;
    int                                 relPort;
};

{
  foundation: "abcd1234",
  component: 1,
  transport: "udp",
  priority: 1694498815,
  connectionAddress: "192.0.2.33",
  connectionPort: 10000,
  type: "host"
};

2.3.10 The RTCTrackFilter Object

This Object is used to filter the output of the tracks method in RTCConnection.

dictionary RTCTrackFilter {
    MediaStream?        mediaStream;
    DOMString?          kind;
};

3.3.1 Attributes

source of type MediaStreamTrack, readonly

The associated MediaStreamTrack instance.

kind of type DOMString, readonly

Can be "audio" or "video".

ssrc of type DOMString, readonly

msid of type sequence

A sequence of id attributes of the MediaStream instances this track belongs to.

codecs of type sequence

When setting the codec list for a sending track, the browser must choose the first supported codec in the list.

mediaAttributes of type sequence

rtpExtHeaders of type Object.

An Object which RTP extension header name and value pairs (useful for the onunknowntrack event usage in RTCConnection.

3.3.2 Methods

3.3.3 The RTCTrackDescription Object

dictionary RTCTrackDescription {
    DOMString                           kind;
    DOMString                           ssrc;
    sequence<DOMString>                 msid;
    sequence<RTCCodec>                  codecs;
    sequence<RTCMediaAttributes>?       mediaAttributes;
    Object?                             rtpExtHeaders;
};

The meaning of attributes of RTCTrackDescription is the same as in the RTCTrack interface.

When passing a RTCTrackDescription to the receiveTrack method of a RTCConnection, the values in the codecs field tells the browser to be ready to receive RTP with any of the listed codecs.

TODO: RTCConnection.receiveTrack() should throw an exception in case the browser does not support any of the codec in the given RTCTrackDescription.

{
  kind: "audio",
  ssrc: "1234",
  msid: ["m1"],
  codecs: [
      {
          payload-id: 96,
          name: "opus",
          clockRate: 48000,
          numChannels: 2
      }
  ]
}

3.3.4 The RTCCodec Object

dictionary RTCCodec {
    unsigned byte       payload-id;
    DOMString           name;
    unsigned int?       clockRate;
    unsigned int?       numChannels;
    RTCCodecParam[]     params;
}

dictionary RTCCodecParam {
    DOMString           name;
    DOMString?          value;
}

3.3.5 The RTCMediaAttributes Object

dictionary RTCMediaAttributes {
    int?        videoMaxWidth;
    int?        videoMaxHeight;
};

TODO: Complete.

4.2.1 Events

ondtmf of type EventHandler,

This event handler, of event handler event type candidate, must be fired to allow a developer's JavaScript to receive a DTMF tone from the remote peer.

| Event Argument | Description | |--- | --- | |DOMString tone |The received DTMF tone. | }; ```

4.2.2 Methods

4.2.3 Audio RTCTrackDescription Example with DTMF

Calling addDtmfHandler method on a RTCConnection (including at least one audio MediaStreamTrack) would enhance the RTCTrack of the audio track as follows:

{
  kind: "audio",
  ssrc: "1234",
  msid: ["m1"],
  codecs: [
      {
          payload-id: 96,
          name: "opus",
          clockRate: 48000,
          numChannels: 2
      },
      {
          payload-id: 101,
          name: "dtmf"
      }
  ]
}

Methods

The RTCCapabilities Object

dictionary RTCCapabilities {
    sequence<RTCCodec>                  audioCodecs;
    sequence<RTCCodec>                  videoCodecs;
};

TODO: Complete.

Methods

Events

onconnected of type EventHandler,

This event handler, of event handler event type connected, must be fired to allow a developer's JavaScript to be notified when a remote MediaStream is connected, which means that RTP for at least one of the tracks in this MediaStream has been received.

Event arguments: none

ondisconnected of type EventHandler,

This event handler, of event handler event type disconnected, must be fired to allow a developer's JavaScript to be notified when a remote MediaStream is disconnected, which means that a RTCP BYE has been received or RTP timeout occurred for the last remaining track in this MediaStream.

Event arguments: none

Events

onconnected of type EventHandler,

This event handler, of event handler event type connected, must be fired to allow a developer's JavaScript to be notified when a remote MediaStreamTrack is connected, which means that RTP for this track has been received.

Note that this event is just fired for a remote MediaStreamTrack which MediaStream was already connected (so onaddstream event was called for it).

Event arguments: none

ondisconnected of type EventHandler,

This event handler, of event handler event type disconnected, must be fired to allow a developer's JavaScript to be notified when a remote MediaStreamTrack is disconnected, which means that a RTCP BYE has been received or RTP timeout occurred.

Event arguments: none