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

Commentary: removes parsing of a = ssrc and a = ssrc - group . The createOffer parts were removed in the -17 draft . 
 Would n't it make more sense to add the ssrc - group back into the draft to allow proper handling of RTX . 
 I 'm fine with removing this 
 Not sure why we need to remove this since this can be used to indicate how to init the demux table . 
 I do think removing ssrc - group would be a good idea though since we do n't plan to use it . We should also make clear that a = ssrc is only used for seeding the demux table . 
 To be specific : 5.9 ( remote desc ) should be updated to indicate that any a = ssrc values are supplied to the demuxer , and we should remove discussion of a = ssrc - group here . 
 You arguments to keep this make sense . I 'm fine with keeping it . 
 Changed it to only remove a = ssrc - group , since IIUC the demux algorithm does not consider it . does this seem reasonable to you ? Separately I will add text in 5.9 to say that the a = ssrc values should be supplied to the demuxer . 
 It was non - obvious to me that RTX has to use the same MID RTP header extension values as the RTP stream it covers . Now the same argument for priming the demuxer could be made for the SSRC learned from ssrc - group . But if we assume that RTX packets will not be the first packets which you receive it 's probably fine . 
 Remaining task from
Paragraph (version A):
Any "a=ssrc" or "a=ssrc-group" attributes MUST be parsed as
specified in RFC5576, Sections 4.1-4.2, and their values stored.
Paragraph (version B):
Any "a=ssrc" attributes MUST be parsed as specified in RFC5576,
Section 4.1, and their values stored.
Draft: draft-ietf-rtcweb-jsep

Commentary: Note that the use of CVO in webrtc is described in 
 feel free to rewrite however and merge . I just wanted to get the xref in . 
 We mention it in the imageattr section . This is required regardless of whether the receiver supports performing receive - side rotation ( e.g. , through CVO ) , as it significantly simplifies the matching logic . 
 , can you look into this ? Not  blocking . 
 will do - I seem to recall it is a 3GPP ref but will try and track down .
Paragraph (version A):
This specification prescribes more specific behavior.  When a sender
of a given MediaStreamTrack, which is producing video of a certain
resolution, receives an "a=imageattr recv" attribute, it MUST check
to see if the original resolution meets the size criteria specified
in the attribute, and adapt the resolution accordingly by scaling (if
appropriate).  Note that when considering a MediaStreamTrack that is
producing rotated video, the unrotated resolution MUST be used.  This
is required regardless of whether the receiver supports performing
receive-side rotation (e.g., through CVO), as it significantly
simplifies the matching logic.
Paragraph (version B):
This specification prescribes more specific behavior.  When a sender
of a given MediaStreamTrack, which is producing video of a certain
resolution, receives an "a=imageattr recv" attribute, it MUST check
to see if the original resolution meets the size criteria specified
in the attribute, and adapt the resolution accordingly by scaling (if
appropriate).  Note that when considering a MediaStreamTrack that is
producing rotated video, the unrotated resolution MUST be used.  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: Turns out that 5245 does n’t capitalize “ agent ” in “ ICE agent ” .
Paragraph (version A):
If the ICE ufrag or password changed from the previous remote
description, then an ICE restart is needed, as described in
Section 9.1.1.1 of RFC5245 If the description is of type "offer",
mark that an ICE restart is needed.  If the description is of type
"answer" and the current local description is also an ICE restart,
then signal the ICE agent to begin checks as described in
Section 9.3.1.1 of RFC5245.  An answer MUST change the ufrag and
password in an answer if and only if ICE is restarting, as
described in Section 9.2.1.1 of RFC5245.
Paragraph (version B):
If the ICE ufrag or password changed from the previous remote
description, then an ICE restart is needed, as described in
Section 9.1.1.1 of RFC5245.  If the description is of type
"offer", mark that an ICE restart is needed.  If the description
is of type "answer" and the current local description is also an
ICE restart, then signal the ICE agent to begin checks as
described in Section 9.3.1.1 of RFC5245.  An answer MUST change
the ufrag and password in an answer if and only if ICE is
restarting, as described in Section 9.2.1.1 of RFC5245.
Draft: draft-ietf-rtcweb-jsep

Commentary: PTAL at this . I realized the answer section also needed to be updated to match the new offer text , so I made some changes there which involved a bit of massaging of the text in . 
 LGTM
Paragraph (version A):
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):
If a data channel m= section has been offered, a m= section MUST also
be generated for data.  The <media> field MUST be set to
"application" and the <proto> and "fmt" fields MUST be set to exactly
match the fields in the offer.  Note that if media m= sections are
bundled into a data m= section, then certain TRANSPORT and IDENTICAL
attributes may appear in the data m= section even if they would
otherwise only be appropriate for a media m= section (e.g., "a=rtcp-
mux").
Paragraph (version B):
If a data channel m= section has been offered, a m= section MUST also
be generated for data.  The <media> field MUST be set to
"application" and the <proto> and <fmt> fields MUST be set to exactly
match the fields in the offer.
Paragraph (version A):
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".
Paragraph (version B):
Note that if media m= sections are bundled into a data m= section,
then certain TRANSPORT and IDENTICAL attributes may also appear in
the data m= section even if they would otherwise only be appropriate
for a media m= section (e.g., "a=rtcp-mux").
Draft: draft-ietf-rtcweb-jsep

Commentary: ( i.e. , for only present in new m= sections )
Paragraph (version A):
The JSEP implementation will only gather RTP candidates and will
insert an "a=rtcp-mux-only" indication into any offers it
generates.  This halves the number of candidates that the offerer
needs to gather.  Applying a description with an m= section that
does not contain an "a=rtcp-mux" attribute will cause an error to
be returned.
Paragraph (version B):
The JSEP implementation will only gather RTP candidates and will
insert an "a=rtcp-mux-only" indication into any new m= sections in
offers it generates.  This halves the number of candidates that
the offerer needs to gather.  Applying a description with an m=
section that does not contain an "a=rtcp-mux" attribute will cause
an error to be returned.
Paragraph (version B):
The "a=rtcp-mux-only" line MUST NOT be added.
Draft: draft-ietf-rtcweb-jsep

Commentary: FYI 
 Looks good to me .
Paragraph (version A):
The media formats in the answer MAY include codecs present in the
offer that were discarded in a previous offer/answer exchange.
This is necessary for compatibility with third- party call control
and SIP use cases.
Paragraph (version A):
The m= line and corresponding "a=rtpmap" and "a=fmtp" lines MUST
only include codecs present in the most recent answer which have
not been excluded by the codec preferences of the associated
transceiver.  Note that non-JSEP endpoints are not subject to
these restrictions, and might offer media formats that were not
present in the most recent answer, as specified in RFC3264,
Section 8.  Therefore, JSEP implementations MUST be prepared to
receive such offers.
Paragraph (version A):
Unless codec preferences have been set for the associated
transceiver, the media formats on the m= line MUST be generated in
the same order as in the current local description.
Paragraph (version A):
The RTCP feedback extensions MUST only include those that are
present in the most recent answer.
Paragraph (version B):
The m= line and corresponding "a=rtpmap" and "a=fmtp" lines MUST
only include media formats which have not been excluded by the
codec preferences of the associated transceiver, and MUST include
all currently available formats.  Media formats that were
previously offered but are no longer available (e.g., a shared
hardware codec) MAY be excluded.
Paragraph (version B):
Unless codec preferences have been set for the associated
transceiver, the media formats on the m= line MUST be generated in
the same order as in the most recent answer.  Any new media
formats that were not present in the most recent answer MUST be
added after all existing formats.
Paragraph (version B):
The RTCP feedback mechanisms MUST only include those that are
present in the most recent answer, except for the case of format-
specific mechanisms that are referencing a newly-added media
format.
Draft: draft-ietf-rtcweb-jsep

Commentary: Good way of getting ICE going quickly , and shows off IceTransportPolicy . Consider ICE restart for second offer ( shows off ICE restart handling ) . Could also go into complex example . 
 Started on this .
Paragraph (version B):
This example also makes use of the "relay" ICE candidate policy
described in sec.ice-candidate-policy to minimize the ICE gathering
and checking needed.
Draft: draft-ietf-rtcweb-jsep

Commentary: Since the second ref is so close to the first , I decided it was n't needed . 
 Yes , we need a reference for 7587 , since we talk about usedtx . It might make sense to have one for 6716 as well in S 5.2.3.2 . 
 Looks good . Do you think we need a similar ref to 7587 in the para that discusses dtx=0 ?
Paragraph (version A):
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 offered audio codec, as specified in RFC3389, Section 5.1,
except for codecs that have their own internal silence suppression
support.  For codecs that have their own internal silence suppression
support, the appropriate fmtp parameters for that codec MUST be
specified to indicate that silence suppression for received audio is
desired.  For example, when using the Opus codec, the "usedtx=1"
parameter would be specified in the offer.  This option allows the
endpoint to significantly reduce the amount of audio bandwidth it
receives, at the cost of some fidelity, depending on the quality of
the remote VAD algorithm.
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 offered audio codec, as specified in RFC3389, Section 5.1,
except for codecs that have their own internal silence suppression
support.  For codecs that have their own internal silence suppression
support, the appropriate fmtp parameters for that codec MUST be
specified to indicate that silence suppression for received audio is
desired.  For example, when using the Opus codec RFC6716, the
"usedtx=1" parameter, specified in RFC7587, would be used in the
offer.  This option allows the endpoint to significantly reduce the
amount of audio bandwidth it receives, at the cost of some fidelity,
depending on the quality of the remote VAD algorithm.
Draft: draft-ietf-rtcweb-jsep

Commentary: This does n't affect SDP , but we could add some text to the para below indicating a SSRC switch is needed when changing to a codec with a different clockrate : If the directional attribute in the answer is of type " sendrecv " or " sendonly " , choose the media format to send as the most preferred media format from the remote description that is also present in the answer , as described in [ RFC3264 ] , Sections 6.1 and 7 , and start transmitting RTP media once the underlying transport layers have been established . If a SSRC has not already been chosen for this outgoing RTP stream , choose a random one . 
 ( and add a reference ) 
 Closing per
Paragraph (version A):
If the directional attribute in the answer is of type
"sendrecv" or "sendonly", choose the media format to send as
the most preferred media format from the remote description
that is also present in the answer, as described in RFC3264,
Sections 6.1 and 7, and start transmitting RTP media once the
underlying transport layers have been established.  If a SSRC
has not already been chosen for this outgoing RTP stream,
choose a random one.
Paragraph (version B):
If the directional attribute in the answer is of type
"sendrecv" or "sendonly", choose the media format to send as
the most preferred media format from the remote description
that is also present in the answer, as described in RFC3264,
Sections 6.1 and 7, and start transmitting RTP media once the
underlying transport layers have been established.  If an SSRC
has not already been chosen for this outgoing RTP stream,
choose a random one.  If media is already being transmitted,
the same SSRC SHOULD be used unless the clockrate of the new
codec is different, in which case a new SSRC MUST be chosen, as
specified in RFC7160, Section 3.1.
Draft: draft-ietf-rtcweb-jsep

Commentary: I cleaned up as you suggested . 
 this is TCP Candidates with Interactive Connectivity Establishment ( ICE ) 
 We could have an informative reference for S 5.1.3 where we mention ICE can use UDP or TCP . 
 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 TCP or UDP
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 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.
Draft: draft-ietf-rtcweb-jsep

Commentary: I fixed the grammar and some text about " subsequent verification " 
 Also see 
 What 's the issue ? 
 Someone thought we should talk about how to parse SDP with more than one identity line and handle that . I did not look , we may already have whatever we need in the draft but I just opened this so we would at least go check . 
 JSEP practice is just to put in placeholders and link to the defining draft , so we should punt the actual semantics in security - arch . 
 See email to rtcweb from   subject " Identity in the SDP " 
   : [ 2 ]
Paragraph (version B):
If WebRTC identity is being used, an "a=identity" line as
described in I-D.ietf-rtcweb-security-arch, Section 5.
Paragraph (version B):
Any "a=identity" lines are parsed and the identity values stored
for subsequent verification, as specified I-D.ietf-rtcweb-
security-arch, Section 5.
Draft: draft-ietf-rtcweb-jsep

Commentary: In Section 5.4 , JSEP says : " The SDP returned from createOffer or createAnswer MUST NOT be changed before passing it to setLocalDescription . " However in Section 5.8 , it says : " 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 Section 5.4 ; otherwise , processing MUST stop and an error MUST be returned . " [ BA ] So is any change to unacceptable ( e.g. must be byte for byte identical ) ? Or is the text trying to say that the parsed representation must be the same ( e.g. " a= " lines appearing in a different order should n't matter ) ? 
 I believe the expectation was that the description is entirely immutable . Verifying isomorphism in the face of minor modifications seems like something that is not entirely trivial , and TBH I do n't quite understand why it would be needed . 
 Thanks . PR assumes that is immutable . 
 I will update 5.8 accordingly .
Paragraph (version B):
The SessionDescription is then checked to ensure that its contents
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.
Paragraph (version A):
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: o If the m= section is not bundled into another m= section , an " a = rtcp " attribute line MUST be with of the default RTCP candidate , as indicated in [ RFC5761 ] , Section 5.1.3 .
Paragraph (version A):
If the m= section is not bundled into another m= section, an
"a=rtcp" attribute line MUST be added with of the default RTCP
candidate, as indicated in RFC5761, Section 5.1.3.
Paragraph (version B):
If the m= section is not bundled into another m= section, its
"a=rtcp" attribute line MUST be filled in with the port and
address of the default RTCP candidate, as indicated in RFC5761,
Section 5.1.3.  If no RTCP candidates have yet been gathered,
dummy values MUST be used, as described in the initial offer
section above.
Draft: draft-ietf-rtcweb-jsep

Commentary: All the xref I removed are used elsewhere in spec other than the one which I to where it is used . 
 Fixed as Justin suggested and ready for re review 
 - have a look - I think I got all the changes 
 I tweaked the discussion of unknown a= ; now LGTM
Paragraph (version B):
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 TCP or UDP
transport depending on network conditions, this advertisement is
consistent with ICE eventually selecting either either UDP or TCP.
Draft: draft-ietf-rtcweb-jsep

Commentary: Merging . 
 LGTM with minor editorial
Paragraph (version A):
The codec preferences of an RtpTransceiver can also determine the
order of codecs in subsequent calls to createOffer and createAnswer,
in which case the order of the media formats in the associated m=
section will match.  However, the codec preferences cannot change the
order of the media formats after an answer containing the transceiver
has been applied.  At this point, codecs can only be removed, not
reordered.
Paragraph (version B):
The codec preferences of an RtpTransceiver can also determine the
order of codecs in subsequent calls to createOffer and createAnswer,
in which case the order of the media formats in the associated m=
section will match.
Draft: draft-ietf-rtcweb-jsep

Commentary: I applied the following principles , which unfortunately are somewhat inconsistent with the current mux - exclusive draft . You use a = rtcp - mux to negotiate mux a = rtcp - mux - only is used by the offerer to say " I really mean it " To that end , offers contain a = rtcp - mux - only if the policy is require . Answers do n't contain it because you do n't need it to negotiate mux . 
 Those principles are consistent with bundle - only , although I wrote the mux - only examples as if mux - only should always be included whenever a = rtcp - mux is present . 
 back at you 
 ping 
 LG
Paragraph (version A):
The JSEP implementation will only gather RTP candidates.  This
halves the number of candidates that the offerer needs to gather.
Applying a description with an m= section that does not contain an
"a=rtcp-mux" attribute will cause an error to be returned.
Paragraph (version B):
The JSEP implementation will only gather RTP candidates and will
insert an "a=rtcp-mux-only" indication into any offers it
generates.  This halves the number of candidates that the offerer
needs to gather.  Applying a description with an m= section that
does not contain an "a=rtcp-mux" attribute will cause an error to
be returned.
Paragraph (version B):
If the RTP/RTCP multiplexing policy is "require", an "a=rtcp-mux-
only" line, as specified in I-D.ietf-mmusic-mux-exclusive,
Section 4.
Paragraph (version A):
The "a=rtcp-mux-only" line MUST only be added if present in the
most recent answer.
Paragraph (version A):
If the RTP/RTCP multiplexing policy is "require", each m= section
MUST contain an "a=rtcp-mux" attribute.
Paragraph (version B):
If the RTP/RTCP multiplexing policy is "require", each m= section
MUST contain an "a=rtcp-mux" attribute.  If an "m=" section
contains an "a=rtcp-mux-only" attribute then that section MUST
also contain an "a=rtcp-mux" attribute.
Draft: draft-ietf-rtcweb-jsep

Commentary: Followup for
Paragraph (version A):
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.
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 JSEP implementation MUST be
prepared for the JS to pass in bogus data instead.