OpenSheetMusicDisplay

To style an individual block, use Advanced -> Additional CSS class(es) in the block editor and add the corresponding styles to your theme.

OSMD Sheet Music Block Options

The block has a number of options in the sidebar (Inspector Controls) described here.

Rendering

The section immediately below the block heading contains two controls related to re-rendering the sheet music.

Automatically Rerender on Change

Toggle, Default: Off When this is on, changes to the score settings (except for ‘Container Aspect Ratio’) trigger a re-render of the sheet music in the editor. Changes affecting only Music Braille regenerate the braille output without re-rendering the score.

This is not recommended for larger pieces of sheet music, as rendering can take time. It is best to do ‘batch’ updates with the settings and use the ‘Rerender’ button to manually preview the changes.

Rerender

Button This button is used to trigger a manual rerender of the sheet music in the currently selected OSMD block. This is particularly useful for updating the settings of larger pieces of sheet music that take longer to render.

Basic Options

This section contains basic options for the block: the musicXML file to render as well as some display options.

Select Media

Button/File Select, Default: None Selected This control shows the currently selected score above it (if there is one). The button ‘Select Media’ opens your WordPress Media Library in a modal window, which allows you to select previously uploaded MusicXML, or to upload one to select for rendering in the block.

NOTE: Selecting a new file will always trigger a render of the new file, no matter if “Automatically Rerender on Change” is selected or not.

Width (%)

Number Input, Default: 100 This control translates directly to the CSS width of the sheet music. What this means is that it controls the percentage of the parent container that the sheet music will take up. e.g. – If you have the OSMD block in a post set to 100%, it will fill the entire width of the post – If you have the OSMD block in a column layout of a post set to 100%, it will fill the entire width of that column

Container Aspect Ratio

Dropdown/Number Input, Default: Auto (No Scrollbar) This dropdown sets the aspect ratio of the sheet music container – The height in relation to the width. What this does pratically is add a scrollbar, which is useful with very long pieces that you don’t want to extend all the way down the page. – Auto (No Scrollbar) will render the full sheet music as-is, taking up as much room as needed. – Landscape makes the height 0.667x the width. Or, put another way, the width will be 1.5x the height (3:2) – Portrait sets the height to 1.778x the width. Width being 0.5625x the height (9:16) – Custom allows you to set your own value of what the width will be divided by to get the height.

NOTE: This control does not trigger or require a re-render since it is merely a CSS property of the sheet music container. It will be reflected immediately.

Zoom (%)

Number Input, Default: 100 This input allows you to control the zoom level of the rendered sheet music.

Drawing Options

These are additional OSMD drawing options – Whether to render certain parts of the sheet music.

Draw Title

Toggle, Default: On Whether to render the sheet music title.

NOTE: Draw Subtitle must be off for this to be reflected in the sheet music (currently).

Draw Subtitle

Toggle, Default: On Whether to render the sheet music subtitle.

Draw Composer

Toggle, Default: On Whether to render the sheet music composer.

NOTE: There seem to be some rendering issues in OSMD with this option if ‘Draw Lyricist’ is not off as well. We are working on this.

Draw Lyricist

Toggle, Default: On Whether to render the sheet music Lyricist.

Draw Metronome Marks

Toggle, Default: On Whether to render the tempo markings.

Draw Part Names

Toggle, Default: On Whether to render the part names before each stave.

Draw Part Abbreviations

Toggle, Default: On Whether to render the part abbreviations on subsequent music systems.

Draw Measure Numbers

Toggle, Default: On Whether to render measure numbers

Draw Measure Numbers Only at System Start

Toggle, Default: Off Whether to render measure numbers just at the start of new music systems.

Draw Time Signatures

Toggle, Default: On Whether to render time signatures on the staves

New Systems From XML

Toggle, Default: Off This determines whether system breaks specified in the MusicXML will be honored.

Music Braille

Open the Music Braille panel in the block sidebar and enable Show Music Braille . The remaining braille controls appear when it is enabled. All seven toggles default to Off.

Braille output is selectable Unicode text. It includes notes, rests, octave signs, key and time signatures, chords, voices, dynamics, articulations, ornaments, ties, slurs and repeats. Multi-staff scores are detected automatically; keyboard output includes hand signs.

Show Music Braille

Renders Music Braille below the sheet music in the editor and on the published page.

Hide Score (Braille Only)

Hides the printed sheet music and keeps the braille output visible. This can be combined with any braille layout.

Lyrics

Adds aligned word and music lines for vocal music, including multiple verses when present in the MusicXML.

Bar-over-bar (Keyboard)

Aligns the right-hand and left-hand music vertically, measure by measure. This option applies to multi-staff scores and has no effect on a single-staff score.

Ensemble

Produces aligned music for multiple instruments with instrument abbreviations and an instrument list. Enable it explicitly for ensemble scores; it has no effect on a single-instrument score.

Facsimile (Mirror Print Layout)

Includes clef and octave-shift signs. For a single-staff score, braille line breaks follow the rendered score’s system breaks. Keyboard, ensemble and lyrics layouts retain their own line grouping.

Show Translation (Sign Meanings)

Adds a translation view below the braille text, grouped by measure, explaining the musical meaning of the signs.

When combining layout options, Ensemble takes precedence for scores with multiple instruments, followed by Lyrics, then the multi-staff keyboard layout. Bar-over-bar aligns the keyboard layout; Facsimile adds its signs to the selected layout.

With Automatically Rerender on Change enabled, changes affecting only braille update its display without redrawing the score. With it disabled, click Rerender to apply queued braille settings.

OpenSheetMusicDisplay Shortcode Options

The shortcode has the same options as above. Attribute names can be written in camelCase or lowercase.

In the shortcode any Toggle attribute values are specified with true or false. Numeric values can be specified as float or integers.

To specify the musicXML you need to provide a URL; This can be copied from your Media center in WordPress when viewing the details of a file.

The shortcode is “opensheetmusicdisplay”. Example with drawing options: [opensheetmusicdisplay musicXmlUrl="http://url.com/wp-content/uploads/sites/2/2021/02/Beethoven_AnDieFerneGeliebte.xml" zoom="0.75" width="75" drawTitle="false" drawSubtitle="false" drawComposer="true" drawLyricist="true" drawMetronomeMarks="false" drawPartNames="false" drawPartAbbreviations="false" drawMeasureNumbers="true" drawMeasureNumbersOnlyAtSystemStart="true" drawTimeSignatures="true"]

It’s important to note that zoom is out of 1: so 1 = 100%, 0.75 = 75%, 2 = 200%, etc.

Music Braille Shortcode Attributes

Attribute Block control

brailleenabled Show Music Braille

braillehidescore Hide Score (Braille Only)

braillelyrics Lyrics

braillebaroverbar Bar-over-bar (Keyboard)

brailleensemble Ensemble

braillefacsimile Facsimile (Mirror Print Layout)

brailleshowtranslation Show Translation (Sign Meanings)

All braille attributes default to false . Set brailleenabled="true" to enable braille output; the other attributes customize it as described in the block options above.

Show braille alone with explanations of the signs:

`

[opensheetmusicdisplay musicxmlurl=”https://example.com/score.musicxml” brailleenabled=”true” braillehidescore=”true” brai