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

Draft
ignotus666 wants to merge 1 commit into
base: next-release
Choose a base branch
from
Draft

Update MIDI docs for GUI tab #1121

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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/b1b07b0d-e5e7-4704-a7ae-17bc18004095
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/b1b07b0d-e5e7-4704-a7ae-17bc18004095
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/b1b07b0d-e5e7-4704-a7ae-17bc18004095
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/b1b07b0d-e5e7-4704-a7ae-17bc18004095
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/b1b07b0d-e5e7-4704-a7ae-17bc18004095
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/b1b07b0d-e5e7-4704-a7ae-17bc18004095
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/b1b07b0d-e5e7-4704-a7ae-17bc18004095
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/b1b07b0d-e5e7-4704-a7ae-17bc18004095
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/b1b07b0d-e5e7-4704-a7ae-17bc18004095
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/b1b07b0d-e5e7-4704-a7ae-17bc18004095
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/b1b07b0d-e5e7-4704-a7ae-17bc18004095
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/b1b07b0d-e5e7-4704-a7ae-17bc18004095
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/b1b07b0d-e5e7-4704-a7ae-17bc18004095
24 changes: 23 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,28 @@ 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.

When using Linux 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). If using QjackCtl in Linux you may need to install and launch `a2jmidid` so your device shows up in the MIDI tab. For non-JACK Windows, Jamulus will find the MIDI device(s) automatically, but [see the `d` command line option](Tips-Tricks-More#using---ctrlmidich-for-midi-controllers) if more than one MIDI device is connected.

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.

*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
18 changes: 5 additions & 13 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,15 +82,9 @@ 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 it will overwrite any values set previously via the GUI. Any values not set in the command line will be reverted to defaults (0 for offset/first MIDI CC and 1 for count).
Copy link
Contributor

@pljones pljones Feb 12, 2026

Choose a reason for hiding this comment

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

I think the style guide prefers "using" to "via" -- give it a quick read.

Also, it's probably useful to link to the MIDI section in the Software Manual page from here, as you've centralised it nicely.

Copy link
Member Author

@ignotus666 ignotus666 Feb 12, 2026

Choose a reason for hiding this comment

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

Will do.


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:

Expand All @@ -100,15 +94,15 @@ When using JACK or macOS, make sure you connect your MIDI device's output port t

* `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`
Copy link
Contributor

@pljones pljones Feb 12, 2026 •
edited
Loading

Choose a reason for hiding this comment

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

Why is the description removed?

--ctrlmidich ";1"

should fail to parse and be ignored.

Copy link
Member Author

@ignotus666 ignotus666 Feb 12, 2026

Choose a reason for hiding this comment

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

I removed it because it's a verbatim repetition of the same explanation a bit further up. But I see your point - it could be assumed that the requirement doesn't apply in this case.


* `control letter` defines which Jamulus Control the MIDI controller number is assigned to:

Expand Down Expand Up @@ -183,8 +177,6 @@ When using JACK or macOS, make sure you connect your MIDI device's output port t

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

### Converting a Registered Server to an Unregistered one on the fly
Expand Down
Loading