ReSampler

Synopsis

ReSampler is a high-performance command-line audio sample rate conversion tool which can convert audio file formats with a variety of different bit-depths and audio channel configurations.

ReSampler compiles and runs on Windows, Linux and macOS

ReSampler is intended to produce outstanding quality sound files, keeping aliasing and other unwanted artifacts to a minimum, as the following actual measurement graphs show:

Typical frequency response when downsampling from 96kHz to 44.1kHz with standard (default) LPF

Spectrogram of 0-48kHz Sine Sweep @96kHz sample rate, after having been downsampled to 44kHz sample rate

Motivation

• experimentation with digital filters and some basic DSP concepts
• a requirement to have a simple command-line tool to be used in a script to convert a large collection of audio files
• a need for a quality SRC tool, as the quality of other offerings (both commercial and free) varies wildly from terrific to appalling

Design Philosophy

• ReSampler is first and foremost a converter. Other functionality (for example, generation of synthesised waveforms or spectrograms) is considered outside the scope of the project.
• Output file quality takes precedence over all other considerations, such as processing speed (although efforts to improve the latter will certainly be explored, they cannot be at the expense of the former)
• Core command-line options (the ones that are fundamental to performing a conversion) have a single hyphen and a single letter (eg -r 44100).
• Additional options (those that tweak or tune the behavior of the program in some way) follow the GNU long option style with two hyphens and a keyword (eg --dither)
• Command-line options selected by the user should be echoed to the user in the converter's console output, to confirm the acceptance and application of the options
• The introduction of new features to the converter should not change the basic behaviour of the converter, or the sound of files produced by the converter, UNLESS the user explicitly invokes the new features.

Usage

from the command line, the main options are as follows:

resampler.exe -i inputfile [-o outputfile] -r samplerate [-b bitformat] [-n [<normalization factor>]]

samplerate : target sample rate in Hz.

bitformat : bit representation (sub format) of the data in the output file. If this option is omitted, resampler will try to deduce the intended bit format automatically. Not all bit formats are valid for a given output file type. For more details, refer to the libsndfile documentation. Here is a list of all subformats:

8           8-bit (signed or unsigned - automatic, based on file type)
s8          Signed 8 bit data
16          Signed 16 bit data
24          Signed 24 bit data
32          Signed 32 bit data
u8          Unsigned 8 bit data
32f         32 bit float data
64f         64 bit float data
ulaw        mu-Law encoded
alaw        A-Law encoded
ima-adpcm   IMA ADPCM
ms-adpcm    Microsoft ADPCM
gsm610      GSM 6.10 encoding
vox-adpcm   OKI Dialogix ADPCM
g721-32     32kbs G721 ADPCM encoding
g723-24     24kbs G723 ADPCM encoding
g723-40     40kbs G723 ADPCM encoding
dwvw12      12 bit Delta Width Variable Word encoding
dwvw16      16 bit Delta Width Variable Word encoding
dwvw24      24 bit Delta Width Variable Word encoding
dwvwn       N bit Delta Width Variable Word encoding
dpcm8       8 bit differential PCM (XI only)
dpcm16      16 bit differential PCM (XI only)
vorbis      Xiph Vorbis encoding
alac16      Apple Lossless Audio Codec (16 bit)
alac20      Apple Lossless Audio Codec (20 bit)
alac24      Apple Lossless Audio Codec (24 bit)
alac32      Apple Lossless Audio Codec (32 bit)

Note: the --listsubformats option will cause the program to display the valid formats for a given file-type

Normalization factor : value between 0.0 and 1.0, with 1.0 (equivalent to 100 percent) producing the largest possible output level without clipping. Note: ReSampler will accept normalization values over 1.0, but this will certainly result in clipping, and is therefore only for experimental and testing purposes. Just using -n with no parameter is equivalent to -n 1.0

Additional options:

Note: as of version 2.0, command-line options are more "forgiving" - they are now case insensitive, and allow hyphens within the text of the option to be omitted. (However, the hyphens preceding the option are still required). This allows for variations such as the following to be possible: --steep-lpf --steeplpf --steep-LPF etc

--help : show usage and list additional commandline options

--version : display the version number of the program

--compiler : display compiler used to build the app

--sndfile-version : display the version of libsndfile library

--listsubformats <filetype> : list all valid subformats for a given filetype

--showDitherProfiles : show a list of all available dither profiles.

-i <inputfile> --info : display header and metadata information for the input file, without performing any conversion. See --info option for details.

--gain <amount> : adjust the gain (amplification factor). 1.0 = unity gain (no amplification), -1.0 = invert signal, 0 = silence. Note: if clipping protection is enabled, gain will be automatically re-adjusted after the first pass if clipping occurs.

Note: Setting the gain differs from applying normalization in that normalization is a type of automatic gain control, which sets the gain to whatever it needs to be to achieve the requested output level.

--doubleprecision : force ReSampler to use double-precision (64-bit floating point) arithmetic for its internal calculations.

--dither [<amount>] : generate +/-amount bits of dither. Dithering deliberately adds a small amount of a particular type of noise (triangular pdf with noise-shaping) prior to quantization to the output file. The goal of dithering is to reduce distortion, and allow extremely quiet passages to be preserved when they would otherwise be below the threshold of the target bit depth. Usually, it only makes sense to add dither when you are converting to a lower bit depth, for example:

• floating-point -> 16bit, or 8bit
• 24bit -> 16bit, or 8bit
• 16bit -> 8bit

The effect of dithering is most noticeable during extremely quiet passages (typically, in fade-outs) of the audio. If you can hear modulation effects, or "tearing" in the quietest passages of your output file, then a greater amount of dither may need to be applied. (note: in many cases, these passages are so quiet, you will need to normalize them just to hear them).

The amount parameter represents the number of bits of dither noise to be generated (prior to the noise-shaping process). The actual level of dither noise is equal to +/- 2^(amount-1) steps. The default for amount is 1.0, and it doesn't need to be an integer. Values in the range 1-6 are sensible for most situations. The noise-shaping curve may further increase the amplitude of the dither, depending on the "intensity" (overall gain) of the chosen noise-shaping curve.

--autoblank : when specified in conjunction with --dither , causes dithering to switch-off after 30,000 consecutive input samples of silence (< -193dB is considered silence). Dithering is re-enabled immediately upon a non-zero input sample being detected.

--ns <n> : select dither profile from 0-13. Generally speaking, as the dither profile number increases, the noise-shaping curve gets progressively more "intense" (higher amplitude), with the exception of profle 13 (blue noise) which is actually the most gentle profile. Dither profile 0 is completely flat (no noise shaping), and is equivalent to --flat-tpdf. The default dither profile (if no profile is specified) is #6 (standard), which has a moderate noise-shaping curve.

--flat-tpdf : when specified in conjunction with --dither , causes the dithering to use flat tpdf noise with no noise-shaping.

--seed <n> : when specified in conjunction with --dither , causes the pseudo-random number generator used to generate dither noise to generate a specific (repeatable) sequence of noise associated with the number n. Using the same value of n on subsequent conversions should reproduce precisely the same result. n is a signed integer in the range -2,147,483,648 through 2,147,483,647.

--quantize-bits <number of bits> : when used in conjunction with --dither, quantize the output to a specified number of bits. (eg. quantize to 8 bits when output is really 16 bits)

--noDelayTrim : deactivate correction of delay due to the linear-phase FIR anti-aliasing filter. By default, delay correction is active to ensure that the timing of the converted output file matches the timing of the input file precisely.

--minphase : use a minimum-phase FIR filter, instead of Linear-Phase

--flacCompression <compressionlevel> : set the compression level for flac output files (between 0 and 8)

--vorbisQuality <quality> : set the quality level for ogg vorbis output files (between -1 and 10)

--noClippingProtection : disable clipping protection (clipping protection is normally active b