From ce5794c3d698cf0906a58ff50a80a9e0e3ddd998 Mon Sep 17 00:00:00 2001 From: Justin Uberti Date: Tue, 14 Oct 2014 23:11:22 -0700 Subject: [PATCH 01/25] Add RTCRtpSender, RTCRtpSender, and friends --- webrtc.html | 694 ++++++++++++++++++++++++---------------------------- 1 file changed, 318 insertions(+), 376 deletions(-) diff --git a/webrtc.html b/webrtc.html index 4dc2321d0..b2596e3d9 100644 --- a/webrtc.html +++ b/webrtc.html @@ -325,15 +325,6 @@

Operation

RTCPeerConnection signaling state, ICE gathering state, and ICE connection state. These are initialized when the object is created.

-

An RTCPeerConnection object has two associated - stream sets. A local streams set, - representing streams that are currently sent, and a remote streams set, representing streams - that are currently received with this - RTCPeerConnection object. The stream sets are - initialized to empty sets when the - RTCPeerConnection object is created.

-

When the RTCPeerConnection() constructor is invoked, the user agent MUST run the following steps:

@@ -518,7 +509,7 @@

Operation

"component".

When a user agent has reached the point where a - MediaStream can be created to represent incoming + MediaStreamTrack can be created to represent incoming components, the user agent MUST run the following steps:

    @@ -528,8 +519,8 @@

    Operation

  1. -

    Create a MediaStream object - stream, to represent the incoming media stream.

    +

    Create a MediaStreamTrack object + track, to represent the incoming media track.

  2. @@ -538,7 +529,7 @@

    Operation

    component.

    The creation of new incoming - MediaStreams may be triggered either by SDP + MediaStreamTracks may be triggered either by SDP negotiation or by the receipt of media on a given flow.

    @@ -556,15 +547,16 @@

    Operation

  3. -

    Add stream to connection's remote streams set.

    +

    Create a new RTCRtpReceiver object for track, and add it + to connection's set of receivers.

  4. -

    Fire a stream event named - addstream with - stream at the connection +

    Fire an event named + addtrack with + track at the connection object.

@@ -573,32 +565,32 @@

Operation

When a user agent has negotiated media for a component that belongs to a media stream that is already represented by an existing - MediaStream object, the user agent MUST associate - the component with that MediaStream object.

+ MediaStreamTrack object, the user agent MUST associate + the component with that MediaStreamTrack object.

-

When an RTCPeerConnection finds that a stream +

When an RTCPeerConnection finds that a track from the remote peer has been removed, the user agent MUST follow these steps:

  1. Let connection be the - RTCPeerConnection associated with the stream + RTCPeerConnection associated with the track being removed.

  2. -

    Let stream be the MediaStream +

    Let track be the MediaStreamTrack object that represents the media stream being removed, if any. If there isn't one, then abort these steps.

  3. -

    By definition, stream is now ended.

    +

    By definition, track is now ended.

    A task is thus queued to update - stream and fire an event.

    + track and fire an event.

  4. @@ -614,15 +606,15 @@

    Operation

    task ran -->
  5. -

    Remove stream from connection's - remote streams set.

    +

    Remove the RTCRtpSender associated with track from + connection's set of receivers.

  6. -

    Fire a stream event named - removestream with - stream at the connection +

    Fire a track event named + ended + at the track object.

@@ -1256,259 +1248,6 @@

Interface Definition

"#ice-servers-list">ICE servers list.

-
sequence<MediaStream> getLocalStreams()
- -
-

Returns a sequence of MediaStream objects - representing the streams that are currently sent with this - RTCPeerConnection object.

- -

The getLocalStreams() - method MUST return a new sequence that represents a snapshot of all - the MediaStream objects in this - RTCPeerConnection object's local streams set. The conversion from the - streams set to the sequence, to be returned, is user agent defined - and the order does not have to stable between calls.

-
- -
sequence<MediaStream> getRemoteStreams()
- -
-

Returns a sequence of MediaStream objects - representing the streams that are currently received with this - RTCPeerConnection object.

- -

The getRemoteStreams() - method MUST return a new sequence that represents a snapshot of all - the MediaStream objects in this - RTCPeerConnection object's remote streams set. The conversion from - the streams set to the sequence, to be returned, is user agent - defined and the order does not have to stable between calls.

-
- -
MediaStream? getStreamById(DOMString streamId)
- -
-

If a MediaStream object, with an - id - equal to streamId, exists in this - RTCPeerConnection object's stream sets - (local streams set or remote streams set), then the getStreamById() - method MUST return that MediaStream object. The - method MUST return null if no stream matches the - streamId argument.

- -
-

For this method to make sense, we need to make sure that ids - are unique within the two stream sets of a RTCPeerConnection. - This is not the case today when a peer re-adds a stream that is - received. Two different stream instances will now have the same - id at both peers; one in the remote stream set and one in the - local stream set.

- -

One way to resolve this is to not allow re-adding a stream - instance that is received (guard on id). If an application really - needs this functionality it's really easy to make a clone of the - stream, which will give it a new id, and send the clone.

-
-
- -
void addStream (MediaStream stream)
- -
-

Adds a new stream to the RTCPeerConnection.

- -

When the addStream() method is invoked, the user agent MUST - run the following steps:

- -
    -
  1. -

    Let connection be the - RTCPeerConnection object on which the - MediaStream, stream, is to be - added.

    -
    2. - -
  2. -

    If connection's RTCPeerConnection - signalingState is closed, throw an - InvalidStateError exception and abort these - steps.

    -
    3. - -
  3. -

    If stream is already in connection's - local streams set, then abort - these steps.

    -
    4. - -
  4. -

    Add stream to connection's local streams set.

    -
    5. - -
  5. -

    A stream could have contents that are inaccessible to the - application. This can be due to being marked with a - peerIdentity option or anything that would make a - stream - CORS cross-origin. These streams can be added to the - local streams set but content - MUST NOT be transmitted, though streams marked with - peerIdentity can be transmitted if they meet the - requirements for sending (see ).

    - -

    All other streams that are not accessible to the application - MUST NOT be sent to the peer, with silence (audio), black - frames (video) or equivalently absent content being sent in - place of stream content.

    - -

    Note that this property can change over time.

    -
    6. - -
  6. -

    If connection's RTCPeerConnection - signalingState is stable, then fire a negotiationneeded event at - connection.

    -
    7. -
-
- -
void removeStream (MediaStream stream)
- -
-

Removes the given stream from the - RTCPeerConnection.

- -

When the other peer stops sending a stream in this manner, a - removestream event is - fired at the RTCPeerConnection object.

- -

When the removeStream() method is invoked, the user agent - MUST run the following steps:

- -
    -
  1. -

    Let connection be the - RTCPeerConnection object on which the - MediaStream, stream, is to be - removed.

    -
    2. - -
  2. -

    If connection's RTCPeerConnection - signalingState is closed, throw an - InvalidStateError exception.

    -
    3. - -
  3. -

    If stream is not in connection's - local streams set, then abort - these steps.

    -
    4. - -
  4. -

    Remove stream from connection's - local streams set.

    -
    5. - -
  5. -

    If connection's RTCPeerConnection - signalingState is stable, then fire a negotiationneeded event at - connection.

    -
    6. -
-
-
void close ()
@@ -1562,28 +1301,6 @@

Interface Definition

setRemoteDescription, or code. It does not fire for the initial state change into new.
-
attribute EventHandler onaddstream
- -
This event handler, of event handler event type addstream, MUST be fired - by all objects implementing the RTCPeerConnection - interface. It is called any time a MediaStream is added - by the remote peer. This will be fired only as a result of - setRemoteDescription. Onnaddstream happens as early as - possible after the setRemoteDescription. This callback - does not wait for a given media stream to be accepted or rejected via - SDP negotiation.
- -
attribute EventHandler onremovestream
- -
This event handler, of event handler event type removestream, MUST be - fired by all objects implementing the - RTCPeerConnection interface. It is called any - time a MediaStream is removed by the remote peer. This - will be fired only as a result of - setRemoteDescription.
-
attribute EventHandler oniceconnectionstatechange
@@ -2074,6 +1791,281 @@

RTCPeerConnectionIceEvent

+
+

RTP media API

+ +

The RTP media API lets a web application send and receive MediaStreamTracks + over a peer-to-peer connection. Tracks, when added to a PeerConnection, result in + signaling; when this signaling is forwarded to a remote peer, it causes + corresponding tracks to be created on the remote side.

+ +

The actual encoding and transmission of MediaStreamTracks is managed through + objects called RTCRtpSenders. Similarly, the reception and decoding of + MediaStreamTracks is managed through objects called RTCRtpReceivers.

+ +

A RTCPeerConnection object contains a + set of RTCRtpSenders, representing tracks to + be sent, and a set of RTCRtpReceivers, + representing tracks that are to be received on this + RTCPeerConnection object. Both of these sets are + initialized to empty sets when the + RTCPeerConnection object is created.

+ +
+

RTCPeerConnection Interface Extensions

+ +

The RTP media API extends the + RTCPeerConnection interface as described below.

+ +
+
sequence<RTCRtpSender> getSenders()
+ +
+

Returns a sequence of RTCRtpSender objects + representing the RTP senders that are currently attached to this + RTCPeerConnection object.

+ +

The getSenders() + method MUST return a new sequence that represents a snapshot of all + the RTCRtpSenders objects in this + RTCPeerConnection object's set of senders. The conversion from the + senders set to the sequence, to be returned, is user agent defined + and the order does not have to stable between calls.

+
+ +
sequence<RTCRtpReceiver> getReceivers()
+ +
+

Returns a sequence of RTCRtpReceiver objects + representing the RTP receivers that are currently attached to this + RTCPeerConnection object.

+ +

The getReceivers() + method MUST return a new sequence that represents a snapshot of all + the RTCRtpReceiver objects in this + RTCPeerConnection object's set of receivers. The conversion from + the receivers set to the sequence, to be returned, is user agent + defined and the order does not have to stable between calls.

+
+ +
RTCRtpSender addTrack (MediaStreamTrack track, MediaStream... streams)
+ +
+

Adds a new track to the RTCPeerConnection, and indicate that it + is contained in the specified MediaStreams.

+ +

When the addTrack() method is invoked, the user agent MUST + run the following steps:

+ +
    +
  1. +

    Let connection be the + RTCPeerConnection object on which the + MediaStreamTrack, track, is to be + added.

    +
    2. + +
  2. +

    If connection's RTCPeerConnection + signalingState is closed, throw an + InvalidStateError exception and abort these + steps.

    +
    3. + +
  3. +

    If a RTCRtpSender for track already exists in + connection's set of senders, + then abort these steps.

    +
    4. + +
  4. +

    Create a new RTCRtpSender for track, add it to + connection's set of senders, + and return it to the caller.

    +
    5. + +
  5. +

    A track could have contents that are inaccessible to the + application. This can be due to being marked with a + peerIdentity option or anything that would make a + track + CORS cross-origin. These tracks can be supplied to the + addTrack method, and have a RTCRtpSender created for them, but content + MUST NOT be transmitted, though tracks marked with + peerIdentity can be transmitted if they meet the + requirements for sending (see ).

    + +

    All other tracks that are not accessible to the application + MUST NOT be sent to the peer, with silence (audio), black + frames (video) or equivalently absent content being sent in + place of track content.

    + +

    Note that this property can change over time.

    +
    6. + +
  6. +

    If connection's RTCPeerConnection + signalingState is stable, then fire a negotiationneeded event at + connection.

    +
    7. +
+
+ +
void removeTrack (RTCRtpSender sender)
+ +
+

Removes sender, and its associated MediaStreamTrack, from the + RTCPeerConnection.

+ + +

When the other peer stops sending a track in this manner, a + ended event is + fired at the MediaStreamTrack object.

+ +

When the removeTrack() method is invoked, the user agent + MUST run the following steps:

+ +
    +
  1. +

    Let connection be the + RTCPeerConnection object on which the + RTCRtpSender, sender, is to be + removed.

    +
    2. + +
  2. +

    If connection's RTCPeerConnection + signalingState is closed, throw an + InvalidStateError exception.

    +
    3. + +
  3. +

    If sender is not in connection's + set of senders, then abort + these steps.

    +
    4. + +
  4. +

    Remove sender from connection's + set of senders.

    +
    5. + +
  5. +

    If connection's RTCPeerConnection + signalingState is stable, then fire a negotiationneeded event at + connection.

    +
    6. +
+
+ +
attribute EventHandler onaddtrack
+ +
This event handler, of event handler event type addtrack, MUST be fired + by all objects implementing the RTCPeerConnection + interface. It is called any time a MediaStreamTrack is added + by the remote peer. This will be fired only as a result of + setRemoteDescription. onaddtrack happens as early as + possible after the setRemoteDescription. This callback + does not wait for a given media track to be accepted or rejected via + SDP negotiation.
+ +
+ +
+ +
+

RTCRtpSender Interface

+ +
+
readonly attribute MediaStreamTrack track
+ +
+

The RTCRtpSender.track + attribute is the track that is immutably associated with this + RTCRtpSender object.

+
+
+ +
+

RTCRtpReceiver Interface

+ +
+
readonly attribute MediaStreamTrack track
+ +
+

The RTCRtpReceiver.track + attribute is the track that is immutably associated with this + RTCRtpReceiver object.

+
+
+ +
+

AddTrackEvent

+ +

The onaddtrack + event uses the + AddTrackEvent interface.

+ +

Firing an + AddTrackEvent event named e with an + MediaStreamTrack track 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 AddTrackEvent interface with the + track attribute + set to track, MUST be created and dispatched at the + given target.

+ +
+
Constructor(DOMString type, AddTrackEventInit + eventInitDict)
+ +
readonly attribute RTCRtpReceiver receiver
+
readonly attribute MediaStreamTrack track
+
readonly attribute MediaStream stream
+ +
+

The track attribute + represents the MediaStreamTrack object associated with + the event.

+
+
+ +
+ +
RTCRtpReceiver receiver
+
MediaStreamTrack track
+
MediaStream stream
+ +
+

TODO

+
+
+
+ +
+

Peer-to-peer Data API

@@ -2909,10 +2901,9 @@

RTCPeerConnection Interface Extensions

The createDTMFSender() method creates an RTCDTMFSender - that references the given MediaStreamTrack. The MediaStreamTrack MUST - be an element of a MediaStream that's currently in the - RTCPeerConnection object's local streams set; if not, throw an + that references the given MediaStreamTrack. A RTCRtpSender for track + MUST already exist in theRTCPeerConnection object's set of senders; if not, throw an InvalidParameter exception and abort these steps.

@@ -4180,7 +4171,7 @@

MediaStreamTrack

readyState set to muted on the remote peer if the local user agent disables the corresponding MediaStreamTrack in the - MediaStream that is being sent. When the addstream + MediaStream that is being sent. When the onaddtrack event triggers on an RTCPeerConnection, all MediaStreamTrack objects in the resulting MediaStream are muted until media data can be read @@ -4190,48 +4181,6 @@

MediaStreamTrack

seems like an SDP question, not a media-level question.

-
-

MediaStreamEvent

- -

The addstream - and removestream events use the - MediaStreamEvent interface.

- -

Firing a - stream event named e with a - MediaStream stream 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 MediaStreamEvent interface with the - stream attribute - set to stream, MUST be created and dispatched at the - given target.

- -
-
Constructor(DOMString type, MediaStreamEventInit - eventInitDict)
- -
readonly attribute MediaStream? stream
- -
-

The stream attribute - represents the MediaStream object associated with - the event.

-
-
- -
-
MediaStream stream
- -
-

TODO

-
-
-
-

Isolated Media Streams

@@ -4288,7 +4237,7 @@

Isolated Media Streams

  • Used as the argument to addStream() + "#widl-RTCPeerConnection-addTrack-void-MediaStream-stream">addTrack() on an RTCPeerConnection instance, subject to the restrictions in .

    • @@ -4475,15 +4424,20 @@

    Simple Peer-to-peer Example

    pc.createOffer(localDescCreated, logError); } - // once remote stream arrives, show it in the remote video element - pc.onaddstream = function (evt) { - remoteView.srcObject = evt.stream; + // once remote video track arrives, show it in the remote video element + pc.onaddtrack = function (evt) { + if (evt.track.kind === "video") { + remoteView.srcObject = evt.stream; + } }; // get a local stream, show it in a self-view and add it to be sent navigator.mediaDevices.getUserMedia({ "audio": true, "video": true }, function (stream) { selfView.srcObject = stream; - pc.addStream(stream); + if (stream.getAudioTracks().length > 0) + pc.addTrack(stream.getAudioTracks(0), stream); + if (stream.getVideoTracks().length > 0) + pc.addTrack(stream.getVideoTracks(0), stream); }, logError); } @@ -4546,7 +4500,7 @@

    Peer-to-peer Data Example

    in detail at the moment. This example can hopefully help to drive that discussion. An assumption made in this example is that the event only triggers when a new negotiation should be started. This means that an - action (such as addStream()) that normally would have fired the + action (such as addTrack()) that normally would have fired the negotiationneeded event will not do so during an ongoing offer/answer dialog.

    @@ -4859,25 +4813,13 @@ 
    Event summary
    
 
         
           addstream
-
-              MediaStreamEvent
-
-          
-            A new stream has been added to the remote streams set.
-          
-        
-
-        
-          removestream
+          "event-addtrack">addtrack
 
-          MediaStreamEvent
+          AddTrackEvent
 
           
-            A stream has been removed from the remote streams set.
+            A new RTCRtpReceiver, and associated MediaStreamTrack, has been added to the set of receivers.
           
         
 

From dc0b2169b185ed8d477433013b19abf94ddf4198 Mon Sep 17 00:00:00 2001
From: Justin Uberti 
Date: Thu, 16 Oct 2014 23:11:19 -0700
Subject: [PATCH 02/25] Respond to CR comments

---
 webrtc.html | 42 +++++++++++++++++++++++++++++-------------
 1 file changed, 29 insertions(+), 13 deletions(-)

diff --git a/webrtc.html b/webrtc.html
index b2596e3d9..cf41a6039 100644
--- a/webrtc.html
+++ b/webrtc.html
@@ -118,7 +118,7 @@ 
    Terminology
    
     Constraints, and Consumer are defined in
     [[!GETUSERMEDIA]].
    - +

    Peer-to-peer connections

    @@ -509,8 +509,8 @@

    Operation

    "component".

    When a user agent has reached the point where a - MediaStreamTrack can be created to represent incoming - components, the user agent MUST run the following steps:

    + MediaStreamTrack can be created to represent an incoming + component, the user agent MUST run the following steps:

    1. @@ -520,7 +520,12 @@

      Operation

    2. Create a MediaStreamTrack object - track, to represent the incoming media track.

      + track, to represent the incoming media track. + Add track to the MediaStreams streams + referenced by the SDP + negotiation, creating a new ones if they do not exist. If no + MediaStreams are indicated in the SDP negotiation, a default MediaStream + is used.

    3. @@ -547,7 +552,8 @@

      Operation

    4. -

      Create a new RTCRtpReceiver object for track, and add it +

      Create a new RTCRtpReceiver object receiver + for track, and add it to connection's set of receivers.

      5. @@ -556,8 +562,8 @@

      Operation

      Fire an event named addtrack with - track at the connection - object.

      + receiver, track, and streams + at the connection object.

    @@ -1879,7 +1885,7 @@

    RTCPeerConnection Interface Extensions

  • -

    If a RTCRtpSender for track already exists in +

    If an RTCRtpSender for track already exists in connection's set of senders, then abort these steps.

    • @@ -1897,7 +1903,7 @@

    RTCPeerConnection Interface Extensions

    track CORS cross-origin. These tracks can be supplied to the - addTrack method, and have a RTCRtpSender created for them, but content + addTrack method, and have an RTCRtpSender created for them, but content MUST NOT be transmitted, though tracks marked with peerIdentity can be transmitted if they meet the requirements for sending (see ).

    @@ -1991,6 +1997,12 @@

    RTCPeerConnection Interface Extensions

    RTCRtpSender Interface

    +

    The RTCRtpSender interface allows an application to control how a given + MediaStreamTrack is encoded and transmitted to a remote peer. + When attributes on an RTCRtpSender are modified, the encoding is either + changed appropriately, or a negotiation is triggered to signal the new encoding + parameters to the other side.

    +
    readonly attribute MediaStreamTrack track
    @@ -2006,6 +2018,10 @@

    RTCRtpSender Interface

    RTCRtpReceiver Interface

    +

    The RTCRtpReceiver interface allows an application to control the receipt + of a MediaStreamTrack. When attributes on an RTCRtpReceiver are modified, a negotiation is triggered to signal the changes regarding what the application + wants to receive to the other side.

    +
    readonly attribute MediaStreamTrack track
    @@ -2042,7 +2058,7 @@

    AddTrackEvent

    readonly attribute RTCRtpReceiver receiver
    readonly attribute MediaStreamTrack track
    -
    readonly attribute MediaStream stream
    +
    readonly attribute sequence<MediaStream> streams

    The AddTrackEvent

    RTCRtpReceiver receiver
    MediaStreamTrack track
    -
    MediaStream stream
    +
    sequence<MediaStream> streams

    TODO

    @@ -2901,7 +2917,7 @@

    RTCPeerConnection Interface Extensions

    The createDTMFSender() method creates an RTCDTMFSender - that references the given MediaStreamTrack. A RTCRtpSender for track + that references the given MediaStreamTrack. An RTCRtpSender for track MUST already exist in theRTCPeerConnection object's set of senders; if not, throw an InvalidParameter exception and abort these steps.

    @@ -4427,7 +4443,7 @@

    Simple Peer-to-peer Example

    // once remote video track arrives, show it in the remote video element pc.onaddtrack = function (evt) { if (evt.track.kind === "video") { - remoteView.srcObject = evt.stream; + remoteView.srcObject = evt.streams[0]; } }; From 9506f8ba10282de586da19dbefc012403c1944cb Mon Sep 17 00:00:00 2001 From: Justin Uberti Date: Fri, 17 Oct 2014 18:32:16 -0700 Subject: [PATCH 03/25] Merge anchor fix from @dontcallmedom --- webrtc.html | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/webrtc.html b/webrtc.html index cf41a6039..c8d68d729 100644 --- a/webrtc.html +++ b/webrtc.html @@ -1906,7 +1906,8 @@

    RTCPeerConnection Interface Extensions

    addTrack method, and have an RTCRtpSender created for them, but content MUST NOT be transmitted, though tracks marked with peerIdentity can be transmitted if they meet the - requirements for sending (see ).

    + requirements for sending (see     + isolated streams and RTCPeerConnection).

    All other tracks that are not accessible to the application MUST NOT be sent to the peer, with silence (audio), black @@ -4255,7 +4256,7 @@

    Isolated Media Streams

    Used as the argument to addTrack() on an RTCPeerConnection instance, subject to the - restrictions in .

    + restrictions in isolated streams and RTCPeerConnection.

    From 2e0075a96294648a219162b2d99485e90ca4e797 Mon Sep 17 00:00:00 2001 From: Justin Uberti Date: Fri, 17 Oct 2014 18:45:45 -0700 Subject: [PATCH 04/25] AddTrackEvent -> RTCAddTrackEvent Fix the parameter descriptions for RTCAddTrackEvent --- webrtc.html | 49 ++++++++++++++++++++++++++++++++++++------------- 1 file changed, 36 insertions(+), 13 deletions(-) diff --git a/webrtc.html b/webrtc.html index c8d68d729..b59bcd386 100644 --- a/webrtc.html +++ b/webrtc.html @@ -2036,45 +2036,68 @@

    RTCRtpReceiver Interface

    -

    AddTrackEvent

    +

    RTCAddTrackEvent

    The onaddtrack event uses the - AddTrackEvent interface.

    + RTCAddTrackEvent interface.

    Firing an - AddTrackEvent event named e with an + RTCAddTrackEvent event named e with an MediaStreamTrack track 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 AddTrackEvent interface with the + uses the RTCAddTrackEvent interface with the track attribute set to track, MUST be created and dispatched at the given target.

    -
    -
    Constructor(DOMString type, AddTrackEventInit +
    +
    Constructor(DOMString type, RTCAddTrackEventInit eventInitDict)
    readonly attribute RTCRtpReceiver receiver
    + +
    +

    The receiver attribute + represents the RTCRtpReceiver object associated with + the event.

    +
    +
    readonly attribute MediaStreamTrack track
    -
    readonly attribute sequence<MediaStream> streams

    The track attribute - represents the MediaStreamTrack object associated with - the event.

    + represents the MediaStreamTrack object that is + associated with the RTCRtpReceiver identified by + receiver.

    +
    + +
    readonly attribute sequence<MediaStream> streams
    + +
    +

    The streams attribute + identifies the MediaStreams that + track is a part of.

    +
    -
    +
    RTCRtpReceiver receiver
    +
    +

    TODO

    +
    MediaStreamTrack track
    +
    +

    TODO

    +
    sequence<MediaStream> streams
    -

    TODO

    @@ -4832,7 +4855,7 @@

    Event summary

    addtrack - AddTrackEvent + RTCAddTrackEvent A new RTCRtpReceiver, and associated MediaStreamTrack, has been added to the Date: Sun, 26 Oct 2014 22:30:03 -0700 Subject: [PATCH 05/25] PR feedback; onaddtrack -> ontrack --- webrtc.html | 109 ++++++++++++++++++++++++---------------------------- 1 file changed, 50 insertions(+), 59 deletions(-) diff --git a/webrtc.html b/webrtc.html index b59bcd386..79d61b3c6 100644 --- a/webrtc.html +++ b/webrtc.html @@ -518,20 +518,10 @@

    Operation

    RTCPeerConnection expecting this media.

    -
  • -

    Create a MediaStreamTrack object - track, to represent the incoming media track. - Add track to the MediaStreams streams - referenced by the SDP - negotiation, creating a new ones if they do not exist. If no - MediaStreams are indicated in the SDP negotiation, a default MediaStream - is used.

    -
    • -

  • Run the algorithm - to represent an incoming component with a track for each incoming - component.

    + to represent the incoming component with a new + MediaStreamTrack track.

    The creation of new incoming MediaStreamTracks may be triggered either by SDP @@ -540,6 +530,13 @@

    Operation

    when you receive multiple conflicting pranswers?]] -->

    • +
  • + Add track to the MediaStreams streams + referenced by the SDP negotiation, creating new ones if they do not + yet exist. If no MediaStreams are specified, + a default MediaStream is created and used.

    +
    • +

  • Queue a task to run the following substeps:

    @@ -560,8 +557,8 @@

    Operation

  • Fire an event named - addtrack with + track with receiver, track, and streams at the connection object.

    • @@ -570,7 +567,7 @@

    Operation

    When a user agent has negotiated media for a component that belongs - to a media stream that is already represented by an existing + to a media track that is already represented by an existing MediaStreamTrack object, the user agent MUST associate the component with that MediaStreamTrack object.

    @@ -587,7 +584,7 @@

    Operation

  • Let track be the MediaStreamTrack - object that represents the media stream being removed, if any. If + object that represents the track being removed, if any. If there isn't one, then abort these steps.

    • @@ -612,16 +609,12 @@

    Operation

    task ran -->
  • -

    Remove the RTCRtpSender associated with track from +

    Remove the RTCRtpReceiver associated with track from connection's set of receivers.

  • -

    Fire a track event named - ended - at the track - object.

    +

    End the track object.

    • @@ -1832,7 +1825,7 @@

    RTCPeerConnection Interface Extensions

    RTCPeerConnection object.

    The getSenders() + "dom-peerconnection-getsenders">getSenders() method MUST return a new sequence that represents a snapshot of all the RTCRtpSenders objects in this RTCPeerConnection object's RTCPeerConnection Interface Extensions RTCPeerConnection object.

    The getReceivers() + "dom-peerconnection-getreceivers">getReceivers() method MUST return a new sequence that represents a snapshot of all the RTCRtpReceiver objects in this RTCPeerConnection object's RTCPeerConnection Interface Extensions

    When the other peer stops sending a track in this manner, a ended event is + "#event-mediastream-ended">ended event is fired at the MediaStreamTrack object.

    When the RTCPeerConnection Interface Extensions

    -
    attribute EventHandler onaddtrack
    +
    attribute EventHandler ontrack
    This event handler, of event handler event type addtrack, MUST be fired + "#event-track">track, MUST be fired by all objects implementing the RTCPeerConnection interface. It is called any time a MediaStreamTrack is added by the remote peer. This will be fired only as a result of - setRemoteDescription. onaddtrack happens as early as + setRemoteDescription. ontrack happens as early as possible after the setRemoteDescription. This callback does not wait for a given media track to be accepted or rejected via SDP negotiation.
    @@ -2005,13 +1998,13 @@

    RTCRtpSender Interface

    parameters to the other side.

    + "interface RTCRtpSender">
    readonly attribute MediaStreamTrack track

    The RTCRtpSender.track - attribute is the track that is immutably associated with this + attribute is the track that is associated with this RTCRtpSender object.

    @@ -2024,7 +2017,7 @@

    RTCRtpReceiver Interface

    wants to receive to the other side.

    + "interface RTCRtpReceiver">
    readonly attribute MediaStreamTrack track
    @@ -2036,32 +2029,32 @@

    RTCRtpReceiver Interface

    -

    RTCAddTrackEvent

    +

    RTCTrackEvent

    -

    The onaddtrack +

    The ontrack event uses the - RTCAddTrackEvent interface.

    + RTCTrackEvent interface.

    -

    Firing an - RTCAddTrackEvent event named e with an +

    Firing an + RTCTrackEvent event named e with an MediaStreamTrack track 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 RTCAddTrackEvent interface with the - track attribute + uses the RTCTrackEvent interface with the + track attribute set to track, MUST be created and dispatched at the given target.

    -
    -
    Constructor(DOMString type, RTCAddTrackEventInit +
    +
    Constructor(DOMString type, RTCTrackEventInit eventInitDict)
    readonly attribute RTCRtpReceiver receiver

    The receiver attribute + "dom-trackevent-receiver">receiver attribute represents the RTCRtpReceiver object associated with the event.

    @@ -2070,24 +2063,23 @@

    RTCAddTrackEvent

    The track attribute + "dom-trackevent-track">track attribute represents the MediaStreamTrack object that is associated with the RTCRtpReceiver identified by receiver.

    -
    readonly attribute sequence<MediaStream> streams
    - -
    -

    The streams attribute - identifies the MediaStreams that +

    sequence<MediaStream> getStreams()
    + +
    +

    Returns a sequence of MediaStream objects + representing the MediaStreams that this event's track is a part of.

    -
    +
    RTCRtpReceiver receiver
    @@ -3450,7 +3442,7 @@

    Example

    following example code might be used:

     var baselineReport, currentReport;
-var selector = pc.getRemoteStreams()[0].getAudioTracks()[0];
+var selector = pc.getSenders()[0].track;
 
 pc.getStats(selector, function (report) {
     baselineReport = report;
@@ -4211,7 +4203,7 @@ 
    MediaStreamTrack
    
       readyState set to muted on the remote peer if
       the local user agent disables the corresponding
       MediaStreamTrack in the
-      MediaStream that is being sent. When the onaddtrack
+      MediaStream that is being sent. When the ontrack
       event triggers on an RTCPeerConnection, all
       MediaStreamTrack objects in the resulting
       MediaStream are muted until media data can be read
@@ -4465,19 +4457,18 @@ 
    Simple Peer-to-peer Example
    
     }
 
     // once remote video track arrives, show it in the remote video element
-    pc.onaddtrack = function (evt) {
-        if (evt.track.kind === "video") {
+    pc.ontrack = function (evt) {
+        if (evt.track.kind === "video")
           remoteView.srcObject = evt.streams[0];
-        }
     };
 
     // get a local stream, show it in a self-view and add it to be sent
     navigator.mediaDevices.getUserMedia({ "audio": true, "video": true }, function (stream) {
         selfView.srcObject = stream;
         if (stream.getAudioTracks().length > 0)
-            pc.addTrack(stream.getAudioTracks(0), stream);
+            pc.addTrack(stream.getAudioTracks()[0], stream);
         if (stream.getVideoTracks().length > 0)
-            pc.addTrack(stream.getVideoTracks(0), stream);    
+            pc.addTrack(stream.getVideoTracks()[0], stream);    
     }, logError);
 }
 
@@ -4853,9 +4844,9 @@ 
    Event summary
    
 
         
           addtrack
+          "event-track">track
 
-          RTCAddTrackEvent
+          RTCTrackEvent
 
           
             A new RTCRtpReceiver, and associated MediaStreamTrack, has been added to the 
Date: Thu, 30 Oct 2014 14:46:17 -0700
Subject: [PATCH 06/25] no change

---
 webrtc.html | 1 +
 1 file changed, 1 insertion(+)

diff --git a/webrtc.html b/webrtc.html
index f8c6d3c35..4e964d605 100644
--- a/webrtc.html
+++ b/webrtc.html
@@ -4,6 +4,7 @@
   -->
 
 
+
 
 
   WebRTC 1.0: Real-time Communication Between Browsers

From 1243001307355946be4d69aa574b1d9055c26d63 Mon Sep 17 00:00:00 2001
From: Stefan Hakansson LK 
Date: Tue, 2 Dec 2014 10:01:45 +0100
Subject: [PATCH 07/25] Editorial, changed some text that talks about
 MediaStream's to MediaStreamTrack's.

---
 webrtc.html | 21 ++++++++++-----------
 1 file changed, 10 insertions(+), 11 deletions(-)

diff --git a/webrtc.html b/webrtc.html
index 19386f6bd..f9b417b1e 100644
--- a/webrtc.html
+++ b/webrtc.html
@@ -630,13 +630,16 @@ 
    Operation
    
         "#event-negotiation">negotiationneeded     event is fired at the
         RTCPeerConnection object.
    
 
-        
    In particular, if an RTCPeerConnection object is
-        consuming a MediaStream on
-        which a track is added, by, e.g., the addTrack()
-        method being invoked, the RTCPeerConnection object
-        MUST fire the "negotiationneeded" event. Removal of media components
-        must also trigger "negotiationneeded".
    
+        
    In particular, if a MediaStreamTrack object
+        is added to, using the addTrack()  method, or removed from, using the
+        removeTrack()
+         method, an RTCPeerConnection object, the
+        RTCPeerConnection object MUST fire the
+        "negotiationneeded" event (except for the cases when the added track
+        is already present in the set of RTCRtpSenders,
+        or the removed track is not present in the set 
+        of RTCRtpSenders).
    
 
         
    To prevent network sniffing from allowing a fourth
         party to establish a connection to a peer using the information sent
@@ -1599,10 +1602,6 @@ 
    RTCSdpError
    
             current state. User agents SHOULD provide as much additional
             information in the error message as possible.
 
-            
  • IncompatibleMediaStreamTrackError: The provided
-            MediaStreamTrack is not an element of a MediaStream that is
-            currently in the RTCPeerConnection's localStreams attribute.
    • 
-
             
  • InternalError: The RTCPeerConnection encountered an error that
             it could not recover from.
    • 
           

From 6ec919a3699a316097ee2a2d45da71440276a50d Mon Sep 17 00:00:00 2001
From: Stefan Hakansson LK 
Date: Tue, 2 Dec 2014 11:07:39 +0100
Subject: [PATCH 08/25] Fixed some respec errors. The "Duplicate definition of
 'track'" remains though.

---
 webrtc.html | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/webrtc.html b/webrtc.html
index f9b417b1e..93eef8cc8 100644
--- a/webrtc.html
+++ b/webrtc.html
@@ -631,15 +631,15 @@ 
    Operation
    
         RTCPeerConnection object.
    
 
         
    In particular, if a MediaStreamTrack object
-        is added to, using the addTrack()  method, or removed from, using the
-        removeTrack()
-         method, an RTCPeerConnection object, the
+        is added to, using the 
+        addTrack()  method, or removed from, using the
+        removeTrack()
+         method, an RTCPeerConnection object, the
         RTCPeerConnection object MUST fire the
         "negotiationneeded" event (except for the cases when the added track
-        is already present in the set of RTCRtpSenders,
-        or the removed track is not present in the set 
-        of RTCRtpSenders).
    
+        is already present in the set of RTCRtpSenders,
+        or the removed track is not present in the set 
+        of RTCRtpSenders).
    
 
         
    To prevent network sniffing from allowing a fourth
         party to establish a connection to a peer using the information sent

From 711a49f539b17ca40f893e19c15746a5645079d8 Mon Sep 17 00:00:00 2001
From: Stefan Hakansson LK 
Date: Tue, 2 Dec 2014 14:48:02 +0100
Subject: [PATCH 09/25] More edits associated with moving from sending streams
 to sending tracks.

---
 webrtc.html | 143 ++++++++++++++++++++++------------------------------
 1 file changed, 61 insertions(+), 82 deletions(-)

diff --git a/webrtc.html b/webrtc.html
index 93eef8cc8..b0ddae885 100644
--- a/webrtc.html
+++ b/webrtc.html
@@ -631,10 +631,10 @@ 
    Operation
    
         RTCPeerConnection object.
    
 
         
    In particular, if a MediaStreamTrack object
-        is added to, using the 
-        addTrack()  method, or removed from, using the
+        is added to (using the 
+        addTrack()  method) or removed from (using the
         removeTrack()
-         method, an RTCPeerConnection object, the
+         method) an RTCPeerConnection object, the
         RTCPeerConnection object MUST fire the
         "negotiationneeded" event (except for the cases when the added track
         is already present in the set of RTCRtpSenders,
@@ -3987,21 +3987,35 @@ 
    Media Stream API Extensions for Network Use
    
     
    
       
    Introduction
    
 
-      
    The MediaStream interface, as defined in the
+      
    The MediaStreamTrack interface, as defined in the
       [[!GETUSERMEDIA]] specification, typically represents a stream of data of
-      audio and/or video. A MediaStream may be extended to
-      represent a stream that either comes from or is sent to a remote node
+      audio or video. One or more MediaStreamTracks can be
+      collected in a MediaStream (strictly speaking, a 
+      MediaStream as defined in [[!GETUSERMEDIA]] may contain
+      zero or more MediaStreamTrack objects).
+
+      A  MediaStreamTrack may be extended to
+      represent a stream that either comes from or is sent to a remote peer
       (and not just the local camera, for instance). The extensions required to
-      enable this capability on the MediaStream object will be
+      enable this capability on the MediaStreamTrack object will be
       described in this section. How the media is transmitted to the peer is
       described in [[!RTCWEB-RTP]], [[!RTCWEB-AUDIO]], and
       [[!RTCWEB-TRANSPORT]].
    
 
-      
    A MediaStream as defined in [[!GETUSERMEDIA]] may contain
-      zero or more MediaStreamTrack objects. A
-      MediaStreamTrack sent to another peer will appear as one and
+      
    As described earlier in this document, the object dealt with when
+      sending audio or video to a remote peer is MediaStreamTracks.
+      A MediaStreamTrack sent to another peer will appear as one and
       only one MediaStreamTrack to the recipient. A peer is
-      defined as a user agent that supports this specification.
    
+      defined as a user agent that supports this specification.      
+      In addition, the sending side application can indicate what 
+      MediaStream object(s) the MediaStreamTrack is member
+      of. The corresponding MediaStream object(s) on the receiver
+      side will be created (if not already present) and populated accordingly.
    
+
+      
    As also described earlier in this document, the objects 
+      RTCRTPSender and RTCRTPReceiver can be used by the
+      application to get more fine grained control over the transmission and
+      reception of MediaStreamTracks.
    
 
       
    Channels are the smallest unit considered in the
       MediaStream specification. Channels are intended to be
@@ -4011,24 +4025,25 @@ 
    Introduction
    
       encode, or discard, all the channels in the track.
    
 
       
    The concepts of an input and output to a given
-      MediaStream apply in the case of MediaStream
+      MediaStreamTrack apply in the case of MediaStreamTrack
       objects transmitted over the network as well. A
-      MediaStream created by an
-      RTCPeerConnection object (described later in this
+      MediaStreamTrack created by an
+      RTCPeerConnection object (as described previously in this
       document) will take as input the data received from a remote peer.
-      Similarly, a MediaStream from a local source, for instance a
+      Similarly, a MediaStreamTrack from a local source, for instance a
       camera via [[!GETUSERMEDIA]], will have an output that represents what is
       transmitted to a remote peer if the object is used with an
       RTCPeerConnection object.
    
 
-      
    The concept of duplicating MediaStream objects as
-      described in [[!GETUSERMEDIA]] is also applicable here. This feature can
-      be used, for instance, in a video-conferencing scenario to display the
+      
    The concept of duplicating MediaStream and
+      MediaStreamTrack objects as described in [[!GETUSERMEDIA]] is
+      also applicable here. This feature can be used, for instance, in a
+      video-conferencing scenario to display the
       local video from the user's camera and microphone in a local
       monitor, while only transmitting the audio to the remote peer (e.g. in
-      response to the user using a "video mute" feature). Combining tracks from
-      different MediaStream objects into a new
-      MediaStream is useful in certain situations.
    
+      response to the user using a "video mute" feature). Combining
+      different MediaStreamTrack objects into new MediaStream
+      objects is useful in certain situations.
    
 
       
    In this document, we only specify aspects of the
       following objects that are relevant when used along with an
@@ -4047,12 +4062,12 @@ 
    id
    
         
    The id attribute
         specified in MediaStream returns an id that is unique to
-        this stream, so that streams can be recognized after they are sent
-        through the RTCPeerConnection API.
    
 
         
    When a MediaStream is
-        created to represent a stream obtained from a remote peer, the
+        created to represent a stream defined at a remote peer, the
         id
         attribute is initialized from information provided by the remote
         source.
    
@@ -4073,15 +4088,15 @@ 
    Events on MediaStream
    
         
    A new media track may be associated with an existing
         MediaStream. For example, if a remote peer adds a
         new MediaStreamTrack object to a
-        MediaStream that is being sent over an
-        RTCPeerConnection, this is observed on the local
+        RTCPeerConnection, and indicates that the
+        MediaStreamTrack is a member of a 
+        MediaStream that has already been created locally
+        by the RTCPeerConnection, this is observed on the local
         user agent. If this happens for the reason exemplified, or for any
         other reason than the addTrack()
-        method being invoked locally on a MediaStream or
-        tracks being added as the stream is created (i.e. the stream is
-        initialized with tracks), the user agent MUST run the following
-        steps:
    
+        method being invoked locally on a MediaStream,
+        the user agent MUST run the following steps:
    
 
         
      
           
    1. 
@@ -4090,48 +4105,13 @@ 
      Events on MediaStream
      
           
      2. 
 
           
    2. 
-            
      Represent component
-            with track: Run the following steps to create a track
-            representing the incoming component:
      
-
-            
        
-              
      1. 
-                
        Create a MediaStreamTrack object
-                track to represent the component.
        
-              
        2. 
-
-              
      2. 
-                
        Initialize track's kind
-                attribute to "audio" or "video"
-                depending on the media type of the incoming component.
        
-              
        3. 
-
-              
      3. 
-                
        Initialize track's id
-                attribute to the component track id.
        
-              
        4. 
-
-              
      4. 
-                
        Initialize track's label
-                attribute to "remote audio" or "remote
-                video" depending on the media type of the incoming
-                component.
        
-              
        5. 
-
-              
      5. 
-                
        Initialize track's readyState
-                attribute to muted.
        
-              
        6. 
+            
        Let track be the MediaStreamTrack
+            object representing the media component about to be added.
        
+          
 
-              
      6. 
-                
        Add track to stream's track set.
        
-              
        7. 
-            
      
+          
    3. 
+            
      Add track to stream's track set.
      
           
      4. 
 
           
    4. 
@@ -4186,7 +4166,7 @@ 
      MediaStreamTrack
      
       source, as is the case for a MediaStream received over an
       RTCPeerConnection ) is always strong.
      
 
-      
      When a track belongs to a MediaStream that comes
+      
      When a track comes
       from a remote peer and the remote peer has permanently stopped sending
       data the ended event MUST be fired on the track, as
       specified in [[!GETUSERMEDIA]].
      
@@ -4194,20 +4174,19 @@ 
      MediaStreamTrack
      
       
      ISSUE: How do you know when it has stopped? This seems
       like an SDP question, not a media-level question.
      
 
-      
      A track in a MediaStream, received with an
+      
      A MediaStreamTrack, received with an
       RTCPeerConnection, MUST have its
-      readyState attribute [[!GETUSERMEDIA]] set to
-      muted until media data arrives.
      
+      muted attribute [[!GETUSERMEDIA]] set to
+      true until media data arrives.
      
 
       
      In addition, a MediaStreamTrack has its
-      readyState set to muted on the remote peer if
+      muted attribute set to true on the remote peer if
       the local user agent disables the corresponding
-      MediaStreamTrack in the
-      MediaStream that is being sent. When the ontrack
-      event triggers on an RTCPeerConnection, all
-      MediaStreamTrack objects in the resulting
-      MediaStream are muted until media data can be read
-      from the RTP source.
      
+      MediaStreamTrack that is being sent. When the
+      ontrack event triggers on an
+      RTCPeerConnection, the
+      MediaStreamTrack object in the event
+      is muted until media data can be read from the RTP source.
      
 
       
      ISSUE: How do you know when it has been disabled? This
       seems like an SDP question, not a media-level question.
      

From fe6fdeb686c197fbd165eb4baa878b2151692330 Mon Sep 17 00:00:00 2001
From: Stefan Hakansson LK 
Date: Fri, 12 Dec 2014 10:05:59 +0100
Subject: [PATCH 10/25] Fixed (hopefully) the link error spotted by Adam when
 reviewing PR #40.

---
 webrtc.html | 45 ++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 40 insertions(+), 5 deletions(-)

diff --git a/webrtc.html b/webrtc.html
index b0ddae885..438c97b31 100644
--- a/webrtc.html
+++ b/webrtc.html
@@ -520,9 +520,44 @@ 
      Operation
      
           
      5. 
 
           
    5. 
-            
      Run the algorithm
-            to represent the incoming component with a new 
-            MediaStreamTrack track.
      
+            
      Run the following steps to create a track
+            representing the incoming component:
      
+
+            
        
+              
      1. 
+                
        Create a MediaStreamTrack object
+                track to represent the component.
        
+              
        2. 
+
+              
      2. 
+                
        Initialize track's kind
+                attribute to "audio" or "video"
+                depending on the media type of the incoming component.
        
+              
        3. 
+
+              
      3. 
+                
        Initialize track's id
+                attribute to the component track id.
        
+              
        4. 
+
+              
      4. 
+                
        Initialize track's label
+                attribute to "remote audio" or "remote
+                video" depending on the media type of the incoming
+                component.
        
+              
        5. 
+
+              
      5. 
+                
        Initialize track's readyState
+                attribute to muted.
        
+              
        6. 
+
+            
      
+          
      6. 
 
             
      The creation of new incoming
             MediaStreamTracks may be triggered either by SDP
@@ -532,9 +567,9 @@ 
      Operation
      
           
 
           
    6.  
-            Add track to the MediaStreams streams
+            Add track to the MediaStream(s) streams
             referenced by the SDP negotiation, creating new ones if they do not
-            yet exist. If no MediaStreams are specified,
+            yet exist. If no MediaStream is specified,
             a default MediaStream is created and used.
      
           
      7. 
 

From aa2bb9f7eab5348e28afce2693d4c193427c1e31 Mon Sep 17 00:00:00 2001
From: Justin Uberti 
Date: Wed, 7 Jan 2015 23:48:11 -0800
Subject: [PATCH 11/25] Cleanups

Clean extraneous whitespace
Add  elements as needed
Change sequence -> array as suggested by DOM
Minor spelling and indentation fixups
---
 webrtc.html | 84 ++++++++++++++++++++++++++---------------------------
 1 file changed, 42 insertions(+), 42 deletions(-)

diff --git a/webrtc.html b/webrtc.html
index 438c97b31..ab480233f 100644
--- a/webrtc.html
+++ b/webrtc.html
@@ -11,11 +11,11 @@
   
   
   
 
 
@@ -119,7 +119,7 @@ 
      Terminology
      
     Constraints, and Consumer are defined in
     [[!GETUSERMEDIA]].
      
   
    
- 
+
   
    
     
    Peer-to-peer connections
    
 
@@ -436,13 +436,13 @@ 
    Operation
    
 
           
  • 
             
    If the ICE Agent has found one or more candidate pairs for each
-            MediaStreamTrack that forms a valid connection, the ICE connection
+            MediaStreamTrack that forms a valid connection, the ICE connection
             state is changed to "connected".
    
           
    • 
 
           
  • 
             
    When the ICE Agent finishes checking all candidate pairs, if at
-            least one connection has been found for each MediaStreamTrack, the
+            least one connection has been found for each MediaStreamTrack, the
             RTCPeerConnection
             ice connection state is changed to "completed"; otherwise
@@ -561,12 +561,12 @@ 
    Operation
    
 
             
    The creation of new incoming
             MediaStreamTracks may be triggered either by SDP
-            negotiation or by the receipt of media on a given flow. 
+            negotiation or by the receipt of media on a given flow.
             
    
           
    • 
 
-          
  •  
+          
  • 
             Add track to the MediaStream(s) streams
             referenced by the SDP negotiation, creating new ones if they do not
             yet exist. If no MediaStream is specified,
@@ -585,7 +585,7 @@ 
    Operation
    
               
    • 
 
               
  • 
-                
    Create a new RTCRtpReceiver object receiver
+                
    Create a new RTCRtpReceiver object receiver
                   for track, and add it
                   to connection's set of receivers.
    
@@ -645,7 +645,7 @@ 
    Operation
    
          task ran -->
 
               
  • 
-                
    Remove the RTCRtpReceiver associated with track from 
+                
    Remove the RTCRtpReceiver associated with track from
                 connection's set of receivers.
    
               
    • 
 
@@ -672,9 +672,9 @@ 
    Operation
    
          method) an RTCPeerConnection object, the
         RTCPeerConnection object MUST fire the
         "negotiationneeded" event (except for the cases when the added track
-        is already present in the set of RTCRtpSenders,
-        or the removed track is not present in the set 
-        of RTCRtpSenders).
    
+        is already present in the set of RTCRtpSenders,
+        or the removed track is not present in the set
+        of RTCRtpSenders).
    
 
         
    To prevent network sniffing from allowing a fourth
         party to establish a connection to a peer using the information sent
@@ -1826,20 +1826,20 @@ 
    RTCPeerConnectionIceEvent
    
   
    
 
   
    
-      
    RTP media API
    
+      
    RTP Media API
    
 
-      
    The RTP media API lets a web application send and receive MediaStreamTracks
-      over a peer-to-peer connection. Tracks, when added to a PeerConnection, result in 
+      
    The RTP media API lets a web application send and receive MediaStreamTracks
+      over a peer-to-peer connection. Tracks, when added to a RTCPeerConnection, result in
       signaling; when this signaling is forwarded to a remote peer, it causes
       corresponding tracks to be created on the remote side.
    
 
-      
    The actual encoding and transmission of MediaStreamTracks is managed through
-      objects called RTCRtpSenders. Similarly, the reception and decoding of 
-      MediaStreamTracks is managed through objects called RTCRtpReceivers.
    
+      
    The actual encoding and transmission of MediaStreamTracks is managed through
+      objects called RTCRtpSenders. Similarly, the reception and decoding of
+      MediaStreamTracks is managed through objects called RTCRtpReceivers.
    
 
-      
    A RTCPeerConnection object contains a 
-      set of RTCRtpSenders, representing tracks to
-      be sent, and a set of RTCRtpReceivers, 
+      
    A RTCPeerConnection object contains a
+      set of RTCRtpSenders, representing tracks to
+      be sent, and a set of RTCRtpReceivers,
       representing tracks that are to be received on this
       RTCPeerConnection object. Both of these sets are
       initialized to empty sets when the
@@ -1848,11 +1848,11 @@ 
    RTP media API
    
       
    
         
    RTCPeerConnection Interface Extensions
    
 
-      
    The RTP media API extends the
-      RTCPeerConnection interface as described below.
    
+        
    The RTP media API extends the
+        RTCPeerConnection interface as described below.
    
 
-            
    
-
    sequence<RTCRtpSender> getSenders()
    
+        
    
+          
    sequence<RTCRtpSender> getSenders()
    
 
           
    
             
    Returns a sequence of RTCRtpSender objects
@@ -1913,13 +1913,13 @@ 
    RTCPeerConnection Interface Extensions
    
               
 
               
  • 
-                
    If an RTCRtpSender for track already exists in
+                
    If an RTCRtpSender for track already exists in
                 connection's set of senders,
                 then abort these steps.
    
               
    • 
 
               
  • 
-                
    Create a new RTCRtpSender for track, add it to 
+                
    Create a new RTCRtpSender for track, add it to
                  connection's set of senders,
                  and return it to the caller.
    
               
    • 
@@ -1931,7 +1931,7 @@ 
    RTCPeerConnection Interface Extensions
    
                 track 
                 CORS cross-origin. These tracks can be supplied to the
-                addTrack method, and have an RTCRtpSender created for them, but content
+                addTrack method, and have an RTCRtpSender created for them, but content
                 MUST NOT be transmitted, though tracks marked with
                 peerIdentity can be transmitted if they meet the
                 requirements for sending (see 
@@ -1958,7 +1958,7 @@ 
    RTCPeerConnection Interface Extensions
    
           
    void removeTrack (RTCRtpSender sender)
    
 
           
    
-            
    Removes sender, and its associated MediaStreamTrack, from the
+            
    Removes sender, and its associated MediaStreamTrack, from the
             RTCPeerConnection.
    
 
             
@@ -2007,7 +2007,7 @@ 
    RTCPeerConnection Interface Extensions
    
             
           
    
 
-            
    attribute EventHandler ontrack
    
+          
    attribute EventHandler ontrack
    
 
           
    This event handler, of event handler event type track, MUST be fired
@@ -2019,7 +2019,7 @@ 
    RTCPeerConnection Interface Extensions
    
           does not wait for a given media track to be accepted or rejected via
           SDP negotiation.
    
 
-            
    
+        
    
 
       
    
 
@@ -2039,7 +2039,7 @@ 
    RTCRtpSender Interface
    
         
    
           
    The RTCRtpSender.track
-          attribute is the track that is associated with this 
+          attribute is the track that is associated with this
           RTCRtpSender object.
    
         
    
       
    
@@ -2058,7 +2058,7 @@ 
    RTCRtpReceiver Interface
    
         
    
           
    The RTCRtpReceiver.track
-          attribute is the track that is immutably associated with this 
+          attribute is the track that is immutably associated with this
           RTCRtpReceiver object.
    @@ -2104,10 +2104,10 @@

    RTCTrackEvent

    receiver.

    -
    sequence<MediaStream> getStreams()
    - +
    readonly attribute MediaStream[] streams
    +
    -

    Returns a sequence of MediaStream objects +

    Returns an array of MediaStream objects representing the MediaStreams that this event's track is a part of.

    @@ -2115,7 +2115,7 @@

    RTCTrackEvent

    - +
    RTCRtpReceiver receiver

    TODO

    @@ -2124,7 +2124,7 @@

    RTCTrackEvent

    TODO

    -
    sequence<MediaStream> streams
    +
    MediaStream[] streams

    TODO

    @@ -2968,7 +2968,7 @@

    RTCPeerConnection Interface Extensions

    The createDTMFSender() method creates an RTCDTMFSender - that references the given MediaStreamTrack. An RTCRtpSender for track + that references the given MediaStreamTrack. An RTCRtpSender for track MUST already exist in theRTCPeerConnection object's set of senders; if not, throw an InvalidParameter exception and abort these steps.

    @@ -4041,7 +4041,7 @@

    Introduction

    sending audio or video to a remote peer is MediaStreamTracks. A MediaStreamTrack sent to another peer will appear as one and only one MediaStreamTrack to the recipient. A peer is - defined as a user agent that supports this specification. + defined as a user agent that supports this specification. In addition, the sending side application can indicate what MediaStream object(s) the MediaStreamTrack is member of. The corresponding MediaStream object(s) on the receiver @@ -4482,7 +4482,7 @@

    Simple Peer-to-peer Example

    if (stream.getAudioTracks().length > 0) pc.addTrack(stream.getAudioTracks()[0], stream); if (stream.getVideoTracks().length > 0) - pc.addTrack(stream.getVideoTracks()[0], stream); + pc.addTrack(stream.getVideoTracks()[0], stream); }, logError); } @@ -4863,7 +4863,7 @@

    Event summary

    RTCTrackEvent - A new RTCRtpReceiver, and associated MediaStreamTrack, has been added to the RTCRtpReceiver    , and associated MediaStreamTrack, has been added to the set of receivers. From e1372b8576fe255e9fb6c2e12241777bbfca717c Mon Sep 17 00:00:00 2001 From: Adam Bergkvist Date: Sun, 14 Dec 2014 13:24:05 +0100 Subject: [PATCH 12/25] Update misleading local/remoteDescription attribute text --- webrtc.html | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/webrtc.html b/webrtc.html index ab480233f..51ce9d6e0 100644 --- a/webrtc.html +++ b/webrtc.html @@ -1021,8 +1021,8 @@

    Interface Definition

    The localDescription - attribute MUST return the RTCSessionDescription - that was most recently passed to RTCSessionDescription + that was successfully set using setLocalDescription(), plus any local candidates that have been generated by the ICE Agent since then.

    @@ -1092,8 +1092,8 @@

    Interface Definition

    The remoteDescription - attribute MUST return the RTCSessionDescription - that was most recently passed to RTCSessionDescription + that was successfully set using setRemoteDescription(), plus any remote candidates that have been supplied via Change Log +

    Changes since December 5, 2014

    + +
      +
    1. Update misleading local/RemoteDescription attribute text.
      2. +
    +

    Changes since June 4, 2014

      From 2b020e296cb17783ee3f7080b8e0af1a9d101b39 Mon Sep 17 00:00:00 2001 From: Adam Bergkvist Date: Thu, 22 Jan 2015 15:49:26 +0100 Subject: [PATCH 13/25] Define streams in the algorithm to represent an incoming component as a MediaStreamTrack --- webrtc.html | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/webrtc.html b/webrtc.html index 51ce9d6e0..6450c4149 100644 --- a/webrtc.html +++ b/webrtc.html @@ -519,6 +519,14 @@

      Operation

      RTCPeerConnection expecting this media.

      +
    1. +

      Let streams be a list of + MediaStream objects that the sender indicated the + sent MediaStreamTrack being a part of. This + information needed to collect these objects is part of the incoming + SDP.

      +
      2. +

    2. Run the following steps to create a track representing the incoming component:

      @@ -567,10 +575,14 @@

      Operation

    3. - Add track to the MediaStream(s) streams - referenced by the SDP negotiation, creating new ones if they do not - yet exist. If no MediaStream is specified, - a default MediaStream is created and used.

      +

      If streams is an empty list, create a new + MediaStream object and add it to streams. +

      +
      4. + +
    4. +

      Add track to all MediaStream + objects in streams.

    5. From d6b462272906d47c3c952cb218e2a2447abb7470 Mon Sep 17 00:00:00 2001 From: Adam Bergkvist Date: Thu, 22 Jan 2015 15:51:36 +0100 Subject: [PATCH 14/25] Remove paragraph not applicable with the move from sending streams to tracks --- webrtc.html | 5 ----- 1 file changed, 5 deletions(-) diff --git a/webrtc.html b/webrtc.html index 6450c4149..0412c5086 100644 --- a/webrtc.html +++ b/webrtc.html @@ -614,11 +614,6 @@

      Operation

    -

    When a user agent has negotiated media for a component that belongs - to a media track that is already represented by an existing - MediaStreamTrack object, the user agent MUST associate - the component with that MediaStreamTrack object.

    -

    When an RTCPeerConnection finds that a track from the remote peer has been removed, the user agent MUST follow these steps:

    From b1ebed9783f9a61c825043cd7b010e479d5111c2 Mon Sep 17 00:00:00 2001 From: Adam Bergkvist Date: Thu, 22 Jan 2015 15:54:08 +0100 Subject: [PATCH 15/25] Remove step 4.3 in the algorithm where the UA removes incoming tracks --- webrtc.html | 4 ---- 1 file changed, 4 deletions(-) diff --git a/webrtc.html b/webrtc.html index 0412c5086..079455b7b 100644 --- a/webrtc.html +++ b/webrtc.html @@ -655,10 +655,6 @@

    Operation

    Remove the RTCRtpReceiver associated with track from connection's set of receivers.

    - -
  • -

    End the track object.

    -
    • From 7738aa90cd76fc4c12f2cb9ecc72e535d3550dc5 Mon Sep 17 00:00:00 2001 From: Adam Bergkvist Date: Thu, 22 Jan 2015 15:54:51 +0100 Subject: [PATCH 16/25] Fixed typo --- webrtc.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/webrtc.html b/webrtc.html index 079455b7b..dc6c485ee 100644 --- a/webrtc.html +++ b/webrtc.html @@ -1951,7 +1951,7 @@

    RTCPeerConnection Interface Extensions

  • If connection's RTCPeerConnection - signalingState is stable, then fire a is stable, then fire an negotiationneeded event at connection.

    • From 8165d3d1c12f2df9370723dfa4f3cf7af72f9bd5 Mon Sep 17 00:00:00 2001 From: Adam Bergkvist Date: Tue, 27 Jan 2015 11:06:00 +0100 Subject: [PATCH 17/25] Include receiver and streams attributes in the RTCTrackEvent description --- webrtc.html | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/webrtc.html b/webrtc.html index dc6c485ee..43d0c1671 100644 --- a/webrtc.html +++ b/webrtc.html @@ -597,8 +597,8 @@

    Operation

  • -

    Create a new RTCRtpReceiver object receiver - for track, and add it +

    Create a new RTCRtpReceiver object + receiver for track, and add it to connection's set of receivers.

    • @@ -2074,13 +2074,19 @@

    RTCTrackEvent

    RTCTrackEvent interface.

    Firing an - RTCTrackEvent event named e with an - MediaStreamTrack track means that an event + RTCTrackEvent event named e with an + RTCRtpReceiver receiver, a + MediaStreamTrack track and a + MediaStream[] streams, 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 RTCTrackEvent interface with the + receiver attribute + set to receiver, track attribute - set to track, MUST be created and dispatched at the + set to track, + streams attribute + set to streams, MUST be created and dispatched at the given target.

    RTCTrackEvent
    readonly attribute MediaStream[] streams
    -

    Returns an array of MediaStream objects +

    The streams + attribute returns an array of MediaStream objects representing the MediaStreams that this event's track is a part of.

    From 89da30527c43a772b2fff198a6c63ad0f40cca9a Mon Sep 17 00:00:00 2001 From: Adam Bergkvist Date: Tue, 27 Jan 2015 11:07:34 +0100 Subject: [PATCH 18/25] Remove redundant sentence --- webrtc.html | 2 -- 1 file changed, 2 deletions(-) diff --git a/webrtc.html b/webrtc.html index 43d0c1671..71b556330 100644 --- a/webrtc.html +++ b/webrtc.html @@ -4047,8 +4047,6 @@

    Introduction

    described in [[!RTCWEB-RTP]], [[!RTCWEB-AUDIO]], and [[!RTCWEB-TRANSPORT]].

    -

    As described earlier in this document, the object dealt with when - sending audio or video to a remote peer is MediaStreamTracks. A MediaStreamTrack sent to another peer will appear as one and only one MediaStreamTrack to the recipient. A peer is defined as a user agent that supports this specification. From c3afe0fb11504b58ab29e4f2d8c25bf11b3400ba Mon Sep 17 00:00:00 2001 From: Adam Bergkvist Date: Tue, 27 Jan 2015 11:11:38 +0100 Subject: [PATCH 19/25] Bring back note about not dispatching events when adding tracks to a stream as it's created --- webrtc.html | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/webrtc.html b/webrtc.html index 71b556330..8303b3b00 100644 --- a/webrtc.html +++ b/webrtc.html @@ -4138,7 +4138,9 @@

    Events on MediaStream

    user agent. If this happens for the reason exemplified, or for any other reason than the addTrack() - method being invoked locally on a MediaStream, + method being invoked locally on a MediaStream or + tracks being added as the stream is created (i.e. the stream is + initialized with tracks), the user agent MUST run the following steps:

      From 9444b4f5589ebafbc170391b8393a2762b8de595 Mon Sep 17 00:00:00 2001 From: Justin Uberti Date: Fri, 30 Jan 2015 16:00:11 -0800 Subject: [PATCH 20/25] PR feedback; add note about early media Address comments from Cullen, and one from Adam --- webrtc.html | 83 +++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 75 insertions(+), 8 deletions(-) diff --git a/webrtc.html b/webrtc.html index b3593d845..601c757ab 100644 --- a/webrtc.html +++ b/webrtc.html @@ -1859,7 +1859,64 @@

      RTP Media API

      The actual encoding and transmission of MediaStreamTracks is managed through objects called RTCRtpSenders. Similarly, the reception and decoding of - MediaStreamTracks is managed through objects called RTCRtpReceivers.

      + MediaStreamTracks is managed through objects called RTCRtpReceivers. + Each track to be sent is associated with exactly one RTCRtpSender, and + each track to be received is associated with exactly one RTCRtpReceiver.

      + +

      RTCRtpSenders are created when the application attaches a + MediaStreamTrack to a PeerConnection, via the + addTrack method. RTCRtpReceivers, on the other + hand, are created when remote signaling indicates new tracks are available, + and each new MediaStreamTrack and its associated RTCRtpReceiver + are surfaced to the application via the ontrack event.

      + +
      +

      Since the beginning of this specification, remote MediaStreamTracks have been + created by the setRemoteDescription call, one track for each non-rejected + m-line in the remote description. This meant that at the caller, + MediaStreamTracks were not created until the answer was received, and any media + received prior to a remote description (AKA "early media") would be discarded. + If any form of remote description is provided (either an answer or a pranswer), + this issue does not occur.

      + +

      If we want to allow early media to be played out, minor changes are necessary. + Fundamentally, we would need to change when tracks are created + for the offerer; this would have to happen either as a result of setLocalDescription, + or when media packets are received. This ensures that these objects can be created and + connected to media elements for playout.

      + +

      However, there are three consequences to this potential change: +

        +
      1. Media may arrive before the remote DTLS fingerprint has been received. + This means that media could be played out before the validity of the + DTLS fingerprint has been established, which may be hard to explain to users. + As such, it is recommended that media not be played out unless some + TBD RTCConfiguration property (e.g. AllowUnverifiedMedia) has been set. +
        2. +
      2. The information needed to correlate MediaStreamTracks with their + enclosing MediaStream will not yet be present when the tracks are + initially generated. Therefore, the implementation will need to + create dummy MediaStream objects for each MediaStreamTrack, and then + possibly change the associated MediaStream for each track when the + remote description is received (e.g. if it indicates that an audio + and video MediaStreamTrack should be combined into a single MediaStream). + Since media elements act on MediaStreams, some complex reshuffling may + need to occur when the remote description is received. +
        3. +
      3. The track events fired and their timing will change. + For the offerer, ontrack will now fire during setLocalDescription, + once for each track being offered, and track.onended will fire during + setRemoteDescription for any offered tracks that were rejected. + For the answerer, ontrack will continue to fire during setRemoteDescription, + as it does today (this is necessary to allow the answerer to reject + offered tracks by stopping them). +
        4. +
      +

      + +

      For now, we simply make note of this issue, until it can be + considered fully by the WG.

      +

      A RTCPeerConnection object contains a set of RTCRtpSenders, representing tracks to @@ -1939,7 +1996,8 @@

      RTCPeerConnection Interface Extensions

    1. If an RTCRtpSender for track already exists in connection's set of senders, - then abort these steps.

      + throw an InvalidParameter exception and abort these + steps.

    2. @@ -1975,6 +2033,14 @@

      RTCPeerConnection Interface Extensions

      signalingState is stable, then fire an negotiationneeded event at connection.

      + +
      +

      Throughout this document, we need to indicate what should + happen if a change happens and the state is not stable, most + likely to fire the negotiationneeded event when the state + eventually returns to stable. +

      +
    @@ -1986,7 +2052,7 @@

    RTCPeerConnection Interface Extensions

    RTCPeerConnection.

    -

    When the other peer stops sending a track in this manner, a +

    When the other peer stops sending a track in this manner, an ended event is fired at the MediaStreamTrack object.

    @@ -2037,11 +2103,12 @@

    RTCPeerConnection Interface Extensions

    "#event-track">track    , MUST be fired by all objects implementing the RTCPeerConnection interface. It is called any time a MediaStreamTrack is added - by the remote peer. This will be fired only as a result of - setRemoteDescription. ontrack happens as early as - possible after the setRemoteDescription. This callback - does not wait for a given media track to be accepted or rejected via - SDP negotiation. + by the remote peer; currently, this will be fired only as a result of + a setRemoteDescription call, for any new tracks indicated in the + remote description. The ontrack event happens as early as + possible after the setRemoteDescription; any rejection of + new tracks can be done by the application after receiving the ontrack + event, by stopping the track.
    From 092504a8276dee977c4710666b3203f0d853736b Mon Sep 17 00:00:00 2001 From: Justin Uberti Date: Fri, 30 Jan 2015 18:05:19 -0800 Subject: [PATCH 21/25] Move incoming MST text to the RTP Media section Section 4 is now agnostic of MediaStreamTracks, and this lines up well with the new note about when MSTs are generated. --- webrtc.html | 445 +++++++++++++++++++++++++--------------------------- 1 file changed, 210 insertions(+), 235 deletions(-) diff --git a/webrtc.html b/webrtc.html index 601c757ab..53cefd512 100644 --- a/webrtc.html +++ b/webrtc.html @@ -498,184 +498,9 @@

    Operation

    -

    User agents negotiate the codec resolution, bitrate, and other media - parameters. It is RECOMMENDED that user agents initially negotiate for - the maximum resolution of a video stream. For streams that are then - rendered (using a video element), it is RECOMMENDED that - user agents renegotiate for a resolution that matches the rendered - display size.

    - -

    The word "components" in this context refers to an RTP media flow - and does not have anything to do with how [[ICE]] uses the term - "component".

    - -

    When a user agent has reached the point where a - MediaStreamTrack can be created to represent an incoming - component, the user agent MUST run the following steps:

    - -
      -
    1. -

      Let connection be the - RTCPeerConnection expecting this media.

      -
      2. - -
    2. -

      Let streams be a list of - MediaStream objects that the sender indicated the - sent MediaStreamTrack being a part of. This - information needed to collect these objects is part of the incoming - SDP.

      -
      3. - -
    3. -

      Run the following steps to create a track - representing the incoming component:

      - -
        -
      1. -

        Create a MediaStreamTrack object - track to represent the component.

        -
        2. - -
      2. -

        Initialize track's kind - attribute to "audio" or "video" - depending on the media type of the incoming component.

        -
        3. - -
      3. -

        Initialize track's id - attribute to the component track id.

        -
        4. - -
      4. -

        Initialize track's label - attribute to "remote audio" or "remote - video" depending on the media type of the incoming - component.

        -
        5. - -
      5. -

        Initialize track's readyState - attribute to muted.

        -
        6. - -
      -

      4. - -

      The creation of new incoming - MediaStreamTracks may be triggered either by SDP - negotiation or by the receipt of media on a given flow. -

      - - -
    4. -

      If streams is an empty list, create a new - MediaStream object and add it to streams. -

      -
      5. - -
    5. -

      Add track to all MediaStream - objects in streams.

      -
      6. - -
    6. -

      Queue a task to run the following substeps:

      - -
        -
      1. -

        If the connection's RTCPeerConnection - signalingState is closed, abort these - steps.

        -
        2. - -
      2. -

        Create a new RTCRtpReceiver object - receiver for track, and add it - to connection's set of receivers.

        -
        3. - -
      3. -

        Fire an event named - track with - receiver, track, and streams - at the connection object.

        -
        4. -
      -
      7. -
    - -

    When an RTCPeerConnection finds that a track - from the remote peer has been removed, the user agent MUST follow these - steps:

    - -
      -
    1. -

      Let connection be the - RTCPeerConnection associated with the track - being removed.

      -
      2. - -
    2. -

      Let track be the MediaStreamTrack - object that represents the track being removed, if any. If - there isn't one, then abort these steps.

      -
      3. - -
    3. -

      By definition, track is now ended.

      - -

      A task is thus - queued to update - track and fire an event.

      -
      4. - -
    4. -

      Queue a task to run the following substeps:

      - -
        -
      1. -

        If the connection's RTCPeerConnection - signalingState is closed, abort these - steps.

        -
        2. - -
      2. -

        Remove the RTCRtpReceiver associated with track from - connection's set of receivers.

        -
        3. -
      -
      5. -
    -

    The task source for the tasks listed in this section is the networking task source.

    -

    If something in the browser changes that causes the - RTCPeerConnection object to need to initiate a new - session description negotiation, a negotiationneeded event is fired at the - RTCPeerConnection object.

    - -

    In particular, if a MediaStreamTrack object - is added to (using the - addTrack() method) or removed from (using the - removeTrack() - method) an RTCPeerConnection object, the - RTCPeerConnection object MUST fire the - "negotiationneeded" event.

    -

    To prevent network sniffing from allowing a fourth party to establish a connection to a peer using the information sent out-of-band to the other peer and thus spoofing the client, the @@ -1870,54 +1695,6 @@

    RTP Media API

    and each new MediaStreamTrack and its associated RTCRtpReceiver are surfaced to the application via the ontrack event.

    -
    -

    Since the beginning of this specification, remote MediaStreamTracks have been - created by the setRemoteDescription call, one track for each non-rejected - m-line in the remote description. This meant that at the caller, - MediaStreamTracks were not created until the answer was received, and any media - received prior to a remote description (AKA "early media") would be discarded. - If any form of remote description is provided (either an answer or a pranswer), - this issue does not occur.

    - -

    If we want to allow early media to be played out, minor changes are necessary. - Fundamentally, we would need to change when tracks are created - for the offerer; this would have to happen either as a result of setLocalDescription, - or when media packets are received. This ensures that these objects can be created and - connected to media elements for playout.

    - -

    However, there are three consequences to this potential change: -

      -
    1. Media may arrive before the remote DTLS fingerprint has been received. - This means that media could be played out before the validity of the - DTLS fingerprint has been established, which may be hard to explain to users. - As such, it is recommended that media not be played out unless some - TBD RTCConfiguration property (e.g. AllowUnverifiedMedia) has been set. -
      2. -
    2. The information needed to correlate MediaStreamTracks with their - enclosing MediaStream will not yet be present when the tracks are - initially generated. Therefore, the implementation will need to - create dummy MediaStream objects for each MediaStreamTrack, and then - possibly change the associated MediaStream for each track when the - remote description is received (e.g. if it indicates that an audio - and video MediaStreamTrack should be combined into a single MediaStream). - Since media elements act on MediaStreams, some complex reshuffling may - need to occur when the remote description is received. -
      3. -
    3. The track events fired and their timing will change. - For the offerer, ontrack will now fire during setLocalDescription, - once for each track being offered, and track.onended will fire during - setRemoteDescription for any offered tracks that were rejected. - For the answerer, ontrack will continue to fire during setRemoteDescription, - as it does today (this is necessary to allow the answerer to reject - offered tracks by stopping them). -
      4. -
    -

    - -

    For now, we simply make note of this issue, until it can be - considered fully by the WG.

    -
    -

    A RTCPeerConnection object contains a set of RTCRtpSenders, representing tracks to be sent, and a set of RTCRtpReceivers, @@ -2099,19 +1876,216 @@

    RTCPeerConnection Interface Extensions

    attribute EventHandler ontrack
    -
    This event handler, of event handler event type track, MUST be fired - by all objects implementing the RTCPeerConnection - interface. It is called any time a MediaStreamTrack is added - by the remote peer; currently, this will be fired only as a result of - a setRemoteDescription call, for any new tracks indicated in the - remote description. The ontrack event happens as early as - possible after the setRemoteDescription; any rejection of - new tracks can be done by the application after receiving the ontrack - event, by stopping the track.
    +
    +

    This event handler, of event handler event type track, MUST be fired + by all objects implementing the RTCPeerConnection + interface.

    +

    It is called any time a MediaStreamTrack is added + by the remote peer; the process for this is indicated below.

    +

    Rejection of incoming tracks can be done by the application after + receiving the ontrack event, by stopping the track.

    +
    +
    +

    Processing Remote MediaStreamTracks

    +

    The word "components" in this context refers to an RTP media flow + and does not have anything to do with how [[ICE]] uses the term + "component".

    + +

    When a user agent has reached the point where a + MediaStreamTrack can be created to represent an incoming + component, the user agent MUST run the following steps:

    + +
      +
    1. +

      Let connection be the + RTCPeerConnection expecting this media.

      +
      2. + +
    2. +

      Let streams be a list of + MediaStream objects that the sender indicated the + sent MediaStreamTrack being a part of. This + information needed to collect these objects is part of the remote + SDP.

      +
      3. + +
    3. +

      Run the following steps to create a track + representing the incoming component:

      + +
        +
      1. +

        Create a MediaStreamTrack object + track to represent the component.

        +
        2. + +
      2. +

        Initialize track's kind + attribute to "audio" or "video" + depending on the media type of the incoming component.

        +
        3. + +
      3. +

        Initialize track's id + attribute to the component track id.

        +
        4. + +
      4. +

        Initialize track's label + attribute to "remote audio" or "remote + video" depending on the media type of the incoming + component.

        +
        5. + +
      5. +

        Initialize track's readyState + attribute to muted.

        +
        6. + +
      +
      4. + +
    4. +

      If streams is an empty list, create a new + MediaStream object and add it to streams. +

      +
      5. +
    5. +

      Add track to all MediaStream + objects in streams.

      +
      6. + +
    6. +

      Queue a task to run the following substeps:

      + +
        +
      1. +

        If the connection's RTCPeerConnection + signalingState is closed, abort these + steps.

        +
        2. + +
      2. +

        Create a new RTCRtpReceiver object + receiver for track, and add it + to connection's set of receivers.

        +
        3. + +
      3. +

        Fire an event named + track with + receiver, track, and streams + at the connection object.

        +
        4. +
      +
      7. +
    + +

    When an RTCPeerConnection finds that a track + from the remote peer has been removed, the user agent MUST follow these + steps:

    + +
      +
    1. +

      Let connection be the + RTCPeerConnection associated with the track + being removed.

      +
      2. + +
    2. +

      Let track be the MediaStreamTrack + object that represents the track being removed, if any. If + there isn't one, then abort these steps.

      +
      3. + +
    3. +

      By definition, track is now ended.

      + +

      A task is thus + queued to update + track and fire an event.

      +
      4. + +
    4. +

      Queue a task to run the following substeps:

      + +
        +
      1. +

        If the connection's RTCPeerConnection + signalingState is closed, abort these + steps.

        +
        2. + +
      2. +

        Remove the RTCRtpReceiver associated with track from + connection's set of receivers.

        +
        3. +
      +
      5. +
    + +
    +

    Since the beginning of this specification, remote MediaStreamTracks have been + created by the setRemoteDescription call, one track for each non-rejected + m-line in the remote description. This meant that at the caller, + MediaStreamTracks were not created until the answer was received, and any media + received prior to a remote description (AKA "early media") would be discarded. + If any form of remote description is provided (either an answer or a pranswer), + this issue does not occur.

    + +

    If we want to allow early media to be played out, minor changes are necessary. + Fundamentally, we would need to change when tracks are created + for the offerer; this would have to happen either as a result of setLocalDescription, + or when media packets are received. This ensures that these objects can be created and + connected to media elements for playout.

    + +

    However, there are three consequences to this potential change: +

      +
    1. Media may arrive before the remote DTLS fingerprint has been received. + This means that media could be played out before the validity of the + DTLS fingerprint has been established, which may be hard to explain to users. + As such, it is recommended that media not be played out unless some + TBD RTCConfiguration property (e.g. AllowUnverifiedMedia) has been set. +
      2. +
    2. The information needed to correlate MediaStreamTracks with their + enclosing MediaStream will not yet be present when the tracks are + initially generated. Therefore, the implementation will need to + create dummy MediaStream objects for each MediaStreamTrack, and then + possibly change the associated MediaStream for each track when the + remote description is received (e.g. if it indicates that an audio + and video MediaStreamTrack should be combined into a single MediaStream). + Since media elements act on MediaStreams, some complex reshuffling may + need to occur when the remote description is received. +
      3. +
    3. The track events fired and their timing will change. + For the offerer, ontrack will now fire during setLocalDescription, + once for each track being offered, and track.onended will fire during + setRemoteDescription for any offered tracks that were rejected. + For the answerer, ontrack will continue to fire during setRemoteDescription, + as it does today (this is necessary to allow the answerer to reject + offered tracks by stopping them). +
      4. +
    +

    + +

    For now, we simply make note of this issue, until it can be + considered fully by the WG.

    +
    + +
    @@ -4958,7 +4932,8 @@

    Event summary

    RTCTrackEvent - A new RTCRtpReceiver, and associated MediaStreamTrack, has been added to the MediaStreamTrack has been created, and an associated + RTCRtpReceiver has been added to the set of receivers. @@ -5164,6 +5139,7 @@

    Change Log

    Changes since December 5, 2014

      +
    1. Add support for RTCRtpSender and RTCRtpReceiver.
    2. Update misleading local/RemoteDescription attribute text.
    @@ -5181,7 +5157,6 @@

    Changes since June 4, 2014

    -
  • Add support for RTCRtpSender and RTCRtpReceiver.
  • Bug 25724: Allow garbage collection of closed PeerConnections
    • From ceecbf2782b55f796613acd836d00f10864d8eb2 Mon Sep 17 00:00:00 2001 From: Justin Uberti Date: Fri, 30 Jan 2015 18:19:44 -0800 Subject: [PATCH 22/25] Fix ReSpec complaint regarding track --- webrtc.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/webrtc.html b/webrtc.html index 53cefd512..c75e3ee6a 100644 --- a/webrtc.html +++ b/webrtc.html @@ -2169,7 +2169,7 @@

    RTCTrackEvent

    The track attribute + "dom-trackevent-track">RTCTrackEvent.track attribute represents the MediaStreamTrack object that is associated with the RTCRtpReceiver identified by receiver.

    From a14fe06ceffba6d3bd09ed825cff24ba96a42509 Mon Sep 17 00:00:00 2001 From: Justin Uberti Date: Fri, 30 Jan 2015 18:44:04 -0800 Subject: [PATCH 23/25] Fix typos when rereading, and note ICE issues --- webrtc.html | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/webrtc.html b/webrtc.html index c75e3ee6a..e2e06666d 100644 --- a/webrtc.html +++ b/webrtc.html @@ -450,6 +450,15 @@

    Operation

    +
    +

    The section above shouldn't need to reference MediaStreamTracks when + discussing the ICE connection state; one problem with this is that + it doesn't handle the data channel situation properly. + Rewrite this to refer to m-lines or ICE "media streams" or some such + (here and in the later ICE connection state discussions.) +

    +
    +

    When the ICE Agent needs to notify the script about the candidate gathering progress, the user agent must queue a task to run the following steps:

    @@ -4120,7 +4129,7 @@

    Introduction

    side will be created (if not already present) and populated accordingly.

    As also described earlier in this document, the objects - RTCRTPSender and RTCRTPReceiver can be used by the + RTCRtpSender and RTCRtpReceiver can be used by the application to get more fine grained control over the transmission and reception of MediaStreamTracks.

    @@ -4169,7 +4178,7 @@

    id

    The id attribute specified in MediaStream returns an id that is unique to - this stream, so that streams can be recognized after they at the + this stream, so that streams can be recognized at the remote end of the RTCPeerConnection API.

    From d9857481963ca918c623c2ba5380e43f5e468a9b Mon Sep 17 00:00:00 2001 From: Justin Uberti Date: Sat, 31 Jan 2015 10:22:57 -0800 Subject: [PATCH 24/25] Add hidden files from master --- .nojekyll | 0 .travis.yml | 13 +++++++++++++ 2 files changed, 13 insertions(+) create mode 100644 .nojekyll create mode 100644 .travis.yml diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 000000000..e69de29bb diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 000000000..38136c9ed --- /dev/null +++ b/.travis.yml @@ -0,0 +1,13 @@ +language: python +install: + - git clone https://github.com/w3c/respec.git + - git clone https://github.com/dontcallmedom/webidl-checker.git + - git clone https://github.com/dontcallmedom/widlproc + - git clone https://github.com/halindrome/linkchecker.git + - cd widlproc && make obj/widlproc && cd .. + - pip install html5lib lxml +script: + - phantomjs --ignore-ssl-errors=true --ssl-protocol=tlsv1 respec/tools/respec2html.js -e -w webrtc.html output.html + - python webidl-checker/webidl-check output.html + - "! (perl -T linkchecker/bin/checklink -S 0 -q -b output.html |grep \"^\")" +env: WIDLPROC_PATH=$TRAVIS_BUILD_DIR/widlproc/obj/widlproc \ No newline at end of file From 089100a7cf23cce5763dc33cb94769d9ea61643c Mon Sep 17 00:00:00 2001 From: Adam Bergkvist Date: Mon, 2 Feb 2015 16:29:54 +0100 Subject: [PATCH 25/25] Use the correct event name --- webrtc.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/webrtc.html b/webrtc.html index 087097904..fa8ba304d 100644 --- a/webrtc.html +++ b/webrtc.html @@ -2413,7 +2413,7 @@

    RTCRtpReceiver Interface

    RTCTrackEvent

    -

    The ontrack +

    The track event uses the RTCTrackEvent interface.