Merge pull request #1053 from pljones/ctrlmidich-improved-doc

--ctrlmidich improved documentation

wiki/en/Include-Client-Commands.md

@@ -2,5 +2,5 @@
 - `--mutemyown` Prevent me from hearing what I play in the server mix (headless only)                                                      
 -  `-c` or `--connect`  Connect to given server address on startup, format `address[:port]`  
 -  `-j` or `--nojackconnect`  Disable auto JACK connections  
--  `--ctrlmidich`  MIDI controller channel to listen on, control number offset and consecutive CC numbers (channels) and Mute Myself CC number. Format: `channel[;f*][;p*][;s*][;m*][;o]` See [Tips & Tricks](Tips-Tricks-More#using-ctrlmidich-for-midi-controllers)
+-  `--ctrlmidich`  MIDI channel to listen on, Jamulus control + MIDI control number and count of consecutive CC numbers (or Jamulus channels), device selection option. Format: `channel[;fn[*n]][;pn[*n]][;sn[*n]][;mn[*n]][;on][;dDeviceName]` See [Tips & Tricks](Tips-Tricks-More#using---ctrlmidich-for-midi-controllers).
 - `--clientname`  Window title and JACK client name

wiki/en/Tips-Tricks-More.md

@@ -80,23 +80,110 @@ Here is the script:
  jack_connect Jamulus:'output right' system:playback_2
 ~~~
 
-### Using ctrlmidich for MIDI controllers
+### Using `--ctrlmidich` for MIDI controllers
 
-The volume fader, pan control and mute and solo buttons in the Client's mixer window strips can be controlled using a MIDI controller by using the `--ctrlmidich` parameter (note: only available for use with macOS and Linux using Jamulus version 3.7.0 or higher, and on Windows using the Jamulus version with JACK support). To enable this feature, Jamulus must be launched with `--ctrlmidich`. There is one global MIDI channel parameter (1-16) and two parameters you can set for each item controlled: `offset` and `consecutive CC numbers`. Set the first parameter to the channel you want Jamulus to listen on (0 for all channels) and then specify the items you want to control (f = volume fader; p = pan; m = mute; s = solo; o = mute myself) with the offset (CC number to start from) and number of consecutive CC numbers. There is one exception that does not require establishing consecutive CC numbers which is the "Mute Myself" command - it only requires a single CC number as it is only applied to one's own audio stream. Take the following example:
+The volume fader, pan control and mute and solo buttons in the Client's mixer window strips can be controlled using a connected MIDI controller. This feature is available from version 3.7.0 on macOS, Linux, and the JACK version of Jamulus for Windows. From Jamulus 3.12.0 onwards, it is also available for the non-JACK (ASIO) Windows version.  To enable this feature, Jamulus must be launched with the `--ctrlmidich` command-line option.
 
-`--ctrlmidich "1;f0*8;p16*8;s32*8;m48*8;o64"`
+When this option is used on the command line, Jamulus will prepend a channel number to each Client name, which can be used to control the channel using MIDI CC numbers. In Jamulus version 3.12.0 onwards, when connected to a server of at least version 3.5.5, your own fader will always be given channel 0, and so will appear first when sorted by channel or when "Own Fader First" is enabled.
 
-Here, Jamulus listens on MIDI channel 1. Volume fader CC numbers start at 0 and there are 8 of them (so end at CC number 7). Pan controls start at CC number 16 and end at 23; Solo 32 to 39 and Mute 48 to 55. Mute Myself is enabled/disabled by CC number 64.
+*Tip*: With default settings, when some users leave and others join, their left-right arrangement in the GUI may cease to follow a numerical order, making it more difficult to know who each physical fader/knob on your MIDI controller corresponds to. To keep the fader strips following a numerical order, go to "View" on the top menu bar and switch to "Sort by Channel" (or type `Ctrl+E`).
 
-Please note that for the functions controlled by buttons to work properly, your MIDI controller needs the buttons to be set to "toggle" mode. This means that when pressed to 'turn on' a control, it must send a MIDI CC number with a value >=64, and to 'turn off' the control it must send the same CC number with a value <64. You can read your controller's manual to find out how to set this.
+When using JACK or macOS, make sure you connect your MIDI device's output port to the Jamulus MIDI in port (QjackCtl (Linux/Windows), Audio/MIDI Setup (macOS) or whatever you use for managing connections). In Linux you may need to install and launch `a2jmidid` so your device shows up in the MIDI tab in Qjackctl.  For non-JACK Windows, Jamulus will find the MIDI device(s) automatically, but see the `d` option below if more than one MIDI device is connected.
 
-*Note*: Jamulus does not provide feedback on the on/off state of buttons, meaning that your controller must keep track and toggle LEDs (if any) to 'on' or 'off' itself.
+`--ctrlmidich` takes a single argument.  If you omit it, the parameter is ignored.  There are two formats for the argument:
 
-Fader strips in the mixer window are controlled in ascending numerical order. Continuing with the above example, in strip numbered 0, the volume fader would be controlled by CC number 0; pan by 16; solo by 32 and mute by 48. As we have specified 8 consecutive controllers for each parameter, this would give us MIDI control over 8 strips (volume, pan, solo and mute in each one) in the mixer window. The next strip would be controlled by 1, 17, 33 and 49, and so forth.
+1. The legacy definition has one or two numbers in the format:
 
-Make sure you connect your MIDI device's output port to the Jamulus MIDI in port (QjackCtl (Linux/Windows), MIDI Studio (macOS) or whatever you use for managing connections). In Linux you may need to install and launch a2jmidid so your device shows up in the MIDI tab in Qjackctl.
+   ```
+   [MIDI channel];[offset for first fader]
+   ```
 
-*Tip*: When you enable MIDI control in Jamulus, each user's name is prepended with a number, with the first user starting at 0, then 1, etc. With default settings, when some users leave and others join, their left-right arrangement in the GUI may cease to follow a numerical order, making it more difficult to know who each physical fader/knob on your MIDI controller corresponds to. To keep the fader strips following a numerical order, go to "View" on the top menu bar and switch to "Sort by Channel" (or type `Ctrl+E`).  In Jamulus version 3.12.0 onwards, when connected to a server of at least version 3.5.5, your own fader will always be given channel 0, and so will appear first, whether or not "Own Fader First" is enabled.
+   * `MIDI channel` is required or else the parameter argument is ignored and the feature is not active.  `0` means "any channel", `1`-`16` listen only to MIDI messages on the specified MIDI channel.
+
+   * `offset for first fader` is the first MIDI CC to use to control a Jamulus Channel fader (default 70, which matches the Behringer X-Touch defaults), with all MIDI CCs after that being used; must be a number or else the long form is used.
+
+     For example
+
+     ```
+     --ctrlmidich "0"
+     ```
+
+     would listen on all MIDI channels and use MIDI controller 70 to control Jamulus channel 0 fader and so on.  Here's another example:
+
+     ```
+     --ctrlmidich "2;50"
+     ```
+
+     This would listen on MIDI channel 2 and use MIDI controller 50 to control Jamulus channel 0 fader and so on.
+
+2. The long form is a sequence of offsets and counts for various controllers:
+
+   ```
+   [MIDI channel];[control letter][offset](*[count])(;...)
+   ```
+
+   * `MIDI channel` is required or else the parameter argument is ignored and the feature is not active.  `0` means "any channel", `1`-`16` listen only to MIDI messages on the specified MIDI channel.
+
+   * `control letter` defines which Jamulus Control the MIDI controller number is assigned to:
+
+     | control letter | Jamulus Control |
+     |--------:|---------|
+     | `f` | Fader |
+     | `p` | Pan   |
+     | `s` | Solo  |
+     | `m` | Mute  |
+
+   * `offset` is the base MIDI CC number for the control.
+
+   * `count` is the number of CC values for the control, defaulting to 1 (i.e. the number Jamulus channels that can be controlled).
+
+   An example for a Korg nanoKONTROL2 using eight sliders starting at MIDI CC 0 to control faders and eight knobs starting at MIDI CC 16 to control pan, on any MIDI channnel, for eight Jamulus channels would be
+
+   ```
+   --ctrlmidich "0;f0*8;p16*8"
+   ```
+
+   Enhancing this to add eight Solo buttons starting at CC 32, and eight Mute buttons starting at CC 48 would give:
+
+   ```
+   --ctrlmidich "0;f0*8;p16*8;s32*8;m48*8"
+   ```
+
+   * Two additional `control letter` values are available:
+
+     1. `o` controls Mute Myself and has a single `offset` (i.e. `count` is ignored and taken as 1).
+
+     2. `d` is an option on Windows non-JACK Jamulus to specify a particular MIDI input device by name -- without this, all devices will be assigned to Jamulus; with it, only the specified device will be used.  For example:
+
+        ```
+        --ctrlmidich "1;f0*8;dnanoKontrol"
+        ```
+
+        would listen for CC0 through CC7 on MIDI channel 1 from a MIDI device called "nanoKontrol".  Remember to wrap the whole of the `--ctrlmidich` argument in double quotes and you will have no problems with device names containing spaces.
+
+        In order to discover the correct device name to use, start Jamulus from the command line with `--ctrlmidich` and observe the output. Jamulus will list all discovered MIDI devices:
+
+        ```
+        C:\Users\Me>"C:\Program Files\Jamulus\Jamulus" --ctrlmidich "0"
+        - MIDI controller settings: 0
+        - allocated port number: 22134
+        - MIDI devices found: 2
+          0: nanoKONTROL2
+          1: Keystation Mini 32
+
+        C:\Users\Me>"C:\Program Files\Jamulus\Jamulus" --ctrlmidich "1;f0*8;p16*8;s32*8;m48*8;dnanoKONTROL2"
+        - MIDI controller settings: 1;f0*8;p16*8;s32*8;m48*8;dnanoKONTROL2
+        - allocated port number: 22134
+        - MIDI devices found: 2
+          0: nanoKONTROL2
+          1: Keystation Mini 32 (ignored)
+        ```
+
+	Note that if only one MIDI device is connected, the `d` option is not necessary, as Jamulus will use the device automatically.
+
+	On macOS, Linux or Windows with JACK, the `d` option is accepted if given, but ignored.
+
+*Note*: Jamulus does not provide feedback on the on/off state of buttons, meaning that your controller must keep track and toggle LEDs (if any) to 'on' or 'off' itself, that is, buttons on your MIDI controller need to be set to "toggle" mode. This means that when pressed to 'turn on' a control, it must send a MIDI CC number with a value >=64, and to 'turn off' the control it must send the same CC number with a value <64. You can read your controller's manual to find out how to set this.
 
 ## For Server admins