Object RTC (ORTC) API for WebRTC
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 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.
1.
Overview
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). ORTC focuses on "connections" and "tracks" being carried over those connections.
The RTCDtlsTransport Object
Overview
An
RTCDtlsTransport
instance is associated to a
RTCRtpSender
or
RTCRtpReceiver
Operation
RTCDtlsTransport
instance is optionally constructed from a
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
Overview
An
RTCIceTransport
instance is associated to a sending
MediaStreamTrack
and provides RTC related methods to it.
Operation
RTCIceTransport
instance is constructed from an
MediaStreamTrack
object and associated to an
RTCConnection
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
localCandidates
Sequence of the candidates associated with local
RTCIceTransport
readonly attribute sequence
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.
Example
// 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.
getL
ocalParameters(),
"dtls": dtls.
getL
ocalParameters(),
// ... 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 signalled
// to us. This is an example of how answer with ICE 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.
getL
ocalParameters(),
"dtls": ice.
getL
ocalParameters()
// ... 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 RTCIceCandidate Object
The
RTCIceCandidate
includes all information relevant 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
RTCConnection
s.
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 candidate.
host
A host candidate.
srflx
A server reflexive candidate.
prflx
A peer reflexive candidate.
relay
A relay candidate.
The RTCRtpSender Object
Overview
An
RTCRtpSender
instance is associated to a sending
MediaStreamTrack
and provides RTC related methods to it.
Operation
RTCRtpSender
instance is constructed from an
MediaStreamTrack
object and associated to an
RTCConnection
Interface Definition
attribute
MediaStreamTrack
track
The associated
MediaStreamTrack
instance.
attribute
RTCConnection
transport
The associated
RTCConnection
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
Overview
An
RTCRtpReceiver
instance is associated to a sending
MediaStreamTrack
and provides RTC related methods to it.
Operation
RTCRtpReceiver
instance is constructed from an
MediaStreamTrack
object and associated to an
RTCConnection
Interface Definition
attribute
MediaStreamTrack
? track
The associated
MediaStreamTrack
instance.
attribute
RTCConnection
transport
The associated
RTCConnection
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
Example
// Assume we already have a way to signal, a transport
// (RTCConnection), 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
// (RTCConnection), 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 RTCRtpParameters
sequence
sequence
Can specify multiple layers or "encodings" to be used for things like simulcast, RTC, FEC, etc.
dictionary RTCRtpEncodingParameters
unsigned int ssrc
int TODO
Temporary placeholder for things to control various layers, simulcast, rtc, etc.
dictionary RTCRtpCodec
unsigned byte payload-id
DOMString name
unsigned int? clockRate
unsigned int? numChannels
RTCRtpCodecParameter[] params
dictionary RTCRtpCodecParameter
DOMString name
DOMString? value
The RTCDTMFTrack Object
Overview
This section needs reworking. 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
Methods
playTones
Audio RTCDTMFTrack Example
Calling the constructor method of
RTCDTMFTrack
with a
MediaStreamTrack
would enhance the
RTCTrack
and result in a structure as follows:
id: "id",
kind: "audio",
ssrc: "1234",
msid: ["m1"],
codecs: [
payload-id: 96,
name: "opus",
clockRate: 48000,
numChannels: 2
},
payload-id: 101,
name: "dtmf"
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 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.
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&video session between two browsers.