vexml

• vexml.dev
• MusicXML
• VexFlow

Usage

Installing

You will be able to use any JavaScript package manager (e.g. yarn, npm, pnpm) to install vexml. At the moment, stringsync/vexml is not published to any public registry.

⚠️ IMPORTANT: Loading Fonts

vexml uses VexFlow 5, which requires you to load the fonts you need to use. See the vexflow documentation TODO(TBD link) on how to do this.

Rendering

import { vexml } from 'vexml';

const width = 600;
const height = 600;

const div = document.createElement('div');
div.style.width = `${width}px`;
div.style.height = `${height}px`;

const musicXML = 'some valid musicXML'; // see tests/integration/__data__ for valid musicXML documents

vexml.Vexml.fromMusicXML(musicXML).render({ element: div, width: width });

This will render a child SVG element whose height will automatically adjust to fit the container. There is currently no option to disable this.

Motivation

[!NOTE] At the time of writing, most of these features are aspirational. Please see the Usage section for a list of available features.

Render MusicXML in Any Web Browser 🌐🎶

MusicXML is the standard for digital sheet music, but visualizing it often requires specialized desktop software. This library empowers you to bring musical notation to the web, making it accessible on any device with a browser.

Navigate Musical Renderings 🎼🗺️

• Programmatic scrolling and zooming to specific sections.
• Jumping between measures or movements.
• Synchronizing the visual score with audio playback.
• Navigating based on musical events (e.g., chord changes).

Interactive User Experience 🖱️🎹

• Built-in hooks for reacting to user input (clicks, keyboard events, MIDI).
• Customizable interactions (e.g., highlighting notes, changing playback speed).
• Opportunities to build educational tools, interactive performances, or adaptive learning experiences.

Development

Prerequisites

• yarn
• docker

Installing

Before you run any commands, install the dependencies.

yarn install

Running the Dev Server

In order to run a dev server that hot reloads vexml changes, run:

yarn dev

You should be able to "save" MusicXML documents in localstorage using the dev app, which will cause the documents to survive refreshing the page.

Running Tests

In order to run tests on x86 architecture, run:

yarn test

If you're running a machine using ARM architecture (such as an M series mac), try setting the default platform before running the command (or set it in your shell profile):

export DOCKER_DEFAULT_PLATFORM=linux/amd64

These commands are just an alias for jest, so you use all the jest CLI options. For example, to run in watch mode:

yarn test --watchAll

To bypass Docker, run:

yarn jest

This will cause snapshots to be saved to tests/integration/__tmp_image_snapshots__, which is ignored by git. It is important that you run it for the first time on a branch without any changes. Doing this on a dirty branch could cause you to have an incorrect snapshot, which may cause problems when developing.

If you suspect issues with the tmp snapshots, run the following command to retake the snapshots (which is scripted to do this at origin/master):

yarn resnap

Debugging Tests

To run a debugger, run:

yarn debug

If you're using VSCode, open the debugging tool and launch Attach to Process. You can set breakpoints in VSCode or insert debugger statements to cause execution to pause.

If you're not using VSCode, open Chrome and visit chrome://inspect. You should see a virtual device that starts with ./node_modules/.bin/jest with an "inspect" button. Clicking this will allow you to use the Chrome debugger.

If you're still having issues, check the jest docs or file an issue.

Snapshots

This library uses americanexpress/jest-image-snapshot for image-based snapshot tests.

Diffs

You can see diff images in the __diff_output__ directory (nested under __image_snapshots__). Images here are ignored by git, but allow you to see what changed. The order of images are: snapshot, diff, received.

Updating Snapshots

Rendering varies by platform, so it is important you run tests using the yarn test* commands, since that runs tests in a consistent environment (via Docker). This is also the environment that CI will use.

When you want to update all snapshots, rerun the test command with the --updateSnapshot.

yarn test --updateSnapshot

If you want to only update a single snapshot from specific test, you can use --testNamePattern.

Removing tests

When removing a test, it is important to remove the corresponding snapshot. There is currently no automatic mechanism to do this. Alternatively, you can run the vexml:latest Docker image with JEST_IMAGE_SNAPSHOT_TRACK_OBSOLETE=1, but make sure you're running the entire test suite. See the docs for more information.