3.3 Contexts and engravers

Contexts and engravers have been mentioned informally in earlier sections; we now must look at these concepts in more detail, as they are important in the fine-tuning of LilyPond output.

3.3.1 Contexts explained

When music is printed, many notational elements which do not appear explicitly in the input file must be added to the output. For example, compare the input and output of the following example:

\relative { cis''4 cis2. | a4 a2. | }

The input is rather sparse, but in the output, bar lines, accidentals, clef, and time signature have been added. When LilyPond interprets the input the musical information is parsed from left to right, similar to the way a performer reads the score. While reading the input, the program remembers where measure boundaries are, and which pitches require explicit accidentals. This information must be held on several levels. For example, an accidental affects only a single staff, while a bar line must be synchronized across the entire score.

Within LilyPond, these rules and bits of information are grouped in Contexts. We have already introduced the Voice context. Others are the Staff and Score contexts. Contexts are hierarchical to reflect the hierarchical nature of a musical score. For example: a Staff context can contain many Voice contexts, and a Score context can contain many Staff contexts.

Each context has the responsibility for enforcing some notation rules, creating some notation objects and maintaining the associated properties. For example, the Voice context may introduce an accidental and then the Staff context maintains the rule to show or suppress the accidental for the remainder of the measure.

As another example, the synchronization of bar lines is, by default, handled in the Score context. However, in some music we may not want the bar lines to be synchronized – consider a polymetric score in 4/4 and 3/4 time. In such cases, we must modify the default settings of the Score and Staff contexts.

For very simple scores, contexts are created implicitly, and you need not be aware of them. For larger pieces, such as anything with more than one staff, they must be created explicitly to make sure that you get as many staves as you need, and that they are in the correct order. For typesetting pieces with specialized notation, it is usual to modify existing, or even to define totally new, contexts.

In addition to the Score, Staff and Voice contexts there are contexts which fit between the score and staff levels to control staff groups, such as the PianoStaff and ChoirStaff contexts. There are also alternative staff and voice contexts, and contexts for lyrics, percussion, fret boards, figured bass, etc.

The names of all context types are formed from one or more words, each word being capitalized and joined immediately to the preceding word with no hyphen or underscore, e.g., GregorianTranscriptionStaff.

See also

Notation Reference: (notation)Contexts explained section ‘Contexts explained’ in Notation Reference.

3.3.2 Creating contexts

In an input file, a score block (introduced with a \score command) contains a single music expression; but it can also contain associated output definitions too – either a \layout block, a \midi block or both. The Score context is usually left to be created automatically when the interpretation of that music expression starts.

For scores with only one voice and one staff, the Voice and Staff contexts may also be left to be created automatically, but for more complex scores it is necessary to create them by hand. The simplest command that does this is \new. It is prepended to a music expression, for example

\new type music-expression

where type is a context name (like Staff or Voice). This command creates a new context, and starts interpreting the music-expression within that context.

You have seen many practical examples which created new Staff and Voice contexts in earlier sections, but to remind you how these commands are used in practice, here’s an annotated real-music example:

\score { % start of single compound music expression << % start of simultaneous staves section \time 2/4 \new Staff { % create RH staff \clef "treble" \key g \minor \new Voice { % create voice for RH notes \relative { % start of RH notes d''4 ees16 c8. | d4 ees16 c8. | } % end of RH notes } % end of RH voice } % end of RH staff \new Staff << % create LH staff; needs two simultaneous voices \clef "bass" \key g \minor \new Voice { % create LH voice one \voiceOne \relative { % start of LH voice one notes g8 <bes d> ees, <g c> | g8 <bes d> ees, <g c> | } % end of LH voice one notes } % end of LH voice one \new Voice { % create LH voice two \voiceTwo \relative { % start of LH voice two notes g4 ees | g4 ees | } % end of LH voice two notes } % end of LH voice two >> % end of LH staff >> % end of simultaneous staves section } % end of single compound music expression

(Note how all the statements which open a block with either a curly bracket, {, or double angle brackets, <<, are indented by two further spaces, and the corresponding closing bracket is indented by exactly the same amount. While this is not required, following this practice will greatly reduce the number of ‘unmatched bracket’ errors, and is strongly recommended. It enables the structure of the music to be seen at a glance, and any unmatched brackets will be obvious. Note too how the LH staff is created using double angle brackets because it requires two voices for its music, whereas the RH staff is created with a single music expression surrounded by curly brackets because it requires only one voice.)

The \new command may also give an identifying name to the context to distinguish it from other contexts of the same type,

\new type = id music-expression

Note the distinction between the name of the context type, Staff, Voice, etc, and the identifying name of a particular instance of that type, which can be any sequence of letters invented by the user. Digits and spaces can also be used in the identifying name, but then it has to be placed in quotes, i.e. \new Staff = "MyStaff 1" music-expression. The identifying name is used to refer back to that particular instance of a context. We saw this in use in the section on lyrics, see Voices and vocals.

See also

Notation Reference: (notation)Creating and referencing contexts section ‘Creating and referencing contexts’ in Notation Reference.

3.3.3 Engravers explained

Every mark on the printed output of a score produced by LilyPond is produced by an Engraver. Thus there is an engraver to print staves, one to print note heads, one for stems, one for beams, etc, etc. In total there are over 120 such engravers! Fortunately, for most scores it is not necessary to know about more than a few, and for simple scores you do not need to know about any.

Engravers live and operate in Contexts. Engravers such as the Metronome_mark_engraver, whose action and output apply to the score as a whole, operate in the highest level context – the Score context.

The Clef_engraver and Key_engraver are to be found in every Staff Context, as different staves may require different clefs and keys.

The Note_heads_engraver and Stem_engraver live in every Voice context, the lowest level context of all.

Each engraver processes the particular objects associated with its function, and maintains the properties that relate to that function. These properties, like the properties associated with contexts, may be modified to change the operation of the engraver or the appearance of those elements in the printed score.

Engravers all have compound names formed from words which describe their function. Just the first word is capitalized, and the remainder are joined to it with underscores. Thus the Staff_symbol_engraver is responsible for creating the lines of the staff, the Clef_engraver determines and sets the pitch reference point on the staff by drawing a clef symbol.

Here are some of the most common engravers together with their function. You will see it is usually easy to guess the function from the name, or vice versa.

We shall see later how the output of LilyPond can be changed by modifying the action of Engravers.

See also

Internals reference: (internals)Engravers and Performers section ‘Engravers and Performers’ in Internals Reference.

3.3.4 Modifying context properties

Contexts are responsible for holding the values of a number of context properties. Many of them can be changed to influence the interpretation of the input and so change the appearance of the output. They are changed by the \set command. This takes the form

\set ContextName.propertyName = #value

Where the ContextName is usually Score, Staff or Voice. It may be omitted, in which case the current context (typically Voice) is assumed.

The names of context properties consist of words joined together with no hyphens or underscores, all except the first having a capital letter. Here are a few examples of some commonly used ones. There are many more.

where a Boolean is either True (#t) or False (#f), an Integer is a positive whole number, a Real is a positive or negative decimal number, and text is enclosed in double apostrophes. Note the occurrence of hash signs, (#), in two different places – as part of the Boolean value before the t or f, and before value in the \set statement. So when a Boolean is being entered you need to code two hash signs, e.g., ##t.

Before we can set any of these properties we need to know in which context they operate. Sometimes this is obvious, but occasionally it can be tricky. If the wrong context is specified, no error message is produced, but the expected action will not take place. For example, the clefGlyph clearly lives in the Staff context, since it is the staff’s clef glyph that is to be changed. In this example the first staff’s clef is printed correctly, but not the second – which prints the default treble clef instead of the expected bass (or F) clef – because we omitted the context name.

<< \new Staff \relative { \set Staff.clefGlyph = "clefs.C" c''2 c } \new Staff \relative { \set clefGlyph = "clefs.F" % Wrong! d'2 d } >>

Remember the default context name is Voice, so the second \set command set the property clefGlyph in the Voice context to clefs.F, but as LilyPond does not look for any such property in the Voice context, no further action took place. This is not an error, and no error message is logged in the log file.

Similarly, if the property name is mis-spelt no error message is produced, and clearly the expected action cannot be performed. In fact, you can set any (fictitious) ‘property’ using any name you like in any context that exists by using the \set command. But if the name is not known to LilyPond it will not cause any action to be taken. Some text editors with special support for LilyPond input files document property names with bullets when you hover them with the mouse, like JEdit with LilyPondTool, or highlight unknown property names differently, like ConTEXT. If you do not use an editor with such features, it is recommended to check the property name in the Internals Reference: see (internals)Tunable context properties section ‘Tunable context properties’ in Internals Reference, or (internals)Contexts section ‘Contexts’ in Internals Reference.

The clefGlyph property will take effect only if it is set in the Staff context, but some properties can be set in more than one context. For example, the property extraNatural is by default set to ##t (true) for all staves. If it is set to ##f (false) in one particular Staff context it applies just to the accidentals on that staff. If it is set to false in the Score context it applies to all staves.

So this turns off extra naturals in one staff:

<< \new Staff \relative { aeses'2 aes } \new Staff \relative { \set Staff.extraNatural = ##f aeses'2 aes } >>

and this turns them off in all staves:

<< \new Staff \relative { aeses'2 aes } \new Staff \relative { \set Score.extraNatural = ##f aeses'2 aes } >>

As another example, if clefTransposition is set in the Score context this immediately changes the value of the transposition in all current staves and sets a new default value which will be applied to all staves.

The opposite command, \unset, effectively removes the property from the context, which causes most properties to revert to their default value. Usually \unset is not required as a new \set command will achieve what is wanted.

The \set and \unset commands can appear anywhere in the input file and will take effect from the time they are encountered until the end of the score or until the property is \set or \unset again. Let’s try changing the font size, which affects the size of the note heads (among other things) several times. The change is from the default value, not the most recently set value.

\relative { c'4 d % make note heads smaller \set fontSize = #-4 e4 f | % make note heads larger \set fontSize = #2.5 g4 a % return to default size \unset fontSize b4 c | }

We have now seen how to set the values of several different types of property. Note that integers and numbers are always preceded by a hash sign, #, while a true or false value is specified by ##t and ##f, with two hash signs. A text property should be enclosed in double quotation signs, as above, although we shall see later that text can actually be specified in a much more general way by using the very powerful \markup command.

Setting context properties with \with

The default value of context properties may be set at the time the context is created. Sometimes this is a clearer way of setting a property value if it is to remain fixed for the duration of the context. When a context is created with a \new command it may be followed immediately by a \with { … } block in which the default property values are set. For example, if we wish to suppress the printing of extra naturals for the duration of a staff we would write:

\new Staff \with { extraNatural = ##f }

like this:

<< \new Staff { \relative { gisis'4 gis aeses aes } } \new Staff \with { extraNatural = ##f } { \relative { gisis'4 gis aeses aes } } >>

Properties set in this way may still be changed dynamically using \set and returned to the default value set in the \with block with \unset.

So if the fontSize property is set in a \with clause it sets the default value of the font size. If it is later changed with \set, this new default value may be restored with the \unset fontSize command.

Setting context properties with \context

The values of context properties may be set in all contexts of a particular type, such as all Staff contexts, with a single command. The context type is identified by using its type name, like Staff, prefixed by a back-slash: \Staff. The statement which sets the property value is the same as that in a \with block, introduced above. It is placed in a \context block within a \layout block. Each \context block will affect all contexts of the type specified throughout the \score or \book block in which the \layout block appears. Here is an example to show the format:

\score { \new Staff { \relative { cisis''4 e d cis } } \layout { \context { \Staff extraNatural = ##t } } }

If the property override is to be applied to all staves within the score:

\score { << \new Staff { \relative { gisis'4 gis aeses aes } } \new Staff { \relative { gisis'4 gis aeses aes } } >> \layout { \context { \Score extraNatural = ##f } } }

Context properties set in this way may be overridden for particular instances of contexts by statements in a \with block, and by \set commands embedded in music statements.

See also

Notation Reference: (notation)Changing context default settings section ‘Changing context default settings’ in Notation Reference. (notation)The set command section ‘The set command’ in Notation Reference.

Internals Reference: (internals)Contexts section ‘Contexts’ in Internals Reference, (internals)Tunable context properties section ‘Tunable context properties’ in Internals Reference.

3.3.5 Adding and removing engravers

We have seen that contexts each contain several engravers, each of which is responsible for producing a particular part of the output, like bar lines, staves, note heads, stems, etc. If an engraver is removed from a context, it can no longer produce its output. This is a crude way of modifying the output, but it can sometimes be useful.

Changing a single context

To remove an engraver from a single context we use the \with command placed immediately after the context creation command, as in the previous section.

As an illustration, let’s repeat an example from the previous section with the staff lines removed. Remember that the staff lines are produced by the Staff_symbol_engraver.

\new Staff \with { \remove "Staff_symbol_engraver" } \relative { c'4 d \set fontSize = #-4 % make note heads smaller e4 f | \set fontSize = #2.5 % make note heads larger g4 a \unset fontSize % return to default size b4 c | }

Engravers can also be added to individual contexts. The command to do this is

\consists Engraver_name,

placed inside a \with block. Some vocal scores have an ambitus placed at the beginning of a staff to indicate the range of notes in that staff – see (music-glossary)ambitus section ‘ambitus’ in Music Glossary. The ambitus is produced by the Ambitus_engraver, which is not normally included in any context. If we add it to the Voice context, it calculates the range from that voice only:

\new Staff << \new Voice \with { \consists "Ambitus_engraver" } { \relative { \voiceOne c''4 a b g } } \new Voice { \relative { \voiceTwo c'4 e d f } } >>

but if we add the ambitus engraver to the Staff context, it calculates the range from all the notes in all the voices on that staff:

\new Staff \with { \consists "Ambitus_engraver" } << \new Voice { \relative { \voiceOne c''4 a b g } } \new Voice { \relative { \voiceTwo c'4 e d f } } >>

Changing all contexts of the same type

The examples above show how to remove or add engravers to individual contexts. It is also possible to remove or add engravers to every context of a specific type by placing the commands in the appropriate context in a \layout block. For example, if we wanted to show an ambitus for every staff in a four-staff score, we could write

\score { << \new Staff { \relative { c''4 a b g } } \new Staff { \relative { c'4 a b g } } \new Staff { \clef "G_8" \relative { c'4 a b g } } \new Staff { \clef "bass" \relative { c4 a b g } } >> \layout { \context { \Staff \consists "Ambitus_engraver" } } }

The values of context properties may also be set for all contexts of a particular type by including the \set command in a \context block in the same way.

See also

Notation Reference: (notation)Modifying context plug-ins section ‘Modifying context plug-ins’ in Notation Reference, (notation)Changing context default settings section ‘Changing context default settings’ in Notation Reference.

Known issues and warnings

The Stem_engraver and Beam_engraver attach their objects to note heads. If the Note_heads_engraver is removed no note heads are produced and therefore no stems or beams are created either.

This document was generated by gub on July 13, 2020 using texi2html 1.82.

Other languages: català, česky, deutsch, español, français, magyar, italiano, 日本語, nederlands.
About automatic language selection.