% Synergy MIDI Tracker - Getting Started
% bsp
% May 31st, 2019
>>>
May 31st, 2019
<<<

$(var:header)

# Introduction

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


# 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](https://www.tobias-erichsen.de/software/loopmidi.html)
      -   Linux: `$ sudo modprobe snd-virmidi`
- recommended: a MIDI keyboard



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



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



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



# 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
1) assign meaningful names to MIDI controllers (e.g. CC#74 = "Flt1 CutOff")
2) 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).



# 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).



# Advanced: MIDIMap configuration

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

There are two MIDI maps:
1) the global MIDI map, which is active on every page of the application
2) 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.



# MIDI Scene configuration

Scenes are used for transforming incoming MIDI events to output events.
There are eight scene groups (A..H) which each contain 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 convience, 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.

NOTE: 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. 



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



# 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 recommend 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.



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



# 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 !



# 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".


# Last but not least

Don't forget about the [documentation](adoc/index.html) in the `adoc/` folder.

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