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:

import MusicTime from ' musictime ' ; const t1 = new MusicTime ( 1 , 2 , 3 ) ; const t3 = new MusicTime ( 2 ) ; const t2 = MusicTime . fromString ( ' 1.2.3 ' ) ; const t5 = MusicTime . fromTime ( 10 , 120 ) ;

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):

new MusicTime ( 0 , 120 , 0 ) . toTime ( 120 ) ;

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).

new MusicTime ( 1 , 0 , 0 ) . getBarsBeatsSixteenths ( ) ;

By default, 1 bar consists of 4 beats , and 1 beat consists of 4 sixteenths .

new MusicTime ( 0 , 0 , 16 ) . getBarsBeatsSixteenths ( ) ; new MusicTime ( 0 , 0 , 23 ) . getBarsBeatsSixteenths ( ) ;

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:

new MusicTime ( 0 , 3 , 0 , { sixteenthsPerBeat : 4 , beatsPerBar : 3 } ) . getBarsBeatsSixteenths ( ) ;

You are allowed to use floats for the bars , beats or sixteenths values:

new MusicTime ( 0 . 5 , 0 , 0 ) . getBarsBeatsSixteenths ( ) ; new MusicTime ( 0 , 0 . 5 , 0 ) . getBarsBeatsSixteenths ( ) ; new MusicTime ( 0 , 0 , 1 . 5 ) . getBarsBeatsSixteenths ( ) ;

(Floats are not allowed in strings that you pass to the fromString method. This will result in an error.)

operations

const result1 = t1 . add ( t2 ) ; const result2 = t2 . subtract ( t1 ) ; const result3 = t2 . multiply ( 3 ) ; const result4 = MusicTime . add ( t1 , t2 ) ; const result5 = MusicTime . subtract ( t2 , t1 ) ; const result6 = MusicTime . multiply ( t2 , 3 ) ; const clone = result1 . clone ( ) ; new MusicTime ( 1 , 2 , 3 ) . toString ( ) ;

When adding or subtracting, the resulting (newly created) instance will use the sixteenthsPerBeat and beatsPerBar settings from the instance that comes first:

const result = t1 . add ( t2 ) ; const result = MusicTime . add ( t1 , t2 ) ;

comparison

Instances have a valueOf method, which makes direct comparison through relational operators ( > < >= <= ) possible:

const time1 = new MusicTime ( 1 , 0 , 0 ) ; const time2 = new MusicTime ( 2 , 0 , 0 ) ; time1 > time2 time1 < time2

Note that this does not affect checking equality ( == , === , != , !== ).

limitations