1 @c -*- coding: utf-8; mode: texinfo; -*-
3 @chapter Tweaking output
5 This chapter discusses how to modify output. LilyPond is extremely
6 configurable; virtually every fragment of output may be changed.
11 * Fixing overlapping notation::
14 * Advanced tweaks with Scheme::
19 @section Moving objects
21 This may come as a surprise, but LilyPond is not perfect. Some notation
22 elements can overlap. This is unfortunate, but (in most cases) is easily
25 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
26 e4^\markup{ \italic ritenuto } g b e
31 The easiest solution is to increase the distance between the object
32 (in this case text, but it could easily be fingerings or dynamics
33 instead) and the note. In LilyPond, this is called the
34 @code{padding} property; it is measured in staff spaces. For most
35 objects, this value is around 1.0 or less (it varies with each
36 object). We want to increase it, so let's try 1.5
38 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
39 \once \override TextScript #'padding = #1.5
40 e4^\markup{ \italic ritenuto } g b e
43 That looks better, but it isn't quite big enough. After experimenting
44 with a few values, we think 2.3 is the best number in this case. However,
45 this number is merely the result of experimentation and my personal
46 taste in notation. Try the above example with 2.3... but also try higher
47 (and lower) numbers. Which do you think looks the best?
49 The @code{staff-padding} property is closely related. @code{padding}
50 controls the minimum amount of space between an object and the nearest
51 other object (generally the note or the staff lines);
52 @code{staff-padding} controls the minimum amount of space between an
53 object and the staff. This is a subtle difference, but you can see
56 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
58 \once \override TextScript #'padding = #2.6
60 \once \override TextScript #'staff-padding = #2.6
61 c4^"piu mosso" fis a g
63 c,,4^"piu mosso" b a b
64 \once \override TextScript #'padding = #2.6
66 \once \override TextScript #'staff-padding = #2.6
67 c4^"piu mosso" fis a g
72 Another solution gives us complete control over placing the object -- we
73 can move it horizontally or vertically. This is done with the
74 @code{extra-offset} property. It is slightly more complicated and can
75 cause other problems. When we move objects with @code{extra-offset},
76 the movement is done after LilyPond has placed all other objects. This
78 that the result can overlap with other objects.
80 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
81 \once \override TextScript #'extra-offset = #'( 1.0 . -1.0 )
82 e4^\markup{ \italic ritenuto } g b e
85 With @code{extra-offset}, the first number controls the horizontal
86 movement (left is negative); the second number controls the vertical
87 movement (up is positive). After a bit of experimenting, we decided
88 that these values look good
90 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
91 \once \override TextScript #'extra-offset = #'( -1.6 . 1.0 )
92 e4^\markup{ \italic ritenuto } g b e
96 Again, these numbers are simply the result of a few experiments and
97 looking at the output. You might prefer the text to be slightly higher,
98 or to the left, or whatever. Try it and look at the result!
100 One final warning: in this section, we used
103 \once \override TextScript @dots{}
106 This tweaks the display of text for the next note. If the note has
107 no text, this tweak does nothing (and does @strong{not} wait until
108 the next bit of text). To change the behavior of everything after
109 the command, omit the @code{\once}. To stop this tweak, use a
110 @code{\revert}. This is explained in depth in
111 @ref{The \override command}.
113 @lilypond[quote,fragment,ragged-right,verbatim,relative=3]
115 \once \override TextScript #'padding = #2.6
118 \once \override TextScript #'padding = #2.6
122 \override TextScript #'padding = #2.6
125 \revert TextScript #'padding
131 This manual: @ref{The \override command}, @ref{Common tweaks}.
134 @node Fixing overlapping notation
135 @section Fixing overlapping notation
137 In @ref{Moving objects}, we saw how to move a @code{TextScript}
138 object. The same mechanism can be used to move other types of
139 objects; simply replace @code{TextScript} with the name of
142 To find the object name, look at the ``@strong{see also}'' at
143 bottom of the relevant documentation page. For example, at
144 the bottom of @ref{Dynamics}, we see
149 Program reference: @internalsref{DynamicText}, @internalsref{Hairpin}.
150 Vertical positioning of these symbols is handled by
151 @internalsref{DynamicLineSpanner}.
155 So to move dynamics around vertically, we use
158 \override DynamicLineSpanner #'padding = #2.0
161 We cannot list every object, but here is a list of the most
164 @multitable @columnfractions .33 .66
165 @headitem Object type @tab Object name
166 @item Dynamics (vertically) @tab @code{DynamicLineSpanner}
167 @item Dynamics (horizontally) @tab @code{DynamicText}
168 @item Ties @tab @code{Tie}
169 @item Slurs @tab @code{Slur}
170 @item Articulations @tab @code{Script}
171 @item Fingerings @tab @code{Fingering}
172 @item Text e.g. @code{^"text"} @tab @code{TextScript}
173 @item Rehearsal / Text marks @tab @code{RehearsalMark}
178 @section Common tweaks
180 Some overrides are so common that predefined commands are provided as
181 short-cuts, such as @code{\slurUp} and @code{\stemDown}. These
182 commands are described in the Notation Reference under the appropriate
185 The complete list of modifications available for each type of
186 object (like slurs or beams) are documented in the Program
187 Reference. However, many layout objects share properties which can be
188 used to apply generic tweaks.
195 The @code{padding} property can be set to increase
196 (or decrease) the distance between symbols that are printed
197 above or below notes. This applies to all objects with
198 @code{side-position-interface}.
200 @lilypond[quote,fragment,relative=1,verbatim]
202 \override Script #'padding = #3
206 @lilypond[quote,fragment,relative=1,verbatim]
207 % This will not work, see below:
208 \override MetronomeMark #'padding = #3
212 \override Score.MetronomeMark #'padding = #3
217 Note in the second example how important it is to figure out what
218 context handles a certain object. Since the @code{MetronomeMark} object
219 is handled in the @code{Score} context, property changes in the
220 @code{Voice} context will not be noticed. For more details, see
221 @ref{Constructing a tweak}.
226 The @code{extra-offset} property moves objects around
227 in the output; it requires a pair of numbers. The first number
228 controls horizontal movement; a positive number will
229 move the object to the right. The second number controls vertical
230 movement; a positive number will move it higher. The
231 @code{extra-offset} property is a low-level feature: the
232 formatting engine is completely oblivious to these offsets.
234 In the following example, the second fingering is moved a little to
235 the left, and 1.8 staff space downwards:
237 @lilypond[quote,fragment,relative=1,verbatim]
240 \once \override Fingering
241 #'extra-offset = #'(-0.3 . -1.8)
246 Setting the @code{transparent} property will cause an object to be printed
247 in `invisible ink': the object is not printed, but all its other
248 behavior is retained. The object still takes up space, it takes part in
249 collisions, and slurs, ties, and beams can be attached to it.
251 @cindex transparent objects
252 @cindex removing objects
253 @cindex hiding objects
254 @cindex invisible objects
255 The following example demonstrates how to connect different voices
256 using ties. Normally, ties only connect two notes in the same
257 voice. By introducing a tie in a different voice,
259 @lilypond[quote,fragment,relative=2]
268 and blanking the first up-stem in that voice, the tie appears to cross
271 @lilypond[quote,fragment,relative=2,verbatim]
273 \once \override Stem #'transparent = ##t
282 @cindex Tweaks, distances
285 Distances in LilyPond are measured in staff-spaces, while most
286 thickness properties are measured in line-thickness. Some
287 properties are different; for example, the thickness of beams
288 are measured in staff-spaces. For more information, see the
289 relevant portion of the program reference.
293 @section Default files
295 The Program Reference documentation contains a lot of information
296 about LilyPond, but even more information can be gathered from
297 looking at the internal LilyPond files.
299 Some default settings (such as the definitions for
300 @code{\header@{@}}s) are stored as @code{.ly} files. Other
301 settings (such as the definitions of markup commands) are
302 stored as @code{.scm} (Scheme) files. Further explanation is
303 outside the scope of this manual; users should be warned that
304 a substantial amount of technical knowledge or time is required
305 to understand these files.
309 @item Linux: @file{@{INSTALLDIR@}/lilypond/usr/share/lilypond/current/}
312 @file{@{INSTALLDIR@}/LilyPond.app/Contents/Resources/share/lilypond/current/}.
313 To access this, either @code{cd} into this directory from
314 the Terminal, or control-click on the LilyPond application
315 and select "Show Package Contents".
317 @item Windows: @file{@{INSTALLDIR@}/LilyPond/usr/share/lilypond/current/}
321 The @file{ly/} and @file{scm/} directories will be of
322 particular interest. Files such as @file{ly/property-init.ly} and
323 @file{ly/declarations-init.ly} define all the common tweaks.
326 @node Advanced tweaks with Scheme
327 @section Advanced tweaks with Scheme
329 We have seen how LilyPond output can be heavily modified using
331 @code{\override TextScript #'extra-offset = ( 1 . -1)}. But
332 we have even more power if we use Scheme. For a full explantion
333 of this, see the @ref{Scheme tutorial} and
334 @ref{Interfaces for programmers}.
336 We can use Scheme to simply @code{\override} commands,
338 @lilypond[quote,verbatim,ragged-right]
339 padText = #(define-music-function (parser location padding) (number?)
341 \once \override TextScript #'padding = #$padding
349 c4^"piu mosso" fis a g
353 We can use it to create new commands,
355 @lilypond[quote,verbatim,ragged-right]
356 tempoMark = #(define-music-function (parser location padding marktext)
359 \once \override Score . RehearsalMark #'padding = $padding
360 \once \override Score . RehearsalMark #'no-spacing-rods = ##t
361 \mark \markup { \bold $marktext }
366 \tempoMark #3.0 #"Allegro"
371 Even music expressions can be passed in.
373 @lilypond[quote,verbatim,ragged-right]
374 pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
381 \pattern {d16 dis} { ais16-> b\p }