Draft: draft-ietf-rtcweb-jsep

Commentary: this is a reworked version of your original text . PTAL and let me know what you think . 
 Cullen PTAL 
 LGTM
Paragraph (version B):
RtpTransceivers allow the application to control the RTP media
associated with one m= section.  Each RtpTransceiver has an RtpSender
and an RtpReceiver, which an application can use to control the
sending and receiving of RTP media.  The application may also modify
the RtpTransceiver directly, for instance, by stopping it.
Paragraph (version B):
When a new gathering phase starts, the ICE Agent will notify the
application that gathering is occurring through an event.  Then, when
each new ICE candidate becomes available, the ICE Agent will supply
it to the application via an additional event; these candidates will
also automatically be added to the current and/or pending local
session description.  Finally, when all candidates have been
gathered, an event will be dispatched to signal that the gathering
process is complete.
Paragraph (version A):
Typically, when gathering ICE candidates, the browser will gather all
possible forms of initial candidates - host, server reflexive, and
relay.  However, in certain cases, applications may want to have more
specific control over the gathering process, due to privacy or
related concerns.  For example, one may want to suppress the use of
host candidates, to avoid exposing information about the local
network, or go as far as only using relay candidates, to leak as
little location information as possible (note that these choices come
with corresponding operational costs).  To accomplish this, the
browser MUST allow the application to restrict which ICE candidates
are used in a session.  In addition, administrators may also wish to
control the set of ICE candidates, and so the browser SHOULD also
allow control via local policy, with the most restrictive policy
prevailing.
Paragraph (version B):
The rules here express a single set of preferences, and therefore,
the "a=imageattr" q= value is not important.  It SHOULD be set to
1.0.
Paragraph (version B):
RFC6236 defines "a=imageattr" to be an advisory field.  This means
that it does not absolutely constrain the video formats that the
sender can use, but gives an indication of the preferred values.
Paragraph (version B):
In the special case of receiving a maximum resolution of [0, 0], as
described above, the sender MUST NOT transmit the track.
Paragraph (version B):
Applications request support for simulcast by configuring multiple
encodings on an RtpSender, which, upon generation of an offer or
answer, are indicated in SDP markings on the corresponding m=
section, as described below.  Receivers that understand simulcast and
are willing to receive it will also include SDP markings to indicate
their support, and JSEP endpoints will use these markings to
determine whether simulcast is permitted for a given RtpSender.  If
simulcast support is not negotiated, the RtpSender will only use the
first configured encoding.
Paragraph (version B):
In addition, JSEP does not provide a mechanism to handle an incoming
offer requesting simulcast from the JSEP endpoint.  This means that
established simulcast streams will continue to work through a
received re-offer, but setting up initial simulcast by way of a
received offer requires out-of-band signaling or SDP inspection.
Future versions of this specification may add additional APIs to
provide direct control.
Paragraph (version A):
In a "last-one-wins" situation, all answers would be applied as
provisional answers, and any previous call leg will be terminated.
At some point, the application will end the setup process, perhaps
with a timer; at this point, the application could reapply the
existing remote description as a final answer.
Paragraph (version B):
In a "last-one-wins" situation, all answers would be applied as
provisional answers, and any previous call leg will be terminated.
At some point, the application will end the setup process, perhaps
with a timer; at this point, the application could reapply the
pending remote description as a final answer.
Paragraph (version A):
To trigger an ICE restart, for the purpose of reestablishing
connectivity.
Paragraph (version B):
The default multiplexing policy MUST be set to "require".
Implementations MAY choose to reject attempts by the application to
set the multiplexing policy to "negotiate".
Paragraph (version B):
The addTransceiver method adds a new RtpTransceiver to the
PeerConnection.  If a MediaStreamTrack argument is provided, then the
transceiver will be configured with that media type and the track
will be attached to the transceiver.  Otherwise, the application MUST
explicitly specify the type; this mode is useful for creating
recvonly transceivers as well as for creating transceivers to which a
track can be attached at some later point.
Paragraph (version B):
The createOffer method generates a blob of SDP that contains a
RFC3264 offer with the supported configurations for the session,
including descriptions of the media added to this PeerConnection, the
codec/RTP/RTCP options supported by this implementation, and any
candidates that have been gathered by the ICE Agent.  An options
parameter may be supplied to provide additional control over the
generated offer.  This options parameter allows an application to
trigger an ICE restart, for the purpose of reestablishing
connectivity.
Paragraph (version B):
The createAnswer method generates a blob of SDP that contains a
RFC3264 SDP answer with the supported configuration for the session
that is compatible with the parameters supplied in the most recent
call to setRemoteDescription, which MUST have been called prior to
calling createAnswer.  Like createOffer, the returned blob contains
descriptions of the media added to this PeerConnection, the
codec/RTP/RTCP options negotiated for this session, and any
candidates that have been gathered by the ICE Agent.  An options
parameter may be supplied to provide additional control over the
generated answer.
Paragraph (version A):
This API changes the local media state; among other things, it sets
up local resources for receiving and decoding media.  In order to
successfully handle scenarios where the application wants to offer to
change from one media format to a different, incompatible format, the
PeerConnection must be able to simultaneously support use of both the
old and new local descriptions (e.g. support codecs that exist in
both descriptions) until a final answer is received, at which point
the PeerConnection can fully adopt the new local description, or roll
back to the old description if the remote side denied the change.
Paragraph (version A):
If setRemoteDescription was previous called with an offer, and
setLocalDescription is called with an answer (provisional or final),
and the media directions are compatible, and media are available to
send, this will result in the starting of media transmission.
Paragraph (version A):
The localDescription method returns a copy of the current local
configuration, i.e. what was most recently passed to
setLocalDescription, plus any local candidates that have been
generated by the ICE Agent.
Paragraph (version A):
The remoteDescription method returns a copy of the current remote
configuration, i.e. what was most recently passed to
setRemoteDescription, plus any remote candidates that have been
supplied via processIceMessage.
Paragraph (version B):
The pendingLocalDescription method returns a copy of the local
description currently in negotiation - i.e., a local offer set
without any corresponding remote answer - in addition to any local
candidates that have been generated by the ICE Agent since the local
description was set.
Paragraph (version B):
A null object will be returned if the state of the PeerConnection is
"stable" or "have-remote-offer".
Paragraph (version B):
A null object will be returned if the state of the PeerConnection is
"stable" or "have-local-offer".
Paragraph (version A):
The addIceCandidate method provides a remote candidate to the ICE
Agent, which, if parsed successfully, will be added to the remote
description according to the rules defined for Trickle ICE.
Connectivity checks will be sent to the new candidate.
Paragraph (version B):
Because DTLS-SRTP is REQUIRED, the choice of SAVP or AVP has no
effect; support for DTLS-SRTP is determined by the presence of one
or more "a=fingerprint" attribute.  Note that lack of an
"a=fingerprint" attribute will lead to negotiation failure.
Paragraph (version A):
An "a=ice-options" line, with the "trickle" option, as specified
in I-D.ietf-mmusic-trickle-ice, Section 4.
Paragraph (version A):
Once all m= sections have been generated, a session-level "a=group"
attribute MUST be added as specified in RFC5888.  This attribute MUST
have semantics "BUNDLE", and MUST include the mid identifiers of each
m= section.  The effect of this is that the browser offers all m=
sections as one BUNDLE group.  However, whether the m= sections are
bundle-only or not depends on the BUNDLE policy.
Paragraph (version B):
An "a=rtcp" line, as specified in RFC3605, Section 2.1, containing
the dummy value "9 IN IP4 0.0.0.0", because no candidates have yet
been gathered.
Paragraph (version B):
Each "a=ice-ufrag" and "a=ice-pwd" line MUST stay the same, unless
the ICE configuration has changed (either changes to the supported
STUN/TURN servers, or the ICE candidate policy), or the
"IceRestart" option ( sec.icerestart was specified.  If the m=
section is bundled into another m= section, it still MUST NOT
contain any ICE credentials.
Paragraph (version B):
For RtpTransceivers that are still present, any "a=simulcast" line
MUST stay the same.
Paragraph (version A):
If present in the offer, an "a=mid" line, as specified in RFC5888,
Section 9.1.  The "mid" value MUST match that specified in the
offer.
Paragraph (version B):
If and only if present in the offer, an "a=mid" line, as specified
in RFC5888, Section 9.1.  The "mid" value MUST match that
specified in the offer.
Paragraph (version A):
If a local MediaStreamTrack has been associated, an "a=ssrc" line,
as specified in RFC5576, Section 4.1, indicating the SSRC to be
used for sending media.
Paragraph (version A):
If a local MediaStreamTrack has been associated, and RTX has been
negotiated for this m= section, another "a=ssrc" line with the RTX
SSRC, and an "a=ssrc-group" line, as specified in RFC5576, section
4.2, with semantics set to "FID" and including the primary and RTX
SSRCs.
Paragraph (version B):
If present in the offer, an "a=rtcp-mux" line, as specified in
RFC5761, Section 5.1.3.  Otherwise, an "a=rtcp" line, as specified
in RFC3605, Section 2.1, containing the dummy value "9 IN IP4
0.0.0.0" (because no candidates have yet been gathered).
Paragraph (version B):
The "c=" line MUST be checked for syntax but its value is not
used.  This supersedes the guidance in RFC5245, Section 6.1, to
use "ice-mismatch" to indicate mismatches between "c=" and the
candidate lines; because JSEP always uses ICE, "ice-mismatch" is
not useful in this context.
Paragraph (version B):
The "b=" line, if present, MUST be parsed as specified in RFC4566,
Section 5.8, and the bwtype and bandwidth values stored.
Paragraph (version A):
The "c=" line, if present, MUST be parsed as specified in RFC4566,
Section 5.7, and its contents stored.
Paragraph (version B):
As with the "c=" line at the session level, the "c=" line MUST be
parsed according to RFC4566, Section 5.7, but its value is not
used.
Paragraph (version B):
Any "a=rid" lines MUST be parsed as specified in I-D.ietf-mmusic-
rid, Section 10, and their values stored.
Paragraph (version B):
If present, a single "a=simulcast" line MUST be parsed as
specified in I-D.ietf-mmusic-sdp-simulcast, and its values stored.
Paragraph (version A):
The session description must follow the rules defined in RFC3264,
Section 6.
Paragraph (version A):
For each m= section, the protocol value MUST exactly match the
protocol value in the corresponding m= section in the associated
offer.
Paragraph (version B):
DTLS fingerprint values, where at least one fingerprint MUST be
present.
Paragraph (version B):
All RID values referenced in an "a=simulcast" line MUST exist as
"a=rid" lines.
Paragraph (version B):
The session description must follow the rules defined in RFC3264,
Section 6, including the requirement that the number of m=
sections MUST exactly match the number of m= sections in the
associated offer.
Paragraph (version B):
For each m= section, the media type and protocol values MUST
exactly match the media type and protocol values in the
corresponding m= section in the associated offer.
Paragraph (version B):
If the directional attribute is of type "sendrecv" or
"recvonly", enable receipt and decoding of media.
Paragraph (version B):
Configure the ICE components associated with this media section to
use the supplied ICE remote ufrag and password for their
connectivity checks.
Paragraph (version B):
Pair any supplied ICE candidates with any gathered local
candidates, as described in Section 5.7 of RFC5245 and start
connectivity checks with the appropriate credentials.
Paragraph (version B):
If the m= section is sendrecv or recvonly, and there are
RtpTransceivers of the same type that were added to the
PeerConnection by addTrack and are not associated with any
m= section and are not stopped, find the first (according to
the canonical order described in sec.initial-offers) such
RtpTransceiver.
Paragraph (version B):
In addition to the steps mentioned above for processing a local or
remote description, the following steps are performed when processing
a description of type "pranswer" or "answer".
Paragraph (version B):
If no valid DTLS connection exists, prepare to start a DTLS
connection, using the specified roles and fingerprints, on any
underlying ICE components, once they are active.
Paragraph (version B):
The payload type mapping from the remote description is used to
determine payload types for the outgoing RTP streams, including
the payload type for the send media format chosen above.  Any
RTP header extensions that were negotiated should be included
in the outgoing RTP streams, using the extension mapping from
the remote description; if the RID header extension has been
negotiated, and RID values are specified, include the RID
header extension in the outgoing RTP streams, as indicated in
I-D.ietf-mmusic-rid, Section 4.
Paragraph (version B):
If simulcast has been negotiated, send the number of Source RTP
Streams as specified in I-D.ietf-mmusic-sdp-simulcast,
Section 6.2.2.
Paragraph (version B):
If the send media format chosen above has a corresponding "rtx"
media format, or a FEC mechanism has been negotiated, establish
a Redundancy RTP Stream with a random SSRC for each Source RTP
Stream, and start or continue transmitting RTX/FEC packets as
needed.
Paragraph (version B):
If the send media format chosen above has a corresponding "red"
media format of the same clockrate, allow redundant encoding
using the specified format for resiliency purposes, as
discussed in I-D.ietf-rtcweb-fec, Section 3.2.  Note that
unlike RTX or FEC media formats, the "red" format is
transmitted on the Source RTP Stream, not the Redundancy RTP
Stream.
Paragraph (version B):
If the answer contains valid bundle groups, discard any ICE
components for the m= sections that will be bundled onto the primary
ICE components in each bundle, and begin muxing these m= sections
accordingly, as described in I-D.ietf-mmusic-sdp-bundle-negotiation,
Section 8.2.
Paragraph (version B):
This example demonstrates the early warmup technique described in
sec.use-of-provisional-answer.  Here, Alice's endpoint sends an offer
to Bob's endpoint to start an audio/video call.  Bob immediately
responds with an answer that accepts the audio/video m= sections, but
marks them as sendonly (from its perspective), meaning that Alice
will not yet send media.  This allows the JSEP implementation to
start negotiating ICE and DTLS immediately.  Bob's endpoint then
prompts him to answer the call, and when he does, his endpoint sends
a second offer which enables the audio and video m= sections, and
thereby bidirectional media transmission.  The advantage of such a
flow is that as soon as the first answer is received, the
implementation can proceed with ICE and DTLS negotiation and
establish the session transport.  If the transport setup completes
before the second offer is sent, then media can be transmitted
immediately by the callee immediately upon answering the call,
minimizing perceived post-dial-delay.  The second offer/answer
exchange can also change the preferred codecs or other information.