ZynSeq User Guide

1 ZynSeq - The Zynthian Sequencer

This guide explains how to access and use the 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.

2 Installing ZynSeq

The current stable build of Zynthian OS (2020-09-05 at the time of writing) does not include the latest version of ZynSeq. To use it, you're going to need to swap to the ZynSeq branch of Zynthian OS. To do that, you'll want to:

• Log into webconf
• Choose Software / Repositories from the menu
• Change the zynthian-ui dropdown box to 'feature/zynseq'
• Click 'Save'
• Choose Software / Update from the menu
• Click the 'Update Software' button
• Reboot your Zynthian once this process has completed

Once your Zynthian is back online, long push on the learn/snapshot button. All being well, you should see the sequencer's pad screen.

3 Accessing ZynSeq

To access the sequencer, select "Sequencer" from the main menu or use the shortcut: long press LAYER encoder. The first time you access the sequencer you will see a 4x4 grid of rectangles organised as 4 columns of colours. 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 to play.

What is a sequence? A sequence is a collection of tracks which play in unison. By default each sequence has a single track. A sequence is a member of a group (indicated by its prefixe A-Z and pad colour). Several sequences may be played simultaneously but those in the same group do not play concurrently.

What is a track? A track is a collection of patterns which may be played and looped. Each track plays out to its own MIDI channel. We will see how sequences and tracks are manipulated in the section Arranger.

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 tracks. A tack is a collection of patterns. A pattern is a collection of MIDI events. Let's create...

4 Menus and Parameters

First we need to understand some user interface elements. Zynseq includes a context menu that is shown by short press LAYER or touching the top left of the screen. The LAYER or SELECT encoder may be used to highlight entries within this menu and short press LAYER or SELECT will select that entry. Alternatively the touchscreen 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 SELECT or LAYER encoder or press and drag with the touchscreen. (Note: When touch and dragging on touchscreen the menu option will be selected when touch is released.) The first entries in context menu are common to all ZynSeq views. Entries below the first divider are context sensitive, i.e. specific to the current view or action being performed.

If a parameter is selected from the context menu its title and value is displayed in the title bar at the top of the screen. This is called the parameter editor. The value may be adjusted with the LAYER or SELECT encoder and asserted by a short press of LAYER or SELECT. Short press BACK to cancel out of the parameter editor. If touchscreen widgets is enabled then buttons appear in the title bar allowing adjustment of the parameter.

5 Pattern Editor

By default each pad triggers a sequence containing a single pattern. Bold press SELECT encoder to show the Pattern Editor for the highlighted pad or press and hold the pad on the touchscreen. There is a grid on the right called the Step Grid. On the left is a representation of a piano keyboard, scale or drum map. 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 the difference in time between step 1 and step 2 occuring is the same as the difference in time between step 2 and step 3 occuring.

One of the cells in the step grid has a coloured outline. This is the cursor and identifies which cell is currently highlighted. Rotate the BACK encoder to move the cursor up and down (between notes) and the SELECT 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 SELECT 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, i.e. there is no horizontal scrolling or zoom. Notes above or below the visible area may be accessed by moving the cursor beyond the view with the BACK encoder. The view scrolls as the cursor reaches the edge. Alternatively use the touchscreen to press on the keyboard and drag up and down 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 touchscreen widgets are enabled, pressing the touchscreen at the top right corner will display the transport controls. 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 context menu.

The MIDI channel used by the Pattern Editor will be chosen from the sequence / track from which it is launched, e.g. if you selected the first pad (without changing default settings) it should play on MIDI channel 1.

Thare are vertical white lines indicating the beats. The quantity of beats in the pattern may be adjusted from the context menu as well as the quantity of steps in each beat. This allows the duration and quantisation level of the pattern to be adjusted. Changing the beats in pattern will change the pattern duration. Chaning the steps per beat will change the pattern resolution.

Add some notes to form a melody and preview with the play function. Short press BACK will return to ZynPad.

6 Note Duration

So far we have only added note with a duration of one step. Within Pattern Editor bold press SELECT to enable adjustment of note parameters. The duration of a note may now be changed with the SELECT 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. Short press BACK to reeturn to normal note input mode.

7 Note Velocity

By default notes are added with a velocity (loudness) value of 100. (The range is 1 - 127.) Within pPattern Editor bold press SELECT to enable adjustment of note parameters. The velocity of a note may now be changed with the BACK 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 existing 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. The brighter the grid cell, the higher the velocity. Short press BACK to return to normal note input mode.

8 Adding Notes With External 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 SELECT encoder to the end of the range, i.e. below C-1 or above G9.

It is also possible to play live whist the pattern is playing in loop mode. Short press SNAPSHOT encoder to start loop playback then use MIDI controller to overdub the pattern. The same logic applies so playing a note that already exists will remove it.

9 Playing a sequence

ZynPad is the performance view. It shows each sequence as a _pad_. The pad has a colour and its name has a prefix (A-Z) representing its group and a number identifying its sequence number. Each pad triggers a different sequence. By default there are 16 sequences, 1-16.

Each pad has an icon indicating its play mode. The default mode is _Loop All_. This means the pad will play the whole sequence then wait unit the next sync point / bar before starting again.

Similar to how we navigate the cursor in the Pattern Editor we can move the cursor in ZynPad with the BACK and SELECT encoders. Move the cursor to the top left to highlight pad A1 (it is probably already there) then short press SELECT encoder to start playback of sequence A1. This can also be achieved with a touchscreen by simply tapping pad A1.

Playback of the pattern you created should start to loop. During playback a green right-ointing arrow shows on the pad.

Tempo may be adjusted using the SNAPSHOT encoder or by selecting "Tempo" from the context menu (if touchscreen widgets enabled).

Short press SELECT or tap the pad with the touchscreen to stop the sequence playing.

The playback indication icon changes to red to indicate it is stopping and then disappears to indicate it has stopped. Most play modes will continue to play the sequence until the next sync point. A sync point may be thought of as the start of a bar, indeed their spacing is set using the menu option _Beats per bar_.

Most play modes will wait until the next sync point before starting. If you start a sequence part way though a bar then it will show an orange _starting_ icon indicating it is waiting to start and will start at the end of this bar. This may also occur if a sequence length results in it stopping mid-bar in which case it may wait in _starting_ state until the next bar. (See section on Play Modes.)

10 Multiple Sequences

So far we have edited a single pattern in one pad's sequence. Let's add patterns to other pads. By default ZynSeq has 16 pads (sequences) each with a single track with its own pattern. User BACK and SELECT encoders to select pad A2 and bold press SELECT to show its 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 ZynPad.

Start pad A1: see its play icon showgreen and hear its sequence loop.

Start pad A2. Pad A2 shows an orange _starting_ icon but does not start to play yet. A1 pad's icon changes to red and continues to play. Red indicates sequence is playing but will soon stop. A2 pad icon change to green and start playing as A1 stops. The behaviour occurs because these pads are in the same group, "A" (see below).

11 Groups

Each pad belongs to a mutually exclusive group. This means that only one pad within the same group may play concurrently. Pads from other groups may play simultaneously. The group is indicated by the single letter prefix of the pad name. There are up to 26 groups, A-Z.

By default sequences are arranged in columns of groups with the first column being in group A, second column in group B, etc. and the last column being in group J. (This is because the default configuration also allocates MIDI channels 1,2,etc and 10 for last column which is traditionally used for percussion.) ZynPad tries to keep things simple with each sequence containing a single track and a single pattern. We will see later how this can be changed with Arranger. Following this simple workflow, a pad's MIDI channel may be set from the menu option _MIDI channel_. This also sets the pad (sequence) group. There are 16 colours used to indicate groups so that each MIDI channel may have a different colour.

If you start pad A1 then start pad B5 you will see that B5 shows orange _starting_ icon then green _playing_ when the next sync point is reached whilst A1 continues 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.

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.

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

12 Grid Size

By default ZynPad shows a 4x4 grid of 16 pads. The grid is always square, i.e. has the same quantity of columns as rows. The quantity of pads may be adjusted by selecting "Grid size" from the ZynPad context menu. The maximum quantity of pads is 64 (8x8).

Sequences are added or removed when the grid size is selected. Any patterns are not lost but may need to be reselected with Arranger (see later) when the grid size is increased. Beware that this may result in apparently new pads containing previously created patterns.

When the grid size is changed in ZynPad the sequences are reassigned groups and MIDI channels to create columns of mutually exclusive sequences. If this behaviour is undesired then use Arranger to adjust the grid size.

13 Sequence Modes

So far we have used the default mode for sequences which will loop the sequence until requested to stop at which point it will continue to play until the next sync point. There are many modes available which each offer features for different workflows / requirements. To change mode, select "Pad mode" from the ZynPad's context menu. This will allow change of mode of the highlighted sequence. The mode is indicated by an icon.

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.

All these modes affect how sequences stop. There are currently no modes that affect how a sequence starts. The first sequence to be started will start immediately. If any sequences are playing then all sequences will start at the next sync point.

14 Tempo

Tempo is the rate at which the sequencer plays back notes measured in beats per minutes (BPM). By default zynseq plays sequences at 120 BPM. Adjust Tempo with the SNAPSHOT encoder. The tempo is breifly displayed in the title bar. There is also a context menu option to adjust tempo which may be used on touchscreens. The current tempo is saved and loaded with each song.

15 MIDI channels

Each pad will play a sequence to a single MIDI channel. Several sequences may be assigned to the same MIDI channel. By default each sequence is assigned MIDI channel 1. Use the ZynPad's "MIDI channel" context menu option to set the MIDI channel of the currently highlighted pad.

16 Songs

All the configuration described above relates to a song. Zynthian supports 999 songs, each may have different quantity of sequences, etc. Songs are identified by an index 1-999. This can be selected from any ZynSeq context menu or directly by using LAYER encoder in ZynPad or Arranger views. The current song is shown in the topbar. Songs 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 but by default each pad in each song has a different sequence with different pattern. With 2000 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 Arranger context menu.

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

If any sequences are playing when changing song, they continue to play until a sequence in the new song is started. The tempo remains unchanged, i.e. the new song's tempo is ignored (only if playing when the song is selected). This allows seemless transition between songs.

17 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 SELECT 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 SELECT 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 SELECT 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 SELECT encoder then short press SELECT 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 SELECT. A confirmation message is displayed.

Sequence sets are also saved with snapshots.

18 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 the Master MIDI channel.

Each sequence may be triggered by a MIDI note. Select "Trigger note" from ZynPad's context menu to adjust the MIDI note that will trigger the highlighted pad. By default triggers are disabled. To disable a sequence from being triggered set its trigger value to None which is below C-1 or above G9, i.e. increase to maximum value. The trigger note is shown in brackets after the sequence name on the left of the Arranger, e.g. A1 (2, C4) indicates sequence 1 is triggered by note C4.

ZynSeq will 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. Tallies are sent on the Master MIDI channel.

19 Arranger

Each pad triggers a sequence which may contain one or more patterns. By default each sequence contains a single pattern but it is possible to create more complex arrangements by adding more patterns to the sequence. The Arranger is a view that allows the manipulation of sequences used by pads. The Arranger is accessed from the context menu.

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.

When the Arranger is first opened the first pattern (or time slot) of the sequence for the previously highlighted pad will be highlighted.

Navigation around the patterns grid is performed by rotating the BACK encoder to move up and down (select different pads) and the SELECT encoder to move left and right (select time). The currently highlighted cell is shown by a coloured outline called the cursor.

Short press the SELECT encoder or short tap on touchscreen will add or remove a pattern at the position of the cursor. This may take a little practice to place it where you want but you can press, drag and release to position it more accurately.

The pattern to be added is indicated by a number in the bottom left of the screen. This can be adjusted with the LAYER encoder or by clicking on the number / selecting "Pattern" from the context menu to show the parameter editor.

Each pattern is represented as a black block with its pattern number in white text. Bold press SELECT or press and hold touchscreen to open the Pattern Editor for the selected pattern. BACK will return to the Arranger.

Note that triggering a pad in ZynPad starts a sequence which consists of patterns which in turn consists of the notes of your melody. This hierarchical relationship may be slightly more complex than a typical step sequencer offers many benefits. Just remember that a pad triggers a sequence. A sequence contains patterns. A pattern contains MIDI events, e.g. notes.

19.1 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 Arranger:

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

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 SELECT encoder Add / remove patterns with short press SELECT Select pattern with LAYER encoder

20 Zooming

Within Arranger 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.

21 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 Arranger 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.

22 Metronome

TODO

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

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

25 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. Only events from a single MIDI channel are imported.

• Use webconf to upload a MIDI File Format file to the Captures area
• Select a pattern to import into
• Use Pattern Editor's context menu to set the beats in pattern, steps per beat, beat type and Input channel (the MIDI channel to extract)
• Select "Import" from the Pattern Editor context menu
• A list of MIDI files is shown
• Use SELECT encoder to highlight the desired file then short press SELECT 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.

26 Timebase

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.