LoadSound ( filename$ )

Parameters

filename$ - path to the sound file to load

Description

Loads a sound into memory and returns a handle to it.

This is where every sound effect in your game starts. Load your explosions, footsteps and pickup blips once at startup, keep the handles in Global variables or an array, and play them whenever you need with PlaySound. Loading is slow enough that doing it mid-game causes a visible hitch; playing an already-loaded sound is cheap.

The modern runtime accepts RIFF/WAVE (.wav) and single-stream mono or stereo Ogg Vorbis (.ogg) audio. It identifies the format from the file contents, fully decodes the sound to PCM in memory, and rejects decoded data over 256 MiB. A missing, malformed, unsupported or oversized file gives you 0 back rather than an error, so check the handle before using it. MP3, Ogg Opus, multichannel Vorbis and chained Ogg streams are not supported. PlayMusic starts playback directly from a filename, but WAV and Ogg files still use the same complete in-memory decode.

Sound handles and channel handles are different things and this is the point where the distinction begins. The handle here is the loaded sound - one copy of the audio data, which you can play many times over. Each PlaySound gives you back a separate channel handle for that particular playback. Commands starting with Sound set defaults on the loaded sound for the next time it is played; commands starting with Channel reach into a playback that is already running.

Set up the sound before you play it with SoundVolume, SoundPan, SoundPitch and LoopSound. Release it with FreeSound when you no longer need it.

Extended mode also offers opt-in audio effects, mix groups, filters and environmental reverb for WAV/Ogg playback.

See also: PlaySound, FreeSound, LoopSound, SoundVolume, PlayMusic.

Example

; LoadSound Example
; -----------------

Graphics 640,480,0,2
SetBuffer BackBuffer()

; LoadSound reads a whole sound file into memory and returns a handle.
; Load once at startup, then play the handle as often as you like.
snd_beep=LoadSound("media/beep.wav")
snd_boom=LoadSound("media/boom.wav")
snd_shoot=LoadSound("media/shoot.wav")

last_played$="(none yet)"

While Not KeyDown(1)

    ; Keys 1-3 play the loaded sounds
    If KeyHit(2) Then
        PlaySound snd_beep
        last_played$="beep"
    End If
    If KeyHit(3) Then
        PlaySound snd_boom
        last_played$="boom"
    End If
    If KeyHit(4) Then
        PlaySound snd_shoot
        last_played$="shoot"
    End If

    Cls

    Text 0,0,"1: beep   2: boom   3: shoot   Esc: exit"
    Text 0,30,"snd_beep  = LoadSound(media/beep.wav)  -> handle "+snd_beep
    Text 0,50,"snd_boom  = LoadSound(media/boom.wav)  -> handle "+snd_boom
    Text 0,70,"snd_shoot = LoadSound(media/shoot.wav) -> handle "+snd_shoot
    Text 0,110,"Last played: "+last_played$

    Flip

Wend

End

Index

Blitz3D+ Command Reference

LoadSound ( filename$ )

Parameters

Description

Example