Decibel ScorePlayer: Developer Hub



Anatomy of a Score File
Controlling the ScorePlayer via OSC
Canvas Mode
Decibel Score Server

Other Dev Projects
About the Author

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.) Additionally, the code has recently been released under the GNU GPLv3, and is available on github 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 here or can be downloaded directly from this site here. 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.

Additionally, if you are using Adobe Illustrator to create your scores and want an easy way to export layers as individual parts, a beta version of a script to do so can be found here. It gives you the option to specify any layers that you want to appear at full opacity in every part, and allows you to set the opacity that the not currently highlighted parts will be shown at. (Setting this to zero will hide them entirely.) It also conveniently exports a version of the full score in the same resolution and file format. To run the script, simply download it and then in Illustrator go to "File > Scripts > Other Script..." and select it. (On OS X you can use the ⌘F12 shortcut.)

Illustrator Script

The window displayed by the Illustrator script, allowing you to choose which layers you want made into separate parts.

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 patch for starting the ScorePlayer from max is available here. It should be placed in the Max library folder or another location in Max's search path. A patch showing how to use it is available here. 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.

Max Patch

The scoreplayer-connect max patch depends on the zero external by Cycling '74 and the CNMAT externals to work. These can both be installed via Max's built in package manager. Alternatively, the CNMAT externals are available here. Each of the inlets and outlets is commented, so hovering over them should show what they do. Banging the first inlet will cause the zero.browse object to check for any iPads running the ScorePlayer on the network. A list of server names will be sent out of the first outlet, and feeding one of these back into the second inlet will connect the patch to the chosen iPad. From there, any received messages will come out of the second outlet, and messages can be sent through the third inlet. The final outlet shows the connection state (1 for connected, 0 for disconnected) and the final two inlets are to change the listening port (8000 by default) and the protocol version number (currently 16, as of v2.0.0 of the ScorePlayer). It should be safe in most cases to leave these final two values as they are. If the original server iPad disconnects and another iPad takes over the role, the patch will be alerted and will automatically connect to the new server. The first message that should be seen after connecting to the iPad is a /Server/RegistrationOK message. If this isn't seen, then there's a problem with either incoming or outgoing traffic.

The current version of the patch requires Max 8 to work. If using an earlier version of Max, the zeroconf external found here can be used as a substitute for the zero external. (A few minor adjustments to the patch are required to make this work. Replace the zero.browse object with the zeroconf.browser object. Remove the object and just connect the browser object straight to the first outlet. Append ", bang" to the name $1 message and replace the zero.resolve object with the zeroconf.resolve object.)

Start Player Max Patch

The Max library patch to control the ScorePlayer remotely, created by Aaron Wyatt. The Pure Data screenshot below gives some idea of how simple it is to embed in an existing patch. (The process is nearly identical.)

Sending a /Control/Play message through the third inlet will cause the score to start, and /Control/Reset will stop and reset it. A full list of commands will be available soon.

A note for using OSC in 64 bit Max: Max has moved to 64 bit integers, but the opensoundcontrol object doesn't currently (August 2019) take this into consideration when dealing with 32 bit signed integers. As a result, any negative integers sent to Max will be wrong. I've written a small, stop-gap Max extenal to fix this data type issue called oscint which can be downloaded for OS X here.

Pure Data

There's now also a version of the scoreplayer-connect patch for Pure Data, which can be downloaded here, and there's a reference patch showing its use here. (Developed and tested using Purr Data on OS X and Debian.) You'll need to have Albert Gräf's pd-mdnsbrowser object which can be found here. There are a few other dependencies (the Pure language, for instance) and installation instructions for these can also be found via the link above. Additionally, to a stock install of Purr Data, you'll need to add pure, mrpeach, and mdnsbrowser to your list of startup libraries. It works in exactly the same way as the Max patch does, so please read the previous section for an additional understanding of what each of the inlets and outlets does.

Start Player Pure Data Patch

The reference Pure Data patch to control the ScorePlayer remotely, created by Aaron Wyatt. The patch will connect to the iPad chosen from the dropdown menu, and the LED shows the connection status. The messages at the top can be used to send play, seek, and reset commands to the player.


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 here.

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-2020, with contributions to the project from Cat Hope, Lindsay Vickery, Stuart James, and Tristen Parr.