Time to play

Audio can be loaded in two different ways, as follows:

• loadSound(): This preloads an entire sound into the memory
• loadStream(): This prepares the sound to be played by reading small chunks at a time to save memory

audio.loadSound()

The audio.loadSound() function loads an entire file completely into the memory and returns a reference to the audio data. Files that are loaded completely into the memory can be reused, played, and shared simultaneously on multiple channels. So, you only need to load one instance of the file. Sounds that you would use as sound effects in your game will fit in this category.

The syntax is audio.loadSound(audiofileName [, baseDir ]).

The parameters are as follows:

• audiofileName: This specifies the name of the audio file you want to load. The supported file formats are determined by the platform the file is being run on.
• baseDir: By default, sound files are expected to be in the application resources directory. If the sound file is in the application documents directory, use system.DocumentsDirectory.

For example:

• tapSound = audio.loadSound("tap.wav")
• smokeSound = audio.loadSound("smoke.mp3")

audio.loadStream()

The audio.loadStream() function loads a file to be read as a stream. Streamed files are read in small chunks at a time to minimize memory use. Files that are large in size and have a long duration would be ideal for this. These files cannot be shared simultaneously across multiple channels. If need be, you must load multiple instances of the file.

The syntax is audio.loadStream( audioFileName [, baseDir ] )

The parameters are as follows:

• audiofileName: This specifies the name of the audio file you want to load. The supported file formats are determined by the platform the file is being run on.
• baseDir: By default, sound files are expected to be in the application resources directory. If the sound file is in the application documents directory, use system.DocumentsDirectory.

For example:

• music1 = audio.loadStream("song1.mp3")
• music2 = audio.loadStream("song2.wav")

audio.play()

The audio.play() function plays the audio specified by the audio handle on a channel. If a channel is not specified, an available channel will be automatically chosen for you. The function returns the channel number the audio is playing on.

The syntax is audio.play( audioHandle [, options ] )

The parameters are as follows:

• audioHandle: This is the audio data you want to play
• options: This is an additional option for playback, formatted as a table

Parameters for options:

• channel: This option lets you select the channel number that you want the audio to play on. 1 to the maximum number of channels, which is 32, are valid channels. If you specify 0 or omit, this parameter will have a channel automatically picked for you.
• loops: This option lets you select the number of times you want the audio to loop. 0 means the audio will loop zero times, which means that the sound will play once and not loop. Passing -1 will tell the system to infinitely loop the sample.
• duration: This option is measured in milliseconds, this option will cause the system to play the audio for the specified amount of time.
• fadein: This option is measured in milliseconds, this will start playing a sound at the minimum channel volume and transition to the normal channel volume over the specified number of milliseconds.
• onComplete: This is a callback function that you will call when playback ends. The onComplete callback function passes back an event parameter.

For example:

backgroundMusic = audio.loadStream("backgroundMusic.mp3")
backgroundMusicChannel = audio.play( backgroundMusic, { channel=1, loops=-1, fadein=5000 }  )  
-- play the background music on channel 1, loop infinitely, and fadein over 5 seconds

Looping

Highly compressed formats, such as MP3, AAC, and Ogg Vorbis, can remove samples at the end of an audio sample and possibly break a clip that is looped correctly. If you experience gaps in looping during playback, try using WAV (compatible with iOS and Android). Make sure your lead-in and ending points are clean.

Simultaneous playback

Sounds loaded via loadSound() can be played back simultaneously on multiple channels. For example, you can load a sound effect as follows:

bellSound = audio.loadSound("bell.wav")

If you want to make a variety of bell sounds to occur for multiple objects, you can. The audio engine is highly optimized to handle this case. Call audio.play() using that same handle as many times as you need it (up to the maximum channels):

audio.play(bellSound)
audio.play(bellSound)
audio.play(bellSound)