# Module cocos.audio.SDL.mixer

A simple multi-channel audio mixer.

It supports 8 channels of 16 bit stereo audio, plus a single channel of music, mixed by MidMod MOD, Timidity MIDI or SMPEG MP3 libraries.

The mixer can currently load Microsoft WAVE files and Creative Labs VOC files as audio samples, and can load MIDI files via Timidity and the following music formats via MikMod: MOD, S3M, IT, XM. It can load Ogg Vorbis streams as music if built with the Ogg Vorbis libraries, and finally it can load MP3 music using the SMPEG library.

The process of mixing MIDI files to wave output is very CPU intensive, so if playing regular WAVE files sounds great, but playing MIDI files sounds choppy, try using 8-bit audio, mono audio, or lower frequencies.

Note: The music stream does not resample to the required audio rate. You must call Mix_OpenAudio with the sampling rate of your music track.

## Classes

| Mix_Chunk Internal format for an audio chunk.

## Functions

(int, int, int, int) | Mix_QuerySpec() Find out what the actual audio device parameters are.
Mix_Chunk | Mix_LoadWAV(file) Load a WAV, RIFF, AIFF, OGG or VOC file.
Mix_Chunk | Mix_QuickLoad_WAV(mem) Load a wave file of the mixer format from a sequence or SDL_array.
Mix_Chunk | Mix_QuickLoad_RAW(mem) Load raw audio data of the mixer format from a sequence or SDL_array.
| Mix_SetPostMix(mix_func, udata) Set a function that is called after all mixing is performed.
| Mix_HookMusic(mix_func, udata) Add your own music player or additional mixer function.
| Mix_HookMusicFinished(music_finished) Add your own callback when the music has finished playing.
| Mix_ChannelFinished(channel_finished) Add your own callback when a channel has finished playing.
| Mix_RegisterEffect(chan, f, d, arg) Register a special effect function.
int | Mix_PlayChannel(channel, chunk, loops) Play an audio chunk on a specific channel.
| Mix_FadeInChannel(channel, chunk, loops, ms) Fade in a channel.

## Variables

| __package__ = ``'``cocos.audio.SDL``'``

## Function Details

### Mix_QuerySpec

Mix_QuerySpec()

Find out what the actual audio device parameters are.

The function returns a tuple giving each parameter value. The first value is 1 if the audio has been opened, 0 otherwise.

Returns:
  (int, int, int, int): (opened, frequency, format, channels)

### Mix_LoadWAV

Mix_LoadWAV(file)
Load a WAV, RIFF, AIFF, OGG or VOC file.

Parameters:
  file : string
    Filename to load.
Returns: Mix_Chunk

### Mix_QuickLoad_WAV

Mix_QuickLoad_WAV(mem)
Load a wave file of the mixer format from a sequence or SDL_array.

Parameters:
  mem
    : sequence or SDL_array
Returns: Mix_Chunk

### Mix_QuickLoad_RAW

Mix_QuickLoad_RAW(mem)
Load raw audio data of the mixer format from a sequence or SDL_array.

Parameters:
  mem
    : sequence or SDL_array
Returns: Mix_Chunk

### Mix_SetPostMix

Mix_SetPostMix(mix_func, udata)

Set a function that is called after all mixing is performed.

This can be used to provide real-time visual display of the audio stream or add a custom mixer filter for the stream data.

:Parameters
  `mix_func` : function
    The function must have the signature (stream: SDL_array, udata: any) -> None. The first argument is the array of audio data that may be modified in place. `udata` is the value passed in this function.
  `udata` : any
    A variable that is passed to the `mix_func` function each call.

### Mix_HookMusic

Mix_HookMusic(mix_func, udata)

Add your own music player or additional mixer function.

If `mix_func` is None, the default music player is re-enabled.

:Parameters
  `mix_func` : function
    The function must have the signature (stream: SDL_array, udata: any) -> None. The first argument is the array of audio data that may be modified in place. `udata` is the value passed in this function.
  `udata` : any
    A variable that is passed to the `mix_func` function each call.

### Mix_HookMusicFinished

Mix_HookMusicFinished(music_finished)

Add your own callback when the music has finished playing.

This callback is only called if the music finishes naturally.

Parameters:
  music_finished : function
    The callback takes no arguments and returns no value.

### Mix_ChannelFinished

Mix_ChannelFinished(channel_finished)

Add your own callback when a channel has finished playing.

The callback may be called from the mixer's audio callback or it could be called as a result of Mix_HaltChannel, etc.

Do not call SDL_LockAudio from this callback; you will either be inside the audio callback, or SDL_mixer will explicitly lock the audio before calling your callback.

Parameters:
  channel_finished : function
    The function takes the channel number as its only argument, and returns None. Pass None here to disable the callback.

### Mix_RegisterEffect

Mix_RegisterEffect(chan, f, d, arg)

Register a special effect function.

At mixing time, the channel data is copied into a buffer and passed through each registered effect function. After it passes through all the functions, it is mixed into the final output stream. The copy to buffer is performed once, then each effect function performs on the output of the previous effect. Understand that this extra copy to a buffer is not performed if there are no effects registered for a given chunk, which saves CPU cycles, and any given effect will be extra cycles, too, so it is crucial that your code run fast. Also note that the data that your function is given is in the format of the sound device, and not the format you gave to Mix_OpenAudio, although they may in reality be the same. This is an unfortunate but necessary speed concern. Use Mix_QuerySpec to determine if you can handle the data before you register your effect, and take appropriate actions.

You may also specify a callback (`d`) that is called when the channel finishes playing. This gives you a more fine-grained control than Mix_ChannelFinished, in case you need to free effect-specific resources, etc. If you don't need this, you can specify None.

You may set the callbacks before or after calling Mix_PlayChannel.

Things like Mix_SetPanning are just internal special effect functions, so if you are using that, you've already incurred the overhead of a copy to a separate buffer, and that these effects will be in the queue with any functions you've registered. The list of registered effects for a channel is reset when a chunk finishes playing, so you need to explicitly set them with each call to `Mix_PlayChannel*`.

You may also register a special effect function that is to be run after final mixing occurs. The rules for these callbacks are identical to those in Mix_RegisterEffect, but they are run after all the channels and the music have been mixed into a single stream, whereas channel-specific effects run on a given channel before any other mixing occurs. These global effect callbacks are call "posteffects". Posteffects only have their `d` function called when they are unregistered (since the main output stream is never "done" in the same sense as a channel). You must unregister them manually when you've had enough. Your callback will be told that the channel being mixed is (MIX_CHANNEL_POST) if the processing is considered a posteffect.

After all these effects have finished processing, the callback registered through Mix_SetPostMix runs, and then the stream goes to the audio device.

Do not call SDL_LockAudio from your callback function.

Parameters:
  chan : int
    Channel to set effect on, or MIX_CHANNEL_POST for postmix.
  f : function
    Callback function for effect. Must have the signature (channel: int, stream: SDL_array, udata: any) -> None; where channel is the channel being affected, stream contains the audio data and udata is the user variable passed in to this function.
  d : function
    Callback function for when the effect is done. The function must have the signature (channel: int, udata: any) -> None.
  arg : any
    User data passed to both callbacks.

### Mix_PlayChannel

Mix_PlayChannel(channel, chunk, loops)
Play an audio chunk on a specific channel.

Parameters:
  channel : int
    If -1, play on the first free channel.
  chunk : Mix_Chunk
    Chunk to play
  loops : int
    If greater than zero, the number of times to play the sound; if -1, loop infinitely.
Returns:
  int: the channel that was used to play the sound.

### Mix_FadeInChannel

Mix_FadeInChannel(channel, chunk, loops, ms)
Fade in a channel.

Parameters:
  channel : int
    If -1, play on the first free channel.
  chunk : Mix_Chunk
    Chunk to play
  loops : int
    If greater than zero, the number of times to play the sound; if -1, loop infinitely.
  ms : int
    Number of milliseconds to fade up over.