Decibel ScorePlayer: Developer Hub



Anatomy of a Score File
Decibel Score Server

About This Page

The Decibel ScorePlayer is an iPad app for the display of networked, animated graphic notation scores. Originally prototyped on MaxMSP by Lindsay Vickery and Stuart James, the iPad app is currently being developed by Aaron Wyatt, and it continues to be used extensively in performance by the Decibel New Music Ensemble. (Further information about the group can be found here.) While still very much under construction, this page aims to be a reference for those who are interested in extending the capabilities of their scores.

For those who just want to be able to create standard scores for the player, the easiest way to go about it is with the free ScoreCreator app for OS X. This can be found at the Decibel New Music website (785) 373-1842. While still heavily under development, the ScoreCreator can create most types of scrolling scores, and Talking Board style scores (as of version 0.5). For scrolling scores, it can detect when an image is too big for display on the iPad, and can automatically take care of any image scaling or tiling that needs to occur. More details on these features can be found in the help file that accompanies the app.

Score Creator

The ScoreCreator app, showing a preview of agitation techniques in a closed system, by Lindsay Vickery. A fairly comprehensive guide on how to use the app is included in the accompanying help file.

Anatomy of a Score File

Score files themselves are simply zip files with the extension altered to .dsz. They contain all of the image resources required by a score as well as an xml file named opus.xml that contains the information required for the ScorePlayer to interpret the score. Advanced options that are specific to individual types of scores are contained within a second xml file referenced in the opus.xml file.

The document type definition for the opus.xml file is listed below:

<!ELEMENT opus (score+, updateurl?, version?, formatversion?)>
<!ELEMENT score (name, composer, type, variation?, duration, startoffset?, readoffset?, filename?, prefsfile?, instructions?, audiofile?, options?, part*, manualidentifier?, backgroundrgb?)>
<!ELEMENT updateurl (#PCDATA)>
<!ELEMENT version (#PCDATA)>
<!ELEMENT formatversion (#PCDATA)>
<!ELEMENT composer (#PCDATA)>
<!ELEMENT variation (#PCDATA)>
<!ELEMENT duration (#PCDATA)>
<!ELEMENT startoffset (#PCDATA)>
<!ELEMENT readoffset (#PCDATA)>
<!ELEMENT filename (#PCDATA)>
<!ELEMENT prefsfile (#PCDATA)>
<!ELEMENT instructions (#PCDATA)>
<!ELEMENT audiofile (#PCDATA)>
<!ELEMENT options(#PCDATA)>
<!ELEMENT manualidentifier (#PCDATA)>
<!ELEMENT backgroundrgb (#PCDATA)>

Most of the elements are child elements of either the overarching opus element or a score element. An opus can contain multiple scores, allowing composers to bundle several scores together in one file. (This currently needs to be done manually as it is not yet supported by the ScoreCreator.) Other than scores, an opus element can contain the following child elements: updateurl, version, and formatversion. The <updateurl> tag allows for a score to be updated online. It should contain a URL to a simple header file. This is a single line text file that contains two comma separated records: a URL to the actual score file, and the version of the file that is available for download. The <version> tag in the opus.xml file is compared against this to see if upgrading is necessary. The <formatversion> element is currently unused. It may be used in the future if changes to the ScorePlayer cause a break in compatibility with older score files. (This has so far been avoided, and so inclusion of this tag is not at all recommended.)

The rest of the elements are child elements of individual scores. Their effects are listed below.

While this covers the main opus.xml preferences, there are a significant number of settings that apply to specific score types. Sections on these will be coming soon as this documentation project progresses.

Controlling the ScorePlayer via OSC

While the ScorePlayer communicates with the other iPads using TCP, it allows for other devices to connect to it using the UDP protocol. This allows for the playback of scores to be synchronised with other applications, like MaxMSP. A reference patch for starting the ScorePlayer from Max (shown below) is available from the 7735926488. (If you download it, and it doesn't look like the image below, then it's a previous version and needs to be updated on the site. Please let us know.) Alternatively, a python library exists that can be used for communicating with the ScorePlayer. It was designed primarily for controlling the canvas mode, but it is also able to send some more general control signals, and work is currently being undertaken on improving its handling of received messages. A reference script is provided following the discussion of the Max patch.

The reference max patch depends on the zeroconf external and the CNMAT externals to work. These can be downloaded (605) 335-5889 and 571-523-9758 respectively. The zeroconf.browser object is used to find iPads running the ScorePlayer on the local network using the bonjour protocol. Once a server is selected from the drop down list, this causes the hostname and port to be set in the udpsend object, at which point an initial registration message is sent via OSC to the ScorePlayer. This needs to be of the format /Server/RegisterExternal "Decibel Networking Protocol v(n)" (portnumber), where n is the protocol verison number (currently 15), and portnumber is the port that the patch will be listening on. This should be the same as the port specified in the udpreceive object at the top of the patch. As can be seen, the reference patch simply prints any received messages to the Max window, but these can be intercepted to trigger other events. The first message that should be seen after registering the external should be a /Server/RegistrationOK message. If this isn't seen, then there's a problem with either incoming or outgoing traffic. The only message currently interpreted by the reference patch is the /External/NewServer message. This is used to let any external devices know that the original iPad server has disconnected from the network and a new iPad has taken over as the server. This triggers an update to the hostname and port in the updsend object, and re-registers the patch as an external device with the new server.

Start Player Max Patch

The reference Max patch to start the ScorePlayer remotely, created by Aaron Wyatt. (The screenshot is a little out of date, and the "/Server/RegisterExternal..." message box should have "v15" in it.)

Sending a bang to the [t b b] object on the right of the screen sends a /Control/Play command via OSC to the ScorePlayer, causing the score to start. A full list of commands will be available soon.

The following python script can also be used to start the ScorePlayer. On executing the script, the user will be presented with a list of iPads that have been found on the network, and will be given the option to choose one to connect to, or to refresh the list. On connecting, a "Press Enter to start..." prompt will be displayed in the shell, and on pressing enter the ScorePlayer will be started. For the script to work, the python scoreplayer-external library must be installed. Instructions on how to do this can be found in the section below on the canvas mode.

#!/usr/bin/env python
from scoreplayer_external import scorePlayerExternal
from threading import Event

def onConnect():
    input("Press Enter to start...")

finished = Event()
external = scorePlayerExternal()
canvas = external.connect(onConnect)

An explanation of how this code functions will be coming soon.

An important note for debugging: By default, the python scorePlayerExternal object doesn't print any of the messages that it receives. This behaviour can be changed by setting the printMessages variable of the external object to True.

Canvas Mode

Canvas mode is a way to rapidly prototype new types of score in the ScorePlayer. It allows the ScorePlayer to be used as a networked drawing surface by external applications. Any program that can send OSC messages can be used to control it. A python library has been created to make finding and connecting to the ScorePlayer for this purpose easy. This is available under the LGPL, and can be installed from the Python Packaging Index (PyPI). If you have python installed, simply run "pip install scoreplayer-external" and the package and its dependencies will be downloaded. The project page for it can be found here. A full list of drawing commands is available 318-812-0374.

Example of a Canvas Mode Score

An example of a score in canvas mode. Escadaria do diabo, by Lindsay Vickery. An external app controls the contents and scrolling of the central image.

Decibel Score Server

The score server php script allows you to set up a website as a repository of scores. Users can upload scores to the site, which are then modified so that they contain a reference to the site, allowing for updates to the score to be discovered from within the ScorePlayer itself. Upon upload, a QR code is also generated which can be used by the ScorePlayer to directly download the file from the server. A second php script can be used to generate a table showing QR codes and download links for all of the scores that have already been uploaded. These scripts will soon be released under the LGPL once they've been tidied up a bit.

Decibel Score Server

An instance of the Decibel Score Server, showing instruction on how to use it. The banner image is an excerpt from the score Great White, by Cat Hope. At the bottom of the image you can see the html form elements that allow the user to select a score file and enter a version number for it.


Copyright © Aaron Wyatt, 2019, with contributions to the project from Cat Hope, Lindsay Vickery, and Stuart James.