Skip to content

Update MIDI docs for GUI tab #1121

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ignotus666 wants to merge 2 commits into
base: next-release
Choose a base branch
from
Open

Update MIDI docs for GUI tab #1121

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cd9ac50
Update MIDI docs for GUI tab
ignotus666 Feb 11, 2026
191b2f8
Update screenshot links and docs
ignotus666 Mar 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions assets/img/de-screenshots/settings-midi.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
https://github.com/user-attachments/assets/2f14110c-5e73-4416-b8dc-f326fe3b5f3d
1 change: 1 addition & 0 deletions assets/img/en-screenshots/settings-midi.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
https://github.com/user-attachments/assets/2f14110c-5e73-4416-b8dc-f326fe3b5f3d
1 change: 1 addition & 0 deletions assets/img/es-screenshots/settings-midi.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
https://github.com/user-attachments/assets/2f14110c-5e73-4416-b8dc-f326fe3b5f3d
1 change: 1 addition & 0 deletions assets/img/fr-screenshots/settings-midi.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
https://github.com/user-attachments/assets/2f14110c-5e73-4416-b8dc-f326fe3b5f3d
1 change: 1 addition & 0 deletions assets/img/ko-KR-screenshots/settings-midi.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
https://github.com/user-attachments/assets/2f14110c-5e73-4416-b8dc-f326fe3b5f3d
1 change: 1 addition & 0 deletions assets/img/nb-NO-screenshots/settings-midi.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
https://github.com/user-attachments/assets/2f14110c-5e73-4416-b8dc-f326fe3b5f3d
1 change: 1 addition & 0 deletions assets/img/nl-screenshots/settings-midi.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
https://github.com/user-attachments/assets/2f14110c-5e73-4416-b8dc-f326fe3b5f3d
1 change: 1 addition & 0 deletions assets/img/pt-BR-screenshots/settings-midi.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
https://github.com/user-attachments/assets/2f14110c-5e73-4416-b8dc-f326fe3b5f3d
1 change: 1 addition & 0 deletions assets/img/pt-PT-screenshots/settings-midi.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
https://github.com/user-attachments/assets/2f14110c-5e73-4416-b8dc-f326fe3b5f3d
1 change: 1 addition & 0 deletions assets/img/ru-screenshots/settings-midi.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
https://github.com/user-attachments/assets/2f14110c-5e73-4416-b8dc-f326fe3b5f3d
1 change: 1 addition & 0 deletions assets/img/sv-SE-screenshots/settings-midi.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
https://github.com/user-attachments/assets/2f14110c-5e73-4416-b8dc-f326fe3b5f3d
1 change: 1 addition & 0 deletions assets/img/th-screenshots/settings-midi.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
https://github.com/user-attachments/assets/2f14110c-5e73-4416-b8dc-f326fe3b5f3d
1 change: 1 addition & 0 deletions assets/img/zh-CN-screenshots/settings-midi.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
https://github.com/user-attachments/assets/2f14110c-5e73-4416-b8dc-f326fe3b5f3d
10 changes: 5 additions & 5 deletions wiki/en/Include-Client-Commands.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
- `-M` or `--mutestream` Prevent others on a server from hearing what I play
- `--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 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).
- `-M` or `--mutestream` Prevent others on a server from hearing what I play
- `--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 channel to listen on, Jamulus control + MIDI control number and count of consecutive CC numbers (or Jamulus channels), pick-up mode, device selection option. Format: `channel[;fn[*n]][;pn[*n]][;sn[*n]][;mn[*n]][;on][;u][;dDeviceName]` See [Tips & Tricks](Tips-Tricks-More#using---ctrlmidich-for-midi-controllers).
- `--clientname` Window title and JACK client name
31 changes: 30 additions & 1 deletion wiki/en/Software-Manual.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -173,7 +173,7 @@ Sorts by the instrument or city someone has in their profile, along with their n
* Sort by Group<br/>
Where the fader group feature is in use, this sorts in ascending group number from left to right (and within that, by name), with any ungrouped channels off to the right.
* Sort by Channel<br/>
Where Jamulus channel controls (fader, mute, solo, etc) are being controlled by MIDI (see [Using --ctrlmidich for MIDI controllers](Tips-Tricks-More#using---ctrlmidich-for-midi-controllers)), this sorts by the channel number to help ensure a stable sort order that aligns with MIDI hardware controls.
Where Jamulus channel controls (fader, mute, solo, etc) are being controlled by MIDI (see [MIDI control](#midi-control)), this sorts by the channel number to help ensure a stable sort order that aligns with MIDI hardware controls.
Note that in Jamulus clients before version 3.12.0, channel numbers are assigned directly by the server. Clients from 3.12.0 onwards manage their own channel number assignments and always assign channel 0 to the local user (provided the server version is at least 3.5.5).

### View > Chat
Expand Down Expand Up @@ -338,6 +338,35 @@ Controls the relative levels of the left and right local audio channels. For a m
it acts as a pan between the two channels. For example, if a microphone is connected to the right input channel and
an instrument is connected to the left input channel which is much louder than the microphone, move the audio fader to increase the relative volume of the mic.

## MIDI Control

<figure><img src="{% include img/en-screenshots/settings-midi.inc %}" style="border: 5px solid grey;" loading="lazy" alt="Image of MIDI control window"></figure>

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 and open a MIDI-in port, activate the "MIDI-in" checkbox.

### MIDI Device

With MIDI-in enabled, Jamulus will detect the MIDI devices available for connection and list them in the 'MIDI Device' dropdown menu. Select the device you wish to connect to Jamulus. The non-JACK Windows version of Jamulus will automatically connect to all available MIDI devices if none have been selected previously or a saved device is not present. To connect to a single device, select it from the dropdown.
Copy link
Contributor

@pljones pljones Mar 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The non-JACK Windows version of Jamulus will automatically connect to all available MIDI devices if none have been selected previously or a saved device is not present.

This should not be the case.

I thought we'd said the default was to have MIDI disabled -- i.e. not change in current behaviour.

Copy link
Member Author

@ignotus666 ignotus666 Mar 6, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure I understand; the current behaviour is precisely that: if there are any MIDI devices present and none have been specified on the command line (or saved), it will connect to all of them. Note that the paragraph starts with "With MIDI-in enabled".

Copy link
Contributor

@pljones pljones Mar 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No it doesn't.

If I run Jamulus without parameters, no version will even consider opening a MIDI device.

That behaviour should be the default.

Of course, if I say `Jamulus --ctrlmidich '1;', all versions will go find all available MIDI devices to listen on channel 1.

See the difference? In the first case, Jamulus did what Jamulus had always done before --ctrlmidich was introduced: took no notice of MIDI. Only when the user explicitly requested use of MIDI did Jamulus go looking for devices.

The UI needs to retain that model.

Starting up with Jamulus, having taken no notice in the past and having no intention of taking any notice in future of MIDI should not cause any change in behaviour -- Jamulus must not start doing something with MIDI devices because of this change.

If the user then sees there's a new feature, opens MIDI settings and chooses to enable MIDI - just like they might have chosen to use --ctrlmidich -- then yes, Jamulus will go hunting down those MIDI devices, just the same.

Copy link
Member Author

@ignotus666 ignotus666 Mar 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If a user installs Jamulus and has never used MIDI nor intends to, when they launch it MIDI will be disabled, and will continue to be disabled until they enable it. I'm sorry but I don't see where it's implied otherwise.

Of course, if I say `Jamulus --ctrlmidich '1;', all versions will go find all available MIDI devices to listen on channel 1.

No, only the non-Jack Windows version will do that. The others will default to "No device connected" or if there was one saved previously, to that.

Copy link
Contributor

@pljones pljones Mar 7, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The non-JACK Windows version of Jamulus will automatically connect to all available MIDI devices if none have been selected previously or a saved device is not present.

That explicitly tells the user their MIDI devices get connected, doesn't it? Regardless of any choice.

No, only the non-Jack Windows version will do that. The others will default to "No device connected" or if there was one saved previously, to that.

Then how did they work before the optional ;ddevice was added?

Remember - I'm concerned with changes from 3.11.0 - before the UI or preferences existed.

Copy link
Member Author

@ignotus666 ignotus666 Mar 7, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Then how did they work before the optional ;ddevice was added?

You had to make the connection manually using an external connection manager (e.g. QJackctl). Non-Jack Windows just connected to all available devices.

Copy link
Contributor

@pljones pljones Mar 7, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-JACK Windows didn't have MIDI in 3.11.0:

  • Client: Added native MIDI support to the ASIO (non-Jack) Windows build (#3431).
*   39052347 2024-12-06 Merge pull request #3431 from softins/windows-native-midi [Tony Mountifield]
...
* 9f129576 2024-09-21 (tag: r3_11_0, tag: latest) Update ChangeLog for 3.11.0 [Peter L Jones]

So, no, non-JACK Windows did not "just connect to all available devices". The ;d was added in the same change.

Even with that change, unless explicitly requested, MIDI wasn't started.

+
+    // Optional MIDI initialization --------------------------------------------
+    if ( iCtrlMIDIChannel != INVALID_MIDI_CH )
+    {
+        Midi.MidiStart();
+    }
+}

That doesn't just apply to Windows:

src/util.h:#define INVALID_MIDI_CH            -1 // invalid MIDI channel definition
src/sound/jack/sound.cpp:    if ( iCtrlMIDIChannel != INVALID_MIDI_CH )
src/sound/soundbase.cpp:    iCtrlMIDIChannel ( INVALID_MIDI_CH ),
src/sound/coreaudio-mac/sound.cpp:    if ( iCtrlMIDIChannel != INVALID_MIDI_CH )
src/sound/asio/sound.cpp:    if ( iCtrlMIDIChannel != INVALID_MIDI_CH )
src/sound/asio/sound.cpp:    if ( iCtrlMIDIChannel != INVALID_MIDI_CH )

The default was and needs to remain that -- unless the user explicitly requests use of MIDI -- MIDI is not used.

Copy link
Member Author

@ignotus666 ignotus666 Mar 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So, no, non-JACK Windows did not "just connect to all available devices". The ;d was added in the same change.

Ok my bad - since it was there when I started work on this I assumed it'd been in since the previous release. But then it's a moot issue: no change in behaviour from 3.11 since there wasn't any behaviour.

The default was and needs to remain that -- unless the user explicitly requests use of MIDI -- MIDI is not used.

But this is what happens. The only difference now is that if you've enabled MIDI (and not disabled it again), the enabled state will persist across restarts without adding --ctrlmidich. This is what currently happens with some other settings. In fact you can disable MIDI again on the CLI with jamulus --ctrlmidich '-1' or any other invalid channel number; even an empty string will do. If you set e.g. delay panning for the server with the CLI, how do you disable it other than via the GUI? It will stay enabled across restarts even if you omit the -P option. What doesn't make any sense to me is to have to explicitly keep enabling a setting every time I fire up an application. If I've set something to "enabled", particularly if it's in the GUI, I'd expect it to stay that way until I explicitly disable it.

Copy link
Contributor

@pljones pljones Mar 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You've written this in the docs:

The non-JACK Windows version of Jamulus will automatically connect to all available MIDI devices if none have been selected previously or a saved device is not present.

Now you're contradicting it.

Copy link
Member Author

@ignotus666 ignotus666 Mar 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Now you're contradicting it.

It would be helpful if you could point out where this contradiction is, because I don't see it.

This is the quote you keep referencing with the key bit of context added:

With MIDI-in enabled [...] The non-JACK Windows version of Jamulus will automatically connect to all available MIDI devices if none have been selected previously or a saved device is not present.


### MIDI parameters

There is one global MIDI channel parameter (0-16) and two parameters you can set for each item controlled: First MIDI CC and consecutive CC numbers (count). First set the channel you want Jamulus to listen on (0 for all channels). Then, for each item you want to control (volume fader, pan, solo, mute), set the first MIDI CC (CC number to start from) and number of consecutive CC numbers (count) you wish to assign to that particular item. You can either type in the MIDI CC values or use the "Learn" button: click on "Learn", actuate the fader/knob/button on your MIDI controller, and the MIDI CC number will be detected and saved.

As an example, a 'First MIDI CC' of 0 and a 'Count' of 8 for volume faders will mean that CC numbers 0 - 7 will control the volume faders for up to 8 mixer channels.

There is one exception that does not require establishing consecutive CC numbers which is the “Mute Myself” parameter - it only requires a single CC number as it is only applied to one’s own audio stream.

### Pick-up Mode

When enabled, fader and pan controls will wait for your physical controller to match their value before moving. This prevents sudden jumps when they are out of sync.


*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.

When MIDI is enabled, 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.

*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`).

# Backing up Jamulus

{% include_relative Include-Backing-Up.md %}
Expand Down
32 changes: 13 additions & 19 deletions wiki/en/Tips-Tricks-More.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,33 +82,27 @@ Here is the script:

### 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 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.
MIDI controller parameters can be set using the `--ctrlmidich` command-line option. Bear in mind that when used, specified control parameters will overwrite any values set previously using the GUI. Any controls not set in the command line will be disabled, though their values will be preserved.

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.

*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`).

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.

`--ctrlmidich` takes a single argument. If you omit it, the parameter is ignored. There are two formats for the argument:
`--ctrlmidich` takes a single argument. If you omit it, the parameter is ignored. There are two formats for the argument:

1. The legacy definition has one or two numbers in the format:

```
[MIDI channel];[offset for first fader]
```

* `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.
* `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.
* `offset for first fader` is the first MIDI CC to use to control a Jamulus Channel fader, 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:
would listen on all MIDI channels and use MIDI controller 0 to control Jamulus channel 0 fader and so on. Here's another example:

```
--ctrlmidich "2;50"
Expand All @@ -122,7 +116,7 @@ When using JACK or macOS, make sure you connect your MIDI device's output port t
[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.
* `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:

Expand All @@ -149,17 +143,19 @@ When using JACK or macOS, make sure you connect your MIDI device's output port t
--ctrlmidich "0;f0*8;p16*8;s32*8;m48*8"
```

* Two additional `control letter` values are available:
* Three 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:
2. `u` enables `MIDI Pick-up Mode` for the fader and pan controls.

3. `d` is an option to specify a particular MIDI input device by name -- without this, it is up to the user to make connections with a connection manager or by other means, and on Windows non-JACK Jamulus 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.
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:

Expand All @@ -179,11 +175,9 @@ When using JACK or macOS, make sure you connect your MIDI device's output port t
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 that for Windows non-JACK Jamulus if only one MIDI device is connected, the `d` option is not necessary, as Jamulus will use the device automatically.

*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 more information about using MIDI devices with Jamulus, see the [MIDI control](Software-Manual#midi-control) section in the Software Manual.

## For Server admins

Expand Down
Loading