audio.play()

Type Function
Library audio.*
Return value Number
Revision Release 2024.3703
Keywords audio, play, sound, music
See also audio.pause()
audio.loadSound()
audio.loadStream()

Overview

Plays the audio specified by the audio handle on a channel. If a channel is not explicitly specified, an available channel will be automatically chosen for you.

This function returns the channel number which the audio plays on, or 0 if the audio could not be played.

Gotchas

Currently we support 32 channels. You may not play new audio on a channel that is currently active (paused or playing).

Syntax

audio.play( audioHandle [, options ] )
audioHandle (required)

Object. This is the audio data you want to play (as returned from audio.loadSound() and audio.loadStream()).

options (optional)

Table. Additional options for playback — see the next section for details.

Parameter Reference

The options table allows you to specify additional options for playback.

local options =
{
    channel = 1,
    loops = -1,
    duration = 30000,
    fadein = 5000,
    onComplete = callbackListener
}
channel (optional)

Number. The channel number you want to play on. Valid channels are 1 to the maximum number of channels (currently 32). Specify 0 or omit this parameter to have a channel automatically picked for you.

loops (optional)

Number. The number of times you want the audio to loop. 0 means that the audio will loop 0 times (the sound will play once and not loop). 1 means that the audio will play once and loop once which means you will hear the sound a total of 2 times. Passing -1 will tell the system to infinitely loop the sample.

duration (optional)

Number. In milliseconds, this will cause the system to play the audio for the specified amount of time and then auto-stop the playback regardless of whether the audio has finished or not.

fadein (optional)

Number. In milliseconds, this will cause the system to start playing a sound at the minimum channel volume and linearly ramp up to the normal channel volume over the specified number of milliseconds.

onComplete (optional)

Listener. A callback function you want to be called when playback ends. The onComplete callback function passes back an event table with the following properties:

  • event.name (string) — Value of "audio".
  • event.channel (number) — The channel number which just finished playing.
  • event.handle (object) — This is the audio handle you passed into audio.play().
  • event.completed (boolean) — This value will be true if the audio stopped because it finished playing normally (played to the end of the sound). It will be false if the audio was stopped because of other reasons.

Example

-- Completion listener function
local function narrationFinished( event )
    print( "Narration Finished on channel", event.channel )
    if ( event.completed ) then
        print( "Narration completed playback naturally" )
    else
        print( "Narration was stopped before completion" )
    end
end

-- Load two audio streams and one sound
local backgroundMusic = audio.loadStream( "backgroundMusic.m4a" )
local narrationSpeech = audio.loadStream( "narrationSpeech.wav" )
local laserSound = audio.loadSound( "laserBlast.wav" )

-- Play the background music on channel 1, loop infinitely, and fade in over 5 seconds 
local backgroundMusicChannel = audio.play( backgroundMusic, { channel=1, loops=-1, fadein=5000 } )

-- Play the speech on any available channel, for 30 seconds at most, and invoke listener function when audio finishes
local narrationChannel = audio.play( narrationSpeech, { duration=30000, onComplete=narrationFinished } )

-- Play the laser on any available channel
local laserChannel = audio.play( laserSound )