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.

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-posiiton of the element to be isnerted, 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 "diagonalright" and "u" and a virga can be added with the key-value pair "name" and "inclinatum".
  • 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".
  • For "staff", no attributes are currently supported. If shape is not given, clef insertion will fail.

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": "Ids"
    }
}

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": "Ids"
    }
}

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.

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.