Scripts

The basic idea

Scripts add logic to commands and events.

DeviceJockey runs JavaScript in supported commands and events. Scripts can read and change Swaps, inspect item state, calculate values, write diagnostic messages, and use functions provided for the current context.

Command Scripts

Send Local Interface values.

A Local Command Script can call sendCommand(). The first argument is the Local path. The second argument is the value. An optional third argument defines its type.

sendCommand("/test", "Hello")
sendCommand("/test", 10)
sendCommand("/test", 10, "float")
sendCommand("/test", 10.5, "int")
sendCommand("/test", 1, "bool")
sendCommand("/test", true, "bool")

Interface Script Commands

Generate Art-Net and OSC output.

sendArtNet(128, 1)

// 16-bit value using coarse and fine channels
sendArtNet(128, 1, 2)

let arguments = [
  ["Example"],
  [10, "int32"],
  [20, "float"],
  [true, "bool"]
]

sendOSC("/test", arguments)

Swaps

Use Swap names like JavaScript variables.

A Swap can be read or assigned directly by using its exact name:

console.log(mySwap)
mySwap = "Hello world"

The escaped form is replaced before the Script runs. It is useful when the Swap value should become part of a string or part of the Script itself.

console.log("Hello \(mySwap)")

Resolve a Swap stored inside another Swap

If one Swap contains another Swap expression, use getSwapValue() to retrieve the fully replaced value.

// swapA contains the text \(swapB)
// swapB contains 10

console.log(swapA)              // prints \(swapB)
console.log(getSwapValue(swapA)) // prints 10

Remote Options

Choose commands from inside an Event Script.

The remote() function changes which command triggers the current event executes.

remote("all", true)   // enable all triggers
remote("all", false)  // disable all Remote Options
remote("d", true)     // disable control
remote("s", true)     // mark as system event
remote("1", true)     // enable trigger 1
remote("20", false)   // disable trigger 20

Trigger numbers from 1 through 20 are supported.

OSC event values

Format received values for a label.

In supported OSC and Behringer/Midas Label Events, labelValue contains the first received argument. The oscArguments array contains all received arguments. The Script result becomes the label text.

This example converts a value from 0 to 1 into a logarithmic frequency from 200 Hz to 20 kHz:

const maxF = 20000
const minF = 200
const x = Math.min(Math.max(0.0, labelValue), 1.0)
const m = maxF / minF
const frequency = minF * Math.pow(10.0, x * Math.log10(m))

formatFrequency(frequency)

function formatFrequency(frequency) {
  if (frequency < 1000) {
    return Math.round(frequency).toString()
  }

  const k = frequency / 1000
  const rounded = Math.round(k * 10) / 10
  return (rounded % 1 === 0
    ? rounded.toFixed(0)
    : rounded.toFixed(1)) + "k"
}

console.log(oscArguments)

MIDI Clock

Use transport and timing variables.

A Script in a MIDI Clock event can access these built-in variables:

console.log(midiBar)
console.log(midiBeat)
console.log(midiBPM)

Logging and color conversion

Inspect values and convert colors.

Use console.log() while developing a Script:

console.log("Script started")
console.log(itemValue)
console.log(itemSelected)
console.log(itemLight)
console.log(itemProtected)

Convert between RGB and HSL when a Script calculates colors:

let hsl = rgb2hsl(red, green, blue)
let hue = hsl["h"]
let saturation = hsl["s"]
let lightness = hsl["l"]

let rgb = hsl2rgb(hue, saturation, lightness)
let convertedRed = rgb["r"]
let convertedGreen = rgb["g"]
let convertedBlue = rgb["b"]

Practical workflow

Build and test Scripts in small steps.