Dev: Set up Neon and Verovio Locally

Setup

Get the latest version of Neon by cloning the repository.

git clone https://github.com/DDMAL/Neon

The master branch has all stable updates while develop is the latest and (hopefully) greatest!

Requirements

Yarn is used to handle dependencies for Neon. Follow the installation instructions for your system and then simply run

yarn install

to automatically install all the dependencies of Neon.

Updating the Verovio Toolkit

Unless you're developing Neon you shouldn't have to do this.

Make sure you have a recent version of Emscripten and of Git. Clone from Verovio:

git clone https://github.com/DDMAL/verovio

add emcc to the path:

cd verovio/emscripten/emsdk
source ./emsdk_env.sh

If you are running verovio for the first time, install emsdk first:

cd verovio/emscripten

# Get the emsdk repo
git clone https://github.com/emscripten-core/emsdk.git

# Enter that directory
cd emsdk

# Fetch the latest version of the emsdk (not needed the first time you clone)
git pull

# Download and install the latest SDK tools.
./emsdk install 3.1.47

# Make the "latest" SDK "active" for the current user. (writes .emscripten file)
./emsdk activate 3.1.47

# Activate PATH and other environment variables in the current terminal
source ./emsdk_env.sh

For more instructions, check this link.

Add this script as <path to verovio>/emscripten/testNeon.sh (e.g.: /Users/softcat/verovio/emscripten/testNeon.sh

#!/bin/bash

# This is a little script that compiles verovio using buildToolkit
# and moves the output, verovio-toolkit-wasm.js, into Neon/assets/js/.
# It then starts up a local instance of Neon using yarn so the
# developer can see the changes as soon as possible.
# Please change [location_of_your_Neon] with the actual path.
# For example: ~/Desktop/DDMAL


# Builds verovio for Neon
./buildToolkit -x "Gootville,Petaluma" -DHPX -w

cd build

# Moves the needed verovio.js into Neon
cp verovio-toolkit-wasm.js verovio_new.js

mv verovio_new.js $1/assets/js/

cd $1/assets/js/

rm verovio-toolkit-wasm.js; mv verovio_new.js verovio-toolkit-wasm.js

# Runs Neon
yarn cache clean
yarn build && yarn start

add the file to .git/info/exclude:

echo "emscripten/testNeon.sh" >> .git/info/exclude

You may also need to add the folder emscription/emsdk to .git/info/exclude:

echo "emscripten/emsdk" >> .git/info/exclude

cd to <path to verovio>/emscripten

then build with neon path as a command line argument:

bash testNeon.sh <path-to-Neon>

The verovio.js file should be copied to verovio-util/. This contains the bulk of Verovio, along with helper files from Verovio to create the standalone toolkit (which is used normally) and the NPM module (which is used in tests).

Building Neon

Neon uses webpack, so it's necessary to build before starting the server. To do this, run

yarn build

and if it finishes successfully you're ready to run Neon!

Note that this command builds for the local server (that can be run with yarn start).

Running Neon

By default Neon runs on port 8080. To change this simply edit server.js. Then run

yarn start

and access Neon at http://localhost:8080 or the port number set in server.js.

Basic Usage

Here is a brief overview of how to get started using Neon.

Score Upload and Selection

• The index page allows you to either choose an uploaded MEI and source image or to upload your own.
• Score selection is by the name of the MEI file, so a descriptive name is best.
• To delete an uploaded score, click on the blue X next to the name.
• To upload a score, locate the score upload section at the bottom of the page. Then select an MEI file and a source image, and click Upload.
  • As of now, only PNG files are supported for the source image.
  • Neon is tested using MEI 5.0.0-dev, and may not work for previous standards or non-standard MEI files.

A note on facsimiles

Neon supports MEI files with facsimiles. When using facsimiles, make sure the following requirements are met:

• All staves, clefs, neumes, custos, etc. should have an associated zone. This zone should be referenced using the facs attribute on these elements.
• The surface should contain a bounding box for the source image, in pixels. This should correspond to the image uploaded with the MEI.

It's fine to upload MEI files without a facsimile, but then it will likely not line up with the source image. An MEI uploaded with a facsimile that doesn't meet these requirements may not appear correctly or at all.

The Score Viewer

• Once an uploaded MEI score is selected, the viewer will open.
• The left of the screen is the view box for the rendered MEI and the source image.
  • Clicking on some rendered elements (like neumes!) will open an extra information box to the right.
  • To pan across the view, hold Shift and then drag using the left mouse button.
• The right side of the screen is the control panel.
  • Sliders to control the zoom and opacities of the MEI and its source are present.
  • To reset the zoom or opacities, click the labelled buttons to the left of the sliders.
  • Note that the zoom button will also reset any panning done in the view box.

Edit Mode

• Clicking on the "Edit Mode" button in the upper left corner of the screen adds extra panes to the control panel.
• This also enables editor actions like dragging and insertion, which update the state of the MEI within verovio.
  • To learn more about how Neon sends these actions to verovio, see our guide..
• Edit Mode is under active development. Features that are not present in the master branch or latest release should not be considered stable.