txtmus is a set of ECMAscript files that handle many text-based music notations as ABC. It is an extension of abc2svg.
The txtmus scripts may work in a command line context with a ECMAscript (javascript) interpreter as well as in a browser context. They may be used to edit the files, to display, print or play the music and also to translate the tunes to some other format such as ABC or MEI.
A description of the ABC parameters that relate to txtmus and also abcm2ps and abc2svg can be found here.
After accessing music 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 txtmus bookmarklet, first, load a music file into your browser either from a web site of from a file on your system. Once you see the textual code, click on the bookmarklet that you created. After a slight delay depending upon the complexity of the music code, it should be replaced by a music representation or a list of the tunes if the file is a ABC tunebook. Here are two bookmarklets that you can try.
This
first txtmus bookmarklet
renders all the ABC 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 ABC 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 music 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:
The txtmus editor is another example of what can be done with txtmus.
If you are unfamiliar with ABC music notation, just copy this ABC sequence below and paste it into the edition 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 txtmus in a site of yours, you may put a file pref.js with the txtmus scripts. This file may contain various javascript functions and also ABC parameters. These parameters must be defined inside the following sequence:
if (typeof tm == "undefined")
var tm = {}
if (!tm.a_inc)
tm.a_inc = {}
tm.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.
To insert music in your web pages, you have to insert the lines
<script src="http://moinejf.free.fr/js/tmweb-2.js"></script>
<script src="http://moinejf.free.fr/js/snd-2.js"></script>
in the HTML <head>. If the music is in the ABC notation, it must be wrapped in a <script> sequence (see below).
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 tmweb-2.js.
If there is a large collection of tunes, it may be preferable to
link to the other script, tmweb1-2.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 content of the music fie 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.
The txtmus 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.
The script source files are in this tarball and the runable scripts are in this other tarball in my site.
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 txtmus 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 scripts in your pages. As a trick, I put the abc2svg and txtmus scripts in a directory at the same level as the HTML files:
<script src="../js/tmweb-2.js"></script>
This allows the generation of the music to run either locally or remotely.
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 txtmus 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.
tmqjs with qjs QuickJS by Fabrice Bellard and Charlie Gordontmmjs with js115 orjs102 (Mozilla JavaScript shells)tmjsc with jsc (webkit2gtk)tmnode with node (nodeJS without module)Each script gets the txtmus options and text music 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] music_file [[options] music_file]* [options]
with:
script.js is an optional backend script.tohtml.js (HTML+SVG)options are the txtmus options.These scripts try to read a file pref.js 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 TMPATH.
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:
toabc.js
This script returns the (selected) ABC tunes from the ABC source file
applying transposition.
The resulting file does not contain the formatting parameters.
Example:
tmqjs toabc.js my_file.abc --select X:2 > tune_2.abc
tomei.js
This script outputs the music as a MEI file.
Note, only one tune may be translated from ABC to MEI (multi-tunes ABC
generates bad MEI).
tonotes.js
This script outputs a list of the MIDI events.
toodt.js
This script creates an Open Document (ODT+SVG) which can be read by most
word processors (abiword, libreoffice…).
The output ODT document may be specified in the command line argument
after -o (default tm.odt).
Example:
tmqjs toodt.js my_file.abc -o my_file.odt
toparsons.js
This script generates the Parsons Code of tunes.
tosvg.js
This script creates a SVG image containing all the music.
It may be used for editing small tunes using a text editor,
a command line for generation and a SVG viewer with auto-reload.
For instance, first start the editor and SVG viewer:
textadept mytune.abc &
feh /tmp/o.svg &
Then, to generate and see the result, in the txtmus directory, do:
./tmqjs tosvg.js mytune.abc > /tmp/o.svg
tmtopdf is a shell script which converts text music 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 ./tm.pdf).
Example:
abctopdf my_file.abc -o my_file.pdf
The txtmus scripts which are used to render the music either by a web browser or by a shell script may be built from the source files you got by tarball.
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
without minification
This is useful for debugging purposes and the scripts are more human friendly.
NOMIN=1 samu -v
or
NOMIN=1
export NOMIN
ninja -v
in a standard way with minification
In this case, you need one of the tools
JSMin or
uglifyjs which comes with nodeJS.
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 txtmus files by the shell script ./build.
(This script must be run by a Posix compatible shell.)
tmcore-2.js is the txtmus core.
It contains the ABC music 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 txtmus 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 music flow.
Detailed information about the modules may be found in the wiki.
The music is displayed as SVG images. There is one image per
music line / text block.
If you want to move these images to some other files,
each one must contain the full CSS and defs. For that, insert
%%fullsvg x
in the ABC file before rendering (see the
fullsvg documentation
for more information).
Playing uses the HTML5 audio and/or the midi APIs.
For audio, by default, txtmus uses a sound font (format SF2)
which is split into one file
per instrument. This sound font is stored in the subdirectory Scc1t2/.
Each instrument file is a base64 encoded javascript array.
Other sound fonts may be used. Some of them are stored in the subdirectory
sf2/ (AWE_ROM_gm and 2MBGMGS). Two formats are supported: raw SF2 and
SF2 wrapped into javascript (the raw SF2 files can be loaded
only when they are in the same HTTP domain).
The shell script sf.sh (in sf2/) may be used to create the javacript files
from raw SF2 files.
The sound font to be used for playing may be defined in the music code
by the command %%soundfont. E.g.:
%%soundfont http://moinejf.free.fr/js/sf2/AWE_ROM_gm.js
The names of the txtmus scripts have a suffix which is the version of
the core interface (actually '-2').
Here are the scripts which are used in a web context:
tmweb-2.js
This script replaces the ABC sequences found in the (X)HTML file
by SVG images of the music.
The ABC sequences are searched:
abc (lower case letters),X: or %abc- at start of line up to a XML tag at start of line.When a ABC sequence is not included in a <script> and when it contains the characters '<', '>' or '&', it must be enclosed in a XML comment or in a CDATA (%<![CDATA[ .. %]]> - the comment or CDATA must be in a ABC comment).
When using <script>, it is possible to set txtmus parameters via CSS.
For that, the <style> in the HTML <head> may contain custom
properties (properties starting with '–') and these properties are converted
to txtmus parameters (starting with '%%') before the ABC sequence.
For instance, in the (<head>) <style> element, you can put:
.parm {--pagewidth:30cm; --bgcolor: yellow}
and in some <script ..vnd.abc..>, you set the class:
<script class="parm" type="text/vnd.abc">
This defines the page width and the background color of the generated music.
See the
(http://moinejf.free.fr/abcm2ps-doc/beginml.html)
for an example, and here is how to put inline music in HTML.
Playing and highlighting the played notes may be offered loading
the script snd-2.js (see below).
This script also accepts a parameter with_source
that may be set in two ways:
either as a ABC parameter
%%with_source 1
valid for all tunes,
or as a custom attribute of <script>
<script type="text/vnd.abc" data-with_source="1">
valid for the tune(s) of the script.
When this parameter is set, the music source is included before the
SVG images of the music. The music source is displayed
in a <pre> element of class source. The SVG's are included
in a <div> of the same class source.
The source may be displayed either above (default) or
at the left side of the music (using a style as
.source{display: inline-block; vertical-align: top}).
See the source of
abcm2ps/abc2svg features
for an example.
The music source may be editable. To change it, the script contains two functions:
tm.get_music returns the source of the music sequence
(in <script> with type “text/vnd.abc”)
Its argument is the HTML <div> element that contains the music.
tm.set_music has two arguments, the HTML <div> element
and the new source of the music.
It generates and replaces the music in the <div>.
tmweb1-2.js
The page body is analyzed as a ABC file and its content is
replaced by music as SVG images.
If the page contains reserved XML characters
('<', '>' and '&'),
the ABC code must be enclosed in a
<script type="text/vnd.abc"> .. </script>
sequence.
When there are many tunes in the file, the script displays a list of the tunes. The list step may be bypassed when the URL of the file contains a regular expression in the 'hash' value ('#' followed by a string at the end of the URL). This string does a (http://moinejf.free.fr/abcm2ps-doc/select.xhtml).
When one or many tunes are displayed, a menu in the top/right corner offers to go back to the tune list or to modify the ABC source.
snd-2.js
This script may be used with tmweb-2.js or tmweb1-2.js
to play the rendered ABC music.
txtmus includes the following packages:
wps by Tomas Hlavaty
http://logand.com/sw/wps/log.html
JavaScript SoundFont 2 Parser by imaya/GREE Inc and Colin Clark
https://github.com/colinbdclark/sf2-parser
Scc1t2
http://www.ibiblio.org/thammer/HammerSound/localfiles/soundfonts/
strftime by T. H. Doan
https://thdoan.github.io/strftime/