vexflow-json

vexflow-json copied to clipboard

= 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:

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.