Spool

🎹 A piano roll player for MEI (Music Encoding Initiative) files, packaged for npm as mei-piano-roll. It reads an MEI file in the browser, draws its notes as a piano roll, plays them with a choice of synths or sampled instruments, makes still images of any bars, and lists anything in the file it could not show faithfully.

Status

2026-10-10: Spool is a public alpha at https://spool.devinchaloux.com. It opens with a Renaissance motet from the CRIM Project, shows tempo in the beat the meter names, opens a file from your computer or from a link, shares a file as a link or as a player for any web page, and plays the sampled instruments from its own copy of the recordings. The first reader works. It handles short, cleanly encoded files. On the MEI project's 617 sample files it reads everything without crashing, and 144 read with nothing left out; the rest report a gap (repeats, mid-piece changes, notes without a length, a few ties it can't follow). Tied notes sound once, as one long note, grace notes play just before their beat, and measured tremolos play as the repeated notes they stand for. A file with several instruments shows each in its own color, on one roll or one lane per part, with mute, solo, a color and a sound for each, starting from the instruments the file names. The composer, and the artist for a song, show beside the title when the file names them. 2026-10-17: a Notation button swaps the roll for the music in traditional notation, on a paper background, lighting each note as it sounds and scrolling with the playhead; Verovio draws it, downloaded only when the button is first pressed. 2026-10-24: chord symbols show in a row over the roll, written with ♭ and ♯, and a button adds a bass line that holds each chord's bass note, from C2 to B2; the notation view opens at a smaller size and has its own zoom. Notes are named as the file spells them (B♭4, not A#4), and every text color on the roll meets WCAG AA contrast. Held sampled notes now sustain past the end of their recordings without a click, on loop points Spool measures itself, and the notation view scrolls smoothly with the playhead. Nothing is published to npm yet.

Try it

Requires Node 22 or later.

npm install
npm run dev

Open the address it prints. The page opens Tomás Luis de Victoria's O magnum mysterium, encoded by the CRIM Project (CC BY-NC 4.0; see demo/public/files/LICENSE.md). Open any .mei file, drop one on the page, or open one from a link. A file from your computer stays in your browser. Three tabs show the full player, Share (a link to the file, or a small player for a web page) and the image maker, which saves any bars as SVG or PNG. The side panel sets the theme and each part's color for all three, and sounds chosen in one player carry over to the other.

The same demo is hosted on Vercel (vercel.json): main deploys it, and each pull request gets its own preview link. To build it yourself:

npm run build:demo   # static site in dist-demo/

The build first downloads the sampled instruments (about 45 MB, once), with loop points that let a held note sustain past its three-second recording, into demo/public/sounds/, which git ignores, so the hosted demo plays them from its own address (npm run sounds does only that step). The loop points are measured from the recordings and kept in demo/loops/; after changing the recordings' commit in demo/sounds.json, measure them again with npm run loops, which needs ffmpeg.

Share a file, or put it in a web page

Spool keeps nothing on a server, so sharing means putting the MEI file online first, somewhere other sites may read it: a file in a GitHub repository, a Dropbox share link, or your own site with cross-origin reads allowed (Access-Control-Allow-Origin). Paste its address into Share, which gives:

• a link that opens the file in Spool with your theme, colors and sounds;
• an embed, an iframe for any web page, blog or course site that allows iframes:

<iframe src="https://spool.devinchaloux.com/embed?src=https://example.org/song.mei&theme=paper"
  title="Song · Spool" width="100%" height="340" style="border: 0; border-radius: 10px"></iframe>

Option	What it does
src	The file's address (required)
theme	studio (default), paper, neon or ink
colors	One color per part, as hex without #, comma-separated: c00050,1f5fbf
sounds	One sound per part, by id (see SOUNDS), comma-separated: piano,acid-bass

The embed fills the iframe's height. Its expand button opens the file in Spool. Options are never renamed once published, so an embed keeps working. An embed chooses how the file is shown, not who can read it: anyone with the address can download the file.

Use it in a React page

import { MeiPianoRoll } from 'mei-piano-roll'

<MeiPianoRoll src="/music/example.mei" />
// or, with the file's text already loaded:
<MeiPianoRoll meiText={xml} height={320} onLoad={(score) => console.log(score.warnings)} />
// in a page of text: a play button over the roll, a one-line caption with play/pause
<MeiPianoRoll src="/music/example.mei" variant="compact" />

Prop	What it does
src / meiText	The MEI file, by address or as text
openHref	Compact player only: an address its expand button opens in a new tab, instead of opening the full player in place
variant	"full" (default): the roll with its controls underneath. "compact": a play button over the roll and a caption line with play/pause, the title and the composer; it opens into the full player
header	Show the title line above the full player; default true
notation	Offer the Notation button, which shows the file in traditional notation, drawn by Verovio (LGPL-3.0, about 2.4 MB, downloaded the first time a listener presses it); default true
view	The view the player opens in: "roll" (default) or "notation"
sound	Starting sound for every part, by id (see SOUNDS); default each part's nearest sound to the instrument the file names, else the saw lead
partSounds	Starting sound for each part, by id, in score order; takes precedence over sound
samplesUrl	Where the sampled instruments are hosted: a folder of FluidR3 <instrument>-mp3.js files, and optionally <instrument>-loop.json loop points so held notes sustain, ending in /; default the volunteer-run site smplr uses (no loop points)
onPartSoundsChange	Called with every part's sound whenever the listener changes one, so a page can keep the choice
theme	"studio" (default), "paper", "neon", "ink", or your own colors
accent	Note color (the first part's, with several); without it, the page's --accent CSS variable, then the theme's
partColors	One color per part, in score order; default the note color, then quick-pick colors

Also exported: NOTE_COLORS, eight quick-pick note colors that adjust for light and dark themes; parseNative(xml) for the note data without the player; and rollToSvg(score, options) for still images (partColors, separateParts and fadedParts match the player's view of several parts). Drawing needs no browser, so a site's build can draw pictures straight from its files; reading the MEI does need an XML parser, which Node lacks, so a build gives parseNative one first, such as jsdom's DOMParser (the stress test does this, in stress/samples.stress.ts).

Sampled instruments are FluidR3 GM by Frank Wen (CC BY 3.0), played by smplr; the player credits them whenever one is in use.

Checks

npm run lint && npm run test:run && npm run build

CI runs the same on every push. npm run build type-checks, then builds the library into dist/.

Stress test

npm run stress

Downloads the MEI project's sample files (about 113 MB, once) into fixtures/, which git ignores, reads every one, and writes fixtures/stress-report.md. It takes about two minutes. Its job is to show what breaks, not to pass; see docs/fixtures.md.

Layout

Path	What it is
src/mei/	The reader: MEI text in, note data and warnings out. No UI.
src/roll/	The player component (one canvas), its color themes, and the lane layout it shares with the images.
src/audio/	Sounds: the synth recipes, the sampled-instrument list, a part's starting sound, the engine that plays them.
src/render/	Still images: SVG from a score, and PNG in the browser.
src/test/	Unit tests, with short MEI snippets written for them.
demo/	The demo page (npm run dev); not part of the library.
stress/	The stress test (npm run stress).
scripts/fetch-samples.mjs	Downloads the sample files for the stress test.

Docs

• CLAUDE.md: rules for working on this repo with Claude Code
• docs/decisions.md: design decisions and open questions
• docs/fixtures.md: where the test files come from