BeatSched
Extension
ExtensionDescription
Functions can be scheduled for execution using relative seconds, relative beats, absolute seconds or absolute beats.
BeatSched has an epoch — a moment in time for the first downbeat — so functions may be scheduled to happen at a specific beat in the future relative to the beat epoch.
This class uses TempoClock for scheduling, and has some overlap of capabilities with that. What TempoClock does not have is any concept of what beat it is right now, only of scheduling some number of relative beats in the future.
The TempoClock class is used to specify what the tempo is, and is used for all beat <-> second calculations. The default global TempoClock object is used, or you can use a specific TempoClock instance.
Setting the tempo is best done through Tempo. If using a custom (non global) TempoClock then you need to use a custom Tempo that uses that custom TempoClock.
There is a default (global) BeatSched that can be addressed through class methods. It uses the SystemClock and the default global TempoClock. You may also create individual instances that maintain their own scheduling queues, tempii, and time epochs.
The simplest usage just uses the global class BeatSched which uses the global Tempo and global TempoClock.
If using BeatSched instances you can clear the queue, only affecting your own events. If using the global BeatSched class, clearing the queue will affect everybody that also uses the global object.
All of these methods exist as both
class (the default global scheduler) eg. BeatSched.tsched(seconds,function)
and instance methods (a specific scheduler). eg. beatSched = BeatSched.new; beatSched.tsched(seconds,function)
Class Methods
.global
.new
Arguments:
| clock | |
| tempo | |
| tempoClock |
.initClass
.xblock
blocks any and all pending x-scheduled messages.
.time
get the scheduler's time
Arguments:
| seconds |
.beat
get the scheduler's current beat set the scheduler's current beat. this is also used to start a "song": zero the beat, and all absolute times previously scheduled events will be unpredictable
Arguments:
| beat |
.clear
clear all scheduled events.
.deltaTillNext
returns the number of beats untiil the next quantizeDivision. 4.0 means the next even bar 16.0 means the next 4 bar cycle 0.25 means the next 16th note
Arguments:
| quantize |
.tdeltaTillNext
returns the number of seconds untiil the next beat quantizeDivision. 4.0 means the next even bar 16.0 means the next 4 bar cycle 0.25 means the next 16th note
Arguments:
| quantize |
.tsched
time based scheduling delta is specified in seconds
Arguments:
| seconds | |
| function |
.xtsched
exclusive time based schedule any previous messages scheduling using xtsched, xsched or xqsched will be cancelled. this is incredibly useful in situations where several messages might be sent and you only want the last one to be used as the final answer. example: a monkey is hitting many buttons, changing his mind about which sound to play starting at the next measure. this would result in many messages being stacked up all at the same time, and the server would choke trying to execute them all. so the x-methods are a kind of enforced monophony. another example: a monophonic sequence plays successive notes, all using xsched, you then switch to a different sequence. you don't want the note that was scheduled from the previous sequence to happen. using one of the x-methods, you don't have to worry about cancelling it, the old notes will be cleared when new ones are scheduled. (actually it just ignores them when they come due)
Arguments:
| seconds | |
| function |
.sched
delta specified in beats
Arguments:
| beats | |
| function |
.xsched
exclusive, delta specified in beats
Arguments:
| beats | |
| function |
.qsched
function will execute at the next division based on quantize value: 4.0 means the next start of a bar 16.0 means the next 4 bar cycle 1.0 means the next down beat 0.25 means the next 16th note etc or immediately if you happen to be exactly on a division.
Arguments:
| quantize | |
| function |
.xqsched
exclusive quantized beat based scheduling
Arguments:
| quantize | |
| function |
.tschedAbs
will happen at the time specified in seconds
Arguments:
| time | |
| function |
.xtschedAbs
Arguments:
| time | |
| function |
.schedAbs
will happen at the beat specified.
Arguments:
| beat | |
| function |
Instance Methods
.tempo
.tempoClock
.init
.xblock
.time
Arguments:
| seconds |
.beat
Arguments:
| beat |
.clear
.deltaTillNext
Arguments:
| quantize |
.tdeltaTillNext
Arguments:
| quantize |
.tsched
Arguments:
| seconds | |
| function |
.xtsched
Arguments:
| seconds | |
| function |
.sched
Arguments:
| beats | |
| function |
.xsched
Arguments:
| beats | |
| function |
.qsched
Arguments:
| quantize | |
| function |
.xqsched
Arguments:
| quantize | |
| function |
.tschedAbs
Arguments:
| time | |
| function |
.xtschedAbs
Arguments:
| time | |
| function |
.schedAbs
Arguments:
| beat | |
| function |
.tschedAbsNext
Examples
A little rounding error
at 5206.432346276 we ask for deltaTillNext 4 [ 5204, 4, 5206.432346276 ] 1.5676537239997
that would be 5206.432346276 + 1.5676537239997 // at 5208 5208
// but when the scheded event comes due: [ 5204, 4, 5207.999072862 ] 0.00092713799949706
its appears to be slightly ahead of schedule, due to rounding errors in the several math ops that have happened.
so the right answer is 0.00092713799949706 as far as BeatSched is concerned.
but if you try to loop like this, you will suffer from rounding errors.
mostly you would never set up a loop like this, mostly you just want to know when the next even beat is so you can get your groove on.