Make controls accessible

Group, name and describe your plugin's parameters so faces, hosts, hardware controllers and screen readers present them clearly.

Your plugin's controls reach people in more places than its interface: a DAW's automation list, a generic plugin editor, the knob pages of a hardware controller and, for blind and low-vision musicians, a screen reader that speaks each name, group and value. All of them read the same parameter schema, so a few extra fields there make your plugin clearer everywhere at once.

Every field on this page is optional. A plugin without them works as before, and maru module check tells you what would help.

Group controls into sections

Add a sections tree to the schema and point each parameter's group at a section id:

ts
schema: {
  sections: [
    { id: "tone", label: "Tone", tier: "primary", children: [
      { id: "filter", label: "Filter", description: "Shapes the brightness." },
    ] },
    { id: "output", label: "Output" },
  ],
  params: [
    { path: "filter.cutoff", label: "Cutoff", group: "filter",
      type: "float", min: 20, max: 20000, default: 2400, units: "Hz",
      description: "Frequency above which the filter removes sound.",
      shortLabel: "Cut" },
    { path: "out.gain", label: "Gain", group: "output",
      type: "float", min: -24, max: 6, default: 0, units: "dB" },
  ],
}

Sections nest up to three levels. They change how controls are grouped, never the order of params, which is how hosts identify each parameter in saved automation. A group that names no section still works: it becomes a section of its own.

  • Name sections after what they shape, such as Filter, Envelope or Output. A screen reader announces the group with every control in it, so a name like Main or Parameters tells the listener nothing.
  • Order sections along the signal path: source, shaping, modulation, effects, output.
  • Keep about 3 to 12 controls in a section, and nest rather than growing one long list.

Name and describe each control

  • Keep labels short and specific, and do not repeat the section: "Cutoff" in Filter, not "Filter cutoff".
  • Keep labels unique within a section, so two controls never sound alike.
  • Add a shortLabel of up to 8 characters when the label is long. Hardware knobs and narrow host displays use it.
  • Give every time, frequency and level its units, and a 0 to 1 amount display: { format: "percent" }. "200 milliseconds" is clear where "200" is not.
  • Add a one-sentence description where the label alone does not say what happens. It becomes the control's accessible description and tooltip.

Choose what comes first

tier is primary, secondary (the default) or advanced, on a section or a single control. Mark the handful of controls people reach for first as primary and set-and-forget controls as advanced. Hardware controllers page primary sections first and advanced ones last, so on a large plugin the tier decides which controls stay a knob turn away.

Check the result

maru module check includes a parameter-layout row with a score from 0 to 100 and a list of findings, each with what to change. It never fails a check: the score is there to show what would make the plugin easier to use, and it improves as you add sections, units and descriptions.

Related: customize your interface and connect MIDI controls.