# Connect MIDI CC controls

> Make face controls follow hardware controllers through the host's parameter and MIDI mapping system.

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

A hardware knob and an on-screen knob should change the same parameter.
In a Maru face, bind the control to its schema path. The host receives MIDI,
resolves CC assignments and sends the updated value back to the face.

## Bind the control once

```tsx
import type { AudioModuleFaceProps } from "maruaudio/contracts"
import { FaceParamKnob } from "maruaudio/ui/module-face-controls"

export function Cutoff({ face }: { face: AudioModuleFaceProps }) {
  return (
    <FaceParamKnob
      face={face}
      path="filter.cutoff"
      label="Cutoff"
      showLabelOnHover
    />
  )
}
```

The module schema must declare `filter.cutoff`. The bound control uses its
value, range, default and taper, and retains the path used by the host's MIDI
target system. A preset, a mouse edit and a controller movement all reach that
same parameter. You do not need a separate MIDI listener in the face.

For controls installed into another engine's interface, your host must supply
the parameter state and MIDI integration. A standalone visual knob does not
acquire MIDI devices or create a mapping system by itself.

## Choose a useful default

Add `defaultCc` to a parameter descriptor to suggest an initial assignment:

```ts
{
  path: "filter.cutoff",
  label: "Cutoff",
  type: "float",
  min: 20,
  max: 20000,
  default: 1000,
  taper: "log",
  defaultCc: 1,
}
```

CC 1 is the mod wheel; CC 7 is conventionally volume. Pick a musically useful
default and let the player change it. Keep the parameter's response curve in
its schema `taper`, so face travel, automation and MIDI agree. A mapping's
optional curve expresses an additional player preference.

## Map and verify in the host

In the browser module host or local workbench, enable your MIDI input from
the playback bar. Use a control's MIDI CC menu to learn an assignment, or
drag a CC source from the MIDI controls onto the target. **All mappings…**
opens the shared mapping editor for input/channel scope, range and other
binding settings.

Check that moving the hardware updates both the sound and the face, then
edit the same parameter with the mouse and recall a preset. Test persistence
in the host you intend to use: browser module state, rack state and a DAW
project have different save scopes.

## Check your delivery format

CC behavior depends on what the host delivers. Browser and workbench mapping
support ranges, curves and controller modes. VST3 hosts resolve CC through
parameter assignments and do not deliver the same raw CC stream; do not
assume every mapping option behaves identically across formats. Test the
exported plugin in the intended DAW as well as the browser preview.

For custom control gestures and host capabilities, continue with
[Module UI](https://maru.audio/docs/ui.md). See [check, build and export](https://maru.audio/docs/export.md)
for verifying an intended target.