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

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

VERSION
   This man page describes wav2cdr version 2.1.

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 flex- ible  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, bytes (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

OPTIONS
   --cut NUMS
	Cut the input into pieces.  See  sections  below  about argument
	scanning and splitting.

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

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

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

   --help
	Display extensive help.  (The  information  is  derived from 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).

   --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
	Output filename; track number is appended as a  2-digit number.
	Defaults to stdout. '-' = stdout.

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

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

	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
	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 
	--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  information.
	Non-silent intervals are shown. The output format is useful for
	documentation, but  not  for  feeding back into --cut.

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

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

   --swapchannels
        Swap the left with the right channel.

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

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

   --   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 cut numbers. When using negative cut numbers, use
   --  to  terminate  option  processing  or  the  negative numbers  can  be 
   mistaken  as  options  (will  be  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  pro- gress  display 
   might  only  show  numbers  in some of these units.

   Negative cut numbers are shown as  the  equivalent  positive ones.  If  the 
   last cut number is 0, it is converted to the highest possible one, i.e. end
   of file.

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

   If wav2cdr was compiled to use GNU getopt(), argument  scan- ning  is  more 
   powerful and long options can be shortcut to significance. Options are also
   re-ordered; this is nice  but can be a trap.

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 for- mats with these parameters can be processed. The only
   flexi- bility  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 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.

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 sector number are
   discarded, as well as  all  sec- tors 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.

    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 `` syn- tax  works  under Unix and in this case
   puts the contents of file "cuts" on the command line.

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

   (stdin):
                  0 b,      0 C,    0 s, 00:00.00 s
      -->    364560 b,    155 C,    2 s, 00:02.06 s
     DIFF    364560 b,    155 C,    2 s, 00:02.06 s

           57847440 b,  24595 C,  327 s, 05:27.93 s
      -->  58675344 b,  24947 C,  332 s, 05:32.62 s
     DIFF    827904 b,    352 C,    4 s, 00:04.69 s

   showing the beginning and end of  each  silent  interval  as well  as  its 
   length. This is useful for examining existing tracks, but it can not be used
   with --cuts.

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.

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
   None known. (Yet.)

COPYRIGHT
   Copyright (C) Nov, Dec 1997, Jan, Mar, Apr, May 1998 by
   Volker Kuhlmann  <v.kuhlmann@elec.canterbury.ac.nz>

   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             Last change: 03 May 1998
