Key binding improvement

[BenMcLean]

Is your feature request related to a problem? Please describe.
I get on the VNC and try to control the Zynthian with my PC keyboard only of course the default key bindings aren't anywhere even close to being intuitive. But OK, eventually I find out that I can look at what the key bindings are in the web interface at http://zynthian.local/ui-keybind so that makes sense.

But then I see that the text displayed in the "Event" column for what the keys actually bind to does not match the text on the physical buttons on the actual Zynthian v5 device at all. Nor am I aware of there being any sort of chart in the documentation so that I could do a lookup of the lookup to resolve what keys go to what buttons. I was just trying to access the admin menu but I ended up accidentally shutting down the device without ever opening the admin menu because I pressed the wrong keys somehow. What the hell.

Describe the solution you'd like
The "Event" column in the web interface key bindings page should show the same text as is on the physical buttons on the device. This could replace the "Event" column or it could be added to the event column (like it could display both the event and the actual button text) or it could be an additional column on that page describing the events.

Describe alternatives you've considered
Someone could make a graphic / chart showing which physical button triggers which "Event" so to find out how to get the equivalent of that button, you'd first look at the chart to find out which event you want from the button, then look at the key bindings to find out which key triggers that event. That would be an entire extra step for users but it would at least be possible instead of pressing random "ZYNSWITCH " events and just hoping one of them opens the admin menu like I was doing.

Additional context
I'm visually impaired so I struggle to see the small screen on the Zynthian device, which is why having VNC as an option helps. Or would help, if I could figure out how to open the admin menu because so far I still haven't managed to do it.

[riban-bw]

The default keybinding includes a layout based on the zynthian V4, if you have a similar keyboard as the UK author:

key	action	note
i	Encoder switch 1	Top left of 4 keys chosen to represent top left encoder switch on V4
k	Encoder switch 2	Bottom left of 4 keys chosen to represent bottom left encoder switch on V4
o	Encoder switch 3	Top right of 4 keys chosen to represent top right encoder switch on V4
l	Encoder switch 4	Bottom right of 4 keys chosen to represent bottom right encoder switch on V4
comma	Encoder 4 CCW	the comma is on same key as '<' so looks like a decrement
period	Encoder 4 CW	the period is on same key as '>' so looks like an increment
Adding ctrl modifier to encoder keybinding acts on the left encoders.
Adding shift modifier to encoder keybinding acts on the top encoders.
A key mapped to a switch will operate its short, bold or long operations, based on the time the key is pressed.
There is method in this and logical if you know, and have a similar keyboard layout.

The Event column refers to internal API events, not specific zynthian keys. This is a fairly low-level hardware configuration where some understanding of the zynthian's CUIA is desirable. This page of the wiki has some useful information.

[BenMcLean]

The default keybinding includes a layout based on the zynthian V4

What I gather from this is that the Zynthian v5 got designed to have physical buttons with text on them describing functions which don't match previous hardware designs and also don't match the intended design of the software going forward and also aren't a generic industry standard layout like a numpad. So there are custom keys mapping to custom buttons mapping to custom events: three layers of abstraction (buttons on the device, QWERTY keys, events) without having started from a consensus on what the control scheme is going to be. Is that an accurate assessment of what happened?

No wonder I'm having so many problems just trying to control this thing. It is not clear at all which buttons / keys / events will do what in what context. I don't mind a little menu diving in a synth but some consistent easy-to-remember rules about what does what when would be nice.

Is an "encoder" a British word for a "knob"?

I also don't understand how the buttons on the v4 which I don't have would map to the buttons on the v5 which I do have.

[riban-bw]

Is an "encoder" a British word for a "knob"?

A "knob" is the plastic thing that is attached to an electronic component. That might be a potentiometer but in the zynthian we use rotary encoders. These are continuous / endless rotation devices that encode motion into electronic signals.

We abstract the user interface in many ways. It is presented on a V4 with a small touchscreen, 4 rotary encoders with push switches and 4 buttons. On the V5 the UI is presented with a larger, multitouch screen, 4 rotary encoders with push switches and 20 buttons. For touch-only devices we present a screen with touch actions and gestures. For VNC we present a screen with mouse and keyboard binding, etc. Many enthusiasts build their own variations of this.

The default keyboard binding includes the V4 layout I described earlier because it was written on the V4 before the V5 was an itch in its parents' pants. There is also default keyboard binding for a numeric keypad which also makes sense to the designers. Users comprehension may vary! The V3, V4, V5, etc. are designed to be used with their hardware controls, i.e. the default V4 configuration uses UI that differs to the default V5, due to its fewer controls. It didn't make sense to us to provide a keyboard map for the V5 that has many more buttons and hence would require many more keys which, on a standard keyboard do not layout in a 4x5 grid like the V5 does. (There have been users who have built 4x5 USB keypads.) Also, zynthian is built worldwide and there are many different keyboards so creating default keybinding layouts for every user would be fairly futile - most users would want to customise this in some way to better suit themselves, e.g. the default mapping of KeyA to start audio recording may make little sense to a Pole who might expect a different key to be used for "nagranie dźwiękowe".

I am pretty pleased with the keybinding in webconf. It is fast and fairly simple and even has a learn function (although that is kinda undermined by the need to use the browser keyboard rather than an attached keyboard). As soon as you hit Save the changes are applied. Constructive suggestions for improvement are always considered, especially when posed with a postive attitude.

There is an additional layer of abstraction available in the keyboard binding. I had initially avoided it but realised its benefit. You can bind keys to specific actions, like Toggle Audio Record. You can also bind keys to switch or encoder actions which has the benefit of allowing you to drive the zynthian from the QWERTY (or whatever) keyboard just like from its front panel. The default mapping includes that binding for V4. The same could be done for V5 by mapping keys to ZYNSWITCH 4..23, i.e. the top left button (OPT/Admin) is ZYNSWITCH 4 and the bottom right button (F4) is ZYNSWITCH 23. The rotary encoders and their switches are mapped the same as the V4 encoders.

[BenMcLean]

Thanks for explaining what an encoder is and how, while it looks like a knob, it's actually a distinct physical control because of the properties you described.

It looks like the answer to my question, "Is that an accurate assessment of what happened?" is yes, that is what happened because different enthusiasts were all making their own custom hardware.

Is there a way to just paste a large number of custom key/control bindings at once, like by editing a config file? If so, then I am thinking to make one that's specific to the combination of the Zynthian v5 and American QWERTY. I am thinking that the 5x4 grid of buttons on the Zynthian v5 should map to these keys:

f1	f2	f3	f4
1	2	3	4
q	w	e	r
a	s	d	f
z	x	c	v

on an American QWERTY keyboard. The encoders could be mapped like this:

Encoder	Counter-Clockwise	Clockwise	Press
1 (top)	f4	f5	f6
2	t	y	u
3	g	h	j
4 (bottom)	b	n	m

That way, the keyboard layout would match the physical button layout. It'd be like playing StarCraft with TheGrid key bindings.

But I don't want to make this for just my one current install of the Zynthian OS: I want to have a process to add it quickly to any new install so that's why I'm asking about if I can make it so I can quickly paste the entire scheme at once.

[riban-bw]

The file that holds this info is /zynthian/config/keybinding.json. This is the default binding:

{
    "Space": "ALL_NOTES_OFF",
    "shift+Space": "ALL_SOUNDS_OFF",
    "Backspace": "ZYNSWITCH 1",
    "Escape": "ZYNSWITCH 1",
    "Enter": "ZYNSWITCH 3",
    "KeyI": "ZYNSWITCH 0",
    "KeyK": "ZYNSWITCH 1",
    "KeyO": "ZYNSWITCH 2",
    "KeyL": "ZYNSWITCH 3",
    "Comma": "ZYNPOT 3,-1",
    "Period": "ZYNPOT 3,1",
    "shift+Comma": "ZYNPOT 2,-1",
    "shift+Period": "ZYNPOT 2,1",
    "ctrl+Comma": "ZYNPOT 1,-1",
    "ctrl+Period": "ZYNPOT 1,1",
    "shift+ctrl+Comma": "ZYNPOT 0,-1",
    "shift+ctrl+Period": "ZYNPOT 0,1",
    "KeyA": "START_AUDIO_RECORD",
    "shift+KeyA": "STOP_AUDIO_RECORD",
    "alt+KeyA": "TOGGLE_AUDIO_RECORD",
    "ctrl+KeyA": "START_AUDIO_PLAY",
    "shift+ctrl+KeyA": "STOP_AUDIO_PLAY",
    "ctrl+alt+KeyA": "TOGGLE_AUDIO_PLAY",
    "KeyM": "START_MIDI_RECORD",
    "shift+KeyM": "STOP_MIDI_RECORD",
    "alt+KeyM": "TOGGLE_MIDI_RECORD",
    "ctrl+KeyM": "START_MIDI_PLAY",
    "shift+ctrl+KeyM": "STOP_MIDI_PLAY",
    "ctrl+alt+KeyM": "TOGGLE_MIDI_PLAY",
    "ArrowUp": "ARROW_UP",
    "ArrowDown": "ARROW_DOWN",
    "ArrowLeft": "ARROW_LEFT",
    "ArrowRight": "ARROW_RIGHT",
    "Numpad1": "ZYNSWITCH 1",
    "Numpad2": "ARROW_DOWN",
    "Numpad3": "ZYNSWITCH 3",
    "Numpad4": "ARROW_LEFT",
    "Numpad6": "ARROW_RIGHT",
    "Numpad7": "ZYNSWITCH 0",
    "Numpad8": "ARROW_UP",
    "Numpad9": "ZYNSWITCH 2",
    "NumpadEnter": "ZYNSWITCH 3",
    "Digit0": "PROGRAM_CHANGE 0",
    "Digit1": "PROGRAM_CHANGE 1",
    "Digit2": "PROGRAM_CHANGE 2",
    "Digit3": "PROGRAM_CHANGE 3",
    "Digit4": "PROGRAM_CHANGE 4",
    "Digit5": "PROGRAM_CHANGE 5",
    "Digit6": "PROGRAM_CHANGE 6",
    "Digit7": "PROGRAM_CHANGE 7",
    "Digit8": "PROGRAM_CHANGE 8",
    "Digit9": "PROGRAM_CHANGE 9",
    "shift+Home": "RESTART_UI",
    "ctrl+Home": "REBOOT",
    "ctrl+End": "POWER_OFF",
    "ctrl+Insert": "RELOAD_MIDI_CONFIG"
}

You can save a backup of the config files using webconf's backup feature. You could do a backup, edit the json file then restore the backup with the edited file.

[BenMcLean]

Great info, thanks!

I see the events are in ALLCAPS but the keys are in mixed case and only some keys start with a capital letter. Are these strings being evaluated case sensitive so I have to be careful to match or is it case insensitive so it doesn't matter? If it's case sensitive, what case should I use for the function keys?

I get that the ZYNPOT controls correspond to the four rotary encoders, so that ZYNPOT 3,-1 would be turning the third encoder counter-clockwise, ZYNPOT 1,0 would be pressing the first encoder and ZYNPOT 4,1 would be turning the fourth encoder clockwise. Please correct me if I'm wrong on those.

I also get that the upper left button on the 5x4 grid is ZYNSWITCH 4 and the lower right button is ZYNSWITCH 23 following Western reading order. (first left-to-right then top-to-bottom)

But what are ZYNSWITCH 0 to ZYNSWITCH 3?

Also, if I happened to edit the config files with nano over SSH, what would I need to do to make my changes take effect? Or is that just a bad way to do it?

My plan is to make a Github Gist of my custom keybinds with instructions on how to install them when I'm done with this. ;)

[BenMcLean]

Just so there's no confusion, I asked four questions:

1. Are the key names case sensitive?
2. If the key names are case sensitive then what case are the function keys? (f1 or F1? Can be ignored if they are case insensitive)
3. What are ZYNSWITCH 0 to ZYNSWITCH 3?
4. If the config file was edited directly using SSH, what command(s) should be run to make them take effect? (or explain if this is a bad idea for some reason)

(later edit: Four questions, not three. Oops!)

[riban-bw]

Almost correct. The push switches on the encoders are zynswitch 0..3.

[riban-bw]

1. The key names are case sensitive.
2. Almost certainly capital, e.g. F1... but you can test that in webconf.
3. Zynswitch 0..3 are the encoder push switches.
4. Editing the file directly... I can't remember and don't have time to check now but webconf will read the file, save and assert changes so you could use that to assert any changes. Or just reboot.

[riban-bw]

I believe this ticket to be a request for assistance in configuring key bindings which has been provided. I do not believe there to be a bug report or feature request so will close the ticket. Please re-open or create a new ticket if you need further assistance.