dsp - Man Page

an audio processing program with an interactive mode

Synopsis

dsp [options] path ... [!] [:channel_selector] [@[~/]effects_file] [effect [args ...]] ...

Description

dsp is an audio processing program with an interactive mode.

Options

Global options

-h

Show help text.

-b frames

Set buffer size (must be given before the first input).

-R ratio

Set codec maximum buffer ratio (must be given before the first input).

-i

Force interactive mode.

-I

Disable interactive mode.

-q

Disable progress display.

-s

Silent mode.

-v

Verbose mode.

-d

Force dithering.

-D

Disable dithering.

-E

Don't drain effects chain before rebuilding.

-p

Plot effects chain instead of processing audio.

-V

Enable verbose progress display.

-S

Use `sequence' input combining mode.

Input/output options

-o

Output.

-t type

Type.

-e encoding

Encoding.

-B/L/N

Big/little/native endian.

-r frequency[k]

Sample rate.

-c channels

Number of channels.

-n

Equivalent to

	-t null null.

Inputs and Outputs

For a complete list of supported input/output types, run

	$ dsp -h

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.

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 resample and/or remix effects.

Effects

Full effects list

lowpass_1 f0[k]

Single-pole lowpass filter.

highpass_1 f0[k]

Single-pole highpass filter.

lowpass f0[k] width[q|o|h|k]

Double-pole lowpass filter.

highpass f0[k] width[q|o|h|k]

Double-pole highpass filter.

bandpass_skirt f0[k] width[q|o|h|k]

Double-pole bandpass filter with constant skirt gain.

bandpass_peak f0[k] width[q|o|h|k]

Double-pole bandpass filter with constant peak gain.

notch f0[k] width[q|o|h|k]

Double-pole notch filter.

allpass f0[k] width[q|o|h|k]

Double-pole allpass filter.

eq f0[k] width[q|o|h|k] gain

Double-pole peaking filter.

lowshelf f0[k] width[q|s|d|o|h|k] gain

Double-pole lowshelf filter.

highshelf f0[k] width[q|s|d|o|h|k] gain

Double-pole highshelf filter.

linkwitz_transform fz[k] qz fp[k] qp

Linkwitz transform (see http://www.linkwitzlab.com/filters.htm#9).

deemph

Compact Disc de-emphasis filter.

biquad b0 b1 b2 a0 a1 a2

Biquad filter.

gain [channel] gain

Gain adjustment. Ignores the channel selector when the channel argument is given.

mult [channel] multiplier

Multiplies each sample by multiplier. Ignores the channel selector when the channel argument is given.

crossfeed f0[k] separation

Simple crossfeed for headphones. Very similar to Linkwitz/Meier/CMoy/bs2b crossfeed.

remix channel_selector|. ...

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,

	remix 0,1 2,3

mixes input channels 0 and 1 into output channel 0, and input channels 2 and 3 into output channel 1.

	remix -

mixes all input channels into a single output channel.

delay delay[s|m|S]

Delay line. The unit for the delay argument depends on the suffix used: `s' is seconds (the default), `m' is milliseconds, and `S' is samples.

resample [bandwidth] fs[k]

Sinc resampler. Ignores the channel selector.

fir [~/]impulse_path

Non-partitioned 64-bit FFT convolution. Latency is equal to the length of the impulse.

zita_convolver [min_part_len [max_part_len]] [~/]impulse_path

Partitioned 32-bit FFT convolution using the zita-convolver library. Latency is equal to min_part_len (64 samples by default). {min,max}_part_len must be powers of 2 between 64 and 8192.

noise level

Add TPDF noise. The level argument specifies the peak level of the noise (dBFS).

compress thresh ratio attack release

Compress or expand the dynamic range. This effect peak-sensing and input channels are linked. If the ratio is in (1,inf), the dynamic range will be compressed. If the ratio is in (0,1), the dynamic range will be expanded. Attack refers to decreases in gain and release refers to increases in gain.

reverb [-w] [reverberance [hf_damping [room_scale [stereo_depth [pre_delay [wet_gain]]]]]]

Add reverberation using the freeverb algorithm. Effect ported from libSoX. reverberance, hf_damping, room_scale, and stereo_depth are in percent. pre_delay is in seconds.

g2reverb [-w] [room_size [reverb_time [input_bandwidth [damping [dry_level [reflection_level [tail_level]]]]]]]

Add reverberation using Fons Adriaensen's g2reverb algorithm.

ladspa_host module_path plugin_label [control ...]

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.

stats [ref_level]

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 ref_level is given, peak and RMS levels relative to ref_level will be shown as well (dBr).

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.

Selector syntax

[[start][-[end]][,...]]

ExampleDescription
<empty>all
-all
2-2 to n
-40 through 4
1,31 and 3
1-4,7,9-1 through 4, 7, and 9 to n

Width suffixes

SuffixDescription
qQ-factor (default).
sSlope (shelving filters only).
dSlope in dB/octave (shelving filters only).
oBandwidth in octaves.
hBandwidth in Hz.
kBandwidth in kHz.

Note: The `d' width suffix also changes the definition of f0 from center frequency to corner frequency (like Room EQ Wizard and the Behringer DCX2496).

File paths

  • On the command line, relative paths are relative to `$PWD'.
  • Within an effects file, relative paths are relative to the directory containing said effects file.
  • The `~/' prefix will be expanded to the contents of `$HOME'.

Effects file syntax

  • Arguments are delimited by whitespace.
  • If the first non-whitespace character in a line is `#', the line is ignored.
  • The `\' character removes any special meaning of the next character.

Example:

	gain -10
	# This is a comment
	eq 1k 1.0 +10.0 eq 3k 3.0 -4.0
	lowshelf 90 0.7 +4.0

Effects files inherit a copy of the current channel selector. In other words, if an effects chain is this:

	:2,4 @eq_file.txt eq 2k 1.0 -2.0

eq_file.txt will inherit the `2,4' selector, but any selector specified within eq_file.txt will not affect the `eq 2k 1.0 -2.0' effect that comes after it.

Examples

Read file.flac, apply a bass boost, and write to alsa device hw:2:

	dsp file.flac -ot alsa -e s24_3 hw:2 lowshelf 60 0.5 +4.0

Plot amplitude vs frequency for a complex effects chain:

	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

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:

	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 :

Apply effects from a file:

	dsp file.flac @eq.txt

Ladspa Frontend

Configuration

ladspa_dsp looks for configuration files in the following directories:

  • $XDG_CONFIG_HOME/ladspa_dsp
  • $HOME/.config/ladspa_dsp (if $XDG_CONFIG_HOME is not set)
  • /etc/ladspa_dsp

To override the default directories, set the `LADSPA_DSP_CONFIG_PATH' environment variable to the desired path(s) (colon-separated).

Each file that is named either config or config_<name> (where <name> is any string) is loaded as a separate plugin. The plugin label is either ladspa_dsp (for config) or ladspa_dsp:<name> (for config_<name>).

Configuration files are a simple key-value format. Leading whitespace is ignored. The valid keys are:

input_channels

Number of input channels. Default value is 1. May be left unset unless you want individual control over each channel.

output_channels

Number of output channels. Default value is 1. Initialization will fail if this value is set incorrectly.

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

effects_chain

String to build the effects chain. The format is the same as an effects file, but only a single line is interpreted.

Example configuration:

	# 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

Relative file paths in the effects_chain line are relative to the directory in which the configuration file resides.

The loglevel can be set to `VERBOSE', `NORMAL', or `SILENT' through the `LADSPA_DSP_LOGLEVEL' environment variable.

Note: The resample effect cannot be used with the LADSPA frontend.

Examples

See https://github.com/bmc0/dsp/blob/master/README.md for usage examples.

Bugs

No support for metadata.

Some effects do not support plotting.

License

This software is released under the ISC license, except for the reverb effect, which is under the LGPLv2.1 license (copyright robs@users.sourceforge.net), and the g2reverb effect, which is under the GPLv2 license (copyright Fons Adriaensen <fons@linuxaudio.org>). See the LICENSE files for more details.

Info

dsp-1.6