mplayer.lib reference

Version 1.2.0

Overview

mplayer provides easy access to Arkos 2 Minimal Player (AKM) ROM version from SDCC.

The library adds support for priority based sound effects, so it is possible to have two uninterrupted channels for music and leave the third one for effects.

When the priority effects are used, an effect is played if no effect is already being played or if the effect being played has less priority. The effect number is used as priority, being effect number 1 the one with lowest priority.

Arkos 2 Player is licensed MIT, please check src/mplayer/akm/ directory for further info.

Visit Arkos Tracker 2 website to download the tracker.

Exporting songs and effects

The player is quite complex and has a lot of options that can be disabled if not used, reducing space and CPU use.

mplayer is only a fixed interface, and the player is compiled customised to the song and effects used by the game.

Currently AKM can only be compiled with rasm (included in ./tools), and then processed with Disark to generate ASM compatible with SDCC. Once that code is compiled, it will be relocated by the linker.

Notes on Disark:

It is not open source yet, so it needs to be put in the PATH. It is distributed as part of Arkos 2 Traker tools.
Because it uses uppercase labels, the variable exported and accessible from C will be all uppercase. For example: for song we will use SONG.

This is automated, and the only counter-intuitive step is making an ASM file for rasm such as:

;
; to build the custom AKM player with song + effects
;

include "song_playerconfig.asm"
include "effects_playerconfig.asm"

include "../../src/mplayer/akm/akm_ubox.asm"

songDisarkGenerateExternalLabel:
include "song.asm"

effectsDisarkGenerateExternalLabel:
include "effects.asm"

See the example game and the commands run automatically for further details.

Exporting the song

In Arkos Tracker 2, export the song as “AKM”, using “Export as source file” and “Generate configuration file for players”.

Save the file as song.asm.

It should create song_playerconfig.asm in the same directory.

Exporting the effects

In Arkos Tracker 2, export the effects as “AKX”, using “Export as source file” and “Generate configuration file for players”.

Save the file as effects.asm.

It should create effects_playerconfig.asm in the same directory.

Initialization

mplayer_init

void mplayer_init(const uint8_t *song, uint8_t sub_song);

Sets the player to play sub_song from song.

sub_song starts from 0.

This function can be called as many times as needed, for example, to change the playback to a different sub-song.

It is required to call it at least once before using mplayer_play.

Example:

// tell the compiler we will use this
// global symbol
extern uint8_t SONG[];

mplayer_init(SONG, 0);

See exporting songs and effects for details on how to add songs to your project.

mplayer_init_effects

void mplayer_init_effects(const uint8_t *effects);

Inits the effects table.

It is required to call it least once before using mplayer_play or any of the play effect functions.

Example:

// tell the compiler we will use this
// global symbol
extern uint8_t EFFECTS[];

mplayer_init_effects(EFFECTS);

See exporting songs and effects for details on how to add effects to your project.

Playback

mplayer_play

void mplayer_play(void);

Plays a frame using the PSG.

This must be called from the interrupt handler. See set_user_isr.

mplayer_init must be called before using it.

If the player is stopped, mplayer_stop must be called to silence the PSG.

mplayer_stop

void mplayer_stop(void);

Silences the PSG, stopping any sound.

This doesn’t stop the player if mplayer_play is called.

Sound effects

mplayer_is_sound_effect_on

uint8_t mplayer_is_sound_effect_on(uint8_t chan);

Returns 0 if there’s no sound effect being played on chan channel, or a value different than 0 otherwise.

mplayer_play_effect

void mplayer_play_effect(uint8_t effect_no, uint8_t chan, uint8_t inv_vol);

Plays effect_no on chan channel at inv_vol volume.

effect_no starts on 1 and refers to the index in the effects table set by mplayer_init_effects.

chan can be 0, 1 or 2. It is recommended to use one channel for effects and the other two for the music.

inv_vol is the inverted volume, with 0 for max volume and 16 for no sound.

If an effects is already playing on the channel, it will be interrupted and replaced by this effect.

The effects table must be set with mplayer_init_effects before using this function.

See mplayer_play_effect_p for playing effects with priority.

Example:

// plays effect 1 on channel 2 at highest volume
mplayer_play_effect(1, 2, 0);

mplayer_play_effect_p

void mplayer_play_effect_p(uint8_t effect_no, uint8_t chan, uint8_t inv_vol);

Plays effect_no on chan channel at inv_vol volume using priority.

effect_no starts on 1 and refers to the index in the effects table set by mplayer_init_effects.

effect_no is used as priority, being effect number 1 the one with lowest priority.

chan can be 0, 1 or 2. It is recommended to use one channel for effects and the other two for the music.

inv_vol is the inverted volume, with 0 for max volume and 16 for no sound.

The effect is played if no effect is already being played or if the effect being played has less priority. In that case, the effect currently being played will be interrupted and replaced by this effect.

The effects table must be set with mplayer_init_effects before using this function.

See mplayer_play_effect for playing effects without priority.

Example:

// plays effect 2 on channel 2 at highest volume
mplayer_play_effect_p(2, 2, 0);
// won't interrupt effect 2 because it is higher priority than 1
mplayer_play_effect_p(1, 2, 0);

mplayer_stop_effect_channel

void mplayer_stop_effect_channel(uint8_t chan);

Stops the effect being played on chan channel.