Needling Perl Mongers

    TypeScript icon, indicating that this package has built-in type declarations

    2.0.3 • Public • Published


    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.


    npm install musictime

    creating an instance

    There are a few ways to create a MusicTime instance:

    import MusicTime from 'musictime';
    // constructor accepts bars, beats, sixteenths
    const t1 = new MusicTime(1, 2, 3);
    // all params default to 0
    const t3 = new MusicTime(2);
    // parse from a string
    const t2 = MusicTime.fromString('1.2.3');
    // creates an instance at 10s (at 120bpm)
    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);
    // 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).

    new MusicTime(1, 0, 0).getBarsBeatsSixteenths();
    // {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 bar
    new MusicTime(0, 0, 16).getBarsBeatsSixteenths();
    // {bars: 1, beats: 0, sixteenths: 0, remainingSixteenths: 0}
    new MusicTime(0, 0, 23).getBarsBeatsSixteenths();
    // {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:

    new MusicTime(0, 3, 0, {sixteenthsPerBeat: 4, beatsPerBar: 3}).getBarsBeatsSixteenths();
    // {bars: 1, beats: 0, sixteenths: 0, remainingSixteenths: 0}

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

    new MusicTime(0.5, 0, 0).getBarsBeatsSixteenths();
    // {bars: 0, beats: 2, sixteenths: 0, remainingSixteenths: 0}
    new MusicTime(0, 0.5, 0).getBarsBeatsSixteenths();
    // {bars: 0, beats: 0, sixteenths: 2, remainingSixteenths: 0}
    new MusicTime(0, 0, 1.5).getBarsBeatsSixteenths();
    // {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.)


    // calculations
    const result1 = t1.add(t2);
    const result2 = t2.subtract(t1);
    const result3 = t2.multiply(3);
    // also available as static methods
    const result4 = MusicTime.add(t1, t2);
    const result5 = MusicTime.subtract(t2, t1);
    const result6 = MusicTime.multiply(t2, 3);
    const clone = result1.clone();    // clones the instance
    new MusicTime(1,2,3).toString();  // "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 t1
    const result = t1.add(t2);
    const result = MusicTime.add(t1, t2);


    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 // true
    time1 < time2 // false

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


    • anything regarding negative numbers and timings is untested and will probably lead to incorrect results.


    npm i musictime

    DownloadsWeekly Downloads






    Unpacked Size

    183 kB

    Total Files


    Last publish


    • petervdn