humdrum-notation-plugin

A javascript plugin for displaying music notation on a webpage using Humdrum data

Introduction

This website documents a javascript plugin that can display music notation on any webpage, generated from Humdrum data embedded within the page. 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 as text inside the webpage. The notation is displayed as an SVG image, allowing interaction with notational elements. For example the prelude notation was made interactive by adding CSS and javascript code: try moving the mouse over a note in the music. This will highlight other notes in the score that have the same pitch class.

Try out the plugin by copy-and-pasting the following text into an HTML file to display the same musical score. In this case, rather than embedding the data within the webpage, it is being downloaded from a Github repository.

<html>
<head>
<title>Test 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>

<script>
   displayHumdrum({
      uri: "github://craigsapp/hummel-preludes/kern/prelude67-15.krn",
      source: "hummel-op67-no15",
      spacingStaff: 14,
      spacingSystem: 0,
      scale: 29,
      autoResize: true
   });
</script>
<script type="text/x-humdrum" id="hummel-op67-no15"></script>


</body>
</html>

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

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 Nontation Plugin to display chorales, along with an interactive chorale typesetter that generates Humdurm Notation Plugin code for displaying chorales on any website.

Setup

To use the Humdrum notation plugin on a webpage, copy the following lines of text into your webpage:

<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 line loads the verovio toolkit, which is used to convert a Humdrum score into an SVG image, and the second line loads the plugin itself. If you want to guarantee a stable setup, then copy these two javascript files into your website (and update periodically as needed with the latest version of verovio and/or the plugin). The last line of the setup code is a short javascript program that initializes the verovio toolkit on the webpage so that it can be used by the Humdrum notation plugin.

Displaying music

Adding a musical example on 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",
      renderer: vrvToolkit
   });
</script>

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

<script type="text/x-humdrum" id="example">
**kern	**text
*M2/4	*
*k[b-]	*
=1	=1
4Cz	Here
(12DL	is_
12D#	.
12EJ)	.
=2	=2
4DSSs	some
4G	ex-
=3	=3
4F#t	-am-
8qC#	.
4D'	-ple
=4	=4
2DD; 2FF#;	text
==	==
*-	*-
</script>

Note that colorization of the Humdrum data in the above box is random since the highlighter thinks that the example is HTML code. Here is the resulting display for the above plugin code:

Required source parameter

The source parameter is required as input to the displayHumdrum() function, and it must be set to the ID of a Humdrum content script. In this case the value is “example” since the ID of the Humdrum data script is “example”. Placement of the music notation for the example will be dependent on the location of the source element that contains the Humdrum data (the notation will be placed immediately before the source element).

Default renderer parameter

The optional renderer parameter specifies the variable name of the verovio toolkit. This parameter can be omitted if its Javascript variable name is vrvToolkit. So a minimal example using the standard header setup described above would be:

<script>displayHumdrum({source: "example"})</script>
<script type="text/x-humdrum" id="example">
**kern	**text
*M2/4	*
*k[b-]	*
=1	=1
4Cz	Here
(12DL	is_
12D#	.
12EJ)	.
=2	=2
4DSSs	some
4G	ex-
=3	=3
4F#t	-am-
8qC#	.
4D'	-ple
=4	=4
2DD; 2FF#;	text
==	==
*-	*-
</script>

Complete example

Try copy-and-pasting the following HTML content into a file and view it in a web browser:

<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
*M2/4	*
*k[b-]	*
=1	=1
4Cz	Here
(12DL	is_
12D#	.
12EJ)	.
=2	=2
4DSSs	some
4G	ex-
=3	=3
4F#t	-am-
8qC#	.
4D'	-ple
=4	=4
2DD; 2FF#;	text
==	==
*-	*-
</script>

</body>
</html>

(or click here to view it online). After opening the webpage in a browser, it should look something like:

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:

Falling melody: Rising melody:


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; otheriwse, 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:

<script>
   displayHumdrum({
      source: "url-example2",
      scale: 25,
      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: 25,
      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.

option name default value description
appendText   Append the given text line(s) at the end of the Humdrum data before it is rendered. This is typically used to add reference records for printing the title information.
autoResize false Re-typeset the music whenever the browser window is resized. See this page for examples.
filter   A filter command which will be run on the Humdrum data before it is sent to the renderer to generate graphical music notation.
header false When set to “true”, display embedded title, composer, lyricist information in musical notation.
incipit false When set to “true”, only the first system of the music notation will be displayed.
postFunction   The name of a function to run after notation has been rendered to an SVG image.
renderer vrvToolkit The name of the variable that contains the verovio toolkit, which is used to generate SVG of the music notation. If the toolkit is stored in a variable called vrvToolkit, then this parameter is optional.
source   A required ID for an element that stored the Humdrum data to generate notation from. The location of this element on the page will determine the position of the generated notation. If the data is downloaded via a URL, then this is the ID of the element where the downloaded data will be stored.
suppressSvg false Setup the container for an SVG image, but do not actually create one. This option is useful for pre-loading Humdrum data onto the page for later rendering. (see example usage)
target   An optional ID for the target container (useful for sharing a source with multiple notation displays).
uri   A predefined URI shortcut for Humdrum data located on the web. (example)
url   The URL from which to download data can be given with this parameter. By default musical data is stored extracted from the page, but this parameter allowed it to be downloaded from a separate file on the web server, or in certain cases, downloaded from other web servers such as Github. (see url documentation)
urlFallback   An alternate URL if data downloading with the url parameter fails. This allows downloading data from a mirror site if the primary one is down or inaccessible for some reason. (see url documentation)

Numeric options:

option name default min max description
pageHeight none 100 60000 Width of the music notation. By default, the humdrum plugin will set the width of the notation to match the width of the parent element that contains the notation.
pageMarginBottom 50 0 500 Height of the bottom margin.
pageMarginLeft 50 0 500 Width of the left margin.
pageMarginRight 50 0 500 Width of the right margin.
pageMarginTop 50 0 500 Height of the top margin.
scale 40 1   The scaling size of the music notation as a percentage.
spacingStaff 8 0 24 The minimum distance between staves in diatonic steps.
spacingLinear 0.25 0.0 1.0 This parameter controls the density of the notation, with 0.0 being very crowded and 1.0 being very spacious.
spacingNonLinear 0.6 0.0 1.0 This parameter controls the relative widths of notes compared to those that are twice as long. For example 0.6 means that half notes take up 60% of the space that two quarter notes would. A value of 0.0 means that all rhythms are equally spaced, and 1.0 means that note spacings are directly proportional to their durations. Small values will tend to compress the music wile large value tend to expand the musical spacing.
lyricSize ` 4.5 2.0 8.0 The height of lyric text in units of diatonic steps. (see lyrics option doc.)
lyricTopMinMargin 2.0 0.0 8.0 The minimum margin between lyrics and the music on the staff above them in units of diatonic steps (see lyrics options doc.).
lyricHyphenWidth 0.2 0.1 0.5 The minimum margin between lyrics and the music on the staff above them in units of diatonic steps (see lyrics options doc.).

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.

Additional topics

Here are a list of topics that give more examples or elaborate on the main documention on this page.

TODO