CuePlayer Tutorial

Extension

This document introduces the CuePlayer and presents a workflow for composing and performing real-time and mixed electronic works. Full details of the class can be found in the CuePlayer helpfile.

The CuePlayer is a tool which helps a composer to organise processes and musical material in bundles (cues) and execute them when needed during the course of a piece. It is particularly applicable to musical works incorporating real-time electronics and acoustic instruments; it may also be handy in any scenario where the composer wishes to organise, schedule and trigger bundles of processes.

This tutorial has been written having in mind composers who may not be highly proficient in SuperCollider programming, but who have an adequate understanding of the language and are competent in electronic and/or instrumental composition. If you are a composer who is looking for a tool to write music for instruments and electronics with SuperCollider, this is especially for you.

Basics

The first thing to do is to create a CuePlayer instance and assign it to a variable. Then we may define a tempo for the piece (in bpm) at which the processes can be evaluated, (default is 120 bpm).a = CuePlayer.new; a.tempo_(110);

We may now start building the cues. A cue is a bundle of code placed within a function which is linked to a cue-number. All cues are organised into an Array and later on they may be triggered via code, a GUI window or any device/software which outputs midi/osc data, such as a footpedal or a Digital Audio Workstation (DAW). Think of the cue-number as the index of the cue-list which holds all processes.

An easy way to build a cue is with the put method which allows explicitly to create a cue at a specific cue-number.a.put(1, { "this is cue-1".postln }); a.put(2, { "this is cue-2".postln }); a.put(5, { "this is cue-5".postln });

We could also add a cue at the end of the cue-list in a similar fashion.a.add({ "this is cue-6".postln });

When we want to execute a cue we call trigger, specifying also a cue-number.a.trigger(1); // posts "this is cue-1" a.trigger(2); // posts "this is cue-2" a.trigger(3); // nothing a.trigger(4); // nothing a.trigger(5); // posts "this is cue-5" a.trigger(6); // posts "this is cue-6" a.trigger(7); // nothing

The setCurrent method sets the current cue and the next method is a quick way to trigger the next one.a.setCurrent(5); // sets current cue to 5 a.next; // triggers cue-6; posts "this is cue-6"

Most often you will be working along with the CuePlayer window which allows the CuePlayer to be controlled via a Graphic User Interface. Through it you can monitor input/output buses, trigger cues, use a timer and a metronome and control the server's level amongst others. It is brought up with the gui method which has a handful of options to adjust it to your needs. See the CuePlayer helpfile for more.( a.gui( monitorInChannels: 2, // Monitor the first 2 input channels monitorOutChannels: 16, // Monitor 16 output channels options: ( largeDisplay: false, // Show/hide the big window displaying current cue-number left: 1300, // Left bound of the CuePlayer window top: 350, // Top bound of the CuePlayer window ) ) );

Spend a little time to get familiar with this window. You can monitor up to 8 input buses and up to 48 output buses which should be enough for most pieces, but you could easily hack the source code to change this if you like. The big green-button triggers the next cue and the white number-box right next to it displays and sets (when needed) the current cue. The timer displays the time elapsed (usually since the beginning of the piece) and the metro-button starts/stops the metronome; its volume, output-bus and tempo can be adjusted. At the bottom of the window there is a mute button to silence everything and a volume-slider to control the level of the server.

For each cue we can attach text which may be subsequently displayed on screen. This may prove useful for the laptopist in order to see what each cue does while the piece unfolds and to communicate instructions and information to the performer. Have a look at the CueInfo's helpfile for information on this feature.a.guiInstance.window.close; // close the cueplayer window when open // Define cue-7 & add text information ( a.put(7, CueInfo( cueTitle: "this appears on the cueplayer window", largeDisplayInfo: "performer's info", function: { "do something".postln } )) ); // bring up the GUIs ( a.gui(options:( infoDisplay: true, // shows the cue-title largeDisplay: true, )) // shows the big window ); // trigger cue-7 a.trigger(7); // "cueTitle" appears on the cueplayer gui & "largeDisplayInfo" on a second window for the performer.

MIDI & OSC

Cues can be triggered via MIDI and OSC events.

To use midi you need to connect to your midi-devices first; then you may set up a midi-trigger on a given note and channel to trigger the next cue by calling the midiTriggerNoteOn method, this allows to evaluate sequential cues upon receiving a midi-note through a specified midi-channel. Bear in mind that the CuePlayer starts counting midi-channels from 1, (as opposed to 0).// Connect all midi devices & set up a midi-trigger for the CuePlayer MIDIIn.connectAll; a.midiTriggerNoteOn(note: 60, channel: 15); // Ready to trigger cues from an external midi-device hooked up on channel 15 upon sending note 60.

It may also be useful to trigger cues via an external midi-controller. This applies particularly to performance scenarios where the instrumentalist uses a foot-pedal on stage to trigger sequential cues. For this you will need to use the midiTriggerControl method.// Connect all midi devices & set up a trigger which will respond to midi-control messages MIDIIn.connectAll; a.midiTriggerControl(value: 127, ccNum: 64, channel: 1) // Ready to trigger cues from midi-controller 64 hooked up on channel 1 upon sending the value 127

There is also the midiTriggerVelocity method which sets up a midi-trigger on a given note and channel based on the note's velocity value. It allows to evaluate specific cues upon receiving a midi-note with velocity (1-127) controlling the cue-number. This method is useful while composing; when the cues need to be triggered externally via a Digital Audio Workstation (DAW).a.midiTriggerVelocity(note: 60, channel: 16, offset: 0); /* Ready to trigger cues from an external midi-device hooked up on channel 16 based on the note's velocity value. */

When you want to trigger cues via the Open Sound Control protocol you can set up an OSC trigger with the oscTrigger method, which accepts a path as an argument (such as '/cueTrigger') and a message. When the message is -1 the next cue will be triggered; any other positive integer will trigger the respective cue.// An OSC responder a.oscTrigger(path:'/cueTrigger'); // Test it m = NetAddr("127.0.0.1", NetAddr.langPort); // Create a net address m.sendMsg("/cueTrigger", -1); // Send a message to trigger next cue m.sendMsg("/cueTrigger", -1); // Trigger next cue m.sendMsg("/cueTrigger", -1); // Trigger next cue m.sendMsg("/cueTrigger", 2); // Trigger cue 2 m.sendMsg("/cueTrigger", 5); // Trigger cue 5

With sendOSC you may send OSC messages which may be handy while composing if you want to control a DAW that accepts OSC. See the CuePlayer helpfile.// ip/port/message need to be adjusted to match the software's specs. a.sendOSC("127.0.0.1", 8000, ["/play", 1]); a.sendOSC("127.0.0.1", 8000, ["/pause", 1]);

Composing

This section outlines an example workflow for composing musical works for instruments and electronics using SuperCollider. The idea, while composing, is to try to simulate the conditions that emerge during the presentation of a piece, to try to reconstruct adequately the performance scenario in-studio, in order to test the work and solve problems both in musical and technical terms prior to the concert.

• Use your preferred Digital Audio Workstation to lay out the piece. Work with a virtual sampler instrument in order to have some sort of feedback for the instrumental part while composing.
• On a Mac OS, make sure that your DAW uses the IAC Driver which will allow midi-data to be sent internally from one application to another (Applications>Utilities>Audio Midi Setup).
• Within the DAW create a midi-track and route its output to a dedicated midi-channel (16 for example) via IAC. Place a series of midi-notes in the track exactly where the cues should be triggered. All notes need to be the same (middle Cs for example); the 1st note (corresponding to cue-1) should have a velocity of 1, the 2nd a velocity of 2, and so on ...
• In SuperCollider, make an instance of the CuePlayer and assign it to a variable. Connect to your midi-devices and call the midiTriggerVelocity method to respond to the incoming midi-notes. This will allow the CuePlayer to trigger the respective cue every time it receives a note from the DAW via the specified midi-channel.
• Build your cues in SuperCollider as you progress with the instrumental part.
• Hitting "play" inside the DAW not only plays-back the instrumental part (possibly through a virtual instrument track) but also triggers the electronics in SuperCollider. If live-processing of the acoustic source is needed then the output of the virtual instrument needs to be routed (preferably internally) to SuperCollider for processing.

This scenario allows to lay out the piece in a familiar environment and audition the instrumental part along with the electronics in SuperCollider which should be triggered exactly where the score depicts. With this workflow a composer can audition the piece while it is being built, test, debug, adjust and predict with consistency how the work will sound in "real-life".

Performing

This section outlines how the CuePlayer can be used when presenting works for instruments and electronics. It's quite straight forward:

• All electronic processes need to be organised as individual cues with the CuePlayer; they are often triggered sequentially either by the instrumentalist or the laptopist.
• Plug-in any midi/osc devices to the laptop.
• In SuperCollider connect to your midi-devices and call the midiTriggerControl method to respond to incoming midi-control messages (from a foot-pedal for example) and/or use the oscTrigger method to respond to osc messages. These methods allow the CuePlayer to trigger the next cue every time a device sends midi/osc data to the laptop.
• Cues may be triggered via external devices (keyboards, controllers, switches, etc), code or the CuePlayer GUI.

Organising

A rather convenient method to organise a piece is to place the individual cues into separate scd documents and then load them in the cue-list.// A CuePlayer instance a = CuePlayer.new; // Find the path of the CuePlayer class b = PathName(CuePlayer.class.filenameSymbol.asString).parentPath; // Load cues from individual scd files from disk. ( a.put( cueNumber: 1, function: b ++ "HelpSource/Tutorials/cues/cue1.scd", ); a.put( cueNumber: 2, function: b ++ "HelpSource/Tutorials/cues/cue2.scd", ); a.put( cueNumber: 3, function: b ++ "HelpSource/Tutorials/cues/cue3.scd", ); a.put( cueNumber: 4, function: b ++ "HelpSource/Tutorials/cues/cue4.scd", ); ); a.trigger(1); a.trigger(2); a.trigger(3); a.trigger(4);

Both put and add methods of the CuePlayer class accept a timeline as an argument which provides an easy way to schedule processes in the future; for this we need to use an Array with time - function pairs; (time is in beats or optionally in seconds). Here's an example on how to do this.a = CuePlayer.new; a.tempo_(120); // Using a timeline for cues 1 & 2 ( a.put(1, // beat - function pairs timeline: [ 1, { "1 beat later".postln }, 2, { "2 beats later".postln }, // schedule something to happen 2 beats later 3.5, { "3.5 beats later".postln } ], timelineOptions: (mode: \beats, quant: 1) // this works in beats ); a.put(2, // seconds - function pairs timeline: [ 1, { "1 second later".postln }, 2, { "2 seconds later".postln }, // schedule something to happen 2 seconds later 3, { "3 seconds later".postln } ], timelineOptions: (mode: \time, quant: 0) // this works in seconds ); ); a.trigger(1); // trigger cue1 a.trigger(2); // trigger cue2

It is also possible to use scd files in a timeline.( a.put(1, timeline: b ++ "HelpSource/Tutorials/timelines/01.scd", timelineOptions: (mode: \beats, quant: 1) ); a.put(2, timeline: b ++ "HelpSource/Tutorials/timelines/02.scd", timelineOptions: (mode: \time, quant: 0) ); ); a.trigger(1); a.trigger(2);