abc2svg
Documentation
Not logged in

abc2svg

abc2svg is a set of Javascript files for handling ABC music notation. This includes editing, displaying, printing, playing the music files and converting them to other formats such as ABC and MEI notations.

The abc2svg core is based on the abcm2ps C code which requires compilation on every operating system. The abc2svg scripts can run in any system with no compilation on any platform that contains an internet browser. This includes Windows, Apple, and Unix-like systems (Linux, BSD...) as well as portable devices such as cell phones and iPads.

A description of the ABC parameters that relate to both abcm2ps and abc2svg can be found here.

1. Web browser usage

1.1 Rendering ABC files from a local or remote source

After accessing ABC files with a web browser either from a local or web source, you can render or play the music without much preparation. One approach uses bookmarklets.

A bookmarklet is the same as a normal bookmark in a web browser. Its title (or name) is anything you want to use to identify it and its URL (or location or address) is javascript code starting by javascript:. First, create a bookmark from this page adding it to your library of bookmarks. Next, edit this mark changing the title and the URL. (Details for editing a bookmark are specific for each browser. To get instructions, search on the internet the name of the browser and keywords such as 'bookmarklet' and 'javascript in url'). To edit the URL, extract the javascript code by right clicking on one of the bookmarklets below and selecting copy url. Then, paste this code into the URL of your new bookmark in your library.

To use a abc2svg bookmarklet, first load an ABC file into your browser either from a web site of from a file on your system. Once you see the textual abc code, click on the bookmarklet that you created. After a slight delay depending upon the complexity of the abc code, it should be replaced by a music representation or a list of the contents of the ABC file. Here are two bookmarklets that you can try.

This first abc2svg bookmarklet renders all the music it finds in the page currently displayed.
Once the music is displayed, clicking inside a tune starts playing it from the beginning. Clicking on a particular note or rest starts playing from that point.
To print or convert the music to a PDF file, simply click on the 'Print' button of the web browser. (If the 'Print' button does not appear on your browser menu, try right clicking on the web page.)

Alternatively, if your source contains many tunes, you can use this second bookmarklet. The browser will list the titles of the tunes. Click on one of the titles to view the music representation. Playing and printing work in the same manner as above.
The generated pages contain a yellow menu in the top right corner which permits you to return to the tune list or to modify the music. With this last option, you can adjust the page size before printing, correct the ABC syntax or do some transposition. Note that these changes stay only with the browser and are not saved to your system.

If you want to experiment with these bookmarklets, here are some raw ABC files:

1.2 Writing, playing and printing music with the abc2svg editor

The abc2svg editor is another example of what can be done with abc2svg.

If you are unfamiliar with ABC music notation, just copy this ABC sequence below and paste it into the text area of the editor.

X:1
T:C scale
M:C
L:1/4
K:C
CDEF|GABc|

If your ABC files contain %%abc-include, then you must:

Only one included file is allowed.

If you have a US keyboard, its behaviour can be changed for easier music entering by one of these bookmarklets: keyboard 1 and keyboard 2.

1.3 Publishing music on your web pages

To insert music in your web pages, you just have to insert the lines

<script src="http://moinejf.free.fr/js/abcweb-1.js"></script>
<script src="http://moinejf.free.fr/js/snd-1.js"></script>
<script src="http://moinejf.free.fr/js/follow-1.js"></script>

in the HTML <head> and put the music as ABC sequences in the <body>.

This example demonstrates how to do it. (Note that the paths are relative - see why below.)

As it is apparent, HTML and ABC can be mixed in the same html file. Both are rendered in the order you defined them.

You may also have noticed this CSS about SVG elements:
        svg { display: block }

This permits to have the music on separate vertical areas.
Without this CSS, the music is in-lined as in this other example.

In the above examples, all the ABC music is generated (displayed and ready to be played) by means of the script abcweb-1.js.
If there is a large collection of tunes, it may be preferable to link to the other script, abcweb1-1.js, which permits you to select particular tune(s). Without an explicit selection (see below), a list of the tunes is displayed, and, after a tune has been selected, the whole page is replaced by the music. (The HTML code, if any, is not displayed.) A menu on the top right corner of the screen permits to get the tune list again. Here is a real example.

As you may note in the menu, the edition of the ABC content is proposed. This permits, for example, to transpose the tunes. This edition is done inside the browser, so, your changes will be lost after leaving the page.

When accessing such pages, an external selection of the tunes can be accomplished by adding the character '#' in the URL followed by a regular expression to be applied to the tune headers. For instance, here is the 'Duo' de J. Boyvin.

In the first example ("J'ai du bon tabac"), you saw that care should be taken with regard to the special XML characters '<', '>' and '&' by enclosing the ABC sequences inside XML comments. In the case you put ABC in a HTML file (not a XHTML file), the third abc2svg script abcweb2-1.js, following a bit the ABC standard 2.3, searches the music only in the elements of the class abc. As you may see in the source of this psaume, the ABC code is contained in a <script> element, so that it is not changed by the web browser. This is explained in section 4.3 following the description of abcweb2-1.js.

With any of the above scripts the music may be printed using the 'Print' button of the browser. You should add a style as:
      @media print{body{margin:0;padding:0;border:0}.nop{display:none}}

to remove the margins, the error messages and the menus from the printed pages.

1.4 Installing abc2svg on your system or on your server

The abc2svg package on my server is still being tuned which could change its behaviour at any unknown time; so you may prefer to install and run it from your own system.

There are many ways to install abc2svg:

For those unfamiliar with fossil, it is an integrated software management system similar to git.
Chisel acts like a repository similar to github.

Using bookmarklets with a local installation does not work directly (because of a cross-domain security hole), but it is possible by running a local HTTP server (you will also have to change the location of the scripts in the bookmarklet code).

If you have write access on a remote server, you may put there the abc2svg scripts. There is no automatic process to do that. You will have to look at my site to determine the files that need to be copied.

In addition, you have to set the correct location of the abc2svg scripts in your pages. As a trick, I put the abc2svg scripts in a folder at the same level as the HTML files:

        <script src="../js/abcweb-1.js"></script>

This allows the generation of the music to run either locally or remotely.

2. Automatic creation of music sheets

2.1 abc2svg shell scripts

As you have seen, printing the music can be done easily with any web browser. You can automate the process of creating music sheets with abc2svg using shell scripts running a Javascript interpreter.

The interfaces to the various scripts are different. Below you will find various scripts that I had to built.

Each script gets the abc2svg options and ABC files from the command line and sends the generated file to stdout and possible errors to stderr.
The general syntax of the command line is:
        script [script.js] [options] ABC_file [[options] ABC_file]* [options] with:

2.2 Backend scripts

By default, the shell scripts generate (HTML+SVG) files.
This output may be modified by backend scripts. These ones must appear immediately following the name of the shell script.
They are:

2.3 PDF generation

abctopdf is a shell script which converts ABC to PDF using one of the previous shell scripts and, either a chrome/chromium compatible web browser, or the program weasyprint or the program rsvg-convert.

With rsvg-convert, the used music font must be installed and defined by %%musicfont <fontname>.

Note also that, with weasyprint or rsvg-convert, the paper size is forced to A4. Instructions for changing this size may be found in the script source.

The output PDF document may be specified by the command line argument -o (default abc.pdf).

Example:
        abctopdf my_file.abc -o my_file.pdf

3. Build

The abc2svg scripts which are used to render the music either by a web browser or by a shell script must be built from the source files you got by tarball or fossil clone.

Quoting Douglas Crockford, minification is a process that removes comments and unnecessary whitespace from JavaScript files. It typically reduces file size by half, resulting in faster downloads.

If you can run one of the tools ninja or samurai, you can build the scripts

        NOMIN=1 samu -v

or

        NOMIN=1
        export NOMIN
        ninja -v

        samu -v

If you also want to change or add music glyphs, you may edit the source file font/abc2svg.sfd. In this case, you will need both base64 and fontforge, and run

        samu -v font.js

If you cannot or don't want to install ninja or samurai, you may build the abc2svg files by the shell script ./build. (This script must be run by a Posix compatible shell.)

4. Inside the code of abc2svg

4.1 Core and modules

abc2svg-1.js is the abc2svg core.
It contains the ABC parser and the SVG generation engine. It is needed for all music rendering. It is automatically loaded by the web scripts and the shell scripts.
If you want to use the core with your own scripts, its API is described in the wiki.

The core does not handle all the abc2svg commands/parameters. Some of them are treated by modules. A module is a script which is loaded in the browser or in the JS interpreter when the command it treats is seen in the ABC flow.
Detailed information about the modules may be found in the wiki.

4.2 Internal information

4.3 More about the web scripts

Here are the scripts which are used in a web context:

5. MEI support

As an experimental feature, an extented core mei2svg-1.js may be generated. This one may handle both the ABC and MEI notations.

In browser mode, the script abcweb-1.js loads either abc2svg-1.js or mei2svg-1.js after checking if <mei exists in the page (see this tune for an example).

In shell mode, the script abcqjs also loads the right abc2svg core according to the source file extension (.abc or .mei).

Jean-François Moine