MusicXML Player

A TypeScript component that loads and plays MusicXML files in the browser using Web Audio and Web MIDI.

Getting started

npm install
npm run build
npm test
npm run demo:develop

Then open http://127.0.0.1:8080/

NOTE! To use the MMA (Musical MIDI Accompaniment) feature, you need to install and run musicxml-midi separately. Typically, running PORT=3000 npm run start from the musicxml-midi folder in a separate console should be enough.

Theory of operation

This component synchronizes rendering and playback of MusicXML scores. Rendering is done using existing Web-based music engraving libraries such as Verovio or OpenSheetMusicDisplay. Rendering can also use pre-rendered assets (SVG, metadata) obtained from MuseScore or Verovio. Playback uses standard MIDI files that are expected to correspond to the given MusicXML, and sends the MIDI events to either a Web MIDI output, or to a Web Audio synthesizer, using the module spessasynth_lib.

The crucial part of this functionality is to synchronize the measures and beats in the MusicXML file with the events of the MIDI file. In a nutshell, the player expects the provider of the MIDI file (an implementation of IMidiConverter) to supply a "timemap", which associates each measure in the MusicXML file to a timestamp at which this measure occurs. In the case of repeats and jumps, the same measure will be referenced several times in the timemap.

There are 3 bundled implementations of IMidiConverter in this module:

• An API client that connects to the musicxml-midi API server. musicxml-midi is a converter whose major contribution is to generate a MIDI accompaniment in addition to the music in the MusicXML score.
• Verovio, that generates a faithful rendition of the MusicXML score but lacks accompaniment generation.
• It is also possible to hand-craft the MIDI and timemap files, and instruct the player to read those explicitly.

API usage

At the moment, the only documentation available for the usage of the player is located in the demo app.

Tests

This project uses Vitest for testing:

• Unit tests run in Node.

• Integration tests (that might rely on browser-like APIs) run with a jsdom environment. Use the commands below to run all tests, a single file, or a single test in watch or non-watch mode.

• All tests

npm test

• Single file

npm test -- src/helpers/fetish.spec.ts

• Single test by name (pattern)

npm test -- -t "should throw if not ok"

• Watch mode (all tests)

npm test -- --watch

• Watch a single file

npm test -- src/helpers/fetish.spec.ts --watch

• Watch a single test in a file

npm test -- src/helpers/fetish.spec.ts -t "should throw if not ok" --watch