12 KiB
+++ title = "Writing a simple PipeWire parametric equalizer module" date = 2024-05-07 +++
Motivation
When using headphones or in-ear monitors (IEMs), one might want to EQ their headphones or IEMs. Equalization or EQ is the process of adjusting the volume of different frequency bands in an audio signal. Some popular EQ software are EasyEffects on Linux and Equalizer APO on Windows. PipeWire supports EQ via the filter-chain module.
For an understanding of EQ, following resources might help.
- The Headphone Show - EQ Basics
- The Headphone Show - The Limits of EQ
- Graphs 101 - How to Read Headphone Measurements
The basic idea is that there are some “standard” frequency response curves that might sound good to different individuals, and knowing the frequency response characteristics of a specific headphone/IEM model, you can apply a set of filters via an equalizer to achieve something close to the “standard” frequency response curve that sounds good to you.
Websites like Squig or autoeq.app generate a file for parametric equalization for a given target, but this isn't a format that can be directly given to filter chain module. Squig is also useful for evaluating the frequency response curves of various in-ear monitors and headphones when making buying decisions.
An example of Parametric EQ generated from either AutoEQ or Squig looks like below.
Preamp: -6.8 dB
Filter 1: ON PK Fc 20 Hz Gain -1.3 dB Q 2.000
Filter 2: ON PK Fc 31 Hz Gain -7.0 dB Q 0.500
Filter 3: ON PK Fc 36 Hz Gain 0.7 dB Q 2.000
Filter 4: ON PK Fc 88 Hz Gain -0.4 dB Q 2.000
Fc is the frequency, Gain is the amount with which the signal gets boosted or attenuated around that frequency. Q factor controls the bandwidth around the frequency point. To be more precise, Q is the ratio of center frequency to bandwidth. If the center frequency is fixed, the bandwidth is inversely proportional to Q implying that as one raises the Q, the bandwidth is narrowed. Q is by far the most useful tool a parametric EQ offers, allowing one to attenuate or boost a narrow or wide range of frequencies within each EQ band.
If one wants to build a better intuition for this, playing around with the filter type and parameters here, and seeing the effects on the frequency response helps. This linked article also goes into the basics of filters.
EasyEffects allows importing such a file via it’s Import APO option, however, one might want to use an EQ input like this directly in PipeWire without having to resort to additional software like EasyEffects. However, during the course of testing, trying out multiple EQ is definitely much easier with EasyEffects GUI.
Now, this needs to be converted manually into something which filter-chain module can accept.
To simplify this, a simple PipeWire module is implemented which reads a parametric EQ text file like preceding and loads filter chain module while translating the inputs from the text file to what the filter chain module expects.
Before writing the PipeWire module, generate such a parametric equalizer file for a selected headphone and target using AutoEq. While the web interface at autoeq.app can be used, below section covers how to do this from the command line.
Automatic headphone equalization
Installation instructions for AutoEq can be found here. Take the example of Beyerdynamic DT1990 headphone and Diffuse Field 5128 target. For brevity sake, what target curve to select and why isn't covered here.
Measurements can be found in measurements directory and targets can be found in targets directory. Note that if measurements aren't available for the selected headphone, earphone, or in-ear monitor, AutoEq can't be used. oratory1990 and crinacle are well known folks in the audiophile community who have provided measurements for various popular headphones and in-ears. oratory1990's measurements are considered below.
Create a results directory dt1990-results and then execute the below command.
python -m autoeq --input-file="measurements/oratory1990/data/over-ear/Beyerdynamic DT 1990 (balanced earpads).csv" --output-dir="dt1990-results" --target="targets/Diffuse field 5128.csv" --parametric-eq --fs=44100,48000
The results directory dt1990-results has the below output.
Beyerdynamic DT 1990 (balanced earpads).csv
Beyerdynamic DT 1990 (balanced earpads).png
Beyerdynamic DT 1990 (balanced earpads) GraphicEQ.txt
Beyerdynamic DT 1990 (balanced earpads) ParametricEQ.txt
README.md
The Beyerdynamic DT 1990 (balanced earpads) ParametricEQ.txt file has the parametric equalizer configuration needed which can be given to the PipeWire module discussed next. README has some information and recommendation.
Similar process can be followed for in-ear monitors as well.
Module
A module is a client in a shared library .so file which shares a PipeWire context with the loading entity. PipeWire context is an object which manages all locally available resources. See here.
A module is loaded when it's listed in a PipeWire configuration file. Module's entry point is the pipewire__module_init function.
Writing the module
A PipeWire module needs to go into src/modules directory. The file is named module-parametric-equalizer.c and starts with the pipewire__module_init function.
This module primarily has to two tasks:
-
Parse the provided equalizer configuration into what
filter-chainmodule accepts -
Load the
filter-chainmodule with these arguments
The focus is on these two tasks and ignore rest of the ceremony around writing the module.
Parsing parametric equalizer configuration
Below is the parametric equalizer configuration that was generated in the second section of this post. This configuration is converted to match the module args.
Preamp: -6.0 dB
Filter 1: ON LSC Fc 105 Hz Gain -5.2 dB Q 0.70
Filter 2: ON PK Fc 206 Hz Gain -5.3 dB Q 0.51
Filter 3: ON PK Fc 4532 Hz Gain 5.5 dB Q 0.41
Filter 4: ON PK Fc 791 Hz Gain 2.0 dB Q 1.43
Filter 5: ON PK Fc 6829 Hz Gain -3.8 dB Q 2.04
Filter 6: ON HSC Fc 10000 Hz Gain 3.1 dB Q 0.70
Filter 7: ON PK Fc 8944 Hz Gain -1.4 dB Q 2.88
Filter 8: ON PK Fc 3751 Hz Gain -1.6 dB Q 5.97
Filter 9: ON PK Fc 4458 Hz Gain 1.5 dB Q 6.00
Filter 10: ON PK Fc 39 Hz Gain -0.2 dB Q 1.88
For every line read, a node entry like below is generated.
{
type = builtin
name = eq_band_1
label = bq_low/highshelf/peaking
control = { "Freq" = Fc "Q" = Q "Gain" = Gain }
}
PipeWire repository contains a filter chain configuration here which shows the structure of args it expects.
When a pre-amp gain is required, which is usually the case when applying EQ, the first EQ band needs to be modified to apply a bq_highshelf filter at frequency 0 Hzwith the provided negative gain. Pre-amp gain is always negative to offset the effect of possible clipping introduced by the amplification resulting from EQ. For the example preceding,
{
type = builtin,
name = eq_band_1,
label = bq_highshelf,
control = { Freq = 0, Gain = -6.0, Q = 1.0 },
}
Similarly, for Filter 1 this would be
{
type = builtin,
name = eq_band_2,
label = bq_lowshelf,
control = { Freq = 105, Gain = -5.2, Q = 0.7 },
}
Similarly, for the other filters.
PipeWire as of this writing, doesn't have helpers to create module arguments in code. fprintf is used for constructing filter module arguments as a string.
First open a memstream ,
char *args = NULL;
size_t size;
FILE *memstream = open_memstream(&args, &size)
Write a helper function which generates a node entry for the nodes array in the filter chain configuration.
struct eq_node_param {
char filter_type[4];
char filter[4];
uint32_t freq;
float gain;
float q_fact;
};
void init_eq_node(FILE *f, const char *node_desc) {
fprintf(f, "{\n");
fprintf(f, "node.description = \"%s\"\n", node_desc);
fprintf(f, "media.name = \"%s\"\n", node_desc);
fprintf(f, "filter.graph = {\n");
fprintf(f, "nodes = [\n");
}
void add_eq_node(FILE *f, struct eq_node_param *param, uint32_t eq_band_idx) {
fprintf(f, "{\n");
fprintf(f, "type = builtin\n");
fprintf(f, "name = eq_band_%d\n", eq_band_idx);
if (strcmp(param->filter_type, "PK") == 0) {
fprintf(f, "label = bq_peaking\n");
} else if (strcmp(param->filter_type, "LSC") == 0) {
fprintf(f, "label = bq_lowshelf\n");
} else if (strcmp(param->filter_type, "HSC") == 0) {
fprintf(f, "label = bq_highshelf\n");
} else {
fprintf(f, "label = bq_peaking\n");
}
fprintf(f, "control = { \"Freq\" = %d \"Q\" = %f \"Gain\" = %f }\n", param->freq, param->q_fact, param->gain);
fprintf(f, "}\n");
}
void end_eq_node(struct impl *impl, FILE *f, uint32_t number_of_nodes) {
fprintf(f, "]\n");
fprintf(f, "links = [\n");
for (uint32_t i = 1; i < number_of_nodes; i++) {
fprintf(f, "{ output = \"eq_band_%d:Out\" input = \"eq_band_%d:In\" }\n", i, i + 1);
}
fprintf(f, "]\n");
fprintf(f, "}\n");
fprintf(f, "audio.channels = %d\n", impl->channels);
fprintf(f, "audio.position = %s\n", impl->position);
fprintf(f, "capture.props = {\n");
fprintf(f, "node.name = \"effect_input.eq%d\"\n", number_of_nodes);
fprintf(f, "media.class = Audio/Sink\n");
fprintf(f, "}\n");
fprintf(f, "playback.props = {\n");
fprintf(f, "node.name = \"effect_output.eq%d\"\n", number_of_nodes);
fprintf(f, "node.passive = true\n");
fprintf(f, "}\n");
fprintf(f, "}\n");
}
The parsing function relies on the preceding helpers and is now straight forward. Read line by line from the file stream using getline and use sscanf to parse the line itself and call these helpers.
spa_zero(eq_param);
/* Check for Pre-amp gain */
nread = getline(&line, &len, f);
if (nread != -1 && sscanf(line, "%*s %6f %*s", &eq_param.gain) == 1) {
memcpy(eq_param.filter, "ON", 2);
memcpy(eq_param.filter_type, "HSC", 3);
eq_param.freq = 0;
eq_param.q_fact = 1.0;
add_eq_node(memstream, &eq_param, eq_band_idx);
eq_band_idx++;
eq_bands++;
}
/* Read the filter bands */
while ((nread = getline(&line, &len, f)) != -1) {
spa_zero(eq_param);
if (sscanf(line, "%*s %*d: %3s %3s %*s %5d %*s %*s %6f %*s %*c %6f", eq_param.filter, eq_param.filter_type, &eq_param.freq, &eq_param.gain, &eq_param.q_fact) == 5) {
if (strcmp(eq_param.filter, "ON") == 0) {
add_eq_node(memstream, &eq_param, eq_band_idx);
eq_band_idx++;
eq_bands++;
}
}
}
end_eq_node(impl, memstream, eq_bands);
fclose(memstream);
memstream = NULL;
Now, args has a string representation of the parametric equalizer configuration which can now be passed while loading the filter chain module.
Loading filter-chain
The filter chain module can now be loaded with args from the previous step.
struct pw_impl_module *eq_module;
eq_module = pw_context_load_module(impl->context,
"libpipewire-module-filter-chain",
args, NULL);
Conclusion
The merge request for this upstream can be found here.
The module allows one to leverage the built-in equalizer capabilities of PipeWire via it’s filter chain module without having to resort to writing the configuration by hand.
There are examples on writing filter, sink and source modules in the PipeWire repository.