Anatomy of a Score File
Decibel Score Server
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 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 name (#PCDATA)>
<!ELEMENT composer (#PCDATA)>
<!ELEMENT type (#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 part (#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.
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.
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.
from scoreplayer_external import scorePlayerExternal
from threading import Event
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 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.
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.
Copyright Â© Aaron Wyatt, 2019, with contributions to the project from Cat Hope, Lindsay Vickery, and Stuart James.