33.1 Contexts explained

Contexts are arranged hierarchically.


33.1.1 Output definitions – blueprints for contexts

This section explains the relevance of output definitions when working with contexts. Examples for actual output definitions are given later (see Changing all contexts of the same type).

While music written in a file may refer to context types and names, contexts are created only when the music is actually being interpreted. LilyPond interprets music under control of an output definition and may do so for several different output definitions, resulting in different output. The output definition relevant for printing music is specified using \layout.

A much simpler output definition used for producing MIDI output is specified using \midi. Several other output definitions are used by LilyPond internally, like when using the part combiner (Automatic part combining) or creating music quotes (Quoting other voices).

Output definitions define the relation between contexts as well as their respective default settings. While most changes are usually made inside of a \layout block, MIDI-related settings only have an effect when made within a \midi block.

Some settings affect several outputs: for example, if autoBeaming is turned off in some context, beams count as melismata for the purpose of matching music to lyrics, see Automatic syllable durations. This matching is done both for printed output as well as for MIDI – if changes made to autoBeaming within a context definition of a \layout block are not repeated in the corresponding \midi block, lyrics and music will get out of sync in MIDI output.

See also

Installed Files: ly/engraver-init.ly. ly/performer-init.ly.


33.1.2 Score – the master of all contexts

This is the top-level notation context.12 No other context can contain a Score context. This context handles the administration of time signatures. It also makes sure that items such as clefs, time signatures, and key signatures are aligned across staves.

You cannot explicitly instantiate a Score context (since it is not contained in any other context). It is instantiated automatically when an output definition (a \score or \layout block) is processed.

An alias called Timing is established by the Timing_translator in whatever context it is initialized, and the timing variables are then copied from wherever Timing had been previously established. The alias at Score level provides a target for initializing Timing variables in layout definitions before any Timing_translator has been run.


33.1.3 Top-level contexts – staff containers

StaffGroup

Connect staves vertically by adding a bracket on the left side. The bar lines of the contained staves are connected vertically, too.

ChoirStaff

Identical to StaffGroup except that the bar lines of the contained staves are not connected vertically.

GrandStaff

Connect staves vertically by adding a brace on the left side. The bar lines of the contained staves are connected vertically, too.

PianoStaff

Just like GrandStaff, but the staves are only removed together, never separately.

OneStaff

Provides a common axis for the contained staves, making all of them appear in the same vertical space. This can be useful for typesetting staves of different types in immediate succession or for temporarily changing the character of one staff or overlaying it with a different one. Often used with \stopStaff and \startStaff for best results.

VaticanaScore

Top-level context replacing Score for Gregorian chant notated in Vaticana style. Compared to Score, it changes the staff line color to red, uses packed spacing, and removes bar numbers.

ChordGridScore

Top-level context replacing Score in chord grid notation. Compared to Score, it uses proportional notation, and has a few other settings like removing bar numbers.

StandaloneRhythmScore

A Score-level context for use by \markup \rhythm.


33.1.4 Intermediate-level contexts – staves

Staff

Handles clefs, bar lines, keys, accidentals. It can contain Voice contexts.

RhythmicStaff

Like Staff but for printing rhythms. Pitches are ignored when engraving; the notes are printed on one line. The MIDI rendition retains pitches unchanged.

TabStaff

Context for generating tablature. It accepts only TabVoice contexts and handles the line spacing, the tablature clef, etc., properly.

DrumStaff

Handles typesetting for percussion. Can contain DrumVoice.

VaticanaStaff

A kind of Staff for typesetting Gregorian chant in a notational style approximating Editio Vaticana.

MensuralStaff

Same as Staff context, except that it is accommodated for typesetting a piece in mensural style.

PetrucciStaff

A kind of Staff approximating the mensural typesetting of Ottaviano Petrucci’s Harmonices Musices Odhecaton (Venice, 1501).

KievanStaff

Same as Staff context, except that it is accommodated for typesetting a piece in Kievan style.

GregorianTranscriptionStaff

A staff for notating Gregorian chant in modern style.

ChordGrid

Creates chord grid notation. This context is always part of a ChordGridScore context.

StandaloneRhythmStaff

A Staff-level context for use by \markup \rhythm.

FretBoards

A context for displaying fret diagrams.

Devnull

Silently discard all musical information given to this context.


33.1.5 Bottom-level contexts – voices

Voice-level contexts initialize certain properties and start appropriate engravers. A bottom-level context is one without \defaultchild. While it is possible to let it accept/contain subcontexts, they can only be created and entered explicitly.

Voice

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 require multiple voices on the same staff.

VaticanaVoice

A kind of Voice for typesetting Gregorian chant in a notational style approximating Editio Vaticana.

MensuralVoice

Same as Voice context, except that it is accommodated for typesetting a piece in mensural style.

PetrucciVoice

A kind of Voice approximating the mensural typesetting of Ottaviano Petrucci’s Harmonices Musices Odhecaton (Venice, 1501).

KievanVoice

Same as Voice context, except that it is accommodated for typesetting a piece in Kievan style.

GregorianTranscriptionVoice

A voice for notating Gregorian chant in modern style.

Lyrics

Corresponds to a voice with lyrics. Handles the printing of a single line of lyrics.

VaticanaLyrics

Same as Lyrics context, except that it provides a hyphenation style (a single, flush-left hyphen between two syllables) as used in the notational style of Editio Vaticana.

GregorianTranscriptionLyrics

A lyrics context for notating Gregorian chant in modern style.

DrumVoice

A voice on a percussion staff.

FiguredBass

The context in which BassFigure grobs are created from input entered in \figuremode mode.

TabVoice

The voice context used within a TabStaff context. Usually left to be created implicitly.

CueVoice

A voice context used to render notes of a reduced size, intended primarily for adding cue notes to a staff, see Formatting cue notes. Usually left to be created implicitly.

ChordNames

Typesets chord names.

NoteNames

Typesets note names.

NullVoice

For aligning lyrics without printing notes.

Devnull

Silently discard all musical information given to this context.

Dynamics

Holds a single line of dynamics centered between the staves surrounding this context.

StandaloneRhythmVoice

A Voice-level context for use by \markup \rhythm.

Bottom

This is a generic bottom-level context, accepted by all intermediate-level contexts. It can be used for situations where the same music should appear, say, in a Staff and a TabStaff context.


Footnotes

(12)

There exists a context called Global that is even one level higher than Score, and which is the hard-coded entry point for LilyPond. However, this is not meant to be modified; you will need this context only if you are going to implement an engraver in Scheme and can be safely ignored otherwise.


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