LilyPond snippets: Contexts and engravers

# Contexts and engravers

These snippets illustrate the Notation Reference, section Changing defaults.

See also Learning Manual, section Contexts and engravers.

## Adding a figured bass above or below the notes

When writing a figured bass, here’s a way to specify if you want your figures to be placed above or below the bass notes, by defining the `BassFigureAlignmentPositioning #'direction` property (exclusively in a `Staff` context). Choices are `#UP` (or `#1`), `#CENTER` (or `#0`) and `#DOWN` (or `#-1`).

As you can see here, this property can be changed as many times as you wish. Use `\once \override` if you don’t want the tweak to apply to the whole score.

    bass = {
      \clef bass
      g4 b, c d
      e d8 c d2
    }
    continuo = \figuremode {
      <_>4 <6>8
      \once \override Staff.BassFigureAlignmentPositioning #'direction = #CENTER
      <5/>8 <_>4
      \override Staff.BassFigureAlignmentPositioning #'direction = #UP
      <_+>4 <6>
      \set Staff.useBassFigureExtenders = ##t
      \override Staff.BassFigureAlignmentPositioning #'direction = #DOWN
      <4>4. <4>8 <_+>4
    }
    \score {
      <<
        \new Staff = bassStaff \bass
        \context Staff = bassStaff \continuo
      >>
    }

## Adding an extra staff at a line break

When adding a new staff at a line break, some extra space is unfortunately added at the end of the line before the break (to fit in a key signature change, which will never be printed anyway). The workaround is to add a setting of `Staff.explicitKeySignatureVisibility` as is shown in the example. In versions 2.10 and earlier, a similar setting for the time signatures is also required (see the example).

    \score {
      \new StaffGroup \relative c'' {
        \new Staff
        \key f \major
        c1 c^"Unwanted extra space" \break
        << { c1 | c }
           \new Staff {
             \key f \major
             \once \override Staff.TimeSignature #'stencil = ##f
             c1 | c
           }
        >>
        c1 | c^"Fixed here" \break
        << { c1 | c }
           \new Staff {
             \once \set Staff.explicitKeySignatureVisibility = #end-of-line-invisible
             % The next line is not needed in 2.11.x or later:
             \once \override Staff.TimeSignature #'break-visibility = #end-of-line-invisible
             \key f \major
             \once \override Staff.TimeSignature #'stencil = ##f
             c1 | c
           }
        >>
      }
    }

## Adding an extra staff

An extra staff can be added (possibly temporarily) after the start of a piece.

    \score {
      <<
        \new Staff \relative c'' { c1 | c | c | c | c }
        \new StaffGroup \relative c'' {
          \new Staff {
            c1 | c <<
              c1 \new Staff {
                \once \override Staff.TimeSignature #'stencil = ##f
                c1
              }
            >>
            c1
          }
        }
      >>
    }

## Changing MIDI output to one channel per voice

When outputting MIDI, the default behavior is for each staff to represent one MIDI channel, with all the voices on a staff amalgamated. This minimizes the risk of running out of MIDI channels, since there are only 16 available per track.

However, by moving the `Staff_performer` to the `Voice` context, each voice on a staff can have its own MIDI channel, as is demonstrated by the following example: despite being on the same staff, two MIDI channels are created, each with a different `midiInstrument`.

    \score {
      \new Staff <<
        \new Voice \relative c''' {
          \set midiInstrument = #"flute"
          \voiceOne
          \key g \major
          \time 2/2
          r2 g-"Flute" ~
          g fis ~
          fis4 g8 fis e2 ~
          e4 d8 cis d2
        }
        \new Voice \relative c'' {
          \set midiInstrument = #"clarinet"
          \voiceTwo
          b1-"Clarinet"
          a2. b8 a
          g2. fis8 e
          fis2 r
        }
      >>
      \layout { }
      \midi {
        \context {
          \Staff
          \remove "Staff_performer"
        }
        \context {
          \Voice
          \consists "Staff_performer"
        }
        \context {
          \Score
          tempoWholesPerMinute = #(ly:make-moment 72 2)
        }
      }
    }

## Changing time signatures inside a polymetric section using \scaleDurations

The `measureLength` property, together with `measurePosition`, determines when a bar line is needed. However, when using `\scaleDurations`, the scaling of durations makes it difficult to change time signatures. In this case, `measureLength` should be set manually, using the `ly:make-moment` callback. The second argument must be the same as the second argument of `\scaleDurations`.

    \layout {
      \context {
        \Score
        \remove "Timing_translator"
        \remove "Default_bar_line_engraver"
      }
      \context {
        \Staff
        \consists "Timing_translator"
        \consists "Default_bar_line_engraver"
      }
    }

    <<
      \new Staff {
        \scaleDurations #'(8 . 5) {
          \time 6/8
          \set Timing.measureLength = #(ly:make-moment 6 5)
          b8 b b b b b
          \time 2/4
          \set Timing.measureLength = #(ly:make-moment 4 5)
          b4 b
        }
      }
      \new Staff {
        \clef bass
        \time 2/4
        c2 d e f
      }
    >>

## Chant or psalms notation

This form of notation is used for the chant of the Psalms, where verses aren’t always the same length.

    stemOn = { \revert Staff.Stem #'transparent }
    stemOff = { \override Staff.Stem #'transparent = ##t }

    \score {
      \new Staff \with { \remove "Time_signature_engraver" }
      {
        \key g \minor
        \cadenzaOn
        \stemOff a'\breve bes'4 g'4
        \stemOn a'2 \bar "||"
        \stemOff a'\breve g'4 a'4
        \stemOn f'2 \bar "||"
        \stemOff a'\breve^\markup { \italic flexe }
        \stemOn g'2 \bar "||"
      }
    }

## Creating blank staves

To create blank staves, generate empty measures then remove the `Bar_number_engraver` from the `Score` context, and the `Time_signature_engraver`, `Clef_engraver` and `Bar_engraver` from the `Staff` context.

    #(set-global-staff-size 20)

    \score {
      {
        \repeat unfold 12 { s1 \break }
      }
      \layout {
        indent = 0\in
        \context {
          \Staff
          \remove "Time_signature_engraver"
          \remove "Clef_engraver"
          \remove "Bar_engraver"
        }
        \context {
          \Score
          \remove "Bar_number_engraver"
        }
      }
    }

    \paper {
      #(set-paper-size "letter")
      ragged-last-bottom = ##f
      line-width = 7.5\in
      left-margin = 0.5\in
      bottom-margin = 0.25\in
      top-margin = 0.25\in
    }

## Engravers one-by-one

The notation problem, creating a certain symbol, is handled by plugins. Each plugin is called an Engraver. In this example, engravers are switched on one by one, in the following order:

- note heads

- staff symbol,

- clef,

- stem,

- beams, slurs, accents,

- accidentals, bar lines, time signature, and key signature.

Engravers are grouped. For example, note heads, slurs, beams etc. form a Voice context. Engravers for key, accidental, bar, etc. form a Staff context.

You may only see the first example in this document; please download this snippet and run it from your own computer.

    %% sample music
    topVoice =  \relative c' {
      \key d\major
      es8([ g] a[ fis])
      b4
      b16[-. b-. b-. cis-.]
      d4->
    }

    botVoice =  \relative c' {
      \key d\major
      c8[( f] b[ a)]
      es4
      es16[-. es-. es-. fis-.]
      b4->
    }

    hoom =  \relative c {
      \key d \major
      \clef bass
      g8-. r
      r4
      fis8-.
      r8
      r4
      b'4->
    }

    pah =  \relative c' {
      r8 b-.
      r4
      r8 g8-.
      r16 g-. r8
      \clef treble
      fis'4->
    }

    %
    % setup for Request->Element conversion. Guru-only
    %

    MyStaff =\context {
      \type "Engraver_group"
      \name Staff

      \description "Handles clefs, bar lines, keys, accidentals.  It can contain
    @code{Voice} contexts."

      \consists "Output_property_engraver"

      \consists "Font_size_engraver"

      \consists "Volta_engraver"
      \consists "Separating_line_group_engraver"
      \consists "Dot_column_engraver"

      \consists "Ottava_spanner_engraver"
      \consists "Rest_collision_engraver"
      \consists "Piano_pedal_engraver"
      \consists "Piano_pedal_align_engraver"
      \consists "Instrument_name_engraver"
      \consists "Grob_pq_engraver"
      \consists "Forbid_line_break_engraver"
      \consists "Axis_group_engraver"

      \consists "Pitch_squash_engraver"

      \override VerticalAxisGroup #'minimum-Y-extent = #'(-6 . 6)
      extraVerticalExtent = ##f
      verticalExtent = ##f
      localKeySignature = #'()

    				% explicitly set instrument, so we don't get
    				% weird effects when doing instrument names for
    				% piano staves

      instrumentName = #'()
      shortInstrumentName = #'()

      \accepts "Voice"
    }

    MyVoice = \context {
      \type "Engraver_group"
      \name Voice

      \description "
        Corresponds to a voice on a staff.  This context handles the
        conversion of dynamic signs, stems, beams, super- and subscripts,
        slurs, ties, and rests.

        You have to instantiate this explicitly if you want to have
        multiple voices on the same staff."

      localKeySignature = #'()
      \consists "Font_size_engraver"

    				% must come before all
      \consists "Output_property_engraver"
      \consists "Arpeggio_engraver"
      \consists "Multi_measure_rest_engraver"
      \consists "Text_spanner_engraver"
      \consists "Grob_pq_engraver"
      \consists "Note_head_line_engraver"
      \consists "Glissando_engraver"
      \consists "Ligature_bracket_engraver"
      \consists "Breathing_sign_engraver"
    				% \consists "Rest_engraver"
      \consists "Grace_beam_engraver"
      \consists "New_fingering_engraver"
      \consists "Chord_tremolo_engraver"
      \consists "Percent_repeat_engraver"
      \consists "Slash_repeat_engraver"

    %{
      Must come before text_engraver, but after note_column engraver.

    %}
      \consists "Text_engraver"
      \consists "Dynamic_engraver"
      \consists "Fingering_engraver"

      \consists "Script_column_engraver"
      \consists "Rhythmic_column_engraver"
      \consists "Cluster_spanner_engraver"
      \consists "Tie_engraver"
      \consists "Tie_engraver"
      \consists "Tuplet_engraver"
      \consists "Note_heads_engraver"
      \consists "Rest_engraver"

      \consists "Skip_event_swallow_translator"
    }

    \score {
      \topVoice
      \layout {
        \context { \MyStaff }
        \context { \MyVoice }
      }
    }

    MyStaff = \context {
        \MyStaff
        \consists "Staff_symbol_engraver"
    }

    \score {
      \topVoice
      \layout {
          \context { \MyStaff }
          \context { \MyVoice }
                }
    }

    MyStaff = \context {
        \MyStaff
        \consists "Clef_engraver"
        \remove "Pitch_squash_engraver"
    }

    \score {
      \topVoice
      \layout {
        \context { \MyStaff }
        \context { \MyVoice }
      }
    }

    MyVoice = \context {
      \MyVoice
      \consists "Stem_engraver"
    }

    \score {
      \topVoice
      \layout {
        \context { \MyStaff }
        \context { \MyVoice }
      }
    }

    MyVoice = \context {
      \MyVoice
      \consists "Beam_engraver"
    }

    \score {
      \topVoice
      \layout {
        \context { \MyStaff }
        \context { \MyVoice }
      }
    }

    MyVoice= \context {
      \MyVoice
      \consists "Phrasing_slur_engraver"
      \consists "Slur_engraver"
      \consists "Script_engraver"
    }

    \score {
      \topVoice
      \layout {
        \context { \MyStaff }
        \context { \MyVoice }
      }
    }

    MyStaff = \context {
      \MyStaff
      \consists "Bar_engraver"
      \consists "Time_signature_engraver"
    }

    \score {
      \topVoice
      \layout {
        \context { \MyStaff }
        \context { \MyVoice }
      }
    }

    MyStaff = \context {
      \MyStaff
      \consists "Accidental_engraver"
      \consists "Key_engraver"
    }
    \score {
      \topVoice
      \layout {
        \context { \MyStaff }
        \context { \MyVoice }
      }
    }

## Mensurstriche layout (bar lines between the staves)

The mensurstriche-layout where the bar lines do not show on the staves but between staves can be achieved with a `StaffGroup` instead of a `ChoirStaff`. The bar line on staves is blanked out by setting the `transparent` property.

    global = {
      \override Staff.BarLine #'transparent = ##t
      s1 s
      % the final bar line is not interrupted
      \revert Staff.BarLine #'transparent
      \bar "|."
    }
    \new StaffGroup \relative c'' {
      <<
        \new Staff { << \global { c1 c } >> }
        \new Staff { << \global { c c } >> }
      >>
    }

## Nesting staves

The property `systemStartDelimiterHierarchy` can be used to make more complex nested staff groups. The command `\set StaffGroup.systemStartDelimiterHierarchy` takes an alphabetical list of the number of staves produced. Before each staff a system start delimiter can be given. It has to be enclosed in brackets and takes as much staves as the brackets enclose. Elements in the list can be omitted, but the first bracket takes always the complete number of staves. The possibilities are `SystemStartBar`, `SystemStartBracket`, `SystemStartBrace`, and `SystemStartSquare`.

    \new StaffGroup
    \relative c'' <<
      \set StaffGroup.systemStartDelimiterHierarchy
        = #'(SystemStartSquare (SystemStartBrace (SystemStartBracket a
                                 (SystemStartSquare b)  ) c ) d)
      \new Staff { c1 }
      \new Staff { c1 }
      \new Staff { c1 }
      \new Staff { c1 }
      \new Staff { c1 }
    >>

## Removing bar numbers from a score

Bar numbers can be removed entirely by removing the `Bar_number_engraver` from the `Score` context.

    \layout {
      \context {
        \Score
        \remove "Bar_number_engraver"
      }
    }

    \relative c'' {
      c4 c c c \break
      c4 c c c
    }

## Use square bracket at the start of a staff group

The system start delimiter `SystemStartSquare` can be used by setting it explicitly in a `StaffGroup` or `ChoirStaffGroup` context.

    \score {
      \new StaffGroup { <<
      \set StaffGroup.systemStartDelimiter = #'SystemStartSquare
        \new Staff { c'4 d' e' f' }
        \new Staff { c'4 d' e' f' }
      >> }
    }

## Vocal ensemble template with lyrics aligned below and above the staves

This template is basically the same as the simple "Vocal ensemble" template, with the exception that here all the lyrics lines are placed using `alignAboveContext` and `alignBelowContext`.

    global = {
      \key c \major
      \time 4/4
    }

    sopMusic = \relative c'' {
      c4 c c8[( b)] c4
    }
    sopWords = \lyricmode {
      hi hi hi hi
    }

    altoMusic = \relative c' {
      e4 f d e
    }
    altoWords = \lyricmode {
      ha ha ha ha
    }

    tenorMusic = \relative c' {
      g4 a f g
    }
    tenorWords = \lyricmode {
      hu hu hu hu
    }

    bassMusic = \relative c {
      c4 c g c
    }
    bassWords = \lyricmode {
      ho ho ho ho
    }

    \score {
      \new ChoirStaff <<
        \new Staff = women <<
          \new Voice = "sopranos" { \voiceOne << \global \sopMusic >> }
          \new Voice = "altos" { \voiceTwo << \global \altoMusic >> }
        >>
        \new Lyrics \with { alignAboveContext = women } \lyricsto sopranos \sopWords
        \new Lyrics \with { alignBelowContext = women } \lyricsto altos \altoWords
        % we could remove the line about this with the line below, since we want
        % the alto lyrics to be below the alto Voice anyway.
        % \new Lyrics \lyricsto altos \altoWords

        \new Staff = men <<
          \clef bass
          \new Voice = "tenors" { \voiceOne << \global \tenorMusic >> }
          \new Voice = "basses" { \voiceTwo << \global \bassMusic >> }
        >>
        \new Lyrics \with { alignAboveContext = men } \lyricsto tenors \tenorWords
        \new Lyrics \with { alignBelowContext = men } \lyricsto basses \bassWords
        % again, we could replace the line above this with the line below.
        % \new Lyrics \lyricsto basses \bassWords
      >>
      \layout {
        \context {
          % a little smaller so lyrics
          % can be closer to the staff
          \Staff
          \override VerticalAxisGroup #'minimum-Y-extent = #'(-3 . 3)
        }
      }
    }

#### Snippets List