| Name | mscxyz JSON |
| Version |
3.0.0
JSON |
| download |
| home_page | https://mscxyz.readthedocs.io |
| Summary | A command line tool to manipulate the XML based *.mscX and *.mscZ files of the notation software MuseScore. |
| upload_time | 2024-02-12 18:43:52 |
| maintainer | |
| docs_url | None |
| author | Josef Friedrich |
| requires_python | >=3.9,<4.0 |
| license | |
| keywords |
audio
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
.. 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
^^^^^^^^^
alpha
``%alpha{text}``: This function first ASCIIfies the given text, then all
non alphabet characters are replaced with whitespaces.
**Example:** ``%alpha{a1b23c}`` → ``a b c``
alphanum
``%alphanum{text}``: This function first ASCIIfies the given text, then all
non alpanumeric characters are replaced with whitespaces.
**Example:** ``%alphanum{après-évêque1}`` → ``apres eveque1``
asciify
``%asciify{text}``: Translate non-ASCII characters to their ASCII
equivalents. For example, “café” becomes “cafe”. Uses the mapping provided
by the unidecode module.
**Example:** ``%asciify{äÄöÖüÜ}`` → ``aeAeoeOeueUe``
delchars
``%delchars{text,chars}``: Delete every single character of “chars“ in
“text”.
**Example:** ``%delchars{Schubert, ue}`` → ``Schbrt``
deldupchars
``%deldupchars{text,chars}``: Search for duplicate characters and replace
with only one occurrance of this characters.
**Example:** ``%deldupchars{a---b___c...d}`` → ``a-b_c.d``; ``%deldupchars{a
---b___c, -}`` → ``a-b___c``
first
``%first{text}`` or ``%first{text,count,skip}`` or
``%first{text,count,skip,sep,join}``: Returns the first item, separated by
``;``. You can use ``%first{text,count,skip}``, where count is the number of
items (default 1) and skip is number to skip (default 0). You can also use
``%first{text,count,skip,sep,join}`` where ``sep`` is the separator, like
``;`` or ``/`` and join is the text to concatenate the items.
**Example:** ``%first{Alice / Bob / Eve,2,0, / , & }`` → ``Alice & Bob``
if
``%if{condition,trueval}`` or ``%if{condition,trueval,falseval}``: If
condition is nonempty (or nonzero, if it’s a number), then returns the
second argument. Otherwise, returns the third argument if specified (or
nothing if ``falseval`` is left off).
**Example:** ``x%if{false,foo}`` → ``x``
ifdef
``%ifdef{field}``, ``%ifdef{field,trueval}`` or
``%ifdef{field,trueval,falseval}``: If field exists, then return
``trueval`` or field (default). Otherwise, returns ``falseval``. The field
should be entered without ``$``.
**Example:** ``%ifdef{compilation,Compilation}``
ifdefempty
``%ifdefempty{field,text}`` or ``%ifdefempty{field,text,falsetext}``: If
field exists and is empty, then return ``truetext``. Otherwise, returns
``falsetext``. The field should be entered without ``$``.
**Example:** ``%ifdefempty{compilation,Album,Compilation}``
ifdefnotempty
``%ifdefnotempty{field,text}`` or ``%ifdefnotempty{field,text,falsetext}``:
If field is not empty, then return ``truetext``. Otherwise, returns
``falsetext``. The field should be entered without ``$``.
**Example:** ``%ifdefnotempty{compilation,Compilation,Album}``
initial
``%initial{text}``: Get the first character of a text in lowercase. The
text is converted to ASCII. All non word characters are erased.
**Example:** ``%initial{Schubert}`` → ``s``
left
``%left{text,n}``: Return the first “n” characters of “text”.
**Example:** ``%left{Schubert, 3}`` → ``Sch``
lower
``%lower{text}``: Convert “text” to lowercase.
**Example:** ``%lower{SCHUBERT}`` → ``schubert``
nowhitespace
``%nowhitespace{text,replace}``: Replace all whitespace characters with
``replace``. By default: a dash (``-``)
**Example:** ``%nowhitespace{a b}`` → ``a-b``; ``%nowhitespace{a b, _}`` →
``a_b``
num
``%num{number,count}``: Pad decimal number with leading zeros.
**Example:** ``%num{7,3}`` → ``007``
replchars
``%replchars{text,chars,replace}``: Replace the characters “chars” in
“text” with “replace”.
**Example:** ``%replchars{Schubert,-,ue}`` → ``Sch-b-rt``
right
``%right{text,n}``: Return the last “n” characters of “text”.
**Example:** ``%right{Schubert,3}`` → ``ert``
sanitize
``%sanitize{text}``: Delete characters that are not allowed in most file
systems.
**Example:** ``%sanitize{x:*?<>|/~&x}`` → ``xx``
shorten
``%shorten{text}`` or ``%shorten{text,max_size}``: Shorten “text” on word
boundarys.
**Example:** ``%shorten{Lorem ipsum dolor sit, 10}`` → ``Lorem``
time
``%time{date_time,format,curformat}``: Return the date and time in any
format accepted by ``strftime``. For example, to get the year, use
``%time{$added,%Y}``.
**Example:** ``%time{30 Nov 2024,%Y,%d %b %Y}`` → ``2024``
title
``%title{text}``: Convert “text” to Title Case.
**Example:** ``%title{franz schubert}`` → ``Franz Schubert``
upper
``%upper{text}``: Convert “text” to UPPERCASE.
**Example:** ``%upper{foo}`` → ``FOO``
Template Symbols (or Variables)
In path templates, symbols or varialbes such as ``$title``
(any name with the prefix ``$``) are replaced by the corresponding value.
Because ``$`` is used to delineate a field reference, you can use ``$$`` to emit
a dollars sign. As with `Python template strings`_, ``${title}`` is equivalent
to ``$title``; you can use this if you need to separate a field name from the
text that follows it.
.. _Python template strings: https://docs.python.org/library/string.html#template-strings
Template Functions (or Macros)
Path templates also support *function calls*, which can be used to transform
text and perform logical manipulations. The syntax for function calls is like
this: ``%func{arg,arg}``. For example, the ``upper`` function makes its argument
upper-case, so ``%upper{lorem ipsum}`` will be replaced with ``LOREM IPSUM``.
You can, of course, nest function calls and place variable references in
function arguments, so ``%upper{$title}`` becomes the upper-case version of the
title.
Syntax Details
The characters ``$``, ``%``, ``{``, ``}``, and ``,`` are “special” in the path
template syntax. This means that, for example, if you want a ``%`` character to
appear in your paths, you’ll need to be careful that you don’t accidentally
write a function call. To escape any of these characters (except ``{``, and
``,`` outside a function argument), prefix it with a ``$``. For example,
``$$`` becomes ``$``; ``$%`` becomes ``%``, etc. The only exceptions are:
* ``${``, which is ambiguous with the variable reference syntax (like
``${title}``). To insert a ``{`` alone, it's always sufficient to just type
``{``.
* commas are used as argument separators in function calls. Inside of a
function’s argument, use ``$,`` to get a literal ``,`` character. Outside of
any function argument, escaping is not necessary: ``,`` by itself will
produce ``,`` in the output.
If a value or function is undefined, the syntax is simply left unreplaced. For
example, if you write ``$foo`` in a path template, this will yield ``$foo`` in
the resulting paths because "foo" is not a valid field name. The same is true of
syntax errors like unclosed ``{}`` pairs; if you ever see template syntax
constructs leaking into your paths, check your template for errors.
If an error occurs in the Python code that implements a function, the function
call will be expanded to a string that describes the exception so you can debug
your template. For example, the second parameter to ``%left`` must be an
integer; if you write ``%left{foo,bar}``, this will be expanded to something
like ``<ValueError: invalid literal for int()>``.
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 moved to a target directory (``--target /home/xyz/tidy-leadsheets``) and
the file names should not contain any spaces (``--no-whitespace``).
The title should be used as the file name (``--rename '$vbox_title'``).
The individual files should be stored in subdirectories named after the first
letter of the title (``--rename '%lower{%shorten{$vbox_title,1}}/...'``)
::
musescore-manager --rename '%lower{%shorten{$vbox_title,1}}/$vbox_title' \
--target /home/xyz/tidy-leadsheets \
--no-whitespace \
/home/xyz/messy-leadsheets
After executing the above command on the command line, ``find /home/xyz/tidy-leadsheets``
should show the following output:
::
i/I-Walk-the-Line.mscz
j/Jackson.mscz
f/Folsom-Prison-Blues.mscz
... use the Python API?
-----------------------
Please visit the `API documentation <https://mscxyz.readthedocs.io>`_ on readthedocs.
Instantiate a ``Score`` object:
.. code-block:: Python
from mscxyz import Score
score = Score('score.mscz')
assert score.path.exists()
assert score.filename == "score.mscz"
assert score.basename == "score"
assert score.extension == "mscz"
assert score.version == 4.20
assert score.version_major == 4
Examine the most important attribute of a ``Score`` object: ``xml_root``.
It is the root element of the XML document in which MuseScore stores all information
about a score.
It’s best to take a look at the `lxml API <https://lxml.de/api.html>`_ documentation
to see what you can do with this element. So much can be revealed:
lots of interesting things.
.. code-block:: Python
score = Score('score.mscz')
def print_elements(element: _Element, level: int) -> None:
for sub_element in element:
print(f"{' ' * level}<{sub_element.tag}>")
print_elements(sub_element, level + 1)
print_elements(score.xml_root, 0)
The output of the code example is very long, so here is a shortened version:
::
<programVersion>
<programRevision>
<LastEID>
<Score>
<Division>
<showInvisible>
<showUnprintable>
<showFrames>
<showMargins>
<open>
<metaTag>
...
... edit the meta data of a score file?
---------------------------------------
metatag
^^^^^^^
XML structure of a meta tag:
.. code-block:: xml
<metaTag name="tag"></metaTag>
All meta tags:
- ``arranger``
- ``audioComUrl`` (new in v4)
- ``composer``
- ``copyright``
- ``creationDate``
- ``lyricist``
- ``movementNumber``
- ``movementTitle``
- ``mscVersion``
- ``platform``
- ``poet`` (not in v4)
- ``source``
- ``sourceRevisionId``
- ``subtitle``
- ``translator``
- ``workNumber``
- ``workTitle``
vbox
^^^^
XML structure of a vbox tag:
.. code-block:: xml
<VBox>
<Text>
<style>title</style>
<text>Some title text</text>
</Text>
All vbox tags:
- ``title`` (v2,3: ``Title``)
- ``subtitle`` (v2,3: ``Subtitle``)
- ``composer`` (v2,3: ``Composer``)
- ``lyricist`` (v2,3: ``Lyricist``)
This command line tool bundles some meta data informations:
Combined meta data fields:
^^^^^^^^^^^^^^^^^^^^^^^^^^
- ``title`` (1. ``vbox_title`` 2. ``metatag_work_title``)
- ``subtitle`` (1. ``vbox_subtitle`` 2. ``metatag_subtitle`` 3. ``metatag_movement_title``)
- ``composer`` (1. ``vbox_composer`` 2. ``metatag_composer``)
- ``lyricist`` (1. ``vbox_lyricist`` 2. ``metatag_lyricist``)
Set the meta tag ``composer``:
.. code-block:: xml
<museScore version="4.20">
<Score>
<metaTag name="composer">Composer</metaTag>
.. code-block:: Python
score = Score('score.mscz')
assert score.meta.meta_tag.composer == "Composer"
score.meta.meta_tag.composer = "Mozart"
score.save()
new_score: Score = score.reload()
assert new_score.meta.meta_tag.composer == "Mozart"
.. code-block:: xml
<museScore version="4.20">
<Score>
<metaTag name="composer">Mozart</metaTag>
CLI Usage
=========
::
usage: musescore-manager [-h] [--print-completion {bash,zsh,tcsh}]
[-C <file-path>] [-b] [-d] [--catch-errors] [-m]
[-e FILE_PATH] [-E <extension>] [--compress]
[--remove-origin] [-V] [-v] [-k | --color | --no-color]
[--diff] [--print-xml] [-c <fields>] [-D]
[-i <source-fields> <format-string>] [-j]
[-l <log-file> <format-string>] [-y]
[-S <field> <format-string>]
[--metatag <field> <value>] [--vbox <field> <value>]
[--title <string>] [--subtitle <string>]
[--composer <string>] [--lyricist <string>]
[-x <number-or-all>] [-r <remap-pairs>] [-F]
[--rename <path-template>]
[-t <directory> | --only-filename] [-A] [-a] [-n]
[-K <fields>] [--list-fields] [--list-functions] [-L]
[-g <glob-pattern> | --mscz | --mscx]
[-s <style-name> <value>] [--clean] [-Y <file>] [--s3]
[--s4] [--reset-small-staffs] [--list-fonts]
[--text-font <font-face>] [--title-font <font-face>]
[--musical-symbol-font {Leland,Bravura,Emmentaler,Gonville,MuseJazz,Petaluma,Finale Maestro,Finale Broadway}]
[--musical-text-font {Leland Text,Bravura Text,Emmentaler Text,Gonville Text,MuseJazz Text,Petaluma Text,Finale Maestro Text,Finale Broadway Text}]
[--staff-space <dimension>]
[--page-size <width> <height>] [--a4] [--letter]
[--margin <dimension>]
[--show-header | --no-show-header]
[--header-first-page | --no-header-first-page]
[--different-odd-even-header | --no-different-odd-even-header]
[--header <left> <center> <right>]
[--header-odd-even <odd-left> <even-left> <odd-center> <even-center> <odd-right> <even-right>]
[--show-footer | --no-show-footer]
[--footer-first-page | --no-footer-first-page]
[--different-odd-even-footer | --no-different-odd-even-footer]
[--footer <left> <center> <right>]
[--footer-odd-even <odd-left> <even-left> <odd-center> <even-center> <odd-right> <even-right>]
[<path> ...]
The next generation command line tool to manipulate the XML based "*.mscX" and "*.mscZ" files of the notation software MuseScore.
positional arguments:
<path> Path to a "*.msc[zx]" file or a folder containing
"*.msc[zx]" files. can be specified several times.
options:
-h, --help show this help message and exit
--print-completion {bash,zsh,tcsh}
print shell completion script
-C <file-path>, --config-file <file-path>
Specify a configuration file in the INI format.
-b, --backup Create a backup file.
-d, --dry-run Simulate the actions.
--catch-errors Print error messages instead stop execution in a batch run.
-m, --mscore, --save-in-mscore
Open and save the XML file in MuseScore after manipulating
the XML with lxml to avoid differences in the XML structure.
-e FILE_PATH, --executable FILE_PATH
Path of the musescore executable.
export:
Export the scores in different formats.
-E <extension>, --export <extension>
Export the scores in a format defined by the extension. The
exported file has the same path, only the file extension is
different. Further information can be found at the MuseScore
website: https://musescore.org/en/handbook/2/file-formats,
https://musescore.org/en/handbook/3/file-export,
https://musescore.org/en/handbook/4/file-export. MuseScore
must be installed and the script must know the location of
the binary file.
--compress Save an uncompressed MuseScore file (*.mscx) as a compressed
file (*.mscz).
--remove-origin Delete the uncompressed original MuseScore file (*.mscx) if
it has been successfully converted to a compressed file
(*.mscz).
info:
Print informations about the score and the CLI interface itself.
-V, --version show program's version number and exit
-v, --verbose Make commands more verbose. You can specifiy multiple
arguments (. g.: -vvv) to make the command more verbose.
-k, --color, --no-color
Colorize the command line print statements. (default: True)
--diff Show a diff of the XML file before and after the
manipulation.
--print-xml Print the XML markup of the score.
meta:
Deal with meta data informations stored in the MuseScore file.
-c <fields>, --clean-meta <fields>
Clean the meta data fields. Possible values: „all“ or a
comma separated list of fields, for example:
„field_one,field_two“.
-D, --delete-duplicates
Deletes lyricist if this field is equal to composer. Deletes
subtitle if this field is equal totitle. Move subtitle to
combimed_title if title is empty.
-i <source-fields> <format-string>, --distribute-fields <source-fields> <format-string>
Distribute source fields to target fields by applying a
format string on the source fields. It is possible to apply
multiple --distribute-fields options. <source-fields> can be
a single field or a comma separated list of fields:
field_one,field_two. The program tries first to match the
<format-string> on the first source field. If thisfails, it
tries the second source field ... and so on.
-j, --json Write the meta data to a json file. The resulting file has
the same path as the input file, only the extension is
changed to “json”.
-l <log-file> <format-string>, --log <log-file> <format-string>
Write one line per file to a text file. e. g. --log
/tmp/musescore-manager.log '$title $composer'
-y, --synchronize Synchronize the values of the first vertical frame (vbox)
(title, subtitle, composer, lyricist) with the corresponding
metadata fields
-S <field> <format-string>, --set-field <field> <format-string>
Set value to meta data fields.
--metatag <field> <value>, --metatag-meta <field> <value>
Define the metadata in MetaTag elements. Available fields:
arranger, audio_com_url, composer, copyright, creation_date,
lyricist, movement_number, movement_title, msc_version,
platform, poet, source, source_revision_id, subtitle,
translator, work_number, work_title.
--vbox <field> <value>, --vbox-meta <field> <value>
Define the metadata in VBox elements. Available fields:
composer, lyricist, subtitle, title.
--title <string> Create a vertical frame (vbox) containing a title text field
and set the corresponding document properties work title
field (metatag).
--subtitle <string> Create a vertical frame (vbox) containing a subtitle text
field and set the corresponding document properties subtitle
and movement title filed (metatag).
--composer <string> Create a vertical frame (vbox) containing a composer text
field and set the corresponding document properties composer
field (metatag).
--lyricist <string> Create a vertical frame (vbox) containing a lyricist text
field and set the corresponding document properties lyricist
field (metatag).
lyrics:
-x <number-or-all>, --extract <number-or-all>, --extract-lyrics <number-or-all>
Extract each lyrics verse into a separate MuseScore file.
Specify ”all” to extract all lyrics verses. The old verse
number is appended to the file name, e. g.: score_1.mscx.
-r <remap-pairs>, --remap <remap-pairs>, --remap-lyrics <remap-pairs>
Remap lyrics. Example: "--remap 3:2,5:3". This example
remaps lyrics verse 3 to verse 2 and verse 5 to 3. Use
commas to specify multiple remap pairs. One remap pair is
separated by a colon in this form: "old:new": "old" stands
for the old verse number. "new" stands for the new verse
number.
-F, --fix, --fix-lyrics
Fix lyrics: Convert trailing hyphens ("la- la- la") to a
correct hyphenation ("la - la - la")
rename:
Rename the “*.msc[zx]” files.
--rename <path-template>
A path template string to set the destination location.
-t <directory>, --target <directory>
Target directory
--only-filename Rename only the filename and don’t move the score to a
different directory.
-A, --alphanum Use only alphanumeric characters.
-a, --ascii Use only ASCII characters.
-n, --no-whitespace Replace all whitespaces with dashes or sometimes underlines.
-K <fields>, --skip-if-empty <fields>
Skip the rename action if the fields specified in <fields>
are empty. Multiple fields can be separated by commas, e.
g.: composer,title
--list-fields List all available fields that can be used in the path
templates.
--list-functions List all available functions that can be used in the path
templates.
selection:
The following options affect how the manager selects the MuseScore files.
-L, --list-files Only list files and do nothing else.
-g <glob-pattern>, --glob <glob-pattern>
Handle only files which matches against Unix style glob
patterns (e. g. "*.mscx", "* - *"). If you omit this option,
the standard glob pattern "*.msc[xz]" is used.
--mscz Take only "*.mscz" files into account.
--mscx Take only "*.mscx" files into account.
style:
Change the styles.
-s <style-name> <value>, --style <style-name> <value>
Set a single style value. For example: --style pageWidth 8.5
--clean Clean and reset the formating of the "*.mscx" file
-Y <file>, --style-file <file>
Load a "*.mss" style file and include the contents of this
file.
--s3, --styles-v3 List all possible version 3 styles.
--s4, --styles-v4 List all possible version 4 styles.
--reset-small-staffs Reset all small staffs to normal size.
font (style):
Change the font faces of a score.
--list-fonts List all font related styles.
--text-font <font-face>
Set nearly all fonts except “romanNumeralFontFace”,
“figuredBassFontFace”, “dynamicsFontFace“,
“musicalSymbolFont” and “musicalTextFont”.
--title-font <font-face>
Set “titleFontFace” and “subTitleFontFace”.
--musical-symbol-font {Leland,Bravura,Emmentaler,Gonville,MuseJazz,Petaluma,Finale Maestro,Finale Broadway}
Set “musicalSymbolFont”, “dynamicsFont” and
“dynamicsFontFace”.
--musical-text-font {Leland Text,Bravura Text,Emmentaler Text,Gonville Text,MuseJazz Text,Petaluma Text,Finale Maestro Text,Finale Broadway Text}
Set “musicalTextFont”.
page (style):
Page settings.
--staff-space <dimension>
Set the staff space or spatium. This is the vertical
distance between two lines of a music staff.
--page-size <width> <height>
Set the page size.
--a4, --din-a4 Set the paper size to DIN A4 (210 by 297 mm).
--letter Set the paper size to Letter (8.5 by 11 in).
--margin <dimension> Set the top, right, bottom and left margins to the same
value.
header (style):
Change the header.
--show-header, --no-show-header
Show or hide the header.
--header-first-page, --no-header-first-page
Show the header on the first page.
--different-odd-even-header, --no-different-odd-even-header
Use different header for odd and even pages.
--header <left> <center> <right>
Set the header for all pages.
--header-odd-even <odd-left> <even-left> <odd-center> <even-center> <odd-right> <even-right>
Set different headers for odd and even pages.
footer (style):
Change the footer.
--show-footer, --no-show-footer
Show or hide the footer.
--footer-first-page, --no-footer-first-page
Show the footer on the first page.
--different-odd-even-footer, --no-different-odd-even-footer
Use different footers for odd and even pages.
--footer <left> <center> <right>
Set the footer for all pages.
--footer-odd-even <odd-left> <even-left> <odd-center> <even-center> <odd-right> <even-right>
Set different footers for odd and even pages.
Configuration file
==================
``/etc/mscxyz.ini``
.. code-block:: ini
[general]
executable = /usr/bin/mscore3
colorize = True
[rename]
format = '$title ($composer)'
Other MuseScore related projects
================================
* https://github.com/johentsch/ms3
Development
===========
Test
----
::
make test
Publish a new version
---------------------
::
git tag 1.1.1
git push --tags
make publish
Package documentation
---------------------
The package documentation is hosted on
`readthedocs <http://mscxyz.readthedocs.io>`_.
Generate the package documentation:
::
make docs
Raw data
{
"_id": null,
"home_page": "https://mscxyz.readthedocs.io",
"name": "mscxyz",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9,<4.0",
"maintainer_email": "",
"keywords": "audio",
"author": "Josef Friedrich",
"author_email": "josef@friedrich.rocks",
"download_url": "https://files.pythonhosted.org/packages/6f/18/e58059d4793b722807a93643966063ab7f8aa8fd91e9a15ed1787ac18c37/mscxyz-3.0.0.tar.gz",
"platform": null,
"description": ".. image:: http://img.shields.io/pypi/v/mscxyz.svg\n :target: https://pypi.org/project/mscxyz\n :alt: This package on the Python Package Index\n\n.. image:: https://github.com/Josef-Friedrich/mscxyz/actions/workflows/tests.yml/badge.svg\n :target: https://github.com/Josef-Friedrich/mscxyz/actions/workflows/tests.yml\n :alt: Tests\n\n.. image:: https://readthedocs.org/projects/mscxyz/badge/?version=latest\n :target: https://mscxyz.readthedocs.io/en/latest/?badge=latest\n :alt: Documentation Status\n\n==============================\nmscxyz - The MuseScore Manager\n==============================\n\nManipulate the XML based ``.mscz`` and ``.mscx`` files of the notation software\n`MuseScore <https://musescore.org>`_.\n\nFeatures\n========\n\n* Batch processing of ``.msc[zx]`` files in nested folder structures\n* Rename ``.msc[zx]`` files based on meta tags\n* Set, read and synchronized meta tags\n* Set style properties\n* Can handle MuseScore 2, 3 and 4 files\n* Command line interface\n* Python API\n\nInstallation\n============\n\n.. code:: Shell\n\n pipx install mscxyz\n\nHow to ...\n==========\n\n... specify the MuseScore files to work on?\n-------------------------------------------\n\nTo find out which files are selected by the script, the ``-L, --list-files``\noption can be used. The ``--list-files`` option lists as the name suggests\nonly the file paths and doesn\u2019t touch the specified *MuseScore* files:\n\n::\n\n musescore-manager --list-files\n\nWithout an option the script lists all MuseScore files in the current directory\nin a recursive way (``musescore-manager`` = ``musescore-manager .``).\nYou can pass multiple file paths to the script:\n\n::\n\n musescore-manager -L score1.mscz score2.mscz score3.mscz\n\nor multiple directories:\n\n::\n\n musescore-manager -L folder1 folder2 folder3\n\nor use the path expansion of your shell:\n\n::\n\n musescore-manager -L *.mscz\n\nTo apply glob patterns on the file paths, the ``--glob`` option can be used.\n\n::\n\n musescore-manager -L --glob \"*/folder/*.mscz\"\n\nTo selection only *mscz* oder *mscx* files use the options ``--mscz`` or ``--mscx``.\nDon\u2019t mix the options ``--mscz`` and ``--mscx`` with the option ``--glob``.\n\nThe python package ``mscxyz`` exports a function named ``list_path`` which can\nbe used to list the paths of MuseScore files. This allows you to list score\npaths in a nested folder structure in a similar way to the command line.\nThis folder structure is used for the following example:\n\n::\n\n cd /home/xyz/scores\n find . | sort\n\n .\n ./level1\n ./level1/level2\n ./level1/level2/score2.mscz\n ./level1/level2/level3\n ./level1/level2/level3/score3.mscz\n ./level1/score1.mscz\n ./score0.mscz\n\n.. code-block:: Python\n\n from mscxyz import list_path, Score\n\n score_paths = []\n for score_path in list_path(path=\"/home/xyz/scores\", extension=\"mscz\"):\n score = Score(score_path)\n assert score.path.exists()\n assert score.extension == \"mscz\"\n score_paths.append(str(score_path))\n\n assert len(score_paths) == 4\n\n assert \"level1/level2/level3/score3.mscz\" in score_paths[3]\n assert \"level1/level2/score2.mscz\" in score_paths[2]\n assert \"level1/score1.mscz\" in score_paths[1]\n assert \"score0.mscz\" in score_paths[0]\n\n... export files to different files types?\n------------------------------------------\n\nOn the command line use the option ``--export`` to export the scores to\ndifferent file types. The exported file has the same path, only the file\nextension is different. Further information about the supported file formats\ncan be found at the MuseScore website:\n`Version 2 <https://musescore.org/en/handbook/2/file-formats>`_,\n`Version 3 <https://musescore.org/en/handbook/3/file-export>`_ and\n`Version 4 <https://musescore.org/en/handbook/4/file-export>`_\nThe MuseScore binay must be installed and the script must know the location of t\nhis binary.\n\n::\n\n musescore-manager --export pdf\n musescore-manager --export png\n\n.. code-block:: Python\n\n score = Score('score.mscz')\n score.export.to_extension(\"musicxml\")\n\n... change the styling of a score?\n----------------------------------\n\nSet a single style by its style name ``--style``:\n\n::\n\n musescore-manager --style staffDistance 7.5 score.mscz\n\nTo set mulitple styles at once specify the option ``--style`` multiple times:\n\n::\n\n musescore-manager --style staffUpperBorder 5.5 --style staffLowerBorder 5.5 score.mscz\n\n... change the font faces of a score?\n-------------------------------------\n\nSome options change mutliple font related xml elements at once:\n\n::\n\n musescore-manager --text-font Alegreya score.mscz\n musescore-manager --title-font \"Alegreya Sans\" score.mscz\n musescore-manager --musical-symbol-font Leland score.mscz\n musescore-manager --musical-text-font \"Leland Text\" score.mscz\n\nSet all font faces (using a for loop, not available in MuseScore 2):\n\n.. code-block:: Python\n\n score = Score('score.mscz')\n assert score.style.get(\"defaultFontFace\") == \"FreeSerif\"\n\n for element in score.style.styles:\n if \"FontFace\" in element.tag:\n element.text = \"Alegreya\"\n score.save()\n\n new_score: Score = score.reload()\n assert new_score.style.get(\"defaultFontFace\") == \"Alegreya\"\n\nSet all text font faces (using the method ``score.style.set_text_font_faces(font_face)``,\nnot available in MuseScore 2):\n\n.. code-block:: Python\n\n score = Score('score.mscz')\n assert score.style.get(\"defaultFontFace\") == \"FreeSerif\"\n\n response = score.style.set_text_font_faces(\"Alegreya\")\n\n assert response == [\n ...\n (\"harpPedalTextDiagramFontFace\", \"Edwin\", \"Alegreya\"),\n (\"longInstrumentFontFace\", \"FreeSerif\", \"Alegreya\"),\n ...\n ]\n\n score.save()\n\n new_score: Score = score.reload()\n assert new_score.style.get(\"defaultFontFace\") == \"Alegreya\"\n\n... enable autocomplete support?\n--------------------------------\n\nUse one of the following autocomplete files ...\n\n* `bash <https://github.com/Josef-Friedrich/mscxyz/blob/main/autocomplete.bash>`_\n* `zsh <https://github.com/Josef-Friedrich/mscxyz/blob/main/autocomplete.zsh>`_\n* `tcsh <https://github.com/Josef-Friedrich/mscxyz/blob/main/autocomplete.tcsh>`_\n\n... or generate the autocomplete files by yourself?\n---------------------------------------------------\n\n::\n\n musescore-manager --print-completion bash > autocomplete.bash\n musescore-manager --print-completion zsh > autocomplete.zsh\n musescore-manager --print-completion tcsh > autocomplete.tcsh\n\n... rename many files at once?\n------------------------------\n\nFields\n^^^^^^\n\n- ``title``: The combined title\n- ``subtitle``: The combined subtitle\n- ``composer``: The combined composer\n- ``lyricist``: The combined lyricist\n- ``vbox_title``: The title field of the score as it appears in the center of the first vertical frame (VBox).\n- ``vbox_subtitle``: The subtitle field of the score as it appears in the center of the first vertical frame (VBox).\n- ``vbox_composer``: The composer field of the score as it appears in the center of the first vertical frame (VBox).\n- ``vbox_lyricist``: The lyricist field of the score as it appears in the center of the first vertical frame (VBox).\n- ``metatag_arranger``: The arranger field stored as project properties.\n- ``metatag_audio_com_url``: The audio.com URL field stored as project properties.\n- ``metatag_composer``: The composer field stored as project properties.\n- ``metatag_copyright``: The copyright field stored as project properties.\n- ``metatag_creation_date``: The creation date field stored as project properties.\n- ``metatag_lyricist``: The lyricist field stored as project properties.\n- ``metatag_movement_number``: The movement number field stored as project properties.\n- ``metatag_movement_title``: The movement title field stored as project properties.\n- ``metatag_msc_version``: The MuseScore version field stored as project properties.\n- ``metatag_platform``: The platform field stored as project properties.\n- ``metatag_poet``: The poet field stored as project properties.\n- ``metatag_source``: The source field stored as project properties.\n- ``metatag_source_revision_id``: The source revision ID field stored as project properties.\n- ``metatag_subtitle``: The subtitle field stored as project properties.\n- ``metatag_translator``: The translator field stored as project properties.\n- ``metatag_work_number``: The work number field stored as project properties.\n- ``metatag_work_title``: The work title field stored as project properties.\n- ``version``: The MuseScore version as a floating point number, for example ``2.03``, ``3.01`` or ``4.20``.\n- ``version_major``: The major MuseScore version, for example ``2``, ``3`` or ``4``.\n- ``program_version``: The semantic version number of the MuseScore program, for example: ``4.2.0``.\n- ``program_revision``: The revision number of the MuseScore program, for example: ``eb8d33c``.\n- ``path``: The absolute path of the MuseScore file, for example ``/home/xyz/score.mscz``.\n- ``backup_file``: The absolute path of the backup file. The string ``_bak`` is appended to the file name before the extension.\n- ``json_file``: The absolute path of the JSON file in which the metadata can be exported.\n- ``dirname``: The name of the containing directory of the MuseScore file, for example: ``/home/xyz/score_files``.\n- ``filename``: The filename of the MuseScore file, for example:``score.mscz``.\n- ``basename``: The basename of the score file, for example: ``score``.\n- ``extension``: The extension (``mscx`` or ``mscz``) of the score file.\n\nFunctions\n^^^^^^^^^\n\nalpha\n ``%alpha{text}``: This function first ASCIIfies the given text, then all\n non alphabet characters are replaced with whitespaces.\n\n **Example:** ``%alpha{a1b23c}`` \u2192 ``a b c``\n\nalphanum\n ``%alphanum{text}``: This function first ASCIIfies the given text, then all\n non alpanumeric characters are replaced with whitespaces.\n\n **Example:** ``%alphanum{apr\u00e8s-\u00e9v\u00eaque1}`` \u2192 ``apres eveque1``\n\nasciify\n ``%asciify{text}``: Translate non-ASCII characters to their ASCII\n equivalents. For example, \u201ccaf\u00e9\u201d becomes \u201ccafe\u201d. Uses the mapping provided\n by the unidecode module.\n\n **Example:** ``%asciify{\u00e4\u00c4\u00f6\u00d6\u00fc\u00dc}`` \u2192 ``aeAeoeOeueUe``\n\ndelchars\n ``%delchars{text,chars}``: Delete every single character of \u201cchars\u201c in\n \u201ctext\u201d.\n\n **Example:** ``%delchars{Schubert, ue}`` \u2192 ``Schbrt``\n\ndeldupchars\n ``%deldupchars{text,chars}``: Search for duplicate characters and replace\n with only one occurrance of this characters.\n\n **Example:** ``%deldupchars{a---b___c...d}`` \u2192 ``a-b_c.d``; ``%deldupchars{a\n ---b___c, -}`` \u2192 ``a-b___c``\n\nfirst\n ``%first{text}`` or ``%first{text,count,skip}`` or\n ``%first{text,count,skip,sep,join}``: Returns the first item, separated by\n ``;``. You can use ``%first{text,count,skip}``, where count is the number of\n items (default 1) and skip is number to skip (default 0). You can also use\n ``%first{text,count,skip,sep,join}`` where ``sep`` is the separator, like\n ``;`` or ``/`` and join is the text to concatenate the items.\n\n **Example:** ``%first{Alice / Bob / Eve,2,0, / , & }`` \u2192 ``Alice & Bob``\n\nif\n ``%if{condition,trueval}`` or ``%if{condition,trueval,falseval}``: If\n condition is nonempty (or nonzero, if it\u2019s a number), then returns the\n second argument. Otherwise, returns the third argument if specified (or\n nothing if ``falseval`` is left off).\n\n **Example:** ``x%if{false,foo}`` \u2192 ``x``\n\nifdef\n ``%ifdef{field}``, ``%ifdef{field,trueval}`` or\n ``%ifdef{field,trueval,falseval}``: If field exists, then return\n ``trueval`` or field (default). Otherwise, returns ``falseval``. The field\n should be entered without ``$``.\n\n **Example:** ``%ifdef{compilation,Compilation}``\n\nifdefempty\n ``%ifdefempty{field,text}`` or ``%ifdefempty{field,text,falsetext}``: If\n field exists and is empty, then return ``truetext``. Otherwise, returns\n ``falsetext``. The field should be entered without ``$``.\n\n **Example:** ``%ifdefempty{compilation,Album,Compilation}``\n\nifdefnotempty\n ``%ifdefnotempty{field,text}`` or ``%ifdefnotempty{field,text,falsetext}``:\n If field is not empty, then return ``truetext``. Otherwise, returns\n ``falsetext``. The field should be entered without ``$``.\n\n **Example:** ``%ifdefnotempty{compilation,Compilation,Album}``\n\ninitial\n ``%initial{text}``: Get the first character of a text in lowercase. The\n text is converted to ASCII. All non word characters are erased.\n\n **Example:** ``%initial{Schubert}`` \u2192 ``s``\n\nleft\n ``%left{text,n}``: Return the first \u201cn\u201d characters of \u201ctext\u201d.\n\n **Example:** ``%left{Schubert, 3}`` \u2192 ``Sch``\n\nlower\n ``%lower{text}``: Convert \u201ctext\u201d to lowercase.\n\n **Example:** ``%lower{SCHUBERT}`` \u2192 ``schubert``\n\nnowhitespace\n ``%nowhitespace{text,replace}``: Replace all whitespace characters with\n ``replace``. By default: a dash (``-``)\n\n **Example:** ``%nowhitespace{a b}`` \u2192 ``a-b``; ``%nowhitespace{a b, _}`` \u2192\n ``a_b``\n\nnum\n ``%num{number,count}``: Pad decimal number with leading zeros.\n\n **Example:** ``%num{7,3}`` \u2192 ``007``\n\nreplchars\n ``%replchars{text,chars,replace}``: Replace the characters \u201cchars\u201d in\n \u201ctext\u201d with \u201creplace\u201d.\n\n **Example:** ``%replchars{Schubert,-,ue}`` \u2192 ``Sch-b-rt``\n\nright\n ``%right{text,n}``: Return the last \u201cn\u201d characters of \u201ctext\u201d.\n\n **Example:** ``%right{Schubert,3}`` \u2192 ``ert``\n\nsanitize\n ``%sanitize{text}``: Delete characters that are not allowed in most file\n systems.\n\n **Example:** ``%sanitize{x:*?<>|/~&x}`` \u2192 ``xx``\n\nshorten\n ``%shorten{text}`` or ``%shorten{text,max_size}``: Shorten \u201ctext\u201d on word\n boundarys.\n\n **Example:** ``%shorten{Lorem ipsum dolor sit, 10}`` \u2192 ``Lorem``\n\ntime\n ``%time{date_time,format,curformat}``: Return the date and time in any\n format accepted by ``strftime``. For example, to get the year, use\n ``%time{$added,%Y}``.\n\n **Example:** ``%time{30 Nov 2024,%Y,%d %b %Y}`` \u2192 ``2024``\n\ntitle\n ``%title{text}``: Convert \u201ctext\u201d to Title Case.\n\n **Example:** ``%title{franz schubert}`` \u2192 ``Franz Schubert``\n\nupper\n ``%upper{text}``: Convert \u201ctext\u201d to UPPERCASE.\n\n **Example:** ``%upper{foo}`` \u2192 ``FOO``\n\nTemplate Symbols (or Variables)\n In path templates, symbols or varialbes such as ``$title``\n (any name with the prefix ``$``) are replaced by the corresponding value.\n\n Because ``$`` is used to delineate a field reference, you can use ``$$`` to emit\n a dollars sign. As with `Python template strings`_, ``${title}`` is equivalent\n to ``$title``; you can use this if you need to separate a field name from the\n text that follows it.\n\n.. _Python template strings: https://docs.python.org/library/string.html#template-strings\n\nTemplate Functions (or Macros)\n Path templates also support *function calls*, which can be used to transform\n text and perform logical manipulations. The syntax for function calls is like\n this: ``%func{arg,arg}``. For example, the ``upper`` function makes its argument\n upper-case, so ``%upper{lorem ipsum}`` will be replaced with ``LOREM IPSUM``.\n You can, of course, nest function calls and place variable references in\n function arguments, so ``%upper{$title}`` becomes the upper-case version of the\n title.\n\nSyntax Details\n The characters ``$``, ``%``, ``{``, ``}``, and ``,`` are \u201cspecial\u201d in the path\n template syntax. This means that, for example, if you want a ``%`` character to\n appear in your paths, you\u2019ll need to be careful that you don\u2019t accidentally\n write a function call. To escape any of these characters (except ``{``, and\n ``,`` outside a function argument), prefix it with a ``$``. For example,\n ``$$`` becomes ``$``; ``$%`` becomes ``%``, etc. The only exceptions are:\n\n * ``${``, which is ambiguous with the variable reference syntax (like\n ``${title}``). To insert a ``{`` alone, it's always sufficient to just type\n ``{``.\n * commas are used as argument separators in function calls. Inside of a\n function\u2019s argument, use ``$,`` to get a literal ``,`` character. Outside of\n any function argument, escaping is not necessary: ``,`` by itself will\n produce ``,`` in the output.\n\n If a value or function is undefined, the syntax is simply left unreplaced. For\n example, if you write ``$foo`` in a path template, this will yield ``$foo`` in\n the resulting paths because \"foo\" is not a valid field name. The same is true of\n syntax errors like unclosed ``{}`` pairs; if you ever see template syntax\n constructs leaking into your paths, check your template for errors.\n\n If an error occurs in the Python code that implements a function, the function\n call will be expanded to a string that describes the exception so you can debug\n your template. For example, the second parameter to ``%left`` must be an\n integer; if you write ``%left{foo,bar}``, this will be expanded to something\n like ``<ValueError: invalid literal for int()>``.\n\nThe following example assumes that the folder ``/home/xyz/messy-leadsheets``\ncontains the following three MuseScore files: ``folsom prison blues.mscz``,\n``Johnny Cash - I Walk the Line.mscz``, ``Jackson (Cash).mscz``\nThe files are named arbitrarily without any recognizable pattern, but they have a\ntitle in the first vertical frame (VBox).\n\nThe files should be moved to a target directory (``--target /home/xyz/tidy-leadsheets``) and\nthe file names should not contain any spaces (``--no-whitespace``).\nThe title should be used as the file name (``--rename '$vbox_title'``).\nThe individual files should be stored in subdirectories named after the first\nletter of the title (``--rename '%lower{%shorten{$vbox_title,1}}/...'``)\n\n::\n\n musescore-manager --rename '%lower{%shorten{$vbox_title,1}}/$vbox_title' \\\n --target /home/xyz/tidy-leadsheets \\\n --no-whitespace \\\n /home/xyz/messy-leadsheets\n\nAfter executing the above command on the command line, ``find /home/xyz/tidy-leadsheets``\nshould show the following output:\n\n::\n\n i/I-Walk-the-Line.mscz\n j/Jackson.mscz\n f/Folsom-Prison-Blues.mscz\n\n... use the Python API?\n-----------------------\n\nPlease visit the `API documentation <https://mscxyz.readthedocs.io>`_ on readthedocs.\n\nInstantiate a ``Score`` object:\n\n.. code-block:: Python\n\n from mscxyz import Score\n score = Score('score.mscz')\n assert score.path.exists()\n assert score.filename == \"score.mscz\"\n assert score.basename == \"score\"\n assert score.extension == \"mscz\"\n assert score.version == 4.20\n assert score.version_major == 4\n\nExamine the most important attribute of a ``Score`` object: ``xml_root``.\nIt is the root element of the XML document in which MuseScore stores all information\nabout a score.\nIt\u2019s best to take a look at the `lxml API <https://lxml.de/api.html>`_ documentation\nto see what you can do with this element. So much can be revealed:\nlots of interesting things.\n\n.. code-block:: Python\n\n score = Score('score.mscz')\n\n def print_elements(element: _Element, level: int) -> None:\n for sub_element in element:\n print(f\"{' ' * level}<{sub_element.tag}>\")\n print_elements(sub_element, level + 1)\n\n print_elements(score.xml_root, 0)\n\nThe output of the code example is very long, so here is a shortened version:\n\n::\n\n <programVersion>\n <programRevision>\n <LastEID>\n <Score>\n <Division>\n <showInvisible>\n <showUnprintable>\n <showFrames>\n <showMargins>\n <open>\n <metaTag>\n ...\n\n... edit the meta data of a score file?\n---------------------------------------\n\nmetatag\n^^^^^^^\n\nXML structure of a meta tag:\n\n.. code-block:: xml\n\n <metaTag name=\"tag\"></metaTag>\n\nAll meta tags:\n\n- ``arranger``\n- ``audioComUrl`` (new in v4)\n- ``composer``\n- ``copyright``\n- ``creationDate``\n- ``lyricist``\n- ``movementNumber``\n- ``movementTitle``\n- ``mscVersion``\n- ``platform``\n- ``poet`` (not in v4)\n- ``source``\n- ``sourceRevisionId``\n- ``subtitle``\n- ``translator``\n- ``workNumber``\n- ``workTitle``\n\nvbox\n^^^^\n\nXML structure of a vbox tag:\n\n.. code-block:: xml\n\n <VBox>\n <Text>\n <style>title</style>\n <text>Some title text</text>\n </Text>\n\nAll vbox tags:\n\n- ``title`` (v2,3: ``Title``)\n- ``subtitle`` (v2,3: ``Subtitle``)\n- ``composer`` (v2,3: ``Composer``)\n- ``lyricist`` (v2,3: ``Lyricist``)\n\nThis command line tool bundles some meta data informations:\n\nCombined meta data fields:\n^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n- ``title`` (1. ``vbox_title`` 2. ``metatag_work_title``)\n- ``subtitle`` (1. ``vbox_subtitle`` 2. ``metatag_subtitle`` 3. ``metatag_movement_title``)\n- ``composer`` (1. ``vbox_composer`` 2. ``metatag_composer``)\n- ``lyricist`` (1. ``vbox_lyricist`` 2. ``metatag_lyricist``)\n\nSet the meta tag ``composer``:\n\n.. code-block:: xml\n\n <museScore version=\"4.20\">\n <Score>\n <metaTag name=\"composer\">Composer</metaTag>\n\n.. code-block:: Python\n\n score = Score('score.mscz')\n assert score.meta.meta_tag.composer == \"Composer\"\n\n score.meta.meta_tag.composer = \"Mozart\"\n score.save()\n\n new_score: Score = score.reload()\n assert new_score.meta.meta_tag.composer == \"Mozart\"\n\n.. code-block:: xml\n\n <museScore version=\"4.20\">\n <Score>\n <metaTag name=\"composer\">Mozart</metaTag>\n\nCLI Usage\n=========\n\n:: \n\n usage: musescore-manager [-h] [--print-completion {bash,zsh,tcsh}]\n [-C <file-path>] [-b] [-d] [--catch-errors] [-m]\n [-e FILE_PATH] [-E <extension>] [--compress]\n [--remove-origin] [-V] [-v] [-k | --color | --no-color]\n [--diff] [--print-xml] [-c <fields>] [-D]\n [-i <source-fields> <format-string>] [-j]\n [-l <log-file> <format-string>] [-y]\n [-S <field> <format-string>]\n [--metatag <field> <value>] [--vbox <field> <value>]\n [--title <string>] [--subtitle <string>]\n [--composer <string>] [--lyricist <string>]\n [-x <number-or-all>] [-r <remap-pairs>] [-F]\n [--rename <path-template>]\n [-t <directory> | --only-filename] [-A] [-a] [-n]\n [-K <fields>] [--list-fields] [--list-functions] [-L]\n [-g <glob-pattern> | --mscz | --mscx]\n [-s <style-name> <value>] [--clean] [-Y <file>] [--s3]\n [--s4] [--reset-small-staffs] [--list-fonts]\n [--text-font <font-face>] [--title-font <font-face>]\n [--musical-symbol-font {Leland,Bravura,Emmentaler,Gonville,MuseJazz,Petaluma,Finale Maestro,Finale Broadway}]\n [--musical-text-font {Leland Text,Bravura Text,Emmentaler Text,Gonville Text,MuseJazz Text,Petaluma Text,Finale Maestro Text,Finale Broadway Text}]\n [--staff-space <dimension>]\n [--page-size <width> <height>] [--a4] [--letter]\n [--margin <dimension>]\n [--show-header | --no-show-header]\n [--header-first-page | --no-header-first-page]\n [--different-odd-even-header | --no-different-odd-even-header]\n [--header <left> <center> <right>]\n [--header-odd-even <odd-left> <even-left> <odd-center> <even-center> <odd-right> <even-right>]\n [--show-footer | --no-show-footer]\n [--footer-first-page | --no-footer-first-page]\n [--different-odd-even-footer | --no-different-odd-even-footer]\n [--footer <left> <center> <right>]\n [--footer-odd-even <odd-left> <even-left> <odd-center> <even-center> <odd-right> <even-right>]\n [<path> ...]\n\n The next generation command line tool to manipulate the XML based \"*.mscX\" and \"*.mscZ\" files of the notation software MuseScore.\n\n positional arguments:\n <path> Path to a \"*.msc[zx]\" file or a folder containing\n \"*.msc[zx]\" files. can be specified several times.\n\n options:\n -h, --help show this help message and exit\n --print-completion {bash,zsh,tcsh}\n print shell completion script\n -C <file-path>, --config-file <file-path>\n Specify a configuration file in the INI format.\n -b, --backup Create a backup file.\n -d, --dry-run Simulate the actions.\n --catch-errors Print error messages instead stop execution in a batch run.\n -m, --mscore, --save-in-mscore\n Open and save the XML file in MuseScore after manipulating\n the XML with lxml to avoid differences in the XML structure.\n -e FILE_PATH, --executable FILE_PATH\n Path of the musescore executable.\n\n export:\n Export the scores in different formats.\n\n -E <extension>, --export <extension>\n Export the scores in a format defined by the extension. The\n exported file has the same path, only the file extension is\n different. Further information can be found at the MuseScore\n website: https://musescore.org/en/handbook/2/file-formats,\n https://musescore.org/en/handbook/3/file-export,\n https://musescore.org/en/handbook/4/file-export. MuseScore\n must be installed and the script must know the location of\n the binary file.\n --compress Save an uncompressed MuseScore file (*.mscx) as a compressed\n file (*.mscz).\n --remove-origin Delete the uncompressed original MuseScore file (*.mscx) if\n it has been successfully converted to a compressed file\n (*.mscz).\n\n info:\n Print informations about the score and the CLI interface itself.\n\n -V, --version show program's version number and exit\n -v, --verbose Make commands more verbose. You can specifiy multiple\n arguments (. g.: -vvv) to make the command more verbose.\n -k, --color, --no-color\n Colorize the command line print statements. (default: True)\n --diff Show a diff of the XML file before and after the\n manipulation.\n --print-xml Print the XML markup of the score.\n\n meta:\n Deal with meta data informations stored in the MuseScore file.\n\n -c <fields>, --clean-meta <fields>\n Clean the meta data fields. Possible values: \u201eall\u201c or a\n comma separated list of fields, for example:\n \u201efield_one,field_two\u201c.\n -D, --delete-duplicates\n Deletes lyricist if this field is equal to composer. Deletes\n subtitle if this field is equal totitle. Move subtitle to\n combimed_title if title is empty.\n -i <source-fields> <format-string>, --distribute-fields <source-fields> <format-string>\n Distribute source fields to target fields by applying a\n format string on the source fields. It is possible to apply\n multiple --distribute-fields options. <source-fields> can be\n a single field or a comma separated list of fields:\n field_one,field_two. The program tries first to match the\n <format-string> on the first source field. If thisfails, it\n tries the second source field ... and so on.\n -j, --json Write the meta data to a json file. The resulting file has\n the same path as the input file, only the extension is\n changed to \u201cjson\u201d.\n -l <log-file> <format-string>, --log <log-file> <format-string>\n Write one line per file to a text file. e. g. --log\n /tmp/musescore-manager.log '$title $composer'\n -y, --synchronize Synchronize the values of the first vertical frame (vbox)\n (title, subtitle, composer, lyricist) with the corresponding\n metadata fields\n -S <field> <format-string>, --set-field <field> <format-string>\n Set value to meta data fields.\n --metatag <field> <value>, --metatag-meta <field> <value>\n Define the metadata in MetaTag elements. Available fields:\n arranger, audio_com_url, composer, copyright, creation_date,\n lyricist, movement_number, movement_title, msc_version,\n platform, poet, source, source_revision_id, subtitle,\n translator, work_number, work_title.\n --vbox <field> <value>, --vbox-meta <field> <value>\n Define the metadata in VBox elements. Available fields:\n composer, lyricist, subtitle, title.\n --title <string> Create a vertical frame (vbox) containing a title text field\n and set the corresponding document properties work title\n field (metatag).\n --subtitle <string> Create a vertical frame (vbox) containing a subtitle text\n field and set the corresponding document properties subtitle\n and movement title filed (metatag).\n --composer <string> Create a vertical frame (vbox) containing a composer text\n field and set the corresponding document properties composer\n field (metatag).\n --lyricist <string> Create a vertical frame (vbox) containing a lyricist text\n field and set the corresponding document properties lyricist\n field (metatag).\n\n lyrics:\n -x <number-or-all>, --extract <number-or-all>, --extract-lyrics <number-or-all>\n Extract each lyrics verse into a separate MuseScore file.\n Specify \u201dall\u201d to extract all lyrics verses. The old verse\n number is appended to the file name, e. g.: score_1.mscx.\n -r <remap-pairs>, --remap <remap-pairs>, --remap-lyrics <remap-pairs>\n Remap lyrics. Example: \"--remap 3:2,5:3\". This example\n remaps lyrics verse 3 to verse 2 and verse 5 to 3. Use\n commas to specify multiple remap pairs. One remap pair is\n separated by a colon in this form: \"old:new\": \"old\" stands\n for the old verse number. \"new\" stands for the new verse\n number.\n -F, --fix, --fix-lyrics\n Fix lyrics: Convert trailing hyphens (\"la- la- la\") to a\n correct hyphenation (\"la - la - la\")\n\n rename:\n Rename the \u201c*.msc[zx]\u201d files. \n\n --rename <path-template>\n A path template string to set the destination location.\n -t <directory>, --target <directory>\n Target directory\n --only-filename Rename only the filename and don\u2019t move the score to a\n different directory.\n -A, --alphanum Use only alphanumeric characters.\n -a, --ascii Use only ASCII characters.\n -n, --no-whitespace Replace all whitespaces with dashes or sometimes underlines.\n -K <fields>, --skip-if-empty <fields>\n Skip the rename action if the fields specified in <fields>\n are empty. Multiple fields can be separated by commas, e.\n g.: composer,title\n --list-fields List all available fields that can be used in the path\n templates.\n --list-functions List all available functions that can be used in the path\n templates.\n\n selection:\n The following options affect how the manager selects the MuseScore files.\n\n -L, --list-files Only list files and do nothing else.\n -g <glob-pattern>, --glob <glob-pattern>\n Handle only files which matches against Unix style glob\n patterns (e. g. \"*.mscx\", \"* - *\"). If you omit this option,\n the standard glob pattern \"*.msc[xz]\" is used.\n --mscz Take only \"*.mscz\" files into account.\n --mscx Take only \"*.mscx\" files into account.\n\n style:\n Change the styles.\n\n -s <style-name> <value>, --style <style-name> <value>\n Set a single style value. For example: --style pageWidth 8.5\n --clean Clean and reset the formating of the \"*.mscx\" file\n -Y <file>, --style-file <file>\n Load a \"*.mss\" style file and include the contents of this\n file.\n --s3, --styles-v3 List all possible version 3 styles.\n --s4, --styles-v4 List all possible version 4 styles.\n --reset-small-staffs Reset all small staffs to normal size.\n\n font (style):\n Change the font faces of a score.\n\n --list-fonts List all font related styles.\n --text-font <font-face>\n Set nearly all fonts except \u201cromanNumeralFontFace\u201d,\n \u201cfiguredBassFontFace\u201d, \u201cdynamicsFontFace\u201c,\n \u201cmusicalSymbolFont\u201d and \u201cmusicalTextFont\u201d.\n --title-font <font-face>\n Set \u201ctitleFontFace\u201d and \u201csubTitleFontFace\u201d.\n --musical-symbol-font {Leland,Bravura,Emmentaler,Gonville,MuseJazz,Petaluma,Finale Maestro,Finale Broadway}\n Set \u201cmusicalSymbolFont\u201d, \u201cdynamicsFont\u201d and\n \u201cdynamicsFontFace\u201d.\n --musical-text-font {Leland Text,Bravura Text,Emmentaler Text,Gonville Text,MuseJazz Text,Petaluma Text,Finale Maestro Text,Finale Broadway Text}\n Set \u201cmusicalTextFont\u201d.\n\n page (style):\n Page settings.\n\n --staff-space <dimension>\n Set the staff space or spatium. This is the vertical\n distance between two lines of a music staff.\n --page-size <width> <height>\n Set the page size.\n --a4, --din-a4 Set the paper size to DIN A4 (210 by 297 mm).\n --letter Set the paper size to Letter (8.5 by 11 in).\n --margin <dimension> Set the top, right, bottom and left margins to the same\n value.\n\n header (style):\n Change the header.\n\n --show-header, --no-show-header\n Show or hide the header.\n --header-first-page, --no-header-first-page\n Show the header on the first page.\n --different-odd-even-header, --no-different-odd-even-header\n Use different header for odd and even pages.\n --header <left> <center> <right>\n Set the header for all pages.\n --header-odd-even <odd-left> <even-left> <odd-center> <even-center> <odd-right> <even-right>\n Set different headers for odd and even pages.\n\n footer (style):\n Change the footer.\n\n --show-footer, --no-show-footer\n Show or hide the footer.\n --footer-first-page, --no-footer-first-page\n Show the footer on the first page.\n --different-odd-even-footer, --no-different-odd-even-footer\n Use different footers for odd and even pages.\n --footer <left> <center> <right>\n Set the footer for all pages.\n --footer-odd-even <odd-left> <even-left> <odd-center> <even-center> <odd-right> <even-right>\n Set different footers for odd and even pages.\n\nConfiguration file\n==================\n\n``/etc/mscxyz.ini``\n\n.. code-block:: ini\n\n [general]\n executable = /usr/bin/mscore3\n colorize = True\n\n [rename]\n format = '$title ($composer)'\n\nOther MuseScore related projects\n================================\n\n* https://github.com/johentsch/ms3\n\nDevelopment\n===========\n\nTest\n----\n\n::\n\n make test\n\nPublish a new version\n---------------------\n\n::\n\n git tag 1.1.1\n git push --tags\n make publish\n\nPackage documentation\n---------------------\n\nThe package documentation is hosted on\n`readthedocs <http://mscxyz.readthedocs.io>`_.\n\nGenerate the package documentation:\n\n::\n\n make docs\n",
"bugtrack_url": null,
"license": "",
"summary": "A command line tool to manipulate the XML based *.mscX and *.mscZ files of the notation software MuseScore.",
"version": "3.0.0",
"project_urls": {
"Homepage": "https://mscxyz.readthedocs.io",
"Repository": "https://github.com/Josef-Friedrich/mscxyz"
},
"split_keywords": [
"audio"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c46aba0bd20451a309ae6af3c00c41dd2d918d036c506edbd25045907b6e3625",
"md5": "29f21395049c377985d440613215a010",
"sha256": "b22454c8f47d2788768d8389a75044f09defb7b8215b284255735a6af28d39b0"
},
"downloads": -1,
"filename": "mscxyz-3.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "29f21395049c377985d440613215a010",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9,<4.0",
"size": 62628,
"upload_time": "2024-02-12T18:43:51",
"upload_time_iso_8601": "2024-02-12T18:43:51.290954Z",
"url": "https://files.pythonhosted.org/packages/c4/6a/ba0bd20451a309ae6af3c00c41dd2d918d036c506edbd25045907b6e3625/mscxyz-3.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6f18e58059d4793b722807a93643966063ab7f8aa8fd91e9a15ed1787ac18c37",
"md5": "3d4ea8ff710ab26d82d79ad54b1aa4bc",
"sha256": "36c4a8e9be33acd63c124b141e60078e883b33e81865966bf8ca7f18a68f5b85"
},
"downloads": -1,
"filename": "mscxyz-3.0.0.tar.gz",
"has_sig": false,
"md5_digest": "3d4ea8ff710ab26d82d79ad54b1aa4bc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9,<4.0",
"size": 66231,
"upload_time": "2024-02-12T18:43:52",
"upload_time_iso_8601": "2024-02-12T18:43:52.736181Z",
"url": "https://files.pythonhosted.org/packages/6f/18/e58059d4793b722807a93643966063ab7f8aa8fd91e9a15ed1787ac18c37/mscxyz-3.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-12 18:43:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Josef-Friedrich",
"github_project": "mscxyz",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "mscxyz"
}
