Skip to content

audio.md

Latest commit

 

History

History
116 lines (79 loc) · 4.4 KB

audio.md

File metadata and controls

116 lines (79 loc) · 4.4 KB
Raw

Working with Audio in ACE

ACE provides audio capabilities through integrated PTPlayer by Frank Wille rewritten to C for better integration with ACE features. The basic capabilities are:

  • MOD music playback (31-sample format)
  • Handling prioritized sound effects playback
  • Offers channel management (reserving channels for music vs. effects)
  • 64-step volume control
  • Custom callback for song end, e.g. for playlists or adaptative music

You can also combine it with 3rd party audio mixers for squeezing out more out of the audio playback.

Note

Using ptplayerSetChannelsForPlayer() will limit ptplayer channel management to only few channels, leaving others intact for e.g. audio mixer to use.

Amiga-Specific Considerations

  • PTPlayer must store music samples as well as sound effects in Amiga's CHIP memory.
  • PTPlayer sound effects should have an empty first word to prevent audio glitches after playback - audio_conv can ensure that for you
  • Amiga has 8-bit audio channels, totaling to 4 channels, two bound to left channel, two bound to the right one.
  • It's quite common to games to ignore the stereo separation and treat them all as mono, leaving to the user to ensure such playback.

Initialization and Configuration

In your main or gamestate create function, do the following:

// Initialize (1 = PAL mode, 0 = NTSC)
ptplayerCreate(1);

// Optional: Configure which channels are reserved for music
ptplayerSetMusicChannelMask(0b0011);  // Reserves channels 0 and 1 for music

// Optional: Set master volume
ptplayerSetMasterVolume(48);  // Range is 0-64

// Optional: Configure song repeat behavior
ptplayerConfigureSongRepeat(1, onSongEnd);

To play the music in your game, in your main or gamestate create function:

// Load a MOD file
tPtplayerMod *pMod = ptplayerModCreateFromPath("music.mod");

// Start playback (2nd parameter is NULL to use samples from inside the MOD file, set start position to 0)
ptplayerLoadMod(pMod, NULL, 0);

// Enable music playback
ptplayerEnableMusic(1);

While in the game loop, you might want to:

  • change the music by calling ptplayerLoadMod() with different pMod,
  • change the volume with ptplayerSetMasterVolume()
  • enable/disable music temporarily with ptplayerEnableMusic()

At the end of the gamestage or the game itself, do the following:

ptplayerStop();
ptplayerModDestroy(pMod);

// When done with all audio
ptplayerDestroy();

Playback performance will vary depending on:

  • Number of channels used in the song
  • Amount/kinds of ProTracker commands stored in the song.

Playing Sound Effects

To load a sound effect, be sure to have a .sfx file generated by audio_conv tool.

Manage the sound effect by calling:

tPtplayerSfx *pSfx = ptplayerSfxCreateFromPath("explosion.sfx", 0);

// When done with the sound effect, after your game loop ends:
ptplayerSfxDestroy(pSfx);

To play the sound effect:

ptplayerSfxPlay(pSfx, PTPLAYER_SFX_CHANNEL_ANY, PTPLAYER_VOLUME_MAX, 10);

Note

The SFX volume takes into account the volume set by ptplayerSetMasterVolume(). Setting the sfx volume to half of the range (32) with master volume set to 48 will scale it accordingly to 24.

You can also set the specific channel, as well as set the sound effect priority. When using PTPLAYER_SFX_CHANNEL_ANY, PTPlayer will use any free channel, if possible.

Higher priority sound effects will replace lower priority ones if needed.

Note

By default, PTPlayer prioritizes sound effects over music - if you play the sound effect on a channel which is used by the .mod file, some music notes won't play. Because of that, it is strongly recommended to use PTPlayer to only play music on some channels and use a software audio mixer to play back the samples in remaining channel(s)

You can also stop the sound effects playing on given channel by calling ptplayerSfxStopOnChannel().

Advanced Features

  • PTPlayer supports ProTracker's E8 command for synchronizing game events with music. Use ptplayerGetE8() to retrieve the last E8 value.
  • You can use mod_tool to separate MOD files from their sample data using sample packs to save memory when using multiple songs with shared samples. Use ptplayerSampleDataCreateFromPath() to load the sample pack and pass it in 2nd parameter of ptplayerLoadMod().
  • You can adjust individual music sample volumes with ptplayerSetSampleVolume() even when music is playing.