Named exercises, shared passages, and transposition

Define once; repeat and transpose

A named passage is reusable music, not a pasted copy or a formatting shortcut. Give its first range an identity, then assign that identity to later ranges. Editing the original notes changes every derived occurrence when the source is compiled again.

Notation for the preceding Named exercises, shared passages, and transposition example — ScoreScript sourceDownload source

Source	Meaning
`m1-3`	The original occupies measures 1 through 3, inclusive
`=primary`	Its reusable identity; later assignments refer to this name
`{ 1F4 \| E \| r }`	Whole F, whole E, then a full-bar rest in 4/4
`m4-6 = primary +P5`	Those three bars again, up a perfect fifth
`m7-9 = primary -P4`	The original again, down a perfect fourth
`fl5, tpt4`	Both instruments read the music, starting in their stated registers

This is the language's variable-like reuse form. It is not a standalone "Primary Exercises" = [...] declaration: the definition has a real place in the score, and its music belongs in braces. Square brackets have other musical meanings, including chords. wF4 is also accepted for a whole F; numeric durations are the default canonical spelling.

Use a spelled interval such as +P5, not an ambiguous +5. The number is an interval size, not a count of semitones: +P5 is seven semitones. +P4 is five semitones. Each assignment is relative to the named original, never to the preceding assignment. Use the passage's exact identity, not a quoted display title.

The definition and its references belong in the same shared-reader body. Keep source and target lengths equal and their measure ranges distinct. A plain m4-6 = primary repeats without transposition. An apostrophe or comma adjusts the derived register: = primary' raises an octave; = primary +P4, raises a fourth and then lowers an octave.

Repeat it by a half step, key signature and all

A bare interval moves the notes and nothing else: the bars come back transposed and the running key signature still stands over them, with every accidental written in. That is the default and it has not changed.

Add the word key and the signature travels too:

m3-4 = one +m2 key

Those bars are one a half step up and the key signature is a half step up — C becomes D-flat — and the running key comes back after them unless whatever follows states its own. Without key the same line prints the same notes under the old signature, spelled with accidentals.

A whole chromatic page is one line:

m3-16 = one +m2 x7 key

x7 is seven more statements, each a half step above the one before — so +m2 x7 ends a fifth above where it started, and each statement carries its own signature: D-flat, D, E-flat, E, F, G-flat, G. Descending is -m2 x7. The bar range must be the statements times the passage's length; seven statements of a two-bar passage are fourteen bars, and a range that is not fourteen is refused where it stands.

Written	Meaning
`m3-4 = one +m2`	those two bars again a half step up, notes only
`m3-4 = one +m2 key`	the same, and the signature moves with them
`m3-16 = one +m2 x7 key`	seven statements, each a half step above the last
`… key sharps` / `… key flats`	which side of the six-accidental tie the whole sequence takes (F-sharp or G-flat)
`… newline`	each statement opens a new system

Six sharps and six flats are the same sound, so a sequence that reaches one has to pick. key sharps and key flats decide it for the whole line, and the notes follow the side that is picked — G-flat major wants a diminished fifth where F-sharp major wants an augmented fourth, and only one of them agrees with the signature above it. Without the word, the engine's standing prefer sharps / prefer flats decides; without that, the fold lands on whichever side it arrived from.

A vocal warm-up page, whole — four exercises, each repeated chromatically from C up to G, each key on its own system, the vowels rotating per key:

The lyrics-map addresses bars, so it keeps working over a sequence exactly as it does over hand-written repeats: the syllables at m3 sing the first repeat, those at m5 the second, and a bar the map does not speak for keeps the words written under the passage itself.

A hand-written key map and a repeat that carries its key must not both speak for one bar with different answers — that is span.key-conflict, and neither one wins in silence. Where they agree, the map is simply redundant and can be deleted.

Named reuse does not currently create printed exercise headings or book collection entries automatically. An optional quoted title after the name is accepted by the parser, but is currently dropped by formatting and does not print an exercise heading. Do not rely on that title form. Use explicit collection metadata for displayed titles, variant ranges, numbering, book membership, and cross-file exercise identity. These shared-line and collection features are implemented but provisional.

The shared head works in both arrangements. These name one authored passage read by both flute and oboe:

The part-first equivalent is fl,ob { m1-2 { ... } }. You can follow that shared passage with individual parts in a measure-first block. Formatting keeps both passages; choosing a different arrangement later does not delete earlier shared music:

Repeated durations can be omitted within a row: eG eG F becomes eG G F when using letter-duration formatting. Both G notes remain. Each independent row begins with its own default quarter duration; it does not silently borrow another instrument's rhythm. A short row or partly filled measure rests for its remainder. Keep braces balanced, and use m3-4 when a continuation belongs at those bars. Normalization offers explicit consolidation of repeated music as well as removal of redundant notation.

Declare the instruments, then name several readers in one head. A register digit says where the first note lands. A signed interval changes the reading in concert pitch. These shared-line forms are provisional.

The flute receives the line beginning in octave 5 and the oboe in octave 4. A head such as fl5, ob4 +P5 gives the oboe a fifth-up reading as well. A repeated instrument key binds occurrences in source order; a key named once can select all instances of that instrument. Too many readers are an error, not extra implicitly created instruments.

The band warm-up pattern

There are two independent savings: several instruments share one musical body, and later exercises reuse a named range of that body. Neither reduces the number of measures the musicians receive.

For example, a 16-bar primary exercise can supply a 48-bar sequence:

m1-16=primary { ...sixteen bars of music... }
m17-32 = primary +P4
m33-48 = primary -P5

This is a structural excerpt, not runnable music: replace the placeholder with the actual sixteen bars. A smaller complete example follows.

Each interval is relative to the named original. The second derivation does not chain through the first. +P4 raises a perfect fourth; -P5 lowers a perfect fifth. The source and target lengths must agree. Apostrophe and comma can adjust the derived register, as in = theme +P4,.

The old expand keyword is retired. Use the range assignment form above. Shared source reuse prints the derived music; it is different from a notated repeat sign that instructs a performer to return.

Only the old source keyword is retired. The CLI's scorescript expand command and the normalization pass expand are available editing operations. See normalization for automatically finding shared parts and named returns in already-written music with --normalize consolidate.

Instrument sections and individual changes

The roster parts { fl: 2, ob, tpt: 2 } declares five players. In a shared head, fl5, ob4, tpt4 addresses both flutes, the oboe, and both trumpets. To give the flutes different readings, write fl5, fl4, ob4, tpt4 instead: the repeated fl entries bind the first and second flute in roster order. The digit is an octave anchor, not a player number.

An instrument section shares music through its readers; a book section groups exercises. They are different concepts, not interchangeable block heads.

An explicit individual part block overrides its shared reading. That override replaces the covered head's reading, not just one edited cell. To change one player safely, expand its shared passage first and retain all required bars in the resulting part. The selective CLI operation is:

scorescript expand piece.scorescript --part "Flute 1" --bars 1-16

It prints the proposed source without replacing the file. It can materialize more than the requested bars to preserve the whole shared head. Read its diagnostics and the diff; targeting later repeated instances can be refused when they cannot be addressed independently. For a fully written-out editing view, use scorescript format piece.scorescript --normalize expand.

Concert and written pitch

Keep three meanings separate:

Meaning	Notes and keys shown	Does it rewrite source?
Authored	Exactly what the source says, possibly mixed concert/written regions	No
Concert Pitch	Every selected region at sounding pitch	No
Transposed (written)	The notes the selected instrument's player reads	No

Catalog instruments carry their transpositions. By default, author score source in concert pitch and choose written output for the player's page. Do not add a source transpose interval merely because an instrument is transposing: it means the notes are already written, not “transpose this concert passage for printing.”

In the chat viewer, output defaults to Transposed (written). Choose Concert Pitch in its Output pitch control to change the engraved view. This uses the native engine and leaves Code unchanged; the Code view reports the selected music's source basis separately. Without host tool-call support, the control is read-only: ask for a new render in the desired mode.

Other applications and older APIs may use different defaults. In particular, an older API's transposed: false can mean authored, not true concert. Do not relabel mixed or already-written source as concert without an explicit concert conversion. Source organization, output selection, and pitch basis are separate choices; see output views.

A part-scoped transpose region can mark source already written for the player. Its two values are diatonic and chromatic displacement, not a pair of octave values. The explicit no-transposition value is 0.

All three notes sound C5. Measure 1 is concert C5; measure 2 is written D5 for B-flat clarinet; measure 3 returns to concert C5. The written view shows D5 in all three bars; the concert view shows C5 in all three. Keys follow the same pitch conversion. The 0 reset returns source interpretation to concert; it does not turn off the instrument's written-output transposition.

A transposition map belongs to the player, while meter/key/tempo maps normally belong to the whole score. Each interval's values are written-to-sounding: for B-flat clarinet, -1 -2 means one diatonic step and two semitones down. An optional third value adds octaves; bass clarinet uses -1 -2 -1. Unknown instruments require an explicit source interval when authored in written pitch; the engine does not guess their transposition from a name.

Changing a display view is not a source-normalization operation. A source conversion must rewrite notes, keys, and the transposition map together while preserving sounding music. Moving the existing map with maps=top or maps=inline alone does not perform that conversion. Do not manually flip a map and leave its notes and keys untouched.