Blitz3D+ Command Reference

ChannelVolume channel,volume#

Parameters

channel - channel handle returned by PlaySound or PlayMusic

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

Description

Changes the volume of a sound that is already playing.

This is a Channel command, so it acts on one live playback and leaves the loaded sound untouched. That is the difference from SoundVolume, which sets the level future playbacks will start at. Keep the handle PlaySound gave you and you can change this playback while it runs, without affecting anything else using the same sound.

Because it is live, it is what fades are made of. Wind the volume down a little each loop to fade music out before a level change, duck the background track while a voice line plays, or scale an engine loop's volume by how far away the car is so it swells as it approaches.

0.0 is silence and 1.0 is the sample's own level; values above 1.0 amplify rather than being ignored, which will distort if you push them. Setting it to 0 is not the same as stopping - the channel keeps running, so it stays alive for you to bring back later, whereas StopChannel ends it for good.

Once the sound has finished, its channel handle no longer refers to anything and setting the volume on it does nothing. Check with ChannelPlaying if that matters. A channel from PlayMusic playing a MIDI file is handled by the system sequencer and ignores this command.

See also: SoundVolume, ChannelPan, ChannelPitch, ChannelPlaying, StopChannel.

Example

; ChannelVolume Example
; ---------------------

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

; A short tone looped endlessly gives us a steady hum to fade
snd=LoadSound("media/beep.wav")
LoopSound snd
channel=PlaySound(snd)

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

While Not KeyDown(1)

    ; Hold Up/Down to fade the hum in and out
    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

    ; ChannelVolume fades the channel WHILE it plays - no need to
    ; restart it. (SoundVolume instead changes the sound for future
    ; PlaySound calls.)
    ChannelVolume channel,vol_pct/100.0

    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: fade the live channel   Esc: exit"
    Text 0,20,"ChannelVolume channel,vol#   volume = "+vol_pct+"% (0 silent ... 100 full)"

    Flip

Wend

StopChannel channel

End

Index