Draft: draft-ietf-rtcweb-jsep

Commentary: pointed out one nit but LGTM 
 The pool stuff probably needs more discussion than we have time for . Regarding the CN stuff , I wrote the full text that should go into this section , but it might just be best to do that in its own PR . So this LGTM modulo those two parts ; I would remove the example for the pool and leave the CN part as it currently is ( and open issues for those ) . 
 OK , so I just removed the pool section . Do you want me to also remove the rationale in the CN part ? 
 I 'm good with this as - is . I can send you a pull once this lands for the complete CN text . 
 let me have another read of it now
Paragraph (version A):
With these considerations in mind, this document describes the
Javascript Session Establishment Protocol (JSEP) that allows for full
control of the signaling state machine from Javascript.  This
mechanism effectively removes the browser almost completely from the
core signaling flow; the only interface needed is a way for the
application to pass in the local and remote session descriptions
negotiated by whatever signaling mechanism is used, and a way to
interact with the ICE state machine.
Paragraph (version B):
With these considerations in mind, this document describes the
Javascript Session Establishment Protocol (JSEP) that allows for full
control of the signaling state machine from Javascript.  JSEP removes
the browser almost entirely from the core signaling flow, which is
instead handled by the Javascript making use of two interfaces: (1)
passing in local and remote session descriptions and (2) interacting
with the ICE state machine.
Paragraph (version A):
JSEP applications typically inform the browser to begin ICE gathering
via the information supplied to setLocalDescription, as this is where
the app specifies the number of media streams for which to gather
candidates.  However, to accelerate cases where the browser knows the
number of media streams to use ahead of time, the application MAY ask
the browser to gather a pool of potential ICE candidates to help
ensure rapid media setup.  When setLocalDescription is eventually
called, and the browser goes to gather the needed ICE candidates, it
SHOULD start by checking if any candidates are available in the pool.
If there are candidates in the pool, they SHOULD be handed to the
application immediately via the ICE candidate callback.  If the pool
becomes depleted, either because a larger-than-expected number of
media streams is used, or because the pool has not had enough time to
gather candidates, the remaining candidates are gathered as usual.
Paragraph (version B):
JSEP applications typically inform the browser to begin ICE gathering
via the information supplied to setLocalDescription, as this is where
the app specifies the number of media streams for which to gather
candidates.  However, to accelerate cases where the application knows
the number of media streams to use ahead of time, it MAY ask the
browser to gather a pool of potential ICE candidates to help ensure
rapid media setup.  When setLocalDescription is eventually called,
and the browser goes to gather the needed ICE candidates, it SHOULD
start by checking if any candidates are available in the pool.  If
there are candidates in the pool, they SHOULD be handed to the
application immediately via the ICE candidate callback.  If the pool
becomes depleted, either because a larger-than-expected number of
media streams is used, or because the pool has not had enough time to
gather candidates, the remaining candidates are gathered as usual.
Paragraph (version A):
In the initial offer, the generated SDP will contain all desired
functionality for the session (certain parts that are supported but
not desired by default may be omitted); for each SDP line, the
generation of the SDP will follow the process defined for generating
an initial offer from the document that specifies the given SDP line.
The exact handling of initial offer generation is detailed in
sec.initial-offers below.
Paragraph (version B):
In the initial offer, the generated SDP will contain all desired
functionality for the session (functionality that is supported but
not desired by default may be omitted); for each SDP line, the
generation of the SDP will follow the process defined for generating
an initial offer from the document that specifies the given SDP line.
The exact handling of initial offer generation is detailed in
sec.initial-offers below.
Paragraph (version A):
In the event createOffer is called after the session is established,
createOffer will generate an offer to modify the current session
based on any changes that have been made to the session, e.g. adding
or removing MediaStreams, or requesting an ICE restart.  For each
existing stream, the generation of each SDP line must follow the
process defined for generating an updated offer from the document
that specifies the given SDP line.  For each new stream, the
generation of the SDP must follow the process of generating an
initial offer, as mentioned above.  If no changes have been made, or
for SDP lines that are unaffected by the requested changes, the offer
will only contain the parameters negotiated by the last offer-answer
exchange.  The exact handling of subsequent offer generation is
detailed in sec.subsequent-offers. below.
Paragraph (version B):
In the event createOffer is called after the session is established,
createOffer will generate an offer to modify the current session
based on any changes that have been made to the session, e.g. adding
or removing MediaStreams, or requesting an ICE restart.  For each
existing stream, the generation of each SDP line must follow the
process defined for generating an updated offer from the RFC that
specifies the given SDP line.  For each new stream, the generation of
the SDP must follow the process of generating an initial offer, as
mentioned above.  If no changes have been made, or for SDP lines that
are unaffected by the requested changes, the offer will only contain
the parameters negotiated by the last offer-answer exchange.  The
exact handling of subsequent offer generation is detailed in
sec.subsequent-offers. below.
Paragraph (version A):
ICE, as specified in RFC5245, MUST be used.  Note that the remote
endpoint MAY use a Lite implementation.
Paragraph (version B):
ICE, as specified in RFC5245, MUST be used.  Note that the remote
endpoint may use a Lite implementation; implementations MUST
properly handle remote endpoints which do ICE-Lite.
Paragraph (version A):
The third SDP line MUST be a "s=" line, as specified in RFC4566,
Section 5.3; to match the "o=" line, a single dash SHOULD be used
as the session name, e.g. "s=-".
Paragraph (version B):
The third SDP line MUST be a "s=" line, as specified in RFC4566,
Section 5.3; to match the "o=" line, a single dash SHOULD be used
as the session name, e.g. "s=-".  Note that this differs from the
advice in RFC4566 which proposes a single space, but as both "o="
and "s=" are meaningless, having the same meaningless value seems
clearer.
Paragraph (version A):
The next step is to generate m= sections for each MediaStreamTrack
that has been added to the PeerConnection via the addStream method.
(Note that this method takes a MediaStream, which can contain
multiple MediaStreamTracks, and therefore multiple m= sections can be
generated even if addStream is only called once.) m=sections MUST be
sorted first by the order in which the MediaStreams were added to the
PeerConnection, and then by the alphabetical ordering of the media
type for the MediaStreamTrack.  For example, if a MediaStream
containing both an audio and a video MediaStreamTrack is added to a
PeerConnection, the resultant m=audio section will precede the
m=video section.  If a second MediaStream containing an audio
MediaStreamTrack was added, it would follow the m=video section.
Paragraph (version B):
The next step is to generate m= sections, as specified in RFC4566
Section 5.14, for each MediaStreamTrack that has been added to the
PeerConnection via the addStream method.  (Note that this method
takes a MediaStream, which can contain multiple MediaStreamTracks,
and therefore multiple m= sections can be generated even if addStream
is only called once.) m=sections MUST be sorted first by the order in
which the MediaStreams were added to the PeerConnection, and then by
the alphabetical ordering of the media type for the MediaStreamTrack.
For example, if a MediaStream containing both an audio and a video
MediaStreamTrack is added to a PeerConnection, the resultant m=audio
section will precede the m=video section.  If a second MediaStream
containing an audio MediaStreamTrack was added, it would follow the
m=video section.
Paragraph (version A):
If the "OfferToReceiveAudio" option is specified, with a value of
"N", the offer MUST include N non-rejected m= sections with media
type "audio", even if fewer than N audio MediaStreamTracks have been
added to the PeerConnection.  This allows the offerer to receive
audio, including multiple independent streams, even when not sending
it; accordingly, the directional attribute on the audio m= sections
without associated MediaStreamTracks MUST be set to recvonly.  If
this option is specified in the case where at least N audio
MediaStreamTracks have already been added to the PeerConnection, or N
non-rejected m= sections with media type "audio" would otherwise be
generated, it has no effect.  For backwards compatibility, a value of
"true" is interpreted as equivalent to N=1.
Paragraph (version B):
If the "OfferToReceiveAudio" option is specified, with an integer
value of N, the offer MUST include N non-rejected m= sections with
media type "audio", even if fewer than N audio MediaStreamTracks have
been added to the PeerConnection.  This allows the offerer to receive
audio, including multiple independent streams, even when not sending
it; accordingly, the directional attribute on the audio m= sections
without associated MediaStreamTracks MUST be set to recvonly.  If
this option is specified in the case where at least N audio
MediaStreamTracks have already been added to the PeerConnection, or N
non-rejected m= sections with media type "audio" would otherwise be
generated, it has no effect.  For backwards compatibility, a value of
"true" is interpreted as equivalent to N=1.
Paragraph (version A):
If the "OfferToReceiveVideo" option is specified, with a value of
"N", the offer MUST include N non-rejected m= sections with media
type "video", even if fewer than N video MediaStreamTracks have been
added to the PeerConnection.  This allows the offerer to receive
video, including multiple independent streams, even when not sending
it; accordingly, the directional attribute on the video m= sections
without associated MediaStreamTracks MUST be set to recvonly.  If
this option is specified in the case where at least N video
MediaStreamTracks have already been added to the PeerConnection, or N
non-rejected m= sections with media type "video" would otherwise be
generated, it has no effect.  For backwards compatibility, a value of
"true" is interpreted as equivalent to N=1.
Paragraph (version B):
If the "OfferToReceiveVideo" option is specified, with an integer
value of N, the offer MUST include N non-rejected m= sections with
media type "video", even if fewer than N video MediaStreamTracks have
been added to the PeerConnection.  This allows the offerer to receive
video, including multiple independent streams, even when not sending
it; accordingly, the directional attribute on the video m= sections
without associated MediaStreamTracks MUST be set to recvonly.  If
this option is specified in the case where at least N video
MediaStreamTracks have already been added to the PeerConnection, or N
non-rejected m= sections with media type "video" would otherwise be
generated, it has no effect.  For backwards compatibility, a value of
"true" is interpreted as equivalent to N=1.
Paragraph (version A):
If the "VoiceActivityDetection" option is specified, with a value of
"true", the offer MUST indicate support for silence suppression by
including comfort noise ("CN") codecs for each supported clock rate,
as specified in RFC3389, Section 5.1.
Paragraph (version B):
If the "VoiceActivityDetection" option is specified, with a value of
"true", the offer MUST indicate support for silence suppression in
the audio it receives by including comfort noise ("CN") codecs for
each supported clock rate, as specified in RFC3389, Section 5.1.
This option allows for significant bandwidth reductions with codecs
such as G.711.
Paragraph (version A):
If the "IceRestart" option is specified, with a value of "true", the
offer MUST indicate an ICE restart by generating new ICE ufrag and
pwd attributes, as specified in RFC5245, Section 9.1.1.1.  If this
option is specified on an initial offer, it has no effect (since a
new ICE ufrag and pwd are already generated).
Paragraph (version B):
If the "IceRestart" option is specified, with a value of "true", the
offer MUST indicate an ICE restart by generating new ICE ufrag and
pwd attributes, as specified in RFC5245, Section 9.1.1.1.  If this
option is specified on an initial offer, it has no effect (since a
new ICE ufrag and pwd are already generated).  This option is useful
for reestablishing connectivity in cases where failures are detected.
Paragraph (version A):
For each offered m= section of a given media type, if there is a
local MediaStreamTrack of the specified type which has been added to
the PeerConnection via addStream and not yet associated with a m=
section, and the specific m= section is either sendrecv or recvonly,
the MediaStreamTrack is associated with the m= section at this time.
MediaStreamTracks are assigned to m= sections using the canonical
order described in sec.initial-offers.  If there are more m= sections
of a certain type than MediaStreamTracks, some m= sections will not
have an associated MediaStreamTrack.  If there are more
MediaStreamTracks of a certain type than compatible m= sections, only
the first N MediaStreamTracks will be able to be associated in the
constructed answer.  The remainder will need to be associated in a
subsequent offer.
Paragraph (version B):
The next step is to go through each offered m= section.  If there is
a local MediaStreamTrack of the same type which has been added to the
PeerConnection via addStream and not yet associated with a m=
section, and the specific m= section is either sendrecv or recvonly,
the MediaStreamTrack will be associated with the m= section at this
time.  MediaStreamTracks are assigned to m= sections using the
canonical order described in sec.initial-offers.  If there are more
m= sections of a certain type than MediaStreamTracks, some m=
sections will not have an associated MediaStreamTrack.  If there are
more MediaStreamTracks of a certain type than compatible m= sections,
only the first N MediaStreamTracks will be able to be associated in
the constructed answer.  The remainder will need to be associated in
a subsequent offer.