Options
All
  • Public
  • Public/Protected
  • All
Menu

Interface IOSMDOptions

Possible options for the OpenSheetMusicDisplay constructor and osmd.setOptions(). None are mandatory. Note that after using setOptions(), you have to call osmd.render() again to make changes visible. Example: osmd.setOptions({defaultColorRest: "#AAAAAA", drawSubtitle: false}); osmd.render();

Note that some additional, usually more small scale options are available in EngravingRules, though not all of them are meant to be manipulated. The OSMDOptions are the main options we support.

Hierarchy

  • IOSMDOptions

Index

Properties

alignRests?: number

Whether to let Vexflow align rests to preceding or following notes (Vexflow option). Default false (0). This can naturally reduce collisions of rest notes with other notes. Auto mode (2) only aligns rests when there are multiple voices in a measure, and at least once at the same x-coordinate. Auto is the recommended setting, and would be default, if it couldn't in rare cases deteriorate rest placement for existing users. The on mode (1) always aligns rests, also changing their position when there is no simultaneous note at the same x-coordinate, which is nonstandard.

autoBeam?: boolean

Whether to automatically create beams for notes that don't have beams set in XML.

autoBeamOptions?: AutoBeamOptions

Options for autoBeaming like whether to beam over rests. See AutoBeamOptions interface.

autoGenerateMultipleRestMeasuresFromRestMeasures?: boolean

Set to true if subsequent measures full of rests should be auto-converted to multi-rest measure. Default is true This works across instruments- If all instruments have subsequent measures with nothing but rests, multirest measures are generated

autoResize?: boolean

Automatically resize score with canvas size. Default is true.

backend?: string

Render Backend, will be SVG if given undefined, "SVG" or "svg", otherwise Canvas.

colorStemsLikeNoteheads?: boolean

Whether to color the stems of notes the same as their noteheads. Default false.

coloringEnabled?: boolean

Whether to enable coloring noteheads and stems, depending on coloringMode.

coloringMode?: ColoringModes

Defines the mode that is used for coloring: XML (0), Boomwhacker(1), CustomColorSet (2). Default XML. If coloringMode.CustomColorSet (2) is chosen, a coloringSetCustom parameter must be added.

coloringSetCustom?: string[]

Set of 8 colors for automatic coloring of 7 notes from C to B + rest note in HTML form (e.g. "#00ff00" for green).

cursorsOptions?: CursorOptions[]

Defines multiple simultaneous cursors. If left undefined the standard cursor will be used.

darkMode?: boolean

Dark mode (black background, white notes). Simply sets defaultColorMusic and EngravingRules.PageBackgroundColor.

defaultColorLabel?: string

Default color for Labels like title or lyrics. Default black (undefined).

defaultColorMusic?: string

Default color for all musical elements including key signature etc. Can be used for dark mode etc. Default undefined.

defaultColorNotehead?: string

Default color for a note head (without stem). Default black (undefined). Only considered before loading a sample, not before render. To change the color after loading a sample and before render, use note(.sourceNote).NoteheadColor. The format is Vexflow format, either "#rrggbb" or "#rrggbboo" where is opacity (00 = transparent). All hex values. E.g., a half-transparent red would be "#FF000080", invisible/transparent would be "#00000000" or "#12345600".

defaultColorRest?: string

Default color for rests. Default black (undefined).

defaultColorStem?: string

Default color for a note stem. Default black (undefined).

defaultColorTitle?: string

Default color for labels in the title. Overrides defaultColorLabel for title labels like composer. Default black (undefined).

defaultFontFamily?: string

Default font used for text and labels, e.g. title or lyrics. Default Times New Roman Note that OSMD originally always used Times New Roman, so things like layout and spacing may still be optimized for it. Valid options are CSS font families available in the browser used for rendering, e.g. Times New Roman, Helvetica.

defaultFontStyle?: FontStyles

Default font style, e.g. FontStyles.Bold (1). Default Regular (0).

disableCursor?: boolean

Don't show/load cursor. Will override disableCursor in drawingParameters.

drawComposer?: boolean

Whether to draw the composer name (top right of the score).

drawCredits?: boolean

Whether to draw credits (title, subtitle, composer, lyricist) (in future: copyright etc., see ).

drawFingerings?: boolean

Whether to draw fingerings (only left to the note for now). Default true (unless solo part).

drawFromMeasureNumber?: number

Only draw measure n to m, where n is the number you specify. (for m, see drawUpToMeasureNumber)

drawHiddenNotes?: boolean

Whether to draw hidden/invisible notes (print-object="no" in XML). Default false. Not yet supported.

drawLyricist?: boolean

Whether to draw the lyricist's name, if given (top left of the score).

drawLyrics?: boolean

Whether to draw lyrics (and their extensions and dashes).

drawMeasureNumbers?: boolean

Whether to draw measure numbers (labels). Default true. Draws a measure number label at first measure, system start measure, and every [measureNumberInterval] measures. See the [measureNumberInterval] option, default is 2.

drawMeasureNumbersOnlyAtSystemStart?: boolean

Whether to only draw measure numbers at the start of a system ("new line"), instead of every [measureNumberInterval] measures. Default false.

drawMetronomeMarks?: boolean

Whether to draw metronome marks. Default true. (currently OSMD can only draw one at the beginning)

drawPartAbbreviations?: boolean

Whether to draw part (instrument) name abbreviations each system after the first. Only draws if drawPartNames. Default true.

drawPartNames?: boolean

Whether to draw part (instrument) names. Setting this to false also disables drawPartAbbreviations, unless explicitly enabled (drawPartNames: false, drawPartAbbreviations: true).

drawSlurs?: boolean

Whether to calculate extra slurs with bezier curves not covered by Vexflow slurs. Default true.

drawSubtitle?: boolean

Whether to draw the subtitle of the piece. If true, enables drawing Title as well.

drawTimeSignatures?: boolean

Whether to draw time signatures (e.g. 4/4). Default true.

drawTitle?: boolean

Whether to draw the title of the piece. If false, disables drawing Subtitle as well.

drawUpToMeasureNumber?: number

Only draw measure n to m, where m is the number specified. (for n, see drawFromMeasureNumber)

drawUpToPageNumber?: number

Only draw the first n pages, where n is the number specified.

drawUpToSystemNumber?: number

Only draw the first n systems, where n is the number specified.

drawingParameters?: string

Broad Parameters like compact or preview mode. Also try "compacttight", which is like compact but also reduces margins. To see what this mode does and maybe adjust the spacing parameters yourself instead of using the mode, see DrawingParameters.ts:setForCompactTightMode().

fillEmptyMeasuresWithWholeRest?: number

Whether to fill measures that don't have notes given in the XML with whole rests (visible = 1, invisible = 2, for layouting). Default No (0).

fingeringInsideStafflines?: boolean

For above/below fingerings, whether to draw them directly above/below notes (default), or above/below staffline.

fingeringPosition?: string

Where to draw fingerings (above, below, aboveorbelow, left, right, or auto). Default AboveOrBelow. Auto experimental

followCursor?: boolean

Follow Cursor: Scroll the page when cursor.next() is called and the cursor moves into a new system outside of the current view frame.

measureNumberInterval?: number

The interval of measure numbers to draw, i.e. it draws the measure number above the beginning label every x measures. Default 2.

newPageFromXML?: boolean

Whether to begin a new page ("page break") when given in XML ('new-page="yes"'). Default false, because OSMD does its own layout that will do page breaks interactively (when given a PageFormat) at different measures. So this option may result in a page break after a single measure on a page.

newSystemFromNewPageInXML?: boolean

Whether to begin a new system ("line break") when given a new page in XML ('new-page="yes"'), but newPageFromXML is false. Default false, because OSMD does its own layout that will do line breaks interactively at different measures. So this option may result in a system break after a single measure in a system.

newSystemFromXML?: boolean

Whether to begin a new system ("line break") when given in XML ('new-system="yes"'). Default false, because OSMD does its own layout that will do line breaks interactively at different measures. So this option may result in a system break after a single measure in a system.

pageBackgroundColor?: string

A custom page/canvas background color. Default undefined/transparent. Example: "#FFFFFF" = white. "#12345600" = transparent. This can be useful when you want to export an image with e.g. white background color instead of transparent, from a CanvasBackend. Note: Using a background color will prevent the cursor from being visible for now (will be fixed at some point).

pageFormat?: string

See OpenSheetMusicDisplay.PageFormatStandards for standard options like "A4 P" or "Endless". Default Endless. Uses OpenSheetMusicDisplay.StringToPageFormat(). Unfortunately it would be error-prone to set a PageFormat type directly.

percussionForceVoicesOneLineCutoff?: number

This property is only active if the above property is active (percussionOneLineCutoff) This is the cutoff for forcing all voices to the single line, instead of rendering them at different positions above/below the line. The default is 3, so if a part has less than voices, all of them will be rendered on the line. This is for cases like a Concert snare, which has multiple 'instruments' available (snare, side stick) should still render only on the line since there is no ambiguity. If this value is 0, the feature is turned off. IF this value is -1, it will render all percussion clef voices on the single line.

percussionOneLineCutoff?: number

The cutoff number for rendering percussion clef stafflines as a single line. Default is 4. This is number of instruments specified, e.g. a drumset: Drumset D. Set Acoustic Bass Drum Bass Drum 1 Side Stick Acoustic Snare ... Would still render as 5 stafflines by default, since we have 4 (or greater) instruments in this part. While a snare: Concert Snare Drum Con. Sn. Side Stick Acoustic Snare ... Would render with 1 line on the staff, since we only have 2 voices. If this value is 0, the feature is turned off. If this value is -1, it will render all percussion clefs as a single line.

preferredSkyBottomLineBatchCalculatorBackend?: SkyBottomLineBatchCalculatorBackendType

Defines which skyline and bottom-line batch calculation algorithm to use.

renderSingleHorizontalStaffline?: boolean

This makes OSMD render on one single horizontal (staff-)line. This option should be set before loading a score. It only starts working after load(), calling setOptions() after load and then render() doesn't work in this case.

setWantedStemDirectionByXml?: boolean

Whether to set the wanted stem direction by xml (default) or automatically.

skyBottomLineBatchMinMeasures?: number

Defines the minimum number of measures in the entire sheet music where the skyline and bottom-line batch calculation is enabled.

spacingBetweenTextLines?: number

Number in pixels, of spacing between multi-line labels

spacingFactorSoftmax?: number

The softmaxFactor for Vexflow's formatter. Default is 5, default in Vexflow is 100 (voice.js). Lowering this factor makes the spacing between individual notes smaller (especially from one half note to the next). So, to get more compact scores, try lowering this value (or set osmd.zoom, which simply scales), or try 100 for a more expansive layout. Setting this is the same as setting osmd.EngravingRules.SoftmaxFactorVexFlow.

stretchLastSystemLine?: boolean

Set to true if the last system line should be streched across the whole page just as the other systems. Default is false

tripletsBracketed?: boolean

Whether all triplets should be bracketed. Overrides tupletsBracketed for triplets. If false, only triplets given as bracketed in XML (bracket="yes") will be bracketed. (Bracketing all triplets can be cluttering)

tupletsBracketed?: boolean

Whether all tuplets should be bracketed (e.g. |--5--| instead of 5). Default false. If false, only tuplets given as bracketed in XML (bracket="yes") will be bracketed.

tupletsRatioed?: boolean

Whether tuplets are labeled with ratio (e.g. 5:2 instead of 5 for quintuplets). Default false.

useXMLMeasureNumbers?: boolean

Whether to read measure numbers from the "number" attribute in the xml file as opposed to defaulting to start at measure 1. Default true.

Methods

  • onXMLRead(xml: string): string
  • A custom function that is executed when the xml is read, modifies it, and returns a new xml string that OSMD then parses.

    Parameters

    • xml: string

    Returns string

Generated using TypeDoc