Blitz3D+ Command Reference

ChannelGroup ( channel,group )

Parameters

channel - live WAV/Ogg playback channel

group - mixing group:
0: SFX (default for LoadSound/Load3DSound)
1: Music (default for non-MIDI PlayMusic)
2: UI
3: Ambience

Description

Moves a playing channel to a different mixing group.

Groups are 0=SFX, 1=Music, 2=UI and 3=Ambience. LoadSound/Load3DSound default to SFX; non-MIDI PlayMusic defaults to Music. Group processing includes dry sound and shared wet returns.

Changes future samples from this channel without restarting playback. Old shared tails remain in the old group. A brief route fade protects the topology change.

The channel must be a live WAV/Ogg playback. Null, foreign, MIDI and completed handles fail safely. ChannelPlaying reports source playback, including paused sources, rather than the lifetime of a shared effect tail.

Call InitAudioEffects before the first WAV/Ogg playback. Configuration commands return 1 on success or 0 on failure; use AudioLastError for the reason. Finite numeric values and valid handles are required in Debug and Release. Queries preserve errors unless the query itself fails.

Audio effects process decoded WAV and mono/stereo Ogg at an internal 48 kHz. MIDI uses a separate backend. Sound defaults are copied to independent playing channels. Runtime pause freezes sources, tails and transition time; pausing one channel leaves shared tails running. Event waits service transitions and release completed source resources without ChannelPlaying polling. Lightweight completed handles are retained until program shutdown.

The interactive Audio Playground sample demonstrates the whole effects family together.

Requires Extended mode.

See also: SoundGroup, AudioGroupVolume, AudioGroupClearEffects.

Example

; ChannelGroup Example
; --------------------
; Requires Extended mode.

; Effects must be initialized before the first WAV/Ogg playback
If Not InitAudioEffects() Then RuntimeError AudioLastError$()

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

; A looping machine hum to hear the effect on
sound=LoadSound("../../../samples/audio/media/machine.wav")
If sound=0 Then RuntimeError "The audio sample media is missing."
LoopSound sound
SoundVolume sound,0.25

; Meters make the audio state visible on screen
RequireAudio AudioMasterMeter(True)
For g=0 To 3
    RequireAudio AudioGroupMeter(g,True)
Next

; Groups: 0 SFX, 1 Music, 2 UI, 3 Ambience
group=0

channel=PlaySound(sound)
If channel=0 Then RuntimeError "Unable to play the example sound."

While Not KeyDown(1)

    ; 1-4 move the LIVE channel between groups without restarting it
    If KeyHit(2) Then group=0
    If KeyHit(3) Then group=1
    If KeyHit(4) Then group=2
    If KeyHit(5) Then group=3
    RequireAudio ChannelGroup(channel,group)

    Cls
    Text 0,0,"1-4: move live channel to group   Esc: exit"
    Text 0,20,"ChannelGroup channel,"+group+"   (0 SFX, 1 Music, 2 UI, 3 Ambience)"
    Text 0,40,"The playing channel switches group without restarting"
    For g=0 To 3
        Text 0,80+g*20,"Group "+g+" RMS: "+AudioGroupRMS(g)
    Next
    Text 0,170,"Master peak: "+AudioMasterPeak()+"   RMS: "+AudioMasterRMS()

    Flip

Wend

; Let shared effect tails fade before the program ends
For group=0 To 3
    RequireAudio AudioGroupClearEffects(group)
Next
StopChannel channel
FreeSound sound

End

; Stop with the recorded reason if an audio-effects call fails
Function RequireAudio(success)
    If Not success Then RuntimeError AudioLastError$()
End Function

Index