Parts, voices, and measures

Parts first

Declare instruments with parts, then write each part's music in its body. A measure range labels a run of bars. Separate bars with |.

scorescript 0.3
score "Duet" {
  meter 4/4

  parts {
    fl
    ob
  }

  fl {
    m1-2 {
      4C5 D E F | 1G
    }
  }

  ob {
    m1-2 {
      2C4 E | 1G
    }
  }
}

Generated notation

Canonical spelling

scorescript 0.3
score "Duet" {
  meter 4/4

  parts {
    fl
    ob
  }

  fl {
    m1-2 {
      4C5 D E F | 1G
    }
  }

  ob {
    m1-2 {
      2C4 E | 1G
    }
  }
}

A part is addressed by its roster key and nothing else. fl { ... }, clarinet-bb { ... }, trombone { ... } — the key the roster wrote, in every arrangement and in every group label. The printed name lives in the roster and is never an address; where a key is declared more than once, the bodies bind to the players in declaration order, so two flutes need no second spelling. A cue-only, instruction-only, or empty body still claims its place in that order. An extra repeated body is an error; an explicit player number must exist on the roster. See the instrument reference for catalog keys.

The roster says who is on each part. Players stand after the key; a comma lists the players on ONE part and a + starts the next part.

scorescript 0.3
score "Band" {
  parts {
    fl 2
    clarinet-bb 1,2
    horn-f 1,2 + 3,4
    tuba
    oboe: "Oboe 1 & 2"
  }

  fl {
    m1 {
      1C5
    }
  }

  fl {
    m1 {
      1A4
    }
  }

  clarinet-bb {
    m1 {
      1G4
    }
  }

  horn-f {
    m1 {
      1C4
    }
  }

  horn-f {
    m1 {
      1E4
    }
  }

  tuba {
    m1 {
      1C2
    }
  }

  oboe {
    m1 {
      1E5
    }
  }
}

Generated notation

Canonical spelling

scorescript 0.3
score "Band" {
  parts {
    fl 2
    clarinet-bb 1,2
    horn-f 1,2 + 3,4
    tuba
    oboe: "Oboe 1 & 2"
  }

  fl {
    m1 {
      1C5
    }
  }

  fl {
    m1 {
      1A4
    }
  }

  clarinet-bb {
    m1 {
      1G4
    }
  }

  horn-f {
    m1 {
      1C4
    }
  }

  horn-f {
    m1 {
      1E4
    }
  }

  tuba {
    m1 {
      1C2
    }
  }

  oboe {
    m1 {
      1E5
    }
  }
}

fl 2 is two parts of one player each — Flute 1 and Flute 2. clarinet-bb 1,2 is ONE part read by two players — Clarinet in Bb 1, 2. horn-f 1,2 + 3,4 is two parts of two players each. tuba is one unnumbered player. A bare count N is the shorthand for 1 + 2 + … + N. The printed name derives from the catalog instrument and the player list; the quoted string after a colon overrides it and is a label, never an address. Counts must be positive whole numbers representable by the engine: fl 0 is an error, not a way to omit a player. Remove the roster entry to omit it.

Inside a part, v1 is the first player of the list and v2 the second.

How many people read a part is what makes a chord in it a DIVISION rather than a chord — see the desk's own page below.

Piano staves and voices

pn, pno, and piano name the piano. One piano normally has two staves; its upper staff starts in treble clef and its lower staff starts in bass clef. Use t or treble and b or bass to address those staves:

meter 4/8

parts {
  pn
}

pn treble {
  m1-2 {
    8C5 D E F | 2G
  }
}

pn bass {
  m1-2 {
    4C3 G' | 2C,
  }
}

Generated notation

Canonical spelling

meter 4/8

parts {
  pn
}

pn treble {
  m1-2 {
    8C5 D E F | 2G
  }
}

pn bass {
  m1-2 {
    4C3 G' | 2C,
  }
}

These are stable staff addresses. A clef change inside pn b does not turn it into the upper staff. st3 addresses a third staff when the instrument has one. Voices belong to a staff; v2 means its second voice, not its bass staff. Use labeled voice collections within a measure:

meter 4/8

parts {
  pn
}

pn treble {
  m1 {
    v1 [ 4C5 D ]
    v2 [ 2G4 ]
  }
}

pn bass {
  m1 {
    2C3
  }
}

Generated notation

Canonical spelling

meter 4/8

parts {
  pn
}

pn treble {
  m1 {
    v1 [ 4C5 D ]
    v2 [ 2G4 ]
  }
}

pn bass {
  m1 {
    2C3
  }
}

An unwritten partner staff still has measures on the score timeline. You do not need a row of r(hidden) placeholders to establish it. Empty written measure collections use m1 { }; a musical body never uses m1:.

For an explicit layout, [staves N] or [sts N] sets the staff count. parts { pn 2 [staves 2] } declares two pianos, each with two staves. pn 2 b { m1 { hC3 } } then addresses the second piano's lower staff. A piano on a single staff uses parts { pn [staves 1] }.

An instrument's own key

A short key names the usual instrument: tpt is the B-flat trumpet, cl the B-flat clarinet, hn the horn in F. Say the tuning the way a part is named aloud to choose another one the catalog builds:

scorescript 0.3
score "Tunings" {
  meter 4/4

  parts {
    tpt in C
    cl-a
  }

  tpt {
    m1 {
      1C5
    }
  }

  cl-a {
    m1 {
      1E4
    }
  }
}

Generated notation

Canonical spelling

scorescript 0.3
score "Tunings" {
  meter 4/4

  parts {
    tpt in C
    cl-a
  }

  tpt {
    m1 {
      1C5
    }
  }

  cl-a {
    m1 {
      1E4
    }
  }
}

tpt in C is the C trumpet, cl-a the A clarinet; the hyphenated key (tpt-c, cl-a, trumpet-c) and the spoken in form mean the same, and the formatter writes back whichever you said. A tuning the catalog does not build (hn in Eb today) is an unknown instrument, not a guess. The body is addressed by the key as written on the roster line, and the printed name follows the instrument ("C Trumpet"). The tuning is the instrument's transposition; transpose inside a part is a different statement (it says the notes are already written pitch), and key is the signature.

What a transposing player reads for each concert key is arithmetic on the circle of fifths, and the engine holds the whole table (docs/WRITTEN-KEYS.md, generated from the catalog). A derived signature is folded to six accidentals or fewer — six sharps and six flats are what players read, and seven is redundant — so concert B for a B-flat instrument reads D-flat, never C-sharp. At exactly six the two spellings tie: a major key keeps the side the arithmetic gives (concert E for a B-flat instrument reads F-sharp major, as arrangers write it) and a minor key takes the flats (E-flat minor, the key winds read; D-sharp minor is the rare one). prefer sharps or prefer flats — in the score head for every part, in a part, at at m9 { … }, or inline — decides the tie your way; an authored key is never touched. The common columns:

The octave is a separate fact: the alto and baritone saxophones read the same key a page apart, and every range check and every fit uses the whole interval, octave included. A non-transposing instrument reads the concert key as the author wrote it, seven accidentals included.

A body addressed to one player

A body may address ONE PLAYER of a multi-player part, and what it writes is that player's alone: they play those bars while the rest of the desk rests. The head is the roster key and the player's number.

scorescript 0.3
score "Solo" {
  meter 4/4

  parts {
    clarinet-bb 1,2: "Clarinet in Bb 1 & 2"
  }

  clarinet-bb {
    m1 {
      1C4
    }
  }

  clarinet-bb 1 {
    m2 {
      4G4 A B C
    }
  }
}

Generated notation

Canonical spelling

scorescript 0.3
score "Solo" {
  meter 4/4

  parts {
    clarinet-bb 1,2: "Clarinet in Bb 1 & 2"
  }

  clarinet-bb {
    m1 {
      1C4
    }
  }

  clarinet-bb 1 {
    m2 {
      4G4 A B C
    }
  }
}

The first clarinet plays m2; the second gets its rest, which nobody typed. The desk's own page shows that one line and prints 1. over it — no second layer of rests, because the label already says who is playing. 2. is what clarinet-bb 2 { ... } prints.

Writing the same bar in the desk's body AND a player's is two authors for one bar and is an error. Writing it in two DIFFERENT players' bodies is not: that is the divided case, and it is dealt exactly as v1 and v2 are.

A player body stands after the desk's own body, in player order, and formatting keeps it there — it is a body, not a voice, and rewriting it as v1 would say the desk divides where one player has a bar the desk does not.

Player parts

A part read by two players is three parts on the page: the one the desk shares, and one for each of them. scorescript parts lists all three, and --part takes any of their names.

scorescript 0.3
score "Fanfare" {
  meter 4/4

  parts {
    trombone 1,2: "Trombone 1 & 2"
  }

  trombone {
    m1-3 {
      1[G3 Bb] | v1 [ 2D' C ] v2 [ 2Bb3 A ] | 1F,
    }
  }
}

Generated notation

Canonical spelling

scorescript 0.3
score "Fanfare" {
  meter 4/4

  parts {
    trombone 1,2: "Trombone 1 & 2"
  }

  trombone {
    m1-3 {
      1[G3 Bb] | v1 [ 2D' C ] v2 [ 2Bb3 A ] | 1F,
    }
  }
}

Trombone 1 reads Bb3, then v1, then F3. Trombone 2 reads G3, then v2, then the same F3. Nothing in the file changes: a player part is a view of the music that is already there.

One question decides each bar. Does it divide into voices? Then v1 is the first player and v2 the second; more voices than players and the last player keeps the extra ones; fewer voices than players and the rest read the last one. Does it not? Then the chord divides instead: a single note is everybody's (a2), a chord of one note per player deals top-down, a chord with fewer notes than players doubles the lowest, and a chord with more notes than players leaves the surplus with the last player.

The player's name is the desk's name with the player list replaced by their own number, so Clarinet in Bb 1, 2 gives Clarinet in Bb 1 and Clarinet in Bb 2.

Cues go to every player, and so does everything that belongs to the bar rather than to a note: meter, key, clef, tempo, rehearsal marks, navigation and the layout maps. A divided bar lends its dynamics to whichever player did not write them, because a dynamic at a desk is read by everybody at it — but a quoted word does not travel, since ("Tbn. 2") is addressed to one player by name. A player who has nothing of their own in a bar still counts it, so they get its rest, and a run of those rests becomes that page's own multirest.

A voice is not a part. v2 is a way of writing a second line in the bars that need one, and it exists only in those bars; the parts are what the roster says they are.

The desk's own page

Every instrument in the catalog says how many notes ONE of its players can sound at once. A trombone, a flute and a singer sound one. A violin sounds two, bowed together. A piano, a harp, a guitar and a marimba sound as many as there are fingers.

So a chord means different things on different staves. On a desk of two trombones it is the two of them — the players, dealt top-down. On a violin it is a double stop, which is one player's two strings. On a piano it is a chord. And on a SINGLE trombone it is nobody's: the checker says so (divisi.single-player-chord) and tells you that trombone 1,2 is probably what was meant. The chord is still engraved; a diagnostic is a reason, never a refusal.

The desk's own part — the page the two of them share — is then engraved from what the music IS, not from how it is spelled.

scorescript 0.3
score "Two trombones" {
  meter 4/4

  parts {
    trombone 1,2: "Trombone 1 & 2"
  }

  trombone {
    m1-2 {
      1[G3 Bb] | v1 [ 2D' C ] v2 [ 4Bb3 A G F ]
    }
    m4-6 {
      v1 [ 4G A B C' ] v2 [ 4Eb F G A ] | v1 [ 1r ] v2 [ 4A B C' D ] | F,
    }
  }
}

Generated notation

Canonical spelling

scorescript 0.3
score "Two trombones" {
  meter 4/4

  parts {
    trombone 1,2: "Trombone 1 & 2"
  }

  trombone {
    m1-2 {
      1[G3 Bb] | v1 [ 2D' C ] v2 [ 4Bb3 A G F ]
    }
    m4-6 {
      v1 [ 4G A B C' ] v2 [ 4Eb F G A ] | v1 [ 1r ] v2 [ 4A B C' D ] | F,
    }
  }
}

Six bars, and the page reads each of them for itself:

m1's chord could be shown as chords and m4's voices could be shown as voices — but the decision is the PASSAGE's, not the bar's. m1 shares a passage with m2, which really does divide, so the page keeps m2's voices and does not fold m1 into anything; m3's silence ends that passage, and m4 begins one whose bars all agree. A page that flipped between chords and voices bar by bar would be unreadable, so it does not.

Nothing in the file changed. The page is a view, exactly as a player part is: explode and reduce are the verbs that change a spelling, and they write the source. The words the page adds — a2, 1., 2., and div. and unis. for a bowed section — are printed where the reading CHANGES and restated at the head of each system, which is what a copyist does.

Saying it yourself

Those four words are marks you can write: (1.), (a2), (div), (unis), in the marks chapter. Write one and the engine defers — it prints your word, once, where you put it, and prints none of its own for that passage.

scorescript 0.3
score "Who is playing" {
  meter 4/4

  parts {
    trombone 1,2: "Trombone 1 & 2"
  }

  trombone {
    m1-2 {
      1[G3 Bb] | v1 [ 2D' C ] v2 [ 4Bb3 A G F ]
    }
    m4-6 {
      v1 [ 4G A B C' ] v2 [ 4Eb F G A ] | v1 [ 1r ] v2 [ (2.)4A B C' D ] | F,
    }
  }
}

Generated notation

Canonical spelling

scorescript 0.3
score "Who is playing" {
  meter 4/4

  parts {
    trombone 1,2: "Trombone 1 & 2"
  }

  trombone {
    m1-2 {
      1[G3 Bb] | v1 [ 2D' C ] v2 [ 4Bb3 A G F ]
    }
    m4-6 {
      v1 [ 4G A B C' ] v2 [ 4Eb F G A ] | v1 [ 1r ] v2 [ (2.)4A B C' D ] | F,
    }
  }
}

The word is yours, and it is kept. If it says something the bars under it do not show — 2. over a bar every player reads on one line, a number nobody on the roster carries — the checker says so (divisi.word-disagrees) and prints your word anyway: who plays is your decision, not the engine's.

A player's own page never carries these words. 2. over the only line on the page tells its reader nothing, so Trombone 2 gets the notes and none of the labels.

One thing this is not: the conductor's score. Condensing several players' staves onto fewer is a different feature; a full score prints what the file says.

Measures first

To compare ensemble parts at the same moment, put the range outside the parts. The following has the same two lines of music as the duet above.

scorescript 0.3
score "Duet" {
  meter 4/4

  parts {
    fl
    ob
  }

  m1-2 {
    fl {
      4C5 D E F | 1G
    }
    ob {
      2C4 E     | 1G
    }
  }
}

Generated notation

Canonical spelling

scorescript 0.3
score "Duet" {
  meter 4/4

  parts {
    fl
    ob
  }

  m1-2 {
    fl {
      4C5 D E F | 1G
    }
    ob {
      2C4 E     | 1G
    }
  }
}

Each row supplies bars for its selected part. A plain trailing barline can continue a row onto the next physical line while the promised range still needs bars. A blank line ends a row. Do not turn rows into arbitrary newlines: the part-first and measure-first forms have different row structure.

Music or a named part group may begin immediately after the opening brace: m1 { 4C D E F } and m1 { fl { 4C D E F } } both work. A newline after the outer measure-first header is optional. In m3-6 { A B C D }, the four notes default to quarters in m3; m4–m6 are whole-bar rests. The range does not stretch those four notes across four bars.

m1-2 {
  4Eb4(p)< G 2Bb | 4.Eb &G 2F(mf)
}

m3-6 {
  4A5 B C D
}

Generated notation

Canonical spelling

m1-2 {
  4Eb4(p)< G 2Bb | 4.Eb &G 2F(mf)
}

m3-6 {
  4A5 B C D
}

Within a music row, a plain physical newline is not an arbitrary within-bar wrap: use a lone trailing backslash to continue an unfinished bar onto the next line. For smaller source, use native compaction, not a generic minifier.

The to-grid view aligns columns within measure-first collections. A label belongs before its opening brace. Older { m1: ... } grids require explicit migration; normal parsing rejects them.

Inside a measure-first block, fl,ob { ... } lets several instruments read the same passage. Shared and independent blocks may coexist; see shared passages and safe redundancy.

m marks an address, everywhere

Write m10-50 { ... }, not 10-50 { ... }, in both arrangements. The range is inclusive: measures 10 through 50, or 41 measures. The m identifies an address; it is not part of the music's duration. A single measure uses m10 { ... }.

Maps read the same way. system-map {m10, m50} lists two system starts and tempo {96, m10 120} changes the tempo at measure 10 — the same m, meaning the same thing. Maps used to be the one place that dropped it; they no longer are, and nothing in the language now writes a bare ordinal as an address.

An address never takes a colon. A colon binds a name to what a thing is REPRESENTED AS — a roster label, an exercise title, a cue's printed label — so whatever a map merely PLACES at a bar stands after the address with nothing between: key {C, m35 G}, RH {m5 [[A]]}, system-map {m10 3}. The older spellings (35:G, m35:G) are still read and are rewritten by formatting.

Formatting can regroup a long part-first range into smaller blocks without changing its measure addresses or music.

Different instruments on one staff

Put each instrument's line in brackets inside the same measure collection:

parts { fl hn }
m1-2 {
  fl [ 4C5(p) D E F | 1G ]
  hn [ 1C4(f) | 1D ]
}

Generated notation

Canonical spelling

parts {
  fl
  hn
}

m1-2 {
  fl [
    4C5(p) D E F | 1G
  ]
  hn [
    1C4(f)       | D
  ]
}

Flute is the upper line and horn the lower line. Each keeps its own sound and extracted part. Change those owner brackets to braces to print separate staves; the notes, dynamics and spans keep their owners. Ordinary formatting and migration keep the staff choice you wrote.

The first instrument supplies the clef. If the instruments transpose differently, the shared staff shows concert pitch; otherwise it follows the score's selected pitch view. The names stack in line order, full on the first system and short later. The smaller (concert) or (written) line under the names identifies the pitch basis when the staff appears or its basis changes. Different dynamics belong above the upper line and below the lower line; a shared dynamic prints once.

The collection can set a different printed clef or common pitch view:

parts { fl hn }
m1-2 {
  [clef bass] [transpose Bb]
  fl [ 1C5 | D ]
  hn [ 1C4 | D ]
}

Generated notation

Canonical spelling

parts {
  fl
  hn
}

m1-2 {
  [clef bass]
  [transpose Bb]
  fl [
    1C5 | D
  ]
  hn [
    1C4 | D
  ]
}

[transpose Bb] is the common B-flat page; [transpose C] is concert. These display points leave each instrument's sound and extracted part alone. The numeric interval [transpose -1 -2] means the same B-flat page and formats to the named form. Exact intervals with no unambiguous name retain their numbers. The top map at m1 { [clef bass] [transpose Bb] } selects the sole shared group at that bar. If several groups exist, place the points inside the intended collection. A later clef point still changes the staff. Shared overrides end when the owners return to separate staves; separate a collection only after explicitly removing or relocating its shared-view points.

A new shared membership starts a system with its own name column. Returning to separate staves can happen within a system.

Two to four owners can share, with no more than four musical voices in total. Their bars must have matching lengths, meters and staff-line counts. This form belongs in score or movement measure collections; exercise containers and part-first bracket bodies are not supported yet. MusicXML retains separate instrument parts and reports the shared display as omitted.

Simultaneous voices

Voices are bar-local. A staff carries a second, third, or fourth voice in the measures that need one, and nothing is declared anywhere else in the part. Inside a measure block, write each voice as a labeled group of that block's bars: v1 [ ... ], v2 [ ... ], up to v4.

scorescript 0.3
score "Two voices" {
  parts {
    violin
  }

  violin {
    m1 {
      v1 [ 2C5 D ]
      v2 [ 1G4 ]
    }
  }
}

Generated notation

Canonical spelling

scorescript 0.3
score "Two voices" {
  parts {
    violin
  }

  violin {
    m1 {
      v1 [ 2C5 D ]
      v2 [ 1G4 ]
    }
  }
}

Measure 1 contains C5 and D5 as half notes above a whole-note G4. Both groups start at the same time. This is one measure, not two.

The same groups read inside an instrument's block of a measure-first score. Only the arrangement differs; the music is the same.

scorescript 0.3
score "Divisi trombones" {
  parts {
    trombone 1,2
  }

  m1-2 {
    trombone {
      v1 [ 2D3 C | 1G' ]
      v2 [ 8Bb2 G G G 2F' | m2 { r } ]
    }
  }
}

Generated notation

Canonical spelling

scorescript 0.3
score "Divisi trombones" {
  parts {
    trombone 1,2
  }

  m1-2 {
    trombone {
      v1 [ 2D3 C | 1G' ]
      v2 [ 8Bb2 G G G 2F' | m2 { r } ]
    }
  }
}

The rules are the same in both arrangements.

• v1 … v4 and the longer voice 1 … voice 4 are the same label. Formatting writes the short spelling. Groups may share a line. Either spelling can also collect a whole voice's addressed measures: v2 [ m1 { 1G4 } m3 { 1A4 } ]. Only those measures carry voice 2. Beam and staff scopes may surround measures inside that voice collection.
• Direct events are voice 1. Use | to place a simultaneous group of voices between direct bars: r | v1 [1C3] v2 [1C4] | 1D3. Only the middle bar divides; no extra staff or part is created.
• A block that divides writes v1 among its groups; v3 and v4 are optional.
• Adjacent groups cover the same number of bars. A group may span the whole collection or just a portion of it. v1 [C | D] v2 [E | F] | G writes two simultaneous bars followed by a direct bar. Each voice keeps its own duration inheritance; returning to direct music continues voice 1.
• Rests are only ever the ones you write. A measure where a voice has no group prints nothing for that voice: single-voice bars keep their natural stem directions and one centred rest.
• Ties, slurs, hairpins, pitch, octave, and duration inheritance are per voice inside the group. A leading ~ in v2 closes a voice-2 span from the previous bar's voice 2, and the group's first note carries its own octave reference.
• 3{8C D E} is a tuplet, inside a voice group as anywhere else. A voice is named by its label, never by an unlabeled brace.

Do not assume that multiple voices automatically mean two separately extractable players, an ossia, or a piano grand staff. Those are distinct musical requirements. Multi-staff rh:/lh: notation is not part of this documented authoring surface.

Cue notes

A cue is another player's music, printed small above your own so you know where you are. You do not retype it: you reference it. The reading part names the source and the bars, and the notes, the label and the reader's own clef follow.

scorescript 0.3
score "Cues" {
  parts {
    bassoon 1
    trombone 1,2
  }

  bassoon {
    m1-3 {
      2r 4r 8r 16G3(mf)~ A | ~8Bb Bb Bb~ F ~4E 8r 16F~ G | 1D
    }
  }

  trombone {
    cue {m1-2 bassoon}
    m3 {
      4F3 G A Bb
    }
  }
}

Generated notation

Canonical spelling

scorescript 0.3
score "Cues" {
  parts {
    bassoon 1
    trombone 1,2
  }

  bassoon {
    m1-3 {
      2r 4r 8r 16G3(mf)~ A | ~8Bb Bb Bb~ F ~4E 8r 16F~ G | 1D
    }
  }

  trombone {
    cue {m1-2 bassoon}
    m3 {
      4F3 G A Bb
    }
  }
}

cue { m1-2 bassoon } is the map at the head of the part body, the shape every other map has: an address — a bar or a range, carrying its m — and the roster key of the player being quoted, placed after it with no colon between. The same fact can be written where it happens, and a block may both play and quote:

scorescript 0.3
score "Playing and quoting" {
  parts {
    bassoon 1
    trombone 1,2
  }

  bassoon {
    m1-2 {
      2r 4r 8r 16G3(mf)~ A | 1Bb
    }
  }

  trombone {
    cue {m1-2 bassoon}
    m1-2 {
      2r 4r 8r 16G3(mf)~ A | 1Bb
    }
  }
}

Generated notation

Canonical spelling

scorescript 0.3
score "Playing and quoting" {
  parts {
    bassoon 1
    trombone 1,2
  }

  bassoon {
    m1-2 {
      2r 4r 8r 16G3(mf)~ A | 1Bb
    }
  }

  trombone {
    cue {m1-2 bassoon}
    m1-2 {
      2r 4r 8r 16G3(mf)~ A | 1Bb
    }
  }
}

There are two ways to write a cue, and they are equals. The source decides which:

• Reference — cue { m8-10 bassoon } or m8-10 { cue bassoon } — when the player really is on this roster. Nothing is retyped: the source's own bars are quoted, and the label derives from their printed name shortened to its standard abbreviation, so Bassoon 1 prints Bsn. 1. Write your own after the source, behind the colon that binds it: cue { m40 bassoon: "Bsn. I" }.
• Inline — m30 { cue: "Bsn. 1" { 2r 4C4 D E } } — when the source is NOT a part of this score. The quoted string is the printed label and the notes are written in place, because there is nothing in the file to point at. The braces are what tell the two arms apart.

In a measure-first collection, a following declared part body belongs to that part, including a quoted roster key or printed label. A body-less cue bsn does not absorb the next "fl" { 1G5 }. Use the colon for a cue's own label, as in cue bsn: "Bsn. I"; moving either head to a new line does not change which part owns the music.

Do not add a part to the roster only so a cue can read it. A part of the score is a player of the ensemble; whether they are printed or extracted is a layout decision, not something the roster says. If the source is not in the ensemble, quote it inline.

• The source's own rests place the entry. A bassoon that enters on beat 4 wrote 2r 4r 8r 16G3~ A, and that is exactly what the cue prints; there is no sub-bar cue address to write.
• The whole quotation is small, not only its noteheads. Its beams, its stems, its flags, its accidentals, its dots, its own rests, its dynamics, its articulations, its slurs and its tuplet brackets and numbers all print at the same three-quarter size, and its stems all point up. Your own rests, your own multirest and your own marks stay full size, so the page never leaves you wondering which music is yours. docs/ENGINE-CUES.md is the engraving contract behind that.
• The name stands over the first NOTE of the quotation, above the staff, once per unbroken run — not over the source player's leading rests, however many bars of them place the entry.
• Beam instructions travel with a reference cue. Voice subdivisions, complete node beams, feather shapes and paired tremolos keep their resolved connections. A quote that omits an endpoint reports cue.partial-connection; include the whole connection to retain it. Cross-bar beam policies stop at the quotation boundary.
• Cues are silent. They are on the page, not in the room: playback and MIDI pass over them, and a way to ask for them is a later option.

Formatting collects a part's references into one cue { … } at the head of its body. --normalize maps=inline writes them back into the blocks instead.

Clefs and staff defaults

A catalog instrument supplies its usual clef: flute and piano start in treble, viola in alto, tuba in bass, and unpitched percussion in percussion clef. An anonymous fragment without a stated clef uses treble or bass according to its register; it does not acquire alto merely to reduce ledger lines.

State a clef in the part to override the default. An inline change applies from its containing measure onward, including when no opening clef was stated:

scorescript 0.3
score "Cello clefs" {
  parts {
    cello
  }

  cello {
    clef bass

    m1-2 {
      1C3 | [clef tenor] C'
    }
  }
}

Generated notation

Canonical spelling

scorescript 0.3
score "Cello clefs" {
  parts {
    cello
  }

  cello {
    clef bass

    m1-2 {
      1C3 | [clef tenor] C'
    }
  }
}

Named clefs include treble, soprano, mezzo-soprano, alto, tenor, baritone, bass, and percussion. Octave-clef spellings include treble-8va, treble-8vb, bass-8va, and bass-8vb. An explicit clef is preserved; switching the output pitch does not erase your clef changes.

Written output keeps transposing players in their catalog reading clefs. Concert output may use a register-appropriate clef for octave-transposing instruments such as bass clarinet. Low written notes alone must not turn a bass-clarinet player's treble staff into a bass staff.

One declared part is one staff; simultaneous voices remain on that staff. piano does not automatically split a melody into right and left hands. Multiple systems are successive lines of music, not additional instruments. See left-side grouping for grouping existing staves without creating or redistributing music.

Silence, pickups, and names

In part-first source, gaps between explicitly addressed ranges are silent. A part that begins at m9 has eight preceding measures of rest. Check the range before changing it: deleting music and leaving its next addressed range can leave silence rather than renumber the score.

m0 addresses a pickup. =name gives a note or a measure an authored name.

scorescript 0.3
score "Pickup" {
  parts {
    flute
  }

  flute {
    m0-1 {
      4G4 | C=theme D E F
    }
  }
}

Generated notation

Canonical spelling

scorescript 0.3
score "Pickup" {
  parts {
    flute
  }

  flute {
    m0-1 {
      4G4 | C=theme D E F
    }
  }
}

Measure ranges also support names and reuse; see shared passages. For multiple complete movements, use collections.

Compatibility spellings

Musical measure bodies require braces: m1 { ... }. The former m1: ... header is an error, including inside part, staff and voice bodies. Brace-first { m1: ... } grids are also errors and require explicit migration.

Older files may contain direct part flute: Flute { ... } declarations or measure-first rows stacked under one instrument to mean its further voices. These remain accepted input; they are not the default examples for new files. Formatting writes the labeled v1 [ ... ] groups above wherever a range carries more than one voice. Old same-staff voice N { ... } groups require explicit migration to brackets; they are not accepted as same-staff voices. The older direct part body does not accept all nested ranges, shared readers, and layout maps supported by the current roster-plus-body form.

A display destination uses those same staff selectors: [st b] and [st 2] route the following music to the owner's second staff; [st t] and [st 1] route it to the first. treble, bass and stN are also accepted. These names identify staff positions, so b still means the second staff if its clef has changed to treble. own returns to the music's owning staff. The aliases also work in bounded staff scopes and owner-qualified staff maps.

Cues in a bar sequence

A cue followed by a barline occupies the bars where you write it. Here the flute rests during the horn quote in measure 1, then plays C5 in measure 2 and E5 in measure 3. The sequence m1-3 { cue: "Hn." { 1D5 } | 1C5 | 1E5 } formats with the cue's own measure shown explicitly:

parts {
  fl
}

fl {
  m1 {
    cue: "Hn." { 1D5 }
  }
  m2-3 {
    1C5 | E
  }
}

Generated notation

Canonical spelling

parts {
  fl
}

fl {
  m1 {
    cue: "Hn." { 1D5 }
  }
  m2-3 {
    1C5 | E
  }
}

A two-bar quote occupies two bars. A cue after a barline starts at that point; putting it on a new row does not move it. A cue following the player's own completed music without a separating barline remains an overlay on the addressed block. A cue cannot fill the remainder of a partial player bar. Keep a cue in its own bar, separated from the player's notes with | when sharing a range. Notes after a cue also need that barline; a new row cannot create another voice. Write r for a silent bar: an empty slot between barlines is counted as a rest and diagnosed, never discarded.

Measure collection bounds

A single head such as m1 { 1C5 } contains one bar. Write a range for several: m1-2 { 1C5 | 1D5 }. A nested measure address must stay within its containing range; an extra bar is diagnosed rather than silently extending the range. Older sources such as m1 { 1C5 | 1D5 } keep their two bars and receive an implicit-range warning. format and migrate write m1-2 explicitly.

A counted rest or repeat states its extent explicitly: m4 { r3 } rests through m6, and &&3 repeats three bars. Further music needs its own address or a range covering all those bars. A written range still bounds a counted run, so m4-5 { r3 } is too long.