Extending Aurora

Aurora is designed to be very easily extendible. You can add new Sources, Demuxers, Decoders and even AudioDevices to the framework in order to extend its functionality. This guide will cover the common tasks of adding a Demuxer and Decoder to the framework. For the others, see their respective class references.

Writing A Demuxer

Demuxers are responsible for decoding the container format and extracting format information, duration information, metadata, and actual audio data from the file.

Writing a demuxer involves extending the AV.Demuxer class, unsurprisingly. To do this, you must implement two methods: probe and readChunk. probe is a class level method that determines whether or not a given audio file is of the format supported by the demuxer. readChunk is the main decoding function for the demuxer. It is responsible for emitting a number of events containing the format, duration, metadata, and actual audio data. Most demuxers will use the AV.Stream class to read the data from the binary stream.

Let's write a simple probe method for the WAVE format:

var MyDemuxer = AV.Demuxer.extend(function() {
  AV.Demuxer.register(this);

  this.probe = function(stream) {
    return stream.peekString(0, 4) === 'RIFF' && 
           stream.peekString(8, 4) === 'WAVE';
  }

});

Writing the actual demuxing readChunk function is much more complicated. Keep in mind that not all of the file will have been received yet at the time readChunk is called, so you may need to wait until the next readChunk call in order to read an entire data structure. Checking whether enough data is available using the stream.available method will be helpful to you.

You must emit several events from the readChunk function, including format, duration, metadata, cookie, and data. See the AV.Demuxer class reference for details.

The full source code to the WAVE demuxer can be found here.

Writing a decoder

Writing a decoder is in many ways much more complicated than writing a demuxer. Generally, we follow several implementations in other languages in order to implement our decoder. You must provide a readChunk method for your decoder, which is responsible for returning decoded raw LPCM audio data. You can also implement the setCookie method if you expect a "magic cookie" or decoder specific chunk to be embedded in the container format, and the init method to perform any initialization. If an error occurs during decoding, you should throw an Error object, and the decoder class will handle emitting it and stopping the decoding process.

See the AV.Decoder class reference for more details, and check out some of our decoders as examples.