Draft: draft-ietf-rtcweb-jsep

Commentary: EKR as editor 2 This should be a bunch of uncontroversial changes , which are mostly editorial , and if substantive are intended to enact what I think the authors intended . 
 I put in a handfull of comments . There is only two of them that I would like to resolve before put this in the spec ( both clearly identified ) . One is trivial about example projects and the other one about state created on subsceuent createOffers is a bit more complicated . The rest of the comments - do as you see fit and I 'm fine with ignoring them or not . 
 I just another commit . If you guys are happy , can you merge ?
Paragraph (version A):
Regarding ICE RFC5245, JSEP decouples the ICE state machine from the
overall signaling state machine, as the ICE state machine must remain
in the browser, because only the browser has the necessary knowledge
of candidates and other transport info.  Performing this separation
also provides additional flexibility; in protocols that decouple
session descriptions from transport, such as Jingle, the transport
information can be sent separately; in protocols that don't, such as
SIP, the information can be used in the aggregated form.  Sending
transport information separately can allow for faster ICE and DTLS
startup, since the necessary roundtrips can occur while waiting for
the remote side to accept the session.
Paragraph (version B):
Regarding ICE RFC5245, JSEP decouples the ICE state machine from the
overall signaling state machine, as the ICE state machine must remain
in the browser, because only the browser has the necessary knowledge
of candidates and other transport info.  Performing this separation
also provides additional flexibility; in protocols that decouple
session descriptions from transport, such as Jingle, the session
description can be sent immediately and the transport information can
be sent when available.  In protocols that don't, such as SIP, the
information can be used in the aggregated form.  Sending transport
information separately can allow for faster ICE and DTLS startup,
since ICE checks can start as soon as any transport information is
available rather than waiting for all of it.
Paragraph (version A):
One way to mitigate this is to provide a Javascript library that
hides this complexity from the developer; said library would
implement a given signaling protocol along with its state machine and
serialization code, presenting a higher level call-oriented interface
to the application developer.  For example, this library could easily
adapt the JSEP API into the API that was proposed for the ROAP
signaling protocol I-D.jennings-rtcweb-signaling, which would perform
a ROAP call setup under the covers, interacting with the application
only when it needs a signaling message to be sent.  In the same
fashion, one could also implement other popular signaling protocols,
including SIP or Jingle.  This allow JSEP to provide greater control
for the experienced developer without forcing any additional
complexity on the novice developer.
Paragraph (version B):
One way to mitigate this is to provide a Javascript library that
hides this complexity from the developer; said library would
implement a given signaling protocol along with its state machine and
serialization code, presenting a higher level call-oriented interface
to the application developer.  For example, libraries exist to adapt
the JSEP API into an API suitable for a SIP or XMPP.  Thus, JSEP
provides greater control for the experienced developer without
forcing any additional complexity on the novice developer.
Paragraph (version A):
Whether a session description applies to the local side or the remote
side affects the meaning of that description.  For example, the list
of codecs sent to a remote party indicates what the local side is
willing to receive, which, when intersected with the set of codecs
the remote side supports, specifies what the remote side should send.
However, not all parameters follow this rule; for example, the SRTP
parameters RFC4568 sent to a remote party indicate what the local
side will use to encrypt, and thereby what the remote party should
expect to receive; the remote party will have to accept these
parameters, with no option to choose a different value.
Paragraph (version A):
In addition, various RFCs put different conditions on the format of
offers versus answers.  For example, a offer may propose multiple
SRTP configurations, but an answer may only contain a single SRTP
configuration.
Paragraph (version A):
JSEP addresses this by adding both a setLocalDescription and a
setRemoteDescription method and having session description objects
contain a type field indicating the type of session description being
supplied.  This satisfies the requirements listed above for both the
offerer, who first calls setLocalDescription(sdp [offer]) and then
later setRemoteDescription(sdp [answer]), as well as for the
answerer, who first calls setRemoteDescription(sdp [offer]) and then
later setLocalDescription(sdp [answer]).
Paragraph (version B):
JSEP addresses this by adding both setLocalDescription and
setRemoteDescription methods and having session description objects
contain a type field indicating the type of session description being
supplied.  This satisfies the requirements listed above for both the
offerer, who first calls setLocalDescription(sdp [offer]) and then
later setRemoteDescription(sdp [answer]), as well as for the
answerer, who first calls setRemoteDescription(sdp [offer]) and then
later setLocalDescription(sdp [answer]).
Paragraph (version A):
Aside from these state transitions, there is no other difference
between the handling of provisional ("pranswer") and final ("answer")
answers.
Paragraph (version B):
Aside from these state transitions there is no other difference
between the handling of provisional ("pranswer") and final ("answer")
answers.
Paragraph (version A):
Note that most applications should be able to treat the
SessionDescriptions produced and consumed by these various API calls
as opaque blobs; that is, the application will not need to read or
change them.  The W3C API will provide appropriate APIs to allow the
application to control various session parameters, which will provide
the necessary information to the browser about what sort of
SessionDescription to produce.
Paragraph (version B):
Note that most applications should be able to treat the
SessionDescriptions produced and consumed by these various API calls
as opaque blobs; that is, the application will not need to read or
change them.  The W3C WebRTC API specification will provide
appropriate APIs to allow the application to control various session
parameters, which will provide the necessary information to the
browser about what sort of SessionDescription to produce.
Paragraph (version A):
Candidate trickling is a technique through which a caller may
incrementally provide candidates to the callee after the initial
offer has been dispatched; the semantics of "Trickle ICE" are defined
in I-D.ietf-mmusic-trickle-ice.  This process allows the callee to
begin acting upon the call and setting up the ICE (and perhaps DTLS)
connections immediately, without having to wait for the caller to
gather all possible candidates.  This results in faster call startup
in cases where gathering is not performed prior to initiating the
call.
Paragraph (version B):
Candidate trickling is a technique through which a caller may
incrementally provide candidates to the callee after the initial
offer has been dispatched; the semantics of "Trickle ICE" are defined
in I-D.ietf-mmusic-trickle-ice.  This process allows the callee to
begin acting upon the call and setting up the ICE (and perhaps DTLS)
connections immediately, without having to wait for the caller to
gather all possible candidates.  This results in faster media setup
in cases where gathering is not performed prior to initiating the
call.
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 to gather candidates
for.  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 can
start by checking if any candidates are available in the pool.  If
there are candidates in the pool, they can be handed to the
application immediately via the aforementioned candidate callback.
If the pool becomes depleted, either because a larger than expected
number of candidates is needed, 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 to gather candidates
for.  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
candidates is needed, or because the pool has not had enough time to
gather candidates, the remaining candidates are gathered as usual.
Paragraph (version A):
The PeerConnection constructor allows the application to specify
global parameters for the media session, such as the STUN/TURN
servers and credentials to use when gathering candidates.  The size
of the ICE candidate pool can also be set, if desired; by default the
candidate pool size is zero.
Paragraph (version A):
"default": The application will BUNDLE all media streams of the
same type together.  That is, if there are multiple audio and
multiple video MediaStreamTracks attached to a PeerConnection, all
but the first audio and video tracks will be marked as bundle-
only, and candidates will only be gathered for N media streams,
where N is the number of distinct media types.  When talking to a
non-BUNDLE-aware endpoint, only the non-bundle-only streams will
be negotiated.  This policy balances desire to multiplex with the
need to ensure basic audio and video still works in legacy cases.
Paragraph (version A):
"max-bundle": The application will BUNDLE all of its media streams
on a single transport.  All streams other than the first will be
marked as bundle-only.  This policy aims to minimize candidate
gathering and maximize multiplexing, at the cost of less
compatibility with legacy endpoints.
Paragraph (version A):
"max-compat": The application will offer BUNDLE, but mark none of
its streams as bundle-only.  This policy will allow all streams to
be received by non-BUNDLE-aware endpoints, but require separate
candidates to be gathered for each media stream.
Paragraph (version B):
The application will BUNDLE all of its media streams on a single
transport.  All streams other than the first will be marked as
bundle-only.  This policy aims to minimize candidate gathering and
maximize multiplexing, at the cost of less compatibility with
legacy endpoints.
Paragraph (version B):
The application will offer BUNDLE, but mark none of its streams as
bundle-only.  This policy will allow all streams to be received by
non-BUNDLE-aware endpoints, but require separate candidates to be
gathered for each media stream.
Paragraph (version A):
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 offer.  Like
createOffer, the returned blob contains descriptions of the local
MediaStreams attached to this PeerConnection, the codec/RTP/RTCP
options negotiated for this session, and any candidates that have
been gathered by the ICE Agent.  A constraints parameter may be
supplied to provide additional control over the generated answer.
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 offer.  Like
createOffer, the returned blob contains descriptions of the local
MediaStreams attached 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 B):
"rollback" is a special session description type implying that the
state machine should be rolled back to the previous state, as
described in sec.rollback.  The contents MUST be empty.
Paragraph (version A):
TODO: Do we need to expose accessors for both the current and
proposed local description?
Paragraph (version A):
TODO: Do we need to expose accessors for both the current and
proposed remote description?
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.)  When generating m=
sections, the ordering is based on (1) the order in which the
MediaStreams were added to the PeerConnection, and (2) 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.
Paragraph (version A):
Each m= section, provided it is not being bundled into another m=
section, MUST generate a unique set of ICE credentials and gather its
own unique set of ICE candidates.  Otherwise, it MUST use the same
ICE credentials and candidates that were used in the m= section that
it is being bundled into.
Paragraph (version A):
For DTLS, all m= sections MUST use the certificate for the identity
that has been specified for the PeerConnection; as a result, they
MUST all have the same RFC4572fingerprint value.
Paragraph (version B):
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 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):
For DTLS, all m= sections MUST use the certificate for the identity
that has been specified for the PeerConnection; as a result, they
MUST all have the same RFC4572fingerprint value, or this value MUST
be a session-level attribute.
Paragraph (version B):
Note that these requirements are in some cases stricter than those of
SDP.  Implementations MUST be prepared to accept compliant SDP even
if it would not conform to the requirements for generating SDP in
this specification.
Paragraph (version A):
The createOffer method takes as a parameter a MediaConstraints
object.  Special processing is performed when generating a SDP
description if the following constraints are present.
Paragraph (version A):
If the "OfferToReceiveAudio" constraint 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 constraint 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):
The createOffer method takes as a parameter an RTCOfferOptions
object.  Special processing is performed when generating a SDP
description if the following constraints are present.
Paragraph (version B):
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 A):
If the "OfferToReceiveVideo" constraint 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 constraint 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 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 A):
If the "VoiceActivityDetection" constraint 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 A):
If the "IceRestart" constraint 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 constraint 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 "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 "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).