README
1Release notes for jconvolver and fconvolver 1.0
2-----------------------------------------------
3
4Jconvolver is Jack client performing real-time
5convolution. It supports up to a 64 by 64 matrix
6(i.e. 4096 simultaneous convolutions) as long as
7your CPU(s) can handle the load.
8
9Jconvolver is designed to be efficient also for
10sparse (e.g. diagonal) matrices, and for sparse
11impulse responses. Unused matrix elements and
12unused partitions do not take any CPU time.
13
14In contrast to e.g. BruteFir, jconvolver uses
15multiple partition sizes, small ones at the start
16of the impulse response and progressively longer
17ones for the rest. This allows it provide both
18zero processing delay while still remaining
19efficient in CPU use. The exact sequence of
20partition sizes used depends in a complex way
21on some elements of the configuration.
22
23Fconvolver performs the same processing on files
24instead of real-time. The same configuration file
25as for jconvolver can be used, any elements that
26are not required will be ignored.
27
28--
29FA
30
README.CONFIG
1Configuration file format for jconvolver and fconvolver
2-------------------------------------------------------
3
4See the files in the directory 'config-files' for some
5examples. Lines starting with '#' are comments.
6
7The file processor fconvolver accepts the same config
8files as the real-time processer jconvolver. Any commands
9relating to Jack ports are ignored, and input and output
10numbers refer to channels in the input and output files.
11
12The configuration language is 'imperative', i.e. it consists
13of commands that are executed in the order given, and that
14together build up the required configuration.
15
16
17The following commands are available:
18
19/jack/client <name>
20
21 Set the jack client name. The command line option -N overrides this.
22 This command must come before the '/convolver/new' one.
23
24
25/jack/server <name>
26
27 Set the jack server name. The command line option -s overrides this.
28 This command must come before the '/convolver/new' one.
29
30
31/convolver/new <inputs> <outputs> <partition size> <maximum impulse length> <density>
32
33 This command is always required and except for the two commands above
34 must be first one. The 'partition size' is the minumum partition size
35 that will be used, and should be 1, 2, 4, 8 or 16 times the Jack period
36 size. It will be adjusted (with a warning) otherwise. Processing delay
37 will be zero if this is set to the Jack period size. The Jack period
38 size must be a power of 2.
39
40 The 'maximum impulse length' has little or no effect on CPU usage, but
41 determines the amount of memory used, and will affect the sequence of
42 partition sizes that will be used, so it should not be much larger than
43 the longest convolution you want to use. Unused inputs or outputs do not
44 take significant CPU or memory.
45
46 The optional 'density' parameter should be between 0 and 1. It should
47 be representative of the fraction of possible input/output pairs that
48 will actually have a convolution defined between them. It is used as a
49 hint to optimize the sequence of partition sizes for short and medium
50 length convolutions.
51
52
53/input/name <input number> <port name> {<source port>}
54/output/name <output number> <port name> {<destination port>}
55
56 These can be used to provide more informative ports names,
57 and to optionally connect the inputs or outputs. Input and
58 output numbers start at 1.
59
60
61/cd <path>
62
63 Change the directory where impulse response files are searched for to 'path'.
64 Permits the use of short names in the next command. Initial value is the
65 current directory.
66
67
68/impulse/read <input> <output> <gain> <delay> <offset> <length> <channel> <file>
69
70 Read impulse from a sound file. 'Input', 'output' and 'channel'
71 start from 1. Impulse files are read by libsndfile.
72 'Gain' is the linear gain (i.e. not in dB) applied to the response.
73 'Delay' sets the number of zero samples inserted before any data read.
74 'Offset' can be used to skip frames at the start of the file.
75 'Length' is the number of frames used, or zero for all.
76
77
78/impulse/dirac <input> <output> <gain> <delay>
79
80 Create an impulse response consisting of a single sample of amplitude
81 'gain' at position 'delay'. This is mainly used together with the
82 /impulse/hilbert command to create complex matrices. Do not use this
83 to measure CPU usage as only a single partition will be computed.
84
85
86/impulse/hilbert <input> <output> <gain> <delay> <length>
87
88 Create an hilbert transform impulse response of the given lenght and
89 having a delay equal to 'delay', which must be at least half the lenght
90 (plus any latency compensation). The 90 degrees phase relation compared
91 to a Dirac impulse with the same delay will be exact at all frequencies.
92 The magnitude response will roll off at low frequencies, with a -3 dB
93 point at approximately the sample frequency divided by the length.
94
95
96The commands /impulse/read, /impulse/dirac and /impulse/hilbert
97can be used any number of times on the same input/output pair.
98The individual impulse responses will be added.
99
100
101/impulse/copy <input> <output> <from input> <from output>
102
103 Copy a convolution to another input/output pair. This can save a lot
104 of memory if the same long convolution has to be performed on many
105 in/out pairs. This is a 'symbolic link' - frequency domain impulse
106 data will be shared for such copies. This includes any additions made
107 to the original after the copy has been made.
108
109