1 @node Properties, , , Reference Manual
3 Properties are Scheme values, so they have a type. The type of a
4 property is listed in parentheses after the property name.
11 @item @code{Generic_property_list}
12 Defines names and types for generic properties. These are properties
13 than can be plugged into the backend directly. See the init file
14 @file{generic-property.scm} for details. For internal use only.
16 @item @code{XXXVerticalExtent}@indexcode{groupVerticalExtent} @propertytype{Interval: a cons of numbers}
17 Hard code the size of the vertical group in context XXX, example
19 \property Staff.StaffVerticalExtent = #(-5.0 . 5.0)
21 The value is a cons of real numbers, that measure the extent in
25 @subsubheading Lyrics properties
27 @cindex properties!Lyrics
30 @item @code{textStyle}@indexcode{textStyle} @propertytype{string}
31 Set the font for lyrics. The available font choices are
32 @code{roman}, @code{italic}, @code{bold}, @code{large}, @code{Large},
33 @code{typewriter}, and @code{finger}. The @code{finger} font can
34 only display numbers. Note also that you must be careful when
35 using @code{\property} in Lyrics mode, because of the way strings
36 are parsed. Either put quotes around the arguments to
37 @code{\property} or be sure to leave a space on both sides of the
41 @subsubheading Thread properties
43 @cindex properties!Thread
46 @item @code{noteheadStyle}@indexcode{noteheadStyle} @propertytype{string}
47 Selects type of note head. Choices are @code{cross},
48 @code{diamond}, @code{harmonic}, @code{transparent}, and @code{""}.
49 They are shown in that order below.
51 @mudela[center,verbatim]
54 \property Staff.barNonAuto = 1
55 \property Voice.noteHeadStyle = cross
57 \property Voice.noteHeadStyle = diamond
59 \property Voice.noteHeadStyle = harmonic
61 \property Voice.noteHeadStyle = transparent
63 \property Voice.noteHeadStyle = ""
74 @subsubheading Grace properties
76 @cindex properties!Grace
80 @item @code{stemStyle}@indexcode{flagStyle} @propertytype{string}
81 By default set to @code{"grace"} meaning that all unbeamed
82 notes with flags are typeset with a slash through the flag.
83 Setting to @code{""} gives standard flags.
86 c'8 \property Voice.flagStyle = "grace" c'8
91 @subsubheading Voice properties
93 @cindex properties!Voice
96 @item @code{abbrev}@indexcode{abbrev} @propertytype{integer}
97 Set length for tremolo to be used if no length is explicitly
100 @item @code{articulationScriptPadding}@indexcode{articulationScriptPadding}
101 Determines the extra space added between articulation marks, such
102 as staccato, tenuto, trill, up/down bow or fermata, and the
103 closest staff line or note.
105 @item @code{articulationScriptVerticalDirection} @propertytype{direction}
106 @indexcode{articulationScriptVerticalDirection}
107 Determines the location of articulation marks. Set to @code{\up}
108 to print marks above the staff; set to @code{\down} to print marks
109 below the staff. This property does not override explicit
110 directions marked with `@code{^}' or `@code{_}' in the mudela file.
112 @item @code{noAutoBeaming}@indexcode{beamAuto} @propertytype{boolean}
113 If set to 1 then beams are not generated automatically.
115 @item @code{beamAutoEnd}@indexcode{beamAutoEnd} @propertytype{?}
116 Specifies when automatically generated beams can end. See
117 section XREF-autobeam [FIXME].
119 @item @code{beamAutoBegin}@indexcode{beamAutoBegin} @propertytype{?}
120 Specifies when automatically generated beams can start. See
121 section XREF-autobeam [FIXME].
125 @item @code{beamQuantisation}@indexcode{beamQuantisation} @propertytype{symbol}
126 Set to @code{\none} for no quantization. Set to @code{\normal} to
127 quantize position and slope. Set to @code{\traditional} to avoid
128 wedges. These three settings are available via
129 @code{\beamposfree}@keyindex{beamposfree},
130 @code{\beamposnormal}@keyindex{beamposnormal}, and
131 @code{\beampostraditional}@keyindex{beampostraditional}.
133 @item @code{beamSlopeDamping}@indexcode{beamSlopeDamping} @propertytype{number}
134 Set to @code{\none} for undamped beams. Set to @code{\normal} for
135 damped beams. Set to @code{\infinity} for beams with zero slope.
137 @code{\beamslopeproportional}@keyindex{beamslopeproportional},
138 @code{\beamslopedamped}@keyindex{beamslopedamped}, and
139 @code{\beamslopezero}@keyindex{beamslopezero} each set the
142 @item @code{dynamicDirection}@indexcode{dynamicDirection} @propertytype{direction}
143 Determines location of dynamic marks. Set to @code{\up} to print
144 marks above the staff; set to @code{\down} to print marks below
147 @item @code{dynamicStyle}@indexcode{dynamicStyle} @propertytype{string}
148 Set the text style for dynamics.
150 @item @code{fontSize}@indexcode{fontSize} @propertytype{number}
151 Can be used to select smaller font sizes for music. The normal
152 font size is 0, and the two smaller sizes are -1
156 c''16 \property Staff.fontSize = -2 c''16
159 @item @code{forceHorizontalShift}@indexcode{forceHorizontalShift}
160 Force horizontal shift for collision resolution. It overrides
161 automatic collision resolution. The value is the shift amount
162 expressed in @code{note_width}, as set in the paper section.
164 @item @code{collisionMergeDotted}@indexcode{collisionMergeDotted} @propertytype{boolean}
166 Merge noteheads in collisions, even if they have a different number of
167 dots. This normal notation for polyphonic guitar music.
169 @mudelafile[verbatim]{force-hshift.ly}
172 [FIXME: this should be moved]
174 Lilypond always arranges note heads on alternate sides of a stem (that
175 is, within a single voice) as necessary to prevent collisions (note head
176 overlaps). For up stems, the upper note of a colliding pair is placed
177 on the right side of the stem, the lower on the left. For down stems,
178 the algorithm works in reverse.
180 Lily also attempts to prevent collisions of note heads in different
181 voices. A situation where chords of two or more voices are played
182 simultaneously within one staff.
184 By default, if only two voices (and both have opposite stem directions)
185 are in this 'collision group', the notes both are shifted by @code{0.5
186 \quartwidth} if there are unisons or seconds between the voices.
188 If there are more than two voices in a collision group, shifting is
189 inactive by default, since in this case, there are multiple chords with
190 the same stem direction. By distinguish between those chords, LilyPond
191 can do collision resolution in these cases as well.
193 Distinguishing between voices with the same stem direction, is done by
194 setting the property @code{Voice.horizontalNoteShift}. It must be set
195 to a different integer for each voice. Then, all note heads in collision
196 groups (not just unisons and seconds) will be offset, one voice relative
197 another. The following fragment of sheet music shows how shifting is
198 done, with values of @code{horizontalNoteShift} printed over and under
199 the notes. In this case the chords are just simple notes.
201 @c URG : mudela book bug.
202 @mudela[singleline,verbatim]
204 \notes \context Staff <
205 \context Voice = VA { \stemup f''4^"0" }
206 \context Voice = VB {\stemup
207 \property Voice.horizontalNoteShift = 1 d''4^" 1" }
208 \context Voice = VC { \stemup \property
209 Voice.horizontalNoteShift = 2 b'4^" 2" }
210 \context Voice = VD { \stemdown \property
211 Voice.horizontalNoteShift = 1 g'4_"1 " }
212 \context Voice = VE { \stemdown e'4_"0" }
217 If you are not satisfied with the collision resolution of LilyPond, you
218 can override the horizontal shift value of the chord of one Voice, by
219 setting @code{forceHorizontalShift}. This sets the amount shift,
220 measured in black note head widths.
222 To take complete control of note position shifts in complex passages,
223 you have set things up for normal collisions and override all shifts by
224 setting @code{forceHorizontalShift} to zero everywhere
226 \property Voice.horizontalNoteShift = <n>
227 \property Voice.forceHorizontalShift = "0.0"
230 Then you can set the force property to a suitable value before each note
231 that really needs it (unisons and seconds), and reset it to 0.0 after
234 @item @code{horizontalNoteShift}@indexcode{horizontalNoteShift} @propertytype{integer}
235 Enable LilyPond to shift notes horizontally if they collide with
236 other notes. This is useful when typesetting many voices on one
237 staff. The identifier @code{\shift}@keyindex{shift} is defined to
238 enable this. Traditionally, the outer chords (the upmost and
239 downmost voices), should have no @code{horizontalNoteShift}.
241 @item @code{markScriptPadding}@indexcode{markScriptPadding} @propertytype{number}
242 Determines the extra space added between the mark and the closest
245 @item @code{markDirection}@indexcode{markDirection} @propertytype{direction}
246 Determines if marks should be printed above or below the staff.
247 Set to @code{\up} to print marks above the staff; set to
248 @code{\down} to print marks below the staff.
250 @item @code{midiInstrument}@indexcode{midiInstrument} @propertytype{string}
251 Sets the instrument for MIDI output. If this property is not set
252 then LilyPond will use the @code{instrument} property. This must
253 be set to one of the strings on the list of MIDI instruments that
254 appears in section XREF-midilist [FIXME]. If you use a string which
255 is not listed, LilyPond will silently substitute piano.
257 @item @code{restStyle}@indexcode{restStyle} @propertytype{string}
258 Change the layout of rests shorter than quarter notes.
259 Currently, the standard layout @code{""} and mensural notation
260 @code{"mensural"} are available. Mensural rests of duration
261 32 or shorter are not available.
263 r\longa r\breve r1 r2 r4 r8 r16 r32 r64 r128 r128
264 \property Staff.restStyle = "mensural"
265 r\longa r\breve r1 r2 r4 r8 r16 r32 r64 r128 r128
268 @item @code{scriptHorizontal}@indexcode{scriptHorizontal} @propertytype{boolean}
269 Put scripts left or right of note heads. Support for this is
270 limited. Accidentals will collide with scripts.
272 @item @code{slurVerticalDirection}@indexcode{slurVerticalDirection} @propertytype{direction}
273 Set to @code{\free} for free choice of slur direction, set to
274 @code{\up} to force slurs up, set to @code{\down} to force slurs
275 down. The shorthands @code{\slurup}@keyindex{slurup},
276 @code{\slurdown}@keyindex{slurdown}, and
277 @code{\slurboth}@keyindex{slurboth} are available.
279 @item @code{slurDash}@indexcode{slurDash} @propertytype{number}
280 Set to NIL for normal slurs, 1 for dotted slurs, and a
281 larger value for dashed slurs. Identifiers
282 @code{\slurnormal}@keyindex{slurnormal} and
283 @code{\slurdotted}@keyindex{slurdotted} are predefined to set the
288 \property Voice.slurDash = 3
292 @item @code{stemLength}@indexcode{stemLength}
293 Set length of stems. Unit is `@code{interline}/2', so
294 @code{stemLength} defaults to 7.
296 g''4 \property Voice.stemLength = #14 g4 \property Voice.stemLength = #3 g4 g,,4
299 @item @code{stemLeftBeamCount}@indexcode{stemLeftBeamCount} @propertytype{integer}
300 Specify the number of beams to draw on the left side of the next
301 note. Overrides automatic beaming. The value is only used once,
302 and then it is erased.
304 @item @code{stemRightBeamCount}@indexcode{stemRightBeamCount} @propertytype{integer}
305 Specify the number of beams to draw on the right side of the next
306 note. Overrides automatic beaming. The value is only used once,
307 and then it is erased.
309 @item @code{tieDash}@indexcode{tieDash} @propertytype{integer}
310 Set dashing of ties. See also @code{slurDash}
312 @item @code{tieVerticalDirection}@indexcode{tieVerticalDirection} @propertytype{direction}
313 Set to @code{\free} for free choice of tie direction, set to
314 @code{\up} to force ties up, set to @code{\down} to force ties
317 @item @code{transposing}@indexcode{transposing} @propertytype{integer}
318 Transpose the MIDI output. Set this property to the number of
319 half-steps to transpose by.
321 @item @code{textEmptyDimension}@indexcode{textEmptyDimension} @propertytype{boolean}
322 If set to true then text placed above or below the staff is
323 assumed to have zero width. @code{fatText} and @code{emptyText}
324 are predefined settings.
327 c4^"foo" \emptyText c4^"foo" c4
330 @item @code{textStyle}@indexcode{textStyle} @propertytype{string}
331 Set the text style for superscripts and subscripts. See above
332 for list of text styles.
334 @item @code{textScriptPadding}@indexcode{textScriptPadding} @propertytype{number}
335 Determines the extra space added between superscripted resp.
336 subscripted text and the closest staff line or note.
338 @item @code{verticalDirection}@indexcode{verticalDirection} @propertytype{direction}
339 Determines the direction of stems, subscripts, beams, slurs, and
340 ties. Set to @code{\down} to force them down, @code{\up} to force
341 them up, or @code{\free} to let LilyPond decide. This can be used
342 to distinguish between voices on the same staff. The
343 @code{\stemdown}@keyindex{stemdown}, @code{\stemup}@keyindex{stemup},
344 and @code{\stemboth}@keyindex{stemboth} identifiers set this
348 @item @code{tupletDirection}@indexcode{tupletDirection} @propertytype{direction}
349 Determines the direction of triplets and other tuplets. Set to
350 @code{\down} to force them below the staff, @code{\up} to force
351 them above, or @code{\free} to let LilyPond decide.
353 @item @code{tupletBracketVisibility}@indexcode{tupletBracketVisibility} @propertytype{boolean} or @propertytype{symbol}
354 @item @code{tupletNumberVisibility}@indexcode{tupletNumberVisibility} @propertytype{boolean} or @propertytype{symbol}
356 These properties the visibility of the tuplet bracket and its
357 number respectively. Setting it to false will prevent printing of the
358 associated element. Setting the property to 'if-no-beam will make it
359 print only if there is no beam associated with this tuplet bracket.
363 @item @code{tupletInvisible}@indexcode{tupletInvisible} @propertytype{boolean}
365 If set to true, tuplet bracket creation is switched off
366 entirely. This has the same effect as setting both
367 @code{tupletNumberVisibility} and @code{tupletBracketVisibility} to
368 @code{#f}, but as this does not even create elements, this setting
369 uses less memory and time.
372 @item @code{tupletSpannerDuration} @indexcode{tupletSpannerDuration}
373 @propertytype{moment}
375 Normally a tuplet bracket is as wide as the
376 @code{\times} expression that gave rise to it. By setting this
377 property, you can make brackets last shorter. Example
379 @mudela[verbatim,fragment]
380 \context Voice \times 2/3 {
381 \property Voice.tupletSpannerDuration = #(make-moment 1 4)
388 @subsubheading Staff properties
390 @cindex properties!Staff
394 @item @code{barNonAuto}@indexcode{barNonAuto} @propertytype{boolean}
395 If set to true then bar lines will not be printed
396 automatically; they must be explicitly created with @code{\bar}
397 keywords. Unlike with the @code{\cadenza} keyword, measures are
398 still counted. Bar generation will resume according to that
399 count if this property is set to zero.
401 @item @code{barNumberDirection}@indexcode{barNumberDirection} @propertytype{direction}
402 Set to @code{\up} or @code{\down} to put bar numbers above or below
405 @item @code{barNumberScriptPadding}@indexcode{barNumberScriptPadding}
406 Sets extra space between the bar number and the bar it labels.
408 @item @code{barSize}@indexcode{barSize}
409 Specify the height of the bar lines if it should be different
410 than the staff height.
412 c1 c1 \property Staff.barSize = 20 c1 c1
415 @item @code{barAtLineStart}@indexcode{barAtLineStart} @propertytype{boolean}
416 Set to true to produce a bar line after the clef at the start
417 of each line (but not at the beginning of the music).
421 @item @code{clefStyle}@indexcode{clefStyle} @propertytype{string}
422 Determines how clefs are typeset. If set to @code{transparent},
423 the clefs are not printed at all, if set to
424 @code{fullSizeChanges}, clef changes in the middle of a line are
425 typeset with a full size clef. By default, clef changes are
426 typeset in smaller size.
428 @item @code{supportedClefTypes}@indexcode{supportedClefTypes} @propertytype{alist}
430 Clef settings supported. The value is an association list clef
431 descriptions indexed by clef name (alto, baritone, etc.). A clef
432 description is a list with the glyph name, and the staff position
433 where it should go. For internal use.
435 @item @code{clefPitches}@indexcode{clefPitches} @propertytype{alist}
436 Settings for the position of the central C, relative to this clef
437 symbol. For internal use.
439 @item @code{defaultClef}@indexcode{defaultClef} @propertytype{string}
440 Clef setting to use when this context is created. If unset,
441 no clef is printed upon creation.
443 @item @code{marginDirection}@indexcode{marginDirection} @propertytype{direction}
444 Set to @code{\left} or @code{\right} to specify location of
447 @item @code{marginScriptPadding}@indexcode{marginScriptPadding}
448 Specify extra space for marginal scripts.
450 @item @code{forgetAccidentals}@indexcode{forgetAccidentals} @propertytype{boolean}
451 Causes accidentals to be printed at every note instead of
452 remembered for the duration of a measure.
454 @item @code{noResetKey}@indexcode{noResetKey} @propertytype{boolean}
455 Do not reset the key at the start of a measure. Accidentals will
456 be printed only once and are in effect until overridden, possibly
459 @item @code{staffSpace}@indexcode{staffLineLeading} @propertytype{number}
460 Specifies the distance (in points) between lines of the staff.
462 @item @code{numberOfStaffLines}@indexcode{numberOfStaffLines} @propertytype{integer}
463 Specifies the number of staff lines. The default is 5.
465 @item @code{postBreakPadding}@indexcode{postBreakPadding} @propertytype{number}
466 Extra space in points to be added after the clef, time signature
467 and key signature on the staff. Deprecated, do not use.
469 @item @code{noVoltaBraces}@indexcode{noVoltaBraces} @propertytype{boolean}
470 Set to true to suppress the printing of brackets over alternate
471 endings specified by the command @code{\alternative}.
474 @item @code{barAlways}@indexcode{barAlways} @propertytype{boolean}
475 If set to true a bar line is drawn after each note.
477 @item @code{defaultBarType}@indexcode{defaultBarType} @propertytype{string}
478 Sets the default type of bar line. See Section XREF-barlines [FIXME]
479 for a list of available bar types.
481 @item @code{instrument}, @code{instr} @propertytype{string}
482 @indexcode{instrument}@indexcode{instr}
483 If @code{Instrument_name_engraver}
484 @cindex Instrument_name_engraver
486 added to the Staff translator, then the @code{instrument} property
487 is used to label the first line of the staff and the @code{instr}
488 property is used to label subsequent lines. If the
489 @code{midiInstrument} property is not set, then @code{instrument}
490 is used to determine the instrument for MIDI output.
492 @item @code{keyOctaviation}@indexcode{keyOctaviation} @propertytype{boolean}
493 If set to false, then keys are the same in all octaves. If set
494 to true then the key signature for different octaves can be
495 different and is specified independently:
498 \keysignature bes fis'
501 The default value is @code{#f}. Can be set to @code{#t} with
502 @code{\specialkey} or reset with @code{\normalkey}.
504 @item @code{timeSignatureStyle}@indexcode{timeSignatureStyle} @propertytype{string}
505 Changes the default two-digit layout for time signatures. The
506 following values are recognized:
509 @item @code{C}@indexcode{C}
510 4/4 and 2/2 are typeset as C and struck C, respectively. All
511 other time signatures are written with two digits.
513 @item @code{old}@indexcode{old}
514 2/2, 3/2, 2/4, 3/4, 4/4, 6/4, 9/4, 4/8, 6/8 and 9/8 are
515 typeset with old-style mensuration marks. All other time
516 signatures are written with two digits.
518 @item @code{1}@indexcode{1}
519 All time signatures are typeset with a single
520 digit, e.g. 3/2 is written as 3.
522 @item @indexcode{CM/N}@code{C}@var{M}@code{/}@var{N},
523 @indexcode{oldM/N}@code{old}@var{M}@code{/}@var{N} or
524 @code{old6/8alt}@indexcode{old6/8alt}
525 Tells LilyPond to use a specific symbol as time signature.
528 The different time signature characters are shown below with its
531 @mudela[center,verbatim]
534 \notes\relative c'' {
535 \property Voice.textStyle = typewriter
536 \property Staff.timeSignatureStyle = "C2/2"
537 \time 2/2; a2^"C2/2" a2
538 \property Staff.timeSignatureStyle = "C4/4"
539 \time 2/2; a2^"C4/4" a2
540 \property Staff.timeSignatureStyle = "old2/2"
541 \time 2/2; a2^"old2/2" a2
542 \property Staff.timeSignatureStyle = "old3/2"
543 \time 2/2; a2^"old3/2" a2
544 \property Staff.timeSignatureStyle = "old2/4"
545 \time 2/2; a2^"old2/4" a2
546 \property Staff.timeSignatureStyle = "old4/4"
547 \time 2/2; a2^"old4/4" a2
548 \property Staff.timeSignatureStyle = "old6/4"
549 \time 2/2; a2^"old6/4" a2
550 \property Staff.timeSignatureStyle = "old9/4"
551 \time 2/2; a2^"old9/4" a2
552 \property Staff.timeSignatureStyle = "old4/8"
553 \time 2/2; a2^"old4/8" a2
554 \property Staff.timeSignatureStyle = "old6/8"
555 \time 2/2; a2^"old6/8" a2
556 \property Staff.timeSignatureStyle = "old6/8alt"
557 \time 2/2; a2^"old6/8alt" a2
558 \property Staff.timeSignatureStyle = "old9/8"
559 \time 2/2; a2^"old9/8" a2
568 @item @code{voltaSpannerDuration}@indexcode{voltaSpannerDuration} @propertytype{moment}
569 Set to an integer to control the size of the brackets printed by
570 @code{\alternative}. The integer specifies the number of whole
571 notes duration to use for the brackets. It is rounded to the
572 nearest measure. This can be used to shrink the length of
573 brackets in the situation where one alternative is very large.
574 It may have odd effects if the specified duration is longer than
575 the music given in an @code{\alternative}.
578 @subsubheading GrandStaff properties
580 @cindex properties!GrandStaff
583 @item @code{maxVerticalAlign}@indexcode{maxVerticalAlign} @propertytype{number}
584 Set the maximum vertical distance between staffs.
586 @item @code{minVerticalAlign}@indexcode{minVerticalAlign} @propertytype{number}
587 Set the minimum vertical distance between staffs.
590 @subsubheading Score properties
592 @cindex properties!Score
595 @item @code{skipBars}@indexcode{skipBars} @propertytype{boolean}
596 Set to 1 to skip the empty bars that are produced by
597 multimeasure notes and rests. These bars will not appear on the
598 printed output. Set to zero (the default) to expand multimeasure
599 notes and rests into their full length, printing the appropriate
600 number of empty bars so that synchronization with other voices is
605 @mudela[fragment,verbatim,center]
606 r1 r1*3 R1*3\property Score.skipBars=1 r1*3 R1*3
611 @item @code{breakAlignOrder}@indexcode{breakAlignOrder} @propertytype{list of string}
613 Defines the order in which prefatory matter (clefs, key signatures) appears, eg. this puts the key signatures after the bar lines:
615 \property Score.breakAlignOrder = #'(
626 @subsubheading ChordNamesVoice properties
628 @cindex properties!ChordNamesVoice
631 @item @code{chordInversion}@indexcode{chordInversion} @propertytype{boolean}
632 Determines whether LilyPond should look for chord inversions when
633 translating from notes to chord names. Set to 1 to find
634 inversions. The default is 0 which does not look for