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:
- press always fired immediately after the control is pressed
- short_press fires after the control is pressed then released in quick succession
- long_press fires after the control is held for a brief period
- release always fires immediately after the control is released
- long_release fires after the held control is released — will only fire after a
long_pressevent - double_click fires after the control is pressed twice in quick succession
Note
Previous versions of zcx used different names for these gestures: pressed, released_immediately, pressed_delayed, released, released_delayed, and double_clicked.
You may continue to use these names if you prefer.
Note
The double_click 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.
quotes in strings¶
Very often, ClyphX action lists include quotation marks, e.g. "my track" / SEL. This causes a small problem with yaml:
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¶
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:
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.
modes syntax¶
When using modes in zcx, the syntax is extended:
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 (__).
multiple matching gestures¶
If you have a configuration like above, where there are multiple variations on the press 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.
cascading gestures¶
You may configure a control to execute all matching command bundles in sequence.
This is done by setting the control's cascade option to up or down:
This will execute command bundles in order of least-specific to most-specific, i.e pressed, pressed__shift, and pressed__shift__select.
Setting cascade: up will reverse this order.
conflicting gestures¶
Take this example:
With both the shift and select modes active, only the pressed__select gesture will fire.
This is because pressed__select is defined last.
You can use cascading to fire them both.
command syntax¶
The default command fires a ClyphX action list:
This is equivalent to:
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:
command types¶
cxp¶
Accepts an action list as a string and triggers it in ClyphX.
page¶
Accepts a page name, page number, or keyword, and switches to that page:
keywords¶
next
Goes to the next page.
prev
Goes to the previous page.
last
Goes back to the page that was active before the current one.
mode_on, mode_off, mode¶
Enables, disables, or toggles the given mode:
overlay¶
Enable, disable, or toggle the given overlay.
msg¶
Shows a message briefly at the bottom of Live's UI:
This is, in most cases, functionally equivalent to doing:
log¶
Prints a message directly to Live's Log.txt:
color¶
Change the control's color.
See also:
on_color, off_color¶
As above, but sets on/off or active/inactive colors. Only available on controls with such feedback, including the param control, page control and others.
ring¶
Move the session ring of the script.
relative moves¶
Move the ring along its x (track) or y (scene) axis.
up:
gestures:
press:
ring:
y: -1
right:
gestures:
press:
ring:
x: 1
down:
gestures:
press:
ring:
y: 1
left:
gestures:
press:
ring:
x: -1
simplified syntax¶
You can simply specify a direction rather than using x and y values.
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.
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.
keyboard¶
Adjust the settings of the melodic keyboard view.
pseq / rpseq¶
Emulates sequential action lists from ClyphX Pro.
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:
press:
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.
refresh¶
Force zcx to refresh all LED feedback.
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.
hot_reload¶
Perform a hot reload.
special commands¶
Some control types may feature unique command types. You can find information on these commands on each control's reference page.