BRL.Audio: | Functions | Types | Modinfo | Source |
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 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 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 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 LoadSound:TSound( url:Object,loop_flag=False ) | |
Returns | A sound object. |
Description | Load a sound. |
Information | url 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 ) | |
Description | Pause audio channel playback. |
Information | Pauses audio channel playback. |
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 ResumeChannel( channel:TChannel ) | |
Description | Resume audio channel playback. |
Information | Resumes audio channel playback after it has been paused by CueSound or PauseChannel. |
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 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 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 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 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" |
Type TChannel | |
Description | Audio channel Type. |
Method Playing() | |
Returns | True if channel is currently playing. |
Description | Determine whether audio channel is playing. |
Information | Playing will return False if the audio channel is either paused, or has been stopped using Stop. |
Method SetDepth( depth# ) | |
Description | Set audio channel depth. |
Information | depth should be in the range -1 (back) to 1 (front). |
Method SetPan( pan# ) | |
Description | Set audio channel stereo pan. |
Information | pan should be in the range -1 (full left) to 1 (full right). |
Method SetPaused( paused ) | |
Description | Pause or unpause audio channel playback. |
Information | If paused is True, the audio channel is paused. Otherwise, the audio channel is unpaused. |
Method SetRate( rate# ) | |
Description | Set audio channel playback rate. |
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). |
Method SetVolume( volume# ) | |
Description | Set audio channel volume. |
Information | volume should be in the range 0 (silence) to 1 (full volume). |
Method Stop() | |
Description | Stop audio channel playback. |
Information | Shuts down the audio channel. Further commands on this audio channel will have no effect. |
Type TSound | |
Description | Audio sound type. |
Method Cue:TChannel( alloced_channel:TChannel=Null ) | |
Returns | An audio channel object. |
Description | Cue the sound for playback. |
Information | Prepares 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 ) | |
Returns | An audio channel object. |
Description | Play the sound. |
Information | Starts 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 ) | |
Returns | A sound object. |
Description | Load sound. |
Information | url can be either a string, a stream or an audio sample object. The returned sound object can be played using Play or Cue. |
Version | 1.04 |
---|---|
Author | Mark Sibly |
License | Blitz Shared Source Code |
Copyright | Blitz Research Ltd |
Modserver | BRL |