Blitz3D+ Command Reference

SoundVolume sound,volume#

Parameters

sound - handle of a sound loaded with LoadSound

volume# - loudness, where 0.0 is silent and 1.0 is full volume

Description

Sets the volume a sound will start at the next time it is played.

This is a Sound command, so it changes the loaded sound, not anything currently audible. Set it once after loading and every PlaySound from then on starts at that level. To change the volume of a sound that is already playing - a fade-out, a siren getting closer - use ChannelVolume on the channel handle instead.

It is the natural place for per-sound balancing. Recordings never arrive at matching levels, so trim the loud ones down at load time and your mix stays sane without touching the rest of your code. It is also how you implement a sound-effects slider: keep the player's setting in a variable and apply it to every sound as you load it.

0.0 is silence and 1.0 is the sample's own level. Values above 1.0 amplify rather than being clamped, which is a quick way to lift a quiet recording but will distort if you push it far.

See also: ChannelVolume, SoundPan, SoundPitch, PlaySound, LoadSound.

Example

; SoundVolume Example
; -------------------

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

; Load the explosion into memory
snd=LoadSound("media/boom.wav")

; Volume as a percentage: 0 = silence, 100 = full volume
vol_pct=100

While Not KeyDown(1)

    ; Up/Down arrows set the volume
    If KeyDown(200) And vol_pct<100 Then vol_pct=vol_pct+2
    If KeyDown(208) And vol_pct>0 Then vol_pct=vol_pct-2

    ; SoundVolume changes the SOUND itself, so it must be set BEFORE
    ; PlaySound - every later play uses it. To fade a sound that is
    ; already playing, use ChannelVolume on its channel instead.
    SoundVolume snd,vol_pct/100.0

    ; Space plays the explosion at the current volume
    If KeyHit(57) Then PlaySound snd

    Cls

    ; A volume bar: full width = full volume
    Color 100,100,100
    Rect 100,240,441,20,False
    Color 80,255,120
    If vol_pct>0 Then Rect 102,242,vol_pct*437/100,16

    Color 255,255,255
    Text 0,0,"Up/Down: set volume   Space: play explosion   Esc: exit"
    Text 0,20,"SoundVolume snd,vol#   volume = "+vol_pct+"% (0 silent ... 100 full)"

    Flip

Wend

End

Index