treble_sdk_shared.filter_definition
Functions
|
Deserialize a filter from Polars struct format. |
Classes
A filter that performs an integration of the data using a Butterworth filter with a very low cutoff frequency, some phase distortion at the very low frequencies may occur, if this is critical, use a lower cutoff frequency for the filter |
|
An enumeration. |
|
Butterworth filtering for lowpass, highpass and bandpass filtering |
|
A filter that "removes" the default treble bandpass filter (20Hz-crossover frequency) from the IR. |
|
Filtering using an finite impulse response filter |
|
Gain stage filter |
|
Filtering using an infinite impulse response filter |
|
A filter that applies a time window to the data |
|
A filter that applies a time shift to the data |
- class treble_sdk_shared.filter_definition.ApproximateIntegrationFilter
A filter that performs an integration of the data using a Butterworth filter with a very low cutoff frequency, some phase distortion at the very low frequencies may occur, if this is critical, use a lower cutoff frequency for the filter
- filter(data: numpy.ndarray, sampling_rate: int, zero_pad_samples: int = 0)
Apply the filtering operation
- classmethod from_struct(struct: dict) → ApproximateIntegrationFilter
Deserialize filter from a dict representation suitable for Polars Struct storage.
- Parameters:
struct (dict) – {‘type’: str, ‘params’: str} where type is class name and params is JSON string
- Return FilterDefinition:
The deserialized filter
- to_struct() → dict
Serialize filter to a dict representation suitable for Polars Struct storage.
- Return dict:
{‘type’: str, ‘params’: str} where type is class name and params is JSON string
- class treble_sdk_shared.filter_definition.Biquad
- __init__(biquad_type: BiquadType | str, fc: float, Q: float | None = None, gain_db: float | None = None)
Initialize the biquad filter
- Parameters:
fc (float) – Center frequency of the biquad filter in Hz
Q (float) – Q factor of the biquad filter
gain_db (float) – Gain of the biquad filter in dB
biquad_type (BiquadType) – Type of the biquad filter. Supported types: ‘peaking’, ‘lowpass_2’, ‘highpass_2’, ‘lowshelf’, ‘highshelf’, ‘notch’, ‘allpass’, ‘lowpass_1’, ‘highpass_1’.
- filter(data: numpy.ndarray, sampling_rate: int, zero_pad_samples: int) → numpy.ndarray
Apply the filtering operation
- classmethod from_struct(struct: dict) → Biquad
Deserialize filter from a dict representation suitable for Polars Struct storage.
- Parameters:
struct (dict) – {‘type’: str, ‘params’: str} where type is class name and params is JSON string
- Return FilterDefinition:
The deserialized filter
- to_struct() → dict
Serialize filter to a dict representation suitable for Polars Struct storage.
- Return dict:
{‘type’: str, ‘params’: str} where type is class name and params is JSON string
- class treble_sdk_shared.filter_definition.ButterworthFilter
Butterworth filtering for lowpass, highpass and bandpass filtering
- __init__(lp_order: int | None = None, hp_order: int | None = None, lp_frequency: float | None = None, hp_frequency: float | None = None, forward_backward: bool = True)
Initialize the butterworth filter
- Parameters:
lp_order (int) – low pass order, None will turn off the lp filtering, defaults to None
hp_order (int) – high pass order, None will turn off the lp filtering, defaults to None
lp_frequency (float) – low pass frequency, None will turn off the lp filtering, defaults to None
hp_frequency (float) – high pass frequency, None will turn off the lp filtering, defaults to None
forward_backward (bool) – Enable zero phase filtering, using forward-backwards filtering. This applies the filter twice, i.e. doubles the order of the filter, defaults to True
- filter(data: numpy.ndarray, sampling_rate: int, zero_pad_samples: int) → numpy.ndarray
Apply the filtering operation
- classmethod from_struct(struct: dict) → ButterworthFilter
Deserialize filter from a dict representation suitable for Polars Struct storage.
- Parameters:
struct (dict) – {‘type’: str, ‘params’: str} where type is class name and params is JSON string
- Return FilterDefinition:
The deserialized filter
- to_struct() → dict
Serialize filter to a dict representation suitable for Polars Struct storage.
- Return dict:
{‘type’: str, ‘params’: str} where type is class name and params is JSON string
- class treble_sdk_shared.filter_definition.DefaultBandpassRemovalFilter
A filter that “removes” the default treble bandpass filter (20Hz-crossover frequency) from the IR. This is useful when evaluation frequency responses
The filter works by dividing with the original filter, but compensating with another bandpass filter with a wider margin and higher order to remove. The response essentially moves rolloff outside of the passband and can therefore lead to artifacts in the time domain response.
- __init__(crossover_freq: float, sampling_rate: int, n_samples: int, compensate_hp: bool = True, compensate_lp: bool = True)
- static butterworth_cutoff_for_gain(freq_hz, gain=0.99, order=15, fs=32000)
Return the cutoff frequency (Hz) of a digital Butterworth low-pass filter of given order that achieves gain at freq_hz.
- filter(data: numpy.ndarray, sampling_rate: int, zero_pad_samples: int = 0)
Apply the filtering operation
- classmethod from_struct(struct: dict) → DefaultBandpassRemovalFilter
Deserialize filter from a dict representation suitable for Polars Struct storage.
- Parameters:
struct (dict) – {‘type’: str, ‘params’: str} where type is class name and params is JSON string
- Return FilterDefinition:
The deserialized filter
- to_struct() → dict
Serialize filter to a dict representation suitable for Polars Struct storage.
- Return dict:
{‘type’: str, ‘params’: str} where type is class name and params is JSON string
- class treble_sdk_shared.filter_definition.FIRFilter
Filtering using an finite impulse response filter
- __init__(fir_filter: numpy.ndarray, sampling_rate: int, zero_pad_samples: int = 0)
Initialize the filter with the FIR. The FIR should be a 1D array with the filter centered at the middle element and have an odd number of elements
- Parameters:
fir_filter (np.ndarray) – _description_
sampling_rate (int) – _description_
- filter(data: numpy.ndarray, sampling_rate: int, zero_pad_samples: int) → numpy.ndarray
Apply the filtering operation
- static from_ir_data(data: numpy.ndarray, sampling_rate: float, zero_pad_samples: int = 0) → FIRFilter
Creates an FIR filter from mono impulse response data
- Parameters:
- Return FIRFilter:
An FIRFilter that can be used to filter other IR’s
- static from_mono_ir(mono_ir: MonoIR) → FIRFilter
Creates an FIR filter using a mono IR, a rollback and wavespeed can be specified if the ir needs to be compensated for a certain propagation distance
- Parameters:
mono_ir (MonoIR) – mono ir to create the filter from
- Return FIRFilter:
An FIRFilter that can be used to filter other IR’s
- classmethod from_struct(struct: dict) → FIRFilter
Deserialize filter from a dict representation suitable for Polars Struct storage.
- Parameters:
struct (dict) – {‘type’: str, ‘params’: str} where type is class name and params is JSON string
- Return FilterDefinition:
The deserialized filter
- static inverse_filter_from_ir_data(data: numpy.ndarray, sampling_rate: float, zero_pad_samples: int = 0, crossover_frequency: float | None = None, regularization: float = 0.001, filter_length: int | None = None, n_window_samples: int = 64) → FIRFilter
Creates a correction FIR filter that spectrally inverts a reference impulse response.
The filter inverts both magnitude and phase of the reference IR within the default Treble bandpass (20 Hz HP, crossover LP). Outside the passband, the bandpass envelope rolls off the response so the filter behaves well in the time domain and avoids amplifying noise where the reference has little energy.
When applied to another IR, the result is that IR “relative to” the reference, with the reference’s delay and spectral shape removed.
- Parameters:
data (np.ndarray) – The reference impulse response data to invert
sampling_rate (float) – Sampling rate of the reference impulse response
zero_pad_samples (int) – Number of zero pad samples at the beginning of the reference impulse response
crossover_frequency (float) – Crossover frequency for the low-pass side of the bandpass envelope. Defaults to None, which uses 90% of the Nyquist frequency.
regularization (float) – Regularization parameter for the spectral inversion, expressed as a fraction of the peak spectral magnitude. Prevents amplification of noise at frequencies where the reference has little energy. Defaults to 1e-3.
filter_length (int) – Length of the output FIR filter in samples. A longer filter avoids circular wrap-around when the inverse impulse response is longer than the reference signal (common with low regularization or narrow-band references). Must be >= the reference signal length. Defaults to None, which uses 2x the reference signal length. The actual length is rounded up to odd as required by FIRFilter.
n_window_samples (int) – Number of samples to taper on each side of the filter using a Tukey window, capped so that the Tukey alpha does not exceed 0.1. Defaults to 64.
- Return FIRFilter:
An FIR filter that corrects for the reference IR
- static inverse_filter_from_mono_ir(mono_ir: MonoIR, crossover_frequency: float = None, regularization: float = 0.001, filter_length: int = None, n_window_samples: int = 64) → FIRFilter
Creates a correction FIR filter that spectrally inverts a reference MonoIR.
See
inverse_filter_from_ir_data()for the details of the inversion.- Parameters:
mono_ir (MonoIR) – The reference impulse response to invert
crossover_frequency (float) – Crossover frequency for the low-pass side of the bandpass envelope. Defaults to None, which uses 90% of the Nyquist frequency.
regularization (float) – Regularization parameter for the spectral inversion, expressed as a fraction of the peak spectral magnitude. Defaults to 1e-3.
filter_length (int) – Length of the output FIR filter in samples. Defaults to None, which uses 2x the reference signal length.
n_window_samples (int) – Number of samples to taper on each side of the filter using a Tukey window. Defaults to 64.
- Return FIRFilter:
An FIR filter that corrects for the reference IR
- to_struct() → dict
Serialize to Polars struct format
- class treble_sdk_shared.filter_definition.FilterDefinition
- abstract filter(data: numpy.ndarray, sampling_rate: int, zero_pad_samples: int) → numpy.ndarray
Apply the filtering operation
- abstract from_struct(struct: dict) → FilterDefinition
Deserialize filter from a dict representation suitable for Polars Struct storage.
- Parameters:
struct (dict) – {‘type’: str, ‘params’: str} where type is class name and params is JSON string
- Return FilterDefinition:
The deserialized filter
- abstract to_struct() → dict
Serialize filter to a dict representation suitable for Polars Struct storage.
- Return dict:
{‘type’: str, ‘params’: str} where type is class name and params is JSON string
- class treble_sdk_shared.filter_definition.GainFilter
Gain stage filter
- __init__(gain: float)
initialize the gain filter with the gain factor
- Parameters:
gain (float) – Linear gain factor to apply
- filter(ir: numpy.ndarray, sampling_rate: int, zero_pad_samples: int) → numpy.ndarray
Apply the filtering operation
- classmethod from_struct(struct: dict) → GainFilter
Deserialize filter from a dict representation suitable for Polars Struct storage.
- Parameters:
struct (dict) – {‘type’: str, ‘params’: str} where type is class name and params is JSON string
- Return FilterDefinition:
The deserialized filter
- to_struct() → dict
Serialize filter to a dict representation suitable for Polars Struct storage.
- Return dict:
{‘type’: str, ‘params’: str} where type is class name and params is JSON string
- class treble_sdk_shared.filter_definition.IIRFilter
Filtering using an infinite impulse response filter
- __init__(iir_filter: tuple[numpy.ndarray, numpy.ndarray], sampling_rate: int)
Initialize the filter with the IIR. The IIR should be a tuple of the numerator and denominator coefficients of the digital filter’s transfer function.
- filter(data: numpy.ndarray, sampling_rate: int, zero_pad_samples: int) → numpy.ndarray
Apply the filtering operation
- to_struct() → dict
Serialize to Polars struct format
- class treble_sdk_shared.filter_definition.OctaveBandFilter
- __init__(center_frequency: float, octave_fraction: int = 1, lp_order: int = 4, hp_order: int = 4, forward_backward: bool = True)
Defines a filter which bandpass filters across an octave band
- Parameters:
center_frequency (float) – The center frequency of the octave band
octave_fraction (int) – The fraction of the octave bands, defaults to 1
lp_order (int) – The order of the low pass filter, defaults to 4
hp_order (int) – The order of the high pass filter, defaults to 4
forward_backward (bool) – Enable zero phase filtering, using forward-backwards filtering. This applies the filter twice, i.e. doubles the order of the filter, defaults to True
- filter(data: numpy.ndarray, sampling_rate: int, zero_pad_samples: int) → numpy.ndarray
Apply the filtering operation
- classmethod from_struct(struct: dict) → OctaveBandFilter
Deserialize filter from a dict representation suitable for Polars Struct storage.
- Parameters:
struct (dict) – {‘type’: str, ‘params’: str} where type is class name and params is JSON string
- Return FilterDefinition:
The deserialized filter
- to_struct() → dict
Serialize filter to a dict representation suitable for Polars Struct storage.
- Return dict:
{‘type’: str, ‘params’: str} where type is class name and params is JSON string
- class treble_sdk_shared.filter_definition.TimeWindowFilter
A filter that applies a time window to the data
- __init__(start_time_s: float | None = None, end_time_s: float | None = None, fadein_length_s: float = 0.005, fadeout_length_s: float = 0.005)
- filter(data: numpy.ndarray, sampling_rate: float, zero_pad_samples: int) → numpy.ndarray
Apply the filtering operation
- classmethod from_struct(struct: dict) → TimeWindowFilter
Deserialize filter from a dict representation suitable for Polars Struct storage.
- Parameters:
struct (dict) – {‘type’: str, ‘params’: str} where type is class name and params is JSON string
- Return FilterDefinition:
The deserialized filter
- to_struct() → dict
Serialize filter to a dict representation suitable for Polars Struct storage.
- Return dict:
{‘type’: str, ‘params’: str} where type is class name and params is JSON string
- class treble_sdk_shared.filter_definition.TimeshiftFilter
A filter that applies a time shift to the data
- __init__(shift_seconds: float)
- filter(data: numpy.ndarray, sampling_rate: float, zero_pad_start: int) → numpy.ndarray
Apply the filtering operation
- classmethod from_struct(struct: dict) → TimeshiftFilter
Deserialize filter from a dict representation suitable for Polars Struct storage.
- Parameters:
struct (dict) – {‘type’: str, ‘params’: str} where type is class name and params is JSON string
- Return FilterDefinition:
The deserialized filter
- to_struct() → dict
Serialize filter to a dict representation suitable for Polars Struct storage.
- Return dict:
{‘type’: str, ‘params’: str} where type is class name and params is JSON string
- treble_sdk_shared.filter_definition.from_struct_dict(struct: dict) → FilterDefinition
Deserialize a filter from Polars struct format. Dispatches to the appropriate filter’s from_struct method.
- Parameters:
struct (dict) – {‘type’: str, ‘params’: str} where type is class name and params is JSON string
- Return FilterDefinition:
The deserialized filter