musictime
A class that helps with timings in a musical context. Instances are defined on a grid of bars, beats and sixteenths and can be converted to and from actual time in seconds.
install
npm install musictime
creating an instance
There are a few ways to create a MusicTime
instance:
; // constructor accepts bars, beats, sixteenthsconst t1 = 1 2 3; // all params default to 0const t3 = 2; // parse from a stringconst t2 = MusicTime; // creates an instance at 10s (at 120bpm)const t5 = MusicTime;
Note that bars
, beats
and sixteenths
all start at 0. This might be slightly counterintuitive from a musical perspective (counting 0,1,2,3 instead of 1,2,3,4).
converting to seconds
The most common thing to do with a MusicTime
instance is converting to seconds. You can do this by supplying the tempo in beats per minute (BPM):
01200;// result = 60
bars, beats, sixteenths grid
Every MusicTime
instance ends up on the bars/beats/sixteenths grid, which can be seen using the getBarsBeatsSixteenths
method. In the resulting object, all these three values will be integers, any remaining time (when the instance can not be placed exactly on the grid) can be found in the remainingSixteenths
property (defined as a factor of sixteenths).
1 0 0;// {bars: 1, beats: 0, sixteenths: 0, remainingSixteenths: 0}
By default, 1 bar
consists of 4 beats
, and 1 beat
consists of 4 sixteenths
.
// all values are normalized, so 16 sixteenths make up 1 bar0 0 16;// {bars: 1, beats: 0, sixteenths: 0, remainingSixteenths: 0} 0 0 23;// {bars: 1, beats: 2, sixteenths: 3, remainingSixteenths: 0}
If you want to change how many beats go in a bar and/or how many sixteenths in a beat, you can pass that info in the constructor:
0 3 0 sixteenthsPerBeat: 4 beatsPerBar: 3;// {bars: 1, beats: 0, sixteenths: 0, remainingSixteenths: 0}
You are allowed to use floats for the bars
, beats
or sixteenths
values:
05 0 0;// {bars: 0, beats: 2, sixteenths: 0, remainingSixteenths: 0} 0 05 0;// {bars: 0, beats: 0, sixteenths: 2, remainingSixteenths: 0} 0 0 15;// {bars: 0, beats: 0, sixteenths: 1, remainingSixteenths: 0.5}
(Floats are not allowed in strings that you pass to the fromString
method. This will result in an error.)
operations
// calculationsconst result1 = t1;const result2 = t2;const result3 = t2; // also available as static methodsconst result4 = MusicTime;const result5 = MusicTime;const result6 = MusicTime; const clone = result1; // clones the instance123; // "1.2.3". note that this does not show the remainingSixteenths value
When adding or subtracting, the resulting (newly created) instance will use the sixteenthsPerBeat
and beatsPerBar
settings from the instance that comes first:
// in both cases: result will have the settings from t1const result = t1;const result = MusicTime;
comparison
Instances have a valueOf
method, which makes direct comparison through relational operators (> < >= <=
) possible:
const time1 = 1 0 0;const time2 = 2 0 0; time1 > time2 // truetime1 < time2 // false
Note that this does not affect checking equality (==
, ===
, !=
, !==
).
limitations
- anything regarding negative numbers and timings is untested and will probably lead to incorrect results.