cocos.audio.SDL.mixer module

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.

class Mix_Chunk

Bases: _ctypes.Structure

Internal format for an audio chunk.

Ivariables
allocatedint

Undocumented.

abufSDL_array

Buffer of audio data

alenint

Length of audio buffer

volumeint

Per-sample volume, in range [0, 128]

alen

Structure/Union member

allocated

Structure/Union member

volume

Structure/Union member

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_finishedfunction

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

Mix_FadeInChannel(channel, chunk, loops, ms)

Fade in a channel.

Parameters
channelint

If -1, play on the first free channel.

chunkMix_Chunk

Chunk to play

loopsint

If greater than zero, the number of times to play the sound; if -1, loop infinitely.

msint

Number of milliseconds to fade up over.

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_funcfunction

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.

udataany

A variable that is passed to the mix_func function each call.

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_finishedfunction

The callback takes no arguments and returns no value.

Mix_LoadWAV(file)

Load a WAV, RIFF, AIFF, OGG or VOC file.

Parameters
filestring

Filename to load.

Return type

Mix_Chunk

Mix_PlayChannel(channel, chunk, loops)

Play an audio chunk on a specific channel.

Parameters
channelint

If -1, play on the first free channel.

chunkMix_Chunk

Chunk to play

loopsint

If greater than zero, the number of times to play the sound; if -1, loop infinitely.

Return type

int

Returns

the channel that was used to play the sound.

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.

Return type

(int, int, int, int)

Returns

(opened, frequency, format, channels)

Mix_QuickLoad_RAW(mem)

Load raw audio data of the mixer format from a sequence or SDL_array.

Parameters
  • mem: sequence or SDL_array

Return type

Mix_Chunk

Mix_QuickLoad_WAV(mem)

Load a wave file of the mixer format from a sequence or SDL_array.

Parameters
  • mem: sequence or SDL_array

Return type

Mix_Chunk

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
chanint

Channel to set effect on, or MIX_CHANNEL_POST for postmix.

ffunction

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.

dfunction

Callback function for when the effect is done. The function must have the signature (channel: int, udata: any) -> None.

argany

User data passed to both callbacks.

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_funcfunction

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.

udataany

A variable that is passed to the mix_func function each call.