Action Value Bindings

Use a trigger's movement or value to control an action's numeric field: volume, brightness, MIDI values and more, without scripting.

Create a binding

1. Add an action under While Moving, While Pinching/Rotating, a continuous trackpad direction, or Drag … (Continuous) for a mouse button.
2. Click the link icon beside a supported numeric field and enable Use the swipe value, Use the drag value, or the equivalent.
3. Choose How to change the value, set the Output range, then click Done.

No link icon? Check that the field supports numeric bindings and the category supplies a value. Gesture Begin does not. Click the icon again to edit or Remove Binding.

Choose the source

Mode	Behavior
Increase / Decrease Value	Adds signed movement to the current or remembered value. Reversing direction reverses the change. Default for new continuous trackpad and mouse-drag bindings.
Set Value Directly	Maps the trigger's value to the output range. For fluid gestures/drags, this is 0–100 stroke progress; for MIDI/sliders, their current value. Default for other sources.

Saved bindings keep their mode. Trackpad stroke progress restarts when direction reverses; Increase / Decrease Value continues from the current value. With Linear, up/right, pinch out and counterclockwise rotation increase the value; the opposite directions decrease it.

Advanced modes

• Position (0…1) maps normalized position to the output range.
• Change Since Last Update maps the signed delta. It does not accumulate movement or read the target setting. Mapping, curves and clamping still apply, so negative deltas can map to the lower output bound.

Mapping and sensitivity

• Output range: values sent to the action, e.g. 0 … 100 volume or 0 … 127 MIDI.
• Curve: Linear, Inverted, Logarithmic or Exponential.
• Round: use To Whole Numbers for MIDI values.
• Keep within the target range: limits the result to your range.

Increase / Decrease settings

Movement for the full range controls sensitivity: larger means more movement. Defaults are 40% of trackpad for swipes/edge slides, 50% magnification for pinch, 90 degrees for rotation and 200 px for mouse drags. Leave Wrap around at the ends off for volume/brightness.

This binding setting is separate from the trackpad trigger's full-range setting, which controls direct stroke progress.

Starting and remembered values

For system output/input volume and display/keyboard brightness, BTT reads the current setting when you use the control again. Other targets start halfway through the range before applying the curve, then remember the last sent value until BTT restarts. External changes cannot be read back automatically.

Trackpad bindings remember values separately per action/category: use one While Moving action for both directions. Matching mouse-drag fields under one button trigger share their remembered value across directional actions.

Example: send MIDI values from a gesture

Add Send MIDI Command to the movement category and configure its destination, channel and controller. Bind the desired value field with Output range 0 … 127, Linear, To Whole Numbers, and range limiting enabled. Leave other fields fixed.

Use one While Moving action for trackpad control, or matching actions in both mouse-drag directions.

This screenshot shows earlier labels; the instructions above use the current names.

Supported value sources

Source	Available categories
Fluid trackpad gestures	While Moving/Pinching/Rotating, continuous directions and Gesture End.
Mouse drags	Drag directions; use continuous categories for ongoing control.
MIDI	Incoming value, normally 0–127.
Floating-menu sliders/knobs	Value-change categories; knobs also support rotation categories.

For shortcuts without a numeric field, use Only Continue After Accumulating Movement / Value.

Script variables

Variable	Value
BTTTriggerValue	0–100 stroke progress for fluid gestures/drags; raw value for other sources.
BTTTriggerValueNormalized	Position normalized to 0–1.
BTTTriggerValuePercent	Position as 0–100 percent.
BTTTriggerValueMIDI	Position mapped to an integer 0–127.
BTTTriggerValueDelta	Signed movement: swipes/edges use trackpad percentage points, pinch magnification percentage points, rotation degrees, mouse drags pixels; other sources use their native units.

These are trigger inputs, not the accumulated output of a bound action field. They are latest shared variables, not a snapshot for each action invocation: another trigger can overwrite them while an asynchronous script runs.

Add Run Real JavaScript under a continuous movement category and set Function To Call to someJavaScriptFunction:

async function someJavaScriptFunction() {
  const value = await get_number_variable({variable_name: "BTTTriggerValue"});
  const delta = await get_number_variable({variable_name: "BTTTriggerValueDelta"});
  return JSON.stringify({value, delta});
}

Variables and exported JSON

For action creation/export, see the binding JSON reference. Stored source keys remain "accumulated" for Increase / Decrease Value and "value" for Set Value Directly.