Audio addon

Audio types

ALLEGRO_AUDIO_DEPTH

enum 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

ALLEGRO_AUDIO_DRIVER_ENUM

enum 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

ALLEGRO_AUDIO_PAN_NONE

#define ALLEGRO_AUDIO_PAN_NONE      (-1000.0f)

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

ALLEGRO_CHANNEL_CONF

enum 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

ALLEGRO_MIXER

typedef struct ALLEGRO_MIXER ALLEGRO_MIXER;

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

ALLEGRO_MIXER_QUALITY

enum ALLEGRO_MIXER_QUALITY {

• ALLEGRO_MIXER_QUALITY_POINT
• ALLEGRO_MIXER_QUALITY_LINEAR

ALLEGRO_PLAYMODE

enum ALLEGRO_PLAYMODE {

Sample and stream looping mode.

• ALLEGRO_PLAYMODE_ONCE
• ALLEGRO_PLAYMODE_LOOP
• ALLEGRO_PLAYMODE_BIDIR

ALLEGRO_SAMPLE_ID

typedef struct ALLEGRO_SAMPLE_ID 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.

ALLEGRO_SAMPLE

typedef struct ALLEGRO_SAMPLE 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.

ALLEGRO_SAMPLE_INSTANCE

typedef struct ALLEGRO_SAMPLE_INSTANCE 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).

ALLEGRO_STREAM

typedef struct ALLEGRO_STREAM ALLEGRO_STREAM;

An ALLEGRO_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_stream_fragments, or listen to events from the stream. An ALLEGRO_EVENT_STREAM_EMPTY_FRAGMENT event is generated whenever a new fragment is ready. Use al_get_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_stream.

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

ALLEGRO_VOICE

typedef struct ALLEGRO_VOICE 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

al_install_audio

bool al_install_audio(ALLEGRO_AUDIO_DRIVER_ENUM mode)

Parameters:

• mode - see ALLEGRO_AUDIO_DRIVER_ENUM

Returns true on success, false on failure.

See also: al_reserve_samples.

al_uninstall_audio

void al_uninstall_audio(void)

al_reserve_samples

bool al_reserve_samples(int 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

al_create_voice

ALLEGRO_VOICE *al_create_voice(unsigned long freq,
   ALLEGRO_AUDIO_DEPTH depth, ALLEGRO_CHANNEL_CONF chan_conf)

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.

al_destroy_voice

void al_destroy_voice(ALLEGRO_VOICE *voice)

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

al_detach_voice

void al_detach_voice(ALLEGRO_VOICE *voice)

Detaches the sample or mixer stream from the voice.

al_attach_stream_to_voice

bool al_attach_stream_to_voice(ALLEGRO_STREAM *stream,
   ALLEGRO_VOICE *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.

al_attach_mixer_to_voice

bool al_attach_mixer_to_voice(ALLEGRO_MIXER *mixer, ALLEGRO_VOICE *voice)

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

al_attach_sample_to_voice

bool al_attach_sample_to_voice(ALLEGRO_SAMPLE_INSTANCE *spl,
   ALLEGRO_VOICE *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.

al_get_voice_frequency

unsigned int al_get_voice_frequency(const ALLEGRO_VOICE *voice)

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

al_get_voice_channels

ALLEGRO_CHANNEL_CONF al_get_voice_channels(const ALLEGRO_VOICE *voice)

Return the channel configuration of the voice.

See also: ALLEGRO_CHANNEL_CONF.

al_get_voice_depth

ALLEGRO_AUDIO_DEPTH al_get_voice_depth(const ALLEGRO_VOICE *voice)

Return the audio depth of the voice.

See also: ALLEGRO_AUDIO_DEPTH.

al_get_voice_playing

bool al_get_voice_playing(const ALLEGRO_VOICE *voice)

Return true if the voice is currently playing.

al_set_voice_playing

bool al_set_voice_playing(ALLEGRO_VOICE *voice, bool val)

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.

al_get_voice_position

unsigned long al_get_voice_position(const ALLEGRO_VOICE *voice)

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.

al_set_voice_position

bool al_set_voice_position(ALLEGRO_VOICE *voice, unsigned long val)

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

al_create_sample

ALLEGRO_SAMPLE *al_create_sample(void *buf, unsigned long samples,
   unsigned long freq, ALLEGRO_AUDIO_DEPTH depth,
   ALLEGRO_CHANNEL_CONF chan_conf, bool free_buf)

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)

al_destroy_sample

void al_destroy_sample(ALLEGRO_SAMPLE *spl)

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.

al_play_sample

bool al_play_sample(ALLEGRO_SAMPLE *spl, float gain, float pan, float speed,
   int loop, ALLEGRO_SAMPLE_ID *ret_id)

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.

al_stop_sample

void al_stop_sample(ALLEGRO_SAMPLE_ID *spl_id)

Stop the sample started by al_play_sample.

al_stop_samples

void al_stop_samples(void)

Stop all samples started by al_play_sample.

al_get_sample_channels

ALLEGRO_CHANNEL_CONF al_get_sample_channels(const ALLEGRO_SAMPLE *spl)

Return the channel configuration.

See also: ALLEGRO_CHANNEL_CONF.

al_get_sample_depth

ALLEGRO_AUDIO_DEPTH al_get_sample_depth(const ALLEGRO_SAMPLE *spl)

Return the audio depth.

See also: ALLEGRO_AUDIO_DEPTH.

al_get_sample_frequency

unsigned int al_get_sample_frequency(const ALLEGRO_SAMPLE *spl)

Return the frequency of the sample.

al_get_sample_length

unsigned long al_get_sample_length(const ALLEGRO_SAMPLE *spl)

Return the length of the sample in sample values.

al_get_sample_data

void *al_get_sample_data(const ALLEGRO_SAMPLE *spl)

Return a pointer to the raw sample data.

al_create_sample_instance

ALLEGRO_SAMPLE_INSTANCE *al_create_sample_instance(ALLEGRO_SAMPLE *sample_data)

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.

al_destroy_sample_instance

void al_destroy_sample_instance(ALLEGRO_SAMPLE_INSTANCE *spl)

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

al_play_sample_instance

bool al_play_sample_instance(ALLEGRO_SAMPLE_INSTANCE *spl)

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

al_stop_sample_instance

bool al_stop_sample_instance(ALLEGRO_SAMPLE_INSTANCE *spl)

Stop an sample instance playing.

al_get_sample_instance_channels

ALLEGRO_CHANNEL_CONF al_get_sample_instance_channels(
   const ALLEGRO_SAMPLE_INSTANCE *spl)

Return the channel configuration.

See also: ALLEGRO_CHANNEL_CONF.

al_get_sample_instance_depth

ALLEGRO_AUDIO_DEPTH al_get_sample_instance_depth(const ALLEGRO_SAMPLE_INSTANCE *spl)

Return the audio depth.

See also: ALLEGRO_AUDIO_DEPTH.

al_get_sample_instance_frequency

unsigned int al_get_sample_instance_frequency(const ALLEGRO_SAMPLE_INSTANCE *spl)

Return the frequency of the sample instance.

al_get_sample_instance_length

unsigned long al_get_sample_instance_length(const ALLEGRO_SAMPLE_INSTANCE *spl)

Return the length of the sample instance in sample values.

al_set_sample_instance_length

bool al_set_sample_instance_length(ALLEGRO_SAMPLE_INSTANCE *spl,
   unsigned long val)

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.

al_get_sample_instance_position

unsigned long al_get_sample_instance_position(const ALLEGRO_SAMPLE_INSTANCE *spl)

Get the playback position of a sample instance.

al_set_sample_instance_position

bool al_set_sample_instance_position(ALLEGRO_SAMPLE_INSTANCE *spl,
   unsigned long val)

Set the playback position of a sample instance.

Returns true on success, false on failure.

al_get_sample_instance_speed

float al_get_sample_instance_speed(const ALLEGRO_SAMPLE_INSTANCE *spl)

Return the playback speed.

al_set_sample_instance_speed

bool al_set_sample_instance_speed(ALLEGRO_SAMPLE_INSTANCE *spl, float val)

Set the playback speed.

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

al_get_sample_instance_gain

float al_get_sample_instance_gain(const ALLEGRO_SAMPLE_INSTANCE *spl)

Return the playback gain.

al_set_sample_instance_gain

bool al_set_sample_instance_gain(ALLEGRO_SAMPLE_INSTANCE *spl, float val)

Set the playback gain.

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

al_get_sample_instance_pan

float al_get_sample_instance_pan(const ALLEGRO_SAMPLE_INSTANCE *spl)

Get the pan value.

al_set_sample_instance_pan

bool al_set_sample_instance_pan(ALLEGRO_SAMPLE_INSTANCE *spl, float val)

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

al_get_sample_instance_time

float al_get_sample_instance_time(const ALLEGRO_SAMPLE_INSTANCE *spl)

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

al_get_sample_instance_playmode

ALLEGRO_PLAYMODE al_get_sample_instance_playmode(const ALLEGRO_SAMPLE_INSTANCE *spl)

Return the playback mode.

al_set_sample_instance_playmode

bool al_set_sample_instance_playmode(ALLEGRO_SAMPLE_INSTANCE *spl,
   ALLEGRO_PLAYMODE val)

Set the playback mode.

Returns true on success, false on failure.

al_get_sample_instance_playing

bool al_get_sample_instance_playing(const ALLEGRO_SAMPLE_INSTANCE *spl)

Return true if the sample instance is playing.

al_set_sample_instance_playing

bool al_set_sample_instance_playing(ALLEGRO_SAMPLE_INSTANCE *spl, bool val)

Change whether the sample instance is playing.

Returns true on success, false on failure.

al_get_sample_instance_attached

bool al_get_sample_instance_attached(const ALLEGRO_SAMPLE_INSTANCE *spl)

Return whether the sample instance is attached to something.

al_detach_sample_instance

bool al_detach_sample_instance(ALLEGRO_SAMPLE_INSTANCE *spl)

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

al_get_sample

ALLEGRO_SAMPLE *al_get_sample(ALLEGRO_SAMPLE_INSTANCE *spl)

Return the sample data that the sample instance plays.

al_set_sample

bool al_set_sample(ALLEGRO_SAMPLE_INSTANCE *spl, ALLEGRO_SAMPLE *data)

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

al_create_mixer

ALLEGRO_MIXER *al_create_mixer(unsigned long freq,
   ALLEGRO_AUDIO_DEPTH depth, ALLEGRO_CHANNEL_CONF chan_conf)

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.

al_destroy_mixer

void al_destroy_mixer(ALLEGRO_MIXER *mixer)

Destroys the mixer stream.

al_get_default_mixer

ALLEGRO_MIXER *al_get_default_mixer(void)

Return the default mixer.

al_set_default_mixer

bool al_set_default_mixer(ALLEGRO_MIXER *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.

al_restore_default_mixer

bool al_restore_default_mixer(void)

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

al_attach_mixer_to_mixer

bool al_attach_mixer_to_mixer(ALLEGRO_MIXER *stream, ALLEGRO_MIXER *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.

al_attach_sample_to_mixer

bool al_attach_sample_to_mixer(ALLEGRO_SAMPLE_INSTANCE *spl,
   ALLEGRO_MIXER *mixer)

Attach a sample instance to a mixer.

Returns true on success, false on failure.

al_attach_stream_to_mixer

bool al_attach_stream_to_mixer(ALLEGRO_STREAM *stream, ALLEGRO_MIXER *mixer)

Attach a stream to a mixer.

Returns true on success, false on failure.

al_get_mixer_frequency

unsigned int al_get_mixer_frequency(const ALLEGRO_MIXER *mixer)

Return the mixer frequency.

al_set_mixer_frequency

bool al_set_mixer_frequency(ALLEGRO_MIXER *mixer, unsigned long val)

al_get_mixer_channels

ALLEGRO_CHANNEL_CONF al_get_mixer_channels(const ALLEGRO_MIXER *mixer)

Return the mixer channel configuration.

al_get_mixer_depth

ALLEGRO_AUDIO_DEPTH al_get_mixer_depth(const ALLEGRO_MIXER *mixer)

Return the mixer audio depth.

al_get_mixer_quality

ALLEGRO_MIXER_QUALITY al_get_mixer_quality(const ALLEGRO_MIXER *mixer)

Return the mixer quality.

See also: ALLEGRO_MIXER_QUALITY.

al_set_mixer_quality

bool al_set_mixer_quality(ALLEGRO_MIXER *mixer, ALLEGRO_MIXER_QUALITY val)

Set the mixer quality.

Returns true on success, false on failure.

al_get_mixer_playing

bool al_get_mixer_playing(const ALLEGRO_MIXER *mixer)

Return true if the mixer is playing.

al_set_mixer_playing

bool al_set_mixer_playing(ALLEGRO_MIXER *mixer, bool val)

Change whether the mixer is playing.

Returns true on success, false on failure.

al_get_mixer_attached

bool al_get_mixer_attached(const ALLEGRO_MIXER *mixer)

Return true if the mixer is attached to something.

al_detach_mixer

bool al_detach_mixer(ALLEGRO_MIXER *mixer)

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

al_set_mixer_postprocess_callback

bool al_set_mixer_postprocess_callback(ALLEGRO_MIXER *mixer,
   postprocess_callback_t postprocess_callback, void *pp_callback_userdata)

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

al_create_stream

ALLEGRO_STREAM *al_create_stream(size_t fragment_count, unsigned long samples,
   unsigned long freq, ALLEGRO_AUDIO_DEPTH depth,
   ALLEGRO_CHANNEL_CONF chan_conf)

Creates an ALLEGRO_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.

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

al_destroy_stream

void al_destroy_stream(ALLEGRO_STREAM *stream)

al_get_stream_event_source

ALLEGRO_EVENT_SOURCE *al_get_stream_event_source(ALLEGRO_STREAM *stream)

Retrieve the associated event source.

al_drain_stream

void al_drain_stream(ALLEGRO_STREAM *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.

al_rewind_stream

bool al_rewind_stream(ALLEGRO_STREAM *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.

al_get_stream_frequency

unsigned int al_get_stream_frequency(const ALLEGRO_STREAM *stream)

Return the stream frequency.

al_get_stream_channels

ALLEGRO_CHANNEL_CONF al_get_stream_channels(const ALLEGRO_STREAM *stream)

Return the stream channel configuration.

al_get_stream_depth

ALLEGRO_AUDIO_DEPTH al_get_stream_depth(const ALLEGRO_STREAM *stream)

Return the stream audio depth.

al_get_stream_length

unsigned long al_get_stream_length(const ALLEGRO_STREAM *stream)

al_get_stream_speed

float al_get_stream_speed(const ALLEGRO_STREAM *stream)

Return the playback speed.

al_set_stream_speed

bool al_set_stream_speed(ALLEGRO_STREAM *stream, float val)

Set the playback speed.

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

al_get_stream_gain

float al_get_stream_gain(const ALLEGRO_STREAM *stream)

Return the playback gain.

al_set_stream_gain

bool al_set_stream_gain(ALLEGRO_STREAM *stream, float val)

Set the playback gain.

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

al_get_stream_pan

float al_get_stream_pan(const ALLEGRO_STREAM *stream)

Get the pan value.

al_set_stream_pan

bool al_set_stream_pan(ALLEGRO_STREAM *stream, float val)

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.

al_get_stream_playing

bool al_get_stream_playing(const ALLEGRO_STREAM *stream)

Return true if the stream is playing.

al_set_stream_playing

bool al_set_stream_playing(ALLEGRO_STREAM *stream, bool val)

Change whether the stream is playing.

Returns true on success, false on failure.

al_get_stream_playmode

ALLEGRO_PLAYMODE al_get_stream_playmode(const ALLEGRO_STREAM *stream)

Return the playback mode.

al_set_stream_playmode

bool al_set_stream_playmode(ALLEGRO_STREAM *stream, ALLEGRO_PLAYMODE val)

Set the playback mode.

Returns true on success, false on failure.

al_get_stream_attached

bool al_get_stream_attached(const ALLEGRO_STREAM *stream)

Return whether the stream is attached to something.

al_detach_stream

bool al_detach_stream(ALLEGRO_STREAM *stream)

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

al_get_stream_fragment

bool al_get_stream_fragment(const ALLEGRO_STREAM *stream, void **val)

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 true, and val will contain the address of an internal buffer to be filled with audio data. The length and format of the buffer are specified with al_create_stream or can be queried with the various functions described here.

Once the buffer is filled, you must signal this to Allegro by passing val to al_set_stream_fragment.

Note: If you listen to events from the stream, an ALLEGRO_EVENT_STREAM_EMPTY_FRAGMENT event will be generated whenever a new fragment is ready.

al_set_stream_fragment

bool al_set_stream_fragment(ALLEGRO_STREAM *stream, void *val)

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

al_get_stream_fragments

unsigned int al_get_stream_fragments(const ALLEGRO_STREAM *stream)

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

al_get_available_stream_fragments

unsigned int al_get_available_stream_fragments(const ALLEGRO_STREAM *stream)

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

al_seek_stream_secs

bool al_seek_stream_secs(ALLEGRO_STREAM *stream, double time)

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.

al_get_stream_position_secs

double al_get_stream_position_secs(ALLEGRO_STREAM *stream)

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

al_get_stream_length_secs

double al_get_stream_length_secs(ALLEGRO_STREAM *stream)

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

al_set_stream_loop_secs

bool al_set_stream_loop_secs(ALLEGRO_STREAM *stream, double start, double end)

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

al_register_sample_loader

bool al_register_sample_loader(const char *ext,
   ALLEGRO_SAMPLE *(*loader)(const char *filename))

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.

al_register_sample_saver

bool al_register_sample_saver(const char *ext,
   bool (*saver)(const char *filename, ALLEGRO_SAMPLE *spl))

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.

al_register_stream_loader

bool al_register_stream_loader(const char *ext,
   ALLEGRO_STREAM *(*stream_loader)(const char *filename,
      size_t buffer_count, unsigned int samples))

Register a handler for al_stream_from_file. 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.

al_load_sample

ALLEGRO_SAMPLE *al_load_sample(const char *filename)

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

Returns the sample on success, NULL on failure.

See also: al_register_sample_loader, al_load_sample_wav

al_stream_from_file

ALLEGRO_STREAM *al_stream_from_file(const char *filename, size_t buffer_count,
   unsigned int samples)

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_STREAM for more details.

Returns the stream on success, NULL on failure.

See also: al_register_stream_loader, al_load_stream_wav

al_save_sample

bool al_save_sample(const char *filename, ALLEGRO_SAMPLE *spl)

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_stream_loader, al_save_sample_wav

al_load_sample_wav

ALLEGRO_SAMPLE *al_load_sample_wav(const char *filename)

Load a sample from a PCM .wav file.

Returns the sample on success, NULL on failure.

See also: al_load_sample_wav

al_save_sample_wav

bool al_save_sample_wav(const char *filename, ALLEGRO_SAMPLE *spl)

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

al_save_sample_wav_pf

bool al_save_sample_wav_pf(ALLEGRO_FILE *pf, ALLEGRO_SAMPLE *spl)

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

al_load_stream_wav

ALLEGRO_STREAM *al_load_stream_wav(const char *filename, size_t buffer_count,
   unsigned int samples)

Like al_stream_from_file but assumes the file is PCM .wav file.