Working with style files

Summary

• Create or modify a style file
• Remove default values
• Restore intrinsic values
• Create a group of related styles
• Compare styles
• Helper functions

Create or modify a style file

1. Open a score in the latest version of MuseScore Studio.
2. If modifying an existing style, load it now with Format > Load style.
3. Make desired changes in Format > Style and Format > Page settings.
4. Go to Format > Save style.
5. Give the file a name (e.g. MyStyleFull.mss).

The style file will include default values as well as your changes.

Remove default values

It's often desirable to exclude default values from the style, so only the changed values remain. This has several advantages:

• The style can be loaded in scores without overwriting values unnecessarily, which matters if:
  • The score already had a carefully tailored style that you want to preserve where possible.
  • MuseScore Studio's default values change in a future version, and you want to benefit from the new default values.
• When examining the style file in a text editor, you'll only see the important parameters.

For example, if you have a style file called Big_Notes.mss, you might want it to contain only parameters relating to note size, and leave all other style parameters unspecified.

To remove all default values from the file you created before:

1. Create a new, empty score in the same version of MuseScore Studio as you used before.
2. Don't change any styles or settings. Instead, go straight to Format > Save style.
3. Give the file a name (e.g. DefaultStyle.mss).
4. Copy the helper functions at the bottom of this page and paste them into a Bash terminal.
5. Run this command in the same terminal:

style_changes DefaultStyle.mss MyStyleFull.mss >MyStyleChanges.mss

Restore intrinsic values

You might want to specify certain values even if they do happen to match MuseScore Studio's current default value. You should do this for all values that you consider intrinsic to your style. This ensures the specified value will be used even if the style is loaded in a score that uses a non-default value for the parameter, or if MuseScore Studio's default value changes in a future version.

To see which values were removed in the previous section:

git diff --no-index MyStyleFull.mss MyStyleChanges.mss

Use a text editor to restore the default values that you want to keep in MyStyleChanges.mss, if any. Make sure you put restored lines in the correct place relative to other lines, otherwise the diff will become harder to read. (If the diff shows lines added, it means you put them in the wrong place.)

Tip: If you're struggling to find a particular parameter in the MSS, modify MyStyleFull.mss again in MuseScore Studio and set the parameter to a non-default value. Look for it with this command:

git diff --no-index DefaultStyle.mss MyStyleFull.mss

Once you know what it's called, you can manually change it to the correct (default) value again in MyStyleFull.mss and MyStyleChanges.mss.

Create a group of related styles

If you're creating a group of related styles, it may be desirable to ensure that all styles in the group specify the same parameters, even if the values used for those parameters are different in each style. This ensures users can switch between the styles without leaving any values in place from the previous style.

For example, let's say you have three styles, Big_Notes.mss, Bigger_Notes.mss, and Biggest_Notes.mss. You want users to be able to experiment with all three styles and then pick the one they like best. If certain parameters are specified in Biggest_Notes.mss but not in the other files, the final appearance of the user's score would depend on the order in which the styles were applied.

To prevent this, you can compare the styles to each other using the techniques below, or simply paste the helper functions into a Bash terminal and run this command:

tags Big*_Notes.mss | sort | uniq -c    # count occurrences of each parameter across all files

If any parameter appears fewer times than the number of files in the group (in this case 3) then you know it's missing from at least one of the files.

For each missing parameter, use this command to find out which files do contain the parameter:

grep nameOfParameter Big*_Notes.mss

You'll either need to remove the parameter from the files that have it, or add it to the ones that don't.

If adding, you'll need to choose a suitable value for the parameter, which may or may not match the value used in other files, or use the default value from DefaultStyle.mss. Make sure you add the parameter in the right place relative to other parameters, otherwise the diff will become harder to read.

Compare styles

Let's say you have a group of styles (e.g. Big_Notes.mss, Bigger_Notes.mss, and Biggest_Notes.mss) and you want to compare them to each other.

git diff --no-index Big_Notes.mss Bigger_Notes.mss
git diff --no-index Big_Notes.mss Biggest_Notes.mss
git diff --no-index Bigger_Notes.mss Biggest_Notes.mss

If these were created according to the steps for related styles above then the style parameters should be the same in each file; only the values may differ between related styles.

If lots of values are different it can be distracting in the diff. To mitigate this, paste the helper functions into a Bash terminal, then use these commands to compare the parameters in each file without their values:

# Use 'diff' because 'git diff' can't read from file descriptors used in process substitution.
diff -u --color=auto <(tags Big_Notes.mss) <(tags Bigger_Notes.mss)
diff -u --color=auto <(tags Big_Notes.mss) <(tags Biggest_Notes.mss)
diff -u --color=auto <(tags Bigger_Notes.mss) <(tags Biggest_Notes.mss)

You can also compare one file to all the other files at the same time. This is handy if there are many files in the group.

unify Bigg{er,est}_Notes.mss | git diff --no-index - Big_Notes.mss         # compare with values
diff -u --color=auto <(unify Bigg{er,est}_Notes.mss) Big_Notes.mss         # compare with values
diff -u --color=auto <(unify_tags Bigg{er,est}_Notes.mss) <(tags Big.mss)  # compare without values

Here's how to interpret the diff produced by these commands:

• + added: These lines appear in Big_Notes.mss but not in any of the other files.
• - removed: Appear in at least one of the other files, but not in Big_Notes.mss.
• unchanged: Appear in Big_Notes.mss and at least one of the other files.

Helper functions

Paste these function definitions into a Bash terminal, then use them as directed above.

# Show style_file_2, omitting values that are also present in style_file_1.
function style_changes()
{
    local style_file_1="$1" style_file_2="$2"
    head -n3 "${style_file_2}"
    diff "${style_file_1}" "${style_file_2}" | sed -En 's|^>  | |p'
    tail -n2 "${style_file_2}"
}

# Show XML tags without values.
function tags()
{
    sed -En 's|^ *<([^ ?/>]+).*$|\1|p' "$@"
}

# Combine similar files, preserving the order of lines in each file.
function unify()
(  # subshell
    set +e
    if (($# < 2)); then
        echo >&2 "${FUNCNAME}: Must provide 2 or more arguments (files or '-' for standard input)."
        return 1
    elif (($# == 2)); then
        diff --line-format=%L "$1" "$2"
    else
        local file="$1"
        shift
        "${FUNCNAME}" "$@" | diff --line-format=%L - "${file}"
    fi
    (($? == 0 || $? == 1)) # 'diff' returns 1 when files differ, >1 when errors
)

# Show XML tags from similar files, preserving the order of tags in each file.
function unify_tags()
(  # subshell
    set +e
    if (($# < 2)); then
        echo >&2 "${FUNCNAME}: Must provide 2 or more arguments (files or '-' for standard input)."
        return 1
    elif (($# == 2)); then
        diff --line-format=%L <(tags "$1") <(tags "$2")
    else
        local file="$1"
        shift
        "${FUNCNAME}" "$@" | diff --line-format=%L - <(tags "${file}")
    fi
    (($? == 0 || $? == 1)) # 'diff' returns 1 when files differ, >1 when errors
)