.TH "libpipewire-module-filter-chain" 7 "1.1.82" "PipeWire" \" -*- nroff -*-
.ad l
.nh
.SH NAME
libpipewire-module-filter-chain \- Filter-Chain 
.SH DESCRIPTION
.PP
The filter-chain allows you to create an arbitrary processing graph from LADSPA, LV2 and builtin filters\&.
.PP
This filter can be made into a virtual sink/source or between any 2 nodes in the graph\&.
.PP
The filter chain is built with 2 streams, a capture stream providing the input to the filter chain and a playback stream sending out the filtered stream to the next nodes in the graph\&.
.PP
Because both ends of the filter-chain are built with streams, the session manager can manage the configuration and connection with the sinks and sources automatically\&.
.PP
.SH "MODULE NAME"
.PP
.PP
\fClibpipewire-module-filter-chain\fP
.PP
.SH "MODULE OPTIONS"
.PP
.PP
.IP "\(bu" 2
\fCnode\&.description\fP: a human readable name for the filter chain
.IP "\(bu" 2
\fCfilter\&.graph = []\fP: a description of the filter graph to run, see below
.IP "\(bu" 2
\fCcapture\&.props = {}\fP: properties to be passed to the input stream
.IP "\(bu" 2
\fCplayback\&.props = {}\fP: properties to be passed to the output stream
.PP
.PP
.SH "FILTER GRAPH DESCRIPTION"
.PP
.PP
The general structure of the graph description is as follows:
.PP
.PP
.nf
 filter\&.graph = {
     nodes = [
         {
             type = <ladspa | lv2 | builtin | sofa>
             name = <name>
             plugin = <plugin>
             label = <label>
             config = {
                 <configkey> = <value> \&.\&.\&.
             }
             control = {
                 <controlname|controlindex> = <value> \&.\&.\&.
             }
         }
         \&.\&.\&.
     ]
     links = [
         { output = <portname> input = <portname> }
         \&.\&.\&.
     ]
     inputs = [ <portname> \&.\&.\&. ]
     outputs = [ <portname> \&.\&.\&. ]
     capture\&.volumes = [
         { control = <portname>  min = <value>  max = <value>  scale = <scale> } \&.\&.\&.
     ]
     playback\&.volumes = [
         { control = <portname>  min = <value>  max = <value>  scale = <scale> } \&.\&.\&.
     ]
}
.fi
.PP
.PP
.SS "Nodes"
.PP
Nodes describe the processing filters in the graph\&. Use a tool like lv2ls or listplugins to get a list of available plugins, labels and the port names\&.
.PP
.IP "\(bu" 2
\fCtype\fP is one of \fCladspa\fP, \fClv2\fP, \fCbuiltin\fP or \fCsofa\fP\&.
.IP "\(bu" 2
\fCname\fP is the name for this node, you might need this later to refer to this node and its ports when setting controls or making links\&.
.IP "\(bu" 2
\fCplugin\fP is the type specific plugin name\&.
.IP "  \(bu" 4
For LADSPA plugins it will append \fC\&.so\fP to find the shared object with that name in the LADSPA plugin path\&.
.IP "  \(bu" 4
For LV2, this is the plugin URI obtained with lv2ls\&.
.IP "  \(bu" 4
For builtin and sofa this is ignored
.PP

.IP "\(bu" 2
\fClabel\fP is the type specific filter inside the plugin\&.
.IP "  \(bu" 4
For LADSPA this is the label
.IP "  \(bu" 4
For LV2 this is unused
.IP "  \(bu" 4
For builtin and sofa this is the name of the filter to use
.PP

.IP "\(bu" 2
\fCconfig\fP contains a filter specific configuration section\&. Some plugins need this\&. (convolver, sofa, delay, \&.\&.\&.)
.IP "\(bu" 2
\fCcontrol\fP contains the initial values for the control ports of the filter\&. normally these are given with the port name but it is also possible to give the control index as the key\&.
.PP
.PP
.SS "Links"
.PP
Links can be made between ports of nodes\&. The \fCportname\fP is given as \fC<node_name>:<port_name>\fP\&.
.PP
You can tee the output of filters to multiple other filters\&. You need to use a mixer if you want the output of multiple filters to go into one filter input port\&.
.PP
links can be omitted when the graph has just 1 filter\&.
.PP
.SS "Inputs and Outputs"
.PP
These are the entry and exit ports into the graph definition\&. Their number defines the number of channels used by the filter-chain\&.
.PP
The \fC<portname>\fP can be \fCnull\fP when a channel is to be ignored\&.
.PP
Each input/output in the graph can only be linked to one filter input/output\&. You need to use the copy builtin filter if the stream signal needs to be routed to multiple filters\&. You need to use the mixer builtin plugin if multiple graph outputs need to go to one output stream\&.
.PP
inputs and outputs can be omitted, in which case the filter-chain will use all inputs from the first filter and all outputs from the last filter node\&. The graph will then be duplicated as many times to match the number of input/output channels of the streams\&.
.PP
.SS "Volumes"
.PP
Normally the volume of the sink/source is handled by the stream software volume\&. With the capture\&.volumes and playback\&.volumes properties this can be handled by a control port in the graph instead\&. Use capture\&.volumes for the volume of the input of the filter (when for example used as a sink)\&. Use playback,volumes for the volume of the output of the filter (when for example used as a source)\&.
.PP
The min and max values (defaults 0\&.0 and 1\&.0) respectively can be used to scale and translate the volume min and max values\&.
.PP
Normally the control values are linear and it is assumed that the plugin does not perform any scaling to the values\&. This can be changed with the scale property\&. By default this is linear but it can be set to cubic when the control applies a cubic transformation\&.
.PP
.SH "BUILTIN FILTERS"
.PP
.PP
There are some useful builtin filters available\&. You select them with the label of the filter node\&.
.PP
.SS "Mixer"
.PP
Use the \fCmixer\fP plugin if you have multiple input signals that need to be mixed together\&.
.PP
The mixer plugin has up to 8 input ports labeled 'In 1' to 'In 8' and each with a gain control labeled 'Gain 1' to 'Gain 8'\&. There is an output port labeled 'Out'\&. Unused input ports will be ignored and not cause overhead\&.
.PP
.SS "Copy"
.PP
Use the \fCcopy\fP plugin if you need to copy a stream input signal to multiple filters\&.
.PP
It has one input port 'In' and one output port 'Out'\&.
.PP
.SS "Biquads"
.PP
Biquads can be used to do all kinds of filtering\&. They are also used when creating equalizers\&.
.PP
All biquad filters have an input port 'In' and an output port 'Out'\&. They have a 'Freq', 'Q' and 'Gain' control\&. Their meaning depends on the particular biquad that is used\&. The biquads also have 'b0', 'b1', 'b2', 'a0', 'a1' and 'a2' ports that are read-only except for the bq_raw biquad, which can configure default values depending on the graph rate and change those at runtime\&.
.PP
We refer to https://arachnoid.com/BiQuadDesigner/index.html for an explanation of the controls\&.
.PP
The following labels can be used:
.PP
.IP "\(bu" 2
\fCbq_lowpass\fP a lowpass filter\&.
.IP "\(bu" 2
\fCbq_highpass\fP a highpass filter\&.
.IP "\(bu" 2
\fCbq_bandpass\fP a bandpass filter\&.
.IP "\(bu" 2
\fCbq_lowshelf\fP a low shelf filter\&.
.IP "\(bu" 2
\fCbq_highshelf\fP a high shelf filter\&.
.IP "\(bu" 2
\fCbq_peaking\fP a peaking filter\&.
.IP "\(bu" 2
\fCbq_notch\fP a notch filter\&.
.IP "\(bu" 2
\fCbq_allpass\fP an allpass filter\&.
.IP "\(bu" 2
\fCbq_raw\fP a raw biquad filter\&. You need a config section to specify coefficients per sample rate\&. The coefficients of the sample rate closest to the graph rate are selected:
.PP
.PP
.PP
.nf
filter\&.graph = {
    nodes = [
        {
            type   = builtin
            name   = \&.\&.\&.
            label  = bq_raw
            config = {
                coefficients = [
                    { rate =  44100, b0=\&.\&., b1=\&.\&., b2=\&.\&., a0=\&.\&., a1=\&.\&., a2=\&.\&. },
                    { rate =  48000, b0=\&.\&., b1=\&.\&., b2=\&.\&., a0=\&.\&., a1=\&.\&., a2=\&.\&. },
                    { rate = 192000, b0=\&.\&., b1=\&.\&., b2=\&.\&., a0=\&.\&., a1=\&.\&., a2=\&.\&. }
                ]
            }
            \&.\&.\&.
        }
    }
    \&.\&.\&.
}
.fi
.PP
.PP
.SS "Convolver"
.PP
The convolver can be used to apply an impulse response to a signal\&. It is usually used for reverbs or virtual surround\&. The convolver is implemented with a fast FFT implementation\&.
.PP
The convolver has an input port 'In' and an output port 'Out'\&. It requires a config section in the node declaration in this format:
.PP
.PP
.nf
filter\&.graph = {
    nodes = [
        {
            type   = builtin
            name   = \&.\&.\&.
            label  = convolver
            config = {
                blocksize = \&.\&.\&.
                tailsize = \&.\&.\&.
                gain = \&.\&.\&.
                delay = \&.\&.\&.
                filename = \&.\&.\&.
                offset = \&.\&.\&.
                length = \&.\&.\&.
                channel = \&.\&.\&.
                resample_quality = \&.\&.\&.
            }
            \&.\&.\&.
        }
    }
    \&.\&.\&.
}
.fi
.PP
.PP
.IP "\(bu" 2
\fCblocksize\fP specifies the size of the blocks to use in the FFT\&. It is a value between 64 and 256\&. When not specified, this value is computed automatically from the number of samples in the file\&.
.IP "\(bu" 2
\fCtailsize\fP specifies the size of the tail blocks to use in the FFT\&.
.IP "\(bu" 2
\fCgain\fP the overall gain to apply to the IR file\&.
.IP "\(bu" 2
\fCdelay\fP The extra delay (in samples) to add to the IR\&.
.IP "\(bu" 2
\fCfilename\fP The IR to load or create\&. Possible values are:
.IP "  \(bu" 4
\fC/hilbert\fP creates a \fChilbert function\fP that can be used to phase shift the signal by +/-90 degrees\&. The \fClength\fP will be used as the number of coefficients\&.
.IP "  \(bu" 4
\fC/dirac\fP creates a \fCDirac function\fP that can be used as gain\&.
.IP "  \(bu" 4
A filename to load as the IR\&. This needs to be a file format supported by sndfile\&.
.IP "  \(bu" 4
[ filename, \&.\&.\&. ] an array of filenames\&. The file with the closest samplerate match with the graph samplerate will be used\&.
.PP

.IP "\(bu" 2
\fCoffset\fP The sample offset in the file as the start of the IR\&.
.IP "\(bu" 2
\fClength\fP The number of samples to use as the IR\&.
.IP "\(bu" 2
\fCchannel\fP The channel to use from the file as the IR\&.
.IP "\(bu" 2
\fCresample_quality\fP The resample quality in case the IR does not match the graph samplerate\&.
.PP
.PP
.SS "Delay"
.PP
The delay can be used to delay a signal in time\&.
.PP
The delay has an input port 'In' and an output port 'Out'\&. It also has a 'Delay (s)' control port\&. It requires a config section in the node declaration in this format:
.PP
.PP
.nf
filter\&.graph = {
    nodes = [
        {
            type   = builtin
            name   = \&.\&.\&.
            label  = delay
            config = {
                "max\-delay" = \&.\&.\&.
            }
            control = {
                "Delay (s)" = \&.\&.\&.
            }
            \&.\&.\&.
        }
    }
    \&.\&.\&.
}
.fi
.PP
.PP
.IP "\(bu" 2
\fCmax-delay\fP the maximum delay in seconds\&. The 'Delay (s)' parameter will be clamped to this value\&.
.PP
.PP
.SS "Invert"
.PP
The invert plugin can be used to invert the phase of the signal\&.
.PP
It has an input port 'In' and an output port 'Out'\&.
.PP
.SS "Clamp"
.PP
The clamp plugin can be used to clamp samples between min and max values\&.
.PP
It has an input port 'In' and an output port 'Out'\&. It also has a 'Control' and 'Notify' port for the control values\&.
.PP
The final result is clamped to the 'Min' and 'Max' control values\&.
.PP
.SS "Linear"
.PP
The linear plugin can be used to apply a linear transformation on samples or control values\&.
.PP
It has an input port 'In' and an output port 'Out'\&. It also has a 'Control' and 'Notify' port for the control values\&.
.PP
The control value 'Mult' and 'Add' are used to configure the linear transform\&. Each sample or control value will be calculated as: new = old * Mult + Add\&.
.PP
.SS "Reciprocal"
.PP
The recip plugin can be used to calculate the reciprocal (1/x) of samples or control values\&.
.PP
It has an input port 'In' and an output port 'Out'\&. It also has a 'Control' and 'Notify' port for the control values\&.
.PP
.SS "Exp"
.PP
The exp plugin can be used to calculate the exponential (base^x) of samples or control values\&.
.PP
It has an input port 'In' and an output port 'Out'\&. It also has a 'Control' and 'Notify' port for the control values\&.
.PP
The control value 'Base' is used to calculate base ^ x for each sample\&.
.PP
.SS "Log"
.PP
The log plugin can be used to calculate the logarithm of samples or control values\&.
.PP
It has an input port 'In' and an output port 'Out'\&. It also has a 'Control' and 'Notify' port for the control values\&.
.PP
The control value 'Base', 'M1' and 'M2' are used to calculate out = M2 * log2f(fabsf(in * M1)) / log2f(Base) for each sample\&.
.PP
.SS "Multiply"
.PP
The mult plugin can be used to multiply samples together\&.
.PP
It has 8 input ports named 'In 1' to 'In 8' and an output port 'Out'\&.
.PP
All input ports samples are multiplied together into the output\&. Unused input ports will be ignored and not cause overhead\&.
.PP
.SS "Sine"
.PP
The sine plugin generates a sine wave\&.
.PP
It has an output port 'Out' and also a control output port 'notify'\&.
.PP
'Freq', 'Ampl', 'Offset' and 'Phase' can be used to control the sine wave frequency, amplitude, offset and phase\&.
.PP
.SH "SOFA FILTER"
.PP
.PP
There is an optional builtin SOFA filter available\&.
.PP
.SS "Spatializer"
.PP
The spatializer can be used to place the sound in a 3D space\&.
.PP
The spatializer has an input port 'In' and a stereo pair of output ports called 'Out L' and 'Out R'\&. It requires a config section in the node declaration in this format:
.PP
The control can be changed at runtime to move the sounds around in the 3D space\&.
.PP
.PP
.nf
filter\&.graph = {
    nodes = [
        {
            type   = sofa
            name   = \&.\&.\&.
            label  = spatializer
            config = {
                blocksize = \&.\&.\&.
                tailsize = \&.\&.\&.
                filename = \&.\&.\&.
            }
            control = {
                "Azimuth" = \&.\&.\&.
                "Elevation" = \&.\&.\&.
                "Radius" = \&.\&.\&.
            }
            \&.\&.\&.
        }
    }
    \&.\&.\&.
}
.fi
.PP
.PP
.IP "\(bu" 2
\fCblocksize\fP specifies the size of the blocks to use in the FFT\&. It is a value between 64 and 256\&. When not specified, this value is computed automatically from the number of samples in the file\&.
.IP "\(bu" 2
\fCtailsize\fP specifies the size of the tail blocks to use in the FFT\&.
.IP "\(bu" 2
\fCfilename\fP The SOFA file to load\&. SOFA files usually end in the \&.sofa extension and contain the HRTF for the various spatial positions\&.
.IP "\(bu" 2
\fCAzimuth\fP controls the azimuth, this is the direction the sound is coming from in degrees between 0 and 360\&. 0 is straight ahead\&. 90 is left, 180 behind, 270 right\&.
.IP "\(bu" 2
\fCElevation\fP controls the elevation, this is how high/low the signal is in degrees between -90 and 90\&. 0 is straight in front, 90 is directly above and -90 directly below\&.
.IP "\(bu" 2
\fCRadius\fP controls how far away the signal is as a value between 0 and 100\&. default is 1\&.0\&.
.PP
.PP
.SH "GENERAL OPTIONS"
.PP
.PP
Options with well-known behavior\&. Most options can be added to the global configuration or the individual streams:
.PP
.IP "\(bu" 2
\fBremote.name\fP
.IP "\(bu" 2
\fBaudio.rate\fP
.IP "\(bu" 2
\fBaudio.channels\fP
.IP "\(bu" 2
\fBaudio.position\fP
.IP "\(bu" 2
\fBmedia.name\fP
.IP "\(bu" 2
\fBnode.latency\fP
.IP "\(bu" 2
\fBnode.description\fP
.IP "\(bu" 2
\fBnode.group\fP
.IP "\(bu" 2
\fBnode.link.group\fP
.IP "\(bu" 2
\fBnode.virtual\fP
.IP "\(bu" 2
\fBnode.name\fP : See notes below\&. If not specified, defaults to 'filter-chain-PID-MODULEID'\&.
.PP
.PP
Stream only properties:
.PP
.IP "\(bu" 2
\fBmedia.class\fP
.IP "\(bu" 2
\fBnode.name\fP : if not given per stream, the global node\&.name will be prefixed with 'input\&.' and 'output\&.' to generate a capture and playback stream node\&.name respectively\&.
.PP
.PP
.SH "EXAMPLE CONFIGURATION OF A VIRTUAL SOURCE"
.PP
.PP
This example uses the rnnoise LADSPA plugin to create a new virtual source\&.
.PP
.PP
.nf
context\&.modules = [
{   name = libpipewire\-module\-filter\-chain
    args = {
        node\&.description =  "Noise Canceling source"
        media\&.name =  "Noise Canceling source"
        filter\&.graph = {
            nodes = [
                {
                    type = ladspa
                    name = rnnoise
                    plugin = ladspa/librnnoise_ladspa
                    label = noise_suppressor_stereo
                    control = {
                        "VAD Threshold (%)" 50\&.0
                    }
                }
            ]
        }
        capture\&.props = {
            node\&.name =  "capture\&.rnnoise_source"
            node\&.passive = true
        }
        playback\&.props = {
            node\&.name =  "rnnoise_source"
            media\&.class = Audio/Source
        }
    }
}
]
.fi
.PP
.PP
.SH "EXAMPLE CONFIGURATION OF A DOLBY SURROUND ENCODER VIRTUAL SINK"
.PP
.PP
This example uses the ladpsa surround encoder to encode a 5\&.1 signal to a stereo Dolby Surround signal\&.
.PP
.PP
.nf
context\&.modules = [
{   name = libpipewire\-module\-filter\-chain
    args = {
        node\&.description = "Dolby Surround Sink"
        media\&.name       = "Dolby Surround Sink"
        filter\&.graph = {
            nodes = [
                {
                    type  = builtin
                    name  = mixer
                    label = mixer
                    control = { "Gain 1" = 0\&.5 "Gain 2" = 0\&.5 }
                }
                {
                    type   = ladspa
                    name   = enc
                    plugin = surround_encoder_1401
                    label  = surroundEncoder
                }
            ]
            links = [
                { output = "mixer:Out" input = "enc:S" }
            ]
            inputs  = [ "enc:L" "enc:R" "enc:C" null "mixer:In 1" "mixer:In 2" ]
            outputs = [ "enc:Lt" "enc:Rt" ]
        }
        capture\&.props = {
            node\&.name      = "effect_input\&.dolby_surround"
            media\&.class    = Audio/Sink
            audio\&.channels = 6
            audio\&.position = [ FL FR FC LFE SL SR ]
        }
        playback\&.props = {
            node\&.name      = "effect_output\&.dolby_surround"
            node\&.passive   = true
            audio\&.channels = 2
            audio\&.position = [ FL FR ]
        }
    }
}
]
.fi
.PP