LilyPond Notation Reference: 5.3.6 The \offset command

### 5.3.6 The `\offset` command

While it is possible to set grob properties to new values with the `\override`, `\tweak`, and `\overrideProperty` commands, it is often more convenient to modify such properties relative to a default value. The `\offset` command is available for this purpose.

The syntax for `\offset` is

>     [-]\offset property offsets item

The command works by adding the contents of offsets to the default setting of the property property of the grob indicated by item.

Depending on the formulation of the command, `\offset` may act as either a `\tweak` or `\override`. The variations in usage are discussed after consideration is given to grob properties that may be used with `\offset`.

#### Properties which may be offset

Many, but not all, grob properties may be offset. If property cannot be offset, the object will remain unchanged and a warning will be issued. In such cases, `\override` or `\tweak` should be used to modify the object instead.

One can work by trial and error and let the warnings be the guide to what may or may not be offset. A more systematic approach is possible, however.

The following criteria determine whether a property can be modified with `\offset`:

- The property has a ‘default setting’ in the grob’s description. Such properties are listed for each grob in All layout objects. (They are also found in ‘`scm/define-grobs.scm`’.)
- The property takes a numerical value. Numerical values include `number`, list of `number`s, `number-pair`, and `number-pair-list`. The pages at All layout objects list the type of data characteristic to each property. It is immaterial whether the default setting is a function.
- The property cannot be a ‘subproperty’ – a property residing within another property.
- Properties set to infinite values cannot be offset. There is no sensible way to offset positive and negative infinity.

The following examples consider several grob properties against the criteria outlined above.

- Properties that may be offset
  `Hairpin.height`

    This property is not a subproperty, and it is listed at Hairpin. For a value, it takes ‘dimension, in staff space’ set to `0.6666` – clearly a non-infinite `number`.

  `Arpeggio.positions`

    The page Arpeggio lists a `positions` property which accepts a ‘pair of numbers’. It defaults to `ly:arpeggio::positions` – a callback which will be evaluated during the typesetting phase to yield a pair of numbers for any given `Arpeggio` object.

- Properties that may not be offset
  `Hairpin.color`

    There is no listing for `color` at Hairpin.

  `Hairpin.circled-tip`

    The listing for `Hairpin.circled-tip` at Hairpin shows that it takes a `boolean` value. Booleans are non-numerical.

  `Stem.details.lengths`

    Though listed at Stem and defaulting to a list of `number`s, this is a ‘subproperty’. There is currently no support for ‘nested properties’.

#### `\offset` as an override

If item is a grob name like `Arpeggio` or `Staff.OttavaBracket`, the result is an `\override` of the specified grob type.

>     \offset property offsets [context.]GrobName

Note that the leading hyphen is never used with the ‘override’ form, just as it is never used with the `\override` command itself.

The following example uses the ‘override’ form to lengthen the default arpeggios shown in the first measure to cover the extent of the chords more fully. The arpeggios are stretched by a half staff space to top and bottom. Also shown is the same operation done on the first chord with an ordinary override of the `positions` property. This method is not at all expressive of the task of ‘stretching by a half staff space’, as the endpoints must be specified with absolute rather than relative coordinates. Furthermore, individual overrides would be needed for the other chords, as they vary in size and position.

>     arpeggioMusic = {
>       <c' e' g'>\arpeggio <a' c'' e''>\arpeggio
>       <d' f' a' c''>\arpeggio <c' e' g' b' d'' f'' a''>\arpeggio
>     }

>     {
>       \arpeggioMusic
>       \bar "||"
>       \offset positions #'(-0.5 . 0.5) Arpeggio
>       \arpeggioMusic
>       \bar "||"
>       \once \override Arpeggio.positions = #'(-3.5 . -0.5)
>       <c' e' g'>1\arpeggio
>       \bar "||"
>     }

In its ‘override’ usage, `\offset` may be prefaced with `\once` or `\temporary` and reverted using `\revert` with property (see functions Intermediate substitution functions). This follows from the fact that `\offset` actually creates an `\override` of property.

>     music = { c'8\< d' e' f'\! }

>     {
>       \music
>       \offset height 1 Hairpin
>       \music
>       \music
>       \revert Hairpin.height
>       \music
>       \bar "||"
>       \once \offset height 1 Hairpin
>       \music \music
>       \bar "||"
>       \override Hairpin.height = 0.2
>       \music
>       \temporary \offset height 2 Hairpin
>       \music
>       \music
>       \revert Hairpin.height
>       \music
>       \bar "||"
>     }

Also like `\override`, the ‘override’ form of `\offset` may be used with `\undo` and `\single`.

>     longStem = \offset length 6 Stem

>     {
>      \longStem c'4 c''' c' c''
>      \bar "||"
>      \undo \longStem c'4 c''' c' c''
>      \bar "||"
>      \single \longStem c'4 c''' c' c''
>      \bar "||"
>     }

#### `\offset` as a tweak

If item is a music expression such as `(` or `\arpeggio`, the result is the same music expression with a tweak applied.

>     [-]\offset [GrobName.]property offsets music-expression

The syntax of `\offset` in its ‘tweak’ form is analogous to the `\tweak` command itself, both in ordering and in the presence or absence of the leading hyphen.

The following example uses the ‘tweak’ form to adjust the vertical position of the `BreathingSign` object. Compare this with the ordinary `\tweak` command also demonstrated. The syntax is equivalent; however, the output of `\tweak` is less intuitive, since `BreathingSign.Y-offset` is calculated from the middle staff line. It is not necessary to know how `Y-offset` is calculated when using `\offset`.

>     {
>       c''4
>       \breathe
>       c''4
>       \offset Y-offset 2 \breathe
>       c''2
>       \tweak Y-offset 3 \breathe
>     }

In the previous example, the tweaked objects were created directly from the user input: the `\breathe` command was an explicit instruction to return a `BreathingSign` object. Since the focus of the command was unambiguous, there was no need to specify the object’s name. When an object is indirectly created, however, it is necessary to include the grob’s name. This is the same as for the `\tweak` command.

In the following example, the `Beam` object is lowered two staff spaces by applying `\offset` to the `positions` property.

The first application of `\offset` requires that the grob’s name be included, because nothing in the input explicitly creates the beam. In the second application, the beam is created manually with the music expression `[`; therefore, the grob’s name is not needed. (Also illustrated is a shorthand: a single `number` will be applied to both members of a `number-pair`.)

>     {
>       c''8 g'' e'' d''
>       \offset Beam.positions #'(-2 . -2)
>       c''8 g'' e'' d''
>       c''8 g'' e'' d''
>       c''8-\offset positions #-2 [ g'' e'' d'']
>     }

#### `\offset` with broken spanners

Independently modifying segments of a spanner extending over a line break or breaks is also possible. In this case, offsets takes a list of values of the property’s required data type.

The `\offset` command used in this manner is similar to the `\alterBroken` command. (See Modifying broken spanners.) In contrast with `\alterBroken`, however, the values given to `\offset` are relative, not absolute.

The following example displaces the ‘broken’ `OttavaBracket` object through its `staff-padding` property. Since the property takes a `number`, offsets is provided with a list of `number`s to account for the two segments created by the line break. The bracket piece on the first line is effectively untouched since `0` is added to its default value of `staff-padding`. The segment on the second line is raised three staff spaces from its default height. The default height happens to be `2`, though it is not necessary to know this to achieve the desired positioning.

>     {
>       \offset staff-padding #'(0 3) Staff.OttavaBracket
>       \ottava #1
>       c'''2 c'''
>       \break
>       c'''2 c'''
>     }

The following example mimics the effect of the `\shape` command by offsetting the `control-points` property of the `Slur` object. Here, offsets is a list of `number-pair-list`s, one for each slur segment. This example achieves a result identical to the corresponding illustration at Modifying shapes.

>     {
>       c'4-\offset control-points #'(
>                    ((0 . 0) (0 . 0) (0 . 0) (0 . 1))
>                    ((0.5 . 1.5) (1 . 0) (0 . 0) (0 . -1.5))
>                   ) ( f'4 g' c''
>       \break
>       d'4 c'' f' c')
>     }

#### LilyPond — Notation Reference v2.24.4 (stable-branch).