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 (or long tap) in a staff, moves or defines the edges of a looping range. The first two long 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 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 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 (or long tap) 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 clicking on it (or long tap). 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).

Menu

Several settings can be changed with checkboxes via the menu. When you make a preload file, all settings are saved, except the "enable sync" setting.
enable sync Turns on synchronization mode. A special panel appears in the top right corner. This panel also contains the save button
file buttons Shows the buttons to load score and media. Also shows the "use dropbox" checkbox
line cursor Displays a line cursor in the score in addition to the geen staff shading.
speed ctrl Shows the speed input field, next to the media.
loop mode Enables loop mode. A long click in the staff sets/moves the edges of a looping range
annotate Enables annotation mode. A long click in the staff adds/deletes an annotation in the score.
autoscale Resizes the score to the width of the browser page
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
crop width of margin (in pixels) that is cut off the left and right side of the score. This makes the score wider by deleting useless white space.
width sets the width of the score (in pixels)
advanced also shows menu items that allow changing more complicated parameters (see below)
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.
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 staff The time in seconds that the staff stays shaded (or the time that it takes for the line cursor to traverse the staff).
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.
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.
wait With this option checked the media starts playing but the cursor remains halted. You have to click in the staff as soon as playback arrives at the first beat of that staff. After the click the cursor starts moving but waits again at the end of the staff for a click to move on to the next staff. In stead of clicking you can also type a key-B on the keyboard. This is more accurate as it does not intefere with scrolling (as the mouse or tapping possibly could)
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.
jump When the jump box is checked, and you click in a staff, play back jumps back one staff 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.
save Saves score, settings and synchronization data to a file, called the preload file.
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.
(Make sure that checkbox "wait" is on and checkbox "jump" is off)
- click while playing (or just type a 'B')
When you check "enable sync" with a new score (that is not synchronized) the first staff will get unselected (shaded green disappears). Also after turning on playback the cursor will not move and the staff remains unselected.
You have to click on the staff (or just type a B on the keyboard) to get the cursor (red line) moving. You have to do that as soon as you hear the first beat (note) in that staff.
At the end of the staff the cursor halts again and waits for you to click (or type a B) to move on to the next staff. You do so when you hear the first beat of the next staff.
When the music arives at the next staff before the cursor does, you still click (or type B) to make the cursor catch up with the music and jump to the next staff. Repeat this process with every staff until the complete score is synchronized.
- synchronizing repeats
To set a repeat (or "jump back" location) you stop playback and scroll to the staff where the cursor should go to (begin of the repeat). Then long-click (or long tap) on that staff. You will see a red R appear to the right of the staff, indicating that this staff is the jump-back location.
Now resume playback and when the music arrives at the right side (end) of the repeat: press key G (in stead of B). Immediately the cursor jumps back to the left side of the repeat and the red R disappears.
You can continue synchronizing normally, using the B. There is no click-equivalent for key-G. Setting and using repeats requires a keyboard.
- using keys while paused
You can always set (or 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.
  1. Stop play back (key-P) and make sure the line cursor (key-L) is visible.
    Go back to and select the first staff (key-[) 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. The offset can assume (large) negative values when the music starts late in the media file.
  2. Select a staff (with play back halted!) where you find that the ending time deviates too much from the actual music. Use the keys . or , to increase or decrease the staff duration. When the cursor is too late at the end of the staff you have to decrease the duration.
  3. Frequently stop playback (p), navigate a couple of staves backwards ([), and restart playback (p) to judge synchronization.
  4. When all staves 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

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_20.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:
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 abcweb 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_20.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).