% Audio addon

# Audio types

## API: ALLEGRO_AUDIO_DEPTH

Sample depth and type, and signedness. Mixers only use 32-bit signed
float (-1..+1). The unsigned value is a bit-flag applied to the depth
value.

* ALLEGRO_AUDIO_DEPTH_INT8
* ALLEGRO_AUDIO_DEPTH_INT16
* ALLEGRO_AUDIO_DEPTH_INT24
* ALLEGRO_AUDIO_DEPTH_FLOAT32
* ALLEGRO_AUDIO_DEPTH_UNSIGNED

For convenience:

* ALLEGRO_AUDIO_DEPTH_UINT8
* ALLEGRO_AUDIO_DEPTH_UINT16
* ALLEGRO_AUDIO_DEPTH_UINT24

## API: ALLEGRO_AUDIO_DRIVER_ENUM

The sound driver to use. It is *highly* recommended to use
ALLEGRO_AUDIO_DRIVER_AUTODETECT whenever possible.

* ALLEGRO_AUDIO_DRIVER_AUTODETECT
* ALLEGRO_AUDIO_DRIVER_OPENAL
* ALLEGRO_AUDIO_DRIVER_ALSA
* ALLEGRO_AUDIO_DRIVER_DSOUND
* ALLEGRO_AUDIO_DRIVER_OSS

## API: ALLEGRO_AUDIO_PAN_NONE

Special value for the ALLEGRO_AUDIOPROP_PAN property.
Use this value to play samples at their original volume with panning
disabled.

## API: ALLEGRO_AUDIO_PROPERTY

Flags to pass to the various al\_\*\_get\_\* and al\_\*\_set\_\* functions.
Not all types will apply to all functions.

* ALLEGRO_AUDIOPROP_DEPTH
* ALLEGRO_AUDIOPROP_CHANNELS
* ALLEGRO_AUDIOPROP_FREQUENCY
* ALLEGRO_AUDIOPROP_PLAYING
* ALLEGRO_AUDIOPROP_ATTACHED
* ALLEGRO_AUDIOPROP_LENGTH
* ALLEGRO_AUDIOPROP_BUFFER
* ALLEGRO_AUDIOPROP_LOOPMODE
* ALLEGRO_AUDIOPROP_SPEED
* ALLEGRO_AUDIOPROP_POSITION
* ALLEGRO_AUDIOPROP_GAIN
* ALLEGRO_AUDIOPROP_PAN
* ALLEGRO_AUDIOPROP_FRAGMENTS
* ALLEGRO_AUDIOPROP_USED_FRAGMENTS
* ALLEGRO_AUDIOPROP_QUALITY
* ALLEGRO_AUDIOPROP_TIME

## API: ALLEGRO_CHANNEL_CONF

Speaker configuration (mono, stereo, 2.1, 3, etc).

* ALLEGRO_CHANNEL_CONF_1
* ALLEGRO_CHANNEL_CONF_2
* ALLEGRO_CHANNEL_CONF_3
* ALLEGRO_CHANNEL_CONF_4
* ALLEGRO_CHANNEL_CONF_5_1
* ALLEGRO_CHANNEL_CONF_6_1
* ALLEGRO_CHANNEL_CONF_7_1

## API: ALLEGRO_MIXER

A mixer is a type of stream which mixes together attached streams into a
single buffer.

## API: ALLEGRO_MIXER_QUALITY

* ALLEGRO_MIXER_QUALITY_POINT
* ALLEGRO_MIXER_QUALITY_LINEAR

## API: ALLEGRO_PLAYMODE

Sample and stream looping mode.

* ALLEGRO_PLAYMODE_ONCE
* ALLEGRO_PLAYMODE_LOOP
* ALLEGRO_PLAYMODE_BIDIR

## API: ALLEGRO_SAMPLE_ID

An ALLEGRO_SAMPLE_ID represents a sample being played via [al_play_sample].
It can be used to later stop the sample with [al_stop_sample].

## API: ALLEGRO_SAMPLE

An ALLEGRO_SAMPLE object stores the data necessary for playing
pre-defined digital audio. It holds information pertaining to data length,
frequency, channel configuration, etc.  You can have an ALLEGRO_SAMPLE
object playing multiple times simultaneously.  The object holds a
user-specified PCM data buffer, of the format the object is created with.

## API: ALLEGRO_SAMPLE_INSTANCE

An ALLEGRO_SAMPLE_INSTANCE object represents a playable instance
of a predefined sound effect.
It holds information pertaining to the looping mode, loop
start/end points, playing position, etc.  An instance uses the
data from an [ALLEGRO_SAMPLE] object.  Multiple instances may be created
from the same ALLEGRO_SAMPLE. An ALLEGRO_SAMPLE must not be
destroyed while there are instances which reference it.

To be played, an ALLEGRO_SAMPLE_INSTANCE object must be attached to an
[ALLEGRO_VOICE] object,
or to an [ALLEGRO_MIXER] object which is itself attached to an
ALLEGRO_VOICE object (or to another ALLEGRO_MIXER object which is attached
to an ALLEGRO_VOICE object, etc).

An ALLEGRO_SAMPLE_INSTANCE object uses the following fields:

XXX much of this will probably change soon

* ALLEGRO_AUDIOPROP_DEPTH (enum) -
  Gets the bit depth format the object was created with. This may not be
  changed after the object is created.

* ALLEGRO_AUDIOPROP_CHANNELS (enum) -
  Gets the channel configuration the object was created with. This may not
  be changed after the object is created.

* ALLEGRO_AUDIOPROP_FREQUENCY (long) -
  Gets the frequency (in hz) the object was created with. This may not be
  changed after the object is created. To change playback speed, see
  ALLEGRO_AUDIOPROP_SPEED.

* ALLEGRO_AUDIOPROP_PLAYING (bool) -
  Gets or sets the object's playing status. By default, it is stopped.
  Note that simply setting it true does not cause the object to play. It
  must also be attached to a voice, directly or indirectly (eg.
  sample->voice, sample->mixer->voice, sample->mixer->...->voice).

* ALLEGRO_AUDIOPROP_ATTACHED (bool) -
  Gets the object's attachment status (true if it is attached to a
  something, false if not). Setting this to false detaches the object from
  whatever it is attached to. You may not directly set this to true.

* ALLEGRO_AUDIOPROP_LENGTH (long) -
  Gets or sets the length of the object's data buffer, in
  samples-per-channel. When changing the length, you must make sure the
  current buffer is large enough. You may not change the length while the
  object is set to play.

* ALLEGRO_AUDIOPROP_BUFFER (ptr) -
  Gets or sets the object's data buffer. You may not get or set this if the
  object is set to play.

* ALLEGRO_AUDIOPROP_LOOPMODE (enum) -
  Gets or sets the object's looping mode. Setting this may fail if the
  object is attached to a voice and the audio driver does not support the
  requested looping mode.

* ALLEGRO_AUDIOPROP_SPEED (float) -
  Gets or sets the object's playing speed. Negative values will cause the
  object to play backwards. If the value is set too close to 0, this will
  fail to set.

* ALLEGRO_AUDIOPROP_POSITION (long) -
  Gets or sets the object's playing position. The value is in
  samples-per-channel.

* ALLEGRO_AUDIOPROP_GAIN (float) -
  Gets or sets the object's gain. The gain is only applied when mixing the
  sample into a parent mixer. Has no effect if the object is attached
  directly to a voice.

* ALLEGRO_AUDIOPROP_PAN (float) -
  Gets or sets the object's panning (-1.0 to 1.0, from left to right).
  The panning is only applied when mixing the sample into a parent mixer.
  Has no effect if the object is attached directly to a voice.

    To maintain a constant sound power level, when a sound is played in the
  middle, it will be output equally from both front speakers but reduced in
  level by 3 dB (about 0.707 of the original).  To play a sound centred
  and at its original level, set its ALLEGRO_AUDIOPROP_PAN property to
  [ALLEGRO_AUDIO_PAN_NONE].

## API: ALLEGRO_STREAM

An ALLEGRO_STREAM object is used to stream generated audio to the sound
device, in real-time. As with [ALLEGRO_SAMPLE_INSTANCE] objects,
they store information necessary for playback,
so you may not play one multiple times simultaneously.
They also need to be attached to an [ALLEGRO_VOICE] object, or
to an [ALLEGRO_MIXER] object which, eventually, reaches an ALLEGRO_VOICE
object.

While playing, you must periodically supply new buffer data by first
checking ALLEGRO_AUDIOPROP_USED_FRAGMENTS, then refilling the buffers via
ALLEGRO_AUDIOPROP_BUFFER. If you're late with supplying new data, the object
will be silenced until new data is provided. You must call [al_drain_stream]
when you're finished supplying the stream.

ALLEGRO_STREAM objects use the following fields:

* ALLEGRO_AUDIOPROP_DEPTH (enum) -
  Same as ALLEGRO_SAMPLE

* ALLEGRO_AUDIOPROP_CHANNELS (enum) -
  Same as ALLEGRO_SAMPLE

* ALLEGRO_AUDIOPROP_FREQUENCY (enum) -
  Same as ALLEGRO_SAMPLE

* ALLEGRO_AUDIOPROP_ATTACHED (bool) -
  Same as ALLEGRO_SAMPLE

* ALLEGRO_AUDIOPROP_PLAYING (bool) -
  Same as ALLEGRO_SAMPLE, with the exception that ALLEGRO_STREAM objects
  are set to play by default.

* ALLEGRO_AUDIOPROP_LOOPMODE (enum) -
  Same as ALLEGRO_SAMPLE

* ALLEGRO_AUDIOPROP_SPEED (float) -
  Same as ALLEGRO_SAMPLE, with the added caveat that negative values aren't
  allowed.

* ALLEGRO_AUDIOPROP_GAIN (float) -
  Same as ALLEGRO_SAMPLE.

* ALLEGRO_AUDIOPROP_PAN (float) -
  Same as ALLEGRO_SAMPLE.

* ALLEGRO_AUDIOPROP_LENGTH (long) -
  This gets the length, in samples-per-channel, of the individual buffer
  fragments. You may not set this after the object is created.

* ALLEGRO_AUDIOPROP_BUFFER (ptr) -
  This gets the next buffer fragment that needs to be filled. After the
  buffer is filled, this field must be set to the same pointer value to let
  the object know the new data is ready.

* ALLEGRO_AUDIOPROP_FRAGMENTS (long) -
  This gets the total number of buffer fragments the object was created
  with. You may not set this after the object is created.

* ALLEGRO_AUDIOPROP_USED_FRAGMENTS (long) -
  This gets the number of buffer fragments that are waiting to be refilled.
  This value is decreased when ALLEGRO_AUDIOPROP_BUFFER is used to retrieve a
  waiting buffer fragment. You may not set this value.

## API: ALLEGRO_VOICE

A voice structure that you'd attach a mixer or sample to. Ideally there
would be one ALLEGRO_VOICE per system/hardware voice.



# Setting up

## API: al_install_audio

Parameters:

* mode - see [ALLEGRO_AUDIO_DRIVER_ENUM]

Returns zero on success, non-zero on failure.

XXX the return value seems a bit out of place

*See also:*
[al_reserve_samples].

## API: al_uninstall_audio

## API: al_reserve_samples

Reserves 'reserve_samples' number of samples attached to the default mixer.
[al_install_audio] must have been called first.  If no default mixer is set,
then this function will create a voice with an attached mixer.
Returns true on success, false on error.



# Voice functions

## API: al_create_voice

Creates a voice struct and allocates a voice from the digital sound driver.
The sound driver's allocate_voice function should change the voice's
frequency, depth, chan_conf, and settings fields to match what is actually
allocated. If it cannot create a voice with exact settings it will fail.
Use a mixer in such a case.

## API: al_destroy_voice

Destroys the voice and deallocates it from the digital driver.
Does nothing if the voice is NULL.

## API: al_detach_voice

Detaches the sample or mixer stream from the voice.

## API: al_attach_stream_to_voice

Attaches an audio stream to a voice. The same rules as
[al_attach_sample_to_voice] apply. This may fail if the driver can't create
a voice with the buffer count and buffer size the stream uses.

## API: al_get_voice_bool

## API: al_get_voice_enum

## API: al_get_voice_long

## API: al_set_voice_bool

## API: al_set_voice_enum

## API: al_set_voice_long

## API: al_attach_mixer_to_voice

Attaches a mixer to a voice. The same rules as [al_attach_sample_to_voice]
apply, with the exception of the depth requirement.

## API: al_attach_sample_to_voice

Attaches a sample to a voice, and allows it to play. The sample's volume
and loop mode will be ignored, and it must have the same frequency and
depth (including signed-ness) as the voice. This function may fail if the
selected driver doesn't support preloading sample data.



# Sample functions

## API: al_create_sample

Create a sample data structure from the supplied buffer.
If `free_buf` is true then the buffer will be freed as well when the
sample data structure is destroyed.

## API: al_destroy_sample

Free the sample data structure. If it was created with the `free_buf`
parameter set to true, then the buffer will be freed as well.

You must destroy any [ALLEGRO_SAMPLE_INSTANCE] structures which reference
this ALLEGRO_SAMPLE beforehand.

## API: al_play_sample

Plays a sample over the default mixer. [al_reserve_samples] must have
previously been called. Returns true on success, false on failure.
Playback may fail because all the reserved samples are currently used.

## API: al_stop_sample

Stop the sample started by [al_play_sample].

## API: al_stop_samples

Stop all samples started by [al_play_sample].

## API: al_create_sample_instance

Creates a sample stream, using the supplied data.  This must be attached
to a voice or mixer before it can be played.
The argument may be NULL. You can then set the data later with
[al_set_sample].

## API: al_destroy_sample_instance

Detaches the sample stream from anything it may be attached to and frees
it (the sample data is *not* freed!).

## API: al_play_sample_instance

Play an instance of a sample data.
Returns true on success, false on failure.

## API: al_stop_sample_instance

## API: al_get_sample_instance_bool

## API: al_get_sample_instance_enum

## API: al_get_sample_instance_float

## API: al_get_sample_instance_long

## API: al_get_sample_instance_ptr

## API: al_get_sample

## API: al_set_sample_instance_bool

## API: al_set_sample_instance_enum

## API: al_set_sample_instance_float

## API: al_set_sample_instance_long

## API: al_set_sample_instance_ptr

## API: al_set_sample

Change the sample data that a sample plays.  This can be quite an involved
process.

First, the sample is stopped if it is not already.

Next, if data is NULL, the sample is detached from its parent (if any).

If data is not NULL, the sample may be detached and reattached to its
parent (if any).  This is not necessary if the old sample data and new
sample data have the same frequency, depth and channel configuration.
Reattaching may not always succeed.

On success, the sample remains stopped.  The playback position and loop
end points are reset to their default values.  The loop mode remains
unchanged.

Returns zero on success, non-zero on failure.  On failure, the sample will
be stopped and detached from its parent.



# Mixer functions

## API: al_create_mixer

Creates a mixer stream, to attach sample streams or other mixers to. It
will mix into a buffer at the requested frequency and channel count.
Only floating point mixing is currently supported.

## API: al_destroy_mixer

Destroys the mixer stream.

## API: al_get_default_mixer

Return the default mixer.

## API: al_set_default_mixer

Sets the default mixer. All samples started with [al_play_sample]
will be stopped. If you are using your own mixer, this should be
called before [al_reserve_samples].
Returns true on success, false on error.

## API: al_restore_default_mixer

Restores Allegro's default mixer. All samples started with [al_play_sample]
will be stopped.
Returns true on success, false on error.

## API: al_attach_mixer_to_mixer

Attaches a mixer onto another mixer. The same rules as with
[al_attach_sample_to_mixer] apply, with the added caveat that both
mixers must be the same frequency.

## API: al_attach_sample_to_mixer

## API: al_attach_stream_to_mixer

## API: al_get_mixer_bool

## API: al_get_mixer_enum

## API: al_get_mixer_long

## API: al_set_mixer_bool

## API: al_set_mixer_enum

## API: al_set_mixer_long

## API: al_set_mixer_postprocess_callback

Sets a post-processing filter function that's called after the attached
streams have been mixed. The buffer's format will be whatever the mixer
was created with. The sample count and user-data pointer is also passed.



# Stream functions

## API: al_create_stream

Creates an audio stream, using the supplied values. The stream will be
set to play by default.

## API: al_destroy_stream

## API: al_drain_stream

Called by the user if sample data is not going to be passed to the stream
any longer. This function waits for all pending buffers to finish playing.
Stream's playing state will change to false.

## API: al_rewind_stream

Set the streaming file playing position to the beginning. Returns true on
success. Currently this can only be called on streams created with acodec's
[al_stream_from_file].

## API: al_get_stream_bool

## API: al_get_stream_enum

## API: al_get_stream_float

## API: al_get_stream_long

## API: al_get_stream_ptr

## API: al_set_stream_bool

## API: al_set_stream_enum

## API: al_set_stream_float

## API: al_set_stream_long

## API: al_set_stream_ptr

## API: al_seek_stream

Set the streaming file playing position to time. Returns true on success.
Currently this can only be called on streams created with acodec's
[al_stream_from_file].

## API: al_get_stream_position

Return the position of the stream in seconds.
Currently this can only be called on streams created with acodec's
[al_stream_from_file].

## API: al_get_stream_length

Return the position of the stream in seconds.
Currently this can only be called on streams created with acodec's
[al_stream_from_file].

## API: al_set_stream_loop

Return the position of the stream in seconds.
Currently this can only be called on streams created with acodec's
[al_stream_from_file].

