Knob

{
  "registries": {
    "@pluginui": "https://pluginui.com/r/{name}.json"
  }
}

// Module face: recommended schema-bound dial. No caption behavior overrides.
import { FaceParamKnob } from "maruaudio/ui/shared/maru/module-face-controls"
<FaceParamKnob face={face} path="filter.cutoff" variant="flat"
  size={60} captionWidth={130} />

// Standalone controls: appearance and caption behavior are independent.
import { Knob } from "@/components/ui/knob"
import { KnobHeadless } from "maruaudio/ui/shared/knob-headless"
import {
  KnobmanVisualRendererProvider,
  type KnobmanVisualRenderer,
} from "@maruaudio/ui-kit/registry/lib/knobman-source"

// The host owns this adapter and may return null when the source is unavailable.
const renderKnobman: KnobmanVisualRenderer = (request) =>
  hostKnobmanRenderer(request) ?? null

<KnobmanVisualRendererProvider renderer={renderKnobman}>
  <Knob
    label="Cutoff"
    path="filter.cutoff"
    size="m"
    cursor="grab"
    min={20}
    max={20000}
    defaultValue={2200}
    curve="log"
    valueDisplay="hz"
    pizza="interaction"
    visual={{
      kind: "knobman",
      templateName: "Sonatom_red.knob",
      settingId: 2664,
    }}
    // Choose 1x, 2x, or 4x; the host also applies its bounded DPR policy.
    visualOptions={{ scale: 2, output: "frame", fit: "contain" }}
    onChange={(hz) => param.set("cutoff", hz)}
    onInteraction={() => audioContext.resume()}
  />
</KnobmanVisualRendererProvider>

// Arc-only treatment for a dense panel. The label swaps to the value while
// hovering or editing, so the control does not need a permanent readout.
<Knob variant="ring" label="Decay" labelPosition="top" min={0} max={4}
      defaultValue={1.8} trackScale={0.5}
      format={(seconds) => seconds.toFixed(1) + " s"} />

// The same geometry works for bipolar parameters. A marker is opt-in.
<Knob variant="ring" label="Pan" min={-1} max={1} defaultValue={0}
      bipolar indicator="dot" format={(value) => String(value)} />

// Persistent label AND value; split places label above and value below.
<Knob label="Cutoff" showLabelOnHover={false} labelPosition="split"
  min={20} max={20000} defaultValue={2200} valueDisplay="hz" />

// Explicit edit-only reveal: hover keeps the label. This is NOT the dial default.
<Knob label="Cutoff" valueReveal="edit" min={20} max={20000}
  defaultValue={2200} valueDisplay="hz" />

// Text-only defaults to both label/value; opt into hover/edit substitution.
<Knob variant="text" label="Tempo" min={40} max={240} defaultValue={120}
  unit="BPM" showLabelOnHover />

// Fixed type size with ellipsis, instead of the default caption compression.
<Knob label="A deliberately long parameter caption" captionWidth={100}
  labelCompressible={false} defaultValue={0.5} min={0} max={1} />

// Need a completely custom face? KnobHeadless keeps the same interaction,
// ARIA, host-parameter and MIDI/CC wiring while renderFrame draws the visual.
<KnobHeadless
  {...gestureProps}
  path="filter.cutoff"
  ccLabel="Cutoff"
  ccRange={{ min: 20, max: 20000, unit: "Hz" }}
  renderFrame={({ control, chrome }) => (
    <YourCustomKnob control={control} chrome={chrome} />
  )}
/>