Player control functions

These functions support file playback. More...

Functions
ASX32_API ASX_ERROR	ASX_Player_Open (ASX_HANDLE hPlayer, const char *pszFile)
	Open a file for playback.
ASX32_API ASX_ERROR	ASX_Player_Format_GetString (ASX_HANDLE hPlayer, char **pszFormat)
	Get the format of the currently opened file as a string.
ASX32_API ASX_ERROR	ASX_Player_Format_GetDetails (ASX_HANDLE hPlayer, enum asxAUDIO_FORMAT *peFormat, int *pnChannnels, int *pnSampleRate, int *pnBitRate)
	Get the format of the currently opened file as individual variables.
ASX32_API ASX_ERROR	ASX_Player_PreLoad (ASX_HANDLE hPlayer, const enum asxTIMESCALE nType, const unsigned long lPosition)
	Preloads playback buffers from the given position, ready for playback.
ASX32_API ASX_ERROR	ASX_Player_Start (ASX_HANDLE hPlayer)
	Start playback of a previously opened (and optionally pre-loaded) file.
ASX32_API ASX_ERROR	ASX_Player_Pause (ASX_HANDLE hPlayer)
	Pause playback of the currently playing file.
ASX32_API ASX_ERROR	ASX_Player_Stop (ASX_HANDLE hPlayer)
	Stops playback of the currently playing file.
ASX32_API ASX_ERROR	ASX_Player_Wait (ASX_HANDLE hPlayer)
	Wait for the current file to finish.
ASX32_API ASX_ERROR	ASX_Player_Close (ASX_HANDLE hPlayer)
	Close the current playback file.
ASX32_API ASX_ERROR	ASX_Player_GetPosition (ASX_HANDLE hPlayer, const enum asxTIMESCALE nType, unsigned long *plPosition)
	Get the current playback position as the offset in bytes, samples or milliseconds from the beginning or end of the file depending on the timescale code used.
ASX32_API ASX_ERROR	ASX_Player_SetPosition (ASX_HANDLE hPlayer, const enum asxTIMESCALE nType, const unsigned long lPosition)
	Sets the playback to the given position.
ASX32_API ASX_ERROR	ASX_Player_GetState (ASX_HANDLE hPlayer, enum asxPLAYER_STATE *pnState)
	Get the current playback state.
ASX32_API ASX_ERROR	ASX_Player_SetTimeScale (ASX_HANDLE hPlayer, const float fTimeScale)
	Set the playback timescale.
ASX32_API ASX_ERROR	ASX_Player_GetTimeScale (ASX_HANDLE hPlayer, float *pfTimeScale)
	Get the playback timescale.
ASX32_API ASX_ERROR	ASX_Player_GetFilename (ASX_HANDLE hPlayer, char *pszFilename, const int nStringLength, int *pnRequiredLength)
	Get the current filename, if any.
ASX32_API ASX_ERROR	ASX_Player_SetLoopMode (ASX_HANDLE hPlayer, const int nLooping)
	Set the player to loop or single play mode.
ASX32_API ASX_ERROR	ASX_Player_GetLoopMode (ASX_HANDLE hPlayer, int *pnLooping)
	Get the current player loop mode.
ASX32_API ASX_ERROR	ASX_Player_OpenPlaylist (ASX_HANDLE hPlayer, const char **pszFileList, const unsigned int nFiles)
	Open a list of files for playback.
ASX32_API ASX_ERROR	ASX_Player_PlaylistStatus (ASX_HANDLE hPlayer, unsigned int *nTotalFileCount, int *nCurrentFile, char **szCurrentFilename, unsigned int *nTotalTime_ms, unsigned int *nCurrentTime_ms)
	Returns playlist status.
ASX32_API ASX_ERROR	ASX_Player_RegisterCallback (ASX_HANDLE hPlayer, ASX_PLAYER_CALLBACK *pCallback, const enum asxPLAYER_FLAGS flags, void *pUser1)
	Register a callback function that should be called when playback has completed.
ASX32_API ASX_ERROR	ASX_Player_PlaylistWait (ASX_HANDLE hPlayer)
	Wait for the playlist to finish.

---

Detailed Description

These functions support file playback.

The player control transparently supports the playback of several different file formats and compression formats. Formats supported for playback in this version:

asxFILE_FORMAT	_WAV	_RAW
Filename Extension	.WAV	any
_PCM8 or _PCM16	supported	write only
_PCM24 or _PCM32	supported	write only
_PCM32_FLOAT	supported	write only
_MPEG_L2	supported	supported
_MPEG_L3	supported	supported
_MPEG_AACPLUS	not supported yet	not supported yet
_DOLBY_AC2	not supported yet	not supported yet

Note: RAW format playback currently cannot support PCM data formats due to the lack format information in the file. A future version of ASX will include a new playback function to play raw PCM files.

Player State Diagram

---

Function Documentation

ASX32_API ASX_ERROR ASX_Player_Close

(

ASX_HANDLE

hPlayer

)

Close the current playback file.

Parameters:

hPlayer

A handle to an ASX player control object.

Returns:

Returns 0 if there is no error, otherwise one of asxERROR is returned.

Examples:

play/main.c, and playlist/main.c.

ASX32_API ASX_ERROR ASX_Player_Format_GetDetails	(	ASX_HANDLE	hPlayer,
		enum asxAUDIO_FORMAT *	peFormat,
		int *	pnChannnels,
		int *	pnSampleRate,
		int *	pnBitRate
	)

Get the format of the currently opened file as individual variables.

Parameters:

hPlayer	A handle to an ASX player control object.
peFormat	The returned format code - see asxAUDIO_FORMAT.
pnChannnels	The returned number of channels.
pnSampleRate	The returned sample rate.
pnBitRate	The returned bitrate.

Returns:

Returns 0 if there is no error, otherwise one of asxERROR is returned.

ASX32_API ASX_ERROR ASX_Player_Format_GetString	(	ASX_HANDLE	hPlayer,
		char **	pszFormat
	)

Get the format of the currently opened file as a string.

Parameters:

hPlayer	A handle to an ASX player control object.
pszFormat	The returned pointer to a format string.

Returns:

Returns 0 if there is no error, otherwise one of asxERROR is returned.

Examples:

play/main.c, and playlist/main.c.

ASX32_API ASX_ERROR ASX_Player_GetFilename	(	ASX_HANDLE	hPlayer,
		char *	pszFilename,
		const int	nStringLength,
		int *	pnRequiredLength
	)

Get the current filename, if any.

Parameters:

hPlayer	A handle to an ASX player control object.
pszFilename	The returned pointer to the filename.
nStringLength	The length in bytes of pszFilename.
pnRequiredLength	The required length in bytes of pszRevision.

Returns:

Returns 0 if there is no error, otherwise one of asxERROR is returned. Returns asxERROR_INDEX_OUT_OF_RANGE if the buffer is too small.

ASX32_API ASX_ERROR ASX_Player_GetLoopMode	(	ASX_HANDLE	hPlayer,
		int *	pnLooping
	)

Get the current player loop mode.

Parameters:

hPlayer	A handle to an ASX player control object.
pnLooping	Pointer to return value: 1 for looping, 0 for single play.

Returns:

Returns 0 if there is no error, otherwise one of asxERROR is returned. Returns asxERROR_INDEX_OUT_OF_RANGE if the buffer is too small.

ASX32_API ASX_ERROR ASX_Player_GetPosition	(	ASX_HANDLE	hPlayer,
		const enum asxTIMESCALE	nType,
		unsigned long *	plPosition
	)

Get the current playback position as the offset in bytes, samples or milliseconds from the beginning or end of the file depending on the timescale code used.

NOTE: For compressed file it is assumed that the same bitrate is used throughout the file. If the file uses different bitrates (sometimes called "bitrate switching") then the position may not be accurate.

Parameters:

hPlayer	A handle to an ASX player control object.
nType	The units to return the position in (see asxTIMESCALE).
plPosition	The current relative playback position.

Returns:

Returns 0 if there is no error, otherwise one of asxERROR is returned.

ASX32_API ASX_ERROR ASX_Player_GetState	(	ASX_HANDLE	hPlayer,
		enum asxPLAYER_STATE *	pnState
	)

Get the current playback state.

Parameters:

hPlayer	A handle to an ASX player control object.
pnState	The current player state. See asxPLAYER_STATE.

Returns:

Returns 0 if there is no error, otherwise one of asxERROR is returned.

Examples:

play/main.c.

ASX32_API ASX_ERROR ASX_Player_GetTimeScale	(	ASX_HANDLE	hPlayer,
		float *	pfTimeScale
	)

Get the playback timescale.

This function allows the user read the time ratio. Time scale range is 0.8 - 1.2 (80% to o120%) of original file time.

Note:

This function is only supported on the ASI6xxx series adapters.

Parameters:

hPlayer	A handle to an ASX player control object.
pfTimeScale	Pointer to the returned time scale. Range is 0.8 < fTimeScale < 1.2.

Returns:

Returns 0 if there is no error, otherwise one of asxERROR is returned.

ASX32_API ASX_ERROR ASX_Player_Open	(	ASX_HANDLE	hPlayer,
		const char *	pszFile
	)

Open a file for playback.

Parameters:

hPlayer	A handle to an ASX player control object.
pszFile	The name of the file to play. This can be the name of a file in the current directory or a fully qualified path name The file can be a .wav or .mp3 file. Note that MP3 playback is currently only supported on those adapters that support MP3 decoding. This would be the ASI43xx and ASI6xxx series.

You can also generate a sine wave. The format of the string is: "~w,c,f,a,m,s,t"

w = waveform = SINE (default=SINE)
c = channels = 1..8 (default = 2)
f = frequency = 1000 for 1kHz (default=1000)
a = amplitude = -1 for -1dBFs (default=0dBFS, ie full scale)
m = channel_mask = 10 for left only, 01 for right only, 11 for stereo etc (default=1 for all channels)
t = sampletype = (PCM8,PCM16,PCM24,PCM32,FLOAT32), (default=FLOAT32)
s = samplerate = positive integer (default=48000) [validity depends on adapter]

Defaults can be used if the complete string is not specifed, ie

"~" -> "~wSINE,c2,f1000,a0,m11,s48000,tFLOAT32"

Any subset of the options may be specified, the remaining options will be set to the defaults. eg "~f500" -> 500Hz stereo sine wave at 0dBFS, 48kHz samplerate

Returns:

Returns 0 if there is no error, otherwise one of asxERROR is returned.

Examples:

play/main.c, and playlist/main.c.

ASX32_API ASX_ERROR ASX_Player_OpenPlaylist	(	ASX_HANDLE	hPlayer,
		const char **	pszFileList,
		const unsigned int	nFiles
	)

Open a list of files for playback.

Parameters:

hPlayer	A handle to an ASX player control object.
pszFileList	The names of the files to play. This can be the name of a file in the current directory or a fully qualified path name. See ASX_Player_Open(). Note that the player makes a copy of the filelist, so there in no need for the calling application to keep the list of strings in the calling context.
nFiles	The number of files in the playlist.

Returns:

Returns 0 if there is no error, otherwise one of asxERROR is returned.

Examples:

playlist/main.c.

ASX32_API ASX_ERROR ASX_Player_Pause

(

ASX_HANDLE

hPlayer

)

Pause playback of the currently playing file.

Use ASX_Player_Start to continue playing. To end a paused recording call ASX_Player_Stop.

Parameters:

hPlayer

A handle to an ASX player control object.

Returns:

Returns 0 if there is no error, otherwise one of asxERROR is returned.

ASX32_API ASX_ERROR ASX_Player_PlaylistStatus	(	ASX_HANDLE	hPlayer,
		unsigned int *	nTotalFileCount,
		int *	nCurrentFile,
		char **	szCurrentFilename,
		unsigned int *	nTotalTime_ms,
		unsigned int *	nCurrentTime_ms
	)

Returns playlist status.

Use this function to monitor playlist progress.

Parameters:

hPlayer	A handle to an ASX player control object.
nTotalFileCount	Returns the total number of files remaining in the current playlist. This will equal the parameter "nFiles" used in the call to ASX_Player_OpenPlaylist()
nCurrentFile	Returns the index of the currently playing file. A value of -1 indicates that the first file has not yet started. The range of nCurrentFile is 0 to (nTotalFileCount-1). A pause operation does not affect the value returned by nCurrentFile.
szCurrentFilename	The name of the current file being played. This returns "undefined" before the first Start() command is issued.
nTotalTime_ms	The total time in milliseconds of all the files that are in the playback list. Note that this variable will be affected if timescaling is enabled.
nCurrentTime_ms	The current accumlated time of the file list playback in milliseconds. This will range from 0 to nTotalTime_ms. Note that this variable will be affected if timescaling is enabled.

Examples:

playlist/main.c.

ASX32_API ASX_ERROR ASX_Player_PlaylistWait

(

ASX_HANDLE

hPlayer

)

Wait for the playlist to finish.

This function does not return until the current playlist has finished playing.

Parameters:

hPlayer

A handle to an ASX player control object.

Returns:

Returns 0 if there is no error, otherwise one of asxERROR is returned.

Examples:

playlist/main.c.

ASX32_API ASX_ERROR ASX_Player_PreLoad	(	ASX_HANDLE	hPlayer,
		const enum asxTIMESCALE	nType,
		const unsigned long	lPosition
	)

Preloads playback buffers from the given position, ready for playback.

This function will seek to the specified file position and then load audio buffers from the file. This shortens the time between the time a ASX_Player_Start() is issued and the time for audio to be output.

Note:

This function does not have to be used. It is optional. If ASX_Player_Start() is called without calling ASX_Player_PreLoad(), the preload operation will happen internal to the ASX_Player_Start() call. The assumption will also be that playback begins at the start of the audio file.

Parameters:

hPlayer	A handle to an ASX player control object.
nType	The units of lPosition (see asxTIMESCALE).
lPosition	The position to start playback from. A value of zero start from the beginning of the file.

Returns:

Returns 0 if there is no error, otherwise one of asxERROR is returned.

Examples:

play/main.c, and playlist/main.c.

ASX32_API ASX_ERROR ASX_Player_RegisterCallback	(	ASX_HANDLE	hPlayer,
		ASX_PLAYER_CALLBACK *	pCallback,
		const enum asxPLAYER_FLAGS	flags,
		void *	pUser1
	)

Register a callback function that should be called when playback has completed.

Note that using this function is optional.

Parameters:

hPlayer	A handle to an ASX player control object.
pCallback	A pointer to a callback of type ASX_PLAYER_CALLBACK.
flags	Defines whether the callback should be called on file completion and/or filelist completion. See asxPLAYER_FLAGS.
pUser1	A user defined pointer that is passed back when a callback is made.

Examples:

playlist/main.c.

ASX32_API ASX_ERROR ASX_Player_SetLoopMode	(	ASX_HANDLE	hPlayer,
		const int	nLooping
	)

Set the player to loop or single play mode.

Parameters:

hPlayer	A handle to an ASX player control object.
nLooping	1 for looping, 0 for single play.

Returns:

Returns 0 if there is no error, otherwise one of asxERROR is returned. Returns asxERROR_INDEX_OUT_OF_RANGE if the buffer is too small.

ASX32_API ASX_ERROR ASX_Player_SetPosition	(	ASX_HANDLE	hPlayer,
		const enum asxTIMESCALE	nType,
		const unsigned long	lPosition
	)

Sets the playback to the given position.

Parameters:

hPlayer	A handle to an ASX player control object.
nType	The units of lPosition (see asxTIMESCALE).
lPosition	The position playback from.

Returns:

Returns 0 if there is no error, otherwise one of asxERROR is returned.

ASX32_API ASX_ERROR ASX_Player_SetTimeScale	(	ASX_HANDLE	hPlayer,
		const float	fTimeScale
	)

Set the playback timescale.

This function allows the user to adjust the time a file takes to playback without affecting the pitch. Time scale range is 0.8 - 1.2 (80% to o120%) of original file time.

Note:

This function is only supported on the ASI6xxx series adapters.

Parameters:

hPlayer	A handle to an ASX player control object.
fTimeScale	The time scale to use on the playing file. Range is 0.8 < fTimeScale < 1.2.

Returns:

Returns 0 if there is no error, otherwise one of asxERROR is returned.

ASX32_API ASX_ERROR ASX_Player_Start

(

ASX_HANDLE

hPlayer

)

Start playback of a previously opened (and optionally pre-loaded) file.

Parameters:

hPlayer

A handle to an ASX player control object.

Returns:

Returns 0 if there is no error, otherwise one of asxERROR is returned.

Examples:

play/main.c, and playlist/main.c.

ASX32_API ASX_ERROR ASX_Player_Stop

(

ASX_HANDLE

hPlayer

)

Stops playback of the currently playing file.

This call resets the play position as well as stopping playback. Use ASX_Player_Pause() to retain the current position.

Parameters:

hPlayer

A handle to an ASX player control object.

Returns:

Returns 0 if there is no error, otherwise one of asxERROR is returned.

Examples:

play/main.c.

ASX32_API ASX_ERROR ASX_Player_Wait

(

ASX_HANDLE

hPlayer

)

Wait for the current file to finish.

This function does not return until the current file has finished playing.

Parameters:

hPlayer

A handle to an ASX player control object.

Returns:

Returns 0 if there is no error, otherwise one of asxERROR is returned.

Examples:

play/main.c.