Developers’ Reference — ms3 0.1.2.post0.dev2+g9d887e1.dirty documentation

# Developers’ Reference

## The score module

class `ms3.score.` `Score`(mscx_src=None, infer_label_types=['dcml'], read_only=False, logger_name='Score', level=None, parser='bs4')

  Object representing a score.

  `infer_label_types`

    Changing this value results in a call to `infer_types()`.

    Type

      `list` or `dict`, optional

  `logger`

    Current logger that the object is using.

    Type

      `logging.Logger` or `logging.LoggerAdapter`

  `parser`

    The only XML parser currently implemented is BeautifulSoup 4.

    Type

      {‘bs4’}

  `paths, files, fnames, fexts, logger_names`

    Dictionaries for keeping track of file information handled by `handle_path()`.

    Type

      `dict`

  `_annotations`
  `_harmony_regex`
  `_label_types`
  `_mscx`

    After parsing, holds the MSCX object with the parsed score.

    Type

      `MSCX`

  `_types_to_infer`
  `handle_path`(path, key)

    Puts the path into paths, files, fnames, fexts dicts with the given key.

  property `mscx`

    Returns the MSCX object with the parsed score.

class `ms3.score.` `MSCX`(mscx_src=None, read_only=False, parser='bs4', logger_name='MSCX', level=None)

  Object for interacting with the XML structure of a MuseScore 3 file.

  `mscx_src`

    MuseScore 3 file to parse.

    Type

      `str`

  `_parsed`

    Holds the MSCX score parsed by the selected parser.

    Type

      `_MSCX_bs4`

  `parser`

    Which XML parser to use.

    Type

      `str`, optional

  `infer_label_types :obj:`bool`, optional`

    For label_type 0 (simple string), mark which ones

  `logger_name`

    If you have defined a logger, pass its name.

    Type

      `str`, optional

  `level`

    Pass a level name for which (and above which) you want to see log records.

    Type

      {‘W’, ‘D’, ‘I’, ‘E’, ‘C’, ‘WARNING’, ‘DEBUG’, ‘INFO’, ‘ERROR’, ‘CRITICAL’}, optional

  `output_mscx`(filepath)

    Write the internal score representation to a file.

  `add_labels`(df, label='label', mc='mc', onset='onset', staff='staff', voice='voice', **kwargs)
    Parameters

      - df (`pandas.DataFrame`) – DataFrame with labels to be added.

      - label (`str`) – Names of the DataFrame columns for the five required parameters.

      - mc (`str`) – Names of the DataFrame columns for the five required parameters.

      - onset (`str`) – Names of the DataFrame columns for the five required parameters.

      - staff (`str`) – Names of the DataFrame columns for the five required parameters.

      - voice (`str`) – Names of the DataFrame columns for the five required parameters.

      - kwargs –

        label_type, root, base, leftParen, rightParen, offset_x, offset_y, nashville

          For these parameters, the standard column names are used automatically if the columns are present. If the column names have changed, pass them as kwargs, e.g. `base='name_of_the_base_column'`

    Returns

    Return type

      None

  property `version`

    MuseScore version with which the file was created (read-only).

## The annotations module

class `ms3.annotations.` `Annotations`(tsv_path=None, df=None, index_col=None, sep='\t', infer_types={}, logger_name='Annotations', level=None, **kwargs)

  Class for storing, converting and manipulating annotation labels.

  `get_labels`(staff=None, voice=None, label_type=None, positioning=True, decode=False, drop=False)

    Returns a list of harmony tags from the parsed score.

    Parameters

      - staff (`int`, optional) – Select harmonies from a given staff only. Pass staff=1 for the upper staff.

      - label_type ({0, 1, 2, 3, 'dcml', ..}, optional) –

        If MuseScore’s harmony feature has been used, you can filter harmony types by passing

          0 for unrecognized strings 1 for Roman Numeral Analysis 2 for Nashville Numbers 3 for encoded absolute chords ‘dcml’ for labels from the DCML harmonic annotation standard … self-defined types that have been added to self.regex_dict through the use of self.infer_types()

      - positioning (`bool`, optional) – Set to True if you want to include information about how labels have been manually positioned.

      - decode (`bool`, optional) – Set to True if you don’t want to keep labels in their original form as encoded by MuseScore (with root and bass as TPC (tonal pitch class) where C = 14).

## The parse module

class `ms3.parse.` `Parse`(dir=None, key=None, file_re='\\.mscx$', folder_re='.*', exclude_re='^(\\.|__)', recursive=True, logger_name='Parse', level=None)

  Class for storing and manipulating the information from multiple parses.