Version en Français
Versione in Italiano
Versão em Português
Examples of VDJScript actions
VDJscript is the language in which all commands in VirtualDJ 6 and 7 are written.
It is used in skins, keyboard shortcuts or controller mappers.
It has been designed to be simple and short when used for simple actions, but versatile enough to allow complex scripting and macros.
In its simplest form, you can write commands like "play", "pause", "goto_cue 1", "volume 70%", "pitch +0.5%", etc...
Or you can write complex macros like "play ? crossfader +12.3% & effect 'flanger' activate : deck 2 loop 4 & set $myvar 42"
The basic elements of VDJscript are "verbs".
You can find a list of the verbs understood by VirtualDJ in the "see also" box in the Settings/Mapper window in VirtualDJ.
Or, alternatively, you can open the file English.xml in the Documents/VirtualDJ/Languages/ folder, and check all the verbs (and their description) under the <action> element.
The most basic command would consist of only a verb (like "play" or "pause").
Optionally, the verb can be accompanied by different modifiers and parameters:
- deck: you can specify which deck the verb act upon by adding "deck xxx" in front of the verb. xxx can be "1", "2", "left", "right", "default" or "active". ("1"/"left" and "2"/"right" are synonyms).
- parameters: the verb can be followed by one or two parameters. The function of these parameters depends on the verb. parameters can be strings, percentages, booleans, times, integer values, or decimal values.
- effects: for verbs acting on effects, you need to prepend the verb with the keyword "effect", optionally followed by the effect name or effect slot number: "effect activate" or "effect 'flanger' slider 1 100%".
- sampler: for verbs acting on the sampler, you need to prepend the verb with the keyword "sampler", optionally followed by the sampler slot number: "sampler activate" or "sampler 3 volume 100%".
- queries: all verbs usually can be queried for their 'state' and returns a boolean. But some specific queries that need to return some text or numbers, need to use the keyword "get" before the verb: "get time_ms".
- temporary action: you can specify that the verb is to act only while the button is pressed by adding "while_pressed" at the end of the command: "volume 100% while_pressed".
- blinks: for queries, you can add "blink" or "blinkfast" to get the boolean answer blinking between true and false if the original answer was true: "play blink" [Deprecated: use the verb "blink" instead: "play ? blink : nothing"]
The full command syntax is:
( [...] means : optional )
( | means : or )
If you need to write more complex macros, you can use the operator "&" to chain commands, or the operators "?" and ":" to write conditional branching.
Using "command1 & command2 & command3" will execute the command1, then execute the command2, then command3.
Using "command1 ? command2 : command3" will query the state of command1, and if the result is true, execute command2, otherwise execute command3.
Using "action_deck 1? command1 : command2" will execute the command1 if the button on the controller was defined to work on deck 1 (see "definition" xml file) or execute the command2 if the button was defined to work on deck 2
Actions vs queries
Commands can be used either as actions or as queries, depending on the context.
For example, the command "play" used in a keyboard shortcut, will be an action, and start to play the music when called.
The same command "play" used as a mapping for a controller's LED, will be a query, and will return true if the song is playing, or false if not.
Some commands can return a boolean (true or false) or a value, depending on the parameters:
- "crossfader" will return the value (between 0.0 and 1.0) if used in a query.
- "crossfader 42%" will return true if the crossfader is at 42%, and false otherwise.
Commands using the keyword "get" can also return a string or a number, depending on the verb.
VDJscript knows 6 types of parameters:
- text: need to be enclosed in either single quotes (') or double quotes ("): "load 'myfile.mp3'"
- boolean: can be the keywords "on", "off" or "toggle". (they are often equivalent to the integers 1, 0 and -1 respectively): "smart_play off"
- time: are specified by adding the keyword "ms": "nudge +100ms"
- integer: "effect select +1"
- decimal: "crossfader 0.5"
- percentage: "crossfader 50%"
Most of the time, decimal and percent are treated as same (after dividing the % by 100 of course).
There are a few exceptions, like the verb "pitch", where "pitch 100%" sets the pitch to the middle, while "pitch 1.0" sets the pitch to the maximum of the slider.
Keep in mind also that "nudge +1" and "nudge +1.0" is not the same thing. The first moves from 1 beat, while the second is equivalent to "nudge +100%" which jumps at the end of the song. Most of the time you should use percents instead of decimals, but if you write complex scripts it's worth knowing.
When a command is used as an action for a slider (or knob, jogwheel, etc), the value of the slider will be added as an implicit parameter.
When an implicit parameter is added, it is added at the end of the command, as an additional parameter coming just after the existing ones.
So if your action is "volume" and you map this to a slider that you move to 42%, the action sent will be "volume 0.42".
But if your action is "volume +10%", the action sent will be "volume +10% 0.42" (and the second parameter 0.42 will just be safely ignored because the verb volume expects only one parameter).
If you need to modify the implicit parameter, you can use some verbs like "param_multiply", "param_add", etc...
So "param_multiply 0.1 & volume" will result in setting the volume at 4.2%
If you have a macro with several commands, each commands will have the implicit parameter added.
So if you write "crossfader & loop" and map that to a slider that you move to 42%, the action sent will be "crossfader 0.42 & loop 0.42".
If you want to prevent the implicit parameter to act on some commands, you can use the keyword "value" to specify where the implicit parameter should go.
So "crossfader value & loop" will send "crossfader 0.42 & loop".
(you can have several occurence of "value" in your macro, each one will be replaced by the implicit parameter).
Also, it's worth knowing that sliders will add a decimal parameter ("crossfader" -> "crossfader 0.42"), jogwheel will add a relative decimal ("crossfader" -> "crossfader +0.42", +1.0 being a full revolution of the wheel), and encoders will add a relative integer ("crossfader" -> "crossfader +1").
If you use an encoder for a verb that expects a slider, the integer will be automatically converted to a decimal by dividing it by 32 (so that one needs 32 steps of the encoder to move the slider from 0% to 100%). So in the previous example "crossfader +1" is equivalent to "crossfader +0.03125". You can use "param_multiply" if you need another resolution.
VDJscript can store states or numbers in internal variables.
If the name of the variable starts with a $ (like "set $myvar"), the variable will be 'global' to both decks.
If the name of the variable starts with a % (like "set %myvar") or with nothing (like "set 'myvar'"), the variable will be 'local' to this deck (and can have a different value if used on the other deck).
Variables are persistent during the whole time VirtualDJ is running (they are not local to a specific controller or skin).
To set a variable, you can use verbs like "set", "toggle", "cycle".
To read a variable, you can use verbs like "var", "var_equal", "var_smaller", etc...
A typical example of using variables is to have "set $myshift while_pressed" on a shift button, and "var $myshift ? command1 : command2" on another button.