Skip to content

Actions & aliases

The action id grammar, every deck/mixer/engine/library action, and the closed input alias catalog.

A mapping uses two closed vocabularies: action ids, the values you assign in map.toml, and input aliases, the keys of an [inputs.<section>] table. A name that is not listed here is rejected at load time.

Action id grammar

An action id is:

<OriginTemplate>::<leaf>
<OriginTemplate>::<leaf>(key:value,…)
  • The origin and leaf are separated by exactly one ::.
  • Parentheses are only used when the leaf takes named arguments. A no-arg leaf is written without ().
  • Named args are comma-separated key:value pairs.

The parser rejects:

  • a missing :: (action must be OriginTemplate::leaf);
  • an empty origin or leaf;
  • more than one ::;
  • an unclosed argument list;
  • an empty (): omit the parentheses for no-arg leaves instead;
  • an empty argument entry (e.g. a trailing comma), a non key:value entry, a duplicate key, an invalid key, or an invalid value.

An argument key must be a lowercase identifier (ASCII lowercase, digits, _, starting with a letter). An argument value is one of:

Value kind Example Notes
Integer n:3, beats:-2 Signed integers are allowed.
Float beats:0.25 Must be finite.
Identifier mode:loop_roll Lowercase identifier.

Origin templates

Template Meaning
Deck(_) Wildcard: inherits the deck of the enclosing deck_* section (deck_1 → deck 0). Only valid inside a deck_* section.
Deck(n) An explicit deck, n in 0..=3.
Mixer The mixer origin.
Engine The engine origin.
LibraryNavigation The library navigation origin.

Deck(_) is bound from the section: in deck_1 it resolves to deck 0, in deck_2 to deck 1, and so on. Using Deck(_) in a section that is not deck_* (for example [inputs.master]) is an error.

[inputs.deck_1]
# Deck(_) is only legal in a deck_* section; here it binds to deck 0.
volume = { action = "Deck(_)::set_volume", soft_takeover = true }

A Deck(n) origin can be used anywhere, including master, to target a fixed deck:

[inputs.master]
load_deck_1 = "LibraryNavigation::load_to_deck(deck:1)"

Deck leaves

Deck leaves apply to Deck(_) or Deck(n) origins. The button leaves fire on the active edge (press); the absolute controls take a 0..1 value; relative controls take a device-decoded tick delta.

Transport

Leaf Args Effect
toggle_play – Toggle play/pause.
play – Start playback.
pause – Pause playback.
cue – Set the cue point.
cue_default – Cue hold: begins the cue hold on press, ends it on release.
begin_cue_hold – Begin cue hold (press).
end_cue_hold – End cue hold (release).
toggle_sync – Toggle beat sync.
set_quantize – Toggle quantize.
cycle_tempo_range – Cycle the tempo range through 6% → 10% → 16% → 25%.

Mixer-per-deck

Leaf Args Effect
set_volume – Absolute volume 0..1.
set_filter – Absolute filter 0..1.
set_gain – Absolute gain trim 0..1.
set_eq_high – Absolute high EQ 0..1.
set_eq_mid – Absolute mid EQ 0..1.
set_eq_low – Absolute low EQ 0..1.
set_stem_eq_high – Absolute stem EQ 0..1 (0.5 = neutral); high = vocals. Always targets the stem EQ.
set_stem_eq_mid – Absolute stem EQ 0..1 (0.5 = neutral); mid = bass + other. Always targets the stem EQ.
set_stem_eq_low – Absolute stem EQ 0..1 (0.5 = neutral); low = drums. Always targets the stem EQ.
toggle_stem_eq – Toggle the deck’s stem-EQ routing (the deck header ST key).
set_speed – Absolute speed/tempo 0..1.
set_headphone_cue – Toggle headphone cue (PFL) for the deck.

The set_eq_* leaves follow the deck’s ST toggle: with stem EQ on and the deck really playing stems they drive the stem EQ, otherwise the channel EQ, so one EQ knob mapping covers both without a second binding.

Jog

Leaf Args Effect
jog_touch – Report platter touch state (press/release).
jog_turn – Relative jog turn; consumes a decoded tick delta.

Hot cues

Leaf Args Effect
trigger_hot_cue slot:1+ Trigger the stored cue in slot; if the slot is empty, save one there.
delete_hot_cue slot:1+ Delete the cue in slot.

Hot-cue slots are counted from 1. The engine keeps 16 slots per deck, and slot is the 1-based index into them. trigger_hot_cue(slot:1+) is stateful. If the slot already holds a cue it triggers it; if the slot is empty it saves the current position there instead.

Loops / beat jump

Leaf Args Effect
loop_in – Set the loop in point at the current position.
loop_out – Set the loop out point at the current position.
exit_loop – Exit the active loop.
auto_loop beats:>0 Set an auto-loop of beats beats (positive finite, decimals allowed).
beat_jump beats:≠0 Jump by beats beats (non-zero finite, signed; decimals allowed).

Pads

Leaf Args Effect
pad_mode mode:hot_cue|loop_roll|beat_jump|sampler|stems Select the deck’s pad mode.
pad n:1+ Publish a generic pad press/release; the engine honors the deck’s current pad mode.
hot_cue_pad n:1+ Force a hot-cue pad press/release regardless of the current pad mode.
loop_roll_pad n:1+ Force a loop-roll pad press/release.
beat_jump_pad n:1+ Force a beat-jump pad press/release.
sampler_pad n:1+ Force a sampler pad press/release.
trigger_sampler slot:1+ Sampler pad press/release for slot (1-based).

pad(n) and the named *_pad(n) leaves differ in intent:

Form Publishes Use for
pad(n) The generic pad press/release pair; the engine applies whatever pad mode the deck is currently in. Controllers whose pad notes stay the same across hardware modes.
hot_cue_pad(n), loop_roll_pad(n), beat_jump_pad(n), sampler_pad(n) The pad event for one specific mode. Controllers (e.g. Pioneer) whose pad note banks differ per hardware page, where the note itself already encodes the mode.

The n argument is not capped at eight. Any n:1+ is accepted, and numbered aliases (pad_<n>, hot_cue_<n>, …) likewise accept any n ≥ 1.

Mixer, Engine and Library leaves

Mixer

Leaf Args Effect
set_crossfader – Absolute crossfader position 0..1.
set_cue_mix – Absolute cue-mix blend 0..1.
set_master_cue – Toggle master cue.
toggle_fx – Arm/disarm the shared Beat FX unit (slot 0), flipping its current state.
disarm_fx – Disarm the shared Beat FX unit without touching wet or knobs.
cycle_fx_next, cycle_fx_prev – Step the effect selection through the shipped effects (no Off entry).
step_fx_division_down, step_fx_division_up – Step Echo’s beat division one table entry; inert for other effects and clamped at both ends.
set_fx_wet – Absolute Beat FX level 0..1. Listed in the absolute catalog, so bindings default to soft-takeover.
set_fx_route target:ch1|ch2|master Exclusive CH SELECT: publishes the full per-deck routing group in one control.
set_crossfader_curve id:<curve-id> Select a preset, custom group, or curve set by canonical snake_case id on press. An unknown id installs constant_power and raises a notice.
set_channel_fader_curve id:<curve-id> Select the channel-fader preset or custom one-channel group by canonical snake_case id on press. An unknown or multi-channel id installs linear and raises a notice.
set_tempo_curve id:<curve-id> Select the deck’s tempo-fader preset or custom one-channel group by canonical snake_case id on press. An unknown or multi-channel id installs linear and raises a notice.
set_fx_level_curve id:<curve-id> Select the shared FX level/depth preset or custom one-channel group by canonical snake_case id on press. An unknown or multi-channel id installs linear and raises a notice.
cycle_crossfader_curve – Step to the next available preset (constant_power → linear → fast_cut, wrapping). A custom selection steps back to constant_power.
set_crossfader_curve_amount set:<set-id> Absolute knob sweep 0..1 across the named curve set. Listed in the absolute catalog, so bindings default to soft-takeover.
set_crossfader_hamster – Toggle the invert flag (wire name hamster; swaps A/B gains) on press.
set_crossfader_disabled – Toggle curve bypass (both sides full gain) on press.

Engine

Leaf Args Effect
start_engine – Start the engine.

LibraryNavigation

Leaf Args Effect
navigate – Relative browse: consumes a decoded tick delta.
navigate_next – Move the library selection forward by one.
navigate_prev – Move the library selection back by one.
focus_next – Step browser focus to the next pane (sidebar → track list).
focus_prev – Step browser focus back to the previous pane (track list → sidebar).
load_to_deck deck:1+ Load the focused track into deck deck (1-based; deck 1 → index 0).

navigate acts on whichever pane owns browser focus. In the track list it moves the focused row. In the sidebar it moves the focused row of the active tab: the selected collection, the selected history session, or the Drive tree row. A tree row’s selection is the folder it opens, so the listing follows the focus. The two panes flip between each other, so focus_next and focus_prev are the same move on a browser with two panes.

[inputs.master]
browse = "LibraryNavigation::navigate"
focus_next = "LibraryNavigation::focus_next"
focus_prev = "LibraryNavigation::focus_prev"
load_deck_1 = "LibraryNavigation::load_to_deck(deck:1)"
load_deck_2 = "LibraryNavigation::load_to_deck(deck:2)"

The DDJ-400 binds its rotary selector to exactly this: browse is the encoder. Pressing it (focus_next, note 0x41 on channel 7) or SHIFT + pressing it (focus_prev, note 0x42 on channel 7) hands the browser between the panes.

Named-arg rules

Argument keys are validated per leaf, and a leaf accepts exactly the keys listed for it. Extra or missing keys are errors. Leaves not listed here take no arguments, and any argument is rejected (this leaf does not take arguments).

Leaf(s) Required key Constraint
pad, hot_cue_pad, loop_roll_pad, beat_jump_pad, sampler_pad n Integer ≥ 1.
trigger_hot_cue, delete_hot_cue, trigger_sampler slot Integer ≥ 1.
load_to_deck deck Integer ≥ 1 (1-based).
auto_loop beats Positive finite number.
beat_jump beats Non-zero finite number (may be negative).
pad_mode mode One of the five pad modes.
set_crossfader_curve id Canonical snake_case curve id (fast_cut, a custom group, or a curve set).
set_crossfader_curve_amount set Canonical snake_case curve-set id.
set_channel_fader_curve id Canonical snake_case channel-fader curve id (linear or a custom one-channel group).
set_fx_level_curve id Canonical snake_case FX level/depth curve id (linear or a custom one-channel group).
all other leaves – Arguments rejected.

Absolute vs. relative leaves

Most leaves are buttons (edge-triggered on press, or press/release pairs such as cue_default, jog_touch, pad, trigger_sampler). Two categories carry a continuous value instead:

Category Leaves Wire value
Absolute set_volume, set_filter, set_gain, set_eq_high, set_eq_mid, set_eq_low, set_stem_eq_high, set_stem_eq_mid, set_stem_eq_low, set_crossfader, set_crossfader_curve_amount, set_cue_mix, set_speed Normalized 0..1, clamped.
Relative jog_turn, navigate A decoded tick delta from the device’s relative mode.

Absolute leaves default to soft-takeover behavior (and can opt out per binding). They are the ones you typically pair with soft_takeover = true in map.toml. What soft takeover does and why it is useful is explained on the inputs page:

[inputs.deck_1]
volume = { action = "Deck(_)::set_volume", soft_takeover = true }
tempo  = { action = "Deck(_)::set_speed", soft_takeover = true, invert = true }

See Binding inputs to actions for the [inputs] binding form and its per-binding options.

Input alias catalog

Aliases are closed per section: only the names below are accepted in [inputs.<section>]. They are also what you use as keys in a device.toml input map. Numbered aliases accept any n ≥ 1.

deck_*

Alias Notes
play_pause
cue
cue_hold
sync
quantize
volume Absolute.
gain Absolute.
tempo Absolute speed.
tempo_range
eq_high Absolute.
eq_mid Absolute.
eq_low Absolute.
filter Absolute.
jog_touch
jog_turn Relative.
jog_side
jog_touch_shift
jog_search
headphone_cue
hot_cue_1 … hot_cue_8 Numbered: any n ≥ 1.
delete_hot_cue_1 … delete_hot_cue_8 Numbered: any n ≥ 1.
pad_1 … pad_8 Numbered: any n ≥ 1.
loop_pad_1 … loop_pad_8 Numbered: any n ≥ 1.
jump_pad_1 … jump_pad_8 Numbered: any n ≥ 1.
sampler_pad_1 … sampler_pad_8 Numbered: any n ≥ 1.
loop_in
loop_out
exit_loop
auto_loop
auto_loop_1, auto_loop_2, auto_loop_4, auto_loop_8, auto_loop_16, auto_loop_32
beat_jump_fwd, beat_jump_back
beat_jump_fwd_1/2/4/8
beat_jump_back_1/2/4/8
pad_mode_hot_cue
pad_mode_loop_roll
pad_mode_beat_jump
pad_mode_sampler
pad_mode_stems

The numbered aliases (hot_cue_<n>, delete_hot_cue_<n>, pad_<n>, loop_pad_<n>, jump_pad_<n>, sampler_pad_<n>) accept any n ≥ 1, not only the values shown.

master

Alias Notes
crossfader Absolute.
cue_mix Absolute.
master_cue Button.
browse Relative.
load_deck_1, load_deck_2
headphone_cue_1 … headphone_cue_4
beat_fx_on, beat_fx_on_shift Buttons.
beat_fx_select, beat_fx_select_shift Buttons.
beat_left, beat_right Buttons.
beat_fx_level_depth Absolute.
beat_fx_ch_1, beat_fx_ch_2, beat_fx_ch_master Buttons (exclusive routing).

sampler

Alias Notes
trigger_1 … trigger_8
end_1 … end_8

custom

Free-form: any alias name is allowed (modifiers only). This is the one section where the alias catalog is not closed.

Pad modes

pad_mode and pad_mode_* aliases select one of exactly five modes:

Mode Meaning
hot_cue Hot-cue pads.
loop_roll Loop-roll pads.
beat_jump Beat-jump pads.
sampler Sampler pads.
stems Stems pads.
[inputs.deck_1]
pad_mode_hot_cue = "Deck(_)::pad_mode(mode:hot_cue)"
pad_mode_loop_roll = "Deck(_)::pad_mode(mode:loop_roll)"
pad_mode_beat_jump = "Deck(_)::pad_mode(mode:beat_jump)"
pad_mode_sampler = "Deck(_)::pad_mode(mode:sampler)"

A pad_mode value outside these five is rejected. For the pad-note strategy that pairs with these modes, see the deck leaves above and Binding inputs to actions.