Manual

The archicture of ms3

This page is a detailed guide for using ms3 for different tasks. It supposes you are working in an interactive Python interpreter such as IPython, Jupyter, Google Colab, or just the console.

Good to know

Corpus structure

ms3 extracts various aspects (e.g. notes, chord labels, dynamics) from a single MuseScore file and stores them in separate TSV files. In order to jointly evaluate this information (e.g. to combine harmony labels with the corresponding notes in the score), ms3 associates files by their names. Therefore it is important to not rename files at a later point and it is recommended to stick to one organizational principle for all corpora in use. The two main principles are suffixes and subfolders.

DCML corpora use the same subfolder structure: MuseScore files are stored in the MS3 folder of a corpus and all other aspects are stored with identical filenames (but different extension) in sibling folders. This structure results naturally when using default parameters such as ms3 extract -N -M -X:

corpus1
├── harmonies
├── measures
├── MS3
└── notes
corpus2
├── harmonies
├── measures
├── MS3
└── notes

When loading corpora, ms3 looks for the standard folder names (and suffixes) to indentify individual corpora and assign them keys automatically (e.g. in the example above, ‘corpus1’ and ‘corpus2’). Using the default names will therefore facilitate the use of the library considerably.

Label types

ms3 recognizes different types of labels, depending on how they are encoded in MuseScore:

label_type

explanation

0

Label encoded in MuseScore’s chord layer (Add->Text->Chord Symbol, or [C]+K) that does not start with a note name, i.e. MuseScore did not recognize it as an absolute chord and encoded it as plain text (compare type 3).

1

Roman Numeral (Add->Text->Roman Numeral Analysis).

2

Nashville number (Add->Text->Nashville Number).

3

Label encoded in MuseScore’s chord layer (Add->Text->Chord Symbol, or [C]+K) that does start with a note name, i.e. MuseScore did recognize it as an absolute chord and encoded its root (and bass note) as numerical values.

Independent of the type, ms3 will also try to infer whether the label conforms to the DCML syntax, in which case the type information will appear with a subtype, e.g. 0 (dcml). If instead or additionally you want other subtypes to be recognized, specify the infer_label_types attribute.

Measure counts (MC) vs. measure numbers (MN)

Measure counts are strictly increasing numbers for all <measure> nodes in the score, regardless of their length. This information is crucial for correctly addressing positions in a MuseScore file and are shown in the software’s status bar. The first measure is always counted as 1 (following MuseScore’s convention), even if it is an anacrusis.

Measure numbers are the traditional way by which humans refer to positions in a score. They follow a couple of conventions which can be summarised as counting complete bars. Quite often, a complete bar (MN) can be made up of two <measure> nodes (MC). In the context of this library, score addressability needs to be maintained for humans and computers, therefore a mapping MC -> MN is preserved in the score information DataFrames.

Onset positions

Onsets express positions of events in a score as their distance from the beginning of the corresponding MC or MN. The distances are expressed as fractions of a whole note. In other words, beat 1 has onset 0, an event on beat 2 of a 4/4 meter has onset 1/4 and so on.

Since there are two ways of referencing measures (MC and MN), there are also two ways of expressing onsets:

  • mc_onset expresses the distance from the corresponding MC

  • mn_onset expresses the distance from the corresponding MN

In most cases, the two values value will be identical, but take as an example the case where a 4/4 measure with MN 8 is divided into MC 9 of length 3/4 and MC 10 of length 1/4 because of a repeat sign or a double bar line. Since MC 9 corresponds to the first part of MN 8, the two onset values are identical. But for the anacrusis on beat 4, the values differ: mc_onset is 0 but mn_onset is 3/4 because this is the distance from MN 8.

Read-only mode

For parsing faster using less memory. Scores parsed in read-only mode cannot be changed because the original XML structure is not kept in memory.

Stacks-of-fifths intervals

In order to express note names (tonal pitch classes, tpc), and scale degrees, ms3 uses stacks of fifths (the only way to express these as a single integer). For note names, 0 corresponds to C, for scale degrees to the local tonic.

fifths

note name

interval

scale degree

-6

Gb

d5

b5

-5

Db

m2

b2

-4

Ab

m6

b6 (6 in minor)

-3

Eb

m3

b3 (3 in minor)

-2

Bb

m7

b7 (7 in minor)

-1

F

P4

4

0

C

P1

1

1

G

P5

5

2

D

M2

2

3

A

M6

6 (#6 in minor)

4

E

M3

3 (#3 in minor)

5

B

M7

7 (#7 in minor)

6

F#

A4

#4

Voltas

“Prima/Seconda volta” is the Italian designation for “First/Second time”. Therefore, in the context of ms3, we refer to ‘a volta’ as one of several endings. By convention, all endings should have the same measure numbers (MN), which are often differentiated by lowercase letters, e.g. 8a for the first ending and 8b for the second ending. In MuseScore, correct bar numbers can be achieved by excluding 8b from the count or, if the endings have more than one bar, by subtracting the corresponding number from the second ending’s count. For example, in order to achieve the correct MNs [7a 8a][7b 8b], you would add -2 to 7b’s count which otherwise would come out as 9.

ms3 checks for incorrect MNs and warns you if the score needs correction. It will also ask you to make all voltas the same length. If this is not possible for editorial reasons (although often the length of the second volta is arbitrary), ignore the warning and check in the measures table if the MN are correct for your purposes.

Tables with score information

This section gives an overview of the various tables that ms3 exposes after parsing a MuseScore file. Their names, e.g. measures, correspond to the properties of Score and the methods of Parse with which they can be retrieved. They come as pandas.DataFrame objects. The available tables are:

All score information, except the metadata, is contained in the following two tables:

  • measures: A list of all measures contained in the score together with their respective features.

  • notes: A list of all notes contained in the score together with their respective features.

  • rests: A list of all rests contained in the score together with their respective features.

  • notes_and_rests: A combination of the two above.

  • chords: Not to be confounded with labels or chord annotations, a chord is a notational unit in which all included notes are part of the same notational layer and have the same onset and duration. Every chord has a chord_id and every note is part of a chord. These tables are used to convey score information that is not attached to a particular note, such as lyrics, staff text, dynamics and other markup.

  • labels: The annotation labels contained in the score. The output can be controlled by changing the labels_cfg configuration.

  • expanded: If the score contains DCML harmony labels, return them after being split into the encoded features.

  • cadences: If DCML harmony labels include cadence labels, return only those (simply a filter on expanded).

  • events: A raw version of the score where the XML tags of all events have been transformed to column names. Cumbersome to work with and only needed in special cases.

For each of the available tables you will see an example and you can click on the columns to learn about their meanings.

Measures

>>> s.mscx.measures   # access through a Score object
>>> p.measures()      # access through a Parse object

mc

mn

keysig

timesig

act_dur

mc_offset

volta

numbering_offset

dont_count

barline

breaks

repeats

next

1

1

-4

4/4

1

0

<NA>

<NA>

<NA>

NaN

NaN

firstMeasure

(2,)

2

2

-4

4/4

1

0

<NA>

<NA>

<NA>

NaN

NaN

nan

(3,)

Notes

>>> s.mscx.notes   # access through a Score object
>>> p.notes()      # access through a Parse object

mc

mn

mc_onset

mn_onset

timesig

staff

voice

duration

gracenote

nominal_duration

scalar

tied

tpc

midi

volta

chord_id

1

1

0

0

4/4

4

2

1/8

NaN

1/8

1

<NA>

-1

53

<NA>

4

1

1

0

0

4/4

3

2

3/4

NaN

1/2

3/2

<NA>

-1

77

<NA>

1

Rests

>>> s.mscx.rests   # access through a Score object
>>> p.rests()      # access through a Parse object

mc

mn

mc_onset

mn_onset

timesig

staff

voice

duration

nominal_duration

scalar

volta

1

1

0

0

4/4

1

1

1

1

1

<NA>

1

1

0

0

4/4

2

1

1

1

1

<NA>

Notes and Rests

>>> s.mscx.notes_and_rests   # access through a Score object
>>> p.notes_and_rests()      # access through a Parse object

mc

mn

mc_onset

mn_onset

timesig

staff

voice

duration

gracenote

nominal_duration

scalar

tied

tpc

midi

volta

chord_id

1

1

0

0

4/4

4

2

1/8

NaN

1/8

1

<NA>

-1

53

<NA>

4

1

1

0

0

4/4

3

2

3/4

NaN

1/2

3/2

<NA>

-1

77

<NA>

1

1

1

0

0

4/4

3

1

1/2

NaN

1/2

1

<NA>

<NA>

<NA>

<NA>

<NA>

1

1

0

0

4/4

4

1

1/2

NaN

1/2

1

<NA>

<NA>

<NA>

<NA>

<NA>

Chords

In a MuseScore file, every note is enclosed by a <Chord> tag. One <Chord> tag can enclose several notes, as long as they occur in the same staff and voice (notational layer). As a consequence, notes belonging to the same <Chord> have the same onset and the same duration.

Why chord lists? Most of the markup (such as articulation, lyrics etc.) in a MuseScore file is attached not to individual notes but instead to <Chord> tags. It might be a matter of interpretation to what notes exactly the symbols pertain, which is why it is left for the interested user to link the chord list with the corresponding note list by joining on the chord_id column of each.

Standard columns

The output of the analogous commands depends on what markup is available in the score (see below). The columns that are always present in a chord list are exactly the same as (and correspond to) those of a note list except for tied, tpc, and midi.

mc

mn

mc_onset

mn_onset

timesig

staff

voice

duration

gracenote

nominal_duration

scalar

volta

chord_id

1

1

1/2

1/2

4/4

3

1

1/2

NaN

1/2

1

<NA>

0

1

1

0

0

4/4

3

2

3/4

NaN

1/2

3/2

<NA>

1

Such a reduced table can be retrieved using Score.mscx.parsed.get_chords(mode='strict')

Dynamic columns

Leaving the standard columns aside, the normal interface for accessing chord lists calls Score.mscx.parsed.get_chords(mode='auto') meaning that only columns are included that have at least one non empty value. The following table shows the first two non-empty values for each column when parsing all scores included in the ms3 repository for demonstration purposes:

>>> s.mscx.chords   # access through a Score object
>>> p.chords()      # access through a Parse object

lyrics:1

dynamics

articulation

staff_text

tempo

qpm

slur

decrescendo_hairpin

diminuendo_line

crescendo_hairpin

crescendo_line

Ottava:15mb

Ottava:8va

pedal

system_text

<NA>

<NA>

<NA>

<NA>

Grave

45

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

0

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

0

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

p

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

articStaccatoBelow

<NA>

<NA>

<NA>

2

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

articStaccatoBelow

<NA>

<NA>

<NA>

2

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

simile

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

espr.

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

other-dynamics

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

0

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

0, 1

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

0

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

0

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

Sta

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

bat

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

Andante amoroso

55

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

0

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

0

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

0

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

0

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

0

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

0

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

0

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

0

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

0

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

0

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

<NA>

Swing

Labels

>>> s.mscx.labels   # access through a Score object
>>> p.labels()      # access through a Parse object

mc

mn

mc_onset

mn_onset

timesig

staff

voice

volta

label

label_type

1

1

0

0

4/4

3

2

<NA>

.f.i

0 (dcml)

1

1

1/4

1/4

4/4

3

2

<NA>

i6

0 (dcml)

Expanded

>>> s.mscx.expanded   # access through a Score object
>>> p.expanded()      # access through a Parse object

mc

mn

mc_onset

mn_onset

timesig

staff

voice

volta

label

globalkey

localkey

pedal

chord

numeral

form

figbass

changes

relativeroot

cadence

phraseend

chord_type

globalkey_is_minor

localkey_is_minor

chord_tones

added_tones

root

bass_note

1

1

0

0

4/4

3

2

<NA>

.f.i

f

i

NaN

i

i

NaN

NaN

NaN

NaN

NaN

NaN

m

True

True

(0, -3, 1)

()

0

0

1

1

1/4

1/4

4/4

3

2

<NA>

i6

f

i

NaN

i6

i

NaN

6

NaN

NaN

NaN

NaN

m

True

True

(-3, 1, 0)

()

0

-3

Cadences

This table is simply a filter on expanded. The table has the same columns and contains only rows that include a cadence label. Just for convenience…

>>> s.mscx.cadences   # access through a Score object
>>> p.cadences()      # access through a Parse object

Events

This table is the original tabular representation of the MuseScore file’s source code from which all other tables, except measures are generated. The nested XML tags are transformed into column names.

The value '∅' is used for empty tags. For example, in the column Chord/Spanner/Slur it would correspond to the tag structure (formatting as in an MSCX file):

<Chord>
  <Spanner type="Slur">
    <Slur>
      </Slur>
    </Spanner>
  </Chord>

The value '/' on the other hand represents a shortcut empty tag. For example, in the column Chord/grace16 it would correspond to the tag structure (formatting as in an MSCX file):

<Chord>
  <grace16/>
  </Chord>

Parsing

This chapter explains how to

  • parse a single score to access and manipulate the contained information using a Score object

  • parse a group of scores to access and manipulate the contained information using a Parse object.

Parsing a single score

  1. Import the library.

    To parse a single score, we will use the class Score. We could import the whole library:

    >>> import ms3
    >>> s = ms3.Score()
    

    or simply import the class:

    >>> from ms3 import Score
    >>> s = Score()
    
  2. Locate the MuseScore 3 score you want to parse.

    Tip

    MSCZ files are ZIP files containing the uncompressed MSCX. In order to trace the score’s version history, it is recommended to always work with MSCX files.

    In the examples, we parse the annotated first page of Giovanni Battista Pergolesi’s influential Stabat Mater. The file is called stabat.mscx and can be downloaded from here (open link and key Ctrl + S to save the file or right-click on the link to Save link as...).

  3. Create a Score object.

    In the example, the MuseScore 3 file is located at ~/ms3/docs/stabat.mscx so we can simply create the object and bind it to the variable s like so:

    >>> from ms3 import Score
    >>> s = Score('~/ms3/docs/stabat.mscx')
    
  4. Inspect the object.

    To have a look at the created object we can simply evoke its variable:

    >>> s
    MuseScore file
    --------------
    
    ~/ms3/docs/stabat.mscx
    
    Attached annotations
    --------------------
    
    48 labels:
    staff  voice  label_type  color_name
    3      2      0 (dcml)    default       48
    

Parsing options

Score.__init__(musescore_file=None, infer_label_types=['dcml'], read_only=False, labels_cfg={}, logger_cfg={}, parser='bs4', ms=None)[source]
Parameters
  • musescore_file (str, optional) – Path to the MuseScore file to be parsed.

  • infer_label_types (list or dict, optional) – Determine which label types are determined automatically. Defaults to [‘dcml’]. Pass [] to infer only main types 0 - 3. Pass {'type_name': r"^(regular)(Expression)$"} to call ms3.Score.new_type().

  • read_only (bool, optional) – Defaults to False, meaning that the parsing is slower and uses more memory in order to allow for manipulations of the score, such as adding and deleting labels. Set to True if you’re only extracting information.

  • labels_cfg (dict) – Store a configuration dictionary to determine the output format of the Annotations object representing the currently attached annotations. See MSCX.labels_cfg.

  • logger_cfg (dict, optional) – The following options are available: ‘name’: LOGGER_NAME -> by default the logger name is based on the parsed file(s) ‘level’: {‘W’, ‘D’, ‘I’, ‘E’, ‘C’, ‘WARNING’, ‘DEBUG’, ‘INFO’, ‘ERROR’, ‘CRITICAL’} ‘file’: PATH_TO_LOGFILE to store all log messages under the given path.

  • parser ('bs4', optional) – The only XML parser currently implemented is BeautifulSoup 4.

  • ms (str, optional) – If you want to parse musicXML files or MuseScore 2 files by temporarily converting them, pass the path or command of your local MuseScore 3 installation. If you’re using the standard path, you may try ‘auto’, or ‘win’ for Windows, ‘mac’ for MacOS, or ‘mscore’ for Linux.

Parsing multiple scores

  1. Import the library.

    To parse multiple scores, we will use the class ms3.Parse. We could import the whole library:

    >>> import ms3
    >>> p = ms3.Parse()
    

    or simply import the class:

    >>> from ms3 import Parse
    >>> p = Parse()
    
  2. Locate the folder containing MuseScore files.

    In this example, we are going to parse all files included in the ms3 repository which has been cloned into the home directory and therefore has the path ~/ms3.

  3. Create a Parse object

    The object is created by calling it with the directory to scan, and bound to the typical variable p. ms3 scans the subdirectories for corpora (see Corpus structure) and assigns keys automatically based on folder names (here ‘docs’, and ‘tests’):

    >>> from ms3 import Parse
    >>> p = Parse('~/ms3')
    >>> p
    
    76 files.
    KEY   -> EXTENSIONS
    -------------------
    docs  -> {'.mscx': 4}
    tests -> {'.tsv': 62, '.mscx': 10}
    
    None of the 14 score files have been parsed.
    

    Without any further parameters, ms3 detects only file types that it can potentially parse, i.e. MSCX, MSCZ, and TSV. In the following example, we infer the location of our local MuseScore 3 installation (if ‘auto’ fails, indicate the path to your executable). As a result, ms3 also shows formats that MuseScore can convert, such as XML, MIDI, or CAP.

    >>> from ms3 import Parse
    >>> p = Parse('~/ms3', ms='auto')
    >>> p
    
    77 files.
    KEY   -> EXTENSIONS
    -------------------
    docs  -> {'.mscx': 4}
    tests -> {'.tsv': 62, '.mscx': 10, '.xml': 1}
    
    None of the 15 score files have been parsed.
    
    MuseScore 3 executable has been found.
    

    By default, present TSV files are detected and can be parsed as well, allowing one to access already extracted information without parsing the scores anew. In order to select only particular files, a regular expression can be passed to the parameter file_re. In the following example, only files ending on mscx are collected in the object ($ stands for the end of the filename, without it, files including the string ‘mscx’ anywhere in their names would be selected, too):

    >>> from ms3 import Parse
    >>> p = Parse('~/ms3', file_re='mscx$', key='ms3')
    >>> p
    
    14 files.
    KEY -> EXTENSIONS
    -----------------
    ms3 -> {'.mscx': 14}
    
    None of the 14 score files have been parsed.
    

    In this example, we assigned the key 'ms3'. Note that the same MSCX files that were distributed over several keys in the previous example are now grouped together. Keys allow operations to be performed on a particular group of selected files. For example, we could add MSCX files from another folder using the method add_dir() and the key 'other':

    >>> p.add_dir('~/other_folder', file_re='mscx$', key='other')
    >>> p
    
    72 files.
    KEY   -> EXTENSIONS
    -------------------
    ms3   -> {'.mscx': 14}
    other -> {'.mscx': 58}
    
    None of the 72 score files have been parsed.
    

    Most methods of the Parse object have a keys parameter to perform an operation on a particular group of files.

  4. Parse the scores.

    In order to simply parse all registered MuseScore files, call the method parse_mscx(). Instead, you can pass the argument keys to parse only one (or several) selected group(s) to save time. The argument level controls how many log messages you see; here, it is set to ‘critical’ or ‘c’ to suppress all warnings:

    >>> p.parse_mscx(keys='ms3', level='c')
    >>> p
    
    INFO     Parse -- parse.py (line 1713) parse_mscx():
    	All 14 files have been parsed successfully.
    72 files.
    KEY   -> EXTENSIONS
    -------------------
    ms3   -> {'.mscx': 14}
    other -> {'.mscx': 58}
    
    14/72 MSCX files have been parsed.
    
    8 of them have annotations attached.
    KEY -> ANNOTATION LAYERS
    ------------------------
    ms3 -> staff  voice  label_type          color             
        -> 2      1      0 (dcml)            default               167
        -> 3      1      0 (dcml)            default                63
        ->        2      0 (dcml)            default                48
        -> 1      1      0 (Plain Text)      default                 7
        ->               3 (Absolute Chord)  default               166
        ->               0 (dcml)            default               568
        -> 3      1      0 (dcml)            blue                    1
        ->                                   cyan                    1
        ->                                   lime                    1
        ->                                   magenta                 1
        ->                                   ms3_aquamarine          1
        ->                                   ms3_blue                1
        ->                                   ms3_chartreuse          1
        ->                                   ms3_cornflowerblue      1
        ->                                   ms3_darkcyan            1
        ->                                   ms3_darkgoldenrod       1
        ->                                   ms3_darkgray            1
        ->                                   ms3_darkmagenta         1
        ->                                   ms3_darkolivegreen      1
        ->                                   ms3_darkslateblue       1
        ->                                   ms3_darkviolet          1
        ->                                   ms3_deeppink            1
        ->                                   ms3_deepskyblue         1
        ->                                   ms3_dodgerblue          1
        ->                                   ms3_green               1
        ->                                   ms3_indianred           1
        ->                                   ms3_indigo              1
        ->                                   ms3_khaki               1
        ->                                   ms3_lawngreen           1
        ->                                   ms3_lightcoral          1
        ->                                   ms3_lightgreen          1
        ->                                   ms3_lightpink           1
        ->                                   ms3_lightsalmon         1
        ->                                   ms3_lightsteelblue      1
        ->                                   ms3_maroon              1
        ->                                   ms3_mediumorchid        1
        ->                                   ms3_mediumseagreen      1
        ->                                   ms3_navy                1
        ->                                   ms3_olive               1
        ->                                   ms3_orange              1
        ->                                   ms3_orangered           1
        ->                                   ms3_palegreen           1
        ->                                   ms3_paleturquoise       1
        ->                                   ms3_royalblue           1
        ->                                   ms3_sienna              1
        ->                                   ms3_teal                1
        ->                                   ms3_violet              1
        ->                                   red                     1
        ->                                   springgreen             1
        ->                                   white                   1
        ->                                   yellow                  1
        ->               2 (Roman Numeral)   ms3_darkred             1
        ->               3 (Absolute Chord)  ms3_darkred             1
        ->               3 (dcml)            ms3_darkgreen           1
    

    As we can see, only the files with the key ‘ms3’ were parsed and the table shows an overview of the counts of the included label types in the different notational layers (i.e. staff & voice), grouped by their colours.

Parsing options

Parse.__init__(directory=None, paths=None, key=None, file_re=None, folder_re='.*', exclude_re=None, recursive=True, simulate=False, labels_cfg={}, logger_cfg={}, ms=None)[source]
Parameters
  • directory (optional) – Arguments for the method add_folder(). If dir is not passed, no files are added to the new object except if you pass paths

  • key (optional) – Arguments for the method add_folder(). If dir is not passed, no files are added to the new object except if you pass paths

  • index (optional) – Arguments for the method add_folder(). If dir is not passed, no files are added to the new object except if you pass paths

  • file_re (optional) – Arguments for the method add_folder(). If dir is not passed, no files are added to the new object except if you pass paths

  • folder_re (optional) – Arguments for the method add_folder(). If dir is not passed, no files are added to the new object except if you pass paths

  • exclude_re (optional) – Arguments for the method add_folder(). If dir is not passed, no files are added to the new object except if you pass paths

  • recursive (optional) – Arguments for the method add_folder(). If dir is not passed, no files are added to the new object except if you pass paths

  • paths (Collection or str, optional) – List of file paths you want to add. If directory is also passed, all files will be combined in the same object.

  • simulate (bool, optional) – Pass True if no parsing is actually to be done.

  • logger_cfg (dict, optional) –

    The following options are available:
    ’name’: LOGGER_NAME -> by default the logger name is based on the parsed file(s)
    ’level’: {‘W’, ‘D’, ‘I’, ‘E’, ‘C’, ‘WARNING’, ‘DEBUG’, ‘INFO’, ‘ERROR’, ‘CRITICAL’}
    ’path’: Directory in which log files are stored. If ‘file’ is relative, this path is used as root, otherwise, it is ignored.
    ’file’: PATH_TO_LOGFILE Pass absolute path to store all log messages in a single log file. If PATH_TO_LOGFILE is relative, multiple log files are created dynamically, relative to the original MSCX files’ paths. If ‘path’ is set, the corresponding subdirectory structure is created there.

  • ms (str, optional) – If you pass the path to your local MuseScore 3 installation, ms3 will attempt to parse musicXML, MuseScore 2, and other formats by temporarily converting them. If you’re using the standard path, you may try ‘auto’, or ‘win’ for Windows, ‘mac’ for MacOS, or ‘mscore’ for Linux. In case you do not pass the ‘file_re’ and the MuseScore executable is detected, all convertible files are automatically selected, otherwise only those that can be parsed without conversion.

Extracting score information

One of ms3’s main functionalities is storing the information contained in parsed scores as tabular files (TSV format). More information on the generated files is summarized here

Using the commandline

The most convenient way to achieve this is the command ms3 extract and its capital-letter parameters summarize the available tables:

-M [folder], --measures [folder]
                      Folder where to store TSV files with measure information needed for tasks such as unfolding repetitions.
-N [folder], --notes [folder]
                      Folder where to store TSV files with information on all notes.
-R [folder], --rests [folder]
                      Folder where to store TSV files with information on all rests.
-L [folder], --labels [folder]
                      Folder where to store TSV files with information on all annotation labels.
-X [folder], --expanded [folder]
                      Folder where to store TSV files with expanded DCML labels.
-E [folder], --events [folder]
                      Folder where to store TSV files with all events (notes, rests, articulation, etc.) without further processing.
-C [folder], --chords [folder]
                      Folder where to store TSV files with <chord> tags, i.e. groups of notes in the same voice with identical onset and duration. The tables include lyrics, slurs, and other markup.
-D [path], --metadata [path]
                      Directory or full path for storing one TSV file with metadata. If no filename is included in the path, it is called metadata.tsv

The typical way to use this command for a corpus of scores is to keep the MuseScore files in a subfolder (called, for example, MS3) and to use the parameters’ default values, effectively creating additional subfolders for each extracted aspect next to each folder containing MuseScore files. For example if we take the folder structure of the ms3 repository:

ms3
├── docs
│   ├── cujus.mscx
│   ├── o_quam.mscx
│   ├── quae.mscx
│   └── stabat.mscx
└── tests
    ├── MS3
    │   ├── 05_symph_fant.mscx
    │   ├── 76CASM34A33UM.mscx
    │   ├── BWV_0815.mscx
    │   ├── D973deutscher01.mscx
    │   ├── Did03M-Son_regina-1762-Sarti.mscx
    │   ├── K281-3.mscx
    │   └── stabat_03_coloured.mscx
    └── repeat_dummies
        ├── repeats0.mscx
        ├── repeats1.mscx
        └── repeats2.mscx

Upon calling ms3 extract -N, two new notes folders containing note lists are created:

ms3
├── docs
│   ├── cujus.mscx
│   ├── o_quam.mscx
│   ├── quae.mscx
│   └── stabat.mscx
├── notes
│   ├── cujus.tsv
│   ├── o_quam.tsv
│   ├── quae.tsv
│   └── stabat.tsv
└── tests
    ├── MS3
    │   ├── 05_symph_fant.mscx
    │   ├── 76CASM34A33UM.mscx
    │   ├── BWV_0815.mscx
    │   ├── D973deutscher01.mscx
    │   ├── Did03M-Son_regina-1762-Sarti.mscx
    │   ├── K281-3.mscx
    │   └── stabat_03_coloured.mscx
    ├── notes
    │   ├── 05_symph_fant.tsv
    │   ├── 76CASM34A33UM.tsv
    │   ├── BWV_0815.tsv
    │   ├── D973deutscher01.tsv
    │   ├── Did03M-Son_regina-1762-Sarti.tsv
    │   ├── K281-3.tsv
    │   ├── repeats0.tsv
    │   ├── repeats1.tsv
    │   ├── repeats2.tsv
    │   └── stabat_03_coloured.tsv
    └── repeat_dummies
        ├── repeats0.mscx
        ├── repeats1.mscx
        └── repeats2.mscx

We witness this behaviour because the default value is ../notes, interpreted as relative path in relation to each MuseScore file. Alternatively, a relative path can be specified without initial ./ or ../, e.g. ms3 extract -N notes, to store the note lists in a recreated sub-directory structure:

ms3
├── docs
├── notes
│   ├── docs
│   └── tests
│       ├── MS3
│       └── repeat_dummies
└── tests
    ├── MS3
    └── repeat_dummies

A third option consists in specifying an absolute path which causes all note lists to be stored in the specified folder, e.g. ms3 extract -N ~/notes:

~/notes
├── 05_symph_fant.tsv
├── 76CASM34A33UM.tsv
├── BWV_0815.tsv
├── cujus.tsv
├── D973deutscher01.tsv
├── Did03M-Son_regina-1762-Sarti.tsv
├── K281-3.tsv
├── o_quam.tsv
├── quae.tsv
├── repeats0.tsv
├── repeats1.tsv
├── repeats2.tsv
├── stabat_03_coloured.tsv
└── stabat.tsv

Note that this leads to problems if MuseScore files from different subdirectories have identical filenames. In any case it is good practice to not use nested folders to allow for easier file access. For example, a typical DCML corpus will store all MuseScore files in the MS3 folder and include at least the folders created by ms3 extract -N -M -X:

.
├── harmonies
├── measures
├── MS3
└── notes

Extracting score information manually

What ms3 extract effectively does is creating a Parse object, calling its method parse_mscx() and then store_lists(). In addition to the command, the method allows for storing two additional aspects, namely notes_and_rests and cadences (if the score contains cadence labels). For each of the available aspects, {notes, measures, rests, notes_and_rests, events, labels, chords, cadences, expanded}, the method provides two parameters, namely _folder (where to store TSVs) and _suffix, i.e. a slug appended to the respective filenames. If the parameter simulate=True is passed, no files are written but the file paths to be created are returned. Since corpora might have quite diverse directory structures, ms3 gives you various ways of specifying folders which will be explained in detail in the following section.

Briefly, the rules for specifying the folders are as follows:

  • absolute folder (e.g. ~/labels): Store all files in this particular folder without creating subfolders.

  • relative folder starting with ./ or ../: relative folders are created “at the end” of the original subdirectory structure, i.e. relative to the MuseScore files.

  • relative folder not starting with ./ or ../ (e.g. rests): relative folders are created at the top level (of the original directory or the specified root_dir) and the original subdirectory structure is replicated in each of them.

To see examples for the three possibilities, see the following section.

Specifying folders

Consider a two-level folder structure contained in the root directory . which is the one passed to Parse:

.
├── docs
│   ├── cujus.mscx
│   ├── o_quam.mscx
│   ├── quae.mscx
│   └── stabat.mscx
└── tests
    └── MS3
        ├── 05_symph_fant.mscx
        ├── 76CASM34A33UM.mscx
        ├── BWV_0815.mscx
        ├── D973deutscher01.mscx
        ├── Did03M-Son_regina-1762-Sarti.mscx
        └── K281-3.mscx

The first level contains the subdirectories docs (4 files) and tests (6 files in the subdirectory MS3). Now we look at the three different ways to specify folders for storing notes and measures.

Absolute Folders

When we specify absolute paths, all files are stored in the specified directories. In this example, the measures and notes are stored in the two specified subfolders of the home directory ~, regardless of the original subdirectory structure.

>>> p.store_lists(notes_folder='~/notes', measures_folder='~/measures')
~
├── measures
│   ├── 05_symph_fant.tsv
│   ├── 76CASM34A33UM.tsv
│   ├── BWV_0815.tsv
│   ├── cujus.tsv
│   ├── D973deutscher01.tsv
│   ├── Did03M-Son_regina-1762-Sarti.tsv
│   ├── K281-3.tsv
│   ├── o_quam.tsv
│   ├── quae.tsv
│   └── stabat.tsv
└── notes
    ├── 05_symph_fant.tsv
    ├── 76CASM34A33UM.tsv
    ├── BWV_0815.tsv
    ├── cujus.tsv
    ├── D973deutscher01.tsv
    ├── Did03M-Son_regina-1762-Sarti.tsv
    ├── K281-3.tsv
    ├── o_quam.tsv
    ├── quae.tsv
    └── stabat.tsv
Relative Folders

In contrast, specifying relative folders recreates the original subdirectory structure. There are two different possibilities for that. The first possibility is naming relative folder names, meaning that the subdirectory structure (docs and tests) is recreated in each of the folders:

>>> p.store_lists(root_dir='~/tsv', notes_folder='notes', measures_folder='measures')
~/tsv
├── measures
│   ├── docs
│   │   ├── cujus.tsv
│   │   ├── o_quam.tsv
│   │   ├── quae.tsv
│   │   └── stabat.tsv
│   └── tests
│       └── MS3
│           ├── 05_symph_fant.tsv
│           ├── 76CASM34A33UM.tsv
│           ├── BWV_0815.tsv
│           ├── D973deutscher01.tsv
│           ├── Did03M-Son_regina-1762-Sarti.tsv
│           └── K281-3.tsv
└── notes
    ├── docs
    │   ├── cujus.tsv
    │   ├── o_quam.tsv
    │   ├── quae.tsv
    │   └── stabat.tsv
    └── tests
        └── MS3
            ├── 05_symph_fant.tsv
            ├── 76CASM34A33UM.tsv
            ├── BWV_0815.tsv
            ├── D973deutscher01.tsv
            ├── Did03M-Son_regina-1762-Sarti.tsv
            └── K281-3.tsv

Note that in this example, we have specified a root_dir. Leaving this argument out will create the same structure in the directory from which the Parse object was created, i.e. the folder structure would be:

.
├── docs
├── measures
│   ├── docs
│   └── tests
│       └── MS3
├── notes
│   ├── docs
│   └── tests
│       └── MS3
└── tests
    └── MS3

If, instead, you want to create the specified relative folders relative to each MuseScore file’s location, specify them with an initial dot. ./ means “relative to the original path” and ../ one level up from the original path. To exemplify both:

>>> p.store_lists(root_dir='~/tsv', notes_folder='./notes', measures_folder='../measures')
~/tsv
├── docs
│   └── notes
│       ├── cujus.tsv
│       ├── o_quam.tsv
│       ├── quae.tsv
│       └── stabat.tsv
├── measures
│   ├── cujus.tsv
│   ├── o_quam.tsv
│   ├── quae.tsv
│   └── stabat.tsv
└── tests
    ├── measures
    │   ├── 05_symph_fant.tsv
    │   ├── 76CASM34A33UM.tsv
    │   ├── BWV_0815.tsv
    │   ├── D973deutscher01.tsv
    │   ├── Did03M-Son_regina-1762-Sarti.tsv
    │   └── K281-3.tsv
    └── MS3
        └── notes
            ├── 05_symph_fant.tsv
            ├── 76CASM34A33UM.tsv
            ├── BWV_0815.tsv
            ├── D973deutscher01.tsv
            ├── Did03M-Son_regina-1762-Sarti.tsv
            └── K281-3.tsv

The notes folders are created in directories where MuseScore files are located, and the measures folders one directory above, respectively. Leaving out the root_dir argument would lead to the same folder structure but in the directory from which the Parse object has been created. In a similar manner, the arguments p.store_lists(notes_folder='.', measures_folder='.') would create the TSV files just next to the MuseScore files. However, this would lead to warnings such as

Warning

The notes at ~/ms3/docs/cujus.tsv have been overwritten with measures.

In such a case we need to specify a suffix for at least one of both aspects:

p.store_lists(notes_folder='.', notes_suffix='_notes',
              measures_folder='.', measures_suffix='_measures')
Examples

Before you are sure to have picked the right parameters for your desired output, you can simply use the simulate=True argument which lets you view the paths without actually creating any files. In this variant, all aspects are stored each in individual folders but with identical filenames:

>>> p = Parse('~/ms3/docs', key='pergo')
>>> p.parse_mscx()
>>> p.store_lists(  notes_folder='./notes',
                    rests_folder='./rests',
                    notes_and_rests_folder='./notes_and_rests',
                    simulate=True
                    )
['~/ms3/docs/notes/cujus.tsv',
 '~/ms3/docs/rests/cujus.tsv',
 '~/ms3/docs/notes_and_rests/cujus.tsv',
 '~/ms3/docs/notes/o_quam.tsv',
 '~/ms3/docs/rests/o_quam.tsv',
 '~/ms3/docs/notes_and_rests/o_quam.tsv',
 '~/ms3/docs/notes/quae.tsv',
 '~/ms3/docs/rests/quae.tsv',
 '~/ms3/docs/notes_and_rests/quae.tsv',
 '~/ms3/docs/notes/stabat.tsv',
 '~/ms3/docs/rests/stabat.tsv',
 '~/ms3/docs/notes_and_rests/stabat.tsv']

In this variant, the different ways of specifying folders are exemplified. To demonstrate all subtleties we parse the same four files but this time from the perspective of ~/ms3:

>>> p = Parse('~/ms3', folder_re='docs', key='pergo')
>>> p.parse_mscx()
>>> p.store_lists(  notes_folder='./notes',            # relative to ms3/docs
                    measures_folder='../measures',     # one level up from ms3/docs
                    rests_folder='rests',              # relative to the parsed directory
                    labels_folder='~/labels',          # absolute folder
                    expanded_folder='~/labels', expanded_suffix='_exp',
                    simulate = True
                    )
['~/ms3/docs/notes/cujus.tsv',
 '~/ms3/rests/docs/cujus.tsv',
 '~/ms3/measures/cujus.tsv',
 '~/labels/cujus.tsv',
 '~/labels/cujus_exp.tsv',
 '~/ms3/docs/notes/o_quam.tsv',
 '~/ms3/rests/docs/o_quam.tsv',
 '~/ms3/measures/o_quam.tsv',
 '~/labels/o_quam.tsv',
 '~/labels/o_quam_exp.tsv',
 '~/ms3/docs/notes/quae.tsv',
 '~/ms3/rests/docs/quae.tsv',
 '~/ms3/measures/quae.tsv',
 '~/labels/quae.tsv',
 '~/labels/quae_exp.tsv',
 '~/ms3/docs/notes/stabat.tsv',
 '~/ms3/rests/docs/stabat.tsv',
 '~/ms3/measures/stabat.tsv',
 '~/labels/stabat.tsv',
 '~/labels/stabat_exp.tsv']

Column Names

Glossary of the meaning and types of column types. In order to correctly restore the types when loading TSV files, either use an Annotations object or the function load_tsv().

General Columns

duration

fractions.Fraction

Duration of an event expressed in fractions of a whole note. Note that in note lists, the duration does not take into account if notes are tied together; in other words, the column expresses no durations that surpass the final bar line.

keysig Key Signatures

int

The feature keysig represents the key signature of a particular measure. It is an integer which, if positive, represents the number of sharps, and if negative, the number of flats. E.g.: 3: three sharps, -2: two flats, 0: no accidentals.

mc Measure Counts

int

Measure count, identifier for the measure units in the XML encoding. Always starts with 1 for correspondence to MuseScore’s status bar. For more detailed information, please refer to Measure counts (MC) vs. measure numbers (MN).

mn Measure Numbers

int

Measure number, continuous count of complete measures as used in printed editions. Starts with 1 except for pieces beginning with a pickup measure, numbered as 0. MNs are identical for first and second endings! For more detailed information, please refer to Measure counts (MC) vs. measure numbers (MN).

mc_onset

fractions.Fraction

The value for mc_onset represents, expressed as fraction of a whole note, a position in a measure where 0 corresponds to the earliest possible position (in most cases beat 1). For more detailed information, please refer to Onset positions.

mn_onset

fractions.Fraction

The value for mn_onset represents, expressed as fraction of a whole note, a position in a measure where 0 corresponds to the earliest possible position of the corresponding measure number (MN). For more detailed information, please refer to Onset positions.

quarterbeats

fractions.Fraction

This column expresses positions, otherwise accessible only as a tuple (mc, mc_onset), as a running count of quarter notes from the piece’s beginning (quarterbeat = 0). If second endings are present in the score, only the last ending is counted in order to give authentic values to such a score, as if played without repetitions. If repetitions are unfolded, i.e. the table corresponds to a full play-through of the score, all endings are taken into account correctly.

staff

int

In which staff an event occurs. 1 = upper staff.

timesig Time Signatures

str

The time signature timesig of a particular measure is expressed as a string, e.g. '2/2'. The actual duration of a measure can deviate from the time signature for notational reasons: For example, a pickup bar could have an actual duration of 1/4 but still be part of a '3/8' meter, which usually has an actual duration of 3/8.

volta

int

In the case of first and second (third etc.) endings, this column holds the number of every “bracket”, “house”, or _volta_, which should increase from 1. This is required for MS3’s unfold repeats function to work. For more information, see here.

voice

int

In which notational layer an event occurs. Each staff has (can have) up to four layers:

  • 1 = upper, default layer (blue)

  • 2 = second layer, downward stems (green)

  • 3 = third layer, upward stems (orange)

  • 4 = fourth layer, downward stems (purple)

Measures

act_dur Actual duration of a measure

fractions.Fraction

The value of act_dur in most cases equals the time signature, expressed as a fraction; meaning for example that a “normal” measure in 6/8 has act_dur = 3/4. If the measure has an irregular length, for example a pickup measure of length 1/8, would have act_dur = 1/8.

The value of act_dur plays an important part in inferring MNs from MCs. See also the columns dont_count and numbering_offset.

barline

str

The column barline encodes information about the measure’s final bar line.

breaks

str

The column breaks may include three different values: {'line', 'page', 'section'} which represent the different breaks types. In the case of section breaks, MuseScore

dont_count Measures excluded from bar count

int

This is a binary value that corresponds to MuseScore’s setting Exclude from bar count from the Bar Properties menu. The value is 1 for pickup bars, second MCs of divided MNs and some volta measures, and NaN otherwise.

mc_offset Offset of a MC

fractions.Fraction

The column mc_offset , in most cases, has the value 0 because it expresses the deviation of this MC’s mc_onset 0 (beginning of the MC) from beat 1 of the corresponding MN. If the value is a fraction > 0, it means that this MC is part of a MN which is composed of at least two MCs, and it expresses the current MC’s offset in terms of the duration of all (usually 1) preceding MCs which are also part of the corresponding MN. In the standard case that one MN would be split in two MCs, the first MC would have mc_offset = 0 , and the second one mc_offset = the previous MC's act_dur .

numbering_offset Offsetting MNs

int

MuseScore’s measure number counter can be reset at a given MC by using the Add to bar number setting from the Bar Properties menu. If numbering_offset ≠ 0, the counting offset is added to the current MN and all subsequent MNs are inferred accordingly.

Scores which include several pieces (e.g. in variations or a suite), sometimes, instead of using section breaks, use numbering_offset to simulate a restart for counting MNs at every new section. This leads to ambiguous MNs.

repeats

str

The column repeats indicates the presence of repeat signs and can have the values {'start', 'end', 'startend', 'firstMeasure', 'lastMeasure'}. MS3 performs a test on the repeat signs’ plausibility and throws warnings when some inference is required for this.

The repeats column needs to have the correct repeat sign structure in order to have a correct next column which, in return, is required for MS3’s unfolding repetitions functionality.

Notes and Rests

chord_id

int

Every note keeps the ID of the <Chord> tag to which it belongs in the score. This is necessary because in MuseScore XML, most markup (e.g. articulation, lyrics etc.) are attached to chords rather than to individual notes. This column allows for relating markup to notes at a later point.

gracenote

str

For grace notes, type of the grace note as encoded in the MuseScore source code. They are assigned a duration of 0.

midi Piano key

int

MIDI pitch with 60 = C4, 61 = C#4/Db4/B##3 etc. For the actual note name, refer to the tpc column.

nominal_duration

fractions.Fraction

Note’s or rest’s duration without taking into account dots or tuplets. Multiplying by scalar results in the actual duration.

scalar

fractions.Fraction

Value reflecting dots and tuples by which to multiply a note’s or rest’s nominal_duration.

tied

int

Encodes ties on the note’s left (-1), on its right (1) or both (0). A tie merges a note with an adjacent one having the same pitch.

value

explanation

<NA>

No ties. This note represents an onset and ends after the given duration.

1

This note is tied to the next one. It represents an onset but not a note ending.

0

This note is being tied to and tied to the next one. It represents neither an onset nor a note ending.

-1

This note is being tied to. That is, it does not represent an onset, instead it adds to the duration of a previous note on the same pitch and ends it.

tpc Tonal pitch class

int

Encodes note names by their position on the line of fifth with 0 = C, 1 = G, 2 = D, -1 = F, -2 = Bb etc. The octave is defined by midi DIV 12 - 1

Chords

The various <Chord> tags are identified by increasing integer counts in the column chord_id. Within a note list, a column of the same name specifies which note belongs to which <Chord> tag. A chord and all the notes belonging to it have identical values in the columns mc, mn, mc_onset, mn_onset, timesig, staff, voice, duration, gracenote, nominal_duration, scalar, volta, and of course chord_id.

articulation

str

Articulation signs named as in the MuseScore file, e.g. articStaccatoBelow.

dynamics

str

Dynamic signs such as p, ff etc. Other dynamic markings such as dolce are currently displayed as other-dynamics. Velocity values are currently not extracted. These features can easily be implemented upon request.

lyrics:1

str

When a voice includes only a single verse, all syllables are contained in the column lyrics:1. If it has more than one verse, for each <Chord> the last verse’s syllable is contained in the respective column, e.g. lyrics:3 if the 3rd verse is the last one with a syllable for this chord. Each syllable has a trailing - if it’s the first syllable of a word, a leading - if it’s the last syllable of a word, and both if it’s in the middle of a word.

qpm Quarter notes per minute

int

Defined for every tempo mark. Normalizes the metronome value to quarter notes. For example, 𝅘𝅥. = 112 gets the value qbm = 112 * 1.5 = 168.

staff_text

str

Free-form text such as dolce or div.. Depending on the encoding standard, this layer may include dynamics such as cresc., articulation such as stacc., movement titles, and many more. Staff texts are added in MuseScore via [C] + T.

system_text

Free-form text not attached to a particular staff but to the entire system. This frequently includes movement names or playing styles such as Swing. System texts are added in MuseScore via [C] + [S] + T.

tempo

Metronome markings and tempo texts. Unfortunately, for tempo texts that include a metronome mark, e.g. Larghetto. (𝅘𝅥 = 63), the text before the 𝅘𝅥 symbol is lost. This can be fixed upon request.

Spanners

str (-> tuple)

Spanners designate markup that spans several <Chord> tags, such as slurs, hairpins, pedal, trill and ottava lines. The values in a spanner column are IDs such that all chords with the same ID belong to the same spanner. Each cell can have more than one ID, separated by commas. For evaluating spanner columns, the values should be turned into tuples.

Spanners span all chords belonging to the same staff, except for slurs and trills which span only chords in the same voice. In other words, won’t find the ending of a slur that goes from one voice to another.

slur

str (-> tuple)

Slurs expressing legato and/or phrasing. These spanners always pertain to a particular voice.

(de)crescendo_hairpin

str (-> tuple)

crescendo_hairpin is a < spanner, decrescendo_hairpin a > spanner. These always pertain to an entire staff.

crescendo_line, diminuendo_line

str (-> tuple)

These are spanners starting with a word, by default cresc. or dim., followed by a dotted line. These always pertain to an entire staff.

Ottava

str (-> tuple)

These spanners are always specified with a subtype such as Ottava:8va or Ottava:15mb. They always pertain to an entire staff

pedal

str (-> tuple)

Pedal line spanners always pertain to an entire staff.

Trill

str

Trills spanners can have different subtypes specified after a colon, e.g. 'Trill:trill'. They always pertain to a particular voice.

Labels

label

str

Annotation labels from MuseScores <Harmony> tags. Depending on the label_type the column can include complete strings (decoded) or partial strings (encoded).

label_type

str

See label types above.

Expanded

bass_note

int

The bass note designated by the label, expressed as scale degree.

cadence

str

Currently allows for the values

value

cadence

PAC

perfect authentic

IAC

imperfect authentic

HC

half

DC

deceptive

EC

evaded

PC

plagal

chord

str

This column stands in no relation to the <Chord> tags discussed above. Instead, it holds the substring of the original labels that includes only the actual chord label, i.e. excluding information about modulations, pedal tones, phrases, and cadences. In other words, it comprises the features numeral, form, figbass, changes, and relativeroot.

chord_tones, added_tones

str (-> tuple)

Chord tones designated by the label, expressed as scale degrees. Includes 3 scale degrees for triads, 4 for tetrads, ordered according to the inversion (i.e. the first value is the bass_note). Accounts for chord tone replacement expressed through intervals <= 8 within parentheses, without leading +. added_tones reflects only those non-chord tones that were added using, again within parentheses, intervals preceded by + or/and greater than 8.

chord_type

str

A summary of information that otherwise depends on the three columns numeral, form, figbass. It can be one of the wide-spread abbreviations for triads: M, m, o, + or for seventh chords: o7, %7, +7, +M7 (for diminished, half-diminished and augmented chords with minor/major seventh), or Mm7, mm7, MM7, mM7 for all combinations of a major/minor triad with a minor/major seventh.

figbass Inversion

Figured bass notation of the chord inversion. For triads, this feature can be <NA>, '6', '64', for seventh chords '7', '65', '43', '2'. This column plays into computing the chord_type. This feature is decisive for which chord tone is in the bass.

form

str

This column conveys part of the information what chord_type a label expresses.

value

chord type

<NA>

If figbass is one of <NA>, '6', '64', the chord is either a major or minor triad. Otherwise, it is either a major or a minor chord with a minor seventh.

o, +

Diminished or augmented chord. Again, it depends on figbass whether it is a triad or a seventh chord.

%, M, +M

Half diminished or major seventh chord. For the latter, the chord form (MM7 or mM7) depends on the numeral.

globalkey

str

Tonality of the piece, expressed as absolute note name, e.g. Ab for A flat major, or g# for G sharp minor.

globalkey_is_minor

bool

Auxiliary column which is True if the globalkey is a minor key, False otherwise.

localkey

str

Local key expressed as Roman numeral relative to the globalkey, e.g. IV for the major key on the 4th scale degree or #iv for the minor scale on the raised 4th scale degree.

localkey_is_minor

bool

Auxiliary column which is True if the localkey is a minor key, False otherwise.

numeral

str

Roman numeral defining the chordal root relative to the local key. An uppercase numeral stands for a major chordal third, lowercase for a minor third. The column root expresses the same information as scale degree.

phraseend Phrase annotations

In versions < 2.2.0, only phrase endings where annotated, designated by \\. From version 2.2.0 onwards, { means beginning and } ending of a phrase. Everything between } and the subsequent { is to be considered as part of the previous phrase, a ‘codetta’ after the strong end point.

relativeroot Tonicized key

str

This feature designates a lower-level key to which the current chord relates. It is expressed relative to the local key. For example, if the current numeral is a V and it is a secondary dominant, relativeroot is the Roman numeral of the key that is being tonicized.

root

int

The numeral expressed as scale degree.