Scribbletune

Scribbletune has a very minimal API.

The work flow involves creating clips which are containers for musical ideas. Once a clip is created, it can be concatenated with other clips to create longer musical ideas (or songs). You can then, either export the clip as a MIDI file or play it in the browser.

clip returns: Array

A clip is a like a measure of music. It can be a single bar or two bars or how many ever bars you need. In DAWs such as Ableton Live and Propellerhead Reason, a clip is what you create in the session or arrangement view to capture a musical idea.

The clip method takes an object literal as an argument. This object lets you define the parameters of that clip. Here is an example of the clip method being called with an object that sets up the most basic properties of the clip:

var scribble = require('scribbletune');

// Create a clip that plays the middle C
var clip = scribble.clip({
	notes: 'c4',
	pattern: 'x'
});

// Render a MIDI file of this clip
scribble.midi(clip, 'c.mid');

notes {String|Array}

This property lets you set up the notes we want to play in the clip. You can enter notes manually or use the built-in scale/mode method to generate notes from a scale and further mangle them into an array. For instance, in the preceding example we set the 'c4' note as the only note to be played across a pattern. You can even set up a bunch of notes:

var scribble = require('scribbletune');

// Create a clip that plays the C major scale
var clip = scribble.clip({
	notes: 'c4 d4 e4 f4 g4 a4 b4 c5', // Or ['c4', 'd4', 'e4' ...]
	pattern: 'x'.repeat(8)
});

// Render a MIDI file of this clip
scribble.midi(clip, 'cscale.mid');

In this example we explicitly set the notes of the C major scale in the 4th octave. Scribbletune also has a method to generate scales directly and output an array which you can then manipulate with JavaScript Array functions.

pattern {String}

This is the second most important parameter for the clip method's object. It abstracts away the MIDI note on and note off events along with the individual note durations into a nifty 3 character instruction language made up only of x, -(hyphen) and _(underscore). This is native to Scribbletune and it's used in multiple ways across the Scribbletune library. But maybe we are making it too complex to understand, here's an example of what a pattern looks like and what it means:

xxxx

This pattern is akin to what would look like the following in a DAW:

As you can deduce, each x implies a note on event (hence shows a note in the piano roll when imported) and each hyphen implies a note off event which does not have any note in that location in the 16 beat clip. Other than setting note on and off events, we can even set the duration of a note on event using the pattern language's third and final character: _ (underscore) character instead:

x__-x__-x__-x__-

Here we replaced 2 hyphens after each x with underscores. An underscores implies a sustain to the preceding x. More underscores imply more sustain of the preceding x. Here's how it now looks in a piano roll:

Basically the underscores just extended the notes set up by the x character. These are really simply examples but you can do a lot with patterns! The examples section showcase a lot more patterns and how they are useful when creating complex melodies or chord progressions. You can try out some patterns and see how they look on a 16 beat grid.

shuffle (Boolean) default: false

Setting this property will randomize the order of the notes you set in the clip method.

scale/mode returns: Array

A scale is a set of musical notes ordered by pitch. A displaced order of a scale is also called a mode. Scribbletune exports the same method as scale as well as mode.

The scale method takes 2 mandatory + 2 optional parameters:

  • root {String}
  • scale {String}
  • octave {Number} default: 4
  • addRootFromNextOctave {Boolean} default: true
var scribble = require('scribbletune');

// Create a clip that plays the middle C
var cMinor = scribble.scale('c4 minor'); // [ 'c4', 'd4', 'd#4' ... ]

// The scale method can also be refered to as `mode`
cMinor = scribble.mode('c4 minor'); // [ 'c4', 'd4', 'd#4' ... ]

// That's the same as
cMinor = scribble.mode('c4 aeolian'); // [ 'c4', 'd4', 'd#4', 'f4' ...]

There are a bunch of scales and modes available in Scribbletune. You can list the available modes by invoking the modes method. To view a list now, click here.

midi

As the name suggests, the midi method generates a MIDI file from it's input. It takes 1 mandatory and 1 optional parameter:

  1. clip {Array} The clip that you create using the clip method
  2. filename {String} This is optional. If you don't provide a filename, Scribbletune will create a file called music.mid
var scribble = require('scribbletune');

var clip = scribble.clip({
	notes: 'c4',
	pattern: 'x_______'
});

scribble.midi(clip); // Will create a file called music.mid
// OR
scribble.midi(clip, 'c.mid'); // Will create a file called c.mid

chord

Scribbletune recognizes chords by their commonly used names. For instance here is a chord progression set up via chord names:

var scribble = require('scribbletune');

var clip = scribble.clip({
	// Use chord names directly in the notes array
	// M stands for Major, m stands for minor
	notes: 'CM FM GM CM',
	pattern: 'x---'.repeat(4)
});


scribble.midi(clip, 'chords.mid');

Here's how that looks on a piano roll when imported into a DAW

Other than recognizing chords in a notes array, Scribbletune uses Tonal.js to get a particular chord as an array of notes from that chord:

var scribble = require('scribbletune');
var cMajorChord = scribble.chord('CM'); // [ 'c4', 'e4', 'g4' ]

To get the chord on a particular octave, just append a hyphen and a number:

var scribble = require('scribbletune');
var cMajorChord = scribble.chord('CM-5'); // [ 'c5', 'e5', 'g5' ]

Lastly, you can get an array of the available chords by calling the getChords method:

var scribble = require('scribbletune');
var availableChords = scribble.chords(); // Lists all available chords

If you like this project then show your ❤ Star this project on Github!