Skip to content

Getting Started

Jump to bottom
Simon edited this page Nov 26, 2021 · 42 revisions

Learning OSMD

To get to know what OSMD can do, try Exploring the Demo!

Quickstart (Plain Javascript/HTML)

This is a simplification of our Plain Javascript usage example index.html:

<div id="osmdContainer"/>
<script src="opensheetmusicdisplay.min.js"></script>
<script>
  var osmd = new opensheetmusicdisplay.OpenSheetMusicDisplay("osmdContainer");
  osmd.setOptions({
    backend: "svg",
    drawTitle: true,
    // drawingParameters: "compacttight" // don't display title, composer etc., smaller margins
  });
  osmd
    .load("http://downloads2.makemusic.com/musicxml/MozaVeilSample.xml")
    .then(
      function() {
        osmd.render();
      }
    );
</script>

(Get the latest OSMD release min.js here)

For more details, see below, especially the Plain Javascript section and usage example project.

For further options, see IOSMDOptions.

Importing OSMD

How to include OSMD in your software depends on which dynamic module loader you use.

These usage examples for OSMD are available from our Github organization page:

Also, there's a React Component (WIP) and an Angular OSMD-Component (3rd party)

We offer an npm package containing the build.

You can also import OSMD more simply with plain html and javascript, see the Plain Javascript section.

Mobile and server-side

Mobile app integration is also possible, though a bit trickier. You could use a WebView and load OSMD on a page, as in the plain javascript example.

You can also use a node script to generate PNGs and SVGs browserless (e.g. server-side),
see #670 and generateImages_browserless.js, and its usage in package.json (generate commands).

Plain Javascript

First, you need the .js binary. Either download it from our Github Releases or build it to use the latest develop branch version.

  • OSMD can be loaded in the browser with a global statement like:
<script src="opensheetmusicdisplay.min.js"></script>

This exposes the OpenSheetMusicDisplay object to the window scope.

Alternatively, to import OSMD from a hosting server, you can use something like this:

<script src="https://unpkg.com/opensheetmusicdisplay@0.8.3/build/opensheetmusicdisplay.min.js">

This is useful for testing in a live sandbox environment, e.g. jsfiddle. But be aware that this .min.js is about 1MB in size, taking some load time and bandwidth for every use.

To start displaying MusicXML documents, just pass the ID of a div element from your HTML to the constructor :

var osmd = new opensheetmusicdisplay.OpenSheetMusicDisplay("div-container", {
  autoResize: true, // just an example for an option, no option is necessary.
  backend: "svg",
  drawTitle: true,
  // put further options here
});

(for information about options, see the section Constructor options below)

This is equivalent to:

var container = document.getElementById("div-container");
var osmd = new opensheetmusicdisplay.OpenSheetMusicDisplay(container);

A MusicXML document can be loaded with:

var loadPromise = osmd.load("http://www.example.org/my-score.xml");

As the argument to load, one can specify the URL of a XML/MXL document, or pass the document itself (as a string, or as a Javascript Document object).

Notice that load returns a promise object that we want to capture in a variable.

Note that to load a file the server and/or browser need to have CORS enabled. For security reasons you can't load files from your local file system in most browsers by default (unless it's chosen by the user via file dialog). You can instead use a local server, see the Plain Javascript example repo and README for more details.

If you haven't set the container width via CSS or inline styling, do so before rendering:

container.style.width = "720px";

After the load promise resolves we can render the sheet music with the render method:

loadPromise.then(function(){
     osmd.render();
});

For transposing, look at how our demo uses the TransposeCalculator: https://github.com/opensheetmusicdisplay/opensheetmusicdisplay/blob/develop/demo/index.js

If you have trouble importing TransposeCalculator, try importing it from our plugin build: transpose-osmd-plugin.min.js.zip

OSMD Options

Since OSMD 0.5.1, the constructor takes only one optional IOSMDOptions object argument besides the HTMLElement container.

For example: 

var osmd = new OpenSheetMusicDisplay(div, {
  autoResize: false,
  backend: "canvas",
  drawingParameters: "compacttight", // more compact spacing, less padding
  drawTitle: false, // included in "compacttight"
  pageFormat: "A4_P",
});

will set up OSMD in compact mode (see setForCompactMode) so it uses less space,
not displaying the title header and instrument names.
(there's also `drawingParameters: "compacttight" now, which reduces margins etc.)

For other options, check the IOSMDOptions interface in OSMDOptions.ts.

You can alternatively simply use the default options with:
var osmd = new OpenSheetMusicDisplay(div);.

You can also set almost all options during runtime with osmd.setOptions(optionsObject), except for the render backend.
Though for many options, to take effect, you'll have to call osmd.render() again afterwards.

For the first argument and how to use the OSMD object, see the Plain Javascript section.

For more detailed but sometimes experimental options, you can try to modify some EngravingRules:

osmd.EngravingRules.StaffLineColor = "#AABBAA"; // grey instead of black

However, we can not support arbitrary modification of EngravingRules, because there are too many, and many of them are not supposed to be modified. For fully supported options, it's better to stick to OSMDOptions (though e.g. colors or StaffLineWidth should be safe to change).

Automatic resize

OSMD supports automatically adapting the music sheet to the full page (or container size), when the browser is resized.
This is enabled by default, but can be deactivated by an IOSMDOptions parameter:

var osmd = new OSMD(container, {autoResize: false});

If enabled, OSMD attaches a handler to the window.onresize event, calling osmd.render whenever the size of the window changes.

Part/Instrument selection

You can choose not to render certain parts contained in the XML (e.g. instead of voice+piano, just show voice), see here: https://github.com/opensheetmusicdisplay/opensheetmusicdisplay/wiki/Exploring-the-Demo#part-selection-not-rendering-individual-partsinstruments

In general, we recommend the Exploring the Demo page as a next step to try out some things interactively and get to know OSMD better.

Clone this wiki locally