Re: [web-audio-api] The callbacks of the decodeAudioData API are underspecified (#189)

> [Original comment](https://www.w3.org/Bugs/Public/show_bug.cgi?id=20039#1) by Ehsan Akhgari [:ehsan] on W3C Bugzilla. Thu, 29 Nov 2012 16:26:13 GMT

(In reply to [comment #1](#issuecomment-24244733))
> (In reply to comment #0)
> > Here is a list of problems that come to my mind right now.
> > 
> > 1. It's not clear whether the callbacks have to be asynchronous or not.  For
> > example, if for some reason the implementation decides that it's unable to
> > decode the audio right away, should it just call the failure callback
> > directly, or call it the next time that the execution hits the event loop.
> 
> I'm not sure I completely understand the question.  The decoding is meant to
> be asynchronous, so in some sense will not happen "right away".  So neither
> the success nor the error callback will be called directly, but at some
> later time (a later time in the event loop).  The failure callback should be
> called if there is an actual error in the decoding, meaning that the audio
> data is not one of the known and supported formats (depending on what the
> user agent supports), or that the audio data is corrupt.

Let me clarify the question.  Consider this test case for example:

  var cx = new AudioContext();
  var buf = new Uint8Array(100);
  // buf is filled with zeros, and therefore, not a valid audio stream
  var decodeFailed = false;
  cx.decodeAudioData(buf.buffer, function(x) {
    }, function(x) {
      decodeFailed = true;
  });
  alert(decodeFailed);

The question is, should decodeFailed be true or false after the call to decodeAudioData.  The reason that I started to think about this is that in the Gecko implementation, we sniff the buffer synchronously as it's a relatively cheap operation, so in this case we will know immediately that the decoding operation will fail.  Now, we have the option of calling the failure callback immediately which means that decodeFailed will be true when decodeAudioData returns, or calling it the next time that we hit the event loop, which means that decodeFailed will be false when decodeAudioData returns.

> > 2. It's not clear what the AudioBuffer callback passed to the failure
> > callback should contain.  For example, if the audio's type cannot be
> > sniffed, what should be passed to the failure callback?  What if the source
> > buffer doesn't contain valid samples and the decoding operation fails
> > half-way?
> 
> I think it's best that there is *no* AudioBuffer in the failure case.

In that case, we need to change the Web IDL to offer two distinct callback types, like this:

  callback DecodeSuccessCallback = void (AudioBuffer decodedData);
  callback DecodeErrorCallback = void ();

  interface AudioContext {
    // ...
    void decodeAudioData(ArrayBuffer audioData,
                         DecodeSuccessCallback successCallback,
                         optional DecodeErrorCallback errorCallback);
    // ...
  };

I personally think that this makes way more sense.  Please let me know if you want me to change the Web IDL accordingly.  Thanks!

---
Reply to this email directly or view it on GitHub:
https://github.com/WebAudio/web-audio-api/issues/189#issuecomment-24244739