@scorelabs/viewer

A high-performance, canvas-based music score viewer and editor for the web.

Overview

@scorelabs/viewer is a standalone React-based component library for rendering and interacting with musical scores. Built with performance and precision in mind, it uses HTML5 Canvas to provide smooth rendering of complex musical notation, from solo piano pieces to full orchestral scores.

Key Features

• 🎨 Canvas Rendering: High-performance rendering engine that scales effortlessly.
• 🎼 Rich Notation: Support for dynamics, articulations, ornaments, ties, slurs, hairpins, and more.
• 🎹 Interaction: Full editing capabilities with multi-selection, transposition, and real-time score updates.
• 🔊 Audio Playback: Integrated playback system powered by Tone.js with support for various instrument presets.
• 📂 MusicXML Support: Built-in parser and exporter for industry-standard MusicXML files.
• 🤖 AI Features: Integration with Magenta.js for musical infilling and professional post-processing.
• 🎙️ Vocal Synthesis: Generate vocal guides directly from score lyrics.
• 📱 Responsive Layout: Advanced layout engine that handles systems, pages, and zooming.

supported feaures

• Core notation: Pitched notes, rests, chords, multiple voices per staff, tuplets, dots (single and double), grace notes, cue notes, beaming (including secondary/tertiary hooks), stem direction control.
• Durations: whole, half, quarter, eighth, sixteenth, thirty-second, sixty-fourth, one-hundred-twenty-eighth, two-hundred-fifty-sixth.
• Accidentals: sharp, flat, natural, double-sharp, double-flat.
• Accidental display styles: cautionary, editorial, parenthesized, bracketed.
• Articulations: staccato, accent, tenuto, marcato, fermata, staccatissimo, caesura, breath mark.
• Dynamics: ppp, pp, p, mp, mf, f, ff, fff, sfz, fp.
• Hairpins: crescendo and decrescendo, with start/stop semantics.
• Ornaments: trill, mordent, inverted mordent, turn, inverted turn, delayed turn.
• Tremolos: unmeasured tremolo (1-4 strokes) and measured tremolo (1-4 strokes), including MusicXML distinction and rendering behavior.
• Ornament extensions: trill wavy-line extenders, accidental marks on ornaments, delayed-turn parsing/rendering.
• Connections and spans: ties (start/stop/continue, numbered), slurs (start/stop, numbered), glissando/slide (wavy and straight), arpeggios (normal/up/down), ottava lines (8va, 8vb, 15ma, 15mb), pedal (sustain and una corda).
• Guitar and technical notation: tablature string/fret, circled string numbers, bowings (up/down), hammer-on, pull-off, palm mute, fretboard diagrams.
• Noteheads: normal, cross, diamond, slash, triangle, square.
• Text and metadata notation: title/subtitle/composer/lyricist/copyright, lyrics with syllabic handling and melisma extension, chord symbols, rehearsal marks, system text, staff text.
• Score structure and symbols: clefs (including tab/percussion and octave variants), key signatures, time signatures (including common/cut symbols), repeats, voltas, roadmap symbols (segno, coda, D.C., D.S., Fine, To Coda), multi-measure rests, cross-staff beams.
• Layout and engraving controls: paginated/flow views, zoom, page size/orientation, system and page breaks, first-system indent, configurable spacing/style controls, measure numbering options, collision-aware placement improvements for dynamics/hairpins/lyrics/ornaments.
• Playback and practice: Tone.js playback, metronome and count-in, playback speed, multiple instrument synth presets, tied-note sustain, repeats/voltas in playback, MIDI input, waterfall/learning mode, vocal guide synthesis.
• Import/export and interoperability: MusicXML import/parser and export, MIDI export, PDF export, MP3 export, JSON score model serialization.
• Editing workflow: note palette tools, keyboard shortcuts, multi-selection, transposition, undo/redo, edit/view mode support, real-time score updates.

Installation

npm install @scorelabs/viewer
# or
yarn add @scorelabs/viewer

Note: This package has peer dependencies on react, react-dom, @mui/material, and @emotion/react.

Quick Start

import { MusicXMLParser, Score, ScoreCanvas } from '@scorelabs/viewer';
import { useState } from 'react';

function App() {
  const [score, setScore] = useState(() => Score.empty());

  const handleUpdate = (newScore: Score) => {
    setScore(newScore);
  };

  return (
    <div style={{ height: '100vh', width: '100%' }}>
      <ScoreCanvas
        score={score}
        zoomLevel={1.0}
        onUpdateScore={handleUpdate}
        onZoomIn={() => {
          /* ... */
        }}
        onZoomOut={() => {
          /* ... */
        }}
        onResetZoom={() => {
          /* ... */
        }}
        // ... see Props for more
      />
    </div>
  );
}

Core Components

ScoreCanvas

The primary component for displaying and editing musical scores.

| Prop | Type | Description | | ----------------- | ------------------------ | ----------------------------------------------- | | score | Score | The score model to render. | | zoomLevel | number | Current zoom multiplier (default: 1.0). | | onUpdateScore | (score: Score) => void | Callback triggered when the score is modified. | | audioPlayer | AudioPlayer | Optional audio player instance for playback. | | layoutConfig | LayoutConfig | Configuration for margins, spacing, and sizing. | | initialEditMode | boolean | Whether the score starts in edit mode. |

Data Models

The library provides a robust object-oriented model for musical data:

• Score: The top-level container including metadata, parts, and global signatures.
• Part: Represents an instrument or voice.
• Staff: A single musical staff within a part.
• Measure: Contains voices and notes.
• Note: Represents a single pitch or rest with durations and markings.

Advanced Usage

Importing MusicXML

const parser = new MusicXMLParser();
const scoreJson = parser.parse(xmlString);
const score = Score.fromJSON(scoreJson);

Playback

import { AudioPlayer } from '@scorelabs/viewer';

const player = new AudioPlayer();
player.loadScore(score);
player.play();