NAME

       ALLEGRO_AUDIO_STREAM - Allegro 5 API

SYNOPSIS

              #include <allegro5/allegro_audio.h>

              typedef struct ALLEGRO_AUDIO_STREAM ALLEGRO_AUDIO_STREAM;

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.

       As with ALLEGRO_SAMPLE_INSTANCE(3alleg5) 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(3alleg5), which, eventually, reaches an ALLEGRO_VOICE(3alleg5) 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(3alleg5),
       or listen to events from the stream.

       You    can    register    an    audio    stream    event    source    to    an    event    queue;     see
       al_get_audio_stream_event_source(3alleg5).    An  ALLEGRO_EVENT_AUDIO_STREAM_FRAGMENT(3alleg5)  event  is
       generated   whenever   a   new   fragment   is   ready.     When    you    receive    an    event,    use
       al_get_audio_stream_fragment(3alleg5)  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(3alleg5).

       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(3alleg5) when you’re finished with supplying data to the stream.

       It    is    often    a    good    idea    to    prefill    the    audio    stream    with   data   before
       ALLEGRO_EVENT_AUDIO_STREAM_FRAGMENT(3alleg5) events arrive.  Here is a snippet that will fill the  stream
       buffers with silence:

              ALLEGRO_AUDIO_STREAM *stream = al_create_audio_stream(num_buffers,
                 samples_per_buffer, freq, depth, channel_conf);
              void *buf;
              while ((buf = al_get_audio_stream_fragment(stream))) {
                 al_fill_silence(buf, samples_per_buffer, depth, channel_conf);
                 al_set_audio_stream_fragment(stream, buf);
              }

       If  the  stream is created by al_load_audio_stream(3alleg5) or al_play_audio_stream(3alleg5) then it will
       also generate an ALLEGRO_EVENT_AUDIO_STREAM_FINISHED(3alleg5) event if it reaches the end of the file and
       is not set to loop.

Allegro reference manual                                                           ALLEGRO_AUDIO_STREAM(3alleg5)