1 Introduction

This is a brief quick-start guide for first time users:

2 Prerequisites

x64 Windows or Linux OS
OpenGL 2.x GPU (or better)
a MIDI synth
- alternatively, use a virtual instrument host (e.g. a DAW) via MIDI loopback
  - Windows: install loopMIDI
  - Linux: $ sudo modprobe snd-virmidi
recommended: a MIDI keyboard

3 Preparation (directories)

Copy the synergy_data/ folder (including the presets/ and projects/ sub directories) to a place where you usually keep your work data.
On Windows, this could be something like f:/synergy_data/.
On Linux, this could be ~/synergy_data/.
These directories will store your personal data so make sure to include them in your backups.

4 Program Start

On Windows, run synergy.exe to start the application.
On Linux, run ./synergy.

LINUX: In case some of the keys (e.g. ` (us) / ^ (de)) are not working, make sure that a keyboard layout other than "system default" (in XFCE) is selected.

5 Directory configuration

Once the application is running, click Prefs in the top-left window corner.

Set the Project dir so it matches the location of your synergy_data/projects/ work directory.

6 Device Setup

The first order of business is to setup the MIDI input and output devices you want to use.

Go to the MIDI Devices page (click Devs in the top left corner of the window).
The page will list all available input and output devices.

For each device you want to use, tick the Use checkbox.

Double click a device row to edit the device details.

It is highly recommended to assign an alias name to each device.

For example, if you have a USB synth that provides an input device named mysynth in, and an output device named mysynth out, you should assign the alias mysynth to both the input and output device.
Make sure that in the mysynth in input device settings, Out.Device is set to mysynth.

One important thing to keep in mind is that each MIDI input device must be mapped to an output device to be able to use it.
If the Echo checkbox is ticked, all incoming events will be forwarded to the corresponding output device (which should then have its "local mode" set to off).

The Channel Profiles are used to

assign meaningful names to MIDI controllers (e.g. CC#74 = "Flt1 CutOff")
assign patch editors to MIDI devices (e.g. Korg Radias, Matrix 1000, DSI Prophet 12, Roland MKS 50, ..)

In case there's a profile for your particular synth does not exist, yet, you can create one. Take a look at the text files in the midi_synth_profiles/ directory.

Last but not least, don't forget to save your new configuration by either pressing "esc", then Save configuration, or click on Prefs, then choose Save configuration.

On Linux, the configuration will be saved to ~/synergy_config.tks.
It's a text file which can also be edited manually (if you know what you are doing).

7 Metronome configuration

In case you want to use the builtin metronome feature, go to Prefs, click on the Metronome tab, then select the MIDI device, channel, and Bar / Beat notes for the metronome.

The metronome is toggled by pressing F12, or via the Stop button hold-click menu (hold-click the bottom-right button).

8 Advanced: MIDIMap configuration

Many of the program's functions can be remote controlled with MIDI devices.

There are two MIDI maps:

the global MIDI map, which is active on every page of the application
page / context specific MIDI maps

The global MIDI map is edited by clicking the MIDIMap(g) button in the the (top) toolbar area.

Page / context specific MIDI maps are edited by first selecting the context (e.g. a Tracker node), then clicking the MIDIMap(c) button in the (top) toolbar area.

Keep in mind that the MIDI map feature requires suitable MIDI profiles to be selected for your MIDI controllers (these, among other things, define which controls are buttons, knobs, or rotary controllers).

MIDIMap configurations are stored in the project file, not the global configuration.

If in doubt, skip this step for now.

9 MIDI Scene configuration

Scenes are used for transforming incoming MIDI events to output events.
There are eight scene groups (A..H), each containing 16 scenes (1..16).
Scene A1 has the highest priority, and Scene H16 the lowest. I.e. events consumed by A1 will not be processed by H16.
The F3/F4, F5/F6, F7/F8, F9/F10 keys are used to change the active scene for groups A..D.
By holding the left ALT key, the active scene for groups E..H can be changed.
Last but not least, there are 16 "multi-scene" setups which can be used to quickly change the active scenes for all groups (the lctrl-x NUMPAD 0..9 keyboard shortcuts select one of the first 10).

For example, if you have three synths and one master keyboard, you could create three scenes that map the master keyboard's input events to one of the three synths.
By using one the Input / Source source filter and Output / Target transform mode (click on the arrows to expand them), it is possible to transpose the keyboard or create splits where each zone redirects the incoming notes to different devices.

Another use for scenes is to redirect MIDI knobs and faders to specific synth parameters, or program-internal node parameters (via the internal virtual MIDI devices play_a .. play_d).

For reasons of convenience, the Tracker sequencer node automatically redirects incoming MIDI events (note on/off and common performance controllers like pitchbend, expression, breath control, foot pedal, sustain pedal, sostenuto pedal) to the currently selected tracker instrument.

MIDI Scene configurations are stored in the project file, not the global configuration.

Selecting a scene will cause an RPN MIDI event to be sent to the midimorph_scene_selection_device (default=<global>). This feature can be used by script nodes (for example) to update their configuration. An example for this is the Linnstrument Arranger script preset.

10 Pipe and Node basics

Since this is also described in the regular documentation, I'll keep this one short.

A sequencer project consists of an arbitrary number of pipes.
Each pipe contains an arbitrary number of nodes.
Nodes process and / or generate MIDI events.

The very first pipe (usually named master) has a special meaning since

its output will be sent to all other pipes
its output will not be sent to actual MIDI outputs (i.e.: don't put a sequencer node in there!)

The first pipe usually contains an Arranger node, which controls the (sequencer) nodes in the other pipes.
It may also contain additional utility nodes which process incoming MIDI events (e.g. for fixing jittering foot pedals).

Each node has two automation ports (A + B), which can be configured in the node's Play tab.
Usually the automation port is set to an internal (virtual) MIDI device (play_a..play_d).

Additionally, when a node's Show in Arranger checkbox is ticked, the node will show up in the selected arranger(s).

Most of the nodes support common functionality like mute, unmute, pattern select, and seek.
There's a chart in the regular documentation that shows which remote-control features each node type supports.

While pattern select is usually controlled via MIDI program changes, most of a node's remote control features are implemented via RPNs (registered parameter name) events.
The internal MIDI synth profile (midi_synth_profiles/internal.msp) should be assigned to all internal / virtual MIDI devices.
Note that certain remote control features are specific to certain node types.

The most advanced sequencer node type is the Tracker node. Don't let the name fool you, this has nothing to do with fixed-grid trackers from the 80ies. It supports arbitrary timing resolution, multiple notes per track, configurable controller cels, and so on. It basically works like any other real MIDI sequencer, except that it uses a tracker-like UI for displaying / editing the MIDI events.

11 Tips & Tricks (Tracker node)

The easiest way to initialize / set up a Tracker node is to record the notes and controllers you want to use into a Monitor node, then creating a new Tracker node and importing the recorded Monitor pattern into it. This will automatically create the required tracks, instruments, and controller cels. The monitor pattern can be imported by copying it to the clipboard (lctrl-c), then selecting / creating the tracker node and pressing lctrl-lshift-f9 (or choosing Pattern → Import → Import from Monitor (multitrack).
In a Tracker node, it is highly recommended to record note durations instead of separate note off events. Make sure that Record CTL_DURn is selected in the Events pulldown menu.
When recording realtime events into a Tracker node, you will notice that there is no dedicated pre-count recording feature. Instead, move the cursor to the start of the last bar of the pattern and press lshift-SPACE to set the play / record offset. Remember to set it back to the first step later on.
During realtime recording (rshift shortcut), press RETURN to undo the last take and restart recording (synchronized to bar start)
The easiest way to add controllers to a Tracker instrument / controller cels to a pattern is to go to the instrument editor, right click the Instrument Parameters table, and pick one of the Import options (e.g. Import Performance Ctls (MW,Pitchbend)).
While each track in a Tracker node is limited to five note cels, you can simply add another track and tick the Spread checkbox on the Play tab. This will automatically distribute recorded notes to multiple tracks.

12 Tips & Tricks (general)

It is usually recommended to separate note and controller data. For example, while your note pattern may only consist of 16 steps, the associated controller data (e.g. modwheel) may span 8 bars. Simply create another node and assign the same MIDI output. Remember that nodes can be cloned on the PipeMap page by pressing lshift-INSERT or choosing Clone node from the node context menu (RMB click).
For certain music styles it is useful to separate note and timing data. The TrigSeq and Tracker nodes can be set to external clock mode (Ext.Clk checkbox on the Play tab). Make sure the extclk node has an active automation port (e.g. <Scratch>), then place another sequencer node in front of the extclk node and make it send Com: Clock, Com: Gate and / or Com: Clock + Gate events to the extclk's node automation port. This can be used to mimic classic configurations like the "TR808 rimshot output into a Juno 60 arpeggiator clock input". It's also possible to use ratcheting via the Com: Retrig RPN.
Keep in mind that this application is designed for (very) fast workflows. You should connect a regular, full-size computer keyboard to be able to use all available keyboard shortcuts effectively. Also keep in mind that all node and pipe setups can be saved as presets.
An active (unmuted) Monitor node will record everything you play into a (very large) ringbuffer. This can be handy to capture / preserve those "happy accidents" which happen every now and then.
Monitor nodes can be used to save and restore synth-specific SysEx data. It is recommended to use one Monitor node instance per synth. To backup a synth's patch(es), clear the Monitor pattern (click Clear), then initiate a SysEx dump on the synth. To restore a synth's patch(es), e.g. after loading a project, click the Play button in the Monitor node to send all SysEx events back to the synth.
When you create a new project by clicking New.. on the project page, the application will attempt to load a project template (project_template.flx). You should spend some time to create a personalized template so you won't have to repeat the pipe/node and MIDI scene + map setup each time you start working on a new song.

13 About file dialogs

The file dialog in this application is a bit unusual.

One important thing to remember is that pressing DOWN (or clicking the RMB) will open an additional dialog that shows all file entries (regardless of their subdirectory location) which match the current file name string.
You can search for file names, file dates, and even file sizes.

Directories can be changed by typing in the directory name and pressing enter, or by selecting the directory in the DOWN key / RMB dialog.

/ refers to the project root directory, not the system root !

14 Auto-saving

While the replay is not currently running, the application will automatically save backup files to the projects/autosaves/ folder. The interval can be configured on the Prefs page (default = 5min).
The files are named synergy_autosave_0..n.flx (auto-cycled).

While I have honestly never lost any work so far myself, I would still recommend to keep the autosave feature enabled "just in case".

15 Last but not least

Don't forget about the documentation in the adoc/ folder.

In case you need additional support or want to report a bug, you can reach me on gearslutz.com or kvraudio.com (user "bsp804").

Document:	Synergy MIDI Tracker - Getting Started
Author:	bsp
Date:	May 31st, 2019