humdrum-notation-plugin

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

This page describes option parameters related to downloading musical scores into the webpage rather than embedding digital scores within the page.

Downloading data by URL

Both local and remote external scores can be downloaded. Here are examples for each case:

Local URL

The url parameter can be used to specify an external data source for a digital score. The following example loads the file sonata05-1.krn and then converts it into notation on the webpage.

<script>
displayHumdrum({
   source: "example-local",
   incipit: true,
   url: "sonata05-1.krn"
})
</script>
<script type="text/x-humdrum" id="example-local"></script>

The URL is relative to the webpage, so the full address is https://plugin.humdrum.org/options/url/sonata05-1.krn.

Remote URL

The above example downloads data from the same web server as this webpage. It is also possible to download data from external web servers, provided that they permit it. Here is an example of downloading the same score from a Github repository:

<script>
displayHumdrum({
   source: "example-remote",
   incipit: true,
   url: "https://raw.githubusercontent.com/craigsapp/beethoven-piano-sonatas/master/kern/sonata05-1.krn"
})
</script>
<script type="text/x-humdrum" id="example-remote"></script>

Fallback URL

The parameter urlFallback can be given to displayHumdrum() as a backup URL in case there was a problem downloading musical data using the primary url parameter. This is useful, for example, if you want to usually download the most up-to-date score in an online repository, but the access is temporarily down or you are currently offline (with a local installation of the Humdrum notation plugin).

Here is an example where the url parameter is set to a non-existent location, and the urlFallback parameter is set to a copy of the intended score saved statically on the same web server as this webpage:

HTML code for the example:

<script>
displayHumdrum({
   source: "backup",
   incipit: true,
   url: "https://some-random.comp.uter/data/sonata05-1.krn",
   urlFallback: "sonata05-1.krn"
})
</script>

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

The urlFallback parameter can be either a relative path to a file on the same web server, or an absolute path to a file on another web server.

Fallback data

If the url parameter fails to load data, and the urlFallback parameter also fails to load data, then the Humdrum notation plugin will use any data embedded within the Humdrum text script on the webpage.

HTML code for the example:

<script>
displayHumdrum({
   source: "embed",
   url: "https://some-random.comp.uter/data/some-random-file.krn",
   urlFallback: "some-random-file.krn"
})
</script>

<script type="text/x-humdrum" id="embed">
**kern
*clefG2
*M4/4
!LO:TX:b:B:t=Score not found!:color=red
1r;
=-
*-
</script>

The url parameter (“https://some-random.comp.uter/data/some-random-file.krn”) does not load successfully. Then the urlFallback parameter is used to check for “some-random-file.krn” on the local server, but that also fails. So the Humdrum notation plugin displays the existing digital score found in the Humdrum text script.

Error score

The emptyScore option can point to a digital score to display when the intended score cannot be downloaded via the url or urlFallback parameters, and there is otherwise no contents in the Humdrum text script. The first two examples try to download invalid files, and the third has an empty Humdrum text script. All three of them use the score stored in the element having an ID empty-score.

<script>
displayHumdrum({
   source: "error-example",
   incipit: true,
   url: "inaccessible.krn",
   urlFallback: "https://unknown.comp.uter/inaccessible.krn",
   errorScore: "empty-score"
})
</script>
<script type="text/x-humdrum" id="error-example"></script>

<script>
displayHumdrum({
   source: "error-example2",
   incipit: true,
   url: "another-inaccessible-file.krn",
   urlFallback: "https://unknown.comp.uter/inaccessible-file2.krn",
   errorScore: "empty-score"
})
</script>
<script type="text/x-humdrum" id="error-example2"></script>

<script>
displayHumdrum({
   source: "error-example3",
   incipit: true,
   errorScore: "empty-score"
})
</script>
<script type="text/x-humdrum" id="error-example3"></script>


<script type="text/x-humdrum" id="empty-score">
**kern
*clefG2
*M4/4
!LO:TX:b:B:t=Score not found!:color=red
1r;
=-
*-
</script>

Default empty score

If you always want to show an error score if the intended score is not successfully downloaded, but you do not want to add the errorScore parameter to every call of displayHumdrum(), then you can call setErrorScore() with the ID of a Humdrum text script containing the error score. Here is a similar example to the previous set, but now there is an automatically placed error score when the Humdrum text script is empty.

<script> setErrorScore("empty-score-2") </script>


<script>
displayHumdrum({
   source: "error-example-4",
   incipit: true,
   url: "inaccessible.krn",
   urlFallback: "https://unknown.comp.uter/inaccessible.krn"
})
</script>
<script type="text/x-humdrum" id="error-example-4"></script>

<script>
displayHumdrum({
   source: "error-example-5",
   incipit: true,
   url: "another-inaccessible-file.krn",
   urlFallback: "https://unknown.comp.uter/inaccessible-file2.krn"
})
</script>
<script type="text/x-humdrum" id="error-example-5"></script>

<script>
displayHumdrum({
   source: "error-example-6",
   incipit: true
})
</script>
<script type="text/x-humdrum" id="error-example-6"></script>


<script type="text/x-humdrum" id="empty-score-2">
**kern
*clefG2
*M4/4
!LO:TX:b:B:t=Score not found!:color=hotpink
1r;
=-
*-
!!!hnp-option:scale:80.0
</script>