# BlitzMax/Modules/Audio/Audio playback

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
## TSound

Audio sound type
* Play
* Cue
* Load

## TSound: Methods

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

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

Audio channel Type
* Stop
* SetPaused
* SetVolume
* SetPan
* SetDepth
* SetRate
* Playing

## TChannel: Methods

Method Stop
Description: Stop audio channel playback
Information: Shuts down the audio channel. Further commands on this audio channel will have no effect.
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 SetVolume( volume# )
Description: Set audio channel volume
Information: volume should be in the range 0 (silence) to 1 (full volume).
Method SetPan( pan# )
Description: Set audio channel stereo pan
Information: pan should be in the range -1 (full left) to 1 (full right).
Method SetDepth( depth# )
Description: Set audio channel depth
Information: depth should be in the range -1 (back) to 1 (front).
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).
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
## LoadSound

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:

## PlaySound

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:

## CueSound

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:

## AllocChannel

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:

## StopChannel

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:

## ChannelPlaying

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:

## SetChannelVolume

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:

## SetChannelPan

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:

## SetChannelDepth

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:

## SetChannelRate

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:

## PauseChannel

Function PauseChannel( channel:TChannel )
Description: Pause audio channel playback
Information: Pauses audio channel playback.

## ResumeChannel

Function ResumeChannel( channel:TChannel )
Description: Resume audio channel playback
Information: Resumes audio channel playback after it has been paused by CueSound or PauseChannel.

## AudioDrivers

Function AudioDrivers$
Description: Get audio drivers
Information: Returns an array of strings, where each string describes an audio driver.

## AudioDriverExists

Function AudioDriverExists( name$ )
Description: Determine if an audio driver exists
Information: Returns True if the audio driver specified by driver exists.

## SetAudioDriver

Function SetAudioDriver( name$ )
Description: Set current audio driver
Information: Returns true if the audio driver was successfully set.