[ << Musical notation ]	[Top][Contents][Index]	[ Specialist notation >> ]
[ < Coloring objects ]	[ Up : Inside the staff ]	[ Parentheses > ]

---

Staff highlights

For analytical or pedagogical purposes, it may be useful to “highlight” musical passages, for example in order to show local tonality. This can be done using the \staffHighlight command, which expects a color. For all ways to enter colors, see section Coloring objects. The highlight is terminated using \stopStaffHighlight.

\relative {
  \time 2/4
  c'4 4
  \staffHighlight "lightsteelblue"
  g'8( fis g4)-.
  \stopStaffHighlight
  c2
}

If there are consecutive highlights, it is not necessary to write \stopStaffHighlight, as \staffHighlight also implicitly terminates the current highlight, if any. Similarly, it is not necessary to add \stopStaffHighlight at the end of the piece. This is particularly handy if every measure is to be highlighted.

\relative {
  \time 2/4
  \staffHighlight "lightpink"
  c'4 4
  \staffHighlight "lightsteelblue"
  g'8( fis g4)-.
  \staffHighlight "lightpink"
  c2
}

By default, staves are highlighted separately.

music = {
  \time 2/4
  \staffHighlight "lightpink"
  c'4 4
  \staffHighlight "lightsteelblue"
  g'8( fis g4)-.
  \staffHighlight "lightpink"
  c2
}

<<
  \new Staff \music
  \new Staff \music
>>

However, several staves can be highlighted together by moving Staff_highlight_engraver to a higher context than Staff (or RhythmicStaff, or similar). This is done using the \consists and \remove commands; See section Modifying context plug-ins for more information. For example, if the engraver is moved to Score, the highlights are shared by all staves.

\layout {
  \context {
    \Staff
    \remove Staff_highlight_engraver
  }
  \context {
    \Score
    \consists Staff_highlight_engraver
  }
}

music = {
  \time 2/4
  \staffHighlight "lightpink"
  c'4 4
  \staffHighlight "lightsteelblue"
  g'8( fis g4)-.
  \staffHighlight "lightpink"
  c2
}

<<
  \new Staff \music
  \new Staff \music
>>

Staff_highlight_engraver may also be moved to intermediate contexts such as StaffGroup.

music = {
  \time 2/4
  \staffHighlight "lightpink"
  c'4 4
  \staffHighlight "lightsteelblue"
  g'8( fis g4)-.
  \staffHighlight "lightpink"
  c2
}

<<
  \new StaffGroup \with { \consists Staff_highlight_engraver } <<
    \new Staff \with { \remove Staff_highlight_engraver } \music
    \new Staff \with { \remove Staff_highlight_engraver } \music
  >>
  \new Staff \music
>>

The StaffHighlight.shorten-pair property may be used to tweak the horizontal start and end of the highlight span.

{
  c'1
  \once \override Staff.StaffHighlight.shorten-pair = #'(1.0 . 1.0)
  \staffHighlight lightsteelblue
  c'1
}

Predefined commands

\staffHighlight, \stopStaffHighlight.

See also

Notation Reference: Coloring objects, Modifying context plug-ins.

Internals Reference: StaffHighlight, staff-highlight-interface, Staff_highlight_engraver, StaffHighlightEvent, staff-highlight-event.

Known issues and warnings

The behavior of highlights may not be what is expected at start repeat bar lines. The shorten-pair property demonstrated above can be used to work around this issue.

{
  \staffHighlight "lightsteelblue"
  c'1
  \stopStaffHighlight
  \repeat volta 2 { c'1 }
  c'1
}

---

[ << Musical notation ]	[Top][Contents][Index]	[ Specialist notation >> ]
[ < Coloring objects ]	[ Up : Inside the staff ]	[ Parentheses > ]

<< Back to Documentation Index

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