https://github.com/infojunkie/musicxml-player
Play MusicXML scores in the browser using Web Audio and Web MIDI.
https://github.com/infojunkie/musicxml-player
midi music-i18n music-notation musicxml web-audio
Last synced: 2 months ago
JSON representation
Play MusicXML scores in the browser using Web Audio and Web MIDI.
- Host: GitHub
- URL: https://github.com/infojunkie/musicxml-player
- Owner: infojunkie
- License: gpl-3.0
- Created: 2022-11-28T03:51:12.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2026-03-12T17:58:45.000Z (3 months ago)
- Last Synced: 2026-03-12T22:33:21.821Z (3 months ago)
- Topics: midi, music-i18n, music-notation, musicxml, web-audio
- Language: TypeScript
- Homepage: https://blog.karimratib.me/demos/musicxml/
- Size: 271 MB
- Stars: 71
- Watchers: 4
- Forks: 13
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
- awesome-webaudio - MusicXML Player - A TypeScript component that loads and plays MusicXML files in the browser using Web Audio and Web MIDI. (Packages / Libraries)
README
MusicXML Player
===============
[](https://www.npmjs.com/package/@music-i18n/musicxml-player)
[](https://github.com/infojunkie/musicxml-player/actions/workflows/test.yml)
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`](https://github.com/infojunkie/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](https://github.com/rism-digital/verovio) or [OpenSheetMusicDisplay](https://github.com/opensheetmusicdisplay/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`](https://github.com/spessasus/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`](https://github.com/infojunkie/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](https://github.com/rism-digital/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.
# Development
At the moment, the only documentation available for the usage of the player is located in the [demo app](demo/demo.mjs) and the 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.
```bash
npm test
npm test -- src/helpers/fetish.spec.ts
npm test -- -t "should throw if not ok"
npm test -- --watch
npm test -- src/helpers/fetish.spec.ts --watch
npm test -- src/helpers/fetish.spec.ts -t "should throw if not ok" --watch
```
When creating a new version, some tests will fail - run `npm run build:snap` to update the snapshots.