Blitz3D+ Command Reference

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 decodes RIFF/WAVE (.wav) files. A file that is not a WAV, or is missing, gives you 0 back rather than an error, so a quick check on the handle will save you wondering later why nothing is audible. For longer music tracks use PlayMusic instead, which plays a file directly rather than holding it in memory.

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.

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