Cues¶

The cue system can be used to create timelines and arrange sections of a composition or even full songs. A cue is a timeline with one or more steps that contain actions in the form of code. With the code actions such as switching patterns, note lists and even switching to or starting other cues can be triggered.

Using cues¶

Press cue+# to start cue #. By default the main clock is started when a cue is triggered but this can be disabled by setting start on cue trigger to false in settings. From the sequencer view the active cue can be seen:

../_images/cue-in-progress.png — Cue 0 is running and the most recently executed step is 2¶

Editing cues¶

Cues are edited using the cue editor which can be opened by pressing edit+cue and closed by pressing shift+yes.

In the cue editor a single cue is shown with the timeline of a cue from left to right. Along the timeline the cue steps are shown with the step number below the timeline and the length of the of the step above the timeline. Dark gray ticks highlight the main clock beats with brighter ticks every 4 and 16 beats.

To the right you can see the current cue progress with from left to right: the current cue, the current step, the time until the next step is reached and finally the number times the cue has looped. If cues are triggered from other cues with startCue() multiple rows of cue progress is shown.

Note

By default time is shown as beats.ticks. If clock mult is set to 8, a time value of 4.2 corresponds to 34 ticks (4 beats * 8 clock mult + 2 ticks = 34)

X scrolls through the cue steps on the timeline.
Y changes the value that is blinking.
Pressing and turning X changes what value is edited using Y:
- step length sets the length of the current step. By changing the step length all steps that follow the current are also moved on the timeline. If shift is held however the currently selected step can be moved on the timeline without moving the other steps.
- clock mult sets resolution of the cue’s timeline.
- start sets the cue starting quantization when triggered using cue+#. If set to 4 for example, when the cue is selected by pressing cue+# it will wait with starting until the beginning of the next 4 beats (in relation to the main clock reset).
- loop sets how many times a cue loops.

Note

By default start and step length/step position changes in beats (or inc/decrements of clock mult). For precise adjustments press and turn Y to change time in single ticks.

Press edit and select add step to add a cue step to the right of the currently selected step.
Press no to remove the currently selected cue step.
Press + or - to move the selected cue step on the timeline.
Press edit and select change cue label to set a label for each cue, which will be shown in the top of the screen.

Starting cues using MIDI¶

Cues can be triggered using MIDI note on, control change or program change messages. MIDI mappings are assigned using a process often called MIDI learn.

To add a MIDI mapping to a cue:

Press edit to open the editing menu.
Scroll to add MIDI mapping and press yes.
Send a MIDI message to the PolyPulse by pressing a keyboard key or turning a knob or fader on your MIDI controller.
Press yes when the correct MIDI message is shown.

Editing cue steps¶

The currently highlighted cue step can be opened and closed by pressing yes. Cue steps contain code that is executed when the step is reached.

X moves the cursor one through the code one character at a time. Press and turn X to move a line up or down.
Y changes the number directly left of the cursor (if there is one). The function argument is visible on the top right of the screen.
no removes a single character.
shift+no removes a full line.
Holding shift while moving the cursor selects code so it can be removed (no) or copied (edit → copy code)

When code is changed the cue editor will automatically recompile code so the cue step can be executed. If the code contains an error it will be underlined and an error message shown. If the cue is running and encounters a cue step with an error the step will not be executed and the timeline will continue moving to the next step.

Adding actions to cue steps¶

To make things happen functions need to be called. Common functions such as setPattern and setNoteList() are added using the same button combination as used when invoking these actions while performing. For example: pressing pattern+# adds setPattern() to the code.

Algorithmic variation¶

Variation can be introduced in action by means of using random numbers in commands. For example, instead of setting the pattern on track 3 to 2 every time this cue step is executed, we can use the random() function instead:

Press pattern+# to insert the setPattern() command.
Use X to move the cursor to the second function argument and press no to remove the number.
Press edit and select insert code.
Select random() and press yes.
Use X and Y to adjust the range of random numbers.

The code should now look something like this:

Each time the cue step is executed the random() function will output a new random number.

if statements can be used to only execute certain commands if a condition evaluates to true. For example, let’s use an if statement together with the chance() function to only execute a bit of code 20% of the time:

Press edit and select insert control flow.
Select if statement and press yes.
The if statement is now inserted and the cursor placed in the position where the condition is to be placed.
Press edit and select insert function.
Select chance() and press yes.
Use X and Y to set the chance to 20.
Add one or more commands on the empty line between the { and }. These will only be executed 20% of the time when this cue step is executed.

In the code above it selects pattern 3 and note list 6 on track 1. Then on the third line we find the if statement with chance(20) as condition. If chance(20) evaluates to true the block of code that starts with { and ends with } is executed. In practice that means that when this code is executed there is a 20% chance that on track 2 the pattern is set to 7.

Combining cues¶

There are two functions that can be used to combine cues into longer arrangements:

switchCue() will switch to the specified cue step and will forget previous cue progress. This is the same behavior as when a cue is started by pressing cue+#.
startCue() will start a new cue and at some point come back and resume the current cue:
- If the until_end argument = 0 the new cue will run until the cue from which it was triggered reaches the next step.
- If the until_end argument = 1 the new cue will run until it reaches the end of the timeline (and if set to loop after it has completed all loops).

When the goal is to chain multiple cues together simply add a switchCue() to the last step of a cue.

The startCue() function however can be used to nest or embed cues. For example: short cues such as a verse and a chorus can be combined to into a song by having a longer cue with multiple startCue() calls that start a verse, chorus, then a verse again etc… The duration of the different sections can then be modified in the longer song cue if startCue() is called with until_end = 0.

Note

When calling switchCue() or startCue() it will first finish executing the current cue step’s code before proceeding with the new cue that has just been started/switched to.