cute70.jpg
CuteStudio Ltd.

TxtDeClip Pro Documentation

A text/batch program from CuteStudio Ltd used in streaming music systems.

Please make sure you have read the page on Installation and the Getting started guide before you continue.

DeClip is a command line program without graphics. To run it, you will need access to the command line on your computer. Linux and Mac are very similar, Windows is slightly different but you can readily find all the information you need on the web:

The reason you need a command line program for streaming audio is that most of the available audio streaming services are text based - written in Perl etc, and there is no interactive work at the music server side. Thus DeClip just gets passed a track to declip, so it merely reads it in, repairs it, writes it out and then exits.

terminal_t.png
in effect you need to get to your command line (by opening a terminal), find your files, and then run DeClip as detailed on this page and in the help:

WAV formats

DeClip Pro contains 16bit integer, 32bit integer and 32bit floating point declipping routines. This allows if to do some very fast conversions as well as declipping and levelling.

It also allows the format to be read from any to float, processed, and then written to any.
When levelling is used the internal format used is float 32.

OperationInput formatInternal formatOutput format
Fast declip, e.g. txtdeclip in.wav out.wav8/16/24/32/floatappropriate for inputas input
Levelling, e.g. txtdeclip -VL18.2 in.wav out.wav8/16/24/32/floatfloatas input
Conversion, e.g. txtdeclip -C24 -n in.wav out.wav8/16/24/32/floatappropriate for outputas requested (8/16/24/32/float)

Command line options

PLEASE NOTE This version introduces floating point arguments - all dB quantities will not work using old values.
i.e. if you used to use -VL185, now use -VL18.5 for a 18.5dB target.

TxtDeClip ProV3.0-0 written by Graham Wilkinson
Copyright (c) CuteStudio Ltd. 2004-2008, All Rights Reserved.
Licensed to CuteStudio Ltd. (dev copy)
Go to www.cutestudio.net for more information and programs.
Usage: declip -[JnAzsriXVkUaZoxdFSRvqMDWu] -[tmejCcEwhTpP(num)] -[INyflLgb(db)] -[G(string)] [in.wav [out.wav]]
FlagDescriptionDefault
Declipping options
-J:Just do it: ignore -t (declip anyway, defers analysis) false
-tN:Only declip if there are more clips per minute -t100
-n:No declipping true
-A:Round off false
-IF:Rounding zone in dB, relative to max signal -I1.00
-NF:Gap between clip and new rounded signal (dB) -N0.10
-mN:How flat is a clip, relative to a 16bit wav. -m300
-z:zero-lift - do not lift clip-edge values false
-yF:Max gain for simple declipping dB: -f3.3 = 3.3dB -y1.50
-fF:Max gain for non-simple declipping dB: -f2.5 = 2.5dB -f6.00
-s:Scan all WAVs in folder, update to 'declipped' sub-folder false
Effects
-r:Rotate channels, so L->R and R->L false
-i:Invert the waveforms (180 phase shift) false
-X:Reverse the whole track so it plays backwards. false
Level options
-V:Manage volume levels (internal float used) false
-lF:(with -V) Relative level to lower by (dB -l3 = 3dB) -l0.00
-LF:(with -V) Level to aim for (neg dB -L15 = -15dB) -L12.50
-gF:(with -V) Gap between clip and signal dB: -g5 = 0.5dB -g0.30
-k:(with -V) keep any channel level mismatch false
-U:(with -V) Unsafe - ignore gap (-g). This may re-clip. false
-a:(with -V) Average 50ms RMS blocks, instead of pure RMS false
Dithering options
-Z:Use dither in re-mastering false
-o:(with -Z) Correlate dither between channels false
-eN:(with -Z) Envelope/shape used in the dither -e2
-jN:(with -Z) LSBs used in the dither -j1
-x:(with -Z) Output is pure dither false
Conversion options
-CN:Convert to 8/16/24/32 rescaling or float(1), e.g. -C24 -C0
-cN:same as -C but without rescaling (may clip or be quiet) -c0
-d:Suggest deferral of conversion until write (for testing) false
-F:Force use of internal float false
-S:Strip non-data chunks appended to the wavfile false
-G*:Get rid of a named chunk, e.g. -Ggain will remove 'gain' -G(nul)
Resampling options
-R:Expand/resample to a new bitrate false
-EN:(with -R) The new bitrate (e.g. -E96000) -E0
-bF:(with -R) Kaiser window Beta (e.g. -b6.5) -b7.00
-wN:(with -R) Sinc window length (source samples) -w64
-hN:(with -R) Caching, big = better+slower, 0 = off/very slow -h50
Misc options
-v:Verbose false
-q:Quiet mode false
-M:Map dynamic usage (only 8 and 16bit) false
-D:Look at two WAV files and output a difference WAV file false
-W:Signal any differences (-L) with a big signal false
-TN:Wdiff: audio file signal compare, with threshold -T0
-pN:Printing (start) -p0
-PN:Printing (no. of samples) -P0
-u:Print usage in CuteText format true


The DeClip Pro command line options

DeClip has a huge number of options, here we attempt to explain some of them.

Basic declipping options

Only declip if there are more clips per minute (dflt: -t100)
This gives the option of not bothering to declip at all. This is mainly of use if you are not using the level option, otherwise you can just leave it alone.

-J

This will speed up the processing of long files sometimes, and forces a declip even if the threshold (-t) of clips/min is not reached.
Mostly just used for testing.

-n

No declipping (dflt: false)
Prevent declipping. This is handy for format conversions, level changes etc. It switches the declipping off.

-A

This switches mode into 'Rounding', which does not level but used the rounding zone to round off clipped peaks in a suitably scientific way.
This is most useful if your track is basically OK but clips now and again. It's a proper limiter.

-I1.23

Rounding zone size (with -A). 1dB is good, but others may suit you better.

-N1.23

Gap between new rounded waveform and clip limit. 0 is as loud as possible, lower gives CD players a better chance.

-m1234

How flat is a clip, relative to a 16bit wav. (dflt: -m300 or -0.08dB)
The tops of clips are not flat, so this gives a leeway. If you think a clipped waveform should be declipped to a greater extent - then try increasing this. For reasons of compatibility the scale is 'points in a 16bit waveform' and is scaled accordingly for other formats.

-z

zero-lift - do not lift clip-edge values (dflt: false)
When a point is found at the edge of a clip, technically this point is compressed. This option prevents DeClip from working out where it thinks it should be. This creates a slightly softer result. but not so realistic.

-y1.23

Max gain for simple declipping (dB)
The short clips (clips of 5 samples and smaller) are declipped in a fairly arbitrary manner and use a very different method than that of the longer clips. In practice this means they are highly dependant on the source material and generally need more taming. This is why the maximum gain from these is set lower than for the long clips.

-f1.23

Max gain for non-simple declipping (dB)
When a waveform segment is copied or shifted onto a clip-top, it can cause the new waveform to also be clipped. DeClip therefore detects how much extra gain there is and compresses the clip if necessary. On a standard (non levelling) DeClip the default of 6dB prevents any further clipping. If you are using levelling however it just acts as a sentry to tame spikes that will disrupt the levelling. 6dB is a good compromise but if you want unlimited dynamics just set it to a high value like 12dB - i.e. -f120.

-s

Scan all WAVs in folder, update to 'declipped' sub-folder (dflt: false)
This is useful when you've a whole folder full of WAV tracks that need processing and you want the same operation done on all of them. With this option you do not specify any file names, the current folder (where you run DeClip from) is scanned, and all output files are put into a new sub-folder named declipped, with their original file names.
I.e. this command is for batch processing.

Conversion options

-C1234

Convert to 8/16/24/32 rescaling or float(1), e.g. -C24 (dflt: -C0)
This allows you to convert your waveforms to different resolutions. If for instance you have a 24bit playback mechanism then you will lose no information when a 16bit input file is declipped. So for instance a declip command may be:
 txtdeclip -VL20 -C24 in.wav out.wav

-c1234

same as -C but without rescaling (may clip or be quiet) (dflt: -c0)
With the -C option above there is scaling carried out to convert for instance a 24bit waveform into a 16bit. If you are not using levelling then you can use this option to switch off scaling, with the proviso that:
  • Converting from float to integer will always scale appropriately
  • If you convert a higher bit signal into a lower one, there will be huge clipping generated


-d

Suggest deferral of conversion until write (for testing) (dflt: false)
This does not affect anything and is just used for testing.

-F

Force use of internal float (dflt: false)
This does not affect anything and is just used for testing.

-S

Strip non-data chunks appended to the wavfile (dflt: false)
WAV files are constructed of a RIFF header and a series of CHUNKS, like 'fmt' for the format info and 'data' for the sound data - for example. Some (other) programs add chunks to WAV files, which can make audio programs with insufficient format checking crash or refuse to read them.
Using the -S flag strips out all chunks except for the essential 'fmt' and 'data' chunks.

-Gchunk name

Get rid of a named chunk, e.g. -Ggain will remove 'gain' (dflt: -G(nul))
As above with -S, this option allows you to remove specific chunks only. For instance to remove all 'gain' chunks in all files in the current directory (fixed files going to 'declipped' folder - see above)
 txtdeclip -nGgain in.wav out.wav

Level options

All of these options require the -V flag (to switch on levelling) to be present.

-V

Switch levelling ON.
Manage volume levels (internal float used) (dflt: false)
All of these options require the -V flag (to switch on levelling) to be present.
All levels are measured in the middle 80% of the waveform. This means that the first 10% and the last 10% of a wavefor are ignored for the purposes of measuring the level of a track.

-Vl1.23

Relative level to lower by (dB)
If you also use -k, this has an overall 'volume control' effect.

-VL1.23

Level to aim for (neg dB)
This targets the RMS level to the specified one. (Average RMS if you also use -a). Two things can disturb this:
  1. If the level is too high and may be clipped or not allow a gap (-g) it is lowered to suit
  2. If the level is too high and a -U (unsafe) option is used, the output will become clipped


-Vg1.23

Gap between clip and signal (dB)
It allows the DAC some dynamic (overshoot) headroom, setting -g0 will allow waveforms to approach the edge, -g20 will give a 2.5dB gap.
It is worth noting that the -f option (above) can cause clipping only without levelling (or with levelling and -U).

-Vk

Keep any channel level mismatch (dflt: false)
Many CDs have an RMS level mismatch between the L and R channels, which in some circumstances you may wish to preserve.

-VU

Unsafe - ignore gap (-g). This may re-clip. (dflt: false)
This will allow a level seting (-Vl or -VL) to clip the waveform, otherwise the gap (-g) will always be maintained when using levelling.

-Va

RMS averaging. The default measuring method is to perform an RMS level of the whole track.
However an emerging standard of 'how loud is a track' is called RMS averaging or RMS Energy Calculation.

In this case the level is computed by dividing up the track into 50ms chunks, taking an RMS measurement of those, and then averaging all of the results together.
A useful resource is:

Resampling options

All of these options require the -E flag (to switch on resampling) to be present.
Resampling is a little slow and 'idiosyncratic' as there are a number of trade-offs.
It uses a simple convolution of a sinc function windowed with a Kaiser filter window

The Sinc function has a number of poles and the more you use, the slower but more accurate the filtering is.
After you have re-sampled a waveform, check the loudest parts in a waveform editor for ripple, and increase the Sinc window length as required, or change the Kaiser α or β (a single property referred to as beta here).
kaiser.gif
convolve.gif
The newly resampled output is built up from the finite impulse effect each of the source samples has, a process known as bandlimited interpolation. For further reading yu may be interested in Julius O. Smith III at Stanford.

-E1234

Switch resample ON.
Expand/resample to a new bitrate (e.g. -E96000) (dflt: -E0)
All of these options require the -E flag (to switch on resampling) to be present.
You are allowed pretty much any resampled rate, however if you go for a simple multiple (i.e. converting 44100 to 88200) you need far fewer terms in the sinc function than going to an uneven step, for instance going from 44100 to 96000.

-Eb1.23

Kaiser window Beta (β)
This has an effect on the window shape that has a big effect on the ripple in the resampled output. There is no time penalty associated with any value here - just accuracy.

-Ew1234

Sinc window length (source samples) (dflt: -w64)
This has a big effect on the ripple in the resampled output, especially when going to an uneven step, for instance going from 44100 to 96000:
./txtdeclip -n -E96000 -w7 -C24 tr2.wav out.wav
DeClip ProV2.3-0 written by Graham Wilkinson
 Copyright (c) CuteStudio Ltd. 2004-2008, All Rights Reserved.
Converting to 24bit wav
Reading 'tr2.wav', fmt: 2ch 44100:16, c1, data: len 9.478ms [418], 16bit -> 32bit float.
No declip requested. Just supply an input file if you want to analyse it.
Resample: 418 samples at 44100 -> 909 samples at 96000, ws[7], beta 7.000000, cf 50
Resample channel 1 (please wait)
Resample channel 2 (please wait)
Writing 'out.wav', fmt, data, 32bit float -> 24bit.
Which creates a huge ripple:
ripple_w7.gif
upping the filter to -w128 then smooths that off
ripple_w128.gif

You are allowed pretty much any filter length, i.e. you can use a length of 16, 22, 500 etc. However the value is in proportion to the speed, so a length of 100 will take twice as long as 50, because the number of computations are doubled.

-Eh1234

Caching, big = better+slower, 0 = off/very slow (dflt: -h50)
DeClip maintains flexibility by having no built in filter tables, the filter points are computed as they are needed. This however is very slow, and if you have all night to resample a waveform then by all means set it to -h0. However to speed up the operation a caching system is used to hold and re-use precomputed filter points, where the more points used, the more accurate (but slower) the resample.

However - simple multiple resamples (e.g. 44100 to 88200) need only a few cache positions anyway, in which case a value of -h10 will give full accuracy. However for complex or uneven steps, for instance going from 44100 to 96000, a value of 50 is useful and 100 or 200 is better.

Dithering

Dithering is the act of suppressing quantisation errors when going from a high resolution format to a lower one. For instance, if running DeClip and you use levelling (-V) or force a floating point (-F) the resultant waveform gain changes may sound better if we 'remaster' the track with dither, rather than just output the raw data.

The effect is to mask any quantisation noise with white noise, and lower the overall noise floor. It doesn't really do very much for treble however, and there may already be an element of dither left over from the original track, so you may need to listen before you decide.
i.e. some people however prefer the sound of the un-dithered output.

Useful references are:


Basically DeClip provides for a dither signal of between 1 to 8 bits with a noise shape (probability) of rectangle, triange and gaussian distributions. The dither is random enough to give a nice flat FFT plot and therefore suitable for studio and hi-fi use.

-Z

Enable dither in re-mastering.

-o

Correlate the dither between the channels. This causes exactly the same noise to be applied to both channels, hence maintaining stero separation.

-eN

Envelope/shape used in the dither. The usual setting is 2 which is a triangular probability distribution, known as TPDF or Triangular Probability Desnity Function. 1 is rectangular and 3+ are various gaussian.

-jN

Output LSBs used in the dither. A setting of 1 will apply dither to the lowest bit, 2 to the lowest 2 bits etc. You probably only need 1 or 2 really, if you decide to use dither.

This is not the total dither bits - for example if you are converting from 24bits to 16bits and dithering to 1bit (-j1) DeClip will apply an 8 + 1) or 9 bit dither to the 24bit signal before downscaling to 16bit.

-x

Setting this gives an output is pure dither, without signal.
This is so you can create a track of noise or analyse the dither signal.

Misc options

-v

Verbose (dflt: false)
This details every clip and how it was fixed. Be prepared for HUGE amounts of output!!
e.g:
Fixing channel 1 at 4.785ms [211] -> 4.966ms [219] (len 0.204ms [ 9]) ....
 found good at 218 (ch 0, started at 211, limit 219) (8 len)
 tweaking pos clip incursion of 1721.00 found between 4.785ms [211] and 4.966ms [219]
 - increase level to obey pos clip by -339.286072
 copy alt channel (0) declip chan 1 at 211( 8)
Fixing channel 1 at 4.966ms [219] -> 4.966ms [219] (len 0.023ms [ 1]) ....
 simple 1pt declip chan 1 at 219( 1)
Fixing channel 1 at 5.034ms [222] -> 5.057ms [223] (len 0.045ms [ 2]) ....
 simple 2pt declip chan 1 at 222( 2)
Fixing channel 1 at 5.510ms [243] -> 5.556ms [245] (len 0.068ms [ 3]) ....
 simple 3pt declip chan 1 at 243( 3)
Fixing channel 1 at 5.601ms [247] -> 5.964ms [263] (len 0.385ms [ 17]) ....
 found good at 251 (ch 0, started at 247, limit 263) (5 len)
 - increase level to obey pos clip by 172.000000
 shift (from 228) declip chan 1 at 247( 17)

-q

Quiet mode (dflt: false)
The reduces the amount of output from DeClip.

-u

Print usage in CuteText format (dflt: false)
For this documentation - it has no other purpose. The ultimate self documenting code Smiley 01

-M

Map dynamic usage (only 8 and 16bit) (dflt: false)
This gives a prinout of how often all of the values are used. It's often quite revealing.

-D

Look at two WAV files and output a difference WAV file (dflt: false)
This is just used for testing.
If you do not provide the output (3rd) file then the diff will just do the comparism.

-W

Signal any differences (-L) with a big signal (dflt: false)
This does not affect anything and is just used for testing - i.e. picking up where differences occur. You should NEVER play this waveform as it may contain lots of nasty spikes!!

-r

Rotate channels, so L→R and R→L (dflt: false)
As described - it reverses the stereo effect.

-i

Invert the waveforms (180° phase shift) (dflt: false)
Sometimes a CD has not got the absolute phasing correct, you can fix it with this option, i.e. use -ni.

-R

Reverse the whole track so it plays backwards. (dflt: false)
There is no sense to this option, it's just here because it's easy to do and can create some interesting effects!

-T1234

Wdiff: audio file signal compare, with threshold (dflt: -T0)
This is just used for testing. This diff will just do the comparism, and if the audio waveforms are within the required margin - it will exit with 0, else -1 or 255. The threshold is needed because different maths chips on different computers can vary the results by a tiny amount but the wavefrm is still valid.

-p1234

Printing (start) (dflt: -p0)
Use with -P to print out the values in a section of the WAV file.

-P1234

Printing (no. of samples) (dflt: -P0)

Usage examples

Some commonly used DeClip examples
NB: Only WAV format stereo is supported.

CommandDescription
txtdeclip -VL15 in.wav out.wav This will declip and level to -15dB RMS both channels
txtdeclip -VL15 -k in.wav out.wav This will declip and level to -15dB RMS both channels keeping the existing channel balance
txtdeclip -ni in.wav out.wav Invert (180° phase shift)
txtdeclip -nkVl6.5 in.wav out.wav Reduce the level by 6.5dB
txtdeclip -VL1 -g0 in.wav out.wav DeClip but leave at/expand to maximum level

Copyright © 2007-2016, CuteStudio Ltd.
Page generated in 0.110s, Powered by Silk V1.1-1 from Cutestudio