SoundTutorial: Contents
  Introduction
  How to play sounds
    Sound banks
    Using sound banks in a script
      Modules
      Sound effects
      Unload the sound bank

Sound Tutorial

Tutorial about playing sounds with MicroLua.

Introduction

This page is directly taken from the sound tutorial of the 3.0 prerelease.

How to play sounds

Microlua 3 allows you to play module sounds and sound effects (SFX).
  • Module supported files: MOD, XM, S3M, IT
  • SFX supported files: WAV (wave files)

Sound banks

You can't play these files directly with MicroLua, you must first create a sound bank.

To do this, you can use the Soundbank Maker tool included in the Micro Lua 3 package. Put all music files you want to play in the in directory and lauch convert.bat. The program will create two files: soundbank.bin and soundbank.h. The first one is the sound bank: a file which contains all mods and sfx files. The second one is not used by Micro Lua but it can help you to identify your modules and SFX with their ID.

Example: soundbank.h
#define SFX_AMBULANCE                 0 // ID of he SFX ambulance
#define SFX_BOOM                      1 // ID of the SFX Boom
#define MOD_KEYG_SUBTONAL             0 // ID of the the module Keyg Subtonal
#define MOD_PURPLE_MOTION_INSPIRATION 1 // ID of the module Purple Motion
#define MOD_REZ_MONDAY                2 // ID of the module Rez monday
#define MSL_NSONGS                    3
#define MSL_NSAMPS                    67
#define MSL_BANKSIZE                  70

Using sound banks in a script

First, we must load the databank. The databank is never loaded fully in memory so the sound bank file can be very big.

To load a soundbank.bin file (or any other file name), you use
Sound.loadBank("soundbank.bin")

Modules

Now, we want to play a module, for example the Purple Motion song (ID=1, see before).
Sound.loadMod(1) -- Load the module on memory
Sound.startMod(1, PLAY_ONCE) -- Start to play the module once. We can also use PLAY_LOOP
You can stop, pause, resume, modify the volume level... Have look at the documentation for more details.

Now, at the end of our script we must unload the module from memory with:
Sound.unloadMod(1)

Sound effects

Playing a Sound effect (SFX) is a little bit different. First we need to load the effect in memory. We want to play the Boom effect (ID=1):
Sound.loadSFX(1)  -- again, see before for the ID
Now we can play it:
handle = Sound.startSFX(1) -- Start playing the effect and get a handle to this sound
The handle allow you to do some effects on the sound like changing its volume level. Look at the documentation and examples for more details.

Then, we must unload this sound from the memory at the end of the script with:
Sound.unloadSFX(1)

Unload the sound bank

Eventually, don't forget to unload the soundbank from the momory:
Sound.unloadBank()
You can now use another sound bank!