Generate configurable Musical Timers
that can be running at the requested tempo (BPM) frequency, with the desired beat subdivision resolution, and aware of the provided time signature stucture. Properties as BAR, BEAT and SUB-BEAT... are being tracked and updated automatically by the internal clock.
Main Features :
- Cross enviroment : Browser & Node compatible
- Highly Performant
- Third party dependencies free
- Adjustable Tempo (up to 200 bpm)
- Supported time signatures : 2/4 | 3/4 | 4/4 | 6/8 | 9/8 | 12/8
- Supported time subdivision Modes : Binary / Ternary
- Beat subdivision resolution up to π £ ( sixty-fourth note, hemidemisemiquave, 1/16th of a beat)
- Tracks clock lose of Sync
- Clock controls : Play / Pause / Resume / Stop (Reset)
Example :
import {MusicalTimer} from './path-to/musical-timer.js';
// Create a new timer, handled by a function called myTickHandler
let myTimer = new MusicalTimer( myTickHandler );
// configure and start ticking
myTimer.tempo = 120;
myTimer.signature = '2/4';
myTimer.play();
// -> myTickHandler will be executed every 500ms (120bpm)
Demo: See it in action
You can choose between any of the following available distribution channels:
- GIT: Clone the repository locally using git (or download the latest release here)
$ git clone https://github.com/colxi/musical-timer.git
- NPM: Install it using npm.
$ npm install musical-timer -s
- CDN: Include the script in your HTML header (
window.MusicalTimer
will be created).
<script src="https://colxi.info/musical-timer/src/main.js" type="module"></script>
You can import/include this library in Browser & Node enviroment:
- Node : You can require the library (after installing it with
npm
) with :
const MusicalTimer = require('musical-timer');
- Browser (import) : You can import the library with :
import {MusicalTimer} from './path-to/musical.timer.js';
- Browser (include) : You can include in your HTML head. The Constructor will become available as
window.MusicalTimer
<script src="./path-to/musical-timer/src/main.js" type="module"></script>
The MusicalTimer()
Constructor creates a new MusicalTimer Instance
.
var musicalTimerInstance = new MusicalTimer( tickHandler [, tempo] )
-
tickHandler
: (Required). A callback function to be called in each clock tick. The callback will be bound to the new timer instance, and will recieve a reference to the instance as a first argument, when called. -
tempo
: (Optional) Number representing the clock tempo. (Default:60
)
The following reference, documents all the methods & properties available in a MusicalTimer
instance :
musicalTimerInstance.play()
Starts (or resumes when paused) the timer.
let myTimer = new MusicalTimer( ()=>{} )
myTimer.play(); // clock starts ticking
musicalTimerInstance.pause()
Pauses the timer. If timer is stopped, the request is ignored.
let myTimer = new MusicalTimer( ()=>{} )
myTimer.play();
myTimer.pause(); // pause clock
musicalTimerInstance.stop()
Stops the timer, and resets its initial values.
let myTimer = new MusicalTimer( ()=>{} )
myTimer.play();
myTimer.stop(); // timer stops and gets reseted
Read only. Returns an integer representing the current musical bar
Read only. Returns an integer representing the current beat in the bar.
Read only. Returns an integer representing the ammount of elements a beat can contain considering the resolution factor.
Read only. Returns an integer representing the ammount of beats each bar contain, according to the time signature.
Read only. Returns an boolean representing the clock sync status. If the provided callback function is not performant, clock could run out of sync.
musicalTimerInstance.resolutionFactor
Accepts an integer (range 0-4) to set the beat subdivision resolution ( Default=0 ). Resolution levels are :
- ( π ) 0 : Each beat has 0 sub-beats - quarter note (crotchet) -
- ( π ) 1 : Each beat has 2 sub-beats - eighth note (quaver) -
- ( π ‘ ) 2 : Each beat has 4 sub-beats - sixteenth note (semiquaver) -
- ( π ’ ) 3 : Each beat has 8 sub-beats - thirty-second note (demisemiquaver)
- ( π £ ) 4 : Each beat has 8 sub-beats - sixty-fourth note (hemidemisemiquaver) -
Depending on the resolution level, each timer tick, will represent a crotchet, a quaver, a semiquaver...
musicalTimerInstance.signature
Accepts a string representing the time signature ( Default='4/4' ). Accepted time signatures are :
- 2/4 (binary - π π )
- 3/4 (binary - π π π )
- 4/4 (binary - π π π π )
- 6/8 (ternary - π π )
- 9/8 (ternary - π π π )
- 12/8 (ternary - π π π π )
Read only. String representing the status of the timer : 'stopped' , 'running' , 'paused'
Read only. Integer representations of the status of the timer : 0, 1, 2
Read only. Returns an integer representing the current subbeat in the beat.
musicalTimerInstance.tempo
Accepts a positive number ( range 1-200 ) representing the beats per minute (bpm) clock frequency. ( Default=60 )
Read only. Integer representing the clock's current tick.
Read only. Integer representing the time in miliseconds since the last clock tick.
Read only. Integer representing the theoretical time in miliseconds betwen ticks (considering the beat resolution and tempo).
Read only. Integer representing the time passed since timer was started, in miliseconds
Read only. String representing the time passed since timer was started, in the format hh:mm:ss:SS
In the following example the Constructor
is called to create a musical timer, handled by a function that outputs the timer state in each tick.
:
import {MusicalTimer} from './path-to/musical-timer.js';
// Create a new timer and asign a tick handler
let myTimer = new MusicalTimer( function(){
console.log( `${this.timestampFormated} : SubBeat ${this.subBeat} of Beat ${this.beat} of bar ${this.bar}` );
});
// configure timer to run at 120bpm
myTimer.tempo = 120;
// with a 2/4 signature ( 2 beats per bar in binary mode )
myTimer.signature = '2/4';
// and a beat subdivision of 2 sub-beats ( π
, eighth note, quaver )
myTimer.resolutionFactor = 1;
// start timer!
myTimer.play();
Output :
00:00:00.00 : SubBeat 1 of Beat 1 of bar 1
00:00:00.25 : SubBeat 2 of Beat 1 of bar 1
00:00:00.50 : SubBeat 1 of Beat 2 of bar 1
00:00:00.75 : SubBeat 2 of Beat 2 of bar 1
00:00:01.00 : SubBeat 1 of Beat 1 of bar 2
00:00:01.25 : SubBeat 2 of Beat 1 of bar 2
00:00:01.50 : SubBeat 1 of Beat 2 of bar 2
00:00:01.75 : SubBeat 2 of Beat 2 of bar 2
00:00:02.00 : SubBeat 1 of Beat 1 of bar 3
...
In the current release the timer can be used to handle simple scenarios, and to play elementary scores/rythmical patterns, but would be imposible to use it to play advanced and complex patterns. The following improvements should be performed in order to provide support for ot:
- Set
current tick
manually - Allow a
swing
modifier - Allow
binary
&ternary
modes to run simultaneously (to let polyphonic complex melodies to be played)
Other improvements in mind :
- Set configurable
SyncThreeshold
property - Set
current tick
providing timestamp (or formated timestamp)