--ctrlmidich improved documentation

[pljones]

Short description of changes

jamulussoftware/jamulus#3394 adds a new feature to the --ctrlmidich option to allow binding a MIDI CC number explicitly to the participant's "own" channel on the server, regardless of the assigned channel number.

This required some changes to the documentation to explain how it worked. I took the opportunity to clarify (hopefully) the detailed information in Tips & Tricks.

Context: Fixes an issue? Related issues

See jamulussoftware/jamulus#3394

Status of this Pull Request

Looks okay locally.

What is missing until this pull request can be merged?

Needs reviewing and shouldn't be merged until after jamulussoftware/jamulus#3394

Does this need translation?

YES

Checklist

• I've verified that this Pull Request follows the general code principles
• I'm sure that this Pull Request goes to the correct branch
• I waited some time after this Pull Request was opened and all GitHub checks completed without errors.

[pljones]

Website available for preview here:
http://jamuluswebsite.drealm.info/wiki/Software-Manual#command-line-options
http://jamuluswebsite.drealm.info/wiki/Tips-Tricks-More#using---ctrlmidich-for-midi-controllers

[ann0see]

On the basis that @ignotus666 also gives his ok to this...

[ignotus666]

Looks good to me

[pljones]

Spotted another couple of places I'd said "0 is default" (when it's not -- feature disabled is default).

[ann0see]

If this is mergable, please do so.

[pljones]

shouldn't be merged until after jamulussoftware/jamulus#3394

[pljones]

Converted to draft as will need reconsidering after jamulussoftware/jamulus#3426

[pljones]

@softins do you want to take this branch and replace the z with the d option?

[pljones]

Rebased and updated. @softins you'll probably need to fix what I've just broken...

[softins]

@pljones I have made my updates to the docs; please review and comment if desired.

I found that the CI was failing from today. It seems like the ubuntu-latest runner has now switched from 22.04 to 24.04, and this causes the Jekyll build to fail. I pushed a commit here to pin the CI runner to ubuntu-22.04 and it then succeeded.

We ought to update the CI runner separately from this PR - I'll raise one shortly, and then revert that commit from this PR. DONE

[pljones]

Suggested change

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 unsorted or sorted by channel, whether or not "Own Fader First" is enabled.

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.

In "unsorted", if you join an occupied server, you'll go to the position in the list you arrive back at the client in. Are you guaranteed to be the first in that list?

[softins]

I tested that. In 3.12.0, if you join an occupied server of 3.5.5 or later, you get channel 0 and appear first in the unsorted list.

[softins]

When I tested the new version by connecting to an occupied server of a recent version, my own channel always showed up first in the unsorted view. Performing the same test against a server older than 3.5.5, my own channel appeared to the right of the the prior occupants.

I haven't worked through the code to examine whether this is guaranteed, but it appeared consistent in practice.

Also my wording of the final sentence "whether or not" was intended to make clear that when unsorted or sorted by channel, the Own fader first option made no difference.

[pljones]

I tested that. In 3.12.0, if you join an occupied server of 3.5.5 or later, you get channel 0 and appear first in the unsorted list.

Does that mean the server holds multiple lists of clients, one per client, so it can consistently return the list to the client in that order? Or does it just filter the response and set to zero and move to first the client for each client it's sending the list to? Sounds like more work than needed... (Especially given how much work the client then does with the list when it arrives...)

Also my wording of the final sentence "whether or not" was intended to make clear that when unsorted or sorted by channel, the Own fader first option made no difference.

"Own Fader First" should be taken as the one that disregards sort order. To say a sort order then disregards "Own Fader First" is somewhat circular. It's either unnecessary or confusing. "Unsorted" shouldn't be expressed to mean "your own fader will be first (under some circumstances)" because that's not really that useful (even if it may be true).

[softins]

I tested that. In 3.12.0, if you join an occupied server of 3.5.5 or later, you get channel 0 and appear first in the unsorted list.

Does that mean the server holds multiple lists of clients, one per client, so it can consistently return the list to the client in that order? Or does it just filter the response and set to zero and move to first the client for each client it's sending the list to? Sounds like more work than needed... (Especially given how much work the client then does with the list when it arrives...)

No, the server always sends its own channel numbers to every client. And from 3.5.5 it also sends the client its own server channel ID when it connects. Since the recently-merged update, each client maintains its own set of client-side channel numbers and maps between the two. It maps its own server channel number to client channel 0, and each new server-side channel to the lowest free client channel ID.

When the server sends a connected clients list to the client, the client rewrites the channel numbers in that list according to its own mapping, before passing it up to the mixer board. The mixer board doesn't need to know the client layer mapped them. But I think it processes new channels in order of channel number, rather than order in the list, which means that when processing the first list received after a new connection, it will put channel 0 first. I need to verify this by examining the code.

Also my wording of the final sentence "whether or not" was intended to make clear that when unsorted or sorted by channel, the Own fader first option made no difference.

"Own Fader First" should be taken as the one that disregards sort order. To say a sort order then disregards "Own Fader First" is somewhat circular. It's either unnecessary or confusing. "Unsorted" shouldn't be expressed to mean "your own fader will be first (under some circumstances)" because that's not really that useful (even if it may be true).

OK, fair enough. I'll commit your wording.

[pljones]

Just a few bits and pieces.

[ignotus666]

@softins any outstanding Weblate PRs have to be merged before a documentation (website) PR goes in... Weblate's locked up now.

[softins]

@softins any outstanding Weblate PRs have to be merged before a documentation (website) PR goes in... Weblate's locked up now.

Oh, right, sorry. Didn't know that! Would you like me to resolve the conflict? I'm happy to, but don't want to duplicate effort.

[ignotus666]

Don't worry, it's happened to me a few times! The way I did it was to just revert the offending merged PR, merge the Weblate PR and then this one - but feel free to apply whatever fix you think is best.

[softins]

That sounds good to me.

[softins]

@ignotus666 ok, I've successfully reverted this PR, and the weblate PR no longer complains of a conflict. Shall I just go ahead and merge it, or does it need checking first?

[ignotus666]

Yes, I think you can merge it, I checked the Spanish docs and they're ok, can't speak for the other one though.