Editorial changes:
I guess my one comment addressing the document as a whole would be
that the examples used in the draft are helpful in explaining certain
aspects and therefore even more examples would be even more helpful.
J: Which particular examples were most useful - the inline hand-wavy descriptions, the API flows, or the example SDP?
- Section 1.1, Paragraph 3, Last Sentence
"This mechanism effectively removes the browser almost completely
from the core signaling flow; the only interface needed is a way
for the application to pass in the local and remote session
descriptions negotiated by whatever signaling mechanism is used,
and a way to interact with the ICE state machine."
I think this can be reworded to be clearer and more powerful, something
such as:
"JSEP removes the browser almost entirely from the core signaling flow.
The Javascript application needs interfaces for only (1) passing in
local and remote session descriptions and (2) interacting with the ICE
state machine."
Perhaps the exact wording I've suggested is not ideal, but something
that more clearly shows that JSEP removes the browser from the signaling
flow and that the application (and therefore, the application's
developer) needs to do only two things for establishing a session. The
way it is worded now is unclear at first read and does not adequately
persuade me why JSEP is awesome (IMO).
J: Agree your wording is more direct. We'll rework this part.
- Section 3.4.2, Paragraph 1
"However, to accelerate cases where the browser knows the number of
media streams to use ahead of time"
An example of a situation where the browser might know the number of
media streams ahead of time might be useful for context here, if one is
easily explained.
J: Sure, that makes sense. The typical case here is for an endpoint that wants to be able to quickly set up a received call. The caller has the ability to just start the call and leave it in the local-offer state instead.
- Section 3.5.1, Paragraph 2
"... the application can choose to apply it either as a provisional
answer, leaving open the possibility of using a different answer in
the future, or apply it as a final answer, ending the setup flow."
How does the application decide whether to apply as provisional or
final? Does JSEP care at all or is this left entirely up to the
application to decide? This is expounded on somewhat in the 2 paragraphs
that follow, but I still don't feel like these questions are completely
answered.
J: This is an application decision; in JSEP's opinion, forking should overall be avoided.
- Section 4.1.2, Paragraph 2
"the generated SDP will contain all desired functionality for the
session (certain parts that are supported but not desired by
default may be omitted)"
I think this sentence would be clearer if "certain parts that are" was
replaced with "functionality that is".
J: Agreed.
- Section 4.1.2, Paragraph 3
"For each existing stream, the generation of each SDP line must
follow the process defined for generating an updated offer from the
document that specifies the given SDP line."
This sentence was too hard to compute in my opinion, and I'm still not
quite sure what "the document" refers to. I think rewording would be
beneficial.
J: Agreed - refer to "the RFC" or somesuch
- Section 5.1.2, bullet R-2
"R-2 ICE, as specified in [RFC5245], MUST be used. Note that the
remote endpoint MAY use a Lite implementation."
This shouldn't be MAY because it is not referring to an optional
implementation specification of JSEP but rather a possible scenario that
JSEP needs to support. It should read as just a warning and possibly
specify that JSEP MUST be equipped to interface with an endpoint that is
using a Lite ICE implementation.
J: Agree. We'll adjust accordingly (MAY->may, MUST handle ice-lite)
" o The third SDP line MUST be a "s=" line, as specified in
[RFC4566], Section 5.3; to match the "o=" line, a single dash
SHOULD be used as the session name, e.g. "s=-"."
Is there a reason to ignore the following SHOULD from RFC4566?
"If a session has no meaningful name, the value "s= " SHOULD be
used (i.e., a single space as the session name)."
It seems like "-" and " " are both equally meaningless, so why deviate
from the standard? (I'm also not sure why we need to match it with the
username in the o= line). There may be good reason for both of these,
but it is not clear to me from reading the draft so I wanted to bring
it up.
J: It's entirely arbitrary. Since they are meaningless, I figured using similar meaningless values made this more clear than individual meaningless values. We can add some text to make this clear.
- Section 5.2.1, Paragraph 3
"The next step is to generate m= sections for each
MediaStreamTrack..."
Consider adding: "...as specified in [RFC4566] Section 5.14..." The
draft references specific sections for the other SDP fields and I think
it is useful here as well.
J: Sounds good.
- Section 5.2.3, Paragraph 1
"The createOffer method takes as a parameter a MediaConstraints
object. Special processing is performed when generating a SDP
description if the following constraints are present."
I think an example of when this would be useful might be nice for context.
J: I assume you are asking for when each of the individual constraints parameters would be useful. That sounds helpful. (also dictionary change)
- Section 5.2.3.1 AND Section 5.2.3.2, Paragraph 1
"If the "OfferToReceiveVideo" constraint is specified, with a value
of "N", the offer MUST include N non-rejected m= sections with
media type "video",... "
The use of "N" is confusing. Is "N" referencing an integer value or a
string with value "N". I think removing the quotes around "N" would make
it entirely more understandable.
J: Agreed. Constraints have been replaced with dictionaries, so we can clearly refer to this as an integer var.
- Section 5.3.1, Paragraph 5
"For each offered m= section of a given media type, if there is a
local MediaStreamTrack of the specified type which has been added
to the PeerConnection via addStream and not yet associated with a
m= section, and the specific m= section is either sendrecv or
recvonly, the MediaStreamTrack is associated with the m= section
at this time."
This sentence is long and hard to parse. I think rewording and/or
breaking up would be beneficial.
J: OK.