Skip to content
WebMusic

Search documentation

Enter a title, API, or topic.

    ↑ ↓ NavigateEnter Open resultEsc Close

    Kernel

    @webmusic/kernel supplies domain-neutral contracts and runtime logic for WebMusic players and custom integrations. It contains event emitters, custom-element and worker lifecycle helpers, AudioContext construction, playback and effect contracts, and transport math. It imports no Score or Audio model.

    Install

    Section titled “Install”
    Terminal window
    npm install @webmusic/kernel

    Kernel has no runtime or peer dependencies. Node.js 22 or later is supported; ES modules and CommonJS use the same public import paths. Browser-specific operations require the relevant Web APIs, while imports remain safe during SSR.

    Source workspaces

    Section titled “Source workspaces”

    The source tree contains five packages. Kernel provides shared runtime contracts for both domain families:

    Package Role Workspace peer dependencies
    @webmusic/kernel Domain-neutral runtime contracts and pure logic —
    @webmusic/ui Dependency-free DOM presenters and styling hooks —
    @webmusic/score Symbolic music — MIDI, MusicXML, MXL, ABC Kernel required; UI optional
    @webmusic/audio Digital audio — clips, playback, analysis and views Kernel required; UI optional
    @webmusic/bridge Score/Audio coordination and conversion Kernel, Score and Audio required

    The earlier published release included Kernel, UI and Score. Source presence does not establish that Audio and Bridge are available in the npm registry.

    Shared contracts and explicit instances

    Section titled “Shared contracts and explicit instances”

    Score and Audio declare Kernel as a required peer so the application resolves a compatible runtime contract. UI is optional for code-only use and is required by Elements and UI-backed renderers. Bridge declares the domain packages and Kernel as required peers.

    A compatible dependency version does not allocate or share an AudioContext, player or transport group. Applications explicitly create, pass and release those runtime instances according to the owning API. A custom player can implement PlayerLike structurally, and Element authors can reuse WebMusicElement for connected-lifetime cleanup.

    The admission rule

    Section titled “The admission rule”

    Code qualifies for the kernel only if:

    1. existing duplicated implementations demonstrate a reusable need, or
    2. it is a domain-neutral contract shared by compatible participants.

    Domain behavior stays with its owning package. The extraction ledger — what moved here, from where, and what stayed behind — lives in the repository’s platform/README.md.

    For third parties

    Section titled “For third parties”

    Implementing a WebMusic-compatible player, effect, or timeline mapping means depending on @webmusic/kernel directly and implementing its structural contracts — no domain package required. Element authors can subclass WebMusicElement for connected-lifetime cleanup with SSR-safe imports.

    See the API reference for the ten capability subpaths and their contracts.