Submodule `meta`

Class for metadata maniplation

exception mscxyz.meta.UnmatchedFormatStringError(format_string: str, input_string: str)[source]: Bases: Exception

exception mscxyz.meta.FormatStringNoFieldError(format_string: str)[source]: Bases: Exception

class mscxyz.meta.Metatag(score: Score)[source]

Bases: object

The class provides access to the MuseScore metadata fields.

The class should not be renamed to MetaTag because it would conflict with the naming scheme of the fields metatag_title etc.

See:: MuseScore Handbook

The available metaTag fields are:

arranger
audioComUrl (new in v4)
composer
copyright
creationDate
lyricist
movementNumber
movementTitle
mscVersion
platform
poet (not in v4)
source
sourceRevisionId
subtitle
translator
workNumber
workTitle

Project properties dialog (4.7.3):

Work title
Subtitle
Composer
Arranger
Lyricist
Translator
Copyright
Work number
Movement title
Movement number
Creation date
Platfrom
Source
Audio.com URL

version 4

<museScore version="4.20">
    <Score>
        <metaTag name="arranger"></metaTag>
        <metaTag name="audioComUrl"></metaTag>
        <metaTag name="composer">Composer / arranger</metaTag>
        <metaTag name="copyright"></metaTag>
        <metaTag name="creationDate">2024-01-05</metaTag>
        <metaTag name="lyricist"></metaTag>
        <metaTag name="movementNumber"></metaTag>
        <metaTag name="movementTitle"></metaTag>
        <metaTag name="platform">Linux</metaTag>
        <metaTag name="source"></metaTag>
        <metaTag name="sourceRevisionId"></metaTag>
        <metaTag name="subtitle">Subtitle</metaTag>
        <metaTag name="translator"></metaTag>
        <metaTag name="workNumber"></metaTag>
        <metaTag name="workTitle">Untitled score</metaTag>

4.7.3: New Score:

<museScore version="4.70">
    <Score>
        <metaTag name="arranger"></metaTag>
        <metaTag name="composer">Composer / arran
        <metaTag name="arranger"></metaTag>
        <metaTag name="composer">Composer / arranger</metaTag>
        <metaTag name="copyright"></metaTag>
        <metaTag name="creationDate">2026-06-14</metaTag>
        <metaTag name="lyricist"></metaTag>
        <metaTag name="movementNumber"></metaTag>
        <metaTag name="movementTitle"></metaTag>
        <metaTag name="platform">Linux</metaTag>
        <metaTag name="source"></metaTag>
        <metaTag name="translator"></metaTag>
        <metaTag name="workNumber"></metaTag>
        <metaTag name="workTitle">Untitled score</metaTag>

fields

score: Score

xml_root: _Element

property arranger: str | None

<metaTag name="arranger">...</metaTag>

property audio_com_url: str | None

<metaTag name="audioComUrl">...</metaTag>

property composer: str | None

Same text as “Composer” on the first page of the score

<metaTag name="composer">...</metaTag>

property copyright: str | None

Same text as “Copyright” on the first page of the score.

<metaTag name="copyright">...</metaTag>

property creation_date: str | None

https://github.com/musescore/MuseScore/blob/06793ff5ff3065fe87fe9a8a651a6d20f49fd28c/src/engraving/dom/masterscore.cpp#L93

<metaTag name="creationDate">2024-01-05</metaTag>

property lyricist: str | None

Same text as “Lyricist” on the first page of the score.

<metaTag name="lyricist">...</metaTag>

property movement_number: str | None

<metaTag name="movementNumber">...</metaTag>

property movement_title: str | None

<metaTag name="movementTitle">...</metaTag>

property msc_version: str | None

<metaTag name="mscVersion">4.20</metaTag>

property platform: str | None

The computing platform the score was created on. This might be empty if the score was saved in test mode.

https://github.com/musescore/MuseScore/blob/06793ff5ff3065fe87fe9a8a651a6d20f49fd28c/src/engraving/dom/masterscore.cpp#L74-L81

<metaTag name="platform">Linux</metaTag>
<metaTag name="platform">Apple Macintosh</metaTag>

property poet: str | None

<metaTag name="poet">...</metaTag>

property source: str | None

May contain a URL if the score was downloaded from or Publish to MuseScore.com.

<metaTag name="source">http://musescore.com/isaacweiss/getting-started</metaTag>
<metaTag name="source">http://musescore.com/score/111410</metaTag>

property source_revision_id: str | None

<metaTag name="sourceRevisionId">...</metaTag>

property subtitle: str | None

The subtitle. It has the same text as “Subtitle” on the first page of the score.

<metaTag name="subtitle">Subtitle</metaTag>

property translator: str | None

<metaTag name="translator">...</metaTag>

property work_number: str | None

<metaTag name="workNumber">...</metaTag>

property work_title: str | None

The Work Title. It has the same text as “Title” on the first page of the score.

<metaTag name="workTitle">Untitled score</metaTag>

clean() → None[source]

class mscxyz.meta.VboxText(style: str, parent_vbox: _Element, container: _Element | None)[source]

Bases: object

Manage one <Text> entry inside a <VBox> element.

<Text>
    <eid>hibWj5obkBO_6AUar0D+y6K</eid>
    <style>title</style>
    <text>Untitled score</text>
</Text>

Text style overrides:

Global overrides:

<Text>
    <eid>MX+29xsCL0G_gQ+qjPGU4EO</eid>
    <style>title</style>
    <family>FreeSans</family>
    <bold>1</bold>
    <italic>1</italic>
    <text><b><i><font face="FreeSans"/>Untitled score</i></b></text>
</Text>

Inline overrides:

<Text>
    <eid>0iZtR+qEd6C_jIRPV50caLG</eid>
    <style>composer</style>
    <text><i>Composer</i> / <b>arranger</b></text>
</Text>

param style:: The style name used in the <style>...</style> element.
param parent_vbox:: The parent <VBox> element where <Text> lives.
param container:: The existing <Text> element or None.

exists() → bool[source]

Checks whether the <Text>...</Text> element with the given style name exists.

Returns:: True if the </Text> element with the given style name, otherwise False.

reset_style() → None[source]

Reset the text style overrides.

This method removes style override tags from the <Text> container and keeps only <eid>, <style>, and <text> tags.

Before:

<Text>
    <eid>MX+29xsCL0G_gQ+qjPGU4EO</eid>
    <style>title</style>
    <family>FreeSans</family>
    <bold>1</bold>
    <italic>1</italic>
    <text><b><i><font face="FreeSans"/>Untitled score</i></b></text>
</Text>

After:

<Text>
    <eid>MX+29xsCL0G_gQ+qjPGU4EO</eid>
    <style>title</style>
    <text>Untitled score</text>
</Text>

remove() → None[source]: Remove the container element <Text>...</Text> from the parent <Vbox>...</Vbox> element.

property style: str

The name of the style.

In the XML markup <style>title</style>, for example, the style name is title.

property text: str | None

The plain text content.

Setting text to None removes the entire <Text> container.

class mscxyz.meta.Vbox(score: Score)[source]

Bases: object

The first vertical box or frame of a score.

Available fields:

title: Title
subtitle: Subtitle
composer: Composer
lyricist (poet): Lyricist
instrument_excerpt: Part name

Version 2, 3

<Staff id="1">
    <VBox>
        <height>10</height>
        <Text>
            <style>Title</style>
            <text>Title</text>
        </Text>
        <Text>
            <style>Composer</style>
            <text>Composer</text>
        </Text>
    </VBox>
</Staff>

Version 4

<Staff id="1">
    <VBox>
        <height>10</height>
        <boxAutoSize>0</boxAutoSize>
        <eid>4294967418</eid>
        <Text>
            <eid>8589934598</eid>
            <style>title</style>
            <text>Title</text>
        </Text>
        <Text>
            <eid>12884901894</eid>
            <style>composer</style>
            <text>Composer</text>
        </Text>
    </VBox>
</Staff>

Version 4.6.5 (lyricist is now poet)

<Staff id="1">
    <VBox>
        <height>10</height>
        <eid>3yH8HKTgwb_p8uM4j9efcE</eid>
        <Text>
            <eid>hibWj5obkBO_6AUar0D+y6K</eid>
            <style>title</style>
            <text>Untitled score</text>
        </Text>
        <Text>
            <eid>mDB0b0Sa0SM_73LrivvAWEC</eid>
            <style>subtitle</style>
            <text>Subtitle</text>
        </Text>
        <Text>
            <eid>13Y3EfRgceC_QRif2MiL9ZM</eid>
            <style>composer</style>
            <text>Composer / arranger</text>
        </Text>
        <Text>
            <eid>5bIbUnhSBCP_qqv84cvOnMO</eid>
            <style>poet</style>
            <text>Lyricist</text>
        </Text>
    </VBox>
</Staff>

fields

set_text(style_name: str, text: str) → VboxText[source]

Add a <Text> element to the first VBox of a score, or set it if it already exists.

If a <Text> element already exists, its content is updated; otherwise, the <Text> element is created.

Parameters:: style_name – The style name used in the <style>...</style> element.
Returns:: A VBoxText wrapper instance that provides further, more fine-grained access to the text element.

get_text(style_name: str) → str | None[source]

Retrieve the text content of a <Text> element by its style name.

Parameters:: style_name – The style name used in the <style>...</style> element.
Returns:: The text content of the <Text> element

rename_style(old: str, new: str) → VboxText[source]

Rename the style name of a <Text> element.

Parameters:

old – The old style name used in the <style>...</style> element.
new – The new style name used in the <style>...</style> element.

Returns:

A VBoxText wrapper instance that provides further, more fine-grained access to the text element.

remove_text(style_name: str) → VboxText[source]

Remove a <Text> element from the first VBox in a score by its style name.

Parameters:: style_name – The style name used in the <style>...</style> element.
Returns:: A VBoxText wrapper instance that provides further, more fine-grained access to the text element.

reset_text_style(style_name: str) → VboxText[source]

Parameters:: style_name – The style name used in the <style>...</style> element.
Returns:: A VBoxText wrapper instance that provides further, more fine-grained access to the text element.

property title_element: VboxText

The title element of the first vertical box or frame of a score.

<Staff id="1">
    <VBox>
        <height>10</height>
        <boxAutoSize>0</boxAutoSize>
        <eid>3yH8HKTgwb_p8uM4j9efcE</eid>
        <Text>
            <eid>9EZXpseYfo_z5oSRZ7xoaL</eid>
            <style>title</style>
            <text>Mondscheinsonate</text>
        </Text>
    </VBox>
</Staff>

property title: str | None

The title text field of the first vertical box or frame of a score.

<Staff id="1">
    <VBox>
        <height>10</height>
        <boxAutoSize>0</boxAutoSize>
        <eid>3yH8HKTgwb_p8uM4j9efcE</eid>
        <Text>
            <eid>9EZXpseYfo_z5oSRZ7xoaL</eid>
            <style>title</style>
            <text>Mondscheinsonate</text>
        </Text>
    </VBox>
</Staff>

property subtitle_element: VboxText

The subtitle element of the first vertical box or frame of a score.

<Staff id="1">
    <VBox>
        <height>10</height>
        <boxAutoSize>0</boxAutoSize>
        <eid>3yH8HKTgwb_p8uM4j9efcE</eid>
        <Text>
            <eid>W2TmIWNulw_3xwF7Hs22D</eid>
            <style>subtitle</style>
            <text>1. Satz</text>
        </Text>
    </VBox>
</Staff>

property subtitle: str | None

The subtitle plain text content of the first vertical box or frame of a score.

Setting this field to None will delete the corresponding XML element from the score.

If this field is None, the corresponding XML element does not exist.

property composer_element: VboxText

The composer element of the first vertical box or frame of a score.

<Staff id="1">
    <VBox>
        <height>10</height>
        <boxAutoSize>0</boxAutoSize>
        <eid>3yH8HKTgwb_p8uM4j9efcE</eid>
        <Text>
            <eid>TzY/P+VBDFG_lyazF6x468M</eid>
            <style>composer</style>
            <text>Ludwig van Beethoven</text>
        </Text>
    </VBox>
</Staff>

property composer: str | None

The composer plain text content of the first vertical box or frame of a score.

Setting this field to None will delete the corresponding XML element from the score.

If this field is None, the corresponding XML element does not exist.

property lyricist_element: VboxText

The lyricist element of the first vertical box or frame of a score.

<Staff id="1">
    <VBox>
        <height>10</height>
        <boxAutoSize>0</boxAutoSize>
        <eid>3yH8HKTgwb_p8uM4j9efcE</eid>
        <Text>
            <eid>iklYO/iK0CE_kALp5O5iuVN</eid>
            <style>poet</style>
            <text>Johann Wolfgang von Goethe</text>
        </Text>
    </VBox>
</Staff>

migrate_lyricist() → None[source]: Migrate the lyricist text element by renaming the style from lyricist to poet.

property lyricist: str | None

The lyricist plain text content of the first vertical box or frame of a score.

Setting this field to None will delete the corresponding XML element from the score.

If this field is None, the corresponding XML element does not exist.

property instrument_excerpt_element: VboxText

property instrument_excerpt: str | None

The instrument excerpt text field of the first vertical box or frame of a score.

<Staff id="1">
    <VBox>
        <height>10</height>
        <boxAutoSize>0</boxAutoSize>
        <eid>4294967418</eid>
        <Text>
            <eid>fx/RTjxo4CE_M0P0jIU0j3L</eid>
            <style>instrument_excerpt</style>
            <text>Instrument Name</text>
        </Text>
    </VBox>
</Staff>

clean() → None[source]: Remove the text elements title subtitle, composer, lyricist and instrument_excerpt from the vbox.

reset_style() → None[source]: Reset the text style overrides of the elements title subtitle, composer, lyricist and instrument_excerpt from the vbox.

class mscxyz.meta.Meta(score: Score)[source]

Bases: object

High-level interface for score metadata.

This class combines metadata stored in MuseScore metaTag elements (Metatag) and text objects in the first vertical frame (Vbox) and exposes them through a unified API.

MuseScore version 4.7.2 metatag_lyricist == vbox_poet

score: Score

metatag: Metatag

vbox: Vbox

sync_fields() → None[source]

Re-assign key fields to trigger internal synchronization.

This forces current values to be written back through property setters, ensuring metaTag and VBox representations are aligned.

write_to_log_file(log_file: str, format_string: str) → None[source]

Write formatted exported score fields to a log file.

Parameters:

log_file – Path of the output log file.
format_string – Template string parsed with exported fields.

clean() → None[source]: Clean all metadata fields of the object.

delete_duplicates() → None[source]

Delete duplicates in the metadata.

This method checks if the lyricist and composer are the same, and if so, it sets lyricist to an empty string.

It also checks if title is empty but subtitle is not, and if so, it sets title to subtitle.

Finally, it checks if subtitle is the same as title, and if so, it sets subtitle to an empty string.

reload(save: bool = False) → Meta[source]

Reload the MuseScore file.

Parameters:: save – Whether to save the changes before reloading. Default is False.
Returns:: The reloaded Meta object.
See:: mscxyz.Score.reload()

property title: str | None

Get and set the value of Vbox.title and Metatag.work_title all at once.

If the attributes have different values, then the attribute Vbox.title is preferred.

property subtitle: str | None

Get and set the value of Vbox.subtitle, Metatag.subtitle and Metatag.movement_title all at once.

If the attributes have different values, then the attribute Vbox.subtitle is preferred.

property composer: str | None

Get and set the value of Vbox.composer and Metatag.composer all at once.

If the attributes have different values, then the attribute Vbox.composer is preferred.

property lyricist: str | None

Get and set the value of Vbox.lyricist and Metatag.lyricist all at once.

If the attributes have different values, then the attribute Vbox.lyricist is preferred.

Submodule meta

Text style overrides:

Global overrides:

Inline overrides:

Submodule `meta`