Audio Usage/Functions

Overview

The Corona audio system gives you access to advanced OpenAL features. It features 32 distinct channels on which you can play sound effects or streaming audio files. The system offers a unique volume setting for each channel plus a master volume level for all channels.

The audio system is a "best effort" system. Requested sounds will play as quickly as possible, but there is no guarantee that they'll start or end at exact times. If you are streaming a song and there's a buffer underrun due to CPU stress, the audio system will continue playing as soon as it can, but the song may finish playing later than anticipated.

Please read further to learn about audio API functions and methods, acceptable file formats, and performance tips.

Sound vs. Stream

The audio system offers two functions for loading: audio.loadSound() and audio.loadStream(). There is no mandated distinction between the file you provide to either function, but the proper method should be used according to these general guidelines:

• audio.loadSound() — loads an entire sound into memory. It should be used for shorter audio files that may be used repeatedly throughout the app.

• audio.loadStream() — reads in small chunks of an audio file over the course of its duration. It should be used for longer audio tracks like background music. Note that streamed files may have a slightly higher latency cost and CPU cost than files loaded with audio.loadSound().

All of the audio APIs can be applied to files loaded via either method. However, in some cases, the differences are not entirely transparent.

Audio Formats

The Corona audio system supports different formats depending on the environment/platform:

Channels and Volume

As stated in the overview, there are 32 audio channels available. Each sound effect or streaming audio track must play on a distinct channel. If you don't explicitly set the channel on which you want to play audio, Corona will attempt to locate a free channel on which to play the audio file.

In some cases, it's useful to reserve certain channels for different purposes. For example, you may want to set different volume levels for music, speech, and sound effects. In this case, you can reserve a few channels toward the lower end of the range and effectively prevent auto-assignment on those channels. This is done via the audio.reserveChannels() API, wherein you block off channels 1 to x via audio.reserveChannels( x ). Then, assuming you reserve a few channels for music and speech, the remaining channels can be used for auto-assigned sound effects.

Corona also provides various functions to check the status of a channel. These include audio.isChannelActive(), audio.isChannelPlaying(), and audio.isChannelPaused().

audio.setVolume( 0.5 )  --set the master volume to 50%

audio.setVolume( 0.5, { channel=1 } )  --set the volume level of channel 1 to 50%

Audio Handles

When you load an audio file using either audio.loadSound() or audio.loadStream(), Corona returns a handle for that audio file. This handle can then be used to reference and play the audio file, assuming the handle remains in memory.

The following example shows how to load a basic sound file into a handle soundEffect and play it immediately.

local soundEffect = audio.loadSound( "chime.wav" )
audio.play( soundEffect )

Note that audio handles are only used when you need to play, dispose, seek/rewind, or check the duration of an audio file. Once an audio file is playing, you cannot pause, stop, or control the volume of it by referencing its handle. Instead, you must reference the channel on which it's playing, since the same file (handle) may be playing on multiple channels.

Playing Audio

local soundTable = {

    chimeSound = audio.loadSound( "chime.wav" ),
    bellSound = audio.loadSound( "bell.wav" ),
    buzzSound = audio.loadSound( "buzz.aac" ),
    clickSound = audio.loadSound( "click.aac" )
}

audio.play( soundTable["chimeSound"] )

local backgroundMusic = audio.loadStream( "backgroundMusic.wav" )
audio.play( backgroundMusic )

Audio Events

The audio system offers a completion event for audio.play() which can be used to perform an action related to the sound. For example, if you have a ticking time bomb object, you may use the onComplete callback to trigger an animated bomb explosion and a separate explosion sound.

To listen for the completion event of a sound, just specify the listener function in the onComplete value of the options table:

local function bombExplode( event )
    --bomb has exploded!
end

local tickSound = audio.loadSound( "tick.wav" )
audio.play( tickSound, { onComplete=bombExplode } )

In turn, when the listener function is called, the following event parameters are available:

• event.name — string with the value "soundCompletion".
• event.channel — the channel number associated with the completed sound.
• event.handle — the audio handle associated with the completed sound.
• event.completed — boolean value which will be true if the audio file completed by itself or false if it was prematurely stopped.

Controlling Audio

In addition to the volume control methods described above, Corona provides the following audio control functions:

Disposing Audio

Disposing audio files is essential if you're finished using them. This frees the memory allocated to the audio file. To dispose of an audio file, call the audio.dispose() function and pass the handle of the audio file as its sole parameter.

audio.dispose( audioHandle )

If you've organized your audio handles into a table as illustrated in Playing Audio, a simple pairs loop can be used to dispose of each audio file:

audio.stop()

for s,v in pairs( soundTable ) do
    audio.dispose( soundTable[s] )
    soundTable[s] = nil
end

Performance Tips

application =
{
    content =
    {
        width = 320,
        height = 480,
        scale = "letterbox",
        audioPlayFrequency = 22050
    },
}