Braille Music Viewer

v0.9.1b by Toby W. Rush

Braille Music Viewer is a tool web authors can use to display self-translating excerpts of braille music on any web page. It uses the functionality from Braille Music Notator, an online utility which displays braille music using symbols that are easy to read by people who are unfamiliar with braille music notation.

Quick Start

To use Braille Music Viewer on your web page:

1. Include the following code in the <head> section of your HTML document:

An example of Braille Music Viewer, showing a C major scale.

2. Include the following in your beginning <body> tag:

(If you have another function being called in the "onload" event, simply make sure to call initializeBMViewers() from within that function.)

3. Lastly, include a musical example by placing a <canvas>...</canvas> element in your page where you want the example to appear. The parameters of the canvas element indicate the content of the example and several customizable options.

You can use the utility below to automatically build a canvas element ready to include in your page. To do so, create your musical example using Braille Music Notator, click and drag to select the area you want included in your example, and choose Copy from the Edit menu. Then place the cursor in the "Score Code" text area below and choose Paste from the Edit menu. (The pasted characters will look strange... it's fine!) Make any desired changes to the settings listed and click "Get Viewer Code"; the required code will appear in the "HTML Code" text area and the resulting viewer will be shown below. You can change settings and click "Get Viewer Code" again to update the code and example. When you are satisfied with the look and functionality of the viewer, simply copy the code from the "HTML Code" field and paste it directly into your web page's HTML.

Tips on advanced usage are included below the Viewer Code Generator.

Viewer Code Generator

Score Code:

Height:
Width:
Scrollable
Include Small Dots
Initial View:
Score Size:

HTML Code:

Advanced Usage

If you prefer to create the code manually, the available parameters for the <canvas>...</canvas> are described here:

class: (required) this parameter must be set to "bmviewer" to use the canvas as a Braille Music Viewer.
id: (optional) this parameter is not required, but may be used if your web page uses CSS or Javascript.
height: (optional) this parameter indicates the height of the viewer in pixels. If omitted, the canvas is set to the default height (usually 150).
width: (optional) this parameter indicates the width of the viewer in pixels. If omitted, the canvas is set to the default width (usually 300).
initialView: (optional) this parameter indicates whether the viewer will show translated music symbols or untranslated braille symbols when the page first loads. The user can switch between these two settings using the button in the lower right-hand corner of the viewer. Possible values for the parameter are "braille" or "translation". If omitted, translated symbols will be shown initially.
initialAlternateInterface: (optional) this parameter indicates whether the viewer's alternate interface will output translated music symbols, or untranslated braille descriptions, or braille characters when the page first loads. The alternate interface is not visible on graphic displays, but provides information which is sent to screen-reading software and refreshable braille displays. The user can switch between these two settings using Control-U or Command-U. Possible values for the parameter are "translation", "character-descriptions", or "braille". If omitted, translated symbols will be output initially.
ariaLiveID: (optional) this parameter indicates the "id" of an existing HTML element on the page that Braille Music Viewer can use for status messages related to the alternative interface. If omitted, the necessary code will be automatically added dynamically by the viewer.
scrollable: (optional) this parameter indicates whether the user will be able to scroll the score within the viewer window. A value of "true" indicates that the viewer is scrollable. If omitted, the viewer will not be scrollable.
drawSmallDots: (optional) this parameter indicates whether small dots will be shown in unused portions of braille characters in the braille view. A value of "true" indicates that the viewer will show these small dots. If omitted, small dots will not be shown.
scoreSize: (optional) this parameter indicates the magnification level of the score. The value corresponds to the height of a grid cell in pixels. If omitted, the cell size is set to a height of 60.
value (required) this parameter is a comma-delimited list of braille music character values to display in the viewer. Braille music character codes are generated by the Braille Music Notator utility and are cataloged here. If this parameter is omitted, the viewer will display a message indicating that the parameter needs to be populated.

The initialAlternateInterface and ariaLiveID parameters above affect all Braille Music Viewer instances on the page. If you wish to set these parameters, you need only include them in one of the Braille Music Viewer tags on your page. Multiple different settings of these parameters on a single page will cause unpredictable behaviour.

The code above will always load the latest version of Braille Music Viewer into your page, even if a previous version was in place when your page was authored. Every attempt will be made to ensure that Braille Music Viewer maintains backward compatibility throughout future development. If, however, you wish to force a particular version of Braille Music Viewer to be used in your page, include version information in the first and third lines of the HTML code included in the <head> section as shown below: