audio — Sound effects and music

Sound reference

class audio.Sound(sound_filepath, volume=1.0)

A Sound object represents a sound effect. Multiple sound effects can be played simultaneously.

sound_filepath argument must point to a sound file in a compatible format. Currently supported formats are:

• wav

• ogg

volume paramter must be a value between 0 and 1

Instance properties:

Sound.volume

Gets or sets a default volume of the sound effect.

Instance methods:

Sound.play(volume=1.0)

Plays the sound effect.

Volume is a value between 0 and 1. The volume is modified by the master sound volume level setting.

Refer to engine.AudioManager documentation on how to set the master volume for sounds.

Multiple sound effects can be played simultaneously, up to a limit set on the AudioManager.mixing_channels property.

The play() method is a simple “fire and forget” mechanism. It does not allow you to stop, pause or resume the sound. If you need more control on how the sound effects playback, use the SoundPlayback wrapper.

SoundPlayback reference

class audio.SoundPlayback(sound, volume=1.0)

A wrapper class for Sound objects, offering more control over sound effects playback.

The sound parameter must be a Sound instance.

Volume must be a value between 0 and 1.

Instance properties:

SoundPlayback.sound

Read only. Returns the wrapped Sound instance

SoundPlayback.status

Read only. Returns the sound status, as AudioStatus enum value.

SoundPlayback.is_playing

Read only. Returns True if the sound is playing.

SoundPlayback.is_paused

Read only. Returns True if the sound is paused.

SoundPlayback.volume

Gets or sets the volume. Must be a number between 0 and 1.

Instance methods:

SoundPlayback.play(loops=1)

Plays the sound effect.

The loops parameter is how many times the sound should play. Set to 0 to play the sound in the infinite loop.

Multiple sound effects can be played simultaneously, up to a limit set on the AudioManager.mixing_channels property.

Use stop(), pause() and resume() methods to control the sound playback.

SoundPlayback.stop()

Stops the sound playback if it’s playing or paused.

SoundPlayback.pause()

Pauses the sound playback if it’s playing.

SoundPlayback.resume()

Resumes the sound playback if it’s paused.

Music reference

class audio.Music(music_filepath, volume=1.0)

A Music object represents a single music track. There’s more control over playing Music tracks than Sounds as you can pause, resume or stop them on demand. Only one music track can be played at a time.

music_filepath argument must point to a soundtrack file in a compatible format. Currently supported formats are:

• wav

• ogg

Class methods

classmethod Music.get_current()

Returns Music instance currently being played

Instance properties

Music.status

Read only. Returns the status of the Music track, as AudioStatus enum value.

Music.is_playing

Read only. Returns True if the music is playing.

Music.is_paused

Read only. Returns True if the music is paused.

Music.volume

Gets or sets a default volume of the music track.

Instance methods

Music.play(volume=1.0)

Starts playing the music track. If another music track is playing it is automatically stopped.

Volume is a value between 0 and 1. The volume is modified by the master music volume level setting.

Refer to engine.AudioManager documentation on how to set the master volume for music.

Music.pause()

Pauses the music track currently being played. Can be resumed with Music.resume() method

Music.resume()

Resumes music track paused by Music.pause(). If the track is not paused, it does nothing.

Music.stop()

Stops the music track.

AudioStatus reference

class audio.AudioStatus

Enum type used for referencing sound or music status when working with Music, Sound and SoundPlayback objects. It has the following values:

• AudioStatus.playing

• AudioStatus.paused

• AudioStatus.stopped