The API of the libmsx audio replayer. More...

Collaboration diagram for The API of the libmsx audio replayer.:

Functions
void	audio_init (void)
	`MSX` Initialize the libmsx audio replayer.

void	audio_start (void)
	`MSX` Start / Resume music.

void	audio_pause (void)
	`MSX` Pause music.

bool	audio_is_paused (void)
	`MSX` Return whether paused or not.

void	audio_stop (void)
	`MSX` Stop music.

void	audio_play (void)
	`MSX` Main routine of the libmsx audio replayer.

uint8_t	audio_get_bgm_frequency (void)
	`MSX` Return replayer frequency of the background music.

void	audio_set_bgm_frequency (uint8_t freq)
	`MSX` Force replayer frequency of the background music.

bool	audio_is_playing (void)
	`MSX` Return whether BGM and/or SFX is playing or not.

bool	audio_is_playing_bgm (void)
	`MSX` Return whether BGM is playing or not.

bool	audio_is_playing_sfx (void)
	`MSX` Return whether SFX is playing or not.

void	audio_set_repeat (bool repeat)
	`MSX` Turn on/off the auto-repeat of the BGM.

Detailed Description

The API of the libmsx audio replayer.

Features of The libmsx audio replayer :

Supported sound chip :
- PSG (AY-3-8910) x 1,
- Konami SCC/SCC+ x 1,
- MSX-MUSIC (OPLL/YM2413) x 1.
Pluggable audio decoder design :
- The replayer only provides playback functionality. Loading and/or decoding music data is performed by supported audio decoders.
- Depending on the supported audio decoders, it can handle various types of music data.
- If the decoder is compatible, it will support playback of sound effects as well as background music.
Functionality :
- NTSC (60Hz), PAL/SECAM (50Hz), auto detect and auto adjust.
- Available to specify default playing frequency that the sound data author expecting, if supported by the decoder.
- Run-time replay frequency control.
- Stop, Start, Pause, Resume.
- Auto-repeat function for background music, if supported by the decoder.
- Playing sound effects (SFX) during playing background music (BGM), if supported by the decoder.

Function Documentation

◆ audio_init()

void audio_init ( void )

MSX Initialize the libmsx audio replayer.

This function must be called at least once. In particular, it must be called before the first call to audio_play().

◆ audio_start()

void audio_start ( void )

MSX Start / Resume music.

◆ audio_pause()

void audio_pause ( void )

MSX Pause music.

◆ audio_is_paused()

bool audio_is_paused ( void )

MSX Return whether paused or not.

Returns: true if paused.

◆ audio_stop()

void audio_stop ( void )

MSX Stop music.

◆ audio_play()

void audio_play ( void )

MSX Main routine of the libmsx audio replayer.

To play back background music and sound effects, this function must be called at each VSYNC timing.

The easiest way is to set this function as the VSYNC interrupt handler by calling set_vsync_handler().

// At first, initialize the replayer.
audio_init();
 
// Then, register the replayer as the VSYNC interrupt handler.
set_vsync_handler(audio_play);
 
// And then, calls other APIs to start, stop, etc.
// \note The replayer is already started in default.
// audio_start();
 
// Look up / load a music data and set it to the decoder by using decoder
// specific APIs.
// (Here, assume that any type or function prefixed with `l2a_` is such a
// decoder-specific API.)
 
l2a_File sf;
if (!l2a_open_resource(&sf, "songs.l2a") {
  // Failed to open l2a file.
}
 
l2a_set_bgm(0, &sf);

◆ audio_get_bgm_frequency()

uint8_t audio_get_bgm_frequency ( void )

MSX Return replayer frequency of the background music.

Returns: frequency in Hz.

See also: audio_set_bgm_frequency()

◆ audio_set_bgm_frequency()

void audio_set_bgm_frequency ( uint8_t freq )

MSX Force replayer frequency of the background music.

Parameters

freq	frequency in Hz.

See also: audio_get_bgm_frequency()

Note: When a background music is set to the audio decoder, the replayer frequency is set (reset) to the default frequency of the music.

◆ audio_is_playing()

bool audio_is_playing ( void )

MSX Return whether BGM and/or SFX is playing or not.

Returns: true if BGM and/or SFX is playing.

◆ audio_is_playing_bgm()

bool audio_is_playing_bgm ( void )

MSX Return whether BGM is playing or not.

Returns: true if BGM is playing.

◆ audio_is_playing_sfx()

bool audio_is_playing_sfx ( void )

MSX Return whether SFX is playing or not.

Returns: true if SFX is playing.

◆ audio_set_repeat()

void audio_set_repeat ( bool repeat )

MSX Turn on/off the auto-repeat of the BGM.