BRL.Audio: Functions Types Modinfo Source  

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.

Functions

Function AllocChannel:TChannel()
ReturnsAn audio channel object.
DescriptionAllocate audio channel.
InformationAllocates 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 ChannelPlaying( channel:TChannel )
ReturnsTrue if channel is currently playing.
DescriptionDetermine whether an audio channel is playing.
InformationChannelPlaying 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 CueSound:TChannel( sound:TSound,channel:TChannel=Null )
ReturnsAn audio channel object.
DescriptionCue a sound.
InformationPrepares 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 LoadSound:TSound( url:Object,loop_flag=False )
ReturnsA sound object.
DescriptionLoad a sound.
Informationurl can be either a string, a stream or an audio sample 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"

Function PauseChannel( channel:TChannel )
DescriptionPause audio channel playback.
InformationPauses audio channel playback.

Function PlaySound:TChannel( sound:TSound,channel:TChannel=Null )
ReturnsAn audio channel object.
DescriptionPlay a sound.
InformationPlaySound 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 ResumeChannel( channel:TChannel )
DescriptionResume audio channel playback.
InformationResumes audio channel playback after it has been paused by CueSound or PauseChannel.

Function SetChannelDepth( channel:TChannel,depth# )
DescriptionSet surround sound depth of an audio channel.
Informationdepth 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 SetChannelPan( channel:TChannel,pan# )
DescriptionSet stereo balance of an audio channel.
Informationpan 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 SetChannelRate( channel:TChannel,rate# )
DescriptionSet playback rate of an audio channel.
Informationrate 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 SetChannelVolume( channel:TChannel,volume# )
DescriptionSet playback volume of an audio channel.
Informationvolume 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 StopChannel( channel:TChannel )
DescriptionStop an audio channel.
InformationShuts 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"

Types

Type TChannel
DescriptionAudio channel Type.
Method Playing()
ReturnsTrue if channel is currently playing.
DescriptionDetermine whether audio channel is playing.
InformationPlaying will return False if the audio channel is either paused, or has been stopped using Stop.
Method SetDepth( depth# )
DescriptionSet audio channel depth.
Informationdepth should be in the range -1 (back) to 1 (front).
Method SetPan( pan# )
DescriptionSet audio channel stereo pan.
Informationpan should be in the range -1 (full left) to 1 (full right).
Method SetPaused( paused )
DescriptionPause or unpause audio channel playback.
InformationIf paused is True, the audio channel is paused. Otherwise, the audio channel is unpaused.
Method SetRate( rate# )
DescriptionSet audio channel playback rate.
Informationrate 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).
Method SetVolume( volume# )
DescriptionSet audio channel volume.
Informationvolume should be in the range 0 (silence) to 1 (full volume).
Method Stop()
DescriptionStop audio channel playback.
InformationShuts down the audio channel. Further commands on this audio channel will have no effect.

Type TSound
DescriptionAudio sound type.
Method Cue:TChannel( alloced_channel:TChannel=Null )
ReturnsAn audio channel object.
DescriptionCue the sound for playback.
InformationPrepares an audio channel for playback of a sound. To actually start the sound, you must use the channel's SetPaused method. If no channel is specified, Cue automatically allocates a channel for you.

Cue allows you to setup various audio channel states such as volume, pan, depth and rate before a sound actually starts playing.
Method Play:TChannel( alloced_channel:TChannel=Null )
ReturnsAn audio channel object.
DescriptionPlay the sound.
InformationStarts a sound playing through an audio channel. If no channel is specified, Play automatically allocates a channel for you.
Function Load:TSound( url:Object,loop_flag )
ReturnsA sound object.
DescriptionLoad sound.
Informationurl can be either a string, a stream or an audio sample object. The returned sound object can be played using Play or Cue.

Module Information

Version1.04
AuthorMark Sibly
LicenseBlitz Shared Source Code
CopyrightBlitz Research Ltd
ModserverBRL