A selection of some of the avaialable glyphs showing their centre points. These are positioned to allow for much easier and more convenient placement of the glyphs.
Here is a full list of commands for the canvas mode of the ScorePlayer. This is accurate for version 1.9.2 of the software and beyond. Future versions will add more commands, but should retain backwards compatibility with this current list.
If sending OSC messages directly, remember to prepend these commands with /Renderer/Command/objectname. If using the python library these are the methods called on your object. (All examlpes given below are in the python format.) In python, any numerical values given as arguments will automatically be cast to the variable type expected by the player. In other environments, you will have to manually take this into consideration. All arguments are either strings (s), integers (i), or floats (f). Optional variables are listed with the defaults values that they take if the argument is omitted.
addGlyph
addLayer
addLine
addNote
addNotehead
addScroller
addStave
addText
clear
clearImage
fade
loadImage
addGlyph(name(s), part(i), x(i), y(i), glyphSize(f)=36.0)
Applies to: canvas, layer, scroller, text, glyph, stave
Adds a music symbol from the bravura font to the object. Name must be a unique identifier: the glyph won’t be created if an object of that name already exists. Part specifies the part to be drawn into, or 0 for the object to be placed in all parts. (If the parent object doesn’t exist in all parts, then this is ignored and this value is instead inherited from the parent object.) Unlike other objects, the x and y position coordinates refer not to the top lefthand corner of the glyph but rather to a sensible point within it (like the centre of a notehead). The size of the glyph is set to 36 if omitted. Creating the glyph does not display anything immediately: the setGlyph command must be used to specify the actual glyph to be loaded.
A selection of some of the avaialable glyphs showing their centre points. These are positioned to allow for much easier and more convenient placement of the glyphs.
The following glyphs are currently available in the player:
addLayer(name(s), part(i), x(i), y(i), width(i), height(i))
Applies to: canvas, layer, scroller, text, glyph, stave
See the addGlyph command for information about the name and part arguments. Adds a layer to the parent object. The x and y position coordinates refer to the location of the top left corner of the layer within the parent object’s coordinate space. Width and height are in pixels. When first loaded, the layer is empty: the loadImage or setColour commands can be used to change this.
The following code example shows the creation of nested layers using two addLayer commands. The colour of the parent layer has been changed, and an image loaded into the child layer to make it easy to distinguish the two.
| #Add a layer called red to our canvas, #and set it to appear in all parts. red = canvas.addLayer('red', 0, 10, 10, 150, 150) red.setColour(255, 0, 0) #Add our bunny layer as a child of our red layer. #Have it appear only in part 1. bunny = red.addLayer('bunny', 1, 20, 20, 100, 100) bunny.loadImage('distortion.png', 1) |
 |
An important thing to note is that child layers can spill beyond the boundaries of their parent layer. While a command may be added later to give the option to change this behaviour, the current behaviour will remain the default in order to maintain backwards compatability. If you do want a child layer to be masked by the boundaries of thier parent, then the easiest way to accomplish this at present is to instead use a scroller as the parent object. This will achieve the desired effect.
addLine(name(s), part(i), x1(i), y1(i), x2(i), y2(i), lineWidth(i))
Applies to: canvas, layer, scroller, text, glyph, stave
See the addGlyph command for information about the name and part arguments. Draws a line on the parent object from the start point (x1, y1) to the end point (x2, y2). The width of the line is given by the lineWidth argument, and the default colour is black.
addNote(pitch(s), position(i), duration(i))
Applies to: stave
Draws a note at the horizontal point on the stave given by the position argument. The pitch is of the form Ax4, where x can be omitted for a note without any accidental or one of the following: ## double sharp, #+ three quarter sharp, # sharp, + quarter sharp, n natural, - quarter flat, b flat, b- three quarter flat, bb double flat. C4 is middle C. The duration can be one of the following: 0 breve, 1 semibreve, 2 minim, 4 crotchet, 8 quaver, 16 semiquaver, 32 demisemiquaver.
The following example code shows the use of the addNote and addNotehead commands to position notes on a stave object.
| #Add a stave to the canvas stave = canvas.addStave('stave', 0, 10, 100, 600, 72, 2) #Need to set a clef before adding notes stave.setClef('treble', 40) stave.addNotehead('C#+4', 120, 1) stave.addNote('Gbb3', 200, 32) stave.setClef('alto', 400) stave.addNotehead('D-5', 500, 0) |  |
Obviously, since notes are placed on the stave using pitches, it is necessary to set a clef for these commands to work. If you want to avoid displaying a clef to the performers, you could either place a layer (containing an image or flat colour) over the top of the clef to mask it, or you can use the addGlyph command to manually position notes and accidentals using coordinates. At present, these commands bluntly place notes where they are told to along the horizontal axis, and do not check to see if this will result in overlap with other notes or accidentals.
addNotehead(pitch(s), position(i), filled(i)=1)
Applies to: stave
See the addNote command for information about the pitch and position arguments, as well as a code example. The filled argument determines whether the notehead is filled (1) or not (0). If omitted, the default is a filled notehead.
addScroller(name(s), part(i), x(i), y(i), width(i), height(i), scrollerWidth(i), scrollerSpeed(f))
Applies to: canvas, layer, scroller, text, glyph, stave
See the addGlyph command for information about the name and part arguments. Adds a scroller to the object with a viewing window whose location and size is determined by the x, y, width, and height arguments. The scrollerWidth sets the width of the scrolling layer that can be set in motion from right to left through the viewing window. The scrollerSpeed specifies how fast the scrolling layer will move in pixels per second. Setting a negative value for this will reverse the direction of the scroller.
addStave(name(s), part(i), x(i), y(i), width(i), height(i), lineWidth(i))
Applies to: canvas, layer, scroller, text, glyph, stave
See the addGlyph command for information about the name and part arguments. Adds a stave to the object. The x and y position coordinates refer to the left end of the top stave line. The width and height specify the length of the stave lines and the distance from the top to bottom stave line respectively. The lineWidth argument sets the width of the stave lines.
For a usage example, see the addNote entry.
addText(name(s), part(i), x(i), y(i), fontSize(f)=36.0)
Applies to: canvas, layer, scroller, text, glyph, stave
See the addGlyph command for information about the name and part arguments. Adds text to the object. The x and y position coordinates refer to the top left corner of the bounding box of the text. If not specified, the fontSize is 36. No text is drawn immediately: the setText command should be used to achieve this.
clear()
Applies to: canvas, stave
When applied to the canvas, this method removes all of the existing objects and any reference to them. When applied to the stave, this method removes all notes and clefs, leaving a blank stave.
clearImage()
Applies to: layer, scroller
Removes the currently loaded image. (This has no effect on any child objects in the layer.)
fade(opacity(f), duration(f))
Applies to: canvas, layer, scroller, text, glyph, stave, line
Sets the opacity of an object and animates the transition over a period of time specified in seconds by the duration argument.
loadImage(imageFile(s), autoSize(i)=0)
Applies to: layer, scroller
Loads an image into the object. The source of the image must be a file that was placed in the current score’s .dsz file at the time of its creation. The autoSize argument is disabled by default. If set to 1 then the object’s size will be altered to accommodate the image. In the case of a scroller object, the height of the scroller and the width of the scrolling layer will be adjusted to fit this. (There is no change made to the width of the viewing window.)
move(x(i), y(i), duration(f))
Applies to: canvas, layer, scroller, text, glyph, stave
Sets the position of an object and animates the transition over a period of time specified in seconds by the duration argument.
remove()
Applies to: canvas, layer, scroller, text, glyph, stave, line
Removes the object from its parent object. All references to the object are removed and it cannot be reused.
removeClef(position(i))
Applies to: stave
Removes the clef at the specified horizontal position on the stave. This is only allowed if doing so doesn’t leave any ambiguous notes or noteheads on the stave. (The leftmost clef cannot be removed unless there are no notes between it and the next clef.)
removeNote(pitch(s), position(i))
Applies to: stave
Removes the note or notehead of the given pitch located at the specified horizontal position on the stave.
setClef(clef(s), position(i))
Applies to: stave
Sets the clef for the given horizontal position on the stave. If a clef already exits at this point then it is replaced, otherwise a new clef is added. The current available clefs are treble, bass, and alto.
setColour(r(i), b(i), g(i), a(i)=255)
Applies to: canvas, layer, scroller, text, glyph, stave, line
Sets the colour of the object. For the canvas and for layers, this is the background colour. For the scroller, it is the background colour of the scrolling layer. For text, glyphs and lines it is the foreground colour of the object. For staves, it currently only sets the colour of the stave lines, although this behaviour may change in future. The colour is specified with red, green, and blue parameters between 0 and 255, with an optional alpha parameter (set to full opacity if omitted.)
setEndPoint(x(i), y(i))
Applies to: line
Sets the end point of the line to the given coordinates.
setFont(fontName(s))
Applies to: text
Sets the font to be used by the text object. A full list of font names on iOS can be found here. Additionally “Bravura” can be supplied as the fontName argument to use the Bravura music font.
setFontSize(fontSize(f))
Applies to: text
Sets the font size of the text object.
setGlyph(glyphType(s))
Applies to: glyph
Sets the music symbol displayed by the glyph. The argument should be the canonical name of the desired glyph as defined in the SMuFL specifications. Only a small subset of these are currently implemented. (Mostly basic clefs, accidentals, and notes.) If the wanted glyph is not available an unknown glyph message will be returned.
setGlyphSize(glyphSize(f))
Applies to: glyph
Sets the size of the glyph. The command will make the glyph an appropriate size for a stave of the height given by the glyphSize argument.
setLineWidth(lineWidth(i))
Applies to: stave
Sets the width of the stave lines in pixels.
setOpacity(opacity(f))
Applies to: canvas, layer, scroller, text, glyph, stave, line
Sets the opacity of the object. 0 is entirely transparent, 1 is fully opaque.
setPosition(x(i), y(i))
Applies to: canvas, layer, scroller, text, glyph, stave
Sets the position of the object within the coordinate space of the parent object.
setScrollerPosition(scrollerPosition(i))
Applies to: scroller
Sets the position of the scrolling layer. This value specifies which horizontal point on the scrolling layer should align with the leftmost edge of the viewing window. When set to 0, the left edge of the scrolling layer is aligned with the left edge of the viewing window. Increasing the value offsets it to the left. The maximum value this can take is the width of the scroller layer: at this value, the layer is hidden just off to the left of the viewing window. The minimum value it can take is the negative of the viewing window width: at this value the scroller layer is hidden just off to the right of the viewing window.
setScrollerSpeed(scrollerSpeed(f))
Applies to: scroller
Sets the rate at which the scrolling layer moves through the viewing window, in pixels per second. A positive value sees the scrolling layer move to the left. A negative value sees it move to the right.
setScrollerWidth(scrollerWidth(i))
Applies to: scroller
Sets the width of the scrolling layer.
setSize(width(i), height(i))
Applies to: layer, scroller, stave
Sets the size of the object, given by the width and height arguments.
setStartPoint(x(i), y(i))
Applies to: line
Sets the starting point of the line to the given coordinates.
setText(text(s))
Applies to: text
Sets the string of text to be displayed by the text object. Unicode characters are permitted.
setWidth(width(i))
Applies to: line
Sets the width of the line in pixels.
start()
Applies to: scroller
Sets the scroller layer in motion.
stop()
Applies to: scroller
Stops the animation of the scroller.
Copyright © Aaron Wyatt, 2019, with contributions to the project from Cat Hope, Lindsay Vickery, and Stuart James. The bunnies used in the canvas test score have been taken from Kim Krans’ artwork for the cover of Tape Op. issue #88.