Synpdf

You can either start synpdf from http://wim.vree.org/js2/synpdf.html or from a local copy of this file on your computer.
Synpdf 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 synpdf 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 PDF 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

Speed control can be enabled in the menu. With the input field appearing to the right of the media player you can change the play back speed. The available speed values are determined by the media player. Normal speed is 1.0. The speed factor can range between 0.5 and 2.0. (the Youtube player only allows a few speed values). Synchronization works at all speeds and can be done more precisely with lower speed settings.

Looping

When loop mode is enabled in the menu, a long click/tap (or shift click) in a measure, moves or defines the edges of a looping range. The first two long/shift clicks in the score set the left and right edge of the looping range. Each edge is marked with a bold red character: '<' for the left side and '>' for the right side. When long/shift clicking again in a staff the loop marker closest to the click location is repositioned. (closest in time)
When both range markers are placed, play back will continuously loop between these points. The loop range can still be adjusted by long/shift clicking in the staff near one of the markers (also when playing). The loop mode is switched off by unchecking the loop mode in the menu. Both range markers will be retained and when you check the loop box again they will reappear (en be active immediately). Loop markers are saved in the preload file and the preload will start play back at the first loop marker.

Annotations

Annotations can be added or edited in the score when annotation mode is enabled in the menu. Annotations can be added anywhere in the score area. A long click/tap (or shift click ) adds a default annotation. Clicking (tapping) in an (existing) annotation pops up an edit dialog where arbitrary (html formatted) text can be entered. Annotations can be dragged to a new position anywhere on the score page. An annotation is removed by long/shift clicking on it. Annotations are always saved in the preload file. In principle all html tags are allowed in an annotation. No checks are made. Not all tags may work, but many do (e.g. img, svg).

enable sync	Turns on synchronization mode. A special panel appears in the top right corner. This panel also contains the save button
advanced	also shows menu items that allow changing more complicated parameters (see below)
full screen	Switches the browser to full screen display (if supported)
file buttons	Shows the buttons to load score and media. Also shows the "use dropbox" checkbox
save	Saves score, settings and synchronization data to a file, called the preload file.
line cursor	Displays a line cursor in the score as an alternative to the measure shading.
speed ctrl	Shows the speed input field, next to the media.
loop mode	Enables loop mode. A long click/tap (or shift click) in a measure sets/moves the edges of a looping range
annotate	Enables annotation mode. A long click (or shift click) in the score adds/deletes an annotation in the score.
hide player	Hides the media player and resizes the height of the button area to zero.
hide dashes	Hides the dashed horizontal line to which the top of the currently playing staff is aligned
count-in	Displays a count down timer before starting playback. Only works when starting playback with the space bar or a click in the margin (does not work when starting the html-player directly). The initial value of the count down timer is determined by (URL) option "cnt=n". The default is 4 beats.

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 line cursor to traverse the measure).
media offset	The time in seconds from the beginning of the media file to the first note of the score. Some media files start (far) before the point where the score starts. The offset is the media playback time at the point where the score starts.
Backspace	Does a "backspace" of one measure. It erases the current synchronization point and backs up to (the beginning of) the previous measure. It also erases the timing data after the current measure. Playback will resume at the start of the previous measure (now shaded).

Synchronization starts at the currently selected measure. When you check enable sync with a new score the measure shading disappears and the audio/video is positioned at the beginning (rewound). Before starting playback you can now adjust the audio/video position with the media controls. It will not change the (disappeared) cursor. The media should start a little bit before the first note of the measure the cursor was on.

- click while playing (or just type a 'B')

Now there are two situations:

The media starts (some time) before the first note of the selected measure.
The media starts (precisely) at the time of the first note of the selected measure.

In the first case you switch on playback (spacebar!) and wait until you hear the first note of the measure. Precisely at that time you hit the B-key. Now the shaded cursor appears at the selected measure and waits for you to hit B again to mark the begin of the next measure.
In the second case you do not switch on playback, but just press B. This switches on playback and puts the shaded cursor on the selected measure. Wait until you hear the first note of the next measure and tap again (press B again). The cursor will move to the next measure.
Each time you press B or tap in the score the cursor moves to the next measure. When you arive at the end of the score and the last note has been played, tap once again (press B) to terminate the synchronization. This final tap (B) is essential as it records the end of play back time and removes the shading from the last measure.

- saving

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.

- errors

When you make an error you can press the Backspace button (in the sync menu) or press the Backspace key. This erases the last synchronization point and backs up to the previous measure. Playback jumps to the begin of that measure. The cursor waits again for you to tap (or press B).
You can press the Backspace button (or Backspace key) without pausing play back. Because play back jumps back one measure, you have plenty of time to catch up with the rhythm until you have to press B again at the end of the measure.
However, you may prefer to stop play back when you made an error (tap in margin or press Spacebar). You can then press the Backspace button (or press the Backspace key) once or multiple times. Each time it goes back one measure. Then you have to restart playback (Spacebar, or tap in left margin), which will start at the beginning of the currently shaded measure. The cursor will wait for your tap (or B) at the end of that measure and you can continue the synchronization.

- re-syncing with the B-key

You can also re-synchronize a fragment of the score using the B-key. Stay in sync mode (enable sync checked), go back to the measure where you want to start re-synchronizing (with the arrow keys), switch on playback (space bar). Now the cursor starts moving normally just like during play back, but, your strokes on the B-key will be noticed and used to redefine the nearest time point (bar line). You do not have to tap the B-key at every measure, just (near to) those where you want to correct the timing. You can best see the effect of your B-key stokes when the line cursor mode is enabled, because you will see the line cursor jump immediately (forwards or backwards) to the nearest bar line.

- synchronizing repeats

Synpdf is not smart enough to recognize repeat bars. Thus, before you start synchronizing, you have to mark all repeats. A repeat mark is set by long-clicking on a measure (or shift-clicking). First mark the end of a repeat (where the jump is made), then the begin (where the jump goes to).
At the first long/shift click you see a blue text "Jump_1" appear above the measure. At the second long/shift click a red text "Repeat_1" is written. Every repeat section requires 2 long clicks.

The figure above shows a score after the two repeat bars have been marked with two long/shift clicks. It may be counter intuitive that you have to mark the end bar of the repeat section first and then the start of the repeat section, but it is logical in terms of jumping: first from, then to. For instance, when we add an alternative ending:

In the figure above four long/shift clicks have been made for 2 repeat actions. The first is a normal repeat (jump backwards), while the second is a jump skipping an alternative ending.
After thus marking all repeats you can start synchronizing, using the B-key. The repeat jumps will be made automatically when you press B at (the end of) a measure with a "Jump_x" mark.
When you make an error while marking the repeats you can use key-G to erase the last pair of markings. Repeatedly pressing G erases all pairs until none are left.
You can enter multiple repeat marks in one measure. They will be stacked. This is needed when a section is repeated twice or more, for instance.

- using keys while paused

Once you have synchronized the score, you can always edit the synchronization accurately with the keyboard. The relevant timing data is displayed in the sync area at the top right corner of the page.

Adjusting one measure.
Stop play back (Spacebar).
Select a measure (with the arrow keys) where you find that the ending time deviates too much from the actual music. Use the keys . or , to increase or decrease the measure duration. When the cursor jumps too late you have to decrease the duration.
Adjusting the offset.
Stop play back (Spacebar). Switch to line cursor mode (key-L)
Go back (key Left Arrow) to the first measure and look at the offset time. Use the keys Ctrl-. and Ctrl-, 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 line cursor starts moving.

Advanced Settings

These items only appear in the menu when the advanced checkbox is marked.

line threshold	Lower the value of this threshold when not enough staves are recognized. Increase the value when too many areas are recognized as a staff (e.g. lyrics). The threshold determines when a horizontal line is considered as a real staff line and not a cross section of notes or text.
cluster threshold	Lower this value (to somewhere between 1.0 and 1.5) for complex director scores, where the systems on a page have different vertical sizes (== are composed of different number of staves).
skip	Some times there are title or text areas in the beginning of a score that are recognized as staves and get selected (green) in the beginning. Here you can set the number of such areas that have to be skipped.
select	In director scores, where multiple instruments are shown on a page, you can focus on one particular instrument by setting the select parameter to the position of that instrument on the page. For instance, setting select to 3 will only show (make green) the third instrument (system) on each page. A select value of zero (default) disables this feature.
first quarter	Normally only the rightmost quarter of the page is processed to find staves. With this checkbox the program only scans the leftmost quarter of the page. This is needed when some staves are shortened and left aligned with the other staves.
prefer systems	This checkbox increases the likelihood to group staves into a system.
single staves	Completely disable grouping of staves into systems. Only single staves are selectable (green shading). Use this if you have a single staff score and some staves are erroneously grouped into systems.
black theshold	Theshold value (0..1) between black (0) and white (1). Only applies when searching for bar lines. Rarely needs to be changed. (lower value -> less black pixels)
before/after theshold	Fraction (0-1) of the maximum whiteness before and after a bar line. (lower number → more bar lines)
barline threshold	Fraction (0-1) of maximum blackness that a bar line should have. (lower number → more potential bar lines)
dx	The distance in pixels where whiteness (before/after barline) is measured
page	The page that is displayed. In advanced mode only one page of the score is shown. This enables fast rending after changes are made with the controls. Also, the changes are only applied to the page shown. The other pages remain unchanged. When you change the page number the current values of all advanced controls are then applied to this new page. This means that if you want to apply the same (changed settings) to all pages, you have to go through al these pages using the page number input box.
fixed width	This checkbox (checked by default) takes care that the score is displayed with a fixed resolution of 1000 pixels width. This is important because all advanced parameters are preset to values that work best with this resolution. When you uncheck this checkbox, the score will be displayed with the actual window width. When you do this, you will probably have to change one or more advanced parameter values considerably. That is why it is better to start tuning the recognition parameters with the fixed width option checked. Then you have to change less and the optical recognition works better.
no menu	Save a preload file that hides the menu for the user. The preload file will set the internal option "no_menu" that hides the menu and disables the context menu. This is meant to protect score files from being easily copied.
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.
pdf data	Embed the pdf (or jpeg) data in the preload file. This makes the preload file much bigger, but the advantage is that synpdf does not need to read a separately stored score file. Expecially when uploading to a server this is an advantage. When the preload file refers to a Youtube video, then also embedding the score data makes the preload file completely self contained.

	The following two settings can only be changed by manually editing the preload file with a text editor
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};

Saving and using a preload file

synpdf 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 synpdf (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 synpdf.
For example, when you use a webserver:

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

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

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

or when opening synpdf as a local file:

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

The latter example assumes that the preload file is in the same directory as synpdf.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/synpdf.html
          /media/example.mp3
          /preload/example.js

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

    file:///score/synpdf.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 synpdf 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, synpdf 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/js2/synpdf.html?https://dl.dropboxusercontent.com/s/nvekxxa9cnn3l1z/gadma_2.js

This example loads synpdf 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/nvekxxa9cnn3l1z/gadma_2.js?dl=0

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

    http://wim.vree.org/js2/synpdf.html?d:nvekxxa9cnn3l1z/gadma_2.js

The string "d:" at the beginning of the preload parameter is expanded internally by synpdf 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.

Operation without internet connection

When you want to run synpdf on a computer without internet connection you need to have the following files in a directory of your choice:

    jquery-1.11.1.min.js
    pdf.js
    pdf.worker.js
    synpdf.html
    synpdf.js

All files are included in synpdf_188.zip. You can open the local file synpdf.html in your browser and everything should work normally. The same files can also be put on your own server when you want to serve synpdf your self. Note, however, that the Dropbox Chooser and Saver only work when synpdf is loaded from wim.vree.org. In practice this means: you cannot use the Dropbox Chooser and Saver with your local copy.

Extra parameters in the URL

Synpdf.html recognizes some parameters in the URL:

ln=	Switch the line cursor on/off (ln=1 or ln=0)
mmin=	Hide all menu items given in this comma separated list (no spaces). The names given in this list should be the ID's of the menu items to be hidden. You can find those ID's in the file synpdf.html. For example: mmin=lp,l2,l3,l5,l6,lg,lo,ln
playbtn	Shows a small play button at the top left of the score window. This button starts/stops playback (same as hitting the space bar or clicking in the margin)
cnt=	Determines the initial count down value when the count-in menu option is checked. Should be the number of beats to count down before starting playback. For instance: cnt=3 for a 3/4 time signature. The default value of the count down timer is 4 (beats).
nosm	Disables smooth scrolling.
fullmenu	Shows all menu items, in case some were hidden by option mmin= (see above)
ip=	With the parameter ip=ip_number 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 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 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 parameter: http://.../synpdf.html?preload&ip=192.168.xx.xx&mstr (master with slow video player) http://.../dynpdf.html?preload&ip=192.168.xx.xx&nomed&d3 (fast slaves with delay of 0.3 sec)

Multiple devices running synpdf synchronized (with Web Sockets)

When you have a group of tablets/phones/computers playing synpdf, you can synchronize these devices. 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.
This only 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. Thus, one of the devices on your local network has to run an special program (abcSrv.js) which takes care of the start/stop synchronization. (see running abcSrv.js).
A group of devices synchronized with the parameter ip=ip_number, behaves in a symmetrical fashion. Every device in the group can initiate a play/pause command, or jump to a different measure. 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/synpdf.html?some_preload.js&ip=192.168.178.xx      (for all slave devices)
http://wim.vree.org/js/synpdf.html?some_preload.js&ip=192.168.178.xx&mstr (for the master device)

where the device with ip number 192.168.178.xx has to run abcSrv.js
The device where abcSrv.js runs can also serve the preloads and media files (so you do not need internet connection):

http://192.168.178.xx:8090/synpdf.html?some_preload.js&ip=host      (for all slave devices)
http://192.168.178.xx:8090/synpdf.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 special abbreviation ip=host. This short form of the ip= parameter can only be used when the real ip number of the web socket server is already present (as host address) in the URL (so you do not have to type the ip number twice).

Running abcSrv.js

AbcSrv.js is included in: synpdf_188.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. Synpdf 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 implement 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 (more info).