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 &)

Decoder &	operator= (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:

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.

Parameters

output	Pointer to 16-bit signed integer numbers. The output. Must be at least numberOfFrames * 4 + 16384 bytes big.
numberOfFrames	The 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

takeOwnership For 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

takeOwnership For 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:

A positive number or zero: the frame index where audio starts.
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.

Parameters

limitFrames	Optional. How far to search for. 0 means "the entire audio file".
thresholdDb	Optional. 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

offset Parse 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

takeOwnership For 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

takeOwnership For 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

path	Full file system path or progressive download path (http or https).
metaOnly	If true, it opens the file for fast metadata reading only, not for decoding audio. Available for fully available local files only (no network access).
offset	Byte offset in the file. Primarily designed to open raw files from an apk.
length	Byte length from offset. Set offset and length to 0 to read the entire file.
stemsIndex	Stems track index for Native Instruments Stems format.
customHTTPRequest	If 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

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

◆ 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

positionFrames The 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

positionFrames The requested position.

◆ startParsingID3Frames()

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

Starts reading ID3 frames.

Use readNextID3Frame() in an iteration after this.

Parameters

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

◆ 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

code	The 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

Call AdvancedAudioPlayer::setTempFolder first.

◆ 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:

latest/Superpowered/SuperpoweredDecoder.h

Public Member Functions

Static Public Member Functions

Static Public Attributes

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Decoder() [1/2]

◆ ~Decoder()

◆ Decoder() [2/2]

Member Function Documentation

◆ decodeAudio()

◆ getAlbum()

◆ getArtist()

◆ getAudioStartFrame()

◆ getBPM()

◆ getBufferedEndPercent()

◆ getBufferedStartPercent()

◆ getDurationFrames()

◆ getDurationSeconds()

◆ getFormat()

◆ getFramesPerChunk()

◆ getFullyDownloadedPath()

◆ getID3FrameAsString()

◆ getID3FrameData()

◆ getID3FrameDataLengthBytes()

◆ getID3FrameName()

◆ getImage()

◆ getImageSizeBytes()

◆ getPositionFrames()

◆ getSamplerate()

◆ getStemsJSONString()

◆ getTitle()

◆ getTrackIndex()

◆ open()

◆ operator=()

◆ parseAllID3Frames()

◆ readNextID3Frame()

◆ reconnectToMediaserver()

◆ setPositionPrecise()

◆ setPositionQuick()

◆ startParsingID3Frames()

◆ statusCodeToString()

Member Data Documentation

◆ BufferingTryAgainLater

◆ EndOfFile

◆ Error

◆ internals

◆ NetworkError

◆ OpenError_AppleAssetFailed

◆ OpenError_AppleDecoding

◆ OpenError_AppleMissingTracks

◆ OpenError_FastMetadataNotLocal

◆ OpenError_FileFormatNotRecognized

◆ OpenError_FileLengthError

◆ OpenError_FileOpenError

◆ OpenError_FileTooShort

◆ OpenError_ID3ReadError

◆ OpenError_ID3VersionNotSupported

◆ OpenError_ImplementationError0

◆ OpenError_ImplementationError1

◆ OpenError_ImplementationError2

◆ OpenError_OutOfMemory

◆ OpenError_PathIsNull

◆ OpenError_UseSetTempFolder

◆ OpenSuccess