abcjs

javascript for rendering abc music notation

abcjs Home page

API Documentation

This library makes it easy to incorporate sheet music into your websites. You can also turn visible ABC text into sheet music on websites that you don't own using a greasemonkey script, or change your own website that contains ABC text with no other changes than the addition of this javascript file.

NOTE: We are changing the release license to the MIT License, effective immediately. Let us know if this causes any problems, but we're hoping that it solves some. Our goal is that you can use this library in a convenient way, as long as you give us credit for it.

License: The MIT License (MIT)

For a demo of what this library can do, see the following:

The abcjs libraries come in three basic flavors:

Library Name	Description	Demo
abcjs basic	Call the library from javascript, passing the abc string to it.	Basic
abcjs editor	Transforms a textarea into an abc editor with score sheet and audio.	Editor
abcjs plugin	Adds onto an existing webpage, rendering all abc it finds.	Plugin

Which flavor should you use?

If you are writing significant JavaScript on your site, and you are generating the music yourself, then you probably want to use abcjs-basic. This gives you the most control over the generation.

If you are allowing the user to enter music using ABC notation, whether a whole tune or a fragment, then you probably want to use abcjs-editor. This is just like the basic version, except that it adds the ability for the music generator to watch a textarea and output what the user puts there.

If you are using Rails, you can just use this gem: abcjs-rails This is the same code, but it has been packaged for you to use with the asset pipeline.

If you already have ABC notation on your page and don't want to modify the page more than you have to, then you can use abcjs-plugin, which will render all ABC that it finds on the page on page load, simply by including one line: the line to include the script. Another use of this is if you have a comment section on a blog, then you can allow users to post ABC tunes and they will appear as sheet music automatically.

If you are looking at someone else's website and see ABC on the page and want to see what it looks like in standard notation, you can install the greasemonkey script in FireFox or Chrome and it will render the ABC for you.

Downloads:

Release Notes

Here are the latest versions. You can just download one of these:

• Basic

• Editor

• Plugin

• Greasemonkey script

And here are the latest versions packaged without the standard libraries. To use these, you need to include those libraries yourself:

• Basic without Raphael

• Editor without Raphael

• Plugin without JQuery

• Plugin without JQuery or Raphael

NOTE: Do NOT link to these files directly! Upload them to your own server! Here's why.

Partial list of some websites using abcjs:

Site	Notes
http://www.drawthedots.com	(editor)
http://www.tradzone.net/forum	(plugin) (sample page)
http://abcnotation.com/forums	(plugin) (sample page)
http://www.pmwiki.org/wiki/Cookbook/AbcTunebook	(plugin and editor) (this is an addon for pmwiki for creating tune books)
http://www.tunepal.org	(basic)
http://people.opera.com/howcome/2010/video/norway/	(Demoed during a keynote at Google I/O 2010 by Håkon Wium Lie, CTO of Opera)
http://www.bestmusicteacher.com/	> left menu > music theory (Educational)
http://www.eastofcleveland.com/flashcards/notereading.php	(Educational)
https://sightreadingfactory.com	(Educational)
http://tunearch.org

Let us know if you want to be listed!

Some notes:

• ABC 1.6 is pretty much implemented.
• Many of the new features of ABC 2.1 are being implemented now.
• Midi playback is at a very early stage and does not yet feature ornamentation, dynamics, chords or multi voice.
• Midi playback will not work in Internet Explorer.

API Changes for Version 1.11

"Bouncing Ball" cursor:

ABCJS.startAnimation(paper, tune, options)
	paper: the output div that the music is in.
	tune: the tune object returned by renderAbc.
	options: a hash containing the following:
		hideFinishedMeasures: true or false [ false is the default ]
		showCursor: true or false [ false is the default ]
		bpm: number of beats per minute [ the default is whatever is in the Q: field ]

renderABC() now returns the object that was created by the process. This allows further processing.

highlight() and unhighlight() now can be passed an optional class name and color.

Descriptive classes to all SVG elements: If you include { add_classes: true } in the rendering params, then a set of classes are applied to each SVG element so they can be manipulated with css.

API Changes for Version 1.3

There is a new public entry point that is designed for those who want some information about what is in a tunebook before processing it.

// Tunebook is the contents of the text file containing one or more
// ABC-formatted tunes, plus global header info, and inter-tune text.
var book = new ABCJS.TuneBook(tunebook);

var fileHeader = book.header;
var numberOfTunes = book.tunes.length;

for (var i = 0; i < numberOfTunes; i++) {
    var title = book.tunes[i].title;
    var tuneAndHeader = book.tunes[i].abc;
    var justTheTune = book.tunes[i].pure;
    var id = book.tunes[i].id;
}

var tune = book.getTuneById(id);
tune = book.getTuneByTitle(title);

The variable book contains:

Member	Description
book.header	This is all of the text that appears before the first tune starts in the file.
book.tunes.length	This is how many tunes are in that file.
book.tunes[i].title	This is the first title found for the particular tune. White space is trimmed from both the beginning and end.
book.tunes[i].abc	This is the particular tune with the global header information added to it. This is what should be passed to the parser in most cases.
book.tunes[i].pure	This is the particular tune without the header.
book.tunes[i].id	This is the id (that is, the text on the X: line). White space is trimmed from both the beginning and end.
book.getTuneById	This will find the FIRST tune in the tune book with the id.
book.getTuneByTitle	This will find the FIRST tune in the tune book with the title.

API Changes for Version 1.1

IMPORTANT: Version 1.1 has removed all globals and any side effects of ABCJS except for this single global:

window.ABCJS

This means that you will have to modify your pages to use the new syntax. All of the old entry points are still available with a slightly different name. Here is a list of all recommended entry points:

New name	Old name
ABCJS.numberOfTunes	numberOfTunes
ABCJS.renderAbc	renderABC
ABCJS.renderMidi	renderMidi
ABCJS.Editor	ABCEditor
ABCJS.plugin	abc_plugin