Abcweb

You can either start abcweb from http://wim.vree.org/js/abcweb.html or from a local copy of this file on your computer.
Abcweb also supports loading and saving on dropbox, but only when you start from the website. A local copy will not work with dropbox and only load/save files locally. How to use abcweb on a computer without internet connection is explained at the end of this page.

Opening score and media files

With the score file button you can open a MusicXml file (or an ABC text file) from the local computer (PC). When the "use dropbox" option is checked the score file button opens a Dropbox Chooser. This allows you to load score files directly from your dropbox. The same holds for the media file button. Normally local files are opened, but with dropbox enabled you can load the media from your dropbox. For video files there is a third possibility: "use youtube". With this option checked the media file button changes into a text field where you can enter the youtube-id of the video you want to display. With both "use dropbox" and "use youtube" checked, you can load the score file from dropbox and the video from youtube.
When you have opened (and possibly synchronized) a score file and a media file you can save the result into a preload file. This preload file will be saved locally or, when "use dropbox" is checked in your dropbox. Such a preload file can be opened with the score file button or by specifying it in the URL as explained in the section on saving and using a preload file. Opening a preload file loads score an media and all settings as the were at the time of saving.

Speed

Two buttons to the right of the media player change the play back speed. The button called plus increases and the button called min decreases the speed. Normal speed is 1.0. Each button click changes this factor by 0.1. The speed factor can range between 0.5 and 2.0. Synchronization (explained below) works at all speeds and can be done more precisely with lower speed settings.

Looping

When the loop mode menu item is checked, the first two clicks in the score set the left and right edge of a looping range. Each edge is marked with a bold red character: '<' for the left side and '>' for the right side. When clicking again in the score the loop marker closest to the click location is repositioned.
When both range markers are placed, play back will continuously loop between these points. The loop range can still be adjusted by clicking in the score near one of the markers (also when playing). The loop mode is switched off by unselecting the loop mode menu item. Both range markers are retained and when you enable loop mode again they will reappear (en be active immediately).

enable sync	Turns on synchronization mode. A special panel appears in the top right corner. This panel also contains the save button
speed ctrl	Shows the speed buttons.
loop mode	Enables the loop mode when this item is checked.
file buttons	Shows the buttons to load score and media. Also shows the "use dropbox" checkbox
no cursor	Hides the cursor when playing and shows the cursor when paused.
note cursor	Displays note cursors in the score in stead of the blue measure shading. Every voice gets a separate note cursor with a different color.
center player	When set the player is centered on the page. When not set the player together with the speedbuttons are centered
center score	Centers the score on the page. When not set the score is left aligned.
hide player	Hides the media player and resizes the height of the button area to zero. (score aligns to top of page)
autoscale	Resizes the score to the width of the browser page
skip repeats	Skips playing repeated sections. Is only effective when enabled before loading a score or preload file. Has no effect after loading.
count in	Displays a count down before starting playback. The tempo of the count-in is the average of the tempo in the next three measures. Takes speed setting into account. The current meter determines the number of beats that is counted down.
metronome	Displays a beat number count-down while playing. The beat tempo is that of the current measure, taking speed control into account.
help	Shows a panel with help info. The panel is hidden when the mouse leaves the panel area

Two settings can only be changed by manually editing a preload file:

msc_credits	The contents of msc_credits will be displayed next to, and to the right of, the media player. The setting is made by adding the following string assignment to the preload file: msc_credits = "any html formatted credit text goes here"
opacity	Sets the opacity of the measure shading (0.0 is no shading, default: 0.2, solid color is 1.0). This setting is in the line that looks like: opt = {"jump":0, ..., "opacity":0.2, ...,"btns":0};

Synchronization

To synchronize a live performance to the score you have to mark the enable sync checkbox. A special area becomes visible which shows some information related to synchronization:

duration measure	The time in seconds that the measure stays shaded (or the time that it takes for the note cursor to traverse the measure).
media offset	The time in seconds from the moment that the media starts playing until the cursor/shading starts moving. Some media files do not start at the point where the score starts. This time accounts for the difference. A positive offset means that the media starts earlier than the the score (which is the most common situation). A negative offset means that the score cursor starts before the media.
wait offset	With this option checked the media starts playing but the cursor (and score) are halted. A click in the first measure then unchecks this option and the cursor starts moving again (starting at the first measure) to allow further synchronization.
jump	When the jump box is checked, and you click in a measure, play back jumps back one measure to let you review the timing accuracy of your click (or rather the browser latency). Because this happens at each click, it is turned off by default.
import	Imports timing data from another preload file. When separate parts of the same score have to be synchronized, one only has to synchronize one part and import that data into the other parts. This not only saves work but is essential when these parts have to play synchronized in multiple devices.
save	Saves score, settings and synchronization data to a file, called the preload file.
scramble	The score data in the preload file will be scrambled. When such a scrambled preload file is loaded, abcweb disables the main menu, the context menu and drag/drop. This makes it more difficult for a user to retrieve the ABC score data.

You can follow two methods, while you can switch between both methods at any time. The first method is probably the easiest but not the most accurate:

- clicking while playing

You turn on play back and click in a measure as soon as you hear the first beat of that measure. By clicking in a measure you synchronize the *first* beat of that measure to the audio. You do not need to click in every measure, because, as soon as you click, the program calculates the current tempo and assumes the music keeps playing with that tempo. So you only need to click in a measure when the deviation between the score cursor and the audio becomes too large.
Clicking in the first measure synchronizes the first beat (of the music) to (the first note) in the media file. This sets the, so called, offset of the media file. When the score belongs to a fragment that starts late in the media file, one does not want the cursor moving before playback arrives at the fragment. With option wait offset checked you can start playback while the cursor and score stay halted. When play back arives at the position of the first measure, a click in that measure unchecks this option and the cursor starts moving to allow further synchronization.
When the jump box is checked (above the save button), playback jumps one measure backwards at every synchronization click. The idea is that you can review how well your click was timed.

- using keys while paused

Although you can easily synchronize playback by just clicking in a measure at the right time, a more precise result can be obtained when using the keyboard short cuts. Proceed as follows:

Make sure your score has at least one tempo marking (at the beginning) with approximately the right tempo of the live performance. You will then start off with at least an approximately synchronized score.
Stop play back (space bar). Switch on the note cursor (l).
Go back to the first measure (←) and look at the offset time (it will be zero in the beginning). Use the keys control-. and control-, to increase or decrease this offset time by 0.1 sec per keystroke. Adjust the offset until the music starts at the same time as the note cursor starts moving. The offset can assume (large) negative values when the music starts late in the media file.
Go to the first measure (with play back halted!) where you find that the cursor deviates too much from the music. Use the keys . or , to increase or decrease the measure duration. When the cursor is too late in the measure you have to decrease the duration. You may also want to decrease the measure before the one where you find the deviation too much. When the cursor is too far ahead relative to the music (too fast) you should increase the duration of the measure.
Frequently stop playback (space bar), navigate a couple of measures backwards (←), and restart playback (space bar) to judge synchronization. Using the note cursor is probably better for this purpose than measure shading.
When all measures are synchronized you can save the results (w or save button) to a preload file. The preload file can have any name, but should end with ".js" as it is a regular javascript file.

Saving and using a preload file

abcweb can preload score data, media file, synchronization data and several settings from a special javascript file. Such a "preload file" is made by pressing the save button in abcweb (visible when the synchronisation option is checked).
To use a preload file you can either load it like a score file with the score file button or you can add the name of the preload file as a parameter in the URL that starts abcweb.
For example, when you use a webserver:

    http://your.domain/abcweb.html?preload_file.js

or when the preload is on dropbox (explanation below):

    http://wim.vree.org/js/abcweb.html?d:z5swu2kum6vorxv/preload_file.js

or when opening abcweb as a local file:

    file:///path/to/abcweb.html?preload_file.js

The latter example assumes that the preload file is in the same directory as abcweb.html. When it is in another location, the relative path to the preload file should be given. As an example, suppose the following directory layout:

    /root
    /score/abcweb.html
          /media/example.mp3
          /preload/example.js

Then abcweb.html can be opened in the browser using the following (local file) URL:

    file:///score/abcweb.html?../preload/example.js

The preload file is a regular javascript file. It only contains a couple of assignments. The first assignment sets the media file to load. When example.js is freshly saved using abcweb it will look as follows:

    media_file = "example.mp3";

Note that only a file name is specified and no path. Due to security restrictions in the browser, abcweb cannot save the correct path. This means that you have to add the path manually into example.js. With the example directory tree from above, the first assignment should read:

    media_file = "../media/example.mp3";

Preload files with Dropbox

When saving with dropbox a preload file is created which already contains the correct shared link to the media file. No manual changes are necessary. The preload file is used by specifying the shared link to the preload file as URL parameter. For example:

    http://wim.vree.org/js/abcweb.html?https://dl.dropboxusercontent.com/s/kb5d2uyletj4exh/gadma_2.js

This example loads abcweb from its website and loads the preload file gadma_2.js from the user's dropbox. However, when you obtain a shared link from dropbox it has a different form, like:

    https://www.dropbox.com/s/kb5d2uyletj4exh/gadma_2.js?dl=0

Unfortunalely the link in this form cannot be used for abcweb. You have to extract the 15 character long code string ("kb5d2uyletj4exh" in the example above) and the file name. The URL parameter you have to use for abcweb then becomes "d:code_string/file_name". Thus the example above becomes:

    http://wim.vree.org/js/abcweb.html?d:kb5d2uyletj4exh/gadma_2.js

The string "d:" at the beginning of the preload parameter is expanded internally by abcweb to "https://dl.dropboxusercontent.com/s/". This saves you some typing.
A preload file on DropBox must always have extension .js otherwise it will not load.

A Playlist

You can have several preload files playing in sequence with a playlist. A playlist is an ordinary javascript file (say: playlist.js) containing one assignement statment:

    play_list = ["preload_1.js", "preload_2.js", "preload_3.js"]

In this statement the variable name play_list is mandatory. The preload file names can be freely choosen, of course. To execute a playlist it is added as a parameter to the URL, just like a preload file:

    https://wim.vree.org/js/abcweb.html?playlist.js

or, you may open a playlist with the score browse button.

In this example above the playlist and the preload files should be in the same directory as abcweb.html, but you can also put them in other places when you provide the relative path of all file names (relative to abcweb.html). For instance:

    play_list = ["../test/preload_1.js", "../test/preload_2.js", "../test/preload_3.js"]

and the playlist itself may also be anywhere:

    https://wim.vree.org/js/abcweb.html?../somewhere/else/playlist.js

Operation without internet connection

When you want to run abcweb on a computer without internet connection you just open the file abcweb.html in the browser. You have to put four extra javascript files (that are normally loaded from the internet) into the same directory as abcweb.html:

    jquery-1.11.0.min.js
    abc2svg-1.js
    abc2web.js
    xml2abc.js

All files are included in abcweb_203.zip.

Off-line use on iPad

On the iPad you can use abcweb off-line (stand alone, wihtout internet connection) with the help of the Documents App by Readdle.

Extra parameters in the URL

Abcweb.html recognizes several extra parameters in the URL:

file name	When you use a file_name as parameter in the URL, the file extension determines its intended use, i.e. media files should end with .ogg, .mp3, .webm or .mp4 and score files should end with .xml or .abc, filnally preload files should end with .js. For example, when using dropbox: http://wim.vree.org/js/abcweb.html?d:dropbox_id1/scorefile.xml&d:dropbox_id2/mediafile.webm or with your own webserver: http://your.domain/abcweb.html?relative_path/to/scorefile.xml&relative_path/to/mediafile.webm The first example uses abcweb from the standard location and loads the other files from your dropbox. In the second example both score file and media file are located on your.domain, the same domain from where abcweb.html is opened. This causes abcweb to preload the score file and the media file from the server.
med=	To use a youtube identifier as URL parameter you need to specify med=youtube_id. For instance: http://wim.vree.org/js/abcweb.html?d:dropbox_id/scorefile.xml&med=youtube_id loads the youtube player with the identified video and gets the score from dropbox.
ip=	With the ip=ip_number parameter you specify the ip number of a WebSocket server on your local network. All instances of abcweb that are started with the same ip=ip_number parameter are playing synchronized with each other. This is useful to get a group of computers/tablets play the same score at precisely the same time. Each instance can start/stop playing and all others follow. Same for jumping to a different measure. See Web Sockets for more details on how the run the server.
mstr	The master parameter mstr makes one device the master of a group of synchronized devices. Only the master device can issue play/pause commands and position the playback. All other devices follow the master but cannot play/pause or jump to another measure.
nomed	Skips the loading of the media and aligns the score with the top of the page. On a synchronized device this option shows the score and the synchronized cursor, but does not load or play the media file.
dx.x	Inserts an initial latency of 0.xx seconds for all commands received on a synchronized device. This is useful if some devices of a synchronized group are much slower than others. For example, the simulated default player is much faster than the youtube player. A latency of 0.3 seconds is no exception, which can be compensated by adding d3 as paramter: http://.../abcweb.html?preload&med=youtube_id&ip=192.168.xx.xx&mstr (master with slow youtube player) http://.../abcweb.html?preload&ip=192.168.xx.xx&nomed&d3 (fast slaves with delay of 0.3 sec)
nb	Hides the menu. The user cannot change anything. Of course it also prevents saving. To make this setting permanent in a preload file, you have to edit the preload file manually with a text editor. The setting is called no_menu and should be set to 1 to hide the menu: opt = {"jump":0,"no_menu":1,"nospd":true, ... Note: a scrambled preload file implies this option.
tmr=n	Sets the margin between the top of current music line and the bottom of the player to n pixels (default 0, which displays the current music line precisely adjacent to the player). This setting is saved in the preload file.
tb=s.s	Starts playback at time s.s seconds. This time point may be inside or outside the time range covered by the score. Time 0.0 is the start of the media file. The start time must be positive and smaller than the end time of the media file. The parameter is saved in the preload.
te=s.s	Stops playback at time s.s seconds. This time point may be inside or outside the time range covered by the score. The end time must fall after the start time (tb=s.s, when given) or the start of the score. The parameter is saved in the preload.

Notes:

The parameter nb is only interpreted when also a preload file or a score file is present in the URL.

In stead of specifying a score and media file name parameter in the URL one can also (and better) use a preload file. But when granting access to a large collection of score files on a server, it may be preferable not to have to provide an extra preload file for every score/media file.
The advantage of using a preload file is that it also provides synchronization data and other preferences.

You can not use score and media file name parameters in the URL when abcweb is started from the local file system on your pc (double click abcweb.html). A preload file, on the other hand, can always be used. Even when abcweb.html is opened from the local file system.

Multiple devices running abcweb synchronized (with Web Sockets)

When you have a group of tablets/phones/computers playing abcweb, it is possible to have these devices precisely synchronized. When one device starts playing all other devices start as well. When one device jumps to a different measure all devices jump at the same time. Hereby it is possible to have only one master who is able to perform play, pause or jump or to have a symmetrical situation where each device can issue these commands. Also it is possible to have only one device with both score and media files loaded while all other devices only have score and no media. The media-less devices still move the cursor synchronized with all others through the score.
All this requires one extra parameter in the URL: ip=ip_number. It needs to be typed on each device to be synchronized. The ip_number in this parameter is the address of a computer/tablet/phone running the javascript program abcSrv.js (see running abcSrv.js). This program preforms the role of director for the group of synchronized devices. It receives a play/pause/jump command from one member of the group and (re)issues the command to all members of the group.
A group of devices synchronized with the ip=ip_number parameter, behaves in a symmetrical fashion. Every device in the group can initiate a play/pause command, or jump to a different measure.

To start/stop playback for a group of devices you have to use the P-key or click somewhere in the margin. Using the play-button of the media player will not issue synchronized commands; only the P-key or a click in the margin can start multiple devices in sync.

One extra parameter: "mstr" makes the device where this parameter is present the master of the group, disabling all others from issuing play/pause or jump commands. Only the master can now initiate play/pause of jump. For example:

http://wim.vree.org/js/abcweb.html?some_preload.js&ip=192.168.178.xx      (for all slave devices)
http://wim.vree.org/js/abcweb.html?some_preload.js&ip=192.168.178.xx&mstr (for the master device)

while the device with ip number 192.168.178.xx has to run abcSrv.js
To run locally one would use:

http://192.168.178.xx:8090/abcweb.html?some_preload.js&ip=host      (for all slave devices)
http://192.168.178.xx:8090/abcweb.html?some_preload.js&ip=host&mstr (for the master device)

This works while abcSrv.js not only synchronizes the devices but also acts as a normal web server (on port 8090). In this case one needs all abcweb files to be present in the same directory where abcSrv.js is located. Also some_preload.js and its corresponding media file have to be there. This is because abcSrv.js uses its own directory as root directory for the http server it implements.
Note the specal abbreviation ip=host. This short form of the ip= ip_number can only be used when the real ip number of the web socket server is already present (as host address) in the URL.
When you want the slave devices without media player you have to add the parameter "nomed" in the URL. For example:

http://192.168.178.xx:8090/abcweb.html?some_preload.js&ip=host&nomed (for all slave devices)
http://192.168.178.xx:8090/abcweb.html?some_preload.js&ip=host&mstr  (for the master device)

This example is for a class room where only the master is connected to loudspeakers and the slaves are mute and only follow the score.
When a device succesfully connects to abcSrv.js (the WebSocket server) the menu button becomes green. For the master device the menu button becomes red. This gives some feedback to indicate that henceforth all play/pause/jump actions will be issued by abcSrv.js as the director of the group.

Running abcSrv.js

AbcSrv.js is included in: abcweb_203.zip. It is a javascript program that implements a simple http server and a special Web Socket server. The normal http server runs on port 8090 and the web socket server on port 8091. Abcweb expects the web socket server to be on port 8091.
To run abcSrv.js you need to have Node installed. Node is a javascript engine with unrestricted access to many underlying computer capabilities. Browsers can run javascript too, but they hide these capabilities almost completely (sandbox) and are of no use to implements servers.
When you have Node installed you can start abcSrv.js with a command like:

# nodejs abcSrv.js

When started it prints the following output on the console:

websocket server listening on port: 8091, address: 192.168.178.xx
http server listening in port: 8090, adress: 192.168.178.xx
web server root directory: /path/to/where/abcSrv.js/is/located/

On a normal (i.e. not jailbroken) iPad, abcSrv.js has been tested using the app Touch Code Pro from iTunes. This app can load and run abcSrv.js, which turns the iPad into a simple http server and websocket server, so you can not only synchonize a group of other tablets but also serve the score an media locally, without connecting to the internet (see running abcweb.html locally).