---
name: "ALLEGRO_AUDIO_STREAM"
section: "3"
platform: "linux"
package: "allegro"
version: "5.2.11.3-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/ALLEGRO_AUDIO_STREAM"
---

# ALLEGRO\_AUDIO\_STREAM(3)

Allegro 5 API

## 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(3)](/ALLEGRO_SAMPLE_INSTANCE/3.md) 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)](/ALLEGRO_MIXER/3.md), which, eventually, reaches an [ALLEGRO\_VOICE(3)](/ALLEGRO_VOICE/3.md) 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(3)](/al_get_available_audio_stream_fragments/3.md), 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(3)](/al_get_audio_stream_event_source/3.md). 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)](/al_get_audio_stream_fragment/3.md) 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)](/al_create_audio_stream/3.md).

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(3)](/al_drain_audio_stream/3.md) 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(3) 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(3)](/al_load_audio_stream/3.md) or [al\_play\_audio\_stream(3)](/al_play_audio_stream/3.md) 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.