npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

musical-timer

v1.0.2

Published

Timers based in musical parameters (time signature, tempo and beat resolution)

Downloads

4

Readme

Javascript Musical Timers

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

Installation

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>

Import/Include

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>

Constructor Syntax

The MusicalTimer() Constructor creates a new MusicalTimer Instance.

var musicalTimerInstance = new MusicalTimer( tickHandler [, tempo] )

Parameters

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

Methods & Properties

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

musicalTimerInstance.bar Read only

Read only. Returns an integer representing the current musical bar


musicalTimerInstance.beat Read only

Read only. Returns an integer representing the current beat in the bar.


musicalTimerInstance.beatSubdivision Read only

Read only. Returns an integer representing the ammount of elements a beat can contain considering the resolution factor.


musicalTimerInstance.beatsPerBar Read only

Read only. Returns an integer representing the ammount of beats each bar contain, according to the time signature.


musicalTimerInstance.inSync Read only

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 - 𝅘𝅥 𝅘𝅥 𝅘𝅥 𝅘𝅥 )

musicalTimerInstance.status Read only

Read only. String representing the status of the timer : 'stopped' , 'running' , 'paused'


musicalTimerInstance.statusCode Read only

Read only. Integer representations of the status of the timer : 0, 1, 2


musicalTimerInstance.subBeat Read only

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 )


musicalTimerInstance.tick Read only

Read only. Integer representing the clock's current tick.


musicalTimerInstance.tickDeltatime Read only

Read only. Integer representing the time in miliseconds since the last clock tick.


musicalTimerInstance.tickInterval Read only

Read only. Integer representing the theoretical time in miliseconds betwen ticks (considering the beat resolution and tempo).


musicalTimerInstance.timestamp Read only

Read only. Integer representing the time passed since timer was started, in miliseconds


musicalTimerInstance.timestampFormated Read only

Read only. String representing the time passed since timer was started, in the format hh:mm:ss:SS

Usage example

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

To do...

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)