-
-
Notifications
You must be signed in to change notification settings - Fork 289
Getting Started
To get to know what OSMD can do, try Exploring the Demo!
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.
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 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).
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
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).
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.
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.