Build a reusable method book

Keep the complete musical edition in one .scorescript file. Define a passage once, return to it by name in other keys, and give genuinely different exercises their own definitions. Use movements for independently metered studies and exercise identities for the divisions within them. The same source supplies notation, playback, parts, and export.

One octave and two octaves are separate exercises

This trumpet example has a two-measure one-octave scale and a four-measure two-octave scale. Both return a semitone lower. Their different sequences, breaths, double bars, and line lengths belong to the definitions. Editing a definition changes its returns too.

Notation for the Build a reusable method book example — Edit this exampleDownload source

The source pitches are concert pitches. Written B-flat trumpet export shows G major followed by F-sharp major. The first scale spans written G3–G4; the second spans G3–G5. Changing the key and choosing a register are distinct decisions. Neither operation turns the first sequence into the second.

When the one- and two-octave versions are the SAME scale and only the player's range decides which they read, define the scale once as a music object and let first { … } choose per player:

The flute reads two octaves of every key, the trumpet two of C and one of F and B-flat, the tuba one of C and two of the rest — each from the lowest tonic inside its declared range, each labelled with its own octave count. An All-State packet is this head with fifteen keys and a @scale-chromatic line under it.

meter none hides the meter and accepts free-length divisions. Keep the bars that organize the lesson. Each system-map entry collects an exact number of measures on one line: m3 4 collects m3 through m6. The inclusive spelling m3-m6 means the same thing; formatting writes the count form. Placing these collectors inside the shared reader body lets named returns inherit them. Choose a page width and staff size at which the collected music remains readable.

Organize the complete edition

Use movements and collections to place scales, warmups, and independently metered etudes in the same file. Stable movement and exercise IDs allow titles and numbering to change without redefining the music. Exercise sections describe a musical range; book sections group exercise identities. Use one heading for each actual level of the lesson instead of repeating a movement title in every exercise label.

Named returns currently resolve inside their containing reader body. Keep the definition and its returns together. For a vocabulary reused by several movements, define a music object at book scope, before the movements collection; every movement can apply it while retaining its own roster, local bar numbers and layout. A movement-local object deliberately shadows a book object with the same name. Separate movements can still be retained in one authoritative file. Optional linked exercises require a filesystem-aware reader and are described in the collections chapter.

For another instrument, use the native reader and register controls. Review the whole exercise's lowest and highest written notes, its spelling, clef, and intended teaching range. Preserve deliberately distinct upper and lower variants. Practical-range diagnostics inform this review; clearing them by folding notes into a single octave can destroy the lesson.

State the set-up once

The pieces of a method book share their set-up: the players, the credits, a subtitle that names the key. Say it once in the book's head, before the movements, and every movement that does not say it itself uses it:

Notation for the Build a reusable method book example, movement 1 — Edit this exampleDownload source

Both etudes are for flute, trumpet and horn, both are by Brandon Dicks, and both read the head band names. The march's heading carries the book's subtitle, so each player sees the key they read; the lullaby writes subtitle none, so its heading is its title alone. Neither writes number: a movement is numbered by its place in the book, and one that writes number 7 is number 7.

A statement in the book's head stands in every movement that has no statement of its own of that kind, exactly as if the movement had written it:

In the book's head	A movement uses it when
`composer`, `arranger`, `lyricist`, `translator`	it names none of its own; `composer none` keeps it empty
`title`, `subtitle`	it writes none; `subtitle none` keeps it empty
`meter`, `key`, `tempo`, `partial`, `clef`, `spell`, `solfege`, `rehearsal`, `prefer`, `highlight`	it writes no statement of that name
`parts { … }`	it declares no players (`parts { … }` or `part`); its own part bodies are read by the book's players
`range written { … }`	always: the movement's own entries follow the book's, and the later entry for a player wins
`range catalog`, `range none`	it writes no `range` statement of its own
music objects, rhythms, `use`, reader sets	always; a movement's own definition of one name is used in that movement

Statements addressed by bar — at m5 { … }, meter {m9 3/4}, system-map, page-map — and the book's own book { … }, text-page, sections and numbering belong to one timeline or to the volume, and no movement takes them. A chapter written as another in a new key takes its set-up from the chapter it is, and a chapter pulled with movement from brings the set-up of the book it was written in.

A chapter written as another cannot keep an inherited slot empty: movement =g-scales = c-scales in F { subtitle none } is refused (chapter.slot-inherited), and so are lyricist none and translator none there. none in the SOURCE is not the answer either — it would empty the slot for the source and for every other chapter written as it. A chapter that needs a heading of its own is written out in full, where every head statement is its own to write.

band = readers { fl +P8, tpt, hn -P8 } names a reader head. Write the name wherever a head is written — band { … }, band written fit { … }, or beside other readers as band, pno { … } — and it reads exactly as the head it names. The readings stay in the head: the roster still says only who plays. A set is seen after its definition, in the book or movement that defines it. A second set of one name (reader-set.duplicate), a name that is already a music object or rhythm (reader-set.name-taken), an empty set (reader-set.empty), all or a set inside a set (reader-set.nested), a register or interval on the set's name (reader-set.modified), and title or subtitle in a score with no movements (setup.without-movements) are refused by name.

What a set's readers open with

The chapters of a book are held to the written ranges its head states; its etudes are not. Say how the etude band reads where the band is named:

with { transpose 0 range catalog } opens every head that names band with those statements at its first bar, exactly as if the head had written at m1 { transpose 0 range catalog } — m0 in a movement that opens with a pickup. The march's flute reads up to written B-flat 6, past the book's C4–C6, because range catalog hands its range back to the catalog's advice. A statement of the same name the head writes at that bar is its own and stands instead. The book's head could not say this: a player's own range outranks the book's map, so a range stated for every movement would release the chapters too.

A set opens its readers with what a player carries from bar to bar — key, clef, transpose, range, highlight, spell, solfege and prefer; meter, tempo and partial belong to the score (context.scope). A head's opening statements govern every reader in it, so a set that carries some is written in a head of its own (reader-set.opening-shared).

Write the set-up out, or state it once

scorescript format book.scorescript --normalize setup=explicit,numbers=explicit,readers=explicit
scorescript format book.scorescript --normalize setup=shared,numbers=derived,readers=named

setup=explicit writes every statement a movement uses from the book into the movement; setup=shared states once in the book's head what every written-out movement repeats, and takes it out of the movements. With setup-quorum=most, a credit or subtitle most movements repeat is stated once too, and the movements that have none write none; so is the title the most movements repeat, and the movements with another title keep their own. numbers=derived leaves out every number that equals the movement's place and numbers=explicit writes them all. readers=named writes a set's name wherever a head holds its readers and, for a set that opens them with { … }, opens with exactly those statements; readers=explicit spells every head out, statements and all. A set of ONE reader is written out as that reader alone (pno { … }) and read back as the head it is, not as a part body, so both doors cross for it as well. Each result compiles to the same MusicXML and pages as the file it came from.

Write a chapter once and print it in every key

A method book often prints one chapter of exercises in twelve keys. Write the chapter once as an ordinary movement, then write every other key as that chapter in a new key:

movement =f-scales = c-scales in Eb reads like an assignment: the chapter f-scales is c-scales in E-flat. Its own id is required, and it stays the address books, layouts and links use. The key of a chapter is the tonic of its first object application — here @two-octaves Bb, the key {concert-key} prints — and every application in the chapter moves by the interval from that key to the new one. Choices made by range (fit, first { }, fits { }, if range contains) are made again in the new key: the horn reads two octaves of concert B-flat and one of concert E-flat. Titles that use {written-key} and {concert-key} follow the new key.

The block after the key says what is different about this key, and nothing else:

Head statements — number, title, subtitle, credits, meter, tempo and range written { … }. A statement stands after the source chapter's statement of the same name, the way a chapter's statements stand after the book's.
Ranges start from the book. A range the source chapter states for its own key (its range written, a range statement, a bound on a roster line) stays with that chapter. The instance holds its players to the book's ranges, plus the range written { … } it writes itself; write there only what is genuinely different about this key.
page before =exercise { readers } — who turns the page before one of the source's exercises in this key. The named readers open that exercise on a new page and every other reader does not; { } names nobody. The turn lands where each reader opens that exercise — its first body there — and a later body the same reader reads inside the exercise keeps what it wrote. One line names every exercise the same readers turn before: page before =again, =finale { hn }. The source's own turns carry to its instances, and an instance's line for an exercise replaces them.

Only music applied through objects moves. A chapter that writes notes directly, anchors a pattern to a register (@scale-major C4a {q8}) or states a key signature cannot be printed in another key this way (chapter.literal-music): moving written notes would mean guessing their octave. A chapter written as an instance of another instance is the source's chapter moved twice, and carries both blocks' statements. An id no chapter has (chapter.unknown-source), an instance of itself or a loop of instances (chapter.cycle), music inside the block (chapter.instance-body) and a page before name the source does not have (chapter.page-before-unknown) are refused by name. Two movements with one id (movement.duplicate-id) and two exercises with one id in a movement (exercise.duplicate-id) are refused too.

Any movement says its own turns the same way. The C chapter above writes its second exercise once, for everyone, and page before =again { tpt } puts the trumpet alone on a new page; writing the exercise twice — once under the trumpet with \p at the head of its body, once under everyone else — prints the same pages.

Write it out, or write it as an instance

The two forms are the same music, and the formatter crosses between them:

scorescript format book.scorescript --normalize chapters=explicit
scorescript format book.scorescript --normalize chapters=instances

chapters=explicit writes every instance out as the full chapter it stands for — the way to give one key music of its own — with that chapter's range exceptions against the book. chapters=instances finds each chapter that equals an earlier chapter in another key, differing only in head statements, ranges and page turns, and writes it as an instance whose range written names only the ranges that differ from the book's. A chapter with any other difference stays written out, and every exercise the same readers turn before is named on one page before line. Either result compiles to the same MusicXML and the same printed pages as the file it came from.

scorescript format book.scorescript --normalize page-turns=heads
scorescript format book.scorescript --normalize page-turns=lines
scorescript format book.scorescript --normalize page-turns=combined

page-turns=heads writes every turn a written-out movement can hold as \p at the head of the bodies that turn; page-turns=lines writes an exercise whose heads differ only in who opens it with \p once, with one page before line per exercise; page-turns=combined also names every exercise the same readers turn before on one line. An instance keeps its lines, one per exercise under heads.

Check, format, and export the native source

When complete native scores already exist, import them once with scorescript book. An empty volume template owns the title, book furniture, and instructional pages. Each standalone input needs the stable movement ID it will have in the master. A multi-movement input keeps its own IDs and order. For example:

scorescript book --template volume.scorescript --input warmups warmups.scorescript --input scales scales.scorescript --input etudes etudes.scorescript -o method-book.scorescript

The command uses the native AST and formatter, preserves comments and named returns, and writes one self-contained master. Edit that master from then on. It does not create ongoing links to the input files. Duplicate movement IDs, inputs with volume-owned furniture/text, and shared outer musical context in multi-movement inputs are refused. Place that context inside each movement before importing. An explicit standalone movement-title becomes the movement title; a distinct original score title becomes its subtitle. Move an imported volume's outer extensions into the template or their owning movement before combining it. Template credits and extensions survive formatting. An existing output file is refused rather than replaced.

Save the complete example as method-book.scorescript. The native CLI workflow is:

scorescript check method-book.scorescript --format json
scorescript format method-book.scorescript --write
scorescript check method-book.scorescript --format json
scorescript pdf method-book.scorescript --part tpt --transposed -o method-book.pdf

For a multi-movement file, native CLI PDF export includes all movements by default. Add --movement ID to select one. MusicXML export selects an individual movement with the same option. Check the host's export scope explicitly; seeing a whole-book preview alone does not establish what its export selects.

Source owns notes, variants, headings, and musical line constraints. A native layout file owns engraving choices such as paper and staff size. An external assembly script or parallel music JSON file is unnecessary for this workflow. See layout for the supported controls.

Compile success establishes that the language accepts the book. Before printing, inspect the exported pages: inventory every lesson and instruction against the reference, confirm written pitch and registers, check repeats and navigation, and inspect line breaks, headings, and clipping. Cover, contents, folios, and running heads are supported book furniture. Write each rights notice beside composer at the head of the score — copyright "© 2026 The Author. All Rights Reserved.", and another copyright line for an arrangement or permission notice; a movement that states none carries the volume's. By default a book prints its title and author on its cover or, without a cover, in every running head, and every notice in the foot of every page. Which lines print, where, and in what case is the layout's book_furniture option.

Worksheets, instructions and notes on a page: `text-page`

Words that are not lyrics go on a text-page: a worksheet, the instructions above an exercise, descriptions under the music, practice notes, a preface, a blank page. With excerpt it is also how you print one page carrying the music and its description together, which is what a worksheet usually is.

Native instructional pages use text-page =id { before =movement heading "Title" paragraph "Text" } at volume level. Each block owns one page; omit before to place it after all movements. Equal anchors retain source order. An empty block deliberately creates a blank page. Text that does not fit is refused instead of clipped.

Headings, paragraphs and hanging bullets can carry their own typography. Sizes and before/after spacing are in points, so they keep their printed size when the music's staff size changes. Use align left, center or right, and style regular, bold, italic or bold-italic. Omitted properties use the book's text roles. A page can set vertical middle or vertical bottom to position its ink within the margins; contents pages retain top alignment.

A columns block has two to four equal-width prose columns with a 12-point gutter. Each accepts headings, paragraphs and bullets. Columns begin together; the next block starts below the tallest one. Music excerpts stay outside prose columns. Text sizes must be positive, spacing nonnegative, and values no larger than 10000 points. A word wider than its column or text taller than the page produces a diagnostic instead of clipping.

Place excerpt =study m1-4 between headings and paragraphs to show music from the visible movement =study. The inclusive range must contain complete systems in the selected layout. The example uses the same engraved notes, key, and slurs as that movement and adds no measures to playback. Changing the music updates the example. Missing references, partial systems, and overflowing pages are refused with a diagnostic.

book.excerpt-boundary says the excerpt is too wide for the text page. The measurement is the ink of the excerpted systems together with the text marks attached to them, not the number of staves: a grand staff excerpts like any other movement. The usual cause is one long attached text mark — a section label such as ("PENTASCALE ASCENDING AND DESCENDING") on a note — whose ink runs past the page's content box while the music itself fits. Shorten that mark, or move it out of the music: a label that names the section belongs in a heading between excerpts, where the page can wrap it. An excerpt is drawn at its own movement's staff size, so a page that is too tall is fitted by lowering that movement's staff_size_mm in movement_overrides.

To make the instructional page the published form of its movement, add replace-music beside before =study. Its excerpts must contain every retained bar of that movement exactly once, in order. Several pages with the same anchor can divide the music between them. ScoreScript then prints those composed pages and points the contents at the first one. Without replace-music, the example page and the movement's ordinary music pages both print. Missing, repeated or reordered bars refuse the replacement; the music remains defined once.

For a boxed practice passage, name its first and last notes in the music and write excerpt =study m1-4 { box =trouble-start =trouble-end }. The box uses those notes' engraved bounds; use the same name twice for a single note. Names must resolve uniquely within the excerpt. See structure for note names and layout for the system and paper choices.

Named passage returns preserve the original note names and give copied notes destination-qualified names, such as trouble-start-m40 for a copy in m40. An occupied name receives a numeric suffix. Original instructional references therefore remain stable when the passage is reused in another key.

Check which documentation a tool is using

The chapter source is shared by the native wiki, CLI, and MCP documentation. scorescript docs --manifest, the MCP resource scorescript://docs/manifest, and the website's /reference/docs.json expose the documentation bundle fingerprint and engine version. Compare both when a tool appears to teach an older spelling. The fingerprint checks content drift; it is not an authenticity signature and does not update an installed client.