Toolkit Actions

A summary of Verovio editor actions

Verovio receives editor actions from Neon in the form of JSON objects composed of two main parts: an action and its parameters. What parameters an action takes entirely depends on the action being performed. Here is a brief summary of the different JSON objects Neon sends to Verovio.

Drag

A drag JSON action is formatted as follows:

{
    "action": "drag",
    "param": {
        "elementId": "m-1234-5678",
        "x": 12,
        "y": 34
    }
}

Here is what the parameters mean:

• "elementId": The unique ID of the element being dragged. This ID is either provided as the xml:id attribute of the element in the MEI file or is generated by Verovio. It is the same ID as the <g> tag for this element.
• "x": The change in x-position for the element being dragged, in SVG units.
• "y": The change in the y-position for the element being dragged, in SVG units.
  • Note that the coordinate system has an upward-facing y-axis. That is, moving an element towards the top of the window has a positive y value.

Resize

A resize JSON action (for bounding boxes and staves only) is formatted as follows:

{
    "action": "resize",
    "param": {
        "elementId": "m-1234-5678",
        "ulx": 1,
        "uly": 2,
        "lrx": 3,
        "lry": 4
    }
}

Here is what the parameters mean:

• "elementId": The unique ID of the element being resized. For staves this id is the id of the stave, for bounding boxes this is the id of the ''
• "ulx": The new Upper Left X coordinate for the staff/bounding box in SVG units.
• "uly": The new Upper Left Y coordinate for the staff/bounding box in SVG units.
• "lrx": The new Lower Right X coordinate for the staff/bounding box in SVG units.
• "lry": The new Lower Right Y coordinate for the staff/bounding box in SVG units.

Resize Rotate Action

A resize rotate JSON action is formatted as follows:

{
    "action": "resizeRotate",
    "param": {
        "elementId": "staffId",
        "ulx": 1,
        "uly": 2,
        "lrx": 3,
        "lry": 4,
        "rotate": 0
    }
}

Here is what the parameters mean:

• "elementId": The unique ID of the element being resized. For staves this id is the id of the stave, for bounding boxes this is the id of the ''
• "ulx": The new Upper Left X coordinate for the staff box in SVG units.
• "uly": The new Upper Left Y coordinate for the staff box in SVG units.
• "lrx": The new Lower Right X coordinate for the staff box in SVG units.
• "lry": The new Lower Right Y coordinate for the staff box in SVG units.
• "rotate": The new rotate of the rect in radians.

Insert

An insert JSON action is formatted as follows:

{
    "action": "insert",
    "param": {
        "elementType": "type",
        "staffId": "ID or auto",
        "ulx": "1234",
        "uly": "1234",
        "lrx": "1234",
        "lry": "1234",
        "attributes": {
            "key": "value"
        }
    }
}

Here is what the parameters mean:

• "elementType": The type of element to insert. This is either "nc" (neume component), "clef", "staff", or "custos".
• "staffId": The xml:id or ID of the <g> tag of the staff to place this new element on. If set to "auto", then Verovio will find the closest staff to the point where the element is to be inserted. If another staff is being inserted, then this is the staff whose attributes (number of lines, notation type, etc.) will be used as a base for the new staff.
• "ulx": The absolute x-position of the element to be inserted, in SVG units. This will be the Upper Left X position of the glyph.
• "uly": The absolute y-position of the element to be inserted, in SVG units. This will be the Upper Left Y position of the glyph.
• "lrx": The lower right x-position of the element to be inserted. Only for staff insertion.
• "lry": The lower right y-position of the element to be inserted. Only for staff insertion.
  • Note that here "ulx" and "uly" define a point in the SVG coordinate system. That is, the upper left corner of the SVG is the origin.
• "attributes": An optional parameter containing a set of key-value pairs to define attributes of the new element. Not all attributes are supported, and for some element types insertion may fail if a required attribute is unspecified.
  • For "nc" (neume component), an inclinatum can be added with the key-value pair "tilt" and "se" and a virga can be added with the key-value pair "tilt" and "n".
  • For "custos", no attributes are currently supported.
  • For "clef", the key "shape" must be specified with the shape of the clef to add. Accepted values are "C" and "F". If shape is not given, clef insertion will fail.
  • For "staff", no attributes are currently supported.

Insert to Syllable

An insert JSON action is formatted as follows:

{
    "action": "insertToSyllable",
    "param": {
        "elementId": "m-1234-5678"
    }
}

All this requires is the ID of the element to be inserted into the nearest syllable. The supported elements include divLine and accidentals (Clef coming up).

Remove

A remove JSON action is formatted as follows:

{
    "action": "remove",
    "param": {
        "elementId": "m-1234-5678"
    }
}

All this requires is the ID of the element to remove. Then it will simply delete it from Verovio (or fail if no such element exists or is able to be deleted).

Group

Group allows you to group neume components into neumes and neumes into syllables and is formatted as follows:

{
    "action":"group",
    "param": {
        "groupType": "neume or nc",
        "elementsIds": ["id1", "id2"]
    }
}

Here is what the parameters mean:

• "groupType": "neume" or "nc". A string that specifies if we are grouping neumes or neume components.
• "elementIds": A string array of the unique ids of the elements to be grouped together.

Ungroup

Ungroup allows you to to ungroup a syllable with several neume children into several syllables, each with a single neume child. Similarly, you can ungroup a neume with several neume component children into a several neumes, each with a single neume component child. It is formatted as follows:

{
    "action":"ungroup",
    "param": {
        "groupType": "neume or nc",
        "elementsIds": ["id1", "id2"]
    }
}

Here is what the parameters mean:

• "groupType": "neume" or "nc". A string that specifies if we are creating individual neumes (from syllables) or individual neume components (from neumes).
• "elementIds": A string array of the unique ids of the elements to be ungrouped.

Set

A set JSON action is formatted as follows:

{
    "action": "set",
    "param": {
        "elementId": "m-1234-5678",
        "attrType": "xmlAttribute",
        "attrValue": "xmlValue"
    }
}

Here is what the parameters mean:

• "elementId": The unique ID of the element being dragged, corresponding to the xml:id in the MEI file and the id attribute of the <g> tag in the rendered SVG.
• "attrType": The valid attribute name for this element as it would appear in a valid MEI file.
• "attrValue": The value of this attribute as a string.

Merge Systems

A merge system JSON action moves each element of the staves whose IDs are given to the first based on page order.

{
    "action": "merge",
    "param": {
        "elementIds": [
            "staffId1",
            "staffId2",
            "staffId3"
        ]
    }
}

The element IDs are the unique element ID of staves. Putting an ID that is not from a staff element will cause the merge to fail. The order of these IDs does not matter. The ID of the staff that inherits the other staff elements will be returned in the Edit Info.

Split Staff

A split action splits a staff into two separate staves on a certain x-axis coordinate.

{
  "action": "split",
  "param": {
    "elementId": "staffId",
    "x": 1234
  }
}

Musical elements on the staff left of the x-coordinate belong to the left staff. Musical elements to the right belong to the right staff.

Split Neume

A split neume action splits a neume into two separate neumes on a certain neume component.

{
  "action": "splitNeume",
  "param": {
    "elementId": "m-1234-5678",
    "ncId": "ncId"
  }
}

Neume components before the given neume component belong to the former neume. The given neume component and the neume components after it belong to the latter neume.

Set Syl Text

This action sets the text of a syl tag in a syllable element. The elementId must be the ID of either the <syl> itself or the parent syllable element.

{
  "action": "setText",
  "param": {
    "elementId": "sylOrSyllableId",
    "text": "text content"
  }
}

Set Clef

This action updates the shape of a clef.

{
  "action": "setClef",
  "param": {
    "elementId": "clefId",
    "shape": "newShape"
  }
}

Toggle Ligature Action

This will toggle the ligated attribute on two <nc> elements provided in an array.

{
  "action": "toggleLigature",
  "param": {
    "elementIds": [ "firstNc", "secondNc" ]
  }
}

Change Skew

This adjusts the skew angle of a bounding box of a staff element. This is done using the change in the y-direction in a device context (i.e. positive-y is down) and the side of the staff being moved.

{
  "action": "changeSkew",
  "param": {
    "elementId": "id-of-staff",
    "dy": -42,
    "rightSide": true
  }
}

The above action would adjust the skew of the staff with ID id-of-staff by moving the right side of it in the negative-y direction by 42 units. This would also update upper left and lower right points in the facsimile for this element.

Change Staff

This re-associates an element to the nearest staff. If the pitch of it or any other elements needs to change to stay in the same position that will also occur. It logs a warning (but doesn't fail) if the element is already part of the staff it is closest to.

{
  "action": "changeStaff",
  "param": {
    "elementId": "id-of-element",
  }
}

Edit Info

Verovio also has a function under the editor toolkit called EditInfo. This gives us access to more information about the action performed than whether or not it succeeded. As of now, this only provides any information for the insert action, where it contains the ID of the new element. This makes it easier to locate the new element, especially when Neon is being used in a headless environment.

Chain Action

The chain action is actually a way of sending multiple other actions to Verovio in a single call. It returns true if every action is run successfully, and false otherwise. The EditInfo result is a JSON array of the results of the actions in order. An arbitrary number of actions can be chained. Attempting to put a chain action within a chain may have unexpected behavior.

{
    "action": "chain",
    "param": [
        {
            "action": "remove",
            "param": {
                "elementId": "m-1234-5678"
            }
        },
        {
            "action": "insert",
            "param": {
                "elementType": "type",
                "staffId": "ID or auto",
                "ulx": "1234",
                "uly": "1234",
                "attributes": {
                    "key": "value"
                }
            }
        }
    ]
}

Note that unlike regular actions, the param key of a chain action is actually an array and not an object.