HelpSource/Classes/TempoClock.schelp

   1 CLASS::TempoClock
   2 categories::Scheduling>Clocks
   3 summary::tempo based scheduler
   4 related::Classes/AppClock, Classes/SystemClock
   5
   6 DESCRIPTION::
   7
   8 TempoClock is a scheduler like link::Classes/SystemClock::, but it schedules relative to a strong::tempo:: in beats per second.
   9
  10 CLASSMETHODS::
  11
  12 private::initClass
  13
  14 method::new
  15 Creates a new TempoClock scheduler with the given tempo and starting times. If not supplied, strong::tempo:: defaults to one, strong::beats:: defaults to zero and strong::seconds:: defaults to the current elapsed time since SuperCollider startup. The default queueSize is 256, see link::#-queue::.
  16 code::
  17 t = TempoClock.new(1, 0, Main.elapsedTime.ceil);
  18 ::
  19
  20 method::default
  21 Sets or gets the permanent default TempoClock instantiated at startup.
  22 code::
  23 TempoClock.default.beats // beats since default TempoClock was started
  24 ::
  25
  26 subsection::Methods that allow TempoClock to act as TempoClock.default
  27
  28 method::stop, play, sched, schedAbs, clear, tempo, etempo, beats, beats2secs, secs2beats, nextTimeOnGrid, timeToNextBeat, setTempoAtBeat, setTempoAtSec, setMeterAtBeat, beatsPerBar, baseBarBeat, baseBar, playNextBar, beatDur, elapsedBeats, beats2bars, bars2beats, bar, nextBar, beatInBar
  29
  30 INSTANCEMETHODS::
  31
  32 private::prDump, prStart, prStop, prClear
  33
  34 method::stop
  35 Destroys the scheduler and releases the OS thread running the scheduler.
  36
  37 method::clear
  38 Removes all tasks from the scheduling queue.
  39
  40 method::tempo
  41 Sets or gets the current tempo in beats per second.
  42 code::
  43 t= TempoClock.new;
  44 t.tempo_(2.0); // equivalent to t.tempo = 2.0;
  45 t.tempo;
  46 t.tempo_(72/60) // 72 beats per minute
  47 t.tempo;
  48 ::
  49
  50 method::permanent
  51 Sets or gets a link::Classes/Boolean:: value indicating whether the clock will survive cmd-period. If false the clock is stopped (and thus removed) on cmd-period. If true the clock survives cmd-period. It is false by default.
  52
  53 method::beats
  54 Returns the appropriate beat time of the clock from any thread. If the receiver is the clock of the current thread, this returns the current logical time: code::thisThread.beats::. If the receiver is not the current thread's clock then this translates the current thread's logical time in seconds to this clock's logical time in beats.
  55
  56 method::schedAbs
  57 Schedules a function to be evaluated at a particular strong::beat::. If the function returns an link::Classes/Integer:: or a link::Classes/Float::, it will be re-evaluated at the logical time plus the returned value. The function receives a number of default arguments, see link::#-play:: example below.
  58
  59 method::sched
  60 Schedules a function to be evaluated strong::delta:: beats from the current logical time in this clock. If the receiver is the clock of the current thread, the delta is applied to the current logical time. If the receiver is not the current thread's clock then the delta is applied to the clock's elapsed time.
  61
  62 method::play
  63 Plays task (a function) at the next beat, where strong::quant:: is 1 by default. Shortcut for link::#-schedAbs::; see link::#-seconds:: and link::#-nextTimeOnGrid:: for further details on time and quant.
  64 code::
  65 t= TempoClock.default;
  66 t.play({arg beats, time, clock; [beats, time, clock].postln});
  67 ::
  68
  69 method::playNextBar
  70 Plays task (a function) at the next bar using link::#-schedAbs::.
  71
  72 method::queue
  73 Returns the scheduling queue Array in the form [beat, function]. The maximum number of items is determined by the clock's queueSize argument upon instantiation. The default queueSize of 256 allows 128 functions to be in the queue at any time.
  74
  75 method::beatDur
  76 Returns the duration in seconds of a current whole beat.
  77
  78 method::beatsPerBar
  79 Gets or sets the number of beats per bar. The default is 4. Setting must be done from within the scheduling thread, e.g.
  80 code::
  81 t= TempoClock.new;
  82 t.schedAbs(t.nextBar, {t.beatsPerBar_(3)});
  83 t.beatsPerBar;
  84 ::
  85
  86 method::bar
  87 Returns the current bar. See link::#-bars2beats:: for returning beat of current bar.
  88
  89 method::nextBar
  90 Returns the number of beats at the next bar line relative to the beat argument. If strong::beat:: is not supplied, returns the beat at which the next bar begins.
  91
  92 method::beatInBar
  93 Returns the current bar beat (as a link::Classes/Float::) in relation to link::#-beatsPerBar::. Values range from 0 to < beatsPerBar.
  94
  95 method::baseBar
  96 Returns bar at which link::#-beatsPerBar:: was last changed. If beatsPerBar has not been changed since the clock was created, returns 0.
  97
  98 method::baseBarBeat
  99 Returns beat at which the link::#-beatsPerBar:: was last changed. If beatsPerBar has not been changed since the clock was created, returns 0.
 100
 101 method::beats2bars
 102 Returns a bar as a float relative to link::#-baseBarBeat::.
 103
 104 method::bars2beats
 105 Returns a beat relative to link::#-baseBar::.
 106 code::
 107 t= TempoClock.default;
 108 t.bars2beats(t.bar) // downbeat of the current bar
 109 ::
 110
 111 method::timeToNextBeat
 112 Returns the logical time to next beat. strong::quant:: is 1 by default, relative to baseBarBeat, see link::#-nextTimeOnGrid::.
 113
 114 method::nextTimeOnGrid
 115 With default values, returns the next whole beat. strong::quant:: is 1 by default, strong::phase:: is 0. quant is relative to link::#-baseBarBeat::, such that
 116 code::
 117 t= TempoClock.default;
 118 t.nextTimeOnGrid(t.beatsPerBar) == t.nextBar // => true
 119 ::
 120 Together strong::quant:: and strong::phase:: are useful for finding the next n beat in a bar, e.g. code::nextTimeOnGrid(4, 2):: will return the next 3rd beat of a bar (of 4 beats), whereas code::nextBar-2:: may return an elapsed beat.
 121
 122 method::elapsedBeats
 123 Returns the current elapsed time in beats. This is equivalent to code::tempoClock.secs2beats(Main.elapsedTime)::. It is often preferable to use link::#-beats:: instead of elapsedBeats because beats uses a thread's logical time.
 124
 125 method::seconds
 126 Returns the current elapsed time. (This method is inherited from link::Classes/Clock::.)
 127
 128 method::beats2secs
 129 Converts absolute strong::beats:: to absolute strong::seconds::, returning the elapsed time of the clock at the given strong::beats::. Only works for times in the current tempo. If the tempo changes any computed time in future will be wrong.
 130 code::
 131 t= TempoClock.default;
 132 t.beats2secs(t.beats) // equivalent to t.seconds
 133 t.beats2secs(0) // how many seconds after startup did beat 0 occur?
 134 ::
 135
 136 method::secs2beats
 137 Converts absolute strong::seconds:: to absolute beats. Only works for times in the current tempo. If the tempo changes any computed time in future will be wrong.
 138
 139 EXAMPLES::
 140
 141 code::
 142 t = TempoClock(1); // create a TempoClock
 143
 144 // schedule an event at next whole beat
 145 t.schedAbs(t.beats.ceil, { arg beat, sec; [beat, sec].postln; 1 });
 146
 147 t.tempo = 2;
 148 t.tempo = 4;
 149 t.tempo = 0.5;
 150 t.tempo = 1;
 151
 152 t.clear;
 153
 154 t.schedAbs(t.beats.ceil, { arg beat, sec; [beat, sec].postln; 1 });
 155
 156 t.stop;
 157 ::
 158 code::
 159 (
 160 // get elapsed time, round up to next second
 161 v = Main.elapsedTime.ceil;
 162
 163 // create two clocks in a 5:2 relation, starting at time v.
 164 t = TempoClock(1, 0, v);
 165 u = TempoClock(0.4, 0, v);
 166
 167 // start two functions at beat zero in each clock.
 168 t.schedAbs(0, { arg beat, sec; [\t, beat, sec].postln; 1 });
 169 u.schedAbs(0, { arg beat, sec; [\u, beat, sec].postln; 1 });
 170 )
 171
 172 (
 173 u.tempo = u.tempo * 3;
 174 t.tempo = t.tempo * 3;
 175 )
 176
 177 (
 178 u.tempo = u.tempo * 1/4;
 179 t.tempo = t.tempo * 1/4;
 180 )
 181
 182 (
 183 t.stop;
 184 u.stop;
 185 )
 186 ::
 187 code::
 188 (
 189 // get elapsed time, round up to next second
 190 v = Main.elapsedTime.ceil;
 191
 192 // create two clocks, starting at time v.
 193 t = TempoClock(1, 0, v);
 194 u = TempoClock(1, 0, v);
 195
 196 // start two functions at beat zero in each clock.
 197 // t controls u's tempo. They should stay in sync.
 198 t.schedAbs(0, { arg beat, sec; u.tempo = t.tempo * [1,2,3,4,5].choose; [\t, beat, sec].postln; 1 });
 199 u.schedAbs(0, { arg beat, sec; [\u, beat, sec].postln; 1 });
 200 )
 201
 202 (
 203 u.tempo = u.tempo * 3;
 204 t.tempo = t.tempo * 3;
 205 )
 206
 207 (
 208 u.tempo = u.tempo * 1/4;
 209 t.tempo = t.tempo * 1/4;
 210 )
 211
 212 (
 213 t.stop;
 214 u.stop;
 215 )
 216 ::