autools

autools-1.2.4
=============

Contents
========

Contents
ABOUT autools
Install
The AFsp Audio File I/O Package
Usage
plax -- play and record audio on Linux/Solaris/IRIX/Win32
auquery -- query audio device capabilities
playlist -- play list of audio files (and query listeners gradings)
randhead -- add random number as first column
catcol -- concatenate two files as columns
augen -- generate tones/noise according to "*.gen" script
genfm -- generate sine with triangular freq. mod.
genam -- generate sine with triangular ampl. mod.
auquant -- very simple quantiser & noise-shaper
ac3spdif -- encapsulates AC3 in S/P-DIF according to IEC 61937
auduplex -- au record & play (duplex, for Linux)
fifo -- fifo for use with mkfifo and auduplex
other tools and files


ABOUT autools
=============

(c) Heiko Purnhagen 1993-2003
e-mail: purnhage@tnt.uni-hannover.de
WWW:    http://www.tnt.uni-hannover.de/~purnhage/
Version autools-1.2.4 ($Id: gen-html,v 1.13 2003/01/19 23:24:09 purnhage Exp $)

autools homepage: http://www.tnt.uni-hannover.de/~purnhage/software/autools/

All usual disclaimers apply!

The programs in this package are available under the terms of the GNU
General Public Licence. See file COPYING for
further details.

The modules in this package are available under the terms of the GNU
Lesser General Public License. See file <a
href="COPYING-LGPL">COPYING-LGPL for further details.

Acknowledgements:
  MPEG-4 Audio VM authors
    for comments on common.c, cmdline.c, and audio.c
  Bernd Edler <edler@tnt.uni-hannover.de>
    for the initial playlist software (also as base for for playrec.c)
  Nikolaus Meine <meine@tnt.uni-hannover.de>
    for code used in austream.c and the highly optimised rateconv.c
  Lampos Ferekidis <l.ferekidis@NXTSound.com>
    for porting autools to MSVC and Cygwin
  Peter Kabal <kabal@TSP.ECE.McGill.CA>
    for the AFsp package (including libtsp)
  David Viens <davidv@plogue.com>
    for providing a modified version of the rateconv module for use as DLL

Authors:
HP    Heiko Purnhagen, Uni Hannover <purnhage@tnt.uni-hannover.de>
NM    Nikolaus Meine, Uni Hannover <meine@tnt.uni-hannover.de>

Changes:
20-dec-98   HP    README born
30-dec-98   HP    CVS, refined many files ...
17-jan-99   HP    updated to autools-0.3
26-jan-99   HP    updated to autools-0.4
28-jan-99   HP    updated to autools-0.4.2
29-jan-99   HP    updated to autools-0.5
18-feb-99   HP    updated to autools-0.5.1
06-aug-99   HP    updated to autools-0.6
04-nov-99   HP    updated to autools-0.7
11-nov-99   HP    updated to autools-0.7.1
19-nov-99   HP    updated to autools-0.7.2
28-dec-99   HP    autools-0.8, fixed bug in plax recording
16-feb-00   HP    updated to autools-0.8.1, several extensions of plax
17-mar-00   HP    updated to autools-0.8.2, several extensions of plax
06-jun-00   HP    updated to autools-0.9.0, added auduplex, fifo
07-jun-00   HP    updated to autools-0.9.1, fixed plax hangup / playrec.c
06-sep-00   HP    updated to autools-0.9.2
26-Nov-2001 HP    not yet fully updated to autools-1.1.2 ...
06-Feb-2002 HP    updated to autools-1.1.5, automatic HTML documentation ...
08-Mar-2002 HP    added wav2toc 
11-Apr-2002 HP    added ac3spdif
2003-01-19  HP    added GPL/LGPL (c) headers, added rateconv-dll


Install
=======

Compile:
  make

Install:
  make install
or
  make install INSTALL_DIR=/usr/local/bin

Most of this software utilises AFsp's libtsp for audio file i/o. Thus
libtsp needs to be available in the default include & library paths or
in the directories given by the environment variables AFSP_INCLUDE_PATH
and AFSP_LIBRARY_PATH. Further details about AFsp are given below.

This software can also be compiled without AFsp's libtsp library - in
this case, only 16-bit SUN "*.au"-files are supported:
  make clean
  make USE_AFSP=0

The makefile assumes gcc/g++ and GNU make. It was successfully tested
on Linux, Solaris, and IRIX. However it might be necessary to adapt it
to your local environment ...


The AFsp Audio File I/O Package
-------------------------------

To provide support for a variety of audio file formats, this
software can use the AFsp package for audio file i/o. The AFsp
package is written by Peter Kabal <kabal@TSP.ECE.McGill.CA> and is
available by ftp:

WWW site:               http://www.tsp.ece.mcgill.ca/Docs/Software/AFsp/AFsp.html
ftp site:               ftp://ftp.TSP.ECE.McGill.CA/TSP/AFsp/
mirror site:            ftp://ftp.tnt.uni-hannover.de/pub/audio/AFsp

This software has been tested with the AFsp versions AFsp-V3R2.tar.Z,
AFsp-v4r1.tar.gz, AFsp-v4r2.tar.gz, AFsp-v4r3.tar.gz, AFsp-v5r2.tar.gz,
AFsp-v6r4.tar.gz and AFsp-v6r5a.tar.gz.

To make the libtsp library required by this software, unpack
AFsp-v4r3.tar.gz, goto AFsp-v4r3/libtsp, and start make. Then you can
install the content of ../include and ../lib on your system (e.g. in
/usr/local/include and /usr/local/lib) or set the environment
variables AFSP_INCLUDE_PATH and AFSP_LIBRARY_PATH to point to the proper
AFsp directories.


Usage
=====

plax -- play and record audio on Linux/Solaris/IRIX/Win32
---------------------------------------------------------

plax: plax V1.2.4 09-Dec-2003   autools-1.2.4
$Id: plax.c,v 1.52 2003/12/09 04:06:17 purnhage Exp $
all AFsp file formats supported

usage: plax -switches <input files (- = stdin) (dflt: audio device)>
switches: -h        print help
          -o <x>    output file name (- = stdout) (dflt: audio device)
          -of <x>   output file format (au/wav/aiff/raw/be/le)
                    (16 bit, raw/be: big-endian raw, le: little-endian raw)
                    (dflt: as file extension or au for stdout)
          -if <x>   input file format
                    (AFsp: auto/raw/be/le ..., see also -ia -f xxx)
                    (16 bit au/raw: auto/au/raw/be/le, see also -is)
                    (dflt: auto)
          -is <x>   header bytes to skip if raw input (not AFsp) (dflt: 0)
          -ia       stdin using AFsp (dflt: 16 bit au/raw)
          -oa       stdout using AFsp, needs -of xxx
                    (dflt: 16 bit au/raw)
          -f <x>    raw input file format (AFsp)
                    (dflt: $RAWAUDIOFILE / "integer16,0,48000.,native,1,1.0")
          -c <x>    output: number of channels (dflt: as input or 1)
          -s <x>    output: sampling frequency [Hz] (dflt: as input or 8000.0)
          -rc <x>   rec: number of channels
                    (SGI: 0 = use audio panel settings) (dflt: as output)
          -rs <x>   rec: sampling frequency [Hz]
                    (SGI: 0 = use audio panel settings) (dflt: as output)
          -pd <x>   play: audio device name (dflt: default device)
          -rd <x>   rec: audio device name (dflt: default device)
          -df <x>   max. tolerated relative sampling frequency deviation
                    (dflt: 0.01)
          -a        enable automatic conversion to audio device capabilities
          -ad       enable automatic upsampling to 32/44.1/48 kHz if required
                    (for digital audio device)
          -al <x>   lower limit for output sampling frequency [Hz] (dflt: none)
          -au <x>   upper limit for output sampling frequency [Hz] (dflt: none)
          -x        enable channel & sample rate conversion
          -xf       resampling for sub-sample start time accuracy
          -g <x>    amplitude gain (dflt: 1.0)
          -g0 <x>   add. ampl. gain for chan. 0 (left) (dflt: 1.0)
          -hp <x>   output high-pass filter frequency [Hz] (0=off) (dflt: 0.0)
          -ho <x>   output high-pass filter order (dflt: 1)
          -ts <x>   start time in input [sec]
                    (use -xf for sub-sample accuracy) (dflt: 0.0)
          -td <x>   max. duration of output [sec] (without added silence)
                    (0=unlimited) (dflt: 0.0)
          -tf <x>   force output duration [sec] (without added silence)
                    (dflt: see -td)
          -ss       strip leading and trailing silence
          -sq <x>   trailing silence to quit [sec] (0=off) (dflt: 0.0)
          -sm <x>   leading silence magnitude threshold [LSB]
                    (trailing silence magnitude threshold = 0) (dflt: 0)
          -sl <x>   add leading silence [sec] (dflt: 0.0)
          -st <x>   add trailing silence [sec] (dflt: 0.0)
          -fi <x>   signal fade-in [sec] (dflt: 0.0)
          -fo <x>   signal fade-out [sec] (dflt: 0.0)
          -n        no audio output (just show audio file format)
          -wd       wplax: print time of played frames on stdout
          -wl       wplax: list audio file format on stdout (no audio output)
          -b <x>    buffer size [sec] (if no sample rate conv.) (dflt: 0.2)
          -bf <x>   fragment size [sec] (recommended if only 2 fragments)
          -bp <x>   play buffer size [sec] (limit playback latency)
                    (0 disables buffer control to prevent hangup) (dflt: 0.2)
          -ht <x>   sample rate conv.: num taps
                    (-1 = auto) (dflt: -1)
          -al <x>   sample rate conv.: alpha for Kaiser window
                    (-1 = auto) (dflt: -1.0)
          -fc <x>   sample rate conv.: 6 dB cutoff freq / input bandwidth
                    (-1 = auto) (dflt: -1.0)
          -fd <x>   sample rate conv.: 100 dB cutoff freq / input bandwidth
                    (-1 = auto) (dflt: -1.0)
          -d <x>    debug level (on stderr) (0=off 1=basic 2=med 3=high)
                    (+4*austreamDbgLvl +16*playrecDbgLvl +64*rateconvDbgLvl)
                    (dflt: 0)


auquery -- query audio device capabilities
------------------------------------------

auquery: auquery V1.2 07-Jan-2003   autools-1.2.4
$Id: auquery.c,v 1.6 2003/01/19 23:17:09 purnhage Exp $
only 16 bit format supported

usage: auquery -switches <audio devices (dflt: default device)>
switches: -h        print help
          -c <x>    specific number of channels (dflt: range cl .. cu)
          -cl <x>   lower limit for number of channels
                    (0 = try default / audio panel settings) (dflt: 0)
          -cu <x>   upper limit for number of channels (dflt: 2)
          -s <x>    specific sampling frequency [Hz] (dflt: range sl .. su)
          -sl <x>   lower limit for sampling frequency [Hz] (dflt: 4000)
          -su <x>   upper limit for sampling frequency [Hz] (dflt: 200000)
          -m <x>    query mode (0=rec&play 1=rec 2=play) (duplex not supported)
                    (dflt: 0)
          -d <x>    debug level (on stderr) (0=off 1=basic .. 5=full)
                    (dflt: 0)


playlist -- play list of audio files (and query listeners gradings)
-------------------------------------------------------------------

playlist: playlist V0.7.2 19-Nov-1999   autools-1.2.4
$Id: playlist.c,v 1.25 2003/01/19 23:17:09 purnhage Exp $

usage: playlist -switches <playlist entries>
switches: -h        print help
          -o <x>    output file name (- = stdout) (dflt: audio device)
          -c <x>    output: number of channels (dflt: as 1st input file)
          -s <x>    output: sampling frequency [Hz] (dflt: as 1st input file)
          -pd <x>   play: audio device name (dflt: default device)
          -df <x>   max. tolerated relative sampling frequency deviation
                    (dflt: 0.01)
          -g <x>    amplitude gain (dflt: 1.0)
          -l <x>    playlist file name
          -n        no audio output
          -t        interactive listening test
                    (grading file: playlist file name + YYYYMMDDHHMMSS)
                    [ "enter grading(s)" prompt: 'r' to repeat          ]
                    [                            'x' to seek to trial # ]
                    [                            'quit' to quit         ]
                    [ '^C' to abort playback and goto next audio file   ]
          -p <x>    audio file path (dflt: $PLAYLISTPATH)
          -e <x>    audio file extension (dflt: .au)
          -el <x>   playlist file extension (dflt: .lis)
          -et <x>   test file extension (dflt: .tst)
          -f <x>    audio file format for raw files
                    (dflt: $RAWAUDIOFILE / "integer16,0,48000.,native,1,1.0")
          -b <x>    buffer time [sec] (if no sample rate conv.) (dflt: 0.2)
          -bp <x>   play buffer size [sec] (0=max.) (dflt: 0.2)
          -ht <x>   sample rate conv.: num taps
                    (-1 = auto) (dflt: -1)
          -al <x>   sample rate conv.: alpha for Kaiser window
                    (-1 = auto) (dflt: -1.0)
          -fc <x>   sample rate conv.: 6 dB cutoff freq / input bandwidth
                    (-1 = auto) (dflt: -1.0)
          -fd <x>   sample rate conv.: 100 dB cutoff freq / input bandwidth
                    (-1 = auto) (dflt: -1.0)
          -d <x>    debug level (on stderr) (0=off 1=basic 2=info file 3=full)
                    (+4*audioDbgLvl +16*playrecDbgLvl +64*rateconvDbgLvl)
                    (dflt: 0)

playlist entry format:
  comment:           ;comment
  raw file format:   @integer16,0,48000.,native,1,1.0
  trial n:           !n
  keys:              *key1 key2 key3 
  audio file:        path/file.au
  ask grading(s):    ?question
  n second pause:    #n


randhead -- add random number as first column
---------------------------------------------

randhead: randhead V0.4 11-jan-99   autools-1.2.4
$Id: randhead.c,v 1.6 2003/01/19 23:17:09 purnhage Exp $

Usage: randhead mode [infile]
 mode '+' : add random numbers as 1st column (random seed)
 mode 'nn': add random numbers as 1st column (seed nn)
 mode '-' : remove 1st column
Example: randhead + ordered.list | sort | randhead - > randomised.list


catcol -- concatenate two files as columns
------------------------------------------

usage: catcol input1 input2 > output


augen -- generate tones/noise according to "*.gen" script
---------------------------------------------------------

augen: augen V2.0 17-Apr-2002   autools-1.2.4
$Id: augen.c,v 1.14 2003/01/19 23:17:09 purnhage Exp $

usage: augen -switches <generator parameter set>
switches: -h        print help
          -s <x>    sampling frequency [Hz] (dflt: 8000)
          -c <x>    number of channels (dflt: 1)
          -a <x>    amplitude factor (dflt: 32767)
          -ts <x>   signal start time [sec] (dflt: 0)
          -td <x>   signal duration [sec]
                    (dflt: complete signal)
          -g <x>    generator parameter file name or - for stdin
          -o <x>    audio file name or - for stdout
                    (dflt: as generator parameter file)
          -eg <x>   generator parameter file extension (dflt: .gen)
          -ea <x>   audio file extension
                    supported file formats: .au, .snd, .wav, .aif, .raw
                    (dflt: .au)
          -b <x>    buffer time (dflt: 0.2)
          -d <x>    debug level (dflt: 0)
          -da <x>   audio file debug level (dflt: 0)


generator parameter set format:

  <wave> <ts> <td> <fs> <fe> <p> <a1s> <a1e> [<a2s> <a2e> ...]
    wave: s=sine u=saw-up t=triangle q=square p=pulse
    ts: start time [sec]
    td: duration [sec]
    fs: start frequency [Hz]
    fe: end frequency [Hz]
    p: start phase [deg]
    a1s: channel 1 start amplitude [FS]
    a1e: channel 1 end amplitude [FS]
    a2s: channel 2 start amplitude [FS]
    a2e: ...
  if wave = S, U, T, Q, P then frequencies in MIDI notes:
     24 = C1 =   32.70 Hz
     60 = c1 =  261.63 Hz
     69 = a1 =  440.00 Hz
    108 = c5 = 4186.01 Hz

  n <ts> <td> <a1s> <a1e> [<a2s> <a2e> ...]
    noise (full BW, uniform distribution [-a,a])

additional control parameters:
  f <sampling frequency [Hz]>
  c <number of channels>
  a <amplitude factor>
  % comment

test augen with "*.gen" script file:
  <platform>/augen -d 1 -g sweep.gen
  <platform>/augen -d 1 -g noise-side-mid.gen
  <platform>/augen -d 1 -g scale-c1-c2.gen


genfm -- generate sine with triangular freq. mod.
-------------------------------------------------

usage: echo fc fd fm t0 td | genfm | augen -s 32000 -g - | plax -

parameter units: fc [Hz], fd [Hz], fm [Hz], t0 [s], td [s]

signal:                x(t0+t) = 0.5*sin(2*pi*int(0,t,f(tau),dtau))
duration:              t = [0,td]
instantaneous freq.:   f(t) = fc+fd/2*tri(fm*t)
triangular modulation: tri(x) = 1-2*abs(frac(x)-.5)


genam -- generate sine with triangular ampl. mod.
-------------------------------------------------

usage: echo f ad fm t0 td | genam | augen -s 32000 -g - | plax -

parameter units: f [Hz], ad [1], fm [Hz], t0 [s], td [s]

signal:                x(t0+t) = 0.5*a(t)*sin(2*pi*f*t)
duration:              t = [0,td]
instantaneous ampl.:   a(t) = 1+ad/2*tri(fm*t)
triangular modulation: tri(x) = 1-2*abs(frac(x)-.5)


auquant -- very simple quantiser & noise-shaper
-----------------------------------------------

auquant: auquant V1.2.1 19-Dec-2001   autools-1.2.4
$Id: auquant.c,v 1.17 2003/01/19 23:17:09 purnhage Exp $

usage: auquant -switches <input files (- = stdin) (dflt: -)>
switches: -h        print help
          -o <x>    output file name (- = stdout) (dflt: as input)
          -ts <x>   start time [sec] (dflt: 0)
          -td <x>   duration [sec]
                    (0 = complete signal) (dflt: 0)
          -g <x>    pre-quantisation amplitude gain (dflt: 1.0)
          -q <x>    num quantiser steps (dflt: 65536)
          -s <x>    post-quantisation amplitude scaling
                    (dflt: (int)(65536/num_quantiser_steps) )
          -di <x>   dithering (tpdf) (0=off(0dB) 1=on(+4.77dB)) (dflt: 0)
          -ns <x>   noiseshaper feedback factor
                    (0.0 = off(0dB)  0.9 = -5.6dB..20dB  1.0 = -6.0dB..+inf)
                    (dflt: 0)
          -p <x>    audio file path (dflt: $AUQUANTPATH)
          -ei <x>   input audio file extension (dflt: .au)
          -eo <x>   output audio file extension (dflt: _q.au)
          -f <x>    raw input file format
                    (dflt: $RAWAUDIOFILE / "integer16,0,48000.,native,1,1.0")
          -b <x>    buffer time (dflt: 0.2)
          -d <x>    debug level (0=off 1=basic 2=full) (dflt: 0)
          -da <x>   audio file debug level (dflt: 0)


ac3spdif -- encapsulates AC3 in S/P-DIF according to IEC 61937
--------------------------------------------------------------

ac3spdif: ac3spdif V1.0 11-Apr-2002   autools-1.2.4
$Id: ac3spdif.c,v 1.9 2003/01/19 23:17:09 purnhage Exp $

usage: ac3spdif -switches <input file (- = stdin)> <output file (- = stdout)>
switches: -h        print help
          -r        reverse operation (spdif -> ac3)
          -f <x>    raw input file format
                    (dflt: $RAWAUDIOFILE / integer16,0,48000.,big-endian,2,1.0)
          -d <x>    debug level (0=off 1=basic .. 4=full) (dflt: 0)
          -da <x>   audio file debug level (dflt: 0)


This tools implements the encapsulation of AC3 bit streams
for transmission over IEC 60958 (S/P-DIF digital audio interface)
according to IEC 61937. The audio file format is auto-detected
from header or extension (stdin/stdout support .au only).
Example: ac3spdif demo.ac3 - | plax -


auduplex -- au record & play (duplex, for Linux)
------------------------------------------------

auduplex: auduplex V1.1.8 07-Jan-2003   autools-1.2.4
$Id: auduplex.c,v 1.24 2003/02/27 23:54:59 purnhage Exp $

usage: auduplex -switches <play input .au file (- = stdin)>
switches: -h        print help
          -o <x>    record output .au file (- = stdout) (dflt: -)
          -c <x>    number of channels (dflt: 1)
          -s <x>    sampling frequency [Hz] (dflt: 8000.0)
          -ad <x>   audio device name (dflt: /dev/dsp)
          -gr <x>   rec. amplitude gain (dflt: 1.0)
          -gp <x>   play amplitude gain (dflt: 1.0)
          -ts <x>   start time [sec] (+: dly play / -: dly rec.) (dflt: 0.0)
          -td <x>   max. duration [sec] (0=unlimited or as input) (dflt: 0.0)
          -b <x>    transfer block size [sec] (dflt: 0.1)
          -bf <x>   fragment size [sec] (recommended if only 2 fragments)
          -bn <x>   nap time [sec] (dflt: 0.3*block size)
          -bl <x>   buffering latency [sec] (play) (dflt: 0.2)
          -br <x>   record fifo size [sec] (dflt: 0.5)
          -bp <x>   play fifo size [sec] (dflt: 0.5)
          -d <x>    debug level (on stderr) (0=off 1=basic 2=med 3=high)
                    (+4*austreamDbgLvl) (dflt: 0)

example a)
  mkfifo fifo.au
  cat fifo.au | linux/fifo | linux/auduplex -d 1 -ts 1 - -o fifo.au

example b)
  linux/augen -c 2 -s 48000 -o noise.au "n 0 1 0.1 0.1 0 0" "n 1 1 0 0 0.1 0.1"
  linux/auduplex -c 2 -s 48000 -d 2 noise.au -o response.au


fifo -- fifo for use with mkfifo and auduplex
---------------------------------------------

fifo V0.5 20-Mar-2002   autools-1.2.4
$Id: fifo.c,v 1.16 2003/01/19 23:17:09 purnhage Exp $
usage: fifo [options] <in >out
options: fxxx   fifo size xxx bytes (dflt: 1048576)
         bxxx   block size xxx bytes (dflt: 65536)
         wxxx   write delay (start after xxx bytes) (dflt: 0)
         nxxx   nap time [ms] (0 = wait for event) (dflt: 0)
         dxxx   debug level xxx (dflt: 0)
         rxxx   debug update rate xxx (dflt: 1)


other tools and files
---------------------

auinfo
toc2plax-trk
toc2plax-idx
toc2plax-cut
wav2toc
dao2toc
toc2toc
cd-cover.fig
MSVC
rateconv-dll

Heiko Purnhagen
10-Dec-2003

