SDL::Mixer(3pm)

Supported Formats

The SDL Mixer library is a multi-channel audio mixer. It supports 8 channels of 16 bit stereo audio, and a single channel for music.

You can use the channels to load samples (i.e. sound effects) in the following formats:

•

Microsoft WAVE files (WAV)

•

Creative Labs VOC files (VOC)

•

MIDI files (if compiled with Timidity)

If you use MIDI, you should note that the process of mixing MIDI files to wave output is very CPU-intensive, so if playing regular WAVE files sound great, but playing MIDI files sound choppy, try using 8-bit audio, mono audio, or lower frequencies.

The music channel can play the following formats:

•

AIFF

•

MOD (.mod .xm .s3m .669 .it .med and more - if compiled with libmikmod)

•

OggVorbis (.ogg - if compiled with ogg/vorbis libraries)

•

MP3 (if compiled with SMPEG or MAD libraries)

•

FLAC (if compiled with FLAC library)

init

 my $init_flags = SDL::Mixer::init( $flags );

Loads dynamic libraries and prepares them for use. Flags should be one or more flags from init flags OR'd together. It returns the flags successfully initialized, or 0 on failure.

Example:

 use SDL::Mixer;
 
 my $init_flags = SDL::Mixer::init( MIX_INIT_MP3 | MIX_INIT_MOD | MIX_INIT_FLAC | MIX_INIT_OGG );
 
 print("We have MP3 support!\n")  if $init_flags & MIX_INIT_MP3;
 print("We have MOD support!\n")  if $init_flags & MIX_INIT_MOD;
 print("We have FLAC support!\n") if $init_flags & MIX_INIT_FLAC;
 print("We have OGG support!\n")  if $init_flags & MIX_INIT_OGG;

Flags:

•

MIX_INIT_MP3

•

MIX_INIT_MOD

•

MIX_INIT_FLAC

•

MIX_INIT_OGG

Note: Only available for SDL_mixer >= 1.2.10

quit

 SDL::Mixer::quit();

This function unloads the libraries previously loaded with init().

Note: Only available for SDL_mixer >= 1.2.10

linked_version

 $version = SDL::Mixer::linked_version();

"linked_version" gives you the major-, minor-, and patchlevel for SDL_mixer. This way you can check if e.g. init() and quit() are available.

Example:

 use SDL::Mixer;
 use SDL::Version;
 
 my $version = SDL::Mixer::linked_version();
 printf("%d.%d.%d\n", $version->major, $version->minor, $version->patch); # prints "1.2.8" for me

open_audio

 my $audio_opened = SDL::Mixer::open_audio( $frequency, $format, $channels, $chunksize );

"open_audio" will initialize SDL_mixer if it is not yet initialized, see note. SDL_mixer may not be able to provide the exact specifications your provided, however it will automatically translate between the expected format and the real one. You can retrieve the real format using query_spec.

Returns 0 on success, -1 on error.

Note: You must not use "AUDIO_S16", "AUDIO_U16", "AUDIO_S16LSB", or "AUDIO_U16LSB." They are not portable, and SDL will not return an error code when they fail. The result will be a horrible staticy noise. You can usually use "AUDIO_S16SYS", though not always. Future versions of SDL should take this parameter only as a hint, then read back the value that the OS (for example, OSS or ALSA) has chosen to use in case the desired audio type is not supported.

Note: When already initialized, this function will not re-initialize SDL_mixer, nor fail. It will merely increment the number of times SDL::Mixer::close_audio must be called to actually get it to uninitialize. This serves as a very simplistic method for multiple application components to use SDL_mixer without necessitating a great deal of inter-component awareness. Be warned however that in such a situation, the latest components to initialize SDL_mixer will probably not get the SDL_mixer settings they're expecting.

Example:

 use SDL;
 use SDL::Mixer;
 
 printf("Error initializing SDL_mixer: %s\n", SDL::get_error()) unless SDL::Mixer::open_audio(44100, AUDIO_S16, 2, 1024) == 0;

close_audio

 SDL::Mixer::close_audio();

Close the mixer and halting all playing audio. This function does not return anything.

query_spec

 my @query_spec = @{ SDL::Mixer::query_spec() };

Find out what the actual audio device parameters are. This function returns 1 as first array element (status) if the audio has been opened, 0 otherwise.

Example:

 use SDL::Mixer;
 
 my ($status, $freq, $format, $channels) = @{ SDL::Mixer::query_spec() };
 
 printf("%s, %s, %s, %s\n", $status, $freq, $format, $channels);