reaticulate

an articulation management system for REAPER

Reaticulate notations for Reabank files

In the alpha preview of Reaticulate, there is no GUI for creating custom banks. It'll come, but for now, you'll need to understand the nitty gritty on this page.

Reaticulate directly manages REAPER’s assigned global Reabank file, which it dynamically assembles from both the distributed factory banks and your own custom banks. Relative to REAPER’s resource directory (which you can find by invoking the REAPER action “Show REAPER Resource path”), these files are:

  1. Factory banks: Scripts/Reaticulate/app/Reaticulate-factory.reabank
  2. User banks: Data/Reaticulate.reabank

(Reaticulate combines these files into a file it manages called Data/Reaticulate-tmp*.reabank. You’ll never edit this file directly, but it’s what Reaticulate feeds back to REAPER to use as the default reabank file.)

floating You can take a look at the factory banks for inspiration, but if you want to start slinging your own custom articulation banks, the easiest way is to click the pencil button at the top of the UI and open the file in your editor. Clicking this will create the file if necessary before opening the editor. Open in Default App will launch whatever application you’ve associated with .reabank files.

Once you save changes to the file, click the reload button (next to the pencil) to force Reaticulate to pick up the changes.

Anatomy of a standard Reabank file

Let’s take a look at the normal REAPER reabank file. The standard format is:

Bank <MSB> <LSB> <Bank name>
<program #> <articulation name>

For example:

Bank 65 1 Spitfire Symphonic Brass - Horn Solo
20 legato
1 long
52 marcato
50 tenuto
40 staccato
100 rip
101 fall
70 trill m2
71 trill M2

The two numbers on the Bank line indicate the MSB and LSB of the MIDI bank. These values are between 0 and 127 and are somewhat arbitrary, as long as the pair is unique to the REAPER instance. Following that is an arbitrary name for the bank.

User banks must use MSBs from 0 to 63. MSB of 64 and above are reserved for factory banks.

Each subsequent line (until the next Bank line) specifies the programs for the bank. The number is the MIDI Program Change event number (which is technically arbitrary but see the Program Numbers section below for some advice), and the description is, in our case, the name of the articulation.

Reaticulate notations

Reaticulate extends Reabank files by adding special notations on lines starting with //!

Let’s revisit the above example bank, now notated for Reaticulate, and how this bank looks in the GUI:

floating

//! g="Spitfire/Symphonic Brass" n="Horn Solo"
//! m="Set patch to UACC"
Bank 65 1 SSB - Horn Solo
//! c=legato i=legato o=cc:32,20
20 legato
//! c=long i=note-whole o=cc:32,1
1 long
//! c=short i=marcato-quarter o=cc:32,52
52 marcato
//! c=short i=tenuto-eighth o=cc:32,50
50 tenuto
//! c=short i=staccato o=cc:32,40
40 staccato
//! c=short-dark i=rip o=cc:32,100
100 rip
//! c=short-dark i=rip-downward o=cc:32,101
101 fall
//! c=long i=trill-min2 o=cc:32,70
70 trill m2
//! c=long i=trill-maj2 o=cc:32,71
71 trill M2

Notated attributes take the form name=value (or name="value" if the value contains spaces) and are separated by whitespace. The line(s) prefixed with //! immediately preceding the uncommented line will annotate it with the supplied attributes.

When an articulation is triggered, Reaticulate will emit the MIDI output events defined by the o attribute (see below). In the above example, each articulation sends a single MIDI event: CC 32 with a value defined by the second argument. The expectation for this factory bank is that the Spitfire Horns Solo patch be set to UACC (a feature of the patch itself).

Attributes for Bank lines

These are the supported attributes for Bank lines. Attributes are optional unless specifically marked as required.

NameDescription
g
required
Group name separated by slashes. Used to build a menu hierarchy for the bank. Generally should be Vendor/Product.
n The name of the patch the bank describes. If not specified, the Reabank name is used.
clone Clones the articulations in the specified fully qualified bank name (which is groupname/bankname).
off For articulations with note-hold outputs, this defines the "default program" when no note-hold articulation is active. The GUI will show this program as active when a manually triggered note-hold keyswitch is released. When this articulation is explicitly activated via Reaticulate, it will cause any active note-hold articulation to be released.
f Default articulation flags. Most can be overridden per articulation. Is a comma-delimited list of one or more of the options below. Any option can be prefixed with ! to negate it.
  • chase: Chase CCs when target MIDI channel changes. (Default)
  • antihang: Prevent note hanging when a note is released on a different channel than it's pressed. (Default)
  • antihangcc: Similar to antihang, but prevents the note from hanging due to sustain pedal or breath control (CC 2 and 64). In other words, it ensures sustain release or breath off is sent to the channel where the ringing note was struck, regardless of the current routing. (Default)
  • nobank: Blocks the bank select messages generated by Reaticulate from hitting the downstream FX. (Default. Bank level only.)
  • toggle: Triggering the articulation when it's active will deactivate it. It will still emit the output events but the UI will indicate the articulation as off if it was previously on.
  • hidden: Articulation will not be visible in the UI.

Attributes for Program lines

And programs can be decorated with these attributes:

NameDescription
i
required
Articulation icon name. See Articulation Icons section below for possible names.
n Overrides the articulation name for display in the articulation list in the Reaticulate UI. Program events as seen in the MIDI editor will use the program name specified on the uncommented line.
c Color for the articulation button. Either the name of a color (see the Articulation Colors section below) or an HTML hex-style color in the form #rrggbb
f Articulation flags as defined above. (Overrides the defaults set at the bank level.)
g A group number between 1 and 4 (defaults to 1 if not specified). Only one articulation within a group may be active at a time.

For consistency, it is recommended that you use group 1 for the main set of articulations.
o One or more output events that describe the action taken when the articulation is triggered.

This is where things get fun. See the Output Events section below for the gory details.

Program Numbers

Although the program numbers are arbitary and don’t influence any specific behavior, some form of standardization is recommended because this allows using the Reaticulate_Activate articulation by CC actions to trigger a given articulation (or at least its closest approximation) from a control surface, tablet, etc., no matter the underlying instrument.

Reaticulate's factory banks will conform as closely as possible to Spitfire's UACC specification.

So, for example, by consistently using program 42 to map to spiccato, or some similar very short articulation, you could have a control surface send CC value 42 (via a CC number of your choice bound to the Activate Articulation action) to set spiccato, no matter what track is selected.

Output Events

Programs can trigger up to 16 output events, specified by the o attribute, which ultimately describe the articulation’s behavior.

Output events can be used to send a MIDI event to the virtual instrument to cause the underlying patch to change articulations, or even just to set up routing to some destination MIDI channel. Or both: you can have a program send a MIDI event to a specific channel, and subsequently performed MIDI will be routed to that channel.

Multiple output events are separated by a / (forward slash) where each individual output event takes the form type@channel:arg1,arg2 (no whitespace allowed).

Possible output event types are:

Type Definition
program Program change message. arg1 indicates the program number and arg2 can be omitted.
cc A CC event, with arg1 indicating the CC number and arg2 defining the CC value
note A sequence of note-on and note-off events, where arg1 defines the note number and arg2 indicates note-on velocity. arg2 is optional and if not specified the default velocity is 127.
note-hold A note-on event, where arg1 and arg2 are according to the note type. The corresponding note-off event is deferred until the next articulation is activated. This is useful with patches that use non-latching keyswitches.

The type can also be empty, specifying just @channel, in which case the action of the articulation will just be to set up routing to the destination channel specified, with no MIDI event emitted.

Ok, with the technicals out of the way, here are some examples.

Multiple notes

This one from Cinematic Studio Strings sends 3 separate notes at specific velocities to set sordino and legato in addition to the sustains patch.

//! c=long-light i=con-sord o=note:12/note:22,1/note:23,127
7 con sordino

Simple channel routing

A generic example where we have 3 individual articulation patches on 3 separate MIDI channels and we want to do simple routing only: no keyswitches needed by the underlying virtual instrument.

//! c=legato i=legato o=@1
20 legato
//! c=long i=note-whole o=@2
1 sustains
//! c=short i=staccato o=@3
40 staccato

One-off layering

Here’s another one from Cinematic Studio Strings, setting up spiccato without sordino. The twist is the “beefy spiccato” program, where we are setting CSS as with spiccato but also layering it with another patch on channel 2.

//! c=short i=spiccato o=note:17,1/note:23,1
42 spiccato
//! c=short-dark i=spiccato o=note:17,1/note:23,1/@2
44 beefy spiccato

Both non-latching and latching articulation keyswitches

Now for a more sophisticated example: an excerpt from the Bohemian violin bank. This instrument controls legato by a single note toggle keyswitch (hitting the same note repeatedly toggles legato), so this is in its own group.

Most of the articulations in the Bohemian are only active while the note is held, and once the note is released, it defaults back to an intelligent, adaptive mode which VirHamonic calls the Performer. So the trick here is to specify an off program for the bank (we arbitrarily choose 0) which describes the default mode of the Bohemian when no articulations are explicitly chosen.

Finally, the last 3 programs define the Performer styles, and unlike the others, these ones are latching keyswitches, so we use the note type for these.

//! g="VirHarmonic/Bohemian Violin" n="Expansion 1" off=0
Bank 42 7 Bohemian Violin Exp1
//! c=long-dark i=note-whole g=2 f=toggle o=note:35
35 chords

//! c=long-light i=phrase o=note-hold:0
0 performer
//! c=long i=note-half o=note-hold:24
24 arc
//! c=long-light i=legato-bowed2 o=note-hold:41
41 rebow

//! c=fx i=phrase g=3 o=note:48
48 improv
//! c=fx i=phrase g=3 o=note:49
49 czardas
//! c=fx i=phrase g=3 o=note:50
50 emotive

Articulation Colors

floating

The c program attribute defines the color of the button for the articulation, which is either a HTML color code or one of the predefined names. When c isn’t specified, then the default color is used.

The image right shows the available names and their out-of-the-box colors.

(The icons shown are just for demonstration purposes. The color selection has no bearing on the icon. That’s defined by the i attribute.)

The factory banks use the light variants for articulations played more softly or subdued than normale, for example con sordino, sul tasto, or harmonics. The dark variants are used for grittier, distorted, or louder articulations, such as sul ponticello or Bartok pizzicato.

These color names can be overridden by specifying a color attribute anywhere in your user Reabank file (path #2 listed at the top of this page), whose value is a comma-delimited list of name=#hexcode items. For example, this line overrides the default and fx colors:

//! colors=fx=#00ff00,default=#ff00ff

Articulation Icons

Here are the current icon names that may be assigned to the i attribute:

scaled