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