|
sound - sound handle from LoadSound or Load3DSound 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) |
|
Sets the filter applied to a sound's future plays. 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. Source filtering affects dry audio, reverb and echo sends. Sound settings affect future plays. Every playback copies its own settings; changing a sound does not change channels already playing. FreeSound does not stop existing channels. 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. See also: ChannelFilter, AudioGroupFilter, SoundEcho, SoundReverb. |
; SoundFilter Example
; -------------------
; 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)
RequireAudio AudioGroupMeter(0,True)
; Filter types: 0 off, 1 low-pass, 2 high-pass, 3 band-pass, 4 notch
filter_type=1
frequency#=600
RequireAudio SoundFilter(sound,filter_type,frequency)
channel=PlaySound(sound)
If channel=0 Then RuntimeError "Unable to play the example sound."
While Not KeyDown(1)
; 0-4 choose the type, [ / ] the frequency; Space restarts to apply
If KeyHit(11) Then filter_type=0
If KeyHit(2) Then filter_type=1
If KeyHit(3) Then filter_type=2
If KeyHit(4) Then filter_type=3
If KeyHit(5) Then filter_type=4
If KeyDown(26) And frequency>120 Then frequency=frequency-20
If KeyDown(27) And frequency<8000 Then frequency=frequency+20
RequireAudio SoundFilter(sound,filter_type,frequency)
If KeyHit(57)
StopChannel channel
channel=PlaySound(sound)
EndIf
Cls
Text 0,0,"0-4: type [ / ] : frequency Space: replay Esc: exit"
Text 0,20,"SoundFilter sound,"+filter_type+","+frequency
Text 0,40,"Sound settings affect future plays - press Space to hear the change"
Text 0,80,"Group 0 peak: "+AudioGroupPeak(0)+" RMS: "+AudioGroupRMS(0)
Text 0,100,"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