Dilla

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.

Install

$ npm install --save dilla

Usage

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.

Example

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', [
  high,
  ['*.>1.01', low]
]);
 
var oscillator, gainNode;
dilla.on('step', function (step) {
  if (step.event === 'start') {
    oscillator = step.context.createOscillator();
    gainNode = step.context.createGain();
    oscillator.connect(gainNode);
    gainNode.connect(step.context.destination);
    oscillator.frequency.value = step.args.freq;
    gainNode.gain.setValueAtTime(1, step.time);
    oscillator.start(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;
  }
});
 
dilla.start();

Tutorials

• Making a boombap beat with Dilla and the Web Audio API
• Using expressions in Dilla

API

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

Scheduling

• 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

Objects

Position

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

Note

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

Events

tick

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"
});

step

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()
});

Develop

• make test
• make coverage
• make publish

Changelog

• 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
  • NEW: Modulus operator expression
  • NEW: Add custom matcher with dilla.expressions.addMatcher
• 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
  • DOCS: Added link to expressions tutorial
  • CHANGED: Improved code complexity and test coverage
• 1.3.4
  • DOCS: Fix typos
• 1.3.5
  • FIXED: Updated dilla-expressions to solve modulus by 1 issue
• 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

License

MIT © Adam Renklint