Creates and attaches an OpenSheetMusicDisplay object to an HTML element container.
After the constructor, use load() and render() to load and render a MusicXML file.
The container element OSMD will be rendered into.
Either a string specifying the ID of an HTML container element,
or a reference to the HTML element itself (e.g. div)
An object for rendering options like the backend (svg/canvas) or autoResize.
For defaults see the OSMDOptionsStandard method in the [[OSMDOptions]] class.
ProtectedautoProtectedbackendProtectedcontainerOptions from which OSMD creates cursors in enableOrDisableCursors().
ProtecteddrawProtecteddrawProtecteddrawerProtecteddrawingProtecteddrawProtectedfollowProtectedgraphicTimeout in milliseconds used in osmd.load(string) when string is a URL.
ProtectedneedA function that is executed when the XML has been read.
The return value will be used as the actual XML OSMD parses,
so you can make modifications to the xml that OSMD will use.
Note that this is (re-)set on osmd.setOptions as {return xml}, unless you specify the function in the options.
ProtectedresizeProtectedrulesProtectedsheetProtectedversionProtectedzoomStaticPageStandard page format options like A4 or Letter, in portrait and landscape. E.g. PageFormatStandards["A4_P"] or PageFormatStandards["Letter_L"].
Whether an incremental render (renderNext) is in progress (started and not yet reset).
Whether the in-progress incremental render has rendered the whole sheet (its last measure).
Current incremental-render progress as a snapshot (same shape renderNext returns), queryable at any time -- e.g. for a progress bar, or to re-render the same extent after a resize. Reports zero rendered measures when no session is active.
Returns the version of OSMD this object is built from (the version you are using).
ProtectedautoAttach the appropriate handler to the window.onResize event
Clears what OSMD has drawn on its canvas.
OptionalidOverride: stringProtectedcreateStop driving renderNext from scrolling (see enableIncrementalRenderingOnScroll).
Drive renderNext automatically from scrolling: render the next batch whenever the user scrolls within ~1.5 viewports of the not-yet-rendered edge (the page bottom for the endless vertical format, the right edge for RenderSingleHorizontalStaffline). Renders the first batch immediately if none has been rendered yet, then keeps appending as the user scrolls, and detaches itself once the whole sheet is rendered. Re-enabling replaces any previous listener; reset/render/load also detach it.
Optionaloptions: IRenderNextOptions & { scrollElement?: HTMLElement | Window }batch size (as renderNext) plus an optional scrollElement -- the element whose
scrolling drives loading. Defaults to the OSMD container for a single horizontal staffline (it scrolls
horizontally) and to window otherwise (the page scrolls vertically).
Enable or disable (hide) the cursor.
whether to enable (true) or disable (false) the cursor
ProtectedhandleHelper function for managing window's onResize events
is the function called when resizing starts
is the function called when resizing (kind-of) ends
States whether the render() function can be safely called.
Load a MusicXML file
is either the url of a file, or the root node of a MusicXML document, or the string content of a .xml/.mxl file, or a file blob.
is used as the title for the piece if there is no title in the XML.
Render the loaded music sheet to the container.
Re-render and scroll back to previous scroll bar y position in percent. If the document keeps the same height/length, the scroll bar position will basically be unchanged. For example, if you scroll to the bottom of the page, resize by one pixel (or enable dark mode) and call this, for the human eye there will be no detectable scrolling or change in the scroll position at all. If you just call render() instead of renderAndScrollBack(), it will scroll you back to the top of the page, even if you were scrolled to the bottom before.
Incrementally render the loaded sheet one batch at a time, appending each batch so a large score
paints progressively ("system by system") instead of blocking on a full render(). The first call --
or the first after load(), render() or resetIncrementalRendering() -- starts a fresh session: it
clears the container and lays the score out from the first measure. Each later call appends the next
batch. Returns progress; once done is true the whole sheet is rendered and further calls are no-ops.
Pair with enableIncrementalRenderingOnScroll for scroll-to-load, or renderRemaining to finish synchronously (e.g. before PDF/image export). Works for the endless vertical-scroll page format and for RenderSingleHorizontalStaffline (one staffline scrolling right).
Optionaloptions: IRenderNextOptionsbatch options; defaults to 8 visual measures (a multi-rest counts as one). Pass
systems instead to advance by whole music systems (vertical only); see IRenderNextOptions.
Finish an in-progress incremental render synchronously: render all remaining measures at once. Useful before PDF/image export or printing, which need every system, not just the ones scrolled into view. No-op if no incremental render is in progress, or it is already complete.
ProtectedresetInitialize this object to default values FIXME: Probably unnecessary
Abandon any in-progress incremental render and restore the draw-measure range it mutated, so a following normal render() draws the whole sheet again. Called automatically by render(), load() and clear(); call it directly only to cancel a session yourself.
Sets the logging level for this OSMD instance. By default, this is set to warn.
@param: content can be trace, debug, info, warn or error.
Set OSMD rendering options using an IOSMDOptions object. Can be called during runtime. Also called by constructor. For example, setOptions({autoResize: false}) will disable autoResize even during runtime.
Sets page format by string. Used by setOptions({pageFormat: "A4_P"}) for example.
(Re-)creates the graphic sheet from the music sheet
StaticString
The main class and control point of OpenSheetMusicDisplay.
It can display MusicXML sheet music files in an HTML element container.
After the constructor, use load() and render() to load and render a MusicXML file.