Instructions

Single- and Multi-Page Modes

Neon supports loading a single page of a manuscript or multiple pages, with different requirements for each. Single page mode associates an image file, typically a PNG, with a single MEI file corresponding to the page. Multi page mode instead associates multiple MEI files with multiple canvases present in a IIIF manifest.

These modes load automatically depending on what is provided to Neon. After Neon starts, there are minimal differences between these two modes. Neon gets the information it needs using a Neon Manifest. Typically this does not need to be manually generated.

Using Neon

This page contains instructions on how to use Neon's tools. Detailed video instructions for each step of the correction process can be found here:

Neon tutorial - Display options

Neon tutorial - Editing staves

Neon tutorial - Editing neumes

Neon tutorial - Editing syllables

Neon tutorial - Bonus tips'n'tricks

Viewing and display options

To the left is a view panel, which will contain the source image(s) and any rendered MEI. In multi-page mode, the view panel is the diva.js viewer. To the right is a display panel.

View Panel

The view panel has interactive features in viewer mode.

• Panning - The user can move the image and rendered MEI in all four directions.
  • In single-page mode, holding the Shift key, clicking, and dragging will result in panning.
  • In multi-page mode, scrolling will result in panning. Note that holding shift and scrolling vertically will cause horizontal scrolling.
• Zooming - The user can zoom in or out on the contents of the view panel.
  • In single-page mode, this can be done by holding the Shift key and scrolling or by using the + and - keys. There is also a zoom slider in the display panel.
  • In multi-page mode, this can be done by double clicking on the contents to zoom in. Zooming out can be done by holding the Ctrl key and double clicking. There are also zoom in and zoom out buttons near the top left of the diva.js viewer.

Display Panel

The display panel consists of various tools and options to aid in visualization, as well as a report on the status of the MEI file of the active page. The active page is whatever page occupies most of the view panel in multi-page mode. In single-page mode, it is always the one page.

• Zoom Slider - The zoom slider allows the user to scale the image between 25% and 400% its original size. The button with the circling arrow resets the zoom to 100% and snaps the image to centre and the button with a square frame sets to zoom to 180, which shows the full width of the folio image.
  • The zoom slider is only present in single-page mode.
• Opacity Sliders - Two opacity sliders are present to control the opacity of the background image(s) and the rendered MEI file(s). Opacity ranges from 0% to 100%. The buttons with an eye toggle between 0% and 100% opacity for their respective slider.
  • The "Glyph Opacity" button and slider control the opacity of the rendered MEI.
  • The "Image Opacity" button and slider control the opacity of the background image(s).
• Display Text - When checked, lyrics from the MEI file are rendered (if available). For more information, see information on lyrics.
• Display Text BBoxes - When checked, bounding boxes for text will be rendered in the view panel. For more information, see information on lyrics.
• Display Info - When checked, the Info Box is visible below any panels on the right side of the screen. Mousing over any MEI element will make a description of it appear in the Info Box. This will provide the pitch of the element, if applicable, or the staff line it appears on.
  • For neumes, Neon will attempt to determine the shape of the neume via its contour.
  • For clefs, Neon will report whether it is a C or F clef.
• Highlight - A dropdown menu allows the user to highlight different musical elements in different colours. The colour scheme is based on how elements are grouped in the MEI file. The highlight colours will always appear in the same order: pale orange, pale blue, green, yellow, blue, orange, pink. While looking pretty and helping distinguish the MEI from the background, it is also extremely useful for verifying that each element is logically part of the correct system, grouping, etc.
  • There are four basic highlight modes in Neon: highlight by syllable, neume, staff, and layer element. There is also a highlight by selection mode, which is only available in the Edit mode. In the highlight by layer element mode, clefs, custodes, divisiones, and accidentals will be highlighted. In the highlight by selection mode, the highlight mode will be changed according to the selection mode. Note that both select by neume and select by neume component mode will trigger highlight by neume mode.
• MEI Validation - If the active page has an associated MEI file, xml.js is used to validate the loaded MEI file against the MEI 5.0.0-dev schema. If validation fails, clicking on "INVALID" will download a log of the errors found in the file.

Edit and Insert Modes

Differentiating Edit and Insert Modes

In edit mode, the heading of the edit panel is tinted blue and the text is underlined. In insert mode, the heading of the insert panel is tinted blue and the text is underlined.

Insert Panel

The insert panel provides access to the various kinds of musical elements that can be inserted into the active page. Clicking on the image of one of these elements will cause Neon to enter insert mode. In insert mode, the selected insert element is inserted where the user clicks on the view panel. The musical elements that can be inserted are grouped into tabs:

• Primitive Elements
  • Allows insertion of neume components (punctum, virga, reversed virga, inclinatum, liquescents), clefs (C, F), custodes, accidentals (flat, natural), and divisiones.
  • The element is inserted centered around where the user clicks and snaps to the nearest pitch position of the system.
  • For clefs, the element is inserted to the nearest line to where the user clicks.
• Groupings
  • Allows insertion of common grouped neumes.
  • The grouping is inserted with the first neume component centered on where the user clicks.
• System
  • Allows the insertion of a new staff.
  • The system is inserted in-order (by left-to-right and top-to-bottom ordering).
  • This insert action requires two clicks: the first click selects the upper left corner of the new system, and the second click selects the lower right corner of the system.

Every type of insert action except system will not cause Neon to exit insert mode. In all cases, a user can leave insert mode and enter edit mode by:

• Pressing the Escape key on the keyboard;
• Clicking outside of the view panel and the insert panel; or
• Clicking on the "Return to Edit Mode" button below the edit panel.

Edit Panel

The edit panel contains buttons to control what to select by. Note that clefs, custodes, accidentals and divisiones can be selected when selecting by syllable, neume, or neume component. For more information on selecting, see the selection section.

• Syllable - Select by the <syllable> tag in MEI.
• Neume - Select by the <neume> tag in MEI.
• Neume Component - Select by the <nc> tag in MEI.
• Staff - Select by the <staff> tag in MEI.
• BBox - Select by Text Bounding Box, tied to the <syl> tag in MEI.
  • Only visible when Display Text BBoxes is checked. See Text Viewing and Editing
• LayerElement - Select by the <clef>, <custos>, <accid>, and <divLine> tag in MEI.

Selecting Elements

Musical elements can be selected in one of five ways: syllable, neume, neume component, staff, or layer element. Selected elements are highlighted in red. Elements can only be selected in edit mode.

Tips: Layer elements can also be selected in Select by syllable, neume, or neume component mode.

Whenever any selection is made, extra actions will appear below the edit panel. A "Delete" button will always appear, which deletes the selected elements. Other actions are made available if they are applicable given the selection made.

The user can select elements in two ways: by clicking or by dragging. Clicking directly on a glyph of an element that can be selected will naturally select it. To continue selecting multiple elements, a user can either hold the Ctrl key (on Windows or Linux) or the Command key (on Mac OS) and click on the other elements to select.

Dragging involves clicking on the background, holding, and moving the mouse to draw a box around the musical elements to select. If any part of an element is contained in the box it will be selected.

Context Options

Context options are made available below the edit panel when certain elements are selected. For information on making selections, see the edit panel and selecting elements. The options are specific to what the user is selecting by. In all cases, the selection can be deleted.

• Syllable

  • If one syllable is selected, the option is given to ungroup such that each neume in the syllable becomes its own syllable in the staff.
  • If one syllable is selected, the option is also given to reassociate to nearest staff, which applies if a syllable or layer element is mistakenly assigned to the wrong staff.
  • If two or more syllables on the same staff are selected, the option is given to merge the neumes in each syllable into a single syllable.
  • If two syllables are selected and the second neume is on the next staff line, the option is given to toggle linked syllables.

• Neume

  • If one neume is selected, the options to change the grouping and ungroup are given.
    • Changing the grouping means changing the contour and number of neume components in the neume to match the selected neume grouping.
      Notice: if the syllable parent of neume is linked to another syllable, the grouping action will automatically untoggle the linked syllable.
    • Ungrouping the neume means to separate the neume components of the neume into separate neumes.
    • The Split Neumes button provides the option to split a neume into two neumes. The user indicates where the split should happen by clicking on the first neume component of the desired second neume.
  • If two or more neumes in the same staff are selected, the option is given to group the neumes into a single syllable.

• Neume Component

  • If one neume component is selected, the option is given to change the head shape of the neume component to be a punctum, virga (tail on the right), reversed virga (tail on the left), liquescent A (tails pointing upwards), liquescent B (tails pointing downwards), or inclinatum.
  • If two neume components are selected that are part of the same neume and the second neume component is of a lower pitch than the first, the option is given to toggle the components into a ligature. Inversely, if a ligature is selected, the option is given to toggle it into its starting and ending pitches, which will take the form of puncta.
  • If two or more neume components are selected that are part of the same syllable, the option is given to group the neume components into a single neume.

• Staff

  • If a single staff is selected, the option is given to split the staff into two staves and to resize the staff.
    • Clicking the "Split" button begins the process of splitting a staff. Then clicking on the staff where the staff should be split on the y-axis will cause the staff to become two staves where each new staff logically contains the elements on it.
    • The staff can be resized using the blue circles and diamonds surrounding it. Clicking and dragging on any of the sides will cause the bounding box of the staff to change. Clicking and dragging on the diamonds will cause the staff to tilt up or down. The graphic will not be updated until the user releases the button.
  • If two staves are selected that are roughly in the same y-position, the option is given to merge the staves into a single staff containing all the elements previously in the separate staves.

• Clef

  • If a single clef is selected, the option is given to change the shape of it to be either a C clef or an F clef. The pitches of the neume components that follow will update automatically.

• Accidental

  • If a single accidental is selected, the option is given to change the shape of it to be either a flat or a natural.

• Layer element

  • If a divisio, clef, or accidental is selected, the option is given to "Insert to nearest syllable". The layer element becomes a child of the nearest .

Note that there are no context options for a selected custos.

Grouping

Musical elements can be grouped and ungrouped as described in the section on context options based on MEI tag. The hierarchy of tags where grouping is applicable is:

Staff > Layer > Syllable > Neume > Neume Component

Elements can be grouped generally speaking if the following requirements are satisfied:

• The elements are of the same type (e.g. all the elements are neumes);
• The parent element of the elements is the same element (e.g. the elements are neumes and are in the same layer); and
• The elements are not already grouped.

These requirements exist to ensure there are no assumptions made in Neon about how the user wants the resulting group to be. For example if two neume components in two different syllables were grouped, it would be ambiguous if the new neume should be part of the first syllable, the second syllable, or a new third syllable. If the neume components were part of the same syllable, as is required by Neon, this ambiguity is avoided.

Notifications

Notifications may sometimes appear in the upper left corner of the screen. These are colour-coded: green for a successful action, red for a failed action, yellow for an error warning, and blue for an instruction to the user. Notifications will disappear after 5 seconds, or immediately if clicked by the user.

Text Viewing and Editing

You can view and edit the text and text bounding boxes in Neon. In MEI a <syllable> element can have a <syl> child, which can contain text and can have facsimile (coordinates) information. If an MEI file is loaded into Neon where some of the <syllable>s don't have <syl> children, verovio will populate the syllables with syl children without text. Similarly, if a <syl> element doesn't have facsimile information verovio will automatically generate a bounding box for the syl.

Text

By clicking Display Text in the display panel, a box in the bottom right will appear with the text from the current MEI page. If an empty <syl> element was generated for a syllable, its text is represented by the ◊ symbol. By mousing over the text, the syllable (and bounding box) associated with the text will be highlighted in the viewer.

While in edit mode, you can edit text by clicking on it. A box will appear to type in the new text value.

Bounding Boxes

By selecting BBoxes in the 'Display Options' panel, the bounding boxes for the text of each syllable will appear in the Neon viewer. The colour of each syllable matches that of its associated bounding box.

While displaying the bounding boxes and in edit mode, you can click the BBox button in the Edit Panel. The bounding boxes have many of the same editing features as the neumes and staves. These include:

• Clicking to select a bounding box. This will highlight it and any neume associated with it in red.
• Clicking and dragging the bounding box to a new location. This works in exactly the same way as with neumes and staves.
• Resizing the bounding box. This works in the same way as resizing staves: when you select a bounding box, blue circles will appear surrounding it. Click and drag those blue circles to resize the bounding box.
• Selecting multiple bounding boxes by clicking at some point in the background and dragging to draw a box around the bounding boxes to select. When selecting multiple bounding boxes you can move them but not resize them.

When selecting the BBoxes display option, the 'BBox Circle' slider appears below the main three sliders. This slider allows the user to resize the blue circles around a selected bounding box. If a manuscript is very densely written, or if the script is very small, the blue circles have to be sized down for the text on the folio to be visible.

Bounding boxes and grouping/ungrouping

Grouping and ungrouping syllables affects their <syl> children (since a <syllable> can have at most one <syl> child) which means that it also affects their bounding boxes.

When grouping two syllables together their bounding boxes will be merged into one, which will be the smallest rectangle to comprise the full area of both of the original boxes. In other words, the grouped bounding box will comprise both of the originals and any space in between them.

When ungrouping a syllable into two new ones, a new bounding box with an arbitrary size and position will be created for the new syllable that is created.

"Inserting" bounding boxes

There is no way in Neon to actually insert a new bounding box in way that you insert neumes. This is because bounding boxes are really just the coordinate values of the MEI <syl> element, which can't exist without a <syllable> parent. Having a <syllable> without any neumes doesn't make any sense, so a bounding box needs to be associated to some neumes in order to exist. This also means that there's no way to change which neumes/syllable a bounding box is associated with.

Instead, you should use the dragging, resizing, and grouping functions. Here are some example use cases where you might want to insert or re-associate a bounding box:

• If a bounding box is associated with the wrong syllables, the bounding box should be moved and resized to the correct text.
• If a piece of text doesn't have a bounding box, find the bounding box that is associated with the neumes associated with that piece of text and drag/resize it to the correct position.
• If there are more actual syllables in the text than bounding boxes, then ungroup the appropriate syllable and drag/resize the newly created bounding box to the piece of text.

Keyboard shortcuts

There are several keyboard shortcuts that make Neon use more efficient. Those can be found under "Hotkeys", in the "Help" dropdown menu. They are also detailed here:

Display

shift++ = Zoom in

shift+- = Zoom out

0 = Zoom reset

h = Hide glyphs (Glyph opacity becomes 0)

Shift+t = Scroll to syllable text

Edit

Ctrl+z or ⌘+z = Undo

Ctrl+shift+z or ⌘+shift+z = Redo

q/w/e/r/t/y = Highlight by staff/syllable/neume/layer element/current selection/off

1/2/3/4 = Select by syllable/neume/neume component/layer element

shift+number = Begin Insert for the nth option in the selected tab

g = group toggle (groups if the selected elements are ungrouped, ungroups if the selected elements are grouped)

Other

s = Save file

Esc = Return to Edit Mode

File Menu Actions

• Save - Saves the changes made so far. This first attempts to update the MEI files from the server it fetched them from. If this fails, it will track the changes of the file locally. For more information, see the page on Neon manifests.
• Save and Export File - Saves the changes made so far and downloads a Neon manifest file reflecting all the changes made.
• Download MEI - Downloads the MEI file for the active page.
• Revert - Revert to the originally uploaded file, discarding any changes. The page will automatically refresh.