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.StructureInternal 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.