Skip to main content

Module Preset Definitions (API 1.x)

warning

This describes how presets worked before the overhaul in the API 2.0.
If you are using the newer API, check the new presets page

Presets are a description of ready-made buttons that will be presented to the user in the Presets tab on the Buttons page. The user can then drag-and-drop the preset onto the button-grid, to build out config quickly without having to code it from scratch.

API call: setPresetDefinitions()​

In order to add presets to a module, you call this.setPresetDefinitions(presetsDefinitions) much like how you define actions and feedbacks.

Preset types​

Companion supports two types of presets

For the most part you will be defining button presets. See the linked documentation, above, for text presets.

Button preset definitions​

Presets are placed into categories, which show up as separate groups in the Companion admin UI. Other than that, the property-names for the button preset definition correspond to the nomenclature on the button definitions.

The only tricky part is that action-lists are nested inside steps, so you don't explicitly write "step 1", but rather the steps are determined by positions in the steps array. Inside the element of the array, the press action-list is labeled down:; the release action-list is labeled up:, see the Actions section, below for additional options.

The basic structure looks like:

   steps: [
    { // step 1
       up: [...],
       down: [...],
    },
    { // step 2
       up: [...],
       down: [...],
    },
   ]

Let's start with a minimal example preset button:

const presets = {}
presets[`my_first_preset`] = {
  type: 'button',
  category: 'Test', // This groups presets into categories in the ui. Try to create logical groups to help users find presets
  name: `My button`, // A name for the preset. Shown to the user when they hover over it
  style: {
    // This is the minimal set of style properties you must define
    text: `$(my-module:some-variable)`, // You can use variables from your module here
    size: 'auto',
    color: combineRgb(255, 255, 255),
    bgcolor: combineRgb(0, 0, 0),
  },
  steps: [
    {
      down: [
        {
          // add an action on down press
          actionId: 'my-action',
          options: {
            // options values to use
            brightness: 100,
          },
        },
      ],
      up: [],
    },
  ],
  feedbacks: [], // You can add some presets from your module here
}
this.setPresetDefinitions(presets)

Configuring a preset​

In addition to the minimal example shown above there are more properties that can be set.

You can see the full list of values that can be set and their valid values in the style object in the autogenerated documentation

Additionally, there are some behaviour options that can be set in the options object:

{
	/** Use relative delays between the actions executing (default = false) */
	relativeDelay: false,
	/** Auto-progress the current step when releasing the button (default = true) */
	stepAutoProgress: true,
	/** Enable rotary actions for this button (default = false) */
	rotaryActions: false
}

Actions​

The steps property is where the magic happens. This describes what the action will do when pressed. This used to be defined with actions and release_actions, but it has been restructured in 3.0 to give some new functionality.

In Companion 2.x it was possible to latch buttons, but now that can be achieved with steps. In the typical case a button will have a single step, which will give the behaviour of a normal button. You can make a latching button by defining a second step which does something different. By default, each time the button is released it will shift to the next step, this can be disabled by setting options: { stepAutoProgress: false } for the preset. This likely isn't very useful right now, due to it not being possible to use internal actions in presets.

You can add as many steps as you like, and build a button which runs through a whole cue list by simply pressing it. There are internal actions that a user can use to change the step manually.

Tip: You can build a preset for a rotary encoder by setting options: { rotaryActions: true }, and defining rotate_left and rotate_right actions on each step of your button:

steps: [
  {
    down: [],
    up: [],
     rotate_left: [
      {
        actionId: 'my-action',
        options: { },
      },
    ],
    rotate_right: [
      {
        actionId: 'my-action',
        options: { },
      },
    ],
  },
],

To define a duration group with a specific delay, you can set additional values inside a step with the delay in milliseconds as the key. This should contain the same structure as the up and down lists. See the example below as a reference:

steps: [
  {
    down: [],
    up: [],
    // Duration group that gets executed 2s after button release
    2000: {
      // Execute the actions after 2s while the button is held or only after it is released
      options: { runWhileHeld: true },
      actions: [{
        actionId: 'my-action',
        options: { },
      }],
    },
  },
],

Each action inside of the steps property can also have a delay property specified (in milliseconds).

tip

You can "simulate" an internal:wait action by adding the property delay: (in ms) to any action definition. This will cause it to execute after the delay, and is converted internally to internal:wait.

Feedbacks​

The feedbacks property allows you to define style changes using feedbacks from your module.

These look similar to actions, but a little different:

feedbacks: [
  {
    feedbackId: 'my-feedback',
    options: {
      channel: 1,
    },
    style: {
      // The style property is only valid for 'boolean' feedbacks, and defines the style change it will have.
      color: 0xffffff, // or combineRgb(255, 255, 255),
      bgcolor: 0xff0000, // or combineRgb(255, 0, 0),
    },
  },
]

The feedbackId should match a feedback you have defined, and the options should contain all of the parameters as you defined as the options.

Standard Colors​

Below are some color profiles for typical action and/or feedback combinations we recommend.

ColorRGB ValueText colorUsage
RED255,0,0White textSTOP,HALT,BREAK,KILL and similar terminating functions + Active program on switchers
GREEN0,204,0White textTAKE,GO,PLAY, and similar starting functions. + Active Preview on switchers
YELLOW255,255,0Black textPAUSE,HOLD,WAIT and similar holding functions + active Keyer on switchers
BLUE0,51,204White textActive AUX on switchers
PURPLE255,0,255White textPresets that need user configuration after they have been dragged onto a button

Icons​

There are some icons you can use that are part of the fonts.

GlyphHex Codefont sizeUsage
⏵23F544Play,Start,Go, TAKE
⏹23F944Stop, Halt, Break, KILL
⏸23F844Pause, Hold, Wait
⏯23EF44Toggle Play/Pause
⏺23FA44Rec, Save, Store
⏭23ED44Next, Skip, FWD
⏮23EE44Previous, Back, Rev
⏩23E944Fast FWD, Shuttle Fwd
⏪23EA44Fast Rewind , Shuttle rev
⏏️23CF44Eject, Unload
🔁1F50144Loop, Cycle
❄︎274444Freeze
⬆️2B0644Up
↗️219744Up Right
➡️27A144Right
↘️219844Down Right
⬇️2B0744Down
↙️219944Down Left
⬅️2B0544Left
↖️219644Up Left
🔀1F50044Transition
🔇1F50744Mute
🔈1F50844Unmute
⏻23FB44Power Toggle
⏾23FE44Power Sleep
⏽23FD44Power On
⏼23FC44Power Off
😱1F63144Panic

Further Reading​