Blitz3D+ Command Reference

AudioGroupFilter ( group,type[,frequency#][,q#] )

Parameters

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

type - filter type; frequency and q are checked but unused when off:
0: off
1: low-pass
2: high-pass
3: band-pass
4: notch
5: one-pole low-pass
6: one-pole high-pass

frequency# (optional) - cutoff/centre frequency in Hz; 1000 (default)

q# (optional) - filter resonance; 0.7071068 (default)

Description

Sets the filter applied to a whole 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.

Types 1-4 accept 20..8000 Hz and Q 0.667..10. Types 5-6 accept 20..20000 Hz and ignore Q. Off ignores frequency/Q after checking they are finite. There is one filter per source and one per group. Frequency changes ramp over about 20 ms; a type change briefly fades the signal.

The group filter processes its combined dry and wet sound. Filter SFX/ambience for underwater audio while leaving music/UI clear.

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: SoundFilter, ChannelFilter, AudioGroupEQ, AudioGroupClearEffects.

Example

; AudioGroupFilter example. Compile in Extended mode; media ships with Audio Playground.
AppTitle "AudioGroupFilter"
If Not InitAudioEffects() Then RuntimeError AudioLastError$()
Graphics 680,240,0,2
SetBuffer BackBuffer()
sound = LoadSound("../../../samples/audio/media/machine.wav")
If sound = 0 Then RuntimeError "The installed audio sample media is missing."
LoopSound sound
SoundVolume sound,0.25
RequireAudio AudioMasterMeter(True)
RequireAudio AudioGroupMeter(0,True)
message$ = "AudioGroupFilter"
RequireAudio AudioGroupFilter(0,1,600)
channel = PlaySound(sound)
If channel = 0 Then RuntimeError "Unable to play the example sound."

started = MilliSecs()
While KeyDown(1) = False And MilliSecs()-started < 5000

    Cls
    Text 20,20,message
    Text 20,50,"Group 0 peak: " + AudioGroupPeak(0) + "   RMS: " + AudioGroupRMS(0)
    Text 20,80,"Master peak: " + AudioMasterPeak() + "   RMS: " + AudioMasterRMS()
    Text 20,120,"Listen for five seconds, or press Escape to finish."
    Flip
Wend
StopChannel channel
For group = 0 To 3
    RequireAudio AudioGroupClearEffects(group)
Next
Delay 60
FreeSound sound
EndGraphics
End

Function RequireAudio(success)
    If Not success Then RuntimeError AudioLastError$()
End Function

Index