
wav2cdr(1)                                             wav2cdr(1)

NAME
       wav2cdr - converts input in (or similar to) wav format to cdr for-
       mat suitable for writing onto audio CDs.

SYNOPSIS
       wav2cdr [options ...] [infile [outfile]] [--cut cutnumber ...]

VERSION
       This man page describes wav2cdr version 2.3.2.

DESCRIPTION
       wav2cdr is a conversion program for audio data which adopts  auto-
       matically  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):

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

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

           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

OPTIONS
       --cut NUM NUM [NUM...]
              Cut  the  input into pieces, cutting at positions NUM.  See
              sections about argument scanning and splitting below.

       --endsilence, --es DUR
              Adds the given amount of silence to the end of each  output
              file.

       --fadein LEN
              Fade  in  at  the start over a duration of LEN.  The syntax
              for LEN is the same as for cut numbers, see  section  about
              argument  scanning  below.  If cutting is active, fading is
              performed for each cut.

              Fading in is performed by increasing the amplitude  for  CD
              sectors  by  an  amount derived from LEN over a duration of
              LEN. --fadein 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.

       --fadeout LEN
              Fade out at the end over a duration of LEN.  The syntax for
              LEN is the same as for cut numbers, see section about argu-
              ment  scanning below.  If cutting is active, fading is per-
              formed for each cut.

              The computation is similar to --fadein.  --fadein  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
              --endsilence.

              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 the fade-out starts before the fade-in is finished, both
              will overlap, producing sensible results.

       --fscale FLOAT
              Scale data by FLOAT, i.e. multiply by FLOAT (1.0 does noth-
              ing).

       -h, -u, --usage
              Display usage.

       --help Display extensive help. (The information  is  derived  from
              and equivalent to this manual page.)

       --inbig, -I
              Input data is big endian (MSB, LSB) (Motorola).

       --incdr
              Read  cdr  format  (default  is wav). Sets the correct byte
              order.

       --infile, -r NAME
              Input filename. Defaults to stdin. '-' = stdin.

       --inlittle, -i
              Input data is little endian (LSB, MSB) (Intel).

       --inraw
              Read raw format. Byte order should be specified with  -i/-I
              (default big).

       --inwav
              Read wav format (default). Sets the correct byte order.

       --iscale NUM
              Scale data to NUM percent (100 does nothing).

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

       --noswapchannels
              Don't swap channels. (default)

       --outfile, -w NAME
              Write output to file NAME.  The track number is appended as
              a 2-digit number.  The default is to write output  to  std-
              out.   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.

       --outbig, -O
              Output data in big endian (MSB, LSB) (Motorola) byte order.

       --outlittle, -o
              Output data in little endian (LSB, MSB) (Intel) byte order.

       --quiet
              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 --verbose.

       --silencecuts
              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 --cut.  After  cutting,  every  second
              track  (those with even numbers) contains a silent interval
              and can be deleted.

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

              Silence   is   detected    by    applying    a    threshold
              (--silencethresh)  to  a value computed for each CD sector;
              the value must be below the threshold for a minimum  number
              of  sectors  (delay --silencedelay). Currently, the average
              is computed first (this is  the  DC  component);  then  the
              average of the absolute of the difference between each sam-
              ple 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 man-
              ually).

              The silence delay period is part of  the  signal  interval,
              not  the  silence interval. This means that each non-silent
              period has --silencedelay 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.

       --silencedelay 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
              --silencecuts. The delay can be specified with units in the
              same way as for --cut, and is truncated to full CD sectors.
              Default is 30C (=0.4s).

       --silenceinfo
              Similar  to  --silencecuts,  but it generates more informa-
              tion. Silent and non-silent intervals are listed in a tabu-
              lar format.  The output format is useful for documentation,
              but not for feeding back into --cut.  With  --verbose,  the
              silence  values  of each CD sector are shown as well.  This
              produces lots of output, but it is  useful  for  finding  a
              suitable --silencethresh.

       --silencethresh THRESHOLD
              Threshold for silence detection. Ignored without --silence-
              cuts.  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.

       --startsilence, --ss DUR
              Adds  the given amount of silence to the start of each out-
              put file.

       --swapchannels
              Swap the left with the right channel.

       --tocdr
              Write data in cdr format (default). Sets the  correct  byte
              order.

       --toraw
              Write  data  in  raw format. Byte order should be specified
              with -o/-O (default big).

       --towav
              Write data in wav format. Sets the correct byte order.

       --verbose
              Produce more output. Currently only used  by  --silencecuts
              and --silenceinfo.

       --version, -V
              Display version information.

       --     Stop  argument processing.  Remaining arguments can only be
              filenames, or cut numbers if cutting is used.

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 mis-
       taken as options (this is a must with GNU getopt()).

       All options which take an argument denoting a time accept the fol-
       lowing 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  (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  min-
       utes) 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.

Data formats:
       All data handling currently assumes signed 16-bit integers, inter-
       leaved 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.

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.

Scaling / Volume change:
       Scaling  can  be  performed  with either integer or floating point
       arithmetic.  Integer arithmatic is faster but possibly not as pre-
       cise. Values will saturate (i.e. be clipped), rather than be trun-
       cated. 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.   Nega-
       tive scale factors are allowed but might be of dubious value.

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.

Output file naming:
       Unless  output  is  to  stdout, the resulting filename is the name
       given with --outfile|--of. A period and a 2-digit track number are
       appended.

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 sec-
       tor number are discarded, as well as all sectors after and includ-
       ing  the  last sector number.  At least 2 sector numbers (cut num-
       bers) 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 file-
       name when only one cut is made, don't use --outfile but  write  to
       stdout and use output redirection.

        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

Cutting out silent intervals:
       Assuming  a digitised record is stored in record.wav, and is to be
       cut into tracks.

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

       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.

Information about silences and actual sound parts:
       --silenceinfo can be used in the same way  as  --silencecuts.   It
       produces output like

       (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

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

Messages:
       Progress messages and statistics are written to stderr when  writ-
       ing 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.

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

CDR Format:
       Raw sample data at a sampling rate of %li 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 %i
       bytes.  There are %i sectors per second.

BUGS / LIMITATIONS
       All operations can only be performed on a minimum of 1 CD block or
       a multiple thereof.

COPYRIGHT
       Copyright (C)
       Nov, Dec 1997, Jan, Mar, Apr, May 1998, Feb, May, Jun, Jul, Aug 1999 by
       Volker Kuhlmann  <v.kuhlmann@elec.canterbury.ac.nz>
       c/o EEE Dept, University of Canterbury, Christchurch,
       New Zealand

       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.

AUTHOR
       Volker Kuhlmann

wav2cdr                    22 Aug 1999                          1

