Scribe

Responsive music notation for the web.

Scribe takes a sequence of events – notes, chords, meter changes and so on – and interprets and renders notation in HTML and CSS.

Documentation and examples at stephen.band/scribe.

`<scribe-music>`

To use the <scribe-music> custom element, import the CSS and JS from the CDN:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/stephband/scribe@0.4.2/build/scribe-music/element.css" />
<script type="module" src="https://cdn.jsdelivr.net/gh/stephband/scribe@0.4.2/build/scribe-music/element.js"></script>

The <scribe-music> element is now registered. It renders music notation from JSON data imported via its src attribute:

<scribe-music src="/path/to/json"></scribe-music>

Alternatively the src attribute may reference JSON already in the document:

<!-- Head -->
<script type="application/json" id="so-what">{
    "events": [...]
}</script>

<!-- Body -->
<scribe-music src="#so-what" swing></scribe-music>

Scribe data

Scribe consumes <a href="https://github.com/soundio/music-json/">Sequence JSON</a>. Here's an example of the horn part for <a href="https://www.youtube.com/watch?v=ylXk1LBvIqU&list=RDylXk1LBvIqU">So What</a> as a sequence document:

{
    "name": "So What",
    "author": { "name": "Miles Davis" },
    "events": [
        [0,  "key", "C"],
        [0,  "meter", 4, 1],
        [0,  "sequence", 1, 0, 32],
        [32, "sequence", 1, 0, 32],
        [64, "sequence", 1, 0, 32, "transpose", 1],
        [96, "sequence", 1, 0, 32]
    ],

    "sequences": [{
        "id": 1,
        "name": "Section",
        "events": [
            [0,  "sequence", 2, 0, 8],
            [8,  "sequence", 2, 0, 8],
            [16, "sequence", 2, 0, 8],
            [24, "sequence", 2, 0, 8]
        ]
    }, {
        "id": 2,
        "name": "Horns",
        "events": [
            [0, "chord", "D", "-7", 32],
            [2,    "note", "B4", 0.1, 1.6],
            [2,    "note", "G4", 0.1, 1.6],
            [2,    "note", "D4", 0.1, 1.6],
            [2,    "note", "A3", 0.1, 1.6],
            [3.6,  "note", "A4", 0.1, 0.4],
            [3.6,  "note", "F4", 0.1, 0.4],
            [3.6,  "note", "C4", 0.1, 0.4],
            [3.6,  "note", "G3", 0.1, 0.4]
        ]
    }]
}

The main sequence plays the "Section" sequence four times, 32 beats (or 8 bars) per section, with the third section transposed up 1 semitone. The "Section" sequence plays the "Horns" phrase four times, 8 beats (or 2 bars) per phrase. That renders as:

Scribe detects when bars are repeated and automatically inserts bar repeat symbols.

The only property actually required by a sequence is an "events" array.

Events

Events are described in the "events" array. Each event is an array that starts with [beat, type, ...] and each type carries some data. Scribe supports these event types:

Unrecognised event types are ignored.

Sequences

Sequences are described in the "sequences" array, and "sequence" events refer to them by id. Child sequences have the same structure as parent sequences. Events may refer to sequences in the same sequence or to any sequence found in their parent chain. Sequences are arbitrarily nestable.

Scribe considers the top-level sequence to describe musical structure by convention. In the example above the top-level sequence contains the key, meter and musical sections as "sequence" events. Scribe renders double bar lines at the end of each of these.

`type="json"`

Both an attribute and a property. Mimetype or type of data to fetch from src or to parse from text content. Scribe supports 3 types of data:

"application/json", or just "json"

"sequence"

`src="url"`

Both an attribute and a property. The URL of a JSON file, or a hash reference to a script element in the document.

`clef="treble"`

Both an attribute and a property. The name of the clef, one of "treble", "treble-up", "treble-down", "alto", "bass", "piano", "drum" or "percussion". Defaults to "treble".

<scribe-music clef="bass">...</scribe-music>

let scribe = document.body.querySelector('scribe-music');
console.log(scribe.clef) // "bass";

`layout="compact"`

The layout attribute can have one of the values "compact" (the default), "regular" or "spaced". Layout does nothing JavaScript-y, it simply sets the flex-basis and min/max-width of the bars for more regular spacing inside their container.

`key="C"`

Both an attribute and a property. Gets and sets the key signature of the stave. Accepts any chromatic note name, spelled with unicode sharps ♯ and flats ♭ or with hash # and small case b. This is the name of the tonic of a major scale. Defaults to "C".

<scribe-music key="F#">...</scribe-music>

let scribe = document.body.querySelector('scribe-music');
scribe.key = "B♭";

There is no provision for choosing a 'minor' key. Declare its relative major.

The key is the key signature pre-transposition. If transpose is something other than 0, the key signature is also transposed.

`meter="4/4"`

Both an attribute and a property. The meter, expressed as a standard time signature. This setting is overridden by any meter event found in the data at beat 0. If this attribute is omitted (or the property not set in JS), no time signature is displayed (unless the data contains a "meter" event at beat 0). Defaults to "4/4".

<scribe-music meter="3/4">...</scribe-music>

let scribe = document.body.querySelector('scribe-music');
scribe.meter = "3/4";

`transpose="0"`

Both an attribute and a property. Sets scribe to render notation transposed by transpose semitones. Transposition is applied to key signature, notes and chords before render, and not to the underlying data.

<scribe-music transpose="2">...</scribe-music>

let scribe = document.body.querySelector('scribe-music');
scribe.transpose = 2;

`swing`

A boolean attribute. Displays swung and triplet 8ths as straight 8ths.

`.data`

Set a .data object, structured as a <a href="https://github.com/soundio/music-json/#sequence">Sequence</a>.

let scribe = document.body.querySelector('scribe-music');
scribe.data = {
    name:      'My Song',
    events:    [...]
};

Get Scribe's internal data object, whose structure is a <a href="https://github.com/soundio/music-json/#sequence">Sequence</a>. To export Sequence JSON, simply stringify scribe.data:

let scribe = document.body.querySelector('scribe-music');
let mySong = JSON.stringify(scribe.data);

Develop

Clone

To install Scribe locally clone the repo and update the submodules:

git clone https://github.com/stephband/scribe.git scribe
cd scribe
git submodule update --init

To check things are working serve this directory and navigate to http://localhost/scribe-music/index.html (obviously localhost needs to be replaced depending on what you are using as a server).

Build

make modules

Research

There is a discussion about using CSS grid layout for rendering music notation in the blog post <a href="https://cruncher.ch/blog/printing-music-with-css-grid/">Printing Music with CSS Grid</a>. Scribe's internals have changed since that post was written but the principal layout technique remains the same.

Changes

0.4.x – The Lead Sheet

Version 0.4 is capable of rendering a reasonable lead sheet. Features:

Supports multiple concurrent notes
Supports multiple parts per stave
Supports sequence events, top-level sequence events denote musical structure
Supports arbitrary nesting of sequences and transforms
Tuplet detection up to nonuplets
Automatic bar repeat symbols for repeated identical bars
New probablistic key-to-spelling detector
Adds config object
Setting settings.swingAsStraight8ths makes 8th tuplets display as stra

Scribe

Install / Use

README

Scribe

`<scribe-music>`

Scribe data

Events

Sequences

`type="json"`

`src="url"`

`clef="treble"`

`layout="compact"`

`key="C"`

`meter="4/4"`

`transpose="0"`

`swing`

`.data`

Develop

Clone

Build

Research

Changes

0.4.x – The Lead Sheet