pygame documentation | || Home || Help Contents || || pygame || cdrom || constants || cursor || display || draw || || event || font || image || joystick || key || mixer || || mixer_music || mouse || movie || sndarray || surfarray || time || || transform || || CD || Channel || Clock || Font || Joystick || Movie || || Overlay || Rect || Sound || Surface || || color || cursors || sprite ||

## pygame.mixer

Contains sound mixer routines and objects. The mixer module is an optional pygame module, dependent on the SDL_mixer library. This module contains the usual routines needed to initialize the module. One difference is the pygame.mixer.init() function takes several optional arguments. These arguments control the playback rates and datatypes for the sound playback. If you do need specific control over the playback rate, but don't want to bother with hand-initializing the modules, there is a function named pygame.mixer.pre_init() which takes the same arguments as init(), but only sets the new default values. You can call this before pygame.init() and not have to worry about the pygame module initialization order.
Sound objects are created from the pygame.mixer.Sound() function. Simple sound playback can simply use the Sound.play() method to play the sound. Each Sound object can be played multiple times simultaneously. If you desire more specific control over the Sound objects, you can access the Channel objects with functions like pygame.mixer.Channel().
The mixer defaults to supporting 8 simultaneous soundfiles. You can change the number of available sound channels at any time with the set_num_channels() function.
All loaded Sound objects are resampled to match the same format that pygame.mixer is initialized to. The current SDL resampling functions are not that good, so it is best if you initialize pygame.mixer to the same format as your sound resources. Also setting the mixer frequency to even multiples of your sound resources will result in a cleaner conversion.
The mixer also contains a special channel for music. You can control the music channel through pygame.mixer.music.

Channel | - get channel object
Sound | - load a new soundfile
fadeout | - fadeout all channels
find_channel | - find an available sound channel
get_busy | - query busy channels
get_init | - query initialization for the mixer
get_num_channels | - query the number of channels
init | - initialize mixer module
pause | - pause all channels
pre_init | - presets the init default values
quit | - unitializes the mixer
set_num_channels | - sets the number of available channels
set_reserved | - reserves first given channels
stop | - stop all channels
unpause | - restart any pause channels

Channel
`pygame.mixer.Channel(int) -> Channel`

Get a channel object for the given channel. This number must be less that the current number of channels.

Sound
`pygame.mixer.Sound(file) -> Sound`

Loads a new sound object from a WAV file. File can be a filename or a file-like object. The sound will be converted to match the current mode of the mixer.

fadeout
`pygame.mixer.fadeout(millisec) -> None`

Fade out all the playing channels over the given number of milliseconds.

find_channel
`pygame.mixer.find_channel([force]) -> Channel`

Find a sound channel that is not busy. If the force argument is passed as a nonzero number, this will return the channel of the longest running sound. If not forced, and there are no available channels, returns None.

get_busy
`pygame.mixer.get_busy() -> int`

Returns the number of current active channels. This is not the total channels, but the number of channels that are currently playing sound.

get_init
`pygame.mixer.get_init() -> (frequency,format,stereo)`

Returns a tuple containing the initialized state of the mixer module. If the module has not been initialized, it will return None.

get_num_channels
`pygame.mixer.get_num_channels() -> int`

Gets the current number of channels available for the mixer. This value can be changed with set_num_channels(). This value defaults to 8 when the mixer is first initialized.

init
`pygame.mixer.init([freq, [size, [stereo, [buffersize]]]]) -> None`

Initializes the mixer module. Usually no arguments will be needed, the defaults are 22050 frequency data in stereo with signed 16bit data. The size argument can be 8 or 16 for unsigned data, or -8 or -16 for signed data. The default buffersize is 1024 samples, sometimes a larger value is required.
The stereo argument is either 1 or 2 to represent mono or stereo. Pygame does not support more than 2 channel stereo.
On some platforms it is important that the display module is initialized before the audio. (that is, if the display will be initialized at all). You can easily use the pygame.init() function to cleanly initialize everything, but first use the pygame.mixer.pre_init() function to change the default values for this init().

pause
`pygame.mixer.pause() -> None`

Temporarily stops playback on all the mixer channels.

pre_init
`pygame.mixer.pre_init([freq, [size, [stereo, [buffersize]]]]) -> None`

This routine is usefull when you want to customize the sound mixer playback modes. The values you pass will change the default values used by pygame.mixer.init(). This way you can still use the pygame automatic initialization to ensure everything happens in the right order, but set the desired mixer mode.
The stereo argument is either 1 or 2 to represent mono or stereo. Pygame does not support more than 2 channel stereo.

quit
`pygame.mixer.quit() -> None`

This will stop all playing sounds and uninitialize the mixer module

set_num_channels
`pygame.mixer.set_num_channels(int) -> None`

Sets the current number of channels available for the mixer. This value defaults to 8 when the mixer is first initialized. If the value is decreased, sounds playing in channels above the new value will stop.

set_reserved
`pygame.mixer.set_reserved(numchans) -> None`

Reserves numchan channels. Reserved channels won't be used when a sound is played without using a specific channel object. In otherwords, just calling Sound.play() will not use the reserved channels. They must implicitly be used with Channel.play().

stop
`pygame.mixer.stop() -> None`

Stop the playback on all mixer channels.

unpause
`pygame.mixer.unpause() -> None`

Restarts playback of any paused channels.