Humdrum wiki extension

The CCARH wiki includes a Humdrum music notation extension that allows Humdrum data embedded within a page to be rendered as graphical music notation.

Basic example

<humdrum>

• • kern

1f;

• -

</humdrum>

The above notation was created with the Humdrum tag:

  <humdrum>
  **kern
  1f;
  *-
  </humdrum>

More complicated example

This example includes lyrics, coloring of notes with RDF records, and a transposition filter (Transposing from A-flat major in the data to C major in the notation).

<humdrum scale="55"> !!!OMD: Slow

• • kern **text
• k[b-e-a-d-] *
• A-: *
• M4/4 *
• met(c) *
• *color:gold

4cc If =1 =1 (8dd-L@ Mu- 8ccJ)@ . (8b-L@ -sic_ 8a-J)@ . (8gL be_ 8a-J) . (8b-L the_ 8ccJ) . =2 =2 (8b-L food_ 8a-J) . (8gL of_ 8fJ) . 4.enN Love, 8c sing =3 =3 4f on, 4f sing 4.a- on, 8f sing =4 =4 4cc on, 4cc sing 4.ee- on, =- =-

• - *-

!!!RDF**kern: @ = marked note, color=chartreuse !!!RDF**kern: N = marked note, color=hotpink !!!filter: transpose -k c </humdrum>

which was created with the text:

  <humdrum scale="55">
  !!!OMD: Slow
  **kern	**text
  *k[b-e-a-d-]	*
  *A-:	*
  *M4/4	*
  *met(c)	*
  4cc	If
  =1	=1
  (8dd-L@	Mu-
  8ccJ)@	.
  (8b-L@	-sic_
  8a-J)@	.
  (8gL	be_
  8a-J)	.
  (8b-L	the_
  8ccJ)	.
  =2	=2
  (8b-L	food_
  8a-J)	.
  (8gL	of_
  8fJ)	.
  4.enN	Love,
  8c	sing
  =3	=3
  4f	on,
  4f	sing
  4.a-	on,
  8f	sing
  =4	=4
  4cc	on,
  4cc	sing
  4.ee-	on,
  =-	=-
  *-	*-
  !!!RDF**kern: @ = marked note, color=chartreuse
  !!!RDF**kern: N = marked note, color=hotpink
  !!!filter: transpose -k c
  </humdrum>

CSV Humdrum

The standard WikiMedia page editor does not allow inserting tab characters, so either copy-and-paste humdrum text from another editor, such as http://verovio.humdrum.org, (which can also be used to validate the Humdrum data) or encode the Humdrum data in CSV format instead of TSV:

  <humdrum scale="55">
  !!!OMD: Slow
  **kern,**text
  *k[b-e-a-d-],*
  *A-:,*
  *M4/4,*
  *met(c),*
  4cc,If
  =1,=1
  (8dd-L@,Mu-
  8ccJ)@,.
  (8b-L@,-sic_
  8a-J)@,.
  (8gL,be_
  8a-J),.
  (8b-L,the_
  8ccJ),.
  =2,=2
  (8b-L,food_
  8a-J),.
  (8gL,of_
  8fJ),.
  4.enN,"Love,"
  8c,sing
  =3,=3
  4f,"on,"
  4f,sing
  4.a-,"on,"
  8f,sing
  =4,=4
  4cc,"on,"
  4cc,sing
  4.ee-,"on,"
  =-,=-
  *-,*-
  !!!RDF**kern: @ = marked note, color=chartreuse
  !!!RDF**kern: N = marked note, color=hotpink
  !!!filter: transpose -k c
  </humdrum>
  

The TSV form of Humdrum can be converted to CSV on VHV by using the alt-u command. Verovio and the humdrum-plugin library know how to convert the CSV form of Humdrum back into the TSV form for processing.

Options

The Humdrum notation extension is implemented using the humdrum javascript plugin documented at https://plugin.humdrum.org. All of the options described in that documentation can be used as attributes for the humdrum element on a wiki page. The full list of options: https://plugin/humdrum.org/options.

Here is an example that loads the Humdrum data from an external source, and it is not stored in the webpage:

<humdrum

        url="https://raw.githubusercontent.com/craigsapp/mozart-piano-sonatas/master/kern/sonata06-3c.krn"
        scale="33"
        header="true"

></humdrum>

This musical example was created with the following text:

  <humdrum 
           url="https://raw.githubusercontent.com/craigsapp/mozart-piano-sonatas/master/kern/sonata06-3c.krn"
           scale="33"
           header="true"
  ></humdrum>

In this case, the music is downloaded from the Github repository https://github.com/craigsapp/moart-piano-sonatas, specified by the url attribute. The scale attribute sets the music notation size to 33% of the default size in verovio (the humdrum plugin uses a default of 40%), and the header tag, when set to "true", displays the title and composer information above the first system of the music.

Here is an example of downloading the same score, but only displaying measures 10 and 11 using the filter option:

<humdrum

          url="https://raw.githubusercontent.com/craigsapp/mozart-piano-sonatas/master/kern/sonata06-3c.krn"
          scale="33"
          filter="myank -m 10-11"

></humdrum>

  <humdrum 
           url="https://raw.githubusercontent.com/craigsapp/mozart-piano-sonatas/master/kern/sonata06-3c.krn"
           scale="33"
           filter="myank -m 10-11"
  ></humdrum>

Musical incipits

There is a special option called incipit that displays only the first system of music. Here is an example of incipits for each movement of the example Mozart sonata:

Movement 1: <humdrum

          url="https://raw.githubusercontent.com/craigsapp/mozart-piano-sonatas/master/kern/sonata06-1.krn"
          scale="33"
           incipit="true"

></humdrum> Movement 2: <humdrum

          url="https://raw.githubusercontent.com/craigsapp/mozart-piano-sonatas/master/kern/sonata06-2.krn"
          scale="33"
           incipit="true"

></humdrum> Movement 3: <humdrum

          url="https://raw.githubusercontent.com/craigsapp/mozart-piano-sonatas/master/kern/sonata06-3a.krn"
          scale="33"
           incipit="true"

></humdrum>

Created with this code:

  Movement 1:
  <humdrum 
             url="https://raw.githubusercontent.com/craigsapp/mozart-piano-sonatas/master/kern/sonata06-1.krn"
             scale="33"
             incipit="true"
  ></humdrum>
  Movement 2:
  <humdrum 
             url="https://raw.githubusercontent.com/craigsapp/mozart-piano-sonatas/master/kern/sonata06-2.krn"
             scale="33"
             incipit="true"
  ></humdrum>
  Movement 3:
  <humdrum 
             url="https://raw.githubusercontent.com/craigsapp/mozart-piano-sonatas/master/kern/sonata06-3a.krn"
             scale="33"
             incipit="true"
  ></humdrum>

Installation

If you have a wiki that uses MediaWiki, then here are instructions for allowing use of the <humdrum> tag to generate music notation on wiki pages:

(1) Place this line in the LocalSettings.php file that is located in the base directory of the wiki's website (wherever that is installed on your web server):

  require_once "$IP/extensions/Humdrum/Humdrum.php";

(2) Place the following contents into a file called extensions/Humdrum/Humdrum.php in relation to the base directory of your wiki website:

<?php

/*
 * humdrum-mediawiki-extension
 * Humdrum music notation extension for MediaWiki.
 *
 * Craig Stuart Sapp <craig@ccrma.stanford.edu>
 * Wed Dec 12 14:54:26 PST 2018
 * Developed for use in MediaWiki 1.24
 *
 * This <humdrum> tag extension converts Humdrum scores into SVG images using
 * the Verovio toolkit on a MediaWiki-based wiki (https://www.mediawiki.org/wiki/MediaWiki).
 * The extension loads two external javascript libraries to produce SVG images
 * directly within a user's web browser:
 *   (1) Verovio (https://www.verovio.org), using a Humdrum-aware version stored at
 *       https://verovio-script.humdrum.org.
 *   (2) humdrum-plugin (https://plugin.humdrum.org) which serves as a front-end to
 *       manage options for the Verovio toolkit.
 * Since the extension inserts javascript code onto a webpage (which in turn inserts
 * SVG images onto the page), the extension is not suitable for publically editable
 * wikis (such as Wikipedia).
 *
 * The extension will convert a <humdrum> tag such as this:
 *
 *   <humdrum scale="40">
 *   **kern
 *   *clefG2
 *   *M4/4
 *   1c;
 *   ==
 *   *-
 *   </humdrum>
 *
 * into the following HTML code inserted onto the page:
 *
 *   <script>
 *      displayHumdrum({
 *         "scale": "40"
 *      })
 *   </script>
 *   <script type="text/x-humdrum" id="example">
 *      **kern
 *      *clefG2
 *      *M4/4
 *      1c;
 *      ==
 *      *-
 *   </script>
 *
 * The scale parameter sets the size of the music.  Additional parameters
 * are listed at https://plugin.humdrum.org/options.  The first use of
 * the <humdrum> tag will insert the following initializtion code:
 *
 *   <script src="https://verovio-script.humdrum.org/scripts/verovio-toolkit.js"></script>
 *   <script src="https://plugin.humdrum.org/scripts/humdrum-plugin.js"></script>
 *   <script>var vrvToolkit = new verovio.toolkit()</script>
 *
 *
 * Programming References:
 *    https://www.mediawiki.org/wiki/Manual:Tag_extensions
 *    https://www.mediawiki.org/wiki/Parser_extension_tags
 */

// tagCounter is used to initialize the humdrum-plugin code:
$tagCounter = 0;

$wgExtensionFunctions[] = 'wfHumdrum';
$wgExtensionCredits['parserhook'][] = array(
   'name'=>'Humdrum',
   'author'=>'Craig Stuart Sapp',
   'url'=>'http://www.mediawiki.org/wiki/Extension:Humdrum',
   'description'=>'Humdrum music notation renderer',
);


function wfHumdrum() {
   new Humdrum();
}

class Humdrum {

   public static function HumdrumTagSetup(Parser &$parser) {
      global $tagCounter;
      $tagCounter = 100;
      $tagName = "humdrum";
      $callback = function($input, $argv, $parser, $frame) use ($tagName) {
         return Humdrum::hookHumdrum($input, $argv, $parser, $frame, $tagName);
      };
      $parser->setHook($tagName, $callback);
      return true;
   }

   # Construct the extension and install it as a parser hook.
   public function __construct() { 
      global $wgHooks;
      $wgHooks['ParserFirstCallInit'][] = 'Humdrum::HumdrumTagSetup';
   }

   # hookHumdrum -- The hook function. Handles <humdrum></humdrum>.
   # Receives the Humdrum content and <humdrum> parameters.
   public static function hookHumdrum($humdrumText, $argv, $parser, $frame, $tagName) {

      // prevent caching of pages using the extension
      $parser->disableCache();

      // Build the displayHumdrum parameters string from the tag parameters
      // and insert into a <script> element.
      global $tagCounter;
      $source = "";
      $optionContainer = "<script>displayHumdrum({";
      foreach ($argv as $key => $val) {
         $optionContainer .= "\t\"$key\":\t\"$val\",";
         if ($key == "source") {
            $source = $val;
         }
      }
      if ($source == "") {
         // create an automatic name for the notation example
         $randval = rand();
         $source = "humdrum-$randval";
         $optionContainer .= "\t\"source\":\t\"$source\",";
      }
      $optionContainer = preg_replace('/,$/', "", $optionContainer);
      $optionContainer .= "})</script>";

      $humdrumContainer = "<script type=\"text/x-humdrum\" id=\"$source\">\n";
      $humdrumContainer .= $humdrumText;
      $humdrumContainer .= "</script>";

      $initialization = "";
      if ($tagCounter == 100) {
         # Only include this code the first time an example is placed on the page.
         $initialization .= "<script src=\"https://verovio-script.humdrum.org/scripts/verovio-toolkit.js\"></script>";
         $initialization .= "<script src=\"https://plugin.humdrum.org/scripts/humdrum-plugin.js\"></script>";
         $initialization .= "<script>var vrvToolkit = new verovio.toolkit()</script>";
      }
      $tagCounter++;

      return array("$initialization$optionContainer$humdrumContainer", "markerType" => 'nowiki');
   }
}

?>