LilyPond Learning Manual: 4.4.3 Outside-staff objects

### 4.4.3 Outside-staff objects

Outside-staff objects are automatically placed to avoid collisions. Objects with the lower value of the `outside-staff-priority` property are placed nearer to the staff, and other outside-staff objects are then raised as far as necessary to avoid collisions. The `outside-staff-priority` is defined in the `grob-interface` and so is a property of all layout objects. By default it is set to `#f` for all within-staff objects, and to a numerical value appropriate to each outside-staff object when the object is created. The following table shows the default numerical values for some of the commonest outside-staff objects.

Note the unusual names for some of the objects: spanner objects are automatically created to control the vertical positioning of grobs which (might) start and end at different musical moments, so changing the `outside-staff-priority` of the underlying grob will have no effect. For example, changing `outside-staff-priority` of the `Hairpin` object will have no effect on the vertical positioning of hairpins – you must change `outside-staff-priority` of the associated `DynamicLineSpanner` object instead. This override must be placed at the start of the spanner, which might include several linked hairpins and dynamics.

Layout Object | Priority | Controls position of:
--- | --- | ---
`RehearsalMark` | `1500` | Rehearsal marks
`MetronomeMark` | `1000` | Metronome marks
`VoltaBracketSpanner` | `600` | Volta brackets
`TextScript` | `450` | Markup text
`MultiMeasureRestText` | `450` | Markup text over full-bar rests
`OttavaBracket` | `400` | Ottava brackets
`TextSpanner` | `350` | Text spanners
`DynamicLineSpanner` | `250` | All dynamic markings
`BarNumber` | `100` | Bar numbers
`TrillSpanner` | `50` | Spanning trills

Here is an example showing the default placement of some of these.

>     % Set details for later Text Spanner
>     \override TextSpanner #'(bound-details left text)
>         = \markup { \small \bold Slower }
>     % Place dynamics above staff
>     \dynamicUp
>     % Start Ottava Bracket
>     \ottava #1
>     c'4 \startTextSpan
>     % Add Dynamic Text and hairpin
>     c4\pp\<
>     c4
>     % Add Text Script
>     c4^Text |
>     c4 c
>     % Add Dynamic Text and terminate hairpin
>     c4\ff c \stopTextSpan |
>     % Stop Ottava Bracket
>     \ottava #0
>     c,4 c c c |

This example also shows how to create Text Spanners – text with extender lines above a section of music. The spanner extends from the `\startTextSpan` command to the `\stopTextSpan` command, and the format of the text is defined by the `\override TextSpanner` command. For more details see Text spanners.

It also shows how ottava brackets are created.

If the default values of `outside-staff-priority` do not give you the placing you want, the priority of any of the objects may be overridden. Suppose we would like the ottava bracket to be placed below the text spanner in the example above. All we need to do is to look up the priority of `OttavaBracket` in the IR or in the tables above, and reduce it to a value lower than that of a `TextSpanner`, remembering that `OttavaBracket` is created in the `Staff` context:

>     % Set details for later Text Spanner
>     \override TextSpanner #'(bound-details left text)
>         = \markup { \small \bold Slower }
>     % Place dynamics above staff
>     \dynamicUp
>     % Place following Ottava Bracket below Text Spanners
>     \once \override Staff.OttavaBracket #'outside-staff-priority = #340
>     % Start Ottava Bracket
>     \ottava #1
>     c'4 \startTextSpan
>     % Add Dynamic Text
>     c4\pp
>     % Add Dynamic Line Spanner
>     c4\<
>     % Add Text Script
>     c4^Text |
>     c4 c
>     % Add Dynamic Text
>     c4\ff c \stopTextSpan |
>     % Stop Ottava Bracket
>     \ottava #0
>     c,4 c c c |

Note that some of these objects, in particular bar numbers, metronome marks and rehearsal marks, live by default in the `Score` context, so be sure to use the correct context when these are being overriden.

Slurs by default are classed as within-staff objects, but they often appear above the staff if the notes to which they are attached are high on the staff. This can push outside-staff objects such as articulations too high, as the slur will be placed first. The `avoid-slur` property of the articulation can be set to `'inside` to bring the articulation inside the slur, but the `avoid-slur` property is effective only if the `outside-staff-priority` is also set to `#f`. Alternatively, the `outside-staff-priority` of the slur can be set to a numerical value to cause it to be placed along with other outside-staff objects according to that value. Here’s an example showing the effect of the two methods:

>     c4( c^\markup { \tiny \sharp } d4.) c8 |
>     c4(
>     \once \override TextScript #'avoid-slur = #'inside
>     \once \override TextScript #'outside-staff-priority = ##f
>     c4^\markup { \tiny \sharp } d4.) c8 |
>     \once \override Slur #'outside-staff-priority = #500
>     c4( c^\markup { \tiny \sharp } d4.) c8 |

Changing the `outside-staff-priority` can also be used to control the vertical placement of individual objects, although the results may not always be desirable. Suppose we would like “Text3” to be placed above “Text4” in the example under Automatic behavior, above (see Automatic behavior). All we need to do is to look up the priority of `TextScript` in the IR or in the tables above, and increase the priority of “Text3” to a higher value:

>     c2^"Text1"
>     c2^"Text2" |
>     \once \override TextScript #'outside-staff-priority = #500
>     c2^"Text3"
>     c2^"Text4" |

This certainly lifts “Text3” above “Text4” but it also lifts it above “Text2”, and “Text4” now drops down. Perhaps this is not so good. What we would really like to do is to position all the annotation at the same distance above the staff. To do this, we clearly will need to space the notes out horizontally to make more room for the text. This is done using the `textLengthOn` command.

### \textLengthOn

By default, text produced by markup takes up no horizontal space as far as laying out the music is concerned. The `\textLengthOn` command reverses this behavior, causing the notes to be spaced out as far as is necessary to accommodate the text:

>     \textLengthOn  % Cause notes to space out to accommodate text
>     c2^"Text1"
>     c2^"Text2" |
>     c2^"Text3"
>     c2^"Text4" |

The command to revert to the default behavior is `\textLengthOff`. Remember `\once` only works with `\override`, `\set`, `\revert` or `unset`, so cannot be used with `\textLengthOn`.

Markup text will also avoid notes which project above the staff. If this is not desired, the automatic displacement upwards may be turned off by setting the priority to `#f`. Here’s an example to show how markup text interacts with such notes.

>     % This markup is short enough to fit without collision
>     c2^"Tex" c'' |
>     R1 |

>     % This is too long to fit, so it is displaced upwards
>     c,,2^"Text" c'' |
>     R1 |

>     % Turn off collision avoidance
>     \once \override TextScript #'outside-staff-priority = ##f
>     c,,2^"Long Text   " c'' |
>     R1 |

>     % Turn off collision avoidance
>     \once \override TextScript #'outside-staff-priority = ##f
>     \textLengthOn        % and turn on textLengthOn
>     c,,2^"Long Text   "  % Spaces at end are honored
>     c''2 |

### Dynamics

Dynamic markings will normally be positioned beneath the staff, but may be positioned above with the `dynamicUp` command. They will be positioned vertically relative to the note to which they are attached, and will float below (or above) all within-staff objects such as phrasing slurs and bar numbers. This can give quite acceptable results, as this example shows:

>     \clef "bass"
>     \key aes \major
>     \time 9/8
>     \dynamicUp
>     bes4.~\f\< \( bes4 bes8 des4\ff\> c16 bes\! |
>     ees,2.~\)\mf ees4 r8 |

However, if the notes and attached dynamics are close together the automatic placement will avoid collisions by displacing later dynamic markings further away, but this may not be the optimum placement, as this rather artificial example shows:

>     \dynamicUp
>     a4\f b\mf c\mp b\p

Should a similar situation arise in ‘real’ music, it may be preferable to space out the notes a little further, so the dynamic markings can all fit at the same vertical distance from the staff. We were able to do this for markup text by using the `\textLengthOn` command, but there is no equivalent command for dynamic marks. So we shall have to work out how to do this using `\override` commands.

### Grob sizing

First we must learn how grobs are sized. All grobs have a reference point defined within them which is used to position them relative to their parent object. This point in the grob is then positioned at a horizontal distance, `X-offset`, and at a vertical distance, `Y-offset`, from its parent. The horizontal extent of the object is given by a pair of numbers, `X-extent`, which say where the left and right edges are relative to the reference point. The vertical extent is similarly defined by a pair of numbers, `Y-extent`. These are properties of all grobs which support the `grob-interface`.

By default, outside-staff objects are given a width of zero so that they may overlap in the horizontal direction. This is done by the trick of adding infinity to the leftmost extent and minus infinity to the rightmost extent by setting the `extra-spacing-width` to `'(+inf.0 . -inf.0)`. So to ensure they do not overlap in the horizontal direction we must override this value of `extra-spacing-width` to `'(0 . 0)` so the true width shines through. This is the command to do this for dynamic text:

>     \override DynamicText #'extra-spacing-width = #'(0 . 0)

Let’s see if this works in our previous example:

>     \dynamicUp
>     \override DynamicText #'extra-spacing-width = #'(0 . 0)
>     a4\f b\mf c\mp b\p |

Well, it has certainly stopped the dynamic marks being displaced, but two problems remain. The marks should be spaced a little further apart and it would be better if they were all the same distance from the staff. We can solve the first problem easily. Instead of making the `extra-spacing-width` zero we could add a little more to it. The units are the space between two staff lines, so moving the left edge half a unit to the left and the right edge half a unit to the right should do it:

>     \dynamicUp
>     % Extend width by 1 staff space
>     \override DynamicText #'extra-spacing-width = #'(-0.5 . 0.5)
>     a4\f b\mf c\mp b\p

This looks better, but maybe we would prefer the dynamic marks to be aligned along the same baseline rather than going up and down with the notes. The property to do this is `staff-padding` which is covered in the following section.

Autres langues : česky, deutsch, español, italiano, 日本語, nederlands.

#### LilyPond — Learning Manual