Overview

RTCConnection is the main class of ORTC. A RTCConnection instance provides the interface for a browser to directly communicate with another browser or a compliant device, for sending and receiving media stream tracks. Communication is signaled through an external means such as via HTTP or WebSocket through a web server or WebSocket server by unspecified means.

Operation

A peer instantiates a RTCConnection. Once the RTCConnection has been instantiated and the connect method called, the ICE gathering procedure automatically starts retrieving local ICE candidates.

The peer can, at any time, signal its ICE information to the remote peer. Once the remote ICE information is entered into the RTCConnection ICE establishment procedure begins until the connection is established. ICE candidates can be signaled one by one to each other or at any time (trickle-ICE). In order to apply a discovered local ICE candidate in the RTCConnection the event oncandidate is called by passing as argument the RTCIceCandidateInfo. The remote ICE candidates are added to the RTCConnection by using the addRemoteCandidate method.

The developer's JavaScript can attach MediaStream instances to the RTCConnection to be sent to the remote peer. Audio/video sending tracks can be individually managed by constructing their associated RTCTrack instance via the send method. The developer's JavaScript can also signal the receiving tracks information by providing an RTCTrack to the receive method.

Interface Definition

readonly attribute RTCSocket> socket

The readonly value points to the RTCSocket object associated to the RTCConnection. If an RTCSocket object is not specified in the RTCConnectionOptions object then an RTCSocket object is automatically created and attached to the RTCConnection.

readonly attribute RTCConnectionState state

The current RTCConnectionState connectivity state of the RTCConnection object.

attribute RTCConnectionRole role

The current RTCConnectionRole of the RTCConnection object.

readonly attribute RTCConnectionInfo local

Contains readonly information about the local connection, including the ICE negotiation attributes and the DTLS fingerprints.

attribute RTCConnectionInfo remote

Contains information about the remote connection, including the ICE negotiation attributes and the readonly remote DTLS fingerprints as negotiated during the DTLS negotiation phase that are valid once the RTCConnection enters the RTCConnectionState connected state.

void addRemoteCandidate(RTCCandidateDescription candidate)

Adds a remote ICE candidate to the RTCConnection.

Parameter	Type	Nullable	Optional	Description
candidate	RTCIceCandidateInfo	no	no

void connect()

Starts the ICE connectivity tests and establishment procedure with the peer. If remote ICE candidates are provided once this method has been called, they will be also considered for the ICE connection connectivity testing procedure.

If gather has not been called at this point then it is implicitly called to start the candidate discovery process.

Connection data for the remote side (the iceUsernameFrag and icePassword attributes within the remote RTCConnectionInfo attribute) must be set before calling this method.

void gather()

This method will usually be called automatically upon onnetworkchange but can be called manually when a higher layer detects a network topology change (e.g. in mobile network). By calling this method the ICE candidate gathering procedure re-starts again as it did when the RTCConnection was instantiated and onendofcandidates will be called again when no more candidates are able to be discovered.

If gather is called before connect, the ICE candidate gathering process will start immediately but no connectivity checks will be performed until connect is called.

(RTCSTream? or RTCTrack?) send((MediaStream or MediaStreamTrack or RTCTrack or RTCStream) streamOrTrack)

Starts sending a MediaStream or MediaStreamTrack over an RTCConnection.

If an MediaStream is passed in an RTCStream is returned. If an MediaStreamTrack is passed in an RTCTrack is returned.

To send or update the attributes for an existing RTCStream or an RTCTrack call the method with the updated object values. Upon success the same object is returned.

Parameter	Type	Nullable	Optional	Description
streamOrTrack	MediaStream or MediaStreamTrack or RTCStream or RTCTrack	no	no

(RTCStream? or RTCTrack?) receive((RTCStream or RTCTrack) streamOrTrack)

Tell the RTCConnection to expect to start receiving a RTCStream or RTCTrack from the remote peer.

By creating an RTCStream or an RTCTrack with the correct values pre-filled this method will start the receive process for the stream or track from the RTCConnection. Upon success the source for the respective RTCStream and RTCTrack are filled with the MediaStream or MediaStreamTrack objects.

Parameter	Type	Nullable	Optional	Description
streamOrTrack	RTCStream or RTCTrack	no	no

sequence<RTCStream> sendStreams()

Returns a sequence of RTCStream instances being sent over the RTCConnection.

sequence<RTCTrack> sendTracks()

Returns a sequence of RTCTrack instances being sent over the RTCConnection.

sequence<RTCStream> receiveStreams()

Returns a sequence of RTCStream instances being received over the RTCConnection.

sequence<RTCTrack> receiveTracks()

Returns a sequence of RTCTrack instances being received over the RTCConnection.

void close()

Closes the connection. Once closed the object is shutdown an no longer re-useable.

attribute EventHandler oncandidate

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

To preserve privacy, this event's default action can be canceled (see http://www.w3.org/TR/DOM-Level-3-Events/#events-event-type-canCancel). The default action is to add the candidate to the list of connectivity tests. Canceling the candidate event will prevent connectivity tests on the candidate.

Event Argument	Description
RTCIceCandidateInfo candidate	A local ICE candidate.

attribute EventHandler onendofcandidates

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 after the connect method is called and after the gather method executes and completes.

Event arguments: none

attribute EventHandler onactivecandidate

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
RTCIceCandidateInfo localCandidate	The connected local ICE candidate.
RTCIceCandidateInfo remoteCandidate	The connected remote ICE candidate.

attribute EventHandler onstatechanged

This event handler, of event handler event type statechanged, must be fired to allow a developer's JavaScript to be notified when the RTCConnection object state has changed.

Event Argument	Description
RTCConnectionState state	The state at the time this event fired.

attribute EventHandler onnetworkchange

This event handler, of event handler event type networkchange, must be fired to allow a developer's JavaScript to be notified when a change has been detected in the network topology.

The default action is to automatically call the RTCConnection gather method. This event's default action can be canceled (see http://www.w3.org/TR/DOM-Level-3-Events/#events-event-type-canCancel).

Event arguments: none

attribute EventHandler onunknowntrack

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 RTCTrack has been connected from the remote peer.

It is possible for a peer to receive a track for which its RTCTrack information has not yet been received (via wire signaling) and added via the receive method or for which there won't be RTCTrack known in advance at all. If an unknown track (for which there is no RTCTrack) is connected this event fires by providing the RTCTrack and 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 onunknowntrack event fires.

Event Argument	Description
RTCTrack track	The newly discovered track object.
Object rtpExtHeaders	A collection of RTP extension header and value pairs.

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

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

Overview

An RTCStream instance is associated to a sending or receiving MediaStream and provides RTC related methods to it.

Operation

A RTCStream instance is retrieved from a RTCConnection via the sendStreams or receiveStreams methods.

Interface Definition

attribute MediaStream source

The associated MediaStreamTrack instance.

attribute DOMString msid

The associated media stream id.

sequence<RTCTrack> tracks()

A sequence of contained RTCTrack instances

void start()

Starts sending the track on the wire (if the RTCConnection is connected, or wait until it becomes connected).

void stop()

Stops sending the track on the wire.

void remove()

Remove this sending stream from the RTCConnection (automatically stops sending it on the wire). This method does not alter the original MediaStream, but just tells the RTCConnection to ignore the stream.

Overview

An RTCTrack instance is associated to a sending MediaStreamTrack and provides RTC related methods to it.

Operation

A RTCTrack instance is retrieved from a RTCConnection via the track or tracks methods or constructed from an MediaStreamTrack object.

Interface Definition

attribute MediaStreamTrack source

The associated MediaStreamTrack instance.

This attribute does not jsonify so that the entire object can be jsonified for easier signaling.

attribute DOMString id

The id of the associated MediaStreamTrack instance.

attribute DOMString kind

Can be "audio" or "video".

attribute unsigned long ssrc

attribute sequence<RTCCodec> codecs

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

attribute sequence<RTCMediaAttributes> mediaAttributes

attribute Object rtpExtHeaders

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

void start()

Starts sending the track on the wire (if the RTCConnection is connected, or wait until it becomes connected).

void stop()

Stops sending the track on the wire.

void remove()

Remove this sending track from the RTCConnection (automatically stops sending it on the wire). This method does not alter the original MediaStream, but just tells the RTCConnection to ignore the track.

Example

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

The RTCCodec Object

unsigned byte payload-id

DOMString name

unsigned int? clockRate

unsigned int? numChannels

RTCCodecParam[] params

DOMString name

DOMString? value

The RTCMediaAttributes Object

int? videoMaxWidth

int? videoMaxHeight

TODO: Complete.

Overview

An RTCDTMFTrack class instance allows sending DTMF tones to/from the remote peer.

Interface Definition

void playTones(DOMString tones, optional unsigned duration = 100, optional unsigned long interToneGap = 70)

This event handler, of event handler event type tone, 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 character.
unsigned length duration	The duration of the tone (in milliseconds).

attribute EventHandler ontone

Method used for sending DTMF tones. The tones parameter is treated as a series of characters. The characters 0 through 9, A through D, #, and * generate the associated DTMF tones. The characters a to d are equivalent to A to D. The character ',' indicates a delay of 2 seconds before processing the next character in the tones parameter. Unrecognized characters are ignored.

The duration parameter indicates the duration in ms to use for each character passed in the tones parameters. The duration cannot be more than 6000 ms or less than 70 ms. The default duration is 100 ms for each tone.

The interToneGap parameter indicates the gap between tones. It must be at least 70 ms. The default value is 70 ms.

Parameter	Type	Nullable	Optional	Description
tones	DOMString	no	no
duration	long	no	yes
interToneGap	long	no	yes

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

Overview

An RTCDataChannel class instance allows sending data messages to/from the remote peer.

Interface Definition

readonly attribute RTCConnection connection

The readonly value referring to the related connection object.

readonly attribute DOMString id

An identifier for the data channel.

readonly attribute DOMString type

The type of data channel being used.

void send(Object data)

Method used for sending data to the remote peer.

Parameter	Type	Nullable	Optional	Description
data	Object	no	no

attribute EventHandler ondata

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

Event Argument	Description
Object data	The received remote data.

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

Simple Peer-to-peer Example

This example code provides a basic audio&video session between two browsers.

var signalingChannel = new SignalingChannel();
var conn;


// call start() to initiate
function start() {
    conn = new RTCConnection({ iceServers: [{ url: "stun:stun.example.org" }] });

    // send my ICE information to the other peer
    signalingChannel.send(JSON.stringify({ "iceInfo": { "usernameFrag": conn.local.ice.usernameFrag, "password": conn.local.ice.password } }));

    // apply any local ICE candidate and send it to the remote
    conn.oncandidate = function (evt) {
        signalingChannel.send(JSON.stringify({ "candidate": evt.candidate }));
    }

    // get a local stream, show it in a self-view and add it to be sent
    navigator.getUserMedia({ "audio": true, "video": true }, function (stream) {
        selfView.src = URL.createObjectURL(stream);
        conn.send(stream);
        // send stream description to the peer
        conn.sendStreams().forEach(function(stream) {
            signalingChannel.send(JSON.stringify({ "stream": stream }));
        });
    }, logError);
}

signalingChannel.onmessage = function (evt) {
    if (!conn)
        start();

    var message = JSON.parse(evt.data);
    if (message.iceInfo) {
        conn.remote.ice.usernameFrag = message.iceInfo.usernameFrag;
        conn.remote.ice.password = message.iceInfo.password;
        conn.connect();
    }
    if (message.candidate) {
        conn.addRemoteCandidate(message.candidate);
    }
    if (message.stream) {
        // once remote stream information arrives, show it in the remote video element
        remoteView.src = URL.createObjectURL(conn.receive(message.stream).source);
    }
};


function logError(error) {
    log(error.name + ": " + error.message);
}