README.md

Clock

Clock maps a beat clock against a Web Audio time clock and provides functions for scheduling function calls.

Dependencies and tests

Clock depends on two repos that can be installed as git submodules:

• github.com/cruncher/collection
• github.com/soundio/audio-object

Install with submodules:

git clone https://github.com/soundio/clock.git
cd clock
git submodule update --init

Tests use Karma. To run tests:

npm install
karma start

Clock(audio, array)

Constructs a tempo clock, where audio is a Web Audio context and data is an optional array of tempo changes.

var audio = new window.AudioContext();
var data  = [
    { beat: 0, tempo: 120 },
    { beat: 16, tempo: 180 }
];
var clock = new Clock(audio, data);

The clock object is now a Collection of tempo data that maps a beat clock against the audio context's time clock. It is a library of properties and methods for scheduling function calls. It is also an AudioObject with two outputs, "rate" and "duration", for syncing Web Audio parameters to the tempo.

clock

.time

The current time. Gets audio.currentTime. Read-only.

.beat

The current beat. Gets clock.beatAtTime(audio.currentTime). Read-only.

.rate

The current rate, in beats per second.

.timeAtBeat(beat)

Returns the audio context time at beat.

.beatAtTime(time)

Returns the beat at time.

.automate(name, value, time)

// Move to 120bpm in 2.5 seconds
clock.automate('rate', 2, clock.time + 2.5);

Inherited from AudioObject.

.tempo(beat, tempo)

Creates a tempo change at a time given by beat. If beat is not defined, the clock creates a tempo change at the current beat.

.find(beat)

Returns tempo change found at beat or undefined.

.remove(beat)

Removes tempo change found at beat.

.on(beat, fn)

Calls fn at the beat specified (no lookahead).

.cue(beat, fn)

Cue a function to be called just before beat. fn is called with the argument time, which can used to accurately schedule Web Audio changes.

clock.cue(42, function(time) {
    gainParam.setValueAtTime(time, 0.25);
    bufferSourceNode.start(time);
});

Additional parameters are also passed to the callback fn as extra arguments.

function fire(time, delayNode, value) {
    delayNode.delayTime.setValueAtTime(time, value);
}

clock.cue(42, fire, delayNode, value);

.uncue(beat, fn)

Removes fn at beat from the timer queue. Either, neither or both beat and fn can be given.

Remove all cues from the timer queue:

clock.uncue();

Remove all cues at beat from the timer queue:

clock.uncue(beat);

Remove all cues to fn from the timer queue:

clock.uncue(fn);

Remove all cues at beat for fn from the timer queue:

clock.uncue(beat, fn)

.uncueAfter(beat, fn)

Removes fn after beat from the timer queue. fn is optional.

Remove all cues after beat from the timer queue:

clock.uncueAfter(beat);

Remove all cues after beat for fn from the timer queue:

clock.uncueAfter(beat, fn)

.onTime(time, fn)

Shorthand for clock.cue(time, fn, 0), calls fn at the time specified (0 ms lookahead).

.cueTime(time, fn)

Cue a function to be called just before time. fn is called with the argument time, which can used to accurately schedule changes to Web Audio parameters:

clock.cue(42, function(time) {
    gainParam.setValueAtTime(time, 0.25);
    bufferSourceNode.start(time);
});

Pass in a third parameter lookahead to override the default (0.05s) lookahead:

clock.cue(44, fn, 0.08);

.uncueTime(time, fn)

Removes fn at time from the timer cues. Either, neither or both time and fn can be given.

Remove all cues from the timer queue:

clock.uncueTime();

Remove all cues at time from the timer queue:

clock.uncueTime(time);

Remove all cues to fn from the timer queue:

clock.uncueTime(fn);

Remove all cues at time for fn from the timer queue:

clock.uncueTime(time, fn)

.uncueAfterBeat(time, fn)

Removes fn after time from the timer queue. fn is optional.

Remove all cues after time from the timer queue:

clock.uncueAfterTime(time);

Remove all cues after time for fn from the timer queue:

clock.uncueAfterTime(time, fn)