BRL.Audio: Types Functions Source  


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 AllocChannel.

Types

TSoundAudio sound type
TChannelAudio channel Type

Functions

LoadSoundLoad a sound
PlaySoundPlay a sound
CueSoundCue a sound
AllocChannelAllocate audio channel
StopChannelStop an audio channel
ChannelPlayingDetermine whether an audio channel is playing
SetChannelVolumeSet playback volume of an audio channel
SetChannelPanSet stereo balance of an audio channel
SetChannelDepthSet surround sound depth of an audio channel
SetChannelRateSet playback rate of an audio channel
PauseChannelPause audio channel playback
ResumeChannelResume audio channel playback
AudioDriversGet audio drivers
AudioDriverExistsDetermine if an audio driver exists
SetAudioDriverSet current audio driver

Function reference

Function LoadSound:TSound( url:Object,flags=0 )
ReturnsA sound object
DescriptionLoad a sound
Information url can be either a string, a stream or a TAudioSample object. The returned sound can be played using PlaySound or CueSound.

The flags parameter can be any combination of:

Flag valueEffect
SOUND_LOOPThe sound should loop when played back.
SOUND_HARDWAREThe sound should be placed in onboard soundcard memory if possible.

To combine flags, use the binary 'or' operator: '|'.

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

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

Input "Press any key to continue"

Function PlaySound:TChannel( sound:TSound,channel:TChannel=Null )
ReturnsAn audio channel object
DescriptionPlay a sound
Information PlaySound starts a sound playing through an audio channel. If no channel is specified, PlaySound automatically allocates 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"

Function CueSound:TChannel( sound:TSound,channel:TChannel=Null )
ReturnsAn audio channel object
DescriptionCue a sound
Information Prepares a sound for playback through an audio channel. To actually start the sound, you must use ResumeChannel. If no channel is specified, CueSound automatically allocates a channel for you.

CueSound allows you to setup various audio channel states such as volume, pan, depth and rate before a sound actually 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"

Function AllocChannel:TChannel()
ReturnsAn audio channel object
DescriptionAllocate audio channel
Information Allocates an audio channel for use with PlaySound and CueSound. Once you are finished with an audio channel, you should use StopChannel.
Example
'AllocChannel.bmx

timer=createtimer(20)

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

for i=1 to 20
	waittimer timer
	playsound sound,channel
next

Function StopChannel( channel:TChannel )
DescriptionStop an audio channel
Information Shuts down an audio channel. Further commands using 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"

Function ChannelPlaying( channel:TChannel )
ReturnsTrue if channel is currently playing
DescriptionDetermine whether an audio channel is playing
Information ChannelPlaying will return False if either the channel has been paused using PauseChannel, or stopped using StopChannel.
Example
' 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

Function SetChannelVolume( channel:TChannel,volume# )
DescriptionSet playback volume of an audio channel
Information 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

Function SetChannelPan( channel:TChannel,pan# )
DescriptionSet stereo balance of an audio channel
Information 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

Function SetChannelDepth( channel:TChannel,depth# )
DescriptionSet surround sound depth of an audio channel
Information 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

Function SetChannelRate( channel:TChannel,rate# )
DescriptionSet playback rate of an audio channel
Information rate is a multiplier used to modify the audio channel's frequency. For example, a rate of .5 will cause the audio channel to play at half speed (ie: an octave down) while a rate of 2 will cause the audio channel to play at double speed (ie: an octave up).
Example
' 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

Function PauseChannel( channel:TChannel )
DescriptionPause audio channel playback
Information Pauses audio channel playback.

Function ResumeChannel( channel:TChannel )
DescriptionResume audio channel playback
Information Resumes audio channel playback after it has been paused by CueSound or PauseChannel.

Function AudioDrivers$[]()
DescriptionGet audio drivers
Information Returns an array of strings, where each string describes an audio driver.

Function AudioDriverExists( name$ )
DescriptionDetermine if an audio driver exists
Information Returns True if the audio drvier specified by driver exists.

Function SetAudioDriver( name$ )
DescriptionSet current audio driver
Information Returns true if the audio driver was successfully set.