API 2.2 (Companion 5.1+)

API 2.2 builds on API 2.1 with a handful of additions, mostly to presets. If you use TypeScript, check the value feedback typings change when updating.

TypeScript: value feedback schemas declare their result type

When strongly typing your feedbacks, a value feedback's schema must now include a result property, describing the type its callback returns. The callback is then type-checked against it.

Before:

type FeedbacksSchema = {
  channel_level: {
    type: 'value'
    options: {
      channel: number
    }
  }
}

After:

type FeedbacksSchema = {
  channel_level: {
    type: 'value'
    options: {
      channel: number
    }
    result: number | null // now required for value feedbacks
  }
}

const feedbacks: CompanionFeedbackDefinitions<FeedbacksSchema> = {
  channel_level: {
    type: 'value',
    name: 'Channel level',
    options: [{ id: 'channel', type: 'number', label: 'Channel', default: 1, min: 1, max: 64 }],
    callback: (feedback) => myDevice.getLevel(feedback.options.channel), // must return number | null
  },
}

If you don't want to narrow the type, use result: JsonValue.

This is a TypeScript-only change. It has no runtime impact, and boolean and advanced feedback schemas are unchanged. It mirrors the result property that actions gained in API 2.1.

Presets: store action results in local variables

Actions which return a result can now have that result stored into one of the button's local variables, directly from a preset. Add a storeResult to the action entry, naming a simple local variable declared on the same preset:

presets['show_level'] = {
  type: 'simple',
  name: 'Show level',
  style: {
    text: 'Level\n$(local:level)',
    size: 'auto',
    color: 0xffffff,
    bgcolor: 0x000000,
  },
  steps: [
    {
      down: [
        {
          actionId: 'read_current_value', // an action with `hasResult: true`
          options: { channel: 1 },
          storeResult: { type: 'local-variable', variableName: 'level' },
        },
      ],
      up: [],
    },
  ],
  feedbacks: [],
  localVariables: [
    {
      variableType: 'simple',
      variableName: 'level',
      startupValue: '',
    },
  ],
}

This works in simple and layered presets. When typing your presets with your module's types, storeResult is only accepted on actions whose schema declares a result.

Presets: notes

Presets can now define notes, which are copied to the button when the user places the preset. Use this to describe the purpose of the button, or to give the user any setup information they need:

presets['route_output'] = {
  type: 'simple',
  name: 'Input X to Output Y',
  notes: 'Change the `input` and `output` local variables to choose the route.',
  // ...
}

notes is available on both simple and layered presets.

Colours as CSS strings

Everywhere a module provides a colour, it can now use a CSS colour string instead of a packed RGB number. For example, '#ff0000' and 'rgb(255, 0, 0)' are both equivalent to 0xff0000.

This applies to:

• the color and bgcolor style properties, in simple presets, boolean feedback defaultStyle, boolean feedback styles in presets, and the values returned by advanced feedbacks
• the colour properties of graphics elements (color, outlineColor, borderColor, markerColor, and the color of gauge stops)

style: {
  text: 'Stop',
  size: 'auto',
  color: '#000000',
  bgcolor: 'rgb(255, 0, 0)',
},

Packed numbers (0xff0000 or combineRgb(255, 0, 0)) continue to work, and you can mix both forms freely. The new CompanionColorValue type (number | string) describes either form.