<NME> dsp.1
<BEF> .TH DSP 1 dsp\-1.9
.SH NAME
dsp \- an audio processing program with an interactive mode
.SH SYNOPSIS
.B dsp
[\fIoptions\fR] \fIpath\fR ... [\fI!\fR] [:\fIchannel_selector\fR]
[@[~/]\fIeffects_file\fR] [\fIeffect\fR [\fIargs\fR ...]] ...
.SH DESCRIPTION
.B dsp
is an audio processing program with an interactive mode.
.SH OPTIONS
.SS Global options
.TP
\fB\-h\fR
Show help text.
.TP
\fB\-b\fR \fIframes\fR
Set buffer size (must be given before the first input).
.TP
\fB\-R\fR \fIratio\fR
Set codec maximum buffer ratio (must be given before the first input).
.TP
\fB\-i\fR
Force interactive mode.
.TP
\fB\-I\fR
Disable interactive mode.
.TP
\fB\-q\fR
Disable progress display.
.TP
\fB\-s\fR
Silent mode.
.TP
\fB\-v\fR
Verbose mode.
.TP
\fB\-d\fR
Force dithering.
.TP
\fB\-D\fR
Disable dithering.
.TP
\fB\-E\fR
Don't drain effects chain before rebuilding.
.TP
\fB\-p\fR
Plot effects chain instead of processing audio.
.TP
\fB\-V\fR
Enable verbose progress display.
.TP
\fB\-S\fR
Use `sequence' input combining mode.
.SS Input/output options
.TP
\fB\-o\fR
Output.
.TP
\fB\-t\fR \fItype\fR
Type.
.TP
\fB\-e\fR \fIencoding\fR
Encoding.
.TP
\fB\-B\fR/\fBL\fR/\fBN\fR
Big/little/native endian.
.TP
\fB\-r\fR \fIfrequency\fR[\fBk\fR]
Sample rate.
.TP
\fB\-c\fR \fIchannels\fR
Number of channels.
.TP
\fB\-n\fR
Equivalent to
.EX
	\-t null null.
.EE
.SH INPUTS AND OUTPUTS
For a complete list of supported input/output types, run
.EX
	$ dsp -h
.EE
.SS Input combining modes
In concatenate mode (the default), the inputs are concatenated in the order
given and sent to the output. All inputs must have the same sample rate and
number of channels.
.PP
In sequence mode, the inputs are sent serially to the output like concatenate
mode, but the inputs do not need to have the same sample rate or number of
channels. The effects chain and/or output will be rebuilt/reopened when
required. Note that if the output is a file, the file will be truncated if it
is reopened. This mode is most useful when the output is an audio device, but
can also be used to concatenate inputs with different sample rates and/or
numbers of channels into a single output file when used with the \fBresample\fR
and/or \fBremix\fR effects.
.SS Signal generator
The \fBsgen\fR input type is a basic (for now, at least) signal generator that can
generate impulses and exponential sine sweeps. The syntax for the \fIpath\fR
argument is as follows:
.PP
[\fItype\fR[@\fIchannel_selector\fR][:\fIarg\fR[=\fIvalue\fR]...]][/\fItype\fR...][+\fIlen\fR[\fBs\fR|\fBm\fR|\fBS\fR]]
.PP
\fItype\fR may be `sine' for sine sweeps or tones, or `delta' for a delta function
(impulse). `sine' accepts the following arguments:
.TP
\fBfreq\fR=\fIf0\fR[\fBk\fR][-\fIf1\fR[\fBk\fR]]
Frequency. If \fIlen\fR is set and \fIf1\fR is given, an exponential sine sweep
is generated.
.PP
The arguments for `delta' are:
.TP
\fBoffset\fR=\fItime\fR[\fBs\fR|\fBm\fR|\fBS\fR]
Offset in seconds, miliseconds or samples.
.PP
Example:
.EX
	$ dsp -t sgen -c 2 sine@0:freq=500-1k/sine@1:freq=300-800+2 gain -10
.EE
.SH EFFECTS
.SS Full effects list
.TP
\fBlowpass_1\fR \fIf0\fR[\fBk\fR]
Single-pole lowpass filter.
.TP
\fBhighpass_1\fR \fIf0\fR[\fBk\fR]
Single-pole highpass filter.
.TP
\fBlowpass\fR \fIf0\fR[\fBk\fR] \fIwidth\fR[\fBq\fR|\fBo\fR|\fBh\fR|\fBk\fR]
Double-pole lowpass filter.
.TP
\fBhighpass\fR \fIf0\fR[\fBk\fR] \fIwidth\fR[\fBq\fR|\fBo\fR|\fBh\fR|\fBk\fR]
Double-pole highpass filter.
.TP
\fBbandpass_skirt\fR \fIf0\fR[\fBk\fR] \fIwidth\fR[\fBq\fR|\fBo\fR|\fBh\fR|\fBk\fR]
Double-pole bandpass filter with constant skirt gain.
.TP
\fBbandpass_peak\fR \fIf0\fR[\fBk\fR] \fIwidth\fR[\fBq\fR|\fBo\fR|\fBh\fR|\fBk\fR]
Double-pole bandpass filter with constant peak gain.
.TP
\fBnotch\fR \fIf0\fR[\fBk\fR] \fIwidth\fR[\fBq\fR|\fBo\fR|\fBh\fR|\fBk\fR]
Double-pole notch filter.
.TP
\fBallpass\fR \fIf0\fR[\fBk\fR] \fIwidth\fR[\fBq\fR|\fBo\fR|\fBh\fR|\fBk\fR]
Double-pole allpass filter.
.TP
\fBeq\fR \fIf0\fR[\fBk\fR] \fIwidth\fR[\fBq\fR|\fBo\fR|\fBh\fR|\fBk\fR] \fIgain\fR
Double-pole peaking filter.
.TP
\fBlowshelf\fR \fIf0\fR[\fBk\fR] \fIwidth\fR[\fBq\fR|\fBs\fR|\fBd\fR|\fBo\fR|\fBh\fR|\fBk\fR] \fIgain\fR
Double-pole lowshelf filter.
.TP
\fBhighshelf\fR \fIf0\fR[\fBk\fR] \fIwidth\fR[\fBq\fR|\fBs\fR|\fBd\fR|\fBo\fR|\fBh\fR|\fBk\fR] \fIgain\fR
Double-pole highshelf filter.
.TP
\fBlinkwitz_transform\fR \fIfz\fR[\fBk\fR] \fIqz\fR \fIfp\fR[\fBk\fR] \fIqp\fR
Linkwitz transform (see http://www.linkwitzlab.com/filters.htm#9).
.TP
\fBdeemph\fR
Compact Disc de-emphasis filter.
.TP
\fBbiquad\fR \fIb0\fR \fIb1\fR \fIb2\fR \fIa0\fR \fIa1\fR \fIa2\fR
Biquad filter.
.TP
\fBgain\fR [\fIchannel\fR] \fIgain\fR
Gain adjustment. Ignores the channel selector when the \fIchannel\fR argument
is given.
.TP
\fBmult\fR [\fIchannel\fR] \fImultiplier\fR
Multiplies each sample by \fImultiplier\fR. Ignores the channel selector when
the \fIchannel\fR argument is given.
.TP
\fBadd\fR [\fIchannel\fR] \fIvalue\fR
Applies a DC shift. Ignores the channel selector when the \fIchannel\fR
argument is given.
.TP
\fBcrossfeed\fR \fIf0\fR[\fBk\fR] \fIseparation\fR
Simple crossfeed for headphones. Very similar to Linkwitz/Meier/CMoy/bs2b
crossfeed.
.TP
\fBmatrix4\fR [[\fIoptions\fR] \fIsurround_level\fR]
2-to-4 channel (2 front and 2 surround) active matrix upmixer designed for
plain (i.e. unencoded) stereo material. The matrix coefficients and the
main ideas behind the steering behavior come from David Griesinger's
published works on matrix surround.

The intended speaker configuration is fronts at ±30° and surrounds between
±60° and ±120°. The surround speakers must be calibrated correctly in
level and frequency response for best results. No frequency contouring or
delay is done internally, so it is highly recommended to apply \fBdelay\fR and
\fBlowpass_1\fR effects to the surround outputs:
.EX
	matrix4 -6 :2,3 delay 15m lowpass_1 6k :
.EE
The settings shown above (-6dB surround level, 15ms delay, and 6kHz rolloff)
are a good starting point, but may be adjusted to taste. The default
\fIsurround_level\fR is -6dB.

The front outputs replace the original input channels and the surround
outputs are appended to the end of the channel list.

Options are given as a comma-separated list. Recognized options are:
.RS
.TP
\fIno_dir_boost\fR
Disable directional boost of front channels.
.TP
\fIshow_status\fR
Show a status line (slightly broken currently, but still useful for
debugging).
.TP
\fIsignal\fR
Toggle the effect when `effect.signal()' is called.
.RE
.TP
\fBremix\fR \fIchannel_selector\fR|. ...
Select and mix input channels into output channels. Each channel selector
specifies the input channels to be mixed to produce each output channel.
`.' selects no input channels. For example,
.EX
	remix 0,1 2,3
\fBdecorrelate\fR [\fIstages\fR]
Allpass decorrelator as described in ``Frequency-Dependent Schroeder
Allpass Filters'' by Sebastian J. Schlecht (doi:10.3390/app10010187).
Default number of stages is 5.
.TP
\fBzita_convolver\fR [\fImin_part_len\fR [\fImax_part_len\fR]] [~/]\fIfilter_path\fR
Partitioned 32-bit FFT convolution using the zita-convolver library.
\fBst2ms\fR
Convert stereo to mid/side.
.TP
\fBms2st\fR
Convert mid/side to stereo.
.TP
\fBdelay\fR \fIdelay\fR[\fBs\fR|\fBm\fR|\fBS\fR]
Delay line. The unit for the \fIdelay\fR argument depends on the suffix used:
`\fBs\fR' is seconds (the default), `\fBm\fR' is milliseconds, and `\fBS\fR' is samples.
.TP
\fBresample\fR [\fIbandwidth\fR] \fIfs\fR[\fBk\fR]
Sinc resampler. Ignores the channel selector.
.TP
\fBfir\fR [~/]\fIfilter_path\fR
Non-partitioned 64-bit FFT convolution. Latency is equal to the length
of the filter.
.TP
\fBfir_p\fR [\fImin_part_len\fR [\fImax_part_len\fR]] [~/]\fIfilter_path\fR
Non-uniform partitioned 64-bit FFT convolution. Runs slower than the
\fBzita_convolver\fR effect, but potentially useful if you need more precision
and/or lower latency. Latency is equal to \fImin_part_len\fR (16 samples by
default). \fI{min,max}_part_len\fR must be powers of 2.
.TP
\fBhilbert\fR \fItaps\fR
Simple FIR approximation of a Hilbert transform. The number of taps must be
odd. Bandwidth is controlled by the number of taps.
.TP
\fBdecorrelate\fR [\fIstages\fR]
Allpass decorrelator as described in ``Frequency-Dependent Schroeder
Allpass Filters'' by Sebastian J. Schlecht (doi:10.3390/app10010187).
Default number of stages is 5. The average group delay with the default
settings is about 8.5ms at high frequencies.
.TP
\fBzita_convolver\fR [\fImin_part_len\fR [\fImax_part_len\fR]] [~/]\fIfilter_path\fR
Partitioned 32-bit FFT convolution using the zita-convolver library.
Latency is equal to \fImin_part_len\fR (64 samples by default).
\fI{min,max}_part_len\fR must be powers of 2 between 64 and 8192.
.TP
\fBnoise\fR \fIlevel\fR
Add TPDF noise. The \fIlevel\fR argument specifies the peak level of the noise
(dBFS).
.TP
\fBladspa_host\fR \fImodule_path\fR \fIplugin_label\fR [\fIcontrol\fR ...]
Apply a LADSPA plugin. Supports any number of input/output ports (with
the exception of zero output ports). Plugins with zero input ports will
replace selected input channels with their output(s). If a plugin has one
or zero input ports, it will be instantiated multiple times to handle
multi-channel input.

Controls which are not explicitly set or are set to `-' will use default
values (if available).

The `LADSPA_PATH' environment variable can be used to set the search path
for plugins.
.TP
\fBstats\fR [\fIref_level\fR]
Display the DC offset, minimum, maximum, peak level (dBFS), RMS level
(dBFS), crest factor (dB), peak count, peak sample, number of samples, and
length (s) for each channel. If \fIref_level\fR is given, peak and RMS levels
relative to \fIref_level\fR will be shown as well (dBr).
.SS Exclamation mark
A `!' marks the effect that follows as `non-essential'. If an effect is marked
non-essential and it fails to initialize, it will be skipped.
.SS Selector syntax
[[\fIstart\fR][-[\fIend\fR]][,...]]
.TS
tab (|);
lB lB
lB l.
Example|Description
_
<empty>|all
\-|all
2-|2 to n
\-4|0 through 4
1,3|1 and 3
1-4,7,9-|1 through 4, 7, and 9 to n
.TE
.SS Width suffixes
.TS
tab (|);
lB lB
lB l.
Suffix|Description
_
q|Q-factor (default).
s|Slope (shelving filters only).
d|Slope in dB/octave (shelving filters only).
o|Bandwidth in octaves.
h|Bandwidth in Hz.
k|Bandwidth in kHz.
.TE
.PP
Note: The `\fBd\fR' width suffix also changes the definition of \fIf0\fR from
center frequency to corner frequency (like Room EQ Wizard and the Behringer
DCX2496).
.SS File paths
.IP *
On the command line, relative paths are relative to `$PWD'.
.IP *
Within an effects file, relative paths are relative to the directory
containing said effects file.
.IP *
The `~/' prefix will be expanded to the contents of `$HOME'.
.SS Effects file syntax
.IP *
Arguments are delimited by whitespace.
.IP *
If the first non-whitespace character in a line is `#', the line is ignored.
.IP *
The `\\' character removes any special meaning of the next character.
.PP
Example:
.EX
	gain -10
	# This is a comment
	eq 1k 1.0 +10.0 eq 3k 3.0 -4.0
	lowshelf 90 0.7 +4.0
.EE
.PP
Effects files inherit a copy of the current channel selector. In other words,
if an effects chain is this:
.EX
	:2,4 @eq_file.txt eq 2k 1.0 -2.0
.EE
\fIeq_file.txt\fR will inherit the `2,4' selector, but any selector specified
within \fIeq_file.txt\fR will not affect the `eq 2k 1.0 -2.0' effect that comes
after it.
.SH EXAMPLES
Read \fIfile.flac\fR, apply a bass boost, and write to alsa device \fIhw:2\fR:
.EX
	dsp file.flac -ot alsa -e s24_3 hw:2 lowshelf 60 0.5 +4.0
.EE
.PP
Plot amplitude vs frequency for a complex effects chain:
.EX
	dsp -pn gain -1.5 lowshelf 60 0.7 +7.8 eq 50 2.0 -2.7 eq 100 2.0 -3.9
	  eq 242 1.0 -3.8 eq 628 2.0 +2.1 eq 700 1.5 -1.0
	  lowshelf 1420 0.68 -12.5 eq 2500 1.3 +3.0 eq 3000 8.0 -1.8
	  eq 3500 2.5 +1.4 eq 6000 1.1 -3.4 eq 9000 1.8 -5.6
	  highshelf 10000 0.7 -0.5 | gnuplot
.EE
.PP
Implement an LR4 crossover at 2.2KHz, where output channels 0 and 2 are the
left and right woofers, and channels 1 and 3 are the left and right tweeters,
respectively:
.EX
	dsp stereo_file.flac -ot alsa -e s32 hw:3 remix 0 0 1 1 :0,2
	  lowpass 2.2k 0.707 lowpass 2.2k 0.707 :1,3 highpass 2.2k 0.707
	  highpass 2.2k 0.707 :
.EE
.PP
Apply effects from a file:
.EX
	dsp file.flac @eq.txt
.EE
.SH LADSPA FRONTEND
.SS Configuration
\fBladspa_dsp\fR looks for configuration files in the following directories:

.IP *
$XDG_CONFIG_HOME/ladspa_dsp
.IP *
$HOME/.config/ladspa_dsp (if $XDG_CONFIG_HOME is not set)
.IP *
/etc/ladspa_dsp
.PP
To override the default directories, set the `LADSPA_DSP_CONFIG_PATH'
environment variable to the desired path(s) (colon-separated).
.PP
Each file that is named either \fIconfig\fR or \fIconfig_<name>\fR (where \fI<name>\fR is
any string) is loaded as a separate plugin. The plugin label is either
\fIladspa_dsp\fR (for \fIconfig\fR) or \fIladspa_dsp:<name>\fR (for \fIconfig_<name>\fR).
.PP
Configuration files are a simple key-value format. Leading whitespace is
ignored. The valid keys are:
.TP
.B input_channels
Number of input channels. Default value is 1. May be left unset unless
you want individual control over each channel.
.TP
.B output_channels
Number of output channels. Default value is 1. Initialization will fail
if this value is set incorrectly.
.TP
.B LC_NUMERIC
Set `LC_NUMERIC' to the given value while building the effects chain. If
the decimal separator defined by your system locale is something other than
`.', you should set this to `C' (to use `.' as the decimal separator) or an
empty value (to use the decimal separator defined by your locale).
.TP
.B effects_chain
String to build the effects chain. The format is the same as an effects
file, but only a single line is interpreted.
.PP
Example configuration:
.EX
	# This is a comment
	input_channels=1
	output_channels=1
	LC_NUMERIC=C
	effects_chain=gain -3.0 lowshelf 100 1.0s +3.0 @/path/to/eq_file
.EE
.PP
Relative file paths in the \fBeffects_chain\fR line are relative to the
directory in which the configuration file resides.
.PP
The loglevel can be set to `VERBOSE', `NORMAL', or `SILENT' through the
`LADSPA_DSP_LOGLEVEL' environment variable.
.PP
Note: The resample effect cannot be used with the LADSPA frontend.
.SS Examples
See https://github.com/bmc0/dsp/blob/master/README.md for usage examples.
.SH BUGS
No support for metadata.
.PP
Some effects do not support plotting.
.SH LICENSE
This software is released under the ISC license.

<MSG> README.md, dsp.1: Add note about 'decorrelate' effect group delay.

<DFF> @@ -223,7 +223,8 @@ odd. Bandwidth is controlled by the number of taps.
 \fBdecorrelate\fR [\fIstages\fR]
 Allpass decorrelator as described in ``Frequency-Dependent Schroeder
 Allpass Filters'' by Sebastian J. Schlecht (doi:10.3390/app10010187).
-Default number of stages is 5.
+Default number of stages is 5. The average group delay with the default
+settings is about 8.5ms at high frequencies.
 .TP
 \fBzita_convolver\fR [\fImin_part_len\fR [\fImax_part_len\fR]] [~/]\fIfilter_path\fR
 Partitioned 32-bit FFT convolution using the zita-convolver library.

{'commit': 'diff --git a/README.md b/README.md\nindex 4e834d3..baa7752 100644\n--- a/README.md\n+++ b/README.md\n@@ -229,7 +229,8 @@ Example:\n * `decorrelate [stages]`  \n \tAllpass decorrelator as described in "Frequency-Dependent Schroeder\n \tAllpass Filters" by Sebastian J. Schlecht (doi:10.3390/app10010187).\n-\tDefault number of stages is 5.\n+\tDefault number of stages is 5. The average group delay with the default\n+\tsettings is about 8.5ms at high frequencies.\n * `noise level`  \n \tAdd TPDF noise. The `level` argument specifies the peak level of the noise\n \t(dBFS).\ndiff --git a/dsp.1 b/dsp.1\nindex 311325b..7f824df 100644\n--- a/dsp.1\n+++ b/dsp.1\n@@ -223,7 +223,8 @@ odd. Bandwidth is controlled by the number of taps.\n \\fBdecorrelate\\fR [\\fIstages\\fR]\n Allpass decorrelator as described in ``Frequency-Dependent Schroeder\n Allpass Filters\'\' by Sebastian J. Schlecht (doi:10.3390/app10010187).\n-Default number of stages is 5.\n+Default number of stages is 5. The average group delay with the default\n+settings is about 8.5ms at high frequencies.\n .TP\n \\fBzita_convolver\\fR [\\fImin_part_len\\fR [\\fImax_part_len\\fR]] [~/]\\fIfilter_path\\fR\n Partitioned 32-bit FFT convolution using the zita-convolver library.\n', 'commit_subject': "README.md, dsp.1: Add note about 'decorrelate' effect group delay.", 'repo_name': 'bmc0/dsp', 'committer': {'name': 'Michael Barbour', 'email': '5804d1e39640aa7434357829d31c0b09fd996fe0@gmail.com', 'time_sec': '1607634106', 'tz_offset': '-300', 'date': {'seconds': '1607634106'}}, 'commit_tree': '306f1344a48156701b8b92da68e00c05df4993ef', 'commit_message': "README.md, dsp.1: Add note about 'decorrelate' effect group delay.\n", 'language_name': 'C', 'license': 'isc', 'hunks': "@@ -223,7 +223,8 @@ odd. Bandwidth is controlled by the number of taps.\n \\fBdecorrelate\\fR [\\fIstages\\fR]\n Allpass decorrelator as described in ``Frequency-Dependent Schroeder\n Allpass Filters'' by Sebastian J. Schlecht (doi:10.3390/app10010187).\n-Default number of stages is 5.\n+Default number of stages is 5. The average group delay with the default\n+settings is about 8.5ms at high frequencies.\n .TP\n \\fBzita_convolver\\fR [\\fImin_part_len\\fR [\\fImax_part_len\\fR]] [~/]\\fIfilter_path\\fR\n Partitioned 32-bit FFT convolution using the zita-convolver library.\n", 'addition_count': 2, 'deletion_count': 1, 'src_file': 'a/dsp.1', 'tgt_file': 'b/dsp.1', 'file_extension': '.1', 'before_file': ".TH DSP 1 dsp\\-1.9\n.SH NAME\ndsp \\- an audio processing program with an interactive mode\n.SH SYNOPSIS\n.B dsp\n[\\fIoptions\\fR] \\fIpath\\fR ... [\\fI!\\fR] [:\\fIchannel_selector\\fR]\n[@[~/]\\fIeffects_file\\fR] [\\fIeffect\\fR [\\fIargs\\fR ...]] ...\n.SH DESCRIPTION\n.B dsp\nis an audio processing program with an interactive mode.\n.SH OPTIONS\n.SS Global options\n.TP\n\\fB\\-h\\fR\nShow help text.\n.TP\n\\fB\\-b\\fR \\fIframes\\fR\nSet buffer size (must be given before the first input).\n.TP\n\\fB\\-R\\fR \\fIratio\\fR\nSet codec maximum buffer ratio (must be given before the first input).\n.TP\n\\fB\\-i\\fR\nForce interactive mode.\n.TP\n\\fB\\-I\\fR\nDisable interactive mode.\n.TP\n\\fB\\-q\\fR\nDisable progress display.\n.TP\n\\fB\\-s\\fR\nSilent mode.\n.TP\n\\fB\\-v\\fR\nVerbose mode.\n.TP\n\\fB\\-d\\fR\nForce dithering.\n.TP\n\\fB\\-D\\fR\nDisable dithering.\n.TP\n\\fB\\-E\\fR\nDon't drain effects chain before rebuilding.\n.TP\n\\fB\\-p\\fR\nPlot effects chain instead of processing audio.\n.TP\n\\fB\\-V\\fR\nEnable verbose progress display.\n.TP\n\\fB\\-S\\fR\nUse `sequence' input combining mode.\n.SS Input/output options\n.TP\n\\fB\\-o\\fR\nOutput.\n.TP\n\\fB\\-t\\fR \\fItype\\fR\nType.\n.TP\n\\fB\\-e\\fR \\fIencoding\\fR\nEncoding.\n.TP\n\\fB\\-B\\fR/\\fBL\\fR/\\fBN\\fR\nBig/little/native endian.\n.TP\n\\fB\\-r\\fR \\fIfrequency\\fR[\\fBk\\fR]\nSample rate.\n.TP\n\\fB\\-c\\fR \\fIchannels\\fR\nNumber of channels.\n.TP\n\\fB\\-n\\fR\nEquivalent to\n.EX\n\t\\-t null null.\n.EE\n.SH INPUTS AND OUTPUTS\nFor a complete list of supported input/output types, run\n.EX\n\t$ dsp -h\n.EE\n.SS Input combining modes\nIn concatenate mode (the default), the inputs are concatenated in the order\ngiven and sent to the output. All inputs must have the same sample rate and\nnumber of channels.\n.PP\nIn sequence mode, the inputs are sent serially to the output like concatenate\nmode, but the inputs do not need to have the same sample rate or number of\nchannels. The effects chain and/or output will be rebuilt/reopened when\nrequired. Note that if the output is a file, the file will be truncated if it\nis reopened. This mode is most useful when the output is an audio device, but\ncan also be used to concatenate inputs with different sample rates and/or\nnumbers of channels into a single output file when used with the \\fBresample\\fR\nand/or \\fBremix\\fR effects.\n.SS Signal generator\nThe \\fBsgen\\fR input type is a basic (for now, at least) signal generator that can\ngenerate impulses and exponential sine sweeps. The syntax for the \\fIpath\\fR\nargument is as follows:\n.PP\n[\\fItype\\fR[@\\fIchannel_selector\\fR][:\\fIarg\\fR[=\\fIvalue\\fR]...]][/\\fItype\\fR...][+\\fIlen\\fR[\\fBs\\fR|\\fBm\\fR|\\fBS\\fR]]\n.PP\n\\fItype\\fR may be `sine' for sine sweeps or tones, or `delta' for a delta function\n(impulse). `sine' accepts the following arguments:\n.TP\n\\fBfreq\\fR=\\fIf0\\fR[\\fBk\\fR][-\\fIf1\\fR[\\fBk\\fR]]\nFrequency. If \\fIlen\\fR is set and \\fIf1\\fR is given, an exponential sine sweep\nis generated.\n.PP\nThe arguments for `delta' are:\n.TP\n\\fBoffset\\fR=\\fItime\\fR[\\fBs\\fR|\\fBm\\fR|\\fBS\\fR]\nOffset in seconds, miliseconds or samples.\n.PP\nExample:\n.EX\n\t$ dsp -t sgen -c 2 sine@0:freq=500-1k/sine@1:freq=300-800+2 gain -10\n.EE\n.SH EFFECTS\n.SS Full effects list\n.TP\n\\fBlowpass_1\\fR \\fIf0\\fR[\\fBk\\fR]\nSingle-pole lowpass filter.\n.TP\n\\fBhighpass_1\\fR \\fIf0\\fR[\\fBk\\fR]\nSingle-pole highpass filter.\n.TP\n\\fBlowpass\\fR \\fIf0\\fR[\\fBk\\fR] \\fIwidth\\fR[\\fBq\\fR|\\fBo\\fR|\\fBh\\fR|\\fBk\\fR]\nDouble-pole lowpass filter.\n.TP\n\\fBhighpass\\fR \\fIf0\\fR[\\fBk\\fR] \\fIwidth\\fR[\\fBq\\fR|\\fBo\\fR|\\fBh\\fR|\\fBk\\fR]\nDouble-pole highpass filter.\n.TP\n\\fBbandpass_skirt\\fR \\fIf0\\fR[\\fBk\\fR] \\fIwidth\\fR[\\fBq\\fR|\\fBo\\fR|\\fBh\\fR|\\fBk\\fR]\nDouble-pole bandpass filter with constant skirt gain.\n.TP\n\\fBbandpass_peak\\fR \\fIf0\\fR[\\fBk\\fR] \\fIwidth\\fR[\\fBq\\fR|\\fBo\\fR|\\fBh\\fR|\\fBk\\fR]\nDouble-pole bandpass filter with constant peak gain.\n.TP\n\\fBnotch\\fR \\fIf0\\fR[\\fBk\\fR] \\fIwidth\\fR[\\fBq\\fR|\\fBo\\fR|\\fBh\\fR|\\fBk\\fR]\nDouble-pole notch filter.\n.TP\n\\fBallpass\\fR \\fIf0\\fR[\\fBk\\fR] \\fIwidth\\fR[\\fBq\\fR|\\fBo\\fR|\\fBh\\fR|\\fBk\\fR]\nDouble-pole allpass filter.\n.TP\n\\fBeq\\fR \\fIf0\\fR[\\fBk\\fR] \\fIwidth\\fR[\\fBq\\fR|\\fBo\\fR|\\fBh\\fR|\\fBk\\fR] \\fIgain\\fR\nDouble-pole peaking filter.\n.TP\n\\fBlowshelf\\fR \\fIf0\\fR[\\fBk\\fR] \\fIwidth\\fR[\\fBq\\fR|\\fBs\\fR|\\fBd\\fR|\\fBo\\fR|\\fBh\\fR|\\fBk\\fR] \\fIgain\\fR\nDouble-pole lowshelf filter.\n.TP\n\\fBhighshelf\\fR \\fIf0\\fR[\\fBk\\fR] \\fIwidth\\fR[\\fBq\\fR|\\fBs\\fR|\\fBd\\fR|\\fBo\\fR|\\fBh\\fR|\\fBk\\fR] \\fIgain\\fR\nDouble-pole highshelf filter.\n.TP\n\\fBlinkwitz_transform\\fR \\fIfz\\fR[\\fBk\\fR] \\fIqz\\fR \\fIfp\\fR[\\fBk\\fR] \\fIqp\\fR\nLinkwitz transform (see http://www.linkwitzlab.com/filters.htm#9).\n.TP\n\\fBdeemph\\fR\nCompact Disc de-emphasis filter.\n.TP\n\\fBbiquad\\fR \\fIb0\\fR \\fIb1\\fR \\fIb2\\fR \\fIa0\\fR \\fIa1\\fR \\fIa2\\fR\nBiquad filter.\n.TP\n\\fBgain\\fR [\\fIchannel\\fR] \\fIgain\\fR\nGain adjustment. Ignores the channel selector when the \\fIchannel\\fR argument\nis given.\n.TP\n\\fBmult\\fR [\\fIchannel\\fR] \\fImultiplier\\fR\nMultiplies each sample by \\fImultiplier\\fR. Ignores the channel selector when\nthe \\fIchannel\\fR argument is given.\n.TP\n\\fBadd\\fR [\\fIchannel\\fR] \\fIvalue\\fR\nApplies a DC shift. Ignores the channel selector when the \\fIchannel\\fR\nargument is given.\n.TP\n\\fBcrossfeed\\fR \\fIf0\\fR[\\fBk\\fR] \\fIseparation\\fR\nSimple crossfeed for headphones. Very similar to Linkwitz/Meier/CMoy/bs2b\ncrossfeed.\n.TP\n\\fBmatrix4\\fR [[\\fIoptions\\fR] \\fIsurround_level\\fR]\n2-to-4 channel (2 front and 2 surround) active matrix upmixer designed for\nplain (i.e. unencoded) stereo material. The matrix coefficients and the\nmain ideas behind the steering behavior come from David Griesinger's\npublished works on matrix surround.\n\nThe intended speaker configuration is fronts at ±30° and surrounds between\n±60° and ±120°. The surround speakers must be calibrated correctly in\nlevel and frequency response for best results. No frequency contouring or\ndelay is done internally, so it is highly recommended to apply \\fBdelay\\fR and\n\\fBlowpass_1\\fR effects to the surround outputs:\n.EX\n\tmatrix4 -6 :2,3 delay 15m lowpass_1 6k :\n.EE\nThe settings shown above (-6dB surround level, 15ms delay, and 6kHz rolloff)\nare a good starting point, but may be adjusted to taste. The default\n\\fIsurround_level\\fR is -6dB.\n\nThe front outputs replace the original input channels and the surround\noutputs are appended to the end of the channel list.\n\nOptions are given as a comma-separated list. Recognized options are:\n.RS\n.TP\n\\fIno_dir_boost\\fR\nDisable directional boost of front channels.\n.TP\n\\fIshow_status\\fR\nShow a status line (slightly broken currently, but still useful for\ndebugging).\n.TP\n\\fIsignal\\fR\nToggle the effect when `effect.signal()' is called.\n.RE\n.TP\n\\fBremix\\fR \\fIchannel_selector\\fR|. ...\nSelect and mix input channels into output channels. Each channel selector\nspecifies the input channels to be mixed to produce each output channel.\n`.' selects no input channels. For example,\n.EX\n\tremix 0,1 2,3\n\\fBdecorrelate\\fR [\\fIstages\\fR]\nAllpass decorrelator as described in ``Frequency-Dependent Schroeder\nAllpass Filters'' by Sebastian J. Schlecht (doi:10.3390/app10010187).\nDefault number of stages is 5.\n.TP\n\\fBzita_convolver\\fR [\\fImin_part_len\\fR [\\fImax_part_len\\fR]] [~/]\\fIfilter_path\\fR\nPartitioned 32-bit FFT convolution using the zita-convolver library.\n\\fBst2ms\\fR\nConvert stereo to mid/side.\n.TP\n\\fBms2st\\fR\nConvert mid/side to stereo.\n.TP\n\\fBdelay\\fR \\fIdelay\\fR[\\fBs\\fR|\\fBm\\fR|\\fBS\\fR]\nDelay line. The unit for the \\fIdelay\\fR argument depends on the suffix used:\n`\\fBs\\fR' is seconds (the default), `\\fBm\\fR' is milliseconds, and `\\fBS\\fR' is samples.\n.TP\n\\fBresample\\fR [\\fIbandwidth\\fR] \\fIfs\\fR[\\fBk\\fR]\nSinc resampler. Ignores the channel selector.\n.TP\n\\fBfir\\fR [~/]\\fIfilter_path\\fR\nNon-partitioned 64-bit FFT convolution. Latency is equal to the length\nof the filter.\n.TP\n\\fBfir_p\\fR [\\fImin_part_len\\fR [\\fImax_part_len\\fR]] [~/]\\fIfilter_path\\fR\nNon-uniform partitioned 64-bit FFT convolution. Runs slower than the\n\\fBzita_convolver\\fR effect, but potentially useful if you need more precision\nand/or lower latency. Latency is equal to \\fImin_part_len\\fR (16 samples by\ndefault). \\fI{min,max}_part_len\\fR must be powers of 2.\n.TP\n\\fBhilbert\\fR \\fItaps\\fR\nSimple FIR approximation of a Hilbert transform. The number of taps must be\nodd. Bandwidth is controlled by the number of taps.\n.TP\n\\fBdecorrelate\\fR [\\fIstages\\fR]\nAllpass decorrelator as described in ``Frequency-Dependent Schroeder\nAllpass Filters'' by Sebastian J. Schlecht (doi:10.3390/app10010187).\nDefault number of stages is 5. The average group delay with the default\nsettings is about 8.5ms at high frequencies.\n.TP\n\\fBzita_convolver\\fR [\\fImin_part_len\\fR [\\fImax_part_len\\fR]] [~/]\\fIfilter_path\\fR\nPartitioned 32-bit FFT convolution using the zita-convolver library.\nLatency is equal to \\fImin_part_len\\fR (64 samples by default).\n\\fI{min,max}_part_len\\fR must be powers of 2 between 64 and 8192.\n.TP\n\\fBnoise\\fR \\fIlevel\\fR\nAdd TPDF noise. The \\fIlevel\\fR argument specifies the peak level of the noise\n(dBFS).\n.TP\n\\fBladspa_host\\fR \\fImodule_path\\fR \\fIplugin_label\\fR [\\fIcontrol\\fR ...]\nApply a LADSPA plugin. Supports any number of input/output ports (with\nthe exception of zero output ports). Plugins with zero input ports will\nreplace selected input channels with their output(s). If a plugin has one\nor zero input ports, it will be instantiated multiple times to handle\nmulti-channel input.\n\nControls which are not explicitly set or are set to `-' will use default\nvalues (if available).\n\nThe `LADSPA_PATH' environment variable can be used to set the search path\nfor plugins.\n.TP\n\\fBstats\\fR [\\fIref_level\\fR]\nDisplay the DC offset, minimum, maximum, peak level (dBFS), RMS level\n(dBFS), crest factor (dB), peak count, peak sample, number of samples, and\nlength (s) for each channel. If \\fIref_level\\fR is given, peak and RMS levels\nrelative to \\fIref_level\\fR will be shown as well (dBr).\n.SS Exclamation mark\nA `!' marks the effect that follows as `non-essential'. If an effect is marked\nnon-essential and it fails to initialize, it will be skipped.\n.SS Selector syntax\n[[\\fIstart\\fR][-[\\fIend\\fR]][,...]]\n.TS\ntab (|);\nlB lB\nlB l.\nExample|Description\n_\n<empty>|all\n\\-|all\n2-|2 to n\n\\-4|0 through 4\n1,3|1 and 3\n1-4,7,9-|1 through 4, 7, and 9 to n\n.TE\n.SS Width suffixes\n.TS\ntab (|);\nlB lB\nlB l.\nSuffix|Description\n_\nq|Q-factor (default).\ns|Slope (shelving filters only).\nd|Slope in dB/octave (shelving filters only).\no|Bandwidth in octaves.\nh|Bandwidth in Hz.\nk|Bandwidth in kHz.\n.TE\n.PP\nNote: The `\\fBd\\fR' width suffix also changes the definition of \\fIf0\\fR from\ncenter frequency to corner frequency (like Room EQ Wizard and the Behringer\nDCX2496).\n.SS File paths\n.IP *\nOn the command line, relative paths are relative to `$PWD'.\n.IP *\nWithin an effects file, relative paths are relative to the directory\ncontaining said effects file.\n.IP *\nThe `~/' prefix will be expanded to the contents of `$HOME'.\n.SS Effects file syntax\n.IP *\nArguments are delimited by whitespace.\n.IP *\nIf the first non-whitespace character in a line is `#', the line is ignored.\n.IP *\nThe `\\\\' character removes any special meaning of the next character.\n.PP\nExample:\n.EX\n\tgain -10\n\t# This is a comment\n\teq 1k 1.0 +10.0 eq 3k 3.0 -4.0\n\tlowshelf 90 0.7 +4.0\n.EE\n.PP\nEffects files inherit a copy of the current channel selector. In other words,\nif an effects chain is this:\n.EX\n\t:2,4 @eq_file.txt eq 2k 1.0 -2.0\n.EE\n\\fIeq_file.txt\\fR will inherit the `2,4' selector, but any selector specified\nwithin \\fIeq_file.txt\\fR will not affect the `eq 2k 1.0 -2.0' effect that comes\nafter it.\n.SH EXAMPLES\nRead \\fIfile.flac\\fR, apply a bass boost, and write to alsa device \\fIhw:2\\fR:\n.EX\n\tdsp file.flac -ot alsa -e s24_3 hw:2 lowshelf 60 0.5 +4.0\n.EE\n.PP\nPlot amplitude vs frequency for a complex effects chain:\n.EX\n\tdsp -pn gain -1.5 lowshelf 60 0.7 +7.8 eq 50 2.0 -2.7 eq 100 2.0 -3.9\n\t  eq 242 1.0 -3.8 eq 628 2.0 +2.1 eq 700 1.5 -1.0\n\t  lowshelf 1420 0.68 -12.5 eq 2500 1.3 +3.0 eq 3000 8.0 -1.8\n\t  eq 3500 2.5 +1.4 eq 6000 1.1 -3.4 eq 9000 1.8 -5.6\n\t  highshelf 10000 0.7 -0.5 | gnuplot\n.EE\n.PP\nImplement an LR4 crossover at 2.2KHz, where output channels 0 and 2 are the\nleft and right woofers, and channels 1 and 3 are the left and right tweeters,\nrespectively:\n.EX\n\tdsp stereo_file.flac -ot alsa -e s32 hw:3 remix 0 0 1 1 :0,2\n\t  lowpass 2.2k 0.707 lowpass 2.2k 0.707 :1,3 highpass 2.2k 0.707\n\t  highpass 2.2k 0.707 :\n.EE\n.PP\nApply effects from a file:\n.EX\n\tdsp file.flac @eq.txt\n.EE\n.SH LADSPA FRONTEND\n.SS Configuration\n\\fBladspa_dsp\\fR looks for configuration files in the following directories:\n\n.IP *\n$XDG_CONFIG_HOME/ladspa_dsp\n.IP *\n$HOME/.config/ladspa_dsp (if $XDG_CONFIG_HOME is not set)\n.IP *\n/etc/ladspa_dsp\n.PP\nTo override the default directories, set the `LADSPA_DSP_CONFIG_PATH'\nenvironment variable to the desired path(s) (colon-separated).\n.PP\nEach file that is named either \\fIconfig\\fR or \\fIconfig_<name>\\fR (where \\fI<name>\\fR is\nany string) is loaded as a separate plugin. The plugin label is either\n\\fIladspa_dsp\\fR (for \\fIconfig\\fR) or \\fIladspa_dsp:<name>\\fR (for \\fIconfig_<name>\\fR).\n.PP\nConfiguration files are a simple key-value format. Leading whitespace is\nignored. The valid keys are:\n.TP\n.B input_channels\nNumber of input channels. Default value is 1. May be left unset unless\nyou want individual control over each channel.\n.TP\n.B output_channels\nNumber of output channels. Default value is 1. Initialization will fail\nif this value is set incorrectly.\n.TP\n.B LC_NUMERIC\nSet `LC_NUMERIC' to the given value while building the effects chain. If\nthe decimal separator defined by your system locale is something other than\n`.', you should set this to `C' (to use `.' as the decimal separator) or an\nempty value (to use the decimal separator defined by your locale).\n.TP\n.B effects_chain\nString to build the effects chain. The format is the same as an effects\nfile, but only a single line is interpreted.\n.PP\nExample configuration:\n.EX\n\t# This is a comment\n\tinput_channels=1\n\toutput_channels=1\n\tLC_NUMERIC=C\n\teffects_chain=gain -3.0 lowshelf 100 1.0s +3.0 @/path/to/eq_file\n.EE\n.PP\nRelative file paths in the \\fBeffects_chain\\fR line are relative to the\ndirectory in which the configuration file resides.\n.PP\nThe loglevel can be set to `VERBOSE', `NORMAL', or `SILENT' through the\n`LADSPA_DSP_LOGLEVEL' environment variable.\n.PP\nNote: The resample effect cannot be used with the LADSPA frontend.\n.SS Examples\nSee https://github.com/bmc0/dsp/blob/master/README.md for usage examples.\n.SH BUGS\nNo support for metadata.\n.PP\nSome effects do not support plotting.\n.SH LICENSE\nThis software is released under the ISC license.\n", 'message': "README.md, dsp.1: Add note about 'decorrelate' effect group delay.\n", 'author_name': 'Michael Barbour', 'lang': '1'}