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 FIXME: explain what/why. maybe in other sections.
26 @section Common tweaks
32 * Fixing overlapping notation::
33 * Other common tweaks::
34 * Fitting music onto fewer pages::
38 @subsection Moving objects
40 This may come as a surprise, but LilyPond is not perfect. Some notation
41 elements can overlap. This is unfortunate, but (in most cases) is easily
44 TODO: with the new spacing features in 2.12, these specific examples are no
45 longer relevant. However, they still demonstrate powerful features
46 of lilypond, so they remain until somebody creates some better examples.
48 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
49 % temporary code to break this example:
50 \override TextScript #'outside-staff-priority = ##f
51 e4^\markup{ \italic ritenuto } g b e
56 The easiest solution is to increase the distance between the object
57 (in this case text, but it could easily be fingerings or dynamics
58 instead) and the note. In LilyPond, this is called the
59 @code{padding} property; it is measured in staff spaces. For most
60 objects, this value is around 1.0 or less (it varies with each
61 object). We want to increase it, so let's try 1.5
63 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
64 % temporary code to break this example:
65 \override TextScript #'outside-staff-priority = ##f
66 \once \override TextScript #'padding = #1.5
67 e4^\markup{ \italic ritenuto } g b e
70 That looks better, but it isn't quite big enough. After experimenting
71 with a few values, we think 2.3 is the best number in this case. However,
72 this number is merely the result of experimentation and my personal
73 taste in notation. Try the above example with 2.3... but also try higher
74 (and lower) numbers. Which do you think looks the best?
76 The @code{staff-padding} property is closely related. @code{padding}
77 controls the minimum amount of space between an object and the nearest
78 other object (generally the note or the staff lines);
79 @code{staff-padding} controls the minimum amount of space between an
80 object and the staff. This is a subtle difference, but you can see
83 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
84 % temporary code to break this example:
85 \override TextScript #'outside-staff-priority = ##f
87 \once \override TextScript #'padding = #4.6
89 \once \override TextScript #'staff-padding = #4.6
90 c4^"piu mosso" fis a g
93 \once \override TextScript #'padding = #4.6
95 \once \override TextScript #'staff-padding = #4.6
96 c4^"piu mosso" fis a g
101 Another solution gives us complete control over placing the object -- we
102 can move it horizontally or vertically. This is done with the
103 @code{extra-offset} property. It is slightly more complicated and can
104 cause other problems. When we move objects with @code{extra-offset},
105 the movement is done after LilyPond has placed all other objects. This
107 that the result can overlap with other objects.
109 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
110 % temporary code to break this example:
111 \override TextScript #'outside-staff-priority = ##f
112 \once \override TextScript #'extra-offset = #'( 1.0 . -1.0 )
113 e4^\markup{ \italic ritenuto } g b e
116 With @code{extra-offset}, the first number controls the horizontal
117 movement (left is negative); the second number controls the vertical
118 movement (up is positive). After a bit of experimenting, we decided
119 that these values look good
121 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
122 % temporary code to break this example:
123 \override TextScript #'outside-staff-priority = ##f
124 \once \override TextScript #'extra-offset = #'( -1.6 . 1.0 )
125 e4^\markup{ \italic ritenuto } g b e
129 Again, these numbers are simply the result of a few experiments and
130 looking at the output. You might prefer the text to be slightly higher,
131 or to the left, or whatever. Try it and look at the result!
133 One final warning: in this section, we used
136 \once \override TextScript @dots{}
139 This tweaks the display of text for the next note. If the note has
140 no text, this tweak does nothing (and does @strong{not} wait until
141 the next bit of text). To change the behavior of everything after
142 the command, omit the @code{\once}. To stop this tweak, use a
143 @code{\revert}. This is explained in depth in
144 @ruser{The \override command}.
146 @lilypond[quote,fragment,ragged-right,verbatim,relative=3]
147 % temporary code to break this example:
148 \override TextScript #'outside-staff-priority = ##f
150 \once \override TextScript #'padding = #4.6
153 \once \override TextScript #'padding = #4.6
157 \override TextScript #'padding = #4.6
160 \revert TextScript #'padding
166 This manual: @ruser{The \override command}, @ref{Common tweaks}.
169 @node Fixing overlapping notation
170 @subsection Fixing overlapping notation
172 In @ref{Moving objects}, we saw how to move a @code{TextScript}
173 object. The same mechanism can be used to move other types of
174 objects; simply replace @code{TextScript} with the name of
177 To find the object name, look at the @q{@strong{see also}} at
178 bottom of the relevant documentation page. For example, at
179 the bottom of @ruser{Dynamics}, we see
184 Internals Reference: @internalsref{DynamicText}, @internalsref{Hairpin}.
185 Vertical positioning of these symbols is handled by
186 @internalsref{DynamicLineSpanner}.
190 So to move dynamics around vertically, we use
193 \override DynamicLineSpanner #'padding = #2.0
196 We cannot list every object, but here is a list of the most
199 @multitable @columnfractions .33 .66
200 @headitem Object type @tab Object name
201 @item Dynamics (vertically) @tab @code{DynamicLineSpanner}
202 @item Dynamics (horizontally) @tab @code{DynamicText}
203 @item Ties @tab @code{Tie}
204 @item Slurs @tab @code{Slur}
205 @item Articulations @tab @code{Script}
206 @item Fingerings @tab @code{Fingering}
207 @item Text e.g. @code{^"text"} @tab @code{TextScript}
208 @item Rehearsal / Text marks @tab @code{RehearsalMark}
212 @node Other common tweaks
213 @subsection Other common tweaks
215 Some overrides are so common that predefined commands are provided as
216 short-cuts, such as @code{\slurUp} and @code{\stemDown}. These
217 commands are described in the Notation Reference under the appropriate
220 The complete list of modifications available for each type of
221 object (like slurs or beams) are documented in the Program
222 Reference. However, many layout objects share properties which can be
223 used to apply generic tweaks.
230 The @code{padding} property can be set to increase
231 (or decrease) the distance between symbols that are printed
232 above or below notes. This applies to all objects with
233 @code{side-position-interface}.
235 @lilypond[quote,fragment,relative=1,verbatim]
237 \override Script #'padding = #3
241 @lilypond[quote,fragment,relative=1,verbatim]
242 % This will not work, see below:
243 \override MetronomeMark #'padding = #3
247 \override Score.MetronomeMark #'padding = #3
252 Note in the second example how important it is to figure out what
253 context handles a certain object. Since the @code{MetronomeMark} object
254 is handled in the @code{Score} context, property changes in the
255 @code{Voice} context will not be noticed. For more details, see
256 @ruser{Constructing a tweak}.
261 The @code{extra-offset} property moves objects around
262 in the output; it requires a pair of numbers. The first number
263 controls horizontal movement; a positive number will
264 move the object to the right. The second number controls vertical
265 movement; a positive number will move it higher. The
266 @code{extra-offset} property is a low-level feature: the
267 formatting engine is completely oblivious to these offsets.
269 In the following example, the second fingering is moved a little to
270 the left, and 1.8 staff space downwards:
272 @lilypond[quote,fragment,relative=1,verbatim]
275 \once \override Fingering
276 #'extra-offset = #'(-0.3 . -1.8)
281 Setting the @code{transparent} property will cause an object to be printed
282 in @q{invisible ink}: the object is not printed, but all its other
283 behavior is retained. The object still takes up space, it takes part in
284 collisions, and slurs, ties, and beams can be attached to it.
286 @cindex transparent objects
287 @cindex removing objects
288 @cindex hiding objects
289 @cindex invisible objects
290 The following example demonstrates how to connect different voices
291 using ties. Normally, ties only connect two notes in the same
292 voice. By introducing a tie in a different voice,
294 @lilypond[quote,fragment,relative=2]
303 and blanking the first up-stem in that voice, the tie appears to cross
307 @lilypond[quote,fragment,relative=2,verbatim]
309 \once \override Stem #'transparent = ##t
316 To make sure that the just-blanked stem doesn't squeeze the tie too much,
317 we also lengthen the stem, by setting the @code{length} to
320 @lilypond[quote,fragment,relative=2,verbatim]
322 \once \override Stem #'transparent = ##t
323 \once \override Stem #'length = #8
332 @cindex Tweaks, distances
335 Distances in LilyPond are measured in staff-spaces, while most
336 thickness properties are measured in line-thickness. Some
337 properties are different; for example, the thickness of beams
338 are measured in staff-spaces. For more information, see the
339 relevant portion of the program reference.
342 @node Fitting music onto fewer pages
343 @subsection Fitting music onto fewer pages
345 Sometimes you can end up with one or two staves on a second
346 (or third, or fourth...) page. This is annoying, especially
347 if you look at previous pages and it looks like there is plenty
348 of room left on those.
350 When investigating layout issues, @code{annotate-spacing} is
351 an invaluable tool. This command prints the values of various
352 layout spacing commands; see @ruser{Displaying spacing}, for more
353 details. From the output of @code{annotate-spacing}, we can
354 see which margins we may wish to alter.
356 Other than margins, there are a few other options to save space:
360 You may tell LilyPond to place systems as close together as
361 possible (to fit as many systems as possible onto a page), but
362 then to space those systems out so that there is no blank
363 space at the bottom of the page.
367 between-system-padding = #0.1
368 between-system-space = #0.1
369 ragged-last-bottom = ##f
375 You may force the number of systems (i.e., if LilyPond wants
376 to typeset some music with 11 systems, you could force it to
386 Avoid (or reduce) objects which increase the vertical size of
387 a system. For example, volta repeats (or alternate repeats)
388 require extra space. If these repeats are spread over two
389 systems, they will take up more space than one system with
390 the volta repeats and another system without.
392 Another example is moving dynamics which @q{stick out} of
395 @lilypond[verbatim,quote,fragment]
398 \override DynamicLineSpanner #'padding = #-1.8
399 \override DynamicText #'extra-offset = #'( -2.1 . 0)
405 Alter the horizontal spacing via @code{SpacingSpanner}. See
406 @ruser{Changing horizontal spacing}, for more details.
408 @lilypond[verbatim,quote]
411 g4 e e2 | f4 d d2 | c4 d e f | g4 g g2 |
412 g4 e e2 | f4 d d2 | c4 e g g | c,1 |
413 d4 d d d | d4 e f2 | e4 e e e | e4 f g2 |
414 g4 e e2 | f4 d d2 | c4 e g g | c,1 |
419 \override SpacingSpanner
420 #'base-shortest-duration = #(ly:make-moment 1 4)
429 @node TODO other name
430 @section TODO other name
433 * Predefined tweaks::
434 * Advanced tweaks with Scheme::
435 * Avoiding tweaks with slower processing::
436 * The three methods of tweaking::
439 @node Predefined tweaks
440 @subsection Predefined tweaks
442 TODO: Some tweaks are really common, blah blah.
444 for example \slurUp, \fatText.
446 Show example, then explain where to find ly/propert-ly.
449 The Internals Reference documentation contains a lot of information
450 about LilyPond, but even more information can be gathered from
451 looking at the internal LilyPond files.
453 Some default settings (such as the definitions for
454 @code{\header@{@}}s) are stored as @code{.ly} files. Other
455 settings (such as the definitions of markup commands) are
456 stored as @code{.scm} (Scheme) files. Further explanation is
457 outside the scope of this manual; users should be warned that
458 a substantial amount of technical knowledge or time is required
459 to understand these files.
463 @item Linux: @file{@var{installdir}/lilypond/usr/share/lilypond/current/}
466 @file{@var{installdir}/LilyPond.app/Contents/Resources/share/lilypond/current/}.
467 To access this, either @code{cd} into this directory from the
468 Terminal, or control-click on the LilyPond application and select
469 @q{Show Package Contents}.
471 @item Windows: @file{@var{installdir}/LilyPond/usr/share/lilypond/current/}
475 The @file{ly/} and @file{scm/} directories will be of
476 particular interest. Files such as @file{ly/property-init.ly} and
477 @file{ly/declarations-init.ly} define all the common tweaks.
480 @node Advanced tweaks with Scheme
481 @subsection Advanced tweaks with Scheme
483 We have seen how LilyPond output can be heavily modified using
485 @code{\override TextScript #'extra-offset = ( 1 . -1)}. But
486 we have even more power if we use Scheme. For a full explantion
487 of this, see the @ref{Scheme tutorial}, and
488 @ruser{Interfaces for programmers}.
490 We can use Scheme to simply @code{\override} commands,
492 @lilypond[quote,verbatim,ragged-right]
493 padText = #(define-music-function (parser location padding) (number?)
495 \once \override TextScript #'padding = #$padding
503 c4^"piu mosso" fis a g
507 We can use it to create new commands,
509 @lilypond[quote,verbatim,ragged-right]
510 tempoMark = #(define-music-function (parser location padding marktext)
513 \once \override Score . RehearsalMark #'padding = $padding
514 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
515 \mark \markup { \bold $marktext }
520 \tempoMark #3.0 #"Allegro"
525 Even music expressions can be passed in.
527 @lilypond[quote,verbatim,ragged-right]
528 pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
535 \pattern {d16 dis} { ais16-> b\p }
540 @node Avoiding tweaks with slower processing
541 @subsection Avoiding tweaks with slower processing
543 LilyPond can perform extra checks while it processes files. These
544 commands will take extra time, but the result may require fewer
548 %% makes sure text scripts and lyrics are within the paper margins
549 \override Score.PaperColumn #'keep-inside-line = ##t
550 \override Score.NonMusicalPaperColumn #'keep-inside-line = ##t
553 In some cases (see issue 246), this must be done before
554 @code{\override} commands can be processed.
558 \override PaperColumn #'keep-inside-line = ##t
559 \override NonMusicalPaperColumn #'keep-inside-line = ##t
566 @node The three methods of tweaking
567 @subsection The three methods of tweaking
593 FIXME: Move the following words and example into Tweaks or
594 somewhere more suitable, leaving just a ref here. -td
596 Ways of correcting horizontal placings are described fully
597 in the Notation Reference.
598 We introduce just one here, the @code{force-hshift} property of
599 @code{NoteColumn}. The lower two notes of the first chord (i.e,
600 those in the third voice) should not be shifted away from the
601 note column of the higher two notes. To correct this we set
602 @code{force-hshift} of these notes to zero.
603 The lower note of the second chord is best placed just to the
604 right of the higher notes. We achieve this by setting
605 @code{force-hshift} of this note to 0.5, ie half a notehead's
606 width to the right of the note column of the higher notes.
608 Here's the final result:
610 @lilypond[quote,verbatim,fragment,ragged-right]
611 \new Staff \relative c'' {
617 \once \override NoteColumn #'force-hshift = #0 <ees c>2
618 \once \override NoteColumn #'force-hshift = #0.5 des2