1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond-learning.tely
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. See TRANSLATION for details.
11 @chapter Tweaking output
13 This chapter discusses how to modify output. LilyPond is extremely
14 configurable; virtually every fragment of output may be changed.
19 * Fixing overlapping notation::
22 * Fitting music onto fewer pages::
23 * Advanced tweaks with Scheme::
24 * Avoiding tweaks with slower processing::
29 @section Moving objects
31 This may come as a surprise, but LilyPond is not perfect. Some notation
32 elements can overlap. This is unfortunate, but (in most cases) is easily
35 @c FIXME: find a better example for 5.1 Moving Objects. -gp
36 @c yes, I want this TODO to be visible to end-users. It's better
37 @c than having nothing at all.
38 TODO: with the new spacing features in 2.12, these specific examples are no
39 longer relevant. However, they still demonstrate powerful features
40 of lilypond, so they remain until somebody creates some better examples.
42 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
43 % temporary code to break this example:
44 \override TextScript #'outside-staff-priority = ##f
45 e4^\markup{ \italic ritenuto } g b e
50 The easiest solution is to increase the distance between the object
51 (in this case text, but it could easily be fingerings or dynamics
52 instead) and the note. In LilyPond, this is called the
53 @code{padding} property; it is measured in staff spaces. For most
54 objects, this value is around 1.0 or less (it varies with each
55 object). We want to increase it, so let's try 1.5
57 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
58 % temporary code to break this example:
59 \override TextScript #'outside-staff-priority = ##f
60 \once \override TextScript #'padding = #1.5
61 e4^\markup{ \italic ritenuto } g b e
64 That looks better, but it isn't quite big enough. After experimenting
65 with a few values, we think 2.3 is the best number in this case. However,
66 this number is merely the result of experimentation and my personal
67 taste in notation. Try the above example with 2.3... but also try higher
68 (and lower) numbers. Which do you think looks the best?
70 The @code{staff-padding} property is closely related. @code{padding}
71 controls the minimum amount of space between an object and the nearest
72 other object (generally the note or the staff lines);
73 @code{staff-padding} controls the minimum amount of space between an
74 object and the staff. This is a subtle difference, but you can see
77 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
78 % temporary code to break this example:
79 \override TextScript #'outside-staff-priority = ##f
81 \once \override TextScript #'padding = #4.6
83 \once \override TextScript #'staff-padding = #4.6
84 c4^"piu mosso" fis a g
87 \once \override TextScript #'padding = #4.6
89 \once \override TextScript #'staff-padding = #4.6
90 c4^"piu mosso" fis a g
95 Another solution gives us complete control over placing the object -- we
96 can move it horizontally or vertically. This is done with the
97 @code{extra-offset} property. It is slightly more complicated and can
98 cause other problems. When we move objects with @code{extra-offset},
99 the movement is done after LilyPond has placed all other objects. This
101 that the result can overlap with other objects.
103 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
104 % temporary code to break this example:
105 \override TextScript #'outside-staff-priority = ##f
106 \once \override TextScript #'extra-offset = #'( 1.0 . -1.0 )
107 e4^\markup{ \italic ritenuto } g b e
110 With @code{extra-offset}, the first number controls the horizontal
111 movement (left is negative); the second number controls the vertical
112 movement (up is positive). After a bit of experimenting, we decided
113 that these values look good
115 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
116 % temporary code to break this example:
117 \override TextScript #'outside-staff-priority = ##f
118 \once \override TextScript #'extra-offset = #'( -1.6 . 1.0 )
119 e4^\markup{ \italic ritenuto } g b e
123 Again, these numbers are simply the result of a few experiments and
124 looking at the output. You might prefer the text to be slightly higher,
125 or to the left, or whatever. Try it and look at the result!
127 One final warning: in this section, we used
130 \once \override TextScript @dots{}
133 This tweaks the display of text for the next note. If the note has
134 no text, this tweak does nothing (and does @strong{not} wait until
135 the next bit of text). To change the behavior of everything after
136 the command, omit the @code{\once}. To stop this tweak, use a
137 @code{\revert}. This is explained in depth in
138 @ruser{The \override command}.
140 @lilypond[quote,fragment,ragged-right,verbatim,relative=3]
141 % temporary code to break this example:
142 \override TextScript #'outside-staff-priority = ##f
144 \once \override TextScript #'padding = #4.6
147 \once \override TextScript #'padding = #4.6
151 \override TextScript #'padding = #4.6
154 \revert TextScript #'padding
160 This manual: @ruser{The \override command}, @ruser{Common tweaks}.
163 @node Fixing overlapping notation
164 @section Fixing overlapping notation
166 In @ruser{Moving objects}, we saw how to move a @code{TextScript}
167 object. The same mechanism can be used to move other types of
168 objects; simply replace @code{TextScript} with the name of
171 To find the object name, look at the @q{@strong{see also}} at
172 bottom of the relevant documentation page. For example, at
173 the bottom of @ruser{Dynamics}, we see
178 Program reference: @internalsref{DynamicText}, @internalsref{Hairpin}.
179 Vertical positioning of these symbols is handled by
180 @internalsref{DynamicLineSpanner}.
184 So to move dynamics around vertically, we use
187 \override DynamicLineSpanner #'padding = #2.0
190 We cannot list every object, but here is a list of the most
193 @multitable @columnfractions .33 .66
194 @headitem Object type @tab Object name
195 @item Dynamics (vertically) @tab @code{DynamicLineSpanner}
196 @item Dynamics (horizontally) @tab @code{DynamicText}
197 @item Ties @tab @code{Tie}
198 @item Slurs @tab @code{Slur}
199 @item Articulations @tab @code{Script}
200 @item Fingerings @tab @code{Fingering}
201 @item Text e.g. @code{^"text"} @tab @code{TextScript}
202 @item Rehearsal / Text marks @tab @code{RehearsalMark}
207 @section Common tweaks
209 Some overrides are so common that predefined commands are provided as
210 short-cuts, such as @code{\slurUp} and @code{\stemDown}. These
211 commands are described in the Notation Reference under the appropriate
214 The complete list of modifications available for each type of
215 object (like slurs or beams) are documented in the Program
216 Reference. However, many layout objects share properties which can be
217 used to apply generic tweaks.
224 The @code{padding} property can be set to increase
225 (or decrease) the distance between symbols that are printed
226 above or below notes. This applies to all objects with
227 @code{side-position-interface}.
229 @lilypond[quote,fragment,relative=1,verbatim]
231 \override Script #'padding = #3
235 @lilypond[quote,fragment,relative=1,verbatim]
236 % This will not work, see below:
237 \override MetronomeMark #'padding = #3
241 \override Score.MetronomeMark #'padding = #3
246 Note in the second example how important it is to figure out what
247 context handles a certain object. Since the @code{MetronomeMark} object
248 is handled in the @code{Score} context, property changes in the
249 @code{Voice} context will not be noticed. For more details, see
250 @ruser{Constructing a tweak}.
255 The @code{extra-offset} property moves objects around
256 in the output; it requires a pair of numbers. The first number
257 controls horizontal movement; a positive number will
258 move the object to the right. The second number controls vertical
259 movement; a positive number will move it higher. The
260 @code{extra-offset} property is a low-level feature: the
261 formatting engine is completely oblivious to these offsets.
263 In the following example, the second fingering is moved a little to
264 the left, and 1.8 staff space downwards:
266 @lilypond[quote,fragment,relative=1,verbatim]
269 \once \override Fingering
270 #'extra-offset = #'(-0.3 . -1.8)
275 Setting the @code{transparent} property will cause an object to be printed
276 in @q{invisible ink}: the object is not printed, but all its other
277 behavior is retained. The object still takes up space, it takes part in
278 collisions, and slurs, ties, and beams can be attached to it.
280 @cindex transparent objects
281 @cindex removing objects
282 @cindex hiding objects
283 @cindex invisible objects
284 The following example demonstrates how to connect different voices
285 using ties. Normally, ties only connect two notes in the same
286 voice. By introducing a tie in a different voice,
288 @lilypond[quote,fragment,relative=2]
297 and blanking the first up-stem in that voice, the tie appears to cross
301 @lilypond[quote,fragment,relative=2,verbatim]
303 \once \override Stem #'transparent = ##t
310 To make sure that the just-blanked stem doesn't squeeze the tie too much,
311 we also lengthen the stem, by setting the @code{length} to
314 @lilypond[quote,fragment,relative=2,verbatim]
316 \once \override Stem #'transparent = ##t
317 \once \override Stem #'length = #8
326 @cindex Tweaks, distances
329 Distances in LilyPond are measured in staff-spaces, while most
330 thickness properties are measured in line-thickness. Some
331 properties are different; for example, the thickness of beams
332 are measured in staff-spaces. For more information, see the
333 relevant portion of the program reference.
337 @section Default files
339 The Program Reference documentation contains a lot of information
340 about LilyPond, but even more information can be gathered from
341 looking at the internal LilyPond files.
343 Some default settings (such as the definitions for
344 @code{\header@{@}}s) are stored as @code{.ly} files. Other
345 settings (such as the definitions of markup commands) are
346 stored as @code{.scm} (Scheme) files. Further explanation is
347 outside the scope of this manual; users should be warned that
348 a substantial amount of technical knowledge or time is required
349 to understand these files.
353 @item Linux: @file{@var{installdir}/lilypond/usr/share/lilypond/current/}
356 @file{@var{installdir}/LilyPond.app/Contents/Resources/share/lilypond/current/}.
357 To access this, either @code{cd} into this directory from the
358 Terminal, or control-click on the LilyPond application and select
359 @q{Show Package Contents}.
361 @item Windows: @file{@var{installdir}/LilyPond/usr/share/lilypond/current/}
365 The @file{ly/} and @file{scm/} directories will be of
366 particular interest. Files such as @file{ly/property-init.ly} and
367 @file{ly/declarations-init.ly} define all the common tweaks.
370 @node Fitting music onto fewer pages
371 @section Fitting music onto fewer pages
373 Sometimes you can end up with one or two staves on a second
374 (or third, or fourth...) page. This is annoying, especially
375 if you look at previous pages and it looks like there is plenty
376 of room left on those.
378 When investigating layout issues, @code{annotate-spacing} is
379 an invaluable tool. This command prints the values of various
380 layout spacing commands; see @ruser{Displaying spacing}, for more
381 details. From the output of @code{annotate-spacing}, we can
382 see which margins we may wish to alter.
384 Other than margins, there are a few other options to save space:
388 You may tell LilyPond to place systems as close together as
389 possible (to fit as many systems as possible onto a page), but
390 then to space those systems out so that there is no blank
391 space at the bottom of the page.
395 between-system-padding = #0.1
396 between-system-space = #0.1
397 ragged-last-bottom = ##f
403 You may force the number of systems (i.e., if LilyPond wants
404 to typeset some music with 11 systems, you could force it to
414 Avoid (or reduce) objects which increase the vertical size of
415 a system. For example, volta repeats (or alternate repeats)
416 require extra space. If these repeats are spread over two
417 systems, they will take up more space than one system with
418 the volta repeats and another system without.
420 Another example is moving dynamics which @q{stick out} of
423 @lilypond[verbatim,quote,fragment]
426 \override DynamicLineSpanner #'padding = #-1.8
427 \override DynamicText #'extra-offset = #'( -2.1 . 0)
433 Alter the horizontal spacing via @code{SpacingSpanner}. See
434 @ruser{Changing horizontal spacing}, for more details.
436 @lilypond[verbatim,quote]
439 g4 e e2 | f4 d d2 | c4 d e f | g4 g g2 |
440 g4 e e2 | f4 d d2 | c4 e g g | c,1 |
441 d4 d d d | d4 e f2 | e4 e e e | e4 f g2 |
442 g4 e e2 | f4 d d2 | c4 e g g | c,1 |
447 \override SpacingSpanner
448 #'base-shortest-duration = #(ly:make-moment 1 4)
457 @node Advanced tweaks with Scheme
458 @section Advanced tweaks with Scheme
460 We have seen how LilyPond output can be heavily modified using
462 @code{\override TextScript #'extra-offset = ( 1 . -1)}. But
463 we have even more power if we use Scheme. For a full explantion
464 of this, see the @ruser{Scheme tutorial}, and
465 @ruser{Interfaces for programmers}.
467 We can use Scheme to simply @code{\override} commands,
469 @lilypond[quote,verbatim,ragged-right]
470 padText = #(define-music-function (parser location padding) (number?)
472 \once \override TextScript #'padding = #$padding
480 c4^"piu mosso" fis a g
484 We can use it to create new commands,
486 @lilypond[quote,verbatim,ragged-right]
487 tempoMark = #(define-music-function (parser location padding marktext)
490 \once \override Score . RehearsalMark #'padding = $padding
491 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
492 \mark \markup { \bold $marktext }
497 \tempoMark #3.0 #"Allegro"
502 Even music expressions can be passed in.
504 @lilypond[quote,verbatim,ragged-right]
505 pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
512 \pattern {d16 dis} { ais16-> b\p }
517 @node Avoiding tweaks with slower processing
518 @section Avoiding tweaks with slower processing
520 LilyPond can perform extra checks while it processes files. These
521 commands will take extra time, but the result may require fewer
525 %% makes sure text scripts and lyrics are within the paper margins
526 \override Score.PaperColumn #'keep-inside-line = ##t