2. Tutorial

Welcome to the MUSCIMarker tutorial! Here, you will learn how to use MUSCIMarker to annotate symbols in a musical score.


The interface in some screenshots is a little outdated (back to v0.9), but all the interface elements that the tutorial mentions are still available and in the same space.

2.1. Start MUSCIMarker

Follow the startup instructions in Running MUSCIMarker. If you have MUSCIMarker installed in a virtual environment, don’t forget to activate the environment.

After navigate to the folder that contains the main.py file in the console and runing:

python main.py

A window with the app will appear:


Let’s walk through the interface. The main part in the middle is occupied by the image that we annotate:


For marking the symbols in the score, you’ll use a bunch of tools:


To load an image, export the annotation, or to import a different annotation, use the commands on the right-hand side:


There are some convenience commands along the bottom of the screen, such as centering the image, backing up your work, or accessing the app settings:


And that includes the all-important Exit button!


2.2. Explore the image

You can zoom and move the image around. MUSCIMarker works both on a desktop and on a smartphone or tablet, but the usage is a little different.

On a tablet, the image responds to the usual touch commands: drag to move and pinch to zoom. On a desktop, you can drag & drop to move the image around as usual. For zooming, we’ll need to “simulate” one finger by right-clicking anywhere on the image. A red dot should appear:


Dragging now zooms the image, instead of moving.



The red dot is like having one finger pressed against that point in the image, and dragging with the mouse works like the second finger in the pinch-to-zoom gesture. Play around with the desktop zoom for a bit, you’ll get the hang of it soon!

Once you’re done zooming, just left-click the red dot – the “fake finger” – to exit zooming mode.


If you get lost – hey, it happens – or anytime you want to jump back to the original scale, use the CENTER command on the bottom pane.


The annotated image will scale back to its original size and center itself in the editor window.

You’ll probably be spending most of your time with MUSCIMarker zoomed in, so spend a minute getting used to navigating the image before we proceed to the next step: annotating.

2.3. Annotate objects

Annotating objects means marking regions of the image as objects from a certain set. In this tutorial, we’ll the objects are “primitives” that make up common western music notation. The set of possible notation symbols has been pre-loaded and we already have an image, so we can get right to it!

First, zoom in the image to a level where you can comfortably see all the details. (Don’t forget to “unclick” the red spot afterwards.)

Now, choose an annotation tool from the toolkit. No punches pulled, go for the Trimmed Lasso tool – it’s the most powerful one you get, and you’ll be probably spending most of your precious annotator time with that tool. So, let’s get used to it right away.


The selected tool is now highlighted.

Check which symbol type is selected:


Select a different symbol type to annotate by clicking on the current symbol type (it works like a button) and then choose from the drop-down. Drag or scroll to move the drop-down around.


To mark a symbol with the trimmed lasso, just draw the lasso around the object. Don’t worry about where you’re going in the black area: this tool ignores ignores black parts.


The bounding box of the selected symbol will appear (it’s a bit transparent, because sometimes they overlap and you need to see what’s in the image underneath).

However, when symbols overlap and you need to draw the lasso through a white
area, trace the symbol contour that you think is there very accurately.

Zoom in closer if you are not sure that the line is exactly where you want it. Accuracy matters.

Try annotating a bunch of objects!


Find out more about the available tools here: Tools

2.4. Save and load your work

Once you have annotated something, use the Export CropObject List button.


Navigate to the folder where you want to save the file. The proposed filename (ending with xml) is derived from the current image file.


Save often (every, let’s say, 3-5 minutes) - there is no “Undo”!

You can then load the exported annotations in the same way, using the Import CropObject List button, right above the Export button.


2.5. Annotating Relationships

The objects that we have annotated so far have some relationships to each other. For instance, a notehead may have an attached stem, a staccato dot, or it may also come with a beam that you need to be aware of in order to interpret the note correctly.

Let’s annotate a relationship of objects. Choose two objects that you have annotated by clicking on them:


The selected objects will brighten up. Now, press a:


A relationship was formed between the two symbols!

Note the little square in one of the symbols. A relationship leads from one object to another – it has an orientation, like an arrow. The “from” object is the one with the square (the imaginary arrow is pointing away from the square). The order of objects on the info panel is also a hint about how the relationship forms.


2.5.1. Relationships with Rules

Although you could use what you learned to just connect everything, that would not be particularly helpful. Object sets come with some rules that describe how objects form relationships. For instance, the standard rules of writing music notation say that a stem should be connected to a notehead, or that a repeat sign consists of a thin barline, a thick barline, and some dots. For the default set of musical symbols, these rules also come built-in with MUSCIMarker.

There is a lot of relationships involved in music notation, so in order to make it quicker to annotate, you can add many at once! Go ahead and select all symbols that are related to our notehead:


Now, press p:


MUSCIMarker checked which selected symbol pairs can form a relationship, and added all these potential relationships. (The objects automatically unselect. That’s to make workflow easier: after creating relationships among one set of symbols, you will probably be creating relationships for a different group of symbols.)

The p is mighty useful for adding the right relationships, and adding many of them with one keystroke. However, take care not to create extra relationships that should not be there! MUSCIMarker only knows “noteheads connect to stems”, but not “only one stem per notehead” so if you select two noteheads and two stems in hopes of doing more at once, this will happen:


(This screenshot is done with auto-deselection off, so that the selection leading to problems is obvious.)


By the way, a rule saying “only one stem per notehead” would not be correct. Can you figure out why?


Building musiclal notation relationships correctly is described in the Notes section of the Annotation Instructions.

2.6. Delete an annotation

If you make a mistake, don’t panic! The annotations can be removed. Unselect any tool you’re using and left-click on the symbol. This will mark the symbol as selected. On the screen, it will become highlighted, and some information about the symbol will be shown on the bottom of the right-hand panel.


Now, press backspace (not delete, backspace). The object will disappear and the CropObject counter on the right will go down by 1.


Whenver a tool is selected, all mouse activity inside the image is handled by the tool. So if you hadn’t deactivated the tool before selecting the object, the click would be caught and interpreted as a very small lasso. (This is because when you want to annotate a symbol, nothing you have previously done should get in the way.)

Just like objects, you can also select relationships by clicking on them.

2.7. Other stuff

There are some other useful operations MUSCIMarker allows you to do:

2.7.1. Annotate things that don’t fit on the screen

Sometimes you need to zoom in a lot to annotate overlapping symbols accurately, but then the symbol does not fit on the screen. (This mostly happens with barlines and ties/slurs.) What now?

The symbols support a merge operation: you can mark it in parts and then join them into one. Marking the parts is exactly the same as marking anything else: for the time being, the program will think there are, let’s say, three barlines. However, we then select the parts and press m. Voila: they merge! Make sure the parts overlap, though: otherwise, the merged symbol would have gaps.

2.7.2. Load a different image

It’s analogous to how saving works, just use the Select image file button on the right.


Again, just navigate to the desired image, click it and click Load. Quite simple, eh? Remember to export your annotations before you load a new image, though: once an image is loaded, all the annotations are cleared (they referred to the previous image, so it doesn’t make any sense to leave them with the new image).