Verovio

Using Verovio for Neon

Neon's rendering and editing backbone is Verovio. Ultimately the fork used here tends to differ from the upstream version. Here are some tips for using Verovio in the context of developing for Neon.js:

Toolkit and EditorToolkit

There are two toolkit classes in Verovio, the toolkit (vrv::Toolkit) and the editor toolkit (vrv::EditorToolkit). The toolkit is the class closest to the frontend and is what is called by both main.cpp in the CLI and which is given Javascript bindings by emscripten. The editor toolkit adds the experimental editor actions that Neon relies on, and is accessed through the edit function of the regular toolkit (vrv::Toolkit::Edit). Editor actions are sent to the editor toolkit through a JSON object.

Install Emscripten

Before building Verovio, we need to install emscripten. First, go into the /emscripten folder and get the emsdk repo:

cd emscripten 

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

# Enter that directory
cd emsdk

Then run the following commands to get the latest tools:

Warning: As of August 9th, 2022, the latest version of emsdk, 3.1.18, has a fatal error. We therefore currently use emsdk 3.1.17.

# 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.17

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

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

NOTICE: for ERROR: emscripten compiler (emcc) not found., simply run command source ./emsdk_env.sh to activate PATH.

It's advisable to not install emscripten to the system to avoid compatibility issues related to LLVM or node.

Building for size

Verovio is big, especially when built in javascript. There are two things that can reliably minimize the Verovio package: change optimizations and remove features unused in Neon. This means cutting out unused fonts and not building extra loaders for non-MEI formats and replacing the -O3 optimization in emscripten with -Os. Or, instead of building with

./buildToolkit -H

you build with

sed -i '' "s/-O3/-Os/" buildToolkit
./buildToolkit -x "Gootville,Leipzig,Petaluma" -DHPX

This can get the size down to 3.9 MB from 6.0 MB.

When generated correctly, files will be written to /emscripten/build. verovio.js is the basis of the various files created with setup-verovio, also using helper files like verovio-proxy.js (see below).

Notes

A note on the Node and Standalone Versions

Because of some issues with webpack (#326) we use a standalone toolkit of Verovio for production. But for testing we use the NPM package in src/verovio-dev since it integrates better with Jest. Ultimately both versions use the file verovio-util/verovio.js which is the raw emscripten output, but with some different helpers added (see setup-verovio, which draws from the build file for Verovio).

Running yarn bundle:dev or yarn bundle:pages after this should generate new resources using the updated version of Verovio for testing.

A note on Emscripten PATH variables

Emscripten uses a different version of node.js (among other things) to compile to Web Assembly or asm.js. The typical way that emsdk exposes these to the compiler is by adding them to the path. Using the older version of node.js used for Emscripten for Neon purposes will result in unexpected behavior (e.g. tests failing for no apparent reason).