1 // ng-jackspa.1.txt - manual page documenting the programs in ng-jackspa
2 // Copyright © 2013 Géraud Meyer <graud@gmx.com>
4 // This file is part of ng-jackspa.
6 // ng-jackspa is free software; you can redistribute it and/or modify it under
7 // the terms of the GNU General Public License version 2 as published by the
8 // Free Software Foundation.
10 // This program is distributed in the hope that it will be useful, but WITHOUT
11 // ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 // FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
15 // You should have received a copy of the GNU General Public License along
16 // with ng-jackspa. If not, see <http://www.gnu.org/licenses/>.
25 ng-jackspa - simple LADSPA hosts for the Jack Audio Connection Kit
31 'jackspa_interface' *--help-all*
32 'jackspa_interface' ['options'] [*--*] 'plugin_library' 'UID_or_label'
37 ng-jackspa is a set of simple user interfaces that host a LADSPA plugin,
38 providing JACK ports for its audio inputs and outputs, and dynamic setting of
39 its control inputs through the user interface.
41 The plugin is to be found in the library 'plugin_library'; if it is not an
42 absolute filename, the `$LADSPA_PATH` is searched. The argument 'UID_or_label'
43 identifies the plugin inside the library by its Unique ID or by its label name;
44 it is converted to a number by the function strtol(3); if the whole argument is
45 not recognized as a number, it is considered to be a plugin label.
49 Several interface programs are available that share the same jackspa engine.
50 They have the same features and common command line switches.
52 * The user interfaces allow to reset the controls to their defaults and to
53 switch instantaneously between two sets of control values.
55 * The initial control values, the default values and the bounds can be set on
56 the command line. Otherwise they are taken from the plugin descriptor.
58 * The control ports of the LADSPA plugin can be exported to or controlled by
59 control voltages on standard JACK audio ports; they can be connected to other
60 jackspa control voltages by employing the same methods or tools as for
61 standard JACK audio ports. Only the first sample of a frame belonging to the
62 control outputs is non zero and it is set to the control value; to match this
63 behaviour, only the first sample of a frame coming to the control inputs are
64 read as the control value. The control outputs can be connected to a
65 standard peak meter to visualize their values.
73 An ncurses visual (full screen) interface for the terminal. There is a short
74 help text available on the bottom of the screen; it has additional vi-like
75 keybindings; use 'H'/'L' to change the control values a little.
77 A specification like the one passed on the command line to set some inital
78 values can be given directly in a text entry field ('^O' or 'i'), in which
79 editing keys similar to the ones used in terminal line editing mode (a.k.a.
80 cooked mode) are available, in addition to editing/moving keys à la Emacs:
82 * '\^U', '^K' to kill;
83 * '^H'/backspace to erase back;
84 * '^D'/delete to delete;
85 * '\^A', '\^B', '\^F', '^E' to move;
86 * '^P' to recall the previous entry;
87 * '^O'/escape to cancel;
88 * '\^M'/'^J'/enter to validate.
92 Respectively GTK+ and Qt 4 graphical interfaces for X11. Keyboard shortcuts
93 are available that set to the defaults or exchange values. To exit, tell the
98 A command line program for the terminal with job control awareness.
100 * It can be ended by typing '\^D' (EOF on its input) if stdin is a tty or by
101 sending the signal SIGINT ('^C' when the process is in the foreground).
102 * It has the ability of being put in the background.
103 * By sending SIGTSTP ('^Z'), the process is stopped, as is common, but it
104 is restarted at once to continue to run in the background; this may generate
106 * By sending SIGUSR1, the values of the active controls are printed on the
109 The only way to change to change the control parameters at runtime is by
110 control voltages on the control inputs exported to JACK input audio ports.
115 Most options are available to all the interfaces. Not all the options are
116 listed here; to see all the options available to a given ng-jackspa interface,
120 Print all the command line options available and exit.
122 *--inits*, *-i* 'value_list'::
123 *--defaults*, *-d* 'value_list'::
124 *--bounds*, *-b* 'value_list'::
125 The argument is a colon separated list of value specifications. A
126 specification can be:
128 * empty: skip (keep the default behaviour)
129 * `<`, `>`: the minimum and the maximum respectively; if the plugin does
130 not give bounds, default (somewhat sensible) bounds are computed;
131 * `%23`: a percentage indicating a position in the range between the
133 * `d`: the plugin default, if available;
134 * `1.2e-2`: otherwise a string converted to a number by strtof(3).
137 ENVIRONMENT VARIABLES
138 ---------------------
140 Search paths for the LASDPA plugin libraries.
142 JACK_DEFAULT_SERVER::
143 The name of the JACK server to which to connect; if it is not given, the
144 default server name is `default`.
146 JACK_NO_START_SERVER::
147 If set, do not start a JACK server if none is already running.
152 A non zero exit status indicates an error; messages are printed on stderr in
162 Simple command invocations
163 ~~~~~~~~~~~~~~~~~~~~~~~~~~
167 gjackspa -b 2 amp.so amp_mono
168 jackspa-cli -i '>:0.5' /usr/lib/ladspa/delay.so 1043
170 Connecting several jackspa instances together
171 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
172 Separate high and low frequencies by using two plugins and controlling the
173 common cutoff frequency:
176 jackspa-cli -I cmt lpf &
178 jack_connect jackspa_hpf:"Cutoff Frequency (Hz)" jackspa_lpf:"Cutoff Frequency (Hz)"
179 jack_connect system:capture_1 jackspa_lpf:"Input"
180 jack_connect system:capture_1 jackspa_hpf:"Input"
186 See the ng-jackspa distribution file 'BUGS' to learn how to report bugs or
187 request a feature. This is a list of known important bugs and limitations.
189 * If the sample rate of the JACK server changes, the LADSPA plugin is not
190 restarted and it continues to run with the initial sample rate; depending
191 on the plugin, it may or not be wrong.
193 * If the JACK server shuts down, the interface programs just continue to run,
194 without notifying of the failure and without ever trying to reconnect to a
195 newly started server.
197 * The graphical interfaces do not update their displayed control values when
198 these are changed by control voltages appearing on the JACK input audio ports
199 associated with their respective controls.
201 * If the LADSPA plugin has a port name whose length makes the related JACK port
202 name unacceptably long, no attempt to truncate the name is made and the
203 initialisation fails.
208 ng-jackspa was written by G.raud Meyer.
213 listplugins(1), analyseplugin(1), strtol(3), strtof(3), jackd(1), jack-rack(1),
216 The file 'ladspa.h' that is part of the LADSPA SDK.