Within-system spacing properties

The within-system vertical spacing mechanisms are controlled by two sets of grob properties. The first set is associated with the VerticalAxisGroup grob, which is created by all staves and non-staff lines. The second set is associated with the StaffGrouper grob, which can be created by staff groups, but only if explicitly called. These properties are described individually at the end of this section.

The names of these properties (except for staff-affinity) follow the format item1-item2-spacing, where item1 and item2 are the items to be spaced. Note that item2 is not necessarily below item1; for example, nonstaff-relatedstaff-spacing will measure upwards from the non-staff line if staff-affinity is UP.

Each distance is measured between the reference points⁷ of the two items. The reference point for a staff is the vertical center of its StaffSymbol (i.e., the middle line if line-count is odd; the middle space if line-count is even). The reference points for individual non-staff lines are given in the following table:

Non-staff line	Reference point
ChordNames	baseline
NoteNames	baseline
Lyrics	baseline
Dynamics	mid-height of ‘m’
FiguredBass	baseline of topmost element
FretBoards	top line

In the following image, horizontal lines indicate the positions of these reference points:

Each of the vertical spacing grob properties (except staff-affinity) uses the same alist structure as the \paper spacing variables discussed in Flexible vertical spacing \paper variables. Specific methods for modifying alists are discussed in Modifying alists. Grob properties should be adjusted with an \override inside a \score or \layout block, and not inside a \paper block.

The following example demonstrates the two ways these alists can be modified. The first declaration updates one key value individually, and the second completely redefines the property:

\new Staff \with {
  \override VerticalAxisGroup
            .default-staff-staff-spacing.basic-distance = 10
} { … }

\new Staff \with {
  \override VerticalAxisGroup.default-staff-staff-spacing =
    #'((basic-distance . 10)
       (minimum-distance . 9)
       (padding . 1)
       (stretchability . 10))
} { … }

To change any spacing settings globally, put them in the \layout block:

\layout {
  \context {
    \Staff
    \override VerticalAxisGroup
              .default-staff-staff-spacing
              .basic-distance = 10
  }
}

Standard settings for the vertical spacing grob properties are listed in VerticalAxisGroup and StaffGrouper. Default overrides for specific types of non-staff lines are listed in the relevant context descriptions in Contexts.

Properties of the VerticalAxisGroup grob

VerticalAxisGroup properties are typically adjusted with an \override at the Staff level (or equivalent).

staff-staff-spacing

Used to determine the distance between the current staff and the staff just below it in the same system, even if one or more non-staff lines (such as Lyrics) are placed between the two staves. Does not apply to the bottom staff of a system.

Initially, the staff-staff-spacing of a VerticalAxisGroup is a Scheme function that applies the properties of the StaffGrouper if the staff is part of a group, or the default-staff-staff-spacing of the staff otherwise. This allows staves to be spaced differently when they are grouped. For uniform spacing regardless of grouping, this function may be replaced by a flexible-spacing alist, using the complete-redefinition form of override shown above. If only some values are specified in an override, missing values will be taken from default-staff-staff-spacing (if it has values for them).

default-staff-staff-spacing

A flexible-spacing alist defining the staff-staff-spacing used for ungrouped staves, unless staff-staff-spacing has been explicitly set with an \override.

staff-affinity

The direction of the staff to use for spacing the current non-staff line. Choices are UP, DOWN, and CENTER. If CENTER, the non-staff line will be placed equidistant between the two nearest staves on either side, unless collisions or other spacing constraints prevent this. Adjacent non-staff lines should have non-increasing staff-affinity from top to bottom, e.g., a non-staff line set to UP should not immediately follow one that is set to DOWN. Non-staff lines at the top of a system should use DOWN; those at the bottom should use UP. Setting staff-affinity for a staff causes it to be treated as a non-staff line. Setting staff-affinity to #f causes a non-staff line to be treated as a staff. Setting staff-affinity to UP, CENTER, or DOWN causes a staff to be spaced as a non-staff line.

nonstaff-relatedstaff-spacing

The distance between the current non-staff line and the nearest staff in the direction of staff-affinity, if there are no non-staff lines between the two, and staff-affinity is either UP or DOWN. If staff-affinity is CENTER, then nonstaff-relatedstaff-spacing is used for the nearest staves on both sides, even if other non-staff lines appear between the current one and either of the staves. This means that the placement of a non-staff line depends on both the surrounding staves and the surrounding non-staff lines. Setting the stretchability of one of these types of spacing to a small value will make that spacing dominate. Setting the stretchability to a large value will make that spacing have little effect.

nonstaff-nonstaff-spacing

The distance between the current non-staff line and the next non-staff line in the direction of staff-affinity, if both are on the same side of the related staff, and staff-affinity is either UP or DOWN.

nonstaff-unrelatedstaff-spacing

The distance between the current non-staff line and the staff in the opposite direction from staff-affinity, if there are no other non-staff lines between the two, and staff-affinity is either UP or DOWN. This can be used, for example, to require a minimum amount of padding between a Lyrics line and the staff to which it does not belong.

Properties of the StaffGrouper grob

StaffGrouper properties are typically adjusted with an \override at the StaffGroup level (or equivalent).

staff-staff-spacing

The distance between consecutive staves within the current staff group. The staff-staff-spacing property of an individual staff’s VerticalAxisGroup grob can be overridden with different spacing settings for that staff.

staffgroup-staff-spacing

The distance between the last staff of the current staff group and the staff just below it in the same system, even if one or more non-staff lines (such as Lyrics) exist between the two staves. Does not apply to the bottom staff of a system. The staff-staff-spacing property of an individual staff’s VerticalAxisGroup grob can be overridden with different spacing settings for that staff.

See also

Notation Reference: Flexible vertical spacing \paper variables, Modifying alists.

Installed Files: ly/engraver-init.ly, scm/define-grobs.scm.

Internals Reference: Contexts, VerticalAxisGroup, StaffGrouper.

<< Back to Documentation Index

LilyPond Notation Reference v2.25.15 (development-branch).