pnpm add @audio-ui/core
import { createKnobController, ANGLE_GAP_RAD, ARC_OUTER_RADIUS, arcPath, CENTER_DEAD_ZONE_MIN_PX, /* … */ } from "@audio-ui/core/knob";| Adapters | @audio-ui/react/knob, @audio-ui/elements/knob |
|---|
| Export | Kind | What it is |
|---|---|---|
createKnobController | function | A knob's behavior with no view attached: its value, held or controlled, every way of turning it, and what it looks like as a snapshot. |
KnobChangeEventDetails | type | What onValueChange receives with each change: the reason, the event behind it, and cancel() to refuse the change. |
KnobChangeEventReason | type | Why the value changed: "drag", "keyboard", "wheel", "input-change" (a typed value) or "reset". |
KnobCommitEventDetails | type | What onValueCommitted receives once a gesture ends: the reason and the event behind it. |
KnobCommitEventReason | type | Why the value was committed: the same reasons as a change. |
KnobController | interface | What createKnobController returns: the snapshot to draw from, and the press, keys, wheel, typed value and reset that turn it. |
KnobDragMode | type | How a drag turns a knob: up and down, around its centre, or by the turns of the pointer. |
KnobOptions | interface | The options of createKnobController: the value, held or controlled, its range, scale, steps and anchor, the drag mode, the formatting and the callbacks. |
KnobSnapshot | interface | What a view draws a knob from. |
ANGLE_GAP_RAD | const | Gap at the bottom of the dial: the sweep runs clockwise from bottom-left to bottom-right. |
ARC_OUTER_RADIUS | const | Outer edge of the arcs in the viewBox; each stroke is centered inside it. |
arcPath | function | SVG arc along the dial between two normalized positions (0…1). |
CENTER_DEAD_ZONE_MIN_PX | const | The smallest the hub's dead zone may be, in px, however small the knob. |
CENTER_DEAD_ZONE_REL | const | Circular drag: inside this fraction of the diameter the angle is synced but not accumulated, so crossing the hub doesn't jump. |
DEFAULT_ARC_STROKE_WIDTH | const | The width of the track and indicator arcs in the 48 by 48 view box, unless given. |
DOUBLE_TAP_MAX_MS | const | The longest two taps may be apart, in ms, to count as a double tap and reset the value. |
FINE_DRAG | const | Holding Shift turns the knob this much slower than the pointer moves. |
LARGE_POSITION_STEP | const | With a scale that is not linear, a large step (Shift or Page Up and Down) moves this share of the travel. |
LINEAR | const | The linear scale, resolved once. |
POSITION_STEP | const | With a scale that isn't linear, a key or wheel notch moves this share of the travel. |
pointerAngle | function | The angle of a pointer around the centre of rect, in radians, 0 pointing right. |
START_ANGLE | const | Rotation at min, in degrees clockwise from 12 o'clock. |
STATE_ATTRIBUTES_MAPPING | const | disabled, dragging and the drag mode become data attributes; the numbers stay in state. |
SWEEP_ANGLE | const | Rotation travelled from min to max, in degrees. |
steppedValue | function | The value direction steps away from current: by step (or largeStep) on a linear scale, by a share of the travel on any other, and always by at least one step. |
TAP_MAX_MOVE_PX | const | A press that moves less than this is a tap; two quick taps reset the value. |
VERTICAL_DRAG_RANGE_PX | const | Vertical drag: pointer travel, in px, for the whole min…max range. |
VIEWBOX_CENTER | const | Center of the 48×48 viewBox the arcs are drawn in. |
WHEEL_DELTA_EPSILON | const | A wheel movement smaller than this is ignored. |
Usage
The controller follows the contract every controller shares: create it once, draw from its snapshot, send it the input.
import { createKnobController } from "@audio-ui/core/knob";
const knob = createKnobController({ min: 20, max: 20000, value: 1000, scale: "log", format: { maximumFractionDigits: 0 } });| Option | Meaning |
|---|---|
value, defaultValue, min, max, step, largeStep | As for the fader |
scale | "linear", "log", or a function between 0 and 1 |
dragMode | How a drag turns into a value: "vertical", "circular" (the angle around the centre) or "revolution" (the turns of the pointer) |
anchor | The value the arc grows from, such as 0 on a pan knob |
format, locale, disabled | As for the fader |
A knob resets on a double tap and on Alt with a press, inside the controller: it has no reset gesture in the element. press(event, control) takes the control, the element that gives the angle; keyDown(event) returns true when it handled the key. The snapshot has the angle of the pointer, the percent and the anchorPercent, ready for an arc.
A vertical drag covers the whole range over 150 px (VERTICAL_DRAG_RANGE_PX), and Shift turns it four times slower (FINE_DRAG). On a scale that is not linear, a key or a wheel notch moves 1% of the travel (POSITION_STEP), so a log knob steps as evenly as it looks; steppedValue is that rule as a function.
Drawing the dial
The dial sweeps 288 degrees (SWEEP_ANGLE), clockwise from the bottom left, with its gap at the bottom. arcPath(radius, from, to) is the SVG arc between two positions from 0 to 1 in its 48 by 48 view box, and pointerAngle the angle of a pointer around the centre of an element.
The Knob draws this controller in React.