.. image:: http://img.shields.io/pypi/v/mscxyz.svg :target: https://pypi.org/project/mscxyz :alt: This package on the Python Package Index

.. image:: https://github.com/Josef-Friedrich/mscxyz/actions/workflows/tests.yml/badge.svg :target: https://github.com/Josef-Friedrich/mscxyz/actions/workflows/tests.yml :alt: Tests

.. image:: https://readthedocs.org/projects/mscxyz/badge/?version=latest :target: https://mscxyz.readthedocs.io/en/latest/?badge=latest :alt: Documentation Status

============================== mscxyz - The MuseScore Manager

Manipulate the XML based .mscz and .mscx files of the notation software MuseScore <https://musescore.org>_.

Features

• Batch processing of .msc[zx] files in nested folder structures
• Rename .msc[zx] files based on meta tags
• Set, read and synchronized meta tags
• Set style properties
• Can handle MuseScore 2, 3 and 4 files
• Command line interface
• Python API

Installation

.. code:: Shell

pipx install mscxyz

How to ...

... specify the MuseScore files to work on?

To find out which files are selected by the script, the -L, --list-files option can be used. The --list-files option lists as the name suggests only the file paths and doesn’t touch the specified MuseScore files:

::

musescore-manager --list-files

Without an option the script lists all MuseScore files in the current directory in a recursive way (musescore-manager = musescore-manager .). You can pass multiple file paths to the script:

::

musescore-manager -L score1.mscz score2.mscz score3.mscz

or multiple directories:

::

musescore-manager -L folder1 folder2 folder3

or use the path expansion of your shell:

::

musescore-manager -L *.mscz

To apply glob patterns on the file paths, the --glob option can be used.

::

musescore-manager -L --glob "*/folder/*.mscz"

To selection only mscz oder mscx files use the options --mscz or --mscx. Don’t mix the options --mscz and --mscx with the option --glob.

The python package mscxyz exports a function named list_path which can be used to list the paths of MuseScore files. This allows you to list score paths in a nested folder structure in a similar way to the command line. This folder structure is used for the following example:

::

cd /home/xyz/scores
find . | sort

.
./level1
./level1/level2
./level1/level2/score2.mscz
./level1/level2/level3
./level1/level2/level3/score3.mscz
./level1/score1.mscz
./score0.mscz

.. code-block:: Python

from mscxyz import list_path, Score

score_paths = []
for score_path in list_path(path="/home/xyz/scores", extension="mscz"):
    score = Score(score_path)
    assert score.path.exists()
    assert score.extension == "mscz"
    score_paths.append(str(score_path))

assert len(score_paths) == 4

assert "level1/level2/level3/score3.mscz" in score_paths[3]
assert "level1/level2/score2.mscz" in score_paths[2]
assert "level1/score1.mscz" in score_paths[1]
assert "score0.mscz" in score_paths[0]

... export files to different files types?

On the command line use the option --export to export the scores to different file types. The exported file has the same path, only the file extension is different. Further information about the supported file formats can be found at the MuseScore website: Version 2 <https://musescore.org/en/handbook/2/file-formats>, Version 3 <https://musescore.org/en/handbook/3/file-export> and Version 4 <https://musescore.org/en/handbook/4/file-export>_ The MuseScore binay must be installed and the script must know the location of t his binary.

::

musescore-manager --export pdf
musescore-manager --export png

.. code-block:: Python

score = Score('score.mscz')
score.export.to_extension("musicxml")

... change the styling of a score?

Set a single style by its style name --style:

::

musescore-manager --style staffDistance 7.5 score.mscz

To set mulitple styles at once specify the option --style multiple times:

::

musescore-manager --style staffUpperBorder 5.5 --style staffLowerBorder 5.5 score.mscz

... change the font faces of a score?

Some options change mutliple font related xml elements at once:

::

musescore-manager --text-font Alegreya score.mscz
musescore-manager --title-font "Alegreya Sans" score.mscz
musescore-manager --musical-symbol-font Leland score.mscz
musescore-manager --musical-text-font "Leland Text" score.mscz

Set all font faces (using a for loop, not available in MuseScore 2):

.. code-block:: Python

score = Score('score.mscz')
assert score.style.get("defaultFontFace") == "FreeSerif"

for element in score.style.styles:
    if "FontFace" in element.tag:
        element.text = "Alegreya"
score.save()

new_score: Score = score.reload()
assert new_score.style.get("defaultFontFace") == "Alegreya"

Set all text font faces (using the method score.style.set_text_font_faces(font_face), not available in MuseScore 2):

.. code-block:: Python

score = Score('score.mscz')
assert score.style.get("defaultFontFace") == "FreeSerif"

response = score.style.set_text_font_faces("Alegreya")

assert response == [
    ...
    ("harpPedalTextDiagramFontFace", "Edwin", "Alegreya"),
    ("longInstrumentFontFace", "FreeSerif", "Alegreya"),
    ...
]

score.save()

new_score: Score = score.reload()
assert new_score.style.get("defaultFontFace") == "Alegreya"

... enable autocomplete support?

Use one of the following autocomplete files ...

• bash <https://github.com/Josef-Friedrich/mscxyz/blob/main/autocomplete.bash>_
• zsh <https://github.com/Josef-Friedrich/mscxyz/blob/main/autocomplete.zsh>_
• tcsh <https://github.com/Josef-Friedrich/mscxyz/blob/main/autocomplete.tcsh>_

... or generate the autocomplete files by yourself?

::

musescore-manager --print-completion bash > autocomplete.bash
musescore-manager --print-completion zsh > autocomplete.zsh
musescore-manager --print-completion tcsh > autocomplete.tcsh

... rename many files at once?

Fields ^^^^^^

• title: The combined title
• subtitle: The combined subtitle
• composer: The combined composer
• lyricist: The combined lyricist
• vbox_title: The title field of the score as it appears in the center of the first vertical frame (VBox).
• vbox_subtitle: The subtitle field of the score as it appears in the center of the first vertical frame (VBox).
• vbox_composer: The composer field of the score as it appears in the center of the first vertical frame (VBox).
• vbox_lyricist: The lyricist field of the score as it appears in the center of the first vertical frame (VBox).
• metatag_arranger: The arranger field stored as project properties.
• metatag_audio_com_url: The audio.com URL field stored as project properties.
• metatag_composer: The composer field stored as project properties.
• metatag_copyright: The copyright field stored as project properties.
• metatag_creation_date: The creation date field stored as project properties.
• metatag_lyricist: The lyricist field stored as project properties.
• metatag_movement_number: The movement number field stored as project properties.
• metatag_movement_title: The movement title field stored as project properties.
• metatag_msc_version: The MuseScore version field stored as project properties.
• metatag_platform: The platform field stored as project properties.
• metatag_poet: The poet field stored as project properties.
• metatag_source: The source field stored as project properties.
• metatag_source_revision_id: The source revision ID field stored as project properties.
• metatag_subtitle: The subtitle field stored as project properties.
• metatag_translator: The translator field stored as project properties.
• metatag_work_number: The work number field stored as project properties.
• metatag_work_title: The work title field stored as project properties.
• version: The MuseScore version as a floating point number, for example 2.03, 3.01 or 4.20.
• version_major: The major MuseScore version, for example 2, 3 or 4.
• program_version: The semantic version number of the MuseScore program, for example: 4.2.0.
• program_revision: The revision number of the MuseScore program, for example: eb8d33c.
• path: The absolute path of the MuseScore file, for example /home/xyz/score.mscz.
• backup_file: The absolute path of the backup file. The string _bak is appended to the file name before the extension.
• json_file: The absolute path of the JSON file in which the metadata can be exported.
• dirname: The name of the containing directory of the MuseScore file, for example: /home/xyz/score_files.
• filename: The filename of the MuseScore file, for example:score.mscz.
• basename: The basename of the score file, for example: score.
• extension: The extension (mscx or mscz) of the score file.

Functions ^^^^^^^^^

/bin/sh: 1: tmep-doc: not found

/bin/sh: 1: tmep-doc: not found

The following example assumes that the folder /home/xyz/messy-leadsheets contains the following three MuseScore files: folsom prison blues.mscz, Johnny Cash - I Walk the Line.mscz, Jackson (Cash).mscz The files are named arbitrarily without any recognizable pattern, but they have a title in the first vertical frame (VBox).

The files should be