Unified control syntax

[handeyeco]

Talking with the people on the Deluge Discord, there's an interest in creating a standard for the syntax that describes user interactions. The goals:

• Have a syntax that's computer readable and human maintainable
• Require all features to use this syntax as a form of documentation
• Use this syntax to create user-facing documentation

This site

This is basically what I've done on this site. For instance:

    {
      title: "Cycle default scales",
      command: "hold(SHIFT) press(SCALE)",
      views: ["synth", "midi", "cv"],
    }

• Pros:
  • Easy to write and maintain (the command itself is just a string)
  • Easy to render: each step is a control + action, relationship between steps is implied
• Cons:
  • Ambiguity: "hold(SHIFT) press(SCALE) turn(SELECT)" should I still be holding shift when I turn select?

Discord proposal

Another solution was proposed on the Discord:

{
    "features": [
        {
            "name": "In-Key layout",
            "description": "Play notes only in scale",
            "keywords": ["keyboard", "performance"],
            "video": "https://youtube.com/video/kQmqdpUeciY"
        }
    ],
    "ux": [
        {
            "name": "Scroll through layouts",
            "context": "keyboard_screen",
            "actions": [
                {
                    "name": "Scroll negatively",
                    "modifier": {
                        "button": "SCALE",
                        "type": "hold"
                    },
                    "actionKey": "SelectionScrollLeft"
                }
            ]
        }
    ]
}

• Pros
  • Able to be much more specific with the order of controls
• Cons
  • More complex to write and maintain
  • More complex to render: steps can now be interrelated

The manual

The manual takes somewhat of a middle ground:

Notes on the screenshot:

• The + sign indicates a combo
• There's contextual notes for the combo: "Left most grid button"
• There's an additional description

My proposal

I think wook's suggestion makes sense, although I might suggest something like:

const feature = {
  name: "Load sample (Silent)",
  description: "Load a sample into a kit of synth silently",
  views: [Views.Synth, Views.Kit],
  note: "Scroll to sample and press select. Also, Shift + Browse grid shortcut on an existing row to open browser.",
  steps: [
    {
      substeps: [
        {
          action: Actions.Hold,
          control: Controls.Shift,
        },
        {
          action: Actions.Hold,
          control: Controls.Audition,
        }
        {
          action: Actions.Press,
          control: Controls.Load,
        }
      ]
    },
    {
      action: Actions.Turn,
      control: Controls.Select,
    },
    {
      action: Actions.Press,
      control: Controls.Select,
    },
  ]
}

So I guess:

enum Action { HOLD, PRESS, TURN, TURN_LEFT } // ...etc

enum Control { SELECT, SHIFT, AUDITION, X, Y } // ...etc

enum View { SONG, KIT, MIDI, CV, SYNTH, CLIP } // ...etc

type Step = {
  action: Action,
  control: Control,
  note?: string,
}

type Combo = {
  substeps: Array<Step>,
  note?: string,
}

type Feature = {
  name: string,
  views: Array<View>,
  steps: Array<Step | Combo>,
  description?: string,
  note?: string
}

I'm a little worried about the added complexity, but I think as long as combos can't contain combos it should be fine.

Steps

• [x] Discuss and agree on a standard
• [x] Pick a couple of the more complex combos
• [x] Prototype a renderer that can handle the complex cases as a POC
• [ ] Introduce the requirement to the firmware code base
• [ ] Use the JSON from the firmware code base in the shortcut site

[handeyeco]

https://github.com/SynthstromAudible/DelugeFirmware/issues/856