audio.h

This header contains all functions and definitions related to console sound


General definitions for audio

Definitions: Audio constants
Name Value Description
sound_channels 16 The number of sound channels in the console

Selected audio objects

Function: select_sound
Prototype: void select_sound( int sound_id )
Description: Sets the selected sound to the given sound ID. All sound functions will apply to that sound from that moment
Arguments:
int sound_id ID of the sound to select
Function: get_selected_sound
Prototype: int get_selected_sound()
Description: Gets the ID of the currently selected sound
Returns:
int ID of selected sound (from -1 to the last sound ID in the cartridge, if any)
Function: select_channel
Prototype: void select_channel( int channel_id )
Description: Sets the selected sound channel to the given channel ID. All channel functions will apply to that sound channel from that moment
Arguments:
int channel_id ID of the sound channel to select
Function: get_selected_channel
Prototype: int get_selected_channel()
Description: Gets the ID of the currently selected sound channel
Returns:
int ID of selected sound channel (from 0 to 15)

Configuration of sounds

Function: set_sound_loop
Prototype: void set_sound_loop( bool enabled )
Description: Controls whether the currently selected sound will be played with loop enabled by default
Arguments:
bool enabled True for loop enabled, false (default) for loop disabled
Function: set_sound_loop_start
Prototype: void set_sound_loop_start( int position )
Description: Sets the start position for the looped region in the currently selected sound. By default the looped region is the whole sound
Arguments:
int position Start position, given as number of samples from sound start
Function: set_sound_loop_end
Prototype: void set_sound_loop_end( int position )
Description: Sets the end position for the looped region in the currently selected sound. By default the looped region is the whole sound
Arguments:
int position End position, given as number of samples from sound start

States of a sound channel

Definitions: Possible states
Name Value Description
channel_stopped 40h State for a channel playing no sound
channel_paused 41h State for a channel in paused playback
channel_playing 42h State for a channel currently playing a sound

Configuration of sound channels

Function: set_channel_volume
Prototype: void set_channel_volume( float volume )
Description: Sets the playback volume for the currently selected sound channel. This factor is applied linearly
Arguments:
float volume New channel volume. Range is from 0 (silence) to 10 (10x amplification)
Function: set_channel_speed
Prototype: void set_channel_speed( float speed )
Description: Sets the playback speed for the currently selected sound channel. This will also change playback pitch accordingly. Normal speed is 1 (default)
Arguments:
float speed New channel speed. Range is from 0 (no playback) to 100 (100x acceleration)
Function: set_channel_loop
Prototype: void set_channel_loop( bool enabled )
Description: Enables or disabled loop for selected sound channel. Note that when a sound is played, that sound's loop setting will be applied automatically to the channel
Arguments:
bool enabled True for loop enabled, false (default) for loop disabled
Function: assign_channel_sound
Prototype: void assign_channel_sound( int channel_id, int sound_id )
Description: Assigns the target sound to the given sound channel. Next playback commands on this channel will use the assigned sound
Arguments:
int channel_id ID of the sound channel
int sound_id ID of the sound to be assigned
Function: get_channel_state
Prototype: int get_channel_state( int channel_id )
Description: Returns the current state of the given sound channel. Channel states are {stopped/paused/playing}
Returns:
int State of the target sound channel. Their numerical values are defined in this library
Arguments:
int channel_id ID of the target sound channel

Commands for a single sound channel

Function: play_channel
Prototype: void play_channel( int channel_id )
Description: If stopped, the target channel will begin playing its assigned sound. For a paused channel, it will make it resume playback. If the channel is already playing, it will retrigger that same sound from the beginning.
Arguments:
int channel_id ID of the target sound channel
Function: pause_channel
Prototype: void pause_channel( int channel_id )
Description: Pauses playback on the target channel. Has no effect on stopped or paused channels
Arguments:
int channel_id ID of the target sound channel
Function: stop_channel
Prototype: void stop_channel( int channel_id )
Description: Stops playback on the target channel. Has no effect on stopped channels
Arguments:
int channel_id ID of the target sound channel

Commands for all sound channels

Function: pause_all_channels
Prototype: void pause_all_channels()
Description: Pauses playback on all playing channels. Has no effect on the rest
Function: stop_all_channels
Prototype: void stop_all_channels()
Description: Stops playback on all playing or paused channels. Has no effect on the rest
Function: resume_all_channels
Prototype: void resume_all_channels()
Description: Resumes playback on all paused channels. Has no effect on the rest

Practical sound play functions

Function: play_sound_in_channel
Prototype: void play_sound_in_channel( int sound_id, int channel_id )
Description: Plays the target sound in the specified sound channel
Arguments:
int sound_id ID of the sound to play
int channel_id ID of the channel that will play the sound
Function: play_sound
Prototype: int play_sound( int sound_id )
Description: Plays the given sound in the first available sound channel (found automatically).
Returns:
int The ID of the channel that will play the sound
Arguments:
int sound_id ID of the sound to play