Zynthian UI User's Guide - Vangelis

V5 | V4 | Touch

1 Introduction

Welcome to the Zynthian project, an open source hardware and software platform for musical explorers. Zynthian is a capable platform that can serve a range of musical needs from practice tool to sound design to live performance rig and more. You can find out about some of the features on the front page and here.

The hardware includes the various official boxes from v1 through to the current (as of May 2026) V5.1. (See how some early versions evolved). On the software side, Zynthian Oram is the most recent version of zynthianOS, first released in September 2024 but this guide is for the development version that is prone to unannounced changes.

1.1 How to get started

Just to remind those who are new here, there are three ways you can get started with Zynthian:

1. You can purchase an official kit for the most complete experience
2. If you would like to try Zynthian at the lowest cost, you can grab a Raspberry Pi and a few peripherals and install a basic setup (best with Pi 4b and above)
3. If you're more adventurous you can build yourself an unofficial DIY kit or try DIY your own way

1.2 Choose your own adventure

This user guide describes how to start with zynthian but does not delve into much detail. There is built-in help within the zynthian that provides contextural help. Access this at any time by bold-press ALTlong-press Knob 1.

You can select the documentation for different hardware types (V5 or V4) with the selector in the top right of the page ↑

If you are using V1-V3 then select V4. If you are using touchscreen only, use V5 with "V5 buttons" enabled. If you have a custom build, then select the version that closest matches your hardware. If your hardware uses features from different official kits then you may wish to check the documentation for each hardware type.

It is strongly recommended that you read section 2 on core concepts which explains many aspects of how zynthian works. This provides essential knowledge to improve your understanding and ability to use zynthian. This guide includes details of how to navigate the user interface and some explanation of common workflows.

1.3 Quick Start

Near the bottom of the guide are links to Learning Pills: short video tutorials that show and describe various workflows. These are short, easily digestible snippets of information that can get you started quickly.

As said above, you really should read section 2 on basic concepts to understand basic principals but here is a quick guide to get some sound out of zynthian.

Setup

• Plug audio outputs to amplification / headphones.
• Plug in audio / MIDI inputs. This may include USB MIDI devices.
• Connect power - zynthian should start up and after about 10 seconds, show the mixer view.
• Zynthian remembers its last state and there may be no chains (instruments, audio paths, etc.) shown.

(Optional) Clear the state to start with an empty mixer:

• Press OPT|ADMIN button to show Chain Manager view.
• Tap touch screen "Main" box (or use arrow and SEL|YES buttons) to show the main chain options menu.
• Use arrow and SEL|YES buttons to select "Remove All".
• Confirm operation.

• Rotate encoder 4 to highlight "Main" chain.
• Bold press (press then release after 1s) encoder 4 to show Chain Manager view.
• Rotate encoder 3 to highlight "Main" box then short press (press the release within 0.5s) encoder 4 to show main chian options menu.
• Rotate encoder 4 to highlight "Remove All" then short press encoder 4 to select the menu option.
• Confirm operation.

• Tap topbar (left half of black title bar at top of screen) to show Chain Manager view
• Tap touch screen "Main" box to show the main chain options menu.
• Tap "Remove All" option.
• Confirm operation.

Add an instrument chain. In Chain Manager view

• Show the main chain options menu.
• Select "Insert new chain"
• Select "Instrument"
• Use left/right arrow buttons to select an instrument category.Use encoder 3 to select an instrument category.Swipe left/right to select an instrument category.
• Select an instrument from the list.
• Select a MIDI channel
• Select a preset bank (some instruments do not have banks so will not show this menu)
• Select a preset (some instruments do not have presets so will not show this menu)
• The "Control View" for the chain is shown.
• Play the sound from the MIDI controller connected.

For audio processing, follow a similar procedure but select "Audio Input" instead of "Instrument".

1.4 The Zynthian Project

Zynthian is truly a community effort supported by core developers and the wider group of music makers who contribute in various ways whether by questions, testing (making music & experimentation), contributing code or updating this very wiki site.

With that in mind, please know this guide is a living document, subject to frequent updates. Some sections may be incomplete and the whole document will improve during the lifetime of Zynthian Vangelis. If you want to get involved in documentation, visit the forum and request permission to edit the wiki.

2 Basic concepts

2.1 Processors & Chains

The fundamental building block of zynthian's sound architecture is the processor. A processor generates or manipulates audio or MIDI signals. Zynthian includes over 1000 processors to choose from.

Processors are grouped together and interconnected within chains. Chains are a key concept in Zynthian. The first thing you will do after powering-on your zynthian for first time, once you stop celebrating your success, is creating a chain and adding some processors. It does little without any chains!

Processors may be positioned within the chain in series or in parallel with other processors. The quantity of series or parallel processors is only limited by available processing power and there is no limit to the quantity of chains that may be added. Audio signals from chains by default feed a stereo mixer with typical mixer strip controls: fader, balance, mute, solo, phase reverse, etc. Audio processors may be positioned pre-fader or post-fader. (Note that zynthian treats most audio as stereo.)

The audio and MIDI signals are routed between physical inputs, chain inputs, chain outputs, physical outputs and processor sidechain inputs. This provides a lot of flexibility whilst maintaining a simple, chain-based approach to signal routing.

2.1.1 Type of chains

When you create a chain, you must choose a type for it:

• Synth Chain => Receives MIDI note-events and generates audio output. It must have a synth processor.
• Audio Chain => Receives audio-input and generates audio-output. It only has audio-FX processors.
• MIDI Chain => Receives MIDI-input and generates MIDI-output. It only has MIDI processors.
• MIDI + Audio Chain => Receives MIDI + Audio input and generates MIDI + Audio output. It has MIDI and audio-FX processors.
• Generator Chain => Generates audio output using an algorithm. The first processor is an audio generator.
• Special Chain => It can contain special processors, a MOD-UI pedalboard or a Pure Data patch. It can process audio and MIDI.

The chain's type can't be changed after creating the chain. Processors can be added, removed and positioned within the chain.

Synth and MIDI chains have a MIDI channel assigned. MIDI channels are not exclusive, so you can assign the same MIDI channel to several chains.

In MIDI+Audio chains, all audio processors in the chain receive all the MIDI events in the assigned channel. This is very convenient for some processors, like vocoder and auto-tune ones.

MIDI chains can be configured to receive all MIDI channels. This is specially useful when using zynthian as a MIDI router.

2.1.2 Type of processors

There are five fundamental types of processor

• Synth => Receives MIDI events and generates audio output.
• MIDI => Receives MIDI events and generates MIDI output.
• Audio => Receives audio input and generates audio output.
• Generator => Generates audio output and has no input.
• Special => Receives MIDI events and audio input and generates MIDI output and audio output.

Each type of processor is categorised to ease user selection, e.g. Synths have categories: Synth, Sampler, Piano, Organ, Acoustic & Percussion.

Each processor has parameters that may be controlled with zynthian knobs or mapped to MIDI CC messages. Processors may have presets that may be arranged in banks.

2.2 Signal workflow

As introduced above, Zynthian's signal workflow is based around chains of audio & MIDI processors that feed an audio summing mixer and MIDI outputs. This diagram gives an overview of signal paths which may help in understanding the flow of audio and MIDI signals.

2.2.1 Last state snapshot

When zynthian starts, it always tries to restore the last state saved as this snapshot. It always tries to save the current state before performing some operations, like:

• power-off
• restart
• update
• clean all
• etc.

For convenience, the last state snapshot can also be saved or restored manually.

3 The physical interface

3.1 Description

The V5 physical user interface is composed of:

• 4 infinite knobs (rotary encoders) with push switches
• 5x4 silicone push button grid with RGB-LED feedback
• 5 inch display with capacitive touch

The 20 silicone push buttons and the 4 knobs with switches are the primary user input mechanism to navigate the UI:

• access the different views
• select options on menus and lists
• modify parameters

Each push button is engraved with a text legend or icon and backlit with RGB LED that gives status feedback. The knobs are numbered from top to bottom, so the top one is knob#1 and the bottom one is knob#4. We will refer to knobs in this way throughout this guide.

The V4 physical user interface is composed of:

• 4 infinite knobs (rotary encoders) with push switches
• 4 silicone push buttons: These buttons doesn't exist in older V1-V3 kit versions.
• 3,5 inch display with resistive touch

The four knobs with switches are the primary user input mechanism to navigate the UI:

• access the different views
• select options on menus and lists
• modify parameters

Zynthian can be operated entriely using touch or mouse if touch navigation is enabled in webconf. A minimum display size of 5 inches and capacitive touch is recommended when this is the primary user input method. If using a smaller or resistive touch then a stylus is highly recommended.

Zynthian UI can also be run head-less, accessed remotely with VNC.

3.2 User interaction

Users interact with the system by pressing the silicone buttons or knob-switches or rotating the knobs. Touch can be used too for most operations and some interactions are only available from the touch interface, like the X-Y control ala kaos pad. Users interact with the system by touching or clicking the display elements and performing touch or mouse gestures, like drag, horizontal or vertical swipes, pinch-zoom, etc. The topbar and status area also act as touch zones. See sections below for details. If a mouse is used, its wheel can be used to scroll various parts of the UI. User actions normally produce some feedback in the display. Also, the RBG LEDs give feedback and status info.

3.3 Types of action

User actions can be divided in 3 groups:

• Press: You can press buttons, knob-switches or display widgets. There are 3 types of press actions, depending on how long you hold down before releasing.
• Knob rotation: You can rotate knobs, of course ;-)
• Touch gestures with display's touch surface or mouse: Drag, swipe, pitch-zoom, 2-fingers drag, etc.

User actions can be divided in 2 groups:

• Press: You can tap display widgets. There are 3 types of tap (press) actions, depending on how long you hold down before releasing.
• Touch gestures with display's touch surface or mouse: Drag, swipe, pitch-zoom, 2-fingers drag, etc.

These icons are used throughout this guide to indicate UI actions :

UI actions
	Short Press	Press and release in less than 0.3 seconds. Normally used to select an item, check/uncheck an option or trigger the default action for the item.
	Bold Press	Press and hold for longer than 0.3 seconds then release before 2 seconds. Normally used to open options menu, access extra details or edit the item.
	Long Press	Press and hold for longer than 2 seconds. Long-action triggers before release. Used for important functions that are not used very often.
	Knob Rotate	Rotate the knob. Used to change parameter values or move across a list or grid.

UI actions
	Short Press	Press and release in less than 0.3 seconds. Normally used to select an item, check/uncheck an option or trigger the default action for the item.
	Bold Press	Press and hold for longer than 0.3 seconds then release before 2 seconds. Normally used to open options menu, access extra details or edit the item.
	Long Press	Press and hold for longer than 2 seconds. Long-action triggers before release. Used for important functions that are not used very often.
Horizontal Drag	Horizontal Drag	Press and drag horizontally. Must release before you can drag vertically. If still moving when released, a swipe action may occur.
Vertical Drag	Vertical Drag	Press and drag vertically. Must release before you can drag horizontally. If still moving when released, a swipe actin may occur.
2 Finger Horizontal Drag	2 Finger Horizontal Drag	Press with 2 fingers and drag horizontally. Must release before you can drag vertically. If still moving when released, a swipe actin may occur.
2 Finger Vertical Drag	2 Finger Vertical Drag	Press with 2 fingers and drag vertically. Must release before you can drag horizontally. If still moving when released, a swipe actin may occur.
Horizontal Pinch	Horizontal Pinch	Press with two fingers then drag horzontally towards or away from each other. Must release before you can pinch vertically.
Vertical Pinch	Vertical Pinch	Press with two fingers then drag vertically towards or away from each other. Must release before you can pinch horizontally.

Note:

You can change the timings of the short/bold/long press actions from the webconf's UI options tab. Not all controls have actions assigned to all three press types. You can modify the assigned actions from the webconf tool, accessing the advanced options in the wiring layout section.

3.4 Using the knobs

The V5 knobs behave quite differently from the V1-V4 knobs. Because of the 20 silicone buttons, there is no need to use the knobs' switches to navigate the UI which now is best achieved with the press buttons, so when appropriate, knobs' switches have been mapped to drive the MIDI learning functionality, which is quite intuitive. The knobs are numbered from top to bottom, so the top one is knob#1 and the bottom one is knob#4. We will refer knobs in this way throughout this guide.

General rule

Although a knob's behavior is contextual, there is a kind of pattern that can serve as a general rule and applies to many views:

• Knob#4 is the select knob.
  • rotate to browse lists and move the cursor horizontally in grids.
  • short-press to select items, like the SEL button.
  • bold-press to open contextual options, like the OPT button.
• Knob#3
  • rotate to move the cursor vertically in grids.

Note:

The MAIN Volume is always available with one click. Press MIX button and rotate Knob#3 to change the MAIN volume.

The V4 knobs (rotaries & switches) are the primary mechanism to navigate the UI. Its functionality is contextual, specially rotate, short and bold-press actions. Long press actions are always global. The knobs' names used in this guide are the names printed in the official V4 aluminum case, but you could find some section using the numbered notation, from top to bottom and left to right:

• layer => knob#1
• back => knob#2
• learn/shot => knob#3
• select => knob#4

General rule

Although a knob's behavior is contextual, there is a kind of pattern that can serve as a general rule and applies to many views:

• SELECT Knob
  • rotate to browse lists and move the cursor horizontally in grids.
  • short-press to select items.
• BACK Knob
  • rotate to move the cursor vertically in grids.
  • short-press to go back to previous view.

This general rule is extended in the next section.

Note:

The MAIN Volume is always available with one click. Bold-press BACK Knob to open the mixer view, then rotate Learn/Shot Knob to change the MAIN volume.

3.5 Using the push buttons

The V5 push buttons grid is divided in 5 groups:

View buttons

View buttons are outlined in green in the image and they allow direct access to the main views. Most of these buttons have 2 different views assigned, with a horizontal line separating two printed labels. The primary view is printed at top and the secondary view is printed at bottom. The "metronome" button is the exception, as it's the tap-tempo button. You press it once to access the tempo settings view, but you can tap it several times to change the tempo BPM. Try it!

LED color depends on current view:

• when the primary view is shown, the button lights green.
• when the secondary view is shown, the button lights orange.
• when none of the button's views are shown, the button lights blue.

A short-press on the button will access:

• the primary view, when the button's primary view is not shown
• the secondary view, when button's primary view is shown

A bold-press on the button will always access the secondary view, no matter what the current view is.

For instance, if you are in the mixer view and short-press OPT/ADMIN, the Main menu will be opened. If you short-press it again, the Admin menu will be opened. Then, if you bold-press the MIX/LEVEL button, the Audio Levels view will be opened. You press "metronome" button and the Tempo settings view will be opened. If you tap it several times, the tempo BPM will be changed, e.g. tap twice per second to set tempo to 120BPM.

The View buttons are, from left to right and top to bottom:

• OPT/ADMIN
  • Options / Menu: Opens the context menu for the current view. Press again to reach the main menu.
  • Admin menu
• MIX/LEVEL
  • Mixer
  • Audio Levels
• CTRL/PRESET
  • Chain Control
  • Presets / Banks
• ZS3/SNAPSHOT
  • ZS3 (sub-snapshots)
  • Snapshots
• METRONOME
  • Tempo Settings / Tap-Tempo
• PAD/STEP
  • Zynpad (Scene)
  • Pattern Editor

Some buttons have a global tertiary function assigned to long-press:

• OPT/ADMIN: long-press to power off.
• CTRL/PRESET: long-press to enter/leave preset favorites.
• PAD/STEP: long-press to access the arranger view.

ALT button

The ALT button toggles the alternate function mode. When you press it, the ALT button and the buttons having an alternate function will change their default color from blue to purple or orange. ALT mode is contextual, depending on the current view. By default, only transport and custom buttons (F1-F4) have alternate functions, defined like this:

• Transport buttons toggle between Audio Player/Recorder (normal) and MIDI Player/Recorder (alternate).
• Customizable F1-F4 buttons toggle between Program Change 1-4 (normal) and Program Change 5-8 (alternate). You could use it, for instance, to learn and recall up to 8 subsnapshots (ZS3s).

Some views have a custom ALT mode with specific functionality that partially or totally overrides the defaults. See the details in the sections below.

Transport buttons

By default, transport buttons control the global audio recorder/player and the default color is blue. When the ALT button is pressed (ALT mode enabled), transport buttons control the MIDI recorder/player and the color is purple.

• short-press REC (solid circle) to start/stop a recording. When a recording is in progress, the record button lights red and you should also see the rec icon in the display status area, at top-right.

• short-press PLAY (solid triangle) to play/pause the currently selected track. The last recorded track is selected by default. When a track is being played, the play button lights green. After pausing, pressing again will resume playing at the point it was paused.

• bold-press PLAY to open the track list. After selecting a track, the audio player control view will be shown.

• short-press STOP (solid square) to stop playing a track and rewind. Pressing play again will start playing from the beginning.

• bold-press STOP to stop all sounds, including any audio/MIDI track and sequences.

In some views/modes, transport buttons have specific (contextual) behaviour. When this happens, they will light orange to help you to remember their normal behavior is altered. See the sections below to have the specific details.

Navigation buttons

Navigation buttons are used for basic navigation and operation:

• UP/DOWN:
  • Browse lists and menus.
  • Move cursor (selected item) vertically in pattern editor, zynpad, etc.
• LEFT/RIGHT:
  • Select active chain in the mixer and chain-control views.
  • Move cursor (selected item) horizontally in pattern editor, zynpad, etc.
• SEL/YES:
  • Select items in lists and menus.
  • Enter select mode in chain-control view for browsing controller pages.
  • Add/remove notes in pattern editor.
  • Play/Stop sequences in zynpad.
  • Answer "Yes" in confirmation dialogs.
  • Bold-press may open the options menu for the selected item.
• BACK/NO:
  • Close current view, returning to previous view.
  • Answer "No" in confirmation dialogs.

Note:

When not in the control view, knob#4 acts as the select knob similar to the classic V1-V4 UI. Rotate to browse lists and move the cursor horizontally in grids (zynpad, pattern editor, etc.). Press to select items, same than SELECT button. Knob#3 can be used to move the cursor vertically in grids (zynpad, pattern editor, etc.).

Custom function buttons (F1-F4)
These buttons are considered to be customizable buttons, e.g. if you want direct access to other views, etc. you may reconfigure these buttons using the webconf's wiring layout tab.

As explained above, while describing the ALT-mode, these buttons are assigned by default to MIDI Program Change messages:

• Normal mode: Program Change 1-4
• ALT mode: Program Change 5-8

This default configuration is fine for learning/recalling subsnapshots (ZS3) and you may find this really useful if you use your zynthian as a keyboard expander.

Note:

Although all buttons and switches are fully configurable from the webconf tool (hardware->wiring->advanced), this guide refers to the official V5 profile configuration, that matches printed button legends. Of course, you are very welcome to experiment with button assignment and try different configurations. In fact, if you reach a sweet point, we may be able to produce an alternative keypad with custom printings. Simply contact us at the zynthian forum!

The zynthian's classic workflow (V1-V4) is based on the 4 knobs' switches. While short-press actions are generally contextual, bold and long-press actions are generally global.

Along the sections below, when omitted, these are the default press actions:

• layer
  • bold-press to open the main menu.
  • long-press to open the admin menu.
• back
  • short-press to back to the previous view.
  • bold-press to open the mixer view.
  • long-press to PANIC!. Stop all notes & sounds.
• learn/shot
  • bold-press to open the ZS3 list.
  • long-press to open the snapshot list.
• select
  • short-press to select/check/uncheck an item
  • bold-press to open contextual options.
  • long-press to power off the zynthian (it will ask to confirm).

The V4's extra buttons

The V4's extra silicone push buttons (S1-S4) can be configured depending on the user preference. This can be done from the webconf tool, accessing the advanced options in the wiring layout section. Some predefined customization profiles are available from there:

• V4 Stage: The 4 silicone push buttons are assigned to MIDI program change 1-4. It's specially thought to use with ZS3.
  • S1 => MIDI Program 1
  • S2 => MIDI Program 2
  • S3 => MIDI Program 3
  • S4 => MIDI Program 4

• V4 Studio: The 4 silicone push buttons are assigned like this:
  • S1
    • short => Audio Recorder/Player
    • bold => MIDI Recorder/Player
    • long => All Sounds Off
  • S2
    • short => Zynpad
    • bold => Pattern Editor
    • long => All Sounds Off
  • S3
    • short/bold => Arrow Up
    • long => All Sounds Off
  • S4
    • short/bold => Arrow Down
    • long => All Sounds Off

• V4 CC Switches: The 4 silicone push buttons are assigned to MIDI CC 47-50. It's specially thought to MIDI learn toggle parameters (i.e. to use with SooperLooper)
  • S1 => CC 47 (value 0/127)
  • S2 => CC 48 (value 0/127)
  • S3 => CC 49 (value 0/127)
  • S4 => CC 50 (value 0/127)

4 The top-bar

At the top of the display there is usually a bar that contains information. This may not be visible for some views, such as confirmation or information pop-ups.

4.1 The title-bar

The title bar acts as a kind of breadcrumb. It normally shows the view's title or info about the current snapshot/zs3 or chain (MIDI channel, engine, bank & preset).

It may also show a BACK button on the left which. When tapped will return to the previous view. Tapping the title's bar itself will open the options menu

4.2 The status area

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

• Digital Audio Peak Meter (DPM): horizontal bars indicating digital audio level and peaks
• Status icons: indication of various zynthian states

4.2.1 The Digital Audio Peak Meter (DPM)

The DPM 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.

This meter is the same as the main mixbus DPM that is always visible in the mixer view and is therefore hidden when the audio mixer view is shown.

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

4.2.2 The status icons

1st row: Health & Load
	Cpu Load	Heart, indicating CPU load. It displays as green when under 50%, yellow when load is over 50% and red over 75%.
	Software update available	When a software update is available, the green recycle symbol is shown. You can update from the admin menu, webconf or terminal.
	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.)
2nd row: MIDI activity & Playing/Recording
m	MIDI-IN	It's shown when MIDI messages are received. Underscore indicates system message such as MIDI clock.
	Recording Audio	Audio is being recorded.
	Playing Audio	Audio track is being played.
	Recording MIDI	MIDI is being recorded.
	Playing MIDI	MIDI track is being played.
	Recording Pattern	A sequencer's pattern is being recorded.
	Playing Sequence	A sequence or pattern is being played.

4.2.3 UI Actions

Default behaviour for touch or click of topbar are shown here. Deviations are shown in subsequent sections.

Touch zone	Action	Behaviour
Title		Show chain manager view
Title		Toggle mixer / launcher view
Title		Admin menu
Topbar back button		Previous view
Topbar back button		Show mixer / launcher view
Status Area		Tempo view + Transport control
Status Area		ZS3 menu
Status Area		All notes off (PANIC!)

5 Basic workflow

5.1 Chain creation

There are short video tutorials demonstrating the creation of chains in the learning pills.

Adding chains is a simple wizard driven workflow. Basic steps are:

• Access Main Menu.
• Select "Add ... Chain", e.g. Add Instrument Chain.
• Select the processor to add. (For some chains you may select "None" which adds an empty chain.)
• For MIDI driven chains, select the MIDI channel for the chain to listen for.
• For processors with banks of presets, select the preset bank.
• For processors with presets, select the preset.

Some processors may have extra configuration steps which are presented as simple menu options during the wizard. You may cancel the operation by using the back button.

5.2 Basic chain manipulation

There are short video tutorials demonstrating the manipulation of chains in the learning pills.

Each chain type may have different configuration options. To configure a chain, access the Chain Options menu then select the required configuration option. These may include:

• Note Range & Transpose - allows the MIDI input to the chain to be filtered (range) and modified (transpose).
• MIDI In - allows the MIDI input devices for a chain to be modified.
• MIDI Channel - allows the MIDI channel that a chain listens to to be changed.
• MIDI CC - allows the MIDI CC that a chain reacts to to be modified.
• MIDI Learn - provides access to MIDI learn / binding manipulation.
• Audio Out - allows the chain's audio output routing to be modified. This is also where you can arm a chain for multitrack audio recording.
• Audio In - allows the chain's audio input routing to be modified.
• Audio Options - allows some additional audio mixer controls (not presented in the mixer view) to be manipulated.
• Processors - allows manipulation of processors within the chain, e.g. moving a processor along the chain.
• Add Processor - allows a processor to be added to the end of a chain. (Audio chains allow the processor to be added before or after the fader.)
• Remove - allows removal of all effects or the whole chain. A confirmation is required.
• Rename chain - allows the chain to be given a user defined name which appears on the mixer view's fader.
• Move chain - allows a chain to be moved horizontally in the mixer view. This is a cosmetic change that has no impact on chain behaviour.

5.3 Layering chains ("clone")

A very common use-case is layering sounds to play unison. (This feature was called "clone" in older versions, but this has changed in Oram and the clone option no longer exists. Now we have better mechanisms because several chains can use the same MIDI channel).

• The easy way
  • If you are using ACTIVE mode for your input device, you must enable Active MIDI channel in the admin menu. With this enabled, all chains with the same MIDI channel will receive the MIDI stream from the input when any of them is selected (active).
  • Setup your "layered" chains with the same MIDI channel.

• The cool way
  • If you are using ACTIVE mode for your input device, you must disable Active MIDI channel in the admin menu. With this disabled, only the selected (active) chain will receive MIDI from the input, no matter the MIDI channel.
  • Setup your ”layered” chains in the same MIDI channel.
  • Create a MIDI+Audio chain with the same MIDI channel. Rename this chain to GROUP (or a name that best suits your workflow). You don’t need to add any processor, so you can select None from the list.
  • From the GROUP chain options, access “MIDI out” and select your “layered” chains. This will route MIDI from the GROUP chain to the layered chains.
  • Finally, access the Audio Out submenu on each "layered" chain: uncheck the Main mixbus and check the GROUP chain. With this you are routing audio from your cloned chains to the GROUP chain, so you can control the mixed audio with the GROUP chain’s fader.

Using the cool way you can select each chain individually and audition its sound or select the GROUP chain to play them all simultaneously / layered. You keep full control of each chain (fader, pan, mono, etc.), being able to insert effects and see each peak meter, and you also have overall control of the GROUP with the same control and monitoring (fader, pan, mono, etc. DPM, effects).

Nice, isn’t it? I really love the cool way, but there is a little problem with it: latency. When you route-back audio from chain’s output to the GROUP chain, you add latency. This is a general rule in digital audio processing: If you feed-back the signal, you delay the processed result by 1-period. Note that the MIDI stream is not delayed because there is no real feed-back and it’s processed linearly.

You don’t have to do both audio and MIDI grouping, as each one works individually. By not doing the audio grouping (e.g. using a MIDI chain rather than a MIDI+Audio chain you will avoid adding the extra period of latency and you still keep some of the advantages of the cool way.

7 The Sequencer

Zynthian includes an advanced MIDI sequencer capable of pattern based and linear sequences. There is a full user guide that describes the use of the sequencer in detail. This section gives a high-level overview of accessing and using the sequencer.

7.1 Zynpad (Scene)

Zynpad is a sequencer launcher, presented as a grid of trigger pads. Each pad can start and stop a sequence which may also be triggered by MIDI note-on commands.

• knob#4
  • rotate to move cursor horizontally.
  • short-press to play/stop the selected sequence.
  • bold-press to open the pattern editor for the selected sequence.
• knob#3
  • rotate to move cursor vertically.
  • short-press to MIDI-learn the current pad by pressing a note in your MIDI controller.
• knob#2
  • rotate to change the scene.
• knob#1
  • rotate to adjust tempo BPM.

Note:

Before MIDI-learning pads, you have to select a trigger device. Press OPT to access the zynpad menu and choose your trigger device. Note that if the selected device is already supported (has a driver!), MIDI-learning is not needed at all and the device will be mapped automatically.

7.2 Pattern Editor

The pattern editor allows editing patterns in a variety of ways:

• using the grid to add/remove notes or modifying note parameters.
• capturing MIDI notes step-by-step.
• capturing MIDI notes while playing (live recording).

For live recording you may want to enable the metronome and start playing the pattern before starting the capture.

• Knob#4
  • rotate to move cursor horizontally.
  • short-press to add/remove a note at cursor position.
  • bold-press to edit note parameters:
• Knob#3
  • rotate to move cursor vertically.
• Knob#2
  • rotate to change the zoom level.
  • short-press to restore default zoom level.
• Knob#1
  • rotate to adjust tempo BPM.

• REC to start capturing MIDI notes.
• STOP to stop playing a pattern.
• PLAY to start/stop playing a pattern.

edit note parameters

• Knob#4
  • rotate to select the parameter to edit
    • duration
    • velocity
    • offset
    • stutter count
    • stutter duration
    • play chance
  • short-press knob#4 to end editing
  • bold-press knob#4 again to enter EDIT ALL mode
• Knob#3
  • rotate to change coarse value.
• Knob#2
  • rotate to change fine value (when available).

Note:

Bold-press in an empty position to edit the default note parameters. These are the values used when adding new notes.

ALT mode

The pattern editor has a custom ALT mode that can be toggled with ALT button. When in ALT mode, the arrow buttons will change their color to orange, allowing to quickly access undo/redo functions:

• LEFT undo the last record operation
• RIGHT redo the last record operation
• UP undo ALL record operations
• DOWN redo ALL record operations

When adding notes step by step, each note added/removed is a record operation. When live recording, recorded notes are grouped in pattern-loops.

7.3 Arranger

The sequencer arranger view provides access to its linear sequencing features, including adding multiple tracks to each sequence, multiple patterns to each track, time signature changes, etc. The arranger could be considered Zynthian's song mode and combined with the Zynpad view and sequence play modes can offer flexibility for other performance workflows. See the Zynseq guide for more info.

7.4 Tempo Settings

On the tempo settings page you'll find options relating to time and some record/playback functions. The options are:

• Tempo adjustment (BPM)
• Metronome toggle and
• Metronome volume
• Audio record/playback and
• Midi record/playback

You can also choose the source of the clock that drives some zynthian modules, such as the sequencer. This may be:

Clock Source Options
Internal	The sequencer acts as the clock, so clock is running when sequence is running and BPM parameter controls clock rate.
Internal send	Same as Internal but MIDI clock is sent to MIDI outputs, not just internal modules.
MIDI	Use external MIDI clock to drive internal modules, such as sequencer.
Analogue	Use a GPI pin as a clock signal (similar to DIN Clock) for internal modules.

8 Custom Control Views

A selection of plugins are provided with a UI integrated into the Zynthian environment. The main window area will display additional controls and/or graphics specific to the plugin. Superlooper, x42 tuner and AIDA-X are for guitarists while there are utilities like a spectrum analyser and streaming radio player.

8.1 Zynsampler

Zynsampler is the built-in audio sampler in zynthian. It can record and playback a single audio recording at a time. Simple non-destructive editing can be performed. Playback can be looped between markers. The sample may be short or very long (hours). Speed or pitch or both (varispeed) may be adjusted. Playback can be triggered by MIDI. A MIDI note may adjust playback pitch (not speed) or trigger different slices of the waveform.

If the control view of a zynsampler processor (within a chain) is shown then the transport buttons (if available) control that zynsampler processor's record/play functions, otherwise the transport buttons control the global audio recorder/player.

The ZynSampler User Guide gives more detail.

8.2 Sooperlooper

ALT mode

Redefines the short-press functionality of transport, arrows and F1-F4 buttons:

• REC
  • on empty loop: toggles recording in the selected loop
  • on busy loop: toggles overdubbing in the selected loop
• PLAY toggles mute the selected loop
• STOP toggles multiplying the selected loop
• F1 toggles replacing in the selected loop
• F2 toggles substituting in the selected loop
• F3 toggles inserting in the selected loop
• F4 adds a new empty loop
• LEFT undo the last operation in the selected loop
• RIGHT redo the last operation in the selected loop
• UP/DOWN changes the selected loop

8.3 Tuner

The x42 Instrument Tuner with a native GUI for Zynthian and is available in the Audio Chain/Audio Effect/Analyzer.

8.5 Internet Radio

Zynthian has internet streaming radio with a selection of channels available as a chain from the Audio Generator/Other category.

8.6 AIDA-X - High Fidelity Amp Simulator

A guitar amp simulator using machine learning. Parameters are available across 5 pages. Accessible via Audio + Midi Chain/Audio Effect/Simulation. See the AIDA-X page for some links to different model and impulse response files.

9 CUIA: Callable UI Actions

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

9.1 Key Bindings: Controlling the UI with a computer keyboard

The user interface may be driven using a computer keyboard (QWERTY, Dvorak, etc.). Key assignment map can be consulted and configured from the webconf tool:

Interface->UI Key Binding

Zynthian has default keybinding for a standard (UK) QWERTY keyboard that maps logically to V4 encoders:

   ‘<’ (actually ‘,’) represents counter-clockwise encoder rotation.
   ‘>’ (actually ‘.’) represents clockwise encoder rotation.
   Without any modifiers these operate on encoder 4 (bottom right on V4).
   Adding ‘Ctrl’ modifier will operate on left encoders on V4.
   Adding 'Shift will operate on the top encoders on V4.
   The four keys (in a square) above these operate as the push switches:
   ‘i’ is switch 1 (top left).
   ‘k’ is switch 2 (bottom left).
   ‘o’ is switch 3 (top right).
   ‘l’ is switch 4 (bottom right).

Of course this mapping makes sense on keyboards that have those button grouped in the bottom right of the keyboard and for users familiar with V4 layout but they do work well.

9.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-0 key, if your keyboard has it.

Please, note that you can use the velocity for sending the first CUIA parameter when it's required by the action (for instance, SELECT or CHAIN_CONTROL).

You can check the map of MIDI-CUIA actions in the webconf tool:

Interface->MIDI-options->Master Key Actions

From there, you can also reconfigure the map to better suit your needs.

For a detailed list of available CUIAs, check this section.

9.3 Controlling the UI with OSC (Open Sound Control) messages

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

Also see Open Sound Control at Wikipedia and this explanatory video for more information about the protocol.

10 Software Version

By default, zynthian runs the stable release, oram-2409. Any stable point releases are advertised in the user interfaces with the green circle-arrow icon showing in the top right. Updates may be applied by selecting Update Software in the admin menu or selecting the SOFTWARE->Update option in webconf, then pressing the Update Software button.

There are four options for selecting which version of zynthian to run. The selection is made in webconf's SOFTWARE->Version page:

10.1 Stable (oram-2506)

Selecting this version will configure zynthian to run the most stable version of the software. Updates are infrequent and extensively tested. This is the default version and is recommended for production use. Only point releases appear in this software channel. A point release is a stable version, e.g. oram-24090.1 is the firsts stable update after the release of oram-2409.

After selecting this option, select 'Software Update' to apply changes.

10.2 Staging (oram)

Selecting this version will configure zynthian to run the staging version which is used as a pre-release test version. The staging version should work with minimal issues but is not fully tested. It is recommended to use this if you want to act as a zynthian tester, testing new features and bug fixes ahead of the next point release.

After selecting this option, select 'Software Update' to apply changes.

10.3 Testing (vangelis)

Selecting this version will configure zynthian to run the testing version which is used as the main development version. The testing version is under continual development and will change frequently, sometimes breaking or with substantial workflow changes. It is recommended to use this only if you are a developer or wish to contribute to testing bleeding edge development. The Testing version is generally maintained in a working stage so it should work most of the time.

After selecting this option, select 'Software Update' to apply changes.

10.4 Custom

Selecting the Custom option will, after a few seconds, allow individual selection of each software repository. This provides granular control of the software configuration. Each list contains the stable version, stable point releases, testing version and all development branches. There are two main use cases for selecting custom:

• Freezing the software at a specific point release - selecting a point release for each of the repositories will freeze the software at that version and no updates will be advertised in the user interface.
• Testing bleeding edge development - a new feature may be developed in a specific development branch which may need to be selected to allow testing. It is highly recommended to avoid using this option unless you have a clear understanding of why it may be necessary, e.g. instructed to do so by a core developer.

After selecting this option, select 'Save' and then 'Software Update' to apply changes.

11 Learning Pills

11.1 Create tutorial clips with zynthian

If you like zynthian and you would like to contribute, please, help us to improve zynthian documentation by creating small video clips with your favorite workflows and tricks. It's easier than you think:

How to create a tutorial clip with zynthian, by @gitnob

11.2 Basics

• Creating Instruments and Selecting Presets (workflow capture)
• Audio Mixer (workflow capture)
• Creating a synth chain and adding a MIDI chorder + audio FXs (tutorial - OLD VERSION)
• Creating a synth chain (workflow capture - OLD VERSION)
• Creating another synth chain (alternate workflow capture - OLD VERSION)
• Banks & Presets
• Chain Control
• Chain Options
• Chain FXs
• MIDI-learning: sound engine parameters
• MIDI-learning: audio mixer
• MIDI-learning: ZS3s (Zynthian SubSnapShots)
• Audio Recording
• MIDI Recording

11.3 Sequencer

• Pattern Editor: Creating & Editing patterns
• ZynPad: Launching patterns
• Audio Player: Loops & One-shots
• Arranger: Linear composing

11.4 Mini-HowTos

• MIDI Clone: Make 2 chains to play unison
• Arppeggiator & Chorder
• SooperLooper: Live audio looping

11.5 Contribute your workflow captures

This collection of workflow animations have been recorded with the "capture workflow" option from UI's admin menu and subtitled later with the webconf tool:

library->captures->log

With these tools, you can also capture, subtitle and share your favorite workflows, helping others to learn and contribute to improve zynthian documentation. If you do so, please, share your workflows in the forum:

https://discourse.zynthian.org