Consolidation and normalization

Normalization changes how existing music is represented. Choose the operation by what you want to change; “shorter source” can mean several different things.

The source language for defining and reusing an exercise is in named exercises and shared passages. The operations below can discover that structure in existing written-out music. They do not require rewriting every part by hand.

Find the options in your installed engine

scorescript format --list
scorescript docs normalization

The normalization option reference is generated from the native engine's menu, including presets and unavailable entries. Use the names shown by your installed engine. If an older installed CLI lacks an option, update that CLI; a scorescript 0.3 file header alone does not establish which implementation features are installed.

Updated option names

Current builds use the shorter names below. Earlier names are refused with replacement guidance; they are not additional aliases. Update saved commands and application selections when updating the engine. This does not rename keywords inside your music or require rewriting your score files.

The measure-first choice is arrange=measures, formerly orientation=grid. maps=top|inline is unchanged and still covers musical context placement, not every map or every kind of layout break.

Automatic musical consolidation

scorescript check piece.scorescript
scorescript format piece.scorescript --normalize consolidate > piece.review.scorescript
scorescript check piece.review.scorescript

Review the new source and rendered parts before replacing the original. Never redirect output onto the input filename: the shell truncates it before the formatter can read it. --write is the explicit in-place alternative.

Consolidation recognizes identical part material, constant spelled transpositions, octave-related readings, and repeated ranges that can become named transposed returns. It can produce both fl5, ob4 { ... } and m17-32 = primary +P4: actual reuse, not merely fewer line breaks.

It re-analyzes the proposed music and abandons a rewrite if its musical comparison changes. This is not permission to discard a saved revision: printed layout and editorial text still need review.

When consolidation leaves music alone

• Fewer than two eligible parts: automatic discovery needs parts to share. It is not a general solo repetition finder. Manually authored named ranges still work for one reader.
• Already-shared source: the current pass leaves a score with reader heads alone, including mixed source with additional written-out parts.
• Measure-first source: first request arrange=parts.
• Exercise containers: first request exercises=top if a flat collection is appropriate. The current pass acts on the score's own parts, not nested movement programs. Preserve movement boundaries.
• Different musical material: a genuine variant stays written out; the pass does not approximate it to make it fit a shared line.
• Independent voices, implicit parts, unaddressable names, or unsafe repeated instrument selection can prevent a part from joining.
• Player-specific state and layout can require retaining a part block. hoist-breaks moves only matching per-part system/page maps to score scope; do not manually globalize one player's distinct page breaks.

Read the operation notes on standard error. A successful command can report that a requested transformation was refused and leave that structure unchanged. Do not treat exit status alone as proof that consolidation happened.

Comments attached to bodies that consolidation folds are removed. Comments in surviving bodies and at file level remain. This is separate from strip-comments, which explicitly removes all // comments. Keep important editorial commentary in a saved revision before folding its owning body.

Presets and deliberate combinations

scorescript format piece.scorescript --normalize preset=readable
scorescript format piece.scorescript --normalize preset=condensed
scorescript format piece.scorescript --normalize preset=max

readable aligns columns and puts maps at the top. condensed also requests compact spacing, numeric durations, and matching-break hoisting. max adds actual consolidation and removal of recognized development text. It is not just a whitespace setting, and it is not a promise that every score can be reduced to one body. The generated reference lists each exact expansion.

For an eligible written-out grid or exercise collection, an explicit request is:

scorescript format piece.scorescript --normalize arrange=parts,exercises=top,consolidate

Passes run in the engine's defined pipeline order, not as a left-to-right sequence of arbitrary rewrites. For repeated choices of the same option, the last written value wins, including across repeated --normalize flags. A preset expands where it appears, so preset=max,align=on restores alignment while keeping that preset's other selections. Do not select expand and consolidate together: they are opposing operations and the request is refused. Prefer one preset plus explicit overrides: a later preset does not cancel an earlier action that its own expansion does not mention.

Spaces around = are allowed inside a quoted selection, such as --normalize 'preset = condensed'. A preset requires a value: bare preset is an error. Switches use on or off; bare align and compact mean on. Argumentless actions such as strip-comments do not take =off or any other value. To leave comments alone, omit the action; strip-comments=off is refused.

Readability without changing musical ownership

scorescript format piece.scorescript --durations numbers
scorescript format piece.scorescript --durations letters
scorescript format piece.scorescript --compact
scorescript format piece.scorescript --normalize arrange=measures,maps=top
scorescript format piece.scorescript --normalize arrange=systems
scorescript format piece.scorescript --normalize arrange=rehearsals

Choose part-first source to follow one player's line, and measure-first source to compare players at the same bars. System and rehearsal orientations group around those landmarks. Orientation changes can be refused when the current structure cannot be safely represented; inspect the operation notes.

Use the native formatter for compaction. Newlines can separate measures or simultaneous voices; arbitrary whitespace removal can change or invalidate the music. Canonical compact source preserves the required boundaries.

Maps, exercises, and book sections

maps=top|inline controls meter, key, tempo, and transpose placement. It does not select inline versus mapped system/page cuts. The formatter chooses break-map emission separately; see page and system layout. It does not mean “convert every kind of map.” Written headings have labels=top|inline; exercises have exercises=top|inline; book sections have sections=top|inline.

scorescript format piece.scorescript --normalize exercises=inline,sections=inline
scorescript format piece.scorescript --normalize exercises=top,sections=top

At the inline door, each exercise owns its music and starts locally at m1. At the top/index door, the timeline is numbered continuously. Book sections need exercise containers before they can hold them inline; request both inline operations together. See collections for both forms.

Implemented reuse versus reserved menu entries

Named passage definitions and assignments are implemented. So is automatic consolidate, including its named returns inside shared heads. The separate named-spans normalization option is still marked coming: it is not the switch required to use existing named exercises. Likewise octaves=minimal|explicit is a reserved option, not an available setting. The formatter's current octave anchoring operates without that selector.

For key-signature and accidental-spelling normalization, inspect the native menu's key and chromatic options and check both the sounding and written results. These change notation choices, not just visual padding.

Expand before an independent rewrite

scorescript format piece.scorescript --normalize expand

This writes shared music out for its readers. Expansion preserves music, not the ongoing edit-once relationship: independently edited copies no longer follow a named source. Keep the shared original when that relationship matters. Use selective scorescript expand --part ... --bars ... for an individual player, with the whole-head override precautions in shared passages.