posts: Add post on PipeWire parametric equalizer

2024-05-07 18:17:58 +05:30

10 KiB

Raw Blame History

author	title	tags
Sanchayan Maity	Writing a simple PipeWire parametric equalizer module	linux, pipewire

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 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
Filter 5: ON PK Fc 430 Hz Gain 1.6 dB Q 0.700
Filter 6: ON PK Fc 3200 Hz Gain -1.5 dB Q 0.700
Filter 7: ON PK Fc 7800 Hz Gain -3.9 dB Q 2.000
Filter 8: ON PK Fc 13000 Hz Gain -6.7 dB Q 2.000
Filter 9: ON PK Fc 15000 Hz Gain 9.1 dB Q 0.700

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.

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-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

A Parametric EQ configuration generated via AutoEq or Squig, might look like below. This configuration is converted to match the module args.

Preamp: -2.4 dB
Filter 1: ON PK Fc 52 Hz Gain 1.0 dB Q 0.600
Filter 2: ON PK Fc 210 Hz Gain -0.5 dB Q 1.800
Filter 3: ON PK Fc 390 Hz Gain -0.5 dB Q 1.600
Filter 4: ON PK Fc 2100 Hz Gain 1.3 dB Q 1.200
Filter 5: ON PK Fc 3600 Hz Gain -1.7 dB Q 2.000
Filter 6: ON PK Fc 4900 Hz Gain 3.0 dB Q 2.000

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 = -2.4, Q = 1.0 },
}

Similarly, for Filter 1 this would be

{
  type    = builtin,
  name    = eq_band_2,
  label   = bq_peaking,
  control = { Freq = 52, Gain = 1.0, Q = 0.600 },
}

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.

10 KiB Raw Blame History Unescape Escape