# 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_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).

### API: ALLEGRO_AUDIO_STREAM

An ALLEGRO_AUDIO_STREAM object is used to stream generated audio to the sound
device, in real-time. This is done by reading from a buffer, which is split
into a number of fragments. Whenever a fragment has finished playing, the
user can refill it with new data.

As with [ALLEGRO_SAMPLE_INSTANCE] objects, streams store information necessary
for playback, so you may not play the same stream multiple times simultaneously.
Streams 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 fill fragments with new audio data. To
know when a new fragment is ready to be filled, you can either directly check
with [al_get_available_audio_stream_fragments], or listen to events from the
stream.
An ALLEGRO_EVENT_AUDIO_STREAM_FRAGMENT event is generated whenever a new
fragment is ready. Use [al_get_audio_stream_fragment] to obtain a pointer to the
fragment to be filled. The size and format are determined by the parameters
passed to [al_create_audio_stream].

If you're late with supplying new data, the stream will be silent until new data
is provided. You must call [al_drain_audio_stream] when you're finished with
supplying data to the stream.

If the stream is created by [al_load_audio_stream] then it can also generate an
ALLEGRO_EVENT_AUDIO_STREAM_FINISHED event if it reaches the end of the file and
is not set to loop.

### 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 true on success, false on failure.

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

### API: al_get_allegro_audio_version

Returns the (compiled) version of the addon, in the same format as
[al_get_allegro_version].

### API: al_get_depth_size

Return the size of a sample, in bytes, for the given format. The format is one
of the values listed under [ALLEGRO_AUDIO_DEPTH].

### API: al_get_channel_count

Return the number of channels for the given channel configuration, which is one
of the values listed under [ALLEGRO_CHANNEL_CONF].

## Voice functions

### API: al_create_voice

Creates a voice struct and allocates a voice from the digital sound driver.
The passed frequency, sample format and channel configuration are used as a
hint to what kind of data will be sent to the voice. However, the underlying
sound driver is free to use non-matching values. For example it may be the
native format of the sound hardware. If you attach a mixer to the voice, the
mixer will convert from the mixer's format to the voice format and you do not
have to care about this. If you access the voice directly, make sure to not
rely on the parameters passed to this function, but query the returned voice
for the actual settings.

### 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_audio_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_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.

### API: al_get_voice_frequency

Return the frequency of the voice, e.g. 44100.

### API: al_get_voice_channels

Return the channel configuration of the voice.

See also: [ALLEGRO_CHANNEL_CONF].

### API: al_get_voice_depth

Return the audio depth of the voice.

See also: [ALLEGRO_AUDIO_DEPTH].

### API: al_get_voice_playing

Return true if the voice is currently playing.

### API: al_set_voice_playing

Change whether a voice is playing or not.
The voice must have a sample or mixer attached to it.

Returns true on success, false on failure.

### API: al_get_voice_position

When the voice has a non-streaming object attached to it, e.g. a sample,
returns the voice's current sample position.
Otherwise, returns zero.

### API: al_set_voice_position

Set the voice position.  This can only work if the voice has a non-streaming
object attached to it, e.g. a sample.

Returns true on success, false on failure.


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

To allocate a buffer of the correct size, you can use something like this:

    sample_size = al_get_channel_count(chan_conf) * al_get_depth_size(depth);
    bytes = samples * sample_size;
    buffer = al_malloc(bytes)

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

Parameters:

* gain - relative volume at which the sample is played; 1.0 is normal.

* pan - 0.0 is centred, -1.0 is left, 1.0 is right, or ALLEGRO_AUDIO_PAN_NONE.

* speed - relative speed at which the sample is played; 1.0 is normal.

* loop - the play mode.

* ret_id - if non-NULL the variable which this points to will be assigned
  an id representing the sample being played.

See also: [ALLEGRO_PLAYMODE], [ALLEGRO_AUDIO_PAN_NONE], [ALLEGRO_SAMPLE_ID],
[al_stop_sample].

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

Return the channel configuration.

See also: [ALLEGRO_CHANNEL_CONF].

### API: al_get_sample_depth

Return the audio depth.

See also: [ALLEGRO_AUDIO_DEPTH].

### API: al_get_sample_frequency

Return the frequency of the sample.

### API: al_get_sample_length

Return the length of the sample in sample values.

### API: al_get_sample_data

Return a pointer to the raw sample data.

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

Stop an sample instance playing.

### API: al_get_sample_instance_channels

Return the channel configuration.

See also: [ALLEGRO_CHANNEL_CONF].

### API: al_get_sample_instance_depth

Return the audio depth.

See also: [ALLEGRO_AUDIO_DEPTH].

### API: al_get_sample_instance_frequency

Return the frequency of the sample instance.

### API: al_get_sample_instance_length

Return the length of the sample instance in sample values.

### API: al_set_sample_instance_length

Set the length of the sample instance in sample values.

Return true on success, false on failure.  Will fail if the sample instance is
currently playing.

### API: al_get_sample_instance_position

Get the playback position of a sample instance.

### API: al_set_sample_instance_position

Set the playback position of a sample instance.

Returns true on success, false on failure.

### API: al_get_sample_instance_speed

Return the playback speed.

### API: al_set_sample_instance_speed

Set the playback speed.

Return true on success, false on failure.  Will fail if the sample instance is
attached directly to a voice.

### API: al_get_sample_instance_gain

Return the playback gain.

### API: al_set_sample_instance_gain

Set the playback gain.

Returns true on success, false on failure.  Will fail if the sample instance
is attached directly to a voice.

### API: al_get_sample_instance_pan

Get the pan value.

### API: al_set_sample_instance_pan

Set the pan value on a sample instance.  A value of -1.0 means to play the
sample only through the left speaker; +1.0 means only through the right
speaker; 0.0 means the sample is centre balanced.

A constant sound power level is maintained as the sample is panned from left
to right.  As a consequence, a pan value of 0.0 will play the sample 3 dB
softer than the original level.  To disable panning and play a sample at its
original level, set the pan value to [ALLEGRO_AUDIO_PAN_NONE].

Returns true on success, false on failure.
Will fail if the sample instance is attached directly to a voice.

(A sound guy should explain that better; I only implemented it.
Also this might be more properly called a balance control than pan.
Also we don't attempt anything with more than two channels yet.)

### API: al_get_sample_instance_time

Return the length of the sample instance in seconds,
assuming a playback speed of 1.0.

### API: al_get_sample_instance_playmode

Return the playback mode.

### API: al_set_sample_instance_playmode

Set the playback mode.

Returns true on success, false on failure.

### API: al_get_sample_instance_playing

Return true if the sample instance is playing.

### API: al_set_sample_instance_playing

Change whether the sample instance is playing.

Returns true on success, false on failure.

### API: al_get_sample_instance_attached

Return whether the sample instance is attached to something.

### API: al_detach_sample_instance

Detach the sample instance from whatever it's attached to,
if anything.

### API: al_get_sample

Return the sample data that the sample instance plays.

### API: al_set_sample

Change the sample data that a sample instance 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 true on success, false 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

Attach a sample instance to a mixer.

Returns true on success, false on failure.

### API: al_attach_audio_stream_to_mixer

Attach a stream to a mixer.

Returns true on success, false on failure.

### API: al_get_mixer_frequency

Return the mixer frequency.

### API: al_set_mixer_frequency

### API: al_get_mixer_channels

Return the mixer channel configuration.

### API: al_get_mixer_depth

Return the mixer audio depth.

### API: al_get_mixer_quality

Return the mixer quality.

See also: [ALLEGRO_MIXER_QUALITY].

### API: al_set_mixer_quality

Set the mixer quality.

Returns true on success, false on failure.

### API: al_get_mixer_playing

Return true if the mixer is playing.

### API: al_set_mixer_playing

Change whether the mixer is playing.

Returns true on success, false on failure.

### API: al_get_mixer_attached

Return true if the mixer is attached to something.

### API: al_detach_mixer

Detach the mixer from whatever it is attached to, if anything.

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

Creates an [ALLEGRO_AUDIO_STREAM]. The stream will be set to play by default.
It will feed audio data from a buffer, which is split into a number of
fragments.

--------------------------------------------------------------------------------
Parameter      Meaning
-------------  ------------------------------------------------------------------
fragment_count How many fragments to use for the audio stream. Usually only
               two fragments are required - splitting the audio buffer in two
               halves. But it means that the only time when new data can be
               supplied is whenever one half has finished playing.

               When using many fragments, you usually will use fewer samples
               for one, so there always will be (small) fragments available to
               be filled with new data.

samples        The size of a fragment in samples. See note below.

freq           The frequency, in Hertz.

depth          Must be one of the values listed for [ALLEGRO_AUDIO_DEPTH].

chan_conf      Must be one of the values listed for [ALLEGRO_CHANNEL_CONF].
--------------------------------------------------------------------------------

The choice of *fragment_count*, *samples* and *freq* directly influences the
audio delay. The delay in seconds can be expressed as:

    delay = fragment_count * samples / freq

This is only the delay due to Allegro's streaming, there may be additional
delay caused by sound drivers and/or hardware.

Note: If you know the fragment size in bytes, you can get the size in samples
like this:

    sample_size = al_get_channel_count(chan_conf) * al_get_depth_size(depth);
    samples = bytes_per_fragment / sample_size;

The size of the complete buffer is:

    buffer_size = bytes_per_fragment * fragment_count

### API: al_destroy_audio_stream

Destroy an audio stream which was created with [al_create_audio_stream]
or [al_load_audio_stream].

Note: If the stream is still attached to a mixer or voice,
[al_detach_audio_stream] is automatically called on it first.

### API: al_get_audio_stream_event_source

Retrieve the associated event source.

### API: al_drain_audio_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_audio_stream

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

### API: al_get_audio_stream_frequency

Return the stream frequency.

### API: al_get_audio_stream_channels

Return the stream channel configuration.

### API: al_get_audio_stream_depth

Return the stream audio depth.

### API: al_get_audio_stream_length

### API: al_get_audio_stream_speed

Return the playback speed.

### API: al_set_audio_stream_speed

Set the playback speed.

Return true on success, false on failure.  Will fail if the sample instance is
attached directly to a voice.

### API: al_get_audio_stream_gain

Return the playback gain.

### API: al_set_audio_stream_gain

Set the playback gain.

Returns true on success, false on failure.  Will fail if the sample instance
is attached directly to a voice.

### API: al_get_audio_stream_pan

Get the pan value.

### API: al_set_audio_stream_pan

Set the pan value on a sample instance.  A value of -1.0 means to play the
sample only through the left speaker; +1.0 means only through the right
speaker; 0.0 means the sample is centre balanced.

Returns true on success, false on failure.
Will fail if the sample instance is attached directly to a voice.

### API: al_get_audio_stream_playing

Return true if the stream is playing.

### API: al_set_audio_stream_playing

Change whether the stream is playing.

Returns true on success, false on failure.

### API: al_get_audio_stream_playmode

Return the playback mode.

### API: al_set_audio_stream_playmode

Set the playback mode.

Returns true on success, false on failure.

### API: al_get_audio_stream_attached

Return whether the stream is attached to something.

### API: al_detach_audio_stream

Detach the stream from whatever it's attached to,
if anything.

### API: al_get_audio_stream_fragment

When using Allegro's audio streaming, you will use this function to continuously
provide new sample data to a stream.

If the stream is ready for new data, the function will return the address
of an internal buffer to be filled with audio data.
The length and format of the buffer are specified with [al_create_audio_stream]
or can be queried with the various functions described here.
Once the buffer is filled, you must signal this to Allegro by passing the
buffer to [al_set_audio_stream_fragment].

If the stream is not ready for new data, the function will return NULL.

Note: If you listen to events from the stream, an
ALLEGRO_EVENT_AUDIO_STREAM_FRAGMENT event will be generated whenever a new
fragment is ready. However, getting an event is *not* a guarantee that
[al_get_audio_stream_fragment] will not return NULL, so you still must check for it.

### API: al_set_audio_stream_fragment

This function needs to be called for every successfull call of
[al_get_audio_stream_buffer] to indicate that the buffer is filled with new data.

### API: al_get_audio_stream_fragments

Returns the number of fragments this stream used. This is the same value as
passed to [al_create_audio_stream] when a new stream is created.

### API: al_get_available_audio_stream_fragments

Returns the number of available fragments in the stream. You can use
[al_get_audio_stream_buffer]

### API: al_seek_audio_stream_secs

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

### API: al_get_audio_stream_position_secs

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

### API: al_get_audio_stream_length_secs

Return the length of the stream in seconds.
Currently this can only be called on streams created with
[al_load_audio_stream].

### API: al_set_audio_stream_loop_secs

Sets the loop points for the stream in seconds.
Currently this can only be called on WAV and OGG streams created with
[al_load_audio_stream].

## Audio file I/O

### API: al_register_sample_loader

Register a handler for [al_load_sample].  The given function will be used to
handle the loading of sample files with the given extension.

The extension should include the leading dot ('.') character.
It will be matched case-insensitively.

The `loader` argument may be NULL to unregister an entry.

Returns true on success, false on error.
Returns false if unregistering an entry that doesn't exist.

### API: al_register_sample_saver

Register a handler for [al_save_sample].  The given function will be used to
handle the saving of sample files with the given extension.

The extension should include the leading dot ('.') character.
It will be matched case-insensitively.

The `saver` argument may be NULL to unregister an entry.

Returns true on success, false on error.
Returns false if unregistering an entry that doesn't exist.

### API: al_register_audio_stream_loader

Register a handler for [al_load_audio_stream].  The given function will be
used to open streams from files with the given extension.

The extension should include the leading dot ('.') character.
It will be matched case-insensitively.

The `stream_loader` argument may be NULL to unregister an entry.

Returns true on success, false on error.
Returns false if unregistering an entry that doesn't exist.

### API: al_load_sample

Loads a few different audio file formats based on their extension.
Some formats require external libraries to be installed prior to compiling
the library.

Note that this stores the entire file in memory at once, which
may be time consuming.  To read the file as it is needed, 
use [al_load_audio_stream].

Returns the sample on success, NULL on failure.

See also: [al_register_sample_loader], [al_load_sample_wav]

### API: al_load_audio_stream

Loads an audio file from disk as it is needed.

Unlike regular streams, the one returned by this function
need not be fed by the user; the library will automatically
read more of the file as it is needed.  The stream will 
contain *buffer_count* buffers with *samples* samples.

A stream must be attached to a voice to be used.  See
[ALLEGRO_AUDIO_STREAM] for more details.

Returns the stream on success, NULL on failure.

See also: [al_register_audio_stream_loader], [al_load_audio_stream_wav]

### API: al_save_sample

Writes a sample into a file.  Currently, wav is
the only supported format, and the extension
must be 'wav'.

Returns true on success, false on error.

See also: [al_register_audio_stream_loader], [al_save_sample_wav]

### API: al_load_sample_wav

Load a sample from a PCM .wav file.

Returns the sample on success, NULL on failure.

See also: [al_load_sample_wav]

### API: al_save_sample_wav

Save a sample to a PCM .wav file.

Returns true on success, false on error.

See also: [al_save_sample], [al_save_sample_wav_pf]

### API: al_save_sample_wav_pf

Write a PCM .wav file into the [ALLEGRO_FILE] stream given.

Returns true on success, false on error.

See also: [al_save_sample], [al_save_sample_wav_pf]

### API: al_load_audio_stream_wav

Like [al_load_audio_stream] but assumes the file is PCM .wav file.

