Equalizer
This section covers several types of equalizers including tonestack, graphic equalizers, and parametric equalizers.
Tonestack
- class diffFx_pytorch.processors.eq.Tonestack(*args: Any, **kwargs: Any)[source]
Bases:
ProcessorsBaseDifferentiable implementation of classic guitar amplifier tonestack circuits.
This processor implements a digital model of analog tonestack circuits found in guitar amplifiers, providing control over bass, middle, and treble frequencies. The implementation is based on modeling the analog circuit components and their interactions using a third-order IIR filter.
The transfer function is based on the following analog circuit topology:
\[H(s) = \frac{b_0 + b_1s + b_2s^2 + b_3s^3}{1 + a_1s + a_2s^2 + a_3s^3}\]- where coefficients b0-b3 and a1-a3 are functions of:
Component values (R1-R4, C1-C3) from the chosen preset
Control positions (bass, mid, treble)
The coefficients are calculated using circuit analysis equations
The bilinear transform is then applied to convert to digital domain
- Parameters:
sample_rate (int) – Audio sample rate in Hz. Defaults to 44100.
preset (str) –
Amplifier model preset to use. Must be one of the following:
- Fender Family:
BASSMAN: ‘59 Bassman 5F6-A
MESA: Mesa Boogie Mark
TWIN: ‘69 Twin Reverb AA270
PRINCETON: ‘64 Princeton AA1164
FENDER_BLUES: Fender Blues Junior
FENDER_DEFAULT: Fender Default
FENDER_DEVILLE: Fender Hot Rod Deville
- Marshall Family:
JCM800: ‘59/81 JCM-800 Lead 100 2203
JCM2000: ‘81 2000 Lead
JTM45: JTM 45
MLEAD: ‘67 Major Lead 200
M2199: M2199 30W solid state
- Vox Family:
AC30: ‘59/86 AC-30
AC15: VOX AC-15
- Other Manufacturers:
SOLDANO: Soldano SLO 100
SOVTEK: MIG 100 H
PEAVEY: Peavey C20
IBANEZ: Ibanez GX20
ROLAND: Roland Cube 60
AMPEG: VL 501
AMPEG_REV: Ampeg Reverbrocket
BOGNER: Triple Giant Preamp
GROOVE: Trio Preamp
CRUNCH: Hughes&Kettner
GIBSON: GS12 Reverbrocket
ENGL: Engl
- Parameters Details:
- bass: Low frequency control
Range: 0.0 to 1.0
Higher values boost low frequencies
- mid: Middle frequency control
Range: 0.0 to 1.0
Controls presence of middle frequencies
- treble: High frequency control
Range: 0.0 to 1.0
Higher values boost high frequencies
Note
The processor supports a collection of presets modeling famous guitar amplifier circuits including Fender, Marshall, Vox, and other manufacturers. Each preset defines specific component values that determine the characteristic sound of that amplifier model.
Warning
- When using with neural networks:
norm_params must be in range [0, 1]
Parameters will be automatically mapped to their ranges
Ensure your network output is properly normalized (e.g., using sigmoid)
Parameter order must match _register_default_parameters()
Examples
- Basic DSP Usage:
>>> # Create a tonestack with Fender Bassman preset >>> tonestack = Tonestack( ... sample_rate=44100, ... preset="bassman" ... ) >>> # Process audio with dsp parameters >>> output = tonestack(input_audio, dsp_params={ ... 'bass': 0.7, ... 'mid': 0.5, ... 'treble': 0.6 ... })
- Neural Network Control:
>>> # 1. Simple parameter prediction >>> class TonestackController(nn.Module): ... def __init__(self, input_size, num_params): ... super().__init__() ... self.net = nn.Sequential( ... nn.Linear(input_size, 32), ... nn.ReLU(), ... nn.Linear(32, num_params), ... nn.Sigmoid() # Ensures output is in [0,1] range ... ) ... ... def forward(self, x): ... return self.net(x) >>> >>> # Initialize controller >>> num_params = tonestack.count_num_parameters() # 3 parameters >>> controller = TonestackController(input_size=16, num_params=num_params) >>> >>> # Process with features >>> features = torch.randn(batch_size, 16) # Audio features >>> norm_params = controller(features) >>> output = tonestack(input_audio, norm_params=norm_params)
A classic three-band equalizer that emulates the behavior of analog tone controls found in guitar amplifiers. Typically includes bass, middle, and treble controls that interact with each other similar to passive analog circuits.
- __init__(sample_rate=44100, param_range=None, preset='bassman')[source]
Initialize the processor base.
- Parameters:
sample_rate – Audio sample rate in Hz
param_range – Optional parameter definitions to override defaults
- _register_default_parameters()[source]
Register default parameter ranges for the tonestack.
- Sets up the following parameters with their ranges:
bass: Low frequency control (0 to 1)
mid: Middle frequency control (0 to 1)
treble: High frequency control (0 to 1)
Each control maps to a normalized range that interacts with the circuit component values defined by the chosen preset.
- _calculate_coefficients(t, m, l)[source]
Calculate filter coefficients based on control values and component values.
Implements the circuit analysis equations for the tonestack, converting control positions and component values into analog filter coefficients, then applying the bilinear transform to obtain digital coefficients.
- Parameters:
t (torch.Tensor) – Treble control value (0-1). Shape: (batch,)
m (torch.Tensor) – Middle control value (0-1). Shape: (batch,)
l (torch.Tensor) – Bass control value (0-1). Shape: (batch,)
- Returns:
- (Bs, As) where:
Bs: Numerator coefficients for IIR filter. Shape: (batch, 4)
As: Denominator coefficients for IIR filter. Shape: (batch, 4)
- Return type:
Note
The coefficients are computed in these stages: 1. Get component values from current preset (R1-R4, C1-C3) 2. Apply bass control scaling for improved response 3. Calculate analog domain coefficients (b1-b3, a0-a3) 4. Convert to digital domain using bilinear transform 5. Stack coefficients for IIR filtering
- process(x, norm_params=None, dsp_params=None)[source]
Process input signal through the tonestack.
- Parameters:
x (torch.Tensor) – Input audio tensor. Shape: (batch, channels, samples)
norm_params (Dict[str, torch.Tensor]) –
Normalized parameters (0 to 1) Must contain the following keys:
’bass’: Low frequency control (0 to 1)
’mid’: Mid frequency control (0 to 1)
’treble’: High frequency control (0 to 1)
Each value should be a tensor of shape (batch_size,)
dsp_params (Dict[str, Union[float, torch.Tensor]], optional) – Direct DSP parameters. Can specify tone controls as: - float/int: Single value applied to entire batch - 0D tensor: Single value applied to entire batch - 1D tensor: Batch of values matching input batch size Parameters will be automatically expanded to match batch size and moved to input device if necessary. If provided, norm_params must be None.
- Returns:
Processed audio tensor of same shape as input
- Return type:
GraphicEqualizer
- class diffFx_pytorch.processors.eq.GraphicEqualizer(*args: Any, **kwargs: Any)[source]
Bases:
ProcessorsBaseDifferentiable implementation of a multi-band graphic equalizer.
Implementation is based on the following book:
This processor implements a parallel bank of peak filters to create a graphic equalizer, allowing independent gain control over multiple frequency bands. The implementation supports different frequency spacing schemes including ISO standard frequencies, octave spacing, and third-octave spacing.
The equalizer uses second-order IIR peak filters for each band with transfer function:
\[H(z) = \frac{b_0 + b_1z^{-1} + b_2z^{-2}}{1 + a_1z^{-1} + a_2z^{-2}}\]- where coefficients are computed based on:
Center frequency of each band
Q factor (bandwidth)
Gain setting for each band
- Parameters:
sample_rate (int) – Audio sample rate in Hz. Defaults to 44100.
num_bands (int) – Number of frequency bands. Defaults to 10.
q_factors (float) – Q factor for band filters. Controls bandwidth. Defaults to None.
eq_type (str) – Frequency spacing scheme. Must be one of: - ‘iso’: ISO standard frequencies (31.5, 63, 125, 250, 500, 1000, 2000, 4000, 8000, 16000 Hz) - ‘octave’: Octave-spaced bands - ‘third_octave’: Third-octave spaced bands Defaults to ‘iso’.
- Parameters Details:
- band_X_gain_db: Gain for band X (where X is 1 to num_bands)
Range: -12.0 to 12.0 dB
Controls gain at that frequency band
Positive values boost, negative values cut
Note
- The processor supports three types of frequency spacing:
ISO: Standard audio frequencies
Octave: Logarithmically spaced bands, one per octave
Third-octave: Logarithmically spaced bands, three per octave
Each band uses a constant-Q design where the relative bandwidth remains consistent across frequencies.
Warning
- When using with neural networks:
norm_params must be in range [0, 1]
Parameters will be automatically mapped to their dB ranges
Ensure your network output is properly normalized (e.g., using sigmoid)
Parameter order must match _register_default_parameters()
Examples
- Basic DSP Usage:
>>> # Create a 10-band graphic EQ with ISO frequencies >>> eq = GraphicEqualizer( ... sample_rate=44100, ... num_bands=10, ... q_factors=2.0, ... eq_type='iso' ... ) >>> # Process audio with dsp parameters >>> params = {f'band_{i+1}_gain_db': 6.0 for i in range(10)} # Boost all bands by 6dB >>> output = eq(input_audio, dsp_params=params)
- Neural Network Control:
>>> # 1. Simple parameter prediction >>> class GraphicEQController(nn.Module): ... def __init__(self, input_size, num_bands): ... super().__init__() ... self.net = nn.Sequential( ... nn.Linear(input_size, 32), ... nn.ReLU(), ... nn.Linear(32, num_bands), ... nn.Sigmoid() # Ensures output is in [0,1] range ... ) ... ... def forward(self, x): ... return self.net(x) >>> >>> # Initialize controller >>> eq = GraphicEqualizer(num_bands=10) >>> controller = GraphicEQController(input_size=16, num_bands=10) >>> >>> # Process with features >>> features = torch.randn(batch_size, 16) # Audio features >>> norm_params = controller(features) >>> output = eq(input_audio, norm_params=norm_params)
A multi-band equalizer that divides the frequency spectrum into fixed bands (typically octaves or third-octaves), where each band can be boosted or cut independently using slider controls. The center frequencies and bandwidths are fixed, and the gains can be adjusted to create a visual representation of the frequency response.
- __init__(sample_rate=44100, param_range=None, num_bands=10, q_factors=None, eq_type='octave')[source]
Initialize the processor base.
- Parameters:
sample_rate – Audio sample rate in Hz
param_range – Optional parameter definitions to override defaults
- _get_frequencies()[source]
Get frequency bands based on equalizer type.
- Computes center frequencies for bands based on the selected EQ type:
ISO: Uses standard ISO center frequencies
Octave: Logarithmically spaced bands, one per octave
Third-octave: Logarithmically spaced bands, three per octave
- Returns:
Center frequencies in Hz for each band
- Return type:
- Raises:
ValueError – If eq_type is not recognized
- _register_default_parameters()[source]
Register gain parameters for each frequency band.
Creates a gain parameter for each band with range -12 dB to +12 dB. Parameter names are formatted as ‘band_X_gain_db’ where X is the band number starting from 1.
- _prepare_band_parameters(band_idx, params, device)[source]
Prepare filter parameters for a single frequency band.
- Parameters:
band_idx (int) – Index of the band to prepare parameters for
params (Dict[str, torch.Tensor]) – All EQ parameters
device (torch.device) – Device to place tensors on
- Returns:
- Parameters for the band’s peak filter:
gain_db: Gain in dB
frequency: Center frequency in Hz
q_factor: Q factor for bandwidth
- Return type:
Dict[str, torch.Tensor]
Note
Expands scalar parameters to match batch size of provided parameters.
- process(x, norm_params=None, dsp_params=None)[source]
Process input signal through the graphic equalizer.
- Parameters:
x (torch.Tensor) – Input audio tensor. Shape: (batch, channels, samples)
norm_params (Dict[str, torch.Tensor]) – Normalized parameters (0 to 1) Dictionary with keys ‘band_X_gain_db’ for X in range(1, num_bands+1) Each value should be a tensor of shape (batch_size,) Values will be mapped to -12.0 to 12.0 dB
dsp_params (Dict[str, Union[float, torch.Tensor]], optional) – Direct DSP parameters. Can specify band gains as: - float/int: Single value applied to entire batch - 0D tensor: Single value applied to entire batch - 1D tensor: Batch of values matching input batch size Parameters will be automatically expanded to match batch size and moved to input device if necessary. If provided, norm_params must be None.
- Returns:
Processed audio tensor of same shape as input
- Return type:
ParametricEqualizer
- class diffFx_pytorch.processors.eq.ParametricEqualizer(*args: Any, **kwargs: Any)[source]
Bases:
ProcessorsBaseDifferentiable implementation of a parametric equalizer.
Implementation is based on following book and papers:
This processor implements a versatile parametric equalizer combining multiple peak filters with high and low shelf filters. Each filter section provides independent control over gain, frequency, and bandwidth (Q factor), offering precise frequency response shaping capabilities.
Each filter section uses a second-order IIR (biquad) implementation with transfer function:
\[H(z) = \frac{b_0 + b_1z^{-1} + b_2z^{-2}}{1 + a_1z^{-1} + a_2z^{-2}}\]- where coefficients are computed based on:
Filter type (peak, low shelf, or high shelf)
Center frequency
Q factor (bandwidth/slope)
Gain setting
- Parameters:
sample_rate (int) – Audio sample rate in Hz
param_range (Dict[str, EffectParam], optional) – Parameter ranges.
num_peak_filters (int) – Number of independent peak filters. Defaults to 3.
- Parameters Details:
- Low Shelf Section:
- low_shelf_gain_db: Gain for low frequencies
Range: -12.0 to 12.0 dB
Controls bass boost/cut
- low_shelf_frequency: Corner frequency
Range: 20.0 to 500.0 Hz
Controls bass transition point
- low_shelf_q_factor: Slope control
Range: 0.1 to 1.0
Controls bass shelf slope
- Peak Filter Sections (for each peak filter i):
- peak_i_gain_db: Gain for the band
Range: -12.0 to 12.0 dB
Controls midrange boost/cut
- peak_i_frequency: Center frequency
Range: 20.0 to 20000.0 Hz
Controls midrange center point
- peak_i_q_factor: Bandwidth control
Range: 0.1 to 10.0
Controls midrange bandwidth
- High Shelf Section:
- high_shelf_gain_db: Gain for high frequencies
Range: -12.0 to 12.0 dB
Controls treble boost/cut
- high_shelf_frequency: Corner frequency
Range: 5000.0 to 20000.0 Hz
Controls treble transition point
- high_shelf_q_factor: Slope control
Range: 0.1 to 1.0
Controls treble shelf slope
Note
- The equalizer consists of three main sections:
Low shelf filter for bass control
Multiple peak filters for midrange control
High shelf filter for treble control
Each section provides independent control over gain, frequency, and Q factor, allowing for precise frequency response shaping.
Warning
- When using with neural networks:
norm_params must be in range [0, 1]
Parameters will be automatically mapped to their ranges
Ensure your network output is properly normalized (e.g., using sigmoid)
Parameter order must match _register_default_parameters()
Examples
- Basic DSP Usage:
>>> # Create a parametric EQ with 3 peak filters >>> eq = ParametricEqualizer( ... sample_rate=44100, ... num_peak_filters=3 ... ) >>> # Process audio with dsp parameters >>> params = { ... 'low_shelf_gain_db': 6.0, ... 'low_shelf_frequency': 100.0, ... 'low_shelf_q_factor': 0.7, ... 'peak_1_gain_db': -3.0, ... 'peak_1_frequency': 1000.0, ... 'peak_1_q_factor': 1.4, ... # ... additional peak filter parameters ... ... 'high_shelf_gain_db': -2.0, ... 'high_shelf_frequency': 8000.0, ... 'high_shelf_q_factor': 0.7 ... } >>> output = eq(input_audio, dsp_params=params)
- Neural Network Control:
>>> # 1. Simple parameter prediction >>> class ParametricEQController(nn.Module): ... def __init__(self, input_size, num_parameters): ... super().__init__() ... self.net = nn.Sequential( ... nn.Linear(input_size, 32), ... nn.ReLU(), ... nn.Linear(32, num_parameters), ... nn.Sigmoid() # Ensures output is in [0,1] range ... ) ... ... def forward(self, x): ... return self.net(x) >>> >>> # Initialize controller >>> eq = ParametricEqualizer(num_peak_filters=3) >>> num_params = eq.count_num_parameters() # 15 parameters for 3 peak filters >>> controller = ParametricEQController(input_size=16, num_parameters=num_params) >>> >>> # Process with features >>> features = torch.randn(batch_size, 16) # Audio features >>> norm_params = controller(features) >>> output = eq(input_audio, norm_params=norm_params)
A flexible equalizer that allows precise control over specific frequency ranges through adjustable parameters including center frequency, bandwidth (Q factor), and gain for each band. Unlike graphic EQs, the center frequencies and bandwidths can be freely adjusted, typically offering more surgical sound shaping capabilities.
- __init__(sample_rate, param_range=None, num_peak_filters=3)[source]
Initialize the processor base.
- Parameters:
sample_rate – Audio sample rate in Hz
param_range – Optional parameter definitions to override defaults
- _register_default_parameters()[source]
Register parameters for all filter sections.
- Sets up parameter ranges for:
Low shelf filter (gain, frequency, Q)
Multiple peak filters (gain, frequency, Q for each)
High shelf filter (gain, frequency, Q)
Each parameter is registered with appropriate min/max values for its function.
- process(x, norm_params=None, dsp_params=None)[source]
Process input signal through the parametric equalizer.
- Parameters:
x (torch.Tensor) – Input audio tensor. Shape: (batch, channels, samples)
norm_params (Dict[str, torch.Tensor]) – Normalized parameters (0 to 1) Dictionary with keys for each parameter: - Low shelf: ‘low_shelf_gain_db’, ‘low_shelf_frequency’, ‘low_shelf_q_factor’ - Peak filters: ‘peak_X_gain_db’, ‘peak_X_frequency’, ‘peak_X_q_factor’ for X in range(1, num_peak_filters+1) - High shelf: ‘high_shelf_gain_db’, ‘high_shelf_frequency’, ‘high_shelf_q_factor’ Each value should be a tensor of shape (batch_size,) Values will be mapped to their respective ranges
dsp_params (Dict[str, Union[float, torch.Tensor]], optional) – Direct DSP parameters. Can specify parameters as: - float/int: Single value applied to entire batch - 0D tensor: Single value applied to entire batch - 1D tensor: Batch of values matching input batch size Parameters will be automatically expanded to match batch size and moved to input device if necessary. If provided, norm_params must be None.
- Returns:
Processed audio tensor of same shape as input
- Return type: