FAAR Command-Line Manual Page

The reference below is generated automatically from the upstream faar.1 manual page.

NAME

faar - open source sample rate converter for WAV and raw PCM audio

SYNOPSIS

faar [options] input [output]

faar [options] -o dir input...

DESCRIPTION

faar resamples WAV or raw PCM audio. WAV input is detected from its header, and a WAV file in an unsupported format is rejected rather than read as raw PCM; raw PCM input uses the rate, channel count, and format options below. A named output file is WAV when the input is WAV or the output name ends in .wav (case-insensitive). Output to stdout is raw PCM. Status and progress are written to stderr, so stdout can carry audio data. Existing output files are not replaced unless --overwrite is given; input and output paths that refer to the same file are always rejected.

Use -h for a short option summary or -H for detailed descriptions. The long form --help is an alias for -h.

INPUT AND OUTPUT OPTIONS

• -R, --in-rate Hz Set the raw PCM input rate [default: 44100 Hz]. WAV input uses its header rate.
• -c, --channels num Set audio channel count for raw PCM input [default: 2; range: 1 to 8, subject to the configured build limit]. WAV input uses its header channel count.
• -f, --format fmt Set sample format for raw PCM input and for output: f32le (default), s16le, or s24le. WAV input format comes from its header.
• -I, --ignorelength Ignore the WAV data length in the input header and read until end-of-file.
• --raw Treat input as raw PCM instead of detecting WAV. This is required for raw PCM piped to stdin; specify its format, channel count, and input rate as needed.
• -o, --output path Specify output file path (use - for stdout). When the path is an existing directory, every positional argument is an input and each result is written there under the input's file name; inputs with the same sample rate and channel count share one filter design.
• --overwrite Replace an existing output file. Input and output paths that refer to the same file are still rejected.

RESAMPLING OPTIONS

• -r, --rate Hz Set target output sampling rate in Hz. Required. The accepted range is 7350 through 192000 Hz, or up to 384000 Hz with --allow-extreme-rates. A rate pair must also be supported by the library.
• --quality preset Set the filter quality preset: fast, good (default) or high. See QUALITY PRESETS below for how they compare. Float builds (resampler-float) run High in compensated float arithmetic, which uses more CPU.
• -d, --dither type Set dithering mode for integer format output: none (default), tpdf (triangular dither), or shaped (TPDF dither with high-pass noise shaping).
• -D[<factor>], --decimate[=<factor>] Force a multi-stage filter for downsampling. The optional factor defaults to 2 and must be attached to the option, as in -D4 or --decimate=4. Large downsampling ratios may select multiple stages automatically.
• --allow-extreme-rates Allow output rates above 192000 Hz, up to 384000 Hz.

INFORMATION AND GENERAL OPTIONS

• -v level Set status verbosity: 0 suppresses informational output, 1 (default) shows progress, and 2 shows progress with a completion summary. Errors are always written to stderr.
• -q, --quiet Suppress progress and informational output. Errors are still shown.
• -h, --help Display the short option summary and exit. Use -H for detailed help.
• -H Display detailed descriptions of all options and examples, then exit.
• --license Display copyright and license information.

QUALITY PRESETS

Choose good unless you have a reason not to. The figures are approximate, taken as the worst case over synthetic probes on seven conversions (96 to 44.1, 48 to 44.1, 44.1 to 48, 96 to 48, 192 to 44.1, 192 to 48 and 48 to 24 kHz). They are not listening scores and vary with hardware, build and release.

	fast	good	high
Passband near Nyquist	about -3.4 dB	flat	flat
Min stopband rejection	about 106 dB	about 139 dB	about 154 dB
Worst residual	about -116 dB	about -135 dB	about -149 dB
Min image rejection	about 116 dB	about 147 dB	about 162 dB
Max filter delay	about 1 ms	about 3 ms	about 31 ms
Setup memory	about 0.15 MiB	about 0.4 MiB	about 4 MiB
CPU time vs good	about 0.85x	1x	about 1.5–2x

For reference, 16-bit audio has a noise floor about 96 dB below full scale and 24-bit about 144 dB.

• fast Least setup memory and delay, and a little less CPU than good. Its passband droops by about 3.4 dB near the Nyquist frequency.
• good Flat passband and strong alias rejection for general use.
• high About 15 dB more rejection than good, which matters mainly for 24-bit or float output. It costs roughly 1.5 to 2 times the CPU time, about ten times the setup memory and about 28 ms more filter lookahead.

EXAMPLES

Resample a 96 kHz WAV file to 48 kHz WAV:

faar -r 48000 input_96k.wav output_48k.wav

Resample with High Quality and TPDF dithering to 16-bit WAV in quiet mode:

faar -r 48000 --quality high -d tpdf -f s16le -v0 input.wav output.wav

Resample several files into a directory:

faar -r 48000 -o converted/ a.wav b.wav c.wav

Stream raw float PCM through a shell pipeline:

cat input.raw | faar --raw -r 48000 -c 2 -f f32le - - | aplay -f FLOAT_LE -r 48000 -c 2

EXIT STATUS

0 on success; nonzero on invalid options, unreadable input, resampler setup failure, or output error.

SEE ALSO

faac (1), faad (1), faam (1)

faac (1) is the AAC encoder. It is built and installed unless the encoder build option is disabled.

faad (1) is the AAC decoder. It is built and installed unless the decoder build option is disabled.

faam (1) is the MP4 muxer and tag tool. It is built and installed unless the muxer build option is disabled.

AUTHORS

FAAR is developed and maintained by Nils Schimmelmann.