BlitzMax音频模块包含加载和播放声音的命令。

可以使用LoadSound（加载声音文件）和PlaySound（通过系统音频系统播放声音，如果可用）的组合在BlitzMax中播放声音文件。

BlitzMax 原生支持 .wav（未压缩）和 .ogg（压缩）两种格式的声音文件。

可以使用各种音频通道操作符控制声音的播放，包括SetChannelVolume、SetChannelPan、SetChannelDepth和SetChannelRate。

通道句柄可以从PlaySound和CueSound的返回值获取，也可以通过AllocChannel预留通道获取。

类型

TSound

音频声音类型

方法

播放
提示

函数

加载

TSound：方法

播放

方法 Play:TChannel( alloced_channel:TChannel=Null )

描述：播放声音

返回值：一个音频通道对象

信息：开始通过音频通道播放声音。如果未指定通道，Play 会自动为您分配一个通道。

提示

方法 Cue:TChannel( alloced_channel:TChannel=Null )

描述：提示声音进行播放

返回值：一个音频通道对象

信息：准备音频通道以播放声音。要实际开始播放声音，必须使用通道的 SetPaused 方法。如果未指定通道，Cue 会自动为您分配一个通道。

Cue 允许您在声音实际开始播放之前设置各种音频通道状态，例如音量、声场、深度和速率。

TSound：函数

加载

函数 Load:TSound( url:Object,loop_flag )

描述：加载声音

返回值：一个声音对象

信息：url 可以是字符串、流或音频样本对象。可以使用 Play 或 Cue 播放返回的声音对象。

TChannel

音频通道类型

方法

停止
设置暂停
设置音量
设置声场
设置深度
设置速率
播放中

TChannel：方法

停止

方法 Stop()

描述：停止音频通道播放

信息：关闭音频通道。此音频通道上的进一步命令将无效。

设置暂停

方法 SetPaused( paused )

描述：暂停或取消暂停音频通道播放

信息：如果paused为True，则暂停音频通道。否则，取消暂停音频通道。

设置音量

方法 SetVolume( volume# )

描述：设置音频通道音量

信息：volume应在0（静音）到1（最大音量）之间。

设置声场

方法 SetPan( pan# )

描述：设置音频通道立体声声场

信息：pan应在-1（最左）到1（最右）之间。

设置深度

方法 SetDepth( depth# )

描述：设置音频通道深度

信息：depth应在-1（后）到1（前）之间。

设置速率

方法 SetRate( rate# )

描述：设置音频通道播放速率

信息：rate是用于修改音频通道频率的乘数。例如，速率为0.5将导致音频通道以半速播放（即：降低一个八度），而速率为2将导致音频通道以双倍速度播放（即：提高一个八度）。

播放中

方法 Playing()

描述：确定音频通道是否正在播放

返回值：如果channel当前正在播放，则返回True

信息：如果音频通道已暂停或已使用Stop停止，则Playing将返回False。

函数

LoadSound

函数 LoadSound:TSound( url:Object,flags=0 )

描述：加载声音

返回值：一个声音对象

信息：url可以是字符串、流或TAudioSample对象。可以使用PlaySound或CueSound播放返回的声音。

flags参数可以是以下任何组合

标志值	效果
SOUND_LOOP	播放时声音应循环。
SOUND_HARDWARE	如果可能，声音应放置在板载声卡内存中。

要组合标志，请使用二进制“或”运算符：“|”。

示例:

Rem
Load and Play a small example wav file.
End Rem

sound=LoadSound("shoot.wav")
PlaySound sound

Input "Press any key to continue"

PlaySound

函数 PlaySound:TChannel( sound:TSound,channel:TChannel=Null )

描述：播放声音

返回值：一个音频通道对象

信息：PlaySound开始通过音频通道播放声音。如果未指定channel，PlaySound会自动为您分配一个通道。

示例:

Rem
Load and Play a small example wav file with looping.
End Rem

sound=LoadSound("shoot.wav",true)
PlaySound sound

Input "Press any key to continue"

CueSound

函数 CueSound:TChannel( sound:TSound,channel:TChannel=Null )

描述：提示声音

返回值：一个音频通道对象

信息：准备通过音频通道播放声音。要实际开始播放声音，必须使用ResumeChannel。如果未指定channel，CueSound会自动为您分配一个通道。

CueSound允许您在声音实际开始播放之前设置各种音频通道状态，例如音量、声场、深度和速率。

示例:

Rem
CueSound example
End Rem

sound=LoadSound("shoot.wav")
channel=CueSound(sound)

Input "Press return key to play cued sound"

ResumeChannel channel

Input "Press return key to quit"

AllocChannel

函数 AllocChannel:TChannel()

描述：分配音频通道

返回值：一个音频通道对象

信息：分配音频通道以用于PlaySound和CueSound。完成音频通道后，应使用StopChannel。

示例:

'AllocChannel.bmx

timer=CreateTimer(20)

sound=LoadSound ("shoot.wav")
channel=AllocChannel()

For i=1 To 20
	WaitTimer timer
	PlaySound sound,channel
Next

StopChannel

函数 StopChannel( channel:TChannel )

描述：停止一个音频通道

信息：关闭一个音频通道。之后使用此通道的命令将无效。

示例:

Rem
StopChannel example
End Rem

sound=LoadSound("shoot.wav",true)
channel=PlaySound(sound)

print "channel="+channel

Input "Press return key to stop sound"

StopChannel channel

Input "Press return key to quit"

ChannelPlaying

函数 ChannelPlaying( channel:TChannel )

描述：确定一个音频通道是否正在播放

返回值：如果channel当前正在播放，则返回True

信息：如果通道使用PauseChannel暂停或使用StopChannel停止，则ChannelPlaying将返回False。

示例:

' channelplaying.bmx

sound = LoadSound ("shoot.wav")

Input "Hit return to begin channelplaying test, use ctrl-C to exit"

channel=PlaySound (sound)
While True
	Print "ChannelPlaying(channel)="+ChannelPlaying(channel)
Wend

SetChannelVolume

函数 SetChannelVolume( channel:TChannel,volume# )

描述：设置音频通道的播放音量

信息：volume应该在0（静音）到1（最大音量）之间。

示例:

' setchannelvolume.bmx

timer=CreateTimer(20)

sound = LoadSound ("shoot.wav")

For volume#=.1 To 2 Step .05
	WaitTimer timer
	channel=CueSound(sound)
	SetChannelVolume channel,volume
	ResumeChannel channel
Next

SetChannelPan

函数 SetChannelPan( channel:TChannel,pan# )

描述：设置音频通道的立体声平衡

信息：pan应该在-1（左）到1（右）之间。

示例:

' setchannelpan.bmx

Graphics 640, 480

channel = AllocChannel ()
sound = LoadSound ("shoot.wav") ' Use a short sample...

Repeat
	If MouseHit(1) PlaySound sound,channel
	
	pan# = MouseX () / (GraphicsWidth () / 2.0) - 1
	vol# = 1 - MouseY () / 480.0
	SetChannelPan channel, pan
	SetChannelVolume channel, vol*2

	Cls
	DrawText "Click to play...", 240, 200
	DrawText "Pan   : " + pan, 240, 220
	DrawText "Volume: " + vol, 240, 240

	Flip
Until KeyHit (KEY_ESCAPE)

End

SetChannelDepth

函数 SetChannelDepth( channel:TChannel,depth# )

描述：设置音频通道的环绕声深度

信息：depth应该在-1（后）到1（前）之间。

示例:

' setchanneldepth.bmx

Graphics 640, 480

channel = AllocChannel ()
sound = LoadSound ("shoot.wav") ' Use a short sample...

Repeat
	If MouseHit(1) PlaySound sound,channel
	
	pan# = MouseX () / (640 / 2.0) - 1
	depth# = MouseY () / (480 /2.0) -1
	
	SetChannelPan channel,pan
	SetChannelDepth channel,depth

	Cls
	DrawText "Click to play...", 240, 200
	DrawText "Pan   : " + pan, 240, 220
	DrawText "Depth : " + depth, 240, 240

	Flip
Until KeyHit (KEY_ESCAPE)

End

SetChannelRate

函数 SetChannelRate( channel:TChannel,rate# )

描述：设置音频通道的播放速度

信息：rate是用于修改音频通道频率的乘数。例如，速率为0.5将导致音频通道以半速播放（即：降低一个八度），而速率为2将导致音频通道以双倍速度播放（即：提高一个八度）。

示例:

' setchannelrate.bmx

timer=CreateTimer(20)

sound = LoadSound ("shoot.wav",True)
channel=CueSound(sound)
ResumeChannel channel

For rate#=1.0 To 4 Step 0.01
	WaitTimer timer
	SetChannelRate channel,rate
Next

PauseChannel

函数 PauseChannel( channel:TChannel )

描述：暂停音频通道播放

信息：暂停音频通道播放。

ResumeChannel

函数 ResumeChannel( channel:TChannel )

描述：恢复音频通道播放

信息：在使用CueSound或PauseChannel暂停后恢复音频通道播放。

AudioDrivers

函数 AudioDrivers$[]()

描述：获取音频驱动程序

信息：返回一个字符串数组，其中每个字符串描述一个音频驱动程序。

AudioDriverExists

函数 AudioDriverExists( name$ )

描述：确定音频驱动程序是否存在

信息：如果由driver指定的音频驱动程序存在，则返回True。

SetAudioDriver

函数 SetAudioDriver( name$ )

描述：设置当前音频驱动程序

信息：如果音频驱动程序成功设置，则返回true。