sound

Load and play WAV, MP3, OGG and QOA sounds, with volume, pitch, pan, pause and seeking.

std:sound plays audio. Load a sound from a file, bytes or a URL, then play, pause, seek and change its volume, pitch and stereo position while it plays. It works on its own or beside a raylib window, and supports WAV, MP3, OGG Vorbis and QOA.

Playing needs an audio device, so the playing examples are marked compile-only. Loading and inspecting a sound doesn't, so that example runs here. To have a sound to load, it makes a half-second beep in memory with a small helper in tone.osl.

Load a sound#

sound.decode(bytes) reads a sound from bytes and sound.decodeFile(path) from a file. Both return a result. A sound knows how long it is, in milliseconds. A new one has volume 1, pitch 1 (normal speed) and pan 0 (centre), and its setters take effect at once, even while it plays:

import "std:sound"
import "./tone.osl"

*sound.Sound beep = sound.decode(tone(500)).unwrap()
log beep.duration()
log beep.volume() beep.pitch() beep.pan()

beep.setVolume(0.5)
beep.setPitch(2)
beep.setPan(-1)
log beep.volume() beep.pitch() beep.pan()

log beep.isPlaying() beep.isPaused() beep.position()
beep.seek(250).unwrap()
log beep.position() beep.progress()

Change tone(500) to tone(1200) and run it again.

Play it#

play() starts the sound, or resumes it if it was paused. It fails with an IOError when there is no audio device, so it returns a result:

import "std:sound"

*sound.Sound jump = sound.decodeFile("jump.wav").unwrap()
jump.play().unwrap()

The program ends when main ends, so a short program that plays a sound needs to stay alive, for instance with thread.sleep(jump.duration()). A game keeps running anyway.

Volume, pitch and pan#

Volume is 0 (silent) to 1. Pitch is the playback speed, so 2 is twice as fast and an octave higher, and 0.5 an octave lower. Pan runs from -1 (left) to 1 (right). A value out of range throws a ValueError. sound.setGlobalVolume scales every sound at once, like a master volume knob.

Pause, stop and seek#

A sound has a position in milliseconds. pause keeps it, stop rewinds to the start, and seek(ms) jumps anywhere, playing or not. progress() is the position as a fraction from 0 to 1, so a progress bar is progress() times the bar's width.

Sound effects and music#

Sound effects are loaded once and played often. Each Sound plays one voice, and play() on one that is already playing does nothing, so for overlapping effects (many gunshots) load the file more than once. Music is one long sound with isPlaying() checked each frame:

import "std:raylib"
import "std:sound"

*sound.Sound music = sound.decodeFile("theme.ogg").unwrap()
*sound.Sound click = sound.decodeFile("click.wav").unwrap()
music.setVolume(0.4)
music.play().unwrap()

raylib.runWindow(def(ms) (
  if raylib.isKeyPressed("space") (
    click.stop()
    click.play().unwrap()
  )
  if !music.isPlaying() (
    music.seek(0).unwrap()
    music.play().unwrap()
  )
), {background: "#181825"})

click.stop() rewinds it first, so a quick second press restarts the sound.

From a URL, and cleaning up#

sound.fetch(url) downloads and decodes a sound from an http or https address. sound.isReady() opens the audio device and tells you whether there is one, which is how a program checks before it relies on sound. sound.close() stops everything and releases the device, and a sound's own close() frees it. Using a closed sound throws a StateError.

import "std:sound"

log sound.globalVolume()

import "std:sound"

log sound.globalVolume()

ParseError

API reference#