spRemoveSound

Manually remove an SPSound from an SPPlayer.

Synopsis

Err spRemoveSound (SPSound *sound)

Description

Removes and frees the specified sound from the SPPlayer that it belongs to. All markers belonging to this sound including any the client may have added, are automatically freed by this function.

All sounds belonging to an SPPlayer are automatically disposed of when that SPPlayer is disposed of with spDeletePlayer(). Use this function if you want to remove a sound manually.

For sound file class SPSounds, the file opened by spAddSoundFile() is closed. The sample item passed into spAddSample() is left behind after this spRemoveSound() for the client to clean up.

An SPSound cannot be removed from its owning SPPlayer while it is being read from while the player is running. spIsSoundInUse() can be used to determine if the sound is being read. If this function is called for an SPSound for which spIsSoundInUse() returns TRUE, the SPPlayer is stopped by calling spStop().

Arguments

sound: Pointer to an SPSound to remove. Can be NULL.

Return Value

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

Caveats

This function only stops the SPPlayer when while the SPPlayer is still reading from the SPSound being removed, which is fine for AIFF Sound File class SPSounds. For Sample Item class SPSounds, the player passes pointers to the Sample Item's sound data in memory the SoundSpooler rather than copying the sound data to the SPPlayer's buffers. That means that the sound data must remain valid until the SoundSpooler has completely played the sound data, which happens some amount of time after the SPPlayer is done 'reading' that data.

If you remove a Sample Item class SPSound during that window of vulnerability and then delete the data for the Sample Item (e.g. UnloadSample()), the SoundSpooler is then pointing to freed memory, whose contents may be clobbered by another task at any time. Unfortunately you may not hear bad results if you do this inadvertently because there's no guarantee that freed memory will get trashed (unless you are running a daemon to munge newly freed memory).

So, avoid removing Sample Item class SPSounds while the SPPlayer is playing. Or at least go to measures to insure that the Sample Item class SPSound you are removing is not in the spooler (e.g. it has never been played, or at least not since the last spStop()).

Implementation

Library call implemented in music.lib V24.

Associated Files

soundplayer.h, music.lib