import { VexFlowBackend } from "./../MusicalScore/Graphical/VexFlow/VexFlowBackend";
import { GraphicalMusicSheet } from "./../MusicalScore/Graphical/GraphicalMusicSheet";
import { VexFlowMusicSheetDrawer } from "./../MusicalScore/Graphical/VexFlow/VexFlowMusicSheetDrawer";
import { MusicSheet } from "./../MusicalScore/MusicSheet";
import { Cursor } from "./Cursor";
import { DrawingParameters } from "../MusicalScore/Graphical/DrawingParameters";
import { IOSMDOptions, BackendType, CursorOptions } from "./OSMDOptions";
import { EngravingRules, PageFormat } from "../MusicalScore/Graphical/EngravingRules";
import { GraphicalMusicPage } from "../MusicalScore/Graphical/GraphicalMusicPage";
import { GraphicalMeasure } from "../MusicalScore/Graphical/GraphicalMeasure";
import { ITransposeCalculator } from "../MusicalScore/Interfaces/ITransposeCalculator";
/**
* 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.
*/
export declare class OpenSheetMusicDisplay {
protected version: string;
/**
* 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.
* @param container 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)
* @param options An object for rendering options like the backend (svg/canvas) or autoResize.
* For defaults see the OSMDOptionsStandard method in the [[OSMDOptions]] class.
*/
constructor(container: string | HTMLElement, options?: IOSMDOptions);
/** Options from which OSMD creates cursors in enableOrDisableCursors(). */
cursorsOptions: CursorOptions[];
cursors: Cursor[];
get cursor(): Cursor;
get Cursor(): Cursor;
zoom: number;
protected zoomUpdated: boolean;
/** Timeout in milliseconds used in osmd.load(string) when string is a URL. */
loadUrlTimeout: number;
protected container: HTMLElement;
protected backendType: BackendType;
protected needBackendUpdate: boolean;
protected sheet: MusicSheet;
protected drawer: VexFlowMusicSheetDrawer;
protected drawBoundingBox: string;
protected drawSkyLine: boolean;
protected drawBottomLine: boolean;
protected graphic: GraphicalMusicSheet;
protected drawingParameters: DrawingParameters;
protected rules: EngravingRules;
protected autoResizeEnabled: boolean;
protected resizeHandlerAttached: boolean;
protected followCursor: boolean;
/** A 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. */
OnXMLRead: (xml: string) => string;
/**
* Load a MusicXML file
* @param content 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.
* @param tempTitle is used as the title for the piece if there is no title in the XML.
*/
load(content: string | Document | Blob, tempTitle?: string): Promise<{}>;
/**
* (Re-)creates the graphic sheet from the music sheet
*/
updateGraphic(): void;
/** Lazy rendering (LazyConsistentGraphic): number of systems already drawn into the shared
* backend across prior batches. Greedy layout is *usually* forward-stable, so the next batch skips
* redrawing these and draws from this index -- but some scores re-position earlier systems as the
* prefix grows, so each batch verifies the drawn systems against lazyDrawnSystemY and redraws from
* the topmost one that moved (reconciliation). */
private lazyDrawnSystemCount;
/** Lazy rendering: the absolute Y (in units) each already-drawn system [index] was drawn at,
* used to detect when a later batch's full-prefix layout moves an earlier system (forward-stability
* is not universal) so it can be redrawn at its corrected position. */
private lazyDrawnSystemY;
/** Lazy HORIZONTAL rendering (RenderSingleHorizontalStaffline): number of graphical measures already
* drawn into the shared SVG (left-to-right). The next batch draws from here, deferring the prefix's
* last measure (it carries an end-barline until it becomes interior), like the vertical path defers
* its last system. */
private lazyDrawnHMeasureCount;
/** Lazy HORIZONTAL: for a multi-staff score, lay the whole score out ONCE on the first batch and reuse that
* final layout for every batch (only the drawn x-window grows). A growing partial re-layout would route
* slurs/ties along each batch's boundary skyline and size the inter-staff gap to the prefix's max
* clearance -- so lower stafflines would drift down batch to batch. A single horizontal staffline always
* fits one SVG, so the full layout is safe; only the (expensive) DRAW stays lazy. Single-staff scores keep
* the growing layout (lazy layout + draw; nothing below the top line to drift). */
private lazyHReuseLayout;
/** Incremental rendering ({@link renderNext}): whether a session is in progress (started, not yet reset). */
private lazyIncrementalActive;
/** Incremental rendering: source-measure index where the next batch continues (the drawn frontier). */
private lazyNextSourceIndex;
/** Incremental rendering: the draw-measure range the lazy layout mutates, saved on begin and restored on
* reset, so a later normal render() isn't left limited to the last batch's draw range. */
private lazySavedMinMeasureToDrawIndex;
private lazySavedMaxMeasureToDrawIndex;
/** Incremental rendering: the scroll listener + its target, while enableIncrementalRenderingOnScroll() is on. */
private lazyScrollHandler;
private lazyScrollTarget;
/** Render the loaded music sheet to the container. */
render(): void;
/** Internal range-based engine behind {@link renderNext} (the public incremental API). Lays out the
* whole prefix [0..toMeasureIndex] and APPENDS the newly-stable source measures below previously
* rendered batches, without clearing the container, so a large score renders "system by system".
* clearFirst=true starts a fresh session (clears prior content, resets the counters). Returns the
* source-measure index at which the next batch should continue. fromMeasureIndex is informational --
* the drawn frontier is tracked internally. Targets the endless vertical-scroll format and
* RenderSingleHorizontalStaffline. `targetNewSystems`, if set, draws that many whole systems this batch
* (vertical path only; ignored for the single horizontal staffline, which is one system). */
private renderAppend;
/**
* 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 {@link enableIncrementalRenderingOnScroll} for scroll-to-load, or {@link 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).
*
* @param options batch options; defaults to 8 visual measures (a multi-rest counts as one). Pass
* `systems` instead to advance by whole music systems (vertical only); see {@link IRenderNextOptions}.
*/
renderNext(options?: IRenderNextOptions): IRenderNextResult;
/**
* 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.
*/
renderRemaining(): void;
/** Whether an incremental render ({@link renderNext}) is in progress (started and not yet reset). */
get IncrementalRenderingActive(): boolean;
/** Whether the in-progress incremental render has rendered the whole sheet (its last measure). */
get IncrementalRenderingComplete(): boolean;
/** Current incremental-render progress as a snapshot (same shape {@link 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. */
get IncrementalRenderProgress(): IRenderNextResult;
/** All GraphicalMeasures (one per staff/instrument) at the measure position for source-measure index
* `sourceIndex`, walking BACK over collapsed multi-rest members (which have no graphical measure of their
* own) to the nearest real measure. Empty if there is none at/before it. Used to resolve the last- /
* next-measure handles for renderNext(). */
private graphicalMeasuresAtOrBefore;
/**
* 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.
*/
resetIncrementalRendering(): void;
/**
* Drive {@link 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.
*
* @param options batch size (as {@link 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).
*/
enableIncrementalRenderingOnScroll(options?: IRenderNextOptions & {
scrollElement?: HTMLElement | Window;
}): void;
/** Stop driving {@link renderNext} from scrolling (see {@link enableIncrementalRenderingOnScroll}). */
disableIncrementalRenderingOnScroll(): void;
/** Start a fresh incremental session: save the draw-measure range the lazy layout mutates (restored on
* reset). Lazy needs the greedy, forward-stable builder so earlier systems keep their position as the
* prefix grows -- public OSMD is greedy-only, so that is already in effect (nothing to force). */
private beginIncrementalRendering;
/** Number of VISUAL measures in the source-measure range [from, toExcl): a multi-rest renders as one
* GraphicalMeasure when RenderMultipleRestMeasures collapses it, so it counts as one. */
private visualMeasureCount;
/** Source-measure index (inclusive) at which a batch of `visualCount` visual measures starting at source
* index `from` ends -- i.e. the toMeasureIndex to render this batch (multi-rests collapsed; see above). */
private visualBatchEndIndex;
/**
* Lazy rendering (EngravingRules.LazyConsistentGraphic). Lays out the WHOLE prefix
* [0..toMeasureIndex] into ONE globally-consistent graphic and draws only the systems that became
* stable since the previous batch, appending them into the shared backend below what's already drawn.
*
* There is no per-batch vertical offset or seam-distance
* computation: the real Y-layout already stacks and crisp-snaps every system at its final absolute
* position, and the title space / first-system instrument names fall out of laying the prefix from
* measure 0 each time. The greedy builder is forward-stable -- every system except the LAST of a
* prefix is *usually* forward-stable (an interior system keeps its position as the prefix grows), so
* we skip drawing the already-drawn systems above and DEFER the last system of a non-final batch (it
* is unstretched and shifts once it becomes an interior, stretched system next batch). But this is NOT
* universal -- some scores re-position earlier systems by several px as later systems are added -- so
* each batch first VERIFIES the drawn systems against their drawn Y (lazyDrawnSystemY) and, if any
* moved, redraws the whole drawn range at the corrected positions (reconciliation). In the common
* (stable) case nothing is redrawn. See export/inspect_prefix_stability.mjs / inspect_optionb_drawpos.mjs.
*
* @returns the source-measure index at which the next batch should continue (past the last drawn system).
*/
private renderAppendGrowing;
/**
* Lazy rendering for RenderSingleHorizontalStaffline (one continuous staffline, horizontal scroll).
* Lays out the whole prefix [0..toMeasureIndex] as ONE system (greedy builder at SheetMaximumWidth so it
* never breaks) and draws only the measures (and spanning elements) whose right edge first entered the
* drawn frontier this batch -- the single SVG grows to the RIGHT (and taller if later measures are tall).
* Measure X and Y are forward-stable here, so unlike the vertical path there is no reconciliation and no
* deferred last unit: every batch simply appends. SVG backend only (Canvas keeps its existing width cap).
* @returns the source-measure index at which the next batch should continue.
*/
private renderAppendGrowingHorizontal;
protected createOrRefreshRenderBackend(): void;
exportSVG(): void;
/** States whether the render() function can be safely called. */
IsReadyToRender(): boolean;
/** Clears what OSMD has drawn on its canvas. */
clear(): void;
/** 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.
*/
setOptions(options: IOSMDOptions): void;
setColoringMode(options: IOSMDOptions): void;
/**
* 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`.
*/
setLogLevel(level: string): void;
getLogLevel(): number;
/**
* Initialize this object to default values
* FIXME: Probably unnecessary
*/
protected reset(): void;
/**
* Attach the appropriate handler to the window.onResize event
*/
protected autoResize(): void;
/** 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. */
renderAndScrollBack(): void;
/**
* Helper function for managing window's onResize events
* @param startCallback is the function called when resizing starts
* @param endCallback is the function called when resizing (kind-of) ends
*/
protected handleResize(startCallback: () => void, endCallback: () => void): void;
/** Enable or disable (hide) the cursor.
* @param enable whether to enable (true) or disable (false) the cursor
*/
enableOrDisableCursors(enable: boolean): void;
createBackend(type: BackendType, page: GraphicalMusicPage, idOverride?: string): VexFlowBackend;
/** Standard page format options like A4 or Letter, in portrait and landscape. E.g. PageFormatStandards["A4_P"] or PageFormatStandards["Letter_L"]. */
static PageFormatStandards: {
[type: string]: PageFormat;
};
static StringToPageFormat(pageFormatString: string): PageFormat;
/** Sets page format by string. Used by setOptions({pageFormat: "A4_P"}) for example. */
setPageFormat(formatId: string): void;
setCustomPageFormat(width: number, height: number): void;
set DrawSkyLine(value: boolean);
get DrawSkyLine(): boolean;
set DrawBottomLine(value: boolean);
get DrawBottomLine(): boolean;
set DrawBoundingBox(value: string);
get DrawBoundingBox(): string;
setDrawBoundingBox(value: string, render?: boolean): void;
get AutoResizeEnabled(): boolean;
set AutoResizeEnabled(value: boolean);
get Zoom(): number;
set Zoom(value: number);
set FollowCursor(value: boolean);
get FollowCursor(): boolean;
set TransposeCalculator(calculator: ITransposeCalculator);
get TransposeCalculator(): ITransposeCalculator;
get Sheet(): MusicSheet;
get Drawer(): VexFlowMusicSheetDrawer;
get GraphicSheet(): GraphicalMusicSheet;
get DrawingParameters(): DrawingParameters;
get EngravingRules(): EngravingRules;
/** Returns the version of OSMD this object is built from (the version you are using). */
get Version(): string;
}
/** Options for {@link OpenSheetMusicDisplay.renderNext} (incremental, "system by system" rendering). */
export interface IRenderNextOptions {
/** Target number of visual measures to advance per batch (a multi-rest counts as ONE -- it renders as a
* single GraphicalMeasure). Defaults to 8. This is a TARGET, not an exact count: a batch always ends on a
* whole music-system (line) boundary, so the system the measure count lands inside is deferred to the next
* batch (and a batch always renders at least one whole system). The measures actually drawn may therefore
* be somewhat fewer or more than this -- e.g. 8 lands part-way into a system, so only the complete systems
* before it are drawn; or if 8 doesn't fill one system, the layout extends until one whole system is ready.
* To see what was actually rendered, read the returned {@link IRenderNextResult}: `renderedMeasures` (total
* visual measures drawn so far, cumulative) and `lastRenderedMeasure` (the GraphicalMeasures at the last
* drawn measure position). Ignored when `systems` is set (and applicable). */
measures?: number;
/** How many whole music systems (lines) to render in this batch, instead of advancing by `measures`.
* Each batch then ends exactly on a system boundary. Takes precedence over `measures` when > 0.
* VERTICAL ONLY: a single horizontal staffline (RenderSingleHorizontalStaffline) is one system, so
* `systems` is ignored there and rendering falls back to `measures`. */
systems?: number;
}
/** Progress returned by {@link OpenSheetMusicDisplay.renderNext}. Measure counts are visual (a multi-rest
* counts as one). */
export interface IRenderNextResult {
/** True once the last measure of the sheet has been rendered -- no more batches remain. */
done: boolean;
/** Visual measures rendered so far, cumulative across batches. */
renderedMeasures: number;
/** Total visual measures in the sheet. */
totalMeasures: number;
/** The last measure position rendered so far (highest measure index): all its GraphicalMeasures, one per
* staff/instrument (e.g. 3 for a voice + piano score). Empty if nothing has been rendered yet. They
* share one source measure -- reach it and its number/index via any element's `.parentSourceMeasure` and
* `.parentSourceMeasure.measureListIndex` (0-based). */
lastRenderedMeasure: GraphicalMeasure[];
/** The next measure position not yet rendered (the frontier): all its GraphicalMeasures (one per staff),
* or empty once `done`. Same `.parentSourceMeasure` / `.parentSourceMeasure.measureListIndex` accessors. */
nextUnrenderedMeasure: GraphicalMeasure[];
}