pygame2.sdlmixer – basic SDL_mixer wrapper module

Note

Do not use pygame2.sdlmixer and pygame2.sdl.audio at the same time. As they both deal with audio hardware access, this can lead to problems and weird behaviour.

Module Functions

pygame2.sdlmixer.close_audio() → None

Closes an opened instance of the audio hardware.

Use query_spec() to detect how often close_audio() has to be called.

After calling this function (often enough), you should not invoke any SDL_mixer related class, method or function as they are likely to fail or might give unpredictable results.

pygame2.sdlmixer.get_compiled_version() -> (int, int, int)

Gets the SDL_mixer version pygame2 was compiled against as three-value tuple.

This version is built at compile time. It can be used to detect which features may not be available through Pygame, if it is used as precompiled package using a different version of the SDL_mixer library.

pygame2.sdlmixer.get_error() → str

Gets the last SDL_mixer error message occured.

SDL_mixer maintains an internal error message. This message will usually be given to you when a pygame2.Error is raised.

You will rarely need to call this function.

pygame2.sdlmixer.get_version() -> (int, int, int)

Gets the SDL_mixer version pygame2 currently uses as three-value tuple.

This version is detected at runtime. It can be used to detect which features may not be available through Pygame, if it is used as precompiled package using a different version of the SDL_mixer library.

pygame2.sdlmixer.init([flags]) → int

Initializes the underlying SDL_mixer library.

Initializes the underlying SDL_mixer library using the passed mixer flags. The flags indicate, which music library (FLAC, OGG, ...) SDL_mixer should initialize and can be a bitwise combination of the initialization constants of the pygame2.sdlmixer.constants module.

In case an error occured, an exception will be raised.

pygame2.sdlmixer.open_audio(frequency, format, channels, chunksize) → None

Initializes the mixer API and prepares the audio hardware for access.

This must be called before using any other method or class for audio output. It initializes the API with a certain frequency (e.g. 44100 for 44.1 KHz).

format is the sample format that will be used in the Chunk and Music objects and can be one of the AUDIO_XXX constants.

channels denotes the number of output channels, not the number of Channel instances and can be 1 for mono or 2 for stereo sound.

chunksize is the size of bytes used per output sample to stream. The larger the value, the more often the output hooks will be called. A good value for chunksize is between 1024 and 4096 on most computers (1kB - 4 kB).

Note

You can call this method multiple times with different values. In turn, you have to call close_audio() as often as you called open_audio() to shut anything down.

Example:

import pygame2.sdlmixer as mixer
import pygame2.sdlmixer.constants as mixconst
...

mixer.open_audio (22050, mixconst.AUDIO_U16SYS, 2, 2048)
pygame2.sdlmixer.query_spec() -> (int, int, int, int)

Queries the actual settings used by the audio device.

Queries the actual settings used by the audio device and returns the setting in the following order:

  • number of times open_audio() was called
  • current frequency
  • current format
  • current channel setting (stereo or mono)

See open_audio() for the typical meaning and values of the returned tuple.

pygame2.sdlmixer.quit() → None

Shuts down the underlying SDL_mixer library.

After calling this function, you should not invoke any SDL_mixer related class, method or function as they are likely to fail or might give unpredictable results.

pygame2.sdlmixer.was_init() → bool

Gets, whether the SDL_mixer library was initialized or not.

Note

This only checks, whether the SDL flag INIT_AUDIO was set.

Channel

class pygame2.sdlmixer.Channel([index]) → Channel

Creates a new Channel for playing audio data

Channel represents a playback destination for audio data. SDL_mixer can handle multiple channels to play audio simultanously.

If index is omitted or smaller than 1, a new Channel will be created. Otherwise Channel will refer to an existing channel and reuse it.

Note

The state of an existing channel will not be reset.

Attributes

Channel.chunk
The current Chunk of audio data to be played.
Channel.fading
The fading status of the Channel.
Channel.paused
Gets, whether the Channel playback is currently paused.
Channel.playing
Gets, whether the Channel is currently playing audio.
Channel.volume
Gets or sets the channel volume.

Methods

Channel.expire(ms) → None
Halts the playback of the Channel after ms milliseconds.
Channel.fade_in(sound, ms[, loops, ticks]) → None

Fades in the passed sound.

This starts playing the passed sound at volume 0, which fades up to the maximum value over ms milliseconds. The sound will be played for loops + 1 number of times.

ticks is the optional maximum time in milliseconds to stop playing after.

Channel.fade_out(ms) → None

Fades out the current audio playback.

This gradually reduces the volume to 0 over ms milliseconds. The channel will be halted after the fadeout is complete.

Channel.halt() → None
Stops the audio playback immediately and resets the playback state
Channel.pause() → None
Pauses the current audio playback.
Channel.play(sound[, loops, ticks]) → None

Starts the playback of an audio Chunk.

The audio chunk will be played for loops + 1 times (or one time only, if loops is omitted).

ticks is the optional maximum time in milliseconds to stop playing after.

Channel.resume() → None
Resumes the playback of a paused sound chunk.

Chunk

class pygame2.sdlmixer.Chunk(file) → Chunk

Creates a new sound chunk for audio playback.

Note

The file object must support binary read and write access. This is especially important for Python 3.x users.

Attributes

Chunk.buf
Gets the raw audio buffer of the Chunk.
Chunk.len
Gets the length of the audio data.
Chunk.volume
Gets or sets the default volume for the audio data.

Music

class pygame2.sdlmixer.Music(file) → Music

Creates a new sound chunk for music playback.

Note

The file object must support binary read and write access. This is especially important for Python 3.x users.

Attributes

Music.type
Gets the music format.

Methods

Music.fade_in(ms[, loops, pos]) → None

Fades in the Music.

This starts playing the Music at volume 0, which fades up to the maximum value over ms milliseconds. The Music will be played for loops + 1 number of times.

pos is the position to start the playback from.

Music.play([loops]) → None

Starts the playback of the Music.

Starts the playback of the Music. The music will be played once, if loops is omitted, otherwise it will be played loops + 1 times.