Command Reference¶

In zcx, a command is something that happens when a control is interacted with. Usually this means firing a ClyphX Pro action list.

gestures¶

Gestures are physical actions you can perform on a control to trigger a command. There are six gestures supported by zcx:

pressed always fired immediately after a control is pressed
pressed_delayed fires after the control is held for a short time
released always fired immediately after a control is released
released_delayed fired after a held control is released — will only fire after a pressed_delayed event
released_immediately fired after a control that was not being held is released
double_clicked fired after a control is pressed twice in quick succession

Note

The double_clicked gesture may be unituitive. See the lesson to undestand how it works.

gesture syntax¶

To define gestures on a control, add a gestures key, with key/value pairs of gesture/command.

my_control:
  color: green
  gestures:
    pressed: SEL / PLAY
    released: SEL / STOP

quotes in strings¶

Very often, ClyphX action lists include quotation marks, e.g. "my track" / SEL. This causes a small problem with yaml:

  gestures:
    pressed: "my track" / SEL

Because of the quotes around my track, yaml interprets my track as the value for pressed, and then freaks out when it sees the rest of the action list (/ SEL). There are two ways to deal with this.

block scalar syntax¶

gestures:
  pressed: >    # this `>` character indicates a block scalar
    "my track" / SEL

This is the recommended method. Yaml will interpret the whole line "my track" / SEL as the action list.

This syntax also makes it easy to spread out long action lists over multiple lines for clarity:

pressed: >
  "my track" / ARM ON ;
  "my track" / MON AUTO ;
  "my track" / RECFIX 8

quotes within quotes¶

By wrapping the entire action list in single quotes, we can freely use double quotes. This works, but is harder to read.

gestures:
  pressed: '"my track" / SEL'

modes syntax¶

When using modes in zcx, the syntax is extended:

gestures:
  pressed: SREC FIX 4
  pressed__shift: SREC FIX 8
  pressed__shift__select: SREC FIX 16

Gesture definitions always start with one of the six supported gestures. Modes can be added by appending the name of each mode prefixed with a double underscore (__).

Note

If you have a configuration like above, where there are multiple variations on the pressed gesture, only the most specific definition will be executed.

E.g. if shift is active, the action list SREC FIX 8 will fire but SREC FIX 4 will not. If both shift and select are active, only SREC FIX 16 will fire.

command syntax¶

The default command fires a ClyphX action list:

my_control:
  gestures:
    pressed: SEL / MUTE

This is equivalent to:

my_control:
  gestures:
    pressed: 
      cxp: SEL / MUTE

The cxp key is specifying the command type. Because cxp is the default command type, it's usually not necessary to specify it.

command bundles¶

You may 'bundle' a combination of command types and execute them sequentially when a gesture is performed:

my_control:
  gestures:
    pressed:
      cxp: METRO
      msg: activated the metronome
      log: activated the metronome

command types¶

cxp¶

Accepts an action list as a string and triggers it in ClyphX.

gestures:
  pressed: 
    cxp: SETPLAY

gestures:
  pressed: >
    "my track" / SEL; 
    "my track" / ARM ON;
    SREC 8

page¶

Accepts a page name, page number, or keyword, and switches to that page:

gestures:
  pressed:
    page: 0
  pressed__shift:
    page: my_cool_page
  pressed__select:
    page: next

keywords¶

next

page: next

Goes to the next page.

prev

page: prev

Goes to the previous page.

last

page: last

Goes back to the page that was active before the current one.

mode_on, mode_off¶

Enables or disables the given mode:

gestures:
  pressed:
    mode_on: shift
  released:
    mode_off: shift

msg¶

Shows a message briefly at the bottom of Live's UI:

gestures:
  pressed:
    msg: Look at my super cool message!

This is, in most cases, functionally equivalent to doing:

pressed: >
  MSG "Look at my super cool message!"

log¶

Prints a message directly to Live's Log.txt:

pressed:
  log: failed successfully

color¶

Change the color of the activated control.

pressed:
  color: green
released:
  color: initial

ring¶

Move the session ring of the script.

relative moves¶

Move the ring along its x (track) or y (scene) axis.

up:
  gestures:
    pressed:
      ring:
        y: -1

right:
  gestures:
    pressed:
      ring:
        x: 1

down:
  gestures:
    pressed:
      ring:
        y: 1

left:
  gestures:
    pressed:
      ring:
        x: -1

simplified syntax¶

You can simply specify a direction rather than using x and y values.

left:
  gestures:
    pressed:
      ring: left

absolute moves¶

Directly position the left-most or top-most edge of the ring to a particular track or scene.

by track¶

Specify a track name (recommended) or number. When specifying a number, the number is zero-indexed.

my_button:
  ring:
    track: my cool track

my_button:
  ring:
    track: 0

by scene¶

Specify a scene name (recommended) or number. When specifying a number, the number is zero-indexed.

When targeting an X-Scene by name, you must use the X-Scene's identifier. E.g., with a scene name like [my cool scene] ALL / MUTE; METRO ON, you would use my cool scene as the scene name.

my_button:
  ring:
    scene: 7

my_button:
  ring:
    scene: my cool scene

pseq / rpseq¶

Emulates sequential action lists from ClyphX Pro.

my_control:
  gestures:
    pressed:
      pseq:
        - >
          "my first track" / SEL
        - >
          "my second track" / SEL

The value of a pseq or rpseq key must be a list, with each list item being a command bundle (or action list). pseq will step through each command in order, while rpseq will trigger a random command (repeat commands are possible).

python¶

Execute Python code in a limited execution context.

my_control:
  gestures:
    pressed:
      python: |
        for i, track in enumerate(song.tracks):
          if i != 0 and i % 15 == 0:
            print("fizzbuzz")
          elif i != 0 and i % 5 == 0:
            print("buzz")
          elif i != 0 and i % 3 == 0:
            print("fizz")
          else:
            print(track.name)

hardware_mode¶

For a multimode controller (e.g. Push), force the controller back into 'Live' mode.

my_control:
  gestures:
    pressed:
      hardware_mode: live

refresh¶

Force zcx to refresh all LED feedback.

my_control:
  gestures:
    pressed:
      refresh: true

Note

Generally, it should not be necessary to use this command. If you are using this command to work around an issue you're having, please consider reporting a bug.