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.

scorescript 0.3
score "Scale variants — structure proof" {
  meter none

  key {F, m7 E}

  exercises {
    exercise =one-octave {
      title "Standard Scale (1 Octave)"
      section m1-2
    }

    exercise =two-octaves {
      title "Standard Scale (2 Octaves)"
      section m3-6
    }

    exercise =one-octave-next-key {
      title "Standard Scale (1 Octave)"
      section m7-8
    }

    exercise =two-octaves-next-key {
      title "Standard Scale (2 Octaves)"
      section m9-12
    }
  }

  parts {
    tpt
  }
  tpt3 {
    system-map {m1 2, m3 4}
    m1-2=one-octave {
      4F3 G3 A3 Bb3 C4 D4 E4 (,)F4 | F4 E4 D4 C4 Bb3 A3 G3 F3 ||
    }
    m3-6=two-octaves {
      4F3 G3 A3 Bb3 C4 D4 E4 (,)F4 | F4 G4 A4 Bb4 C5 D5 E5 (,)F5
      4F5 E5 D5 C5 Bb4 A4 G4 (,)F4 | F4 E4 D4 C4 Bb3 A3 G3 F3 ||
    }
    m7-8 = one-octave -m2
    m9-12 = two-octaves -m2
  }

}

Generated notation

Canonical spelling

scorescript 0.3
score "Scale variants — structure proof" {
  meter none

  key {F, m7 E}

  exercises {
    exercise =one-octave {
      title "Standard Scale (1 Octave)"
      section m1-2
    }

    exercise =two-octaves {
      title "Standard Scale (2 Octaves)"
      section m3-6
    }

    exercise =one-octave-next-key {
      title "Standard Scale (1 Octave)"
      section m7-8
    }

    exercise =two-octaves-next-key {
      title "Standard Scale (2 Octaves)"
      section m9-12
    }
  }

  parts {
    tpt
  }
  tpt3 {
    system-map {m1 2, m3 4}
    m1-2=one-octave {
      4F3 G3 A3 Bb3 C4 D4 E4 (,)F4 | F4 E4 D4 C4 Bb3 A3 G3 F3 ||
    }
    m3-6=two-octaves {
      4F3 G3 A3 Bb3 C4 D4 E4 (,)F4 | F4 G4 A4 Bb4 C5 D5 E5 (,)F5
      4F5 E5 D5 C5 Bb4 A4 G4 (,)F4 | F4 E4 D4 C4 Bb3 A3 G3 F3 ||
    }
    m7-8 = one-octave -m2
    m9-12 = two-octaves -m2
  }

}

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.

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. Do not assume that a definition in one movement is available in another. 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.

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. 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.

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.

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.