.TH wav2cdr 1 "27 Oct 2000" "wav2cdr"
.de Ss
.    sp
.    ft CW
.    nf
..
.de Se
.    fi
.    ft P
.    sp
..
.SH NAME
wav2cdr - 
converts input in (or similar to) wav format to cdr format suitable
for writing onto audio CDs.
.SH SYNOPSIS
.B "wav2cdr"
[\fIoptions\fP ...] [\fIinfile\fP [\fIoutfile\fP]] [--cut \fIcutnumber\fP ...]
.SH VERSION
This man page describes wav2cdr version 2.3.3.
.SH DESCRIPTION
wav2cdr is a conversion program for audio data which adopts automatically to
big and little endian machines. Its primary use was to convert wav to cdr, but
it is a little more flexible now and can handle some file formats and perform
some operations on the data. These formats are possible (reading and writing):

.nf
    wav   MS Windows sound
    cdr   audio CD
    raw   fixed sampling rate, channels, and bytes per sample
          (= that of cdr); byte order must be specified
.fi

These operations can be performed on the data (combinations are possible as
long as they are meaningful):

.nf
    Scaling (volume change), integer arithmetic
    Scaling (volume change), floating point arithmetic
    Cutting of the input into pieces / tracks
    Conversion to mono and back to stereo
    Swapping of the 2 channels
    Adding silence to (or removing from, see cutting) the
      start and/or end
    Generation of cut numbers along silent intervals, e.g.
      to break up a record into tracks
    Information about non-silent intervals
    Fading in and out
.fi
.SH OPTIONS
.TP
.B "\fI--cut\fP NUM NUM [NUM...]"
Cut the input into pieces, cutting at positions NUM.
See sections about argument scanning and splitting below.
.TP
.B "\fI--endsilence\fP, \fI--es\fP DUR"
Adds the given amount of silence to the end of each output file.
.TP
.B "\fI--fadein\fP LEN"
Fade in at the start over a duration of LEN.
The syntax for LEN is the same as for a cut number, see section about argument
scanning below.
If cutting is active, fade-in is applied to the beginning of each cut.

Fading in is performed by increasing the amplitude for CD sectors by an amount
derived from LEN over a duration of LEN. \fI--fadein\fP 3 would result in the
amplitude of the first sector lowered to 1/4, of the second sector to 2/4, and
the third sector to 3/4. The fourth sector is unchanged and has then reached
full amplitude.
.TP
.B "\fI--fadeout\fP LEN"
Fade out at the end over a duration of LEN.
The syntax for LEN is the same as for a cut number, see section about argument
scanning below.
If cutting is active, fad-out is applied to the end of each cut.

The computation is similar to \fI--fadein\fP. \fI--fadein\fP 3 would result in
the last 3 CD sectors having their amplitudes lowered to 3/4, 2/4, and 1/4. The
(non-existant) following sector is assumed to be silent.

To add silent sector(s) to the end of the audio file, use \fI--endsilence\fP.

Fading out can only be performed if the input size can be determined (i.e. the
input must be seekable and cannot be a pipe). If cutting is active, the end of
the cut is always known and the fade-out can be applied.

If the fade-out starts before the fade-in is finished, both will overlap,
producing sensible results.
.TP
.B "\fI--fscale\fP FLOAT"
Scale data by FLOAT, i.e. multiply by FLOAT (1.0 does nothing).
.TP
.B "\fI-h\fP, \fI-u\fP, \fI--usage\fP"
Display usage.
.TP
.B "\fI--help\fP"
Display extensive help. (The information is derived from and equivalent to this
manual page.)
.TP
.B "\fI--inbig\fP, \fI-I\fP"
Input data is big endian (MSB, LSB) (Motorola).
.TP
.B "\fI--incdr\fP"
Read cdr format (default is wav). Sets the correct byte order.
.TP
.B "\fI--infile\fP, \fI-r\fP NAME"
Input filename. Defaults to stdin. '-' = stdin.
.TP
.B "\fI--inlittle\fP, \fI-i\fP"
Input data is little endian (LSB, MSB) (Intel).
.TP
.B "\fI--inraw\fP"
Read raw format. Byte order should be specified with \fI-i\fP/\fI-I\fP (default
big).
.TP
.B "\fI--inwav\fP"
Read wav format (default). Sets the correct byte order.
.TP
.B "\fI--iscale\fP NUM"
Scale data to NUM percent (100 does nothing).
.TP
.B "\fI--monostereo\fP"
Convert input to mono and immediately back to stereo. The result is 2
channels with the same data. This can be useful in some cases.
.TP
.B "\fI--noswapchannels\fP"
Don't swap channels. (default)
.TP
.B "\fI--outfile\fP, \fI-w\fP NAME"
Write output to file NAME.
The track number is appended as a 2-digit number.
The default is to write output to stdout.
A NAME of '-' means stdout.
When cutting is active and more than one cut is made, output can not be written
to stdout and the use of this option is mandatory.
.TP
.B "\fI--outbig\fP, \fI-O\fP"
Output data in big endian (MSB, LSB) (Motorola) byte order.
.TP
.B "\fI--outlittle\fP, \fI-o\fP"
Output data in little endian (LSB, MSB) (Intel) byte order.
.TP
.B "\fI--quiet\fP"
Suppress progress output.
The name of this option might be misleading: it does not prevent copious output
in other places which might be turned on by \fI--verbose\fP.
.TP
.B "\fI--silencecuts\fP"
Generate cut numbers for cutting out silent intervals. This is useful
when digitising a whole record and then cutting it into tracks. The cut
numbers are output on stdout and can be fed back into \fI--cut\fP.
After cutting, every second track (those with even numbers) contains a
silent interval and can be deleted.

Together with \fI--verbose\fP, the silence value of each sector is printed as
well (can't be fed back into \fI--cut\fP then). This most likely produces some
VERY long lines.

Silence is detected by applying a threshold (\fI--silencethresh\fP) to a value
computed for each CD sector; the value must be below the threshold for a
minimum number of sectors (delay \fI--silencedelay\fP). Currently, the average
is computed first (this is the DC component); then the average of the absolute
of the difference between each sample and the DC component. The difference
between these 2 averages is compared with the threshold. Check whether the cuts
really fall into the silent intervals, and adjust threshold and duration if not
(or edit the cut numbers manually).

The silence delay period is part of the signal interval, not the silence
interval. This means that each non-silent period has \fI--silencedelay\fP
silence at the start and at the end. If the silent interval between two signal
intervals is less than (2 * silence delay), the silent part at the start of the
second signal period will be shortened.
.TP
.B "\fI--silencedelay\fP DELAY"
The duration for which the "input" must be below the threshold in order to be
detected as a silent interval. In other words, the number of sectors which must
be silent before a silent interval is detected. Ignored without
\fI--silencecuts\fP. The delay can be specified with units in the same way as
for \fI--cut\fP, and is truncated to full CD sectors. Default is 30C (=0.4s).
.TP
.B "\fI--silenceinfo\fP"
Similar to \fI--silencecuts\fP, but it generates more information. Silent and
non-silent intervals are listed in a tabular format.
The output format is useful for documentation, but not for
feeding back into \fI--cut\fP.
With \fI--verbose\fP, the silence values of each CD sector are shown as well.
This produces lots of output, but it is useful for finding a suitable
\fI--silencethresh\fP.
.TP
.B "\fI--silencethresh\fP THRESHOLD"
Threshold for silence detection. Ignored without \fI--silencecuts\fP.
Default is 10. Always select a threshold as low as possible. When
cutting a record into tracks, the threshold must be high enough to
recognise the crackling between pieces as silence. When the threshold
is too high, a little at the beginning and end of each piece might be
chopped off.

As a special case, if the threshold is set to 0 the usual numerical computation
of the silence value is bypassed, and the sector is deemed to be silent if all
samples are 0.
.TP
.B "\fI--startsilence\fP, \fI--ss\fP DUR"
Adds the given amount of silence to the start of each output file.
.TP
.B "\fI--swapchannels\fP"
Swap the left with the right channel.
.TP
.B "\fI--tocdr\fP"
Write data in cdr format (default). Sets the correct byte order.
.TP
.B "\fI--toraw\fP"
Write data in raw format. Byte order should be specified with \fI-o\fP/\fI-O\fP
(default big).
.TP
.B "\fI--towav\fP"
Write data in wav format. Sets the correct byte order.
.TP
.B "\fI--verbose\fP"
Produce more output. Currently only used by \fI--silencecuts\fP and
\fI--silenceinfo\fP.
.TP
.B "\fI--version\fP, \fI-V\fP"
Display version information.
.TP
.B "\fI--\fP"
Stop argument processing.
Remaining arguments can only be filenames, or cut numbers if cutting is used.
.SH Command line option scanning:
From left to right. Later settings may override previous ones. Beware to switch
file formats before byte ordering, or a byte order might be rejected for the
(then active) format. When not using cutting, remaining arguments are used to
fill up input and output filenames. When using cutting, remaining arguments are
assumed to be cut numbers. When using negative cut numbers, use -- to terminate
option processing or the negative numbers can be mistaken as options (this is a
must with GNU getopt()).

All options which take an argument denoting a time accept the following number
format. The number may be in decimal, octal (leading 0), or hexadecimal
(leading 0x or 0X). A one-letter unit may be following. If there is space
between the number and the unit, both must be quoted, as in "55 C". These units
are recognised: b (bytes), C (audio CD sectors), s (seconds). When no unit is
given, C is assumed. The progress display might only show numbers in some of
these units. Fractions for seconds are allowed.

Negative cut numbers are only allowed if the input size can be determined
(which will not be possible if the input comes from a pipe), and are shown as
the equivalent positive ones. If the last cut number is 0 it means the end of
the file. If the input file size can not be determined the longest possible
input (about 405 minutes) is substituted.

A filename of '-' is taken as stdin/stdout.

If wav2cdr was compiled to use GNU getopt(), argument scanning is more powerful
and long options can be shortened to significance. Options are also re-ordered;
this is nice but can be a trap. Use -- if in doubt, and don't mix options with
filename or cut number arguments.
.SH Data formats:
All data handling currently assumes signed 16-bit integers, interleaved for 2
channels, at a sampling rate of that of a CD. Only wav files with these
parameters can be read correctly. cdr files are in that format, and only raw
formats with these parameters can be processed. The only flexibility allowed
for raw is the byte order, which can be specified for both reading and
writing. The byte ordering for wav and cdr is fixed.
.SH Channel swapping:
Left and right channel are swapped, which is the same as swapping consecutive
16 bit values with each other. Also see 'CDR Format' below.
.SH Scaling / Volume change:
Scaling can be performed with either integer or floating point arithmetic.
Integer arithmatic is faster but possibly not as precise. Values will saturate
(i.e. be clipped), rather than be truncated. The speed of this operation
depends on the endianness of the input data, output data, and host. It is
slowest when bytes have to be swapped before scaling and swapped back after.
Negative scale factors are allowed but might be of dubious value.
.SH Mono / stereo:
Input data can be converted to mono and then back to stereo. The result is 2
channels with the same data. This can be useful in some cases.
.SH Output file naming:
Unless output is to stdout, the resulting filename is the name given with
\fI--outfile\fP. A period and a 2-digit track number are appended.
.SH Input data splitting:
Input data can be split into pieces resp. tracks. Currently cuts can only be
placed at multiples of audio CD sectors (at the sector boundaries), whether
the input format is cdr or not.

The cuts are placed at the given positions, which must be in ascending order
(or equal). Negative numbers are counted from the end of the input data. This
only works if the input is seekable (Unix pipes are not). Sectors of the input
are numbered from 0. Bytes of a header, which the input format might have, are
not counted.

Any number of cuts can be made, but only 99 tracks can be put on a CD. All
sectors before the first but not including the first sector number are
discarded, as well as all sectors after and including the last sector number.
At least 2 sector numbers (cut numbers) must be given, in which case one piece
is cut out.

If there are only 2 cut numbers (1 track to cut out) data can be
written to stdout or file. More than one track can only be written to file, the
track number will be added as an extension to the filename.
To avoid the track number to be appended to the filename when only one cut is
made, don't use \fI--outfile\fP but write to stdout and use output redirection.

.nf
 Example (assuming 50000 sectors in the input):
    wav2cdr < INPUT --outfile NAME --cut 500 20000 40000
         sectors     0-  499: discarded
                   500-19999: saved to NAME.01
                 20000-39999: saved to NAME.02
                 40000-49999: discarded
.fi
.SH Cutting out silent intervals:
Assuming a digitised record is stored in record.wav, and is to be cut into
tracks.

.nf
  wav2cdr < record.wav > cuts --silencecuts --silencedelay 2s
  wav2cdr < record.wav --of tracks --cut `cat cuts`
.fi

Will store the tracks of the record in track.01, track.02, ..., with the delay
for cutting at a silent part set to 2 seconds. The threshold used is the
default. Note the `` syntax works under Unix and in this case puts the
contents of file "cuts" on the command line.
.SH Information about silences and actual sound parts:
\fI--silenceinfo\fP can be used in the same way as \fI--silencecuts\fP.
It produces output like

.nf
(stdin):
 silnc         0 b,      0 C,    0 s, 00:00.00 min
  DIFF    811440 b,    345 C,    4 s, 00:04.22 min
   -->    811440 b,    345 C,    4 s, 00:04.22 min

 AUDIO    811440 b,    345 C,    4 s, 00:04.22 min
  DIFF  20603520 b,   8760 C,  116 s, 01:56.05 min
   -->  21414960 b,   9105 C,  121 s, 02:01.02 min
.fi

showing the beginning, length ("DIFF"), and end ("-->") of both silent
("silnc") and and non-silent ("AUDIO") intervals. This is useful for examining
existing tracks, but it can not be used with \fI--cut\fP.
.SH Messages:
Progress messages and statistics are written to stderr when writing to stdout,
and to stdout when writing to file. It is currently not possible to suppress
this, other than by redirection to the bit bucket.
.SH Writing wav format:
Only wav files with 2 channels, 16 bits per sample, and audio CD sampling rate
can be written. If the input data is different, the resulting wav file is
incorrect. Scaling can be performed when writing wav. Cutting can only be
performed in multiples of an audio CD sector size. When writing wav the output
must be seekable (e.g. no pipes).
.SH CDR Format:
Raw sample data at a sampling rate of 44100 Hz. The channels are interleaved.
The numbers are 16 bit signed integers with this byte order:
MSByte Left, LSByte Left, MSByte Right, LSByte Right.
The track size must be a multiple of the sector size of 2352 bytes.
There are 75 sectors per second.
.SH BUGS / LIMITATIONS
All operations can only be performed on a minimum of 1 CD block or a multiple
thereof.
.SH COPYRIGHT
.nf
Copyright (C)
Nov, Dec 1997, Jan, Mar, Apr, May 1998, Feb, May, Jun, Jul, 
Aug 1999, Oct 2000 by
Volker Kuhlmann  <VolkerKuhlmann@gmx.de>
c/o EEE Dept, University of Canterbury
Christchurch, New Zealand
.fi

Permission granted to use and distribute this software free of charge, provided
any improvements are sent back to the author. Comments and bug reports welcome.
All rights reserved. Standard disclaimer applies.
.SH AUTHOR
Volker Kuhlmann