| 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.
| TSound | Audio sound type |
| TChannel | Audio channel Type |
| LoadSound | Load a sound |
| PlaySound | Play a sound |
| CueSound | Cue a sound |
| AllocChannel | Allocate audio channel |
| StopChannel | Stop an audio channel |
| ChannelPlaying | Determine whether an audio channel is playing |
| SetChannelVolume | Set playback volume of an audio channel |
| SetChannelPan | Set stereo balance of an audio channel |
| SetChannelDepth | Set surround sound depth of an audio channel |
| SetChannelRate | Set playback rate of an audio channel |
| PauseChannel | Pause audio channel playback |
| ResumeChannel | Resume audio channel playback |
| AudioDrivers | Get audio drivers |
| AudioDriverExists | Determine if an audio driver exists |
| SetAudioDriver | Set current audio driver |
| Function LoadSound:TSound( url:Object,flags=0 ) | |||||||
| Returns | A sound object | ||||||
| Description | Load 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:
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 ) | |
| Returns | An audio channel object |
| Description | Play 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 ) | |
| Returns | An audio channel object |
| Description | Cue 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() | |
| Returns | An audio channel object |
| Description | Allocate 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 ) | |
| Description | Stop 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 ) | |
| Returns | True if channel is currently playing |
| Description | Determine 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# ) | |
| Description | Set 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# ) | |
| Description | Set 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# ) | |
| Description | Set 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# ) | |
| Description | Set 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 ) | |
| Description | Pause audio channel playback |
| Information | Pauses audio channel playback. |
| Function ResumeChannel( channel:TChannel ) | |
| Description | Resume audio channel playback |
| Information | Resumes audio channel playback after it has been paused by CueSound or PauseChannel. |
| Function AudioDrivers$[]() | |
| Description | Get audio drivers |
| Information | Returns an array of strings, where each string describes an audio driver. |
| Function AudioDriverExists( name$ ) | |
| Description | Determine if an audio driver exists |
| Information | Returns True if the audio drvier specified by driver exists. |
| Function SetAudioDriver( name$ ) | |
| Description | Set current audio driver |
| Information | Returns true if the audio driver was successfully set. |