abcjs

abcjs

javascript for rendering abc music notation

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 one javascript file. You can also generate MIDI files or play them directly in your browser.

Browser/device support

• The visual part of this library is supported from IE9 and newer, Safari 5.1 and newer, and all modern browsers.

• The audio part of this library is much more limited: it doesn't work in IE, it only works in Safari 9 and 10, it does NOT work in Edge, but does work fine in all other modern browsers. Note that it takes computer resources to play the sound, so a sufficiently fast computer is needed. Research is being done to improve the performance in future versions.

Special notes for Version 5.0.0:

Raphael

• The dependency on the Raphael library has been removed! This has made the minimized package 90K smaller, and has increased the speed of generating the SVG image by about 6 times!

For the most common use of creating either the sheet music or the audio, there isn't any change.

However, if you use the animation callback in the audio to manipulate the notes, then be aware that, instead of receiving elements that are wrapped in a Raphael object, you now receive the actual SVG element. For the most common example of the animation functionality, the following was recommended to change the color of notes:

element.attr({ fill: color });

That should be changed to:

element.setAttribute("fill", color);

• If you do specific manipulation of the SVG, you will need to retest your code. The generated SVG, while it looks the same on the page, has changed somewhat. The selectors you use may return different results.

Special notes for Version 4.0.0:

• BREAKING CHANGE: The names of all the classes that are generated are now prefixed with abcjs-. Any code that searched for particular class names before will have to be adjusted.

• The parameters have been combined into one set of parameters, instead of three sets like previous versions. The old way of calling the parameters will still work, but you are encouraged to use the new, simplified approach going forward.

Important Resources:

abcjs Home page (Overview of what this library does)

Configurator (Experiment with all configuration options)

API Documentation (All the details about using abcjs)

Special Notes (Notes from previous versions)

Info for abcjs contributors (Info about how abcjs is built and managed)

Support of the ABC standard (How abcjs varies from the ABC standard)

Release Notes

License: The MIT License (MIT)

Demos:

Description	Demo
Demonstration of all configuration options	Configurator
Call the library from javascript, passing the abc string to it.	Basic
Transforms a textarea into an abc editor with score sheet and audio.	Editor
Adds onto an existing webpage, rendering all abc it finds.	Plugin
Various simple demos	examples
Examples in complete Vue.js project (search for all the projects with the name in the form vue-abcjs-****-demo)	GitHub

Which flavor should you use?

node.js

If you are in the node ecosystem, simply install the packaged version with npm install --save abcjs.

To import, use one of:

import abcjs from "abcjs";
import abcjs from "abcjs/midi";

The first is a smaller package, but does not do midi. The second is a superset of the first, so do not load both!

To get the styles for the MIDI control:

import 'abcjs/abcjs-midi.css';

Old-style minimized download

If you are writing significant JavaScript on your site, and you are generating the music yourself, or 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-basic. This gives you control over the generation in a smaller package.

If you want to include MIDI playback, then use abcjs-midi. This is a superset of the basic version, so just include one or the other. It is a significantly larger package.

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.

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

• Basic

• Basic+MIDI

• Plugin

• Greasemonkey script

• Styles for the MIDI control

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
https://sightreadingfactory.com	(Educational)
https://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)
http://tunearch.org
http://www.norbeck.nu/abc	(tune collection)
http://ccm.secrice.com/	(CCM scores for playing the guitar)
http://bushtraditions.wiki/tunes/	(Australian Traditional Music Tunes Archive)

Let us know if you want to be listed!

Great big thanks to mudcube for the excellent work on midi.js!

Supported by BrowserStack

If you aren't using the same browser and machine that I use, you can thank BrowserStack for their support of this open-source project.