Zynthian UI User's Guide - Oram

V5 | V4 | Touch

1 Introduction

Zynthian Oram is the most recent version of zynthianOS, first released in September 2024. It has some substantial changes compared to earlier versions. This user guide describes the core concepts of the system and gives detailed guidance on how to use it. Note that you can select the documentation for different hardware types (V5, V4, Touch) with the selector in the top right of the page. If you are using V1-V3 then select V4. 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. 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.

This guide is a living document, subject to frequent update. Some sections may be incomplete and the whole document will improve during the lifetime of zynthian Oram. 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. Audio signals coming out from chains 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.

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 contains 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 => Recieves MIDI events and audio input and generates MIDI output and audio output.

Each type of processor is catagorised 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 MIDI input

Chains receive MIDI data from a set of MIDI inputs. These MIDI inputs could be external MIDI devices connected to MIDI DIN-5 or USB MIDI (sequencers, keyboards and other MIDI controllers) or other MIDI sources (MIDI network services, etc.) and they can be configured for each chain separately. Each MIDI input can work in 2 different modes:

2.2.1 Active mode

When an MIDI input is configured in active mode, the active chain (the highlighted or selected chain) receives all MIDI input from it and all MIDI events are translated to the active chain's MIDI channel. This is the default mode for all MIDI inputs. When using active mode you don't need to worry about the MIDI channel your keyboard or controller is using. You change which instruments are played by changing the active chain in your zynthian (see below).

Active mode's behavior can be modified by the Active MIDI channel global flag (see admin menu):

• Active MIDI channel Disabled => Only the active chain receives data from the MIDI input in active mode. This is the default setting.
• Active MIDI channel Enabled => All chains with the same MIDI channel as the active chain receive data from the MIDI input in active mode. This is very useful for layering sounds without any extra routing. You simply create several synth chains with the same MIDI channel and they will play in unison. You can also create keyboard splits by adjusting note range and transpose for each chain.

2.2.2 Multitimbral mode

When a MIDI input is configured in multitimbral mode, only those chains matching the input's MIDI channel will receive data from this MIDI input. No MIDI channel translation is performed. Multitimbral mode allows receiving and managing each MIDI channel individually. Each MIDI input selects the chains it drives using the MIDI channel. If you are using an external sequencer or a MIDI controller that can sequence multiple tracks (Beatstep Pro, Keystep Pro, Novation Circuit, etc.), you may want to use multitimbral mode.

Note:

Note that MIDI CC (Continuous Controllers) events are handled differently and they are not routed to chains. See section on MIDI Learning & binding.

2.3 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.4 Snapshots

A snapshot is the captured state of zynthian at the time of saving the snapshot. Snapshots are saved in a JSON file with .zss extension and can be loaded at any time, which effectively restores the state of the zynthian device when the snapshot was saved. Snapshots include:

• chains layout: configuration of each chain including its processors and how they are arranged and connected
• audio levels: (optional) physical audio interface settings
• sequencer: patterns & sequences
• MIDI settings: global MIDI settings, USB MIDI port names, etc.!!
• multitrack record settings: mixer strips armed for multitrack recording
• UI state: some user interface configuration relevant to the snapshot (most UI is configured globally)
• sub-snapshots (ZS3s): most other configuration (see ZS3)

Each time you overwrite an existing snapshot file, a backup copy is created. Backups can also be restored at any time, which can avoid much suffering. When you feel the panic, remember that zynthian stores the full save history for all snapshots!

Note:

Many zynthian users like to see snapshots as "zynthian project" files and it's not a a bad approach.

2.4.1 Last state snapshot

When zynthian starts, it always try to restore the last state saved as this snapshot. It always trys 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.

2.5 Sub-snapshots: ZS3

ZS3 means Zynthian Sub-SnapShot. A ZS3 is a partial state that is stored in memory and can be recalled very fast. ZS3s can be easily associated (learned) to MIDI Programs (program change events). Of course, all ZS3s are saved and restored with snapshots, including the default state of the snapshot when first loaded (ZS3-0).

Please bear in mind that in the case of USB connected MIDI devices there are two settings configured in admin under "MIDI-USB mapped by port" that affect this functionality. With mapped to port set the learnt settings will apply only to the specific USB Configuration in place at the time of learning. So if you add a USB hub to the rig the ZS3 sub-snapshots won't act. Turning this off will allow control simply by the MIDI message only

ZS3s include:

• chains configuration: for each chain, MIDI channel, note-range, transpose, etc.
• processors state: for each processor, bank, preset & parameter values
• mixer settings: for each mixer strip, fader, balance, mute, solo, etc.
• MIDI devices configuration: active / multitimbral mode, etc.
• MIDI & Audio routing: connections between chains
• MIDI learning: MIDI bindings to processor and mixer parameters
• global settings: some global settings that can be changed by ZS3, e.g. MIDI transpose (most global settings are not available to ZS3)
• active chain: chain that was active when the ZS3 was saved

The key concept to understand how ZS3s work is noting that chains layout is not stored in ZS3s. In other words, chain's layout is not modified when retoring ZS3s. You can't add/remove chains or processors by restoring ZS3s because this is a slow operation and ZS3s need to be restored very fast.

When loading a snapshot that contains ZS3s, all the chains and processors are created. Later, when recalling the ZS3s, chain's layout will remain the same. Although ZS3s can modify routing, splits, banks, presets, etc., the quantity of chains and processors will be unchanged.

Note:

For instance, if you are keyboardist that plays with several bands, you could have a snapshot for each band with ZS3s for each song.

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 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, accessing remotely with VNC.

3.2 User interaction

Users interact with the system by pushing 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:

• Push: You can push buttons, knob-switches or display widgets. There are 3 types of push 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:

• Push: You can tap display widgets. There are 3 types of tap (push) 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 Push	Push 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 Push	Push 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 Push	Push 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 Push	Push 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 Push	Push 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 Push	Push 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	Push and drag horizontally. Must release before you can drag vertically. If still moving when released, a swipe action may occur.
Vertical Drag	Vertical Drag	Push 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	Push 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	Push 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	Push with two fingers then drag horzontally towards or away from each other. Must release before you can pinch vertically.
Vertical Pinch	Vertical Pinch	Push with two fingers then drag vertically towards or away from each other. Must release before you can pinch horizontally.

You can change the timings from the webconf's UI options tab. Not all controls have actions assigned to all three push 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 to 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 push 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 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-push to select items, like the SEL button.
  • bold-push to open contextual options, like the OPT button.
• Knob#3
  • rotate to move the cursor vertically in grids.

Note:

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

The V4 knobs (rotaries & switches) are the primary mechanism to navigate the UI. It's functionality is contextual, specially rotate, short and bold-push actions. Long push 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 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-push to select items.
• BACK Knob
  • rotate to move the cursor vertically in grids.
  • short-push to back to previous view.

This general rule is extended in the next section.

Note:

MAIN Volume is always available with one click. Bold-push 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 on 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 push 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-push 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-push on the button will always access the secondary view, not matter what the current view is.

For instance, if you are in the mixer view and short-push OPT/ADMIN, the Main menu will be opened. If you short-push it again, the Admin menu will be opened. Then, if you bold-push the MIX/LEVEL button, the Audio Levels view will be opened. You push "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.

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

• OPT/ADMIN
  • Options / Menu: Contextual. Push several times until 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-push:

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

ALT button

The ALT button toggles the alternate function mode. When you push 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 of 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 overrides partial or totally the defaults. See the details in the sections below.

Transport buttons

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

• short-push 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-push 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, pushing again will resume the playing in the point it was paused.

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

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

• bold-push 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.
• 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.). Push 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 in the 4 knobs' switches. While short-push actions are generally contextual, bold and long-push actions are generally global.

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

• layer
  • bold-push to open the main menu.
  • long-push to open the admin menu.
• back
  • short-push to back to the previous view.
  • bold-push to open the mixer view.
  • long-push to PANIC!. Stop all notes & sounds.
• learn/shot
  • bold-push to open the ZS3 list.
  • long-push to open the snapshot list.
• select
  • short-push to select/check/uncheck an item
  • bold-push to open contextual options.
  • long-push 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 of 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 menu
Title		ZynPad view
Title		Admin menu
Topbar back button		Previous view
Topbar back button		Show mixer view
Status Area		Tempo view + Transport control
Status Area		ZS3 menu
Status Area		All notes off (PANIC!)

5 Basic Views

5.1 Mixer

The mixer view is a significant view in zynthian. It can be considered the Home view. It's composed of vertical strips associated with chains. Initially it will be empty, showing the main strip alone. For each chain you create, a new strip is added to the mixer. (There can be more mixer strips than can be displayed. They will scroll left / right if you select a strip that is off screen.) Each strip is an interactive widget that can be manipulated in several ways and it shows status info about the associated chain. From top to bottom:

• solo: Solo flag. Push to toggle. This is a non-exclusive solo mode. When a chain has solo enabled, all other chains without solo enabled will be muted, allowing auditioning of one or more chains. The **main** solo will disable all chain solos.

• mute: Mute flag. Push to toggle. When a chain is muted (it has "mute" enabled), it will remain silent.

• fader: Mixing volume for the associated chain. Drag up & down to modify the fader level. On the touchscreen you can drag multiple faders at once. Tap it to set the active chain.

• DPM: Digital Peak Meter for the associated chain. See DPM section above.

• description: A vertically oriented text describing the chain. By default, for a synth chain it will show synth processor and preset name. If you give a name to the chain, this will be included in the description too.

• balance/pan: Mixing right/left balance (or pan of a mono signal) for the associated chain. Rotate knob#2 or drag left & right to modify the value.

• legend: It shows an icon for the chain's type and a number for the assigned MIDI channel. Tap it to access the chain's control view.

5.1.1 UI Actions

• knob#1
  • rotate to change the volume of the active chain.
  • short-push to solo the active chain.
• knob#2
  • rotate to change the balance of the active chain.
  • short-push to mute the active chain.
• knob#3
  • rotate to change the main volume.
  • short-push or bold-push to open the mixer's MIDI-learning menu.
• knob#4
  • rotate to change the active chain.
  • short-push to open the chain control view for the active chain.
  • bold-push to open the chain options for the active chain.

• LEFT/RIGHT to move across mixer strips, changing the active chain.
• UP/DOWN to change the volume of the active chain.
• SEL to access the control view for the selected chain.

• layer
  • rotate to change the volume of the active chain.
  • short-push to solo the active chain.
• back
  • rotate to change the balance of the active chain.
  • short-push to mute the active chain.
  • bold-push to open the zynpad view => This breaks global rule but improves sequencer workflow!!
• learn/shot
  • rotate to change the main volume.
  • short-push to open the mixer's MIDI-learning menu.
• select
  • rotate to change the active chain.
  • short-push to open the chain control view for the active chain.
  • bold-push to open the chain options for the active chain.

Touch zone	Action	Behaviour
Solo button		Toggle chain solo
Mute button		Toggle chain mute
Chain Legend		Show chain control view
Chain Legend		Show chain options
Chain Fader	Drag up / down	Adjust chain volume
Chain Fader	Drag left / right	Adjust chain balance
Chain Fader	Mouse wheel	Adjust chain volume
Chain Legend	Drag left / right	Scroll chains horizontally
Chain Legend	Mouse wheel	Scroll chains horizontally

5.2 Main menu

The main menu is a selector view, consisting of a list of options you can browse and select. Most views in the zynthian-UI are of this type and they work in quite a similar way, with very little variation.

From this menu you can:

• create a new chain
• remove an existing chain
• remove all chains
• remove all sequences
• remove all

In addition, the main and system sections allow accessing most of the main views and features:

• Snapshots
• Sequencer
• Audio Recorder
• MIDI Recorder
• Tempo Settings
• Audio Levels
• Mixer Learn
• Admin
• Stopping All Sounds (PANIC!)

5.2.1 UI Actions

• knob#4
  • rotate to move across options.
  • short-push or bold push to select the highlighted option.

• UP/DOWN to move across options.
• SEL to select the highlighted option.
• BACK to close the menu and return to previous view.

• back
  • short-push to close the menu and return to previous view.
• select
  • rotate to move across options.
  • short-push or bold-push to select an option.

Touch zone	Action	Behaviour
Topbar back button		Previous view
Topbar back button		Mixer view
Menu entry		Select menu action
Menu entry		Show context menu for menu entry (if appropriate)
Menu entry	Drag up / down	Scroll list
Menu entry	Swipe up / down	Scroll list with momentum
Menu entry	Mouse wheel	Scroll list

Note:

This table shows the common or default touch behaviour for lists. Only deviations from this will be shown in subsequent sections.

5.3 Processor selector

The processor selector is a selector view, but a very special one. It will pop-up when creating a new chain or when adding or replacing processors in a existing chain.

5.3.1 Processor categories

To ease selection and avoid long lists, processors are classified in categories. The selector allows easy browsing across categories and processors so you can find what you want as fast as possible.

5.3.2 Extended info

In addition to the processor's name, when available, some extra info is shown for each processor:

• Quality (stars): From 0 to 5, indicating how good is the processor. Of course, this is very subjective ;-)
• Complexity (knobs): From 0 to 5, indicating how complex is the processor. It's usually related to the number of control parameters.
• Description (text): A concise description of the processor's features. Push it to open the detailed info view.

5.3.3 Enable/Disable processors

To allow greater customization and avoid long lists of processors user never use, processors can be enable/disable. When a processor is disabled, it's not shown in the list, but still can be used when loading a snapshot that includes it.

5.3.4 UI Actions

• knob#3
  • rotate to move across categories.
  • short-push to open the full info view.
• knob#4
  • rotate to move across processors.
  • short-push to select a processor.
  • bold-push to toggle view-all mode.

• LEFT/RIGHT to move across categories.
• UP/DOWN to move across processors.
• SEL to select a processor.
• BACK to cancel the selection and return to previous view.

view-all mode

• knob#3
  • rotate to move across categories.
• knob#4
  • rotate to move across processors.
  • short-push to enable/disable processors.
  • bold-push to back to normal mode.

• LEFT/RIGHT to move across categories.
• UP/DOWN to move across processors.
• SEL to enable/disable processors.
• BACK to back to normal mode.

• back
  • short-push to cancel selection and return to previous view.
• learn/shot
  • rotate to move across categories.
  • short-push to open the full info view.
• select
  • rotate to move across processors.
  • short-push or to select the highlighted processor.
  • bold-push or to toggle view all mode.

view-all mode

• back
  • short-push to back to normal mode.
• learn/shot
  • rotate to move across categories.
• select
  • rotate to move across processors.
  • short-push or to enable/disable processor.
  • bold-push or to back to normal mode.

Touch zone	Action	Behaviour
Topbar back button		Previous view
Topbar back button		Mixer view
Menu entry		Select menu action
Menu entry		Enter "view-all" mode
List	Swipe left or right	Change the category of engines shown
Category	Swipe up or down	Change the category of engines shown
Info area		Open the full info view

5.4 Chain control

The chain control view allow accessing the chain's processors and controlling their parameters. For instance, you can adjust the LFO frequency on a synth, the reverb's room size, the equalizer bands, etc. The default control view is composed of:

• list of controller pages, grouped by processor
• 4 x controller widgets, dynamically assigned to the 4 parameters of the selected page. The controller widgets are layered aside the 4 rotary encoders that can be used for modifying the parameter's value in real time.Depending of configuration options, the controller widgets could be layered at the four display corners (classic layout: top-left, down-left, top-right, down-right) or they could be all at right (V5 layout).

Controller pages can be browsed one-by-one or you can enter select mode to move faster across the list.

Processor parameters can be easily bond to your MIDI controller's knobs & faders (MIDI CC) by using the MIDI learning mechanism.

5.4.1 UI Actions

• knob#1 - knob#4
  • rotate any knob to change the value of the assigned parameter.
  • short-push any knob to start MIDI-learning for the associated parameter.
  • bold-push any knob to open the options menu for the associated parameter.

• UP/DOWN to navigate across controller pages.
• LEFT/RIGHT to move across chains, changing the active chain.
• SEL to enter select mode, then fast-browse controller pages by rotating knob#4.

select mode

• knob#4
  • rotate to move across controller pages
  • short-push to select page and back to control mode

• SEL to select page and back to control mode.
• BACK to back to control mode.

MIDI learning

800px

• knob#1 - knob#4
  • short-push for global learning. A third push to cancel.

• move a knob/fader in the MIDI device to complete the learn.

• BACK to cancel MIDI learning.

• layer
  • rotate to modify the assigned parameter.
  • short-push to rotate active chain.
• back
  • rotate to modify the assigned parameter.
  • short-push to open the preset list for the selected processor.
• learn/shot
  • rotate to modify the assigned parameter.
  • short-push any knob to start MIDI-learning.
• select
  • rotate to modify the assigned parameter.
  • short-push to enter select mode.
  • bold-push to open the chain options view.

select mode

• back
  • short-push to exit from select mode.
• select
  • rotate to move across controller pages.
  • short-push to select page and back to control mode.

midi learning

800px

• back
  • short-push to cancel midi learning.
• learn/shot
  • short-push for global learning. A third push to cancel.
• rotate any knob to select the parameter to learn.
• move a knob/fader in the MIDI device to complete the learn.

Touch zone	Action	Behaviour
Topbar title		Show chain menu
Topbar back button		Return to previous view
Controller widget		Toggle MIDI learning
Controller widget		Show control options menu
Previous button		Select previous chain
Preset button		Show presets menu
Pages button		Show list of pages of controls (useful if a GUI widget is hiding these)
Next button		Select next chain

5.5 Presets

When a processor has presets, the presets list view allows browsing across them and selecting the desired one.

In addition, the preset options can be accessed by bold-pushing any preset. The available options depends of the processor and whether the preset is a user or system preset.

• [ ] Favorite: Available for all presets. Checked / unchecked - adds to the list of favourites presets.
• Rename: Available for user presets only. Allows user to rename a preset.
• Delete: Available for user presets only. Allows a user to delete a preset (with confirmation).

Preset pre-load
If preset preload is enabled from admin options, the highlighted preset is preloaded when a MIDI note is received, allowing to pre-listen presets before selecting them. Please, note that you often need to play 2 notes to pre-listen each preset due to a delay in loading the new preset.

5.5.1 UI Actions

• knob#4
  • rotate to move across presets.
  • short-push to select the highlighted preset.
  • bold push to open the preset options.

• UP/DOWN to move across banks.
• SEL
  • short-push to select the highlighted preset.
  • bold push to open the preset options.
• BACK to close the bank selection and return to control view.

preset options

• knob#4
  • rotate to move across options.
  • short-push or bold push to select/check option.

• UP/DOWN to move across options.
• SEL to select/check option.
• BACK to close the preset options and back to presets list.

• back
  • short-push to open bank selection view or back to control view.
• select
  • rotate to move across presets.
  • short-push to select a preset.
  • bold-push to open the the preset options.

preset options

• back
  • short-push to close preset options and back to presets list.
• select
  • rotate to move across options.
  • short-push or bold-push to select/check an option.

TODO!

5.6 Banks

When the processor have its presets organized in multiple banks, this view allows to browse across the banks and select a bank for preset selection.

In addition, the bank options can be accessed by bold-pushing any bank. The available options depends of the processor and whether the bank is a user or system bank.

• New Create a new user bank. Not available for all processors.
• Rename: Available for user banks only.
• Delete: Available for user banks only.

5.6.1 UI Actions

• knob#4
  • rotate to move across banks.
  • short-push to select the highlighted bank.
  • bold push to open the bank options.

• UP/DOWN to move across banks.
• SEL
  • short-push to select the highlighted bank.
  • bold push to open the bank options.
• BACK to close the bank selection and return to control view.

• back
  • short-push to close the bank selection and return to control view.
• select
  • rotate to move across banks.
  • short-push to select a bank.
  • bold-push to open the bank options.

TODO!

5.7 Chain options

The chain options view allows to manage chains, configuring the many available options and adding, moving, replacing or removing processors.

The available options depends of the chain's type. I.e. audio chains don't need to configure MIDI in or MIDI channel options. MIDI chains don't need to configure audio output, etc.

In the lower part of the view, the chain's processor tree is shown, allowing to access processor options and manipulate the chain in a variety of ways.

From the processor options you can:

• save presets for the processor
• move the processor within the chain
• replace the processor
• clean processor's MIDI-learning
• remove the processor

When moving a processor within the chain, the processor can be positioned in series or parallel with any processor of the same type.

Audio processors can be placed pre-fader or post-fader. Please, note that having post-fader processors adds a period of latency to the chain's audio output.

5.7.1 UI Actions

• knob#3
  • rotate to move the processor within the chain.
• knob#4
  • rotate to move across options and processors.
  • short-push or bold-push to select an option or open the processor options.

• LEFT/RIGHT to move across chains.
• UP/DOWN to move across options and processors.
• SEL to select an option or processor.
• BACK to return to previous view.

processor options

• knob#4
  • rotate to move across options.
  • short-push or bold push to select an option.

• UP/DOWN to move across options.
• SEL
  • short-push or bold push to select an option.
• BACK to back to previous view.

800px

• back
  • short-push to return to previous view.
• learn/shot
  • rotate to move the processor within the chain.
• select
  • rotate to move across options and processors.
  • short-push or bold-push to select an option or open the processor options.

processor options

800px

• back
  • short-push back to previous view.
• select
  • rotate to move across options.
  • short-push or bold-push to select an option.

5.9 MIDI input/output

Global MIDI input/output view is accessed from the admin menu. It allows to manage MIDI input/output sources:

• enable/disable MIDI network services
• enable/disable bluetooth MIDI devices

Bold push on any device to access the device options:

• toggle capture mode: ACTIVE / MULTI
• load/unload controller drivers
• rename the device

Chain's MIDI input/output view is accessed from the chain's options menu. It allows to select the devices from which it will receive MIDI input or to which it will send MIDI output. You can also access device options by bold-pushing any device.

When creating a new chain, all input devices are selected by default and capture mode is ACTIVE.

5.9.1 UI Actions

• knob#4
  • rotate to move across devices.
  • short-push to check/uncheck a device.
  • bold push to open the device options.

• UP/DOWN to move across devices.
• SEL
  • short-push to check/uncheck a device.
  • bold push to open the device options.
• BACK to close the view and back to chain options.

device options

• knob#4
  • rotate to move across options.
  • short-push or bold push to check/uncheck an option.

• UP/DOWN to move across options.
• SEL
  • short-push or bold push to check/uncheck an option.
• BACK to back to previous view.

800px

• back
  • short-push to close the view and back to chain options.
• select
  • rotate to move across devices.
  • short-push to check/uncheck a device.
  • bold-push to open the device options.

device options

800px

• back
  • short-push back to previous view.
• select
  • rotate to move across options.
  • short-push or bold-push to check/uncheck an option.

• short-push back button to close the view and back to chain options.
• drag list up/down to move across the list
• short-push on list item to check/uncheck a device or enable/disable network/bluetooth service
• bold-push on a MIDI device to open the device options.

5.16 ZS3 (sub-snapshots)

The active chain can be changed by recalling a ZS3 (subsnapshot).

5.20 MIDI input/output devices

You can access MIDI input/output devices view from the admin menu. From this view you can manage DIN-5 and USB MIDI devices as well as enable/disable bluetooth and network MIDI services.

6 Basic workflow

6.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.

6.2 Basic chain manipulation

There is 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.

6.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 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, true? 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.

8 The Sequencer

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

8.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-push to play/stop the selected sequence.
  • bold-push to open the pattern editor for the selected sequence.
• knob#3
  • rotate to move cursor vertically.
  • short-push to MIDI-learn the current pad by pushing 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. Push OPT to access the zynpad menu and choose your trigger device. Note that if the selected device is already supported (have a driver!), MIDI-learning is not needed at all and the device will be mapped automatically.

8.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-push to add/remove a note at cursor position.
  • bold-push to edit note parameters:
• Knob#3
  • rotate to move cursor vertically.
• Knob#2
  • rotate to change the zoom level.
  • short push 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-push knob#4 to end editing
  • bold-push 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-push 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 its 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.

8.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.

9 Custom Control Views

9.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. 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.

9.2 Sooperlooper

ALT mode

Redefines the short-push 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

10 Learning Pills

10.1 Basics

• Creating a synth chain and adding a MIDI chorder + audio FXs (tutorial)
• Creating a synth chain (workflow capture)
• Creating another synth chain (alternate workflow capture)
• Audio Mixer (workflow capture)
• 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

10.2 Sequencer

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

10.3 Mini-HowTos

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

10.4 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 this tools, you can also capture, subtitle and share your favorite workflows, helping others to learn and contributing to improve zynthian documentation. If you do so, please, share your workflows in the forum:

https://discourse.zynthian.org