spStartPlaying

Begin emitting sound for an SPPlayer.

Synopsis

Err spStartPlaying (SPPlayer *player, const TagArg *samplerTags)
Err spStartPlayingVA (SPPlayer *player, uint32 samplerTag1, ...)

Description

Begins the actual output of spooled sound. This function begins playback immediately making it suitable for being called in sync with some user activity if necessary. spStartReading() prefills the spooler buffers. This function should therefore be called some time after calling spStartReading().

Calling this function starts the process of signals arriving which need to be serviced with spService(). This function causes the SP_STATUS_F_PLAYING flag to be set.

Call spStop() to manually stop or wait for playback to finish by checking spGetPlayerStatus() after calling spService().

Arguments

player
Pointer to SPPlayer to start playing.

Tags

AF_TAG_AMPLITUDE
(uint32) Amplitude to set SPPlayer's sample player instrument to. Defaults to whatever the last setting was. Valid range is 0 to 0x7fff.
AF_TAG_RATE
(uint32) Sample playback rate value for variable rate sample player instruments expressed as a 1.15 fixed point value. 0x8000 is the normal rate (e.g. 44100 sample frames / sec). Valid range is 0x0001 (really, really, slow) to 0xffff (nearly twice the normal rate). Defaults to whatever the last setting was (variable rate sample player instruments typically default to 0x8000). Ignored for fixed rate sample players.

Return Value

Non-negative value on success; negative error code on failure.

Notes

The only bad thing that will happen if you call this function before calling spStartReading() is that you won't have any control over the precise time that playback begins. In that case, playback would start as soon as spStartReading() has read a buffer's worth of data. The player also might starve briefly if the 2nd buffer weren't ready before the first one finished.

Multiple calls to spStartPlaying() without an intervening stop of some kind (spStop() or marker causing a stop) cause stuttered sound output.

A call to spStartPlaying() will supercede a previous call to spPause().

Implementation

Library call implemented in music.lib V24.

Associated Files

soundplayer.h, music.lib

See Also

spStartReading(),spStop(),spService(),spGetPlayerStatus()