SuperpoweredSDK  v2.0.1
Superpowered Audio SDK
Superpowered::Decoder Class Reference

Audio file decoder. More...

#include "SuperpoweredDecoder.h"

Public Member Functions

 Decoder ()
 Creates an instance of Superpowered Decoder. More...
 
 ~Decoder ()
 
int decodeAudio (short int *output, unsigned int numberOfFrames)
 Decodes audio. More...
 
char * getAlbum (bool takeOwnership=false)
 
char * getArtist (bool takeOwnership=false)
 
int getAudioStartFrame (unsigned int limitFrames=0, int thresholdDb=0)
 Detects silence at the beginning. More...
 
float getBPM ()
 
float getBufferedEndPercent ()
 
float getBufferedStartPercent ()
 
int64_t getDurationFrames ()
 
double getDurationSeconds ()
 
Decoder_Format getFormat ()
 
unsigned int getFramesPerChunk ()
 
const char * getFullyDownloadedPath ()
 
char * getID3FrameAsString (int offset=0)
 Returns with the text inside the current ID3 frame. More...
 
void * getID3FrameData ()
 
unsigned int getID3FrameDataLengthBytes ()
 
unsigned int getID3FrameName ()
 
void * getImage (bool takeOwnership=false)
 
unsigned int getImageSizeBytes ()
 
int64_t getPositionFrames ()
 
unsigned int getSamplerate ()
 
const char * getStemsJSONString ()
 
char * getTitle (bool takeOwnership=false)
 
unsigned int getTrackIndex ()
 
int open (const char *path, bool metaOnly=false, int offset=0, int length=0, int stemsIndex=0, Superpowered::httpRequest *customHTTPRequest=0)
 Opens a file for decoding. More...
 
void parseAllID3Frames (bool skipImages, unsigned int maxFrameDataSize)
 Parses all ID3 frames. More...
 
unsigned int readNextID3Frame ()
 
void reconnectToMediaserver ()
 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. More...
 
bool setPositionPrecise (int64_t positionFrames)
 Jumps to a specific position. More...
 
bool setPositionQuick (int64_t positionFrames)
 Jumps to the specified position's chunk (frame) beginning. More...
 
void startParsingID3Frames (bool skipImages, unsigned int maxFrameDataSize)
 Starts reading ID3 frames. More...
 

Static Public Member Functions

static const char * statusCodeToString (int code)
 

Static Public Attributes

static const int BufferingTryAgainLater = -1
 Buffering (waiting for the network to pump enough data). More...
 
static const int EndOfFile = 0
 Error codes for the decodeAudio() and getAudioStartFrame() methods. More...
 
static const int Error = -3
 Decoding error. More...
 
static const int NetworkError = -2
 Network (download) error. More...
 
static const int OpenError_AppleAssetFailed = 1009
 The Apple system codec could not create an AVURLAsset on the resource. Wrong file format? More...
 
static const int OpenError_AppleDecoding = 1011
 The Apple system codec could not get the audio frames. Wrong file format? More...
 
static const int OpenError_AppleMissingTracks = 1010
 The Apple system codec did not found any audio tracks. Wrong file format? More...
 
static const int OpenError_FastMetadataNotLocal = 1002
 metaOnly was true, but it works on local files only. More...
 
static const int OpenError_FileFormatNotRecognized = 1005
 The decoder is not able to decode this file format. More...
 
static const int OpenError_FileLengthError = 1007
 Such as fseek() failed. Recommended action: check if read permissions are correct. More...
 
static const int OpenError_FileOpenError = 1006
 Such as fopen() failed. Recommended action: check if the path and read permissions are correct. More...
 
static const int OpenError_FileTooShort = 1008
 The file has just a few bytes of data. More...
 
static const int OpenError_ID3ReadError = 1004
 File read error (such as fread() failed) while reading the ID3 tag. More...
 
static const int OpenError_ID3VersionNotSupported = 1003
 ID3 version 2.2, 2.3 and 2.4 are supported only. More...
 
static const int OpenError_ImplementationError0 = 1012
 Should never happen. But if it does, please let us know. More...
 
static const int OpenError_ImplementationError1 = 1013
 Should never happen. But if it does, please let us know. More...
 
static const int OpenError_ImplementationError2 = 1014
 Should never happen. But if it does, please let us know. More...
 
static const int OpenError_OutOfMemory = 1000
 Some memory allocation failed. Recommended action: check for memory leaks. More...
 
static const int OpenError_PathIsNull = 1001
 Path is NULL. More...
 
static const int OpenError_UseSetTempFolder = 1015
 Call AdvancedAudioPlayer::setTempFolder first. More...
 
static const int OpenSuccess = 0
 Error codes for the open() method. More...
 

Private Member Functions

 Decoder (const Decoder &)
 
Decoderoperator= (const Decoder &)
 

Private Attributes

decoderInternals * internals
 

Detailed Description

Audio file decoder.

Provides raw PCM audio from various compressed formats. Supported file types:

  • 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).
  • ALAC/Apple Lossless (on iOS only).

Constructor & Destructor Documentation

◆ Decoder() [1/2]

Superpowered::Decoder::Decoder ( )

Creates an instance of Superpowered Decoder.

◆ ~Decoder()

Superpowered::Decoder::~Decoder ( )

◆ Decoder() [2/2]

Superpowered::Decoder::Decoder ( const Decoder )
private

Member Function Documentation

◆ decodeAudio()

int Superpowered::Decoder::decodeAudio ( short int *  output,
unsigned int  numberOfFrames 
)

Decodes audio.

Returns
The return value can be:
Parameters
outputPointer to 16-bit signed integer numbers. The output. Must be at least numberOfFrames * 4 + 16384 bytes big.
numberOfFramesThe requested number of frames. Should NOT be less than framesPerChunk.

◆ getAlbum()

char* Superpowered::Decoder::getAlbum ( bool  takeOwnership = false)
Returns
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().
Parameters
takeOwnershipFor advanced use. If true, you take ownership on the data (don't forget to free() when done to prevent memory leaks).

◆ getArtist()

char* Superpowered::Decoder::getArtist ( bool  takeOwnership = false)
Returns
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().
Parameters
takeOwnershipFor advanced use. If true, you take ownership on the data (don't forget to free() when done to prevent memory leaks).

◆ getAudioStartFrame()

int Superpowered::Decoder::getAudioStartFrame ( unsigned int  limitFrames = 0,
int  thresholdDb = 0 
)

Detects silence at the beginning.

Warning
This function changes positionFrames!
Returns
The return value can be:
Parameters
limitFramesOptional. How far to search for. 0 means "the entire audio file".
thresholdDbOptional. Loudness threshold in decibel. 0 means "any non-zero audio". The value -49 is useful for vinyl rips starting with vinyl noise (crackles).

◆ getBPM()

float Superpowered::Decoder::getBPM ( )
Returns
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().

◆ getBufferedEndPercent()

float Superpowered::Decoder::getBufferedEndPercent ( )
Returns
Indicates which part of the file has fast access. For local files it will always be 1.0f.

◆ getBufferedStartPercent()

float Superpowered::Decoder::getBufferedStartPercent ( )
Returns
Indicates which part of the file has fast access. For local files it will always be 0.0f.

◆ getDurationFrames()

int64_t Superpowered::Decoder::getDurationFrames ( )
Returns
Returns with the duration of the current file in frames.
Warning
Duration may change after each decode() or seekTo(), because some audio formats doesn't contain precise length information.

◆ getDurationSeconds()

double Superpowered::Decoder::getDurationSeconds ( )
Returns
Returns with the duration of the current file in seconds.
Warning
Duration may change after each decode() or seekTo(), because some audio formats doesn't contain precise length information.

◆ getFormat()

Decoder_Format Superpowered::Decoder::getFormat ( )
Returns
Returns with the format of the current file.

◆ getFramesPerChunk()

unsigned int Superpowered::Decoder::getFramesPerChunk ( )
Returns
Returns with how many frames are in one chunk of the source file. For example: MP3 files store 1152 audio frames in a chunk.

◆ getFullyDownloadedPath()

const char* Superpowered::Decoder::getFullyDownloadedPath ( )
Returns
The file system path of the fully downloaded audio file for progressive downloads. May be NULL until the download finishes.

◆ getID3FrameAsString()

char* Superpowered::Decoder::getID3FrameAsString ( int  offset = 0)

Returns with the text inside the current ID3 frame.

To be used with readNextID3Frame().

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.
Warning
Use it for frames containing text only!
Parameters
offsetParse from this byte index.

◆ getID3FrameData()

void* Superpowered::Decoder::getID3FrameData ( )
Returns
Returns with the raw data of the current ID3 frame. To be used with readNextID3Frame().

◆ getID3FrameDataLengthBytes()

unsigned int Superpowered::Decoder::getID3FrameDataLengthBytes ( )
Returns
Returns with the current ID3 frame data length.

◆ getID3FrameName()

unsigned int Superpowered::Decoder::getID3FrameName ( )
Returns
Returns with the current ID3 frame name (four char). To be used with readNextID3Frame().

◆ getImage()

void* Superpowered::Decoder::getImage ( bool  takeOwnership = false)
Returns
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().
Parameters
takeOwnershipFor advanced use. If true, you take ownership on the data (don't forget to free() when done to prevent memory leaks).

◆ getImageSizeBytes()

unsigned int Superpowered::Decoder::getImageSizeBytes ( )
Returns
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().

◆ getPositionFrames()

int64_t Superpowered::Decoder::getPositionFrames ( )
Returns
Returns with the current position in frames. The postion may change after each decode() or seekTo().

◆ getSamplerate()

unsigned int Superpowered::Decoder::getSamplerate ( )
Returns
Returns with the sample rate of the current file.

◆ getStemsJSONString()

const char* Superpowered::Decoder::getStemsJSONString ( )
Returns
Returns with the JSON metadata string for the Native Instruments Stems format, or NULL if the file is not Stems.

◆ getTitle()

char* Superpowered::Decoder::getTitle ( bool  takeOwnership = false)
Returns
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().
Parameters
takeOwnershipFor advanced use. If true, you take ownership on the data (don't forget to free() when done to prevent memory leaks).

◆ getTrackIndex()

unsigned int Superpowered::Decoder::getTrackIndex ( )
Returns
Returns with the track index (track field or TRCK). Call this after parseAllID3Frames() OR finished reading all ID3 frames with readNextID3Frame().

◆ open()

int Superpowered::Decoder::open ( const char *  path,
bool  metaOnly = false,
int  offset = 0,
int  length = 0,
int  stemsIndex = 0,
Superpowered::httpRequest customHTTPRequest = 0 
)

Opens a file for decoding.

Returns
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.
Parameters
pathFull file system path or progressive download path (http or https).
metaOnlyIf true, it opens the file for fast metadata reading only, not for decoding audio. Available for fully available local files only (no network access).
offsetByte offset in the file. Primarily designed to open raw files from an apk.
lengthByte length from offset. Set offset and length to 0 to read the entire file.
stemsIndexStems track index for Native Instruments Stems format.
customHTTPRequestIf custom HTTP communication is required (such as sending http headers for authorization), pass a fully prepared http request object. The player will take ownership of this.

◆ operator=()

Decoder& Superpowered::Decoder::operator= ( const Decoder )
private

◆ parseAllID3Frames()

void Superpowered::Decoder::parseAllID3Frames ( bool  skipImages,
unsigned int  maxFrameDataSize 
)

Parses all ID3 frames.

Do not use startReadingID3/readNextID3Frame after this.

Parameters
skipImagesParsing ID3 image frames is significantly slower than parsing other frames. Set this to true if not interested in image information to save CPU.
maxFrameDataSizeThe 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).

◆ readNextID3Frame()

unsigned int Superpowered::Decoder::readNextID3Frame ( )
Returns
Reads the next ID3 frame and returns with its data size or -1 if finished reading.

◆ reconnectToMediaserver()

void Superpowered::Decoder::reconnectToMediaserver ( )

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.

◆ setPositionPrecise()

bool Superpowered::Decoder::setPositionPrecise ( int64_t  positionFrames)

Jumps to a specific position.

This method is a little bit slower than setPositionQuick().

Returns
Returns with success (true) or failure (false).
Parameters
positionFramesThe requested position.

◆ setPositionQuick()

bool Superpowered::Decoder::setPositionQuick ( int64_t  positionFrames)

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
Returns with success (true) or failure (false).
Parameters
positionFramesThe requested position.

◆ startParsingID3Frames()

void Superpowered::Decoder::startParsingID3Frames ( bool  skipImages,
unsigned int  maxFrameDataSize 
)

Starts reading ID3 frames.

Use readNextID3Frame() in an iteration after this.

Parameters
skipImagesParsing ID3 image frames is significantly slower than parsing other frames. Set this to true if not interested in image information to save CPU.
maxFrameDataSizeThe 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).

◆ statusCodeToString()

static const char* Superpowered::Decoder::statusCodeToString ( int  code)
static
Returns
Returns with a human readable error string. If the code is not a decoder status code, then it's a SuperpoweredHTTP status code and returns with that.
Parameters
codeThe return value of the Decoder::open method.

Member Data Documentation

◆ BufferingTryAgainLater

const int Superpowered::Decoder::BufferingTryAgainLater = -1
static

Buffering (waiting for the network to pump enough data).

◆ EndOfFile

const int Superpowered::Decoder::EndOfFile = 0
static

Error codes for the decodeAudio() and getAudioStartFrame() methods.

End-of-file reached.

◆ Error

const int Superpowered::Decoder::Error = -3
static

Decoding error.

◆ internals

decoderInternals* Superpowered::Decoder::internals
private

◆ NetworkError

const int Superpowered::Decoder::NetworkError = -2
static

Network (download) error.

◆ OpenError_AppleAssetFailed

const int Superpowered::Decoder::OpenError_AppleAssetFailed = 1009
static

The Apple system codec could not create an AVURLAsset on the resource. Wrong file format?

◆ OpenError_AppleDecoding

const int Superpowered::Decoder::OpenError_AppleDecoding = 1011
static

The Apple system codec could not get the audio frames. Wrong file format?

◆ OpenError_AppleMissingTracks

const int Superpowered::Decoder::OpenError_AppleMissingTracks = 1010
static

The Apple system codec did not found any audio tracks. Wrong file format?

◆ OpenError_FastMetadataNotLocal

const int Superpowered::Decoder::OpenError_FastMetadataNotLocal = 1002
static

metaOnly was true, but it works on local files only.

◆ OpenError_FileFormatNotRecognized

const int Superpowered::Decoder::OpenError_FileFormatNotRecognized = 1005
static

The decoder is not able to decode this file format.

◆ OpenError_FileLengthError

const int Superpowered::Decoder::OpenError_FileLengthError = 1007
static

Such as fseek() failed. Recommended action: check if read permissions are correct.

◆ OpenError_FileOpenError

const int Superpowered::Decoder::OpenError_FileOpenError = 1006
static

Such as fopen() failed. Recommended action: check if the path and read permissions are correct.

◆ OpenError_FileTooShort

const int Superpowered::Decoder::OpenError_FileTooShort = 1008
static

The file has just a few bytes of data.

◆ OpenError_ID3ReadError

const int Superpowered::Decoder::OpenError_ID3ReadError = 1004
static

File read error (such as fread() failed) while reading the ID3 tag.

◆ OpenError_ID3VersionNotSupported

const int Superpowered::Decoder::OpenError_ID3VersionNotSupported = 1003
static

ID3 version 2.2, 2.3 and 2.4 are supported only.

◆ OpenError_ImplementationError0

const int Superpowered::Decoder::OpenError_ImplementationError0 = 1012
static

Should never happen. But if it does, please let us know.

◆ OpenError_ImplementationError1

const int Superpowered::Decoder::OpenError_ImplementationError1 = 1013
static

Should never happen. But if it does, please let us know.

◆ OpenError_ImplementationError2

const int Superpowered::Decoder::OpenError_ImplementationError2 = 1014
static

Should never happen. But if it does, please let us know.

◆ OpenError_OutOfMemory

const int Superpowered::Decoder::OpenError_OutOfMemory = 1000
static

Some memory allocation failed. Recommended action: check for memory leaks.

◆ OpenError_PathIsNull

const int Superpowered::Decoder::OpenError_PathIsNull = 1001
static

Path is NULL.

◆ OpenError_UseSetTempFolder

const int Superpowered::Decoder::OpenError_UseSetTempFolder = 1015
static

◆ OpenSuccess

const int Superpowered::Decoder::OpenSuccess = 0
static

Error codes for the open() method.


The documentation for this class was generated from the following file: