audio.play()

类型 函数
库 audio.*
返回值 数字
修订版本 版本 2024.3703
关键词 audio, play, sound, music（音频，播放，声音，音乐）
另请参阅 audio.pause()
audio.loadSound()
audio.loadStream()

概述

在通道上播放由音频句柄指定的音频。如果未明确指定通道，将自动为您选择一个可用通道。

此函数返回音频播放的通道号，如果音频无法播放，则返回 `0`。

注意事项

目前我们支持 32 个通道。您不能在当前处于活动状态（暂停或播放）的通道上播放新音频。

语法

audio.play( audioHandle [, options ] )
audioHandle (必填)

对象. 这是您要播放的音频数据（由 audio.loadSound() 和 audio.loadStream() 返回）。

options (可选)

表. 播放的附加选项 — 有关详细信息，请参阅下一节。

参数参考

`options` 表允许您指定播放的附加选项。

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

数字. 您要在其上播放的通道号。有效通道为 `1` 到最大通道数（目前为 32）。指定 `0` 或省略此参数将自动为您选择一个通道。

loops (可选)

数字. 您希望音频循环播放的次数。`0` 表示音频将循环 0 次（声音将播放一次且不循环）。`1` 表示音频将播放一次并循环一次，这意味着您将听到该声音共 2 次。传递 `-1` 将告诉系统无限循环播放样本。

duration (可选)

数字. 以毫秒为单位，这将导致系统播放音频指定的时间量，然后自动停止播放，无论音频是否已完成。

fadein (可选)

数字. 以毫秒为单位，这将导致系统以最小通道音量开始播放声音，并在指定的毫秒数内线性上升到正常通道音量。

onComplete (可选)

监听器. 您希望在播放结束时调用的回调函数。`onComplete` 回调函数将传回一个具有以下属性的事件表

  • `event.name`（字符串）— 值为 `"audio"`。
  • `event.channel`（数字）— 刚刚完成播放的通道号。
  • `event.handle`（对象）— 这是您传递给 `audio.play()` 的音频句柄。
  • `event.completed`（布尔值）— 如果音频因正常播放完毕（播放到声音的结尾）而停止，则此值为 `true`。如果音频由于其他原因而停止，则此值为 `false`。

示例

-- 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 )