Decibel ScorePlayer: Developer Hub

Topics

Anatomy of a Score File
Controlling the ScorePlayer via OSC
Canvas Mode
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.) 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.

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

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 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 options(#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.

name: The name of the score. Since the ScorePlayer uses this to find other iPads on the network running the same score, composers should avoid using the same name for multiple works. (This also helps to avoid any confusion in the score selection screen.)
composer: The composer of the work. In the ScorePlayer, scores are sorted by composer surname. This is assumed to start after the last space in the supplied text. If you need to override this, you can instead supply the surname first and separate it from any given names by using a comma. For example "Cat Hope" could alternatively be entered as "Hope, Cat". If a score has more than one composer they should be separated by a semicolon. This will then be expanded into a more natural, human-readable form in the ScorePlayer. "Cat Hope; Lindsay Vickery" will appear as "Cat Hope and Lindsay Vickery". If three or more composers are listed, an Oxford comma will be included in the expanded form because Oxford commas rule.
type: Specifies which particular rendering module in the ScorePlayer will be used to play the score. (A page describing the particulars of each module and the format of the advanced preferences file for each should be coming soon.) The following values are valid: ScrollScore, TalkingBoard, Cage, UBahn, SlideShow, FlashCards, BigClock, Radar, Rodinia, Loaded. (These are case sensitive.)
variation: This value is only used for Cage scores. It selects which of the first six of the eight Cage Variations are to be played. (These are currently being moved into a spin off app, which is the preferred way to play these scores now.) Like the startoffset and the readoffset tags for scrolling scores, it's an artefact of the early development of the ScorePlayer where individual score types didn't yet have their own preference files.
duration: The length of the score, in seconds. Each score type defines whether this value needs to be non-zero or positive. If zero, the play button is hidden and the player's clock is not started. (There can still be animation controlled by the rendering module itself, although this will likely be limited. In the case of canvas mode, timing can be supplied by the external device that is controlling the player's drawing surface.) If non-zero, the play button is visible, and the clock will be started at playback. If the value is positive, it's treated as a hard limit, and the player will stop the clock once this is reached. If negative, it's treated as a soft limit and the clock will continue indefinitely until stopped by the rendering module.
startoffset: This element only applies to scrolling scores. (If used in other types of scores it is simply ignored.) It defines the size of the left margin of the scrolling image in pixels, effectively setting the point in the image at which the actual score starts. This is useful in cases where instructional material is contained at the left edge of the main score image. (This could be information about how the score is to be interpreted, or simply things like instrument labels.)
readoffset: Like the start offset, this tag applies only to scrolling scores. It defines the position of the playhead on the screen. (As represented in the diagram to the right.) If entered as a positive value, it will be interpreted as a pixel offset from the left hand side of the screen. If entered as a negative value it will be interpreted as a percentage of the screen width. This can be useful when you want the playhead to divide the screen in the same proportions regardless of whether the iPad is in landscape or portrait orientations.
filename: The image file to be used as the main score image. It should be a JPEG or PNG file. If part of a set of images, as required by some score types, its name should be of the format filename_1.jpg (or .png), with the index number incremented for each subsequent image.
prefsfile: The name of the xml preferences file that contains any additional preferences that are specific to the selected score type. The only requirement for this file is that it is not named opus.xml as this is reserved for the main score preferences file. Further information on the document type definitions for these files will be made available as this documentation project progresses.
instructions: A JPEG or PNG image file that contains instructions for the performer on how the score is to be interpreted. This image should be 540 pixels wide and can be any height as the contents of the instructions view can be scrolled vertically.
audiofile: An audio file (ideally in wav or aiff format) to be played back with the score. It starts playing exactly as the score is started, so any required lead in time needs to be included as silence in the audio file itself.
options: Some score types can be set to allow the performer to override certain settings when reading the score. (In TalkingBoard scores, for instance, the ensemble may be able to adjust the number of planchettes to be displayed.) This element takes a simple "yes" or "no" value that determines whether the options screen should be available to the performer. The default is "no", meaning the settings contained within the scores advanced preferences file are fixed.
part: This element specifies an image file (or the first image in a set of image files) to be used to create an individual part. Multiple part elements can be added, and parts are loaded in the order they appear in the opus file. While the requirements for parts differ for each score type (with some score types like TalkingBoard not allowing parts at all), they can be always be accessed in the same way in the ScorePlayer: by swiping up or down to change the currently selected part. (The score itself is included in this cycle.)
manualidentifier: At this stage, this setting is only of any use for the Loaded score type. Scores of this type are set to report back interactions between the performer and the iPad to an external device via OSC. By default, the iPad's device name is used to distinguish which iPad the message came from, but using this is not always practical. Setting this element to "yes" prompts the user to enter their own identifier before opening the score. The default is "no".
backgroundrgb: Sets the background colour of the score. For some score types, like TalkingBoard, this will have little effect unless there are transparent regions in the score image, as the screen should always be covered by a section of this image. For other score types, like the more common ScrollScore, this will be more prominent, being seen at the left and right extremes of the score's movement, as well as in the area housing the ScorePlayer's controls. This value should be specify the rgb components of the colour, separated by commas, within a range of 0 to 255.

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 zero.menu.format 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.)

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.

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.

Python

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...")

    external.play()
    finished.set()

finished = Event()
external = scorePlayerExternal()
external.selectServer()
canvas = external.connect(onConnect)
finished.wait()
external.shutdown()

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.

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.

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.