@hiyve/react-music-notation

Sheet music player for MusicXML scores. It renders a score, plays it back with transport, tempo and per-instrument volume controls, and can keep everyone in a room on the same note as a presenter plays, steps or clicks through the piece.

You supply the notation engine

This package is the player: the controls, the layout and the room sync. It does not contain the engine that engraves and plays a score. You provide that engine through the required loadEngine prop, and nothing renders until you do.

Setup is three steps: install the package, add an engine, render a score.

Setup

1. Install the package

npm install @hiyve/react-music-notation @hiyve/utilities @mui/material @mui/icons-material @emotion/react @emotion/styled
Copy

Synced playback across a room additionally needs:

npm install @hiyve/react @hiyve/react-semantic-relay
Copy

2. Add a notation engine

The player works with any OpenSheetMusicDisplay-compatible build. Which build you choose decides what your users get:

You can start with option A and move to option B later; only the loadEngine function changes.

Option A: the public build (rendering only)

Install it:

npm install opensheetmusicdisplay
Copy

Create the loader once, in a module of its own:

// notationEngine.ts
export const loadEngine = () => import('opensheetmusicdisplay');
Copy

The player shows the score with previous-note and next-note buttons. The playback controls are hidden.

Option B: a build with playback

1. Get the build. You need one file: the minified browser build, usually named opensheetmusicdisplay.min.js. It is not on public npm. You obtain it from its publisher and use it under its licence terms.

2. Serve the file from your app. Either put it in your static folder, so that public/vendor/opensheetmusicdisplay.min.js is served at /vendor/opensheetmusicdisplay.min.js, or keep it beside your source and let your bundler emit it:

   const engineUrl = new URL('./vendor/opensheetmusicdisplay.min.js', import.meta.url).href;
   Copy

   Load it as a script, as shown next. Do not import the file as a module.

3. Create the loader once, in a module of its own:

   // notationEngine.ts
   import { createScriptEngineLoader } from '@hiyve/react-music-notation';
   
   export const loadEngine = createScriptEngineLoader('/vendor/opensheetmusicdisplay.min.js');
   Copy

createScriptEngineLoader(url, options?) adds the script to the page the first time a player needs it and reuses it afterwards, however many players you render.

Either way, the engine is downloaded only when a player first mounts, so it adds nothing to your initial page load.

3. Render a score

import { MusicXmlPlayer } from '@hiyve/react-music-notation';
import { loadEngine } from './notationEngine';

function ScoreViewer({ url, onClose }: { url: string; onClose: () => void }) {
  return (
    <MusicXmlPlayer
      fileUrl={url}
      fileName="Minuet in G"
      loadEngine={loadEngine}
      onClose={onClose}
      onError={(error) => console.error(error)}
    />
  );
}
Copy

By default the player covers the viewport with its own header. Use variant="inline" to fill a container you size yourself:

<div style={{ height: 600 }}>
  <MusicXmlPlayer variant="inline" fileUrl={url} loadEngine={loadEngine} />
</div>
Copy

If it does not work

Pass onError while you set up; the message tells you which step failed.

To check an engine in code, engineSupportsPlayback(engine) returns whether it can play audio.

Features

• Score rendering from any MusicXML URL, engraved as SVG and re-flowed when the container resizes.
• Playback transport: play, pause, stop, and note-by-note stepping, with a cursor that follows the music.
• Tempo slider, starting from the tempo the score states.
• Per-instrument volume and mute for every part in the score.
• Click a note to move the cursor there and hear it.
• Synced playback: one presenter drives every follower's player, including tempo, volume and note clicks.
• Render-only mode: with an engine that has no audio player, the score still renders and steps; playback controls are hidden.
• Overlay or inline layout, with customizable labels and colours.

Synced playback

SyncedMusicXmlPlayer mirrors the presenter's actions to every follower. A follower's controls are locked while it follows.

import { SyncedMusicXmlPlayer } from '@hiyve/react-music-notation/sync';

function RoomScore({ file, url, localUserId, ownerId }) {
  return (
    <SyncedMusicXmlPlayer
      variant="inline"
      fileUrl={url}
      loadEngine={loadEngine}
      fileId={file.fileId}
      localUserId={localUserId}
      isPresenter={localUserId === ownerId}
      presenterId={ownerId}
      enabled
    />
  );
}
Copy

Render it under a SemanticRelayProvider from @hiyve/react-semantic-relay. Every participant must pass the same fileId for the same score.

Followers only accept commands sent by presenterId. Until presenterId is known they ignore every command, so pass it as soon as you have it.

Building your own sync

useMusicXmlPlayerSync gives you the transport without the component, for cases where you render MusicXmlPlayer yourself:

import { useRef } from 'react';
import { MusicXmlPlayer, type MusicXmlPlayerHandle } from '@hiyve/react-music-notation';
import { useMusicXmlPlayerSync } from '@hiyve/react-music-notation/sync';

function CustomSyncedScore({ url, fileId, localUserId, isPresenter, presenterId }) {
  const playerRef = useRef<MusicXmlPlayerHandle>(null);
  const { broadcast, isFollowing } = useMusicXmlPlayerSync({
    localUserId,
    isPresenter,
    presenterId,
    fileId,
    enabled: true,
    onRemoteCommand: (command) => playerRef.current?.apply(command),
  });

  return (
    <MusicXmlPlayer
      ref={playerRef}
      variant="inline"
      fileUrl={url}
      loadEngine={loadEngine}
      controlsLocked={isFollowing}
      onLocalCommand={broadcast}
    />
  );
}
Copy

Opening scores from the file manager

FileManager from @hiyve/react-collaboration recognises .musicxml files. Register the player as their viewer:

import { FileManager } from '@hiyve/react-collaboration';
import { MusicXmlPlayer } from '@hiyve/react-music-notation';

<FileManager
  customViewers={{
    musicxml: (_data, _file, _onClose, url) =>
      url ? <MusicXmlPlayer variant="inline" fileUrl={url} loadEngine={loadEngine} /> : null,
  }}
/>
Copy

Props

MusicXmlPlayer

The component's ref exposes apply(command), which performs a command as if the user had done it without reporting it through onLocalCommand.

SyncedMusicXmlPlayer

Takes every MusicXmlPlayer prop except controlsLocked and onLocalCommand, plus:

useMusicXmlPlayerSync

Takes the six sync props above, plus:

Returns:

Commands

MusicXmlPlayerCommand is one of:

Customization

Labels

<MusicXmlPlayer
  fileUrl={url}
  loadEngine={loadEngine}
  labels={{ title: 'Partitur', play: 'Abspielen', pause: 'Pause', stop: 'Stopp' }}
/>
Copy

DEFAULT_LABELS holds the defaults and mergeLabels(overrides) returns the defaults with your overrides applied.

Colours

Each colour is an MUI theme palette path or any CSS colour.

<MusicXmlPlayer
  fileUrl={url}
  loadEngine={loadEngine}
  colors={{ toolbar: 'grey.900', cursor: '#ff3366' }}
/>
Copy

DEFAULT_COLORS holds the defaults and mergeColors(overrides) returns the defaults with your overrides applied.

Instrument samples

During playback the engine downloads instrument samples. To serve them from your own host, pass soundfont:

<MusicXmlPlayer
  fileUrl={url}
  loadEngine={loadEngine}
  soundfont={{
    baseUrl: 'https://cdn.example.com/soundfonts/',
    percussionBaseUrl: 'https://cdn.example.com/soundfonts/FluidR3_GM/',
  }}
/>
Copy

The host must be laid out like the midi-js-soundfonts collection.

Requirements

• React 18 or 19, and MUI 9.
• A notation engine, supplied through loadEngine.
• fileUrl must be fetchable from the browser (CORS applies) and return uncompressed MusicXML. Compressed .mxl files are not supported.
• Content Security Policy. The score is fetched with fetch, so its host must be allowed by connect-src. With a playback engine and no soundfont override, samples are fetched from https://gleitz.github.io and https://paulrosen.github.io. An engine loaded with createScriptEngineLoader must be allowed by script-src.
• Browsers start audio only after a user gesture, so playback begins from a click on the player.
• SyncedMusicXmlPlayer and useMusicXmlPlayerSync must be used under a SemanticRelayProvider from @hiyve/react-semantic-relay.

Public API

@hiyve/react-music-notation

@hiyve/react-music-notation/sync