Using ZynSeq

From ZynthianWiki
Revision as of 12:32, 4 December 2020 by Riban (talk | contribs) (Tutorial for use of zynseq)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search


Do not use this guide until this warning is removed.

zynseq - The Zynthian Sequencer

This guide explains how to access and use the rich set of features provided by Zynthian's step sequencer called, zynseq. Before following the guide, add 2 synth engines to layers using MIDI channels 1 & 2 respectively. We will use these to demonstrate zynseq. If you use a touchscreen instead of rotary encoders then enable touch widgets using webconf INTERFACE->UI Options.

TODO: Provide a demo snapshot with engines and sequences configured.

Accessing zynseq

To access the sequencer, select "Step Sequencer" from the main menu or use the shortcut: bold press SNAPSHOT encoder. The first time you access the sequencer you will see a 2x2 grid of grey rectangles. This view is called ZynPad and provides a live performance interface to zynseq. Each of rectangle represents a pad which may be used to play a sequence. Use of ZynPad is described later but first we need to add some sequences.

What is a sequence? A sequence is a collection of patterns which may be played and looped. Several sequences may be played simultaneously, each playing any of the 16 MIDI channels. We will see how sequences are manipulated in the section Pad Editor.

What is a pattern? A pattern is a collection of MIDI events, e.g. notes. Each pattern has a duration in steps and may include as many simultaneous (polyphonic) notes as desired on each step. We will see how patterns are manipulated in the section Pattern Editor.

So a pad can trigger a sequence which is a collection of patterns. A pattern is a collection of MIDI events. Let's create...

Pad Editor

The Pad Editor is a view that allows the manipulation of sequences used by pads. To access the Pad Editor, from within zynseq short press LAYER encoder or tap the top left of the screen. This shows a context menu. The LAYER encoder or ENTER encoder may be used to highlight entries within this menu and the ENTER or LAYER button will select that entry. Alternatively the touch screen may be used to select an entry by touching the selection. If the menu extends beyond the bottom of the screen it may be scrolled by highlighting lower entries with the LAYER encoder or press and drag with the touchscreen. The first entries in context menu are common to all zynseq views. Select entry, "Pad Editor". The view should change to show a different type of grid. Each horizontal row represents a sequence assigned to a pad. On the left the pad's name and some other info is shown on a coloured cell. To the right is where patterns are added and removed. This is called the Patterns Grid. Each sequence may have as many or few patterns as desired. It may be common to use just one pattern for each sequence but more complex combinations are possible.

Navigation around the patterns grid is performed by rotating the BACK encoder to move up and down (select different pads) and the ENTER encoder to move left and right (select time). The currently highlighted cell is shown by a coloured outline called the cursor. By default there are 4 empty sequences configured. (Empty means no patterns have been added.) Let's add a pattern.

Use the LAYER and BACK encoders to move the cursor to the top left corner. This represents the starting time for the first sequence. Note that this sequence is called "A1" and has a purple background. This will be explained later but we will start to see its relevance soon. Short press ENTER encoder will add a pattern at the cursor position. A black bar should appear which represents the pattern. It will have a number which identifies which pattern has been added. If using a touchscreen you can tap the pattern grid to add a pattern. This may take a little practice to place it where you want but you can press, drag and release to position it more accurately. Great! We now have a pattern added to the sequence for pad A1. This won't yet be of much use but let's see how that looks in ZynPad. Short press LAYER encoder or touch top left of screen to show the context menu and select ZynPad. The ZynPad view shows and now the top left rectangle has changed to show the same colour background as the pad we just modified. This is because an empty sequence disables its pad hence shows grey but a populated sequence enables the pad which shows in that pad's colour. The pad's name, "A1" is shown on the pad and another icon which represents the pad's mode. Let's not worry about that yet.

Playing a sequence

The configured pad is purple. This indicates that the sequence is populated with one or more patterns and is not playing. Similar to how we navigate the cursor in the Pad Editor we can move the cursor in ZynPad with the BACK and ENTER encoders. Move the cursor to the top left to highlight pad A1 (it is probably already there) then short press ENTER encoder to start playback of sequence A1. This can also be achieved with a touchscreen by simply pressing pad A1. The pad changes to green indicating it is playing. (You may see it change to orange briefly - more on this soon). Short press ENTER or tap the pad with the touchscreen to stop the sequeunce playing. The pad changes to red to indicate it is stopping and then to purple to indicate it has stopped. We have not yet added any MIDI events to the pattern so nothing happens with any synth engines you may have loaded. Let's fix that.

TODO: Provide default patterns and sequences to give better OOBE.

Pattern Editor

Use the context menu to open the Pad Editor then move the cursor to the top left to highlight the pattern. Bold press ENTER encoder or press and hold the touchscreen on the pattern. The view changes to the Pattern Editor. Similar to the Pad Editor this has a grid on the right which is the Step Grid. On the left is a representation of a piano keyboard. Each row represents a note and each column in the step grid represents a step in the sequence.

Step sequences are a quantised collection of events, i.e. each event occurs at a discrete time and the available discrete times are equally and evenly distributed across the pattern. This means that step 2 occurs an amount of time after step 1 and step 3 occurs the same amount of time later after step 2, etc.

The step grid has a cursor, similar to the pattern grid in the Pad Editor and navigation is the same, i.e. use BACK encoder to move the cursor up and down (between notes) and the ENTER encoder to move the cursor left and right (between steps). To add a note, move the cusor to the desired step and note then short press the ENTER encoder. A note may be removed in the same way. Alternatively press the touchscreen on the cell you want to add or remove a note. Press and drag to allow more accurate positioning. As a note is added it is also sounded (MIDI sent to engine). All steps in a pattern are always shown but notes above or below those visible may be accessed by moving the cursor beyond the view with the BACK encoder. The view scrolls as the cursor reaches the edge. Alternatively press and drag up and down on the keyboard to vertically scroll the view. Note that as you touch a key on the keyboard it plays that note briefly. This is a useful tool for auditioning notes or phrases before adding them to the step grid.

To preview a pattern, short press the SNAPSHOT button to start the transport. A coloured bar at the bottom of the view will move left to right to indicate the position of the playhead and any notes entered in the pattern will be sent to the Zynthian's engines. To pause playback, short press SNAPSHOT. To stop and recue to the start of the pattern, bold press SNAPSHOT. If you press the touchscreen at the top right corner the transport controls display. Pressing the right pointing arrow play button will start playback. The play button changes colour to indicate it is playing. Pressing again will pause playback. Pressing the square stop button will stop playback and recue to start of pattern. Pressing top right of screen will hide the transport. Playback speed (Tempo) can be adjusted with the SNAPSHOT encoder or by selecting "Tempo" from the Pattern Editor context menu.

Add some notes to form a melody and preview with the play function. Short press BACK will return to the Pad Editor view. Use the context menu to show ZynPad. Highlight pad A1 and short press ENTER or press A1 pad on touchscreen. This time playback should play the pattern you just created. Playback speed (Tempo) can be adjusted with the SNAPSHOT encoder or by selecting "Tempo" from the ZynPad context menu.

Note that ZynPad is starting the A1 sequence which consists of Pattern 1 which in turn consists of the notes of your melody. This hierarchical relationship may be slightly more complex than a typical step sequencer but as we will see it offers many benefits. Just remember that a pad triggers a sequence. A sequence contains patterns. A pattern contains MIDI events, e.g. notes.

Note that to edit a pattern you first need to add the pattern to a sequence. You cannot access the Pattern Editor directly, only by bold ENTER or press and hold touchscreen of a patter in a sequence.

Note Duration

So far we have only added note with a duration of one step. The duration of a note may be changed with the LAYER encoder. This adjusts the quantity of steps that new notes will span. It also adjusts the duration of the currently selected note in the pattern. Alternatively with a touchscreen press on an existing note and drag horizontally to adjust the duration. The cursor indicates the note duration.

Note Velocity

By default notes are added with a velocity (loudness) value of 100. (The range is 1 - 127.) The velocity of a note may be changed with the SNAPSHOT encoder. This adjusts the velocity that new notes will have. It also adjusts the velocity of the currently selected note in the pattern. Alternatively with a touchscreen press on an exsiting note and drag vertically to adjust the velocity. The velocity is indicated by a yellow bar in the bottom left of the screen. The velocity of individual notes is indicated by the opacity of the note in the note grid.

Multiple Sequences

So far we have created a single sequence with a single pattern. Let's complement this with more sequences with different patterns. By default zynseq has 4 pads. Open the Pad Editor and move the cursor to the first time slot of the second sequence, "A2". Note the bottom left corner shows a number. This is the index of the pattern that will be added when you short press ENTER or press the pattern grid on the touchscreen. Use the BACK encoder to change the pattern selection to 2 or press on the bottom left of the touchscreen then adjust the value in the topbar. Add this pattern to sequence A2. Bold press ENTER or press and hold pattern 2 on the touchscreen to show the pattern editor. Add a new melody to the pattern then short press BACK or touch top left and select the back icon from the topbar to return to the Pad Editor view. Repeat for the other two pads then use the context menu to show ZynPad.

There are now 4 coloured pads, each with a different sequence. Start pad A1 and hear its sequence loop. Start pad A2. Pad A2 changes to Orange but does not start to play yet. Orange indicates sequence is waiting to start. A1 pad changes to red and continues to play. Red indicates sequence will stop at next sync point. A2 pad will change to green and start playing as A1 stops and changes to purple. The behaviour occurs because these pads are in the same group, "A". Start pad B3. Sequence B3 will start when the currently playing sequence reaches a sync point so that playback is synchronised. Start pad B4. Sequence B3 will continue then sequence B4 starts as B3 stops. A2 should continue to play. This is a powerful performance feature of ZynPad. You can assign any quantity of pads to any group providing groups of mutually exclusive (only one can play at a time) sequences. Sequences from different groups can play simultaneously but sequences from the same group will play sequentially.

New term: A Sync point is a location within playback at which sequences will loop and / or group sequential play will change to another sequence. Sync points are synonymous with bars in traditional music notation. See section on time signature.

By default sequences are in group A. To change the group of a sequence, select "Group" from the Pad Editor context menu. The group may be set to A-Z. Odd groups (A,C,E, etc.) are represented with purple background. Even groups (B,D,F, etc.) are represented with blue background. This allow a degree of separation in ZynPad without overloading with excessive quantity of colours.

Remember, sequences are indexed by number, 1, 2, 3, etc. and Groups by letter, A, B, C, etc. Sequence labels consist of the group letter and sequence number, e.g. A1.

Quantity of Pads

To change the quantity of pads, select "Tracks" from the Pad Editor context menu. 0-64 pads may be configured. Additional rows are added to the Pad Editor to represent the configured quantity. If this exceeds the available space then pattern grid will scroll when cursor reaches edge of view. Alternatively, press and drag the sequence titles on touchscreen to scroll the view. ZynPad view shows a grid of pads with the same quantity of rows and columns, resizing pads to fit. If the quantity of pads does not fill the grid then the last pads are still shown but disabled (grey). Pads are added top to bottom, left to right, e.g. 5 pads in group A would look like this:

A1 A4 A7
A2 A5 A8
A3 A6 A9

A6, A7, A8 & A9 would be disabled.

Sequence Modes

So far we have used the default mode for sequences which will loop the sequence until stopped at which point it will continue to play until the next sync point but there are many modes available which each offer features for different workflows / requirements. To change mode, select "Mode" from the Pad Editor context menu. This will allow change of mode of the highligted sequence. The mode is indicated in ZynPad and Pad Editor by an icon. Mode can also be changed from ZynPad context menu.

Available modes are:

  • Disabled: Sequence is disabled and cannot be played
  • Oneshot: Sequence will play once, i.e. not loop. When stopped sequence will stop immediately
  • Loop: Sequence will loop at end of sequence. When stopped sequence will stop immediately
  • Oneshot all: Sequence will play once, i.e. not loop. When stopped sequence will continue to play until end of sequence
  • Loop all: Sequence will loop at end of sequence. When stopped sequence will continue to play until end of sequence
  • Oneshot sync: Sequence will play once, i.e. not loop. When stopped sequence will continue to play until next sync point (end of bar)
  • Loop sync: Sequence will loop at end of sequence. When stopped sequence will continue to play until next sync point (end of bar)

Loop sync is the default mode.


Within Pad Editor the quantity of visible sequences (rows) may be adjusted by selecting "Vertical zoom" from the context menu. The size of patterns may be adjusted by selecting "Horizontal zoom" from the context menu. This adjusts the quantity of timeslots shown so increasing horizontal zoom actauall zooms out. Similarly, the quantity of keyboard notes in the Pattern Editor may be adjusted by selecting "Vertical zoom" from the context menu. There is no horizontal zoom for the Pattern Editor because it always shows all steps in a pattern.

MIDI channels

Each sequence may be assigned to a single MIDI channel. (Several sequences may be assigned to the same MIDI channel but that may provide little benefit, can have unexpected results and may be removed in future versions.) By default each sequence is assigned MIDI channel 1. To assign a sequence to a different MIDI channel, open the Pad Editor and move the cursor to the sequence to modify. Short press LAYER / press top left of touchscreen to show context menu and select "MIDI channel" option. The topbar now shows the current MIDI channel for the selected sequence. Use the ENTER encoder to change the value then short press ENTER. If Touch Widgets is enabled then there will also be buttons in the topbar to allow adjustment with the touchscreen. This data entry mode is called the Parameter Editor. The MIDI channel assigned to each sequence is shown in brackets after the sequence name on the left of the Pad Editor, e.g. A1 (2) indicates sequence 1 sends to MIDI channel 2.


All the configuration described above relates to a song. Zynthian supports 1000 songs, each may have different quantity of sequences, etc. Songs are identified by an index 1-1000. This can be selected from any zynseq context menu or directly by using LAYER encoder in ZynPad or Pad Editor views. The current song is shown in the topbar within brackets, e.g. ZynPad (5). Sons 1-128 may also be selected with MIDI Song Select message.

All songs share the same pool of patterns allowing reuse of patterns in different songs. With 999 patterns available there should be sufficient to create all the sequences in all the songs you need. If not, see section on Save and Load.

Songs may be copied by selecting "Copy song" from Pad Editor context menu. Use parameter editor to select the index of the new song to which to copy the current song. Select new song ID with ENTER encoder. Short press ENTER to copy the song. Short press CANCEL to cancel the operation.

A song may be cleared, removing all sequences by selecting "Clear song" from context menu then asserting by short press ENTER.

Save / Load

If you run out of patterns or songs or want to have different configurations for different scenarios you have the option save the whole zynseq sequence set. From any context menu select "Save" to show an on-screen keyboard allowing naming of the sequence set. By default the name of the currenly loaded sequence set is shown. Use the ENTER encoder to highlight a character. This moves the cursor left and right, wrapping to next row at end of row and back to start when reaching the end. The BACK encoder may be used to move cursor between rows (but does not wrap). Short press ENTER to add the character to the name. There is a DELETE button to remove the last character and a SHIFT button to show alternative characters. You may also use the keyboard with direct press of the touchscreen. On-screen CANCEL button or short press BACK will cancel the operation. Selecting on-screen ENTER button will save the sequence set with the name displayed at top of screen.

A previously saved sequence set may be loaded by selecting "Load" from any context menu. A list of sequence sets is displayed. Highlight the required name using the ENTER encoder then short press ENTER to load the highligted sequence set. Alternatively press the touchscreen to select the set to load. A sequence set may be deleted by bold press ENTER. A confirmation message is displayed.

Sequence sets are also saved with snapshots.

External Trigger

It is possible to trigger a sequence from a MIDI controller, e.g. a MIDI keyboard connected to the Zynthian. Zynseq listens for triggers on a single MIDI channel, i.e. only one MIDI channel may be used to trigger zynseq sequences. Select "Trigger channel" from Pad Editor context menu to change the MIDI channel zynseq listens for triggers. This may be None or channel 1-16.

Each sequence may be triggered by a MIDI note. Select "Trigger" from Pad Editor context menu to adjust the MIDI note that will trigger the highlighted sequence. By default sequences are assigned trigger notes sequentially from C4 (MIDI note 60). To disable a sequence from being triggered set its trigger value to None which is above G9, i.e. increase to maximum value. The trigger note is shown in brackets after the sequence name on the left of the Pad Editor, e.g. A1 (2, C4) indicates sequence 1 is triggered by note C4.


ZynSeq has the ability to send MIDI note on / off messages to represent the current play status of each sequence. This may be used by an external pad controller like Novation's Launchpad to indicate the status of a sequence. The note number sent is the same as the external trigger configured for a sequence. The MIDI channel that all tallies are sent to may be configured by selecting "Tally channel" from Pad Editor context menu. This may be None or channel 1-16.

Complex Sequences

A sequence may have any quantity of patterns either sequentially or separated by time. Patterns may not overlap within a sequence, i.e. a pattern's start must be at or later than the preceeding pattern's end. To add patterns to a sequence, within Pad Editor:

  • Select the required pattern
  • Move the cursor to the sequence and time at which to add the pattern
  • Short press ENTER

The cursor will show the duration of the pattern to be added. The cursor moves to the next time division unless the pattern will not fit within the gap in which case the cursor will jump to the start of the next pattern (even if the new pattern is longer than the next highligted pattern, to allow removal of patterns).

Encoders have been assigned to optimise this workflow: Move cursor to sequence with BACK encoder Move cursor to time with ENTER encoder Add / remove patterns with short press ENTER Select pattern with LAYER encoder

Adding Notes With MIDI Controller

It is possible to use a MIDI controller to add notes to a pattern, e.g. MIDI keyboard connected to Zynthian. Select "Input channel" from Pattern Editor context menu to adjust the MIDI channel that zynseq listens for input. When the Pattern Editor is shown, any note sent on this channel will add a note to the pattern at the current playhead cursor position with the current note duration and if the pattern is not being played, move the playhead to the next step. To add longer notes (in multiples of the current note duration) press the hold pedal whilst adding notes. It is possible to assign a note that acts as a rest, i.e. will not add a note to the sequence and skip to the next step. Select "Rest note" from pattern editor context menu to select which note will act as a rest. None may be selected by rotating ENTER encoder to the end of the range, i.e. below C-1 or above G9.

Time Signature

TODO: Time signature is defined by song editor which is not yet enabled.

A pattern has three parameters that affect playback speed: Beats in pattern, Steps per beat & Beat type. These can each be changed from the Pattern Editor context menu.

Beat type defines the duration of each beat and corresponds to the denominator of a time signature. A value of 1 means the beat is a semibreve / whole note. 2 means minim / half note. 4 is a crotchet / quarter note, etc. This is not graphically obvious in the Pattern Editor because it does not change the steps in the pattern and all steps are shown. Beat type changes the duration and hence larger values result in smaller steps and faster playback of the pattern. This is obvious in the Pad Editor where the size of the pattern will change, growing for lower values of beat type.

Beats in pattern defines the quantity of beats the pattern spans. Each beat is represented by a vertical white line on the note grid. As the beats in pattern change these lines move accordingly. The higher the value of beats in pattern, the longer the pattern.

Steps per beat defines the quantisation level of the pattern. The higher the value the more steps in each beat and hence in the whole pattern. This parameter does not affect duration of pattern but existing patterns will expand or shrink which will affect its playback speed. The values are restricted to 1, 2, 3, 4, 6, 8, 12, 24. This allows for a variety of common subdivision of note lengths, e.g. quavers / sixteenth notes, triplets, double speed triplets, etc. (This constraint is technical but also aligns with common musical requirements.)

It may take some practice to master these parameters. Remember that steps per beat adjusts the quantisation level whilst beat type and beats in pattern adjusts pattern length.



Drum Maps and Scales

By default the Pattern Editor shows a piano keyboard on the left side to represent the chromatic scale of notes for each row of the note grid. The scale may be changed by selecting "Scale" from the Pattern Editor's context menu. Scales include; Chromatic, Major, Minor, Blues & Blues pentonic. (Other scales may be added.) Changing the scale from Chromatic will hide notes in the note grid and all keys on the keyboard change to white, i.e. no blank keys are shown. Notes are hidden but not removed from the pattern which may result in notes not being visible. If a percussion preset or engine is selected for the current MIDI channel then an appropriate drum map is available in the list of scales.

Select "Tonic" from the Pattern Editor context menu to change the base note of the scale, e.g. A, A#, B, C, etc.

Pattern Management

A pattern may be cleared, copied or transposed by selecting the corresponding entry it the pattern manager context menu.

Clearing a pattern will remove all notes in the pattern after requesting confirmation.

Copying a pattern will copy all the notes and parameters of a pattern, overwritting the destination pattern after requesting confirmation.

Transposing a pattern moves all notes up or down a semitone at a time. Transpose is constrained to the MIDI range C-1 to G9. If any note in the pattern would be beyond this range then further transposing is prohibited. Transposing is only available when chromatic scale is used, i.e. drum maps cannot be transposed. An attept to transpose when a non-chromatic scale is being used will change the view to chromatic scale.

Import MIDI Files

There are some excellent percussion patterns available in MIDI File Format. Zynthian offers the ability to import such files into zynseq patterns. A MIDI file may be imported to one or more patterns. Some automation is involved in resolving pattern parameters, e.g. if the MIDI file contains events that would span more than one pattern, consecutive patterns are overwritten with the imported events.

  • Copy a MIDI File Format file to a USB drive
  • Insert the USB drive into Zynthian USB socket
  • Select a pattern to import into
  • Set the beat type, beats per bar and steps per beat for the pattern using Pattern Editor context menu
  • Select "Import" from the Pattern Editor context menu
  • A list of MIDI files on USB drive is shown
  • Use ENTER encoder to highlight the desired file then short press ENTER to import or use touchscreen to select the desired file
  • MIDI note events are imported into the current and subsequent patterns, overwritting any existing patterns
  • Events will be quantised to match the pattern configuration

To reconstruct the performance, add each pattern to a sequence.


Zynseq uses JACK timebase for its timing. Transport control and adjustment of tempo may be made by external JACK clients. Those clients may also use the same timebase. This means that zynseq can synchronise with other modules within Zynthian, e.g. synth engine LFO, arpegiators, etc. It also means that other modules may control zynseq playback to some degree. Zynseq acts as the timebase master, i.e. the concept of bars, beats and ticks (fractions of beats) and consequently tempo (BPM) is provided by zynseq. There is currently no mechanism to lock to external MIDI clock but a Zynthian MIDI effects layer may be used to create MIDI clock output. There is a plan to improve this support in a future update.

Note that if a module alters the transport, e.g. stops it then zynseq may have unexpected behaviour. Check what engines are doing if you experience timing or playback issues.