rism-digital / verovio

🎵 Music notation engraving library for MEI with MusicXML and Humdrum support and various toolkits (JavaScript, Python)

Verovio is a fast, portable and lightweight library for engraving Music Encoding Initiative (MEI) digital scores into SVG images. Verovio also contains on-the-fly converters to render Plaine & Easie Code, Humdrum, Musedata, MusicXML, EsAC, and ABC digital scores.

Verovio is written in standard 2020 C++ and can be compiled as a standalone command-line tool, used as a compiled music-rendering library for applications (Qt, python), or compiled into Javascript using the Emscripten LLVM-to-JavaScript compiler. Check out the JavaScript toolkit version of verovio running in the MEI Viewer as well as the app or tutorials for web integration and user interaction.

Verovio uses the Standard Music Font Layout (SMuFL) specification and the font can be changed for personalizing the output.

The project page is https://www.verovio.org. Verovio is available under the LGPL license (see COPYING and COPYING.LESSER).

Building and use instructions by environment

See the Reference book

LibMEI

The code for the attribute classes of Verovio are generated from the MEI schema using a modified version of LibMEI available here. The code generated is included in the Verovio repository and the LibMEI repository does not need to be cloned for building Verovio.

Major releases of Verovio and MEI versions:

• Verovio 1.x.x ⇔ MEI 3.0
• Verovio 2.x.x ⇔ MEI 4.0
• Verovio 3.x.x ⇔ Development of MEI since 4.0

From Verovio 2.x.x, the plan is to have even version numbers for Verovio releases using a stable version of MEI, and odd version numbers for releases using a development version of MEI. It means that once MEI 5.0 will be released, Verovio will move to version 4.x.x. Older versions of MEI are still supported by newer versions of Verovio. MEI files are internally upgraded when loaded into Verovio. This applies only to the features supported by Verovio. We will try to maintain this in the future.

Other libraries

The following libraries are embedded in Verovio:

library	purpose
humlib	Humdrum file import/export
JSON++	JSON data parser
MidiFile	Standard MIDI file export
pugixml	XML data parser
MINIZ-CPP	ZIP files reading/writing

Contributing

See the Reference book

Example output

The sample page of music shown below was generated with version 2.4.0-dev-2748fed

Example resources using verovio

name	type	description
Verovio Humdrum Viewer	editor	An online semi-graphical Humdrum data editor (can also be used to textually edit other digital scores compliant with verovio).
MoVI	repertory	The digital Mozart digital score VIewer at the Mozarteum
Tasso in Music Project	repertory	Musical settings of the poetry of Torquato Tasso
Measuring Polyphony	repertory	Late medieval music in black mensural and modern notations
Probstücke Digital	repertory	open and critical digital edition of Mattheson's test pieces
370 Bach Chorales	repertory	Online edition of Bach chorales, including an interactive typesetter page that allows for creating musical examples for online display or use in papers.
Humdrum Notation Plugin	tool	Javascript interface to verovio for displaying multiple musical examples on a webpage
Music Sheet Viewer	tool	WordPress plugin for displaying graphical music from MEI data

Digital score repositories on Github

Here is a list of digital score repositories on Github that can be displayed with verovio:

link	encoding	description
MEI complete examples	MEI	86 various works encoded in MEI
Mozart Piano Sonatas	Humdrum	17 Piano sonatas by W.A. Mozart from the Alte Mozart-Ausgabe (in VHV)
Beethoven Piano Sonatas	Humdrum	32 Piano sonatas by L. van Beethoven, edited by Paul Dukas (in VHV)
Josquin Research Project	Humdrum	Over 1000 scores of early Renaissance music in modern editions (website)
Tasso in Music Project	Humdrum	Critical edition of 650 Late Renaissance madrigals using the poetry of Torquato Tasso for lyrics. (website)
Music of Scott Joplin	Humdrum	Digital scores of most of Scott Joplins music
Chopin mazurkas	Humdrum	Digital scores of Chopin's mazurkas
Chopin preludes	Humdrum	Digital scores of Chopin's op. 24 preludes
J.N. Hummel preludes, op. 67	Humdrum	24 improvisatory prelude examples in every key
370 Bach chorales	Humdrum	Chorales collected by C.P.E. Bach after his father's death (website)
Deutscher Liederschatz	Humdrum	200 harmonized songs from vol. 1, edited by Ludwig Erk
Beethoven string quartets	Humdrum	18 string quartets by Ludwig van Beethoven

verovio's Issues

support for mei:supplied etc.

While mei:choice should not be handled by Verovio, it would be great if it could support elements like mei:supplied, mei:sic, mei:corr, mei:add or mei:del. The kind of support I'd be interested in is just to add an additional class to all the contained elements: g.accid.supplied, g.clef.corr etc. Another option would be to put the contents in a g.supplied which could share the @xml:id of the mei:supplied, but that might be overkill. This is just to get a simple hook to enrich output with additional information so that Javascript can make use of it…

Making format option name consitant

Currently we have --format for the C++ version and inputFormat for the JS version

Repeat sign in barlines not showing

:// or ://: or //: not parsed.

Slurs max/min should not be tangent to staff lines

minor violation: slurs max/min should not be tangent to staff lines. This makes them more difficult to see, thus making the sight reader do more work reading the music.

Beam placement needs an overhaul

medium-high violation: Beam placement in verovio will need a major overhaul sometime. I highlighted the two main bad ones on the page in the first measure of the 1st violin and viola parts. Tom Brodhead has the best implementation of automatic beam placement as a plugin program for SCORE. See the sample SCORE generated equivalent further below for how they were placed using his program. He implemented the algorithms in Ted Ross's notation book. Behind Bars also has a lengthly discussion of beams on pp. 17-26 (and also elsewhere in the book for other issues for beams). For example the marked viola beam violates the maximum angle rule mid-page on p20 as well as the requirement for a horizontal beam in this case from the guidlines midpage on p. 23.

Multi measure rest show 0

Read <chord> and minimal drawing

We need at least to read chord element and the notes (or only one note); ideally we should also draw them, even if do not want to support appropriate note head and alteration placement at this stage

Grace notes beamed with main notes

Ex: '4qq8DDrE
Grace notes should be beamed separately and only when specified explicitely
'4qq8{DD}rE
'4qq8DDrE

Tie do not show up in PAE

The + sign is supposed to tie notes. To tie notes in verovio, you need to

note1->SetTieAttrInitial();
note2->SetTieAttrTerminal( note1 );

That's it!

Fixing the resource path in cmake

The resources (data) is not install properly. Where should it go?
/usr/local/bin/shared/verovio?

The whole rests not aligned rhythmically

The whole rests do not get aligned rhythmically with the 3rd beat in 4/4; instead, they are aligned to the center of the measure independent of horizontal rhythmic spacing. The first measure on a staff would use the starting position of the first beat in the measure rather than the system barline to the left of the clef. See Behind Bars p. 159 for centering rule, and bottom of 34 for staff line to attach whole rest (book uses English term semi-breve which is equivalent to American term whole-note).

Read nested beam

Nested beams (e.g. with grace notes) currently crashes (assert) when importing MEI

The reason is that we have only one single beam pointer for the current beam being read. We need to change the to a stack and push and pos beam pointers. Two should be the limit for now? (assert)

Whole rests are one line too low

high violation (partially discussed last week): The whole rests are one line two low. It seems logical to attach whole rests to the middle line, but musicians are not rational. Putting a whole rest on that line will cause confusion with a half rest. Second problem is that centered whole rests do not get aligned rhythmically with the 3rd beat in 4/4; instead, they are aligned to the center of the measure independent of horizontal rhythmic spacing. The first measure on a staff would use the starting position of the first beat in the measure rather than the system barline to the left of the clef. So all whole rests on the page have two errors: attached to wrong staff line and not centered in measure. See Behind Bars p. 159 for centering rule, and bottom of 34 for staff line to attach whole rest (book uses English term semi-breve which is equivalent to American term whole-note).

Fermata should be placed on the top always

Generate AttComparison classes from libmei

We should generate a comparison class for each attribute following this model using the verovio version of libmei
https://github.com/rism-ch/verovio/blob/master/include/vrv/att_comparison.h
https://github.com/rism-ch/libmei

The classes can be placed in the existing files (e.g. atts_shared.*). We can have everything in the header as in the example, or splited between header and implementation.

CSS for printing

Ideally we should print only the SVG div

g-2 clef in PAE should be G-2 with octava

See http://www.iaml.info/en/activities/projects/plain_and_easy_code#Clef

.gitignore

It would be handy to create a file called .gitignore in the base directory which contains this content:

tools/CMakeCache.txt
tools/CMakeFiles/
tools/Makefile
tools/cmake_install.cmake
tools/install_manifest.txt
tools/verovio

This will suppress trying to archive these files/directories with git, and you won't have to ignore them or delete them before committing.

preserve @xml:id for <accid>

While the @xml:id of notes etc. are preserved in the resulting SVG, for svg:g.accid a new id is generated. Should be the same as on the element (even though one has to be generated for @accid…)

Replace tinyxml by pugixml in iomusicxml

Barline padding too small

Spacing of notes after a barline is too small. The the padding to the right of a barline should be one "line-space" or two MEI "virtual units". Currently the padding is 0.5 linespaces or 1 VU. Perhaps confusion between those units is the cause of the problem? In any case, the 0.5 line-space/1 VU padding does not look good and is non-standard. See pp. 42-43 of Beyond Bars for more details and exceptions. Here is an illustration showing the problem and the desired solution:

Commit in SVGDeviceContext unclear

@ahwitz : does this do anything (up to line 146) ?

https://github.com/DDMAL/verovio/blob/develop/src/svgdevicecontext.cpp#L140

PAE -4

Typing -4 (instead of 4-) causes weird results

Stem lengths, Ledger line widths, stem/notehead connections

The following example has three problems. They are in order of severity:

1. The stems which would otherwise end below the middle line of the staff must be extended to touch the middle line. No exceptions, and it is an extreme violation of notational conventions to not do so.
2. The ledger lines should have symmetric extensions on either side of the notehead. In the following example, the extension to the right of the notehead is about twice as long as the extension on the left. This is a severe but also minor violation.
3. The outside edge of the stem is not tangent with the right edge of the notehead. The termination of the stem on the notehead should not be visible outside of the notehead. This is a minor violation since it is not very visible when viewing the notation at the normal size, but it would be preferrable to fix.

Measures empty in all staves of a system do not have default width

MEI file from image is http://duchemin-dev.haverford.edu/mei/DC1204.xml.

Log with emscripten

Everything looks good. I am just a bit skeptical with the _persistent_log_string. Actually, we could use the CString we have in the ic. The only thing we need it to add in ic a method GetLogString that would be defined only with EMSCRIPTEN (like SetOptions) and that would return the array concatenated into a string:

Then we need only to do:

const char *vrvInterfaceController_getLog(InterfaceController *ic) {
ic->SetCString(ic->GetLogString());
return ic->GetCString();
}

And nothing needs to be freed elsewhere. What do you think?

stripping verovio command

When compiling the verovio command-line program, the executable contains debugging information which will not be needed in a production setting. To remove this content from the executable, there are two possibilities:

1. Run the strip command on the file (http://en.wikipedia.org/wiki/Strip_(Unix)): strip verovio
2. Add the -s option if using gcc

For example, the verovio executable is 4.8 MB with debugging info, but 1.5 MB after stripping. This should be done by default, since developers can adjust the makefile if they need to debug the program.

Distance between Key Signature and Accidental is too small

medium violation: the distance between the key signature and the accidental is too small. In this case the distance is important because the B-sharp would be the next sharp in the key signature. Behind Bars (p. 42) recommends 1.5 line-spaces (3 MEI VUs) to separate the key signature from the accidental in this case.

Fix adjustPageHeight

the adjustPageHeight option crop to much at the bottom. Border needs to be taken into account

Tuplet bracket not placed properly

The bracket is misplaced with tuplet requiring brackets (unbeamed)

Slur midpoints

Slurs should not become tangent to staff lines at their midpoint (i.e., slurs should not have their high or low points touching a staff unless absolutely necessary).

Measure rests repeated with i do not work

=5/i/i/

Light version very slow on Firefox

The light version (non ASM) is very slow on Firefox, but apparently only with the PAE (and not MEI). Memory management should be checked?

Remove m_cueSize in LayerElement

Legacy member that needs to be changed to MEI equivalent

Bug in key signatures

PAE import shows key sig on wrong octave

Fermata on rests are not shown

http://www.rism-ch.org/manuscripts/00000400110500

Incipit 1.23.1
Fermata must also be placed on the top
00000400110500: 1.29.1

clef.dis dosn't effect notes

@clef.dis and @clef.dis.place should effect the vertical position of the notes.

Double bar with repetition (rptstart //:) not parsed/shown properly in PAE

See http://www.rism-ch.org/manuscripts/00000409003467

Reading accid elements within notes as attribute

We sometimes have within notes for encoding accidentals. Because for now we do not take into account any additional information that this scheme can carry, we should just read within as @accid. So:

Add a ReadAccidAsAttr that will be called from ReadNote if the note has a child accid element and put their content into the note object.

Key, clef and time signature changes in PAE not taken into account

We need to double check if the problem is when parsing or when displaying.

beams should have a class

the actual beams (not the grouping svg:g) should have a class attribute that allows to address them later on. Could be even "beam", since the group is svg:g.beam, and the beams are svg:polygon, so they can be distinguished already.

Stems of notes on the middle line should go downwards as a default

medium-high violation: stems of notes on the middle line should go downwards as a default. Stems can go up for vocal repertories where the stem may collide with lyrics, or in instrumental music to keep the pattern of stems consistent (such as B4/C5 notes alternating). Behind Bars p. 14 top of page for discussion of this rule. Of course, if the input data has stems-up for such case (perhaps because of a diplomatic score), then this is not an error directly in verovio.

Low notes cause text to overlap elements on staff below

The low treble F on the second staff down causes the text to be placed in a position where it could overlap elements on the third staff down.

Bug found using the Apgar reading in http://digitalduchemin.org/mei/DC1220.xml. Requires DDMAL@ef3e41b commit to be rendered. I could not find mention of this in any other issues here.

Standard input

The command-line version of verovio should (must) accept standard input and be able to write to standard output. This is necessary in order to avoid the need for temporary files.

This could be done in several ways. Here is an example possibility for standard input/output processing, using the most common convention for standard input/output behavior:
cat file.xml | verovio -f mei | less

Currently output is tied to the input filename, so the -o option could take "-" as a filename, which is a usual convention for standard output:
cat file.xml | verovio -f mei -o - | less
or equivalently:
cat file.xml | verovio -f mei -o- | less

It is possible to use a similar convention for indicating standard input if you do not want to allow zero arguments:
cat file.xml | verovio -f mei -o - - | less
The second dash is the filename "-" which would indicate that standard input is being expected.

The last example is similar to processing with ps2pdf (manpage: http://man.he.net/man1/ps2pdf).

     ps2pdf file.ps
     ps2pdf file.ps file2.pdf
     cat file3.ps | ps2pdf - - > file4.pdf

The first example is similar to verovio, and the output will automatically be called file.pdf. The second example is similar to "-o file2.svg" option of verovio. The last example would be similar to the proposed "verovio -f mei -o- -" for standard input and output.

---

Standard output should be easy to implement. Standard input can be implemented by adding Toolkit::LoadFile(std::istream &in) or Toolkit::LoadFile(std::ifstream &in). The Toolkit::LoadFile(std::string &filename) function would open the file, and then call one of the previous LoadFile functions with the opened file stream, so not much extra code would be needed. The only complication will be how to calculate the byte size of standard input to preallocate the stored string size (I could look up how to do that if you like).

Double sharp showing 16th type for key sig

We should look what we have for double sharp in early notation in the Leipzig font. If none, then I would suggest to display the correct double sharp in CMN and keep the keysig one for early notation.

Implementing missing methods in MeiOutput

Methods for writing editorial elements have to be implemented.

Change SVG style attribute to separate attributes

Instead of having one single style attribute in SVG /g, we could have separate attribute for each parameter (stroke, stroke-opacity, fill, etc). This would make the building of the SVG tree cleaner.

Alternatively, we could have a CSS, but this can be left for a later enhancement.

Sample page critique

You know I am going to do it: here is a critique of the main sample page of music on the verivio website/github README.md. The example was marked up in the image below with typesetting errors in red. The green numbers refer to the list numbers below. Considering that this is the first image that people see on the website and github repository, it would be useful to fix the problems from a public relations viewpoint—or it could be a ruse to make Finale, Sibelius and Project X complacent...

1. medium violation: the distance between the key signature and the accidental is too small. In this case the distance is important because the B-sharp would be the next sharp in the key signature. Behind Bars (p. 42) recommends 1.5 line-spaces (3 MEI VUs) to separate the key signature from the accidental in this case.
2. medium-high violation: stems of notes on the middle line should go downwards as a default. Stems can go up for vocal repertories where the stem may collide with lyrics, or in instrumental music to keep the pattern of stems consistent (such as B4/C5 notes alternating). Behind Bars p. 14 top of page for discussion of this rule. Of course, if the input data has stems-up for such case (perhaps because of a diplomatic score), then this is not an error directly in verovio.
3. high violation (already mentioned): notes with lots of ledger lines must lengthen their stems to touch the middle line of the staff. See Behind Bars p. 14 middle of the page.
4. high violation (partially discussed last week): The whole rests are one line two low. It seems logical to attach whole rests to the middle line, but musicians are not rational. Putting a whole rest on that line will cause confusion with a half rest. Second problem is that centered whole rests do not get aligned rhythmically with the 3rd beat in 4/4; instead, they are aligned to the center of the measure independent of horizontal rhythmic spacing. The first measure on a staff would use the starting position of the first beat in the measure rather than the system barline to the left of the clef. So all whole rests on the page have two errors: attached to wrong staff line and not centered in measure. See Behind Bars p. 159 for centering rule, and bottom of 34 for staff line to attach whole rest (book uses English term semi-breve which is equivalent to American term whole-note).
5. minor violation: slurs max/min should not be tangent to staff lines. This makes them more difficult to see, thus making the sight reader do more work reading the music.
6. medium-high violation: Beam placement in verovio will need a major overhaul sometime. I highlighted the two main bad ones on the page in the first measure of the 1st violin and viola parts. Tom Brodhead has the best implementation of automatic beam placement as a plugin program for SCORE. See the sample SCORE generated equivalent further below for how they were placed using his program. He implemented the algorithms in Ted Ross's notation book. Behind Bars also has a lengthly discussion of beams on pp. 17-26 (and also elsewhere in the book for other issues for beams). For example the marked viola beam violates the maximum angle rule mid-page on p20 as well as the requirement for a horizontal beam in this case from the guidlines midpage on p. 23.
7. High violation (already mentioned): the padding on the barlines should be one line-space (example uses 0.5 line-space). See Behind Bars p.43.

There are a few other minor problems, but those aren't very important, mostly stem lengths and precise beam positioning which don't really affect readability. Another minor point is that the all staves in the system are equidistant from each other. Adding extra space between instrumental groups is better; also these locations are where tempo indications are usually repeated, so extra space is needed for them.

As a comparison, here is the same music which I typeset in SCORE:

Key signature change non carried in new lines

a $ key signature change overlaps with the old one in new lines.

PAE Tuplets show only 1 as number