Configuration file format for jconvolver and fconvolver
-------------------------------------------------------

See the files in the directory 'config-files' for some
examples. Lines starting with '#' are comments.

The file processor fconvolver accepts the same config
files as the real-time processer jconvolver. Any commands
relating to Jack ports are ignored, and input and output
numbers refer to channels in the input and output files.

The configuration language is 'imperative', i.e. it consists
of commands that are executed in the order given, and that
together build up the required configuration.


The following commands are available:

/jack/client  <name>

    Set the jack client name. The command line option -N overrides this.
    This command must come before the '/convolver/new' one.


/jack/server  <name>

    Set the jack server name. The command line option -s overrides this.
    This command must come before the '/convolver/new' one.


/convolver/new  <inputs> <outputs> <partition size> <maximum impulse length> <density>

    This command is always required and except for the two commands above
    must be first one. The 'partition size' is the minumum partition size
    that will be used, and should be 1, 2, 4, 8 or 16 times the Jack period
    size. It will be adjusted (with a warning) otherwise. Processing delay
    will be zero if this is set to the Jack period size. The Jack period
    size must be a power of 2.

    The 'maximum impulse length' has little or no effect on CPU usage, but
    determines the amount of memory used, and will affect the sequence of
    partition sizes that will be used, so it should not be much larger than
    the longest convolution you want to use. Unused inputs or outputs do not
    take significant CPU or memory. 

    The optional 'density' parameter should be between 0 and 1. It should
    be representative of the fraction of possible input/output pairs that
    will actually have a convolution defined between them. It is used as a
    hint to optimize the sequence of partition sizes for short and medium
    length convolutions.


/input/name <input number> <port name> {<source port>}
/output/name <output number> <port name> {<destination port>}

    These can be used to provide more informative ports names,
    and to optionally connect the inputs or outputs. Input and
    output numbers start at 1.


/cd <path>

    Change the directory where impulse response files are searched for to 'path'.
    Permits the use of short names in the next command. Initial value is the
    current directory.


/impulse/read   <input> <output> <gain> <delay> <offset> <length> <channel> <file>

    Read impulse from a sound file. 'Input', 'output' and 'channel'
    start from 1. Impulse files are read by libsndfile.
    'Gain' is the linear gain (i.e. not in dB) applied to the response.
    'Delay' sets the number of zero samples inserted before any data read.
    'Offset' can be used to skip frames at the start of the file.
    'Length' is the number of frames used, or zero for all.


/impulse/dirac  <input> <output> <gain> <delay>

    Create an impulse response consisting of a single sample of amplitude
    'gain' at position 'delay'. This is mainly used together with the
    /impulse/hilbert command to create complex matrices. Do not use this
    to measure CPU usage as only a single partition will be computed.


/impulse/hilbert  <input> <output> <gain> <delay> <length>

    Create an hilbert transform impulse response of the given lenght and
    having a delay equal to 'delay', which must be at least half the lenght
    (plus any latency compensation). The 90 degrees phase relation compared
    to a Dirac impulse with the same delay will be exact at all frequencies.
    The magnitude response will roll off at low frequencies, with a -3 dB
    point at approximately the sample frequency divided by the length.


The commands /impulse/read, /impulse/dirac and /impulse/hilbert
can be used any number of times on the same input/output pair.
The individual impulse responses will be added. 


/impulse/copy  <input> <output> <from input> <from output>

    Copy a convolution to another input/output pair. This can save a lot
    of memory if the same long convolution has to be performed on many
    in/out pairs. This is a 'symbolic link' - frequency domain impulse
    data will be shared for such copies. This includes any additions made
    to the original after the copy has been made.

