REF / Music API / TimeKeeper

Ascene . Agraph . Aengine
Anode . Modulator . Envelope
Songbook . Song . TimeKeeper
Voices . SampleMgr . StreamMgr
Loader . Async . Plot
Random . Rhythm . Util
MIDI . OSC . HID . Piano
Music Theory with Tonal

right-click to navigate to page sections

TimeKeeper helps you keep the beat.

TimeKeeper

The optional TimeKeeper class can be useful in a number of scenarios to synchronize independent voices/tracks in a larger composition.

As Repository for Tempo

Time Signature defines a musical measure, aka Bar.
Tempo defines musical cadence, measured in BPM (Beats Per Minute).
DeltaTempo description musical acceleration, measured in BPM/second.
TkPosition tracks current beat, bar and time.

Usage: first intialize TimeKeeper via SetSignature and SetTempo. Later, request: BeatDur(), MeasureDur(), NoteDur("notetype", dots?). Multiple independant instances of TimeKeeper are possible and can be synchronized to align their beats or bars. For simplest use-case, a single global TimeKeeper in each sandbox may be preferred.

As Event Generator

You can subscribe to TimeKeeper events like beat and bar then trigger notes, parameter-changes, etc. Multiple callbacks can be installed for each event allowing you to author separate tracks in separate functions. Your callbacks should query TkPosition to produce absolute start times and durations, used as arguments to anode methods like Note(), SetParam(), etc.

See TimeKeeper Examples.

TimeKeeper Methods

Basic Tempo

Name	Description
`constructor(ascene)`	Constructs an instance of TimeKeeper. An active Ascene is required.
`SetSignature(num,denom)`	Changes the current time signature to `num/denom`, where `denom` defines the beat and `num` is beats per bar. (4,4)
`GetSignature()`	Returns the current time signature as an array of length 2.
`SetTempo(bpm, dbpm?)`	Changes the current tempo in `beats per minute` (120). `dbpm` is an optional parameter that expresses tempo change in BPM/sec. (0)
`GetTempo()`	Returns the current BPM.
`BarDur()`	Returns the current duration of a bar, in samples.
`BeatDur()`	Returns the current duration of a beat, in samples.
`BeatSec()`	Returns the current duration of a beat, in seconds.
`NoteDur(type, dots=0)`	Returns the current duration of a note, in samples. `NoteDur type` is a string indicating standard music notation durations relative to the current tempo and time signature. For example, in `4/4 time`, a beat is a quarter note, while in `3/8 time`, a beat is an eighth note.
	When `dots` is > 0, the duration is modified in the usual way: each dot adds a successively smaller fraction of the original note's duration. The first dot adds 1/2, the second adds 1/4, the third adds 1/8, and so on.

NoteDur Type	Quarter Notes
`oct`, `dl`	32
`quad`, `l`	16
`double`, `d`	8
`whole`, `w`	4
`half`, `h`	2
`quarter`, `q`	1
`eighth`, `e`	1/2
`sixteenth`, `s`	1/4
`thirtysecond`,`t`	1/8
`sixtyfourth`,`sf`	1/16
`h`	1/32
`th`	1/64

Event Generator

These methods are required to initiate event generation callbacks.

Name	Description
`On(evt, callback, ctx?)`	Installs a callback for the named event. When provided, the optional ctx parameter is delivered to calback prior to event-specific arguments.
`Off(evt, callback, ctx?)`	Uninstalls a callback for the named event.
`async Start(alignment=0,sections=null)`	Initiates event handling for the TimeKeeper instance. `alignment` can be used to sychronize bar or beat locations across multiple instances. You can provide an array of TkSections to describe tempo changes and repeats across a session.
`Stop()`
`IsRunning()`	Returns true while event-handling is active.
`GetPosition()`	Returns the current global TkPosition
`GetSection()`	Returns the current section TkSection or `null`

Here are the basic events:

Event	Description
`start`	triggers when `TimeKeeper.Start()` is issued.
`stop`	triggers when `TimeKeeper.Stop()` is issued.
`beat`	triggers on each beat, delivering an updated TkPosition
`bar`	triggers on each bar, delivering an updated TkPosition
`section`	triggers on each section, delivering the global TkPosition and current TkSection

TkPosition

The TkPosition class is used to describe a temporal location in your song. When active, the Event Generator uses its current tempo to periodically update the song position and deliver updates to its event subscribers. Subscribers should usually access the song position's read-only (RO) methods.

Name	Access	Description
`Now()`	`RO`	Returns the current time, in samples, for use by callback functions.
`GetPosition()`	Returns the current song position (TkPosition).
`GetSection()`	Returns the current song section (TkSection), null if there are none.
`CurrentTime()`	`RO`	Returns the current `time`, in seconds, for use by callback functions.
`CurrentBeat()`	`RO`	Returns the current global integer `beat` in the song.
`CurrentBeatInBar()`	`RO`	Returns the current `beat` within the current `bar` in the song.
`CurrentBar()`	`RO`	Returns the current integer `bar` in the song.
`NewBarIs(num)`	`RO`	Return true if the new bar matches num. Equivalent to checking bar and beatinbar == 0.
`Reset(timeOrigin)`	`RW`	Invoked by `TimeKeeper.Start`
`NextBeat(signature, beatsecs, beatsamps, sigChanged?)`	`RW`	Periodically invoked by `TimeKeeper`

TkSection

You can use TkSection arrays to define tempo changes and section repeats across a TimeKeeper session.

Name	Description
`constructor(name, signature, tempo, nbars, repeats=1)`	Creates a `TkSection`. Signature is `[num,denom]`, tempo is either `bpm` or `[bpm, dbpm]`.
`GetName()`	returns the section name
`GetTempo()`	returns the section tempo (aa provided).
`GetTimeSig()`	returns the section time signature (as provided).
`GetLocalPosition()`	returns the local position within the section.
`GetRepeatCounter()`	returns a value between 0 and nrepeats-1
`GetNumRepeats()`	returns the section repeats (as provided).