Schedule looped playback of Web Audio notes at 96 ticks per beat
JavaScript Makefile
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


npm npm GitHub stars GitHub forks

Travis branch Code Climate Code Climate David dependencies David devDependencies

Schedule looped playback of Web Audio notes at 96 ticks per beat

Based on ditty and bopper. Named after one of the greatest to ever touch a drum machine.


$ npm install --save dilla


var Dilla = require('dilla');
var audioContext = new AudioContext();
var dilla = new Dilla(audioContext, options);

Options and defaults

  "tempo": 120,
  "beatsPerBar": 4,
  "loopLength": 2

Note that loopLength is measured in bars, i.e. the default loop length above is 8 beats.


The "hello world" of audio libraries, the simple metronome: check out the demo or code.

var high = {
  'position': '*.1.01',
  'freq': 440,
  'duration': 15
var low = { 'freq': 330, 'duration': 15 };

dilla.set('metronome', [
  ['*.>1.01', low]

var oscillator, gainNode;
dilla.on('step', function (step) {
  if (step.event === 'start') {
    oscillator = step.context.createOscillator();
    gainNode = step.context.createGain();
    oscillator.frequency.value = step.args.freq;
    gainNode.gain.setValueAtTime(1, step.time);
  else if (step.event === 'stop' && oscillator) {
    gainNode.gain.setValueAtTime(1, step.time);
    gainNode.gain.linearRampToValueAtTime(0, step.time + 0.1);
    oscillator.stop(step.time + 0.1);
    oscillator = null;
    gainNode = null;




Playback controls

  • dilla.start() start playback at current position
  • dilla.pause() stop playback at current position
  • dilla.stop() stop playback and set position to start of loop


  • dilla.set(id, notes) schedule playback of array of notes on channel with id, clearing any previously scheduled notes on same channel. A note can be defined as a note object (must contain position) or an array with position at index 0 and params in an object at index 1 (see metronome example above)
  • dilla.get(id) returns an array of notes scheduled on channel with id
  • dilla.channels() returns an array of all channel ids
  • dilla.clear(id) clear notes for channel
  • dilla.clear() clear notes for all channels

Position and options

  • dilla.position returns current position string, "BAR.BEAT.TICK"
  • dilla.setPosition(position) set position to "BAR.BEAT.TICK"
  • dilla.setTempo(bpm) set playback tempo, default 120
  • dilla.setBeatsPerBar(beats) change playback time signature, default 4
  • dilla.setLoopLength(bars) change bars per loop, default 2



  • A string in the format BAR.BEAT.TICK
  • Where each part is a (1-based index) number
  • Tick values under 10 are padded with a leading zero
  • Can contain expressions which are expanded by dilla.set()


  • An object that must define position
  • Can define duration in ticks (optional) or any other other params, like frequency or playback rate



Fires when the bar, beat or tick value of dilla.position() is updated.

dilla.on('tick', function (tick) {
  console.log(tick.position) // "1.1.01"


Fires when a scheduled note should start or stop. For notes with undefined or falsy duration value (i.e. oneshots), no stop step event is triggered.

dilla.on('step', function (step) {
  console.log(step.event); // "start" or "stop"
  console.log(step.time); // offset in seconds
  console.log(step.args); // note data originally passed to set()


  • make test
  • make coverage
  • make publish


  • 0.1.0
    • Initial release, ported from bap project
  • 1.0.0
    • Improved release for metronome example oscillator
    • Warn in console when events provided to dilla.set() is out of bounds
  • 1.0.1
    • FIXED: dilla.getClockPositionFromPosition() returns incorrect value for ticks #4
    • FIXED: step.position is incorrect #1
  • 1.0.2
    • FIXED: dilla.getPositionWithOffset() returns incorrect position when offset is falsy #5
    • FIXED: "stop" fires for events with falsy duration (oneshots) #3
  • 1.1.0
    • NEW: Use expressions to insert repeating events #2
    • FIXED: "Out of bounds" warning does not say which channel #6
  • 1.1.1
    • FIXED: Ambiguous use of the word "event" #8
  • 1.2.0
    • CHANGED: Note passed to dilla.set() can be an array with position at index 0, or a note object, and will be merged into a note object
    • NEW: Added lots of unit tests
  • 1.3.0
  • 1.3.1
    • FIXED: Minifying dilla function names breaks everything
  • 1.3.2
    • FIXED: "step" event stops triggering when tab is put to background #14
    • FIXED: Metronome example is leaking, never stops oscillator #15
  • 1.3.3
  • 1.3.4
    • DOCS: Fix typos
  • 1.3.5
  • 1.4.0
    • ADDED: Define options.expandNote(note) to transform note after expression expansion
    • CHANGED: Use local version of Ditty with longer lookahead
    • CHANGED: Use dilla-expressions v1.2, with greater than and less than operators
  • 1.5.0
    • CHANGED: Use dilla-expressions v2.0, with 25-1500 times better performance
    • FIXED: Use prefixed AudioContext in Safari
  • 1.6.0
    • CHANGED: Reduce intensity of keepalive pings to improve CPU performance
    • CHANGED: Memoize expensive methods
  • 1.7.0
    • CHANGED: Use forked version of Bopper, with less object creation
  • 1.8.0
    • CHANGED: Memoize inner part of set method, for better performance and less allocation
    • CHANGED: Use meeemo 1.1.1, which uses Map instead of plain object when possible
    • CHANGED: Refactor ditty to avoid deoptimization of inner loop bodies
  • 1.8.1
    • FIXED: Drops notes when beatsPerBar is above 9 #22
  • 1.8.2
    • FIXED: Changing beats per bar leads to confusion in the order of the steps #23
  • 1.8.3
    • FIXED: Correct memoization key for dilla.getClockPositionFromPosition #23
  • 1.8.4 (2017-12-14)
    • FIXED: setBeatsPerBar not working #26


MIT © Adam Renklint