SuperpoweredTrackLoader

What is the SuperpoweredTrackLoader?

SuperpoweredTrackLoader is a tool you can use to download and decode a remote audio file in a single easy step. It will automatically create a Worker (a background-thread) for the downloading and decoding process, so it doesn't put any load on the current Worker or the main thread. It can operate in Worker and Audio Worklet contexts as well.

The SuperpoweredTrackLoader wraps the HTTP fetching and decoding of the audio file into Superpowered's AudioInMemory format ready to be used with an AdvancedAudioPlayer class.

Under the hood, the SuperpoweredTrackLoader is using a Superpowered Decoder class which offers the following consistent codec support across all devices.

• Stereo or mono pcm WAV and AIFF (16-bit int, 24-bit int, 32-bit int or 32-bit IEEE float).
• MP3: MPEG-1 Layer III (sample rates: 32000 Hz, 44100 Hz, 48000 Hz). MPEG-2 Layer III is not supported (mp3 with sample rates below 32000 Hz).
• AAC or HE-AAC in M4A container (iTunes) or ADTS container (.aac).

The SuperpoweredTrackLoader will automatically create a Worker on another thread to download and decode the remote data so it does not put any work on the thread from which is was called. This is a clear performance advantage over the standard WebAudio APIs native decodeAudioData pattern.

You may find our Loading Audio guide useful as it walks you through every step required.

How to import

The SuperpoweredTrackLoader should be imported from where you are serving the Superpowered library within your application.

For example, at the top of your AudioWorkletProcessor script:

// This is pointing to a publically served library that the processor script can import via a HTTP get request
import { SuperpoweredWebAudio, SuperpoweredTrackLoader } from '/superpowered/SuperpoweredWebAudio.js';

Or from within you main Javascript application on the main thread:

// This is pointing to the bundled copy of superpowered in you main application source code
import { SuperpoweredWebAudio, SuperpoweredTrackLoader } from '/lib/superpowered/SuperpoweredWebAudio.js';

The SuperpoweredTrackLoader object exposes a single static method called downloadAndDecode, which you can call within you application from any scope.

From within an AudioWorkletProcessor

For example, when using SuperpoweredTrackLoader from within your AudioWorkletProcessor script which has an AdvancedAudioPlayer instance:

class YourSuperpoweredProcessor extends SuperpoweredWebAudio.AudioWorkletProcessor {
    ....

    // Called automatically by the parent class when the worklet is ready
    onReady() {
        this.player = new this.Superpowered.AdvancedAudioPlayer(this.samplerate, 2, 2, 0, 0.501, 2, false);
        this.loadTrackByUrl('./music/track.mp3');
    }

    loadTrackByUrl(url) {
        SuperpoweredTrackLoader.downloadAndDecode(url, this);
        // the second argument 'this' refers to the YourSuperpoweredProcessor class, it will automatically call the onMessageFromMainScope method unless overridden by passing in a reference to a function.
    }


    onMessageFromMainScope(message) {
        if (message.SuperpoweredLoaded) {
            // SuperpoweredLoaded is a special message type which will always represent the SuperpoweredTrackLoader having fetched and decoded an asset.
            let buffer = message.SuperpoweredLoaded.buffer; // ArrayBuffer with the downloaded and decoded audio in AudioInMemory format.
            let url = message.SuperpoweredLoaded.url; // The url of the audio file ('./music/track.mp3' in this example).

            // Now we have the audio buffer we can use it to load audio into our player class.
            this.player.openMemory(this.Superpowered.arrayBufferToWASM(buffer), false, false);
            this.player.play();
        }
    }

    processAudio(inputBuffer, outputBuffer, buffersize) {
        if (!this.player.processStereo(outputBuffer.pointer, false, buffersize, 1)) {
            // return 0's if the player has no audio buffer loaded
            this.Superpowered.memorySet(outputBuffer.pointer, 0, buffersize * 8); // 8 bytes for each frame (1 channel is 4 bytes)
        }
    }

    ....
}

From within a Worker

Use this syntax within a regular Worker:

...

self.onmessage = function(message) {
    if (message.SuperpoweredLoaded) {
        let buffer = message.SuperpoweredLoaded.buffer; // ArrayBuffer with the downloaded and decoded audio in AudioInMemory format.
        let url = message.SuperpoweredLoaded.url;       // The url of the audio file ('./music/track.mp3' in this example).

        // Player example loading the contents of the buffer:
        this.player.openMemory(this.Superpowered.arrayBufferToWASM(buffer), false, false);
    }
}  

SuperpoweredTrackLoader.downloadAndDecode('./music/track.mp3', self.onmessage);
...

Static Methods

• downloadAndDecode

  METHOD

  Spins up a Worklet to fetch the url provided and then decodes automatically.

  Parameters

  Name	Type	Description
  url	Number	The remote url of the audio asset the Worker should fetch.
  handler	Number	A reference to the AudioWorklet instance or Worker handler to be called when fetching and decoding completed.

  Returns

  None