.\" Automatically generated by Pandoc 3.1.12.1
.\"
.TH "ALLEGRO_AUDIO_STREAM" "3" "" "Allegro reference manual" ""
.SH NAME
ALLEGRO_AUDIO_STREAM \- Allegro 5 API
.SH SYNOPSIS
.IP
.EX
#include \f[B]<allegro5/allegro_audio.h>\f[R]

\f[B]typedef\f[R] \f[B]struct\f[R] ALLEGRO_AUDIO_STREAM ALLEGRO_AUDIO_STREAM;
.EE
.SH DESCRIPTION
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.
.PP
As with ALLEGRO_SAMPLE_INSTANCE(3) 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_MIXER(3), which,
eventually, reaches an ALLEGRO_VOICE(3) object.
.PP
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(3), or
listen to events from the stream.
.PP
You can register an audio stream event source to an event queue; see
al_get_audio_stream_event_source(3).
An ALLEGRO_EVENT_AUDIO_STREAM_FRAGMENT(3) event is generated whenever a
new fragment is ready.
When you receive an event, use al_get_audio_stream_fragment(3) 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(3).
.PP
If you\[cq]re late with supplying new data, the stream will be silent
until new data is provided.
You must call al_drain_audio_stream(3) when you\[cq]re finished with
supplying data to the stream.
.PP
It is often a good idea to prefill the audio stream with data before
ALLEGRO_EVENT_AUDIO_STREAM_FRAGMENT(3) events arrive.
Here is a snippet that will fill the stream buffers with silence:
.IP
.EX
ALLEGRO_AUDIO_STREAM *stream = al_create_audio_stream(num_buffers,
   samples_per_buffer, freq, depth, channel_conf);
void *buf;
\f[B]while\f[R] ((buf = al_get_audio_stream_fragment(stream))) {
   al_fill_silence(buf, samples_per_buffer, depth, channel_conf);
   al_set_audio_stream_fragment(stream, buf);
}
.EE
.PP
If the stream is created by al_load_audio_stream(3) or
al_play_audio_stream(3) then it will also generate an
ALLEGRO_EVENT_AUDIO_STREAM_FINISHED(3) event if it reaches the end of
the file and is not set to loop.