KDAudioClock

v 1.0.7 | © justKD 2020 | MIT License

This class lets you schedule asynchronous events using the audio hardware clock.

KDAudioClock creates and manages timed events, which are each assigned unique identifiers. It also includes event syncing, time stretching, and a scoring syntax for creating a repeatable series of events.

It's based on WAAClock by @sebpiq, which is itself based on the ideas put forth by Chris Wilson in his article A Tale of Two Clocks.

Demo

KDAudioClock Examples and Documentation

Basic Use

`start()`

Create a new audio context and start the audio clock.

const clock = new KDAudioClock();
clock.start();

`stop()`

Stops the audio clock and deletes all managed events.

clock.stop();

`pause()`

Suspends the audio clock and pauses all managed events.

clock.pause();

Start, stop, and pause return promises.

clock.start().then(f);
clock.stop().then(f);
clock.pause().then(f);

`setTimeout(f, t)`

Emulates window.setTimeout.

clock.setTimeout(() => {
  console.log("tick after 2 sec");
}, 2000)

`setInterval(f, t)`

Emulates window.setInterval.

clock.setInterval(() => {
  console.log("tick every 2 sec");
}, 2000)

`clearInterval(e)`

Emulates window.clearInterval.

const ev = clock.setInterval(f, t);
// later
clock.clearInterval(ev);

KDAudioClockEvent callback functions pass back the event itself.

clock.setInterval((ev) => {
  const loop = ev.get.loop();
  const ticks = loop.elapsedTickCount;
  if (ticks >= 5) ev.delete();
}, 2000)

Extended Use

`schedule(opts)`

Schedule any other timed event.

clock.schedule({
    loop: {
        interval: 2000,
        repetitions: 5,
    },
    onTick: (ev) => console.log("tick"),
    onComplete: (ev) => console.log("done"),
    onAborted: (ev) => console.log("abort"),
    onMissed: (ev) => console.log("missed"),
});

setTimeout and setInterval are just using 'schedule' under the hood.

// Same as `clock.setTimeout`.
clock.schedule({
    delay: 500,
    onComplete: () => console.log("done"),
});

// Same as `clock.setInterval`.
clock.schedule({
    loop: {
        interval: 500,
        repetitions: Infinity,
    },
    onTick: () => console.log("tick"),
});

`sync(events)`

Sync the passed events to the current time.

const events = clock.getEvents();
clock.sync(events);

Tip: use `sync` every so often to counter drifting that may occur between simultaneous long running timers.

const timer1 = clock.setInterval(playSound1, 500);
const timer2 = clock.setInterval((ev)=>{
    playSound2();
    const ticks = ev.get.loop().elapsedTickCount;
    if (ticks >= 120) clock.sync(clock.getEvents());
}, 1000);

`timeStretch(events)`

Uniformly alter the interval of looping events.

const events = clock.getEvents();
clock.timeStretch(events, 2 );   // intervals are double their initial value
clock.timeStretch(events, 0.5 ); // intervals are half their initial value
clock.timeStretch(events, 1 );   // intervals are reset to their initial value

`meter()`

Convert metered durations into time in milliseconds.

/**
 * Clock set to 60 beats per minute
 * and the quarter note gets the beat.
 */
clock.setBPM(60);
clock.setBeat(4);

/**
 * Duration in ms for one quarter note.
 */
const interval = clock.meter(1, 4);
clock.setInterval(f, interval);

`setBPM(bpm)`

This only affects how the helper method clock.meter calculates time. Default is 60.

clock.setBPM(60);
const tickEverySecond = clock.meter(1, 4);
const tickEveryHalfSecond = clock.meter(1, 8);
const eighthNoteTriplet = clock.meter(1, 12);

clock.setBPM(120);
const tickEveryHalfSec = clock.meter(1, 4);
const tickEveryQuarterSec = clock.meter(1, 8);
const sixteenthNoteTriplet = clock.meter(1, 12);

`setBeat(beat)`

This only affects how the helper method clock.meter calculates time. Default is 4 (quarter note).

/**
 * Most applications probably don't need to
 * set the beat independently, but it can
 * be useful if correlating these durations
 * with notated rhythms. Just remember that
 * setting the beat will change how 'meter'
 * is calculated in relation to the BPM.
 */
clock.setBPM(60);
clock.setBeat(8);

const tickEverySecond = clock.meter(1, 8);
const tickEveryHalfSecond = clock.meter(1, 16);

`score(scoredEvents)`

Run a sequence of events in order, each firing after the end of the previous event plus the wait duration. This provides a more readable syntax to replace nesting calls to clock.setTimeout.

// Helper method to create scored events.
const note = clock.createScoredEvent;

// Pass an array of scored events.
clock.score([
    note(0, (ev) => {
        // call this right away
        console.log( ev.get.uid() );
    }),
    note(1000, (ev) => {
        // after 1 second
        console.log( ev.get.uid() );
    }),
    note(500, (ev) => {
        // after another 500ms
        console.log( ev.get.uid() );
    }),
]);

Loop scores by assigning it to a variable and calling itself.

const meter = clock.meter;
const note = clock.createScoredEvent;
cosnt runScore = () => {
    clock.score([
        note(0, f),
        note(meter(1, 4), f),
        note(meter(1, 8), f),
        note(meter(1, 4), f),
        note(meter(1, 8), f),
        note(meter(1, 16), f),
        note(meter(1, 16), f),
        note(meter(1, 4), f),
        note(0, runScore),
    ]);
};

runScore();

Exit a score with `score.break()`.

const meter = clock.meter;
const note = clock.createScoredEvent;

let count = 0;
let maxLoops = 2;
let quarterNote = clock.meter(1, 4);

let runScore = () => {
    const maxed = count++ >= maxLoops;
    const score = clock.score([
        note(quarterNote, (ev) => {
            console.log('1');
        }),
        note(quarterNote, (ev) => {
            console.log('2');
            if (maxed) score.break();
        }),
        note(quarterNote, (ev) => {
            console.log('3');
        }),
        note(quarterNote, (ev) => {
            console.log('4');
            if (!maxed) runScore();
        }),
    ]);
};

runScore();

Create reusable "measures" and add them to a score with the spread operator.

const meter = clock.meter;
const note = clock.createScoredEvent;

const measureOne = [
    note(meter(1, 4), (ev) => {}),
    note(meter(1, 4), (ev) => {}),
];

const measureTwo = [
    note(meter(1, 8), (ev) => {}),
    note(meter(1, 8), (ev) => {}),
    note(meter(1, 8), (ev) => {}),
    note(meter(1, 8), (ev) => {}),
];

const measureThree = [
    note(meter(1, 4), (ev) => {}),
    note(meter(1, 8), (ev) => {}),
    note(meter(1, 8), (ev) => {}),
];

const runScore = () => {
    clock.score([
        ...measureOne,
        ...measureTwo,
        ...measureTwo,
        ...measureOne,
        ...measureThree,
        ...measureThree,
        note(0, runScore),
    ]);
};

runScore();

API

KDAudioClock Constructor Parameters

interface KDAudioClockParams  {
    context?: AudioContext;
    tolerance?: {
        early?: number;
        late?: number;
    };
    bpm?: number;
    beat?: number
};

new KDAudioClock(opts?: KDAudioClockParams)

Param	Type	Description
`context?`	`AudioContext`	If an external audio context should be used, this is where it is passed to `KDAudioClock`. Otherwise, the instance will create and manage its own audio context, which can be accessed via `new KDAudioClock().getContext()`.
`tolerance?`	`{ early?: number; late?: number; }`	Object holding default `early` and `late` tolerance values in seconds. Will default to `{early: 0.001, late: 0.1 }` if this is left empty. These values describe the margin of error for dropping an event. If the scheduled event attempts to fire within the tolerance window, the `onTick` callback is called. Otherwise the `onMissed` callback is called.
`bpm?`	`number`	Beats per minute used by the `meter` helper method to calculate metered time. Default is `60`.
`beat?`	`number`	The note division that is assigned to the beat. Used by the `meter` helper method to calculate metered time. Default is `4` (quarter note).

KDAudioClock Methods

Method	Type	Description
`start`	`(ctx?: AudioContext) => Promise<any>`	Start the clock. Handles the first start as well as resuming a paused or stopped clock. Creates a new AudioContext if one doesn't already exist, otherwise uses the assigned or previously created context. Connects the audio node and begins processing ticks.
`stop`	`() => Promise<any>`	Deletes all currently existing events managed by the clock, disconnects the clock audio node, closes the audio context and releases its internal reference. If a context was passed in the initial options, it will still be referenced by the options object, but a new context must be passed to the `start()` method since the original will be closed.
`pause`	`() => Promise<any>`	Pauses the clock but retains existing events. Disconnects the clock audio node and suspends the audio context.
`resume`	`() => Promise<any>`	An alias for `start`. This method will simply call `start`, but it may help readability if this is used after a `pause` and `start` is only used in opposition to `stop`.
`destroy`	`() => undefined`	Destroy this instance and make it available for garbage collection. This will release any internally held references. Always explicitly returns `undefined`.
`isRunning`	`() => boolean`	Returns `true` if the clock is running or `false` if the clock has never been started, is paused, or has been stopped.
`isPaused`	`() => boolean`	Returns `true` if the clock is paused.

Method	Type	Description
`setTimeout`	`(callback: (ev: KDAudioClockEvent) => void, delayInMs: number) => KDAudioClockEvent`	Shortcut for creating a scheduled event that mimics `window.setTimeout` functionality.
`setInterval`	`(callback: (ev: KDAudioClockEvent) => void, intervalInMs: number) => KDAudioClockEvent`	Shortcut for creating a scheduled event that mimics `window.setInterval` functionality.
`clearInterval`	`(event: KDAudioClockEvent) => void`	Shortcut for deleting an event that mimics `window.clearInterval` functionality.
`schedule`	`(opts: KDAudioClockEventOptions	KDAudioClockEvent

Method	Type	Description
`getContext`	`() => AudioContext`	Returns the `AudioContext` being used by the clock. Either the context passed as a constructor parameter, or the internally created context if one was not provided.
`getCurrentTime`	`() => number	null`
`getTolerance`	`() => { early: number; late: number; }`	Get the current default tolerance levels in seconds that is used when new events are created without their own explicit tolerance option.
`setTolerance`	`(tolerance: { early?: number; late?: number; }) => void`	Set the default tolerance levels in seconds that will be used when new events are created without their own explicit tolerance option.
`getEvents`	`() => KDAudioClockEvent[]`	Returns an array `KDAudioClockEvent[]` holding all events currently being managed by the clock, regardless of whether they are currently queued or not (eg. this will include suspended/paused events).)
`getEventQueue`	`() => KDAudioClockEvent[]`	Returns an array `KDAudioClockEvent[]` holding all events currently in the event queue (eg. will not include suspended/paused events).
`hasEvent`	`(event: KDAudioClockEvent	string) => boolean`
`getUIDFor`	`(event: KDAudioClockEvent) => string`	When passed a valid event, this returns the unique identifier `string` that was automatically assigned to the event when it was created.
`getEventFor`	`(eventID: string) => KDAudioClockEvent`	When passed a valid `string` identifier, this returns the associated `KDAudioClockEvent`.
`getEventUidEntries`	`() => [KDAudioClockEvent, string][]`	Returns an array `[KDAudioClockEvent, string][]` representing the internal map holding managed events and their UID associations.

Method	Type	Description
`sync`	`(events: KDAudioClockEvent[]	KDAudioClockEvent, delayInMs?: number) => void`
`timeStretch`	`(events: KDAudioClockEvent[]	KDAudioClockEvent, ratio: number) => void`
`suspend`	`(events: KDAudioClockEvent[]	KDAudioClockEvent) => void`
`delete`	`(events: KDAudioClockEvent[]	KDAudioClockEvent) => undefined`

Method	Type	Description
`score`	`(events: [number, (event: KDAudioClockEvent) => void][]) => { break: () => void }`	Process a series of events with each subsequent event in the given array taking place only after the previous event fires. The `events` parameter is an array of scored events, each represented as an array `[delayInMs, callback]`. `delayInMs` is the time after the previous event is completed, not the time since initialization. `score` returns an object `{ break: () => void; }` which can be used to break out of a score early.
`createScoredEvent`	`(delayInMs: number, callback: (event: KDAudioClockEvent) => void) => [number, (event: KDAudioClockEvent) => void]`	Helper function to make scored event arrays more readable.
`meter`	`(beats: number, duration: number) => number`	Helper function to convert meter to milliseconds. While you can use absolute time to control `KDAudioClock`, it also includes an internal meter system. The internal bpm and beat defaults to `{bpm: 60, beat: 4}` (60 beats-per-minute and the quarter note gets the beat). You can set the bpm and beat when the instance is created or at a later time, and the `meter` method will use those values along with the time signature values passed to it to compute the appropriate duration in milliseconds.
`getBPM`	`() => number`	Get the internally referenced beats-per-minute. This is only used by the `meter` method when calculating metrical durations. The default is `60`.
`setBPM`	`(bpm: number) => void`	Set the internally referenced beats-per-minute.
`getBeat`	`() => number`	Get the internally referenced metrical beat. This is only used by the `meter` method when calculating metrical durations. The default is `4` (quarter note gets the beat).
`setBeat`	`(beat: number) => void`	Set the internally referenced metrical beat.

KDAudioClockEventOptions Parameters

Param	Type	Description
`delay?`	`number`	Delay the start of the first tick in milliseconds. Default is `0`.
`loop?`	`{ interval?: number; repetitions?: number; }`	`loop.interval` is the time in ms between successive ticks. `loop.repetitions` is the number of repetitions before ending the loop. If the `loop` parameter is empty, the event will be scheduled to fire once after `delay` time (ie. `loop` defaults to `{repetitions: 1}`). If `loop.interval` is provided but `loop.repetitions` is left empty, `loop.repetitions` will default to `Infinity`. If `loop.interval` is provided with no `delay`, the event will tick immediately and again on each successive interval. If both `delay` and `loop.interval` are provided, the first tick will be after the delay time, and each successive tick will be after the interval time.
`tolerance?`	`{ early?: number; late?: number; }`	Describe the allowed margin of error in seconds before dropping a tick (ie. earliest and latest times to allow a tick before or after the scheduled deadline). The margin is calculated as the scheduled deadline minus the `early` value or plus the `late` value. If the event tries to fire within the allowed margin of error, the `onTick` callback is called. Otherwise, the `onMissed` callback is called instead.
`onTick?`	`(event: KDAudioClockEvent) => void`	Called on every successful tick.
`onComplete?`	`(event: KDAudioClockEvent) => void`	Called when the number of intended repetitions is reached. If the `loop.repetitions` value is `Infinity`, this will never be called.
`onAborted?`	`(event: KDAudioClockEvent) => void`	Called if a looping event is deleted (not suspended) before it has reached its intended number of repetitions, including if the `loop.repetitions` value is `Infinity`.
`onMissed?`	`(event: KDAudioClockEvent) => void`	Called if a tick misses its deadline.

KDAudioClockEvent Methods

Method	Type	Description
`schedule`	`(deadline: number) => void`	Schedule the next tick time for a specific deadline in seconds. This does not reset the elapsed tick count, so an event with a max number of loops will retain its current loop count.
`sync`	`(delayInMs?: number) => void`	Schedule the next tick for the `context.currentTime` plus the `delayInMs`. This does not reset the elapsed tick count, so an event with a max number of loops will retain its current loop count.
`suspend`	`() => void`	This will suspend scheduled deadlines, but the event and its options will be retained by the owning `KDAudioClock`.
`reschedule`	`(deadline?: number) => void`	Reschedule the next tick time for a specific deadline in seconds. This resets the elapsed tick count, which will restart a looping event with a max number of loops. Default `deadline` is `context.currentTime`.
`delete`	`() => undefined`	Completely delete the event and all internal references to `KDAudioClock`. Always returns `undefined`.
`isLooping`	`() => boolean`	Returns `true` if this is a looping event and the current number of elapsed loops has not exceeded the maximum number of loops.
`isSuspended`	`() => boolean`	Returns `true` if this event is suspended.
`updateWithInterval`	`(intervalInMs: number) => void`	Sets this events loop interval. This will set a new `initialInterval` and then update the `currentInterval` accounting for the time stretch value.
`timeStretch`	`(ratio: number) => void`	If this event is a looping event, this will be applied to the initial interval time (ie. setting the `timeStretch` back to `1` will reset any stretching). The initial interval value will be multiplied by the `ratio` value for each subsequent tick. Default is `1`.
`get`	`object`	See parameters below.

`new KDAudioClockEvent.get` Methods

Method	Type	Description
`clock`	`() => KDAudioClock`	Returns the `KDAudioClock` instance that owns this event.
`uid`	`() => string`	Returns the unique identifier `string` assigned to this event.
`nextDeadline`	`() => { scheduled: number; earliest: number; latest: number }`	Returns an object holding `scheduled`, `earliest`, and `latest` deadline values in seconds.
`tolerance`	`() => { early: number; late: number }`	Returns an object holding `early` and `late` tolerance values in seconds.
`loop`	`() => object`	Returns an object holding `initialInterval`, `currentInterval`, `repetitions`, `elapsedTickCount`, and `timeStretch` values.
`loop().initialInterval`	`number`	The base interval in milliseconds for a looping event.
`loop().currentInterval`	`number`	The actual interval in milliseconds for a looping event after time stretch has been applied.
`loop().repetitions`	`number`	The total number of repetitions for a looping event.
`loop().elapsedTickCount`	`number`	The number of ticks/repetitions that have already elapsed.
`loop().timeStretch`	`number`	The current time stretch ratio.
`callbacks`	`() => object`	Returns an object holding values for `onTick`, `onComplete`, `onAborted`, and `onMissed` callback functions.
`callbacks().onTick`	`(event: KDAudioClockEvent) => void`	Function called on every successful tick.
`callbacks().onCompleted`	`(event: KDAudioClockEvent) => void`	Function called when `elapsedTickCount` reaches the target number of `repetitions`.
`callbacks().onAborted`	`(event: KDAudioClockEvent) => void`	Function called if an event is deleted before reaching its target number of `repetitions`, including if `repetitions` is `Infinity`.
`callbacks().onMissed`	`(event: KDAudioClockEvent) => void`	Function called if an event attempts to fire outside its margin of error determined by its `tolerance` levels.

justkd / KDAudioClock

KDAudioClock

v 1.0.7 | © justKD 2020 | MIT License

Demo

Basic Use

`start()`

`stop()`

`pause()`

Start, stop, and pause return promises.

`setTimeout(f, t)`

`setInterval(f, t)`

`clearInterval(e)`

Extended Use

`schedule(opts)`

`sync(events)`

Tip: use `sync` every so often to counter drifting that may occur between simultaneous long running timers.

`timeStretch(events)`

`meter()`

`setBPM(bpm)`

`setBeat(beat)`

`score(scoredEvents)`

Loop scores by assigning it to a variable and calling itself.

Exit a score with `score.break()`.

Create reusable "measures" and add them to a score with the spread operator.

API

KDAudioClock Constructor Parameters

KDAudioClock Methods

KDAudioClockEventOptions Parameters

KDAudioClockEvent Methods

`new KDAudioClockEvent.get` Methods

About

Languages

KDAudioClock

v 1.0.7 | © justKD 2020 | MIT License

Demo

Basic Use

start()

stop()

pause()

Start, stop, and pause return promises.

setTimeout(f, t)

setInterval(f, t)

clearInterval(e)

Extended Use

schedule(opts)

sync(events)

Tip: use sync every so often to counter drifting that may occur between simultaneous long running timers.

timeStretch(events)

meter()

setBPM(bpm)

setBeat(beat)

score(scoredEvents)

Loop scores by assigning it to a variable and calling itself.

Exit a score with score.break().

Create reusable "measures" and add them to a score with the spread operator.

API

KDAudioClock Constructor Parameters

KDAudioClock Methods

KDAudioClockEventOptions Parameters

KDAudioClockEvent Methods

new KDAudioClockEvent.get Methods

About

Languages

`start()`

`stop()`

`pause()`

`setTimeout(f, t)`

`setInterval(f, t)`

`clearInterval(e)`

`schedule(opts)`

`sync(events)`

Tip: use `sync` every so often to counter drifting that may occur between simultaneous long running timers.

`timeStretch(events)`

`meter()`

`setBPM(bpm)`

`setBeat(beat)`

`score(scoredEvents)`

Exit a score with `score.break()`.

`new KDAudioClockEvent.get` Methods