Copyright © 2016 David A. Randolph Copyright © 2016 David A. Randolph
AbcDE, the Didactyl Editor for abc music notation, provides a straightforward way to finger piano music. Intended primarily to collect data for researchers studying cognitive aspects of piano fingering, it also provides a convenient way for pianists to create nicely typeset music scores to reflect their personal fingering preferences.
To finger a note, first select it by clicking it. When selected, the note turns red or blue. You may then do one of the following:
The vast majority of fingering entry you do will likely be accomplished by these few actions.
If you are using a touch-capable device, a keypad should display at the bottom of your screen. If you do not see the keypad, click Preferences (
) and ensure that Keypad is set to Show. Navigation using the keypad is via the arrow buttons.
The selection will move automatically to the next note when you have entered a potentially complete fingering. The sequence of note selection proceeds from low to high (for chords and other synchronous notes) and then left to right (through time).
AbcDE renders all fingering annotations for the right hand in a serif font (Bookman). For contrast, it renders all left hand annotations in a bold non-serif font (Helvetica-Bold). This typesetting convention is adopted for conciseness over more traditional RH: or LH: markings. (It should also make it easier to distinguish fingering annotations from tuplet decorations, which are typically rendered in an italic serif font.)
All annotations for notes on the upper staff are rendered above this staff. All annotations for the lower staff are rendered below the lower staff.
By default, fingerings entered for notes on the upper staff are assumed to be for the right hand. Similarly, the default hand for notes on the lower staff is the left hand.
To override this behavior, type the <T> character. You will notice that the selected note now appears in blue instead of the default red and that the area around the printed score has turned black. This is to remind you that you are in toggle mode. Any fingerings you enter will be assigned to the non-default hand.
This behavior will persist until you type the <T> character again. Doing so will return you to the default hand mode.
Enter fingerings for chords from the lowest note to the highest. The chord will remain selected until each note has been annotated. To enter a partial annotation for a chord, enter <TAB> or <RIGHT ARROW>. Such partial annotations, when rendered, should be interpreted as applying the lowest notes of the chord.
AbcDE presents and outputs music as it is scored. It does not unfold repeated sections. If you want to specify different fingerings for the first and last time a particular note is played in a repeated section, take these steps:
In some situations, you may use a different finger to release a key from the one you used to strike it. AbcDE supports annotating such finger repositioning like this:
Grace note fingerings must be entered from low to high and left to right. Only single finger annotations are each element of a grace note. No alternate fingerings or re-positionings are currently allowed.
Any single-pitch, non-grace note may be assigned a sequence of fingering digits to capture how to finger an ornament. Typically, such notes will be assigned an ornamentation symbol (e.g., trill, mordent, grupetto), but abcDE does not require any such symbols to be present.
To assign an ornamented fingering to a note, do the following:
An ornamented pitch may either be fully fingered in parentheses, or any repeated finger patterns may be omitted. For example, a trilled note may be annotated equivalently as (12121212121) or (121).
Using the entry methods described above, a fingering must be entered in one continuous sequence of characters. Use of the <BACKSPACE> key (<DELETE> on Apple devices) will not remove the last character typed. Rather, this key operates on the entire fingering. For finer control over character input, use Dialog entry.
On touch-screen devices in particular, we recommend using the Zoom In (
) and Zoom Out (
) buttons in the control bar to change the size of the displayed music. Pinching or double-tapping will resize the entire window and may render the keypad inaccessible. Using and , you can resize the score from 30% to 300%.
In lieu of the "blind entry" methods described above, you may enter fingerings via a popup window. If you are working with a mouse or other pointing device, simply double-click a note to open its dialog window. You may also press the <ENTER> key to work on the currently selected note or equivalently click the button on the display keypad.
Note that you can enter fingerings for a sequence of notes in a single dialog.
You should be familar with the abcDF syntax to get the most out of dialog entry. Indeed, some aspects of fingering can only be expressed via this dialog interface. If, however, waiting for screens to refresh is making standard (blind) entry cumbersome, you may find that dialog entry is more efficient for even the simplest of annotations.
Your fingering input is saved by your browser every five seconds. This mechanism should reduce the chances that you lose any significant amount of work in the event your browser or hardware system crashes.
That said, you should save your work periodically in a format that abcDE can recognize. To do this, click the Download (
) button at the top of the screen. This should open a dialog window you can use to save a file. The file will be saved in abcD format, which is recognized by abcDE and other Didactyl utilities.
Some browsers do not support directly saving files. You can work around this limitation with the following steps:
) button in the control pane at the top of the screen.This workaround should not be necessary for any modern browser. We recommend Google Chrome for working with abcDE.
Note that all valid abcD files are also valid abc files. As such, they can be opened by any abc editor, such as the desktop application EasyABC or this online tool.
The Print (
) button is available to produce a hard copy or PDF of the engraved score.
AbcDE provides you the option of including the embedded annotations in the printed output or source (abcD) output. This is done by way of the Annotated checkbox on the main control bar. Make sure this box is checked if you want to see annotations in your output.
When printing via the Print () button, you typically will include annotations unless you want to view a clean copy of the score.
However, you should not download () with Annotated checked if you will be using AbcDE to perform further annotation work on the file in the future. At the current time, embedded annotations will confuse AbcDE's output.
(Raw fingering data are included in the abcD output separate from actual annotations, which are interleaved within the abc code. You can inspect the output via the View () button.)
AbcDE can open piano scores encoded in abcD (.abcd), abc (.abc or .txt), and MusicXML (.xml or .mxl) formats.
To annotate a new file that resides on your local file system, click Choose file. AbcDE can open any valid piano score encoded in the abc notation format.
To annotate abc that resides on the Web, click From the Web (
) and enter the appropriate URL. Book 1 of the "Open" Well Tempered Clavier are available at http://nlp.cs.uic.edu/didactyl/abcde/abc. But any URL pointing to piano music encoded in abc format (with two staves) may be opened.
Note: If your web content resides in a different Internet domain from where you are running abcDE, the other domain will need to be configured to support cross-origin resource sharing (CORS).
If you are unable to open a file you can otherwise browse to, you can save the file locally and click Choose file to load it into abcDE.
You may not be able to see the Download () button on the left of the control bar at the top of the screen. This is a known problem in Chrome and Safari for iOS.
In Chrome, it may be covered by an translucent Play button (like 
) for Adobe's Flash Player. (AbcDE uses Flash to perform file downloads.) To perform a download in this circumstance, you first need to run Flash by clicking . Then click to download as normal.
You will need to run Flash manually like this every time you launch abcDE, or you may avoid this inconvenience going forward by following these configuration instructions from Adobe to allow Flash always to run.
The button may also be missing altogether. This is because you do not have the Adobe Flash Player plugin enabled. Adobe also explains how to fix this in their procedure.
Adobe Flash is not supported on Apple's iOS (for iPhone and iPad). Thus, the button is not available. You must use two-step saving in Safari on iOS.
AbcDE is deployed as a JavaScript library, which can be easily leveraged within an HTML document to provide a customized editor.
The following HTML provides an abcDE editor with all features enabled and no constraints placed on user preferences.
<html>
<head profile="http://www.w3.org/2005/10/profile">
<link rel="stylesheet" type="text/css" href="http://nlp.cs.uic.edu/didactyl/abcde/css/abcDE.css">
<script src="http://nlp.cs.uic.edu/didactyl/abcde/lib/abcDE_full_min.js" type="text/javascript"></script>
</head>
<body>
<div id="abcde"></div>
<script type="text/javascript">
window.onload = function() {
AbcDE.render({
file_input:true,
url_input:true,
preset_select:true
});
}
</body>
</html>
A call like the following to AbcDE.render() would be suitable for a controlled experiment where users must provide complete fingering data for a specific piece:
AbcDE.render({
preset:'first',
output:'append',
validate:'complete',
url:'http://nlp.cs.uic.edu/didactyl/s1/p1.abcd'
});
You may also initialize the editor to specific abc (or abcd) content by including a TEXTAREA element with ID "abc_source" above the "abcde" DIV tag, like so:
<body>
<textarea id="abc_source"></textarea>
<div id="abcde"></div>
<script type="text/javascript">
window.onload = function() {
AbcDE.render({
file_input:true,
url_input:true,
preset_select:true
});
}
</body>
Renders an abc Didactyl Editor within the DIV element with ID "abcde" on the page.
Assumes such a DIV exists on the page.
Accepts a hash of arguments to determine the specific behaviors of the editor, as specified below.
Determine when previously entered work saved by the browser should be restored. If ask is specified, prompt user to learn if data should be restored.
If not specified, defer to user preference.
(If integrating with Qualtrics, set to always both to ensure that data is retained and to avoid multiple prompts from being issued. Qualtrics appears to be doing some reloading of content under the covers.)
Allow user to select a file from the local file system to edit. Defaults to false.
Include the Transcriber and Authority names in the abcD content returned through the JavaScript API. By default, such information is suppressed.
Control how fingering data entered by the user is recorded in any saved or viewed abcD content. A new fingering block may be appended to the abcD block, or it may replace the fingering block used to initiate the session.
If not specified, defer to user preference.
Parse any input abcD content and load either the first fingering sequence specified or the last sequence. If not specified, defer to user preference on the matter.
Allow the user to browse different fingering sequences specified in an abcD input file. Defaults to false.
Initialize the editor with the abc content provided at the specified URL.
Allow the user to load abc content from a URL to edit. Defaults to false.
Control how fingering input is validated. A complete validation requires that a fingering be provided for each note (pitch) in the input abc. An automatic validation first applies heuristics in an attempt to infer a complete fingering.
If not specified, no validation is performed.
Returns the "Authority" responsible for the entered fingering. Returns the empty string unless include_pii is set to true.
Returns user's entered comments about entered fingering data.
Returns the fingering data entered by the user as a string.
Returns the complete abcD file, including the user's fingering data.
Returns the "Transcriber" responsible for the entered fingering. Returns the empty string unless include_pii is set to true.
Returns the fingering data as a string if and only if the requested validation is successful. Alerts user to the validation problem and returns an empty string if the validation fails.
Returns the complete abcD file, including the user's fingering data, if and only if the requested validation is successful. Alerts user to the validation problem and returns an empty string if the validation fails.
Returns the ID of the X (tune identifier) field from the input abc string. Convenient for distinguishing exercises posed in Qualtrics.
AbcDE would not be possible without the excellent abc2svg JavaScript library by Jef Moine.
We are also indebted to the following open-source content that made our lives easier:
Online documentation is authored in Markdown using the very handy Mou editor.
The Didactyl project has been partially funded by a Provost's Award for Graduate Research from the University of Illinois at Chicago.