View source for Humdrum wiki extension


<html>
<style>
pre { tab-size: 15; }
</style>
</html>

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:


   &lt;humdrum&gt;
   **kern
   1f;
   *-
   &lt;/humdrum&gt;


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

   &lt;humdrum scale="55"&gt;
   !!!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
   &lt;/humdrum&gt;

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


   &lt;humdrum scale="55"&gt;
   !!!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
   &lt;/humdrum&gt;
   

The TSV form of Humdrum can be converted to CSV on [http://verovio.humdrum.org VHV] by using the [http://doc.verovio.humdrum.org/commands/alt-u 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:


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

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.

== Installation ==

If you have a wiki that uses [https://www.mediawiki.org MediaWiki], then here are instructions for allowing use of the &lt;humdrum&gt; 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 this file into extensions/Humdrum/Humdrum.php in relation to the base directory of your wiki website:


<syntaxhighlight lang="php">
&lt;?php

/*
 * humdrum-mediawiki-extension
 * Humdrum music notation extension for MediaWiki.
 *
 * Craig Stuart Sapp &lt;craig@ccrma.stanford.edu&gt;
 * Wed Dec 12 14:54:26 PST 2018
 * Developed for use in MediaWiki 1.24
 *
 * This &lt;humdrum&gt; 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 &lt;humdrum&gt; tag such as this:
 *
 *   &lt;humdrum scale="40"&gt;
 *   **kern
 *   *clefG2
 *   *M4/4
 *   1c;
 *   ==
 *   *-
 *   &lt;/humdrum&gt;
 *
 * into the following HTML code inserted onto the page:
 *
 *   &lt;script&gt;
 *      displayHumdrum({
 *         "scale": "40"
 *      })
 *   &lt;/script&gt;
 *   &lt;script type="text/x-humdrum" id="example"&gt;
 *      **kern
 *      *clefG2
 *      *M4/4
 *      1c;
 *      ==
 *      *-
 *   &lt;/script&gt;
 *
 * The scale parameter sets the size of the music.  Additional parameters
 * are listed at https://plugin.humdrum.org/options.  The first use of
 * the &lt;humdrum&gt; tag will insert the following initializtion code:
 *
 *   &lt;script src="https://verovio-script.humdrum.org/scripts/verovio-toolkit.js"&gt;&lt;/script&gt;
 *   &lt;script src="https://plugin.humdrum.org/scripts/humdrum-plugin.js"&gt;&lt;/script&gt;
 *   &lt;script&gt;var vrvToolkit = new verovio.toolkit()&lt;/script&gt;
 *
 *
 * 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'=&gt;'Humdrum',
   'author'=&gt;'Craig Stuart Sapp',
   'url'=&gt;'http://www.mediawiki.org/wiki/Extension:Humdrum',
   'description'=&gt;'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-&gt;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 &lt;humdrum&gt;&lt;/humdrum&gt;.
   # Receives the Humdrum content and &lt;humdrum&gt; parameters.
   public static function hookHumdrum($humdrumText, $argv, $parser, $frame, $tagName) {

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

      // Build the displayHumdrum parameters string from the tag parameters
      // and insert into a &lt;script&gt; element.
      global $tagCounter;
      $source = "";
      $optionContainer = "&lt;script&gt;displayHumdrum({";
      foreach ($argv as $key =&gt; $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 .= "})&lt;/script&gt;";

      $humdrumContainer = "&lt;script type=\"text/x-humdrum\" id=\"$source\"&gt;\n";
      $humdrumContainer .= $humdrumText;
      $humdrumContainer .= "&lt;/script&gt;";

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

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

?&gt;
</syntaxhighlight>