Manual — ms3 0.1.2.post0.dev2+g9d887e1.dirty documentation

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