The language itself: tokens, chaining, conditionals, quoting, scope. This is the one document to read before writing VDJScript, because none of it is discoverable by lookup — the parser accepts almost anything and tells you nothing.
Not here: what an individual verb does or which argument forms it honours. Those are
per-verb facts — just get-verb <name>, just list-verbs <term>.
Provenance is per rule. HTTP = the HTTP control interface
on VirtualDJ 2026, 2026-07-22. Pad = the
Grammar Battery pad run on
v2026-m b9482, 2026-07-14. Where a rule is proven on only one surface, it says so —
backticks are the proof that this
distinction is not pedantic.
Rules from the runtime-parser task (H4) carry one of three labels, joined to exact cases by
just runtime-grammar --audit and summarised in
H4 rule status. Repeated: held and separated from the
nonsense controls, with the same reading in a second complete capture. One capture:
held and separated in a single complete capture, so it is unresolved beyond that capture.
Matches controls: the form did the same as nonsense arguments. That shows it did not do
what the literal did, but not why, so the reason stays unresolved. The b9246 binary
supplies structural leads only; behaviour comes from builds 9598 and 9628, as each rule
states.
Enough to write correct VDJScript. If you are only editing skin layout or XML structure and not writing script, you can stop after this section.
- The runtime will never report a syntax error. Wrong script silently does something else. Assume nothing; test it. (The editor is a different story — it autocompletes real verbs and colours ternary branches by role, so it validates far more than the runtime reports. See the correction below.)
&separates statements, it is not "and".a & bruns both.- Never put cleanup after a ternary. In
cond ? a : b & c, the& cbelongs to the false branch. Put unconditional actions first:c & cond ? a : b. Each branch takes its whole chain, on both sides — see Conditionals. - Ternary branches must be verbs, not literals.
on ? get_version : get_clockworks;on ? 'A' : 'B'errors. Neither branch may be empty. - A verb's value is not its truth.
get_versionreports2026and is false as a condition; no slider verb is ever true. 171 of 652 query verbs are traps — check withjust verb-return-type <name>before using one as a condition. - Quote any argument containing a space.
'Beat Grid'works, bareBeat Griddoes not. Single and double quotes are equivalent; quotes are optional for single tokens. &&never guards an action.cond && do_thingrunsdo_thingwhatevercondis. The only guard is a ternary:cond ? do_thing : nothing.- Store numbers in variables, never strings. A string-valued variable cannot be read
back (
get_varreturns blank) or compared (var_equalreturnsyesagainst everything). Use numeric codes. - Computed arguments are consumer-specific. Backticks evaluate in XML attributes and
in some HTTP consumers (
effect_active, build 9628). In thezoom/beatlockexecute forms tested on build 9598 they did not apply the computed value. Those readings match the nonsense controls, so it is unresolved whether the forms are ignored or rejected. Check the verb record and the bounded examples below. - On
zoom, a malformed number resets the value.zoom 0.25zzqqxlands on the same0.2as barezoom; it is not ignored. Also onzoom, a signed number is relative and an unsigned one absolute:zoom +0.25adds,zoom 0.25sets. Other verbs were not measured, so check the verb record. - Leave fixed keywords bare. On
beatlock, bareonset the switch and quoted'on'did not. The quoted form read the same as nonsense arguments. That is one capture on one verb; whether it holds for other switch verbs is unresolved. - There are no comments.
//,#,;,--,/* */all silently discard the rest of the statement. deck activeis the master deck, not the selected deck. So isdeck master; the selected deck is what an unwrapped verb anddeck defaultuse. Do not assumedeck mixerNmeans deck N: in the one capture that measured it, it did not — see which deck a target resolves to.- Variable prefixes are part of the name.
modeand$modeare different variables.$= global,@= persists across restarts, bare = deck-local. - In XML,
&must be written&. - Test any construct in one call:
just vdj-query 'on ? get_version : get_clock'
- The parser never reports an error
- Statements and chaining
- Conditionals
- Boolean composition with
&& - Arguments and quoting
- Variables hold numbers, not strings
- There is no comment syntax
- Chains stop after exactly 255 statements
- Backticks are a surface feature, not a parser feature
- Variable scope prefixes
- Deck and scope wrappers
- XML escaping
- Testing a construct yourself
- H4 rule status
- Not yet established
This is the single most important fact about the language, and the reason every other section exists. VirtualDJ validates the head verb of a statement and essentially nothing else. Junk in argument position — stray quotes, unbalanced backticks and parens, operator soup, extra arguments, a nonexistent deck — is silently discarded and the verb runs anyway.
HTTP, all returning the normal result of get_version:
get_version & & & & get_version '''''' get_version ```
get_version ) ) ( ( get_version !!!@@@### get_version 1 2 3 4 5 6
deck 99 get_version get_version & zzz_bogus
Only the leading verb is checked: zzz_bogus & get_version errors, while
get_version & zzz_bogus returns 2026 — the bogus second statement is dropped in
silence.
Consequences: a working script is no evidence that its syntax is right, and a typo in a verb
argument produces a no-op rather than a complaint. tools/lint_mappers.py resolves leading
verbs against the verb index precisely because the runtime will not.
The heading above, and the summary line "nothing you write will be reported as a syntax error", were written from HTTP and mapper evidence only — the execution path. They are accurate about that path and every example above still holds. But they were too broad about VirtualDJ as a whole, and the distinction matters:
VirtualDJ validates considerably more than it reports. There are two parsing surfaces.
| Surface | Behavior |
|---|---|
| Runtime (HTTP, mappers, pads, skins) | Lenient by design. Head verb checked; argument junk discarded; the verb runs. Reports almost nothing. |
| Editor (Button Editor / mapper Action box) | Validating. Autocomplete offers only real verbs — all 955 canonical, aliases excluded — and the highlighter colours ternary structure, giving the condition, true branch and false branch distinct colours. |
The editor could not colour branches by role unless a structural parser were running as you type. So the app is not ignorant of malformed script; the failure to tell you is a property of the execution surface, not a limit of VirtualDJ's knowledge. Junk in argument position is recognised and discarded, not unnoticed.
The practical advice is unchanged: test everything, because the runtime will not complain.
"You cannot lint VDJScript by feeding it to VirtualDJ" stands — tested 2026-07-30. This
sentence was briefly withdrawn on the theory that the editor might flag unknown verbs. It does
not. Local test (Button Editor, screenshots), three scripts differing only in the head verb:
get_version ? get_text "A" : get_text "B" <- real verb
zzz_bogus ? get_text "A" : get_text "B" <- nonsense
browser_filter ? get_text "A" : get_text "B" <- proven not a verb (rule 1b)
All three render identically — same head-verb colour, same green true branch, same red false branch. The highlighter parses shape, not vocabulary: it will happily colour a well-formed ternary built entirely from verbs that do not exist.
So the two surfaces divide like this, and neither lints:
| Component | Knows the verb set | Validates structure |
|---|---|---|
| Autocomplete | yes — offers exactly the 955 canonical verbs | n/a |
| Highlighter | no | yes — colours ternary branches by role |
| Runtime | head verb only | no — junk in argument position is discarded |
tools/lint_mappers.py therefore remains necessary, and its reason is now sharper: no surface
in VirtualDJ will tell you a verb is fake once you have typed it. What the highlighter is good
for is mapping grammar — see
VDJScript Syntax Evidence, where branch-role colouring is
being used to settle ternary binding questions that the runtime cannot answer.
Error bodies, when you do get one, are coarse — see the
HTTP doc for the E_FAIL vs E_INVALIDARG split. E_FAIL
does not mean "unknown verb": the official verb nothing returns exactly what a bogus name
returns.
& is a statement separator. Both sides run; it is not a boolean operator.
set '$mode' 1 & load_skin
In a query context the value of the first statement is what comes back: on & off
returns yes, off & on returns no (HTTP). So chaining is for actions; do not chain
to build a condition.
A leading chain splits off before a ternary parses, which is the useful, safe ordering
(Pad, HTTP):
set '$mode' 1 & play ? action_a : action_b
The set runs unconditionally, then the ternary evaluates independently.
query ? true_branch : false_branch
This is the biggest trap in the language and it is invisible from the value. A condition
asks a boolean question. It does not mean "the value is non-zero" or "the value is
non-empty". HTTP, 2026-07-30:
get_version -> 2026
get_version ? get_text 'T' : get_text 'F' -> F # returns 2026, but is FALSE
Swept across all 652 query verbs: only 106 are boolean-true in condition position, and 171 return a value that reads as true while the verb is false. The pattern is systematic:
| Observed return type | boolean-true |
|---|---|
float |
0 / 68 |
percent |
0 / 4 |
text |
2 / 72 |
int |
35 / 145 |
bool |
68 / 334 (the rest are genuinely off at rest) |
By implementation family, no slider verb is ever boolean-true (0 / 71). So volume → 1,
pitch → 0.5, zoom → 0.53, stem_color → white are all false as conditions.
volume ? action_a : action_b # WRONG: volume reports 1, but this always takes action_b
get_bpm ? action_a : action_b # WRONG: same trap
Use a verb that is boolean by design (loaded, is_*, has_*, toggles), or make the
comparison explicit:
param_bigger 'volume' 0.5 ? action_a : action_b
var_equal '$mode' 1 ? action_a : action_b
Check any verb before using it as a condition — just verb-return-type <name> reports
boolean_truth alongside the value, and flags truthiness_trap for the 171.
This follows from the typing model in Plugin SDK: the host exposes a numeric channel and a text channel, and the boolean a conditional consumes is a third question that most value-reporting verbs simply do not answer — defaulting to false.
A trailing chain binds to the false branch (Pad). In cond ? a : b & c, c runs only
when cond is false — observed a=1 b=0 c=0 when true, a=0 b=1 c=1 when false. This is
the most common way to get a script wrong, because it reads like c always runs.
cleanup & cond ? action_a : action_b # correct: cleanup always runs
cond ? action_a : action_b & cleanup # WRONG: cleanup is part of the false branch
Each branch takes its whole chain (HTTP). With chains on both sides, the taken branch
runs all of it and the other runs none — the trailing-chain rule above is specifically
about a chain that follows the last branch, not about chains in general:
on ? set '$a' 1 & set '$b' 1 : set '$c' 1 & set '$d' 1 # -> a=1 b=1, c=0 d=0
off ? set '$a' 1 & set '$b' 1 : set '$c' 1 & set '$d' 1 # -> a=0 b=0, c=1 d=1
Corroborated independently by the Button Editor's parse hint (Local test, 2026-07-30): with
the cursor in each statement of get_version ? get_text "A" & get_text "B" : get_text "C" & get_text "D", the editor reports condition: get_version for A and B, and condition: not get_version for C and D. VirtualDJ's own model is a per-statement guard, negated on the
false side — see VDJScript Syntax Evidence.
Chaining gives you else if (Local test, Button Editor parse hint, 2026-07-30).
a ? b : c ? d : e is right-associative — a ? b : (c ? d : e) — and the guards accumulate
exactly as an else-if ladder should. Reading the editor's per-statement guard for
get_version ? get_text "A" : get_version ? get_text "B" : get_text "C"
gives get_version for A, not get_version & get_version for B, and
not get_version & not get_version for C. So the chain works the way you would hope, and
this is the idiom for multi-way selection:
var_equal '$mode' 1 ? do_one : var_equal '$mode' 2 ? do_two : do_default
Note this is the chained form (a ternary in the false branch). It is distinct from nesting a ternary in the true branch, below, and the two are frequently confused.
Nesting associates the standard way (Pad, HTTP): a ? b ? c : d : e parses as
a ? (b ? c : d) : e, so clamped selection composes safely.
var_equal '$phrase_len' 16 ? phrase_sync 16 : phrase_sync 32
nothing is the correct null branch for actions (HTTP). A ternary is the only
construct that actually guards an action:
var_equal '$mode' 1 ? do_thing : nothing
In query position nothing has no value and errors, so this idiom is action-only.
Branches must be verbs and must not be empty (HTTP):
| Form | Result |
|---|---|
on ? get_version : get_clock |
works |
on ? 'A' : 'B' |
error — literals are not values in branch position |
on ? 1 : 2 |
error |
off ? get_version : |
error:1 — empty branch, taken |
on ? : get_version |
error — empty true branch |
off ? get_version : nothing |
error — nothing has no query value |
An empty branch only errors when execution reaches it: on ? get_version : returns
normally because the false branch is never taken. Do not rely on that.
Corrected 2026-07-30 — && is not a distinct operator, and it does not bind into a
conditional. The previous version of this section said "&& is boolean AND over queries, and
it binds tighter than ?, so a && b ? c : d uses a && b as the condition", and read
off && on ? get_version : get_clock returning no as "the ternary never ran". Both were
wrong. They were inferred from returned values alone — exactly the mistake
Evidence Standards rule 4 warns about — and two independent checks
refute them.
Structure (Button Editor parse hint): in get_version && get_bpm ? get_text "A" : get_text "B" the guard for the true branch is get_bpm — not get_version && get_bpm. Replacing
&& with & gives byte-identical guards. The condition is only the statement immediately
before the ?.
Behaviour (HTTP, action position with independent readback — the ternary does run):
| Script | $a |
$b |
|
|---|---|---|---|
off && on ? set '$a' 1 : set '$b' 1 |
1 | 0 | true branch taken — condition is on |
off & on ? set '$a' 1 : set '$b' 1 |
1 | 0 | identical to && |
on && on ? set '$a' 1 : set '$b' 1 |
1 | 0 | |
off && off ? set '$a' 1 : set '$b' 1 |
0 | 1 | false branch — condition is off |
So a false left operand does not abort anything. off && on ? … takes the true branch,
because the condition is on.
& and && are both statement separators. They differ only in the value a query reports
(HTTP, with on→yes and off→no bare):
| Script | Returns | Rule |
|---|---|---|
on & on ? get_version : get_clock |
yes |
& always reports the first statement |
off & on ? get_version : get_clock |
no |
" |
on && on ? get_version : get_clock |
2026 |
&& with a true left reports the right |
on && off ? get_version : get_clock |
06:48 AM |
" (ternary took its false branch) |
off && on ? get_version : get_clock |
no |
&& with a false left reports the left |
off && off ? get_version : get_clock |
no |
" |
That is short-circuit AND semantics applied to the reported value only — false-left reports the left, true-left reports the right — while both statements execute either way. It is a value-selection rule, not a guard, and it never reaches into a following conditional.
In action position && does not guard anything (HTTP). This is the dangerous half:
| Script | $a after |
|---|---|
off && set '$a' 1 |
1 |
var_equal '$x' 999 && set '$a' 1 (with $x=0, so false) |
1 |
var_equal '$x' 0 && set '$a' 1 (true) |
1 |
var_equal '$x' 999 ? set '$a' 1 : nothing |
0 |
&& in front of an action behaves exactly like &: both sides run regardless. Anyone
writing condition && action expecting a guard gets the action unconditionally, with no
error. Use a ternary with a nothing false branch.
This row was always right, and it is now the general case rather than the exception: &&
never guards anything, in any position. Treat && as & with a different value-reporting
rule, and use a ternary whenever you mean "only if".
Single quotes, double quotes, and no quotes are equivalent for a single-token argument.
Quoting becomes mandatory as soon as the value contains a space (HTTP):
get_effect_title 'Echo' -> Echo - Deck 1
get_effect_title "Echo" -> Echo - Deck 1
get_effect_title Echo -> Echo - Deck 1
get_effect_title 'Beat Grid' -> Beat Grid - Deck 1
get_effect_title "Beat Grid" -> Beat Grid - Deck 1
get_effect_title Beat Grid -> '' <- silently wrong
The unquoted multi-word case is the trap: it does not error, it returns nothing. Quote every string argument as a habit.
That equivalence holds for a string argument being matched (an effect name). It does not
hold for a value being stored, where quoting decides the type — see
Variables hold numbers, not strings. on and off
are real constants that evaluate to yes/no; true and false are not — they store
nothing (HTTP).
The equivalence above covers a string being matched. It does not hold for the fixed
keywords a switch-style verb accepts. There, the quoted form did not do what the bare
keyword did (Local test 2026-09-12, HTTP execute with independent state readback, build
9598, from beatlock off and on baselines,
capture):
deck 1 beatlock on -> on from both baselines
deck 1 beatlock 'on' -> unchanged <- same as the nonsense controls
deck 1 beatlock "on" -> unchanged <- same as the nonsense controls
Status: bare on is one capture; the quoted forms match controls. The capture shows a
quoted keyword did not set the switch. It does not show whether the quoted token is rejected
or simply unrecognised, and no second capture repeats it. The practical advice still
follows: quoting every argument is right for names and was wrong here for a keyword. Quote
values that may contain a space; leave bare the fixed words a verb enumerates.
On b9246, beatlock reaches the shared IActionSwitch::onExecute. That is a structural lead
that the vocabulary below may be common to switch verbs. It was measured on beatlock alone,
in the same single capture:
| Argument | Effect | Status |
|---|---|---|
(none), toggle |
toggles | One capture |
on, 1 |
sets on | One capture |
off, 0 |
sets off | One capture |
+1, +0, -1 |
toggles — a signed integer does not set | One capture |
'on', "on", 1.0, 100%, default, all, value, `constant 1` |
unchanged, as with nonsense arguments | Matches controls |
Argument matching is a per-verb matter, not grammar — effect names are case-insensitive
but not space-insensitive, some verbs require a signed number, some ignore computed
values. Those live on the verb record: just get-verb <name>.
%, ms and bt attach to the number with no space, in lower case (HTTP, build 9598,
confirmation capture):
constant 37ms -> 37ms constant 37MS -> '' <- wrong case, no value
constant 37% -> 37% constant 37 ms -> 37 <- suffix dropped
constant 37bt -> 37bt constant 37msbt -> '' <- one suffix only
Status. The left column and 37 ms are one capture. The
interrupted initial capture read the same in its
single round, but its verdicts are incomplete-run. 37MS and 37msbt match controls,
because constant's nonsense controls also return blank. The discriminating evidence for
case is on zoom: zoom 25MS and zoom 25BT reset to 0.2, like other malformed
numbers, in two captures (below).
That case rule is repeated. On zoom, a separated 25 % matches controls.
A comma was accepted as a decimal separator in both channels: constant 37,5 returned
37.5 (query), and zoom 0,25 set the same value as zoom 0.25 (execute,
capture). Each is one capture. A number with no
integer part is not parsed as one. constant .5 returned blank, which matches controls.
zoom .25 reset to 0.2 in two captures, which is repeated. So write 0.5.
A +-combined argument is one token and takes no whitespace, for the same reason
(Local test 2026-09-08, HTTP): effect_arm_stem 'kick+bass' arms both stems,
effect_arm_stem 'kick + bass' returns true and does nothing — the space ends the
token before + is ever read.
A numeric or boolean variable round-trips correctly, and quoting distinguishes the types —
5 and '5' are different values (HTTP):
set '$v' 5 -> get_var 'yes'/5 var_equal '$v' 5 -> yes var_equal '$v' '5' -> no
set '$v' on -> get_var yes var_equal '$v' on -> yes
A string variable is effectively write-only. It cannot be read and it cannot be
compared (HTTP, $v set to 'apple'):
| Read attempt | Result |
|---|---|
get_var '$v' |
'' — blank, as it is in pad labels too (Pad) |
var_equal '$v' 'apple' |
yes |
var_equal '$v' 'banana' |
yes ← wrong |
var_equal '$v' banana |
yes ← wrong |
Once a variable holds a string, var_equal returns yes against anything. So a
string-keyed branch is not just unreadable, it takes the true branch every time and looks
like it works.
Store numeric codes and branch on those. set '$mode' 2 with
var_equal '$mode' 2 ? … : …, never set '$mode' 'reverb'.
true and false are not constants — set '$v' true stores nothing. Use on/off or
1/0.
Every common comment marker is accepted and silently discards the rest of the statement
(HTTP — in each case $a was set and $b was not):
set '$a' 1 // set '$b' 1 set '$a' 1 # set '$b' 1 set '$a' 1 ; set '$b' 1
set '$a' 1 -- set '$b' 1 set '$a' 1 /*x*/ set '$b' 1
There is no way to annotate script inline. Put explanation in the surrounding XML comment
(<!-- … -->) or in the file that documents the page.
A chain executes its first 255 statements and silently drops the rest. /execute returns
false when that happens, so the truncation is reported. HTTP over POST, 2026-07-30,
with per-statement readback (set '$cN' 1, then querying each $cN):
| Statements sent | execute |
Statements that ran |
|---|---|---|
| 254 | true |
254 |
| 255 | true |
255 |
| 256 | false |
255 |
| 300 (4689 chars) | false |
255 |
| 400 (6289 chars) | false |
255 |
| 500 (7889 chars) | false |
255 |
255 = 2^8 − 1, and it is a statement count, not a size: three chains of 4689, 6289 and 7889
characters all cut at exactly the same statement. Keep generated chains under 255, and check
execute's return value if you are anywhere near it.
Two separate transport limits sit above this and are easy to mistake for it:
- GET has a URL-length limit around 2650 characters. Past it the connection is reset before VirtualDJ sees the script, so nothing runs — for transport reasons, not language reasons.
- POST bodies fail somewhere above ~9500 characters with a connection reset.
The previous version said a long chain runs nothing at all including the first statement,
that execute reports success anyway, that the boundary was neither a character count
nor a statement count, and that GET and POST behaved identically. All four were artefacts of
testing over GET: past ~2650 characters the request never arrived, which looks exactly like
"nothing ran". Over POST the real behaviour is visible — partial execution, a false return,
and a clean 255-statement cutoff.
A same-day attempt to "sharpen" the ceiling to 172 statements / 2641 characters was the same mistake once more, and is withdrawn: 2641 characters is where the GET URL limit falls for that statement shape, not where VDJScript stops.
Lesson worth keeping: when a channel and a language limit can produce the same symptom, distinguish them before measuring — here, by re-running over a different transport.
`verb` evaluates in supported XML attribute string/colour contexts and in some
HTTP argument consumers. It is not a universal argument-evaluation mechanism: test
the exact verb, argument position and channel. The former claim that HTTP never
evaluates backticks was too broad.
These HTTP effect-introspection arguments did not substitute (HTTP), with Echo
loaded in slot 1:
get_effect_slider_count 'Echo' -> 6
get_effect_slider_count `get_effect_name 1` -> 0 <- no substitution
get_effect_title `get_effect_name 1` -> ''
Proven to work in a pad attribute context (Pad): set '$dst' `get_var '$src'` read
back 42.
So a construct prototyped over HTTP may behave differently once pasted into a skin, and
vice versa. When a computed argument is needed and backticks are unavailable or ignored,
chain parameters instead — this works on both surfaces tested (Pad):
get_var '$src' & param_multiply 2 & set '$dst'
Whether a given verb honours a computed argument is per-verb: loop, beatjump, and
phrase_sync ignore them even where the identical literal works. Check the verb record.
These negative results also occur in specific execute consumers, which the query evidence above could not show —
a flattened query result is consistent with "the surface stringified it", but a state
readback is not. With zoom and beatlock driven from two prepared baselines and read
back independently (Local test 2026-09-12, HTTP, build 9598,
capture), every backtick form left both
baselines exactly where the nonsense controls did, while the literal moved them:
zoom `constant 0.25` -> unchanged zoom 0.25 -> 0.25
zoom '`constant 0.25`' -> unchanged
deck 1 beatlock `constant 1` -> unchanged deck 1 beatlock on -> on
deck 1 beatlock '`constant 1`' -> unchanged
Status: all four backtick forms match controls, in one capture. They show that the computed value was not applied, and that quoting the expression did not change that. They do not show whether the consumer ignores the argument or rejects it.
A computed deck prefix does not resolve either: deck `constant 2` get_deck returned
error:-2147467259. That is the same error a junk target returns. The
scope capture and its
follow-up, which use junk-target
controls, both record it as matching controls. The
confirmation capture records it as
separating only against blank-returning constant controls. So it behaves like an
unrecognised target, not like a distinct failure.
By contrast, Local test 2026-09-17 on build 18.0.9628 established HTTP execute
evaluation for deck 1 effect_active 1 with paired-backtick on/off and
constant 1/constant 0, both with and without an explicit 'Phaser' argument.
Independent activation readback from off/on baselines separated these forms from
paired-backtick nonsense. That is repeated: the
initial and
confirmation captures agree. Raw quoted
text and unclosed expressions matched their shape-matched controls, so those forms are not
evaluation proof. See the
consumer fixture and preserved captures
for scope and restoration evidence. This does not establish other effect consumers
or persistent action-cache behavior.
The prefix is part of the variable's identity. MyVar and $MyVar are two different
variables, so a global must be set, toggled, and queried with $ every time.
| Prefix | Scope |
|---|---|
name |
local to the current deck |
#name |
a different variable from name — see the correction below |
%name |
local to a logical deck reference such as deck left |
$name |
global for the session |
@name, @%name, @$name |
persistent across restarts |
deck 1 set 'mode' 1
toggle '$MyVar'
set '@$layout_4deck' 1 & load_skin
For skin-wide or controller-wide state use $ or @$; a bare set 'mode' 1 reads
differently when the same script later runs in another deck context.
This table was inherited prose until now. Three of its claims were put to the running app
(Local test, HTTP, build 9598, probe names set back to 0 and the teardown verified —
capture). An unset name reads blank, so none of
these readbacks is measuring a leftover:
deck 1 set 'zzprobescope' 11 & deck 2 set 'zzprobescope' 22
deck 1 get_var 'zzprobescope' -> 11 bare really is per-deck
deck 2 get_var 'zzprobescope' -> 22
deck 1 set '$zzprobescope' 33
deck 2 get_var '$zzprobescope' -> 33 $ really is shared
bare / $ / @ set to 1 / 2 / 3 on one deck
read back -> 1, 2, 3 three names, not one
So writing set 'mode' 1 in a script that runs on two decks gives you two variables, and
the $ you forgot on a toggle is a different variable from the one you set.
An unscoped read of a bare name resolves against the selected deck: with deck 2
selected, get_var 'zzprobescope' returned deck 2's 22. That is the same rule as the
deck targets — unwrapped means selected.
The table used to group name and #name on one row, as though # were optional
decoration. It is not — #X is a separate variable from X, exactly the way $X is:
deck 1 set 'zzprobescope' 44
deck 1 get_var 'zzprobescope' -> 44
deck 1 get_var '#zzprobescope' -> (blank: never set)
deck 1 set '#zzprobescope' 55
deck 1 get_var 'zzprobescope' -> 44 unchanged by the # write
deck 1 get_var '#zzprobescope' -> 55
Blank there is the useful part: an unset name reads blank, so #X was not an empty alias of
X, it was a name that did not exist yet. Whether #X is also deck-local was not tested —
only that it is its own variable.
%name keys on the logical reference, not the deck behind it. deck left resolves to
deck 1 on this setup (deck left get_deck -> 1), and yet:
deck left set '%zzprobescope' 66 & deck 1 set '%zzprobescope' 77
deck left get_var '%zzprobescope' -> 66
deck 1 get_var '%zzprobescope' -> 77
Two values, one physical deck. So % is what you want for state that should follow "the left
deck" through a deck swap, and a script mixing %X with X on the same base name is touching
two variables.
The restart test the earlier run could not do has since been done, and the teardown that
looked like a flaw is what made it readable. Every probe name was set to 0 rather than
deleted, then VirtualDJ was fully quit and relaunched (new pid). On the fresh session:
| Read after restart | Value |
|---|---|
@zzprobescope |
0 — survived |
zzprobescope, $zzprobescope, #zzprobescope, %zzprobescope |
blank — did not |
Blank versus 0 is the whole test: 0 is the value that was written before the quit, and
blank is a name that does not exist in this session.
@ is orthogonal to the scope prefix, not a fourth scope. It combines:
deck 1 set '@zzprobescope' 7 & deck 2 set '@zzprobescope' 8
-> 7 and 8 @name = persistent AND still deck-local
deck 1 set '@$zzprobeglob' 9
-> 9 from deck 2 @$name = persistent AND global
They are stored in settings.xml under <VDJScriptGlobalVariables>, a comma-separated list
of name=index=float triples with the @ stripped and the rest of the name kept as the
key — so @$foo is stored as $foo, and a deck-local @foo writes one row per deck. That
is why the file showed two zzprobescope rows for one probe name. The file is written on
quit, which is why reading it mid-session showed nothing.
One consequence worth stating plainly: @ names outlive the session and land in the user's
settings file. A probe that writes one is leaving a trace behind; name it distinctively.
One caution when re-running the probe: teardown sets the names to 0, which is not the same
as deleting them. A first run sees blank for an unset name; later runs see 0. Only the
blank reading distinguishes "never existed" from "set to zero".
A deck wrapper prefixes a statement and applies to the rest of it, including a conditional
(HTTP):
deck 1 get_version -> 2026
deck 2 get_version -> 2026
deck left get_version -> 2026
deck 1 on ? get_version : get_clock -> 2026
deck 99 get_version -> 2026 <- nonexistent deck, accepted silently
deck 99 is accepted, which is the no-error rule
again: an out-of-range deck is not reported. all_decks get_version errors — all_decks
is action-only and has no query value, so it cannot wrap a query.
From the VDJScript wiki page, fetched 2026-09-03 — the deck wrapper accepts nine targets, four more than this reference had:
deck 1 … deck 4, deck left, deck right, deck leftvideo, deck rightvideo,
deck all, deck default, deck active. Without a wrapper a verb applies to the default
or controller-mapped deck.
Two constructs the wiki documents that are not otherwise recorded here:
- Brackets start a separate execution thread, which is how a script waits without blocking
the rest of the line:
( wait 1000ms & play_pause ) & action_deck 1 ? deck 2 play_pause : deck 1 play_pause while_pressedat the end of a statement limits it to the duration of the button press:volume 100% while_pressed. Its exact semantics are tested below.
Argument units are ms, bt (beats) and %, alongside plain integers and decimals:
nudge +100ms, wait 8bt, crossfader 50%.
deck leftvideo, deck rightvideo and deck default are now locally tested — see
which deck a target resolves to below.
all is a deck target beside 1, left, active and master, and it behaves differently
in the two contexts. Executing broadcasts to every deck (Local test, four-deck setup,
values restored afterwards):
deck all beatlock on -> deck 1..4 beatlock all read yes
deck all beatlock off -> deck 1..4 all read no
deck 1 beatlock on -> only deck 1 reads yes
So deck all play does start every deck, as the name suggests.
Querying does not aggregate — it answers from the first deck. With deck 1 loaded and deck 2 empty:
deck all get_deck -> 1
deck all loaded -> yes (deck 1's answer; deck 2 reads no)
deck all get_title -> the deck 1 title
An unknown target does error here (deck qqqq loaded -> error:-2147467259), so the target
slot is one of the few places the parser is not silent. Do not read a deck all query as
"all decks agree" — it is deck 1's value, and there is no established aggregate-query form.
Earlier tests could not tell these apart, because the selected deck and the master deck were
both deck 1: every target answered 1, which fits "follows master", "follows selection" and
"always deck 1" equally well. Pinning the two to different decks separates them. With
(selection, master) set to (1, 2) and then (2, 3) (Local test, HTTP, build 9598,
four unloaded and stopped decks, state restored and verified —
capture):
| Target | Answers with | Signature (1,2) → (2,3) |
Status |
|---|---|---|---|
| (no wrapper) | the selected deck | 1 → 2 |
One capture |
deck default |
the selected deck | 1 → 2 |
Repeated |
deck master |
the master deck | 2 → 3 |
Repeated |
deck active |
the master deck | 2 → 3 |
Repeated |
deck playing |
the selected deck, with nothing playing | 1 → 2 |
One capture |
deck left, deck leftvideo |
deck 1 | 1 → 1 |
One capture |
deck right, deck rightvideo |
deck 2 | 2 → 2 |
One capture |
The rows marked Repeated also held and separated in the
playing-deck capture (build 9598), a
different fixture. There the selection stayed on deck 1 while the pinned master and the sole
playing deck were different decks. deck active and deck master answered with the pinned
master, deck default with the selected deck, and deck playing with the playing deck. The
other rows discriminate only in the capture above. The symmetric
scope capture is consistent for bare, left and
right, but its fixture cannot tell the selected deck from the master.
active is not the selected deck. This is the trap the symmetric fixture hid: a script
using deck active to mean "the deck the user is looking at" gets the master deck instead.
The earlier run's 1 was the master deck answering, not a constant and not the selection.
deck playing and deck mixer1…deck mixer4 are recognized targets the wiki's list of
nine does not mention — they return a deck number where a junk target
(deck zzqqx get_deck) returns error:-2147467259.
deck mixerN did not resolve to the identity mapping in the capture above: on this
instance mixer1 → 3, mixer2 → 1, mixer3 → 2, mixer4 → 4, unchanged across both
selections and both master decks, and reproduced by an independent read afterwards. Status:
one capture. The identity predictions for mixer1–mixer3 are retained there as failed.
That these tokens are recognised targets is repeated, because
the confirmation capture separates
deck mixerN constant 37 from junk. The mapping itself has no second measurement. Whether
it is a configurable channel assignment or a fixed internal order is untested, so do not
assume mixerN means deck N.
Three limits on the table. In the capture above every deck was unloaded and stopped, so
playing was observed only in its fallback there. The playing-deck capture covers a single
playing deck with automatic master disabled. That is one capture, and it does not settle
multiple playing decks or automatic-master transitions, which remain untested. And these
are query resolutions; execute-side fan-out is the separate
deck all
result.
The HTTP channel has no press or release, so this was the one part of the language it could not reach. Answered instead with a real MIDI button: a virtual CoreMIDI endpoint matched by a custom device definition, mapped to
set '$codex_fires' +1 & set '$codex_while' 1 while_pressed
and read over HTTP between note-on and note-off (Local test, build 9598 —
fixture).
| Event sent | $codex_fires |
$codex_while |
|---|---|---|
| baseline | (unset) | (unset) |
| note-on — press | 1 | 1 |
| still held, 1.4 s later | 1 | 1 |
| note-off — release | 1 | (unset) |
| second press / release | 2 → 2 | 1 → (unset) |
| third press, then a second note-on with no note-off | 3 → 3 | 1 → 1 |
| note-on with velocity 0 | 3 | (unset) |
Four rules come out of that, and three of them are things a mapper author can get wrong:
- A button action runs on press only. Release does not re-run it; the counter advances once per press and never on note-off. So an action mapped to a button fires once per push.
while_pressedsaves and restores the prior value. It is not a "set then clear". With the variable preset to7, the hold read1and the release restored7, not0and not blank. The blank in the table is the same rule: the prior value there was unset, and unset is what came back.while_pressedbinds its own statement, not the chain. Inset A +1 & set B 1 while_pressed,Breverted on release whileAkept its new value. That settles the open question the earlier HTTP run could only half-answer: mid-chain it does not block later statements, and trailing it does not capture earlier ones.- A repeated note-on while the button is already held does nothing, and note-on with velocity 0 is treated as the release, per the usual MIDI convention. Both matter when a controller sends running-status note-ons instead of note-offs.
The channel detail worth keeping: the virtual endpoint must outlive the tool call that creates
it (launchctl submit, not a background process), and the mapping must be bound in
settings.xml under
controllersCustomization
rather than through the Controllers pane, because VirtualDJ's window exposes no accessibility
elements to automate.
Every one of the 1,427 vendor-written snippets in
tests/vdjscript-corpus.json was sent through /query
(tools/check_corpus_parses.py, gated in just check).
1,099 parse. Not one contradicts a grammar claim in this document. The failures map the
channel's boundary instead, and each class is a rule worth knowing:
| Outcome | Count | What it means |
|---|---|---|
parsed |
1,099 | answered without error |
not-implemented |
152 | E_NOTIMPL — verb exists, this form does nothing on this build |
other-error |
97 | non-standard error codes |
no-value |
28 | E_FAIL — silence, not denial |
surface-gated |
28 | action-position verbs (hot_cue 1, loop_color 3, custom_button 1) sent to a query surface |
pipeline |
15 | get_bpm & param_cast — param_* consumes a value flowing down the chain, and HTTP supplies none |
structural |
7 | see below |
placeholder |
1 | sampler_bank X — a documentation stand-in |
Re-running with loop_active established changed nothing, so these are not missing-state
failures.
The seven residual cases are all execute-position semantics, verb by verb. They error under
/query while their absolute equivalents answer:
| Vendor form | /query |
Absolute equivalent | /query |
|---|---|---|---|
loop 50%, loop 200% |
E_INVALIDARG |
loop 4, loop 0.5 |
no |
pitch_range +1 |
E_INVALIDARG |
pitch_range 8 |
no |
sampler_loop +1, -1 |
E_INVALIDARG |
sampler_loop 1 |
yes |
display_time 'elapsed,remain' |
E_INVALIDARG |
display_time elapsed |
no |
The catalog explains the first row — loop 200% multiplies the loop size and loop 50%
halves it, so they are adjustments, not values, and there is nothing for a query to return. The
+1 forms are the same shape. Note the comma list is not a general rule: display_time 'elapsed,remain' is rejected while browser_window 'folders,songs' answers normally, so
multi-value tails are per-verb.
So: a relative or multiplying argument is execute-only, and asking a query for one is an error rather than silence — one of the few places the parser does report a problem.
Under /query a bad argument is ignored and the verb answers anyway — loaded bogusword
returns yes, the no-error rule — which is why an
argument can only be confirmed against a nonsense control.
Under /execute there is no single rule. Measured on 14 allowlisted settings verbs from
both baselines, values restored and verified (Local test, 2026-09-03,
tools/probe_execute_forms.py); a toggle's signature is
what it reads after the call from off and from on:
| Verb behaviour | bare | junk tail | Seen on |
|---|---|---|---|
| Junk suppresses the action | flips (yes,no) |
nothing (no,yes) |
9 of 10 toggles — beatlock, auto_sync, auto_match_bpm, quantize_all, pad_bank2, pad_pressure_switch, repeat_song, djc_shift, rane_timecode_enable |
| Junk is ignored, action proceeds | flips (yes,no) |
flips (yes,no) |
auto_bpm_transition |
| Junk resets to a fixed value | 0.2,0.2 |
0.2,0.2 |
zoom (a continuous verb, so the columns read as the value left from each baseline) |
So the practical warning for mappers stands but is verb-specific: a misspelled argument usually makes the action do nothing, on some verbs it degrades to the bare action instead, and on at least one it discards the current value. None is reported as an error.
The third row is the dangerous one, because "unknown tokens are ignored" is the intuition
most scripts are written on. Measured on zoom from baselines 0.25 and 0.65, two
passes, restored and verified (Local test 2026-09-12, HTTP execute, build 9598). Every
-> 0.2 form in the first three rows is repeated. The
revised capture held and separated.
The original fallback capture read the
same 0.2 and separated too; its predictions of 0.5 failed and remain recorded as failed.
zoom 0.25 zzqqx is one capture, in the action capture.
zoom zzqqx is the nonsense control itself:
zoom 0.25zzqqx -> 0.2 zoom 25MS -> 0.2 zoom .25 -> 0.2
zoom 0.25<tab> -> 0.2 zoom 1e-1 -> 0.2 zoom #zzqqx -> 0.2
zoom 'default' -> 0.2 zoom 0x1 -> 0.2 zoom -> 0.2
zoom 0.25 zzqqx -> 0.25 zoom zzqqx -> unchanged
Both endpoints matter. A token that starts like a number and then fails to parse —
wrong-case suffix, exponent, hex, no leading digit, junk welded to the digits — lands on the
same 0.2 that bare zoom produces, wiping whatever the value was. A purely alphabetic
unknown token (zzqqx) is ignored and leaves the value alone. Space-separating the junk
(zoom 0.25 zzqqx) keeps the parsed number, so adjacency is what decides it.
zoom #zzqqx lands on 0.2 for a different reason: # opens a
comment and discards the rest, leaving bare zoom. The same
mechanism reads harmlessly on a toggle — deck 1 beatlock #zzqqx simply toggles.
Same fixture and build, one action capture.
For zoom, the sign is not decoration: it selects the operation. zoom 0.25 and
zoom +0.25 are repeated. They read the same on build 9628 after a
param_cast float pipeline, in the
pipeline and
confirmation captures.
The other rows are one capture:
zoom 0.25 -> 0.25, 0.25 absolute
zoom +0.25 -> 0.5, 0.9 relative
zoom -0.25 -> 0, 0.4 relative
zoom 25% -> 0.25, 0.25 percent maps onto the same absolute scale
zoom +25% -> 0.5, 0.9
zoom 2.0 -> 1, 1 absolute, clamped
zoom -2.0 -> 0, 0 relative, clamped
A verb may accept only one of the two forms, which is why
beatjump needs its sign (beatjump +4 jumps, beatjump 4
does nothing) and why a signed integer on a switch verb toggles instead of setting. Check
the verb record before assuming a bare number works.
Two forms that look valid did not set zoom: a bare integer (zoom 1, zoom 0) and a
duration (zoom 25ms, zoom 25bt). They left both baselines where the nonsense controls
did, and they did not reset to 0.2. Status: matches controls, one capture. Whether
they are parsed and rejected as the wrong type, or not accepted at all, is unresolved.
Two-baseline measurement is what separates these at all. From a single baseline, beatlock on
and beatlock <junk> both end up on and look identical; only running from both baselines
distinguishes set (yes,yes) from flip (yes,no) from no-op (no,yes).
Less than expected, which is itself worth recording. Across those 14 verbs — each probed with
its own recovered candidates plus the 25-token shared lexicon — exactly one token appeared
that the query sweeps had not found: auto_bpm_transition all, which is the no-op signature
on a verb whose junk tail flips, i.e. all is parsed and suppresses the toggle. That is
consistent with all being a target keyword
rather than vocabulary belonging to this verb.
Corrected 2026-09-03, same day: this section first read that the verbs' own candidates
(source_original, target_current, target_original) "behaved exactly like junk here, so
the query sweep's negative on them is corroborated". That was wrong, and the error was the
observable, not the data. The official verbs appendix documents all three as parameters of
auto_bpm_transition that force which BPM the transition lands on. The probe watched the
verb's own boolean readback — whether a transition is running — which cannot see which BPM
it targets, so a real parameter was indistinguishable from junk by construction.
The lesson generalises past this verb: a signature test is only as good as its observable.
Two-baseline signatures answer "did this token change what the verb did to its own state"; a
token that steers how an action runs, or that affects a different piece of state, is
invisible to it. Verbs whose tail selects a mode or a target need an observable chosen for that
tail — here, two decks at different BPMs and a readback of the resulting BPM over time. Treat
tail-ignored-in-execute as "not visible in this observable", never as "not a parameter".
Inside XML attributes, & must be written &:
<pad action="set '$mode' 1 & load_skin" />This is XML escaping, not VDJScript syntax — it does not apply to the HTTP channel, where
the whole script is URL-encoded instead. < and > need the usual XML entities too.
The fastest way to settle a grammar question is to ask the running app. Queries are read-only:
just vdj-query 'on ? get_version : get_clock'Before that, a static pass catches the forms this document has already shown go wrong —
empty branches, && in front of an action, a trailing chain after a ternary, a truthiness
trap, a name the verb table does not hold — with the section each rule comes from:
just lint-script --script "cond && play" --context actionRemember what an answer does and does not prove: a returned value means the construct
evaluated, not that it parsed the way you intended, and no output at all is far more
often a silently-dropped argument than a rejected script. Prefer probes whose two possible
answers are visibly different — that is why the examples above use get_version against
get_clock rather than two effects that might both be empty.
This is where each runtime-parser rule above stands after the H4 reconciliation. Captures
are under tests/. just runtime-grammar --artifact <capture> --get <case> returns the
exact case, and just runtime-grammar --audit joins cases to branch families. Behaviour is
from builds 9598 and 9628. The b9246 binary only suggested which questions to ask.
| Rule | Status | Captures |
|---|---|---|
Quoted keyword did not set beatlock; bare keyword did |
Bare keyword: one capture. Quoted: matches controls | runtime-grammar-actions-9598 |
beatlock argument vocabulary |
One capture (inert row: matches controls) | runtime-grammar-actions-9598 |
Unit suffixes attach lower-case and adjacent (constant) |
One capture (wrong-case and double-suffix rows: matches controls) | runtime-grammar-confirmation-9598; interrupted runtime-grammar-live-9598 agrees |
Wrong-case suffix is malformed on zoom |
Repeated | runtime-grammar-action-default-9598, runtime-grammar-action-fallback-9598 |
| Comma decimal | One capture per channel | runtime-grammar-confirmation-9598 (query), runtime-grammar-actions-9598 (execute) |
Malformed number resets zoom to 0.2 |
Repeated | runtime-grammar-action-default-9598, runtime-grammar-action-fallback-9598 |
Separated junk keeps the parsed number (zoom 0.25 zzqqx) |
One capture | runtime-grammar-actions-9598 |
Signed relative, unsigned absolute on zoom |
0.25/+0.25: repeated. Other forms: one capture |
runtime-grammar-actions-9598; runtime-grammar-incoming-pipeline-9628, runtime-grammar-incoming-pipeline-confirmation-9628 |
Bare integer and duration did not set zoom |
Matches controls | runtime-grammar-actions-9598 |
Backticks in zoom/beatlock execute forms not applied |
Matches controls | runtime-grammar-actions-9598 |
Paired backticks evaluate in effect_active execute |
Repeated | runtime-grammar-effect-boolean-initial-9628, runtime-grammar-effect-boolean-9628 |
| Computed deck prefix returns the junk-target error | Matches controls | runtime-grammar-scopes-9598, runtime-grammar-scope-followup-9598 |
active/master → master deck; default → selected deck |
Repeated | runtime-grammar-master-9598, runtime-grammar-playing-9598 |
Bare, playing fallback, left/right/*video targets |
One capture | runtime-grammar-master-9598 |
mixerN recognised as a target |
Repeated | runtime-grammar-confirmation-9598, runtime-grammar-master-9598 |
mixerN → non-identity deck permutation |
One capture (identity predictions failed) | runtime-grammar-master-9598 |
H4 also produced captured candidates that were never promoted here and stay unresolved
as grammar: unmatched quotes in chains, empty quoted operands, and incoming-parameter
selection (… & param_cast float & zoom). They are in
Runtime Argument Grammar Tests, with their captures.
Do not guess in these gaps; test and record.
-
Three runtime-parser limits (named at H4 closure, 2026-09-19). It is not known whether script in Remote skins or during skin load parses differently, how list-valued parameters are chosen, or whether Button Editor token spans agree with the runtime. Each is a named limit, not a finding.
-
— answered 2026-09-14 on a real MIDI button. It saves and restores the prior value, and it binds its own statement only. See Button lifetime.while_pressedrelease behaviour -
Backtick boundaries in nested quoting:
param_equal "`get_text 'x'`" "x" ? on : off— and which argument consumers evaluate nested expressions on each surface; the consumer-specific HTTP results above do not settle every quoting boundary. -
The exact chain ceiling and what drives it (parse buffer? execution budget?).
-
Whether— answered 2026-07-30:&&'s query-position short-circuit is deliberate or a parse artefact&&is not a distinct operator structurally (identical parse to&, and identical action-position behaviour with readback). It only changes which statement's value a query reports. See Boolean composition with&&. -
Operator-lookalike names in verb argument position, e.g. a verb whose parameter is literally
on, where a constant and a value collide.setis settled. Forbeatlock, one capture found the opposite split: bareonsets, and quoted'on'matched the nonsense controls (Quoting a keyword argument). That is not yet repeated, and whether the split isIActionSwitch-wide or per-verb is still open.
Recording an answer: put the observation in VDJScript Local Test Tracker with the build and surface, then promote the rule into the matching section above.