Songs and sound effects can be played once the preparations of the previous section have been made. When audio is played back, the maximum number of channels for use are automatically secured.
To playback a song, all you need to do is specify the address of that song. When a song is played, sample bank data is used in addition to the song's data.
Start a song
| Function name: | MusStartSong | |
| Syntax: | musHandle MusStartSong(void *addr) | |
| Arguments: | addr | The address of the song in RAM |
| Return value: | The sound handle value | |
The returned sound handle value is used later to specify the song that is being played back.
To playback a sound effect, all you need to do is to specify which number sound effect in the sound effect bank to play. When a sound effect is played, sample bank data is used in addition to the sound effect bank's data.
Start a sound effect
| Function name: | MusStartEffect | |
| Syntax: | musHandle MusStartEffect(s32 number) | |
| Arguments: | number | The number of the sound effect to play |
| Return value: | The sound handle value | |
Next we explain how to stop the playback of audio. For songs without loops and for sound effects, the channels will be released when the audio ends even if the audio has not been explicitly stopped.
There are two kinds of functions for stopping the audio. MusStop stops the songs or sound effects or both if such has been specified. In contrast, MusHandleStop stops the audio using the sound handle. With either function you can specify how many frames to go before stopping the audio. When a non-zero frame number is specified, the audio will fade out for the specified number of frames.
Stop channels
| Function name: | MusStop |
| Syntax: | void MusStop(u64 flags, s32 speed) |
| Arguments: | flag audio type (can be combined using "or")
MUSFLAG_SONGS All songs MUSFLAG_EFFECTS All sound effects speed The number of frames before stopping |
| Return value: | None |
Use sound handle to stop sound
| Function name: | MusHandleStop | |
| Syntax: | s32 MusHandleStop(musHandle handle, s32 speed) | |
| Arguments: | handle | Sound handle |
| speed | The number of frames before stopping | |
| Return value: | The number of channels that are set to stop | |
| (*) | These two functions are the only functions in the MUS library that depend on number of frames. You must adjust them to either PAL or NTSC (MPAL). |
There are also two functions that can be used to find out the number of channels currently being used.
Return the number of active channels
| Function name: | MusAsk |
| Syntax: | s32 MusAsk(u64 flags) |
| Arguments: | flag The type of audio (can be combined using "or") MUSFLAG_SONGS All songs xMUSFLAG_EFFECTS All sound effects |
| Return value: | The number of channels currently being used |
Return active channel with the sound handle
| Function name: | MusHandleAsk | |
| Syntax: | s32 MusHandleAsk(musHandle handle) | |
| Arguments: | handle | Sound handle |
| Return value: | The number of channels currently being used | |
There is also a function useful for debugging that returns how many sound effects are in the sound effect bank. The numbers for these usable sound effects are from 0 to (the value returned by this function - 1).
Return the number of sound effects in the sound effect bank
| Function name: | MusFxBankNumberOfEffects | |
| Syntax: | s32 MusFxBankNumberOfEffects(void *ifxbank) | |
| Arguments: | ifxbank | Address of the initialized sound effect bank |
| Return value: | The number of sound effects | |