RE: Draft WebAudio API review text

This is lovely. Go TAG!!

Here are some small editorial critiques I think would make the feedback more effective:

- It might be helpful to show code written "after the fixes." E.g., show code that uses the proposed `PannerNode` constructor directly, in addition to showing the desugaring of `createPannerNode` in terms of it. Or code that uses the promise version of `decodeAudioData` directly, instead of the callback version desugared in terms of an internal promise version. For that last one, a compelling example might be doing multiple decodings at once with `Promise.every`, similar to the HTML5 spec's recently-added example for `createImageBitmap`.

- The layering section starts strong by talking about the connection between `<audio>` and web audio. But the bullet-pointed questions start talking about a bunch of stuff related to multiple contexts and hardware, and the connection there is hard to follow. Worse, it's not clear that these questions are answered by the following proposed redesign. Basically this section lost me---which might just be me not knowing the source material well enough, but might indicate it needs a bit more editorial and cohesiveness work.

- The "Other Considerations" section could also benefit from some "after" code; right now it contains the awkward "before" code, but doesn't quite show what the world would look like with the API fixed.

Finally, one potential additional spec improvement:

- It seems like there are many other opportunities for using promises to replace one-off events. For example, OfflineAudioContext and, I believe, the onended events. I admit I might not completely understanding how these work though, so promises might not apply there.

Received on Thursday, 18 July 2013 15:46:04 UTC