Review of gUM, intro parts

I've reviewed the latest version of the spec that I could find.  Git
revision: 6a8204381e61659c37b96f60145db41616864ce7

This is mostly just editorial stuff.  There are cases where the text
is misleading, but none of the changes I propose are substantive in
the sense that they change the meaning of anything.  Of course, I
might get things wrong.

So far, I'm going to reserve judgment about whether this is fit for
human consumption.

Warnings:
1. Found linkless <a> element with text 'setting' but no matching <dfn>.
Errors:
1. Duplicate definition of 'getusermedia()'
2. Duplicate definition of 'settings'

I remember discussing a fix with fluffy about this, but I can't see
the PR or any merged commits.

Section 1.

"Access to multimedia streams (video, audio, or both)" - what about depth?

"video cameras, microphones, Web cams" - are Web cams something special?

"surveillance" - I like that this is a motivating use case.  That sort
of highlights how important context can be, as is proper
authorization.

Suggestion: Roll the examples into the second paragraph:
"This document defines APIs for requesting access to local multimedia
devices, such as microphones or video cameras."

"This document also defines the MediaStream API by which JavaScript is
able to manipulate the stream data or otherwise process it."

Maybe:
"This document also defines the MediaStream API, which provides the
means to control where multimedia stream data is consumed, and
provides some control over the devices that produce the media."

All the actual manipulation occurs in other places, like WebAudio.  No
point in overselling the capabilities of the API.  That is more than
enough.

PR: https://github.com/w3c/mediacapture-main/pull/53


Section 3.

"Other than the source identifier (defined in
MediaDeviceInfo.deviceId), other bits of source identity are never
directly available to the application until the user agent connects a
source to a track. Once a source has been "released" to the
application (either via a permissions UI, pre-configured allow-list,
or some other release mechanism) the application will be able discover
additional source-specific capabilities."

This is not entirely correct and it could be misleading.  We use
access to any source as a signal that some limited information
(labels, for example) are safe to release.  I think that the
appropriate thing to do here would be to note as follows:
"An application that has no prior authorization regarding sources is
only given the number of available sources, their type and any
relationship to other devices.  Additional information about sources
can become available as applications are authorized to use a source
(see 9.2.3 Access control model)."

PR: https://github.com/w3c/mediacapture-main/pull/56

"Sources do not have constraints -- tracks have constraints. When a
source is connected to a track, it must, possibly in combination with
UA processing (e.g., downsampling), conform to the constraints present
on that track (or set of tracks)."

is imprecise.  I think this is better:

"Sources do not have constraints — tracks have constraints. When a
source is connected to a track, it must produce media that conforms to
the constraints present on that track. Multiple tracks can be attached
to the same source. UA processing, such as downsampling, MAY be used
to ensure that all tracks have appropriate media."

PR: https://github.com/w3c/mediacapture-main/pull/57

"On the MediaStreamTrack object, sources are represented by a
sourceType attribute. The behavior of APIs associated with the
source's capabilities and settings change depending on the source
type."

This is monstrously confusing.  I read this as implying that there is
a sourceType attribute on MediaStreamTrack, which there is not.  I
don't know how to recover this paragraph.

PR: https://github.com/w3c/mediacapture-main/pull/58

"A source's settings must always conform to the current set of
mandatory constraints that all of the tracks it is bound to have
defined, and should do its best to conform to the set of optional
constraints specified."

Suggest:
"A source that cannot conform to mandatory constraints causes affected
tracks to become muted. A user agent attempts to ensure that sources
adhere to optional constraints as closely as possible, see 11.
Constrainable Pattern."

PR: https://github.com/w3c/mediacapture-main/pull/59

Capabilities doesn't describe the intentional limitation in
expressiveness, which I think is important to capture.  If only so we
don't have to entertain proposals containing new and wonderful
capability expression languages.

PR: https://github.com/w3c/mediacapture-main/pull/60

"Constraints are an optional track feature for restricting the range
of allowed variability on a source"

Optional?  I think not.  At least not in the general sense.  And
"range of allowed variability" is right, but it doesn't seem right.
Constraints serve two purposes: selecting a source that can produce
media that conforms to the described restrictions, and influencing the
operating mode of that source to most closely match a desired setting.

I found this entire description to be a little hard to follow, so I'm
going to propose a rewrite.

"""
Constraints provide a general control surface that allow applications
to both select an appropriate source for a track and—once selected—to
influence how a source operates.

Constraints limit the range of operating modes that a source can use
when providing media for a track. Without provided track constraints,
implementations are free to select a source's settings from the full
ranges of its supported capabilities, and to adjust those settings at
any time within the bounds imposed by constraints.

getUserMedia() uses constraints to aid in the selection of an
appropriate source for a track. Constraints are then exposed on tracks
via the ConstrainablePattern interface, which includes an API for
dynamically changing constraints from the initial value determined by
getUserMedia().

A track cannot be connected to a source using getUserMedia() if
constraints cannot be met. However, the ability to meet the
constraints on a track can change over time, and constraints can be
changed. If circumstances change such that constraints cannot be met,
a track becomes muted. On the other hand, constraints that cannot be
met, or constraints that conflict with constraints on other tracks
result in errors. 5. The model: sources, sinks, constraints, and
settings explains how constraints interact in more detail.

In general, user agents will have more flexibility to optimize the
media streaming experience the fewer constraints are applied, so
application authors are strongly encouraged to use mandatory
constraints sparingly.

For each constraint that is understood by the user agent, a setting
and capability exist with the same name.
"""

PR: https://github.com/w3c/mediacapture-main/pull/61

Received on Wednesday, 5 November 2014 21:41:45 UTC