LilyPond Notation Reference: 4.4 Vertical spacing

4.4 Vertical spacing

Vertical spacing is controlled by three things: the amount of space available (i.e., paper size and margins), the amount of space between systems, and the amount of space between staves inside a system.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

4.4.1 Flexible vertical spacing within systems

Three separate mechanisms control the flexible vertical spacing within systems, one for each of the following categories:

ungrouped staves,
grouped staves (staves within a staff-group such as ChoirStaff, etc.), and
non-staff lines (such as Lyrics, ChordNames, etc.).

The height of each system is determined in two steps. First, all of the staves are spaced according to the amount of space available. Then, the non-staff lines are distributed between the staves.

Note that the spacing mechanisms discussed in this section only control the vertical spacing of staves and non-staff lines within individual systems. The vertical spacing between separate systems, scores, markups, and margins is controlled by \paper variables, which are discussed in Flexible vertical spacing \paper variables.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

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`	highest point
`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 re-defines 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 (internals)VerticalAxisGroup section ‘VerticalAxisGroup’ in Internals Reference and (internals)StaffGrouper section ‘StaffGrouper’ in Internals Reference. Default overrides for specific types of non-staff lines are listed in the relevant context descriptions in (internals)Contexts section ‘Contexts’ in Internals Reference.

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 overriden 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 overriden with different spacing settings for that staff.

Spacing of ungrouped staves

Staves (such as Staff, DrumStaff, TabStaff, etc.) are contexts that can contain one or more voice contexts, but cannot contain any other staves.

The following properties affect the spacing of ungrouped staves:

VerticalAxisGroup properties:
- default-staff-staff-spacing
- staff-staff-spacing

These grob properties are described individually above; see Within-system spacing properties.

Additional properties are involved for staves that are part of a staff-group; see Spacing of grouped staves.

The following example shows how the default-staff-staff-spacing property can affect the spacing of ungrouped staves. The same overrides applied to staff-staff-spacing would have the same effect, but would also apply in cases where the staves are combined in a group or groups.

\layout {
  \context {
    \Staff
    \override VerticalAxisGroup.default-staff-staff-spacing =
      #'((basic-distance . 8)
         (minimum-distance . 7)
         (padding . 1))
  }
}

<<
  % The very low note here needs more room than 'basic-distance
  % can provide, so the distance between this staff and the next
  % is determined by 'padding.
  \new Staff { b,2 r | }

  % Here, 'basic-distance provides enough room, and there is no
  % need to compress the space (towards 'minimum-distance) to make
  % room for anything else on the page, so the distance between
  % this staff and the next is determined by 'basic-distance.
  \new Staff { \clef bass g2 r | }

  % By setting 'padding to a negative value, staves can be made to
  % collide.  The lowest acceptable value for 'basic-distance is 0.
  \new Staff \with {
    \override VerticalAxisGroup.default-staff-staff-spacing =
      #'((basic-distance . 3.5)
         (padding . -10))
  } { \clef bass g2 r | }
  \new Staff { \clef bass g2 r | }
>>

Spacing of grouped staves

In orchestral and other large scores, it is common to place staves in groups. The space between groups is typically larger than the space between staves of the same group.

Staff-groups (such as StaffGroup, ChoirStaff, etc.) are contexts that can contain one or more staves simultaneously.

The following properties affect the spacing of staves inside staff-groups:

VerticalAxisGroup properties:
- staff-staff-spacing
StaffGrouper properties:
- staff-staff-spacing
- staffgroup-staff-spacing

These grob properties are described individually above; see Within-system spacing properties.

The following example shows how properties of the StaffGrouper grob can affect the spacing of grouped staves:

\layout {
  \context {
    \Score
    \override StaffGrouper.staff-staff-spacing.padding = #0
    \override StaffGrouper.staff-staff-spacing.basic-distance = #1
  }
}

<<
  \new PianoStaff \with {
    \override StaffGrouper.staffgroup-staff-spacing.basic-distance = #20
  } <<
    \new Staff { c'1 }
    \new Staff { c'1 }
  >>

  \new StaffGroup <<
    \new Staff { c'1 }
    \new Staff { c'1 }
  >>
>>

Spacing of non-staff lines

Non-staff lines (such as Lyrics, ChordNames, etc.) are contexts whose layout objects are engraved like staves (i.e., in horizontal lines within systems). Specifically, non-staff lines are non-staff contexts that contain the (internals)Axis_group_engraver section ‘Axis_group_engraver’ in Internals Reference.

The following properties affect the spacing of non-staff lines:

VerticalAxisGroup properties:
- staff-affinity
- nonstaff-relatedstaff-spacing
- nonstaff-nonstaff-spacing
- nonstaff-unrelatedstaff-spacing

These grob properties are described individually above; see Within-system spacing properties.

The following example shows how the nonstaff-nonstaff-spacing property can affect the spacing of consecutive non-staff lines. Here, by setting the stretchability key to a very high value, the lyrics are able to stretch much more than usual:

\layout {
  \context {
    \Lyrics
    \override VerticalAxisGroup.nonstaff-nonstaff-spacing.stretchability = #1000
  }
}

\new StaffGroup
<<
  \new Staff \with {
    \override VerticalAxisGroup.staff-staff-spacing = #'((basic-distance . 30))
  } { c'1 }
  \new Lyrics \with {
    \override VerticalAxisGroup.staff-affinity = #UP
  } \lyricmode { up }
  \new Lyrics \with {
    \override VerticalAxisGroup.staff-affinity = #CENTER
  } \lyricmode { center }
  \new Lyrics \with {
    \override VerticalAxisGroup.staff-affinity = #DOWN
  } \lyricmode { down }
  \new Staff { c'1 }
>>

4.4.2 Explicit staff and system positioning

One way to understand the flexible vertical spacing mechanisms explained above is as a collection of settings that control the amount of vertical padding between staves and systems.

It is possible to approach vertical spacing in a different way using NonMusicalPaperColumn.line-break-system-details. While the flexible vertical spacing mechanisms specify vertical padding, NonMusicalPaperColumn.line-break-system-details can specify exact vertical positions on the page.

NonMusicalPaperColumn.line-break-system-details accepts an associative list of four different settings:

X-offset
Y-offset
extra-offset
alignment-distances

Grob overrides, including the overrides for NonMusicalPaperColumn below, can occur in any of three different places in an input file:

in the middle of note entry directly
in a \context block
in the \with block

When we override NonMusicalPaperColumn, we use the usual \override command in \context blocks and in the \with block. On the other hand, when we override NonMusicalPaperColumn in the middle of note entry, use the special \overrideProperty command. Here are some example NonMusicalPaperColumn overrides with the special \overrideProperty command:

\overrideProperty NonMusicalPaperColumn.line-break-system-details
  #'((X-offset . 20))

\overrideProperty NonMusicalPaperColumn.line-break-system-details
  #'((Y-offset . 40))

\overrideProperty NonMusicalPaperColumn.line-break-system-details
  #'((X-offset . 20)
     (Y-offset . 40))

\overrideProperty NonMusicalPaperColumn.line-break-system-details
  #'((alignment-distances . (15)))

\overrideProperty NonMusicalPaperColumn.line-break-system-details
  #'((X-offset . 20)
     (Y-offset . 40)
     (alignment-distances . (15)))

To understand how each of these different settings work, we begin by looking at an example that includes no overrides at all.

\header { tagline = ##f }
\paper { left-margin = 0\mm }
\book {
  \score {
    <<
      \new Staff <<
        \new Voice {
          s1*5 \break
          s1*5 \break
          s1*5 \break
        }
        \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
      >>
      \new Staff {
        \repeat unfold 15 { d'4 d' d' d' }
      }
    >>
  }
}

This score isolates both line-breaking and page-breaking information in a dedicated voice. This technique of creating a breaks voice will help keep layout separate from music entry as our example becomes more complicated. Also see Breaks.

By using explicit \break commands, the music is divided into five measures per line. Vertical spacing is from LilyPond’s own defaults but the vertical startpoint of each system is set explicitly using the Y-offset pair in the line-break-system-details attribute of the NonMusicalPaperColumn grob:

\header { tagline = ##f }
\paper { left-margin = 0\mm }
\book {
  \score {
    <<
      \new Staff <<
        \new Voice {
          \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
            #'((Y-offset . 0))
          s1*5 \break
          \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
            #'((Y-offset . 40))
          s1*5 \break
          \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
            #'((Y-offset . 60))
          s1*5 \break
        }
        \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
      >>
      \new Staff {
        \repeat unfold 15 { d'4 d' d' d' }
      }
    >>
  }
}

Note that line-break-system-details takes an associative list of potentially many values, but that we set only one value here. Note, too, that the Y-offset property here determines the exact vertical position on the page at which each new system will render.

In contrast to the absolute positioning available through Y-offset and X-offset, relative positioning is possible with the extra-offset property of line-break-system-details. Placement is relative to the default layout or to the absolute positioning created by setting X-offset and Y-offset. The property extra-offset accepts a pair consisting of displacements along the X-axis and Y-axis.

\header { tagline = ##f }
\paper { left-margin = 0\mm }
\book {
  \score {
    <<
      \new Staff <<
        \new Voice {
          s1*5 \break
          \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
            #'((extra-offset . (0 . 10)))
          s1*5 \break
          \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
            #'((extra-offset . (0 . 10)))
          s1*5 \break
        }
        \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
      >>
      \new Staff {
        \repeat unfold 15 { d'4 d' d' d' }
      }
    >>
  }
}

Now that we have set the vertical startpoint of each system explicitly, we can also set the vertical distances between staves within each system manually. We do this using the alignment-distances subproperty of line-break-system-details.

\header { tagline = ##f }
\paper { left-margin = 0\mm }
\book {
  \score {
    <<
      \new Staff <<
        \new Voice {
          \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
            #'((Y-offset . 20)
               (alignment-distances . (10)))
          s1*5 \break
          \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
            #'((Y-offset . 60)
               (alignment-distances . (15)))
          s1*5 \break
          \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
          #'((Y-offset . 85)
             (alignment-distances . (20)))
          s1*5 \break
        }
        \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
      >>
      \new Staff {
        \repeat unfold 15 { d'4 d' d' d' }
      }
    >>
  }
}

Note that here we assign two different values to the line-break-system-details attribute of the NonMusicalPaperColumn grob. Though the line-break-system-details attribute alist accepts many additional spacing parameters (including, for example, a corresponding X-offset pair), we need only set the Y-offset and alignment-distances pairs to control the vertical startpoint of every system and every staff. Finally, note that alignment-distances specifies the vertical positioning of staves but not of staff groups.

\header { tagline = ##f }
\paper { left-margin = 0\mm }
\book {
  \score {
    <<
      \new Staff <<
        \new Voice {
          \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
            #'((Y-offset . 0)
               (alignment-distances . (30 10)))
          s1*5 \break
          \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
            #'((Y-offset . 60)
               (alignment-distances . (10 10)))
          s1*5 \break
          \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
            #'((Y-offset . 100)
               (alignment-distances . (10 30)))
          s1*5 \break
        }
        \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
      >>
      \new StaffGroup <<
        \new Staff { \repeat unfold 15 { d'4 d' d' d' } }
        \new Staff { \repeat unfold 15 { e'4 e' e' e' } }
      >>
    >>
  }
}

Some points to consider:

When using alignment-distances, lyrics and other non-staff lines do not count as a staff.
The units of the numbers passed to X-offset, Y-offset, extra-offset and alignment-distances are interpreted as multiples of the distance between adjacent staff lines. Positive values move staves and lyrics up, negative values move staves and lyrics down.
Because the NonMusicalPaperColumn.line-break-system-details settings given here allow the positioning of staves and systems anywhere on the page, it is possible to violate paper or margin boundaries or even to print staves or systems on top of one another. Reasonable values passed to these different settings will avoid this.

4.4.3 Vertical collision avoidance

Intuitively, there are some objects in musical notation that belong to the staff and there are other objects that should be placed outside the staff. Objects belonging outside the staff include things such as rehearsal marks, text and dynamic markings (from now on, these will be called outside-staff objects). LilyPond’s rule for the vertical placement of outside-staff objects is to place them as close to the staff as possible but not so close that they collide with another object.

LilyPond uses the outside-staff-priority property to determine whether a grob is an outside-staff object: if outside-staff-priority is a number, the grob is an outside-staff object. In addition, outside-staff-priority tells LilyPond in which order the objects should be placed.

First, LilyPond places all the objects that do not belong outside the staff. Then it sorts the outside-staff objects according to their outside-staff-priority (in increasing order). One by one, LilyPond takes the outside-staff objects and places them so that they do not collide with any objects that have already been placed. That is, if two outside-staff grobs are competing for the same space, the one with the lower outside-staff-priority will be placed closer to the staff.

A listing of outside-staff-priorities may be found in (learning)The outside-staff-priority property section ‘The outside-staff-priority property’ in Learning Manual.

\relative c'' {
  c4_"Text"\pp
  r2.
  \once \override TextScript.outside-staff-priority = #1
  c4_"Text"\pp % this time the text will be closer to the staff
  r2.
  % by setting outside-staff-priority to a non-number,
  % we disable the automatic collision avoidance
  \once \override TextScript.outside-staff-priority = ##f
  \once \override DynamicLineSpanner.outside-staff-priority = ##f
  c4_"Text"\pp % now they will collide
}

The vertical padding around outside-staff objects can be controlled with outside-staff-padding.

\relative {
  \once \override TextScript.outside-staff-padding = #0
  a'4-"outside-staff-padding = #0"
  \once \override TextScript.outside-staff-padding = #3
  d-"outside-staff-padding = #3"
  c-"default outside-staff-padding"
  b-"default outside-staff-padding"
  R1
}

By default, outside-staff objects are placed so they avoid a horizontal collision with previously-positioned grobs. This can lead to situations in which objects are placed close to each other horizontally. As shown in the example below, setting outside-staff-horizontal-padding increases the horizontal spacing required, and in this case moves the text up to prevent it from getting too close to the ledger lines.

\relative {
  c''4^"Word" c c''2
  R1
  \once \override TextScript.outside-staff-horizontal-padding = #1
  c,,4^"Word" c c''2
}

4.4 Vertical spacing

4.4.1 Flexible vertical spacing within systems

Within-system spacing properties

Properties of the `VerticalAxisGroup` grob

Properties of the `StaffGrouper` grob

See also

Spacing of ungrouped staves

See also

Spacing of grouped staves

See also

Spacing of non-staff lines

See also

4.4.2 Explicit staff and system positioning

See also

4.4.3 Vertical collision avoidance

See also

4.4 Vertical spacing

4.4.1 Flexible vertical spacing within systems

Within-system spacing properties

Properties of the VerticalAxisGroup grob

Properties of the StaffGrouper grob

See also

Spacing of ungrouped staves

See also

Spacing of grouped staves

See also

Spacing of non-staff lines

See also

4.4.2 Explicit staff and system positioning

See also

4.4.3 Vertical collision avoidance

See also

Properties of the `VerticalAxisGroup` grob

Properties of the `StaffGrouper` grob