zcx concepts¶
zcx uses a lot of jargon. Here is a quick guide to the most important concepts.
ZControls¶
Roughly equivalent to an X or G control from ClyphX Pro. You define ZControls in your configuration files and when you press their associated button they trigger action lists or some other functionality.
Terminology
In this documentation, when we use the word "button" we are referring to the physical input on your MIDI controller. When we use the terms "control" or "ZControl", we are referring to the abstract concept. As one button is usually associated with several ZControls, this distinction will become important.
control definitions¶
A control definition is a yaml object provided by you that describes how a control should behave.
Most control definitions will have the keys color and gestures.
gestures¶
Gestures are physical actions you can perform on a button, which will in turn trigger a command on a ZControl. 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
commands¶
Commands fire in response to gestures, and are usually a ClyphX Pro action list:
Here, the gesture is the key, and the command is the value.
modes¶
Any control can be assigned as a modifier or 'mode' control. A mode is just a keyword that can be on or off. You can configure your other controls to behave differently depending on whether the mode is active or not.
Above we see a control called shift.
It responds to the gestures press and release.
These gestures fire the mode_on and mode_off commands respectively.
The value for these commands is also shift.
So, whenever the control shift is held down, the mode shift is on.
This record control has the press and press__shift gesture.
As you may have guessed, this control will fire the action list SRECFIX 8 when pressed, unless the shift mode is active, in which case it does SRECFIX 16.
You can even require multiple modes for particular functionality:
The names of these modes are completely arbitrary, but they must be defined in your modes.yaml file.
named controls and matrix controls¶
Although MIDI controllers come in all shapes and sizes, zcx is focused on controllers with a 'matrix' or grid of pads or buttons, such as the Ableton Push, Novation Launchpad, Akai APC, and others like them. Because of this, zcx makes a distinction between controls that form the matrix, and those that don't.
named controls¶
These controls exist outside of the matrix. They can be given a simple name, and we can refer to them by that name throughout our configuration. Often, the control's name will be printed on the control.
All named controls are defined in one place, named_controls.yaml:
Note
The names used in named_controls.yaml and encoders.yaml have already been mapped to MIDI messages sent by your hardware.
To check the names of each control, see the Hardware Reference
matrix controls¶
And obviously, these controls exist within the matrix.
In our configuration we don't define them by name or coordinate, but by position within their containing section.
matrix sections¶
A matrix section is a logical segment of the matrix, defined by row and column. These sections you define can be any size.
# 0 □ □ □ □ □ □ □ □
# 1 □ □ □ □ □ □ □ □
# 2 □ □ □ □ □ □ □ □
# 3 □ □ □ □ □ □ □ □
# 4 □ □ □ □ □ □ □ □
# 5 □ □ □ □ □ □ □ □
# 6 □ □ □ □ □ □ □ □
# 7 □ □ □ □ □ □ □ □
# 0 1 2 3 4 5 6 7
#
actions_top_left: # 0 1 2 3
col_start: 0 # 0 □ □ □ □
col_end: 3 # 1 □ □ □ □
row_start: 0 # 2 □ □ □ □
row_end: 3 # 3 □ □ □ □
actions_top_right:
col_start: 4
col_end: 7
row_start: 0
row_end: 3
track_section:
col_start: 0
col_end: 7
row_start: 4
row_end: 7
The dimensions or bounds of the matrix are defined in _config/matrix_sections.yaml.
However, each section then needs its own config file in _config/matrix_sections/<section name>.yaml.
So, looking at the above config, your config directory would have these files:
zcx/
├─ _config/
│ ├─ matrix_sections/
│ │ ├─ actions_top_left.yaml
│ │ ├─ actions_top_right.yaml
│ │ ├─ track_section.yaml
│ ├─ matrix_sections.yaml/
And in each of those files you define a list, containing a definition for every pad that belongs to that section:
# row 1
# col 1
- color: red
gestures:
press: METRO
# col 2
- color: blue
gestures:
press: SETPLAY
...
Skeleton sections
The demo config that comes with zcx features several mostly-empty sections that are great for getting started, as they have a minimal control definition with helpful comments denoting the row and column of each control.
Later, you may want to use the generator to create your own skeletons of custom size.
pages¶
So matrix controls are contained within matrix sections, but there's one more layer: sections are contained within pages:
pages:
home_page:
- actions_top_left
- actions_top_right
- actions_bottom_double
alt_page:
- actions_top_left
- actions_bottom_right
- actions_bottom_left
- actions_top_right
ring_page:
- ring_control
blank_page:
- blank_section
The pages system means that you can change your matrix controls entirely depending on the context. By assigning controls to sections, and not directly to pages, we can have one section appear on multiple pages, or even on all of them, without defining the same control every time.
Matrix sections are always bound to their defined coordinates, which means while they can appear on multiple pages, they'll always be in the same place.
intersecting sections¶
By default, we can't have two sections that intersect, i.e share one or more of the same coordinates.
big_section:
col_start: 0
col_end: 7
row_start: 0
row_end: 7
tiny_section:
col_start: 0
col_end: 7
row_start: 0
row_end: 0
big_section and tiny_section are both reserving the first row of the matrix on the page my_page.
In this situation, zcx will throw an error on startup.
You can learn how to intentionally intersect sections in this lesson.
overlays¶
Only matrix controls are affected by page changes; named controls will behave the same way regardless of the current page. We can define multiple named controls associated with the same button by using an overlay.
In the next lesson, you will learn about any overlays that come with the zcx demo config, or you can skip ahead to the overlay lesson.
encoder mappings¶
zcx allows you to dynamically map encoders (knobs, faders, etc.) to parameters in Live. Targeting of parameters follows the same syntax as ClyphX Pro encoder bindings:
Encoders are also mode-aware:
You can read more about encoder mappings in the Encoder Reference
dynamic controls¶
The most common type of control you'll use is the standard ZControl. There are also special classes of control that offer extra functionality, usually in the LED feedback they provide.
One class of control is the page control, which is bound to a page you specify. It shows one color when its bound page is in view, and another when it isn't. Another is the param control, which binds to almost any parameter in Live, indicating its status.
See the Control Reference to learn more about the different control types.
templating¶
zcx features a powerful templating system that allows you to configure multiple controls at a time. By using this system, you can make a change in one place and have it affect any number of controls, saving you time when creating and, later, updating your config.
Here is an example of the templating system:
__scene_buttons:
includes: [scene_1, scene_2, scene_3, scene_4]
gestures:
press: SCENE ${me.Index}
This is a group definition.
We have grouped the buttons scene_1 through scene_4 under the includes key to apply a common definition to them.
There is one gesture defined, press, with the command (action list) SCENE ${me.Index}.
The ${me.Index} is new syntax called a template string.
Behind the scenes, zcx will evaluate these strings so that the controls fire SCENE 1 through SCENE 4.
The benefits of this system become apparent when we want to extend the control:
__scene_buttons:
includes: [scene_1, scene_2, scene_3, scene_4]
gestures:
press: SCENE ${me.Index}
press__select: SCENE SEL ${me.Index}
With just one line of yaml we have extended the definition for all four controls in the group.
going further with templating¶
The purpose of this section is to provide a brief overview of template strings. If you have explored the zcx demo config in your code editor, you would have seen many examples of them, so it's important to have some idea what you're looking at.
After finishing this "Getting Started" tutorial, you might want to check out the Template Reference for a deeper understanding of the templating system.