Introduction

The Humdrum Notation Plugin creates music notation for web pages from Humdrum digital scores, either embedded within the same page or from an external source. Here is an example use of the plugin to display J.N. Hummel’s prelude in D-flat major, op. 67/15:

The above music notation was created dynamically inside your web browser as the page was loaded, using this Humdrum score stored in a plugin wrapper inside the webpage. The notation is displayed as an SVG image, allowing interaction with notational elements: trying moving the mouse over a note and see what happens. (Here is the javascript code for the interaction). In addition to embedding the musical data within the webpage, the plugin can also download scores from external sources, such as this example of the same score downloaded from Github:

<script>
   displayHumdrum({
      uri: "github://craigsapp/hummel-preludes/kern/prelude67-15.krn",
      source: "hummel-op67-no15",
      scale: 33,
      postFunction: highlightPitchClasses

   });
</script>

<script type="text/x-humdrum" id="hummel-op67-no15"></script>

Different views of the score can be created on a webpage using the same data. Here is an example that extracts the first three measures of the prelude and transposes it to C major:

<script>
   displayHumdrum({
      source: "hummel-prelude-op67n15",
      target: "hummel-extract",
      scale: 35,
      postFunction: highlightPitchClasses,
      filter: "myank -m 1-3 | transpose -k c"
   });
</script>

<script type="text/x-humdrum" id="hummel-extract"></script>

This example applies the filter myank -m 1-3 | transpose -k c to the full score, generating a transposed excerpt. See the Filter section of this documentation for more information, or the filter documentation for Verovio Humdrum Viewer, which is an online interactive music editor where you can prepare scores for use with the Humdrum Notation Plugin.

Feature requests and bug-reports can be submitted to the issues page of the humdrum-plugin repository on Github. See also this J.S. Bach Chorales website which uses the Humdrum Notation Plugin to display chorales, along with an interactive chorale typesetter that generates Humdrum Notation Plugin code for displaying chorales on any website.

Embedding digital scores on webpage

Setup

To use the Humdrum Notation Plugin on a webpage, copy the following line somewhere into your webpage:

<script src="https://plugin.humdrum.org/scripts/humdrum-notation-plugin-worker.js"></script>

If you are displaying a webpage from a local file on your computer without using a webserver, you will instead need to use these setup lines:

<script src="https://verovio-script.humdrum.org/scripts/verovio-toolkit.js"></script>
<script src="https://plugin.humdrum.org/scripts/humdrum-notation-plugin.js"></script>
<script>var vrvToolkit = new verovio.toolkit()</script>

The first case is best for online use, particularly when lots of music notation examples are given on the same page. The second case can also be used for online situations but performs best when there are few examples on a page.

Notation rendering is handled by Vervio. For the single-line setup shown above, the verovio toolkit is loaded automatically by the Humdrum Notation Plugin, while in the second case it is loaded independetly (on the first line of the three-line setup method), and then the toolkit is initialized within the webpage with the last line.

Displaying music

Adding a musical example onto a webpage consists of two components: (1) a javascript function call to displayHumdrum() with a list of display options, such as:

<script>
   displayHumdrum({source: "example"});
</script>

and (2) a corresponding Humdrum data script on the page, such as:

<script type="text/x-humdrum" id="example">
**kern	**text
*clefG2	*
*M4/4	*
=1	=1
4c	Twin-
4c	-kle,
4g	twin-
4g	-kle,
=2	=2
4a	lit-
4a	-tle
2g	star.
=3	=3
4f	How
4f	I
4e	won-
4e	-der
=4	=4
4d	what
4d	you
2c	are!
==	==
*-	*-
</script>

The rendered notation will be placed immediately above the Humdrum script in the file, so the call to displayHumdrum() and the Humdrum script do not need to be adjacent to each other. Here is the resulting display for the above plugin code:

Required source parameter

The displayHumdrum() function is given a list of options to control generation of the notation. The source parameter is the only required parameter, and it must be set to the ID of a Humdrum content script. Note that each musical example must have a different ID so that the Humdrum Notation Plugin can tell them apart.

You can view a list of the plugin options further below, or refer to the same list on the options page. Here is an example of displaying the notation at a smaller size using the scale parameter:

<script>
   var options = {
      source: "example",
      target: "example-small",
      scale: 20
   };
   displayHumdrum(options);
</script>

<script type="text/x-humdrum" id="example-small"></script>

In this case the digital score from the previous example is also being recycled using the source parameter as the ID of the original data, and the target parameter is the ID of the Humdrum script element into which the source data will be duplicated.

Complete webpage example

Try copy-and-pasting the following HTML content into a file and view it in a web browser (typically by double-clicking on the newly created file):

<html>
<head>
<title>An example</title>
<script src="https://verovio-script.humdrum.org/scripts/verovio-toolkit.js"></script>
<script src="https://plugin.humdrum.org/scripts/humdrum-notation-plugin.js"></script>
<script>var vrvToolkit = new verovio.toolkit()</script>
</head>
<body>
<p>A musical example:</p>

<script>displayHumdrum({source: "example"})</script>
<script type="text/x-humdrum" id="example">
**kern	**text
*clefG2	*
*M4/4	*
=1	=1
4c	Twin-
4c	-kle,
4g	twin-
4g	-kle,
=2	=2
4a	lit-
4a	-tle
2g	star.
=3	=3
4f	How
4f	I
4e	won-
4e	-der
=4	=4
4d	what
4d	you
2c	are!
==	==
*-	*-
</script>

</body>
</html>

Multiple examples

More than one musical example can be placed on a page by giving a unique ID name to each Humdrum data script:

Falling melody:
<script>displayHumdrum({source: "example1"})</script>
<script type="text/x-humdrum" id="example1">
**kern
*M4/4
=1-
4g
8fL
8eJ
4d
4c
=
*-
</script>

Rising melody:
<script>displayHumdrum({source: "example2"})</script>
<script type="text/x-humdrum" id="example2">
**kern
*M4/4
=1-
4c
8dL
8eJ
4f
4g
=
*-
</script>

The above HTML code produces the following two musical examples:

Note that the javascript scripts can be merged and/or placed independently from the Humdrum scripts that contain the digital scores:

Falling melody:

<script type="text/x-humdrum" id="example1">
**kern
*M4/4
=1-
4g
8fL
8eJ
4d
4c
=
*-
</script>

Rising melody:
<script type="text/x-humdrum" id="example2">
**kern
*M4/4
=1-
4c
8dL
8eJ
4f
4g
=
*-
</script>


<script>
   displayHumdrum({source: "example1"});
   displayHumdrum({source: "example2"});
</script>

And here is a variation of the above example where all notation examples will automatically be identified and rendered with a single javascript script (provided they all use the same options set):

<script>
   var figures = document.querySelectorAll("script[type='text/x-humdrum']");
   figures.forEach((figure) => { displayHumdrum({"source": figure.id })});
</script>

URL content

Humdrum data can be downloaded from the server that hosts the webpage or from another website that disables the same-origin policy (allowing direct web browser access to a server that is not directly hosting the webpage). Here is an example of downloading a Humdrum score from the same server as the webpage. This is done by adding a url parameter pointing to the online data file as input to the displayHumdrum() function:

<script>
   displayHumdrum({
      source: "url-example1",
      scale: 32,
      header: true,
      url: "sonata06-3a.txt"
   });
</script>

<script type="text/x-humdrum" id="url-example1"></script>

Notice that the Humdrum script element is empty since it will be filled in later with the downloaded Humdrum data. Do not add any content to the Humdrum script when using the url parameter; otherwise, the URL content download will be suppressed. The Humdrum script’s location on the page will control the display location of the final notation, and any initial contents of the data script will be ignored if a url parameter is given to the displayHumdrum() function. In this case the URL is relative to the current page, so the full URL address of the downloaded data is https://plugin.humdrum.org/sonata06-3a.txt. Also notice that the parameter header is set to true. This causes title and composer information to be added above the first system of music.

Here is an example of downloading data for the first variation of the same sonata movement using a URL pointing to a file on Github from the Mozart piano sonata repository (also available on VHV):

<script>
   displayHumdrum({
      source: "url-example2",
      scale: 32,
      url: "https://raw.githubusercontent.com/craigsapp/mozart-piano-sonatas/master/kern/sonata06-3b.krn"
   });
</script>

<script type="text/x-humdrum" id="url-example2"></script>

There are also URI shortcuts for various Humdrum repositories on the web. Here is the same score as above, but downloaded with the github:// URI to simplify the address to the data:

<script>
   displayHumdrum({
      source: "uri-example",
      scale: 32,
      uri: "github://craigsapp/mozart-piano-sonatas/kern/sonata06-3b.krn"
   });
</script>

<script type="text/x-humdrum" id="uri-example"></script>

The URI

github://craigsapp/mozart-piano-sonatas/kern/sonata06-3b.krn

will be mapped internally by the Humdrum Notation Plugin into the URL:

https://raw.githubusercontent.com/craigsapp/mozart-piano-sonatas/master/kern/sonata06-3b.krn

Options

Below is a list of options that can be given to displayHumdrum(). You can also view this list on the Options page, which provides links to additional documentation and examples for the options.

Non-numeric options

Numeric options

Filters

Verovio Humdrum Viewer filters can be included within the Humdrum data to manipulate the final notation display. Here is an example of using the transpose tool to transpose music in C major to E-flat major:

<script>displayHumdrum({source: "transpose"})</script>
<script type="text/x-humdrum" id="transpose">
**kern
*M4/4
*k[]
*C:
=1-
8c
8d
8e
8f
8g
8a
8b
8cc
=2||
*M6/8
8b
8a
8g
8f
8e
8d
=3
2.c;
==
*-
!!!filter: transpose -k e-
!!!filter: autobeam
</script>

Notice that the Humdrum encoding is in C major, but the filter command transposes the music to E-flat major before the music notation is generated:

Another useful filtering tool given in this example is the autobeam tool, which beamed the eighth notes together by quarter-note durations based on the key signature. In this case the tools are used on separate filter lines, but they can be merged onto the same line like this:

!!!filter: transpose -k e- | autobeam

Other interesting filtering tools include myank for extracting a measure range from a longer score, and extract for extracting parts or removing lyrics from the rendered musical notation.

Filter option

One or more filter commands can be specified in the plugin input options. Here is an example that downloads Obrecht’s motet Salve crux from the Josquin Research Project score repository, and then does a dissonance analysis of the musical data, followed by extracting measures 1–18 from the full score, and then extracting only the bass part to display:

<script>
   displayHumdrum({
      source: "obrecht",
      spacingStaff: 3,
      spacingLinear: 0.27,
      spacingNonLinear: 0.5,
      scale: 31,
      url: "https://raw.githubusercontent.com/josquin-research-project/Obr/master/Obr2028-Salve_crux.krn",
      filter: "dissonant --colorize | myank -m 1-18 | extract -k 1"
   });
</script>
<script type="text/x-humdrum" id="obrecht"></script>

The digital score downloaded from the url parameter does not contain any filtering instructions, but by adding the option:

filter: "dissonant --colorize | myank -m 1-18 | extract -k 1"

the music will be processed by this filter before notation is generated:

Colored notes form a dissonance with other voices in the polyphonic texture (blue means a seventh against another note, green is a second against another note, and red means the note forms a forth with the lowest sounding note). The dissonant notes are labeled according to their function: p is a falling passing tone, g is a suspension agent (initiates a suspension, but is considered the consonant note of the suspension), and v is a descending accented passing tone. For more information, see documentation for the dissonant tool.

The filter option can also be set to an array of filters, which will be applied in the same sequence. The above pipe-lined filter can be equivalently expressed as:

filter: [
      "dissonant --colorize",
      "myank -m 1-18",
      "extract -k 1"
   ]

First the music will be analyzed by the dissonant tool, then the first 18 measures will be excerpted from the score, then the first kern spine (for the bass part) will be extracted along with its secondary analysis spines.

TODO

• Allow for shift-click in SVG image to toggle display of Humdrum text.
• Allow Humdrum text to be shown above/below/left/right of the musical example.
• Make examples interactive (typing Humdrum text will update notation).
• Implement optional paged view for longer examples.
• Implement optional MIDI playback of examples.