The \tweak and \offset commands

The final tweaking commands of LilyPond are \tweak and \offset. They 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.

Note that \offset can be used as an replacement for \override, too; it also has more syntax forms. See The offset command, for all the details.

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 and \offset commands operate in a different way. They act on the immediately following item in the input stream. In their simplest forms, they are 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
}

Let’s now try to change the vertical position of the \breathe symbol. By default, LilyPond computes a vertical distance from the middle line automatically. If we would like to move it up by two units, say, \offset is the right command. With \tweak it would be necessary to find the correct position manually by trial and error.

\relative c'' {
  c4
  \breathe
  c4
  \offset Y-offset 2 \breathe
  c2
  \tweak Y-offset 4 \breathe
}

Obviously, \offset only works for values that actually have a numeric value. There are more restrictions to that what can be changed; again, please refer to The offset command, for more details.

Note that the syntax of \tweak and \offset 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 and \offset commands is

\tweak layout-property value
\offset layout-property value

\tweak and \offset 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"

Both \tweak and \offset 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 or \offset 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 and \offset commands can be described as

\tweak LayoutObject.layout-property value
\offset 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: Tweak and single, The offset command

<< Back to Documentation Index

LilyPond Learning Manual v2.25.15 (development-branch).