Unify Manual

Your complete reference to PlugInGuru's creative playground!

User Tools

Site Tools


param-paths

Parameter paths reference

Note: this information is subject to change in future versions.

Unify uses a systematic naming scheme for identifying parameters, which is based on “parameter paths” used in OSC. As in OSC, paths consist of a sequence of components separated by slash (“/”) characters, but unlike in OSC, there is no initial “/” at the start. (See also OSC Support in Unify.)

Basic concepts

Paths, Components, and Values

Each path distinctly identifies a parameter, which may be either a parameter of some plug-in instance, or something internal to Unify, that is to be changed. Changing a parameter can be thought of as sending a “message” consisting of the path (which identifies what is to be changed) plus a “value” (which specifies what it is to be changed to).

Presently in Unify, the value will always be a fraction, i.e., a real number between 0.0 and 1.0 (or if you will, 0 to 100%). The parameter receiving the value may interpret it in various ways, however, e.g.:

  • A filter cutoff parameter might map the range 0.0 - 1.0 to something like 0-20000 Hz
  • An “on/off” parameter like mute or solo might treat anything below 0.5 as “off” and anything above as “on”
  • Many plug-ins have “choice” parameters having a finite number of permissible values. These are often selected in the plug-in's GUI using a menu or a knob with fixed positions. Fractional input values are typically interpreted by dividing the total range 0.0 - 1.0 into equal segments, e.g. a synth might offer a parameter for controlling how a pair of filters are to be connected, with choices “off”, “series”, and “parallel”. Input values below 0.33 might be interpreted as “off”, between 0.33 and 0.67 as “series”, and above 0.67 as “parallel”.

Path validity

Most parameter paths in Unify refer to specific layers using a layer-number component, and many refer to individual plug-ins on the selected layer using a index-number component. Because the number of layers and plug-ins varies from one patch to the next, a given path might or might not correspond to an actual plug-in, and even if it does, the specific plug-in parameter named in the path might not be a valid one for that plug-in. Hence a path may be valid in some contexts, and invalid in others. Invalid paths are harmless; they simply don't do anything.

Path Categories

Unify's parameter paths fall into three categories, based on the first component:

  1. Top-level paths begin with “unify”
  2. Macro paths begin with “macro”
  3. Layer paths begin with “midi”, “inst”, “aux”, or “master”

Top-level paths

Starting with Unify v1.6.0, the syntax of “top-level” paths has been reworked to be more rational and consistent with other parameter paths.

  • variation selects currently-displayed patch variation.
  • inst/<layer#>/mute replaces unify/<layer#>/mute.
  • inst/<layer#>/solo replaces unify/<layer#>/solo.
  • inst/<layer#>/midiEnable replaces unify/<layer#>/midiEnable.
  • inst/<layer#>/midiToggle replaces unify/<layer#>/midiToggle.

These new parameters also appear in parameter-path menus to make them easier to select. (Note the older top-level paths beginning with with unify/ still work, for compatibility with older patches).

All of these are binary parameters. Values 0.5 or greater are treated as “on”. midiToggle is a special case: values 0.5 or greater toggle the layer's MIDI enablement, lower values are simply ignored. This is for compatibility with external MIDI CC controls, which may send a high value when pressed and a low value when released: pressing triggers the action, release does nothing.

Macro paths

Paths beginning with macro and followed by a natural number identify one of Unify's macro parameters.

  • macro/<macro#>

Note these can't be used directly as links on macro knobs, i.e., a macro knob cannot link directly to itself or another macro knob in the same Unify instance. They are mainly intended for use in MIDI Controller Files.

Macro knobs can, however, link to a macro control of an embedded Unify instance, by referring to the parameter-name (Macro1, Macro2, etc. or equivalent custom names in Unify v1.6.0 and later) in a layer-specific path; see below.

Layer-specific paths

The majority of parameter paths used in Unify are layer-specific; they begin with on or more components which select a specific layer in the current patch (e.g. “inst/1”, “aux/2”, or “master”). Among these, only master/volume identifies a single parameter. All the others use additional components which further refine the selection of individual parameters specific to that layer.

  • midi/<layer#>/[MIDI Layer params]
  • inst/<layer#>/[INST Layer params]
  • aux/<layer#>/[AUX Layer params]
  • master/volume
  • master/[AUX Layer params]

The MIDI, INST, and AUX/MASTER parameters use additional path components (sub-path), whose validity may depend on the type of layer, as follows:

sub-path MIDI INST AUX MASTER
midiEnable x x
midiToggle x x
mixLevel x x x
panPos x x
directSend x
auxSend/<aux#> x
plugin/[Plug-in params] x x
effect/<eff#>/[Plug-in params] x x x
midiEffect/<eff#>/[Plug-in params] x x

Plug-in parameters

Individual plug-ins on all layers can be controlled by paths ending in “[Plug-in params]” in the table above. Starting with Unify v1.7, MIDI effect plug-ins must be referred to using “midiEffect”; in earlier versions “effect” could be used, but this is now reserved for audio-effect plug-ins only.

In general, plug-in parameters are the parameters which each individual plug-in exposes for host automation. Unify v1.7 introduced the concept of “special” plug-in parameters, which always begin with the underscore character (“_”); the first of these is “_bypass”, which allows controlling whether or not individual plug-ins are bypassed. Examples:

  • midi/1/midiEffect/2/_bypass bypasses the 2nd MIDI-effect plug-in on the MIDI1 layer
  • inst/2/midiEffect/1/_bypass bypasses the 1st MIDI-effect plug-in on the INST2 layer
  • inst/5/effect/3/_bypass bypasses the 3rd audio-effect plug-in on the INST5 layer

Whether setting the value of these _bypass parameters via macro-knob links or by OSC, setting the parameter value to 0.5 or greater bypasses the plug-in; values below 0.5 un-bypass it.

param-paths.txt · Last modified: 2023/05/08 18:59 by 127.0.0.1