MixerX

1. Overview

A Little Bit About Me (author of original manual)

I am currently, as I write this document, a programmer for Raytheon. There I do all sorts of communications, network, GUI, and other general programming tasks in C/C++ on the Solaris and sometimes Linux Operating Systems. I have been programming sound code in my free time for only a little while now. Sound is an integral part to any game. The human senses are mostly starved during video game play. there’s only some tactile feedback on some controlers, and of course the eyes are in use but only for about 30% of their viewing area. So to add more we do need sound to help the game player feel more in the action, and to set certain moods as the game progresses. Sound ends up accounting for perhaps 50% or more of a gamers experience. Music and sound effects are all integral parts of the gaming experience. While this document doesn’t explain how to get music and samples to use, it will explain how to use them with SDL_mixer.

Feel free to contact me: JonathanCAtkins@gmail.com

I am also usually on IRC at irc.freenode.net in the #SDL channel as LIM

This is the README in the SDL_mixer source archive.

2. MixerX

It’s an extended fork of the SDL_mixer library made by Vitaly Novichkov "Wohlstand" in 13 January 2015. SDL_mixer is a quick and stable high-quality audio library, however, it has own bunch of deffects and lack of certain abilities such as inability to choose the MIDI backend in runtime, No support for cross-fade and parallel streams playing (has only one musical stream. Using of very long Chunks is ineffectively), etc. The goal of this fork is resolving those issues, providing more extended functionality than was originally, and providing support for more supported audio formats.

In this documentation, new-added functions, definitions, and enums in this fork will be marked by [Mixer X] label. That means those functions are existing only in SDL Mixer X fork and wasn’t existed in original SDL_mixer library.

This fork is based on SDL_mixer 2.x unlike original documentation which is created for SDL_mixer 1.2. Some functions would be marked by [Mixer X] label which means those functions are not available in SDL_mixer 1.x, but available in SDL_mixer 2.0 and SDL Mixer X fork.

IMPORTANT: The license for libADLMIDI, libOPNMIDI, libGME with MAME YM2612 emulator is GPL which means that in order to use it your application must also be GPL!

3. Getting Started

This assumes you have gotten SDL Mixer X and installed it on your system. SDL_mixer has an INSTALL document in the source distribution to help you get it compiled and installed.

Generally, installation consists of:

mkdir build
cd build
cmake ..
make

SDL Mixer X supports playing music and sound samples from the following formats:
- WAVE/RIFF (.wav)
- AIFF (.aiff)
- VOC (.voc)
- MOD (.mod .xm .s3m .669 .it .med and more) requiring libxmp or libmodplug [Mixer 2.0] built in package
- MIDI (.mid) using timidity, FluidSynth [Mixer 2.0], libADLMIDI [Mixer X], libOPNMIDI [Mixer X], libEDMIDI [Mixer X] or native midi hardware
- OggVorbis (.ogg) requiring ogg/vorbis libraries built in package, or stb_vorbis enabled isntead
- MP3 (.mp3) requiring MPG123 library built in package, or DRMP3 enabled instead
- FLAC (.flac) requiring the FLAC library built in package, or DRFLAC enabled instead
- Opus (.opus) requiring the Opus/OpusFile library built in package
- GME (.spc .nsf .hes .vgm and more) requiring the libGME library built in package [Mixer X]
- also any command-line player, which is not mixed by SDL Mixer X...

You may also want to look at some demonstration code which may be downloaded from:
http://www.jonatkins.org/SDL_mixer/

3.1 Includes

To use MixerX functions in a C/C++ source code file, you must use the SDL_mixer_ext.h include file:

3.2 Compiling

To link with SDL MixerX you should use sdl-config to get the required SDL compilation options. After that, compiling with MixerX is quite easy.
Note: Some systems may not have the SDL_mixer library and include file in the same place as the SDL library and includes are located, in that case you will need to add more -I and -L paths to these command lines.

Now myprogram is ready to run.

4. Conflicts

When using SDL_mixer functions you need to avoid the following functions from SDL:

SDL_OpenAudio

Use Mix_OpenAudio instead.

SDL_CloseAudio

Use Mix_CloseAudio instead.

SDL_PauseAudio

MIXER-X:
Use Mix_PauseAudio(0) instead, to pause.
Use Mix_PauseAudio(1) instead, to pause.
SDL_mixer:
Use Mix_Pause(-1) and Mix_PauseMusic instead, to pause.
Use Mix_Resume(-1) and Mix_ResumeMusic instead, to unpause.

SDL_LockAudio

Use Mix_LockAudio instead.

SDL_UnlockAudio

Use Mix_UnlockAudio instead.

You may call the following functions freely:

SDL_AudioDriverName

This will still work as usual.

SDL_GetAudioStatus

This will still work, though it will likely return SDL_AUDIO_PLAYING even though SDL_mixer is just playing silence.

It is also a BAD idea to call SDL_mixer and SDL audio functions from a callback. Callbacks include Effects functions and other SDL_mixer audio hooks.

5. Functions

These are the functions in the SDL_mixer API.

5.1 General

These functions are useful, as they are the only/best ways to work with SDL_mixer.

Info

Activation

Manual audio output processing

Errors

Settings

5.1.1 Mix_Linked_Version

const SDL_version *Mix_Linked_Version()
void SDL_MIXER_VERSION(SDL_version *compile_version)

This works similar to SDL_Linked_Version and SDL_VERSION.
Using these you can compare the runtime version to the version that you compiled with.

SDL_version compile_version;
const SDL_version *link_version=Mix_Linked_Version();
SDL_MIXER_VERSION(&compile_version);
printf("compiled with SDL_mixer version: %d.%d.%d\n",
        compile_version.major,
        compile_version.minor,
        compile_version.patch);
printf("running with SDL_mixer version: %d.%d.%d\n",
        link_version->major,
        link_version->minor,
        link_version->patch);

See Also:
Mix_OpenAudio, Mix_QuerySpec

5.1.2 Mix_Init

int Mix_Init(int flags)

flags

bitwise OR’d set of sample/music formats to support by loading a library now. The values you may OR together to pass in are:
MIX_INIT_FLAC
MIX_INIT_MOD
MIX_INIT_MP3
MIX_INIT_OGG
MIX_INIT_MID
MIX_INIT_OPUS

Initialize by loading support as indicated by the flags, or at least return success if support is already loaded. You may call this multiple times, which will actually require you to call Mix_Quit just once to clean up. You may call this function with a 0 to retrieve whether support was built-in or not loaded yet.
Note: you can call Mix_Init with the right MIX_INIT_* flags OR’d together before you program gets busy, to prevent a later hiccup while it loads and unloads the library, and to check that you do have the support that you need before you try and use it.
Note: this function does not always set the error string, so do not depend on Mix_GetError being meaningful all the time.

Returns: a bitmask of all the currently initted sample/music loaders.

// load support for the OGG and MOD sample/music formats
int flags=MIX_INIT_OGG|MIX_INIT_MOD;
int initted=Mix_Init(flags);
if(initted&flags != flags) {
    printf("Mix_Init: Failed to init required ogg and mod support!\n");
    printf("Mix_Init: %s\n", Mix_GetError());
    // handle error
}

See Also:
Mix_Quit

5.1.3 Mix_Quit

void Mix_Quit()

This function cleans up all dynamically loaded library handles, freeing memory. If support is required again it will be initialized again, either by Mix_Init or loading a sample or some music with dynamic support required. You may call this function when Mix_Load functions are no longer needed for the MIX_INIT_* formats. You should call this function for each time Mix_Init was called, otherwise it may not free all the dynamic library resources until the program ends. This is done so that multiple unrelated modules of a program may call Mix_Init and Mix_Quit without affecting the others performance and needs.

// indicate that we are ready to unload the dynamically loaded libraries
Mix_Quit();

NOTE: Since each call to Mix_Init may set different flags, there is no way, currently, to request how many times each one was initted. In other words, the only way to quit for sure is to do a loop like so:

// force a quit
while(Mix_Init(0))
    Mix_Quit();

See Also:
Mix_Init

5.1.4 Mix_OpenAudio

int Mix_OpenAudio(int frequency, Uint16 format, int channels, int chunksize)

frequency

Output sampling frequency in samples per second (Hz).
you might use MIX_DEFAULT_FREQUENCY(44100) since that is a good value for most games.

format

Output sample format.

channels

Number of sound channels in output.
Set to 2 for stereo, 1 for mono. This has nothing to do with mixing channels.

chunksize

Bytes used per output sample.

Initialize the mixer API.
This must be called before using other functions in this library.
SDL must be initialized with SDL_INIT_AUDIO before this call. frequency would be 44100 for 44.1KHz, which is CD audio rate. Some games use 22050, because 44100 requires too much CPU power on very old computers. chunksize is the size of each mixed sample. The smaller this is the more your hooks will be called. If make this too small on a slow system, sound may skip. If made to large, sound effects will lag behind the action more. You want a happy medium for your target computer. You also may make this 4096, or larger, if you are just playing music. MIX_CHANNELS(8) mixing channels will be allocated by default. You may call this function multiple times, however you will have to call Mix_CloseAudio just as many times for the device to actually close. The format will not changed on subsequent calls until fully closed. So you will have to close all the way before trying to open with different format parameters.

format is based on SDL audio support, see SDL_audio.h. Here are the values listed there:

AUDIO_U8

Unsigned 8-bit samples

AUDIO_S8

Signed 8-bit samples

AUDIO_U16LSB

Unsigned 16-bit samples, in little-endian byte order

AUDIO_S16LSB

Signed 16-bit samples, in little-endian byte order

AUDIO_U16MSB

Unsigned 16-bit samples, in big-endian byte order

AUDIO_S16MSB

Signed 16-bit samples, in big-endian byte order

AUDIO_U16

same as AUDIO_U16LSB (for backwards compatability probably)

AUDIO_S16

same as AUDIO_S16LSB (for backwards compatability probably)

AUDIO_U16SYS

Unsigned 16-bit samples, in system byte order

AUDIO_S16SYS

Signed 16-bit samples, in system byte order

AUDIO_S32LSB

Signed 32-bit samples, in little-endian byte order

AUDIO_S32MSB

Signed 32-bit samples, in bin-endian byte order

AUDIO_S32

same as AUDIO_S32LSB (for backwards compatability probably)

AUDIO_S32SYS

Signed 32-bit samples, in system byte order

AUDIO_F32LSB

Floating 32-bit samples, in little-endian byte order

AUDIO_F32MSB

Floating 32-bit samples, in big-endian byte order

AUDIO_F32

same as AUDIO_F32LSB (for backwards compatability probably)

AUDIO_F32SYS

Signed 32-bit float samples, in system byte order

MIX_DEFAULT_FORMAT is the same as AUDIO_S16SYS.

Returns: 0 on success, -1 on errors

// start SDL with audio support
if(SDL_Init(SDL_INIT_AUDIO)==-1) {
    printf("SDL_Init: %s\n", SDL_GetError());
    exit(1);
}
// open 44.1KHz, signed 16bit, system byte order,
//      stereo audio, using 1024 byte chunks
if(Mix_OpenAudio(44100, MIX_DEFAULT_FORMAT, 2, 1024)==-1) {
    printf("Mix_OpenAudio: %s\n", Mix_GetError());
    exit(2);
}

See Also:
Mix_OpenAudioDevice, Mix_CloseAudio, Mix_PauseAudio, Mix_QuerySpec, Mix_AllocateChannels, Mix_OpenAudioDevice

5.1.5 Mix_OpenAudioDevice

int Mix_OpenAudioDevice(int frequency, Uint16 format, int channels, int chunksize, const char* device, int allowed_changes)

frequency

Output sampling frequency in samples per second (Hz).
you might use MIX_DEFAULT_FREQUENCY(44100) since that is a good value for most games.

format

Output sample format. See Mix_OpenAudio for the table of available formats.

channels

Number of sound channels in output.
Set to 2 for stereo, 1 for mono. This has nothing to do with mixing channels.

chunksize

Bytes used per output sample.

device

A UTF-8 string reported by SDL_GetAudioDeviceName() or a driver-specific name as appropriate. NULL requests the most reasonable default device.

allowed_changes

0, or one or more flags OR’d together.

Initialize the mixer API.
This must be called before using other functions in this library.
SDL must be initialized with SDL_INIT_AUDIO before this call. frequency would be 44100 for 44.1KHz, which is CD audio rate. Some games use 22050, because 44100 requires too much CPU power on very old computers. chunksize is the size of each mixed sample. The smaller this is the more your hooks will be called. If make this too small on a slow system, sound may skip. If made to large, sound effects will lag behind the action more. You want a happy medium for your target computer. You also may make this 4096, or larger, if you are just playing music. MIX_CHANNELS(8) mixing channels will be allocated by default. You may call this function multiple times, however you will have to call Mix_CloseAudio just as many times for the device to actually close. The format will not changed on subsequent calls until fully closed. So you will have to close all the way before trying to open with different format parameters.

Returns: 0 on success, -1 on errors

// start SDL with audio support
if(SDL_Init(SDL_INIT_AUDIO)==-1) {
    printf("SDL_Init: %s\n", SDL_GetError());
    exit(1);
}
// open 44.1KHz, signed 16bit, system byte order,
//      stereo audio, using 1024 byte chunks
if(Mix_OpenAudioDevice(44100, MIX_DEFAULT_FORMAT, 2, 1024, NULL,
                        SDL_AUDIO_ALLOW_FREQUENCY_CHANGE |
                        SDL_AUDIO_ALLOW_CHANNELS_CHANGE)==-1) {
    printf("Mix_OpenAudioDevice: %s\n", Mix_GetError());
    exit(2);
}

See Also:
Mix_OpenAudio, Mix_CloseAudio, Mix_PauseAudio, Mix_QuerySpec, Mix_AllocateChannels, Mix_OpenAudio

5.1.6 Mix_PauseAudio

void Mix_PauseAudio(int pause_on)

Pauses or resume the whole audio processing: all playing music and channels will get paused synchroniously.

pause_on

1 pauses the whole audio processing, 0 resumes the audio processing back.

See Also:
Mix_OpenAudio, Mix_OpenAudioDevice, Mix_CloseAudio, Mix_QuerySpec, Mix_AllocateChannels, Mix_OpenAudio

5.1.7 Mix_CloseAudio

void Mix_CloseAudio()

Shutdown and cleanup the mixer API.
After calling this all audio is stopped, the device is closed, and the SDL_mixer functions should not be used. You may, of course, use Mix_OpenAudio to start the functionality again.
Note: This function doesn’t do anything until you have called it the same number of times that you called Mix_OpenAudio. You may use Mix_QuerySpec to find out how many times Mix_CloseAudio needs to be called before the device is actually closed.

Mix_CloseAudio();
// you could SDL_Quit(); here...or not.

See Also:
Mix_OpenAudio, Mix_OpenAudioDevice, Mix_QuerySpec, Mix_PauseAudio,

5.1.8 Mix_InitMixer

void Mix_InitMixer(const SDL_AudioSpec *spec, SDL_bool skip_init_check)

spec

The audio spec such as frequency, sample format, number of channels, and desired chunk size, using the SDL_AudioSpec structure.

skip_init_check

Disable the internal check of the initialization state.

Initialize the mixer API without starting the audio processing. That means, you can make your own audio processing and manually run the mixer API by using callbacks you may retrieve using Mix_GetGeneralMixer, Mix_GetMusicMixer, and Mix_GetMultiMusicMixer calls.

CAUTION: Don’t even try to call this function and any of mixer callback if you initialized the mixer using Mix_OpenAudio or Mix_OpenAudioDevice calls.

See Also:
Mix_GetMusicMixer, Mix_GetMultiMusicMixer, Mix_GetGeneralMixer, Mix_FreeMixer

5.1.9 Mix_GetMusicMixer

Mix_CommonMixer_t Mix_GetMusicMixer()

Returns: The mixer callback to process the single-stream music.

Get the callback to process the single-stream music out of the main process of mixer API and receive the output of currently playing single-stream music. To receive the multi-stream music output use the Mix_GetMultiMusicMixer callback.

CAUTION: Don’t even try to call the returned callback if you initialized the mixer using Mix_OpenAudio or Mix_OpenAudioDevice calls.

See Also:
Mix_InitMixer, Mix_GetMultiMusicMixer, Mix_GetGeneralMixer, Mix_FreeMixer

5.1.10 Mix_GetMultiMusicMixer

Mix_CommonMixer_t Mix_GetMultiMusicMixer()

Returns: The mixer callback to process the multi-stream music.

Get the callback to process the single-stream music out of the main process of mixer API and receive the output of all music streams except the single-stream music. To receive the single-stream music output use the Mix_GetMusicMixer callback.

CAUTION: Don’t even try to call the returned callback if you initialized the mixer using Mix_OpenAudio or Mix_OpenAudioDevice calls.

See Also:
Mix_InitMixer, Mix_GetMusicMixer, Mix_GetGeneralMixer, Mix_FreeMixer

5.1.11 Mix_GetGeneralMixer

Mix_CommonMixer_t Mix_GetMultiMusicMixer()

Returns: The mixer callback to process the general mixer API.

Get the callback to process the general Mixer API out of the main process of mixer API and receive the generated output of all playing music streams and channels.

CAUTION 1: Don’t even try to call the returned callback if you initialized the mixer using Mix_OpenAudio or Mix_OpenAudioDevice calls.

CAUTION 2: Once you execute the callback returned by Mix_GetGeneralMixer()), callbacks returned by Mix_GetMusicMixer() and Mix_GetMultiMusicMixer() were already processed internally. You don’t need to call them at all.

See Also:
Mix_InitMixer, Mix_GetMusicMixer, Mix_GetMultiMusicMixer, Mix_FreeMixer

5.1.12 Mix_FreeMixer

void Mix_FreeMixer()

Shutdown and cleanup the mixer API.
Use this call in only condition you initialized the mixer API using the Mix_InitMixer call.

CAUTION: Don’t even try to call this function and any of mixer callback if you initialized the mixer using Mix_OpenAudio or Mix_OpenAudioDevice calls.

See Also:
Mix_InitMixer, Mix_GetMusicMixer, Mix_GetMultiMusicMixer, Mix_GetGeneralMixer

5.1.13 Mix_SetError

void Mix_SetError(const char *fmt, ...)

This is the same as SDL_SetError, which sets the error string which may be fetched with Mix_GetError (or SDL_GetError). This functions acts like printf, except that it is limited to SDL_ERRBUFIZE(1024) chars in length. It only accepts the following format types: %s, %d, %f, %p. No variations are supported, like %.2f would not work. For any more specifics read the SDL docs.

int mymixfunc(int i) {
    Mix_SetError("mymixfunc is not implemented! %d was passed in.",i);
    return(-1);
}

See Also:
Mix_GetError

5.1.14 Mix_GetError

char *Mix_GetError()

This is the same as SDL_GetError, which returns the last error set as a string which you may use to tell the user what happened when an error status has been returned from an SDL_mixer function call.

Returns: a char pointer (string) containing a humam readble version or the reason for the last error that occured.

printf("Oh My Goodness, an error : %s", Mix_GetError());

See Also:
Mix_SetError

5.1.15 Mix_QuerySpec

int Mix_QuerySpec(int *frequency, Uint16 *format, int *channels)

frequency

A pointer to an int where the frequency actually used by the opened audio device will be stored.

format

A pointer to a Uint16 where the output format actually being used by the audio device will be stored.

channels

A pointer to an int where the number of audio channels will be stored.
2 will mean stereo, 1 will mean mono.

Get the actual audio format in use by the opened audio device. This may or may not match the parameters you passed to Mix_OpenAudio.

Returns: 0 on error. If the device was open the number of times it was opened will be returned. The values of the arguments variables are not set on an error.

// get and print the audio format in use
int numtimesopened, frequency, channels;
Uint16 format;
numtimesopened=Mix_QuerySpec(&frequency, &format, &channels);
if(!numtimesopened) {
    printf("Mix_QuerySpec: %s\n",Mix_GetError());
}
else {
    char *format_str="Unknown";
    switch(format) {
        case AUDIO_U8: format_str="U8"; break;
        case AUDIO_S8: format_str="S8"; break;
        case AUDIO_U16LSB: format_str="U16LSB"; break;
        case AUDIO_S16LSB: format_str="S16LSB"; break;
        case AUDIO_U16MSB: format_str="U16MSB"; break;
        case AUDIO_S16MSB: format_str="S16MSB"; break;
        case AUDIO_S32LSB: format_str="S32LSB"; break;
        case AUDIO_S32MSB: format_str="S32MSB"; break;
        case AUDIO_F32LSB: format_str="F32LSB"; break;
        case AUDIO_F32MSB: format_str="F32MSB"; break;
    }
    printf("opened=%d times  frequency=%dHz  format=%s  channels=%d",
            numtimesopened, frequency, format_str, channels);
}

See Also:
Mix_OpenAudio

5.2 Samples

These functions work with Mix_Chunk samples.

Loading

Settings

Freeing

5.2.1 Mix_GetNumChunkDecoders

int Mix_GetNumChunkDecoders()

Get the number of sample chunk decoders available from the Mix_GetChunkDecoder function. This number can be different for each run of a program, due to the change in availability of shared libraries that support each format.

Returns: The number of sample chunk decoders available.

// print the number of sample chunk decoders available
printf("There are %d sample chunk deocoders available\n", Mix_GetNumChunkDecoders());

See Also:
Mix_GetNumMusicDecoders, Mix_GetChunkDecoder, Mix_HasChunkDecoder, Mix_LoadWAV

5.2.2 Mix_GetChunkDecoder

const char *Mix_GetChunkDecoder(int index)

index

The index number of sample chunk decoder to get.
In the range from 0(zero) to Mix_GetNumChunkDecoders()-1, inclusive.

Get the name of the indexed sample chunk decoder. You need to get the number of sample chunk decoders available using the Mix_GetNumChunkDecoders function.

Returns: The name of the indexed sample chunk decoder. This string is owned by the SDL_mixer library, do not modify or free it. It is valid until you call Mix_CloseAudio the final time.

// print sample chunk decoders available
int i,max=Mix_GetNumChunkDecoders();
for(i=0; i<max; ++i)
	printf("Sample chunk decoder %d is for %s",Mix_GetChunkDecoder(i));

See Also:
Mix_GetNumChunkDecoders, Mix_GetMusicDecoder, Mix_HasChunkDecoder, Mix_LoadWAV

5.2.3 Mix_HasChunkDecoder

SDL_bool Mix_HasChunkDecoder(const char *name)

name

The decoder name to check it’s presence.

Check if the sample chunk decoder named as name presented in this library build.

Returns: SDL_TRUE if the requested codec name is available in this library build or SDL_FALSE if not.

See Also:
Mix_GetNumChunkDecoders, Mix_GetChunkDecoder, Mix_GetMusicDecoder, Mix_LoadWAV

5.2.4 Mix_LoadWAV

Mix_Chunk *Mix_LoadWAV(char *file)

file

File name to load sample from.

Load file for use as a sample. This is actually Mix_LoadWAV_RW(SDL_RWFromFile(file, "rb"), 1). This can load WAVE, AIFF, RIFF, OGG, FLAC, MP3, and VOC files.
Note: You must call SDL_OpenAudio before this. It must know the output characteristics so it can convert the sample for playback, it does this conversion at load time.

Returns: a pointer to the sample as a Mix_Chunk. NULL is returned on errors.

// load sample.wav in to sample
Mix_Chunk *sample;
sample=Mix_LoadWAV("sample.wav");
if(!sample) {
    printf("Mix_LoadWAV: %s\n", Mix_GetError());
    // handle error
}

See Also:
Mix_LoadWAV_RW, Mix_QuickLoad_WAV, Mix_FreeChunk

5.2.5 Mix_LoadWAV_RW

Mix_Chunk *Mix_LoadWAV_RW(SDL_RWops *src, int freesrc)

src

The source SDL_RWops as a pointer. The sample is loaded from this.

freesrc

A non-zero value mean is will automatically close/free the src for you.

Load src for use as a sample. This can load WAVE, AIFF, RIFF, OGG, FLAC, MP3, and VOC formats. Using SDL_RWops is not covered here, but they enable you to load from almost any source. Note: You must call SDL_OpenAudio before this. It must know the output characteristics so it can convert the sample for playback, it does this conversion at load time.

Returns: a pointer to the sample as a Mix_Chunk. NULL is returned on errors.

// load sample.wav in to sample
Mix_Chunk *sample;
sample=Mix_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1);
if(!sample) {
    printf("Mix_LoadWAV_RW: %s\n", Mix_GetError());
    // handle error
}

See Also:
Mix_LoadWAV, Mix_QuickLoad_WAV, Mix_FreeChunk

5.2.6 Mix_QuickLoad_WAV

Mix_Chunk *Mix_QuickLoad_WAV(Uint8 *mem)

mem

Memory buffer containing a WAVE file in output format.

Load mem as a WAVE/RIFF file into a new sample. The WAVE in mem must be already in the output format. It would be better to use Mix_LoadWAV_RW if you aren’t sure.
Note: This function does very little checking. If the format mismatches the output format, or if the buffer is not a WAVE, it will not return an error. This is probably a dangerous function to use.

Returns: a pointer to the sample as a Mix_Chunk. NULL is returned on errors.

// quick-load a wave from memory
// Uint8 *wave; // I assume you have the wave loaded raw,
                // or compiled in the program...
Mix_Chunk *wave_chunk;
if(!(wave_chunk=Mix_QuickLoad_WAV(wave))) {
    printf("Mix_QuickLoad_WAV: %s\n", Mix_GetError());
    // handle error
}

See Also:
Mix_LoadWAV, Mix_QuickLoad_RAW, Mix_FreeChunk

5.2.7 Mix_QuickLoad_RAW

Mix_Chunk *Mix_QuickLoad_RAW(Uint8 *mem)

mem

Memory buffer containing a WAVE file in output format.

Load mem as a raw sample. The data in mem must be already in the output format. If you aren’t sure what you are doing, this is not a good function for you!
Note: This function does very little checking. If the format mismatches the output format it will not return an error. This is probably a dangerous function to use.

Returns: a pointer to the sample as a Mix_Chunk. NULL is returned on errors, such as when out of memory.

// quick-load a raw sample from memory
// Uint8 *raw; // I assume you have the raw data here,
                // or compiled in the program...
Mix_Chunk *raw_chunk;
if(!(raw_chunk=Mix_QuickLoad_RAW(raw))) {
    printf("Mix_QuickLoad_RAW: %s\n", Mix_GetError());
    // handle error
}

See Also:
Mix_LoadWAV, Mix_QuickLoad_WAV, Mix_FreeChunk

5.2.8 Mix_VolumeChunk

int Mix_VolumeChunk(Mix_Chunk *chunk, int volume)

chunk

Pointer to the Mix_Chunk to set the volume in.

volume

The volume to use from 0 to MIX_MAX_VOLUME(128).
If greater than MIX_MAX_VOLUME,
then it will be set to MIX_MAX_VOLUME.
If less than 0 then chunk->volume will not be set.

Set chunk->volume to volume.
The volume setting will take effect when the chunk is used on a channel, being mixed into the output.

Returns: previous chunk->volume setting. if you passed a negative value for volume then this volume is still the current volume for the chunk.

// set the sample's volume to 1/2
// Mix_Chunk *sample;
int previous_volume;
previous_volume=Mix_VolumeChunk(sample, MIX_MAX_VOLUME/2);
printf("previous_volume: %d\n", previous_volume);

See Also:
Mix_Chunk

5.2.9 Mix_FreeChunk

void Mix_FreeChunk(Mix_Chunk *chunk)

chunk

Pointer to the Mix_Chunk to free.

Free the memory used in chunk, and free chunk itself as well. Do not use chunk after this without loading a new sample to it. Note: It’s a bad idea to free a chunk that is still being played...

// free the sample
// Mix_Chunk *sample;
Mix_FreeChunk(sample);
sample=NULL; // to be safe...

See Also:
Mix_LoadWAV, Mix_LoadWAV_RW, Mix_QuickLoad_WAV,

5.3 Channels

These functions work with sound effect mixer channels. Music is not affected by these functions.

Setup

Playing

Pausing

Stopping

Info

5.3.1 Mix_AllocateChannels

int Mix_AllocateChannels(int numchans)

numchans

Number of channels to allocate for mixing.
A negative number will not do anything, it will tell you how many channels are currently allocated.

Set the number of channels being mixed. This can be called multiple times, even with sounds playing. If numchans is less than the current number of channels, then the higher channels will be stopped, freed, and therefore not mixed any longer. It’s probably not a good idea to change the size 1000 times a second though.
If any channels are deallocated, any callback set by Mix_ChannelFinished will be called when each channel is halted to be freed. Note: passing in zero WILL free all mixing channels, however music will still play.

Returns: The number of channels allocated. Never fails...but a high number of channels can segfault if you run out of memory. We’re talking REALLY high!

// allocate 16 mixing channels
Mix_AllocateChannels(16);

See Also:
Mix_OpenAudio

5.3.2 Mix_Volume

int Mix_Volume(int channel, int volume)

channel

Channel to set mix volume for.
-1 will set the volume for all allocated channels.

volume

The volume to use from 0 to MIX_MAX_VOLUME(128).
If greater than MIX_MAX_VOLUME,
then it will be set to MIX_MAX_VOLUME.
If less than 0 then the volume will not be set.

Set the volume for any allocated channel. If channel is -1 then all channels at are set at once. The volume is applied during the final mix, along with the sample volume. So setting this volume to 64 will halve the output of all samples played on the specified channel. All channels default to a volume of 128, which is the max. Newly allocated channels will have the max volume set, so setting all channels volumes does not affect subsequent channel allocations.

Returns: current volume of the channel. If channel is -1, the average volume is returned.

// set channel 1 to half volume
Mix_Volume(1,MIX_MAX_VOLUME/2);

// print the average volume
printf("Average volume is %d\n",Mix_Volume(-1,-1));

See Also:
Mix_VolumeChunk, Mix_VolumeMusic, Mix_VolumeMusicStream

5.3.3 Mix_MasterVolume

int Mix_MasterVolume(int *volume)

Set the master volume for all channels.

SDL_mixer keeps a per-channel volume, a per-chunk volume, and a master volume, and considers all three when mixing audio. This function sets the master volume, which is applied to all playing channels when mixing.

The volume must be between 0 (silence) and MIX_MAX_VOLUME (full volume). Note that MIX_MAX_VOLUME is 128. Values greater than MIX_MAX_VOLUME are clamped to MIX_MAX_VOLUME.

Specifying a negative volume will not change the current volume; as such, this can be used to query the current volume without making changes, as this function returns the previous (in this case, still-current) value.

Note: that the master volume does not affect any playing music; it is only applied when mixing chunks. Use Mix_VolumeMusicStream() for that.

volume

The new volume, between 0 and MIX_MAX_VOLUME, or -1 to query.

Returns: The previous volume. If the specified volume is -1, this returns the current volume.

See Also:
Mix_Volume, Mix_VolumeChunk, Mix_VolumeMusic, Mix_VolumeMusicStream

5.3.4 Mix_PlayChannel

int Mix_PlayChannel(int channel, Mix_Chunk *chunk, int loops)

channel

Channel to play on, or -1 for the first free unreserved channel.

chunk

Sample to play.

loops

Number of loops, -1 is infinite loops.
Passing one here plays the sample twice (1 loop).

Play chunk on channel, or if channel is -1, pick the first free unreserved channel. The sample will play for loops+1 number of times, unless stopped by halt, or fade out, or setting a new expiration time of less time than it would have originally taken to play the loops, or closing the mixer.
Note: this just calls Mix_PlayChannelTimed() with ticks set to -1.

Returns: the channel the sample is played on. On any errors, -1 is returned.

// play sample on first free unreserved channel
// play it exactly once through
// Mix_Chunk *sample; //previously loaded
if(Mix_PlayChannel(-1, sample, 0)==-1) {
    printf("Mix_PlayChannel: %s\n",Mix_GetError());
    // may be critical error, or maybe just no channels were free.
    // you could allocated another channel in that case...
}

See Also:
Mix_PlayChannelTimed, Mix_PlayChannelVol, Mix_PlayChannelTimedVolume, Mix_FadeInChannel, Mix_FadeInChannelTimed, Mix_FadeInChannelVolume, Mix_FadeInChannelTimedVolume, Mix_HaltChannel, Mix_ExpireChannel, Mix_ReserveChannels

5.3.5 Mix_PlayChannelTimed

int Mix_PlayChannelTimed(int channel, Mix_Chunk *chunk, int loops, int ticks)

channel

Channel to play on, or -1 for the first free unreserved channel.

chunk

Sample to play.

loops

Number of loops, -1 is infinite loops.
Passing one here plays the sample twice (1 loop).

ticks

Millisecond limit to play sample, at most.
If not enough loops or the sample chunk is not long enough, then the sample may stop before this timeout occurs.
-1 means play forever.

If the sample is long enough and has enough loops then the sample will stop after ticks milliseconds. Otherwise this function is the same as Mix_PlayChannel.

Returns: the channel the sample is played on. On any errors, -1 is returned.

// play sample on first free unreserved channel
// play it for half a second
// Mix_Chunk *sample; //previously loaded
if(Mix_PlayChannelTimed(-1, sample, -1 , 500)==-1) {
    printf("Mix_PlayChannel: %s\n",Mix_GetError());
    // may be critical error, or maybe just no channels were free.
    // you could allocated another channel in that case...
}

See Also:
Mix_PlayChannel, Mix_PlayChannelVol, Mix_PlayChannelTimedVolume, Mix_FadeInChannelTimed, Mix_FadeInChannelVolume, Mix_FadeInChannelTimedVolume, Mix_FadeOutChannel, Mix_ReserveChannels

5.3.6 Mix_PlayChannelVol

int Mix_PlayChannelVol(int channel, Mix_Chunk *chunk, int loops, int vol)

channel

Channel to play on, or -1 for the first free unreserved channel.

chunk

Sample to play.

loops

Number of loops, -1 is infinite loops.
Passing one here plays the sample twice (1 loop).

vol

Initial volume level between 0 and MIX_MAX_VOLUME

Play chunk on channel, or if channel is -1, pick the first free unreserved channel. The vol will set initial channel volume. The sample will play for loops+1 number of times, unless stopped by halt, or fade out, or setting a new expiration time of less time than it would have originally taken to play the loops, or closing the mixer.
Note: this just calls Mix_PlayChannelTimed() with ticks set to -1.

Returns: the channel the sample is played on. On any errors, -1 is returned.

// play sample on first free unreserved channel
// play it exactly once through
// Mix_Chunk *sample; //previously loaded
if(Mix_PlayChannelVol(-1, sample, 0, 56)==-1) {
    printf("Mix_PlayChannelVol: %s\n",Mix_GetError());
    // may be critical error, or maybe just no channels were free.
    // you could allocated another channel in that case...
}

See Also:
Mix_PlayChannel, Mix_PlayChannelTimed, Mix_PlayChannelTimedVolume, Mix_FadeInChannel, Mix_FadeInChannelTimed, Mix_FadeInChannelVolume, Mix_FadeInChannelTimedVolume, Mix_HaltChannel, Mix_ExpireChannel, Mix_ReserveChannels

5.3.7 Mix_PlayChannelTimedVolume

int Mix_PlayChannelTimedVolume(int channel, Mix_Chunk *chunk, int loops, int ticks)

channel

Channel to play on, or -1 for the first free unreserved channel.

chunk

Sample to play.

loops

Number of loops, -1 is infinite loops.
Passing one here plays the sample twice (1 loop).

ticks

Millisecond limit to play sample, at most.
If not enough loops or the sample chunk is not long enough, then the sample may stop before this timeout occurs.
-1 means play forever.

vol

Initial volume level between 0 and MIX_MAX_VOLUME

If the sample is long enough and has enough loops then the sample will stop after ticks milliseconds. Otherwise this function is the same as Mix_PlayChannelVol.

Returns: the channel the sample is played on. On any errors, -1 is returned.

// play sample on first free unreserved channel
// play it for half a second
// Mix_Chunk *sample; //previously loaded
if(Mix_PlayChannelTimedVolume(-1, sample, -1 , 500, 80)==-1) {
    printf("Mix_PlayChannel: %s\n",Mix_GetError());
    // may be critical error, or maybe just no channels were free.
    // you could allocated another channel in that case...
}

See Also:
Mix_PlayChannel, Mix_PlayChannelVol, Mix_FadeInChannelTimed, Mix_FadeInChannelVolume, Mix_FadeInChannelTimedVolume, Mix_FadeOutChannel, Mix_ReserveChannels

5.3.8 Mix_FadeInChannel

int Mix_FadeInChannel(int channel, Mix_Chunk *chunk, int loops, int ms)

channel

Channel to play on, or -1 for the first free unreserved channel.

chunk

Sample to play.

loops

Number of loops, -1 is infinite loops.
Passing one here plays the sample twice (1 loop).

ms

Milliseconds of time that the fade-in effect should take to go from silence to full volume.

Play chunk on channel, or if channel is -1, pick the first free unreserved channel.
The channel volume starts at 0 and fades up to full volume over ms milliseconds of time. The sample may end before the fade-in is complete if it is too short or doesn’t have enough loops. The sample will play for loops+1 number of times, unless stopped by halt, or fade out, or setting a new expiration time of less time than it would have originally taken to play the loops, or closing the mixer.
Note: this just calls Mix_FadeInChannelTimed() with ticks set to -1.

Returns: the channel the sample is played on. On any errors, -1 is returned.

// play sample on first free unreserved channel
// play it exactly 3 times through
// fade in over one second
// Mix_Chunk *sample; //previously loaded
if(Mix_FadeInChannel(-1, sample, 2, 1000)==-1) {
    printf("Mix_FadeInChannel: %s\n",Mix_GetError());
    // may be critical error, or maybe just no channels were free.
    // you could allocated another channel in that case...
}

See Also:
Mix_PlayChannel, Mix_PlayChannelVol, Mix_PlayChannelTimedVolume, Mix_FadeInChannelTimed, Mix_FadeInChannelVolume, Mix_FadeInChannelTimedVolume, Mix_FadingChannel, Mix_FadeOutChannel, Mix_ReserveChannels

5.3.9 Mix_FadeInChannelTimed

int Mix_FadeInChannelTimed(int channel, Mix_Chunk *chunk,
                           int loops, int ms, int ticks)

channel

Channel to play on, or -1 for the first free unreserved channel.

chunk

Sample to play.

loops

Number of loops, -1 is infinite loops.
Passing one here plays the sample twice (1 loop).

ms

Milliseconds of time that the fade-in effect should take to go from silence to full volume.

ticks

Millisecond limit to play sample, at most.
If not enough loops or the sample chunk is not long enough, then the sample may stop before this timeout occurs.
-1 means play forever.

If the sample is long enough and has enough loops then the sample will stop after ticks milliseconds. Otherwise this function is the same as Mix_FadeInChannel.

Returns: the channel the sample is played on. On any errors, -1 is returned.

// play sample on first free unreserved channel
// play it for half a second
// Mix_Chunk *sample; //previously loaded
if(Mix_PlayChannelTimed(-1, sample, -1 , 500)==-1) {
    printf("Mix_PlayChannel: %s\n",Mix_GetError());
    // may be critical error, or maybe just no channels were free.
    // you could allocated another channel in that case...
}

See Also:
Mix_PlayChannelTimed, Mix_PlayChannelVol, Mix_PlayChannelTimedVolume, Mix_FadeInChannel, Mix_FadeInChannelVolume, Mix_FadeInChannelTimedVolume, Mix_FadingChannel, Mix_HaltChannel, Mix_ExpireChannel, Mix_ReserveChannels

5.3.10 Mix_FadeInChannelVolume

int Mix_FadeInChannelVolume(int channel, Mix_Chunk *chunk, int loops, int ms, int vol)

channel

Channel to play on, or -1 for the first free unreserved channel.

chunk

Sample to play.

loops

Number of loops, -1 is infinite loops.
Passing one here plays the sample twice (1 loop).

ms

Milliseconds of time that the fade-in effect should take to go from silence to full volume.

vol

Initial volume level between 0 and MIX_MAX_VOLUME

Play chunk on channel, or if channel is -1, pick the first free unreserved channel.
The channel volume starts at 0 and fades up to full volume over ms milliseconds of time. The sample may end before the fade-in is complete if it is too short or doesn’t have enough loops. The sample will play for loops+1 number of times, unless stopped by halt, or fade out, or setting a new expiration time of less time than it would have originally taken to play the loops, or closing the mixer.
The vol will set initial channel volume. Note: this just calls Mix_FadeInChannelTimed() with ticks set to -1.

Returns: the channel the sample is played on. On any errors, -1 is returned.

// play sample on first free unreserved channel
// play it exactly 3 times through
// fade in over one second
// Mix_Chunk *sample; //previously loaded
if(Mix_FadeInChannelVolume(-1, sample, 2, 1000, 70)==-1) {
    printf("Mix_FadeInChannel: %s\n",Mix_GetError());
    // may be critical error, or maybe just no channels were free.
    // you could allocated another channel in that case...
}

See Also:
Mix_PlayChannel, Mix_PlayChannelVol, Mix_PlayChannelTimedVolume, Mix_FadeInChannelTimed, Mix_FadeInChannelTimedVolume, Mix_FadingChannel, Mix_FadeOutChannel, Mix_ReserveChannels

5.3.11 Mix_FadeInChannelTimedVolume

int Mix_FadeInChannelTimedVolume(int channel, Mix_Chunk *chunk,
                           int loops, int ms, int ticks, int vol)

channel

Channel to play on, or -1 for the first free unreserved channel.

chunk

Sample to play.

loops

Number of loops, -1 is infinite loops.
Passing one here plays the sample twice (1 loop).

ms

Milliseconds of time that the fade-in effect should take to go from silence to full volume.

ticks

Millisecond limit to play sample, at most.
If not enough loops or the sample chunk is not long enough, then the sample may stop before this timeout occurs.
-1 means play forever.

vol

Initial volume level between 0 and MIX_MAX_VOLUME

If the sample is long enough and has enough loops then the sample will stop after ticks milliseconds. Otherwise this function is the same as Mix_FadeInChannelVolume.

Returns: the channel the sample is played on. On any errors, -1 is returned.

// play sample on first free unreserved channel
// play it for half a second
// Mix_Chunk *sample; //previously loaded
if(Mix_FadeInChannelTimedVolume(-1, sample, -1 , 500, 78)==-1) {
    printf("Mix_PlayChannel: %s\n",Mix_GetError());
    // may be critical error, or maybe just no channels were free.
    // you could allocated another channel in that case...
}

See Also:
Mix_PlayChannelTimed, Mix_PlayChannelVol, Mix_PlayChannelTimedVolume, Mix_FadeInChannel, Mix_FadeInChannelTimed, Mix_FadeInChannelVolume, Mix_FadingChannel, Mix_HaltChannel, Mix_ExpireChannel, Mix_ReserveChannels

5.3.12 Mix_Pause

void Mix_Pause(int channel)

channel

Channel to pause on, or -1 for all channels.

Pause channel, or all playing channels if -1 is passed in. You may still halt a paused channel.
Note: Only channels which are actively playing will be paused.

// pause all sample playback
Mix_Pause(-1);

See Also:
Mix_Resume, Mix_Paused, Mix_HaltChannel

5.3.13 Mix_Resume

void Mix_Resume(int channel)

channel

Channel to resume playing, or -1 for all channels.

Unpause channel, or all playing and paused channels if -1 is passed in.

// resume playback on all previously active channels
Mix_Resume(-1);

See Also:
Mix_Pause, Mix_Paused

5.3.14 Mix_HaltChannel

int Mix_HaltChannel(int channel)

channel

Channel to stop playing, or -1 for all channels.

Halt channel playback, or all channels if -1 is passed in.
Any callback set by Mix_ChannelFinished will be called.

Returns: always returns zero. (kinda silly)

// halt playback on all channels
Mix_HaltChannel(-1);

See Also:
Mix_ExpireChannel, Mix_FadeOutChannel, Mix_ChannelFinished

5.3.15 Mix_ExpireChannel

int Mix_ExpireChannel(int channel, int ticks)

channel

Channel to stop playing, or -1 for all channels.

ticks

Millisecons until channel(s) halt playback.

Halt channel playback, or all channels if -1 is passed in, after ticks milliseconds. Any callback set by Mix_ChannelFinished will be called when the channel expires.

Returns: Number of channels set to expire. Whether or not they are active.

// halt playback on all channels in 2 seconds
Mix_ExpireChannel(-1, 2000);

See Also:
Mix_HaltChannel, Mix_FadeOutChannel, Mix_ChannelFinished

5.3.16 Mix_FadeOutChannel

int Mix_FadeOutChannel(int channel, int ms)

channel

Channel to fade out, or -1 to fade all channels out.

ms

Milliseconds of time that the fade-out effect should take to go to silence, starting now.

Gradually fade out which channel over ms milliseconds starting from now. The channel will be halted after the fade out is completed. Only channels that are playing are set to fade out, including paused channels. Any callback set by Mix_ChannelFinished will be called when the channel finishes fading out.

Returns: The number of channels set to fade out.

// fade out all channels to finish 3 seconds from now
printf("starting fade out of %d channels\n", Mix_FadeOutChannel(-1, 3000));

See Also:
Mix_FadeInChannel, Mix_FadeInChannelTimed, Mix_FadingChannel, Mix_ChannelFinished

5.3.17 Mix_ChannelFinished

void Mix_ChannelFinished(void (*channel_finished)(int channel))

channel_finished

Function to call when any channel finishes playback.

When channel playback is halted, then the specified channel_finished function is called. The channel parameter will contain the channel number that has finished.
NOTE: NEVER call SDL_Mixer functions, nor SDL_LockAudio, from a callback function.

// a simple channel_finished function
void channelDone(int channel) {
    printf("channel %d finished playback.\n",channel);
}

// make a channelDone function
void channelDone(int channel)
{
    printf("channel %d finished playing.\n", channel);
}
...
// set the callback for when a channel stops playing
Mix_ChannelFinished(channelDone);

See Also:
Mix_HaltChannel, Mix_ExpireChannel

5.3.18 Mix_Playing

int Mix_Playing(int channel)

channel

Channel to test whether it is playing or not.
-1 will tell you how many channels are playing.

Tells you if channel is playing, or not.
Note: Does not check if the channel has been paused.

Returns: Zero if the channel is not playing. Otherwise if you passed in -1, the number of channels playing is returned. If you passed in a specific channel, then 1 is returned if it is playing.

// check how many channels are playing samples
printf("%d channels are playing\n", Mix_Playing(-1));

See Also:
Mix_Paused, Mix_Fading, Mix_PlayChannel, Mix_Pause,

5.3.19 Mix_Paused

int Mix_Paused(int channel)

channel

Channel to test whether it is paused or not.
-1 will tell you how many channels are paused.

Tells you if channel is paused, or not.
Note: Does not check if the channel has been halted after it was paused, which may seem a little weird.

Returns: Zero if the channel is not paused. Otherwise if you passed in -1, the number of paused channels is returned. If you passed in a specific channel, then 1 is returned if it is paused.

// check the pause status on all channels
printf("%d channels are paused\n", Mix_Paused(-1));

See Also:
Mix_Playing, Mix_Pause, Mix_Resume

5.3.20 Mix_FadingChannel

Mix_Fading Mix_FadingChannel(int which)

which

Channel to get the fade activity status from.
-1 is not valid, and will probably crash the program.

Tells you if which channel is fading in, out, or not. Does not tell you if the channel is playing anything, or paused, so you’d need to test that separately.

Returns: the fading status. Never returns an error.

// check the fade status on channel 0
switch(Mix_FadingChannel(0)) {
    case MIX_NO_FADING:
        printf("Not fading.\n");
        break;
    case MIX_FADING_OUT:
        printf("Fading out.\n");
        break;
    case MIX_FADING_IN:
        printf("Fading in.\n");
        break;
}

See Also:
Mix_Fading, Mix_Playing, Mix_Paused, Mix_FadeInChannel, Mix_FadeInChannelTimed, Mix_FadeOutChannel

5.3.21 Mix_GetChunk

Mix_Chunk *Mix_GetChunk(int channel)

channel

Channel to get the current Mix_Chunk playing.
-1 is not valid, but will not crash the program.

Get the most recent sample chunk pointer played on channel. This pointer may be currently playing, or just the last used.
Note: The actual chunk may have been freed, so this pointer may not be valid anymore.

Returns: Pointer to the Mix_Chunk. NULL is returned if the channel is not allocated, or if the channel has not played any samples yet.

// get the last chunk used by channel 0
printf("Mix_Chunk* last in use on channel 0 was: %08p\n", Mix_GetChunk(0));

See Also:
Mix_Chunk, Mix_Playing

5.4 Groups

These functions work with groupings of mixer channels.

The default group tag number of -1, which refers to ALL channels.

Setup

TODO

Info

Stopping

5.4.1 Mix_ReserveChannels

int Mix_ReserveChannels(int num)

num

Number of channels to reserve from default mixing.
Zero removes all reservations.

Reserve num channels from being used when playing samples when passing in -1 as a channel number to playback functions. The channels are reserved starting from channel 0 to num-1. Passing in zero will unreserve all channels. Normally SDL_mixer starts without any channels reserved.

The following functions are affected by this setting:
Mix_PlayChannel
Mix_PlayChannelTimed
Mix_FadeInChannel
Mix_FadeInChannelTimed

Returns: The number of channels reserved. Never fails, but may return less channels than you ask for, depending on the number of channels previously allocated.

// reserve the first 8 mixing channels
int reserved_count;
reserved_count=Mix_ReserveChannels(8);
if(reserved_count!=8) {
    printf("reserved %d channels from default mixing.\n",reserved_count);
    printf("8 channels were not reserved!\n");
    // this might be a critical error...
}

See Also:
Mix_AllocateChannels

5.4.2 Mix_GroupChannel

int Mix_GroupChannel(int which, int tag)

which

Channel number of channels to assign tag to.

tag

A group number Any positive numbers (including zero).
-1 is the default group. Use -1 to remove a group tag essentially.

Add which channel to group tag, or reset it’s group to the default group tag (-1).

Returns: True(1) on success. False(0) is returned when the channel specified is invalid.

// add channel 0 to group 1
if(!Mix_GroupChannel(0,1)) {
    // bad channel, apparently channel 1 isn't allocated
}

See Also:
Mix_GroupChannels, Mix_AllocateChannels

5.4.3 Mix_GroupChannels

int Mix_GroupChannels(int from, int to, int tag)

from

First Channel number of channels to assign tag to. Must be less or equal to to.

to

Last Channel number of channels to assign tag to. Must be greater or equal to from.

tag

A group number. Any positive numbers (including zero).
-1 is the default group. Use -1 to remove a group tag essentially.

Add channels starting at from up through to to group tag, or reset it’s group to the default group tag (-1).

Returns: The number of tagged channels on success. If that number is less than to-from+1 then some channels were no tagged because they didn’t exist.

// add channels 0 through 7 to group 1
if(Mix_GroupChannels(0,7,1)!=8) {
    // some bad channels, apparently some channels aren't allocated
}

See Also:
Mix_GroupChannel, Mix_AllocateChannels

5.4.4 Mix_GroupCount

int Mix_GroupCount(int tag)

tag

A group number Any positive numbers (including zero).
-1 will count ALL channels.

Count the number of channels in group tag.

Returns: The number of channels found in the group. This function never fails.

// count the number of channels in group 1
printf("There are %d channels in group 1\n", Mix_GroupCount(1));

See Also:
Mix_GroupChannel, Mix_GroupChannels

5.4.5 Mix_GroupAvailable

int Mix_GroupAvailable(int tag)

tag

A group number Any positive numbers (including zero).
-1 will search ALL channels.

Find the first available (not playing) channel in group tag.

Returns: The channel found on success. -1 is returned when no channels in the group are available.

// find the first available channel in group 1
int channel;
channel=Mix_GroupAvailable(1);
if (channel==-1) {
    // no channel available...
    // perhaps search for oldest or newest channel in use...
}

See Also:
Mix_GroupOldest, Mix_GroupNewer, Mix_GroupChannel, Mix_GroupChannels

5.4.6 Mix_GroupOldest

int Mix_GroupOldest(int tag)

tag

A group number Any positive numbers (including zero).
-1 will search ALL channels.

Find the oldest actively playing channel in group tag.

Returns: The channel found on success. -1 is returned when no channels in the group are playing or the group is empty.

// find the oldest playing channel in group 1
int channel;
channel=Mix_GroupOldest(1);
if (channel==-1) {
    // no channel playing or allocated...
    // perhaps just search for an available channel...
}

See Also:
Mix_GroupNewer, Mix_GroupAvailable, Mix_GroupChannel, Mix_GroupChannels

5.4.7 Mix_GroupNewer

int Mix_GroupNewer(int tag)

tag

A group number Any positive numbers (including zero).
-1 will search ALL channels.

Find the newest, most recently started, actively playing channel in group tag.

Returns: The channel found on success. -1 is returned when no channels in the group are playing or the group is empty.

// find the newest playing channel in group 1
int channel;
channel=Mix_GroupNewer(1);
if (channel==-1) {
    // no channel playing or allocated...
    // perhaps just search for an available channel...
}

See Also:
Mix_GroupOldest, Mix_GroupAvailable, Mix_GroupChannel, Mix_GroupChannels

5.4.8 Mix_FadeOutGroup

int Mix_FadeOutGroup(int tag, int ms)

tag

Group to fade out.
NOTE: -1 will NOT fade all channels out. Use Mix_FadeOutChannel(-1) for that instead.

ms

Milliseconds of time that the fade-out effect should take to go to silence, starting now.

Gradually fade out channels in group tag over ms milliseconds starting from now. The channels will be halted after the fade out is completed. Only channels that are playing are set to fade out, including paused channels. Any callback set by Mix_ChannelFinished will be called when each channel finishes fading out.

Returns: The number of channels set to fade out.

// fade out all channels in group 1 to finish 3 seconds from now
printf("starting fade out of %d channels\n", Mix_FadeOutGroup(1, 3000));

See Also:
Mix_HaltGroup, Mix_FadeOutChannel, Mix_FadingChannel, Mix_ChannelFinished

5.4.9 Mix_HaltGroup

int Mix_HaltGroup(int tag)

tag

Group to fade out.
NOTE: -1 will NOT halt all channels. Use Mix_HaltChannel(-1) for that instead.

Halt playback on all channels in group tag.
Any callback set by Mix_ChannelFinished will be called once for each channel that stops.

Returns: always returns zero. (more silly than Mix_HaltChannel)

// halt playback on all channels in group 1
Mix_HaltGroup(1);

See Also:
Mix_FadeOutGroup, Mix_HaltChannel, Mix_ChannelFinished

5.5 Music

These functions work with music. Music is not played on a normal mixer channel. Music is therefore manipulated separately, except in post-processing hooks.

There are two different music sub-systems provided:
- single-music: the old API of the SDL_mixer. The most of given calls don’t even has the Mix_Music argument and intended to manipulate the currently playing music.
- multi-music: the new API of the MixerX. Every given call intended to work with the multi-music has the Mix_Music argument to manipulate every music individually as they are able to work in parallel.

Loading

Free

Playing

Playing (legacy single-stream)

Settings

Settings (legacy single-stream)

MIDI settings

Stopping

Stopping (legacy single-stream)

Info

Info (legacy single-stream)

Meta-Tags

Timidity Extra Settings

Game Music EMU Extra Settings

FluidSynth Extra Settings

libADLMIDI Extra Settings

libOPNMIDI Extra Settings

Extra

5.5.1 Mix_GetNumMusicDecoders

int Mix_GetNumMusicDecoders()

Get the number of music decoders available from the Mix_GetMusicDecoder function. This number can be different for each run of a program, due to the change in availability of shared libraries that support each format.

Returns: The number of music decoders available.

// print the number of music decoders available
printf("There are %d music deocoders available\n", Mix_GetNumMusicDecoders());

See Also:
Mix_GetNumChunkDecoders, Mix_GetMusicDecoder, Mix_LoadMUS

5.5.2 Mix_GetMusicDecoder

const char *Mix_GetMusicDecoder(int index)

index

The index number of music decoder to get.
In the range from 0(zero) to Mix_GetNumMusicDecoders()-1, inclusive.

Get the name of the indexed music decoder. You need to get the number of music decoders available using the Mix_GetNumMusicDecoders function.

Returns: The name of the indexed music decoder. This string is owned by the SDL_mixer library, do not modify or free it. It is valid until you call Mix_CloseAudio the final time.

// print music decoders available
int i,max=Mix_GetNumMusicDecoders();
for(i=0; i<max; ++i)
	printf("Music decoder %d is for %s",Mix_GetMusicDecoder(i));

See Also:
Mix_GetNumMusicDecoders, Mix_GetChunkDecoder, Mix_LoadWAV

5.5.3 Mix_HasMusicDecoder

SDL_bool Mix_HasMusicDecoder(const char *name)

name

The decoder name to check it’s presence.

Check if the music decoder named as name presented in this library build.

Returns: SDL_TRUE if the requested codec name is available in this library build or SDL_FALSE if not.

See Also:
Mix_Music, Mix_SetMusicCMD, Mix_PlayMusic, Mix_FadeInMusic, Mix_FadeInMusicPos

5.5.4 Mix_LoadMUS

Mix_Music *Mix_LoadMUS(const char *file)

file

Name of music file to use. You may add the Music Arguments after the filepath using the | symbol as the separator.

Load music file to use. This can load WAVE, MOD, MIDI, OGG, MP3, FLAC, and any file that you use a command to play with.
If you are using an external command to play the music, you must call Mix_SetMusicCMD before this, otherwise the internal players will be used. Alternatively, if you have set an external command up and don’t want to use it, you must call Mix_SetMusicCMD(NULL) to use the built-in players again.

Returns: A pointer to a Mix_Music. NULL is returned on errors.

// load the MP3 file "music.mp3" to play as music
Mix_Music *music;
music=Mix_LoadMUS("music.mp3");
if(!music) {
    printf("Mix_LoadMUS(\"music.mp3\"): %s\n", Mix_GetError());
    // this might be a critical error...
}

// load the MIDI file "music.mid" to play as music
// and add the Music Arguments string "s3;c2;" into it
Mix_Music *music;
music=Mix_LoadMUS("music.mid|s3;c2;");
if(!music) {
    printf("Mix_LoadMUS(\"music.mid|s3;c2;\"): %s\n", Mix_GetError());
    // this might be a critical error...
}

See Also:
Mix_Music, Mix_SetMusicCMD, Mix_PlayMusic, Mix_FadeInMusic, Mix_FadeInMusicPos

5.5.5 Mix_LoadMUS_RW

Mix_Music *Mix_LoadMUS_RW(SDL_RWops *src, int freesrc)

src

SDL RWops instance of music file / memory

freesrc

Automatically close SDL_RWops instance on complete loading of music

Load a music file from an SDL_RWop object

Returns: A pointer to a Mix_Music. NULL is returned on errors.

SDL_RWops *file = SDL_RWopen("music.mp3", "rb");
// load the MP3 file "music.mp3" to play as music
Mix_Music *music;
music = Mix_LoadMUS_RW(file, 0);
if(!music) {
    printf("Mix_LoadMUS_RW(file, 0): %s\n", Mix_GetError());
    // this might be a critical error...
}

See Also:
Mix_Music, Mix_LoadMUS_RW_ARG, Mix_LoadMUS_RW_GME, Mix_LoadMUSType_RW, Mix_LoadMUSType_RW_ARG, Mix_SetMusicCMD, Mix_PlayMusic, Mix_FadeInMusic, Mix_FadeInMusicPos

5.5.6 Mix_LoadMUS_RW_ARG

Mix_Music *Mix_LoadMUS_RW_ARG(SDL_RWops *src, int freesrc, const char *args)

src

SDL RWops instance of music file / memory

freesrc

Automatically close SDL_RWops instance on complete loading of music

args

The Music Arguments string supported by specific library

Load a music file from an SDL_RWop object with custom arguments

Returns: A pointer to a Mix_Music. NULL is returned on errors.

// load the MIDI file "music.mid" to play as music with ADLMIDI synthesizer
Mix_Music *music;
SDL_RWops *file = SDL_RWopen("music.mid", "rb");
music = Mix_LoadMUS_RW_ARG(file, 1, "s0;t1;v1;b68;");
if(!music) {
    printf("Mix_LoadMUS_RW_ARG(file, 1, \"s0;t1;v1;b68;\"): %s\n", Mix_GetError());
    // this might be a critical error...
}

See Also:
Mix_Music, Mix_LoadMUS_RW, Mix_LoadMUS_RW_GME, Mix_LoadMUSType_RW, Mix_LoadMUSType_RW_ARG, Mix_SetMusicCMD, Mix_PlayMusic, Mix_FadeInMusic, Mix_FadeInMusicPos

5.5.7 Mix_LoadMUS_RW_GME

Mix_Music *Mix_LoadMUS_RW_GME(SDL_RWops *src, int freesrc, int trackID)

src

SDL RWops instance of music file / memory

freesrc

Automatically close SDL_RWops instance on complete loading of music

trackID

ID of GME file track

Load music file to use.

Returns: A pointer to a Mix_Music. NULL is returned on errors.

// load the PC Engine chiptune file "music.hes" to play as music with GME library
Mix_Music *music;
SDL_RWops *file = SDL_RWopen("music.hes", "rb");
music = Mix_LoadMUS_RW_GME(file, 1, 4);
if(!music) {
    printf("Mix_LoadMUS_RW_GME(file, 1, 4): %s\n", Mix_GetError());
    // this might be a critical error...
}

See Also:
Mix_Music, Mix_LoadMUS_RW, Mix_LoadMUS_RW_ARG, Mix_LoadMUSType_RW, Mix_LoadMUSType_RW_ARG, Mix_SetMusicCMD, Mix_PlayMusic, Mix_FadeInMusic, Mix_FadeInMusicPos

5.5.8 Mix_LoadMUSType_RW

Mix_Music *Mix_LoadMUSType_RW(SDL_RWops *src, Mix_MusicType type, int freesrc)

src

SDL RWops instance of music file / memory

type

A music type identificator

freesrc

Automatically close SDL_RWops instance on complete loading of music

Load a music file from an SDL_RWop object assuming a specific format

Returns: A pointer to a Mix_Music. NULL is returned on errors.

// load the MIDI file "music.mid" to play as music with ADLMIDI synthesizer
Mix_Music *music;
SDL_RWops *file = SDL_RWopen("music.mid", "rb");
music = Mix_LoadMUSType_RW(file, MUS_MID, 1);
if(!music) {
    printf("Mix_LoadMUSType_RW(file, MUS_MID, 1): %s\n", Mix_GetError());
    // this might be a critical error...
}

See Also:
Mix_Music, Mix_LoadMUS_RW, Mix_LoadMUS_RW_GME, Mix_LoadMUSType_RW_ARG, Mix_SetMusicCMD, Mix_PlayMusic, Mix_FadeInMusic, Mix_FadeInMusicPos

5.5.9 Mix_LoadMUSType_RW_ARG

Mix_Music *Mix_LoadMUSType_RW_ARG(SDL_RWops *src, Mix_MusicType type, int freesrc)

src

SDL RWops instance of music file / memory

type

A music type identificator

freesrc

Automatically close SDL_RWops instance on complete loading of music

args

The Music Arguments string supported by specific library

Load a music file from an SDL_RWop object assuming a specific format with custom arguments (trackID for GME or settings for a MIDI playing)

Returns: A pointer to a Mix_Music. NULL is returned on errors.

// load the MIDI file "music.mid" to play as music with ADLMIDI synthesizer
Mix_Music *music;
SDL_RWops *file = SDL_RWopen("music.mid", "rb");
music = Mix_LoadMUSType_RW_ARG(file, MUS_MID, 1, "s0;t1;v1;b68;");
if(!music) {
    printf("Mix_LoadMUSType_RW_ARG(file, MUS_MID, 1, \"s0;t1;v1;b68;\"): %s\n", Mix_GetError());
    // this might be a critical error...
}

See Also:
Mix_Music, Mix_LoadMUS_RW, Mix_LoadMUS_RW_GME, Mix_LoadMUSType_RW, Mix_SetMusicCMD, Mix_PlayMusic, Mix_FadeInMusic, Mix_FadeInMusicPos

5.5.10 Mix_FreeMusic

void Mix_FreeMusic(Mix_Music *music)

music

Pointer to Mix_Music to free.

Free the loaded music. If music is playing it will be halted. If music is fading out, then this function will wait (blocking) until the fade out is complete.

// free music
Mix_Music *music;
Mix_FreeMusic(music);
music=NULL; // so we know we freed it...

See Also:
Mix_LoadMUS

5.5.11 Mix_SetFreeOnStop

void Mix_FreeMusic(Mix_Music *music, int free_on_stop)

music

Pointer to Mix_Music to free.

free_on_stop

1 - make music to be free automatically when it finishes the playback, 0 - cancel the automatical free.

Mark the loaded music to be free automatically when it get halted. Can be used to simplify the dynamic stream processing when you want to automatically free the music once it get halted.

Note: Music will NOT be free when you stop it manually using the Mix_HaltMusicStream call. However, it will get free automatically when you will use the Mix_FadeOutMusicStream call with a non-zero ms delay.
Supported by multi-stream music sub-system only.

// free music
Mix_Music *music;
// play music once
Mix_PlayMusicStream(music, 1);
// Mark music to be free automatically
Mix_SetFreeOnStop(music, 1);
music=NULL; // we are safe to NULL this, no memory leak promised

See Also:
Mix_LoadMUS

5.5.12 Mix_PlayMusicStream

int Mix_PlayMusicStream(Mix_Music *music, int loops)

music

Pointer to Mix_Music to play.

loops

number of times to play through the music.
0 plays the music zero times...
-1 plays the music forever (or as close as it can get to that)

Play the loaded music loop times through from start to finish. The previous music will continue play or fade concurrently. You can use this function to play multiple parallel music files (or long atmosphere sound effects).

CAUTION: You can’t use this function with MIDI played through Native MIDI interface: this interface doesn’t support parallel playing of multiple music files. Please use the Mix_PlayMusic function to playNativeMidi as a single-stream music.

Returns: 0 on success, or -1 on errors.

// play music forever
// Mix_Music *music; // I assume this has been loaded already
if(Mix_PlayMusicStream(music, -1)==-1) {
    printf("Mix_PlayMusicStream: %s\n", Mix_GetError());
    // well, there's no music, but most games don't break without music...
}

See Also:
Mix_FadeInMusicStream Mix_CrossFadeMusicStream

5.5.13 Mix_FadeInMusicStream

int Mix_FadeInMusicStream(Mix_Music *music, int loops, int ms)

music

Pointer to Mix_Music to play.

loops

number of times to play through the music.
0 plays the music zero times...
-1 plays the music forever (or as close as it can get to that)

ms

Milliseconds for the fade-in effect to complete.

Fade in over ms milliseconds of time, the loaded music, playing it loop times through from start to finish.
The fade in effect only applies to the first loop.
Any previous music will continue play or fade concurrently. You can use this function to play multiple parallel music files (or long atmosphere sound effects).
This function is the same as Mix_FadeInMusicStreamPos(music, loops, ms, 0).

CAUTION: You can’t use this function with MIDI played through Native MIDI interface: this interface doesn’t support parallel playing of multiple music files. Please use the Mix_FadeInMusic function to play NativeMidi as a single-stream music.

Returns: 0 on success, or -1 on errors.

// play music forever, fading in over 2 seconds
// Mix_Music *music; // I assume this has been loaded already
if(Mix_FadeInMusicStream(music, -1, 2000)==-1) {
    printf("Mix_FadeInMusicStream: %s\n", Mix_GetError());
    // well, there's no music, but most games don't break without music...
}

See Also:
Mix_PlayMusicStream, Mix_FadeInMusicStreamPos Mix_CrossFadeMusicStream Mix_CrossFadeMusicStreamPos

5.5.14 Mix_FadeInMusicStreamPos

int Mix_FadeInMusicStreamPos(Mix_Music *music, int loops, int ms, double position)

music

Pointer to Mix_Music to play.

loops

number of times to play through the music.
0 plays the music zero times...
-1 plays the music forever (or as close as it can get to that)

ms

Milliseconds for the fade-in effect to complete.

position

Position to play from, see Mix_SetMusicPositionStream for meaning.

Fade in over ms milliseconds of time, the loaded music, playing it loop times through from start to finish.
The fade in effect only applies to the first loop.
The first time the music is played, it position will be set to position, which means different things for different types of music files, see Mix_SetMusicPosition for more info on that.
Any previous music will continue play or fade concurrently. You can use this function to play multiple parallel music files (or long atmosphere sound effects).

CAUTION: You can’t use this function with MIDI played through Native MIDI interface: this interface doesn’t support parallel playing of multiple music files. Please use the Mix_FadeInMusicPos function to play NativeMidi as a single-stream music.

Returns: 0 on success, or -1 on errors.

// play music forever, fading in over 2 seconds
// Mix_Music *music; // I assume this has been loaded already
if(Mix_FadeInMusicStreamPos(music, -1, 2000)==-1) {
    printf("Mix_FadeInMusicStream: %s\n", Mix_GetError());
    // well, there's no music, but most games don't break without music...
}

See Also:
Mix_PlayMusicStream, Mix_FadeInMusicStream, Mix_SetMusicPosition Mix_CrossFadeMusicStream Mix_CrossFadeMusicStreamPos

5.5.15 Mix_CrossFadeMusicStream

int Mix_CrossFadeMusicStream(Mix_Music *old_music, Mix_Music *new_music, int loops, int ms, int free_old)

old_music

Pointer to old playing Mix_Music to stop with the fade out effect.

new_music

Pointer to new Mix_Music to play with the fade in effect.

loops

number of times to play through the music.
0 plays the music zero times...
-1 plays the music forever (or as close as it can get to that)

ms

Milliseconds for the fade-in effect to complete.

free_old

Automatically free the old music after it will complete the fade out.
0 keeps the old music untouched.
1 music will be deleted after it will complete the fade out.

Fade in over ms milliseconds of time, the loaded new_music, playing it loop times through from start to finish.
Fade out the old_music at the same time as fade in the new_music.
The fade in effect only applies to the first loop.
Any previous music will continue play or fade concurrently.
This function is the same as Mix_CrossFadeMusicStreamPos(old_music, new_music, loops, ms, 0, 0).

CAUTION: You can’t use this function with MIDI played through Native MIDI interface: this interface doesn’t support parallel playing of multiple music files.

Returns: 0 on success, or -1 on errors.

// play music forever, fading in over 2 seconds
// Mix_Music *old_music; // I assume this has been loaded already and playing now
// Mix_Music *new_music; // I assume this has been loaded already
if(Mix_CrossFadeMusicStream(old_music, new_music, -1, 2000, 0)==-1) {
    printf("Mix_CrossFadeMusicStream: %s\n", Mix_GetError());
    // well, there's no music, but most games don't break without music...
}

See Also:
Mix_PlayMusicStream, Mix_CrossFadeMusicStreamPos

5.5.16 Mix_CrossFadeMusicStreamPos

int Mix_CrossFadeMusicStreamPos(Mix_Music *old_music, Mix_Music *new_music, int loops, int ms, double position, int free_old)

old_music

Pointer to old playing Mix_Music to stop with the fade out effect.

new_music

Pointer to new Mix_Music to play with the fade in effect.

loops

number of times to play through the music.
0 plays the music zero times...
-1 plays the music forever (or as close as it can get to that)

ms

Milliseconds for the fade-in effect to complete.

position

Position to play from, see Mix_SetMusicPositionStream for meaning.

free_old

Automatically free the old music after it will complete the fade out.
0 keeps the old music untouched.
1 music will be deleted after it will complete the fade out.

Fade in over ms milliseconds of time, the loaded music, playing it loop times through from start to finish.
Fade out the old_music at the same time as fade in the new_music.
The fade in effect only applies to the first loop.
The first time the music is played, it position will be set to position, which means different things for different types of music files, see Mix_SetMusicPosition for more info on that.
Any previous music will continue play or fade concurrently.

CAUTION: You can’t use this function with MIDI played through Native MIDI interface: this interface doesn’t support parallel playing of multiple music files.

Returns: 0 on success, or -1 on errors.

// play music forever, fading in over 2 seconds
// Mix_Music *old_music; // I assume this has been loaded already and playing now
// Mix_Music *new_music; // I assume this has been loaded already
if(Mix_CrossFadeMusicStreamPos(old_music, new_music, -1, 2000, 0)==-1) {
    printf("Mix_CrossFadeMusicStream: %s\n", Mix_GetError());
    // well, there's no music, but most games don't break without music...
}

See Also:
Mix_PlayMusicStream, Mix_CrossFadeMusicStream, Mix_SetMusicPosition

5.5.17 Mix_HookMusic

void Mix_HookMusic(void (*mix_func)(void *udata, Uint8 *stream, int len),
                   void *arg)

mix_func

Function pointer to a music player mixer function.
NULL will stop the use of the music player, returning the mixer to using the internal music players like usual.

arg

This is passed to the mix_func’s udata parameter when it is called.

This sets up a custom music player function. The function will be called with arg passed into the udata parameter when the mix_func is called. The stream parameter passes in the audio stream buffer to be filled with len bytes of music. The music player will then be called automatically when the mixer needs it. Music playing will start as soon as this is called. All the music playing and stopping functions have no effect on music after this. Pause and resume will work. Using a custom music player and the internal music player is not possible, the custom music player takes priority. To stop the custom music player call Mix_HookMusic(NULL, NULL).
NOTE: NEVER call SDL_Mixer functions, nor SDL_LockAudio, from a callback function.

// make a music play function
// it expects udata to be a pointer to an int
void myMusicPlayer(void *udata, Uint8 *stream, int len)
{
    int i, pos=*(int*)udata;

    // fill buffer with...uh...music...
    for(i=0; i<len; i++)
        stream[i]=(i+pos)&ff;

    // set udata for next time
    pos+=len;
    *(int*)udata=pos;
}
...
// use myMusicPlayer for playing...uh...music
int music_pos=0;
Mix_HookMusic(myMusicPlayer, &music_pos);

See Also:
Mix_SetMusicCMD, Mix_GetMusicHookData

5.5.18 Mix_PlayMusic

int Mix_PlayMusic(Mix_Music *music, int loops)

music

Pointer to Mix_Music to play.

loops

number of times to play through the music.
0 plays the music zero times...
-1 plays the music forever (or as close as it can get to that)

Play the loaded music loop times through from start to finish. The previous music will be halted, or if fading out it waits (blocking) for that to finish.
Please use the Mix_PlayMusicStream function to play multiple music streams in parallel.

Returns: 0 on success, or -1 on errors.

// play music forever
// Mix_Music *music; // I assume this has been loaded already
if(Mix_PlayMusic(music, -1)==-1) {
    printf("Mix_PlayMusic: %s\n", Mix_GetError());
    // well, there's no music, but most games don't break without music...
}

See Also:
Mix_FadeInMusic

5.5.19 Mix_FadeInMusic

int Mix_FadeInMusic(Mix_Music *music, int loops, int ms)

music

Pointer to Mix_Music to play.

loops

number of times to play through the music.
0 plays the music zero times...
-1 plays the music forever (or as close as it can get to that)

ms

Milliseconds for the fade-in effect to complete.

Fade in over ms milliseconds of time, the loaded music, playing it loop times through from start to finish.
The fade in effect only applies to the first loop.
Any previous music will be halted, or if it is fading out it will wait (blocking) for the fade to complete.
This function is the same as Mix_FadeInMusicPos(music, loops, ms, 0).
Please use the Mix_FadeInMusicStream function to play multiple music streams in parallel.

Returns: 0 on success, or -1 on errors.

// play music forever, fading in over 2 seconds
// Mix_Music *music; // I assume this has been loaded already
if(Mix_FadeInMusic(music, -1, 2000)==-1) {
    printf("Mix_FadeInMusic: %s\n", Mix_GetError());
    // well, there's no music, but most games don't break without music...
}

See Also:
Mix_PlayMusic, Mix_FadeInMusicPos

5.5.20 Mix_FadeInMusicPos

int Mix_FadeInMusicPos(Mix_Music *music, int loops, int ms, double position)

music

Pointer to Mix_Music to play.

loops

number of times to play through the music.
0 plays the music zero times...
-1 plays the music forever (or as close as it can get to that)

ms

Milliseconds for the fade-in effect to complete.

position

Position to play from, see Mix_SetMusicPosition for meaning.

Fade in over ms milliseconds of time, the loaded music, playing it loop times through from start to finish.
The fade in effect only applies to the first loop.
The first time the music is played, it position will be set to position, which means different things for different types of music files, see Mix_SetMusicPosition for more info on that.
Any previous music will be halted, or if it is fading out it will wait (blocking) for the fade to complete.
Please use the Mix_FadeInMusicStreamPos function to play multiple music streams in parallel.

Returns: 0 on success, or -1 on errors.

// play music forever, fading in over 2 seconds
// Mix_Music *music; // I assume this has been loaded already
if(Mix_FadeInMusicPos(music, -1, 2000)==-1) {
    printf("Mix_FadeInMusic: %s\n", Mix_GetError());
    // well, there's no music, but most games don't break without music...
}

See Also:
Mix_PlayMusic, Mix_FadeInMusic, Mix_SetMusicPosition

5.5.21 Mix_VolumeMusicStream

int Mix_VolumeMusicStream(Mix_Music *music, int volume)

music

Music to set the volume.

volume

Music volume, from 0 to MIX_MAX_VOLUME(128).
Values greater than MIX_MAX_VOLUME will use MIX_MAX_VOLUME.
-1 does not set the volume, but does return the current volume setting.

Set the volume to volume, if it is 0 or greater, and return the previous volume setting. Setting the volume during a fade will not work, the faders use this function to perform their effect! Setting volume while using an external music player set by Mix_SetMusicCMD will have no effect, and Mix_GetError will show the reason why not.

Returns: The previous volume setting.

// set the music volume to 1/2 maximum, and then check it
printf("volume was    : %d\n", Mix_VolumeMusicStream(someMusic, MIX_MAX_VOLUME/2));
printf("volume is now : %d\n", Mix_GetVolumeMusicStream(someMusic));

See Also:
Mix_GetMusicVolume, Mix_GetVolumeMusicStream, Mix_VolumeMusicGeneral, Mix_GetVolumeMusicGeneral, Mix_FadeInMusicStream, Mix_FadeOutMusicStream, Mix_SetMusicCMD

5.5.22 Mix_GetMusicVolume

int Mix_GetMusicVolume(Mix_Music *music)

music

Music to get the volume.

Get the current volume set on the music.

Returns: The current volume setting set on the music.

See Also:
Mix_GetVolumeMusicStream, Mix_VolumeMusicStream, Mix_VolumeMusicGeneral, Mix_GetVolumeMusicGeneral, Mix_FadeInMusicStream, Mix_FadeOutMusicStream, Mix_SetMusicCMD

5.5.23 Mix_GetVolumeMusicStream

int Mix_GetVolumeMusicStream(Mix_Music *music)

music

Music to get the volume.

Get the current volume set on the music. This is an alias to the Mix_GetMusicVolume function.

Returns: The current volume setting set on the music.

See Also:
Mix_GetMusicVolume, Mix_VolumeMusicStream, Mix_VolumeMusicGeneral, Mix_GetVolumeMusicGeneral, Mix_FadeInMusicStream, Mix_FadeOutMusicStream, Mix_SetMusicCMD

5.5.24 Mix_VolumeMusicGeneral

void Mix_VolumeMusicGeneral(int volume)

volume

General multi-stream music volume, from 0 to MIX_MAX_VOLUME(128).
Values greater than MIX_MAX_VOLUME will use MIX_MAX_VOLUME.

Set the general multi-stream music volume to volume, if it is 0 or greater. Setting volume while using an external music player set by Mix_SetMusicCMD will have no effect.

See Also:
Mix_GetMusicVolume, Mix_VolumeMusicStream, Mix_GetVolumeMusicGeneral, Mix_FadeInMusicStream, Mix_FadeOutMusicStream, Mix_SetMusicCMD

5.5.25 Mix_GetVolumeMusicGeneral

int Mix_GetVolumeMusicGeneral()

Get the current general multi-stream music volume.

Returns: The current general multi-stream music volume.

See Also:
Mix_GetMusicVolume, Mix_VolumeMusicStream, Mix_VolumeMusicGeneral, Mix_FadeInMusicStream, Mix_FadeOutMusicStream, Mix_SetMusicCMD

5.5.26 Mix_PauseMusicStream

void Mix_PauseMusicStream(Mix_Music *music)

music

Music to pause.

Pause the music playback. You may halt paused music.
Note: Music can only be paused if it is actively playing.

// pause music playback
Mix_PauseMusicStream(music);

See Also:
Mix_ResumeMusicStream, Mix_PausedMusicStream, Mix_HaltMusicStream

5.5.27 Mix_PauseMusicStreamAll

void Mix_PauseMusicStreamAll()

Pause all multi-stream music playback. You may halt any paused music.
Note: Music can only be paused if it is actively playing.

// pause music playback
Mix_PauseMusicStreamAll();

See Also:
Mix_ResumeMusicStream, Mix_PausedMusicStream, Mix_HaltMusicStream

5.5.28 Mix_ResumeMusicStream

void Mix_ResumeMusicStream(Mix_Music *music)

music

Paused music to resume.

Unpause the music. This is safe to use on halted, paused, and already playing music.

// resume music playback
Mix_ResumeMusicStream(music);

See Also:
Mix_PauseMusicStream, Mix_PausedMusicStream, Mix_HaltMusicStream

5.5.29 Mix_ResumeMusicStreamAll

void Mix_ResumeMusicStreamAll()

Unpause all multi-stream music. This is safe to use on halted, paused, and already playing music.

// resume music playback
Mix_ResumeMusicStreamAll();

See Also:
Mix_ResumeMusicStream, Mix_PausedMusicStream, Mix_HaltMusicStream

5.5.30 Mix_RewindMusicStream

void Mix_RewindMusicStream(Mix_Music *music)

music

Music to rewind.

Rewind the music to the start. This is safe to use on halted, paused, and already playing music. It is not useful to rewind the music immediately after starting playback, because it starts at the beginning by default.

This function only works for streams that supports the seekability.

// rewind music playback to the start
Mix_RewindMusicStream(music);

See Also:
Mix_PlayMusicStream

5.5.31 Mix_SetMusicPositionStream

int Mix_SetMusicPositionStream(Mix_Music *music, double position)

music

Music to change the position.

position

Position to play from in seconds.

Set the position of the music. The position takes different meanings for different music sources. It only works on the music sources listed below.

WAV

Jumps to position seconds from the beginning of the song.

MOD

ModPlug or XMP: Jumps to position seconds from the beginning of the song.
Passing zero is similar to rewinding the song.

OGG

Jumps to position seconds from the beginning of the song.

OPUS

Jumps to position seconds from the beginning of the song.

FLAC

Jumps to position seconds from the beginning of the song.

MP3

Jumps to position seconds from the beginning of the song.

GME

Jumps to position seconds from the beginning of the song.

MIDI

Works for libADLMIDI and libOPNMIDI. Doesn’t works for Timidity, FluidSynth, and NativeMIDI. Jumps to position seconds from the beginning of the song.

Returns: 0 on success, or -1 if the codec doesn’t support this function.

// skip one minute into the song, from the start
if(Mix_SetMusicPositionStream(music, 60.0)==-1) {
    printf("Mix_SetMusicPositionStream: %s\n", Mix_GetError());
}

See Also:
Mix_FadeInMusicStreamPos, Mix_GetMusicPosition, Mix_MusicDuration, Mix_StartTrack, Mix_GetNumTracks

5.5.32 Mix_GetMusicPosition

double Mix_GetMusicPosition(Mix_Music *music)

music

A pointer to current music stream

Get the time current position of music stream. It only works on some of music sources listed in table shown in description of Mix_SetMusicPosition function.

Returns: seconds value of current music position or -1.0 if this feature is not supported for some codec

See Also:
Mix_FadeInMusicStreamPos, Mix_SetMusicPositionStream, Mix_MusicDuration, Mix_StartTrack, Mix_GetNumTracks

5.5.33 Mix_ModMusicStreamJumpToOrder

int Mix_ModMusicStreamJumpToOrder(Mix_Music *music, int order)

music

Music to change the position.

order

A pattern number in the module.

Jump to a given order in mod music. Only for MOD music formats.

Returns: 0 if successful, or -1 if failed or isn’t implemented.

See Also:
Mix_FadeInMusicStreamPos, Mix_SetMusicPositionStream, Mix_MusicDuration, Mix_StartTrack, Mix_GetNumTracks

5.5.34 Mix_StartTrack

int Mix_StartTrack(Mix_Music *music, int track)

music

Music to select a sub-song for play.

track

A song number from 0 to N-1 to play.

Starts a sub-song to play. This function works when one music file contains multiple songs, for example, various chiptunes like NSF, HES, or XMI-based MIDI files.

Returns: 0 if successful, or -1 if failed or isn’t implemented.

See Also:
Mix_FadeInMusicStreamPos, Mix_SetMusicPositionStream, Mix_MusicDuration, Mix_ModMusicStreamJumpToOrder, Mix_GetNumTracks