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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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_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_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_MusicDuration
-----------------

double Mix_MusicDuration(Mix_Music *MUSIC)

music
     A pointer to current music stream

Get the full duration time 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 total length or -1.0 if this feature is not supported for some codec

See Also:

Mix_FadeInMusicPos Mix_GetMusicPosition Mix_SetMusicPosition

Mix_GetMusicLoopStartTime
-------------------------

double Mix_GetMusicLoopStartTime(Mix_Music *MUSIC)

music
     A pointer to current music stream

A part of loop points feature. Get the loop start time position of music stream. It only works on some of music sources.

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

See Also:

Mix_GetMusicLoopEndTime Mix_GetMusicLoopLengthTime

Mix_GetMusicLoopEndTime
-----------------------

double Mix_GetMusicLoopEndTime(Mix_Music *MUSIC)

music
     A pointer to current music stream

A part of loop points feature. Get the loop time length of music stream. It only works on some of music sources.

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

See Also:

Mix_GetMusicLoopStartTime Mix_GetMusicLoopLengthTime

Mix_GetMusicLoopLengthTime
--------------------------

double Mix_GetMusicLoopEndTime(Mix_Music *MUSIC)

music
     A pointer to current music stream

A part of loop points feature. Get the loop time length of music stream. It only works on some of music sources.

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

See Also:

Mix_GetMusicLoopStartTime Mix_GetMusicLoopEndTime

Mix_SetMusicTempo
-----------------

int Mix_SetMusicTempo(Mix_Music *MUSIC, double TEMPO)

music
     Music to change the tempo.

tempo
     Tempo multiplier. Setting value into the 1.0 will reset the tempo into default.

Set the current tempo multiplier in the music stream.

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

See Also:

Mix_GetMusicTempo Mix_FadeInMusicStreamPos Mix_SetMusicPositionStream Mix_MusicDuration

Mix_GetMusicTempo
-----------------

double Mix_GetMusicTempo(Mix_Music *MUSIC)

music
     Music to get the tempo.

Returns the current tempo multiplier of the music stream.

Returns: positive value if successful, or -1.0 if failed or isn't implemented.

See Also:

Mix_SetMusicTempo Mix_FadeInMusicStreamPos Mix_SetMusicPositionStream Mix_MusicDuration

Mix_GetMusicTracks
------------------

int Mix_GetMusicTracks(Mix_Music *MUSIC)

music
     Music to get the number of tracks/channels.

Get the count of concurrently playing tracks at the song (MIDI, Tracker, Chiptune, etc.)

Returns: count of tracks/channels if successful, or -1 if failed or isn't implemented.

See Also:

Mix_SetMusicTrackMute Mix_FadeInMusicStreamPos Mix_SetMusicPositionStream Mix_MusicDuration

Mix_SetMusicTrackMute
---------------------

int Mix_GetMusicTracks(Mix_Music *MUSIC, int TRACK, int MUTE)

music
     Music to get the number of tracks/channels.

track
     Track/Channel number to mute

mute
     The mute state: 1 mute, 0 unmute

Mute one of playing tracks (or channels) at the song (MIDI, Tracker, Chiptune, etc.)

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

See Also:

Mix_GetMusicTracks Mix_FadeInMusicStreamPos Mix_SetMusicPositionStream Mix_MusicDuration

Mix_SetMusicCMD
---------------

int Mix_SetMusicCMD(const char *COMMAND)

command
     System command to play the music.  Should be a complete command, as if typed in to the command line, but it should expect the filename to be added as the last argument.

     NULL will turn off using an external command for music, returning to the internal music playing functionality.

Setup a command line music player to use to play music.  Any music playing will be halted. The music file to play is set by calling Mix_LoadMUS(filename), and the filename is appended as the last argument on the commandline.  This allows you to reuse the music command to play multiple files.  The command will be sent signals SIGTERM to halt, SIGSTOP to pause, and SIGCONT to resume.  The command program should react correctly to those signals for it to function properly with SDL_Mixer.  Mix_VolumeMusic has no effect when using an external music player, and Mix_GetError will have an error code set.  You should set the music volume in the music player's command if the music player supports that.  Looping music works, by calling the command again when the previous music player process has ended.  Playing music through a command uses a forked process to execute the music command.

To use the internal music players set the COMMAND to NULL.

NOTE: External music is not mixed by SDL_mixer, so no post-processing hooks will be for music.

NOTE: Playing music through an external command may not work if the sound driver does not support multiple openings of the audio device, since SDL_Mixer already has the audio device open for playing samples through channels.

NOTE: Commands are not totally portable, so be careful.

Returns: 0 on success, or -1 on any errors, such as running out of memory.

     // use mpg123 to play music
     Mix_Music *music=NULL;
     if(Mix_SetMusicCMD("mpg123 -q")==-1) {
         perror("Mix_SetMusicCMD");
     } else {
         // play some mp3 file
         music=Mix_LoadMUS("music.mp3");
         if(music) {
             Mix_PlayMusic(music,1);
         }
     }

See Also:

Mix_PlayMusic, Mix_VolumeMusic

Mix_GetSynchroValue
-------------------

int Mix_GetSynchroValue()

Not supported by any players at this time.

Mix_SetSynchroValue
-------------------

int Mix_SetSynchroValue(int VALUE)

Not supported by any players at this time.

Mix_SetMusicFileName
--------------------

void Mix_SetMusicFileName(Mix_Music *MUSIC, const char *FILE)

music
     The music to change the reported filename.

file
     The file name or file path.

Change the filename reported by the Mix_GetMusicTitle function in a case when the actual title tag is not specified in the file.

Mix_VolumeMusic
---------------

int Mix_VolumeMusic(int 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_VolumeMusic(MIX_MAX_VOLUME/2));
     printf("volume is now : %d\n", Mix_VolumeMusic(-1));

See Also:

Mix_FadeInMusic, Mix_FadeOutMusic, Mix_SetMusicCMD

Mix_PauseMusic
--------------

void Mix_PauseMusic()

Pause the music playback.  You may halt paused music.

Note: Music can only be paused if it is actively playing.

     // pause music playback
     Mix_PauseMusic();

See Also:

Mix_ResumeMusic, Mix_PausedMusic, Mix_HaltMusic

Mix_ResumeMusic
---------------

void Mix_ResumeMusic()

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

     // resume music playback
     Mix_ResumeMusic();

See Also:

Mix_PauseMusic, Mix_PausedMusic

Mix_RewindMusic
---------------

void Mix_RewindMusic()

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 these streams: MOD, OGG, MP3, Native MIDI.

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

See Also:

Mix_PlayMusic

Mix_SetMusicPosition
--------------------

int Mix_SetMusicPosition(double POSITION)

position
     Position to play from.

Set the position of the currently playing 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_SetMusicPosition(60.0)==-1) {
         printf("Mix_SetMusicPosition: %s\n", Mix_GetError());
     }

See Also:

Mix_FadeInMusicPos Mix_GetMusicPosition Mix_MusicDuration

Mix_ModMusicJumpToOrder
-----------------------

int Mix_ModMusicJumpToOrder(int ORDER)

order
     A pattern number in the module.

Jump to a given order in mod music currently playing as a single-stream. Only for MOD music formats.

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

See Also:

Mix_FadeInMusicPos Mix_SetMusicPosition Mix_MusicDuration

Mix_GetMidiPlayer
-----------------

int Mix_GetMidiPlayer()

Tells currently using MIDI sequencer to play MIDI files.

Returns: The type of currently using MIDI device.

     // print the type of music currently playing
     switch(Mix_GetMidiPlayer())
     {
         MIDI_ADLMIDI:
             printf("ADLMIDI is active.\n");
             break;
         MIDI_Native:
             printf("Operating system native MIDI is active.\n");
             break;
         MIDI_Timidity:
             printf("Timidity is active.\n");
             break;
         MIDI_OPNMIDI:
             printf("OPNMIDI is active.\n");
             break;
         MIDI_Fluidsynth:
             printf("FluidSynth is active.\n");
             break;
         default:
             printf("Unknown MIDI device is using.\n");
             break;
     }

See Also:

Mix_SetMidiPlayer

Mix_GetNextMidiPlayer
---------------------

int Mix_GetNextMidiPlayer()

Tells MIDI sequencer recently choosen by Mix_SetMidiPlayer which will be use in next open of MIDI file.

Returns: The type of currently using MIDI device.

     // print the type of music currently playing
     switch(Mix_GetNextMidiPlayer())
     {
         MIDI_ADLMIDI:
             printf("ADLMIDI is next.\n");
             break;
         MIDI_Native:
             printf("Operating system native MIDI is next.\n");
             break;
         MIDI_Timidity:
             printf("Timidity is next.\n");
             break;
         MIDI_OPNMIDI:
             printf("OPNMIDI is next.\n");
             break;
         MIDI_Fluidsynth:
             printf("FluidSynth is next.\n");
             break;
         default:
             printf("Unknown MIDI device is next.\n");
             break;
     }

See Also:

Mix_GetMidiPlayer, Mix_SetMidiPlayer

Mix_SetMidiPlayer
-----------------

int Mix_SetMidiPlayer(int DEVICE)

device
     A MIDI_* enum value which identifies MIDI sequencer you want to use

Allows to choose a MIDI sequencer to play MIDI files. NOTE: new choosen MIDI device begins to work on  MIDI music file reopen

Returns: 0 on success, or -1 on any errors, such as MIDI sequencer is unknown or does not built with this library assembly.

     //Set libOPNMIDI as MIDI playing sequencer
     Mix_SetMidiPlayer(MIDI_OPNMIDI);

See Also:

Mix_SetLockMIDIArgs

Mix_SetLockMIDIArgs
-------------------

void Mix_SetLockMIDIArgs(int LOCK_MIDIARGS)

lock_midiargs
     0 to disable locking or 1 to enable locking of MIDI arguments passed through Mix_LoadMUS(filename) function

Allows to don't reset MIDI arguments to default when is no arguments passed through Mix_LoadMUS(filename) function, or different arguments was passed.

     //Turn on ignoring of MIDI arguments
     Mix_SetLockMIDIArgs(1);

See Also:

Mix_SetMidiPlayer

Mix_HaltMusicStream
-------------------

int Mix_HaltMusicStream(Mix_Music *MUSIC)

music
     Playing music to halt.

Halt playback of MUSIC. This interrupts music fader effects. Any callback set by Mix_HookMusicStreamFinished will be called when the music stops.

Note: Music will not be free automatically if you called the Mix_SetFreeOnStop function before.

Returns: always returns zero. (even more silly than MIX_HALTGROUP)

     // halt music playback
     Mix_HaltMusicStream(music);

See Also:

Mix_FadeOutMusicStream, Mix_HookMusicStreamFinished, Mix_HookMusicStreamFinishedAny

Mix_FadeOutMusicStream
----------------------

int Mix_FadeOutMusicStream(Mix_Music *MUSIC, int MS)

music
     Playing music to fade out.

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

Gradually fade out the MUSIC over MS milliseconds starting from now. The MUSIC will be halted after the fade out is completed. Only when music is playing and not fading already are set to fade out, including paused channels. Any callback set by Mix_HookMusicStreamFinished will be called when the music finishes fading out.

Note: Music will not be free automatically if you called the Mix_SetFreeOnStop function before and if you set the MS delay to be 0.

Returns: 1 on success, 0 on failure.

     // fade out music to finish 3 seconds from now
     while(!Mix_FadeOutMusicStream(music, 3000) && Mix_PlayingMusicStream(music)) {
         // wait for any fades to complete
         SDL_Delay(100);
     }

See Also:

Mix_HaltMusicStream, Mix_FadingMusicStream, Mix_PlayingMusicStream, Mix_HookMusicStreamFinished, Mix_HookMusicStreamFinishedAny

Mix_HookMusicStreamFinished
---------------------------

void Mix_HookMusicStreamFinished(Mix_Music *MUSIC, void (*MUSIC_FINISHED)(SDLCALL *music_finished)(Mix_Music*, void*), void *USER_DATA)

music
     Music to set the hook.

music_finished
     Function pointer to a void function(Mix_Music *music, void *user_data).

     NULL will remove the hook.

user_data
     User data pointer used with the the MUSIC_FINISHED callback

This sets up a function to be called when MUSIC playback is halted. Any time music stops, the MUSIC_FINISHED function will be called. Call with NULL to remove the callback.

NOTE: NEVER call SDL_Mixer functions, nor SDL_LockAudio, from a callback function.

     // make a music finished function
     void musicFinished(Mix_Music *music, void *user_data)
     {
         printf("Music stopped.\n");
     }
     ...
     // use musicFinished for when music stops
     Mix_HookMusicStreamFinished(music, musicFinished);

See Also:

Mix_HaltMusicStream, Mix_FadeOutMusicStream

Mix_HookMusicStreamFinishedAny
------------------------------

void Mix_HookMusicStreamFinishedAny(void (*MUSIC_FINISHED)())

music_finished
     Function pointer to a void function().

     NULL will remove the hook.

This sets up a function to be called when any multi-stream music playback is halted. Any time music stops, the MUSIC_FINISHED function will be called.  Call with NULL to remove the callback.

NOTE: NEVER call SDL_Mixer functions, nor SDL_LockAudio, from a callback function.

     // make a music finished function
     void musicFinished()
     {
         printf("Music stopped.\n");
     }
     ...
     // use musicFinished for when any music stops
     Mix_HookMusicStreamFinishedAny(musicFinished);

See Also:

Mix_HaltMusicStream, Mix_FadeOutMusicStream

Mix_HaltMusic
-------------

int Mix_HaltMusic()

Halt playback of music. This interrupts music fader effects. Any callback set by Mix_HookMusicFinished will be called when the music stops.

Returns: always returns zero. (even more silly than MIX_HALTGROUP)

     // halt music playback
     Mix_HaltMusic();

See Also:

Mix_FadeOutMusic, Mix_HookMusicFinished

Mix_FadeOutMusic
----------------

int Mix_FadeOutMusic(int MS)

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

Gradually fade out the music over MS milliseconds starting from now. The music will be halted after the fade out is completed.  Only when music is playing and not fading already are set to fade out, including paused channels. Any callback set by Mix_HookMusicFinished will be called when the music finishes fading out.

Returns: 1 on success, 0 on failure.

     // fade out music to finish 3 seconds from now
     while(!Mix_FadeOutMusic(3000) && Mix_PlayingMusic()) {
         // wait for any fades to complete
         SDL_Delay(100);
     }

See Also:

Mix_HaltMusic, Mix_FadingMusic, Mix_PlayingMusic, Mix_HookMusicFinished

Mix_HookMusicFinished
---------------------

void Mix_HookMusicFinished(void (*MUSIC_FINISHED)())

music_finished
     Function pointer to a void function().

     NULL will remove the hook.

This sets up a function to be called when single-stream music playback is halted.  Any time music stops, the MUSIC_FINISHED function will be called.  Call with NULL to remove the callback.

NOTE: NEVER call SDL_Mixer functions, nor SDL_LockAudio, from a callback function.

     // make a music finished function
     void musicFinished()
     {
         printf("Music stopped.\n");
     }
     ...
     // use musicFinished for when music stops
     Mix_HookMusicFinished(musicFinished);

See Also:

Mix_HaltMusic, Mix_FadeOutMusic

Mix_GetMusicType
----------------

Mix_MusicType Mix_GetMusicType(const Mix_Music *MUSIC)

music
     The music to get the type of.

     NULL will get the currently playing single-stream music type.

Tells you the file format encoding of the music.  This may be handy when used with Mix_SetMusicPosition, and other music functions that vary based on the type of music being played.  If you want to know the type of music currently being played, pass in NULL to MUSIC.

Returns: The type of MUSIC or if MUSIC is NULL then the currently playing music type, otherwise MUS_NONE if no music is playing.

     // print the type of music currently playing
     switch(Mix_GetMusicType(NULL))
     {
         case MUS_NONE:
         MUS_CMD:
             printf("Command based music is playing.\n");
             break;
         MUS_WAV:
             printf("WAVE/RIFF music is playing.\n");
             break;
         MUS_MOD:
             printf("MOD (XMP/ModPlug) music is playing.\n");
             break;
         MUS_MID:
             printf("MIDI music is playing.\n");
             break;
         MUS_OGG:
             printf("OGG music is playing.\n");
             break;
         MUS_MP3:
             printf("MP3 music is playing.\n");
             break;
         MUS_OPUS: // [Mixer 2.0]
             printf("OPUS music is playing.\n");
             break;
         MUS_GME: // [Mixer X]
             printf("Game Music Emulators music is playing.\n");
             break;
         MUS_ADLMIDI: // [Mixer X]
             printf("IMF/CMF/XMI music is playing\n");
             break;
         default:
             printf("Unknown music is playing.\n");
             break;
     }

See Also:

Mix_MusicType, Mix_SetPosition

Mix_PlayingMusicStream
----------------------

int Mix_PlayingMusicStream(Mix_Music *MUSIC)

music
     The music to get playing state.

     NULL will get the currently playing music playing state.

Tells you if MUSIC is actively playing, or not.

Note: Does not check if the channel has been paused.

Returns: Zero if the MUSIC is not playing, or 1 if it is playing.

     // check if music is playing
     printf("music is%s playing.\n", Mix_PlayingMusicStream(music)?"":" not");

See Also:

Mix_PausedMusicStream, Mix_FadingMusicStream, Mix_PlayMusicStream

Mix_PausedMusicStream
---------------------

int Mix_PausedMusicStream(Mix_Music *MUSIC)

music
     The music to get paused state.

     NULL will get the currently playing music paused state.

Tells you if MUSIC is paused, or not.

Note: Does not check if the MUSIC was been halted after it was paused, which may seem a little weird.

Returns: Zero if music is not paused.  1 if it is paused.

     // check the music pause status
     printf("music is%s paused\n", Mix_PausedMusicStream(music)?"":" not");

See Also:

Mix_PlayingMusicStream, Mix_PauseMusicStream, Mix_ResumeMusicStream

Mix_FadingMusicStream
---------------------

Mix_Fading Mix_FadingMusicStream(Mix_Music *MUSIC)

music
     The music to get fading state.

     NULL will get the currently playing music fading state.

Tells you if MUSIC is fading in, out, or not at all.  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 music fade status
     switch(Mix_FadingMusicStream(music)) {
         case MIX_NO_FADING:
             printf("Not fading music.\n");
             break;
         case MIX_FADING_OUT:
             printf("Fading out music.\n");
             break;
         case MIX_FADING_IN:
             printf("Fading in music.\n");
             break;
     }

See Also:

Mix_Fading, Mix_PausedMusicStream, Mix_PlayingMusicStream, Mix_FadeInMusicStreamPos, Mix_FadeOutMusicStream

Mix_GetMusicHookData
--------------------

void *Mix_GetMusicHookData()

Get the ARG passed into Mix_HookMusic.

Returns: the ARG pointer.

     // retrieve the music hook data pointer
     void *data;
     data=Mix_GetMusicHookData();

See Also:

Mix_HookMusic

Mix_PlayingMusic
----------------

int Mix_PlayingMusic()

Tells you if any single-stream music is actively playing, or not.

Note: Does not check if the channel has been paused.

Returns: Zero if the any single-stream music is not playing, or 1 if it is playing.

     // check if any single-stream music is playing
     printf("music is%s playing.\n", Mix_PlayingMusic()?"":" not");

See Also:

Mix_PausedMusic, Mix_FadingMusic, Mix_PlayMusic

Mix_PausedMusic
---------------

int Mix_PausedMusic()

Tells you if music is paused, or not.

Note: Does not check if the music was been halted after it was paused, which may seem a little weird.

Returns: Zero if music is not paused.  1 if it is paused.

     // check the music pause status
     printf("music is%s paused\n", Mix_PausedMusic()?"":" not");

See Also:

Mix_PlayingMusic, Mix_PauseMusic, Mix_ResumeMusic

Mix_FadingMusic
---------------

Mix_Fading Mix_FadingMusic()

Tells you if music is fading in, out, or not at all.  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 music fade status
     switch(Mix_FadingMusic()) {
         case MIX_NO_FADING:
             printf("Not fading music.\n");
             break;
         case MIX_FADING_OUT:
             printf("Fading out music.\n");
             break;
         case MIX_FADING_IN:
             printf("Fading in music.\n");
             break;
     }

See Also:

Mix_Fading, Mix_PausedMusic, Mix_PlayingMusic, Mix_FadeInMusicPos, Mix_FadeOutMusic

Mix_GetMusicTitle
-----------------

const char *Mix_GetMusicTitle(const Mix_Music *MUSIC)

Get MUSIC title from meta-tag if possible. If title tag is empty, filename will be returned unlike the Mix_GetMusicTitleTag() call.

Returns: the MUSIC title string pointer.

     // retrieve the music title meta-tag
     void *title;
     title=Mix_GetMusicTitle(myMusic);

See Also:

Mix_GetMusicTitleTag, Mix_GetMusicArtistTag, Mix_GetMusicAlbumTag, Mix_GetMusicCopyrightTag

Mix_GetMusicTitleTag
--------------------

const char *Mix_GetMusicTitleTag(const Mix_Music *MUSIC)

Get MUSIC title from meta-tag if possible. If title tag is empty, returns NULL

Returns: the MUSIC title string pointer or NULL.

     // retrieve the music title meta-tag
     void *title;
     title=Mix_GetMusicTitleTag(myMusic);

See Also:

Mix_GetMusicTitle, Mix_GetMusicArtistTag, Mix_GetMusicAlbumTag, Mix_GetMusicCopyrightTag

Mix_GetMusicArtistTag
---------------------

const char *Mix_GetMusicArtistTag(const Mix_Music *MUSIC)

Get MUSIC artist from meta-tag if possible. If artist tag is empty, returns NULL

Returns: the MUSIC artist string pointer or NULL.

     // retrieve the music artist meta-tag
     void *title;
     title=Mix_GetMusicArtistTag(myMusic);

See Also:

Mix_GetMusicTitle, Mix_GetMusicTitleTag, Mix_GetMusicAlbumTag, Mix_GetMusicCopyrightTag

Mix_GetMusicAlbumTag
--------------------

const char *Mix_GetMusicAlbumTag(const Mix_Music *MUSIC)

Get MUSIC album from meta-tag if possible. If album tag is empty, returns NULL

Returns: the MUSIC album string pointer or NULL.

     // retrieve the music album meta-tag
     void *title;
     title=Mix_GetMusicAlbumTag(myMusic);

See Also:

Mix_GetMusicTitle, Mix_GetMusicTitleTag, Mix_GetMusicArtistTag, Mix_GetMusicCopyrightTag

Mix_GetMusicCopyrightTag
------------------------

const char *Mix_GetMusicCopyrightTag(const Mix_Music *MUSIC)

Get MUSIC copyright from meta-tag if possible. If copyright tag is empty, returns NULL

Returns: the MUSIC copyright string pointer or NULL.

     // retrieve the music copyright meta-tag
     void *title;
     title=Mix_GetMusicCopyrightTag(myMusic);

See Also:

Mix_GetMusicTitle, Mix_GetMusicTitleTag, Mix_GetMusicArtistTag, Mix_GetMusicAlbumTag

Mix_SetTimidityCfg
------------------

int Mix_SetTimidityCfg(const char *PATH)

path
     Timidity config file path.

     Set the NULL to let Timidity use the default system paths by the internal logic.

The Timidity cfg file path which defines the set of patches used by the Timidity during playback.

Note: Takes no effect when no MIDI music files currently loaded by Timidity. To apply the config path change you should unload all MIDI music using Mix_FreeMusic() call and open them back again. Timidity doesn't support individual different patch sets per song.

Returns: 0 if success, -1 on failure.

     // change the timidity config path
     Mix_SetTimidityCfg("/home/user/Music/timidity_patches/mybank.cfg");

See Also:

Mix_GetTimidityCfg, Mix_PausedMusicStream, Mix_FadingMusicStream, Mix_PlayMusicStream

Mix_GetTimidityCfg
------------------

const char *Mix_GetTimidityCfg()

Reports the full path to the current config file. NULL if no custom config paths was set.

Returns: The full Timidity config file path or NULL.

See Also:

Mix_SetTimidityCfg, Mix_PausedMusicStream, Mix_FadingMusicStream, Mix_PlayMusicStream

Mix_SetSoundFonts
-----------------

int Mix_SetSoundFonts(const char *PATHS)

paths
     Semicolon separated paths to sound font files.

     NULL to use default sound font paths from environment.

Set the paths list to sound font files will be used by FluidSynth MIDI backend.

Returns: 1 if path successfully set, or 0 if error has occouped.

     if(Mix_SetSoundFonts("./myfonts/melodic.sf2;myfonts/drups.sf2")==0) {
         printf("Mix_SetSoundFonts: %s\n", Mix_GetError());
         // this might be a critical error...
     }

See Also:

Mix_GetSoundFonts, Mix_EachSoundFont, Mix_EachSoundFontEx

Mix_GetSoundFonts
-----------------

const char *Mix_GetSoundFonts()

paths
     Semicolon separated paths to sound font files.

     NULL to use default sound font paths from environment.

Get the current set of paths list to sound font files will be used by FluidSynth MIDI backend. If there are wasn't set by Mix_SetSoundFonts function, there are will be tooken from SDL_SOUNDFONTS or SDL_FORCE_SOUNDFONTS environment variables.

Returns: Semicolon-separated sound font paths.

     //Print list of available sound fonts
     char *context, *path = NULL;
     char *fonts = Mix_GetSoundFonts();
     printf("Available sound fonts:\n");
     for(path = strtok_r(fonts, ";", &context); path; path = strtok_r(NULL, ";", &context)) {
         printf(" - %s\n", path);
     }

See Also:

Mix_SetSoundFonts, Mix_EachSoundFont, Mix_EachSoundFontEx

Mix_EachSoundFont
-----------------

const char *Mix_EachSoundFont(int (*FUNCTION)(const char *, void *), void *DATA)

function
     The callback function will be called for each sound font listed in the paths. Has arguments PATH and DATA.

data
     User data passed to the callback

Iterate the current set of paths list to sound font files will be used by FluidSynth MIDI backend. If there are wasn't set by Mix_SetSoundFonts function, there are will be tooken from SDL_SOUNDFONTS or SDL_FORCE_SOUNDFONTS environment variables.

Returns: 1 if function successfully completed, or 0 if error has occouped.

     int print_sound_font(const char *path, void *data) {
         printf(" - %s\n", path);
         return 1;
     }

     //...

     //Print list of available sound fonts
     char *fonts = Mix_GetSoundFonts();
     printf("Available sound fonts:\n");
     for(!Mix_EachSoundFont(print_sound_font, NULL)) {
         printf(" - %s\n", path);
     }

See Also:

Mix_SetSoundFonts, Mix_GetSoundFonts, Mix_EachSoundFontEx

Mix_EachSoundFontEx
-------------------

const char *Mix_EachSoundFontEx(const char* CPATHS, int (*FUNCTION)(const char *, void *), void *DATA)

cpaths
     The semicolon-separated list of custom SoundFont file paths

function
     The callback function will be called for each sound font listed in the paths. Has arguments PATH and DATA.

data
     User data passed to the callback

Iterate the current set of internal paths list to sound font files will be used by FluidSynth MIDI backend, and additionally, iterate through the custom paths list given by the CPATHS argument. If there are wasn't set by Mix_SetSoundFonts function, there are will be tooken from SDL_SOUNDFONTS or SDL_FORCE_SOUNDFONTS environment variables.

Returns: 1 if function successfully completed, or 0 if error has occouped.

     int print_sound_font(const char *path, void *data) {
         printf(" - %s\n", path);
         return 1;
     }

     //...

     //Print list of available sound fonts
     char *fonts = Mix_GetSoundFonts();
     char *other_fonts = "/path/to/font1.sf2:/path/to/font2.sf2:/path/to/fontN.sf2";
     printf("Available sound fonts:\n");
     for(!Mix_EachSoundFontEx(other_fonts, print_sound_font, NULL)) {
         printf(" - %s\n", path);
     }

See Also:

Mix_SetSoundFonts, Mix_GetSoundFonts, Mix_EachSoundFont

Mix_ADLMIDI_getTotalBanks
-------------------------

int Mix_ADLMIDI_getTotalBanks()

Returns: Total count of embedded ADLMIDI banks.

Get total count of available embedded banks.

Mix_ADLMIDI_getBankNames
------------------------

const char *const * Mix_ADLMIDI_getBankNames()

Returns: array of strings are names of embedded ADLMIDI banks.

Get array of embedded bank titles.

Mix_ADLMIDI_getBankID
---------------------

int Mix_ADLMIDI_getBankID()

Returns: currently using ID of embedded ADLMIDI bank.

Get currently using ID of embedded ADLMIDI bank.

Mix_ADLMIDI_setBankID
---------------------

void Mix_ADLMIDI_setBankID(int BNK)

bnk
     Embedded ADLMIDI bank ID

Change current embedded ADLMIDI bank. NOTE: Applies on MIDI file reopen

Mix_ADLMIDI_getTremolo
----------------------

int Mix_ADLMIDI_getTremolo()

Returns: 0 if Deep Tremolo is inactive, or 1 if Deep Tremolo is activated.

Get current state of "Deep Tremolo" OPL3 flag in ADLMIDI.

Mix_ADLMIDI_setTremolo
----------------------

void Mix_ADLMIDI_setTremolo(int TR)

tr
     State of Deep Tremolo flag: 0 if Deep Tremolo is inactive, or 1 if Deep Tremolo is activated

Set state of "Deep Tremolo" OPL3 flag. NOTE: Applies on MIDI file reopen

Mix_ADLMIDI_getVibrato
----------------------

int Mix_ADLMIDI_getVibrato()

Returns: 0 if Deep Vibrato is inactive, or 1 if Deep Vibrato is activated.

Get current state of "Deep Vibrato" OPL3 flag in ADLMIDI.

Mix_ADLMIDI_setVibrato
----------------------

void Mix_ADLMIDI_setVibrato(int VIB)

vib
     State of Deep Vibrato flag: 0 if Deep Vibrato is inactive, or 1 if Deep Vibrato is activated

Set state of "Deep Vibrato" OPL3 flag. NOTE: Applies on MIDI file reopen

Mix_ADLMIDI_getScaleMod
-----------------------

int Mix_ADLMIDI_getScaleMod()

Returns: 0 if Scalable Modulation is inactive, or 1 if Scalable Modulation is activated.

Get current state of "Scalable modulation mode" flag

Mix_ADLMIDI_setScaleMod
-----------------------

void Mix_ADLMIDI_setScaleMod(int SC)

sc
     State of Scalable Modulation flag: 0 if Scalable Modulation is inactive, or 1 if Scalable Modulation is activated

Turn on/off scalable modulation mode flag. NOTE: Applies on MIDI file reopen

Mix_ADLMIDI_getVolumeModel
--------------------------

int Mix_ADLMIDI_getVolumeModel()

Returns: value of Mix_ADLMIDI_VolumeModel enum which a current volume model.

Get ID of current volumes model of ADLMIDI

Mix_ADLMIDI_setVolumeModel
--------------------------

void Mix_ADLMIDI_setVolumeModel(int VM)

vm
     Value of Mix_ADLMIDI_VolumeModel enum.

Change current volume model. NOTE: Applies on MIDI file reopen

Mix_ADLMIDI_getFullRangeBrightness
----------------------------------

int Mix_ADLMIDI_getFullRangeBrightness()

Returns: 0 when full-ranged CC74 is disabled, or 1 when full-ranged mode of CC74 is enabled

Get full range mode for CC74-Brightness controller

Mix_ADLMIDI_setFullRangeBrightness
----------------------------------

void Mix_ADLMIDI_setFullRangeBrightness(int FRB)

frb
     0 to disable full-ranged CC74, or 1 to enable full-ranged mode of CC74

Set full range mode for CC74-Brightness controller NOTE: Applies on MIDI file reopen

Mix_ADLMIDI_getAutoArpeggio
---------------------------

int Mix_ADLMIDI_getAutoArpeggio()

Returns: 0 when automatic arpeggio disabled, or 1 when automatic arpeggio is enabled

Get the automatic apreggion enable/disable setting state

Mix_ADLMIDI_setAutoArpeggio
---------------------------

void Mix_ADLMIDI_setAutoArpeggio(int AA_EN)

aa_en
     0 to disable the automatic arpeggio, or 1 to enable automatic arpeggio

Set the automatic apreggion enable/disable setting state NOTE: Applies on MIDI file reopen

Mix_ADLMIDI_getFullPanStereo
----------------------------

int Mix_ADLMIDI_getFullPanStereo()

Returns: 0 when full panning stereo is disabled, or 1 when full panning stereo is enabled

Get full panning stereo mode

Mix_ADLMIDI_setFullPanStereo
----------------------------

void Mix_ADLMIDI_setFullPanStereo(int FP)

fp
     0 to disable full panning stereo, or 1 to enable full panning stereo

Set full panning stereo mode NOTE: Applies on MIDI file reopen

Mix_ADLMIDI_getEmulator
-----------------------

int Mix_ADLMIDI_getEmulator()

Returns: value of Mix_ADLMIDI_Emulator enum which a current OPL3 emulator.

Get ID of current OPL3 emulator of ADLMIDI

Mix_ADLMIDI_setEmulator
-----------------------

void Mix_ADLMIDI_setVolumeModel(int EMU)

emu
     Value of Mix_ADLMIDI_Emulator enum.

Select the default OPL3 Emulator for ADLMIDI used for every new MIDI file opened.

Note: Using path arguments may override this setting.

Mix_ADLMIDI_getChipsCount
-------------------------

int Mix_ADLMIDI_getChipsCount()

Returns: initial number of emulated chips running by ADLMIDI.

Get the number of emulated chips used by ADLMIDI for every new MIDI file opened.

Mix_ADLMIDI_setChipsCount
-------------------------

void Mix_ADLMIDI_setChipsCount(int CHIPS)

chips
     Number of emulated chips.

Get the number of emulated chips used by ADLMIDI for every new MIDI file opened.

Note: Using path arguments may override this setting.

Mix_ADLMIDI_setSetDefaults
--------------------------

void Mix_ADLMIDI_setSetDefaults()

Resets all settings of ADLMIDI into default state. NOTE: Applies on MIDI file reopen

Mix_ADLMIDI_setCustomBankFile
-----------------------------

void Mix_ADLMIDI_setCustomBankFile(const char *BANK_WONL_PATH)

bank_wonl_path
     Path to custom WOPL bank or NULL to use embedded banks.

Sets path to custom WOPL bank file. NOTE: Applies on MIDI file reopen

     //Set custom ADLMIDI bank
     Mix_ADLMIDI_setCustomBankFile("./music/my-gm-bank.wonl");

Mix_OPNMIDI_getVolumeModel
--------------------------

int Mix_OPNMIDI_getVolumeModel()

Returns: value of Mix_OPNMIDI_VolumeModel enum which a current volume model.

Get ID of current volumes model of OPNMIDI

Mix_OPNMIDI_setVolumeModel
--------------------------

void Mix_OPNMIDI_setVolumeModel(int VM)

vm
     Value of Mix_OPNMIDI_VolumeModel enum.

Change current volume model. NOTE: Applies on MIDI file reopen

Mix_OPNMIDI_getFullRangeBrightness
----------------------------------

int Mix_OPNMIDI_getFullRangeBrightness()

Returns: 0 when full-ranged CC74 is disabled, or 1 when full-ranged mode of CC74 is enabled

Get full range mode for CC74-Brightness controller

Mix_OPNMIDI_setFullRangeBrightness
----------------------------------

void Mix_OPNMIDI_setFullRangeBrightness(int FRB)

frb
     0 to disable full-ranged CC74, or 1 to enable full-ranged mode of CC74

Set full range mode for CC74-Brightness controller NOTE: Applies on MIDI file reopen

Mix_OPNMIDI_getAutoArpeggio
---------------------------

int Mix_OPNMIDI_getAutoArpeggio()

Returns: 0 when automatic arpeggio disabled, or 1 when automatic arpeggio is enabled

Get the automatic apreggion enable/disable setting state

Mix_OPNMIDI_setAutoArpeggio
---------------------------

void Mix_OPNMIDI_setAutoArpeggio(int AA_EN)

aa_en
     0 to disable the automatic arpeggio, or 1 to enable automatic arpeggio

Set the automatic apreggion enable/disable setting state NOTE: Applies on MIDI file reopen

Mix_OPNMIDI_getFullPanStereo
----------------------------

int Mix_OPNMIDI_getFullPanStereo()

Returns: 0 when full panning stereo is disabled, or 1 when full panning stereo is enabled

Get full panning stereo mode

Mix_OPNMIDI_setFullPanStereo
----------------------------

void Mix_OPNMIDI_setFullPanStereo(int FP)

fp
     0 to disable full panning stereo, or 1 to enable full panning stereo

Set full panning stereo mode NOTE: Applies on MIDI file reopen

Mix_OPNMIDI_getEmulator
-----------------------

int Mix_OPNMIDI_getEmulator()

Returns: value of Mix_OPNMIDI_Emulator enum which a current OPN2 emulator.

Get ID of current OPN2 emulator of OPNMIDI

Mix_OPNMIDI_setEmulator
-----------------------

void Mix_OPNMIDI_setVolumeModel(int EMU)

emu
     Value of Mix_OPNMIDI_Emulator enum.

Select the OPN2 Emulator for OPNMIDI NOTE: Applies on MIDI file reopen

Mix_OPNMIDI_getChipsCount
-------------------------

int Mix_OPNMIDI_getChipsCount()

Returns: initial number of emulated chips running by OPNMIDI.

Get the number of emulated chips used by OPNMIDI for every new MIDI file opened.

Mix_OPNMIDI_setChipsCount
-------------------------

void Mix_OPNMIDI_setChipsCount(int CHIPS)

chips
     Number of emulated chips.

Get the number of emulated chips used by OPNMIDI for every new MIDI file opened.

Note: Using path arguments may override this setting.

Mix_OPNMIDI_setSetDefaults
--------------------------

void Mix_OPNMIDI_setSetDefaults()

Resets all settings of OPNMIDI into default state. NOTE: Applies on MIDI file reopen

Mix_OPNMIDI_setCustomBankFile
-----------------------------

void Mix_OPNMIDI_setCustomBankFile(const char *BANK_WONP_PATH)

bank_wonp_path
     Path to custom WOPN bank or NULL to use default bank.

Sets path to custom WOPN bank file. NOTE: Applies on MIDI file reopen

     //Set custom OPNMIDI bank
     Mix_OPNMIDI_setCustomBankFile("./music/my-gm-bank.wonp");

Music Arguments
---------------

Also known as a Path arguments. This is a special formatted string that can be concoctated with the music file path using the | separator, or being passed as a dedicated argument. There are individual music properties given to it during the load time. Using these arguments you can choose the track to play (suitable for files that contains multiple songs inside the same file), or select the MIDI synthesizer or its porperties and a banks or SoundFont paths, etc.

     Depending on the music format and the codec library there are different arguments supported

Game music emulators
     The first argument - an integer from 0 to n - a number of the track from multi-track file formats like NSF, NSFE, HES, GBS, etc.

     Example 1 of the music path with music arguments given:

          /path/to/mymusic.nsf|21

     Example 2 of the music path with music arguments given:

          /path/to/mymusic.nsf|21;g=1.0;t=1.0;

     Example music arguments strings to be sent as a dedicated argument:

          21;g=1.0;t=1.0;

     All arguments after the first integer are optional. The leading integer is required, even it's a single-track file. The last argument must be closed with semicolon.

     t=
          Initial tempo factor (1.0 is the default value, accepting positive floating-point number values, for example, t=1.75;), increase or decrease the initial tempo of the song.

     g=
          Gain factor (1.0 is the default value, accepting positive floating-point number values, for example, g=1.75;), increase or decrease the volume level of the song. Use it to increase the volume of too silent songs, or decrease the volume of too loud songs.

MIDI
     Accepts a list of letter-marked integer arguments separated by semicolons.

     Example 1 of the music path with music arguments given:

          mymusic.mid|s0;b62;t0;v0;a0;m0;t=1.0;g=2.0;x=/path/to/bank1.wopl;

     Example 2 of the music path with music arguments given:

          mymusic.mid|s4;r1;rr0.2;rd0.4;rw0.9;rl0.8;c1;cn10;cl4.2;cs3.5;p256;t=1.0;g=1.0;x=/path/to/bank1.sf2&/path/to/bank2.sf2&/path/to/bank3.sf2;

     Example music arguments strings to be sent as a dedicated argument:

          s0;b62;t0;v0;a0;m0;t=1.0;g=2.0;x=/path/to/bank1.wopl;

     All arguments are optional. The last argument must be closed with semicolon.

     s
          Synthesizer type:

          0 - ADLMIDI, emulated OPL3 (YMF262) synthesizer with loop tags and System Exclusive Messages support. Working by Default. (Recorded examples to listen to are presented here). OPL3 chip was widely used on PC sound cards in 80/90'th years.

          1 - Timidity, requires the set of patches to be properly installed (can be customized with Mix_SetTimidityCfg function).

          2 - Native MIDI, uses the default operating system MIDI interface.

          3 - OPNMIDI, emulated OPN2 (YM2612) synthesizer with loop tags and System Exclusive Messages support. OPN2 chip is used on the Sega MegaDrive / Genesis game console.

          4 - FluidSynth, the WaveTable MIDI synthesizer with SoundFont banks support, has the support for loop tags support.

          Example:

                   s3;

     General flags:

          t=
               ADLMIDI, OPNMIDI, and FluidSynth

               Initial tempo factor (1.0 is the default value, accepting positive floating-point number values, for example, t=1.75;), increase or decrease the initial tempo of the song. Don't confuse with t0 and t1 which is a different setting.

               Example:

                        t=1.4;

          g=
               ADLMIDI, OPNMIDI, and FluidSynth

               Gain factor (2.0 is the default value, accepting positive floating-point number values, for example, g=1.75;), increase or decrease the volume level of the song. Use it to increase the volume of too silent songs, or decrease the volume of too loud songs.

               Example:

                        g=5.5;

     ADLMIDI and OPNMIDI:

          b
               ADLMIDI

               Set bank ID (look for available banks list into PGE MusPlay application to preview them). Default is 58.

               Example:

                        b72;

          t
               ADLMIDI

               Deep tremolo (1 or 0, or -1 an auto-mode), increase the amplitude of tremolo effect for instruments that are using tremolo OPL flag. Default -1. Don't confuse with t= which is a different setting.

               Example:

                        t1;

          v
               ADLMIDI

               Deep vibrato (1 or 0, or -1 an auto-mode), increase the amplitude of vibrato effect for instruments that are using vibrato OPL flag. Default -1.

               Example:

                        v1;

          m
               ADLMIDI

               Enables scalable modulation (1 or 0), Allows dynamic scaling of the modulator result with volume. Default 0.

               Example:

                        m1;

          c
               ADLMIDI AND OPNMIDI

               Count of chip emulators are allowing to excite limit of voice channels. Default 4 for ADLMIDI and 8 for OPNMIDI. Allowed value from 1 to 100.

               Example:

                        c2;

          f
               ADLMIDI

               Count of four-operator channels between all chip emulators (6 channels maximum per every chip. For example, you have used 2 chips, you can have 12 four-op channels maximum).

               Example:

                        f8;

          j
               ADLMIDI AND OPNMIDI

               Enable or disable the automatic arpeggio (1 or 0). Default 1.

               Example:

                        j0;

          l
               ADLMIDI AND OPNMIDI

               Volume scaling model code (0 - auto, 1 - Generic, - 2 OPL3-Native, 3 - DMX, 4 - Apogee, - 5 - Win9X-like) - an algorithm to scale a volume level, affects music expressionism.

               Example:

                        l1;

          r
               ADLMIDI AND OPNMIDI

               Use full-ranged CC74 Brightness MIDI controller (1 or 0). Default 0.

               Example:

                        r1;

          p
               ADLMIDI AND OPNMIDI

               Enable full-panning stereo support (1 or 0). Default 1.

               Example:

                        p0;

          e
               ADLMIDI

               Choose OPL3 emulator: 0 - Nuked OPL3 (Very accurate, may lag on older CPUs), 1 - Nuked OPL3 1.7.4 that was optimized by Troosh, and 2 - DosBox 0.74 (Well-accurate, fastest).

               Example:

                        e2;

          e
               OPNMIDI

               Choose OPN2 emulator: 0 - Mame YM2612 (Well-accurate, fast), 1 - Nuked OPN2 (Very accurate, requires VERY powerful CPU. Suggested to use up to 2 chips max with it), 2 - GENS 2.10 (Very outdated, inaccurate, but fastest)

               Example:

                        e2;

          x=
               ADLMIDI and OPNMIDI

               Load custom bank file by absolute path (WOPN bank for OPNMIDI or WOPL for ADLMIDI). Accepting strings without quotes.

               Example:

                        x=/path/to/bank/file.wopn;

     FluidSynth:

          r
               FluidSynth

               Enable or disable the reverb effect: 0 - disabled, 1 - enabled.

               Example:

                        r1;

          rr
               FluidSynth

               Reverb room size value (0.0-1.0).

               Example:

                        rr0.2;

          rd
               FluidSynth

               Reverb damping value (0.0-1.0).

               Example:

                        rd0.4;

          rw
               FluidSynth

               Reverb width value (0.0-100.0).

               Example:

                        rw0.9;

          rl
               FluidSynth

               Reverb level value (0.0-1.0).

               Example:

                        rl0.8;

          c
               FluidSynth

               Enable or disable the chorus effect: 0 - disabled, 1 - enabled.

               Example:

                        c1;

          cn
               FluidSynth

               Chorus voice count (0-99, CPU time consumption proportional to this value).

               Example:

                        cn10;

          cl
               FluidSynth

               Chorus level (0.0-10.0).

               Example:

                        cl4;

          cs
               FluidSynth

               Chorus speed in Hz (0.1-5.0).

               Example:

                        cs3.5;

          cd
               FluidSynth

               Chorus depth (max value depends on synth sample-rate, 0.0-21.0 is safe for sample-rate values up to 96KHz).

               Example:

                        cd10.1;

          ct
               FluidSynth

               Chorus waveform type: 0 - Sine, 1 - Triangle.

               Example:

                        ct1;

          p
               FluidSynth

               Define the allowed polyphony (8-512).

               Example:

                        p256;

          x=
               FluidSynth

               Load custom SoundFont files by absolute path. Accepting strings without quotes, for example, x=/path/to/bank/file.sf2;. You can specify multiple SoundFont files by using an ampersand separator: x=/p/file1.sf2&/p/file2.sf2&/p/filen.sf2;

               Example:

                        x=/p/file1.sf2&/p/file2.sf2&/p/filen.sf2;

See Also:

Mix_LoadMUS, Mix_LoadMUS_RW_ARG, Mix_LoadMUSType_RW_ARG