4.1 Tweaking basics

4.1.1 Introduction to tweaks

‘Tweaking’ is a LilyPond term for the various methods available to the user for modifying the actions taken during interpretation of the input file and modifying the appearance of the printed output. Some tweaks are very easy to use; others are more complex. But taken together the methods available for tweaking permit almost any desired appearance of the printed music to be achieved.

In this section we cover the basic concepts required to understand tweaking. Later we give a variety of ready-made commands which can simply be copied to obtain the same effect in your own scores, and at the same time we show how these commands may be constructed so that you may learn how to develop your own tweaks.

Before starting on this Chapter you may wish to review the section Contexts and engravers, as Contexts, Engravers, and the Properties contained within them are fundamental to understanding and constructing Tweaks.

4.1.2 Objects and interfaces

Tweaking involves modifying the internal operation and structures of the LilyPond program, so we must first introduce some terms which are used to describe those internal operations and structures.

The term ‘Object’ is a generic term used to refer to the multitude of internal structures built by LilyPond during the processing of an input file. So when a command like \new Staff is encountered a new object of type Staff is constructed. That Staff object then holds all the properties associated with that particular staff, for example, its name and its key signature, together with details of the engravers which have been assigned to operate within that staff’s context. Similarly, there are objects to hold the properties of all other contexts, such as Voice objects, Score objects, Lyrics objects, as well as objects to represent all notational elements such as bar lines, note heads, ties, dynamics, etc. Every object has its own set of property values.

Some types of object are given special names. Objects which represent items of notation on the printed output such as note heads, stems, slurs, ties, fingering, clefs, etc are called ‘Layout objects’, often known as ‘Graphical Objects’, or ‘Grobs’ for short. These are still objects in the generic sense above, and so they too all have properties associated with them, such as their position, size, color, etc.

Some layout objects are still more specialized. Phrasing slurs, crescendo hairpins, ottava marks, and many other grobs are not localized in a single place – they have a starting point, an ending point, and maybe other properties concerned with their shape. Objects with an extended shape like these are called ‘Spanners’.

Spanners cannot be tweaked after their creation. This includes both StaffSymbol and LedgerLineSpanner which continue throughout the score, except if they are terminated by the \stopStaff command and then recreated using \startStaff command.

What is more, there are ‘abstract’ grobs which do not print anything of their own, but rather collect, position and manage other grobs. Common examples for this are DynamicLineSpanner, BreakAlignment, NoteColumn, VerticalAxisGroup, NonMusicalPaperColumn and similar. We will see how some of these are used later.

It remains to explain what ‘Interfaces’ are. Many objects, even though they are quite different, share common features which need to be processed in the same way. For example, all grobs have a color, a size, a position, etc, and all these properties are processed in the same way during LilyPond’s interpretation of the input file. To simplify these internal operations these common actions and properties are grouped together in an object called a grob-interface. There are many other groupings of common properties like this, each one given a name ending in interface. In total there are over 100 such interfaces. We shall see later why this is of interest and use to the user.

These, then, are the main terms relating to objects which we shall use in this chapter.

4.1.3 Naming conventions of objects and properties

We met some object naming conventions previously, in Contexts and engravers. Here for reference is a list of the most common object and property types together with the conventions for naming them and a couple of examples of some real names. We have used ‘A’ to stand for any capitalized alphabetic character and ‘aaa’ to stand for any number of lower-case alphabetic characters. Other characters are used verbatim.

As we shall see shortly, the properties of different types of object are modified by different commands, so it is useful to be able to recognize the types of objects and properties from their names.

See also

Notation Reference: (notation)Modifying properties section ‘Modifying properties’ in Notation Reference.

4.1.4 Tweaking methods

The \override command

We have already met the commands \set and \with, used to change the properties of contexts and to remove and add engravers, in Modifying context properties, and Adding and removing engravers. We must now introduce some more important commands.

The command to change the properties of layout objects is \override. Because this command has to modify internal properties deep within LilyPond its syntax is not as simple as the commands you have used so far. It needs to know precisely which property of which object in which context has to be modified, and what its new value is to be. Let’s see how this is done.

The general syntax of this command is:

\override Context.LayoutObject.layout-property = #value

This will set the property with the name layout-property of the layout object with the name LayoutObject, which is a member of the Context context, to the value value.

The Context may be omitted (and usually is) when the required context is unambiguously implied and is one of lowest level contexts, i.e., Voice, ChordNames or Lyrics, and we shall omit it in many of the following examples. We shall see later when it must be specified.

Later sections deal comprehensively with properties and their values, see Types of properties. But in this section we shall use just a few simple properties and values which are easily understood in order to illustrate the format and use of these commands.

LilyPond’s primary expressions are musical items like notes and durations, as well as strings and markups. More specific expressions like numbers, symbols and lists are processed in ‘Scheme mode’, which is invoked by prefixing the value with ‘#’. For more information about Scheme mode, see (extending)LilyPond Scheme syntax section ‘LilyPond Scheme syntax’ in Extending.

\override is the most common command used in tweaking, and most of the rest of this chapter will be directed to presenting examples of how it is used. Here is a simple example to change the color of the note head:

\relative { c'4 d \override NoteHead.color = "red" e4 f | \override NoteHead.color = "green" g4 a b c | }

The \revert command

Once overridden, the property retains its new value until it is overridden again or a \revert command is encountered. The \revert command has the following syntax and causes the value of the property to revert to its original default value; note, not its previous value if several \override commands have been issued.

\revert Context.LayoutObject.layout-property

Again, just like Context in the \override command, Context is often not needed. It will be omitted in many of the following examples. Here we revert the color of the note head to the default value for the final two notes:

\relative { c'4 d \override NoteHead.color = "red" e4 f | \override NoteHead.color = "green" g4 a \revert NoteHead.color b4 c | }

The \once prefix

\override, \revert, \set, and \unset commands may be prefixed with \once. This causes such a command to be effective only during the current musical moment before the property reverts back to its previous value (this can be different from the default if another \override is still in effect). Using the same example, we can change the color of a single note like this:

\relative { c'4 d \override NoteHead.color = "red" e4 f | \once \override NoteHead.color = "green" g4 a \once \revert NoteHead.color b c | \revert NoteHead.color f2 c | }

The \once prefix may also be used in front of many predefined commands to limit their effect to one musical moment:

\relative { c'4( d) \once \slurDashed e4( f) | g4( a) \once \hideNotes b( c) | }

The \overrideProperty command

There is another form of the override command, \overrideProperty, which is occasionally required. We mention it here for completeness, but for details see (extending)Difficult tweaks section ‘Difficult tweaks’ in Extending.

The \tweak command

The final tweaking command which is available is \tweak. This should be used when several objects occur at the same musical moment, but you only want to change the properties of selected ones, such as a single note within a chord. Using \override would affect all the notes within a chord, whereas \tweak affects just the following item in the input stream.

Here’s an example. Suppose we wish to change the size of the middle note head (the E) in a C major chord. Let’s first see what \once \override would do:

\relative { <c' e g>4 \once \override NoteHead.font-size = #-3 <c e g>4 <c e g>4 }

We see the override affects all the note heads in the chord. This is because all the notes of a chord occur at the same musical moment, and the action of \once is to apply the override to all layout objects of the type specified which occur at the same musical moment as the \override command itself.

The \tweak command operates in a different way. It acts on the immediately following item in the input stream. In its simplest form, it is effective only on objects which are created directly from the following item, essentially note heads and articulations.

So to return to our example, the size of the middle note of a chord would be changed in this way:

\relative { <c' e g>4 <c \tweak font-size #-3 e g>4 }

Note that the syntax of \tweak is different from that of the \override command. The context should not be specified; in fact, it would generate an error to do so. Both context and layout object are implied by the following item in the input stream. Note also that an equals sign should not be present. So the simple form of the \tweak command is

\tweak layout-property #value

A \tweak command can also be used to modify just one in a series of articulations, as shown here:

a'4^"Black" -\tweak color "red" ^"Red" -\tweak color "green" _"Green"

Note that the \tweak command must be preceded by an articulation mark since the tweaked expression needs to be applied as an articulation itself. In case of multiple direction overrides (^ or _), the leftmost override wins since it is applied last.

Objects such as stems and accidentals are created later, and not directly from the following event. It is still possible to use \tweak on such indirectly created objects by explicitly naming the layout object, provided that LilyPond can trace its origin back to the original event:

<\tweak Accidental.color "red" cis''4 \tweak Accidental.color "green" es'' g''>

This long form of the \tweak command can be described as

\tweak LayoutObject.layout-property #value

The \tweak command must also be used to change the appearance of one of a set of nested tuplets which begin at the same musical moment. In the following example, the long tuplet bracket and the first of the three short brackets begin at the same musical moment, so any \override command would apply to both of them. In the example, \tweak is used to distinguish between them. The first \tweak command specifies that the long tuplet bracket is to be placed above the notes and the second one specifies that the tuplet number is to be printed in red on the first short tuplet bracket.

\relative c'' { \tweak direction #up \tuplet 3/4 { \tweak color "red" \tuplet 3/2 { c8[ c c] } \tuplet 3/2 { c8[ c c] } \tuplet 3/2 { c8[ c c] } } }

If nested tuplets do not begin at the same moment, their appearance may be modified in the usual way with \override commands:

\relative { \tuplet 3/2 { c'8[ c c] } \once \override TupletNumber.text = #tuplet-number::calc-fraction-text \tuplet 3/2 { c8[ c] c8[ c] \once \override TupletNumber.transparent = ##t \tuplet 3/2 { c8[ c c] } \tuplet 3/2 { c8[ c c] } } }

See also

Notation Reference: (notation)The tweak command section ‘The tweak command’ in Notation Reference.

The \single prefix

Suppose we wanted to emphasize particular note heads by coloring them red and increasing their size, and to make it easy suppose also we have defined a function to do this:

emphNoteHead = { \override NoteHead.color = "red" \override NoteHead.font-size = 2 } \relative { c''4 a \once \emphNoteHead f d | }

The \once prefix works fine to emphasize single notes or complete chords, but it cannot be used to emphasize a single note within a chord. Earlier we have seen how \tweak can be used to do this, see The \tweak command. But \tweak cannot be used with a function; that’s where \single comes in:

emphNoteHead = { \override NoteHead.color = "red" \override NoteHead.font-size = 2 } \relative { <c'' a \single \emphNoteHead f d>4 }

In summary, \single converts overrides into tweaks so when there are several objects at the same point in musical time (like noteheads in a chord), \single will only affect a single one, the one generated by the immediately following music expression, in contrast to \once which will affect all of those objects.

By using \single in this way any shorthand function containing just overrides may be applied to individual notes in a chord. However, \single does not convert \revert, \set or \unset into tweaks.

See also

Learning Manual: The \tweak command, Using variables for layout adjustments.

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

Outros idiomas: català, česky, deutsch, español, français, italiano, 日本語, nederlands.
Sobre seleção automática de idioma.