OSMD 2.2.0 Released: ~10% Faster Rendering, Measure-Repeat Signs & Smarter Transposition

OpenSheetMusicDisplay (OSMD) 2.2.0 is here, and it is a big one. The changelog counts 105 improvements total: 89 bug fixes, 11 features, and 5 performance improvements. Rendering is roughly 10% faster again, there are brand-new notation features such as measure-repeat (simile) signs and part groups, and a new IntervalTransposeCalculator that keeps note and chord spelling consistent with the key signature.

Performance: Rendering Gets Faster Again

Compared to OSMD 2.1.3, scores render a median 10% faster in Chrome, up to 23% faster for orchestral scores, and load 8% faster across the 21 benchmark scores. The core improvements alone make rendering ~13% faster through cheaper SVG attributes, slur curves, skyline and bounding-box calculations, and MusicXML element lookups — with byte-identical output. The skyline step is ~4% faster on average (up to 15% for orchestral scores) by formatting each vertical measure once instead of once per staff.

New Feature: IntervalTransposeCalculator

The new IntervalTransposeCalculator moves every note by the same interval, so the music keeps its spelling: the leading tone G# of A minor becomes F# in G minor. The default TransposeCalculator takes sharps or flats from the new key signature, so here it writes Gb instead. The dominant chord D–F#–A becomes D–Gb–A, and the G after it needs a natural sign. (Schumann, The Wild Horseman, measures 1–4, transposed from A minor down to G minor.) The default stays the same. Thanks to @dotkebi (PR #1770)!

import { OpenSheetMusicDisplay, IntervalTransposeCalculator } from "opensheetmusicdisplay";
const osmd = new OpenSheetMusicDisplay("container");
await osmd.load(musicXml);
// Opt in to interval-based transposition that keeps spelling
// consistent with the key signature (A# in C major -> G# in Bb major)
osmd.TransposeCalculator = new IntervalTransposeCalculator();
osmd.Sheet.Transpose = -2;
osmd.updateGraphic();
osmd.render();

import { OpenSheetMusicDisplay, IntervalTransposeCalculator } from "opensheetmusicdisplay";
const osmd = new OpenSheetMusicDisplay("container");
await osmd.load(musicXml);
// Opt in to interval-based transposition that keeps spelling
// consistent with the key signature (A# in C major -> G# in Bb major)
osmd.TransposeCalculator = new IntervalTransposeCalculator();
osmd.Sheet.Transpose = -2;
osmd.updateGraphic();
osmd.render();

Part-group names

OSMD 2.2.0 draws the names of part groups (<group-name> in MusicXML) to the left of the part names. In orchestral scores, staves are often labeled only with the players’ numbers, like the horn and trombone staves here (“1 2”, “3 4”, “3”). Now “Horns in F” and “Trombones” show which instruments they are, and later systems show the abbreviations (“Hn.”, “Trb.”). This is on by default. To turn it off, set osmd.EngravingRules.RenderPartGroupNames = false. Thanks to @kawato3 (PR #1762)!

Coloring TAB notes

`setColor()` now also colors notes in a TAB staff: their fret numbers, and modifiers like bends.
In this example, the same `setColor()` calls give each note the color of its pitch. 2.1.3 colored only the notes in the standard staff, while 2.2.0 colors the fret numbers to match.
TAB notes now also return their SVG group from `getSVGGElement()`, like other notes, so `setVisible()` can hide them and apps can style them.

New Engraving Rules

Several features arrive as new EngravingRules flags you can toggle before rendering:

const rules = osmd.EngravingRules;
// New in 2.2.0
rules.RenderMeasureRepeats = true;                     // simile / measure-repeat signs (default true)
rules.RenderPartGroupNames = true;                     // e.g. "Horns in F" before "1 2" (default true)
rules.RenderCautionaryAccidentalsInParentheses = true; // cautionary accidentals in () (default false)
rules.ReadFirstPageCreditWords = true;                 // first-page credits without page layout
rules.RenderPartAbbreviationsForSingleStaff = true;    // opt-in single-staff abbreviations
osmd.render();

const rules = osmd.EngravingRules;
// New in 2.2.0
rules.RenderMeasureRepeats = true;                     // simile / measure-repeat signs (default true)
rules.RenderPartGroupNames = true;                     // e.g. "Horns in F" before "1 2" (default true)
rules.RenderCautionaryAccidentalsInParentheses = true; // cautionary accidentals in () (default false)
rules.ReadFirstPageCreditWords = true;                 // first-page credits without page layout
rules.RenderPartAbbreviationsForSingleStaff = true;    // opt-in single-staff abbreviations
osmd.render();

Accidentals: More Faithful to the Score

Accidental handling received a lot of attention. OSMD now renders sharp-sharp as two sharp signs instead of the double-sharp symbol, and draws natural-sharp and natural-flat as a natural followed by a sharp or flat. Single-note tremolos now render correctly on notes with triple sharps or flats, and every accidental given in the XML is drawn — the first courtesy accidental after an alteration in a measure was previously skipped.

Credits Without Page Layout

Scores that provide their title, subtitle, composer or lyricist only through <credit-type> credits — and without a page layout — were previously drawn as “Untitled Score”. OSMD now reads those credits correctly, and no longer ignores all credits when just one of them is missing a page attribute.

Glissandi and Slides

A <glissando> that has no slur or slide on the same note is now read and drawn — previously it was never shown. OSMD also keeps a slur around a glissando or slide with the same number, and draws both glissandi or slides of a note that ends one and starts the next.

Metronome Marks

Metronome marks got several fixes: a mark with print-object="no" is no longer drawn (but still sets the playback tempo), the space between the note and “=” is kept in SVG output, ties in note equations are drawn, and marks at beats 2+ stay visible when beat 1 also has one. OSMD also now reads note equations written with two beat units — MusicXML’s simpler form of a metric modulation.

Ornaments

Ornaments with placement="below" are now rendered below the staff instead of always above, which fixes collisions with the upper voice when two voices share a staff. OSMD also no longer fails to load a score with a triple-sharp accidental mark on a trill, turn or mordent, and draws sharp-sharp, natural-sharp and natural-flat accidental marks as two signs, just like note accidentals.

Repetitions, Key Signatures and More

Repetition handling was overhauled: D.C., D.S., Fine and Coda are now read from the <sound> element (so “Fin” or “Ende” work in any language), a first ending with no second ending plays on the first pass only, and endless loops from mis-ordered brackets are prevented. Key signatures now keep mid-measure key changes at their musical position, and each staff reads its own key via <key number> — so the left hand can have a different key than the right.

Improved Click/Hit Detection

The GetNearest* family of methods is more precise and more flexible. Notes are now matched at the center of their note heads (including grace and cue notes and TAB fret numbers), and the search can be limited to a single page or skip grace notes:

// New optional last parameter restricts the search to one page.
// GetNearestVoiceEntry can also skip grace notes (ignoreGraceNotes).
const entry = osmd.GraphicSheet.GetNearestVoiceEntry(
  clickPosition,
  /* ignoreGraceNotes */ true,
  /* pageIndex */ 0
);

// New optional last parameter restricts the search to one page.
// GetNearestVoiceEntry can also skip grace notes (ignoreGraceNotes).
const entry = osmd.GraphicSheet.GetNearestVoiceEntry(
  clickPosition,
  /* ignoreGraceNotes */ true,
  /* pageIndex */ 0
);

Upgrade Today

With 105 improvements across performance, notation fidelity and transposition, OSMD 2.2.0 is a worthwhile upgrade for any project rendering MusicXML in the browser. Grab the full details in the changelog or view the 2.2.0 release on GitHub.