ASX Version4.13.09
Functions

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 ASX Player State Diagram.


Function Documentation

ASX32_API ASX_ERROR ASX_Player_Close ( ASX_HANDLE  hPlayer)

Close the current playback file.

Parameters:
hPlayerA 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:
hPlayerA handle to an ASX player control object.
peFormatThe returned format code - see asxAUDIO_FORMAT.
pnChannnelsThe returned number of channels.
pnSampleRateThe returned sample rate.
pnBitRateThe 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:
hPlayerA handle to an ASX player control object.
pszFormatThe 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:
hPlayerA handle to an ASX player control object.
pszFilenameThe returned pointer to the filename.
nStringLengthThe length in bytes of pszFilename.
pnRequiredLengthThe 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:
hPlayerA handle to an ASX player control object.
pnLoopingPointer 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:
hPlayerA handle to an ASX player control object.
nTypeThe units to return the position in (see asxTIMESCALE).
plPositionThe 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:
hPlayerA handle to an ASX player control object.
pnStateThe 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:
hPlayerA handle to an ASX player control object.
pfTimeScalePointer 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:
hPlayerA handle to an ASX player control object.
pszFileThe 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:
hPlayerA handle to an ASX player control object.
pszFileListThe 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.
nFilesThe 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:
hPlayerA 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:
hPlayerA handle to an ASX player control object.
nTotalFileCountReturns the total number of files remaining in the current playlist. This will equal the parameter "nFiles" used in the call to ASX_Player_OpenPlaylist()
nCurrentFileReturns 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.
szCurrentFilenameThe name of the current file being played. This returns "undefined" before the first Start() command is issued.
nTotalTime_msThe 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_msThe 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:
hPlayerA 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:
hPlayerA handle to an ASX player control object.
nTypeThe units of lPosition (see asxTIMESCALE).
lPositionThe 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:
hPlayerA handle to an ASX player control object.
pCallbackA pointer to a callback of type ASX_PLAYER_CALLBACK.
flagsDefines whether the callback should be called on file completion and/or filelist completion. See asxPLAYER_FLAGS.
pUser1A 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:
hPlayerA handle to an ASX player control object.
nLooping1 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:
hPlayerA handle to an ASX player control object.
nTypeThe units of lPosition (see asxTIMESCALE).
lPositionThe 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:
hPlayerA handle to an ASX player control object.
fTimeScaleThe 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:
hPlayerA 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:
hPlayerA 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:
hPlayerA 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.