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 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), RTCRtpListener (Section 7),
RTCDtmfSender (Section 9), RTCDataChannel
(Section 10), and RTCSctpTransport (Section 11); RTP dictionaries are described in Section 8.
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.
Horizontal or slanted arrows denote the flow of media or data, whereas vertical arrows denote interactions via methods and events.
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 terms single-session transmission (
SST
) and multi-session transmission (
MST
are defined in [[!RFC6190]].
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
RTCDtlsTransport
instance is optionally constructed from an
RTCIceTransport
object or an
RTCDtlsTransport
is automatically constructed.
Interface Definition
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.
Interface Definition
readonly attribute RTCDtlsTransportState state
The
state
attribute contains the new
RTCDtlsTransportState
that caused the event.
The RTCDtlsParameters Object
The
RTCDtlsParameters
object includes information relating to DTLS configuration.
RTCDtlsRole role
The DTLS role.
sequence
Sequence of certificate algorithms/fingerprints in the form of the "fingerprint-attribute" defined in [[!RFC4572]].
enum RTCDtlsRole
auto
The DTLS role is be determined based on the resolved ICE role: the "Controlled" role acts as the DTLS client,
the "Controlling" role acts as the DTLS server.
client
The DTLS client role.
server
The DTLS server role.
Example
enum RTCDtlsTransportState
RTCDtlsTransportState
provides information about the state of the DTLS transport.
DTLS/SRTP sessions are not reflected in the
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
RTCIceRole
contains the current role of the ICE transport.
readonly attribute RTCIceTransportState state
The current state of the ICE transport.
sequence
Retrieve the sequence of candidates associated with the local
RTCIceTransport
sequence
Retrieve the sequence of candidates associated with the remote
RTCIceTransport
void gather(RTCIceGatherPolicy gatherPolicy)
Start gathering
RTCIceCandidate
objects, based on the gather policy (set on the local system, not negotiated).
void start(RTCIceParameters remoteParameters, optional RTCIceRole role)
Starts candidate 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 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.
attribute EventHandler? ongatherfailure
Set this handler to receive an event when ICE candidate gathering fails.
attribute EventHandler? ongatherneeded
Set this handler to receive an event when ICE candidate gathering is needed.
Interface Definition
readonly attribute RTCIceCandidate? candidate
The
candidate
attribute is the
RTCIceCandidate
object with the
new local ICE candidate that caused the event. If candidate is null,
there are no additional candidates for now.
Interface Definition
Interface Definition
readonly attribute RTCIceTransportState state
The
state
attribute contains the new
RTCIceTransportState
causing the event.
Interface Definition
readonly attribute DOMError e
The
DOMError
object whose
name
attribute has the value TODO.
The RTCIceParameters Object
The
RTCIceParameters
object includes the ICE username and password.
DOMString usernameFragment
ICE username.
DOMString password
ICE password.
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(RTCIceRole.controlled,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 RTCIceGatherPolicy
all
Gather all ICE candidate types.
nohost
Gather all ICE candidate types except for host candidates.
relayonly
Only gather media relay candidates such as candidates passing through a TURN server.
This can be used to reduce leakage of IP addresses in certain use cases.
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 RTCIceOptions Object
The
RTCIceOptions
object includes information relating to ICE configuration.
sequence
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
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,
ip: "192.0.2.33",
protocol: "udp",
port: 10000,
type: "host"
};
DOMString foundation
A unique identifier that allows ICE to correlate candidates that appear on multiple
RTCIceTransport
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.
RTCIceProtocol protocol
The protocol of the candidate (UDP/TCP).
unsigned short port
The 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, the
relatedAddress
refers to the host candidate that these are derived from. For host candidates, the
relatedAddress
is set to the empty string.
unsigned short? relatedPort=null
For candidates that are derived from others, such as relay or reflexive candidates, the
relatedPort
refers to the host candidate that these are derived from. For host candidates, the
relatedPort
is null.
The RTCIceProtocol
The
RTCIceProtocol
includes the protocol of the ICE candidate.
udp
A UDP candidate, as described in [[!RFC5245]].
tcp
A TCP candidate, as described in [[!RFC6544]].
The RTCIceCandidateType
The
RTCIceCandidateType
includes the type of the 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.
void start()
Starts candidate connectivity checks.
void stop()
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
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 send()
is called and stops sending when 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 receiving
MediaStreamTrack
and provides RTC related methods to it.
Operation
RTCRtpReceiver
instance is constructed from an
RTCDtlsTransport
object.
Interface Definition
readonly 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.
sequence
Retrieve the sequence of contributing sources.
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.
var audioSendParams = RTCRtpSender.filterParameters(
sendAudioParams, answer.rtpCaps);
var videoSendParams = RTCRtpSender.filterParameters(
sendVideoParams, answer.rtpCaps);
var audioRecvParams = RTCRtpReceiver.filterParameters(
answer.audio);
var videoRecvParams = RTCRtpReceiver.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 = RTCRtpReceiver.filterParameters(
remote.audio);
var videoRecvParams = RTCRtpReceiver.filterParameters(
remote.video);
audioSender.send(audioSendParams);
videoSender.send(videoSendParams)
audioReceiver.receive(audioRecvParams);
videoReceiver.receive(videoRecvParams);
signaller.answerTracks({
"rtpCaps": RTCRtpReceiver.getCapabilities(),
"audio": audioSendParams,
"video": videoSendParams
});
// Now we can render/play
// audioReceiver.track and videoReceiver.track.
The RTCRtpListener Object
The
RTCRtpListener
listens to RTP packets received from the DTLS transport, and
fires an event if it detects an RTP stream that is not configured to be processed by an
existing
RTCRtpReceiver
object. The amount of buffering to be provided for unhandled
RTP streams is recommended to be strictly limited to protect against denial of service attacks.
Overview
An
RTCRtpListener
instance is associated to an
RTCDtlsTransport
Operation
An
RTCRtpListener
instance is constructed from an
RTCDtlsTransport
object.
To determine whether an RTP stream is configured to be processed by an existing
RTCRtpReceiver
object,
the
RTCRtpListener
attempts to match the values of an incoming RTP packet's
Payload Type and SSRC fields as well as the value of its receiverId RTP extension (if present) against the
RTCRtpReceiver.RTCRtpParameters.RTCRtpCodecParameters.payLoadType,
RTCRtpReceiver.RTCRtpParameters.RTCRtpEncodingParameters.ssrc,
and RTCRtpReceiver.RTCRtpParameters.receiverId attributes of configured RTCRtpReceiver objects.
TODO: provide details of matching behavior, along with examples.
Interface Definition
readonly attribute
RTCDtlsTransport
transport
The
RTCDtlsTransport
instance.
attribute EventHandler? onunhandledrtp
The event handler which handles the
RTCRtpUnhandledRtpEvent
Interface Definition
readonly attribute unsigned int ssrc
The SSRC in the RTP packet triggering the event.
readonly attribute unsigned byte payloadType
The Payload Type value in the RTP packet triggering the event.
readonly attribute DOMString? receiverId
The value of the AppId header extension in the RTP packet triggering the event, if present.
Example
Dictionaries related to Rtp
dictionary RTCRtpContributingSource
DOMHiResTimeStamp timestamp
Timestamp indicating when an RTP packet containing the contributing source was last received.
The time is relative to the UNIX epoch (Jan 1, 1970, UTC).
unsigned int csrc
The contributing source.
int audioLevel
The audio level of the contributing source.
Value is between 0 and -127 representing the contributing source dBov value,
as described in [[!RFC6465]]
dictionary RTCRtpCapabilities
sequence
Supported audio codecs.
sequence
Supported video codecs.
sequence
URIs of supported RTP header extensions.
sequence
Supported RTP features.
dictionary RTCRtpCodec
DOMString name=""
The MIME media type, if set, empty string otherwise.
unsigned int? clockRate=null
Codec clockrate, null if unset.
unsigned int? numChannels=1
The number of channels supported (e.g. stereo); one by default.
sequence
Codec-specific format parameters available for signaling.
enum RTCRtpFeatures
nack
From [[!RFC4585]]
dictionary RTCRtpParameters
DOMString? receiverId=""
The receiverId assigned to the RTP stream, if any, empty string otherwise.
In an
RTCRtpReceiver
object, this corresponds to
recv-appId defined in [[!APPID]]. In an
RTCRtpSender
object, it corresponds to the appId.
This is a stable identifier that can be defined and assign to any RTP stream rather than relying on an SSRC.
An SSRC is randomly generated and can change arbitrarily due to conflicts with other SSRCs, whereas
the receiverId has a value
whose meaning can be defined in advance between RTP
sender and receiver, assisting in RTP demultiplexing.
sequence
The codecs to send or receive (could include RTX and CN as well).
sequence
The RTP header extensions to send or receive.
sequence
The "encodings" or "layers" to be used for things like simulcast, Scalable Video Coding, RTX, FEC, etc.
dictionary RTCRtpCodecParameters
unsigned byte payloadType=null
The value that goes in the RTP Payload Type Field [[!RFC3550]], null if unset.
RTCRtpCodec codec
The codec to be used for sending or receiving.
sequence
Codec parameters that control what is sent, but are not signaled. For example, with Opus [[!RFC6716]], stereo=1.
sequence
RTCP feedback parameters, separated out because they are so different.
dictionary KeyValueParam
DOMString name
Name of the codec-specific parameter.
DOMString? value=""
Value of the codec-specific parameter, if any, empty string otherwise.
dictionary RTCRtcpFeedbackParam
DOMString type
The type of feedback message ("nack", "ccm", "tmmbr", "goog-remb", etc.).
DOMString parameters
The feedback message ("rpsi", "fir", etc.).
dictionary RTCRtpEncodingParameters
unsigned int? ssrc=null
The SSRC for this layering/encoding, null if unset.
DOMString? codecName=""
For per-encoding codec specifications, give the codec name here. If the empty string, the browser will choose.
RTCRtpFecParameters? fec
Specifies the FEC mechanism if used.
RTCRtpRtxParameters? rtx
Specifies the RTX mechanism if used.
double priority=1.0
The higher the value, the more the bits will be given to each as available bandwidth goes up. Default is 1.0.
double scale=null
Do this scale of the input resolution, or die trying. 1.0 = full resolution. Default is unconstrained (null).
double maxBitrate=null
Ramp up resolution/quality/framerate until this bitrate, null if unset. Summed when using dependent layers.
double maxQuality=null
Ramp up resolution/quality/framerate until this quality, null if unset.
double minQuality=null
Never send less than this quality, null if unset.
double bias=null
What to give more bits to, if available, null if unset. 0.0 = strongly favor resolution or 1.0 = strongly favor
framerate. 0.5 = neither.
boolean active=true
Whether the sender or receiver is active. If false, don't send any media right now.
Disable is different than omitting the encoding; it can keep resources
available to re-enable more quickly than re-adding. Plus, it still sends RTCP. Default is active.
DOMString? encodingId
An identifier for the encoding object. This identifier should be unique within the scope of the
localized sequence of
RTCRtpEncodingParameters
for any given
RTCRtpParameters
object.
If encodings contained within sequences of other
RTCRtpParameters
objects are dependent
upon this encoding identifier, the identifier should be globally unique (unless two or more
encodings are intentionally referencing the same dependency
RTCRtpEncodingParameters
such
as described in [[!RFC5583]] Section 6.5a).
sequence
Just the IDs (resolve to
encodingIds
within the same sequence first, then search globally for matches).
Examples
// Normal 1:1 video with resolution feedback from the receiver
var encodings = [
ssrc: 1,
scale: .5
}];
// Crank up the quality to "11"
var encodings = [
ssrc: 1,
maxQuality: 11.0 // TODO: Figure out the scale.
}];
// Send a thumbnail along with regular size
var encodings1 = [
ssrc: 1,
priority: 1.0
}]
// Control the resolution and framerate
// with a different track and RtpSender.
var encodings2 = [{
ssrc: 2,
// Prioritize the thumbnail over the main video.
priority: 10.0
}];
// Sign Language
// (need high framerate, but don't get too bad of quality)
var encodings = [{
minQuality: 0.2,
bias: 1.0
}];
// SVC which handles camera rotation
var encodings =[{
layerId: "0",
scale: 0.25,
priority: 3.0
}, {
layerId: "1",
layerDependencies: ["0"]
scale: 0.5,
priority: 2.0
}, {
layerId: "2",
layerDependencies: ["0", "1"]
scale: 1.0,
priority: 1.0
}]
// SVC w/thumbnail:
var encodings1 =[{
layerId: "0",
scale: 0.25,
priority: 3.0
}, {
layerId: "1",
layerDependencies: ["0"],
scale: 0.5,
priority: 2.0
}, {
layerId: "2",
layerDependencies: ["0", "1"],
scale: 1.0,
priority: 1.0
}];
// Control the resolution and framerate with a different track and
RtpSender.
var encodings2 =[{
layerId: "3",
priority: 10.0
}]
// SVC w/thumbnail temporarily disabled:
var encodings1 =[{
layerId: "0",
scale: 0.25,
priority: 3.0
}, {
layerId: "1",
layerDependencies: ["0"],
scale: 0.5,
priority: 2.0
}, {
layerId: "2",
layerDependencies: ["0", "1"],
scale: 1.0,
priority: 1.0
}];
// Control the resolution and framerate
// with a different track and RtpSender.
var encodings2 =[{
layerId: "3",
priority: 10.0,
active: false
}]
// Must send a very fixed resolution
// Adjust the resolution using the input track.
var encodings = [{
scale: 1.0
}];
// Screencast
var encodings = [{
bias: 0.0
}];
// Remote Desktop
// (High framerate, must not dowscale)
var encodings = [{
bias: 1.0,
scale: 1.0
}];
// Baby Monitor or Security Camera
// Adjust the framerate using the input track.
var encodings = [{ssrc: 1}];
// Audio more important than video
var audioEncodings = [{
priority: 10.0
}];
var videoEncodings = [{
priority: 0.1
}];
Video more important than audio
var audioEncodings = [{
priority: 0.1
}];
var videoEncodings = [{
priority: 10.0
}];
// Camera Rotation
// Since there is only control of scale, there is no issue with camera //
rotation or cropping. Everything should work fine with no jank.
var encodings = [{ssrc: 1}];
dictionary RTCRtpFecParameters
unsigned int ssrc=null
The SSRC to use for FEC, null if unset.
DOMString mechanism=""
The Forward Error Correction (FEC) mechanism to use, if any, empty string otherwise.
dictionary RTCRtpRtxParameters
unsigned int ssrc=null
The SSRC to use for RTX, null if unset.
dictionary RTCRtpHeaderExtensionParameters
DOMString uri=""
The URI of the RTP header extension, if any, as defined in [[!RFC5285]], empty string otherwise.
unsigned short id=null
The value that goes in the packet, null if unset.
boolean encrypt=false
If true, the value in the header is encrypted as per [[!RFC6904]]. Default is unencrypted.
The RTCDtmfSender Object
Overview
An
RTCDtmfSender
instance allows sending DTMF tones to/from the remote peer, as per [[!RFC4733]].
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
with a DOMString
tone
means
that an event with the name
, 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
An
RTCDataChannel
class instance allows sending data messages to/from the remote peer.
Operation
An
RTCDataChannel
object is constructed from an
RTCSctpTransport
object.
Interface Definition
readonly attribute RTCSctpTransport transport
The readonly value referring to the related SCTP 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=false
Whether out of order delivery is allowed. Default is false.
unsigned short maxRetransmitTime=null
The length of the time window (in milliseconds) during which
retransmissions may occur in unreliable mode, or null if unset.
The attribute must return the value to which it was set when the
RTCDataChannel
was created.
unsigned short maxRetransmitNum=null
The maximum number of retransmissions that are attempted in
unreliable mode, or null if unset.
The attribute must return the value to which it was set when the
RTCDataChannel
was created.
DOMString protocol=""
The name of the sub-protocol used with this
RTCDataChannel
if any,
or the empty string otherwise.
The attribute must return the value to which it was set when the
RTCDataChannel
was created.
boolean preset=false
Default is false.
unsigned short stream=null
Null if unset.
dictionary RTCSctpCapabilities
unsigned int maxMessageSize=null
Maximum message size or null if unset.
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");
Interface Extensions
The Statistics API extends the RTCRtpSender, RTCRtpReceiver, RTCDtlsTransport, RTCIceTransport and RTCSctpTransport interfaces.
void getStats(RTCStatsCallback
successCallback, RTCErrorCallback failureCallback)
Gathers stats for the given
RTCRtpSender
object
and reports the result asynchronously.
When the
getStats()
method is
invoked, the user agent MUST queue a task to run the following
steps:
If the
RTCRtpSender
object's
RTCRtpEncodingParameters.active
state is
false
, throw an
InvalidStateError
exception.
Return, but continue the following steps in the
background.
Start gathering the stats.
When the relevant stats have been gathered, queue a task to
invoke the success callback (the method's second argument) with a
new
RTCStatsReport
object, representing the
gathered stats, as its argument.
RTCStatsCallback
RTCStatsReport report
RTCStatsReport
representing the gathered
stats.
RTCStatsReport Object
The
getStats()
method delivers a successful result in the form of a
RTCStatsReport
object. A
RTCStatsReport
object represents a map between
strings, identifying the inspected objects (
RTCStats.id
), and their corresponding
RTCStats
objects.
An
RTCStatsReport
may be composed of several
RTCStats
objects, each reporting stats for one
underlying object.
One achieves the total for the object by summing over all stats of a
certain type; for instance, if an
RTCRtpSender
object is sending
RTP streams involving multiple SSRCs over the network, the
RTCStatsReport
may contain one
RTCStats
object per SSRC (which can be distinguished by the value of the "ssrc"
stats attribute).
getter RTCStats (DOMString id)
Getter to retrieve the
RTCStats
objects that
this stats report is composed of.
The set of supported property names [[!WEBIDL]] is defined as the
ids of all the
RTCStats
objects that has been
generated for this stats report. The order of the property names is
left to the user agent.
RTCStats Dictionary
An
RTCStats
dictionary represents the stats
gathered by inspecting a specific object.
The
RTCStats
dictionary is a base type that specifies as set of default attributes,
such as
timestamp
and
type
. Specific stats are added by extending the
RTCStats
dictionary.
Note that while stats names are standardized, any given implementation
may be using experimental values or values not yet known to the Web
application. Thus, applications MUST be prepared to deal with unknown
stats.
OPEN ISSUE: Need to define an IANA registry for this and populate with
pointers to existing things such as the RTCP statistics.
Statistics need to be synchronized with each other in order to yield
reasonable values in computation; for instance, if "bytesSent" and
"packetsSent" are both reported, they both need to be reported over the
same interval, so that "average packet size" can be computed as "bytes /
packets" - if the intervals are different, this will yield errors. Thus
implementations MUST return synchronized values for all stats in a
RTCStats
object.
DOMHiResTimeStamp timestamp
The
timestamp
of type
DOMHiResTimeStamp
[[!HIGHRES-TIME]], associated
with this object. The time is relative to the UNIX epoch (Jan 1,
1970, UTC).
RTCStatsType type
The type of this object.
The
type
attribute
MUST be initialized to the name of the most specific type this
RTCStats
dictionary represents.
DOMString id
A unique
id
that is
associated with the object that was inspected to produce this
RTCStats
object. Two
RTCStats
objects, extracted from two different
RTCStatsReport
objects, MUST have the same id if
they were produced by inspecting the same underlying object. User
agents are free to pick any format for the id as long as it meets the
requirements above.
Consider naming id something that indicates that the id refers to
the underlying object that was inspected to produce the stats,
instead of being an id for the JavaScript object. Suggestions:
statsObjectId, reporterId, srcId.
inbound-rtp
Inbound RTP. Relevant to
RTCRtpReceiver
objects.
outbound-rtp
Outbund RTP. Relevant to
RTCRtpSender
objects.
Derived Stats Dictionaries
DOMString ssrc
...
DOMString remoteId
The
remoteId
can be used to look up the corresponding
RTCStats
object that represents stats reported by
the other peer.
unsigned long packetsReceived
Relevant to
RTCRtpReceiver
objects.
unsigned long bytesReceived
Relevant to
RTCRtpReceiver
objects.
unsigned long packetsSent
Relevant to
RTCRtpSender
objects.
unsigned long bytesSent
Relevant to
RTCRtpSender
objects.
Other interfaces
RTCRtpReceiver
void getStats(RTCStatsCallback
successCallback, RTCErrorCallback failureCallback)
RTCDtlsTransport
void getStats(RTCStatsCallback
successCallback, RTCErrorCallback failureCallback)
RTCIceTransport
void getStats(RTCStatsCallback
successCallback, RTCErrorCallback failureCallback)
RTCSctpTransport
void getStats(RTCStatsCallback
successCallback, RTCErrorCallback failureCallback)
Example
Consider the case where the user is experiencing bad sound and the application wants to determine if the cause of it is packet loss. The following example code might be used:
RTCP Protocol
This specification requires 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 13 February 2014
Support for contributing source information added, as described in
Issue 27
Support for control of quality, resolution, framerate and layering added, as described in
Issue 31
RTCRtpListener object added and figure in Section 1 updated, as described in
Issue 32
More complete support for RTP and Codec Parameters added, as described in
Issue 33
Data Channel transport problem fixed, as described in
Issue 34
Various NITs fixed, as described in
Issue 37
Section 2.2 and 2.3 issues fixed, as described in
Issue 38
Default values of some dictionary attributes added, to partially address the issue described in
Issue 39
Support for ICE TCP added, as described in
Issue 41
Fixed issue with sequences as attributes, as described in
Issue 43
Fix for issues with onlocalcandidate, as described in
Issue 44
Initial stab at a Stats API, as requested in
Issue 46
Added support for ICE gather policy, as described in
Issue 47
Changes since 07 November 2013
RTCTrack split into RTCRtpSender and RTCRtpReceiver objects, as proposed on
06 January 2014.
RTCConnection split into RTCIceTransport and RTCDtlsTransport objects, as proposed on
09 January 2014.
RTCSctpTransport object added, as described in
Issue 25
RTCRtpHeaderExtensionParameters added, as described in
Issue 28
RTCIceListener added, in order to support parallel forking, as described in
Issue 29
DTMF support added, as described in
Issue 30