jiebi/ids-paragraph-commentary-corpus huggingface dataset:
Draft: draft-ietf-rtcweb-jsep

Commentary: as Justin points out , 3264 explicitly authorizes this . 
 i 'm a bit late but ... without this , the following sequence of events is always going to happen : createOffer setLocalDescription onicecandidate(null ) / icegatheringstatechange(complete ) Executing this snippet in  never shows a candidate . Is that the intended behaviour ? Also the ice gathering state stays " new " ? My confusion about this is probably related to ;-) 
 I guess if we need to allow empty SPDs ( no m - sections ) then ICE related events should fire right away as they know that nothing is going to happen any way . 
 I do n't see why any events need to fire , since ICE gathering never starts in the first place and there are no in that case . 
 I failed to find any text in webrtc - pc or JSEP which indicates that the createOffer ( ) call should fail if no RtpTransceiver or data channel has been to a PeerConnection . Webrtc - pc contains the following : But section does not seem to contain any wording indicating to treat the absence of any RtpTransceiver and DataChannel as such an failure . I think such a scenario should be treated as a failure , as I fail to see any value in generating an empty offer . 
 Good observation . Personally , I 'm inclined to allow this , unless it 's forbidden by 3264 - we would just generate the session - level values with no m= sections . 
 3264 indicates that this is OK : The offer will contain zero or more media streams ( each media stream is described by an " m= " line and its associated attributes ) . Zero media streams implies that the offerer wishes to communicate , but that the streams for the session will be at a later time through a modified offer . I think we should explicitly mention that this is allowed , but otherwise take no action .
Paragraph (version A):
The next step is to generate m= sections, as specified in RFC4566,
Section 5.14.  An m= section is generated for each RtpTransceiver
that has been added to the PeerConnection, excluding any stopped
RtpTransceivers.  This is done in the order the RtpTransceivers were
added to the PeerConnection.
Paragraph (version B):
The next step is to generate m= sections, as specified in RFC4566,
Section 5.14.  An m= section is generated for each RtpTransceiver
that has been added to the PeerConnection, excluding any stopped
RtpTransceivers; this is done in the order the RtpTransceivers were
added to the PeerConnection.  If there are no such RtpTransceivers,
no m= sections are generated; more can be added later, as discussed
in RFC3264, Section 5.
Draft: draft-ietf-rtcweb-jsep

Commentary: 3 talks about setting direction properties , but the values that can be set are n't called out ( and even then only by inference from a list in an example ) in section 4.2.5 . Should there be explicit pointers to the api doc here ? ( And in section 4.2.6 ? ) 
 Yes , I think a pointer to the API doc is what 's needed here . 
 The more I look at it , I think it is the SDP , not the API doc that effectively defines the allow values of the direction . 
 LGTM
Paragraph (version A):
The setDirection method sets the direction of a transceiver, which
affects the direction property of the associated m= section on future
calls to createOffer and createAnswer.
Paragraph (version B):
The setDirection method sets the direction of a transceiver, which
affects the direction property of the associated m= section on future
calls to createOffer and createAnswer.  The permitted values for
direction are "recvonly", "sendrecv", "sendonly", and "inactive",
mirroring the identically-named directional attributes defined in
RFC4566, Section 6.
Draft: draft-ietf-rtcweb-jsep

Commentary: PTAL 
 On page 69 , at " If the application attempt to transmit DTMF when using a media format that does not have a corresponding telephone - event format , this MUST result in an error " . This sentence is out - of - place . The section is about applying a remote description . If the document needs to retain the sentence , it belongs off in some " processing media " section . In particular , the current placement of text is confusing about what and when an error could be returned , and it could be misread to say that an error should be returned to the setRemoteDescription call . 
 I agree 
 Agreed ; I do n't really feel like we need to create a new " Sending DTMF " section , so my recommendation would be to adjust the text to something like For each specified " telephone - event " media format , enable DTMF transmission for all supported media formats with the same clockrate , as described in [ RFC4733 ] , Section 2.5.1.2 . If there are any supported media formats that do not have a corresponding telephone - event format , disable DTMF transmission for those formats . 
 LGTM
Paragraph (version A):
For each specified "telephone-event" media format, enable
DTMF transmission for all supported media formats with the
same clockrate, as described in RFC4733, Section 2.5.1.2.
If the application attempts to transmit DTMF when using a
media format that does not have a corresponding telephone-
event format, this MUST result in an error.
Paragraph (version B):
For each specified "telephone-event" media format, enable
DTMF transmission for all supported media formats with the
same clockrate, as described in RFC4733, Section 2.5.1.2.
If there are any supported media formats that do not have a
corresponding telephone-event format, disable DTMF
transmission for those formats.
Draft: draft-ietf-rtcweb-jsep

Commentary: But also clarify that this can be used to modify an offer OR answer , as long as it remains a legal  o / a. 
 The second paragraph of section 5.4 is confusing . A slight restructuring of the sentences would remove much of the potential confusion , I think . I suggest replacing the first sentence ( which is very complex ) with this : " After calling setLocalDescription , the application MAY modify the SDP to reduce the capabilities in the offer before sending it to the far side , as long as it remains a valid SDP offer and specifies a subset of what was in the original offer . Likewise , an application that has received an offer from a peer MAY modify the received SDP , subject to those same constraints , before calling setRemoteDescription . " 
 lgtm
Paragraph (version A):
Note that the application MAY modify the SDP to reduce the
capabilities in the offer it sends to the far side (post-
setLocalDescription) or the offer that it installs from the far side
(pre-setRemoteDescription), as long as it remains a valid SDP offer
and specifies a subset of what was in the original offer.  This is
safe because the answer is not permitted to expand capabilities, and
therefore will just respond to what is present in the offer.
Paragraph (version A):
The application SHOULD NOT modify the SDP in the answer it transmits,
as the answer contains the negotiated capabilities, and this can
cause the two sides to have different ideas about what exactly was
negotiated.
Paragraph (version B):
After calling setLocalDescription with an offer or answer, the
application MAY modify the SDP to reduce its capabilities before
sending it to the far side, as long as it follows the rules above
that define a valid JSEP offer or answer.  Likewise, an application
that has received an offer or answer from a peer MAY modify the
received SDP, subject to the same constraints, before calling
setRemoteDescription.
Draft: draft-ietf-rtcweb-jsep

Commentary: PTAL 
 The concept of a " pending local description " is used in sections 3.5.1 , 6 , and 4.1.7 but is n't really explained until much later in the document . Please provide forward references , or move a description of what a pending description is earlier in the document . 
 Yah , this does seem like it needs a fix . Probably something about this in S 3.2 . 
 The second paragraph of section 5.4 is confusing . A slight restructuring of the sentences would remove much of the potential confusion , I think . I suggest replacing the first sentence ( which is very complex ) with this : " After calling setLocalDescription , the application MAY modify the SDP to reduce the capabilities in the offer before sending it to the far side , as long as it remains a valid SDP offer and specifies a subset of what was in the original offer . Likewise , an application that has received an offer from a peer MAY modify the received SDP , subject to those same constraints , before calling setRemoteDescription . " 
 LGTMLG with nits
Paragraph (version B):
During the offer/answer exchange, the outstanding offer is considered
to be "pending" at the offerer and the answerer, as it may either be
accepted or rejected.  If this is a re-offer, each side will also
have "current" local and remote descriptions, which reflect the
result of the last offer/answer exchange.  Sections
sec.pendingLocalDescription, sec.pendingRemoteDescription,
sec.currentLocalDescription, and sec.currentRemoteDescription,
provide more detail on pending and current descriptions.
Draft: draft-ietf-rtcweb-jsep

Commentary: Odd edge : The description createAnswer ( in 4.1.7 ) leaves open the possibility that the application could call createAnswer twice ( back - to - back with no intervening calls to other APIs ) with different values in the options parameter . Is this ok ? If not , should there be language that says not to do that somewhere ? 
 This is explicitly OK , and the state machine makes it clear . 
 Not sure we need to say anything here , though , given the state machine . 
 I forgot to mark this invalid but I think it may be . 
 Discussed with team and plan is to amend the paras that talk about cO / cA not changing media state to also mention that they do n't change signaling state . 
 LGTM
Paragraph (version A):
Calling this method may do things such as generating new ICE
credentials, but does not result in candidate gathering, or cause
media to start or stop flowing.  Specifically, the offer is not
applied, and does not become the pending local description, until
setLocalDescription is called.
Paragraph (version B):
Calling this method may do things such as generating new ICE
credentials, but does not change the PeerConnection state, trigger
candidate gathering, or cause media to start or stop flowing.
Specifically, the offer is not applied, and does not become the
pending local description, until setLocalDescription is called.
Paragraph (version A):
Calling this method may do things such as generating new ICE
credentials, but does not trigger candidate gathering or cause a
media state change.  Specifically, the answer is not applied, and
does not become the current local description, until
setLocalDescription is called.
Paragraph (version B):
Calling this method may do things such as generating new ICE
credentials, but does not change the PeerConnection state, trigger
candidate gathering, or or cause a media state change.  Specifically,
the answer is not applied, and does not become the current local
description, until setLocalDescription is called.
Draft: draft-ietf-rtcweb-jsep

Commentary: Slightly more than minor maybe : The first paragraph of 5.1.2 has at least a reference error . UDP / TLS / RTP / SAVPF is not specified in RFC7850 . It 's in RFC5764 . Assuming that this is only a reference error , then the last sentence seems like a stray . It does n't seem to be in the right context ( " this advertisement " does n't cast back to the discussion of the two profiles above it , which are both UDP only ) . Please clarify the sentence , giving it the right context , or remove it . 
 This text is correct . The point is we are saying " advertise UDP but we can do TCP or UDP " . We can try to rewrite . 
 LGTM
Paragraph (version A):
For media m= sections, JSEP implementations MUST support the
"UDP/TLS/RTP/SAVPF" profile specified in RFC7850, and MUST indicate
this profile for each media m= line they produce in an offer.  For
data m= sections, implementations MUST support the "UDP/DTLS/SCTP"
profile and MUST indicate this profile for each data m= line they
produce in an offer.  Because ICE can select either UDP RFC5245 or
TCP RFC6544 transport depending on network conditions, this
advertisement is consistent with ICE eventually selecting either
either UDP or TCP.
Paragraph (version B):
For media m= sections, JSEP implementations MUST support the
"UDP/TLS/RTP/SAVPF" profile specified in RFC5764, and MUST indicate
this profile for each media m= line they produce in an offer.  For
data m= sections, implementations MUST support the "UDP/DTLS/SCTP"
profile and MUST indicate this profile for each data m= line they
produce in an offer.  Although these profiles are formally associated
with UDP, ICE can select either UDP RFC5245 or TCP RFC6544 transport
depending on network conditions, even when advertising a UDP profile.
Draft: draft-ietf-rtcweb-jsep

Commentary: PTAL at the reformulation I . 
 " LS " ( lipsync ) is first used at 4.1.2 , with no context for what it is . Please add a reference . 
 OK
Paragraph (version A):
The addTrack method adds a MediaStreamTrack to the PeerConnection,
using the MediaStream argument to associate the track with other
tracks in the same MediaStream, so that they can be added to the same
"LS" group when creating an offer or answer. addTrack attempts to
minimize the number of transceivers as follows: If the PeerConnection
is in the "have-remote-offer" state, the track will be attached to
the first compatible transceiver that was created by the most recent
call to setRemoteDescription() and does not have a local track.
Otherwise, a new transceiver will be created, as described in
sec.addTransceiver.
Paragraph (version B):
The addTrack method adds a MediaStreamTrack to the PeerConnection,
using the MediaStream argument to associate the track with other
tracks in the same MediaStream, so that they can be added to the same
"LS" group when creating an offer or answer, thus allowing these
tracks to be synchronized when played out, as described in RFC5888,
Section 7.  addTrack attempts to minimize the number of transceivers
as follows: If the PeerConnection is in the "have-remote-offer"
state, the track will be attached to the first compatible transceiver
that was created by the most recent call to setRemoteDescription()
and does not have a local track.  Otherwise, a new transceiver will
be created, as described in sec.addTransceiver.
Draft: draft-ietf-rtcweb-jsep

Commentary: Build error looks like travis bustage 
 PeerConnection is used first at the next to last paragraph of section 3 . Please add a reference at that point . 
 Yes . 
 Does  mean a ref to Section 4 , or a ref to the W3C doc ? We do have a ref to the W3C doc in Section 1 . 
 That is why I concluded to S 4 ( distinguishing between PC and RTCPC ) 
 LGTM
Paragraph (version A):
In the parallel forking case where the JavaScript application wishes
to simultaneously exchange media with multiple peers, the flow is
slightly more complex, but the JavaScript application can follow the
strategy that RFC3960 describes using UPDATE.  The UPDATE approach
allows the signaling to set up a separate media flow for each peer
that it wishes to exchange media with.  In JSEP, this offer used in
the UPDATE would be formed by simply creating a new PeerConnection
and making sure that the same local media streams have been added
into this new PeerConnection.  Then the new PeerConnection object
would produce a SDP offer that could be used by the signaling to
perform the UPDATE strategy discussed in RFC3960.
Paragraph (version B):
In the parallel forking case where the JavaScript application wishes
to simultaneously exchange media with multiple peers, the flow is
slightly more complex, but the JavaScript application can follow the
strategy that RFC3960 describes using UPDATE.  The UPDATE approach
allows the signaling to set up a separate media flow for each peer
that it wishes to exchange media with.  In JSEP, this offer used in
the UPDATE would be formed by simply creating a new PeerConnection
(see sec.peerconnection) and making sure that the same local media
streams have been added into this new PeerConnection.  Then the new
PeerConnection object would produce a SDP offer that could be used by
the signaling to perform the UPDATE strategy discussed in RFC3960.
Draft: draft-ietf-rtcweb-jsep

Commentary: In 4.1.7 ( create Answer ) why would calling setLocalDescription cause the answer to be a pending local description . I think it 's the full on local description at that point , not a pending one ? 
 Yes , this is an error in the text . 
 LGTM
Paragraph (version A):
Calling this method may do things such as generating new ICE
credentials, but does not trigger candidate gathering or cause a
media state change.  Specifically, the answer is not applied, and
does not become the pending local description, until
setLocalDescription is called.
Paragraph (version B):
Calling this method may do things such as generating new ICE
credentials, but does not trigger candidate gathering or cause a
media state change.  Specifically, the answer is not applied, and
does not become the current local description, until
setLocalDescription is called.
Draft: draft-ietf-rtcweb-jsep

Commentary: The last paragraph of 5.1 needs more context . Why woudn't you expect the re - offer to fail , given that you already know the peer is using the older profile strings ? It 's not clear from the email list and proceedings how the document ended up with this particular text . 
 Consensus on editor 's call is that this is correct .  is that a new offer would have failed in any case , so why complicate things . 
 LGTM
Paragraph (version A):
Note that re-offers by JSEP implementations MUST use the correct
profile strings even if the initial offer/answer exchange used an
(incorrect) older profile string.
Paragraph (version B):
Note that re-offers by JSEP implementations MUST use the correct
profile strings even if the initial offer/answer exchange used an
(incorrect) older profile string.  This simplifies JSEP behavior,
with minimal downside, as any remote endpoint that fails to handle
such a re-offer will also fail to handle a JSEP endpoint's initial
offer.
Draft: draft-ietf-rtcweb-jsep

Commentary: Second paragraph of 3.2 , last sentence : at " these parameters or reject them " - " these " and " them " have ambiguous antecedents . It 's not clear if you are trying to point to the parameters that do n't follow the earlier stated rule , or all parameters . The sentence is complex . Splitting it up and finding a way to avoid the need for the semicolon will likely make it easier to say what you mean . 
 I agree that this is messy . Editorial . 
 LGTMLG with comment
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
fingerprints RFC8122 sent to a remote party are calculated based on
the local certificate(s) offered; the remote party MUST either accept
these parameters or reject them altogether, with no option to choose
different values.
Paragraph (version B):
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; some parameters are
declarative and the remote side MUST either accept them or reject
them altogether.  An example of such a parameter is the DTLS
fingerprints RFC8122, which are calculated based on the local
certificate(s) offered, and are not subject to negotiation.
Draft: draft-ietf-rtcweb-jsep

Commentary: The first full bullet on page 18 has a sentence that starts " Note that when considering " . Please change that to simply " When considering " . As written , there is an implication that this is a consequence of something specified somewhere else . 
 Yes , this seems rihgt . 
 To help find it , the whole sentence is is Note that when considering a MediaStreamTrack that is producing rotated video , the unrotated resolution MUST be used for the checks . This is required regardless of whether the receiver supports performing receive - side rotation ( e.g. , through CVO [ TS26.114 ] ) , as it significantly simplifies the matching logic .
Paragraph (version A):
If there is an applicable "a=imageattr recv" attribute for the
encoding, the limits from the attribute are then compared to the
encoder resolution.  Only the specific limits mentioned below are
considered; any other values, such as picture aspect ratio, MUST
be ignored.  Note that when considering a MediaStreamTrack that is
producing rotated video, the unrotated resolution MUST be used for
the checks.  This is required regardless of whether the receiver
supports performing receive-side rotation (e.g., through CVO
TS26.114), as it significantly simplifies the matching logic.
Paragraph (version B):
If there is an applicable "a=imageattr recv" attribute for the
encoding, the limits from the attribute are then compared to the
encoder resolution.  Only the specific limits mentioned below are
considered; any other values, such as picture aspect ratio, MUST
be ignored.  When considering a MediaStreamTrack that is producing
rotated video, the unrotated resolution MUST be used for the
checks.  This is required regardless of whether the receiver
supports performing receive-side rotation (e.g., through CVO
TS26.114), as it significantly simplifies the matching logic.
Draft: draft-ietf-rtcweb-jsep

Commentary: Last paragraph on page 5 - first sentence : at " One way to mitigate this " - " this " has an unclear antecedent . Did you mean " One way to reduce the complexity of the application 's responsibilities " ? 
 Agreed . Editorial
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, 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 B):
One way to make life easier for the application 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.
Draft: draft-ietf-rtcweb-jsep

Commentary: Last paragraph of 3.5.2.1 - " all of these fields " is ambiguous . Please state precisely which fields you mean . 
 Yeah , OK .
Paragraph (version A):
When creating an IceCandidate object, JSEP implementations MUST
populate all of these fields.
Paragraph (version B):
When creating an IceCandidate object, JSEP implementations MUST
populate each of the candidate, ufrag, m= section index, and MID
fields.  Implementations MUST also be prepared to receive objects
with some fields missing, as mentioned above.