Sound and Music¶
Sounds¶
wasabi2d can load sounds in .wav
and .ogg
formats. WAV is great for
small sound effects, while OGG is a compressed format that is more suited to
music. You can find free .ogg and .wav files online that can be used in your
game.
We need to ensure a sounds directory is set up. If your project contains the following files:
drum_kit.py
sounds/drum.wav
Then drum_kit.py
could play the drum sound whenever the mouse is clicked
with this code:
def on_mouse_down():
sounds.drum.play()
Each loaded sound is a Pygame Sound
, and has various methods to play and
stop the sound as well as query its length in seconds:
- class Sound¶
- play()¶
Play the sound.
- play(loops)¶
Play the sound, but loop it a number of times.
- Parameters
loops – The number of times to loop. If you pass
-1
as the number of times to loop, the sound will loop forever (or until you callSound.stop()
- stop()¶
Stop playing the sound.
- get_length()¶
Get the duration of the sound in seconds.
You should avoid using the sounds
object to play longer pieces of music.
Because the sounds sytem will fully load the music into memory before playing
it, this can use a lot of memory, as well as introducing a delay while the
music is loaded.
Music¶
Warning
The music API is experimental and may be subject to cross-platform portability issues.
In particular:
MP3 may not be available on some Linux distributions.
Some OGG Vorbis files seem to hang Pygame with 100% CPU.
In the case of the latter issue, the problem may be fixed by re-encoding (possibly with a different encoder).
A built-in object called music
provides access to play music from within
a music/
directory (alongside your images/
and sounds/
directories,
if you have them). The music system will load the track a little bit at a time
while the music plays, avoiding the problems with using sounds
to play
longer tracks.
Another difference to the sounds system is that only one music track can be playing at a time. If you play a different track, the previously playing track will be stopped.
- music.play(name)¶
Play a music track from the given file. The track will loop indefinitely.
This replaces the currently playing track and cancels any tracks previously queued with
queue()
.You do not need to include the extension in the track name; for example, to play the file
handel.mp3
on a loop:music.play('handel')
- music.play_once(name)¶
Similar to
play()
, but the music will stop after playing through once.
- music.queue(name)¶
Similar to
play_once()
, but instead of stopping the current music, the track will be queued to play after the current track finishes (or after any other previously queued tracks).
- music.stop()¶
Stop the music.
- music.pause()¶
Pause the music temporarily. It can be resumed by calling
unpause()
.
- music.unpause()¶
Unpause the music.
- music.is_playing()¶
Returns True if the music is playing (and is not paused), False otherwise.
- music.fadeout(duration)¶
Fade out and eventually stop the current music playback.
- Parameters
duration – The duration in seconds over which the sound will be faded out. For example, to fade out over half a second, call
music.fadeout(0.5)
.
- music.set_volume(volume)¶
Set the volume of the music system.
This takes a number between 0 (meaning silent) and 1 (meaning full volume).
- music.get_volume()¶
Get the current volume of the music system.
If you have started a music track playing using music.play_once()
, you
can use the on_music_end() hook
to do something when the
music ends - for example, to pick another track at random.
Tone Generator¶
Wasabi2D can play tones using a built-in synthesizer.
- tone.play(pitch, duration, *, waveform='sin', volume=1.0)¶
Play a note at the given pitch for the given duration.
Duration is in seconds.
The pitch can be specified as a number in which case it is the frequency of the note in hertz.
Waveform is a string - either ‘sin’, ‘square’, or ‘saw’.
Alternatively, the pitch can be specified as a string representing a note name and octave. For example:
'E4'
would be E in octave 4.'A#5'
would be A-sharp in octave 5.'Bb3'
would be B-flat in octave 3.
Creating notes, particularly long notes, takes time - up to several milliseconds. You can create your notes ahead of time so that this doesn’t slow your game down while it is running:
- tone.create(pitch, duration *, waveform='sin', volume=1.0)¶
Create and return a Sound object.
The arguments are as for play(), above.
This could be used in a Wasabi2D program like this:
beep = tone.create('A3', 0.5)
def on_mouse_down():
beep.play()