This document defines a set of ECMAScript APIs in WebIDL to allow media to be sent and received from another browser or device implementing the appropriate set of real-time protocols. However, unlike the current WebRTC 1.0 APIs, ORTC does not mandate a media signaling protocol or format. As a result, ORTC does not utilize Session Description Protocol (SDP) within its APIs, nor does it mandate support for the Offer/Answer state machine. Instead, ORTC focuses on "connections" and "tracks" being carried over those connections.

Overview

Object RealTime Communications (ORTC) provides a powerful API for the development of WebRTC based applications. ORTC does not mandate a media signaling protocol or format (as the current WebRTC 1.0 does by mandating SDP Offer/Answer). Instead, ORTC focuses on "sender", "receiver" and "transport" objects, which have "capabilities" describing what they are capable of doing, as well as "parameters" which define what they are configured to do. "Tracks" and "data channels" are sent over the transports, between senders and receivers.

This specification defines several objects: RTCDtlsTransport (Section 2), RTCIceTransport (Section 3), RTCIceListener (Section 4), RTCRtpSender (Section 5), RTCRtpReceiver (Section 6), RTCDTMFTrack (Section 8), RTCDataChannel (Section 9), and RTCSctpTransport (Section 10); RTP dictionaries are described in Section 7.

In a Javascript application utilizing the ORTC API, the relationship between the application and the objects, as well as between the objects themselves is shown below:

The non-normative ORTC Big Picture Diagram

Terminology

The EventHandler interface represents a callback used for event handlers as defined in [[!HTML5]].

The concepts queue a task and fires a simple event are defined in [[!HTML5]].

The terms event, event handlers and event handler event types are defined in [[!HTML5]].

The terms MediaStream, MediaStreamTrack, Constraints, and Consumer are defined in [[!GETUSERMEDIA]].

The RTCDtlsTransport Object

The RTCDtlsTransport includes information relating to Datagram Transport Layer Security (DTLS) transport.

Overview

An RTCDtlsTransport instance is associated to an RTCRtpSender or an RTCRtpReceiver.

Operation

A RTCDtlsTransport instance is optionally constructed from an RTCIceTransport object or an RTCIceTransport is automatically constructed.

Interface Definition

readonly attribute RTCIceTransport transport
The associated RTCIceTransport instance.
readonly attribute RTCDtlsTransportState state
The current state of the DTLS transport.
RTCDtlsParameters getLocalParameters()
Obtain the DTLS parameters of the local RTCDtlsTransport.
RTCDtlsParameters? getRemoteParameters()
Obtain the current DTLS parameters of the remote RTCDtlsTransport.
void start(RTCDtlsParameters remoteParameters)
Start DTLS transport negotiation with the parameters of the remote DTLS transport.
void stop()
Stops and closes the DTLS transport object.
attribute EventHandler? onstatechange
Set this handler to receive events when the state of the DTLS transport changes.

Example


    

enum RTCDtlsTransportState

new
new state
connecting
connecting state
connected
connected state
closed
closed state

The RTCIceTransport Object

The RTCIceTransport includes information relating to Interactive Connectivity Establishment (ICE).

Overview

An RTCIceTransport instance is associated to a transport object (such as RTCDtlsTransport), and provides RTC related methods to it.

Operation

An RTCIceTransport instance is constructed from an RTCIceRole and either an RTCIceListener or an RTCIceOptions object.

Interface Definition

readonly attribute RTCIceRole role
The current role of the ICE transport.
readonly attribute RTCIceTransportState state
The current state of the ICE transport.
readonly attribute sequence<RTCIceCandidate> localCandidates
Sequence of the candidates associated with local RTCIceTransport.
readonly attribute sequence<RTCIceCandidate> remoteCandidates
Sequence of the candidates associated with remote RTCIceTransport.
void gather()
Start gathering RTCIceCandidate objects.
void start(optional RTCIceParameters remoteParameters)
Starts candidates connectivity checks and attempts to connect to the remote RTCIceTransport.
void stop()
Stops and closes the current object.
RTCIceParameters getLocalParameters()
Obtain the ICE parameters of the local RTCIceTransport.
RTCIceParameters? getRemoteParameters()
Obtain the current ICE parameters of the remote RTCIceTransport.
void setRemoteParameters(RTCIceParameters remoteParameters)
Set the remote parameters associated with the remote RTCIceTransport.
void addRemoteCandidate(RTCIceCandidate remoteCandidate)
Add remote candidate associated with remote RTCIceTransport.
attribute EventHandler? onlocalcandidate
Set this handler to receive events when a new local candidate is available.
attribute EventHandler? onstatechange
Set this handler to receive events when the state of the RTCIceTransport has changed.

Examples



// Assume we already have a way to signal. This is an example
// of  how to offer ICE and DTLS parameters and ICE candidates and
// get back ICE and DTLS parameters and ICE candidates, and start
// both ICE and DTLS.

function initiate(signaller) {
 var iceOptions = ...;
 var ice = new RTCIceTransport(RTCIceRole.controlling, iceOptions);
 var dtls = new RTCDtlsTransport(ice);
 // ... get tracks and RTP objects from other example

 signaller.sendInitiate({
   "ice": ice.
getLocalParameters(),
   "dtls": dtls.
getLocalParameters(),
   // ... include RTP info from other example
 }, function(remote) {
   ice.setRemoteParameters(remote.ice);
   dtls.start(remote.dtls);
   // ... start RTP senders and receivers from other example
 });

 ice.oncandidate = function(candidate) {
   signaller.sendLocalCandidate(candidate);
 }

 signaller.onRemoteCandidate = function(candidate) {
   ice.addRemoteCandidate(candidate);
 }

 ice.start();
}

    


// Assume we already have a way to signal and remote info is 
// signalled to us.  This is an example of how to answer with ICE and DTLS
// and DTLS parameters and ICE candidates and start both ICE and DTLS.
//
function accept(signaller, remote) {
 var iceOptions = ...;
 var ice = new RTCIceTransport(iceOptions);
 var dtls = new RTCDtlsTransport(ice);
 // ... get tracks and RTP objects from other example
 ice.oncandidate = function(candidate) {
   signaller.sendLocalCandidate(candidate);
 }

 signaller.onRemoteCandidate = function(candidate) {
   ice.addRemoteCandidate(candidate);
 }

 signaller.sendAccept({
   "ice": ice.
getLocalParameters(),
   "dtls": ice.
getLocalParameters()
   // ... include RTP info from other example
 });

 ice.start(remote.ice);
 dtls.start(remote.dtls);

 // ... start RTP senders and receivers from other example
}

    

enum RTCIceRole

controlling
controlling state
controlled
controlled state

enum RTCIceTransportState

new
new state
checking
checking state
connected
connected state
completed
completed state
disconnected
disconnected state
closed
closed state

The non-normative ICE state transitions are:

The non-normative ICE State Transition Diagram

The RTCIceOptions Object

The RTCIceOptions object includes information relating to ICE configuration.

sequence<RTCIceServer>? iceServers
An array containing STUN and TURN servers available to be used by ICE.

The RTCIceServer Object

The RTCIceServer is used to provide STUN or TURN server configuration. In network topologies with multiple layers of NATs, it is desirable to have a STUN server between every layer of NATs in addition to the TURN servers to minimize the peer to peer network latency.

An example of an array of RTCIceServer objects:


      [ { urls: "stun:stun1.example.net } , { urls:"turn:turn.example.org", username: "user", credential:"myPassword"} ]
    
(DOMString or sequence<DOMString>) urls
STUN or TURN URI(s) as defined in [[!STUN-URI]] and [[!TURN-URI]]
DOMString? username
If this RTCIceServer object represents a TURN server, then this attribute specifies the username to use with that TURN server.
DOMString? credential
If the uri element is a TURN-URI, then this is the credential to use with that TURN server.

The RTCIceCandidate Object

The RTCIceCandidate object includes information relating to an ICE candidate.

{
  foundation: "abcd1234",
  priority: 1694498815,
  connectionAddress: "192.0.2.33",
  connectionPort: 10000,
  type: "host"
};
    
DOMString foundation
A unique identifier that allows ICE to correlate candidates that appear on multiple RTCIceTransports.
unsigned long priority
The assigned priority of the candidate. This is automatically populated by the browser.
DOMString ip
The IP address of the candidate.
unsigned short port
The UDP port for the candidate.
RTCIceCandidateType type
The type of candidate.
DOMString? relatedAddress
For candidates that are derived from others, such as relay or reflexive candidates, this refers to the host candidate that these are derived from. This value is not present on host candidates.
unsigned short? relatedPort
For candidates that are derived from others, such as relay or reflexive candidates, this refers to the host candidate that these are derived from. This value is not present on host candidates.

The RTCIceCandidateType

The RTCIceCandidateType includes the type of ICE candidate.

host
A host candidate.
srflx
A server reflexive candidate.
prflx
A peer reflexive candidate.
relay
A relay candidate.

The RTCIceListener Object

The RTCIceListener enables an endpoint to construct multiple RTCIceTransport objects from a set of local ICE parameters, enabling usage scenarios such as parallel forking.

Overview

An RTCIceListener instance is associated to an RTCIceTransport.

Operation

An RTCIceListener instance is optionally constructed from an RTCIceOptions object, or an RTCIceListener is automatically constructed.

Interface Definition

readonly attribute RTCIceOptions options

The RTCIceOptions instance.

RTCIceParameters getLocalParameters()
readonly attribute sequence<RTCIceCandidate> localCandidates
void start()
void stop()
attribute EventHandler? onlocalcandidate
attribute EventHandler? ongatherfailure

Example



var iceOptions = ...;
var iceListener = new RTCIceListener(iceOptions);
sendInitiate(iceListener.getLocalParameters(), function(response) {
  // We may get N responses
  var ice = new RTCIceTransport(RTCIceRole.controlling, iceListener);
  var ice.setRemoteParameters(response.iceParameters);
  ice.start();
  // ... setup DTLS, RTP, SCTP, etc.
});

iceListener.oncandidate = sendLocalCandidate;
iceListener.start();

    

The RTCRtpSender Object

The RTCRtpSender includes information relating to the RTP sender.

Overview

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

Operation

A RTCRtpSender instance is constructed from an MediaStreamTrack object and associated to an RTCDtlsTransport.

Interface Definition

attribute MediaStreamTrack track

The associated MediaStreamTrack instance.

attribute RTCDtlsTransport transport

The associated RTCDtlsTransport instance.

static RTCRtpCapabilities getCapabilities()

Obtain the capabilities of the RTCRtpSender.

static RTCRtpParameters createParameters(MediaStreamTrack parameters, optional RTCRtpCapabilities capabilities)

Create parameters based on the MediaStreamTrack and the capabilities specified in RTCRtpCapabilities.

static RTCRtpParameters filterParameters(RTCRtpParameters parameters, optional RTCRtpCapabilities capabilities)

Filter parameters based on the RTCRtpCapabilities.

void send(RTCRtpParameters parameters)

Media is controlled by the given "parameters". The sender starts sending when the send() is called and stopped when the stop() is called.

void stop()

Stops sending the track on the wire. Stop is final like MediaStreamTrack

Example


    

The RTCRtpReceiver Object

The RTCRtpReceiver includes information relating to the RTP receiver.

Overview

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

Operation

A RTCRtpReceiver instance is constructed from an MediaStreamTrack object and associated to an RTCDtlsTransport.

Interface Definition

attribute MediaStreamTrack? track

The associated MediaStreamTrack instance.

attribute RTCDtlsTransport transport

The associated RTCDtlsTransport instance.

static RTCRtpCapabilities getCapabilities()

Obtain the capabilities of the RTCRtpReceiver.

static RTCRtpParameters createParameters (DOMString kind, optional RTCRtpCapabilities capabilities)
Create parameters based on the kind and the capabilities specified in RTCRtpCapabilities.
DOMString kind
Specifies kind, either "audio" or "video".
optional RTCRtpCapabilities capabilities
static RTCRtpParameters filterParameters(RTCRtpParameters parameters, optional RTCRtpCapabilities capabilities)

Filter parameters based on the RTCRtpCapabilities.

void receive(RTCRtpParameters parameters)

Media is controlled by the given "parameters". The receiver starts receiving when the receive() is called and stopped when the stop() is called.

void stop()

Stops receiving the track on the wire. Stop is final like MediaStreamTrack

Examples


// Assume we already have a way to signal, a transport 
// (RTCDtlsTransport), and audio and video tracks. This is an example 
// of  how to offer them  and get back an answer with audio and 
// video tracks, and begin sending and receiving them.
function initiate(signaller, transport, audioTrack, videoTrack) {
  var audioSender = new RTCRtpSender(audioTrack, transport);
  var videoSender = new RTCRtpSender(videoTrack, transport);
  var audioReceiver = new RTCRtpReceiver(transport);
  var videoReceiver = new RTCRtpReceiver(transport);

  var sendAudioParams = RTCRtpSender.createParameters(audioTrack);
  var sendVideoParams = RTCRtpSender.createParameters(videoTrack);
  signaller.offerTracks({
    // The initiator offers parameters it wants to send with, 
    // and the capabilities it has for receiving. 
    "rtpCaps": RTCRtpReceiver.getCapabilities(),
    "audio": sendAudioParams,
    "video": sendVideoParams
  }, function(answer) {
    // The responder answers with parameters it wants to send with
    // and the capabilities it has for receiving. 
    audioSendParams = RTCRtpSender.filterParameters(
       sendAudioParams, answer.rtpCaps);
    videoSendParams = RTCRtpSender.filterParameters(
       sendVideoParams, answer.rtpCaps
    var audioRecvParams = RTCRtpSender.filterParameters(
       answer.audio);
    var videoRecvParams = RTCRtpSender.filterParameters(
       answer.video);
      
    audioSender.send(audioSendParams);
    videoSender.send(videoSendParams)
    audioReceiver.receive(audioRecvParams);
    videoReceiver.receive(videoRecvParams);

    // Now we can render/play 
    // audioReceiver.track and videoReceiver.track.
  });
}
    


// Assume we already have a way to signal, a transport 
// (RTCDtlsTransport), and audio and video tracks. This is an example 
// of how to answer an offer with audio and video tracks, and begin 
// sending and receiving them.
function accept(
  signaller, remote, transport, audioTrack, videoTrack) {
  var audioSender = new RTCRtpSender(audioTrack, transport);
  var videoSender = new RTCRtpSender(videoTrack, transport);
  var audioReceiver = new RTCRtpReceiver(transport);
  var videoReceiver = new RTCRtpReceiver(transport);

  var audioSendParams = RTCRtpSender.createParameters(
    audioTrack, remote.rtpCaps);
  var videoSendParams = RTCRtpSender.createParameters(
    videoTrack, remote.rtpCaps);
  var audioRecvParams = RTCRtpSender.filterParameters(
     remote.audio);
  var videoRecvParams = RTCRtpSender.filterParameters(
     remote.video);
  
  audioSender.send(audioSendParams);
  videoSender.send(videoSendParams)
  audioReceiver.receive(audioRecvParams);
  videoReceiver.receive(videoRecvParams);
 
  signaller.answerTracks({
    "rtpCaps": RTCRtpReceiver.getCapabilities(),
    "audio": audioSender.parameters(),
    "video": videoSender.parameters()
  });

  // Now we can render/play 
  // audioReceiver.track and videoReceiver.track.
}
    

Dictionaries related to Rtp

dictionary RTCRtpCapabilities

sequence<RTCRtpCodec> audioCodecs
Supported audio codecs.
sequence<RTCRtpCodec> videoCodecs
Supported video codecs.
sequence<DOMString> headerExtensions
URIs of supported RTP header extensions.
sequence<RTCRtpFeatures> features
Supported features.

dictionary RTCRtpCodec

DOMString name
MIME media type
unsigned byte? payload-id
Payload Type
unsigned int? clockRate
Codec clockrate
unsigned int? numChannels
sequence<RTCRtpCodecParameter> formatParameters
Codec-specific format parameters.

dictionary RTCRtpCodecParameter

DOMString name
Name of the codec-specific parameter.
DOMString? value
Value of the codec-specific parameter.

enum RTCRtpFeatures

nack
From [[!RFC4585]]

dictionary RTCRtpParameters

sequence<RTCRtpCodec> codecs
sequence<RTCRtpEncodingParameters> encodings
Can specify multiple layers or "encodings" to be used for things like simulcast, RTC, FEC, etc.
sequence<RTCRtpHeaderExtensionParameters> headerExtensions
Can specify RTP header extensions.

dictionary RTCRtpEncodingParameters

unsigned int ssrc
int TODO
Temporary placeholder for things to control various layers, simulcast, rtc, etc.

dictionary RTCRtpHeaderExtensionParameters

DOMString uri
The URI of the RTP header extension, as defined in [[!RFC5285]].
unsigned short id
The value that goes in the packet.
boolean encrypt
If true, encrypt the value in the header, as per [[!RFC6904]].

The RTCDtmfSender Object

Overview

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

Operation

An RTCDtmfSender object is constructed from an RTCRtpSender object.

Interface Definition

readonly attribute boolean canInsertDTMF
Whether the RTCDtmfSender is capable of sending DTMF.

void insertDTMF(in DOMString tones, optional long duration, long interToneGap)
readonly attribute RTCRtpSender sender

The RTCRtpSender instance

attribute EventHandler ontonechange

The ontonechange event handler uses the RTCDTMFToneChangeEvent interface to return the character for each tone as it is played out.

readonly attribute DOMString toneBuffer

The toneBuffer attribute returns a list of the tones remaining to be played out.

readonly attribute long duration

The duration attribute returns the current tone duration value in milliseconds. This value will be the value last set via the insertDTMF() method, or the default value of 70 ms if insertDTMF() was called without specifying the duration.

readonly attribute long interToneGap

The interToneGap attribute returns the current value of the between-tone gap. This value will be the value last set via the insertDTMF() method, or the default value of 70 ms if insertDTMF() was called without specifying the interToneGap.

RTCDTMFToneChangeEvent

The tonechange event uses the RTCDTMFToneChangeEvent interface.

Firing an tonechange event named e with a DOMString tone means that an event with the name e, which does not bubble (except where otherwise stated) and is not cancelable (except where otherwise stated), and which uses the RTCDTMFToneChangeEvent interface with the tone attribute set to tone, MUST be created and dispatched at the given target.

Constructor(DOMString type, RTCDTMFToneChangeEventInit eventInitDict)
readonly attribute DOMString tone

The tone attribute contains the character for the tone that has just begun playout (see insertDTMF()). If the value is the empty string, it indicates that the previous tone has completed playback.

DOMString tone

The tone 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 RTCDataChannel Object

Overview

This section needs reworking. An RTCDataChannel class instance allows sending data messages to/from the remote peer.

Interface Definition

readonly attribute RTCDtlsTransport transport
The readonly value referring to the related transport 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.

The RTCSctpTransport Object

The RTCSctpTransport includes information relating to Stream Control Transmission Protocol (SCTP) transport.

Overview

An RTCSctpTransport is associated to a RTCDataChannel.

Operation

An RTCSctpTransport instance is constructed from an RTCDtlsTransport object.

Interface Definition

attribute RTCDtlsTransport transport
The RTCDtlsTransport instance the RTCSctpTransport object is sending over.
static RTCSctpCapabilities getCapabilities()
Retrieves the RTCSctpCapabilities of the RTCSctpTransport instance.
void start(RTCSctpCapabilities remoteCaps)
void stop()
Stops the RTCSctpTransport instance.
DataChannel createDataChannel(RTCDataChannelParameters parameters)
Creates a data channel running over SCTP transport.
attribute EventHandler ondatachannel

dictionary RTCDataChannelParameters

boolean outOfOrderAllowed
unsigned short maxRetransmitTime
unsigned short maxRetransmitNum
DOMString protocol
boolean preset
unsigned short stream

dictionary RTCSctpCapabilities

unsigned int maxMessageSize

Example


function initiate(signaller) {
  var dtls = ...;  // See ICE/DTLS example.
  var sctp = new RTCSctpTransport(dtls);

  signaller.sendInitiate({
    // ... include ICE/DTLS info from other example.
  sctpCapabilities: RTCSctpTransport.getCapabilities()
  }, function(remote) {
    sctp.start(remote.sctpCapabilities);
  });

  var channel = sctp.createDataChannel({...});
  channel.send("foo");
}

function accept(signaller, remote) {
  var dtls = ...;  // See ICE/DTLS example.
  signaller.sendAccept({
    // ... include ICE/DTLS info from other example.
    "sctpCapabilities": RTCSctpTransport.getCapabilities()
  });

  var sctp = new RTCSctpTransport(dtls);
  sctp.start(remote.sctpCapabilties);

  // Assume in-band signalling.  We could also easily add
  // RTCDataChannelParameters into the out-of-band signalling
  // And call .createDataChannel here with negotiated: true.

  sctp.ondatachannel = function(channel) {
    channel.onmessage = function(message) {
    if (message == "foo") {
      channel.send("bar");
    }
  }
}

RTCP Protocol

This specification determines that RTCP packets must be multiplexed with the RTP packets as defined by [[!RFC5761]].

Examples

Simple Peer-to-peer Example

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


Change Log

This section will be removed before publication.

Changes since 07 November 2013

  1. RTCTrack split into RTCRtpSender and RTCRtpReceiver objects, as proposed on 06 January 2014.
  2. RTCConnection split into RTCIceTransport and RTCDtlsTransport objects, as proposed on 09 January 2014.
  3. RTCSctpTransport object added, as described in Issue 25
  4. RTCRtpHeaderExtensionParameters added, as described in Issue 28
  5. RTCIceListener added, in order to support parallel forking, as described in Issue 29
  6. DTMF support added, as described in Issue 30