abc2svg
Documentation
Not logged in
Home Timeline Files Branches Tags Tickets Wiki Login

abc2svg

abc2svg is a set of ECMAscript files that handle the 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 MS-Windows, Apple, and Unix-like systems (Linux, BSD...) as well as portable devices such as cell phones and tablets.

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. Clicking on a title displays the tune. 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 installed abc2svg in a site of yours, you may put a file pref.js with the abc2svg scripts. This file may contain various javascript functions and also ABC parameters. These parameters must be defined inside the following sequence:

if (typeof abc2svg == "undefined")    
    var abc2svg = {}
if (!abc2svg.a_inc)
	abc2svg.a_inc = {}
abc2svg.a_inc["default.abc"] = `
.. put here the ABC parameters ..
`

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>

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

This example demonstrates how to do it. (Note that, in the example, 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 style about SVG elements:
        svg { display: block }

It puts the lines of music on vertical areas.
Without this style, the music is in-lined as in this other example.

Global ABC parameters may be added as parameter=value in the query string of the URL of the page. The following example calls the same "J'ai du bon tabac" with pagescale=1.2 (giving %%pagescale 1.2).

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 offers a tune selection. 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.) You can go back to the list of the tunes thanks to the menu on the top right corner of the screen. Here is a real example.

As you may notice in the menu, the edition of the ABC content is proposed. This permits you, 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 ending the URL with the character '#' followed by a regular expression to be applied to the tune headers. For instance, here is the 'Duo' de J. Boyvin.

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 this 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 interpreters are different. Below you will find the scripts 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:

These scripts try to read a file default.abc at startup time. This file and also the files included by %%abc-include are searched in the current directory or in the colon separated list of directories contained in the environment variable ABCPATH.

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 (settable by the environment variable 'BROWSER'), or the program weasyprint.

Note also that, with weasyprint, 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:

6. Credit

abc2svg includes the following packages:

Jean-François Moine

This page was generated in about 0.013s by Fossil 2.24 [8be0372c10] 2024-04-23 13:25:26