Routines and clocks

Use clocks to create automated, algorithmic scheduling. Among the things that clocks "play" are routines, tasks, and patterns.

To see how a clock "plays" a routine, first examine how a function works in a routine.

The first argument (and usually the only argument) to a routine is a function.

// template for a routine

Routine({ ".... code within curly braces is a function .... "});

A .yield message to an expression in a function (in a routine) returns a value.

r = Routine({ "hello, world".yield.postln });

// to evaluate a routine, send a .next message

// it will "hand over" the value of the expression to which the .yield message is attached

r.next;

Evaluate (again)

r.next;

The routine above returns nil when its evaluated a second time. This is because once a routine "yields" and if there's no additional code after the .yield message, the routine is finished, over, and done - unless it receives a reset message. Then it can start over again.

r.next; // returns nil

r.reset; // reset the routine

r.next; // it works!

////////////////////////////////////////////////////////////////////////////////////////////////////

(

r = Routine({

"hello, world".yield;

"what a world".yield;

"i am a world".yield;

});

)

The first three .next messages return a string. The fourth .next message returns nil.

r.next; // returns a string

r.next; // returns a string

r.next; // returns a string

r.next; // returns nil

Reset the routine.

r.reset;

r.next;

r.next;

r.next;

r.next;

////////////////////////////////////////////////////////////////////////////////////////////////////

Use a .do message in a routine to make a loop.

(

r = Routine({

// setup code

var array;

array = [ "hello, world", "what a world", "i am a world" ];

// the loop

3.do({ array.choose.yield })

});

)

Evaluate the routine one more time than the loop in the routine allows.

4.do({ r.next.postln });

The routine returned three strings followed by nil.

////////////////////////////////////////////////////////////////////////////////////////////////////

Scheduling routines

Rewrite the routine so that it includes a .wait message.

(

r = Routine({

var array;

array = [ "hello, world", "what a world", "i am a world" ];

3.do({

1.wait; // pause for 1 second

array.choose.postln;

})

});

)

Then "play" the routine, eg, send it a .play message.

r.play

Append a .reset message to the routine so that it can start over.

r.reset.play;

////////////////////////////////////////////////////////////////////////////////////////////////////

Clocks and the convenience of .play

When a routine receives a .play message, control (of the routine) is redirected to a clock. The clock uses the receiver of the .wait message as a unit of time to schedule ("play") the routine.

SuperCollider has three clocks, each of which has a help file.

SystemClock // the most accurate

AppClock // for use with GUIs

TempoClock // to schedule in beats

The .play message is a convenience that allows one to write

r.reset.play; // reset the routine before playing it

instead of

SystemClock.play(r)

////////////////////////////////////////////////////////////////////////////////////////////////////

Scheduling synths with routines

Enclose synths within routines. It's often the case that the synthdef used by the synth in routines should have an envelope with a doneAction parameter set to 2 (to deallocate the memory needed for the synth after its envelope has finished playing).

(

// DEFINE A SYNTHDEF

SynthDef("fm2", {

arg bus = 0, freq = 440, carPartial = 1, modPartial = 1, index = 3, mul = 0.2, ts = 1;

// index values usually are between 0 and 24

// carPartial :: modPartial => car/mod ratio

var mod;

var car;

mod = SinOsc.ar(

freq * modPartial,

0,

freq * index * LFNoise1.kr(5.reciprocal).abs

);

car = SinOsc.ar(

(freq * carPartial) + mod,

0,

mul

);

Out.ar(

bus,

car * EnvGen.kr(Env.sine(1), doneAction: 2, timeScale: ts)

)

}).load(s);

)

(

// DEFINE A ROUTINE

r = Routine({

12.do({

Synth(

"fm2",

[

\bus, 2.rand, \freq, 400.0.rrand(1200),

\carPartial, 0.5.rrand(2), \ts, 0.5.rrand(11)

]

);

s.queryAllNodes;

"".postln.postln.postln.postln.postln;

2.wait;

})

});

)

// PLAY THE ROUTINE

r.reset.play;

////////////////////////////////////////////////////////////////////////////////////////////////////

Process synths spawned in a routine through effects that run outside of the routine.

(

// DEFINE A SYNTHDEF

SynthDef("echoplex", {

ReplaceOut.ar(

0,

CombN.ar(

In.ar(0, 1),

0.35,

[Rand(0.05, 0.3), Rand(0.05, 0.3)],

// generate random values every time a synth is created

7,

0.5

)

)

}).load(s);

// DEFINE GROUPS TO CONTROL ORDER-OF-EXECUTION

// attach a ~source group to the head of the rootnode and

// an ~effects group to the tail of the rootenode

~source = Group.head(s);

~effect = Group.tail(s);

// DEFINE A ROUTINE

r = Routine({

// loop is the same as inf.do, eg, create an infinite loop that runs forever

loop({

Synth.head( // attach the synth to the head of the ~source group

~source,

"fm2",

[

\outbus, 0, \freq, 400.0.rrand(1200), \modPartial, 0.3.rrand(2.0),

\carPartial, 0.5.rrand(11), \ts, 0.1.rrand(0.2)]

);

s.queryAllNodes;

2.wait;

})

});

// TURN ON EFFECTS

Synth.head(~effect, "echoplex");

Synth.tail(~effect, "echoplex");

)

// PLAY THE ROUTINE

r.reset.play;

////////////////////////////////////////////////////////////////////////////////////////////////////