rroonniinn / vexflow-json

A wrapper for the VexFlow staff engraving library to render staff notation from simple JSON instead complex API calls.

VexFlow JSON¶ ↑

This library allows musical notation specified in JSON, for rendering with the awesome VexFlow staff engraving library (HTML5 Canvas or SVG). The goal of this project is to make 90% of staff engraving significantly easier than interacting with the VexFlow API directly. Specifying the data in JSON also allows a consistent representation of the staff to be passed around from server to client.

Dependencies:¶ ↑

• VexFlow

• Underscore.js (Will be removed as a dependency before long)

Usage:¶ ↑

Simply define a canvas, initialize a new Vex.Flow.JSON object with the JSON data, and render it:

<canvas id="staff" width="600" height="150"></canvas>

<script type="text/javascript">
  var canvas = document.getElementById("staff");
  var json = new Vex.Flow.JSON(["C", "E", "G"]);
  json.render(canvas);
</script>

Note that the render method accepts a second argument with render options, if you want to override the width and height used for example:

json.render(canvas, {
  width: 200,
  height: 180,
  clef: ["treble", "bass"],  // Defaults to just "treble"
  keySignature: "C" // Defaults to "C"
});

Examples:¶ ↑

Chord¶ ↑

Without anything special, a simple array of pitch values is interpreted as notes in a single chord, rendered by default as a whole note:

["Bb", "D", "F", "A"]

Although vexflow-json will automatically choose an appropriate octave in treble clef if no octave is specified, you can override this:

["Bb/4", "D/4", "F/4", "A/5"]

Need to specify the duration? Wrap it around an object and set your notes to the “keys” hash value:

{ duration: "h", keys: ["Bb", "D", "F", "A"] }

The fully-explicit way to render this is to put this inside of another object and assign it to “notes”, allowing for other top-level options to be specified:

{
  notes: [
    { duration: "h", keys: ["Bb/4", "D/4", "F/4", "A/5"] }
  ]
}

Sequence of Notes/Chords¶ ↑

Without anything special, an array of arrays is interpreted as a sequence of notes, rendered by default as quarter notes.

[["C", "D", "E", "F", "G", "A", "B"]]

You can expand this out with multiple notes to make a sequence of chords. Here are three chords comprising a ii-V-I:

[
  ["C", "Eb", "G", "Bb"],
  ["C", "Eb", "F", "A"],
  ["Bb", "D", "F", "A"]
]

As with above, any of these string key values can override the octave (chosen intelligently by default based on position in the array).

Here’s the fully-explicit way to render this:

{
  notes: [
    { duration: "q", keys: ["C", "Eb", "G", "Bb"] },
    { duration: "q", keys: ["C", "Eb", "F", "A"] },
    { duration: "h", keys: ["Bb", "D", "F", "A"] }
  ]
}

Bars¶ ↑

Within an array of notes, you can create a new bar line by simply including the string “|”, for example:

[
  ["C", "Eb", "G", "Bb"],
  ["C", "Eb", "F", "A"],
  "|"
  ["Bb", "D", "F", "A"]
]

Or if using the more explicit object notation, just include an object { barnote: true }:

{
  notes: [
    { duration: "q", keys: ["C", "Eb", "G", "Bb"] },
    { duration: "q", keys: ["C", "Eb", "F", "A"] },
    { barnote: true },
    { duration: "h", keys: ["Bb", "D", "F", "A"] }
  ]
}

Voices¶ ↑

It’s also possible to abstract notes further and specify full voices, which imply a time signature and must be mathematically complete:

{
  voices: [
    { time: "4/4", notes: [
      { duration: "q", keys: ["E/5"] },
      { duration: "h", keys: ["D/5"] },
      { duration: "q", keys: ["C/5", "E/5", "G/5"] }
    ]},
    { time: "4/4", notes: [
      { duration: "w", keys: ["C/4"] }
    ]}
  ]
}

Beaming¶ ↑

VexFlow can beam contiguous notes for you.

TODO

Top-Level Object¶ ↑

Here are all the options on the top-level objects to explicitly plot any sequence of notes:

{
  renderer: "canvas",  // Or "svg"
  clef: ["treble", "bass"],
  height: 180,
  width: 300,   // This must be wide enough to encompass all notes or an exception will be raised!
  notes: [],   // Array of notes, rendered sequentially outside of time signature (voice)
  voices: []   // Array of voices, supercedes "notes" if specified
}

Render Options Object¶ ↑

Here are all optional keys to the second “render options” object:

{
  width: 200,
  height: 180,
  scale: 1,  // Scales entire renderer up or down (default 1 - no scaling)
  clef: "treble"  // or: ["treble", "bass"]
}

NOTE: Even though you can specify both treble and bass clef at once, for now all notes are rendered “within” treble clef and stemmed as such.