Score

Score is one package, @webmusic/score, for symbolic music: notes with pitches, durations and voices, read from MIDI, MusicXML, MXL or ABC. The play, analyze, and view capabilities support Web Components, Headless objects, and APIs. Combine the APIs with UI presenters or your own interface; integration entries such as React build on the same contracts.

For a working player with notation and a keyboard, start with Quick Start. This page covers package selection and setup.

Capabilities

Capability	What it covers	Forms
play	Turn a Score into sound: push and pull engines, timbres, effect chains, racks, offline WAV render, capture of performed note events into a Score.	Web Components · Headless · API
analyze	Ask a Score questions: key, chords, roman numerals, motifs, rhythm figures, voice-leading issues, distributions and summaries.	Web Components · Headless · API
view	Draw a Score: piano roll, staff, waterfall, engraved notation, whole-piece maps and thumbnails.	Web Components · Headless · API
io	Format detection and MIDI, MusicXML, MXL and ABC parsing/serialization, with worker-backed parsing.	API
react	The same capabilities as React components and hooks.	API

The package root is the model itself — Score, Rational, Pitch, Duration, TimeMap, queries and JSON — and it touches no browser API. See the package subpath table for every published entry.

What Score is not

Score does not decode recorded audio or analyze PCM waveforms. It synthesizes notes and can export their sound as WAV. Audio-file processing and cross-domain Bridge coordination remain accepted future directions; those packages and their public references have not been migrated into this first-release checkout.

Install

Package availability

Registry installs and CDN resources require the relevant package versions to be published. If npm returns E404, use the local checkout installation below. Building the documentation site does not publish those packages.

From npm

Once the packages are available in your registry, run this in your application:

npm install @webmusic/score @webmusic/kernel @webmusic/ui

From a local checkout

Use Node.js 22 or later. From the root of a main checkout, install the locked dependencies, build the packages and create their installable archives:

npm ci
npm run build:packages
npm pack -w @webmusic/kernel -w @webmusic/ui -w @webmusic/score

npm pack writes three .tgz files to the repository root and prints their filenames. In your existing ES-module bundler application’s directory, install all three together. Replace VERSION with the version in those filenames and ../WebMusic with the relative path to your checkout:

npm install "../WebMusic/webmusic-kernel-VERSION.tgz" "../WebMusic/webmusic-ui-VERSION.tgz" "../WebMusic/webmusic-score-VERSION.tgz"

The archives provide the local @webmusic packages; npm still installs their third-party dependencies from your configured registry. Continue with the bundler registration below or the Quick Start player.

Entries and optional peers

io, play, analyze, view, and react are export subpaths of that one installed package; use their public import paths rather than installing them separately.

@webmusic/kernel is required. Add optional peers for the entries and features you use; importing a visual Element requires @webmusic/ui.

Peer	When it is needed
@webmusic/ui	Score Web Components and renderers that compose UI presenters.
tone	An application-supplied Tone.js transport or instrument.
spessasynth_lib	.sf2 / .sf3 SoundFont playback.
opensheetmusicdisplay	Detailed sheet engraving through OSMD.
react	The /react components and hooks.

The built-in oscillator needs no SoundFont peer. SoundFont playback also needs a served AudioWorklet. Resource preparation, worklet URLs and ownership details belong to the Play API and View API references.

Drop-in Web Components

Web Components combine Score behavior with controls or visual presenters. Register the tags needed by your page, supply their data and resources, and configure them through their public properties and attributes. The Web Components inventory lists the tags, registration functions and shared theming.

With a bundler

Importing @webmusic/score/play/auto registers all Play elements at their default names. It does not register Analyze or View elements. Use their @webmusic/score/analyze/element and @webmusic/score/view/element entries and call the registration functions listed in the inventory.

Custom registration

Import an individual define* function from the capability’s /element entry to register a selected tag or choose a custom tag name. The group registration functions register their default names; defineAllElements() does not accept custom names. See the Play, Analyze and View registration references.

From a CDN

Only Play provides a prebuilt browser IIFE through @webmusic/score/play/global, emitted as dist/play/auto.global.js. Loading that published bundle registers the Play elements and exposes WebMusicScorePlay on window. This path needs no bundler, but the requested package version and its assets must be available from the CDN.

The ESM entries retain package imports; a plain browser module URL needs an application-provided resolution strategy. Use the bundler setup above for the three-component Quick Start.

Playback

Use ScorePlayer when your application owns the controls. The same Headless engine powers the player Element and exposes commands, state and lifecycle hooks. The Headless inventory routes to playback, analysis and view objects; their owning pages contain the examples and complete contracts.

API + UI

Use APIs for data operations and independent UI presenters for application-owned controls. See the root API for models and entry points, and Transport for a presenter binding. The shared playback source connects views and analysis to an existing player’s data, state and position.

React

The React entry provides components and hooks over the same Score models and playback contracts. Framework integration does not replace the underlying data model or resource ownership rules.

Next Steps

• Quick Start for the small player, notation and keyboard example.
• Web Components for every tag, its owning page and shared theming.
• Headless for engines, sessions and their export ownership.
• Core API for the score model, builder, time map and events.
• I/O API for MIDI, MusicXML, MXL and ABC import/export.
• Play API for playback, rendering, recording, sounds and effects.
• Analyze API for musical analysis.
• View API for visualization and layout primitives.
• React API for providers, hooks and view bindings.