docs/jack_mixer.1.rst.in

   1 =============
   2  jack_mixer
   3 =============
   4
   5 ----------------------------------------------
   6 A graphical multi-channel audio mixer for JACK
   7 ----------------------------------------------
   8
   9 :Author: Nedko Arnaudov <nedko@arnaudov.name> (original author),
  10     Frédéric Peters <fpeters@0d.be> (current maintainer).
  11 :Date: 2021-03-15
  12 :Copyright: GNU General Public License Version 2
  13 :Version: @VERSION@
  14 :Manual section: 1
  15 :Manual group: audio
  16
  17
  18 SYNOPSIS
  19 ========
  20
  21 jack_mixer.py [-h] [-c FILE] [-d] [NAME]
  22
  23
  24 DESCRIPTION
  25 ===========
  26
  27 This manual page documents the **jack_mixer** command.
  28
  29 **jack_mixer** is a multi-channel audio mixer application for the JACK Audio
  30 Connection Kit with a graphical user interface and has a look & handling similar
  31 to hardware mixing desks.
  32
  33
  34 OPTIONS
  35 =======
  36
  37 positional arguments:
  38   NAME                  set JACK client name
  39
  40 optional arguments:
  41   -h, --help            show this help message and exit
  42   -c FILE, --config FILE
  43                         load mixer project configuration from FILE
  44   -d, --debug           enable debug logging messages
  45
  46
  47 GUI USAGE
  48 =========
  49
  50 After starting **jack_mixer**, you need to create at least one input and one
  51 output channel via the respective entries in the "Mixer" menu (see section
  52 **MAIN MENU**).
  53
  54 Then connect your audio sources to the **jack_mixer's** JACK audio input ports
  55 (see section **JACK AUDIO AND MIDI PORTS**) using ``jack_connect`` or GUI tools
  56 like the QJackCtl's connections window, Catia, Carla, etc. Connect the monitor
  57 channel output port(s) or the output ports of the output channels to the input
  58 ports of your audio interface or any other JACK audio input ports.
  59
  60 Then adjust input and output channel volume levels and balance as required using
  61 the fader controls in each channel strip (see section **MOUSE BINDINGS** for
  62 ways to to control the faders and routing).
  63
  64
  65 JACK AUDIO AND MIDI PORTS
  66 -------------------------
  67
  68 * For each input channel, **jack_mixer** will create one (if it is a mono
  69   channel) or two (stereo) JACK audio input ports. The input port(s) will be
  70   named like the input channel strip, if it is a mono channel, or with an " L"
  71   resp. " R" suffix, it it is a stero channel.
  72
  73 * Optionally, for each input channel, it creates a direct, post-fader audio
  74   output port (mono) or pair of output ports (stereo). These are named the same
  75   as their input port(s) with " Out" resp. " Out L" / "Out R" appended.
  76
  77 * For each ouput channel it will create one (mono) or two (stereo) audio output
  78   ports.
  79
  80 * Additionally it will create one pair of audio monitor ports named "Monitor L"
  81   and "Monitor R".
  82
  83 * If **jack_mixer** was compiled with JACK MIDI support, it will also create
  84   one MIDI input ("midi in") and one MIDI output ("midi out") port.
  85
  86
  87 MAIN MENU
  88 ---------
  89
  90 Main Menu:
  91
  92 Use the **Mixer** menu to:
  93
  94 * Add an input or output channel.
  95 * Add an output channel.
  96 * Open a file with a preset mixer layout.
  97 * Save the current mixer layout to an XML file.
  98 * Exit **jack_mixer**.
  99
 100 Use the **Edit** menu to:
 101
 102 * Change the properties of an input or output channel.
 103 * Remove an input or output channel.
 104 * Toggle all channel strips between wide and narrow view.
 105 * Clear the current mixer layout, i.e. remove all input and output channels.
 106 * Open the setting preferences dialog.
 107
 108 Use the **Help** menu to show **jack_mixer's** about dialog.
 109
 110
 111 MOUSE BINDINGS
 112 --------------
 113
 114 Main window:
 115
 116 * Left-click and drag the vertical divider line horizontally to set the size
 117   distribution of the left and right panels for the input and output channel
 118   strips. If a panel contains more channel strips than can be fit into its
 119   horizontal size, horizontal scrollbars will be available at the bottom of
 120   the panel.
 121
 122 Channel strip header:
 123
 124 * Double click the channel strip header to open the channel properties dialog.
 125 * Ctrl+left-click the channel strip header to toggle the channel strip between
 126   wide and narrow view.
 127 * Left-click and drag the channel strip header horizontally to re-order
 128   channel strips. This doesn't effect the order of the JACK output ports
 129   and input channels are always arranged on the left side of the main
 130   **jack_mixer** window and output chanels on the right side.
 131
 132 Control groups (input channels):
 133
 134 Each input channel header has a control group for each output channel, which
 135 has the same background color and label as the corresponding output channel
 136 header.
 137
 138 Each output channel control group shows a pre/post-fader ("P") and a mute ("M")
 139 button and, optionally, a solo ("S") button.
 140
 141 * Left-click the pre/post-fader ("P") button to toggle the signal sent to the
 142   corresponding output channel between the post-fader (off) and pre-fader (on)
 143   signal of the input channel.
 144 * Left-click the mono ("M") button to mute the signal from the input channel
 145   going to the corresponding output channel.
 146 * Left-click the solo ("S") button to solo the input channel for the
 147   corresponding output channel. i.e. only the signal from this input channel
 148   (plus any other soloed channels) is going to this output channel.
 149
 150 Volume read-out and peak-indicator:
 151
 152 * Left-click the volume level read-out to enter a value manually and press
 153   Enter to set it.
 154 * Left/right-click the peak volume level read-out to reset the over-zero
 155   indication.
 156 * Middle-click the peak volume level read-out to set the volume level to
 157   peak at 0 dB at the current signal input level.
 158
 159 Volume meter:
 160
 161 * Left-click the pre-fader ("PRE") button below the volume meter to switch the
 162   signal, which is metered, from post-fader (off) to pre-fader (on).
 163
 164   *(not yet implemented)*
 165
 166 Volume slider:
 167
 168 * Left-click and drag vertically anywhere in the slider area to set the channel
 169   output volume level.
 170 * Scroll the mouse wheel up or down over the slider area to increase or
 171   decrease the volume level.
 172 * Right-click anywhere in the slider area to move the volume level slowly
 173   towards the click position.
 174 * Double click to set the volume level to -inf.
 175 * Ctrl+left-click to set the volume level to 0 dBFS.
 176
 177 Balance slider:
 178
 179 * Left-click and drag horizontally anywhere in the slider area to set the
 180   balance between the left and right channel of the output signal.
 181 * Scroll the mouse wheel up or down over the slider area to move the
 182   balance to right or left.
 183 * Right-click anywhere in the slider area to move the balance slowly towards
 184   the click position.
 185 * Double click to set the left/right balance to center.
 186
 187 Channel buttons:
 188
 189 * Left-click the  mono ("M") button to mute signal from channel going to all
 190   output channels (including direct channel outs).
 191 * Ctrl+left-click the  mono ("M") button for "exclusive" mute, i.e. the mute
 192   function will be activated on this input or output channel only and
 193   deactivated on all other input resp. output channels.
 194 * Left-click the solo ("S") button to solo an input channel, i.e. only the
 195   signal from this channel is going to all output channels (including the
 196   direct outputs of the channel).
 197
 198   The solo function is cumulative, i.e. you can activate solo on more than one
 199   input channel and the signals from all soloed channels will be going to each
 200   output channel.
 201
 202   Output channels have no solo button.
 203 * Ctrl+left-click the solo ("SM") button for "exclusive" solo, i.e. the solo
 204   function will be activated on this channel only and deactivated on all other
 205   input channels.
 206 * Right-clicking the mute ("M") button acts like left-clicking but also
 207   synchronizes the muted state on all output channel control groups of the
 208   channel with the main channel mute button.
 209
 210   Output channel control groups, where the mute function was already active
 211   before righ-clicking the mute button are unaffected, i.e. it will stay
 212   activated.
 213 * Right-clicking the solo ("S") button acts like left-clicking but also
 214   synchronizes the soloed state on all output channel control groups of the
 215   channel with the main channel solo button.
 216
 217   Output channel control groups, where the solo function was already active
 218   before righ-clicking the solo button are unaffected, i.e. it will stay
 219   activated.
 220 * Left-click the monitor ("MON") button, to toggle monitoring. If monitoring
 221   is on, the (post-fader) signal from the channel is sent to the "Monitor L/R"
 222   outputs. The monitor function is exclusive, i.e. activating monitoring on a
 223   channel, will turn off monitoring on any other channel.
 224
 225
 226 COMPATIBILITY
 227 =============
 228
 229 **jack_mixer** is fully compatible with the New Session Manager (NSM) protocol
 230 and provides Level 1 (L1) support for the LADISH protocol. When running as an
 231 NSM client, the mixer layout and current state will be saved in the NSM session.
 232 When started as an L1 client by LADISH, the mixer layout and current state will
 233 be saved in the LADISH studio session or project (the first time LADISH
 234 requests **jack_mixer** to save a project, it will open a "Save as" dialog).
 235
 236
 237 FILES
 238 =====
 239
 240 ``<XDG_CONFIG_HOME>/jack_mixer/preferences.ini``
 241     This file stores global settings for **jack_mixer**.
 242
 243
 244 ENVIRONMENT
 245 ===========
 246
 247 ``NSM_URL``
 248     When this environment variable is set, **jack_mixer** will act as a New
 249     Session Manager (NSM) session client.
 250 ``JACK_MIXER_DEBUG``
 251     When this environment variable is set, the logging level in the Python
 252     layer is set to ``DEBUG`` unless it is overwritten by the ``-d|--debug``
 253     command line switch.
 254
 255
 256 SIGNALS
 257 =======
 258
 259 ``SIGUSR1``
 260     In accordance with Level 1 support of LADISH, **jack_mixer** saves the
 261     current mixer layout and state on receiving a ``USR1`` signal.
 262 ``SIGINT | SIGTERM``
 263     When receiving an ``INT`` or ``TERM`` signal, **jack_mixer** will either
 264     exit the application immediately or, if enabled in the preferences, will
 265     show a confirmation dialog, allowing the user to either quit or cancel the
 266     action.
 267
 268
 269 SEE ALSO
 270 ========
 271
 272 * Project homepage (https://rdio.space/jackmixer/)
 273 * Source code repository on GitHub (https://github.com/jack-mixer/jack_mixer)
 274 * JACK Audio Connection Kit (https://jackaudio.org/)
 275 * New Session Manager (https://new-session-manager.jackaudio.org/)