ng-jackspa.1.txt

   1 // ng-jackspa.1.txt - manual page documenting the programs in ng-jackspa
   2 // Copyright © 2013 Géraud Meyer <graud@gmx.com>
   3 //
   4 // This file is part of ng-jackspa.
   5 //
   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.
   9 //
  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
  13 // more details.
  14 //
  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/>.
  17
  18 NG-JACKSPA(1)
  19 =============
  20 :doctype: manpage
  21
  22
  23 NAME
  24 ----
  25 ng-jackspa - simple LADSPA hosts for the Jack Audio Connection Kit
  26
  27
  28 SYNOPSIS
  29 --------
  30 [verse]
  31 'jackspa_interface' *--help-all*
  32 'jackspa_interface' ['options'] [*--*] 'plugin_library' 'UID_or_label'
  33
  34
  35 DESCRIPTION
  36 -----------
  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.
  40
  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.
  46
  47 Common features
  48 ~~~~~~~~~~~~~~~
  49 Several interface programs are available that share the same jackspa engine.
  50 They have the same features and common command line switches.
  51
  52 * The user interfaces allow to reset the controls to their defaults and to
  53   switch instantaneously between two sets of control values.
  54
  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.
  57
  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.
  66
  67
  68 INTERFACE PROGRAMS
  69 ------------------
  70
  71 njackspa
  72 ~~~~~~~~
  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.
  76
  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:
  81
  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.
  89
  90 gjackspa, qjackspa
  91 ~~~~~~~~~~~~~~~~~~
  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
  94 window manager.
  95
  96 jackspa-cli
  97 ~~~~~~~~~~~
  98 A command line program for the terminal with job control awareness.
  99
 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
 105   some xrun's.
 106 * By sending SIGUSR1, the values of the active controls are printed on the
 107   standard output.
 108
 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.
 111
 112
 113 OPTIONS
 114 -------
 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,
 117 use `--help-all`.
 118
 119 *--help-all*::
 120         Print all the command line options available and exit.
 121
 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:
 127
 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
 132           bounds;
 133         * `d`: the plugin default, if available;
 134         * `1.2e-2`: otherwise a string converted to a number by strtof(3).
 135
 136
 137 ENVIRONMENT VARIABLES
 138 ---------------------
 139 LADSPA_PATH::
 140         Search paths for the LASDPA plugin libraries.
 141
 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`.
 145
 146 JACK_NO_START_SERVER::
 147         If set, do not start a JACK server if none is already running.
 148
 149
 150 EXIT STATUS
 151 -----------
 152 A non zero exit status indicates an error; messages are printed on stderr in
 153 this case.
 154
 155 *0*::
 156         No errors.
 157
 158
 159 EXAMPLES
 160 --------
 161
 162 Simple command invocations
 163 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 164
 165 [source,sh]
 166 njackspa amp 1049
 167 gjackspa -b 2 amp.so amp_mono
 168 jackspa-cli -i '>:0.5' /usr/lib/ladspa/delay.so 1043
 169
 170 Connecting several jackspa instances together
 171 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 172 Separate high and low frequencies by using two plugins and controlling the
 173 common cutoff frequency:
 174
 175 [source,sh]
 176 jackspa-cli -I cmt lpf &
 177 njackspa -T cmt hpf
 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"
 181
 182 Programmatically controlling an ng-jackspa instance
 183 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 184 To control an ng-jackspa instance from another process, launch `njackspa` in a
 185 `tmux` and let tmux send the required keys:
 186
 187 [source,sh]
 188 tmux new -s 1 'njackspa <args>'
 189 # programmatically set the second control to its default
 190 tmux send-keys -t 1 g j d
 191 # programmatically increase the last control
 192 tmux send-keys -t 1 G l
 193 # set the current control field to zero
 194 tmux send-keys -t 1 'c-o' 0 'c-j'
 195 # interactively control the instance from any terminal
 196 tmux attach -t 1
 197
 198 The easiest way to retrieve the state of another running jackspa instance is to
 199 export the control inputs as JACK control voltages in jackspa then to connect
 200 as a JACK client to get the current values.
 201
 202 Controlling an ng-jackspa instance from a remote host
 203 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 204 If the network access is permanent, `ssh` can be used for the terminal based
 205 interfaces or for the graphical interfaces:
 206
 207 [source,sh]
 208 ssh host -- njackspa -i 0.5 amp 1049
 209 ssh -f -X host -- gjackspa amp 1049
 210
 211 If the network access is not permanent, `tmux` can be added as a terminal
 212 proxy, as above:
 213
 214 [source,sh]
 215 # if only the creation/destruction of an instance is desired
 216 ssh -f host -- daemon jackspa-cli -i 0.5 amp 1049
 217 ssh host -- pkill -INT jackspa-cli
 218 # launch a remote instance
 219 ssh -f host -- tmux new -s 1 -d 'njackspa <args>'
 220 # connect to the remote instance
 221 ssh host -- tmux attach -t 1
 222 # reset all the active values to their defaults
 223 ssh host -- tmux send-keys -t 1 K D
 224
 225
 226 BUGS
 227 ----
 228
 229 See the ng-jackspa distribution file 'BUGS' to learn how to report bugs or
 230 request a feature.  This is a list of known important bugs and limitations.
 231
 232 * If the sample rate of the JACK server changes, the LADSPA plugin is not
 233   restarted and it continues to run with the initial sample rate; depending
 234   on the plugin, it may or not be wrong.
 235
 236 * If the JACK server shuts down, the interface programs just continue to run,
 237   without notifying of the failure and without ever trying to reconnect to a
 238   newly started server.
 239
 240 * The graphical interfaces do not update their displayed control values when
 241   these are changed by control voltages appearing on the JACK input audio ports
 242   associated with their respective controls.
 243
 244 * If the LADSPA plugin has a port name whose length makes the related JACK port
 245   name unacceptably long, no attempt to truncate the name is made and the
 246   initialisation fails.
 247
 248
 249 AUTHOR
 250 ------
 251 ng-jackspa was written by G.raud Meyer.
 252
 253
 254 SEE ALSO
 255 --------
 256 listplugins(1), analyseplugin(1), strtol(3), strtof(3), jackd(1), jack-rack(1),
 257 non-mixer(1)
 258
 259 The file 'ladspa.h' that is part of the LADSPA SDK.