Allegro 5 Tutorial/Addons/Audio

From Allegro Wiki

Jump to: navigation, search

In this section we teach you about using audio. This is not an advanced audio tutorial.

Extending on the display example, we will create a program that plays a music sample for ten seconds after which the display closes and stops the clip. Refer to the display tutorial for any code not covered in this tutorial.

#include <stdio.h>
#include <allegro5/allegro.h>
#include <allegro5/allegro_audio.h>
#include <allegro5/allegro_acodec.h>
 
int main(int argc, char **argv){
 
   ALLEGRO_DISPLAY *display = NULL;
   ALLEGRO_SAMPLE *sample=NULL;
 
   if(!al_init()){
      fprintf(stderr, "failed to initialize allegro!\n");
      return -1;
   }
 
   if(!al_install_audio()){
      fprintf(stderr, "failed to initialize audio!\n");
      return -1;
   }
 
   if(!al_init_acodec_addon()){
      fprintf(stderr, "failed to initialize audio codecs!\n");
      return -1;
   }
 
   if (!al_reserve_samples(1)){
      fprintf(stderr, "failed to reserve samples!\n");
      return -1;
   }
 
   sample = al_load_sample( "footstep.wav" );
 
   if (!sample){
      printf( "Audio clip sample not loaded!\n" ); 
      return -1;
   }
 
   display = al_create_display(640, 480);
 
   if(!display){
      fprintf(stderr, "failed to create display!\n");
      return -1;
   }
 
   /* Loop the sample until the display closes. */
   al_play_sample(sample, 1.0, 0.0,1.0,ALLEGRO_PLAYMODE_LOOP,NULL);
 
   al_rest(10.0);
 
   al_destroy_display(display);
   al_destroy_sample(sample);
   return 0;
}

Walk through

This walk through includes code from the previous Display example. Refer to the previous tutorial's walk through for information on code that is not explained here.

#include <allegro5/allegro_audio.h>
#include <allegro5/allegro_acodec.h>

#include <allegro5/allegro_audio.h> will include the audio add on library
#include <allegro5/allegro_acodec.h>will include the library to add audio formats such as wav,flac,ogg

ALLEGRO_SAMPLE *sample=NULL;

Create a pointer named sample of the the type ALLEGRO_SAMPLE. This creates space in memory for us to place the audio clip. We initialize it to NULL so that later if the assignment of the audio clip load sample fails the value of the pointer will be NULL and we will exit our program because the audio loading failed.

if(!al_install_audio()){
   fprintf(stderr, "failed to initialize audio!\n");
   return -1;
}

Install the audio subsystem. This is required to use audio. The acodec addon requires the audio subsystem to run. The function al_install_audio returns true on success, false on failure. Thus if the audio subsystem install fails we will print failed to initialize audio to the terminal screen and exit the program with an error status -1. Should this function fail, it will return NULL. While failure is unlikely in this simple example, you are better off checking every single function that could fail for any errors. You may have fewer hidden problems when the program becomes more complicated. We will use this idea to check all setup code.

if(!al_init_acodec_addon()) {
   fprintf(stderr, "failed to initialize audio codecs!\n");
   return -1;
}

Install the audio codec addon this function registers all known audio formats so functions like al_load_sample can use them. The available formats are depend on what libraries are available, the full set of recognised extensions is: .wav, .flac, .ogg, .it, .mod, .s3m, .xm.

if (!al_reserve_samples(1)){
   fprintf(stderr, "failed to reserve samples!\n");
   return -1;
}

Reserves a number of sample instances, and creates a default mixer if one doesn't exist. This allows us to decide how many audio samples we will be creating for now we are only creating one. Later we might have 3 different samples. The samples will all use the default mixer.

sample = al_load_sample( "footstep.wav" );
if (!sample) {
   printf( "Audio clip sample not loaded!\n" ); 
   return -1;
}

The function al_load_sample accepts a path and filename as a string. Here we are loading the wav audio file footstep.wav . This doesn't play the sample it returns a memory address for the audio sample footstep.wav which gets assigned to the pointer sample. If a sample isn't actually loaded we will print audio clip sample not loaded to the terminal screen and exit the program.

al_play_sample(sample, 1.0, 0.0,1.0,ALLEGRO_PLAYMODE_LOOP,NULL);

The function al_play_sample is responsible for actually playing the sample. Parameters:
The first parameter is the sample we wish to play in this case it is named sample but we could have called it bob,steve,or baconSandwich.
The rest in order are:
gain - relative volume at which the sample is played; 1.0 is normal.
pan - 0.0 is centered, -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 - ALLEGRO_PLAYMODE_ONCE, ALLEGRO_PLAYMODE_LOOP, or ALLEGRO_PLAYMODE_BIDIR
ret_id - if non-NULL the variable which this points to will be assigned an id representing the sample being played.

al_destroy_sample(sample);

The function al_destroy_sample accepts a sample as a parameter and frees the memory used by the sample.

On a final note, to compile this code you should be in the directory where your code is located you may use gcc or g++.

   gcc audioTest.c -o audioTest -L/usr/local/lib -lallegro -lallegro_main -lallegro_audio -lallegro_acodec

or

   g++ audioTest.c -o audioTest -L/usr/local/lib -lallegro -lallegro_main -lallegro_audio -lallegro_acodec

See also Compiling Allegro Programs for details on compiling.

Personal tools
Adsense