The config block is an optional top-level block for advanced layout, defaults, appearance, print directives, and preserved import detail. It MUST NOT be required for ordinary composition-oriented authoring.

Structure

config {
  defaults { ... }
  appearance { ... }
  print { ... }
  import-detail { ... }
  links { ... }
  bookmarks { ... }
}

Canonical block order within config:

  1. defaults
  2. appearance
  3. print
  4. import-detail
  5. links
  6. bookmarks

Defaults

config {
  defaults {
    scaling {
      millimeters 7.0
      tenths 40
    }
    concert-score false
    page-layout {
      page-height 1760
      page-width 1360
      page-margins both {
        left-margin 80
        right-margin 80
        top-margin 80
        bottom-margin 80
      }
    }
    system-layout {
      system-margins {
        left-margin 0
        right-margin 0
      }
      system-distance 130
      top-system-distance 70
    }
    staff-layout {
      number 1
      staff-distance 60
    }
    music-font {
      font-family "Bravura"
      font-size 20
    }
    word-font {
      font-family "EB Garamond"
      font-size 12
    }
    lyric-font {
      number 1
      name verse
      font-family "EB Garamond"
      font-size 11
    }
    lyric-language {
      number 1
      name verse
      lang "en"
    }
  }
}

Scaling

Field Description
millimeters N Millimeters per staff height
tenths N Tenths per staff height

Page Layout

Field Description
page-height N Page height in tenths
page-width N Page width in tenths
page-margins type { ... } Page margins block

Page margin types: both, odd, even.

System Layout

Field Description
system-margins { ... } System margins block
system-distance N Distance between systems
top-system-distance N Distance from top of page to first system

Staff Layout

Field Description
number N Staff number
staff-distance N Distance to next staff

Fonts

Block Description
music-font { ... } Music notation font
word-font { ... } Text/word font
lyric-font { ... } Lyric font
lyric-language { ... } Lyric language

Font fields: font-family, font-size, font-style, font-weight.

Appearance

config {
  defaults {
    appearance {
      line-width stem 0.8333
      line-width leger 0.8333
      note-size grace 60
      distance hyphen 12
      glyph noteheadBlack "noteheadBlack"
      other-appearance "custom-rule"
    }
  }
}

Appearance Entries

Entry Type Fields Description
line-width type, value Line width for element type
note-size type, value Note size for type
distance type, value Distance for element type
glyph type, value Glyph definition
other-appearance value Custom appearance rule

Print

Print directives for specific parts and measures:

config {
  print {
    part p1 {
      measure 12 {
        new-system true
        new-page false
      }
    }
  }
}

Print Fields

Field Description
new-system true/false Force new system
new-page true/false Force new page

Import Detail

Descriptive preservation state for imported MusicXML:

config {
  import-detail {
    source-shape "score-timewise"
    container-format "mxl"
    preserve-layout true
    preserve-appearance true
    preserve-defaults true
    preserve-print true
    preserve-reference-identity true
  }
}

Import Detail Fields

Field Description
source-shape Source document shape (score-partwise, score-timewise)
container-format Container format (xml, musicxml, mxl)
preserve-layout Preserve layout semantics
preserve-appearance Preserve appearance semantics
preserve-defaults Preserve defaults semantics
preserve-print Preserve print directives
preserve-reference-identity Preserve reference identity

Links

Document-level links:

config {
  links {
    link l1 {
      href "https://example.test"
      target @n1
      element note
      position 1
    }
  }
}

Link Fields

Field Description
id Link identifier
href External URL
target Internal target reference
element Target element kind
position Target position

Bookmarks

Document-level bookmarks:

config {
  bookmarks {
    bookmark b1 {
      element note
      position 1
    }
  }
}

Bookmark Fields

Field Description
id Bookmark identifier
element Target element kind
position Target position

Rules

Next Steps