A music notation engraving library

Repetition expansion

Scores may contain repetitions, endings, or directives to repeat a section from a certain location in the score, such as dal segno or similar. Such instructions allow performers to make informed decisions about the repetition structure during performance. The MEI schema provides the <expansion> element to encode specific versions of a score’s repetition structure.

Verovio supports the expansion MEI element. When loading an MEI file, it will look for the first expansion element, and, depending on the output format, it will apply it and produce an unfolded version of the score. It realises the encoded repetitions by copying, deleting, and/or re-ordering score elements to match the specified repetition structure. This is the case by default for all time related output formats, which are MIDI, Timemap, and Expansionmap. For document related output formats, such as SVG or MEI, the score will not be expanded.

The default behaviour can be modified with a couple of options. The --expand-never option will disable the expansion for all output formats, including the performance related ones (e.g., MIDI). Oppositely, the --expand-always option will enable the expansion for all output formats, including the document related one, such as SVG.

When no expansion element is encoded, Verovio will try to infer one by parsing measure repetitions. This feature is still limited, and only simple repetition patterns will be properly inferred. Inferring expansion is also supported with the MusicXML input. Note that both input formats (MEI and MusicXML) use a distinct implementation for inferring the expansion.

Verovio also features an --expand option, which enables a specific expansion element to be selected.

The expansion element is expected to be the first element in a section or ending and must contain descendant expansion, ending, or rdg elements (see guidelines for section). Its @plist attribute may point to its descendant section, ending, rdg, or lem elements to indicate a particular expanded version of that excerpt of the score. See the MEI guidelines for a simple expansion example.

Minuet example

A typical MEI example (from the Verovio test suite example-expansion-001) is given below containing a straight-forward repetition structure in which the Minuet and the Trio are each repeated once with different endings. As indicated by “Menuett da capo”, the performer is requested to repeat the Minuet after the Trio, but then without repetition, going directly to A2 to terminate the performance.

<section xml:id="all">
  <expansion xml:id="expansion-default" plist="#A #A1 #A #A2 #B #B1 #B #B2 #A #A2"/>
  <expansion xml:id="expansion-minimal" plist="#A #A2 #B #B2 #A #A2"/>
  <expansion xml:id="expansion-maximal" plist="#A #A1 #A #A2 #B #B1 #B #B2 #A #A1 #A #A2"/>
  <section xml:id="A"/>
  <ending xml:id="A1" n="1."/>
  <ending xml:id="A2" n="2."/>
  <section xml:id="B"/>
  <ending xml:id="B1" n="1."/>
  <ending xml:id="B2" n="2."/>
</section>

An expanded version can be engraved by Verovio by triggering its expansion by passing to the toolkit the option --expand-always for the command-line, or expandAlways: true for Javascript/Pythonl, which looks like this:

This example also encodes a “minimal” expansion that omits sections A1 and B1, but still repeats the Minuet:

<expansion xml:id="expansion-minimal" plist="#A #A2 #B #B2 #A #A2"/>

This example also encodes a “maximal” expansion that realises all repeats, including in the repeated Minuet:

<expansion xml:id="expansion-maximal" plist="#A #A1 #A #A2 #B #B1 #B #B2 #A #A1 #A #A2"/>

For an example encoding this minuet with a hierarchical expansion, see below.

Exporting an expansionmap

For sections that get cloned, Verovio generates predictable xml:ids for all containing elements, appending a -rendX to the existing xml:id, where X is a number starting from 2 for the first repetition of a given element. Thus, xml:id="A-rend3" would refer to the third occurence (or the second repetition) of section "A". To track the relationship between the original score and a unfolded repeats, Verovio provides access to the expansionmap. This JSON object contains key-value pairs with unique keys for each xml:id in the encoding (both the original and the unfolded elements) and values containing a list of related (original and unfolded) elements, e.g. ["A", "A-rend2", "A-rend3"].

For more information on the expansionmap, see Output formats.

Example with re-ordered sections

The following example has a slightly more complex default expansion structure that requires section A to be rendered three times, each time choosing a different ending.

The following expansion represents a sensible default:

<expansion xml:id="default" plist="#Upbeat #A #A1 #A #A2 #B #A #A-Fine"/>

Verovio accommodates this complexity automatically by re-ordering the section structure so that it looks like this:

Hierarchical expansion structure

The elements referred to in the expansion@plist may themselves be expansion elements situated in descendent section elements.

The expansion structure of the above Minuet example could also be encoded in a hierarchical way, i.e., with separate sub-sections for Minuet and Trio, each hosting their own expansion element embedded, to which then the top-level expansion elements refer to (for the complete MEI encoding, see Verovio test suite example-expansion-003):

<section xml:id="all">
  <expansion xml:id="exp-default" plist="#exp-menuett-default #exp-trio-default #exp-menuett-minimal"/>
  <expansion xml:id="exp-minimal" plist="#exp-menuett-minimal #exp-trio-minimal #exp-menuett-minimal"/>
  <expansion xml:id="exp-maximal" plist="#exp-menuett-default #exp-trio-default #exp-menuett-default"/>
  <section xml:id="Menuett">
    <expansion xml:id="exp-menuett-default" plist="#A #A1 #A #A2"/>
    <expansion xml:id="exp-menuett-minimal" plist="#A #A2"/>
    <section xml:id="A"/>
    <ending xml:id="A1" n="1."/>
    <ending xml:id="A2" n="2."/>
  </section>
  <section xml:id="Trio">
    <expansion xml:id="exp-trio-default" plist="#B #B1 #B #B2"/>
    <expansion xml:id="exp-trio-minimal" plist="#B #B2"/>
    <section xml:id="B"/>
    <ending xml:id="B1" n="1."/>
    <ending xml:id="B2" n="2."/>
  </section>
</section>

A complex but typical example is the chained Waltz structure of An der schönen blauen Donau by Johann Strauss II. (To open a public-domain encoding in mei-friend, please click here.)

In turn, each waltz contains a set of expansion elements, each defining a repetition structure performed within the history of the Vienna New Year’s Concert series. The higher-level expansion element then refers to these waltz-level expansions.

The beginning of the section structure of the first two waltzes including the respective expansion structure looks like this:

<section xml:id="Donauwalzer">
        <expansion xml:id="Longest_Version_Krauss" plist="#Introduktion #Walzer-1-withRep-woDalSegno #Walzer-2-withRep-withDalSegno ..." />
        <expansion xml:id="Shorter_Version_Boskovsky" plist="#Introduktion #Walzer-1-woRep-woDalSegno #Walzer-2-woRep-withDalSegno ..."/>
        <section xml:id="Introduktion">
                <section xml:id="Andantino"/>
                <section xml:id="Tempo-di-Valse"/>
        </section>
        <section xml:id="Walzer-1">
                <expansion xml:id="Walzer-1-withRep-woDalSegno" plist="#Walzer-1-A #Walzer-1-B-Upbeat #Walzer-1-B #Walzer-1-B-ending1 #Walzer-1-B #Walzer-1-B-Fine"/>
                <expansion xml:id="Walzer-1-woRep-woDalSegno" plist="#Walzer-1-A #Walzer-1-B-Upbeat #Walzer-1-B #Walzer-1-B-Fine"/>
                <section xml:id="Walzer-1-A"/>
                <section xml:id="Walzer-1-B-Upbeat"/>
                <section xml:id="Walzer-1-B"/>
                <ending xml:id="Walzer-1-B-ending1" n="1."/>
                <ending xml:id="Walzer-1-B-dalSegno" n="2."/>
                <ending xml:id="Walzer-1-B-Fine" n="Fine"/>
        </section>
        <section xml:id="Walzer-2">
                <expansion xml:id="Walzer-2-withRep-withDalSegno" plist="#Walzer-2-A-Upbeat #Walzer-2-A #Walzer-2-A-ending1 #Walzer-2-A #Walzer-2-A-ending2 #Walzer-2-B #Walzer-2-A #Walzer-2-A-Fine"/>
                <expansion xml:id="Walzer-2-woRep-withDalSegno" plist="#Walzer-2-A-Upbeat #Walzer-2-A #Walzer-2-A-ending2 #Walzer-2-B #Walzer-2-A #Walzer-2-A-Fine"/>
                <section xml:id="Walzer-2-A-Upbeat"/>
                <section xml:id="Walzer-2-A"/>
                <ending xml:id="Walzer-2-A-ending1" n="1."/>
                <ending xml:id="Walzer-2-A-ending2" n="2."/>
                <ending xml:id="Walzer-2-A-Fine" n="Fine"/>
        </section>
...

The following expansion element refers to the longest and most typical realisation of this piece in the history of the Vienna New Year’s Concert series, as first conducted by Clemens Krauss:

<expansion xml:id="Longest_Version_Krauss" plist="#Introduktion #Walzer-1-withRep-woDalSegno #Walzer-2-withRep-withDalSegno #Walzer-3-withRep1-withRep2-woDalSegno #Walzer-4-withRep1-withRep2-woDalSegno #Walzer-5-withRep-woDalSegno #Coda"/>