Class: Decoder

Overview

Audio file decoder. Provides raw PCM audio and metadata from various compressed formats.

The Superpowered decoder is independent from the standard decodeAudioData Web Audio API, which means it has identical codec support across web browsers. The Decoder can be used in Workers and Worklets too which allow for multiple threaded decoding, preventing blocking in the main thread.

Alternatively, if you'd like to fetch audio and decode in one step then please see:


Supported file formats

  • 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).
iOS, macOS and tvOS: ALAC/Apple Lossless support.

How to implement

// Decodes an entire audio file in memory to AudioInMemory format in a single call. The output can be loaded by the AdvancedAudioPlayer.
let pointerToAudioInMemory = Superpowered.Decoder.decodeToAudioInMemory(
pointer, // Pointer to an audio file loaded onto the WebAssembly Linear Memory.
1000000 // The audio file length in bytes.
);
// Constructor. Has no additional parameters.
let decoder = new Superpowered.Decoder();
// Opens a memory location in Superpowered AudioInMemory format for decoding.
let openErrorCode = decoder.openMemory(
pointer, // Pointer to information in Superpowered AudioInMemory format on the WebAssembly Linear Memory.
false // If true, it opens the file for fast metadata reading only, not for decoding audio.
);
// Opens a memory location for decoding.
let openErrorCode = decoder.openAudioFileInMemory(
pointer, // Pointer to an audio file loaded onto the WebAssembly Linear Memory.
1000000, // The audio file length in bytes.
false // If true, it opens the file for fast metadata reading only, not for decoding audio.
);
// Error codes for the openMemory() method:
Superpowered.Decoder.OpenSuccess;
Superpowered.Decoder.OpenError_OutOfMemory; // Some memory allocation failed. Recommended action: check for memory leaks.
Superpowered.Decoder.OpenError_PathIsNull; // Path is NULL.
Superpowered.Decoder.OpenError_ID3VersionNotSupported; // ID3 version 2.2, 2.3 and 2.4 are supported only.
Superpowered.Decoder.OpenError_ID3ReadError; // File read error while reading the ID3 tag.
Superpowered.Decoder.OpenError_FileFormatNotRecognized; // The decoder is not able to decode this file format.
Superpowered.Decoder.OpenError_FileTooShort; // The file has just a few bytes of data.
Superpowered.Decoder.OpenError_ImplementationError0; // Should never happen. But if it does, please let us know.
Superpowered.Decoder.OpenError_ImplementationError1; // Should never happen. But if it does, please let us know.
Superpowered.Decoder.OpenError_ImplementationError2; // Should never happen. But if it does, please let us know.
// Returns with a human readable error string.
let pointer = Superpowered.Decoder.statusCodeToString(
openErrorCode // The error code.
)
// Returns with how many frames are in one chunk of the source file. For example: MP3 files store 1152 audio frames in a chunk.
let fc = decoder.getFramesPerChunk();
// Decodes audio.
let decodeErrorCode = decoder.decodeAudio(
pointer, // Pointer to 16-bit signed integer numbers. The output. Must be at least numberOfFrames * 4 + 16384 bytes big.
fc // The requested number of frames. Should NOT be less than the value returned by getFramesPerChunk().
);
// Error codes for the decodeAudio(), getAudioStartFrame() and getAudioEndFrame() methods:
Superpowered.Decoder.EndOfFile; // End-of-file reached.
Superpowered.Decoder.BufferingTryAgainLater; // Buffering (waiting for the network to pump enough data).
Superpowered.Decoder.Error; // Decoding error.
// Returns with the duration of the current file in frames.
// Duration may change after each decode() or seekTo(), because some audio formats doesn't contain precise length information.
let df = decoder.getDurationFrames();
// Returns with the duration of the current file in seconds.
// Duration may change after each decode() or seekTo(), because some audio formats doesn't contain precise length information.
let ds = decoder.getDurationSeconds();
// Returns with the current position in frames. The postion may change after each decode() or seekTo().
let pos = decoder.getPositionFrames();
// Returns with the sample rate of the current file.
let sr = decoder.getSamplerate();
// Returns with the format of the current file.
let f = decoder.getFormat();
// File/decoder formant constants:
Superpowered.Decoder.Format_MP3; // MP3
Superpowered.Decoder.Format_AAC; // AAC, HE-AAC
Superpowered.Decoder.Format_AIFF; // AIFF
Superpowered.Decoder.Format_WAV; // WAV
// Jumps to the specified position's chunk (frame) beginning.
// Some codecs (such as MP3) contain audio in chunks (frames). This method will not jump precisely to the specified position, but to the chunk's beginning the position belongs to.
// Returns with success (true) or failure (false).
let success = decoder.setPositionQuick(
10052 // The requested position in frames.
);
// Jumps to a specific position. This method is a little bit slower than setPositionQuick().
// Returns with success (true) or failure (false).
let success = decoder.setPositionPrecise(
10052 // The requested position in frames.
);
// Detects silence at the beginning. This function changes the position!
// The return value can be:
// - A positive number or zero: the frame index where audio starts.
// - Superpowered.Decoder.BufferingTryAgainLater: the decoder needs more data to be downloaded. Retry getAudioStartFrame() or getAudioEndFrame() later (it's recommended to wait at least 0.1 seconds).
// - Superpowered.Decoder.NetworkError: network (download) error.
// - Superpowered.Decoder.Error: internal decoder error.
let start = decoder.getAudioStartFrame(
0, // Limit frames. How far to search for. 0 means "the entire audio file".
0 // Loudness threshold in decibel. 0 means "any non-zero audio". The value -49 is useful for vinyl rips having vinyl noise (crackles).
);
// Detects silence at the end. This function changes the position!
// The return value can be:
// - A positive number or zero: the frame index where audio ends.
// - Superpowered.Decoder.BufferingTryAgainLater: the decoder needs more data to be downloaded. Retry getAudioEndFrame() later (it's recommended to wait at least 0.1 seconds).
// - Superpowered.Decoder.NetworkError: network (download) error.
// - Superpowered.Decoder.Error: internal decoder error.
let end = decoder.getAudioEndFrame(
0, // Limit frames. How far to search for from the end (the duration in frames). 0 means "the entire audio file".
0 // Loudness threshold in decibel. 0 means "any non-zero audio". The value -49 is useful for vinyl rips having vinyl noise (crackles).
);
#include "SuperpoweredDecoder.h"
// Decodes an entire audio file in memory to AudioInMemory format in a single call. The output can be loaded by the AdvancedAudioPlayer.
void *pointerToAudioInMemory = Superpowered::Decoder::decodeToAudioInMemory(
pointer, // Pointer to an audio file loaded into the memory.
1000000 // The audio file length in bytes.
);
// Constructor. Has no additional parameters.
Superpowered::Decoder *decoder = new Superpowered::Decoder();
// Opens a memory location in Superpowered AudioInMemory format for decoding.
int openErrorCode = decoder->openMemory(
pointer, // Pointer to information in Superpowered AudioInMemory format
false // If true, it opens the file for fast metadata reading only, not for decoding audio.
);
// Opens a memory location for decoding.
int openErrorCode2 = decoder->openAudioFileInMemory(
pointer, // Pointer to an audio file loaded into memory
1000000, // The audio file length in bytes.
false // If true, it opens the file for fast metadata reading only, not for decoding audio.
);
// Returns with a human readable error string.
const char *errorString = Superpowered::Decoder::statusCodeToString(
openErrorCode // The error code.
);
// Returns with how many frames are in one chunk of the source file. For example: MP3 files store 1152 audio frames in a chunk.
int fc = decoder->getFramesPerChunk();
// Decodes audio.
int decodeErrorCode = decoder->decodeAudio(
pointer2, // Pointer to 16-bit signed integer numbers. The output. Must be at least numberOfFrames * 4 + 16384 bytes big.
fc // The requested number of frames. Should NOT be less than the value returned by getFramesPerChunk().
);
// Returns with the duration of the current file in frames.
// Duration may change after each decode() or seekTo(), because some audio formats doesn't contain precise length information.
int df = decoder->getDurationFrames();
// Returns with the duration of the current file in seconds.
// Duration may change after each decode() or seekTo(), because some audio formats doesn't contain precise length information.
double ds = decoder->getDurationSeconds();
// Returns with the current position in frames. The postion may change after each decode() or seekTo().
int pos = decoder->getPositionFrames();
// Returns with the sample rate of the current file.
unsigned int sr = decoder->getSamplerate();
// Returns with the format of the current file.
Superpowered::Decoder::Format f = decoder->getFormat();
// Jumps to the specified position's chunk (frame) beginning.
// Some codecs (such as MP3) contain audio in chunks (frames). This method will not jump precisely to the specified position, but to the chunk's beginning the position belongs to.
// Returns with success (true) or failure (false).
bool success = decoder->setPositionQuick(
10052 // The requested position in frames.
);
// Jumps to a specific position. This method is a little bit slower than setPositionQuick().
// Returns with success (true) or failure (false).
bool success2 = decoder->setPositionPrecise(
10052 // The requested position in frames.
);
// Detects silence at the beginning. This function changes the position!
// The return value can be:
// - A positive number or zero: the frame index where audio starts.
// - Superpowered.Decoder.BufferingTryAgainLater: the decoder needs more data to be downloaded. Retry getAudioStartFrame() or getAudioEndFrame() later (it's recommended to wait at least 0.1 seconds).
// - Superpowered.Decoder.NetworkError: network (download) error.
// - Superpowered.Decoder.Error: internal decoder error.
int start = decoder->getAudioStartFrame(
0, // Limit frames. How far to search for. 0 means "the entire audio file".
0 // Loudness threshold in decibel. 0 means "any non-zero audio". The value -49 is useful for vinyl rips having vinyl noise (crackles).
);
// Detects silence at the end. This function changes the position!
// The return value can be:
// - A positive number or zero: the frame index where audio ends.
// - Superpowered.Decoder.BufferingTryAgainLater: the decoder needs more data to be downloaded. Retry getAudioEndFrame() later (it's recommended to wait at least 0.1 seconds).
// - Superpowered.Decoder.NetworkError: network (download) error.
// - Superpowered.Decoder.Error: internal decoder error.
int end = decoder->getAudioEndFrame(
0, // Limit frames. How far to search for from the end (the duration in frames). 0 means "the entire audio file".
0 // Loudness threshold in decibel. 0 means "any non-zero audio". The value -49 is useful for vinyl rips having vinyl noise (crackles).
);

Accessing metadata

// Parses all ID3 frames. Do not use startReadingID3/readNextID3Frame after this.
decoder.parseAllID3Frames(
true, // Parsing ID3 image frames is significantly slower than parsing other frames. Set this to true if not interested in image information to save CPU.
16384, // The maximum frame size in bytes to retrieve if the decoder can not memory map the entire audio file. Affects memory usage. Useful to skip large payloads (such as images).
);
// Starts reading ID3 frames. Use readNextID3Frame() in an iteration after this.
decoder.startParsingID3Frames(
true, // Parsing ID3 image frames is significantly slower than parsing other frames. Set this to true if not interested in image information to save CPU.
16384, // The maximum frame size in bytes to retrieve if the decoder can not memory map the entire audio file. Affects memory usage. Useful to skip large payloads (such as images).
);
// Reads the next ID3 frame and returns with its data size or -1 if finished reading.
let frameSizeBytes = decoder.readNextID3Frame();
// Returns with the current ID3 frame name (four char). To be used with readNextID3Frame().
let frameName = decoder.getID3FrameName();
// Returns with the raw data of the current ID3 frame. To be used with readNextID3Frame().
let pointerToFrame = decoder.getID3FrameData();
// Returns with the current ID3 frame data length.
let frameDataLengthBytes = decoder.getID3FrameDataLengthBytes();
// Returns with the text inside the current ID3 frame. To be used with readNextID3Frame(). Use it for frames containing text only!
// Returns a pointer to the text in UTF-8 encoding (you take ownership on the data, don't forget to free() when done to prevent memory leaks), or NULL if empty.
let pointer = decoder.getID3FrameAsString(
0 // Offset. Parse from this byte index.
);
// Returns with the contents "best" artist tag (TP1-4, TPE1-4, QT atoms). May return NULL.
// Call this after parseAllID3Frames() OR finished reading all ID3 frames with readNextID3Frame().
let pointer = decoder.getArtist(
false // Take ownership. For advanced use. If true, you take ownership on the data (don't forget to free() when done to prevent memory leaks).
);
// Returns with the contents "best" title tag (TT1-3, TIT1-3, QT atoms). May return NULL.
// Call this after parseAllID3Frames() OR finished reading all ID3 frames with readNextID3Frame().
let pointer = decoder.getTitle(
false // Take ownership. For advanced use. If true, you take ownership on the data (don't forget to free() when done to prevent memory leaks).
);
// Returns with the contents of the TALB tag (or QT atom). May return NULL.
// Call this after parseAllID3Frames() OR finished reading all ID3 frames with readNextID3Frame().
let pointer = decoder.getAlbum(
false // Take ownership. For advanced use. If true, you take ownership on the data (don't forget to free() when done to prevent memory leaks).
);
// Returns with the track index (track field or TRCK).
// Call this after parseAllID3Frames() OR finished reading all ID3 frames with readNextID3Frame().
let ti = decoder.getTrackIndex();
// Returns with the contents "best" image tag (PIC, APIC, QT atom). May return NULL.
// Call this after parseAllID3Frames() OR finished reading all ID3 frames with readNextID3Frame().
let pointer = decoder.getImage(
false // Take ownership. For advanced use. If true, you take ownership on the data (don't forget to free() when done to prevent memory leaks).
);
// Returns with the the size of the image returned by getImage(). May return NULL.
// Call this after parseAllID3Frames() OR finished reading all ID3 frames with readNextID3Frame().
let imageSizeBytes = decoder.getImageSizeBytes();
// Returns with the bpm value of the "best" bpm tag (TBP, TBPM, QT atom). May return 0.
// Call this after parseAllID3Frames() OR finished reading all ID3 frames with readNextID3Frame().
let bpm = decoder.getBPM();
// Parses all ID3 frames. Do not use startReadingID3/readNextID3Frame after this.
decoder->parseAllID3Frames(
true, // Parsing ID3 image frames is significantly slower than parsing other frames. Set this to true if not interested in image information to save CPU.
16384 // The maximum frame size in bytes to retrieve if the decoder can not memory map the entire audio file. Affects memory usage. Useful to skip large payloads (such as images).
);
// Starts reading ID3 frames. Use readNextID3Frame() in an iteration after this.
decoder->startParsingID3Frames(
true, // Parsing ID3 image frames is significantly slower than parsing other frames. Set this to true if not interested in image information to save CPU.
16384 // The maximum frame size in bytes to retrieve if the decoder can not memory map the entire audio file. Affects memory usage. Useful to skip large payloads (such as images).
);
// Reads the next ID3 frame and returns with its data size or -1 if finished reading.
unsigned int frameSizeBytes = decoder->readNextID3Frame();
// Returns with the current ID3 frame name (four char). To be used with readNextID3Frame().
unsigned int frameName = decoder->getID3FrameName();
// Returns with the raw data of the current ID3 frame. To be used with readNextID3Frame().
void *pointerToFrame = decoder->getID3FrameData();
// Returns with the current ID3 frame data length.
unsigned int frameDataLengthBytes = decoder->getID3FrameDataLengthBytes();
// Returns with the text inside the current ID3 frame. To be used with readNextID3Frame(). Use it for frames containing text only!
// Returns a pointer to the text in UTF-8 encoding (you take ownership on the data, don't forget to free() when done to prevent memory leaks), or NULL if empty.
char *frame = decoder->getID3FrameAsString(
0 // Offset. Parse from this byte index.
);
// Returns with the contents "best" artist tag (TP1-4, TPE1-4, QT atoms). May return NULL.
// Call this after parseAllID3Frames() OR finished reading all ID3 frames with readNextID3Frame().
char *artist = decoder->getArtist(
false // Take ownership. For advanced use. If true, you take ownership on the data (don't forget to free() when done to prevent memory leaks).
);
// Returns with the contents "best" title tag (TT1-3, TIT1-3, QT atoms). May return NULL.
// Call this after parseAllID3Frames() OR finished reading all ID3 frames with readNextID3Frame().
char *title = decoder->getTitle(
false // Take ownership. For advanced use. If true, you take ownership on the data (don't forget to free() when done to prevent memory leaks).
);
// Returns with the contents of the TALB tag (or QT atom). May return NULL.
// Call this after parseAllID3Frames() OR finished reading all ID3 frames with readNextID3Frame().
char *album = decoder->getAlbum(
false // Take ownership. For advanced use. If true, you take ownership on the data (don't forget to free() when done to prevent memory leaks).
);
// Returns with the track index (track field or TRCK).
// Call this after parseAllID3Frames() OR finished reading all ID3 frames with readNextID3Frame().
unsigned int ti = decoder->getTrackIndex();
// Returns with the contents "best" image tag (PIC, APIC, QT atom). May return NULL.
// Call this after parseAllID3Frames() OR finished reading all ID3 frames with readNextID3Frame().
void *image = decoder->getImage(
false // Take ownership. For advanced use. If true, you take ownership on the data (don't forget to free() when done to prevent memory leaks).
);
// Returns with the the size of the image returned by getImage(). May return NULL.
// Call this after parseAllID3Frames() OR finished reading all ID3 frames with readNextID3Frame().
unsigned int imageSizeBytes = decoder->getImageSizeBytes();
// Returns with the bpm value of the "best" bpm tag (TBP, TBPM, QT atom). May return 0.
// Call this after parseAllID3Frames() OR finished reading all ID3 frames with readNextID3Frame().
float bpm = decoder->getBPM();

Clearing up memory

// Destructor (to free up memory).
decoder.destruct();
delete decoder;

Constants

  • Superpowered.Decoder

    CONSTANTS
    Constants in the main Decoder namespace.
    ValueDescription
    Format_MP3MP3
    Format_AACAAC, HE-AAC.
    Format_AIFFAIFF
    Format_WAVWAV
    Format_MediaServerOther format decoded by iOS, macOS or tvOS.
    Format_HLSHTTP Live Streaming.
    EndOfFileEnd-of-file reached.
    BufferingTryAgainLaterBuffering (waiting for the network to pump enough data).
    NetworkErrorNetwork (download) error.
    ErrorDecoding error.
    OpenSuccessOpened successfully.
    OpenError_OutOfMemorySome memory allocation failed. Recommended action: check for memory leaks.
    OpenError_PathIsNullPath is NULL.
    OpenError_FastMetadataNotLocalmetaOnly was true, but it works on local files only.
    OpenError_ID3VersionNotSupportedID3 version 2.2, 2.3 and 2.4 are supported only.
    OpenError_ID3ReadErrorFile read error while reading the ID3 tag.
    OpenError_FileFormatNotRecognizedThe decoder is not able to decode this file format.
    OpenError_FileOpenErrorSuch as fopen() failed. Recommended action: check if the path and read permissions are correct.
    OpenError_FileLengthErrorSuch as fseek() failed. Recommended action: check if read permissions are correct.
    OpenError_FileTooShortThe file has just a few bytes of data.
    OpenError_AppleAssetFailedThe Apple system codec could not create an AVURLAsset on the resource. Wrong file format?
    OpenError_AppleMissingTracksThe Apple system codec did not found any audio tracks. Wrong file format?
    OpenError_AppleDecodingThe Apple system codec could not get the audio frames. Wrong file format?
    OpenError_ImplementationError0Should never happen. But if it does, please let us know.
    OpenError_ImplementationError1Should never happen. But if it does, please let us know.
    OpenError_ImplementationError2Should never happen. But if it does, please let us know.
    OpenError_UseSetTempFolderCall AdvancedAudioPlayer.setTempFolder first.
  • Superpowered::Decoder

    CONSTANTS
    Constants in the main Decoder namespace.
    ValueDescription
    Format_MP3MP3
    Format_AACAAC, HE-AAC.
    Format_AIFFAIFF
    Format_WAVWAV
    Format_MediaServerOther format decoded by iOS, macOS or tvOS.
    Format_HLSHTTP Live Streaming.
    EndOfFileEnd-of-file reached.
    BufferingTryAgainLaterBuffering (waiting for the network to pump enough data).
    NetworkErrorNetwork (download) error.
    ErrorDecoding error.
    OpenSuccessOpened successfully.
    OpenError_OutOfMemorySome memory allocation failed. Recommended action: check for memory leaks.
    OpenError_PathIsNullPath is NULL.
    OpenError_FastMetadataNotLocalmetaOnly was true, but it works on local files only.
    OpenError_ID3VersionNotSupportedID3 version 2.2, 2.3 and 2.4 are supported only.
    OpenError_ID3ReadErrorFile read error while reading the ID3 tag.
    OpenError_FileFormatNotRecognizedThe decoder is not able to decode this file format.
    OpenError_FileOpenErrorSuch as fopen() failed. Recommended action: check if the path and read permissions are correct.
    OpenError_FileLengthErrorSuch as fseek() failed. Recommended action: check if read permissions are correct.
    OpenError_FileTooShortThe file has just a few bytes of data.
    OpenError_AppleAssetFailedThe Apple system codec could not create an AVURLAsset on the resource. Wrong file format?
    OpenError_AppleMissingTracksThe Apple system codec did not found any audio tracks. Wrong file format?
    OpenError_AppleDecodingThe Apple system codec could not get the audio frames. Wrong file format?
    OpenError_ImplementationError0Should never happen. But if it does, please let us know.
    OpenError_ImplementationError1Should never happen. But if it does, please let us know.
    OpenError_ImplementationError2Should never happen. But if it does, please let us know.
    OpenError_UseSetTempFolderCall AdvancedAudioPlayer::setTempFolder first.

Static Methods

  • decodeToAudioInMemory

    METHOD
    Decodes an entire audio file in memory to AudioInMemory format in a single call. The output can be loaded by the AdvancedAudioPlayer.
    Parameters
    NameTypeDescription
    pointerNumber (pointer in Linear Memory)Pointer to an audio file loaded onto the WebAssembly Linear Memory. The Decoder will free() this data.
    sizeBytesNumberThe audio file length in bytes.
    Returns
    TypeDescription
    Number (pointer in Linear Memory)Linear Memory pointer or 0 on error.
  • decodeToAudioInMemory

    METHOD
    Decodes an entire audio file in memory to AudioInMemory format in a single call. The output can be loaded by the AdvancedAudioPlayer.
    Parameters
    NameTypeDefaultDescription
    pointervoid *Pointer to an audio file loaded onto the heap. Should be allocated using malloc() (and not _aligned_malloc() or similar). The Decoder will free() this data.
    sizeBytesunsigned intThe audio file length in bytes.
    Returns
    TypeDescription
    void *Pointer or NULL on error.
  • statusCodeToString

    METHOD
    Returns with a human readable error string.
    Parameters
    NameTypeDescription
    codeNumberThe return value of the open...() method.
    Returns
    TypeDescription
    Number (pointer in Linear Memory)You can use Superpowered.toString(this_pointer) to create a JavaScript string from it.
  • statusCodeToString

    METHOD
    Returns with a human readable error string.
    Parameters
    NameTypeDefaultDescription
    codeintThe return value of the open...() method.
    Returns
    TypeDescription
    const char *A human readable error string.

Properties

HLSAutomaticAlternativeSwitching

PROPERTY
If true, then the decoder will automatically switch between the HLS alternatives according to the available network bandwidth.
TypeMinMaxDefault
bool
true

HLSBufferingSeconds

PROPERTY
How many seconds ahead of the playback position to download.
TypeMinMaxDefault
int
HLS_DOWNLOAD_REMAINING

HLSMaximumDownloadAttempts

PROPERTY
How many times to retry if a HLS segment download fails.
TypeMinMaxDefault
int
100

Methods

  • constructor

    METHOD
    Creates an instance of the Decoder class.
    Parameters
    None
    Returns
    TypeDescription
    Superpowered.DecoderThe constructed instance.
  • constructor

    METHOD
    Creates an instance of the Decoder class.
    Parameters
    None
    Returns
    TypeDescription
    Superpowered::DecoderThe constructed instance.
  • decodeAudio

    METHOD
    Decodes audio.
    Parameters
    NameTypeDescription
    outputNumber (pointer in Linear Memory)Allocated memory to store the output. Must be at least numberOfFrames * 4 + 16384 bytes big.
    numberOfFramesNumberThe requested number of frames. Should NOT be less than the value returned by getFramesPerChunk().
    Returns
    TypeDescription
    Number
    • A positive number above zero: the number of frames decoded.
    • Decoder.EndOfFile: end of file reached, there is nothing more to decode. Use setPosition.
    • Decoder.BufferingTryAgainLater: the decoder needs more data to be downloaded. Retry decodeAudio() later (it's recommended to wait at least 0.1 seconds).
    • Decoder.NetworkError: network (download) error.
    • Decoder.Error: internal decoder error.
  • decodeAudio

    METHOD
    Decodes audio.
    Parameters
    NameTypeDefaultDescription
    outputshort int *Allocated memory to store the output. Must be at least numberOfFrames * 4 + 16384 bytes big.
    numberOfFramesunsigned intThe requested number of frames. Should NOT be less than the value returned by getFramesPerChunk().
    Returns
    TypeDescription
    int
    • A positive number above zero: the number of frames decoded.
    • Decoder.EndOfFile: end of file reached, there is nothing more to decode. Use setPosition.
    • Decoder.BufferingTryAgainLater: the decoder needs more data to be downloaded. Retry decodeAudio() later (it's recommended to wait at least 0.1 seconds).
    • Decoder.NetworkError: network (download) error.
    • Decoder.Error: internal decoder error.
  • destruct

    METHOD
    Destructor to free Linear Memory.
    Parameters
    None
    Returns
    None
  • getAlbum

    METHOD
    Returns with the contents of the TALB tag (or QT atom). Call this after parseAllID3Frames() OR finished reading all ID3 frames with readNextID3Frame().
    Parameters
    NameTypeDescription
    takeOwnershipBooleanFor advanced use. If true, you take ownership on the data (don't forget to free() when done to prevent memory leaks).
    Returns
    TypeDescription
    Number (pointer in Linear Memory)The string or 0 if not found.
  • getAlbum

    METHOD
    Returns with the contents of the TALB tag (or QT atom). Call this after parseAllID3Frames() OR finished reading all ID3 frames with readNextID3Frame().
    Parameters
    NameTypeDefaultDescription
    takeOwnershipboolfalseFor advanced use. If true, you take ownership on the data (don't forget to free() when done to prevent memory leaks).
    Returns
    TypeDescription
    char *The string or NULL if not found.
  • getArtist

    METHOD
    Returns with the contents "best" artist tag (TP1-4, TPE1-4, QT atoms). Call this after parseAllID3Frames() OR finished reading all ID3 frames with readNextID3Frame().
    Parameters
    NameTypeDescription
    takeOwnershipBooleanFor advanced use. If true, you take ownership on the data (don't forget to free() when done to prevent memory leaks).
    Returns
    TypeDescription
    Number (pointer in Linear Memory)The string or 0 if not found.
  • getArtist

    METHOD
    Returns with the contents "best" artist tag (TP1-4, TPE1-4, QT atoms). Call this after parseAllID3Frames() OR finished reading all ID3 frames with readNextID3Frame().
    Parameters
    NameTypeDefaultDescription
    takeOwnershipboolfalseFor advanced use. If true, you take ownership on the data (don't forget to free() when done to prevent memory leaks).
    Returns
    TypeDescription
    char *The string or NULL if not found.
  • getAudioEndFrame

    METHOD
    Detects silence at the end. WARNING! This function changes the position!
    Parameters
    NameTypeDescription
    limitFramesNumberOptional. How far to search for from the end (the duration in frames). 0 means 'the entire audio file'.
    thresholdDbNumberOptional. Loudness threshold in decibel. 0 means 'any non-zero audio'. The value -49 is useful for vinyl rips having vinyl noise (crackles).
    Returns
    TypeDescription
    Number
    • A positive number or zero: the frame index where audio ends.
    • Decoder::BufferingTryAgainLater: the decoder needs more data to be downloaded. Retry getAudioEndFrame() later (it's recommended to wait at least 0.1 seconds).
    • Decoder::NetworkError: network (download) error.
    • Decoder::Error: internal decoder error.
  • getAudioEndFrame

    METHOD
    Detects silence at the end. WARNING! This function changes the position!
    Parameters
    NameTypeDefaultDescription
    limitFramesunsigned int0Optional. How far to search for from the end (the duration in frames). 0 means 'the entire audio file'.
    thresholdDbint0Optional. Loudness threshold in decibel. 0 means 'any non-zero audio'. The value -49 is useful for vinyl rips having vinyl noise (crackles).
    Returns
    TypeDescription
    int
    • A positive number or zero: the frame index where audio ends.
    • Decoder::BufferingTryAgainLater: the decoder needs more data to be downloaded. Retry getAudioEndFrame() later (it's recommended to wait at least 0.1 seconds).
    • Decoder::NetworkError: network (download) error.
    • Decoder::Error: internal decoder error.
  • getAudioStartFrame

    METHOD
    Detects silence at the beginning. WARNING! This function changes the position!
    Parameters
    NameTypeDescription
    limitFramesNumberOptional. How far to search for from the end (the duration in frames). 0 means 'the entire audio file'.
    thresholdDbNumberOptional. Loudness threshold in decibel. 0 means 'any non-zero audio'. The value -49 is useful for vinyl rips having vinyl noise (crackles).
    Returns
    TypeDescription
    Number
    • A positive number or zero: the frame index where audio ends.
    • Decoder::BufferingTryAgainLater: the decoder needs more data to be downloaded. Retry getAudioStartFrame() later (it's recommended to wait at least 0.1 seconds).
    • Decoder::NetworkError: network (download) error.
    • Decoder::Error: internal decoder error.
  • getAudioStartFrame

    METHOD
    Detects silence at the beginning. WARNING! This function changes the position!
    Parameters
    NameTypeDefaultDescription
    limitFramesunsigned intOptional. How far to search for from the end (the duration in frames). 0 means 'the entire audio file'.
    thresholdDbintOptional. Loudness threshold in decibel. 0 means 'any non-zero audio'. The value -49 is useful for vinyl rips having vinyl noise (crackles).
    Returns
    TypeDescription
    int
    • A positive number or zero: the frame index where audio ends.
    • Decoder::BufferingTryAgainLater: the decoder needs more data to be downloaded. Retry getAudioStartFrame() later (it's recommended to wait at least 0.1 seconds).
    • Decoder::NetworkError: network (download) error.
    • Decoder::Error: internal decoder error.
  • getBPM

    METHOD
    Returns with the bpm value of the "best" bpm tag (TBP, TBPM, QT atom). Call this after parseAllID3Frames() OR finished reading all ID3 frames with readNextID3Frame().
    Parameters
    None
    Returns
    TypeDescription
    NumberBPM or 0.
  • getBPM

    METHOD
    Returns with the bpm value of the "best" bpm tag (TBP, TBPM, QT atom). Call this after parseAllID3Frames() OR finished reading all ID3 frames with readNextID3Frame().
    Parameters
    None
    Returns
    TypeDescription
    floatBPM or 0.
  • getBufferedEndPercent

    METHOD
    Indicates which part of the file has fast access. For local files it will always be 1.0f.
    Parameters
    None
    Returns
    TypeDescription
    floatPercentage between 0 and 1.
  • getBufferedStartPercent

    METHOD
    Indicates which part of the file has fast access. For local files it will always be 0.0f.
    Parameters
    None
    Returns
    TypeDescription
    floatPercentage between 0 and 1.
  • getCurrentBps

    METHOD
    Returns with the current download speed.
    Parameters
    None
    Returns
    TypeDescription
    unsigned intCurrent download speed in bytes per second.
  • getDurationFrames

    METHOD
    Returns with the duration of the current file in frames. Duration may change after each decode() or seekTo(), because some audio formats doesn't contain precise length information.
    Parameters
    None
    Returns
    TypeDescription
    NumberDuration of the current file in frames.
  • getDurationFrames

    METHOD
    Returns with the duration of the current file in frames. Duration may change after each decode() or seekTo(), because some audio formats doesn't contain precise length information.
    Parameters
    None
    Returns
    TypeDescription
    intDuration of the current file in frames.
  • getDurationSeconds

    METHOD
    Returns with the duration of the current file in seconds. Duration may change after each decode() or seekTo(), because some audio formats doesn't contain precise length information.
    Parameters
    None
    Returns
    TypeDescription
    NumberDuration of the current file in seconds.
  • getDurationSeconds

    METHOD
    Returns with the duration of the current file in seconds. Duration may change after each decode() or seekTo(), because some audio formats doesn't contain precise length information.
    Parameters
    None
    Returns
    TypeDescription
    doubleDuration of the current file in seconds.
  • getFormat

    METHOD
    Returns with the format of the current file.
    Parameters
    None
    Returns
    TypeDescription
    Superpowered.Decoder.FormatFormat of the current file.
  • getFormat

    METHOD
    Returns with the format of the current file.
    Parameters
    None
    Returns
    TypeDescription
    Superpowered::Decoder::FormatFormat of the current file.
  • getFramesPerChunk

    METHOD
    Returns with how many frames are in one chunk of the source file. For example: MP3 files store 1152 audio frames in a chunk.
    Parameters
    None
    Returns
    TypeDescription
    NumberNumber of frames in one chunk.
  • getFramesPerChunk

    METHOD
    Returns with how many frames are in one chunk of the source file. For example: MP3 files store 1152 audio frames in a chunk.
    Parameters
    None
    Returns
    TypeDescription
    unsigned intNumber of frames in one chunk.
  • getFullyDownloadedPath

    METHOD
    The file system path of the fully downloaded audio file for progressive downloads.
    Parameters
    None
    Returns
    TypeDescription
    const char *Path of the fully downloaded audio file or NULL until the download finishes.
  • getID3FrameAsString

    METHOD
    Returns with the text inside the current ID3 frame. To be used with readNextID3Frame(). Use it for frames containing text only!
    Parameters
    NameTypeDescription
    offsetNumberParse from this byte index.
    Returns
    TypeDescription
    Number (pointer in Linear Memory)The text in UTF-8 encoding (you take ownership on the data, don't forget to free() when done to prevent memory leaks), or 0 if empty. You can use Superpowered.toString(this_pointer) to create a JavaScript string from it.
  • getID3FrameAsString

    METHOD
    Returns with the text inside the current ID3 frame. To be used with readNextID3Frame(). Use it for frames containing text only!
    Parameters
    NameTypeDefaultDescription
    offsetint0Parse from this byte index.
    Returns
    TypeDescription
    char *A pointer to the text in UTF-8 encoding (you take ownership on the data, don't forget to free() when done to prevent memory leaks), or NULL if empty.
  • getID3FrameData

    METHOD
    Returns with the raw data of the current ID3 frame. To be used with readNextID3Frame().
    Parameters
    None
    Returns
    TypeDescription
    Number (pointer in Linear Memory)The data.
  • getID3FrameData

    METHOD
    Returns with the raw data of the current ID3 frame. To be used with readNextID3Frame().
    Parameters
    None
    Returns
    TypeDescription
    void *The data.
  • getID3FrameDataLengthBytes

    METHOD
    Returns with the current ID3 frame data length.
    Parameters
    None
    Returns
    TypeDescription
    NumberLength of the current ID3 frame in bytes.
  • getID3FrameDataLengthBytes

    METHOD
    Returns with the current ID3 frame data length.
    Parameters
    None
    Returns
    TypeDescription
    unsigned intLength of the current ID3 frame in bytes.
  • getID3FrameName

    METHOD
    Returns with the current ID3 frame name. To be used with readNextID3Frame().
    Parameters
    None
    Returns
    TypeDescription
    NumberName of the current ID3 frame as a "four char".
  • getID3FrameName

    METHOD
    Returns with the current ID3 frame name. To be used with readNextID3Frame().
    Parameters
    None
    Returns
    TypeDescription
    unsigned intName of the current ID3 frame as a "four char".
  • getImage

    METHOD
    Returns with the contents 'best' image tag (PIC, APIC, QT atom). Call this after parseAllID3Frames() OR finished reading all ID3 frames with readNextID3Frame().
    Parameters
    NameTypeDescription
    takeOwnershipBooleanFor advanced use. If true, you take ownership on the data (don't forget to free() when done to prevent memory leaks).
    Returns
    TypeDescription
    Number (pointer in Linear Memory)Pointer to the image or 0 if not found.
  • getImage

    METHOD
    Returns with the contents 'best' image tag (PIC, APIC, QT atom). Call this after parseAllID3Frames() OR finished reading all ID3 frames with readNextID3Frame().
    Parameters
    NameTypeDefaultDescription
    takeOwnershipboolfalseFor advanced use. If true, you take ownership on the data (don't forget to free() when done to prevent memory leaks).
    Returns
    TypeDescription
    void *Pointer to the image or NULL if not found.
  • getImageSizeBytes

    METHOD
    Returns with the the size of the image returned by getImage(). Call this after parseAllID3Frames() OR finished reading all ID3 frames with readNextID3Frame().
    Parameters
    None
    Returns
    TypeDescription
    NumberThe size of the ID3 image in bytes or 0 if not found.
  • getImageSizeBytes

    METHOD
    Returns with the the size of the image returned by getImage(). Call this after parseAllID3Frames() OR finished reading all ID3 frames with readNextID3Frame().
    Parameters
    None
    Returns
    TypeDescription
    unsigned intThe size of the ID3 image in bytes or 0 if not found.
  • getPositionFrames

    METHOD
    Returns with the current position in frames. The postion may change after each decode() or seekTo().
    Parameters
    None
    Returns
    TypeDescription
    NumberCurrent position in frames.
  • getPositionFrames

    METHOD
    Returns with the current position in frames. The postion may change after each decode() or seekTo().
    Parameters
    None
    Returns
    TypeDescription
    intCurrent position in frames.
  • getSampleRate

    METHOD
    Returns with the sample rate of the current file.
    Parameters
    None
    Returns
    TypeDescription
    NumberSample rate of the current file.
  • getSampleRate

    METHOD
    Returns with the sample rate of the current file.
    Parameters
    None
    Returns
    TypeDescription
    unsigned intSample rate of the current file.
  • getStemsJSONString

    METHOD
    Returns with the JSON metadata string for the Native Instruments Stems format.
    Parameters
    None
    Returns
    TypeDescription
    Number (pointer in Linear Memory)Linear Memory pointer or 0 if the file is not Stems. You can use Superpowered.toString(this_pointer) to create a JavaScript string from it.
  • getStemsJSONString

    METHOD
    Returns with the JSON metadata string for the Native Instruments Stems format.
    Parameters
    None
    Returns
    TypeDescription
    const char *JSON metadata string or NULL if the file is not Stems.
  • getTitle

    METHOD
    Returns with the contents "best" title tag (TT1-3, TIT1-3, QT atoms). Call this after parseAllID3Frames() OR finished reading all ID3 frames with readNextID3Frame().
    Parameters
    NameTypeDescription
    takeOwnershipBooleanFor advanced use. If true, you take ownership on the data (don't forget to free() when done to prevent memory leaks).
    Returns
    TypeDescription
    Number (pointer in Linear Memory)The string or 0 if not found.
  • getTitle

    METHOD
    Returns with the contents "best" title tag (TT1-3, TIT1-3, QT atoms). Call this after parseAllID3Frames() OR finished reading all ID3 frames with readNextID3Frame().
    Parameters
    NameTypeDefaultDescription
    takeOwnershipboolfalseFor advanced use. If true, you take ownership on the data (don't forget to free() when done to prevent memory leaks).
    Returns
    TypeDescription
    char *The string or NULL if not found.
  • getTrackIndex

    METHOD
    Returns with the track index (track field or TRCK). Call this after parseAllID3Frames() OR finished reading all ID3 frames with readNextID3Frame().
    Parameters
    None
    Returns
    TypeDescription
    NumberID3 track index
  • getTrackIndex

    METHOD
    Returns with the track index (track field or TRCK). Call this after parseAllID3Frames() OR finished reading all ID3 frames with readNextID3Frame().
    Parameters
    None
    Returns
    TypeDescription
    unsigned intID3 track index
  • open

    METHOD
    Open a file for decoding.
    Parameters
    NameTypeDefaultDescription
    pathconst char * Full file system path or progressive download path (http or https).
    metaOnlyboolIf true, it opens the file for fast metadata reading only, not for decoding audio. Available for fully available local files only (no network access).
    offsetint0Byte offset in the file. Primarily designed to open raw files from an apk.
    lengthint0Byte length from offset. Set offset and length to 0 to read the entire file.
    stemsIndexint0Stems track index for Native Instruments Stems format.
    customHTTPRequestSuperpowered::httpRequest *0If custom HTTP communication is required (such as sending http headers for authorization), pass a fully prepared http request object. The decoder will copy this object.
    Returns
    TypeDescription
    int
    The return value can be grouped into four categories:
    • Decoder::OpenSuccess: successful open.
    • httpResponse::StatusCode_Progress: the open method needs more time opening an audio file from the network. In this case retry open() later until it returns something else than StatusCode_Progress (it's recommended to wait at least 0.1 seconds).
    • A value above 1000: internal decoder error.
    • A HTTP status code for network errors.
  • openAudioFileInMemory

    METHOD
    Opens a memory location for decoding.
    Parameters
    NameTypeDescription
    pointerNumber (pointer in Linear Memory)An audio file loaded onto Linear Memory. The Decoder will take ownership on this data.
    sizeBytesNumberThe audio file length in bytes.
    metaOnlyBooleanIf true, it opens the file for fast metadata reading only, not for decoding audio.
    Returns
    TypeDescription
    Number
    • Decoder::OpenSuccess: successful open.
    • httpResponse::StatusCode_Progress: the open method needs more time opening an audio file from the network. In this case retry open() later until it returns something else than StatusCode_Progress (it's recommended to wait at least 0.1 seconds).
    • A value above 1000: internal decoder error.
    • A HTTP status code for network errors.
  • openAudioFileInMemory

    METHOD
    Opens a memory location for decoding.
    Parameters
    NameTypeDefaultDescription
    pointervoid *An audio file loaded onto the heap. Should be allocated using malloc() (and not _aligned_malloc() or similar). The Decoder will take ownership on this data.
    sizeBytesunsigned intThe audio file length in bytes.
    metaOnlyboolfalseIf true, it opens the file for fast metadata reading only, not for decoding audio.
    Returns
    TypeDescription
    int
    • Decoder::OpenSuccess: successful open.
    • httpResponse::StatusCode_Progress: the open method needs more time opening an audio file from the network. In this case retry open() later until it returns something else than StatusCode_Progress (it's recommended to wait at least 0.1 seconds).
    • A value above 1000: internal decoder error.
    • A HTTP status code for network errors.
  • openHLS

    METHOD
    Opens a HTTP Live Streaming stream.
    Parameters
    NameTypeDefaultDescription
    urlconst char * Stream URL.
    liveLatencySecondschar-1When connecting or reconnecting to a HLS live stream, the decoder will try to skip audio to maintain this latency. Default: -1 (the decoder wil not skip audio and the live stream starts at the first segment specified by the server).
    customHTTPRequestSuperpowered::httpRequest *0If custom HTTP communication is required (such as sending http headers for authorization), pass a fully prepared http request object. The decoder will copy this object.
    Returns
    TypeDescription
    int
    The return value can be grouped into four categories:
    • Decoder::OpenSuccess: successful open.
    • httpResponse::StatusCode_Progress: the open method needs more time opening an audio file from the network. In this case retry open() later until it returns something else than StatusCode_Progress (it's recommended to wait at least 0.1 seconds).
    • A value above 1000: internal decoder error.
    • A HTTP status code for network errors.
  • openMemory

    METHOD
    Opens a memory location in Superpowered AudioInMemory format for decoding.
    Parameters
    NameTypeDescription
    pointerNumber (pointer in Linear Memory)Data in Superpowered AudioInMemory format. Ownership is controlled by the AudioInMemory format.
    metaOnlyBooleanIf true, it opens the file for fast metadata reading only, not for decoding audio.
    Returns
    TypeDescription
    Number
    • Decoder::OpenSuccess: successful open.
    • httpResponse::StatusCode_Progress: the open method needs more time opening an audio file from the network. In this case retry open() later until it returns something else than StatusCode_Progress (it's recommended to wait at least 0.1 seconds).
    • A value above 1000: internal decoder error.
    • A HTTP status code for network errors.
  • openMemory

    METHOD
    Opens a memory location in Superpowered AudioInMemory format for decoding.
    Parameters
    NameTypeDefaultDescription
    pointervoid *Data in Superpowered AudioInMemory format. Ownership is controlled by the AudioInMemory format.
    metaOnlyboolfalseIf true, it opens the file for fast metadata reading only, not for decoding audio.
    Returns
    TypeDescription
    int
    • Decoder::OpenSuccess: successful open.
    • httpResponse::StatusCode_Progress: the open method needs more time opening an audio file from the network. In this case retry open() later until it returns something else than StatusCode_Progress (it's recommended to wait at least 0.1 seconds).
    • A value above 1000: internal decoder error.
    • A HTTP status code for network errors.
  • parseAllID3Frames

    METHOD
    Parses all ID3 frames. Do not use startReadingID3/readNextID3Frame after this.
    Parameters
    NameTypeDescription
    skipImagesBooleanParsing ID3 image frames is significantly slower than parsing other frames. Set this to true if not interested in image information to save CPU.
    maxFrameDataSizeNumberThe maximum frame size in bytes to retrieve if the decoder can not memory map the entire audio file. Affects memory usage. Useful to skip large payloads (such as images).
    Returns
    None
  • parseAllID3Frames

    METHOD
    Parses all ID3 frames. Do not use startReadingID3/readNextID3Frame after this.
    Parameters
    NameTypeDefaultDescription
    skipImagesboolParsing ID3 image frames is significantly slower than parsing other frames. Set this to true if not interested in image information to save CPU.
    maxFrameDataSizeunsigned intfalseThe maximum frame size in bytes to retrieve if the decoder can not memory map the entire audio file. Affects memory usage. Useful to skip large payloads (such as images).
    Returns
    None
  • readNextID3Frame

    METHOD
    Reads the next ID3 frame.
    Parameters
    None
    Returns
    TypeDescription
    NumberID3 frame data size or -1 if finished reading.
  • readNextID3Frame

    METHOD
    Reads the next ID3 frame.
    Parameters
    None
    Returns
    TypeDescription
    usigned intID3 frame data size or -1 if finished reading.
  • reconnectToMediaserver

    METHOD
    Apple's built-in codec may be used in some cases, such as decoding ALAC files. Call this after a media server reset or audio session interrupt to resume playback.
    Parameters
    None
    Returns
    None
  • setPositionPrecise

    METHOD
    Jumps to a specific position. This method is a little bit slower than setPositionQuick().
    Parameters
    NameTypeDescription
    positionFramesNumberThe requested position.
    Returns
    TypeDescription
    BooleanReturns with success (true) or failure (false).
  • setPositionPrecise

    METHOD
    Jumps to a specific position. This method is a little bit slower than setPositionQuick().
    Parameters
    NameTypeDefaultDescription
    positionFramesintThe requested position.
    Returns
    TypeDescription
    boolReturns with success (true) or failure (false).
  • setPositionQuick

    METHOD
    Jumps to the specified position's chunk (frame) beginning. Some codecs (such as MP3) contain audio in chunks (frames). This method will not jump precisely to the specified position, but to the chunk's beginning the position belongs to.
    Parameters
    NameTypeDescription
    positionFramesNumberThe requested position.
    Returns
    TypeDescription
    BooleanReturns with success (true) or failure (false).
  • setPositionQuick

    METHOD
    Jumps to the specified position's chunk (frame) beginning. Some codecs (such as MP3) contain audio in chunks (frames). This method will not jump precisely to the specified position, but to the chunk's beginning the position belongs to.
    Parameters
    NameTypeDefaultDescription
    positionFramesintThe requested position.
    Returns
    TypeDescription
    boolReturns with success (true) or failure (false).
  • startParsingID3Frames

    METHOD
    Starts reading ID3 frames. Use readNextID3Frame() in an iteration after this.
    Parameters
    NameTypeDescription
    skipImagesBooleanParsing ID3 image frames is significantly slower than parsing other frames. Set this to true if not interested in image information to save CPU.
    maxFrameDataSizeNumberThe maximum frame size in bytes to retrieve if the decoder can not memory map the entire audio file. Affects memory usage. Useful to skip large payloads (such as images).
    Returns
    None
  • startParsingID3Frames

    METHOD
    Starts reading ID3 frames. Use readNextID3Frame() in an iteration after this.
    Parameters
    NameTypeDefaultDescription
    skipImagesboolParsing ID3 image frames is significantly slower than parsing other frames. Set this to true if not interested in image information to save CPU.
    maxFrameDataSizeunsigned intThe maximum frame size in bytes to retrieve if the decoder can not memory map the entire audio file. Affects memory usage. Useful to skip large payloads (such as images).
    Returns
    None

FAQ

v1.0.6