LilyPond Notation Reference: 4.4.1 Flexible vertical spacing within systems

[ << Spacing issues ]	[Top][Contents][Index][ ? ]			[ Changing defaults >> ]
[ < Vertical spacing ]		[ Up : Vertical spacing ]	[ Within-system spacing properties > ]

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.

[ << Spacing issues ]	[Top][Contents][Index][ ? ]			[ Changing defaults >> ]
[ < Flexible vertical spacing within systems ]		[ Up : Flexible vertical spacing within systems ]	[ Spacing of ungrouped staves > ]

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`	vertical center
`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) is stored as an alist (association list), and each 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 #'staff-staff-spacing #'basic-distance = #10
} { … }

\new Staff \with {
  \override VerticalAxisGroup #'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 #'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: 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. This replaces any settings inherited from the StaffGrouper grob of the containing staff-group, if there is one. If this is unset, and there are no StaffGrouper properties to inherit, the default-staff-staff-spacing property is used.
default-staff-staff-spacing: The settings to use for staff-staff-spacing when it is unset. This applies to ungrouped staves and to grouped staves that do not inherit settings from the StaffGrouper grob.
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.
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.
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 will be used instead for any staves in the staff-group that have it set. Also see default-staff-staff-spacing.
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 will be used instead for any staves in the staff-group that have it set. Also see default-staff-staff-spacing.

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:
- 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 staff-staff-spacing property can affect the spacing of ungrouped staves:

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

\new StaffGroup <<
  % 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 #'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
- default-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 create the VerticalAxisGroup layout object.

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

LilyPond — Notation Reference

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

LilyPond — Notation Reference

Properties of the `VerticalAxisGroup` grob

Properties of the `StaffGrouper` grob