Audio

The BlitzMax audio module contains commands to load and play sounds.

A sound file can be played in BlitzMax with a combination of LoadSound that loads a sound file and PlaySound which plays the sound through the systems audio system if available.

BlitzMax contains native support for sound files in both .wav (uncompressed) and .ogg (compressed) file formats.

Playback of sounds can be controlled with various audio channel operators including SetChannelVolume, SetChannelPan, SetChannelDepth and SetChannelRate. A channel handle is obtained from either the return value of PlaySound and CueSound or from reserving a channel with the AllocChannel command.

Function reference

LoadSound:TSound( url:Object,loop_flag=False )   Load a sound

Returns: A sound object

url can be either a string, a stream or an audiosample object. The returned sound can be played using PlaySound or CueSound.

Example:

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

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

Input "Press any key to continue"

PlaySound:TChannel( sound:TSound,alloced_channel:TChannel=Null )   Play a sound

Returns: An audio channel object

PlaySound starts a sound playing through an audio channel. If no channel is specified, PlaySound creates a channel for you.

Example:

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:TChannel( sound:TSound,alloced_channel:TChannel=Null )   Cue a sound

Returns: An audio channel object

CueSound prepares an audio channel for playback of a sound. To actually start the sound, you must use ResumeChannel. This allows you to setup various states such as volume or pan before a channel starts playing.

Example:

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:TChannel()   Allocate audio channel

Returns: An audio channel object

Allocates an audio channel for use with PlaySound and CueSound. Any sound playing on a channel when it is reused will stop playing.

Use StopChannel to release the channel.

Example:

'AllocChannel.bmx

timer=CreateTimer(20)

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

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

StopChannel( channel:TChannel )   Stop an audio channel

Shuts down an audio channel. Further commands on this channel will have no effect.

Example:

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"

SetChannelVolume( channel:TChannel,volume# )   Set the playback volume of an audio channel

volume should be in the range 0 (silent) to 1 (full volume)

Example:

' 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( channel:TChannel,pan# )   Adjust stereo balance of an audio channel

pan should be in the range -1 (left) to 1 (right)

Example:

' 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( channel:TChannel,depth# )   Adjust surround sound depth of an audio channel

depth should be in the range -1 (back) to 1 (front)

Example:

' 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( channel:TChannel,rate# )   Set playback rate of an audio channel

rate is a multiplier used to calculate the frequency sounds are played back on the channel. Use 0.5 to play a sound at half it's recorded frequency and 2.0 to replay at twice the frequency.

Example:

' setchannelrate.bmx

timer=CreateTimer(10)

sound = LoadSound ("shoot.wav")

For rate#=.2 To 8 Step .2
	WaitTimer timer
	channel=CueSound(sound)
	ResumeChannel channel
	SetChannelRate channel,rate
Next

PauseChannel( channel:TChannel )   Pause an audio channel

ResumeChannel( channel:TChannel )   Resume an audio channel

SetChannelPaused( channel:TChannel,paused )   Pause/Resume a channel

Module Information

Modulebrl.audio
Version 1.00
Author Mark Sibly
License Blitz Shared Source Code
Copyright Blitz Research Ltd
Modserver BRL