High performance advanced audio player with: More...

#include "SuperpoweredAdvancedAudioPlayer.h"

Public Member Functions
	AdvancedAudioPlayer (unsigned int samplerate, unsigned char cachedPointCount, unsigned int internalBufferSizeSeconds=2, unsigned int negativeSeconds=0)
	Creates a player instance with the current sample rate value. More...

	~AdvancedAudioPlayer ()

void	cachePosition (double ms, unsigned char pointID=255)
	Caches a position for zero latency seeking. More...

double	closestBeatMs (double ms, unsigned char *beatIndex=0)

void	endContinuousPitchBend ()
	Ends pitch bend. More...

void	endScratch (bool returnToStateBeforeScratch)
	Ends scratching. More...

bool	eofRecently ()

void	exitLoop (bool synchronisedStart=false)
	Exit from the current loop. More...

double	getAudioStartMs ()

float	getBeatIndex ()

double	getBendOffsetMs ()

float	getBufferedEndPercent ()

float	getBufferedStartPercent ()

double	getCurrentBpm ()

unsigned int	getCurrentHLSBPS ()

double	getDisplayPositionMs ()

float	getDisplayPositionPercent ()

int	getDisplayPositionSeconds ()

unsigned int	getDurationMs ()

unsigned int	getDurationSeconds ()

const char *	getFullyDownloadedFilePath ()

PlayerEvent	getLatestEvent ()

double	getMsDifference (double phase, double quantum)

double	getMsElapsedSinceLastBeat ()

int	getOpenErrorCode ()

double	getPhase ()

double	getPositionMs ()

double	getQuantum ()

const char *	getStemColor (unsigned char index)

const char *	getStemName (unsigned char index)

double	getWaitingForSyncStartMs ()

double	getWillSyncMs ()

bool	isLooping ()

bool	isPerformingSlip ()

bool	isPlaying ()

bool	isReverse ()

bool	isScratching ()

bool	isStems ()

bool	isWaitingForBuffering ()

void	jogTick (int value, bool bendStretch, float bendMaxPercent, unsigned int bendHoldMs, bool parameterModeIfNoJogTouchBegin)
	A jog wheel should send some "ticks" with the movement. More...

void	jogTouchBegin (int ticksPerTurn, JogMode mode, unsigned int scratchSlipMs=0)
	"Virtual jog wheel" or "virtual turntable" handling. More...

void	jogTouchEnd (float decelerate, bool synchronisedStart)
	Call this when the jog touch ends. More...

bool	loop (double startMs, double lengthMs, bool jumpToStartMs, unsigned char pointID, bool synchronisedStart, unsigned int numLoops=0, bool forceDefaultQuantum=false, bool preferWaitingforSynchronisedStart=false)
	Loop from a start point to some length. More...

bool	loopBetween (double startMs, double endMs, bool jumpToStartMs, unsigned char pointID, bool synchronisedStart, unsigned int numLoops=0, bool forceDefaultQuantum=false, bool preferWaitingforSynchronisedStart=false)
	Loop between a start and end points. More...

bool	msInLoop (double ms)

void	onMediaserverInterrupt ()
	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...

void	open (const char path, Superpowered::httpRequest customHTTPRequest=0, bool skipSilenceAtBeginning=false)
	Opens an audio file with playback paused. More...

void	open (const char path, int offset, int length, Superpowered::httpRequest customHTTPRequest=0, bool skipSilenceAtBeginning=false)
	Opens an audio file with playback paused. More...

void	openHLS (const char url, Superpowered::httpRequest customHTTPRequest=0)
	Opens a HTTP Live Streaming stream with playback paused. More...

void	pause (float decelerateSeconds=0, unsigned int slipMs=0)
	Pause playback. More...

void	pitchBend (float maxPercent, bool bendStretch, bool faster, unsigned int holdMs)
	Starts on changes pitch bend (temporary playback rate change). More...

void	play ()
	Starts playback immediately without any synchronization. More...

void	playSynchronized ()
	Starts beat or tempo synchronized playback. More...

void	playSynchronizedToPosition (double positionMs)
	Starts playback at a specific position. More...

bool	processMulti (float *buffers, bool mix, unsigned int numberOfFrames, float volumes, double *jogParameter=0)
	Processes audio, multi-channel version. More...

void	processSTEMSMaster (float input, float output, unsigned int numberOfFrames, float volume=1.0f)
	Performs the last stage of STEMS processing, the master compressor and limiter. More...

bool	processStereo (float buffer, bool mix, unsigned int numberOfFrames, float volume=1.0f, double jogParameter=0)
	Processes audio, stereo version. More...

void	resetBendMsOffset ()
	Reset the pitch bend offset to the beatgrid to zero. More...

void	scratch (double pitch, float smoothing)
	Scratch movement. More...

void	seek (double percent)
	Simple seeking to a percentage. More...

void	setPosition (double ms, bool andStop, bool synchronisedStart, bool forceDefaultQuantum=false, bool preferWaitingforSynchronisedStart=false)
	Precise seeking. More...

void	setReverse (bool reverse, unsigned int slipMs=0)
	Sets playback direction. More...

void	startScratch (unsigned int slipMs, bool stopImmediately)
	Direct turntable handling. More...

void	togglePlayback ()
	Toggle play/pause (no synchronization). More...

Static Public Member Functions
static const char *	getTempFolderPath ()

static void	setTempFolder (const char *path)
	Set the folder to store for temporary files. More...

static const char *	statusCodeToString (int code)

Public Attributes
double	defaultQuantum
	Sets the quantum for quantized synchronization. Example: 4 means 4 beats. More...

bool	enableStems
	If true and a Native Instruments STEMS file is loaded, output 4 stereo channels. Default: false (stereo master mix output). More...

double	firstBeatMs
	Tells where the first beat is (the beatgrid starts). Must be set to a correct value for syncing. Default: 0. More...

bool	fixDoubleOrHalfBPM
	If true and playbackRate is above 1.4f or below 0.6f, it will sync the tempo as half or double. Default: false. More...

bool	HLSAutomaticAlternativeSwitching
	If true, then the player will automatically swtich between the HLS alternatives according to the available network bandwidth. Default: true. More...

int	HLSBufferingSeconds
	How many seconds ahead of the playback position to download. Default value: HLS_DOWNLOAD_REMAINING. More...

char	HLSLiveLatencySeconds
	When connecting or reconnecting to a HLS live stream, the player will try to skip audio to maintain this latency. Default: -1 (the player wil not skip audio and the live stream starts at the first segment specified by the server). More...

int	HLSMaximumDownloadAttempts
	How many times to retry if a HLS segment download fails. Default: 100. More...

bool	loopOnEOF
	If true, jumps back and continues playback. If false, playback stops. Default: false. More...

float	maximumTimestretchingPlaybackRate
	Will not time-stretch but resample above this playback rate. Default: 2.0f (the recommended value for low CPU load on older mobile devices, such as the first iPad). Will be applied after changing playbackRate or scratching. More...

float	minimumTimestretchingPlaybackRate
	Will not time-stretch but resample below this playback rate. Default: 0.501f (the recommended value for low CPU load on older mobile devices, such as the first iPad). Will be applied after changing playbackRate or scratching. More...

double	originalBPM
	The original bpm of the current music. There is no auto-bpm detection inside, this must be set to a correct value for syncing. Maximum 300. A value below 20 will be automatically set to 0. Default: 0 (no bpm value known). More...

unsigned int	outputSamplerate
	The player output sample rate in Hz. More...

int	pitchShiftCents
	Pitch shift cents, from -1200 (one octave down) to 1200 (one octave up). Use values representing notes (multiply of 100) for low CPU load. Default: 0 (no pitch shift). More...

double	playbackRate
	The playback rate. Must be positive and above 0.00001. Default: 1. More...

bool	reverseToForwardAtLoopStart
	If this is true with playing backwards and looping, then reaching the beginning of the loop will change playback direction to forwards. Default: false. More...

SyncMode	syncMode
	The current sync mode (off, tempo, or tempo+beat). Default: off. More...

double	syncToBpm
	A bpm value to sync with. Use 0.0f for no syncing. More...

double	syncToMsElapsedSinceLastBeat
	The number of milliseconds elapsed since the last beat on audio the player has to sync with. Use -1.0 to ignore. More...

double	syncToPhase
	Used for quantized synchronization. The phase to sync with. More...

double	syncToQuantum
	Used for quantized synchronization. The quantum to sync with. More...

bool	timeStretching
	Enable/disable time-stretching. Default: true. More...

Static Public Attributes
static const int	HLSDownloadEverything
	Will download everything after the playback position until the end. More...

static const int	HLSDownloadRemaining
	Downloads everything from the beginning to the end, regardless the playback position. More...

static const float	MaxPlaybackRate
	The maximum playback rate or scratching speed: 20. More...

Private Member Functions
	AdvancedAudioPlayer (const AdvancedAudioPlayer &)

AdvancedAudioPlayer &	operator= (const AdvancedAudioPlayer &)

Private Attributes
PlayerInternals *	internals

PlayerSwap *	swap

Detailed Description

High performance advanced audio player with:

time-stretching and pitch shifting,
beat and tempo sync,
scratching,
tempo bend,
looping,
slip mode,
fast seeking (cached points),
momentum and jog wheel handling,
0 latency, real-time operation,
low memory usage,
thread safety (all methods are thread-safe),
direct iPod music library access. Can be used in a real-time audio processing thread. Can not be used for offline processing. 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).
Http Live Streaming (HLS): vod/live/event streams, AAC-LC/MP3 in audio files or MPEG-TS files. Support for byte ranges and AES-128 encryption.

Constructor & Destructor Documentation

◆ AdvancedAudioPlayer() [1/2]

Superpowered::AdvancedAudioPlayer::AdvancedAudioPlayer	(	unsigned int	samplerate,
		unsigned char	cachedPointCount,
		unsigned int	internalBufferSizeSeconds = `2`,
		unsigned int	negativeSeconds = `0`
	)

Creates a player instance with the current sample rate value.

Parameters

samplerate	The initial sample rate of the player output in hz.
cachedPointCount	How many positions can be cached in the memory. Jumping to a cached point happens with zero latency. Loops are automatically cached.
internalBufferSizeSeconds	The number of seconds to buffer internally for playback and cached points. Minimum 2, maximum 60. Default: 2.
negativeSeconds	The number of seconds of silence in the negative direction, before the beginning of the track.

◆ ~AdvancedAudioPlayer()

Superpowered::AdvancedAudioPlayer::~AdvancedAudioPlayer ( )

◆ AdvancedAudioPlayer() [2/2]

Superpowered::AdvancedAudioPlayer::AdvancedAudioPlayer ( const AdvancedAudioPlayer & )

private

Member Function Documentation

◆ cachePosition()

void Superpowered::AdvancedAudioPlayer::cachePosition	(	double	ms,
		unsigned char	pointID = `255`
	)

Caches a position for zero latency seeking.

Parameters

ms	Position in milliseconds.
pointID	Use this to provide a custom identifier, so you can overwrite the same point later. Use 255 for a point with no identifier.

◆ closestBeatMs()

double Superpowered::AdvancedAudioPlayer::closestBeatMs	(	double	ms,
		unsigned char *	beatIndex = `0`
	)

Returns: Returns with the position of the closest beat.

Parameters

ms	The position in milliseconds where to find the closest beat.
beatIndex	Pointer to a beat index value. Set to NULL if beat index is not important. Set to 0 to retrieve the beat index of the position. Set to 1-4 to retrieve the position of a specific beat index.

◆ endContinuousPitchBend()

void Superpowered::AdvancedAudioPlayer::endContinuousPitchBend ( )

Ends pitch bend.

◆ endScratch()

void Superpowered::AdvancedAudioPlayer::endScratch ( bool returnToStateBeforeScratch )

Ends scratching.

Warning: This is an advanced method, use it only if not using the jogT... methods.

Parameters

returnToStateBeforeScratch Return to the previous playback state (direction, speed) or not.

◆ eofRecently()

bool Superpowered::AdvancedAudioPlayer::eofRecently ( )

Returns: Returns true if end-of-file has been reached recently (will never indicate end-of-file if loopOnEOF is true). This method should be used in a periodically running code at one place only, because it returns a specific end-of-file event just once. Best to be used in a UI loop.

◆ exitLoop()

void Superpowered::AdvancedAudioPlayer::exitLoop ( bool synchronisedStart = false )

Exit from the current loop.

Parameters

synchronisedStart Synchronized start or re-synchronization after the loop exit.

◆ getAudioStartMs()

double Superpowered::AdvancedAudioPlayer::getAudioStartMs ( )

Returns: Returns with the length of the digital silence at the beginning of the file if open() was called skipSilenceAtBeginning = true, 0 otherwise.

◆ getBeatIndex()

float Superpowered::AdvancedAudioPlayer::getBeatIndex ( )

Returns: Which beat has just happened. Possible values: 0 : unknown 1 - 1.999: first beat 2 - 2.999: second beat 3 - 3.999: third beat 4 - 4.999: fourth beat

◆ getBendOffsetMs()

double Superpowered::AdvancedAudioPlayer::getBendOffsetMs ( )

Returns: Returns with the distance (in milliseconds) to the beatgrid while using pitch bend for correction.

◆ getBufferedEndPercent()

float Superpowered::AdvancedAudioPlayer::getBufferedEndPercent ( )

Returns: Returns with the end of the buffered part. Will always be 1.0f for non-network sources (such as local files).

◆ getBufferedStartPercent()

float Superpowered::AdvancedAudioPlayer::getBufferedStartPercent ( )

Returns: Returns with the beginning of the buffered part. Will always be 0 for non-network sources (such as local files).

◆ getCurrentBpm()

double Superpowered::AdvancedAudioPlayer::getCurrentBpm ( )

Returns: The current bpm of the track (as changed by the playback rate).

◆ getCurrentHLSBPS()

unsigned int Superpowered::AdvancedAudioPlayer::getCurrentHLSBPS ( )

Returns: For HLS only. Returns with the actual network throughput (for best stream selection).

◆ getDisplayPositionMs()

double Superpowered::AdvancedAudioPlayer::getDisplayPositionMs ( )

Returns: The current position in milliseconds, immediately updated after setPosition() or seek(). Use this for UI display.

◆ getDisplayPositionPercent()

float Superpowered::AdvancedAudioPlayer::getDisplayPositionPercent ( )

Returns: Similar to getDisplayPositionMs(), but as a percentage (0 to 1).

◆ getDisplayPositionSeconds()

int Superpowered::AdvancedAudioPlayer::getDisplayPositionSeconds ( )

Returns: Similar to getDisplayPositionMs(), but as seconds elapsed.

◆ getDurationMs()

unsigned int Superpowered::AdvancedAudioPlayer::getDurationMs ( )

Returns: The duration of the current track in milliseconds. Returns UINT_MAX for live streams.

◆ getDurationSeconds()

unsigned int Superpowered::AdvancedAudioPlayer::getDurationSeconds ( )

Returns: The duration of the current track in seconds. Returns UINT_MAX for live streams.

◆ getFullyDownloadedFilePath()

const char* Superpowered::AdvancedAudioPlayer::getFullyDownloadedFilePath ( )

Returns: Returns with the full filesystem path of the locally cached file if the player is in the PlayerEvent_Opened_ProgressiveDownloadFinished state, NULL otherwise.

◆ getLatestEvent()

PlayerEvent Superpowered::AdvancedAudioPlayer::getLatestEvent ( )

Returns: Returns with the latest player event. This method should be used in a periodically running code, at one place only, because it returns a specific event just once per open() call. Best to be used in a UI loop.

◆ getMsDifference()

double Superpowered::AdvancedAudioPlayer::getMsDifference	(	double	phase,
		double	quantum
	)

Returns: Returns with the distance (in milliseconds) to a specific quantum and phase for quantized synchronization.

Parameters

phase	The phase to calculate against.
quantum	The quantum to calculate against.

◆ getMsElapsedSinceLastBeat()

double Superpowered::AdvancedAudioPlayer::getMsElapsedSinceLastBeat ( )

Returns: How many milliseconds elapsed since the last beat.

◆ getOpenErrorCode()

int Superpowered::AdvancedAudioPlayer::getOpenErrorCode ( )

Returns: If getLatestEvent returns with OpenFailed, retrieve the error code or HTTP status code here.

◆ getPhase()

double Superpowered::AdvancedAudioPlayer::getPhase ( )

Returns: Returns with the current phase for quantized synchronization.

◆ getPositionMs()

double Superpowered::AdvancedAudioPlayer::getPositionMs ( )

Returns: The current playhead position in milliseconds. Not changed by any pending setPosition() or seek() call, always accurate regardless of time-stretching and other transformations.

◆ getQuantum()

double Superpowered::AdvancedAudioPlayer::getQuantum ( )

Returns: Returns with the current quantum for quantized synchronization.

◆ getStemColor()

const char* Superpowered::AdvancedAudioPlayer::getStemColor ( unsigned char index )

Returns: Returns with a stem's color if a STEMS file was loaded, NULL otherwise.

◆ getStemName()

const char* Superpowered::AdvancedAudioPlayer::getStemName ( unsigned char index )

Returns: Returns with a stem's name if a STEMS file was loaded, NULL otherwise.

◆ getTempFolderPath()

static const char* Superpowered::AdvancedAudioPlayer::getTempFolderPath ( )

static

Returns: Returns with the temporary folder path.

◆ getWaitingForSyncStartMs()

double Superpowered::AdvancedAudioPlayer::getWaitingForSyncStartMs ( )

Returns: Indicates if the player is waiting to start playback on a synchronization event (such as the next beat) for how many milliseconds (continously updated). Happens when you call a method with synchronisedStart enabled. 0 means not waiting.

◆ getWillSyncMs()

double Superpowered::AdvancedAudioPlayer::getWillSyncMs ( )

Returns: Indicates if the player is waiting for a synchronization event (such as the next beat) for how many milliseconds (continously updated). 0 means not waiting.

◆ isLooping()

bool Superpowered::AdvancedAudioPlayer::isLooping ( )

Returns: Indicates if looping is enabled.

◆ isPerformingSlip()

bool Superpowered::AdvancedAudioPlayer::isPerformingSlip ( )

Returns: Indicates if returning from scratching or reverse playback will maintain the playback position as if the player had never entered into scratching or reverse playback.

◆ isPlaying()

bool Superpowered::AdvancedAudioPlayer::isPlaying ( )

Returns: Indicates if the player is playing or paused.

◆ isReverse()

bool Superpowered::AdvancedAudioPlayer::isReverse ( )

Returns: If true, the player is playing backwards.

◆ isScratching()

bool Superpowered::AdvancedAudioPlayer::isScratching ( )

Returns: Indicates if the player is in scratching mode.

◆ isStems()

bool Superpowered::AdvancedAudioPlayer::isStems ( )

Returns: Returns true if a STEMS file was loaded (and enableStems is also true).

◆ isWaitingForBuffering()

bool Superpowered::AdvancedAudioPlayer::isWaitingForBuffering ( )

Returns: Indicates if the player is waiting for data (such as waiting for a network download).

◆ jogTick()

void Superpowered::AdvancedAudioPlayer::jogTick	(	int	value,
		bool	bendStretch,
		float	bendMaxPercent,
		unsigned int	bendHoldMs,
		bool	parameterModeIfNoJogTouchBegin
	)

A jog wheel should send some "ticks" with the movement.

A waveform's movement in pixels for example.

Parameters

value	The icks value.
bendStretch	Use time-stretching for pitch bend or not (false makes it "audible").
bendMaxPercent	The maximum playback rate change for pitch bend, should be between 0.01f and 0.3f (1% and 30%).
bendHoldMs	How long to maintain the pitch bend state. A value >= 1000 will hold until endContinuousPitchBend is called.
parameterModeIfNoJogTouchBegin	True: if there was no jogTouchBegin, turn to JogMode_Parameter mode. False: if there was no jogTouchBegin, turn to JogMode_PitchBend mode.

◆ jogTouchBegin()

void Superpowered::AdvancedAudioPlayer::jogTouchBegin	(	int	ticksPerTurn,
		JogMode	mode,
		unsigned int	scratchSlipMs = `0`
	)

"Virtual jog wheel" or "virtual turntable" handling.

Parameters

ticksPerTurn	Sets the sensitivity of the virtual wheel. Use around 2300 for pixel-perfect touchscreen waveform control.
mode	Jog wheel mode (scratching, pitch bend, or parameter set in the 0-1 range).
scratchSlipMs	Enables slip mode for a specific amount of time for scratching, or 0 to not slip.

◆ jogTouchEnd()

void Superpowered::AdvancedAudioPlayer::jogTouchEnd	(	float	decelerate,
		bool	synchronisedStart
	)

Call this when the jog touch ends.

Parameters

decelerate	The decelerating rate for momentum. Set to 0.0f for automatic.
synchronisedStart	Beat-synced start after decelerating.

◆ loop()

bool Superpowered::AdvancedAudioPlayer::loop	(	double	startMs,
		double	lengthMs,
		bool	jumpToStartMs,
		unsigned char	pointID,
		bool	synchronisedStart,
		unsigned int	numLoops = `0`,
		bool	forceDefaultQuantum = `false`,
		bool	preferWaitingforSynchronisedStart = `false`
	)

Loop from a start point to some length.

Parameters

startMs	Loop from this milliseconds.
lengthMs	Loop length in milliseconds.
jumpToStartMs	If the playhead is within the loop, jump to startMs or not.
pointID	Looping caches startMs, therefore you can specify a pointID too (or set to 255 if you don't care).
synchronisedStart	Beat-synced start.
numLoops	Number of times to loop. 0 means: until exitLoop() is called.
forceDefaultQuantum	If true and using quantized synchronization, will use the defaultQuantum instead of the syncToQuantum.
preferWaitingforSynchronisedStart	Wait or start immediately when synchronized.

◆ loopBetween()

bool Superpowered::AdvancedAudioPlayer::loopBetween	(	double	startMs,
		double	endMs,
		bool	jumpToStartMs,
		unsigned char	pointID,
		bool	synchronisedStart,
		unsigned int	numLoops = `0`,
		bool	forceDefaultQuantum = `false`,
		bool	preferWaitingforSynchronisedStart = `false`
	)

Loop between a start and end points.

Parameters

startMs	Loop from this milliseconds.
endMs	Loop to this milliseconds.
jumpToStartMs	If the playhead is within the loop, jump to startMs or not.
pointID	Looping caches startMs, therefore you can specify a pointID too (or set to 255 if you don't care).
synchronisedStart	Beat-synced start.
numLoops	Number of times to loop. 0 means: until exitLoop() is called.
forceDefaultQuantum	If true and using quantized synchronization, will use the defaultQuantum instead of the syncToQuantum.
preferWaitingforSynchronisedStart	Wait or start immediately when synchronized.

◆ msInLoop()

bool Superpowered::AdvancedAudioPlayer::msInLoop ( double ms )

Returns: Returns true if a position is inside the current loop.

Parameters

ms	The position in milliseconds.

◆ onMediaserverInterrupt()

void Superpowered::AdvancedAudioPlayer::onMediaserverInterrupt ( )

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.

◆ open() [1/2]

void Superpowered::AdvancedAudioPlayer::open	(	const char *	path,
		Superpowered::httpRequest *	customHTTPRequest = `0`,
		bool	skipSilenceAtBeginning = `false`
	)

Opens an audio file with playback paused.

Playback rate, pitchShift, timeStretching and syncMode are NOT changed if you open a new file.

Warning: This method has no effect if the previous open didn't finish or if called in the audio processing thread.

Parameters

path	Full file system path or progressive download path (http or https).
customHTTPRequest	If custom HTTP communication is required (such as sending http headers for authorization), pass a fully prepared http request object. The player will copy this object.
skipSilenceAtBeginning	If true, the player will set the position to skip the initial digital silence of the audio file (up to 10 seconds).

◆ open() [2/2]

void Superpowered::AdvancedAudioPlayer::open	(	const char *	path,
		int	offset,
		int	length,
		Superpowered::httpRequest *	customHTTPRequest = `0`,
		bool	skipSilenceAtBeginning = `false`
	)

Opens an audio file with playback paused.

Playback rate, pitchShift, timeStretching and syncMode are NOT changed if you open a new file.

Warning: This method has no effect if the previous open didn't finish or if called in the audio processing thread.

Parameters

path	Full file system path or progressive download path (http or https).
offset	The byte offset inside the path.
length	The byte length from the offset.
customHTTPRequest	If custom HTTP communication is required (such as sending http headers for authorization), pass a fully prepared http request object. The player will copy this object.
skipSilenceAtBeginning	If true, the player will set the position to skip the initial digital silence of the audio file (up to 10 seconds).

◆ openHLS()

void Superpowered::AdvancedAudioPlayer::openHLS	(	const char *	url,
		Superpowered::httpRequest *	customHTTPRequest = `0`
	)

Opens a HTTP Live Streaming stream with playback paused.

Playback rate, pitchShift, timeStretching and syncMode are NOT changed if you open a new one. Do not call openHLS() in the audio processing thread.

Parameters

url	Stream URL.
customHTTPRequest	If custom HTTP communication is required (such as sending http headers for authorization), pass a fully prepared http request object. The player will copy this object.

◆ operator=()

AdvancedAudioPlayer& Superpowered::AdvancedAudioPlayer::operator= ( const AdvancedAudioPlayer & )

private

◆ pause()

void Superpowered::AdvancedAudioPlayer::pause	(	float	decelerateSeconds = `0`,
		unsigned int	slipMs = `0`
	)

Pause playback.

There is no need for a "stop" method, this player is very efficient with the battery and has no significant "stand-by" processing.

Parameters

decelerateSeconds	Optional momentum. 0 means to pause immediately.
slipMs	Enable slip mode for a specific amount of time, or 0 to not slip.

◆ pitchBend()

void Superpowered::AdvancedAudioPlayer::pitchBend	(	float	maxPercent,
		bool	bendStretch,
		bool	faster,
		unsigned int	holdMs
	)

Starts on changes pitch bend (temporary playback rate change).

Parameters

maxPercent	The maximum playback rate range for pitch bend, should be between 0.01f and 0.3f (1% and 30%).
bendStretch	Use time-stretching for pitch bend or not (false makes it "audible").
faster	True: faster, false: slower.
holdMs	How long to maintain the pitch bend state. A value >= 1000 will hold until endContinuousPitchBend is called.

◆ play()

void Superpowered::AdvancedAudioPlayer::play ( )

Starts playback immediately without any synchronization.

◆ playSynchronized()

void Superpowered::AdvancedAudioPlayer::playSynchronized ( )

Starts beat or tempo synchronized playback.

◆ playSynchronizedToPosition()

void Superpowered::AdvancedAudioPlayer::playSynchronizedToPosition ( double positionMs )

Starts playback at a specific position.

isPlaying() will return false until this function succeeds starting playback at the specified position. You can call this in a real-time thread (audio processing callback) with a continuously updated time for a precise on-the-fly launch.

Parameters

positionMs Start position in milliseconds.

◆ processMulti()

bool Superpowered::AdvancedAudioPlayer::processMulti	(	float **	buffers,
		bool	mix,
		unsigned int	numberOfFrames,
		float *	volumes,
		double *	jogParameter = `0`
	)

Processes audio, multi-channel version.

Returns: True: buffers has audio output from the player. False: the contents of buffer were not changed (typically happens when the player is paused).

Warning: Duration may change to a more precise value after this, because some file formats have no precise duration information.

Parameters

buffers	32-bit interleaved stereo input/output buffer pairs. Each pair should be numberOfFrames * 8 + 64 bytes big.
mix	If true, the player output will be added to the contents of buffers. If false, the contents of buffers will be overwritten with the player output.
numberOfFrames	The number of frames requested.
volumes	A volume for each buffer in buffers. 0.0f is silence, 1.0f is "original volume". Changes are automatically smoothed between consecutive processes.
jogParameter	If jog wheel mode is JogMode_Parameter, returns with the current parameter typically in the range of -1 to 1, or more than 1000000.0 if there was no jog wheel movement. Can be NULL if not interested.

◆ processSTEMSMaster()

void Superpowered::AdvancedAudioPlayer::processSTEMSMaster	(	float *	input,
		float *	output,
		unsigned int	numberOfFrames,
		float	volume = `1.0f`
	)

Performs the last stage of STEMS processing, the master compressor and limiter.

Works only if a STEMS file was loaded.

Parameters

input	Pointer to floating point numbers. 32-bit interleaved stereo input buffer.
output	Pointer to floating point numbers. 32-bit interleaved stereo output buffer.
numberOfFrames	The number of frames to process.
volume	0.0f is silence, 1.0f is "original volume". Changes are automatically smoothed between consecutive processes.

◆ processStereo()

bool Superpowered::AdvancedAudioPlayer::processStereo	(	float *	buffer,
		bool	mix,
		unsigned int	numberOfFrames,
		float	volume = `1.0f`,
		double *	jogParameter = `0`
	)

Processes audio, stereo version.

Returns: True: buffer has audio output from the player. False: the contents of buffer were not changed (typically happens when the player is paused).

Warning: Duration may change to a more precise value after this, because some file formats have no precise duration information.

Parameters

buffer	Pointer to floating point numbers. 32-bit interleaved stereo input/output buffer. Should be numberOfFrames * 8 + 64 bytes big.
mix	If true, the player output will be mixed with the contents of buffer. If false, the contents of buffer will be overwritten with the player output.
numberOfFrames	The number of frames requested.
volume	0.0f is silence, 1.0f is "original volume". Changes are automatically smoothed between consecutive processes.
jogParameter	If jog wheel mode is JogMode_Parameter, returns with the current parameter typically in the range of -1 to 1, or less than -1000000.0 if there was no jog wheel movement. Can be NULL if not interested.

◆ resetBendMsOffset()

void Superpowered::AdvancedAudioPlayer::resetBendMsOffset ( )

Reset the pitch bend offset to the beatgrid to zero.

◆ scratch()

void Superpowered::AdvancedAudioPlayer::scratch	(	double	pitch,
		float	smoothing
	)

Scratch movement.

Warning: This is an advanced method, use it only if not using the jogT... methods.

Parameters

pitch	The current speed.
smoothing	Should be between 0.05f (max. smoothing) and 1.0f (no smoothing).

◆ seek()

void Superpowered::AdvancedAudioPlayer::seek ( double percent )

Simple seeking to a percentage.

Parameters

percent The position in percentage.

◆ setPosition()

void Superpowered::AdvancedAudioPlayer::setPosition	(	double	ms,
		bool	andStop,
		bool	synchronisedStart,
		bool	forceDefaultQuantum = `false`,
		bool	preferWaitingforSynchronisedStart = `false`
	)

Precise seeking.

Parameters

ms	Position in milliseconds.
andStop	If true, stops playback.
synchronisedStart	If andStop is false, makes a beat-synced start possible.
forceDefaultQuantum	If true and using quantized synchronization, will use the defaultQuantum instead of the syncToQuantum.
preferWaitingforSynchronisedStart	Wait or start immediately when synchronized.

◆ setReverse()

void Superpowered::AdvancedAudioPlayer::setReverse	(	bool	reverse,
		unsigned int	slipMs = `0`
	)

Sets playback direction.

Parameters

reverse	True: reverse. False: forward.
slipMs	Enable slip mode for a specific amount of time, or 0 to not slip.

◆ setTempFolder()

static void Superpowered::AdvancedAudioPlayer::setTempFolder ( const char * path )

static

Set the folder to store for temporary files.

Used for HLS and progressive download only. Call this before any player instance is created. It will create a subfolder with the name "SuperpoweredAAP" in the specified folder (and will clear all content inside SuperpoweredAAP if it exists already). If you need to clear the folder before your app quits, use NULL for the path.

Parameters

path	File system path of the folder.

◆ startScratch()

void Superpowered::AdvancedAudioPlayer::startScratch	(	unsigned int	slipMs,
		bool	stopImmediately
	)

Direct turntable handling.

Call this when scratching starts.

Warning: This is an advanced method, use it only if not using the jogT... methods.

Parameters

slipMs	Enable slip mode for a specific amount of time for scratching, or 0 to not slip.
stopImmediately	Stop playback or not.

◆ statusCodeToString()

static const char* Superpowered::AdvancedAudioPlayer::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.

◆ togglePlayback()

void Superpowered::AdvancedAudioPlayer::togglePlayback ( )

Toggle play/pause (no synchronization).

Member Data Documentation

◆ defaultQuantum

double Superpowered::AdvancedAudioPlayer::defaultQuantum

Sets the quantum for quantized synchronization. Example: 4 means 4 beats.

◆ enableStems

bool Superpowered::AdvancedAudioPlayer::enableStems

If true and a Native Instruments STEMS file is loaded, output 4 stereo channels. Default: false (stereo master mix output).

◆ firstBeatMs

double Superpowered::AdvancedAudioPlayer::firstBeatMs

Tells where the first beat is (the beatgrid starts). Must be set to a correct value for syncing. Default: 0.

◆ fixDoubleOrHalfBPM

bool Superpowered::AdvancedAudioPlayer::fixDoubleOrHalfBPM

If true and playbackRate is above 1.4f or below 0.6f, it will sync the tempo as half or double. Default: false.

◆ HLSAutomaticAlternativeSwitching

bool Superpowered::AdvancedAudioPlayer::HLSAutomaticAlternativeSwitching

If true, then the player will automatically swtich between the HLS alternatives according to the available network bandwidth. Default: true.

◆ HLSBufferingSeconds

int Superpowered::AdvancedAudioPlayer::HLSBufferingSeconds

How many seconds ahead of the playback position to download. Default value: HLS_DOWNLOAD_REMAINING.

◆ HLSDownloadEverything

const int Superpowered::AdvancedAudioPlayer::HLSDownloadEverything

static

Will download everything after the playback position until the end.

◆ HLSDownloadRemaining

const int Superpowered::AdvancedAudioPlayer::HLSDownloadRemaining

static

Downloads everything from the beginning to the end, regardless the playback position.

◆ HLSLiveLatencySeconds

char Superpowered::AdvancedAudioPlayer::HLSLiveLatencySeconds

When connecting or reconnecting to a HLS live stream, the player will try to skip audio to maintain this latency. Default: -1 (the player wil not skip audio and the live stream starts at the first segment specified by the server).

◆ HLSMaximumDownloadAttempts

int Superpowered::AdvancedAudioPlayer::HLSMaximumDownloadAttempts

How many times to retry if a HLS segment download fails. Default: 100.

◆ internals

PlayerInternals* Superpowered::AdvancedAudioPlayer::internals

private

◆ loopOnEOF

bool Superpowered::AdvancedAudioPlayer::loopOnEOF

If true, jumps back and continues playback. If false, playback stops. Default: false.

◆ maximumTimestretchingPlaybackRate

float Superpowered::AdvancedAudioPlayer::maximumTimestretchingPlaybackRate

Will not time-stretch but resample above this playback rate. Default: 2.0f (the recommended value for low CPU load on older mobile devices, such as the first iPad). Will be applied after changing playbackRate or scratching.

◆ MaxPlaybackRate

const float Superpowered::AdvancedAudioPlayer::MaxPlaybackRate

static

The maximum playback rate or scratching speed: 20.

◆ minimumTimestretchingPlaybackRate

float Superpowered::AdvancedAudioPlayer::minimumTimestretchingPlaybackRate

Will not time-stretch but resample below this playback rate. Default: 0.501f (the recommended value for low CPU load on older mobile devices, such as the first iPad). Will be applied after changing playbackRate or scratching.

◆ originalBPM

double Superpowered::AdvancedAudioPlayer::originalBPM

The original bpm of the current music. There is no auto-bpm detection inside, this must be set to a correct value for syncing. Maximum 300. A value below 20 will be automatically set to 0. Default: 0 (no bpm value known).

◆ outputSamplerate

unsigned int Superpowered::AdvancedAudioPlayer::outputSamplerate

The player output sample rate in Hz.

◆ pitchShiftCents

int Superpowered::AdvancedAudioPlayer::pitchShiftCents

Pitch shift cents, from -1200 (one octave down) to 1200 (one octave up). Use values representing notes (multiply of 100) for low CPU load. Default: 0 (no pitch shift).

◆ playbackRate

double Superpowered::AdvancedAudioPlayer::playbackRate

The playback rate. Must be positive and above 0.00001. Default: 1.

◆ reverseToForwardAtLoopStart

bool Superpowered::AdvancedAudioPlayer::reverseToForwardAtLoopStart

If this is true with playing backwards and looping, then reaching the beginning of the loop will change playback direction to forwards. Default: false.

◆ swap

PlayerSwap* Superpowered::AdvancedAudioPlayer::swap

private

◆ syncMode

SyncMode Superpowered::AdvancedAudioPlayer::syncMode

The current sync mode (off, tempo, or tempo+beat). Default: off.

◆ syncToBpm

double Superpowered::AdvancedAudioPlayer::syncToBpm

A bpm value to sync with. Use 0.0f for no syncing.

◆ syncToMsElapsedSinceLastBeat

double Superpowered::AdvancedAudioPlayer::syncToMsElapsedSinceLastBeat

The number of milliseconds elapsed since the last beat on audio the player has to sync with. Use -1.0 to ignore.

◆ syncToPhase

double Superpowered::AdvancedAudioPlayer::syncToPhase

Used for quantized synchronization. The phase to sync with.

◆ syncToQuantum

double Superpowered::AdvancedAudioPlayer::syncToQuantum

Used for quantized synchronization. The quantum to sync with.

◆ timeStretching

bool Superpowered::AdvancedAudioPlayer::timeStretching

Enable/disable time-stretching. Default: true.

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

latest/Superpowered/SuperpoweredAdvancedAudioPlayer.h

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ AdvancedAudioPlayer() [1/2]

◆ ~AdvancedAudioPlayer()

◆ AdvancedAudioPlayer() [2/2]

Member Function Documentation

◆ cachePosition()

◆ closestBeatMs()

◆ endContinuousPitchBend()

◆ endScratch()

◆ eofRecently()

◆ exitLoop()

◆ getAudioStartMs()

◆ getBeatIndex()

◆ getBendOffsetMs()

◆ getBufferedEndPercent()

◆ getBufferedStartPercent()

◆ getCurrentBpm()

◆ getCurrentHLSBPS()

◆ getDisplayPositionMs()

◆ getDisplayPositionPercent()

◆ getDisplayPositionSeconds()

◆ getDurationMs()

◆ getDurationSeconds()

◆ getFullyDownloadedFilePath()

◆ getLatestEvent()

◆ getMsDifference()

◆ getMsElapsedSinceLastBeat()

◆ getOpenErrorCode()

◆ getPhase()

◆ getPositionMs()

◆ getQuantum()

◆ getStemColor()

◆ getStemName()

◆ getTempFolderPath()

◆ getWaitingForSyncStartMs()

◆ getWillSyncMs()

◆ isLooping()

◆ isPerformingSlip()

◆ isPlaying()

◆ isReverse()

◆ isScratching()

◆ isStems()

◆ isWaitingForBuffering()

◆ jogTick()

◆ jogTouchBegin()

◆ jogTouchEnd()

◆ loop()

◆ loopBetween()

◆ msInLoop()

◆ onMediaserverInterrupt()

◆ open() [1/2]

◆ open() [2/2]

◆ openHLS()

◆ operator=()

◆ pause()

◆ pitchBend()

◆ play()

◆ playSynchronized()

◆ playSynchronizedToPosition()

◆ processMulti()

◆ processSTEMSMaster()

◆ processStereo()

◆ resetBendMsOffset()

◆ scratch()

◆ seek()

◆ setPosition()

◆ setReverse()

◆ setTempFolder()

◆ startScratch()

◆ statusCodeToString()

◆ togglePlayback()

Member Data Documentation

◆ defaultQuantum