[Back to overview]

volrace --help

volrace (version 0.9.dev of frankl's stereo utilities)
USAGE:

  volrace [options] 

  This command works as a filter for stereo audio streams
  in raw double or float format (in some programs denoted FLOAT64_LE 
  and FLOAT32_LE, respectively. It can change the volume
  and it implements a simple form of the RACE algorithm (see
  http://www.ambiophonics.org/Tutorials/RGRM-RACE_rev.html).

  Here 'filter' means that input comes from stdin and output is
  written to stdout. Use pipes and 'sox' to deal with other stream
  formats. Internal calculations are done with 64-bit floating point 
  numbers.

  The filter parameters can be given as options or be read from a file.
  In the latter case the file is reread if it was changed.

  RACE

  This is an IIR-filter, which adds the inverted and attenuated 
  signal of the left channel with a delay to the right channel and
  vice versa. (In a former version we also provided an optional
  simple low-pass and high-pass filter for the signal copied to the 
  other channel. But results where not convincing, therefore this is
  not supported by this version.)

  The origin of this algorithm is ambiophonics which is for speakers
  which are positioned closely together (opening angle < 20 degrees
  from the listening position). In this context typical suggested
  values for the attenuation would be around 3dB (factor 0.71) and
  a delay of about 60-120 microseconds (3-6 samples for sample rate
  44100, or 11-21 samples for sample rate 192000).

  The author uses RACE in a standard stereo setup (speakers in 70 
  degree angle) with a 57 sample delay for sample rate 192000 and 
  an attenuation of 12dB-40dB (depending on the recording). 

  On a notebook with builtin speakers a delay of 4 samples at sample
  rate 44100 and an attenuation of 3dB give an interesting effect.

  OPTIONS
  
  --volume=floatval, -v floatval
      the volume as floating point factor (e.g., '0.5' for an attenuation
      of 6dB). Here floatval can be negative in which case the audio stream
      will be inverted. Default is 0.01, and the absolute value of floatval
      must not be larger than max-volume, see below.

  --replay-gain=floatval, -r floatval
      the value of --volume is multiplied by this factor.
      The default is '1.0'. This can be useful if the volume is changed
      during runtime via a --param-file.

  --race-delay=val, -d val
      the delay for RACE as (integer) number of samples (per channel).
      Default is 12.

  --race-volume=floatval, -a floatval
      the volume of the RACE signal copied to the other channel.
      Default is 0.0 (that is, no RACE effect).

  --param-file=fname, -f fname
      the name of a file which can be given instead of the previous three
      options. That file must contain the values for --volume, 
      --race-delay and --race-volume, separated by whitespace.
      This file is reread by the program when it was changed, and the
      parameters are faded to the new values. This way this program can
      be used as volume (and RACE parameter) control during audio playback.
      The file may only contain the value of --volume, in this case RACE
      will be disabled.

  --buffer-length=intval, -b intval
      the length of the chunks read and written. Default is 8192
      frames which should usually be fine.

  --max-volume=floatval, -m floatval
      just for security, the program will refuse to set the absolute
      value of --volume larger than this. Default is 1.0.

  --fading-length=intval, -l intval
      number of frames used for fading to new parameters (when the
      file given in --param-file was changed). Default is 44100 which 
      usually should be fine.

  --float-input, -I
      by default the input of the program is assumed to consist of
      64-bit floating point samples. Use this switch if your input is
      in 32-bit floating point format.

  --float-output, -O
      by default the output of the program consists of 64-bit floating 
      point samples. Use this switch if you want 32-bit floating point 
      samples in the output.
      
   --help, -h
      show this help.

   --verbose, -p
      shows some information during startup and operation.

   --version, -V
      show the version of this program and exit.

   EXAMPLES

   For volume and RACE control during audio playback:
      volrace --param-file=/tmp/vrparams
   where /tmp/vrparams contains something like
      -0.3 57 0.22
   (invert, reduce volume by factor 0.3, use RACE with delay 57 frames 
    and volume 0.22 which is about -13dB).
   Or give these values directly (cannot be changed while running):
      volrace --volume=-0.3 --race-delay=57 --race-volume=0.22
   Apply RACE to a CD quality flac-file x.flac and store it as wav-file:
      sox x.flac -t raw -e float -b 64 - | \
        volrace --volume=-0.7 --race-delay=13 --race-volume=0.22 | \
        sox -t raw -r 44100 -c 2 -e float -b 64 - -t wav -e signed -b 16 \
            x_race.wav dither -f high-shibata