@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.

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();