BlitzMax/Modules/Audio/Audio playback

From Wikibooks, open books for an open world
Jump to navigation Jump to search

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[edit | edit source]

TSound[edit | edit source]

Audio sound type

Methods
  • Play
  • Cue
Functions
  • Load

TSound: Methods[edit | edit source]

Play

Method Play:TChannel( alloced_channel:TChannel=Null )

Description: Play the sound

Returns: An audio channel object

Information: Starts a sound playing through an audio channel. If no channel is specified, Play automatically allocates a channel for you.

Cue

Method Cue:TChannel( alloced_channel:TChannel=Null )

Description: Cue the sound for playback

Returns: An audio channel object

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.

TSound: Functions[edit | edit source]

Load

Function Load:TSound( url:Object,loop_flag )

Description: Load sound

Returns: A sound object

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.

TChannel[edit | edit source]

Audio channel Type

Methods
  • Stop
  • SetPaused
  • SetVolume
  • SetPan
  • SetDepth
  • SetRate
  • Playing

TChannel: Methods[edit | edit source]

Stop

Method Stop()

Description: Stop audio channel playback

Information: Shuts down the audio channel. Further commands on this audio channel will have no effect.

SetPaused

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.

SetVolume

Method SetVolume( volume# )

Description: Set audio channel volume

Information: volume should be in the range 0 (silence) to 1 (full volume).

SetPan

Method SetPan( pan# )

Description: Set audio channel stereo pan

Information: pan should be in the range -1 (full left) to 1 (full right).

SetDepth

Method SetDepth( depth# )

Description: Set audio channel depth

Information: depth should be in the range -1 (back) to 1 (front).

SetRate

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 (i.e.: an octave down) while a rate of 2 will cause the audio channel to play at double speed (i.e.: an octave up).

Playing

Method Playing()

Description: Determine whether audio channel is playing

Returns: True if channel is currently playing

Information: Playing will return False if the audio channel is either paused, or has been stopped using Stop.

Functions[edit | edit source]

LoadSound[edit | edit source]

Function LoadSound:TSound( url:Object,flags=0 )

Description: Load a sound

Returns: A sound object

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 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: '|'.

Example:

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

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

Input "Press any key to continue"

PlaySound[edit | edit source]

Function PlaySound:TChannel( sound:TSound,channel:TChannel=Null )

Description: Play a sound

Returns: An audio channel object

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"

CueSound[edit | edit source]

Function CueSound:TChannel( sound:TSound,channel:TChannel=Null )

Description: Cue a sound

Returns: An audio channel object

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"

AllocChannel[edit | edit source]

Function AllocChannel:TChannel()

Description: Allocate audio channel

Returns: An audio channel object

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

StopChannel[edit | edit source]

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"

ChannelPlaying[edit | edit source]

Function ChannelPlaying( channel:TChannel )

Description: Determine whether an audio channel is playing

Returns: True if channel is currently 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

SetChannelVolume[edit | edit source]

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

SetChannelPan[edit | edit source]

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

SetChannelDepth[edit | edit source]

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

SetChannelRate[edit | edit source]

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 (i.e.: an octave down) while a rate of 2 will cause the audio channel to play at double speed (i.e.: 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

PauseChannel[edit | edit source]

Function PauseChannel( channel:TChannel )

Description: Pause audio channel playback

Information: Pauses audio channel playback.

ResumeChannel[edit | edit source]

Function ResumeChannel( channel:TChannel )

Description: Resume audio channel playback

Information: Resumes audio channel playback after it has been paused by CueSound or PauseChannel.

AudioDrivers[edit | edit source]

Function AudioDrivers$[]()

Description: Get audio drivers

Information: Returns an array of strings, where each string describes an audio driver.

AudioDriverExists[edit | edit source]

Function AudioDriverExists( name$ )

Description: Determine if an audio driver exists

Information: Returns True if the audio drvier specified by driver exists.

SetAudioDriver[edit | edit source]

Function SetAudioDriver( name$ )

Description: Set current audio driver

Information: Returns true if the audio driver was successfully set.