Sound Filtering

It is highly recommended to check the Basic Setup page if you haven't already.
The features mentioned in this page will not work if MonoSound has not been initialized.

Table of Contents
Preface
Filters
Filter Instances
Updating Parameters

Preface

MonoSound was initially just a library for using SoLoud sound filters in C# without requiring bindings.
While that is no longer the main focus of the library, it's still an important feature and, thus, will be described here.

MonoSound currently implements five of SoLoud's sound filters:

1. Low Pass (Biquad Resonant)
2. Band Pass (Biquad Resonant)
3. High Pass (Biquad Resonant)
4. Echo
5. Reverb

(More filter types will be added in future updates.)

Filters

Filters work by manipulating sample data to produce a distinct effect.
Before Version 1.8, some filters — notably Echo and Reverb — require knowledge of previous sample data and cannot be used in audio streams.

Biquad Resonant

This filter type is typically classified via three subtypes: Low Pass, Band Pass and High Pass.

This filter has four parameters:

• Strength / Wetness (paramStrength)
  • The strength of the filter, with a minimum of 0% (0f) and a maximum of 100% (1f)
  • Default is 100% (1f)
• Type (paramType)
  • The type of Biquad Resonant filter to use: Low Pass, High Pass, or Band Pass
    • Low Pass reduces the amplitude of higher frequencies than the set frequency
    • High Pass reduces the amplitude of lower frequencies than the set frequency
    • Band Pass reduces the amplitude of frequencies not within close proximity to the set frequency
  • Defaults to Low Pass
• Frequency Cap (paramFrequency)
  • The frequency cutoff for the filter
  • Low Pass: frequencies above this value are attenuated
  • High Pass: frequencies below this value are attenuated
  • Band Pass: frequencies not within close proximity to this value are attenuated
  • Range is 10 to 8000 Hz
  • Defaults to 2000 Hz
• Resonance (paramResonance)
  • The resonance of the filter
    • Low resonance results in a smoother attenuation and more subtle filtering
    • High resonance results in more aggressive filtering
  • Range is 0.1f to 20
  • Defaults to 2

To register an Biquad Resonant filter, call FilterLoader.RegisterBiquadResonantFilter():

MyBQR = FilterLoader.RegisterBiquadResonantFilter(SoundFilterType.LowPass, strength: 1f, frequency: 1000, resonance: 5);

... or, if you have the BiquadResonantFilter object:

MyBQR = FilterLoader.RegisterFilter(/* BiquadResonantFilter */bqrFilter);

Storing the result in a global variable is encouraged.

Echo

The Echo sound filter causes previous samples in an audio file to be overlapped over the "current" samples.

This filter has four parameters:

• Strength / Wetness (paramStrength)
  • The strength of the filter, with a minimum of 0% (0f) and a maximum of 100% (1f)
  • Default is 100% (1f)
• Delay (paramDelay)
  • The delay of the echo in seconds, with a minimum of 0.0001 seconds
  • Defaults to 0.3 seconds
• Decay (paramDecay)
  • The decay factor of the echo, with a minimum of 0% (0f) and a maximum of 100% (1f)
  • Default is 70% (0.7f)
• Sample Bias (paramBias)
  • The influence of earlier echo samples on the resulting echo, with a minimum of 0% (0f) and a maximum of 100% (1f)
  • Default is 0% (0f)

To register an Echo filter, call FilterLoader.RegisterEchoFilter():

MyEcho = FilterLoader.RegisterEchoFilter(strength: 0.5f, delay: 0.125f, decay: 0.6f, bias: 0.7f);

... or, if you have the EchoFilter object:

MyEcho = FilterLoader.RegisterFilter(/* EchoFilter */echoFilter);

Storing the result in a global variable is encouraged.

Reverb

The Reverb sound filter simulates playing the sound in a small room, where the resulting sound is compounded from the resulting reflections off of walls.

This filter has 5 parameters:

• Strength / Wetness (paramStrength)
  • The strength of the filter, with a minimum of 0% (0f) and a maximum of 100% (1f)
  • Default is 100% (1f)
• Reverb Freeze (paramFrozen)
  • A boolean flag for whether the reverbing effect should decay over time, where true indicates a freeze in the decay and false indicates decay
  • Defaults to false
• Reverb Feedback (paramFeedback)
  • The room size of the reverb, with larger values creating a longer reverb time
  • Range is 0 to 1
  • Defaults to 0.5f
• Dampness (paramDampness)
  • The damping factor of the reverb
    • High damping results in reduced sharpness of the reverb and a more muted sound
    • Low damping results in a sharper and more aggressive reverb
  • Range is 0 to 1
  • Defaults to 0.5f
• Stereo Width (paramStereoWidth)
  • The width of the stereo reverb
  • Range is 0 (Mono) to 1 (full Stereo)
  • Defaults to 1

To register a Reverb filter, call FilterLoader.RegisterReverbFilter():

MyReverb = FilterLoader.RegisterReverbFilter(strength: 0.5f, feedback: 0.5f, dampness: 0.5f, stereoWidth: 1f);

... or, if you have the FreeverbFilter object:

MyReverb = FilterLoader.RegisterFilter(/* FreeverbFilter */reverbFilter);

Storing the result in a global variable is encouraged.

Filter Instances

In order to use a filter, you must first get an instance:

SoLoudFilterInstance instance = /* SoLoudFilter */filter.CreateInstance();

The native filter types to MonoSound all inherit from an intermediary SoLoudFilter<T> class, which allows you to get the instance as the type directly without needing to cast the value:

BiquadResonantFilterInstance instance = /* BiquadResonantFilter */bqrFilter.CreateInstance();

Any new instances of a filter set their initial parameters to the parameters of the filter's singleton instance.

The singleton instance for a filter can be retrieved from its ID via the appropriate method in FilterLoader:

BiquadResonantFilterInstance GetBiquadResonantFilterSingleton(int filterID)

EchoFilterInstance GetEchoFilterSingleton(int filterID)

FreeverbFilterInstance GetReverbFilterSingleton(int filterID)

... or from the SoLoudFilter object directly:

SoLoudFilterInstance singleton = /* SoLoudFilter */ filter.Singleton;

The native filter types to MonoSound all inherit from an intermediary SoLoudFilter<T> class, which allows you to get the singleton without needing to cast the value:

BiquadResonantFilterInstance instance = /* BiquadResonantFilter */bqrFilter.Singleton;

Updating Parameters

To assign a value to a SoLoudFilter.Parameter<T> or SoLoudFilter.BoolParameter, set its Value property to the value:

bqrInstance.paramFrequency.Value = 2500;  // Updates the BQR frequency parameter to 2500 Hz

Some filter parameters (notably, EchoFilter.paramDelay) don't support live updating in certain scenarios. To update them, resetting the instance may be required:

// Initial delay was 0.5s, and attempting to use a larger value will be ignored.
// Hence, resetting the filter is necessary.  This causes the echo filter to be cleared, however.
echoInstance.paramDelay.Value = 0.7f;
echoInstance.Reset();

Parameter Faders

SoLoudFilter.Parameter<T> also has a SoLoudFader<T> Fader { get; } property for implementing the fader behavior from SoLoud.

To use the fader, initialize it to either the Linear Fading or Low-Frequency Oscillation modes:

// The following initializes the fader as a Linear fader that starts at 30 seconds into the audio with a duration of 1.5 seconds.
// While the fader is active, the resonance of this BQR filter will linearly fade from its initial value to the set value of 10
bqrInstance.paramResonance.Fader.Initialize(to: 10f, startTime: 30d, duration: 1.5d);

// The following initializes the fader as a Low-Frequency Oscillating fader that starts at 10 seconds into the audio with a period of 0.75 seconds.
// While the fader is active, the frequency threshold of this BQR filter will oscillate in a sinusoidal pattern from 1000 Hz to 3500 Hz
bqrInstance.paramFrequency.Fader.InitializeLFO(from: 1000, to: 3500, startTime: 10d, period: 0.75d);

Once a Linear fader has finished, it will be tagged as "expired" unless time wraps around to before the start of the fader, in which case it will reactivate automatically and re-fade once time reaches its starting time.

A fader can be disabled at any point by setting Fader.enabled = false;, and manually setting a SoLoudFilter.Parameter<T> parameter will force its fader to be disabled and reset to an uninitialized state.