BRL.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 AllocChannel.
Types
Type | Description |
---|---|
TSound | Audio sound type |
TChannel | Audio channel Type |
Functions
Function LoadSound:TSound( url:Object,flags:Int=0 )
Load a sound
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 value | Effect |
SOUND_LOOP | The sound should loop when played back. |
SOUND_HARDWARE | The sound should be placed in onboard soundcard memory if possible. |
To combine flags, use the binary 'or' operator: '|'.
Returns
A sound object
Example
Rem
Load and Play a small example wav file.
End Rem
SuperStrict
Local sound:TSound = LoadSound("shoot.wav")
PlaySound sound
Input "Press any key to continue"
Function PlaySound:TChannel( sound:TSound,channel:TChannel=Null )
Play a sound
PlaySound starts a sound playing through an audio channel. If no channel is specified, PlaySound automatically allocates a channel for you.
Returns
An audio channel object
Example
Rem
Load and Play a small example wav file with looping.
End Rem
SuperStrict
Local sound:TSound = LoadSound("shoot.wav",True)
PlaySound sound
Input "Press any key to continue"
Function CueSound:TChannel( sound:TSound,channel:TChannel=Null )
Cue a sound
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.
Returns
An audio channel object
Example
' CueSound example
SuperStrict
Local sound:TSound = LoadSound("shoot.wav")
Local channel:TChannel = CueSound(sound)
Input "Press return key to play cued sound"
ResumeChannel channel
Input "Press return key to quit"
Function AllocChannel:TChannel()
Allocate audio channel
Allocates an audio channel for use with PlaySound and CueSound. Once you are finished with an audio channel, you should use StopChannel.
Returns
An audio channel object
Example
'AllocChannel.bmx
SuperStrict
Local timer:TTimer = CreateTimer(20)
Local sound:TSound = LoadSound ("shoot.wav")
Local channel:TChannel = AllocChannel()
For Local i:Int = 1 To 20
WaitTimer timer
PlaySound sound,channel
Next
Function StopChannel( channel:TChannel )
Stop an audio channel
Shuts down an audio channel. Further commands using this channel will have no effect.
Example
' StopChannel example
SuperStrict
Local sound:TSound = LoadSound("shoot.wav",True)
Local channel:TChannel = PlaySound(sound)
Input "Press return key to stop sound"
StopChannel channel
Input "Press return key to quit"
Function ChannelPlaying:Int( channel:TChannel )
Determine whether an audio channel is playing
ChannelPlaying will return False if either the channel has been paused using PauseChannel, or stopped using StopChannel.
Returns
True if channel is currently playing
Example
' channelplaying.bmx
SuperStrict
Local sound:TSound = LoadSound ("shoot.wav")
Input "Hit return to begin channelplaying test, use ctrl-C to exit"
Local channel:TChannel = PlaySound (sound)
While True
Print "ChannelPlaying(channel)="+ChannelPlaying(channel)
Wend
Function SetChannelVolume( channel:TChannel,volume# )
Set playback volume of an audio channel
volume should be in the range 0 (silent) to 1 (full volume)
Example
' setchannelvolume.bmx
SuperStrict
Local timer:TTimer = CreateTimer(20)
Local sound:TSound = LoadSound ("shoot.wav")
For Local volume#=.1 To 2 Step .05
WaitTimer timer
Local channel:TChannel = CueSound(sound)
SetChannelVolume channel,volume
ResumeChannel channel
Next
Function SetChannelPan( channel:TChannel,pan# )
Set stereo balance of an audio channel
pan should be in the range -1 (left) to 1 (right)
Example
' setchannelpan.bmx
SuperStrict
Graphics 640, 480
Local channel:TChannel = AllocChannel ()
Local sound:TSound = LoadSound ("shoot.wav") ' Use a short sample...
Repeat
If MouseHit(1) Then
PlaySound sound,channel
End If
Local pan# = MouseX () / (GraphicsWidth () / 2.0) - 1
Local 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# )
Set surround sound depth of an audio channel
depth should be in the range -1 (back) to 1 (front)
Example
' setchanneldepth.bmx
SuperStrict
Graphics 640, 480
Local channel:TChannel = AllocChannel ()
Local sound:TSound = LoadSound ("shoot.wav") ' Use a short sample...
Repeat
If MouseHit(1) Then
PlaySound sound,channel
End If
Local pan# = MouseX () / (640 / 2.0) - 1
Local 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# )
Set playback rate of an audio channel
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
SuperStrict
Local timer:TTimer = CreateTimer(20)
Local sound:TSound = LoadSound ("shoot.wav",True)
Local channel:TChannel = CueSound(sound)
ResumeChannel channel
For Local rate#=1.0 To 4 Step 0.01
WaitTimer timer
SetChannelRate channel,rate
Next
Function PauseChannel( channel:TChannel )
Pause audio channel playback
Pauses audio channel playback.
Example
' PauseChannel Example
SuperStrict
Graphics 640 , 480
Local noise:TSound = TSound.Load(blitzmaxpath()+"\samples\hitoro\sounds\gameover.ogg",0)
Local channel:TChannel = PlaySound(noise)
Local elapsed:Int = MilliSecs()
Repeat
Cls
DrawText "Press P to play sound" , 10 , 10
If (MilliSecs() - elapsed) > 500
PauseChannel(channel) ' pause after 0.5 secs played
End If
If KeyHit(KEY_P) Then
channel = PlaySound(noise)
elapsed = MilliSecs()
End If
Flip
Until AppTerminate() Or KeyHit(KEY_ESCAPE)
Function ResumeChannel( channel:TChannel )
Resume audio channel playback
Resumes audio channel playback after it has been paused by CueSound or PauseChannel.
Example
' ResumeChannel example
SuperStrict
Graphics 640, 480
Local sound:TSound = LoadSound(blitzmaxpath()+"\samples\hitoro\sounds\gameover.ogg")
Local channel:TChannel = CueSound(sound)
Repeat
DrawText "Press A to play sound",10,10
DrawText "Press C to Cue sound",10,30
If KeyHit(KEY_A) Then
ResumeChannel channel
End If
If KeyHit(KEY_C) Then
Channel=CueSound(sound)
End If
Flip
Until AppTerminate() Or KeyHit(KEY_ESCAPE)
Function AudioDrivers$[]()
Get audio drivers
Returns an array of strings, where each string describes an audio driver.
Example
SuperStrict
'Iterate through every available audio driver on your system
For Local a:String = EachIn AudioDrivers()
Print a
Next
Function AudioDriverExists:Int( name$ )
Determine if an audio driver exists
Returns True if the audio drvier specified by driver exists.
Example
SuperStrict
'Iterate through every available audio driver on your system
For Local a:String = EachIn AudioDrivers()
Print a + ":"+AudioDriverExists(a)
Next
Local a:String ="imaginary driver"
Print a+":"+AudioDriverExists(a)
Function SetAudioDriver:Int( name$ )
Set current audio driver
Returns true if the audio driver was successfully set.
Example
SuperStrict
Repeat
Print "Select Audio Driver:"
Print "1) FreeAudio"
Print "2) OpenAL"
Print "3) DirectSound"
Local n:Int
Select Input( ">" )
Case 1
n = SetDriver( "FreeAudio" )
Case 2
n = SetDriver( "OpenAL" )
Case 3
n = SetDriver( "DirectSound" )
End Select
If n Exit
Forever
Function SetDriver:Int(d:String)
If AudioDriverExists(d) Then
Return SetAudioDriver(d)
Else
RuntimeError "Cannot set " + d
EndIf
End Function