SVG Score Extensions


This document describes the SVG extensions that are written and read by the latest versions of my Assistant Composer and Assistant Performer software.
It is being tracked in the Assistant Performer's GitHub repository at https://github.com/notator/assistant-performer.

N.B.: this document is not currently up to date (22.03.2017). For the current description, see Moritz' issue#2.


This version introduces continuous controller settings (ccSettings), that can be attached to Input Chords.
It also contains a major revision of the trkOptions.

Status of this document: Moritz' Assistant Composer application writes the file format, and its code is therefore the final authority. The Assistant Performer is tested exhaustively with scores created by the latest version of the Assistant Composer, and both programs are changed if any difficulty arises. So, those two programs should agree on the file format.
This document is kept up to date, but if there is any discrepancy between the programsí code and this document, this document should be updated accordingly. It was last checked in March 2016.
Unanswered question: (see trkRef.msPosition) In all the test scores until now, Input Chords are aligned vertically with the first Output Chord in the Trks to which they refer. But is that always necessary? Could a Trk's msPositionInScore actually be different from that of its containing InputChord ? If that were possible, would there be any useful consequences?



Document conventions:
Elements that are SVG <g> elements with a class attribute are written in normal italics.
    For example: an OutputStaff is: <g class="outputStaff" ...>...</g> in the SVG.
Elements and attributes that are members of the score namespace are written in blue code.
    For example: OutputVoice has a score:midiChannel attribute.
The namespace is omitted inside elements that are themselves inside the score namespace.
    For example:score:midiChord contains a basicChords element.

There is a complete, more formal description of the extensions below, but first a broad summary:

Summary (March 2016)

At the top level, a System contains one or more OutputStaff, and zero or more InputStaff elements.
An OutputStaff contains one or two Output Voice elements, which in turn contain Output Chord and Rest elements.
Each Output Chord contains a midiChord element containing midi information that is ultimately sent to a midi output device.

The Assistant Performer deals with Track objects. A Track contains the complete sequence of midi chord and rest objects for a particular midiChannel in the score, and is constructed from the midiChords and Rests in OutputVoices that are at the same vertical position in successive Systems in the score. Such OutputVoices have the same score:midiChannel.
A Trk is a subsection of a Track, and contains a limited sequence of chords and rests. Names such as trkReftrkOptions, trkOffs. etc. refer to Trks.

Input Staff elements contain one or two Input Voices, which in turn contain Input Chords and Rests. Each Input Chord contains a list of inputNote elements. inputNote elements handle midi information coming from a midi input device. Each Input Chord can also contain a ccSettings and/or a  trkOptions element.

A ccSettings element is a switch that defines the behaviour of the standard midi keyboard continuous controllers (pressure, pitchWheel and modWheel), with respect to each output track, from this point on in a performance. (The Assistant Composer never writes synchronous ccSettings.) The behaviour can be different for different output tracks. The Assistant Performer treats controllers individually within the ccSettings: If a particular controller is not set for a particular track, the current setting persists.
The Assistant Performer's default, before the score is loaded, is for all three controllers to be switched off for all tracks.

A trkOptions element defines options that are applied to a Trk before a performance begins. The trkOptions that apply are the result of cascading the trkOptions in the Input Chord, inputNote, noteOn, noteOff, seq and trkRef elements (see below). The Assistant Performer does the cascading, and overrides higher level options individually. It also persists the  trkOptions defined in an Input Chord, as if they are defined in all subsequent Input Chords until the next Input Chord that contains an explicit trkOptions element. The persistence over time is also handled individually per option.
The Assistant Performer's default trkOptions are such that the score plays as written in the OutputVoices.

An inputNote element can contain a trkOptions and/or a noteOn and/or a noteOff element.
noteOn, and noteOff elements can contain a trkOptions and/or a seq and/or a trkOffs element.
A seq element can contain a trkOptions element, and it must contain a list of trkRef elements.
A trkRef defines a Trk (a section of an output track). It can contain a trkOptions element, and must have the following attributes:  midiChannel , msPosition , nMidiObjects.
A trkOffs element defines an output track to which a trackOff message will be sent when the input noteOn or noteOff arrives. A trkOffs element has a single attribute (midiChannels) which is a string of midi channel indices separated by space characters.

This file definition allows very complex output events to be triggered using single noteOn and noteOff input events, but it also allows a single noteOn to trigger a single one-note midiChord — which would be like playing a "prepared piano", except that the preparation can change during the performance.
Different scores can be created for performing the same output information at different levels of control. Recordings are performed by pressing a single button. Piano pieces are traditionally played by pressing a single key for each note...


Namespace

These extensions are contained in the following namespace:
xmlns:score="http://www.james-ingram-act-two.de/open-source/svgScoreExtensions.html"

SVG <g> elements defining container types

Definition: An msDuration is an absolute millisecond duration. msDurations are stored in the score as score:msDuration values, and are are used to define the durations in default performances (i.e. when there is no live performer).
An msDuration is also used to calculate an object's msPositionInScore (the position in absolute milliseconds from the beginning of the score). Objects in different voices that have the same msPositionInScore are vertically aligned in space, and are always synchronous in default performances. In live performances, however, they may not be synchronous since Trks are then being used, and there is a trkOption.speed, that allows parallel Trks to be played at different speeds. (This is possible, because Tracks are played in different threads in live performances.)

The following SVG <g> elements contain both graphics and special types defined in the score: namespace (see below).
These elements all have a class attribute that will be used by the Assistant Performer to identify their type.
System
Attributes
class "system"
Content
<g.../g>... A list of one or more <g.../g> Output Staff elements (class="outputStaff").
<g.../g>... A list of zero or more <g.../g> Input Staff elements (class="inputStaff").
<g.../g> A list of staff connectors (vertical lines) in a single group. (class="staffConnectors")
Output Staff
Attributes
class "outputStaff"
score:staffName A string (e.g. "Flute") which is the name of the staff.
score:invisible This attribute can only be present if the staff is invisible (i.e. the staff contains no graphic information). This attribute is just a debugging convenience. It is not needed (and should not be used) by the client software. If present, its value is always "1".
See the score:staffName attribute.
Content
<g.../g> A list of stafflines (horizontal lines) in a single group. (class="stafflines")
<g.../g> An Output Voice element (class="outputVoice") (see below). There must be at least one Output Voice.
<g.../g> An optional second Output Voice element (class="outputVoice").
Moritz does not support more than two Output Voices per Output Staff.
Output Voice
Attributes
class "outputVoice"
score:midiChannel The (zero-based) MIDI channel index.
The Output Voices in a score are always notated in Output Staffs above the Input Staffs. Each Output Voice has its own MIDI channel, and the MIDI channels are always in increasing order, from top to bottom of the Output Voices in the score, starting at 0.
score:voiceID This value is used by inputNote elements to identify the Output Voices to which they refer. This attribute, which is only written to the file if there are Input Voices in the score, is necessary because Output Voices can be printed in a top-bottom order that is different from the order in which they were composed.
score:masterVolume This value is used to initialize the volume of this Output Voice's MIDI channel at the beginning of a performance. This attribute is always written to Output Voices in the first bar of the score, but nowhere else.
Content
<text>...</text> The voice's name (printed to the left of the voice). (class="staffName")
<use.../> A clef. (class="clef")
<g.../>... One or more SVG <g> elements and <line.../> elements in left to right order in the score.
The <line.../>s are barlines that extend from the top to the bottom staffline in the staff (class="barline").
The <g.../> objects can be
Output Chords (class="outputChord")
Rests (class="rest")
and
Cautionary Chords (class="cautionaryChord")
ClefChangeSymbols (class="clefChange")
BeamBlocks (class="beamBlock")
(These last three objects contain no temporal performance information. The opacity of the Output Voiceís entire graphic content is toggled by the Assistant Performer to indicate whether the voice is performing or not.)
Output Chord
Attributes
class "outputChord"
score:alignmentX Optional Float: written only if the OutputChord is on a visible staff.
The x-coordinate at which the chord symbol is aligned in the score.
This is the number of pixels from the left edge of the SVG's viewBox. The alignment coordinate is needed for user interaction with the score, but it is not easily retrieved from the information in the chord’s graphic components.
Content
score:midiChord One object of this type (see below).
<g>...</g> an SVG graphics group (class="graphics").
Input Staff
Attributes
class "inputStaff"
score:staffName A string (e.g. "Input1") which is the name of the staff.
Content
<g.../g> A list of stafflines in a single group. (class="stafflines")
<g.../g> An Input Voice element (class="inputVoice") (see below). There must be at least one Input Voice in an Input Staff
<g.../g> An optional second Input Voice element (class="inputVoice").
Moritz does not support more than two Input Voices per Input Staff.
Input Voice
Attributes
class "inputVoice"
score:midiChannel Optional. The channel index of the midi input device that will trigger events in this Input Voice. If not present, the midi input device's channel is ignored, and all incoming midi events trigger events in this Input Voice.
Content
<use.../> A clef.
<text>...</text> The voice's name (graphics, printed to the left of the voice.).
<g.../>... One or more SVG <g> elements and <line.../> elements in left to right order in the score.
The <line.../>s are barlines that extend from the top to the bottom staffline in the staff (class="barline").
The <g.../> objects can be
Input Chords (class="inputChord")
Rests (class="rest")
and
Cautionary Chords (class="cautionaryChord")
ClefChangeSymbols (class="clefChange")
BeamBlocks (class="beamBlock")
(These last three objects contain no temporal performance information. The opacity of the Output Voiceís entire graphic content is toggled by the Assistant Performer to indicate whether the voice is performing or not.)
Input Chord
Attributes
class "inputChord"
score:alignmentX Optional Float: written only if the InputChord is on a visible staff.
The x-coordinate at which the chord symbol is aligned in the score.
This is the number of pixels from the left edge of the SVG's viewBox. The alignment coordinate is needed for user interaction with the score, but it is not easily retrieved from the information in the chord’s graphic components.
score:msDuration Integer: The msDuration in the score of this Input Chord.
This value is used by the Assistant Performer to calculate the Input Chord's msPosition, which is the msPosition of the Trks to which the Input Chord points.
Each Input Chord is has the same msPosition as (and is vertically aligned to) its related Trks.
Remarks:
1. Input Voices contain no output information, so they are ignored in default performances. This means that Input Chord msDurations are never converted to real milliseconds.
2. It would have been possible to have had an msPosition attribute here, but the Assistant Performer calculates the msPositions of all Output Chords and Rests anyway (so that it can send simultaneous Output Chords in different voices simultaneously). The Assistant Performer software therefore becomes simpler if Input Chords are not treated differently here.
score:lyric Optional. A lyric string
Content
score:ccSettings Optional. One element of this type. Defines the behaviour of the standard midi keyboard continuous controllers (pressure, pitchWheel and modWheel), with respect to each output track, from this point on in a performance.
The Assistant Performer's default, before the score is loaded, is for all three controllers to be disabled for all tracks.
score:trkOptions Optional. If present, changes the current input track's trkOptions settings to the result of cascading these settings over the current settings. All settings are cascaded individually.
The Assistant Performer's default trkOptions settings are such that the score plays as defined in its OutputVoices.
score:inputNotes One element of this type. A outputSequence of inputNote.
<g>...</g> an SVG graphics group (class="graphics").
Rest
Attributes
class "rest"
score:alignmentX Optional Float: written only if the rest is on a visible staff.
The x-coordinate at which the chord symbol is aligned in the score.
This is the number of pixels from the left edge of the SVG's viewBox. The alignment coordinate is needed for user interaction with the score, but it is not easily retrieved from the information in the chord’s graphic components.
score:msDuration Integer: the msDuration in the score of the Rest .
This is the millisecond duration of the Rest in default performances.
Content
<text>...</text> The rest character (graphics).


The score: namespace

(The score: prefix is omitted whenever an attribute or element is contained by an existing element in the namespace.)
score:msDuration An integer (greater than 0): The msDuration of a Rest or Input Chord.
Output Chord msDurations are calculated from the msDurations of their score:basicChords.
score:midiChord Contained in Output Chord elements
Attributes
hasChordOff Optional. 0 = false, 1 = true. Default is true.
pitchWheelDeviation Optional. MIDI pitch wheel deviation. [0..127]
Coarse control byte only. Default is no change (i.e. the channel setting is changed permanently).
minBasicChordMsDuration Optional. The minimum duration of a of a basicChord in this score:midiChord. Default is 1.
Content:
basicChords See below. This element must exist.
sliders Optional. See below.
basicChords Contained in score:midiChord elements
Attributes  none
Content A outputSequence of basicChord elements. The outputSequence must exist, and it must contain at least one basicChord.
basicChord Contained in basicChords elements
Attributes
msDuration Obligatory. An integer.
bank Optional. MIDI bank index. [0..127]. Default is no change.
Overrides score:midiChord.bank.
patch Optional. MIDI patch index. [0..127]. Default is no change.
Overrides score:midiChord.patch.
hasChordOff Optional. 0 = false, 1 = true. Default is true.
pitches Obligatory. A series of one or more integers in range [0..127] separated by spaces. The numbers are MIDI note numbers in ascending order.
velocities Obligatory. A series of integers in range [0..127] separated by spaces.
The numbers are MIDI velocities corresponding to the MIDI notes.
Content none
sliders Contained in score:midiChord elements
Optional. If the sliders element is present then it has one or more of the attributes below, each of which defines an envelope:
The first integer in each series is the value of the controller at the beginning of the envelope, the last integer is the value of the controller at the end of the envelope. Between these, there can be any number of values, which are distributed at equal intervals across the envelope.
Attributes
pitchWheel Optional. A series of integers in range [0..127] separated by spaces.
The numbers are "coarse adjust" values for The MIDI pitchwheel control.
pan Optional. A series of integers in range [0..127] separated by spaces.
The numbers are "coarse adjust" values for The MIDI pan position control.
modulationWheel Optional. A series of integers in range [0..127] separated by spaces.
The numbers are "coarse adjust" values for The MIDI modulation wheel control.
expressionSlider  Optional. A series of integers in range [0..127] separated by spaces.
The numbers are "coarse adjust" values for The MIDI expression control.
Content none
score:ccSettings Contained in Input Chord elements. Optional.
Defines the behaviour of the standard midi keyboard continuous controllers (pressure, pitchWheel and modWheel), with respect to each output track, from this point on in a performance. (The Assistant Composer ensures that there is never more than one ccSettings element at a particular msPositionInScore.) Different output tracks can react differently to the continuous controllers. The Assistant Performer treats controllers individually within the ccSettings: If a particular controller is not set for a particular track, the current setting persists.
The Assistant Performer's default, before the score is loaded, is for all three controllers to be disabled for all tracks.
Attributes none
Content
An optional default element and/or one or more track elements.
A default element defines settings for all the output channels.
A track element provides settings for a particular output channel, overriding the default element settings (if present).
Attributes:
track elements have a midiChannel attribute (an integer, in range 0..15),
otherwise the attributes are the same in both cases:
Attribute possible values
pressure
"disabled", "aftertouch", "channelPressure", "modulation", "volume", "expression", "timbre", "brightness", "effects", "tremolo", "chorus", "celeste", "phaser"
pitchWheel "pitch", "pan", "speed"
modWheel same as pressure (see above)
maxVolume An integer in range 1..127. This attribute is only present when either the pressure or modWheel is set to "volume".
minVolume An integer greater than 0 and less than maxVolume. This attribute is only present when either the pressure or modWheel is set to "volume".
pitchWheelDeviation An integer in range 0..127. This attribute is only present when pitchWheel is set to "pitch".
The number of semitones by which the pitch glissandos upwards when the pitchWheel is moved from its middle position to its maximum position.
panOrigin An integer in range 0..127. This attribute is only present when pitchWheel is set to "pan".
The pan position associated with the pitchWheel's middle position.
speedDeviation A floating point number >= 1. This attribute is only present when pitchWheel is set to "speed".
Maximum speed is when durations = durations / speedDeviation
Minimum speed is when durations = durations * speedDeviation
Neither default elements nor track elements have content.
score:inputNotes Contained in Input Chord elements
Attributes none
Content
A outputSequence of one or more inputNote elements.
This list may not be empty.
inputNote Contained in score:inputNotes elements
Attributes
:
notatedKey Compulsory. The midi value of the notated key (the notehead).
Content:
noteOn Optional. Things to do when this inputNote's noteOn arrives.
noteOff Optional. Things to do when this inputNote's noteOff arrives.
trkOptions Optional.
noteOn and noteOff Contained in inputNote elements
Attributes: none
Content:
seq Optional. A group of trkRefs.
trkOffs Optional.
trkOptions Optional in noteOn, not present in noteOff.
seq Can be contained in both noteOn and noteOff elements. 
Attributes: none
Content:
trkRef One or more of these.
trkOptions Optional in noteOn, not present in noteOff.
trkRef Contained in noteOn and noteOff elements. 
Attributes:  
midiChannel The Trk's midiChannel.
msPosition The msPositionInScore of the first chord or rest in the Trk. Question: can this value be different from the msPositionInScore of the containing InputChord ?
nMidiObjects The total number of chords and rests in the Trk.
Content:  
trkOptions Optional.
trkOffs Can be contained in noteOn and noteOff elements.
Attributes
midiChannels Compulsory. A string containing space-separated integers that are the channels to be sent TrkOff messages.  The integers are in range 0..15.
Content none
trkOptions Optionally contained in Input Chord, inputNote, noteOn, noteOff, seq and trkRef elements.
Unlike the ccSettings, these options are applied to a Trk before a performance begins.
The trkOptions that apply are the result of cascading the trkOptions in the above elements. The Assistant Performer does the cascading, and overrides higher level options individually. It also persists the  trkOptions defined in an Input Chord, as if they are defined in all subsequent Input Chords until the next Input Chord that contains an explicit trkOptions element. The persistence over time is also handled individually per option.
The Assistant Performer's default trkOptions are such that the score plays as written in its OutputVoices.
Attibutes:  
velocity Optional. A string describing how the velocity value of a received noteOn is to be used. Default is to use the velocity notated in the score.
velocity values can be:
  • "undefined" - the velocity notated in the score is used. this can be used to override another velocity setting in the cascade.
  • "scaled" - the velocities defined in the score are scaled depending on the value of the performer's velocity (corrrected for minVelocity).
  • "shared" - the velocity will be half the velocity notated in the score, plus half the (corrected) performer's velocity.
  • "overriden" - the velocity will be the (corrected) performer's velocity. Velocities notated in the score will be ignored.
minVelocity Is present only if velocity is present and not set to "undefined". This is then the minimum velocity value that can be sent to any midi channel.
minVelocity is always in range [1..127].
pedal Optional. A string describing what happens when a noteOff is received while the Seq is playing. Default is the current value of this option in the midi input channel. The noteOnVel options are always taken into account.
Values can be:
  • "undefined" - turns this option off. The Trk will play as written in the score.
  • "holdLast" - removes noteOffs from the Trk's last moment that contains any, and don't send allNotesOff.
  • "holdAll" - removes all noteOff messages from the Trk, and don't send allNotesOff.
  • "holdAllStop" - like holdAll, but sends AllNotesOff when the track stops (or is stopped).
speed Optional. An floating point number greater than 0.
This is the factor by which to divide the durations written in the score before the performance begins.
Default is for durations to be performed as written in the score (i.e. speed=1). Setting speed=2 doubles the speed (i.e. halves the durations).
trkOff Optional. A string that describes what happens when the Trk recieves a TrkOff message while it is playing.
  • "undefined" - turns this option off. The Trk will not stop, but play as written in the score until it completes.
  • "stopChord" - stop when the current chord or rest completes.
  • "stopNow" - stop immediately, even inside a chord.
  • "fade" - fade the velocity until the end of the track.

Content: None.

Notes (January 2016)


ji ó www March 2016