Player control functions

---

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

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.
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.

---

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.

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.

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. This function returns the relative playback position since the file start playing. The position is relative to the position at which playback was started. 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.

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.

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_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.

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_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.

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.

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.

---