Re: Draft WebAudio API review text

Hi Janessa,


On Thu, Jul 18, 2013 at 10:06 AM, Janessa Det <jandet@gmail.com> wrote:

> Hi there.  As someone who has dug my fingers into working the Web Audio
> API quite a bit, and having given a talk at the end of last year related to
> this at EmpireJS (http://www.slideshare.net/janessadet/experiential-audio),
> I would first like to express that I greatly appreciate how thorough and
> on-point this feedback document is.  I wanted to highlight some of the
> points that I most strongly agree with as well as some feedback & humble
> suggestions that came to mind.
>
> 1) Constructibility
>
> I completely agree that constructability of the AudioNodes would be a huge
> win for making Web Audio more naturally expressible in JS.  As for the two
> options that you propose in your code snippets, the second is more
> compelling to me as it is far less verbose and a pattern that is commonly
> seen and used in JS.
>
> // An alternative that provides the context via the PannerNode ctor:
> AudioContext.prototype.createPanner = function() {
>     return new PannerNode({ context: this });
> };
>
> One of the things that I DO appreciate about the current specification,
> however, is that because of it's restrictiveness (nodes can ONLY be
> produced from an AudioContext), nodes are ensured to ALWAYS be linked to an
> AudioContext and will never be zombie nodes.  I think that defining the
> context as just another parameter in the instantiation object de-emphasizes
> this and new users may easily neglect to define the context if they choose
> to use constructors.  I think it would be clearer, and express a separation
> of concerns, to have something like this instead:
>
> var panner = new PannerNode(context, { panningModel: "equalpower", ... })
>
> The definition of the context is up-front and explicit to users and
> separates its assignment from the other node-specific parameters which
> follow.
>

I agree this is cleaner and that PannerNode's ctor should throw if context
is omitted.


> Also, are you also proposing here that I would be able to do something
> like the following?
>
> context.createPanner({ panningModel: "equalpower", ... });
>

That's a great idea! Adding it.


> If not, this would be more consistent/powerful in my opinion.
>

+1


> 2) ScriptProcessorNode improvements & "De-sugaring" the *Node Types (+
> test suites)
> YES & YES +1000
>
>
> 3) Default context
>
> I agree that there is much ambiguity around the idea of a "default
> context" and the interoperability between the <audio> element and the Web
> Audio API.  Clarification and access/clarity around the "default context"
> would help not only implementers to be consistent, but also help users to
> understand the relationship between the Web Audio API and the other parts
> of the web stack.
>

It really does indicate deep confusion to me: what does it mean to even
have a context? what IS it? what does it connect to? real hardware or
virtual hardawre? And how is that hardware addressed? Is it AudioContexts
all the way down? Actually, that'd be great: explaining the environment in
terms of AudioContext and reifying each Context as a node in a larger graph
would be hugely clarifying...but we're not there in this draft yet.


> 4) AudioNode connect chaining
>
> [Why doesn't AudioNode::connect() return the passed AudioNode destination?]
> I agree 100% with this..  Connecting nodes into an audio graph is VERY
> verbose and manual which also makes it easy to miss a connection in the
> graph.  Being able to chain would allow users to connect full paths which
> is far more expressive.
>

I feel like I don't have a great proposal here. Returning from connect
seems like it's not exactly what you want; although returning both and
allowing you to use destructuring in ES6 to get closer to the mark might be
better.


> 5) Parameters for connecting in/out
>
> I actually disagree on this point.  Adding parameters for connecting
> in/out nodes would provide multiple ways to connect the graph, which I
> think is unnecessary and will make it easy to connect up a graph
> incorrectly.  It is much clearer to create all of the nodes then build it
> explicitly with .connect.  If the connect methods are chainable as you
> propose, this would be sufficiently expressive to eliminate much of the
> pain/overhead of connecting up a graph that exists in the current
> specification.
>

Do you have some code snippets that show the verbosity? I'd like to work
with refactoring them to see how much better it can be.


> Also, if you are also proposing something like: context.createPanner({
> panningModel: "equalpower", ... }); (as I mentioned above)
> it would be far too cluttered to also add in in/out parameters into this
> mix and be more confusing than useful in my opinion.
>

Yeah, I played with that a bit and it didn't feel right.

Thanks so much for the careful read.