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

Commentary: revised 
 Fixed by 
 Maybe in create - answer as well 
 The " Initial Offers " section does not distinguish systematically between requirements that apply for any type of offer and the ones that apply only to mediastreams . For instance : I think this should apply both to mediastreamtrack and to datachannels . Then many of the rules described under " Each m= section MUST include the following attribute lines : " seem specific to mediastreams , but not all ; and that set of rules is then followed by a statement that a m= section must be created for data channels . This could use some reorganization and clarification . 
 Agree this could be refactored a bit . Magnus had a similar comment in the past . 
 Suggest contact with Magnus or Jessep for potential language . 
 I think this is mostly editorial and as such probably needs to be resolved within the author team . 
 Can this be considered fixed now ? The createOffer section has since been structured into " here 's what you generate for each RtpTransceiver " , " here 's what you generate if there 's a data channel " . And the data channel requirements look complete to me : 
 I agree with shall we close this ? 
 I think the concern was that the data channel paragraphs feel a bit like an afterthought . I think this could be improved , but I do n't think the current situation is dire . 
 I can live with the current text as is . Done is a feature and I do n't think this will cause any interoperability problems . 
 This text has been improved as of PR . If we can and this text still reads well , I think we can close this issue . 
 Pending resolution of 
 is it 's own bug . I think we an just close this and any changes needed can be dealt with by 
 I want to take one last editorial pass over the text once lands . This is a purely editorial issue at this point .
Paragraph (version A):
Within the data m= section, the "a=mid", "a=ice-ufrag", "a=ice-pwd",
"a=fingerprint", "a=dtls-id", and "a=setup" lines MUST be included as
mentioned above, along with an "a=fmtp:webrtc-datachannel" line and
an "a=sctp-port" line referencing the SCTP port number as defined in
I-D.ietf-mmusic-sctp-sdp, Section 4.1.
Paragraph (version B):
As discussed above, the following attributes are included only if the
m= section either has a unique address or is associated with the
bundle-tag: "a=ice-ufrag", "a=ice-pwd", "a=fingerprint", "a=dtls-id",
and "a=setup".
Paragraph (version A):
Within the data m= section, the "a=mid", "a=ice-ufrag", "a=ice-pwd",
"a=candidate", "a=fingerprint", "a=dtls-id", and "a=setup" lines MUST
be included under the conditions described above, along with an
"a=fmtp:webrtc-datachannel" line and an "a=sctp-port" line
referencing the SCTP port number as defined in I-D.ietf-mmusic-sctp-
sdp, Section 4.1.
Paragraph (version B):
As discussed above, the following attributes are included only if the
m= section is not bundled into another m= section: "a=ice-ufrag",
"a=ice-pwd", "a=fingerprint", "a=dtls-id", and "a=setup".
Draft: draft-ietf-rtcweb-jsep

Commentary: It 's a transport attribute , so it should come at the end , like other transport attribs 
 just checking ... this is just a style thing right ? the code would accept SDP with these in any order ? 
 Of course . This is just how we order things in Section 5 . 
 For createoffer , createanswer ordering of attribs 
 So SDP has no requirement on the ordering of the a= lines . I do n't see how a parser , even a JSEP one can expect to get the a= lines in any specific order . I fear that even a " it is recommended to generate them in this order " will be misinterpreted . I think this is one of SDPs warts that you will have to live with . 
 Right , there is n't any need to mandate an order , I just think that in the text for generating an offer , the places that talk about adding a = rtpmap should be adjacent . This should be a fairly trivial editorial change .
Paragraph (version A):
For RtpTransceivers that are not stopped, the "a=msid" line MUST
stay the same if they are present in the current description.
Paragraph (version B):
For RtpTransceivers that are not stopped, the "a=msid" lines MUST
stay the same if they are present in the current description.
Draft: draft-ietf-rtcweb-jsep

Commentary: Originally raised by Christer Section 3.2 says : " the DTLS - SRTP parameters [ RFC5763 ] sent to a remote party indicate what certificate the local side will use in DTLS setup " 1 ) I am not sure what " parameters " the text is referring to . If it¹s the fingerprint , I think the text should reference RFC 4572 . 2 ) I think we should simply have a generic statement that , following the rules in RFC3264 , parameters indicate receiving capabilities - unless explicitly indicated otherwise . 
 The parameters include a = setup and a = fingerprint . 5763 seems like it covers both . 
 thoughts ? 
 Authors believe this text is fine . please send us a PR with the specific change you want if you disagree . 
 said in email : certificate the local side will use in DTLS setup " . So , I would suggest to replace : “ However , not all parameters follow this rule ; for example , the DTLS- SRTP parameters [ RFC5763 ] sent to a remote party indicate what certificate the local side will use in DTLS setup , and thereby what the remote party should expect to receive ; ” … with : “ However , not all parameters follow this rule ; for example , the fingerprints sent to a remote party are calculated based on the local certificate(s ) offered ; ” If you agree with that understanding , I ’m happy to submit a pull request . 
 OK , I now see what you are saying , and I think the text you propose looks reasonable . Thanks for offering to submit a PR ! 
 [ waiting on PR from 
 It seems like I do n't have rights to submit new branches ( needed for the PR ) . 
 cd4u : fork the repo and push the branch to your fork , then submit the PR from there . 
 PR created : 
 Fixed by
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 DTLS-
SRTP parameters RFC5763 sent to a remote party indicate what
certificate the local side will use in DTLS setup, and thereby what
the remote party should expect to receive; the remote party will have
to accept these parameters, 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; for example, the
fingerprints I-D.ietf-mmusic-4572-update 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.
Draft: draft-ietf-rtcweb-jsep

Commentary: has given his thumbs up as well . 
 Originally raised by Christer Section 3.2 says : " To support this , the JSEP media layer can provide an offer via the createOffer ( ) method whenever the  application needs one for the signaling . The answerer can send back zero or more provisional answers , and finally end the offer - answer exchange by sending a final answer . The state machine for this is as follows : " 1 ) I would like to explicitly note that the generated offer is not applied ( and any previously applied offer is not removed ) until setLocalDescription ( ) is called . 
 OK . In this case , we should note this for the provisional answers as well . 
 I thought about this for a while and came to the conclusion that this is the wrong place for such text ; spelling everything out makes the overall message less clear . If we need to be super - prescriptive about the fact that the offer does not take effect until after setLD is called , we should state this in the createOffer / Answer sections ( 4.1.5/4.1.6 ) , not here . PTAL . 
 Will update document according to my last comment . 
 See PR 
 PR looks ok .
Paragraph (version A):
Calling this method may do things such as generate new ICE
credentials, but does not result in candidate gathering, or cause
media to start or stop flowing.
Paragraph (version B):
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 A):
Calling this method may do things such as generate new ICE
credentials, but does not trigger candidate gathering or change media
state.
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 pending local description, until
setLocalDescription is called.
Draft: draft-ietf-rtcweb-jsep

Commentary: Would love it if you could have a read of this and see if it was going the right direction . If not , help suggest text - I 'm struggling to figure out what is needed here . 
 OK given the new examples , what needs to happen with this text . 
 We realized that we messed up the a = recvonly case . I adapted the algorithm to handle it better . please check that I got it right . 
 We need to add text than when creating a re - offer , if things were previously grouped in LS , we keep them grouped in new LS 
 This LGTM 
 Waiting for OK from  then we can merge 
 Can you check the fix Justin made looks OK to you . Thanks 
 Given that we are only maintaining OfferToReceiveX for backwards compatibility , I 'm inclined not to try to support offering LS groups in initial recvonly offers . 
 Given that we are only maintaining OfferToReceiveX for backwards compatibility , I 'm inclined not to try to support offering LS groups in initial recvonly offers . Ok , this seems good to me then , after you add the text you suggested for recyling . 
 I think you need text in section 5.9 to complete the scenario . Having an example in the middle of the normative text does n't work too well , I think . LGTM with comments .
Paragraph (version B):
The sec.normal-example example later in this document shows a more
involved case of "LS" group generation.
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.
Draft: draft-ietf-rtcweb-jsep

Commentary: Should we treat endpoint and implementation as interchangeable ? 
 here is the policy I followed JSEP implementation ( or occasionally " implementation " when I just used  right before ) is the term for the browser JSEP endpoint is the term for the app / browser combo . PTAL 
 I think this is on you . 
 Line 4503 should probably be ' implementation ' instead of ' endpoint ' . LG otherwise .
Paragraph (version B):
While formally the JSEP interface is an API, it is better to think of
it is an Internet protocol, with the JS being untrustworthy from the
perspective of the endpoint.  Thus, the threat model of RFC3552
applies.  In particular, JS can call the API in any order and with
any inputs, including malicious ones.  This is particularly relevant
when we consider the SDP which is passed to setLocalDescription().
While correct API usage requires that the application pass in SDP
which was derived from createOffer() or createAnswer(), there is no
guarantee that applications do so.  The endpoint MUST be prepared for
the JS to pass in bogus data instead.
Draft: draft-ietf-rtcweb-jsep

Commentary: This incorporates Justin 's comments to PR
Paragraph (version B):
The removeTrack method removes a MediaStreamTrack from the
PeerConnection, using the RtpSender argument to indicate which sender
should have its track removed.  The sender's track is cleared, and
the sender stops sending.  Future calls to createOffer will mark the
media description associated with the sender as recvonly (if
transceiver.currentDirection is sendrecv) or as inactive (if
transceiver.currentDirection is sendonly).
Draft: draft-ietf-rtcweb-jsep

Commentary: Related to issue
Paragraph (version A):
An "a=setup" line, as specified in RFC4145, Section 4, and
clarified for use in DTLS-SRTP scenarios in RFC5763, Section 5.
The role value in the answer MUST be "active" or "passive"; the
"active" role is RECOMMENDED.  The role value MUST be consistent
with the existing DTLS connection, if one exists and is being
continued.
Paragraph (version B):
An "a=setup" line, as specified in RFC4145, Section 4, and
clarified for use in DTLS-SRTP scenarios in RFC5763, Section 5.
The role value in the answer MUST be "active" or "passive"; the
"active" role is RECOMMENDED.
Paragraph (version B):
Each "a=setup" line MUST use an "active" or "passive" role value
consistent with the existing DTLS association, if the association
is being continued by the offerer.
Draft: draft-ietf-rtcweb-jsep

Commentary: This is from the Windows HW offload framework , and spells things out more specifically in the surrounding text .
Paragraph (version A):
This declaration indicates that the receiver is capable of decoding
any image resolution from 16x16 up to 640x360 pixels.
Paragraph (version B):
This declaration indicates that the receiver is capable of decoding
any image resolution from 48x48 up to 640x360 pixels.
Draft: draft-ietf-rtcweb-jsep

Commentary: LG with one nit
Paragraph (version A):
The SDP returned from createOffer or createAnswer MUST NOT be changed
before passing it to setLocalDescription.  If precise control over
the SDP is needed, the aforementioned createOffer/createAnswer
options or RtpSender APIs MUST be used.
Paragraph (version B):
The SDP returned from createOffer or createAnswer MUST NOT be changed
before passing it to setLocalDescription.  If precise control over
the SDP is needed, the aforementioned createOffer/createAnswer
options or RtpTransceiver APIs MUST be used.
Paragraph (version A):
First, the parsed parameters are checked to ensure that they have not
been altered after their generation in createOffer/createAnswer, as
discussed in sec.modifying-sdp; otherwise, processing MUST stop and
an error MUST be returned.
Paragraph (version B):
First, the parsed parameters are checked to ensure that they are
identical to those generated in the last call to createOffer/
createAnswer, and thus have not been altered, as discussed in
sec.modifying-sdp; otherwise, processing MUST stop and an error MUST
be returned.
Draft: draft-ietf-rtcweb-jsep

Commentary: I tried to do what I thought you needed . 
 LG with one comment
Paragraph (version B):
If this m= section is for media with configurable durations of
media per packet, e.g., audio, an "a=maxptime" line, indicating
the maximum amount of media, specified in milliseconds, that can
be encapsulated in each packet, as specified in RFC4566,
Section 6.  This value is set to the smallest of the maximum
duration values across all the codecs included in the m= section.
Paragraph (version B):
If this m= section is for media with configurable durations of
media per packet, e.g., audio, an "a=maxptime" line, as described
in sec-create-offer.
Draft: draft-ietf-rtcweb-jsep

Commentary: LGTM 
 Section 3.8.2 - " the media flow from these sessions can be managed by specifying SDP direction attributes in the descriptions " . This seems out of place . Surely flipping is a much simpler way of managing them if the problem is what to play to the user ? Suggestion : Remove text .
Paragraph (version A):
As a result of sharing the media streams, the application will end up
with N parallel PeerConnection sessions, each with a local and remote
description and their own local and remote addresses.  The media flow
from these sessions can be managed by specifying SDP direction
attributes in the descriptions, or the application can choose to play
out the media from all sessions mixed together.  Of course, if the
application wants to only keep a single session, it can simply
terminate the sessions that it no longer needs.
Paragraph (version B):
As a result of sharing the media streams, the application will end up
with N parallel PeerConnection sessions, each with a local and remote
description and their own local and remote addresses.  The media flow
from these sessions can be managed using setDirection (see
sec.transceiver-set-direction), or the application can choose to play
out the media from all sessions mixed together.  Of course, if the
application wants to only keep a single session, it can simply
terminate the sessions that it no longer needs.
Draft: draft-ietf-rtcweb-jsep

Commentary: Also describing explicitly what it means for an RtpTransceiver to be " associated " with an m= section . Namely , that it has a mid attribute that matches the MID of that m= section . Addresses issue . 
 There probably are better ways of wording this , I 'm open to suggestions . 
 Ekr pointed out that this does n't handle situations where " a = mid " is not used . So I text describing a transceiver - m= section index mapping . 
 I think I 've addressed all of ekr and juberti 's comments ; ready for another review . 
 LGTM
Paragraph (version A):
RtpTransceivers generally have a 1:1 mapping with m= sections,
although there may be more RtpTransceivers than m= sections when
RtpTransceivers are created but not yet associated with a m= section,
or if RtpTransceivers have been stopped and disassociated from m=
sections.  An RtpTransceiver is never associated with more than one
m= section, and once a session description is applied, a m= section
is always associated with exactly one RtpTransceiver.
Paragraph (version B):
A rollback will disassociate any RtpTransceivers that were associated
with m= sections by the application of the rolled-back session
description (see sec.applying-a-remote-desc and sec.applying-a-local-
desc).  This means that some RtpTransceivers that were previously
associated will no longer be associated with any m= section; in such
cases, the value of the RtpTransceiver's mid property MUST be set to
null, and the mapping between the transceiver and its m= section
index MUST be discarded.  RtpTransceivers that were created by
applying a remote offer that was subsequently rolled back MUST be
removed.  However, a RtpTransceiver MUST NOT be removed if a track
was attached to the RtpTransceiver via the addTrack method.  This is
so that an application may call addTrack, then call
setRemoteDescription with an offer, then roll back that offer, then
call createOffer and have a m= section for the added track appear in
the generated offer.
Draft: draft-ietf-rtcweb-jsep

Commentary: updated .
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
current and pending 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 pending local
description, or roll back to the current description if the remote
side denied the change.
Paragraph (version B):
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
current and pending local descriptions (e.g., support the codecs that
exist in either description).  This dual processing begins when the
PeerConnection enters the have-local-offer state, and continues until
setRemoteDescription is called with either a final answer, at which
point the PeerConnection can fully adopt the pending local
description, or a rollback, which results in a revert to the current
local description.
Paragraph (version A):
The currentLocalDescription method returns a copy of the current
negotiated local description - i.e., the local description from the
last successful offer/answer exchange - in addition to any local
candidates that have been generated by the ICE Agent since the local
description was set.
Paragraph (version B):
The currentLocalDescription method returns the current negotiated
local description - i.e., the local description from the last
successful offer/answer exchange - in addition to any local
candidates that have been generated by the ICE Agent since the local
description was set.
Paragraph (version A):
This call may result in a change to the state of the ICE Agent, and
may result in a change to media state if it results in connectivity
being established.
Paragraph (version B):
This call may result in a change to the state of the ICE Agent.
Draft: draft-ietf-rtcweb-jsep

Commentary: Also , remove awkward reference to WebRTC spec 
 Originally raised by Christer Section 3.3 says : " In the WebRTC specification , session descriptions are formatted as SDP messages . " 1 ) To me it is unclear what an ³SDP  is , so I suggest we say   , as we also do later in the section . 
 FWIW , RFC 4566 itself uses the term ' SDP message ' in Section 7 . However , we could say ' descriptions use SDP syntax ' instead .
Paragraph (version A):
In the WebRTC specification, session descriptions are formatted as
SDP messages.  While this format is not optimal for manipulation from
Javascript, it is widely accepted, and frequently updated with new
features.  Any alternate encoding of session descriptions would have
to keep pace with the changes to SDP, at least until the time that
this new encoding eclipsed SDP in popularity.  As a result, JSEP
currently uses SDP as the internal representation for its session
descriptions.
Paragraph (version B):
JSEP's session descriptions use SDP syntax for their internal
representation.  While this format is not optimal for manipulation
from Javascript, it is widely accepted, and frequently updated with
new features; any alternate encoding of session descriptions would
have to keep pace with the changes to SDP, at least until the time
that this new encoding eclipsed SDP in popularity.