Re: Updates to Web Audio API editor's draft

On Tue, Apr 24, 2012 at 1:06 PM, Chris Rogers <crogers@google.com> wrote:

> Hey folks, I've recently updated the editor's draft of the Web Audio API:
> https://dvcs.w3.org/hg/audio/raw-file/tip/webaudio/specification.html
>
>
Here are a few comments/questions about this draft.

1.2:  The TODO after the diagram of a graph needs to be fixed.

3: "the end result is the same".  What does it mean to be the "same"?
 Bit-exact?  No perceptually audible difference?

4.1.1: "sample-frames per second".  Does "sample-frames" need to be defined?

4.1.2:  createBuffer says "An exception will be thrown...."  Does this mean
an exception MUST be thrown?  "will" is not one of the requirement level
keywords.

Same comment for createChannelSplitter, createChannelMerger, and
createWaveTable.  Is it required to throw an exception for invalid
parameter values?

4.2.2:  Are out-of-bounds values to connect and disconnect required to
throw exceptions?

4.5.1: Will the representation of units be specified?

4.8.1: "maximum value is currently 1 (but this is arbitrary and could be
increased)" should probably be changed since createDelayNode accepts an
optional max delay now.

4.10.1: "The noteOn() method causes a transition"  should probably say
"noteOn() and noteGrainOn() methods".

4.12:  What does it mean to be "invalid"?  Does this mean an exception must
be thrown if the number of input and output channels are both zero?  Or is
this an undefined situation?

In the description of the bufferSize attribute, it should probably say that
the bufferSize MUST be one of 256, 512, ..., etc. to match the description
in the paragraphs above.

4.14: For the attributes refDistance, maxDistance, rolloffFactor,
coneInnerAngle, coneOuterAngle, and coneOuterGain should the default values
be specified?  Or is it expected that all uses of an AudioPannerNode set
this to appropriate values before use?

Should there be a reference describing the coordinate system?

4.15.1:  Perhaps it would be beneficial to say 343.3 m/s is the approximate
speed of sound in air.

4.17:  Any limits on the size of the FFT? Or is this
implementation-dependent?  I think the spec should have at least a minimum
and maximum required sizes, with the implementation possibly allowing
smaller or larger sizes.

smoothingTimeConstant:  Does the smoothing need to be described in more
detail?  Without a description it seems impossible for an independent
implementation to reproduce the desired smoothing.

4.20:  Does the DynamicsCompressorNode need a more detailed description of
how it works?  (Perhaps beyond the scope of the spec?)

4.21.9:  It should probably be said that the lengths of magResponse and
phaseResponse should be the greater than or equal to the length of
frequencyHz.

4.24: I think the description of createWaveTable is better in this section
than in section 4.1.2, but it can go either way.

11: "The following algorithms can be implemented".  Does this mean they
MUST be implemented or SHOULD BE implemented?  Since section 4.14 didn't
say anything about the algorithms, I assume all three MUST be implemented.

14:  This section is empty.  Is that intentional or an oversight?



Finally, a more general question and comment.  I find it difficult to know
what is exactly part of the spec and what is not.  For example section 12
talks about motivation for using convolution.  That seems like it's not
really part of the spec.  This section also mentions two comand-line tools.
 Are these tools part of the spec?

It seems like sections 6 and later are not really part of the spec, but
general discussion, motivation, and options that were discussed during
standardization of the spec.  Are these really part of the spec?

Ray