5.4 Offsets and alignments (LilyPond Learning Manual)

### 5.4 Offsets and alignments

LilyPond needs to know where each and every grob should be placed. This placement information is stored using relative coordinates: the position of a grob is defined relative to the position of its parent (if we had to use absolute coordinates instead – e.g., distances from the edges of the page – it would be hard to maintain spatial relationships between grobs).

Every grob knows which grob is its parent in the respective axis. For example, a `Flag` grob knows that its x-parent is a particular `Stem` grob.

Relative coordinates that describe a grob’s placement are stored in grob properties called `X-offset` and `Y-offset`. They are measured in staff spaces. `X-offset` is the horizontal displacement between a grob’s reference point and the reference point of a grob’s x-parent (similarly with `Y-offset`).

What is a reference point? It’s a special point that defines the grob’s position. Think about geometry: if you have to define where a figure is placed on a plane, you’ll usually say something like “the lower left corner of this square has coordinates (0, 2)”, or “the center of this circle is at (-1, 3)”. ‘Lower left corner’ and ‘center’ would be the reference points for square and circle, respectively.

This illustration shows where reference points of particular grobs are located, indicated as red dots (for example, the middle staff line for bars and stems, the intersection between the baseline and the left edge for a text box, or the vertical center at the left side for a note head).

    {
      \override NoteHead.style = #'altdefault     % for breve

      \time 4/2 g'2-> c''\fermata as'1^"Yogi" |
      b'\breve _"Larry" |
      \mark "Twinkle" e''8 s4.. \bar "|."
    }

By overriding the `X-offset` or `Y-offset` value we can move grobs relative to their parents:

    {
      \override Script.X-offset = 3               % fermata, accent
      \override TextScript.X-offset = 2           % "Yogi", "Larry"
      \override Stem.X-offset = -2
      \override Score.RehearsalMark.Y-offset = 5  % "Twinkle"

      \override NoteHead.style = #'altdefault     % for breve

      \time 4/2 g'2-> c''\fermata as'1^"Yogi" |
      b'\breve _"Larry" |
      \mark "Twinkle" e''8 s4.. \bar "|."
    }

Note that the `Flag` grob moved together with its `Stem` grob.

Note: Changing `X-offset` or `Y-offset` doesn’t always work as expected, see Aligning objects.

Now, let’s explain another pair of properties: `X-extent` and `Y-extent`. Each of them is a pair of numbers (internally, LilyPond calls this an interval), and they store a grob’s dimensions relative to its reference point. For example, `X-extent` equal to (-1 . 4) means that the left edge of the grob is 1 staff space to the left of its reference point, and the right edge is 4 staff spaces to the right from reference point, for a total width of 4 - (-1) = 4 + 1 = 5 staff spaces. Both numbers in an extent may be positive; for example, (2 . 3) is a valid extent: it means that the whole grob is on the right of its reference point, and the width of the grob is 3 - 2 = 1 staff space. Similarly, both numbers can be negative; these situations are quite unusual but won’t give LilyPond headaches. The most common situation (at least for `X-extent`) is that the first number is 0, which means that the reference point is on the left edge of the grob.

The previous example demonstrates this nicely: both the accent’s and the fermata’s left edge is left of the reference point; the same holds for the breve note head (we selected the `'altdefault` note head style to make this better visible).

Now, suppose that we want to position a `RehearsalMark` grob so that its right edge is aligned with a bar line (by default, LilyPond horizontally centers the rehearsal mark). With `X-offset` equal to zero (i.e., its reference point is aligned on the parent, which is equal to the bar line in this situation), the `RehearsalMark` grob is placed like this:

>     {
>       \override Score.RehearsalMark.X-offset = 0
>       b4 b b b \mark "Twinkle" b b b b
>     }

So, we need to shift it. Remember what the second number in `X-extent` means? It’s the position of a grob’s right edge relative to its reference point. If we subtract this value from zero, we’ll get the x-offset we want:

>     {
>       % value -10.4 found by trial and error
>       \override Score.RehearsalMark.X-offset = -10.4
>       b4 b b b \mark "Twinkle" b b b b
>     }

What if we wanted to center some grob on the reference point on its parent? That’s simple: calculate the displacement between a grob’s reference point and the center of its extent. Some examples:

- `X-extent` = (-2 . 2)
  ⇒ `X-offset` = 0 - 0 = 0
- `X-extent` = (0 . 4)
  ⇒ `X-offset` = 0 - (0 + 0.5 * 4) = -2
- `X-extent` = (-2 . 4)
  ⇒ `X-offset` = 0 - ((0.5 * -2) + (0.5 * 4)) = 0 - (-1 + 2) = -1

There is already a function with a super-long name available that can do these calculations for us:

    \override GrobName.X-offset =
      #ly:self-alignment-interface::x-aligned-on-self

and we only need to specify what alignment we want:

    \override GrobName.self-alignment-X = #RIGHT

This code tells the procedure to find the displacement between a grob’s reference point and its right edge, and use it as the x-offset, which will result in the grob being right-aligned.

So, if you change a grob’s extent, you will affect how it will be aligned (because LilyPond will think that the grob’s dimensions are different):

>     {
>       \override Score.RehearsalMark.X-extent = #'(0 . 8)
>       \override Score.RehearsalMark.self-alignment-X = #RIGHT
>       b4 b b b \mark "Twinkle" b b b b
>     }

Also, if a grob’s extent is empty (i.e., it’s not an interval pair), procedures like `x-aligned-on-self` won’t have any information about a grob’s dimensions, so they won’t be able to calculate an offset (they’ll just return value 0). In other words, a grob with an empty extent can only be ‘aligned’ on its reference point because there’s no other information that can be used for alignment:

>     {
>       \override Score.RehearsalMark.X-extent = ##f
>       b4 b b b \mark "Twinkle" b b b b
>     }

Notice that an empty extent and a zero extent result in the same positioning:

>     {
>       \override Score.RehearsalMark.X-extent = #'(0 . 0)
>       b4 b b b \mark "Twinkle" b b b b
>     }

However, an empty extent (or a zero extent, or any other extent) doesn’t prevent us from placing the grob at any location we want – we just can’t use alignment procedures for that. We can still specify any offset we want, and it will work as usual:

>     {
>       \override Score.RehearsalMark.X-extent = ##f
>       \override Score.RehearsalMark.X-offset = -10.4
>       b4 b b b \mark "Twinkle" b b b b
>     }

Now, there is one more thing to keep in mind: a grob’s parent has its own dimensions, too, and we need to take them into account. For example, if we write

>     { a'1 }
>     \addlyrics {
>       \override LyricText.X-offset =
>         #ly:self-alignment-interface::x-aligned-on-self
>       \override LyricText.self-alignment-X = #CENTER
>       nn
>     }

the `LyricText` grob will be centered, but on the reference point of its parent (i.e., the center of the syllable will be aligned to the reference point of the note head). If we want the center of the `LyricText` grob to be aligned with the center of its parent `NoteHead` grob, we have to use a different procedure: `aligned-on-x-parent`. It works very similar to `x-aligned-on-self`, but in addition to calculating an offset based on a grob’s own extent, it also uses the grob’s parent extent and computes positions relative to the center of the extent:

>     { a'1 }
>     \addlyrics {
>       \override LyricText.X-offset =
>         #ly:self-alignment-interface::aligned-on-x-parent
>       \override LyricText.self-alignment-X = #CENTER
>       nn
>     }

#### LilyPond Learning Manual v2.26.0 (stable-branch).

- 1 Installing
  - 1.1 Graphical setup
  - 1.2 Command line setup
- 2 Tutorial
  - 2.1 Compiling a file
  - 2.2 How to write input files
    - 2.2.1 Input characters
    - 2.2.2 Simple notation
      - Pitches
      - Durations (rhythms)
      - Rests
      - Time signature
      - Tempo marks
      - Clef
      - All together
    - 2.2.3 Working on input files
  - 2.3 Dealing with errors
  - 2.4 How to read the manuals
    - 2.4.1 Omitted material
    - 2.4.2 Clickable examples
    - 2.4.3 Overview of manuals
- 3 Common notation
  - 3.1 Single-staff notation
    - 3.1.1 Bar lines and bar checks
      - Bar lines
      - Bar checks
    - 3.1.2 Pitches and key signatures
      - Pitch alterations
      - Key signatures
      - Warning: key signatures and pitches
    - 3.1.3 Ties and slurs
      - Ties
      - Slurs
      - Phrasing slurs
      - Warnings: slurs vs. ties
    - 3.1.4 Articulations and dynamics
      - Articulations
      - Fingerings
      - Dynamics
    - 3.1.5 Adding text
    - 3.1.6 Automatic and manual beams
    - 3.1.7 Advanced rhythmic commands
      - Partial measure
      - Tuplets
      - Grace notes
  - 3.2 Multiple notes at once
    - 3.2.1 Music expressions explained
      - Analogy: mathematical expressions
      - Simultaneous music expressions: multiple staves
      - Simultaneous music expressions: single-staff
    - 3.2.2 Multiple staves
    - 3.2.3 Staff groups
    - 3.2.4 Combining notes into chords
    - 3.2.5 Single-staff polyphony
  - 3.3 Songs
    - 3.3.1 Setting simple songs
    - 3.3.2 Aligning lyrics to a melody
    - 3.3.3 Lyrics to multiple staves
  - 3.4 Final touches
    - 3.4.1 Organizing pieces with variables
    - 3.4.2 Adding titles
    - 3.4.3 Absolute note names
    - 3.4.4 After the tutorial
- 4 Fundamental concepts
  - 4.1 How LilyPond input files work
    - 4.1.1 Introduction to the LilyPond file structure
    - 4.1.2 A score is a (single) compound musical expression
    - 4.1.3 Nesting music expressions
    - 4.1.4 Structure of a note entry
    - 4.1.5 On the un-nestedness of brackets and ties
  - 4.2 Voices contain music
    - 4.2.1 I’m hearing voices
    - 4.2.2 Explicitly instantiating voices
    - 4.2.3 Voices and vocals
  - 4.3 Contexts and engravers
    - 4.3.1 Contexts explained
    - 4.3.2 Creating contexts
    - 4.3.3 Engravers explained
    - 4.3.4 Modifying context properties
    - 4.3.5 Adding and removing engravers
  - 4.4 Extending the templates
    - 4.4.1 Soprano and cello
    - 4.4.2 Four-part SATB vocal score
    - 4.4.3 Building a score from scratch
    - 4.4.4 Saving typing with variables and functions
    - 4.4.5 Scores and parts
- 5 Tweaking output
  - 5.1 Tweaking basics
    - 5.1.1 Objects and interfaces
    - 5.1.2 Naming conventions of objects and properties
    - 5.1.3 Tweaking methods
      - The `\override` command
      - The `\revert` command
      - The `\once` prefix
      - The `\tweak` and `\offset` commands
      - The `\single` prefix
  - 5.2 The Internals Reference manual
    - 5.2.1 Properties of layout objects
    - 5.2.2 Properties found in interfaces
    - 5.2.3 Types of properties
  - 5.3 Appearance of objects
    - 5.3.1 Visibility and color of objects
      - The `stencil` property
      - The `break-visibility` property
      - The `transparent` property
      - The `color` property
    - 5.3.2 Size of objects
    - 5.3.3 Length and thickness of objects
  - 5.4 Offsets and alignments
  - 5.5 Placement of objects
    - 5.5.1 Automatic behavior
    - 5.5.2 Within-staff objects
      - The `direction` property
      - Fingering
    - 5.5.3 Outside-staff objects
      - The `outside-staff-priority` property
      - The `\textLengthOn` command
      - Dynamics placement
      - Grob sizing
  - 5.6 Vertical spacing
  - 5.7 Collisions of objects
    - 5.7.1 Moving objects
    - 5.7.2 Fixing overlapping notation
      - The `padding` property
      - The `right-padding` property
      - The `staff-padding` property
      - The `self-alignment-X` property
      - The `staff-position` property
      - The `extra-offset` property
      - The `positions` property
      - The `force-hshift` property
    - 5.7.3 Real music example
  - 5.8 Further tweaking
    - 5.8.1 Other uses for tweaks
      - Tying notes across voices
      - Simulating a fermata in MIDI
    - 5.8.2 Using variables for layout adjustments
    - 5.8.3 Style sheets
    - 5.8.4 Other sources of information
    - 5.8.5 Advanced tweaks with Scheme
- Appendix A Templates
  - A.1 Built-in templates
    - A.1.1 SATB template
    - A.1.2 SSAATTBB template
  - A.2 Single staff templates
    - A.2.1 Notes only
    - A.2.2 Notes and lyrics
    - A.2.3 Notes and chords
    - A.2.4 Notes, lyrics, and chords
  - A.3 Piano templates
    - A.3.1 Solo piano
    - A.3.2 Piano and melody with lyrics
    - A.3.3 Piano-centered lyrics
  - A.4 String quartet templates
    - A.4.1 String quartet
    - A.4.2 String quartet parts
  - A.5 Vocal ensembles templates
    - A.5.1 SATB vocal score
    - A.5.2 SATB vocal score and automatic piano reduction
    - A.5.3 SATB with aligned contexts
    - A.5.4 SATB on four staves
    - A.5.5 Solo verse and two-part refrain
    - A.5.6 Hymn tunes
    - A.5.7 Psalms
  - A.6 Orchestral templates
    - A.6.1 Orchestra, choir and piano
  - A.7 Ancient notation templates
    - A.7.1 Transcription of mensural music
    - A.7.2 Gregorian transcription template
  - A.8 Other templates
    - A.8.1 Jazz combo
- Appendix B GNU Free Documentation License
- Appendix C Index