webmscore

webmscore

MuseScore's libmscore (the core library) in WebAssembly!

Features

• Parse mscz file data
• Get score metadata
• Export part score
• Generate music sheets in SVG/PNG/PDF format
• Generate MIDI
• Generate audio files in WAV, OGG, MP3, or FLAC format
• Synthesize raw audio frames, can be used in the Web Audio API
• Export as MusicXML compressed/uncompressed
• Generate position information of measures or segments on the generated sheets
• Run inside a Web Worker thread

Installation

The package is available on npm: https://www.npmjs.com/package/webmscore

npm i webmscore

Use webmscore

Load in browsers

<!-- using a CDN -->
<script src="https://cdn.jsdelivr.net/npm/webmscore/webmscore.js"></script>
<script>
    WebMscore.ready.then(async () => {
        const score = await WebMscore.load('mscz', msczdata)
    })
</script>

For latest browsers which support ES Modules

import WebMscore from 'https://cdn.jsdelivr.net/npm/webmscore/webmscore.mjs'

Run in Node.js directly

Minimum version: v8.9.0 with ES Modules support

The --experimental-modules flag is required for Node.js versions under 14,
Also require "type": "module" in package.json

import WebMscore from 'webmscore'
WebMscore.ready.then(async () => {
    const score = await WebMscore.load('mscz', msczdata)
})

Use a JavaScript bundler

(TBD)

Load extra fonts

If your score sheet contains characters out of the range of the bundled FreeFont, those characters will be shown as tofu characters (□ or �) in SVG/PNG/PDF files. Loading extra fonts is required.

webmscore can load any font format supported by FreeType.

const score = await WebMscore.load('mscz', msczdata, [...arrOfFontData])

CJK fonts are no longer bundled inside webmscore since v0.6.0

Load soundfont files

Loading a soudfont (sf2/sf3) file is required before generating/synthesizing audio.

await score.setSoundFont(soudfontData)

Soudfonts can be found on musescore.org website.

Example: (FluidR3Mono_GM.sf3)

const soudfontData = new Uint8Array(
    await (
        await fetch('https://cdn.jsdelivr.net/gh/musescore/MuseScore@2.1/share/sound/FluidR3Mono_GM.sf3')
    ).arrayBuffer()
)

Boost Mode

Sometimes you only want to process a bunch of score metadata, so drawing sheet images internally is a waste of time and system resource.

You can enable the Boost Mode by setting the doLayout parameter in WebMscore.load to false.

Example:

const score = await WebMscore.load('mscz', msczdata, [], false)
const metadata = await score.metadata()
score.destroy()

webmscore's Boost Mode is about 3x faster than the batch converter feature (-j) of the musescore software, according to the benchmark result.

WebAssembly vs native C++ program!

Compiling

1. Install essential tools like make, cmake, llvm, etc.

2. Install emscripten v2.0.6 using emsdk https://emscripten.org/docs/getting_started/downloads.html

3. Get Qt5 for WebAssembly and apply patches

AQT_PREFIX=$PWD/build.qt5
Qt5_VER=5.15.2
Qt5_DIR=${AQT_PREFIX}/${Qt5_VER}/wasm_32
# if you change the install directory or Qt version, remember to also change the `PREFIX_PATH` variable in `web/Makefile` file

# Download Qt using aqtinstall (https://github.com/miurahr/aqtinstall)
pip install aqtinstall==2.1.*
aqt install-qt linux desktop ${Qt5_VER} wasm_32 --outputdir ${AQT_PREFIX} --archives qtbase

# # Compile the `offscreen` platform plugin
# aqt install-src linux desktop ${Qt5_VER} --outputdir ${AQT_PREFIX} --archives qtbase
# cd ${AQT_PREFIX}/${Qt5_VER}/Src/qtbase/src/plugins/platforms/offscreen
# ${Qt5_DIR}/bin/qmake offscreen.pro && make
# cd - && cp -r ${AQT_PREFIX}/${Qt5_VER}/Src/qtbase/plugins build/qt/

# Apply patches, which 
#   enable the prebuilt `offscreen` QPA platform plugin (https://doc.qt.io/qt-5/qpa.html), and
#   exclude other Qt5Gui plugins
cp -r build/qt/* ${Qt5_DIR}

# Patch emcc.py to emit separate .mem files regardless of MEM_INIT_METHOD settings (MEM_INIT_METHOD won't work with wasm)
sed -i -r "s/(shared.Settings.MEM_INIT_IN_WASM = )True/\1False/" "$(which emcc).py"

1. Checkout submodules

git submodule init
git submodule update

1. Compile webmscore

cd web-public
npm i
npm run build

Build artifacts are in the web-public directory

Browser Support

All modern browsers which support WebAssembly and Async Functions

Name	Minimum Version
Chrome	57
Firefox	53, 52 (non-ESR)
Edge	16 (Fall Creators Update)
Safari	11
IE	NO!
Other browsers	I don't know!

Only tested on the latest version of Chrome and Firefox.

Examples

see files in the web-example directory

cd ./web-example
npm i
npm start  # Node.js example
npm run start:browser  # browser example

Debugging

See How to look up function names in the .symbols file?

---

webmscore is part of the LibreScore project.

Changelog

1.2.0 - 2023-01-23

Added

• Throw WasmError when webmscore encounters score processing error

Changed

• The log level can now be set before WebMscore.load(...), overrides the default behaviour which turns off logs in WebMscore.load(...).

Fixed

• For score files created in MuseScore versions older than v3.6.0, instruments no longer all sound like piano in the exported audio.