Mapping of knobs on V4 vs V5

The Zynthian V4 as you all know have two knobs on each side of the screen, whereas V5 has the four knobs on the right hand side. When the Zynthian UI maps parameters to knobs, I’m assuming that on V5, they would be assigned (in numerical order) from top to bottom (is this true?). But on V4, are they assigned top-to-bottom on the left, then top-to-bottom on the right, or top-left - top-right - bottom-left - bottom-right?

I can dig through the code and (default) configuration, but I’m pretty sure someone knows off the top of their head.

Layer(Chain) Learn/Shot
Back Select




(It struck me that I could have looked at the front panel, but looking at Zynthian KIT V5 | Zynthian Shop I remembered why I asked the question in the first place - there are no front panel legends visible for the knobs on V5. Is that because the pictures show an early version, or have the legends been left of purposely - because it’s possible to reassign them?)

I asked about that here, the answer from @jofemodo was that they are “contextual”:

1 Like

Hi @ricard and @tunagenes!

Knob switches are used very differently in V5 and V4.

This is not very accurate. Layer & Back actions are not mapped to knob switches in V5. The V5 user’s guide explains this in detail:

Of course, if you are building a zynthian with 4 rotaries at right and any number of extra buttons, you can assign the knob switches and the rest of buttons as you like from the webconf’s wiring layout screen. In such a case, you should consider contributing your wiring layout config so we can include it in the official software.

Regarding the knob rotaries, then we could say than numbering is:


1 3
2 4



Anyway, this not very important for the final users because each screen decide how to assign the knobs depending on how the graphic elements are layed-out on the display.

If you are a developer, it could be interesting for you to take a look to this file:

You will find very interesting the “GUI layout” section:

# GUI layout

gui_layout = os.environ.get('ZYNTHIAN_UI_GRAPHIC_LAYOUT', '')

if not gui_layout:
	if check_wiring_layout(["Z2", "V5"]):
		gui_layout = "Z2"
		gui_layout = "V4"

if gui_layout == "Z2":
	layout = {
		'name': 'Z2',
		'columns': 2,
		'rows': 4,
		'ctrl_pos': [
			(0, 1),
			(1, 1),
			(2, 1),
			(3, 1)
		'list_pos': (0, 0),
		'ctrl_orientation': 'horizontal',
		'ctrl_order': (0, 1, 2, 3),
	layout = {
		'name': 'V4',
		'columns': 3,
		'rows': 2,
		'ctrl_pos': [
			(0, 0),
			(1, 0),
			(0, 2),
			(1, 2)
		'list_pos': (0, 1),
		'ctrl_orientation': 'vertical',
		'ctrl_order': (0, 2, 1, 3),

First, it check if a “gui_layout” has been specified in the config (webconf->UI Options->Graphic Layout). If not, it will select a “gui_layout” based in the “wiring layout”.
As you can see, currently there are 2 GUI layouts:

  • Z2 => 4 rotaries in the right side (used by V5)
  • V4 => classic layout with rotaries in the corners

Inside the layout definition:

  • “colums” & “rows” define the size of the grid used for the layout
  • “ctrl_pos” define the position of controller widgets inside the grid
  • “list_pos” define the position of the list widget used in many screens
  • “ctrl_orientation” define how the controller elements are layed-out inside the controller widget area
  • “ctrl_order” define the “default” internal numbering of controllers. This can be redefined by some screens.



Thanks @jofemodo for your detailed explanation!

The underlying question here really is, given an LV2 plugin with given parameter numbers (id’s), in which order will the parameters be mapped. From what I can tell - and please correct me if I’m wrong - in the .ttl file related to the plugin in question, the parameters can be put on specific pages if desired, but within each page, and also the order in which the pages are presented in the UI, is dependent on the parameter number. So when designing a new plugin, from the point of view of getting the parameters to appear in a specific order in the Zynthian UI, it is necessary to consider the actual parameter numbers.

Sure, it’s possible to rearrange the knobs (which is of course a great feature and necessary to support different knob layouts), but as I understand it that is on a global level, not per plugin (which of course makes sense given the intended usecase).

1 Like

Each LV2 plugins has one or more TTL files that describe it. Each parameter has an index and by default Zynthian shows the controls in the order of their index split into pages of 4 parameters. It is possible to add a TTL files that either replaces or complements the existing TTLs and adds some info that we use to map controls to specific (groups of) pages or hide controls from view. We have done this for many LV2 plugins and there is a general call for assistance in continuing that effort.

So the upstream LV2 plugins designer does not need to consider how the controls will appear on Zynthian. They are likely to order the controls with some logic that suits themselves.

1 Like

To be more concrete here, in my case I am designing something specifically for Zynthian (MiMi-d - creating a new software synth for Zynthian), so I want to consider the order of the parameters to create a reasonably logical order in the UI not only from page to page (even though the parameters can be grouped into pages in the .ttl file, it still seems that the order of pages follows the parameter index) but also within the pages, as it seems there is no way to override that.

But at any rate, with the knob order being the way it is, for instance, the envelope ADSR parameters would be

A      S
D      R

for V4 and


for V5 which seams reasonable, i.e. A and D appear grouped together as they are on the left side of the UI in V4.


No, A, D, S & R are grouped together. In V4 they appear on the left and on V5 they appear at the top but Zynthian divides gross of parameters into pages of 4. There may be fewer than 4 in a group, e.g.

A      C
B       -

Or have more than 4 in which case it creates multiple pages.

This part of the code is where the LV2 parameters are mapped. Each parameter may have an optional display_priority (lv2:displayPriority) to influence its relative position within a group and a group_symbol (pg:group) to specify to which group it should belong, I think the groups may either be in an arbritary order (maybe the order they are defined) or alphabetical (by symbol, not name) but don’t see in the code how this is defined so if not then maybe an enhancement would allow definition of group order. (I thought it had already been done.)

If you look at some of the lv2-custom configs you will see this in action, e.g. Helm demonstrates both groups and parameter order preference:

    lv2:port [
        a lv2:InputPort, lv2:ControlPort ;
        lv2:index 5 ;
        lv2:symbol "amp_attack" ;
        lv2:name "amp attack" ;
        lv2:default 0.027386 ;
        lv2:minimum 0.0 ;
        lv2:maximum 1.0 ;
        pg:group helm_lv2:AMP_ENV ;
        lv2:displayPriority 1754 ;
    ] ,

We tend to create custom ttl for upstream plugins because unlike your kind effort, no one else is only / primarily targetting Zynthian and hence is less likely to use these optional parameters.

1 Like

Indeed, the impression I get is that the groups are in the order governed by the number of first parameter in each group. I don’t think it’s the symbol, because I have a number of symbols starting with ‘lfo1’ and a number of symbols starting with ‘lfo2’, but the resulting menus are not adjacent to each other.

Perhaps this should be changed, so that a ‘groupPriority’ could be used to set the order of the groups?

You are right.

Please, add this “groupPriority” field to your groups in the TTL file and we will consider to implement it in the zynthian side ASAP.


1 Like

After having worked with the MiMi-d for quite some time now, and after starting to use the Distrho Plugin Framework to generate the lv2 bundle, I’ve devised a method to generate the parameter list in such a way that it is easy to move the parameters around without having to resort to displayPriority or groupPriority (and DPF doesn’t seem to support these anyway, but it does support groups and scale points), so I’ve decided to not try to use them.