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.
16 TODO: explain what/why. maybe in other sections.
25 @section Common tweaks
31 * Fixing overlapping notation::
32 * Other common tweaks::
33 * Fitting music onto fewer pages::
37 @subsection Moving objects
39 This may come as a surprise, but LilyPond is not perfect. Some notation
40 elements can overlap. This is unfortunate, but (in most cases) is easily
43 TODO: with the new spacing features in 2.12, these specific examples are no
44 longer relevant. However, they still demonstrate powerful features
45 of lilypond, so they remain until somebody creates some better examples.
47 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
48 % temporary code to break this example:
49 \override TextScript #'outside-staff-priority = ##f
50 e4^\markup{ \italic ritenuto } g b e
55 The easiest solution is to increase the distance between the object
56 (in this case text, but it could easily be fingerings or dynamics
57 instead) and the note. In LilyPond, this is called the
58 @code{padding} property; it is measured in staff spaces. For most
59 objects, this value is around 1.0 or less (it varies with each
60 object). We want to increase it, so let's try 1.5
62 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
63 % temporary code to break this example:
64 \override TextScript #'outside-staff-priority = ##f
65 \once \override TextScript #'padding = #1.5
66 e4^\markup{ \italic ritenuto } g b e
69 That looks better, but it isn't quite big enough. After experimenting
70 with a few values, we think 2.3 is the best number in this case. However,
71 this number is merely the result of experimentation and my personal
72 taste in notation. Try the above example with 2.3... but also try higher
73 (and lower) numbers. Which do you think looks the best?
75 The @code{staff-padding} property is closely related. @code{padding}
76 controls the minimum amount of space between an object and the nearest
77 other object (generally the note or the staff lines);
78 @code{staff-padding} controls the minimum amount of space between an
79 object and the staff. This is a subtle difference, but you can see
82 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
83 % temporary code to break this example:
84 \override TextScript #'outside-staff-priority = ##f
86 \once \override TextScript #'padding = #4.6
88 \once \override TextScript #'staff-padding = #4.6
89 c4^"piu mosso" fis a g
92 \once \override TextScript #'padding = #4.6
94 \once \override TextScript #'staff-padding = #4.6
95 c4^"piu mosso" fis a g
100 Another solution gives us complete control over placing the object -- we
101 can move it horizontally or vertically. This is done with the
102 @code{extra-offset} property. It is slightly more complicated and can
103 cause other problems. When we move objects with @code{extra-offset},
104 the movement is done after LilyPond has placed all other objects. This
106 that the result can overlap with other objects.
108 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
109 % temporary code to break this example:
110 \override TextScript #'outside-staff-priority = ##f
111 \once \override TextScript #'extra-offset = #'( 1.0 . -1.0 )
112 e4^\markup{ \italic ritenuto } g b e
115 With @code{extra-offset}, the first number controls the horizontal
116 movement (left is negative); the second number controls the vertical
117 movement (up is positive). After a bit of experimenting, we decided
118 that these values look good
120 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
121 % temporary code to break this example:
122 \override TextScript #'outside-staff-priority = ##f
123 \once \override TextScript #'extra-offset = #'( -1.6 . 1.0 )
124 e4^\markup{ \italic ritenuto } g b e
128 Again, these numbers are simply the result of a few experiments and
129 looking at the output. You might prefer the text to be slightly higher,
130 or to the left, or whatever. Try it and look at the result!
132 One final warning: in this section, we used
135 \once \override TextScript @dots{}
138 This tweaks the display of text for the next note. If the note has
139 no text, this tweak does nothing (and does @strong{not} wait until
140 the next bit of text). To change the behavior of everything after
141 the command, omit the @code{\once}. To stop this tweak, use a
142 @code{\revert}. This is explained in depth in
143 @ruser{The \override command}.
145 @lilypond[quote,fragment,ragged-right,verbatim,relative=3]
146 % temporary code to break this example:
147 \override TextScript #'outside-staff-priority = ##f
149 \once \override TextScript #'padding = #4.6
152 \once \override TextScript #'padding = #4.6
156 \override TextScript #'padding = #4.6
159 \revert TextScript #'padding
165 This manual: @ruser{The \override command}, @ref{Common tweaks}.
168 @node Fixing overlapping notation
169 @subsection Fixing overlapping notation
171 In @ref{Moving objects}, we saw how to move a @code{TextScript}
172 object. The same mechanism can be used to move other types of
173 objects; simply replace @code{TextScript} with the name of
176 To find the object name, look at the @q{@strong{see also}} at
177 bottom of the relevant documentation page. For example, at
178 the bottom of @ruser{Dynamics}, we see
183 Program reference: @internalsref{DynamicText}, @internalsref{Hairpin}.
184 Vertical positioning of these symbols is handled by
185 @internalsref{DynamicLineSpanner}.
189 So to move dynamics around vertically, we use
192 \override DynamicLineSpanner #'padding = #2.0
195 We cannot list every object, but here is a list of the most
198 @multitable @columnfractions .33 .66
199 @headitem Object type @tab Object name
200 @item Dynamics (vertically) @tab @code{DynamicLineSpanner}
201 @item Dynamics (horizontally) @tab @code{DynamicText}
202 @item Ties @tab @code{Tie}
203 @item Slurs @tab @code{Slur}
204 @item Articulations @tab @code{Script}
205 @item Fingerings @tab @code{Fingering}
206 @item Text e.g. @code{^"text"} @tab @code{TextScript}
207 @item Rehearsal / Text marks @tab @code{RehearsalMark}
211 @node Other common tweaks
212 @subsection Other common tweaks
214 Some overrides are so common that predefined commands are provided as
215 short-cuts, such as @code{\slurUp} and @code{\stemDown}. These
216 commands are described in the Notation Reference under the appropriate
219 The complete list of modifications available for each type of
220 object (like slurs or beams) are documented in the Program
221 Reference. However, many layout objects share properties which can be
222 used to apply generic tweaks.
229 The @code{padding} property can be set to increase
230 (or decrease) the distance between symbols that are printed
231 above or below notes. This applies to all objects with
232 @code{side-position-interface}.
234 @lilypond[quote,fragment,relative=1,verbatim]
236 \override Script #'padding = #3
240 @lilypond[quote,fragment,relative=1,verbatim]
241 % This will not work, see below:
242 \override MetronomeMark #'padding = #3
246 \override Score.MetronomeMark #'padding = #3
251 Note in the second example how important it is to figure out what
252 context handles a certain object. Since the @code{MetronomeMark} object
253 is handled in the @code{Score} context, property changes in the
254 @code{Voice} context will not be noticed. For more details, see
255 @ruser{Constructing a tweak}.
260 The @code{extra-offset} property moves objects around
261 in the output; it requires a pair of numbers. The first number
262 controls horizontal movement; a positive number will
263 move the object to the right. The second number controls vertical
264 movement; a positive number will move it higher. The
265 @code{extra-offset} property is a low-level feature: the
266 formatting engine is completely oblivious to these offsets.
268 In the following example, the second fingering is moved a little to
269 the left, and 1.8 staff space downwards:
271 @lilypond[quote,fragment,relative=1,verbatim]
274 \once \override Fingering
275 #'extra-offset = #'(-0.3 . -1.8)
280 Setting the @code{transparent} property will cause an object to be printed
281 in @q{invisible ink}: the object is not printed, but all its other
282 behavior is retained. The object still takes up space, it takes part in
283 collisions, and slurs, ties, and beams can be attached to it.
285 @cindex transparent objects
286 @cindex removing objects
287 @cindex hiding objects
288 @cindex invisible objects
289 The following example demonstrates how to connect different voices
290 using ties. Normally, ties only connect two notes in the same
291 voice. By introducing a tie in a different voice,
293 @lilypond[quote,fragment,relative=2]
302 and blanking the first up-stem in that voice, the tie appears to cross
306 @lilypond[quote,fragment,relative=2,verbatim]
308 \once \override Stem #'transparent = ##t
315 To make sure that the just-blanked stem doesn't squeeze the tie too much,
316 we also lengthen the stem, by setting the @code{length} to
319 @lilypond[quote,fragment,relative=2,verbatim]
321 \once \override Stem #'transparent = ##t
322 \once \override Stem #'length = #8
331 @cindex Tweaks, distances
334 Distances in LilyPond are measured in staff-spaces, while most
335 thickness properties are measured in line-thickness. Some
336 properties are different; for example, the thickness of beams
337 are measured in staff-spaces. For more information, see the
338 relevant portion of the program reference.
341 @node Fitting music onto fewer pages
342 @subsection Fitting music onto fewer pages
344 Sometimes you can end up with one or two staves on a second
345 (or third, or fourth...) page. This is annoying, especially
346 if you look at previous pages and it looks like there is plenty
347 of room left on those.
349 When investigating layout issues, @code{annotate-spacing} is
350 an invaluable tool. This command prints the values of various
351 layout spacing commands; see @ruser{Displaying spacing}, for more
352 details. From the output of @code{annotate-spacing}, we can
353 see which margins we may wish to alter.
355 Other than margins, there are a few other options to save space:
359 You may tell LilyPond to place systems as close together as
360 possible (to fit as many systems as possible onto a page), but
361 then to space those systems out so that there is no blank
362 space at the bottom of the page.
366 between-system-padding = #0.1
367 between-system-space = #0.1
368 ragged-last-bottom = ##f
374 You may force the number of systems (i.e., if LilyPond wants
375 to typeset some music with 11 systems, you could force it to
385 Avoid (or reduce) objects which increase the vertical size of
386 a system. For example, volta repeats (or alternate repeats)
387 require extra space. If these repeats are spread over two
388 systems, they will take up more space than one system with
389 the volta repeats and another system without.
391 Another example is moving dynamics which @q{stick out} of
394 @lilypond[verbatim,quote,fragment]
397 \override DynamicLineSpanner #'padding = #-1.8
398 \override DynamicText #'extra-offset = #'( -2.1 . 0)
404 Alter the horizontal spacing via @code{SpacingSpanner}. See
405 @ruser{Changing horizontal spacing}, for more details.
407 @lilypond[verbatim,quote]
410 g4 e e2 | f4 d d2 | c4 d e f | g4 g g2 |
411 g4 e e2 | f4 d d2 | c4 e g g | c,1 |
412 d4 d d d | d4 e f2 | e4 e e e | e4 f g2 |
413 g4 e e2 | f4 d d2 | c4 e g g | c,1 |
418 \override SpacingSpanner
419 #'base-shortest-duration = #(ly:make-moment 1 4)
428 @node TODO other name
429 @section TODO other name
433 * Advanced tweaks with Scheme::
434 * Avoiding tweaks with slower processing::
438 @subsection Default files
440 The Program Reference documentation contains a lot of information
441 about LilyPond, but even more information can be gathered from
442 looking at the internal LilyPond files.
444 Some default settings (such as the definitions for
445 @code{\header@{@}}s) are stored as @code{.ly} files. Other
446 settings (such as the definitions of markup commands) are
447 stored as @code{.scm} (Scheme) files. Further explanation is
448 outside the scope of this manual; users should be warned that
449 a substantial amount of technical knowledge or time is required
450 to understand these files.
454 @item Linux: @file{@var{installdir}/lilypond/usr/share/lilypond/current/}
457 @file{@var{installdir}/LilyPond.app/Contents/Resources/share/lilypond/current/}.
458 To access this, either @code{cd} into this directory from the
459 Terminal, or control-click on the LilyPond application and select
460 @q{Show Package Contents}.
462 @item Windows: @file{@var{installdir}/LilyPond/usr/share/lilypond/current/}
466 The @file{ly/} and @file{scm/} directories will be of
467 particular interest. Files such as @file{ly/property-init.ly} and
468 @file{ly/declarations-init.ly} define all the common tweaks.
471 @node Advanced tweaks with Scheme
472 @subsection Advanced tweaks with Scheme
474 We have seen how LilyPond output can be heavily modified using
476 @code{\override TextScript #'extra-offset = ( 1 . -1)}. But
477 we have even more power if we use Scheme. For a full explantion
478 of this, see the @ref{Scheme tutorial}, and
479 @ruser{Interfaces for programmers}.
481 We can use Scheme to simply @code{\override} commands,
483 @lilypond[quote,verbatim,ragged-right]
484 padText = #(define-music-function (parser location padding) (number?)
486 \once \override TextScript #'padding = #$padding
494 c4^"piu mosso" fis a g
498 We can use it to create new commands,
500 @lilypond[quote,verbatim,ragged-right]
501 tempoMark = #(define-music-function (parser location padding marktext)
504 \once \override Score . RehearsalMark #'padding = $padding
505 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
506 \mark \markup { \bold $marktext }
511 \tempoMark #3.0 #"Allegro"
516 Even music expressions can be passed in.
518 @lilypond[quote,verbatim,ragged-right]
519 pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
526 \pattern {d16 dis} { ais16-> b\p }
531 @node Avoiding tweaks with slower processing
532 @subsection Avoiding tweaks with slower processing
534 LilyPond can perform extra checks while it processes files. These
535 commands will take extra time, but the result may require fewer
539 %% makes sure text scripts and lyrics are within the paper margins
540 \override Score.PaperColumn #'keep-inside-line = ##t
541 \override Score.NonMusicalPaperColumn #'keep-inside-line = ##t
544 In some cases (see issue 246), this must be done before
545 @code{\override} commands can be processed.
549 \override PaperColumn #'keep-inside-line = ##t
550 \override NonMusicalPaperColumn #'keep-inside-line = ##t