Difference between revisions of "Zynthian UI User Guide - V1/V4"

From ZynthianWiki
Jump to navigation Jump to search
Line 2: Line 2:
=General Concepts=
=General Concepts=
The Zynthian UI is displayed on a display and controlled by 4 knobs with switches. You can also control the UI with a touch-display, a mouse or a keyboard (computer keyboard or MIDI keyboard, both!)
The core Zynthian UI consists of a display and four knobs with push switches. You can also control the UI with a touchscreen, a mouse or a keyboard (computer keyboard or MIDI keyboard, both!)
The four knobs & switches are the primary control mechanism to navigate the UI: selecting options on menus and adjusting the instrument parameters. The knobs can act as assignable MIDI / OSC controllers for the instrument's parameters (frequently lots of them!). You can emulate the knob's behaviour using the touch-display, but it's sub-optimal and accessing some features could be tricky.
The four knobs & switches are the primary control mechanism to navigate the UI: selecting options on menus and adjusting parameters. The knobs can act as assignable MIDI / OSC controllers for parameters (frequently lots of them!). Most operations may be performed with the touchscreen but some may not be intuitive. See the section on [[#Touch_Screen_UI|touchscreen]] and comments throughout this documentation.
[[File:Zynthian v4 top legend.png|600px|center]]
[[File:Zynthian v4 top legend.png|600px|center]]

Revision as of 15:39, 1 September 2022

1 General Concepts

The core Zynthian UI consists of a display and four knobs with push switches. You can also control the UI with a touchscreen, a mouse or a keyboard (computer keyboard or MIDI keyboard, both!)

The four knobs & switches are the primary control mechanism to navigate the UI: selecting options on menus and adjusting parameters. The knobs can act as assignable MIDI / OSC controllers for parameters (frequently lots of them!). Most operations may be performed with the touchscreen but some may not be intuitive. See the section on touchscreen and comments throughout this documentation.

Zynthian v4 top legend.png

There are two main screen-layout types:

  • Selector Screen: a list of items that you can scroll and select with the SELECT knob (CTRL-4)
  • Controller Screen: 4 control widgets in the corners (one for each knob), with label and value indicators (graphic and numeric). In the middle there is a list of controller screens, each one mapping 4 controllers which you can use to change the engine parameters.

Most of Zynthian UI screens belongs to one of these 2 categories, however, other screen-layouts do exist:

  • Confirmation Screen: It will ask you to confirm some operation.
  • XY Controller Screen: It allows to modify 2 parameters at once using the touch interface.
  • Info Screen: It displays info about an operation, like "Update Software", or "Network Info".
  • Key Range & Transpose Screen: It allows to choose the key range and transpose notes by octaves or semitones.
  • etc.

There are 3 types of push actions that can be performed, depending on how long you hold down the knob / button (or hold your finger on the touch-display).

  • Short push: Less than 0.3 seconds
  • Bold push: Between 0.3 and 2 seconds
  • Long push: More than 2 seconds (until the long-action is triggered!)

These timing values are the default ones. You can adjust them to your personal feeling from the UI options in the web-based configuration tool (webconf).

Some push actions depends of context. The SELECT knob is mainly used to navigate and a short push on it will select an item on a "Selector Screen". Inside a "Controller Screen", short pushes can be used to rotate between chains (LAYER knob) or between controller pages (SELECT knob). "Bold-pushes" are normally intended as shortcuts for jumping to specific screen like "chain options", "main menu", etc. Pushing the BACK knob generally close the current modal-screen or jumps to the previous screen in the workflow sequence.

Although some push actions depend of context (current screen), there are some actions that are global and will work from any screen:

  • Bold-Back: Audio Mixer
  • Long-Layer: Step Sequencer
  • Long-Back: Admin Menu
  • Long-Learn: All Notes Off
  • Long-Select: Power Off

Later versions of zynthian kits include 4 extra push buttons, labelled as S1 to S4. By default, these buttons are assigned to MIDI Program Change 1-4, but this can be easily changed from the webconf's Wiring Layout menu.

2 The Title Bar

Zynthian ui control status.png

The title bar has 2 functions:

  • Kind of Breadcrumb, normally showing the screen title or current chain information: MIDI channel, engine, bank & preset
  • Back-button, when using the touch-interface (Not very intuitive, but Zynthian-UI was not designed with touch-navigation in mind)

3 The Status Area

Status display.png

On the top-right corner is an area where some useful information is displayed in real time:

  • Audio peak-meter or CPU load-bar: horizontal bars indicating peak audio level or CPU load (configured in webconf)
  • Status Icons: indication of various states
Status Icons Legend
m MIDI-IN It's shown when MIDI messages are received. Underscore indicates system message such as MIDI clock.
XRun It's shown when there are XRuns. This may be accompanied by clicks and pops on audio output. This means the CPU can't process or transfer audio fast enough and you should consider disabling some CPU-hungry option (like VNC, headphones, etc.) or reducing the complexity of your chains.
Under-voltage Zynthian is working in a degraded state, with the CPU frequency capped to 600-800 MHz, trying to stabilize the system and avoid a system crash. You shouldn't see that icon and if you do so, you should consider looking for a better power source.
Over-temperature Zynthian is working in a degraded state, with the CPU frequency capped to 600-800 MHz, trying to stabilize the system and avoid a system crash. You shouldn't see that icon and if you do so, you should improve heat dissipation (using a heat sink, etc.)
Recording Audio / MIDI Audio or MIDI is being recorded.
Playing Audio / MIDI Audio or MIDI track is being played.

3.1 The Peak Meter

The Audio Peak meter is shown by default. The meter covers the range -50dBFS to 0dBFS, i.e. maximum permissible level at full scale (far right) down to 50dB below (far left):

  • The green segment covers the range -50dBFS to -10dBFS.
  • The yellow segment covers the range -10dBFS to -3dBFS.
  • The red segment covers the range -3dBFS to 0dBFS.

There are independent meters for left and right channels which monitor the system output, i.e. the mix of audio that feeds the Zynthian output. Level decays with a logarithmic rule, taking one second to decay to -200dBFS so will decay to -50dBFS (the displayed range) in about quarter of a second. Peaks are displayed instantly, i.e. the attack of the meter is immediate (*). The peak hold bar remains for two seconds or until a higher peak is reached.

(*) Meter is updated 5 times per second so there can be 200 ms delay in peak being displayed.

Alternately, the "CPU-load" bar can be enabled from webconf, replacing the Audio Peak meter. The CPU-load bar shows the CPU usage as calculated by the Jack Audio Server:

This is a running average of the time it takes to execute a full process cycle for all clients as a percentage of the real time available per cycle determined by the buffer size and sample rate.

4 The Zynthian UI Workflow

Zynthian workflow is based around chains of audio generators / processors feeding an audio summing mixer.

Zynthian Signal Flow.png

The main (home) screen is the Audio Mixer. This consists of several vertical strips, each representing an input chain and a strip representing the main mixbus (output) chain.

Navigation between views is performed by pressing buttons or using the touchscreen.

Navigation, default actions and common workflows are shown in the following graphs:

Most destructive changes, e.g. removing chains will request confirmation. Operations that take time to complete may show an animated Zynthian logo representing progress.

4.1 Stage and Multitimbral Modes

By default Zynthian starts in multitimbral mode. Each external MIDI controller will drive the chain that is assigned to that controller's MIDI channel, e.g. a chain assigned to MIDI channel 1 will listen for MIDI messages on MIDI channel 1 only*.

*MIDI Continuous Controllers are handled differently. See section on MIDI Learning & binding.

Stage Mode changes the behaviour of Zynthian so that all MIDI messages are sent to the currently selected chain. This allows multiple external MIDI controllers to drive one chain at a time.

5 The UI Screens

5.1 Audio Mixer

Audio mixer.png

The audio mixer view is the main or home screen. Bold press BACK will navigate to this screen from most locations within the Zynthian UI. It displays a mixer strip (or equivalent) for each configured chain plus a strip for the main mixbus. The quantity of strips displayed may be configured using webconf. If there are more chains than can be displayed, the screen can be scrolled horizontally by selecting a higher / lower chain or dragging the bottom legend strip.

Each audio chain will have the following mixer controls:

  • Fader adjusts the audio level
  • Balance / Pan adjusts the position or balance within the output stereo image
  • Mute toggles the audio feed to the main mixbus
  • Solo toggles the audio contribution to the solo mixbus*

* When solo is enabled on any chain, all other chains are muted. Solo can be enabled for multiple chains, each contributing to the output. Operating the main mixbus solo will disable solo on all chains.

Each audio chain also has a stereo audio level meter indicating peak programme level with peak hold bar. This may be disabled in admin menu or webconf to reduce CPU load if required.

Non-audio (MIDI only) chains show in the mixer view without any audio mixer controls.

Use the SELECT knob or tap on a strip to select a chain. Use the LAYER knob or drag the touchscreen to adjust the selected chain's fader. Use the BACK knob to adjust the selected chain's balance / pan. Use the LEARN/SHOT knob or drag the touchscreen to adjust the main mixbus fader. Short press LAYER to toggle solo of the selected chain. Short press BACK to toggle mute of the selected chain. Short press LEARN/SHOT to enter MIDI learn mode. Short press SELECT to access the chain's Control View. Bold press LAYER to access the main menu. Bold press LEARN/SHOT to access snapshots. Bold press SELECT to access the selected chain's options.

5.2 Main Menu

Main menu.png

This is the first screen you would see when you power on your zynthian for first time and no default or last-state snapshot has been saved yet. The Main Menu gives easy access to the Zynthian-UI's main features:

  • New Synth Chain adds a synthesis chain
  • New Audio Chain adds an audio processing / effect chain
  • New MIDI Chain adds a MIDI processing chain
  • New Generator Chain adds an audio generator chain
  • New Special Chain adds a non-standard or special chain
  • Snapshots manipulate snapshots
  • Sequencer access the step sequencer
  • MIDI Recorder access the standard MIDI file recorder / player
  • Clean All remove all chains and sequences
  • Audio Levels adjust hardware audio parameters
  • Admin access configuration menu
  • PANIC! All Notes OFF resets all MIDI engines

5.3 Chains

Chains are a key concept of the Zynthian. The first thing you do after powering on your Zynthian is probably to create a chain. (It does little without any chains.)

A chain is one or more interconnected engines capable of generating or processing audio or MIDI. Each chain is normally assigned to a MIDI channel. These engines are chained in the same order they are created, but you can change the order from the Chain Options menu. The first engine in a chain is the root and it determines the chain's type:

  • Synth Chain => Receives MIDI note-events and generate audio output
  • Audio Chain => Receives audio-input and generates audio-output
  • MIDI Chain => Receives MIDI-input and generates MIDI-output
  • Generator Chain => Generate audio output using an algorithm
  • Special Chain => Does not fit any other chain type, e.g. MOD-UI pedalboard, Pure Data patch, etc.

The root engine can't be re-arranged or changed. MIDI effects can be added to the start of a chain and audio effects can be added to the end of a chain. These can be arranged as serial or parallel paths.

All engines in a chain receive all the MIDI events on the assigned channel. Some special chains (MOD-UI) don't have an assigned MIDI channel and receive all MIDI channels.

When you select NEW Chain, you create a new chain, choosing its root engine (first engine of the chain), a free MIDI channel and if available, a preset from a bank of presets. You can create up to 16* chains, one per MIDI channel, each having an independent MIDI chain and audio effect chain.

* If Master Channel is enabled then only 15 chains can be created.

Having several chains on the same MIDI channel is not allowed. If you want two or more chains to play in unison (like being on the same MIDI channel), you can use the "Clone" feature, which allow you to bind several chains while keeping MIDI CCs and other MIDI messages (Program Change, Channel Pressure, etc.) independent.

5.4 Engine Selector

Zynthian ui engine list.png

When you create a new chain, you are asked which engine or plugin you want to use for it. An engine creates or processes MIDI or audio. A list of engines to choose from is displayed. They can be synthesizers, effects, generators or special engines, depending on the type of chain you are creating. When you select an element from the list, the Zynthian logo on the top-right will be animated while the engine is being started.

Some engines have special behavior regarding chains and MIDI channels:

  • setBfree: can create 1, 2 or 3 chains assigned to consecutive MIDI channels starting at the selected channel corresponding to the upper manual, lower manual and pedals sections of the Hammond B3 emulation.
  • Pianoteq: only one instance of Pianoteq may be created. (There is also a LV2 version which may be enabled and sevearl instances created.)
  • Aeolus: occupies MIDI channels 1, 2, 3 & 4, each one corresponding to the 3 manuals + 1 pedal of the Aeolus organ emulator. If all four MIDI channels are not available then Aeolus will be hidden from the list of available engines. You can change the MIDI channel assignments from the Aeolus native UI. If you want to use a different instrument definition, you will have to tweak the engine's code a little bit.
  • MOD-UI: only one MOD-UI chain is allowed and it will receive ALL MIDI channels. If you want to filter the messages by channel, you can do it within the MOD-UI patch. (There are plans for improving this behavior.)
  • PureData: only one PureData chain is allowed.

5.5 MIDI Channel selector

Zynthian ui midi channel.png

This screen is shown in various contexts:

  • After you have selected the engine for a new chain. Only unused channels are listed.
  • When you change the assigned MIDI channel from the Chain Options menu. Only unused channels are listed.
  • When you clone MIDI for a chain from the Chain Options menu.

Playing a note on a connected MIDI controller will cause the list to jump to the MIDI channel of the note played. This can assist with assigning chains to controllers.

5.6 Bank selector

Zynthian ui bank list.png

Presets (instruments, patches, sound designs, etc.) for engines may be organized into banks. Choose a bank to see the list of presets for the engine.

You can access an engine's banks by short press BACK from within its presets list.

Bold press SELECT or touch and hold a bank on the touchscreen will show the Bank Options menu. A bank may be renamed or deleted. Some engines do not allow banks to be manipulated in which case this will have no effect.

Short press BACK to return to the Control View without changing the engine's configuration.

5.7 Preset selector

Zynthian ui preset list.png

Once you have chosen a bank, the preset screen will be shown. Choose a preset to load the instrument / sound / patch and the Control View will be shown.

To change preset of an existing engine, navigate to its Control View then short press BACK to access the list of presets. Use the SELECT encoder to highlight the required preset and short press SELECT or tap on the required preset in the list on the touchscreen to select the preset. The engine will configure with the preset values and the Control View will be displayed.

Bold press SELECT or touch and hold a preset on the touchscreen will show the Preset Options menu. A preset may be added to or removed from a list of favorites, renamed or deleted. Some engines do not allow presets to be manipulated and will only show the Favourite option. (Saving presets is performed in the chain options menu described later.)

If the preload with note-on feature is enabled in the admin menu or webconf, you can audition the presets by playing notes. When you do so, the highlighted preset will be pre-loaded without pressing SELECT. N.B. Some engines may be slow to load presets in which case it may be necessary to play the note more than once to hear the new preset sound.

You can return to the bank screen, without selecting any preset, by short press BACK. The previously selected instrument will be restored, e.g. if a preset has been pre-loaded (auditioned).

Press bold SELECT to manipulate the preset including adding to your favorites. The favorites list can be shown by short press LEARN/SHOT in the Bank or Preset View.

Not all engines support presets. If no presets are configured then this screen is not shown.

5.8 Control View

Zynthian ui instrument control 01.png

The Control View shows the controls available for each engine within a chain. It is shown after adding a chain, adding an engine to a chain or by short press SELECT or tapping the bottom legend strip in the mixer view. Your instrument is now enabled and playable and you can modify its parameters.

The controls are shown in groups of four (or fewer) on several pages. Each hardware knob controls a parameter displayed in the control view or the control may be dragged up and down on the touchscreen. Controls may toggle between two values, e.g. on / off, lists of values, e.g. sine, square, triangle or continuously adjustable values, e.g. 0%..100%. If there are a lot of possible values the hardware knobs will accelerate progress if rotated fast, e.g. stepping by one value when turned slowly and stepping by 10 values when rotated fast. This allows fine and coarse selection of a parameter from a single knob.

Zynthian ui instrument control 03.png

There is a list that shows the pages of controls available. To change page, short press SELECT - the list of pages turns grey, rotate SELECT to highlight the required page then short press again to select the page. If there are fewer than three pages then short press SELECT will step through each page. Alternatively, tap the required page on the touchscreen. When a page is selected its controls will be shown. Depending on the configuration, some pages may have fewer than four controls and some engines have no adjustable parameters in which case there will be no control pages.

The pages for the controls for each engine within a chain are shown separated by a title indicating to which engine subsequent pages belong.


Some engines have a graphical representation of controls / monitoring available. This will be shown in place of the list of pages. Pages can still be selected in the same manner as described above except the list is not available for touchscreens.

Tapping (and not dragging) one of the four controls on a touchscreen will simulate pressing its associated knob, i.e. tap on the bottom right control to show the list of pages.

5.9 Chain Options

Chain options.png

Bold press SELECT when in the Mixer View or Control View will show the Chain Options menu. Manipulation of the chain is possible:

  • Save Preset will allow saving of a engine's configuration as a preset that may later be selected from the preset list. This is only available if the engine supports manipulation of presets. If a chain has several engines then a list of engines will be displayed before naming the preset.
  • Note Range & Transpose allows configuration of the key-range and transpose by octaves or semitones applied to the chain.
  • Clone MIDI to... allows MIDI events targetted at this chain to be sent to other MIDI channels. By default only note-on, note-off, pitchbend and key-pressure messages are cloned. CC, channel-pressure, program change, etc. can be enabled by bold SELECT on a channel within the Clone menu
  • Audio Options allows mono and phase reverse to be toggled for the audio mixer strip. If enabled in webconf this menu also allows the chain to be primed to be recorded as a separate channel in the audio recorder. This option is not available for MIDI Chains.
  • Audio Output allows manipulation of the routing of the chain's audio outputs. This allows complex audio routing to be performed. If this is not sufficient, try MOD-UI engine with the MOD-UI web GUI. This option is not available for MIDI chains.
  • Audio Capture allows manipulation of the routing of the chain's audio inputs. This option is only available on audio chains.
  • MIDI Routing => Select the destiny of the chain's MIDI output. This option is only available on MIDI-FX chains.
  • MIDI Channel allows changing of the chain's MIDI Channel. Only MIDI channels not assigned to other chains are available.
  • Replace Synth allows a synth engine to be replaced by another synth engine.
  • Remove Chain will remove the chain.
  • Add MIDI-FX adds a MIDI effect to the chain. The MIDI effect will be inserted before synth engines.
  • Remove All MIDI-FX removes all MIDI effects from the chain
  • The list of MIDI effects in the chain is displayed with arrows representing their relative position
  • Add Audio-FX adds an audio effect to the end of the chain. This option is not available for MIDI Chains.
  • Remove All Audio-FX removes all audio effects from the chain.
  • The list of audio effects in the chain is displayed with arrows representing their relative position. MIDI and audio effects can be added in series or parallel to the last corresponding (MIDI or audio) effect in the chain.

Zynthian ui layer effect options.png

Short press SELECT or tapping on an effect in the list will allow manipulation of the effect:

  • Presets shows list of available presets for the effect
  • Replace offers the list of available effects to replace the effect in the chain
  • Move up chain moves the effect closer to the start of the chain. Only available if space in front of effect.
  • Move down chain moves the effect closer to the end of the chain. Only available if space behind effect.
  • Remove removes the effect from the chain

Note that not all these options will be available all the time. For instance, if there is only one effect in the chain, "Move" options won't be shown. Same if the FX has not presets, etc.

5.10 Note Range & Transpose

Range transpose.png

The MIDI sent to a chain may be transposed +/-5 octaves and +/-12 semitones. The range of MIDI notes that it will respond to can be limited. The Mote Range & Transpose View has controller knobs to adjust the octave transpose, semitone transpose and lower & upper key range limits. The key range is displayed on an onscreen piano keyboard that can be dragged with the touchscreen to set the range.

Short press LEARN will enable MIDI learning. MIDI notes will set the limits of the note range.

5.11 XY-Controller

Zynthian ui xy select.png

From the Control View, simultaneously bold press two knobs to enter the XY-select mode.

The two controllers will be green, indicating they are pre-selected for XY-control. You can change the pre-selection by rotating any knob. (The knob must be rotated through several values before it will be detected.) Use the SELECT switch to navigate through the controller pages to select different controllers if required.

Zynthian ui xy controller.png

After selecting the two required parameters, touch the display to enter the XY-control pad and use the touchscreen ala Kaoss-Pad.

Short press BACK to return to XY-select and BACK again to return to the Control View.

5.12 Load / Save Snapshot

Zynthian ui snapshot load.png
Zynthian ui snapshot save.png

Snapshots are used for saving and restoring the status of Zynthian. A snapshot includes the full state, including chains, effects, parameter values, MIDI-learning, etc.

Bold press SNAPSHOT to access the Snapshot View. The first option allows the current state to be saves as a new snapshot. An on-screen keyboard will allow naming the new snapshot.

Highlighting a snapshot in the list then short press SELECT or tap on list with touchscreen shows options for the snapshot:

  • Load replaces the current configuration with the saved snapshot
  • Load Chainsreplaces the chains with those in the saved snapshot
  • Load Sequences replaces the step sequencer with the sequences in the saved snapshot
  • Save replaces the saved snapshot with the current configuration
  • Rename shows an on-screen keyboard to rename the selected snapshot
  • Set Program assigns a MIDI Program Change to the snapshot
  • Delete removes the snapshot

It is possible to recall snapshots via MIDI Program Change. New snapshots are assigned the next available MIDI Program Change. This number prefixes the snapshot name in the list.

5.12.1 Snapshot Banks

By default, snapshots are stored as a single list and bank-related stuff is not shown by Zynthian-UI. If you want to use banks for organizing your snapshots, you simply create a second bank using the webconf tool and the hidden bank functionality will be enabled.

When using snapshot banks, if you want to go up one level (from snapshot list to bank list), you must use the ".." entry. The back button will close the snapshot screen.

5.12.2 Default Snapshot

Zynthian can load a default snapshot at startup. This snapshot should be called, "Default Snapshot".

5.12.3 Restore Last State

If "Restore last state on startup" option is enabled on webconf (it's enabled by default), then the state will be saved when powering off (using long-click select or from Admin Menu) and restored on next boot. This option has priority over the "Default Snapshot".

5.13 MIDI-learning / binding

MIDI-learning allows you to bind MIDI events to Zynthian-UI actions. There are 2 types of MIDI events you can learn:

  • MIDI CC binds MIDI continuous controllers to adjust engine parameters
  • MIDI PC binds MIDI program change to recall snapshots

5.13.1 MIDI CC

Zynthian ui midi cc learn 01.png
Zynthian ui midi cc learn 02.png

You can map any parameter in the Zynthian UI to a CC knob / slider on your external MIDI controller. It is intended to extend this feature to other MIDI messages but currently only CC messages are supported. Until then, MIDI-filter rules can be used instead.

Learning a MIDI-CC is quite easy:

1. From the Control View, short press LEARN. The CC MIDI-learn view is shown. It’s identical to the Control screen except that the controllers show a green “??”.

2. Move a zynthian controller. The “??” changes to yellow. The other three will go back to normal state.

3. Finally, move a knob / fader in your MIDI keyboard / controller and the binding is done. The new CC number should appear at the bottom of the learned controller, replacing the "??".

To unbind a MIDI learned CC binding:

1. From the Control View, short press SNAPSHOT. The CC MIDI-learn view is shown. 2. Bold press LEARN to unlearn all controls or adjust a control to select it for MIDI learn 3. Bold press LEARN to unlearn the selected controller

MIDI learn with a touchscreen is performed by swiping right on a control to show the yellow "??" then sending the MIDI CC. MIDI unlearn with a touchscreen is performed by swiping left on a control then selecting the option from the menu to unleanr the control or all controls.

Unlearn operations require confirmation.

Of course, MIDI-learning configuration, including CC mappings, is stored and restored with snapshots.

Technical Note: MIDI-CC learning works with all engines. It uses the engine’s native MIDI-learning capabilities if available otherwise Zynthian’s MIDI-filter mappings are used. To be more explicit, native MIDI-learning is used for MOD-UI and ZynAddSubFX OSC parameters. All the other parameters are managed by Zynthian’s MIDI-filter mapping.

5.13.2 MIDI Program Change & ZS3 (SubSnapShots)

Zynthian ui midi zs3 learn.png

A ZS3 (SubSnapShot) saves the zynthian state in the context of the current snapshot. When recalled, the saved state is restored. The chains are defined in the snapshot but their selected preset, parameters and mixer settings are defined in the ZS3. Snapshots can be slow to load as each engine needs to be started. ZS3 is much faster as the presets are restored and parameters adjusted. Some ZS3 may be slower due to the way some engines load presets, e.g. changing instrument within Pianoteq is slower than recalling a preset of the same instrument.

ZS3s may be loaded by MIDI Program Change.

The idea behind this feature is to have a fast preset-change mechanism that can be used on stage. In combination with the “Stage Mode” feature, it turns Zynthian into a “Stage-Beast”. You can prepare a snapshot for the full performance, and use ZS3s for fast changes between songs or even within a song.

Creating a SubSnapShot is obscenely easy:

0. Ensure "Program Change ZS3" is enabled in the admin menu.

1. From the Control View, short press SNAPSHOT to enter MIDI control learn mode then short press SNAPSHOT again. You will see the current list of ZS3s (initially empty) and a message: “Waiting for Program Change…”

2. Send a “MIDI Program Change” from your keyboard / controller and the ZS3 will be stored in memory, associated with the Program Number you pushed on your keyboard / controller. Alternatively select "Save as new ZS3" from the menu to save ZS3 without MIDI Program Change assigned.

You can recall the stored ZS3 by sending the same MIDI Program Change or selecting it from the ZS3 list. ZS3s are saved and restored within snapshots so remember to save the snapshot.

Bold press SELECT to manipulate ZS3:

  • Rename shows an on-screen keyboard to rename the ZS3
  • Update replaces the ZS3 with the current configuration
  • Delete removes the ZS3

ZS3 behavior depends of the mode your zynthian is working on:

  1. TODO: Validate this behaviour:
  • Stage Mode: ZS3 list shows all the ZS3s stored, no matter the chain. Recalling a ZS3 changes the active chain, so the chain associated with the recalled ZS3 will receive *ALL* the MIDI input. Only 127 ZS3s can be stored.
  • Multi-timbral Mode: ZS3 list shows the ZS3 of the currently active chain only. Recalling a ZS3 changes the active chain, but every chain receives MIDI input from its channel. You can use several keyboards on different channels and store 127 ZS3s by MIDI channel.

5.14 MIDI Recording and Playback

Zynthian ui midi recorder.png

5.14.1 Overview

Zynthian provides a tool to record and playback MIDI standard file format (SMF), using the internal SD-card or an USB memory stick for file storage.

Access the MIDI recorder / playback tool from the Main Menu

WARNING! Using the internal SD card to store the captured files will increase the risk of corruption. It is recommended to use an USB memory stick instead.

5.14.2 Recording

1. Press "Start Recording" to start a new capture.

2. A red circle "record" symbol appears in the status area, indicating that a recording is active.

3. Press "Stop Recording" for finishing the capture. The red circle will disappear and the recorded file will be added to the list. The filename is generated automatically from the current chain configuration. The prefix "SDC" or "USB" indicates where the file is stored and the duration in minutes and seconds is shown.

Files are saved to USB storage if connected otherwise they are saved to internal SD card.

5.14.3 Playing

You can play files by simply selecting and clicking the file. A green triangle "play" symbol will be displayed in the UI status area. To loop the file, enable "Loop Play" before or during playback. Disable "Loop Play" to stop playback at end of track.

NOTE: Simultaneous record and playback is possible.

During playback a BPM control will be shown to adjust the transport speed. The same transport is used for step sequencer so tempo adjustments afect both SMF and step sequence playback.

5.14.4 Deleting

Bold press SELECT will offer to delete the selected file.

5.15 Audio Recording and Playback

Audio player.png

Zynthian has an audio recorder that will, by default record the stereo output of the audio mixer's main mixbus output (post effects, post fader).

1. From the Mixer View, highlight the main mixbus (far right strip) and bold press Select or tap and hold the main mixbus legend strip on the touchscreen. The Chain Options menu is shown. Select the option "Start Audio Recording".

2. A red circle "record" symbol appears in the status area, indicating that a recording is active.

3. Within the main mixbus Chain Options menu select "Stop Audio Recording" for finishing the capture. The red circle will disappear.

To playback audio:

1. From Main Menu select "New Special Chain"

2. Select "Audio File Player"

3. Select a spare MIDI channel

4. Select the audio recording from the preset list

The audio player shows transport and other configuration controls and draws a waveform image. Start playback by changing the transport from "stopped" to "playing". Playback position is indicated by a vertical line on the waveform and the "position" controller value (in seconds). Playback position can be adjusted. One-shot or loop playback is available. Selection of which channel in the audio file (or a mix of all odd / even channels) is sent to each output, e.g. for a 4 track audio file you may select any of the four tracks to feed left or right output or select mixdown to mix tracks 1 & 3 to left output and 2 & 4 to right output. There is also a gain control.

The audio recorder's preset list contains all the files within the selected directory. The bank list contains the internal storage location (SDC) and its immediate subdirectories and any attached USB storage and its immediate subdirectories.

The audio player also has a controller to control the audio recorder. Each time the "record" controller is asserted a new recording is started which may be ended by resetting the "record" controller. This is the same audio recorder accessible from the mixer's main mixbus options menu.

There is a configuration in webconf to enable multitrack audio recording. If this is enabled then there is an extra option in the audio options within each chain's options menu to toggle "Recording Primed". With none of these enabled, the audio recorder will record will be a stereo file from the main mixbus output (post effects, post fader). If any are enabled then a multitrack recording is made with a pair of tracks for each enabled chain. The main mixbus may also be enabled to add a stereo mix pair of tracks to the multitrack recording.

Files are recorded as a floating point WAV (or WAVX for multitrack recordings) at the Zynthian's native samplerate (default is 44100 samples per second) and named with the current date and time. Recordings are made to the root directory of any attached USB storage or internal SD card if no external storage is attached.

5.15.1 Managing recordings from your computer

Zynthian webconf captures 02.png

Audio & MIDI recordings can be managed from your computer by accessing the webconf's captures section. From this section you can:

  • rename recordings
  • delete recordings
  • convert audio recordings to .ogg format, e.g. for upload to websites.
  • download recordings to your computer
  • playback the audio recordings in your browser. If .wav files doesn't work in your browser, try converting to ogg.

It is a good idea to rename your recordings so they can be easily identified.

5.16 Audio Levels

Zynthian ui mixer control.png

The Audio Levels view is accessed from the Main Menu and allows adjustment of the soundcard's input & output levels and other audio-hardware related options. Technically speaking, it's an interface to the ALSA (Audio Linux Sound Architecture) mixer.

You can configure the Audio Level controllers from the webconf's hardware->audio menu. Simply click the + button on the "Mixer Controls" text area.

5.17 Step Sequencer

Zynthian has a step sequencer which provides methods to create patterns and arrange them into sequences.

The step sequencer may be accessed from the main screen or by long press LAYER.

  • There may be up to 999 patterns, each with as many simultaneous notes (polphonic) as required over a set of steps and beats that are configurable for each pattern.
  • Patterns are arranged into tracks within sequences.
  • Sequences may be configured to loop or play once and may be grouped so that starting one sequence stops another. Sequences may start and stop at the start of each bar.
  • Note entry can be performed from the Zynthian user interface or using an external MIDI controller.
  • Sequences can be started and stopped from the Zynthian user interface or using an external MIDI controller.

These are three main views:

Zynpad 4x4 playing starting.png

Grid of pads to launch sequences


Track / timeline editor for complex manipulation of sequences

Zynseq patterneditor notevelocity.png

Pattern Editor
Manipulation of individual events within patterns

Using ZynSeq is a detailed tutorial on the use of the step sequencer.

5.18 Admin Menu

Zynthian ui admin.png
Zynthian ui admin 02.png

The Admin menu is accessed from the Main Menu and gives access to some configuration options (most of them also accessible from the webconf tool). It also includes basic testing options for audio and MIDI and indication of network configuration.

5.18.1 Touchscreen Calibration

Zynthian supports touchscreen operation for most operations. To ensure good alignment of the touch interface there is a calibration screen that is accessed from the Admin menu.

Touchscreen calibration 1.png

When the screen opens it shows a target crosshair in the center of the screen and a countdown timer. If the timer expires the screen will close without applying any calibration. Touch the target to detect the screen and begin calibration.

Touchscreen calibration 2.png

The name of the detected display is shown at the bottom of the screen. Further targets will appear. Touch the screen, drag to centre of target and release.

When the screen is pressed the target will show red. When released the measurement is taken and the next crosshair target appears white.

Touchscreen calibration 3.png

After releasing the last target, calibration is applied and the screen closes. Touch is ignored if too close to previous touch.

Use BACK button or wait for timeout to cancel calibration. Timer is reset to 15s when screen is touched and paused until released. The purpose of the timeout is to avoid users of Zynthians without back button being stuck in calibration screen view.


The resistive touchscreen works better with a stylus. Finger is too coarse. It's strongly recommended to run the calibration using a stylus.

6 Touch Screen UI

Zynthian ui top bar.png

You can navigate and control the Zynthian UI without knobs / encoders / switches at all, using only the touchscreen (or mouse).

Short tapping the top-bar acts as a back button. Bold tap will show an appropriate menu or return to the mixer view.

You can "emulate" the switches by tapping (not dragging) the controller widgets (squares in the 4 corners of the screen) where these controllers are presented. (Not all screens have controllers. Some have just one. The zynthian logo (top-right) may be tapped to emulate LEARN/SNAP). There are short, bold and long actions, the same behavior as the rotary encoders workflow.

You can change the controller values by "sliding" up / down over the widgets. (See the green arrow in the figure) This is the same as turning the knob. If you are using a mouse, the mouse wheel also can be used to change the controller value and acts to adjust parameters in some other views.

There is a configuration in webconf UI Options to "Enable Onscreen Buttons". With this enabled some touchscreen helper functions are enabled including the display of buttons where required. This is kept to a minimum to avoid interfering with user workflow. Most operations are possible without the onscreen buttons so they only appear when required, e.g. within the Control View. It is recommended to enable this option when using the touchscreen as your primary user interface.

7 CUIA: Callable UI Actions

The Zynthian UI can be controlled remotely using a set of commands called CUIA: Callable UI Actions. These CUIA are available on several interfaces: Key Bindings, MIDI, OSC, etc.

7.1 KeyBindings: Controlling the UI with a computer keyboard

The user interface may be driven using a USB keyboard, e.g. QWERTY, Dvorak, etc. Key assignment and their combinations can be modified with the webconf tool. The default key bindings are:

Keyboard shortcuts
Action Modifier Key
ALL_OFF Ctrl Space
BACK_DOWN CapsLock Down
BACK_UP CapsLock Up
REBOOT Ctrl Home
SWITCH_BACK_BOLD Shift BackSpace, Escape, Left
SWITCH_BACK_LONG Ctrl BackSpace, Escape, Left
SWITCH_BACK_SHORT None BackSpace, Escape, Left
SWITCH_SELECT_BOLD Shift Return, Right

7.2 Controlling the UI with MIDI messages

CUIA may be triggered by MIDI messages on the Master Channel (disabled by default, but configurable with the webconf tool), specifically, note-on messages (0x9) are used so you can use a MIDI keyboard for controlling the Zynthian UI. For instance, to Power Off the zynthian, you send this message:

0x9F  (Channel 16 Note ON) 
0x00  (Note code for POWER_OFF as below)
0x00  (Velocity / parameter)

or play the C-1 key, if your keyboard has it.

Note that you can use the velocity for sending the CUIA parameter when it's required by the action (SELECT & LAYER_CONTROL).

This is the full map of CUIA to MIDI notes:

Num   CUIA                       Note         System Real-Time
0     POWER_OFF                  C-1
1     REBOOT                     C#-1
2     RESTART_UI                 D-1
3     RELOAD_MIDI_CONFIG         D#-1
4     RELOAD_KEY_BINDING         E-1
5     LAST_STATE_ACTION          F-1
10    ALL_NOTES_OFF              A#-1
11    ALL_SOUNDS_OFF             B-1
12    ALL_OFF                    C0
24    START_AUDIO_RECORD         C1
25    STOP_AUDIO_RECORD          C#1
26    TOGGLE_AUDIO_PLAY          D1
27    START_AUDIO_PLAY           D#1
28    STOP_AUDIO_PLAY            E1
35    TOGGLE_MIDI_RECORD         B1
36    START_MIDI_RECORD          C2
37    STOP_MIDI_RECORD           C#2
38    TOGGLE_MIDI_PLAY           D2
39    START_MIDI_PLAY            D#2           Start / Continue: 0xFA, 0xFB
40    STOP_MIDI_PLAY             E2            Stop: 0xFC
51    SELECT                     D#3
52    SELECT_UP                  E3
53    SELECT_DOWN                F3
54    BACK_UP                    F#3
55    BACK_DOWN                  G3
56    LAYER_UP                   G#3
57    LAYER_DOWN                 A3
58    SNAPSHOT_UP                A#3
59    SNAPSHOT_DOWN              B3
64    SWITCH_BACK_SHORT          E4
63    SWITCH_BACK_BOLD           D#4
62    SWITCH_BACK_LONG           D4
66    SWITCH_SELECT_BOLD         F#4
67    SWITCH_SELECT_LONG         G4
60    SWITCH_LAYER_SHORT         C4
61    SWITCH_LAYER_BOLD          C#4
59    SWITCH_LAYER_LONG          B3
80    SCREEN_MAIN                G#5
81    SCREEN_LAYER               A5 
82    SCREEN_BANK                A#5
83    SCREEN_PRESET              B5
84    SCREEN_CONTROL             C6
90    MODAL_SNAPSHOT_LOAD        F#6
94    MODAL_ALSA_MIXER           A#6
95    MODAL_STEPSEQ              B6
96    MODAL_ADMIN                C7
100   LAYER_CONTROL              E7



7.3 Controlling the UI with OSC messages

CUIA may be triggered using OSC on UDP port 1370, with the path prefix "/cuia", e.g. "/cuia/reboot". Take a look at "Calling CUIA with OSC".