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

Commentary: BLOCKER : The first bullet on page 35 has a normative statement about the AVT profile strings that must be accepted , but uses an unspecified grammar to actually specify the string . If this is normative , it needs to be formal . Either specify the string using a formal and cited grammar , or provide an exhaustive list . 
 Proposal on editor 's call is to use POSIX extended regular expressions . I believe this would give us the expressions . ( UDP|TCP)/TLS / RTP / SAVPF ? and : RTP / S?AVPF ? 
 You 're sure you want to pull in another reference for regexes instead of just listing all eight valid values ?
Paragraph (version A):
Any profile in the offer matching the following patterns MUST be
accepted: "RTP/[S]AVP[F]" and "(UDP|TCP)/TLS/RTP/SAVP[F]".
Draft: draft-ietf-rtcweb-jsep

Commentary: BLOCKER : Section 5.7.1 , first paragraph : this claims that a= lines are order insensitive . Nothing in SDP 's base definition makes this true , and nothing precludes specific attributes from assigning meaning to the order in which they appear . See draft - ietf - slim - negotiating - human - language-08 for an example of an SDP extension that does apply meaning to the order in which attributes appear ( for better or worse ) . 
 Section Session - Level Parsing Text is First , the session - level lines are checked and parsed . These lines MUST occur in a specific order , and with a specific syntax , as defined in [ RFC4566 ] , Section 5 . Note that while the specific line types ( e.g. " v= " , " c= " ) MUST occur in the defined order , lines of the same type ( typically " a= " ) can occur in any order , and their ordering is not meaningful . Remove the text " and their ordering is not meaningful . " from above para 
 FWIW ... some of SDP implementations I work with save a lines in non ordered sets and I never knew this was a bug . Bummer 
 Agree with proposal . 
 LGTM
Paragraph (version A):
First, the session-level lines are checked and parsed.  These lines
MUST occur in a specific order, and with a specific syntax, as
defined in RFC4566, Section 5.  Note that while the specific line
types (e.g. "v=", "c=") MUST occur in the defined order, lines of the
same type (typically "a=") can occur in any order, and their ordering
is not meaningful.
Paragraph (version B):
First, the session-level lines are checked and parsed.  These lines
MUST occur in a specific order, and with a specific syntax, as
defined in RFC4566, Section 5.  Note that while the specific line
types (e.g. "v=", "c=") MUST occur in the defined order, lines of the
same type (typically "a=") can occur in any order.
Draft: draft-ietf-rtcweb-jsep

Commentary: Seen only in S 3.2 ( Session Descriptions and State Machine )
Paragraph (version A):
In order to establish the media plane, the user agent needs specific
parameters to indicate what to transmit to the remote side, as well
as how to handle the media that is received.  These parameters are
determined by the exchange of session descriptions in offers and
answers, and there are certain details to this process that must be
handled in the JSEP APIs.
Paragraph (version B):
In order to establish the media plane, the JSEP implementation needs
specific parameters to indicate what to transmit to the remote side,
as well as how to handle the media that is received.  These
parameters are determined by the exchange of session descriptions in
offers and answers, and there are certain details to this process
that must be handled in the JSEP APIs.
Draft: draft-ietf-rtcweb-jsep

Commentary: Remaining task from
Paragraph (version A):
If the MID header extension is supported, prepare to demux RTP
streams intended for this m= section based on the MID header
extension, as described in I-D.ietf-mmusic-sdp-bundle-
negotiation, Section 14.
Paragraph (version A):
For each specified media format, establish a mapping between
the payload type and the actual media format, as described in
RFC3264, Section 6.1.  If any indicated media format is not
supported, this MUST result in an error.
Paragraph (version B):
If the MID header extension is supported, prepare to demux RTP
streams intended for this m= section based on the MID header
extension, as described in I-D.ietf-mmusic-sdp-bundle-
negotiation, Section 15.
Paragraph (version B):
For each specified media format, establish a mapping between
the payload type and the actual media format, as described in
RFC3264, Section 6.1.  In addition, prepare to demux RTP
streams intended for this m= section based on the media formats
supported by this m= section, as described in I-D.ietf-mmusic-
sdp-bundle-negotiation, Section 10.2.  If any indicated media
format is not supported, this MUST result in an error.
Paragraph (version B):
For each specified SSRC that is signaled in the m= section,
prepare to demux RTP streams intended for this m= section using
that SSRC, as described in I-D.ietf-mmusic-sdp-bundle-
negotiation, Section 10.2.
Draft: draft-ietf-rtcweb-jsep

Commentary: I took your text and sharpened it a bit
Paragraph (version A):
If the PeerConnection state is "have-local-offer", and 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", note that an ICE
restart is needed.  If the description is of type "answer" or
"pranswer" 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 answerer 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 A):
If the PeerConnection state is "have-remote-pranswer", and the ICE
ufrag or password changed from the previous provisional answer,
then signal the ICE agent to discard any previous ICE check list
state for the m= section and begin checks as if this were the
first answer.  However, such an answer MAY only change the ICE
ufrag or password if the local offer is starting or restarting ICE
for the m= section.
Paragraph (version B):
If the ICE ufrag or password changed from the previous remote
description: RFC5245.
Paragraph (version B):
If the description is of type "offer", note that an ICE restart
is needed, as described in Section 9.1.1.1 of RFC5245.
Paragraph (version B):
If the description is of type "answer" or "pranswer", then
check to see if the current local description is an ICE
restart, and if not, generate an error.  It the PeerConnection
state is "have-remote-pranswer", and the ICE ufrag or password
changed from the previous provisional answer, then signal the
ICE agent to discard any previous ICE check list state for the
m= section.  Finally, signal the ICE agent to begin checks as
described in Section 9.3.1.1 of RFC5245.
Paragraph (version B):
If the current local description indicates an ICE restart, and
either the ICE ufrag or password has not changed from the previous
remote description, as prescribed by RFC5245, Section 9.2.1.1,
generate an error.
Draft: draft-ietf-rtcweb-jsep

Commentary: PTAL 
 LGTM with one minor comment
Paragraph (version A):
The thinking behind WebRTC call setup has been to fully specify and
control the media plane, but to leave the signaling plane up to the
application as much as possible.  The rationale is that different
applications may prefer to use different protocols, such as the
existing SIP or Jingle call signaling protocols, or something custom
to the particular application, perhaps for a novel use case.  In this
approach, the key information that needs to be exchanged is the
multimedia session description, which specifies the necessary
transport and media configuration information necessary to establish
the media plane.
Paragraph (version B):
The thinking behind WebRTC call setup has been to fully specify and
control the media plane, but to leave the signaling plane up to the
application as much as possible.  The rationale is that different
applications may prefer to use different protocols, such as the
existing SIP call signaling protocol, or something custom to the
particular application, perhaps for a novel use case.  In this
approach, the key information that needs to be exchanged is the
multimedia session description, which specifies the necessary
transport and media configuration information necessary to establish
the media plane.
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 JSEP implementation, because only the implementation has the
necessary knowledge of candidates and other transport information.
Performing this separation provides additional flexibility in
protocols that decouple session descriptions from transport.  For
instance, in traditional SIP, each offer or answer is self-contained,
including both the session descriptions and the transport
information.  However, I-D.ietf-mmusic-trickle-ice-sip allows SIP to
be used with trickle ICE I-D.ietf-ice-trickle, in which the session
description can be sent immediately and the transport information can
be sent when available.  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.  JSEP's decoupling of the ICE and signaling state
machines allows it to accommodate either model.
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".  When
the offer contains the "actpass" value, as will always be the case
with JSEP endpoints, the answerer SHOULD use the "active" role.
Offers from non-JSEP endpoints MAY send other values for
"a=setup", in which case the answer MUST use a value consistent
with the value in the offer.
Draft: draft-ietf-rtcweb-jsep

Commentary: I think I got all the things Justin mentioned . 
 Will take a final look once  's comments are resolved . 
 Made a slight change to one sentence to mention user agents . PTAL . 
 For the examples , please expand the acronyms " JS " and " UA " . 
 I think we 're going to want to do it once . 
 I think I want to define some of theses instead of replace all of them because we ca n't stay in the column limit if they are expanded .
Paragraph (version A):
The code flow below shows Alice's endpoint initiating the session to
Bob's endpoint.  The messages from Alice's JS to Bob's JS are assumed
to flow over some signaling protocol via a web server.  The JS on
both Alice's side and Bob's side waits for all candidates before
sending the offer or answer, so the offers and answers are complete;
trickle ICE is not used.  Both Alice and Bob are using the default
bundle policy of "balanced", and the default RTCP mux policy of
"require".
Paragraph (version B):
The code flow below shows Alice's endpoint initiating the session to
Bob's endpoint.  The messages from the Javascript application in
Alice's browser to the Javascript in Bob's browser, abbreviated as
AliceJS and BobJS respectively, are assumed to flow over some
signaling protocol via a web server.  The Javascript on both Alice's
side and Bob's side waits for all candidates before sending the offer
or answer, so the offers and answers are complete; trickle ICE is not
used.  The user agents (JSEP implementations) in Alice and Bob's
browsers, abbreviated as AliceUA and BobUA respectively, are using
the default bundle policy of "balanced", and the default RTCP mux
policy of "require".
Draft: draft-ietf-rtcweb-jsep

Commentary: done . still waiting for you . 
 Section 1.2 uses the term " glare " without describing it . This term may be unfamiliar to readers , and should be explained or cited . 
 Agreed . 
 See for a definition . 
 LGTM , but see comment
Paragraph (version A):
One approach that was considered instead of JSEP was to include a
lightweight signaling protocol.  Instead of providing session
descriptions to the API, the API would produce and consume messages
from this protocol.  While providing a more high-level API, this put
more control of signaling within the JSEP implementation, forcing it
to have to understand and handle concepts like signaling glare.  In
addition, it prevented the application from driving the state machine
to a desired state, as is needed in the page reload case.
Paragraph (version B):
One approach that was considered instead of JSEP was to include a
lightweight signaling protocol.  Instead of providing session
descriptions to the API, the API would produce and consume messages
from this protocol.  While providing a more high-level API, this put
more control of signaling within the JSEP implementation, forcing it
to have to understand and handle concepts like signaling glare (see
RFC3264, Section 4).
Draft: draft-ietf-rtcweb-jsep

Commentary: PTAL 
 Section 3.5.1 talks about a " recycled m= section " without any context for what this means . Please provide a forward reference to the section that discusses m= section recycling . 
 2 is where m= section recycling is first defined , but it 's as a bullet point in how to generate an offer , which makes a direct reference problematic . I guess we could say " as spelled out in [ ref ] "
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 said to be associated with an m=
section if its mid property is non-null; otherwise it is said to be
disassociated.  The associated m= section is determined using a
mapping between transceivers and m= section indices, formed when
creating an offer or applying a remote offer.  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):
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 said to be associated with an m=
section if its mid property is non-null; otherwise it is said to be
disassociated.  The associated m= section is determined using a
mapping between transceivers and m= section indices, formed when
creating an offer or applying a remote offer.
Paragraph (version B):
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.  However, in certain
cases where a m= section has been rejected, as discussed in
sec.subsequent-offers below, that m= section will be "recycled" and
associated with a new RtpTransceiver with a new mid value.
Draft: draft-ietf-rtcweb-jsep

Commentary: I did add a MUST here , but I think it 's just a restatement of what is already true . 
 BLOCKER : Several of the SDP - building procedures in this document call out addition of " a = fingerprint " to individual media sections , while the canonical definition of " a = fingerprint " allows these to be at either the session level or the media level . The same is true of ice - pwd and ice - ufrag . While the process of SDP building in this document appears to be prescriptive on purpose , one assumes that it is allowed some variation so as to accommodate deployment of future SDP extensions . Because of this state of affairs , it is unclear whether implementations that consolidate these attributes at the session level when they would otherwise be identical among all media sections is such an allowable variation . Ambiguity in specifications is never a good thing , so I believe that the draft needs to do one of : ( a ) specifically call out this kind of aggregation as allowed ; ( b ) specifically call out this kind of aggregation as disallowed ; or ( c ) include a blanket statement that implementations are allowed to emit SDP that is semantically equivalent to that which is generated by the procedures in this document , but which may vary in exact structure . I have a strong preference for ( c ) -- implementations will be required to deal with such variations anyway to interop with legacy SDP , so prohibiting JSEP clients from generating them serves no goal . 
 My suggestion would be to expand the para below to say ( a ) , i.e. that applications that wish to aggregate may do so , even though we recommend not aggregating . Attributes which SDP permits to either be at the session level or the media level SHOULD generally be at the media level even if they are identical . This promotes readability , especially if one of a set of initially identical attributes is subsequently changed . 
 ( and also fine with suggestions Justin is suggesting )
Paragraph (version A):
Attributes which SDP permits to either be at the session level or the
media level SHOULD generally be at the media level even if they are
identical.  This assists development and debugging by making it
easier to understand individual media sections, especially if one of
a set of initially identical attributes is subsequently changed.
Paragraph (version B):
Attributes which SDP permits to either be at the session level or the
media level SHOULD generally be at the media level even if they are
identical.  This assists development and debugging by making it
easier to understand individual media sections, especially if one of
a set of initially identical attributes is subsequently changed.
However, implementations MAY choose to aggregate attributes at the
session level and JSEP implementations MUST be prepared to receive
attributes in either location.
Draft: draft-ietf-rtcweb-jsep

Commentary: I tried to clarify bundle - only while Iw as in here . 
 BLOCKER : The final paragraph in section 3.5.1 says that candidates are only gathered for m= sections referenced in BUNDLE tags . Section 3.5.4 talks about gathering more candidates than that under certain circumstances . Please make these consistent with each other . 
 Agree this needs to be rewritten ; with BUNDLE , # of media streams is not the number of ICE components .
Paragraph (version A):
Note that gathering phases only gather the candidates needed by
new/recycled/restarting m= sections; other m= sections continue to
use their existing candidates.  Also, when bundling is active,
candidates are only gathered (and exchanged) for the m= sections
referenced in BUNDLE-tags, as described in I-D.ietf-mmusic-sdp-
bundle-negotiation.
Paragraph (version B):
Note that gathering phases only gather the candidates needed by
new/recycled/restarting m= sections; other m= sections continue to
use their existing candidates.  Also, if an m= section is bundled
(either by a successful bundle negotiation or by being marked as
bundle-only), then candidates will be gathered and exchanged for that
m= section if and only if its MID is a BUNDLE-tag, as described in I-
D.ietf-mmusic-sdp-bundle-negotiation.
Paragraph (version A):
JSEP applications typically inform the JSEP implementation to begin
ICE gathering via the information supplied to setLocalDescription, as
this is where the app specifies the number of media streams, and
thereby ICE components, for which to gather candidates.  However, to
accelerate cases where the application knows the number of ICE
components to use ahead of time, it may ask the implementation to
gather a pool of potential ICE candidates to help ensure rapid media
setup.
Paragraph (version B):
JSEP applications typically inform the JSEP implementation to begin
ICE gathering via the information supplied to setLocalDescription, as
the local description indicates the number of ICE components which
will be needed and for which candidates must be gathered.  However,
to accelerate cases where the application knows the number of ICE
components to use ahead of time, it may ask the implementation to
gather a pool of potential ICE candidates to help ensure rapid media
setup.
Draft: draft-ietf-rtcweb-jsep

Commentary: Section 3.6.2 would ideally include a disclaimer , like we have for many other features , indicating that -- despite normative statements in this section -- the remote side might not honor imageattr because of legacy behavior , and that implementations MUST be prepared to handle such situations . 
 Sure . This should probably go into 3.6 or 3.6.1 , since those govern sent imageattr attribs . 
 LGTM
Paragraph (version A):
Video size negotiation is the process through which a receiver can
use the "a=imageattr" SDP attribute RFC6236 to indicate what video
frame sizes it is capable of receiving.  A receiver may have hard
limits on what its video decoder can process, or it may have some
maximum set by policy.
Paragraph (version B):
Video size negotiation is the process through which a receiver can
use the "a=imageattr" SDP attribute RFC6236 to indicate what video
frame sizes it is capable of receiving.  A receiver may have hard
limits on what its video decoder can process, or it may have some
maximum set by policy.  By specifying these limits in an
"a=imageattr" attribute, JSEP endpoints can attempt to ensure that
the remote sender transmits video at an acceptable resolution.
However, when communicating with a non-JSEP endpoint that does not
understand this attribute, any signaled limits may be exceeded, and
the JSEP implementation MUST handle this gracefully, e.g., by
discarding the video.
Draft: draft-ietf-rtcweb-jsep

Commentary: Page 37 contains a statement that " attributes of category IDENTICAL or TRANSPORT should not be repeated in bundled m= sections " . Two issues : this reads as normative , so consider " SHOULD NOT " rather than " should not . " Also , I think this is true of bundle - only sections , not bundled sections in general . 
 If we are going to use normative language , seems like we should match the language from BUNDLE , which probably says ' MUST NOT ' . The statement is correct regarding any actively bundled sections ( which includes bundle - only ) , but this part of the text has caused enough confusion that some extra explanation is probably warranted .
Paragraph (version A):
I-D.ietf-mmusic-sdp-mux-attributes groups SDP attributes into
different categories.  To avoid unnecessary duplication when
bundling, Section 8.1 of I-D.ietf-mmusic-sdp-bundle-negotiation
specifies that attributes of category IDENTICAL or TRANSPORT should
not be repeated in bundled m= sections.
Paragraph (version B):
I-D.ietf-mmusic-sdp-mux-attributes groups SDP attributes into
different categories.  To avoid unnecessary duplication when
bundling, Section 8.1 of I-D.ietf-mmusic-sdp-bundle-negotiation
specifies that attributes of category IDENTICAL or TRANSPORT MUST NOT
be repeated in bundled m= sections.  This includes m= sections for
which bundling has been negotiated and is still desired, as well as
m= sections marked as bundle-only.