# Make controls accessible

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

Canonical: https://maru.audio/docs/accessible-controls
Documentation index: https://maru.audio/llms.txt

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](https://maru.audio/docs/customizing-plugin-ui.md)
and [connect MIDI controls](https://maru.audio/docs/connecting-midi-controls.md).
