276 lines
12 KiB
Markdown
276 lines
12 KiB
Markdown
+++
|
||
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](https://docs.pipewire.org/page_module_filter_chain.html) module.
|
||
|
||
For an understanding of EQ, following resources might help.
|
||
|
||
- [The Headphone Show - EQ Basics](https://youtu.be/FRm9qTmQHKo?si=BFi0IH_XiCz1AxWa)
|
||
- [The Headphone Show - The Limits of EQ](https://www.youtube.com/watch?v=FD_s2s8Mw9k&t=0s)
|
||
- [Graphs 101 - How to Read Headphone Measurements](https://crinacle.com/2020/04/08/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](http://squig.link) or [autoeq.app](https://www.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](https://arachnoid.com/BiQuadDesigner/index.html), and seeing the effects on the frequency response helps. This linked article also goes into the basics of filters.
|
||
|
||
[***EasyEffects***](https://github.com/wwmm/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](https://docs.pipewire.org/page_module_filter_chain.html) 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](https://github.com/jaakkopasanen/AutoEq). While the web interface at [autoeq.app](https://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](https://github.com/jaakkopasanen/AutoEq?tab=readme-ov-file#installing). 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](https://github.com/jaakkopasanen/AutoEq/tree/master/measurements) directory and targets can be found in [targets](https://github.com/jaakkopasanen/AutoEq/tree/master/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.
|
||
|
||
```bash
|
||
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.
|
||
|
||
```bash
|
||
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](https://docs.pipewire.org/group__pw__context.html#details).
|
||
|
||
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-chain` module accepts
|
||
|
||
- Load the `filter-chain` module 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](https://gitlab.freedesktop.org/pipewire/pipewire/-/blob/master/src/daemon/filter-chain/sink-eq6.conf) 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 Hz`with 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` ,
|
||
|
||
```c
|
||
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.
|
||
|
||
```c
|
||
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.
|
||
|
||
```c
|
||
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.
|
||
|
||
```c
|
||
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](https://gitlab.freedesktop.org/pipewire/pipewire/-/merge_requests/2006).
|
||
|
||
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](https://gitlab.freedesktop.org/pipewire/pipewire/-/blob/master/src/modules/module-example-filter.c), [sink](https://gitlab.freedesktop.org/pipewire/pipewire/-/blob/master/src/modules/module-example-sink.c) and [source](https://gitlab.freedesktop.org/pipewire/pipewire/-/blob/master/src/modules/module-example-source.c) modules in the PipeWire repository.
|