Manual

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.

Basics

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.

Read-only mode

For parsing faster using less memory.

Using the library

Parsing a single score

  1. Locate the MuseScore 3 score you want to parse.

    Make sure it is uncompressed. i.e. it has the extension .mscx and not .mscz.

    Tip

    MSCZ files are ZIP files containing the uncompressed MSCX. A later version of ms3 will be able to deal with MSCZ, too.

    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...).

  2. Import the library.

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

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

    or simply import the class:

    >>> from ms3 import Score
    >>> s = Score()
    
  3. Create a ms3.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
    3      2      dcml          48
    

Parsing options

Score.__init__(mscx_src=None, infer_label_types=['dcml'], read_only=False, logger_name='Score', level=None, parser='bs4')[source]
Parameters
  • mscx_src (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.

  • logger_name (str, optional) – If you have defined a logger, pass its name. Otherwise, the MSCX filename is used.

  • level ({'W', 'D', 'I', 'E', 'C', 'WARNING', 'DEBUG', 'INFO', 'ERROR', 'CRITICAL'}, optional) – Pass a level name for which (and above which) you want to see log records.

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