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.
15 @item @code{Generic_property_list}
16 Defines names and types for generic properties. These are properties
17 than can be plugged into the backend directly. See the init file
18 @file{generic-property.scm} for details. For internal use only.
20 @item @code{XXXVerticalExtent}@indexcode{groupVerticalExtent} @propertytype{Interval: a cons of numbers}
21 Hard code the size of the vertical group in context XXX, example
23 \property Staff.StaffVerticalExtent = #(-5.0 . 5.0)
25 The value is a cons of real numbers, that measure the extent in
29 @subsubheading Lyrics properties
31 @cindex properties!Lyrics
34 @item @code{textStyle}@indexcode{textStyle} @propertytype{string}
35 Set the font for lyrics. The available font choices are
36 @code{roman}, @code{italic}, @code{bold}, @code{large}, @code{Large},
37 @code{typewriter}, and @code{finger}. The @code{finger} font can
38 only display numbers. Note also that you must be careful when
39 using @code{\property} in Lyrics mode, because of the way strings
40 are parsed. Either put quotes around the arguments to
41 @code{\property} or be sure to leave a space on both sides of the
45 @subsubheading Thread properties
47 @cindex properties!Thread
50 @item @code{noteHeadStyle}@indexcode{noteHeadStyle} @propertytype{symbol}
51 Selects type of note head. Choices are @code{'cross},
52 @code{'diamond}, @code{'harmonic}, @code{'transparent},
53 @code{'mensural}, @code{'baroque}, and @code{'default}.
54 They are shown in that order below. The @code{'baroque},
55 style gives the default symbols except for brevis and
56 longa notes which are square shaped as in the @code{'mensural}
59 @mudela[center,verbatim]
62 \property Staff.barNonAuto = 1
63 \property Voice.noteHeadStyle = #'cross
65 \property Voice.noteHeadStyle = #'diamond
67 \property Voice.noteHeadStyle = #'harmonic
69 \property Voice.noteHeadStyle = #'transparent
71 \property Voice.noteHeadStyle = #'mensural
73 \property Voice.noteHeadStyle = #'default
84 @subsubheading Grace properties
86 @cindex properties!Grace
90 @item @code{stemStyle}@indexcode{flagStyle} @propertytype{string}
91 By default set to @code{"grace"} meaning that all unbeamed
92 notes with flags are typeset with a slash through the flag.
93 Setting to @code{""} gives standard flags.
96 c'8 \property Voice.flagStyle = "grace" c'8
101 @subsubheading Voice properties
103 @cindex properties!Voice
106 @item @code{abbrev}@indexcode{abbrev} @propertytype{integer}
107 Set length for tremolo to be used if no length is explicitly
110 @item @code{articulationScriptPadding}@indexcode{articulationScriptPadding}
111 Determines the extra space added between articulation marks, such
112 as staccato, tenuto, trill, up/down bow or fermata, and the
113 closest staff line or note.
115 @item @code{articulationScriptVerticalDirection} @propertytype{direction}
116 @indexcode{articulationScriptVerticalDirection}
117 Determines the location of articulation marks. Set to @code{\up}
118 to print marks above the staff; set to @code{\down} to print marks
119 below the staff. This property does not override explicit
120 directions marked with `@code{^}' or `@code{_}' in the mudela file.
122 @item @code{noAutoBeaming}@indexcode{beamAuto} @propertytype{boolean}
123 If set to 1 then beams are not generated automatically.
125 @item @code{beamAutoEnd}@indexcode{beamAutoEnd} @propertytype{?}
126 Specifies when automatically generated beams can end. See
127 section XREF-autobeam [FIXME].
129 @item @code{beamAutoBegin}@indexcode{beamAutoBegin} @propertytype{?}
130 Specifies when automatically generated beams can start. See
131 section XREF-autobeam [FIXME].
135 @item @code{beamQuantisation}@indexcode{beamQuantisation} @propertytype{symbol}
136 Set to @code{\none} for no quantization. Set to @code{\normal} to
137 quantize position and slope. Set to @code{\traditional} to avoid
138 wedges. These three settings are available via
139 @code{\beamposfree}@keyindex{beamposfree},
140 @code{\beamposnormal}@keyindex{beamposnormal}, and
141 @code{\beampostraditional}@keyindex{beampostraditional}.
143 @item @code{beamSlopeDamping}@indexcode{beamSlopeDamping} @propertytype{number}
144 Set to @code{\none} for undamped beams. Set to @code{\normal} for
145 damped beams. Set to @code{\infinity} for beams with zero slope.
147 @code{\beamslopeproportional}@keyindex{beamslopeproportional},
148 @code{\beamslopedamped}@keyindex{beamslopedamped}, and
149 @code{\beamslopezero}@keyindex{beamslopezero} each set the
152 @item @code{dynamicDirection}@indexcode{dynamicDirection} @propertytype{direction}
153 Determines location of dynamic marks. Set to @code{\up} to print
154 marks above the staff; set to @code{\down} to print marks below
157 @item @code{dynamicStyle}@indexcode{dynamicStyle} @propertytype{string}
158 Set the text style for dynamics.
160 @item @code{fontSize}@indexcode{fontSize} @propertytype{number}
161 Can be used to select smaller font sizes for music. The normal
162 font size is 0, and the two smaller sizes are -1
166 c''16 \property Staff.fontSize = -2 c''16
169 @item @code{forceHorizontalShift}@indexcode{forceHorizontalShift}
170 Force horizontal shift for collision resolution. It overrides
171 automatic collision resolution. The value is the shift amount
172 expressed in @code{note_width}, as set in the paper section.
174 @item @code{collisionMergeDotted}@indexcode{collisionMergeDotted} @propertytype{boolean}
176 Merge noteheads in collisions, even if they have a different number of
177 dots. This normal notation for polyphonic guitar music.
179 @mudelafile[verbatim]{force-hshift.ly}
182 [FIXME: this should be moved]
184 Lilypond always arranges note heads on alternate sides of a stem (that
185 is, within a single voice) as necessary to prevent collisions (note head
186 overlaps). For up stems, the upper note of a colliding pair is placed
187 on the right side of the stem, the lower on the left. For down stems,
188 the algorithm works in reverse.
190 Lily also attempts to prevent collisions of note heads in different
191 voices. A situation where chords of two or more voices are played
192 simultaneously within one staff.
194 By default, if only two voices (and both have opposite stem directions)
195 are in this 'collision group', the notes both are shifted by @code{0.5
196 \quartwidth} if there are unisons or seconds between the voices.
198 If there are more than two voices in a collision group, shifting is
199 inactive by default, since in this case, there are multiple chords with
200 the same stem direction. By distinguish between those chords, LilyPond
201 can do collision resolution in these cases as well.
203 Distinguishing between voices with the same stem direction, is done by
204 setting the property @code{Voice.horizontalNoteShift}. It must be set
205 to a different integer for each voice. Then, all note heads in collision
206 groups (not just unisons and seconds) will be offset, one voice relative
207 another. The following fragment of sheet music shows how shifting is
208 done, with values of @code{horizontalNoteShift} printed over and under
209 the notes. In this case the chords are just simple notes.
211 @c URG : mudela book bug.
212 @mudela[singleline,verbatim]
214 \notes \context Staff <
215 \context Voice = VA { \stemup f''4^"0" }
216 \context Voice = VB {\stemup
217 \property Voice.horizontalNoteShift = 1 d''4^" 1" }
218 \context Voice = VC { \stemup \property
219 Voice.horizontalNoteShift = 2 b'4^" 2" }
220 \context Voice = VD { \stemdown \property
221 Voice.horizontalNoteShift = 1 g'4_"1 " }
222 \context Voice = VE { \stemdown e'4_"0" }
227 If you are not satisfied with the collision resolution of LilyPond, you
228 can override the horizontal shift value of the chord of one Voice, by
229 setting @code{forceHorizontalShift}. This sets the amount shift,
230 measured in black note head widths.
232 To take complete control of note position shifts in complex passages,
233 you have set things up for normal collisions and override all shifts by
234 setting @code{forceHorizontalShift} to zero everywhere
236 \property Voice.horizontalNoteShift = <n>
237 \property Voice.forceHorizontalShift = "0.0"
240 Then you can set the force property to a suitable value before each note
241 that really needs it (unisons and seconds), and reset it to 0.0 after
244 @item @code{horizontalNoteShift}@indexcode{horizontalNoteShift} @propertytype{integer}
245 Enable LilyPond to shift notes horizontally if they collide with
246 other notes. This is useful when typesetting many voices on one
247 staff. The identifier @code{\shift}@keyindex{shift} is defined to
248 enable this. Traditionally, the outer chords (the upmost and
249 downmost voices), should have no @code{horizontalNoteShift}.
251 @item @code{markScriptPadding}@indexcode{markScriptPadding} @propertytype{number}
252 Determines the extra space added between the mark and the closest
255 @item @code{markDirection}@indexcode{markDirection} @propertytype{direction}
256 Determines if marks should be printed above or below the staff.
257 Set to @code{\up} to print marks above the staff; set to
258 @code{\down} to print marks below the staff.
260 @item @code{midiInstrument}@indexcode{midiInstrument} @propertytype{string}
261 Sets the instrument for MIDI output. If this property is not set
262 then LilyPond will use the @code{instrument} property. This must
263 be set to one of the strings on the list of MIDI instruments that
264 appears in section XREF-midilist [FIXME]. If you use a string which
265 is not listed, LilyPond will silently substitute piano.
267 @item @code{restStyle}@indexcode{restStyle} @propertytype{string}
268 Change the layout of rests shorter than quarter notes.
269 Currently, the standard layout @code{""} and mensural notation
270 @code{"mensural"} are available. Mensural rests of duration
271 32 or shorter are not available.
273 r\longa r\breve r1 r2 r4 r8 r16 r32 r64 r128 r128
274 \property Staff.restStyle = "mensural"
275 r\longa r\breve r1 r2 r4 r8 r16 r32 r64 r128 r128
278 @item @code{scriptHorizontal}@indexcode{scriptHorizontal} @propertytype{boolean}
279 Put scripts left or right of note heads. Support for this is
280 limited. Accidentals will collide with scripts.
282 @item @code{slurVerticalDirection}@indexcode{slurVerticalDirection} @propertytype{direction}
283 Set to @code{\free} for free choice of slur direction, set to
284 @code{\up} to force slurs up, set to @code{\down} to force slurs
285 down. The shorthands @code{\slurup}@keyindex{slurup},
286 @code{\slurdown}@keyindex{slurdown}, and
287 @code{\slurboth}@keyindex{slurboth} are available.
289 @item @code{slurDash}@indexcode{slurDash} @propertytype{number}
290 Set to NIL for normal slurs, 1 for dotted slurs, and a
291 larger value for dashed slurs. Identifiers
292 @code{\slurnormal}@keyindex{slurnormal} and
293 @code{\slurdotted}@keyindex{slurdotted} are predefined to set the
298 \property Voice.slurDash = 3
302 @item @code{stemLength}@indexcode{stemLength}
303 Set length of stems. Unit is `@code{interline}/2', so
304 @code{stemLength} defaults to 7.
306 g''4 \property Voice.stemLength = #14 g4 \property Voice.stemLength = #3 g4 g,,4
309 @item @code{stemLeftBeamCount}@indexcode{stemLeftBeamCount} @propertytype{integer}
310 Specify the number of beams to draw on the left side of the next
311 note. Overrides automatic beaming. The value is only used once,
312 and then it is erased.
314 @item @code{stemRightBeamCount}@indexcode{stemRightBeamCount} @propertytype{integer}
315 Specify the number of beams to draw on the right side of the next
316 note. Overrides automatic beaming. The value is only used once,
317 and then it is erased.
319 @item @code{tieDash}@indexcode{tieDash} @propertytype{integer}
320 Set dashing of ties. See also @code{slurDash}
322 @item @code{tieVerticalDirection}@indexcode{tieVerticalDirection} @propertytype{direction}
323 Set to @code{\free} for free choice of tie direction, set to
324 @code{\up} to force ties up, set to @code{\down} to force ties
327 @item @code{transposing}@indexcode{transposing} @propertytype{integer}
328 Transpose the MIDI output. Set this property to the number of
329 half-steps to transpose by.
331 @item @code{textEmptyDimension}@indexcode{textEmptyDimension} @propertytype{boolean}
332 If set to true then text placed above or below the staff is
333 assumed to have zero width. @code{fatText} and @code{emptyText}
334 are predefined settings.
337 c4^"foo" \emptyText c4^"foo" c4
340 @item @code{textStyle}@indexcode{textStyle} @propertytype{string}
341 Set the text style for superscripts and subscripts. See above
342 for list of text styles.
344 @item @code{textScriptPadding}@indexcode{textScriptPadding} @propertytype{number}
345 Determines the extra space added between superscripted resp.
346 subscripted text and the closest staff line or note.
348 @item @code{verticalDirection}@indexcode{verticalDirection} @propertytype{direction}
349 Determines the direction of stems, subscripts, beams, slurs, and
350 ties. Set to @code{\down} to force them down, @code{\up} to force
351 them up, or @code{\free} to let LilyPond decide. This can be used
352 to distinguish between voices on the same staff. The
353 @code{\stemdown}@keyindex{stemdown}, @code{\stemup}@keyindex{stemup},
354 and @code{\stemboth}@keyindex{stemboth} identifiers set this
358 @item @code{tupletDirection}@indexcode{tupletDirection} @propertytype{direction}
359 Determines the direction of triplets and other tuplets. Set to
360 @code{\down} to force them below the staff, @code{\up} to force
361 them above, or @code{\free} to let LilyPond decide.
363 @item @code{tupletBracketVisibility}@indexcode{tupletBracketVisibility} @propertytype{boolean} or @propertytype{symbol}
364 @item @code{tupletNumberVisibility}@indexcode{tupletNumberVisibility} @propertytype{boolean} or @propertytype{symbol}
366 These properties the visibility of the tuplet bracket and its
367 number respectively. Setting it to false will prevent printing of the
368 associated element. Setting the property to 'if-no-beam will make it
369 print only if there is no beam associated with this tuplet bracket.
373 @item @code{tupletInvisible}@indexcode{tupletInvisible} @propertytype{boolean}
375 If set to true, tuplet bracket creation is switched off
376 entirely. This has the same effect as setting both
377 @code{tupletNumberVisibility} and @code{tupletBracketVisibility} to
378 @code{#f}, but as this does not even create elements, this setting
379 uses less memory and time.
382 @item @code{tupletSpannerDuration} @indexcode{tupletSpannerDuration}
383 @propertytype{moment}
385 Normally a tuplet bracket is as wide as the
386 @code{\times} expression that gave rise to it. By setting this
387 property, you can make brackets last shorter. Example
389 @mudela[verbatim,fragment]
390 \context Voice \times 2/3 {
391 \property Voice.tupletSpannerDuration = #(make-moment 1 4)
398 @subsubheading Staff properties
400 @cindex properties!Staff
404 @item @code{barNonAuto}@indexcode{barNonAuto} @propertytype{boolean}
405 If set to true then bar lines will not be printed
406 automatically; they must be explicitly created with @code{\bar}
407 keywords. Unlike with the @code{\cadenza} keyword, measures are
408 still counted. Bar generation will resume according to that
409 count if this property is set to zero.
411 @item @code{barNumberDirection}@indexcode{barNumberDirection} @propertytype{direction}
412 Set to @code{\up} or @code{\down} to put bar numbers above or below
415 @item @code{barNumberScriptPadding}@indexcode{barNumberScriptPadding}
416 Sets extra space between the bar number and the bar it labels.
418 @item @code{barSize}@indexcode{barSize}
419 Specify the height of the bar lines if it should be different
420 than the staff height.
422 c1 c1 \property Staff.barSize = 20 c1 c1
425 @item @code{barAtLineStart}@indexcode{barAtLineStart} @propertytype{boolean}
426 Set to true to produce a bar line after the clef at the start
427 of each line (but not at the beginning of the music).
431 @item @code{clefStyle}@indexcode{clefStyle} @propertytype{string}
432 Determines how clefs are typeset. If set to @code{transparent},
433 the clefs are not printed at all, if set to
434 @code{fullSizeChanges}, clef changes in the middle of a line are
435 typeset with a full size clef. By default, clef changes are
436 typeset in smaller size.
438 @item @code{supportedClefTypes}@indexcode{supportedClefTypes} @propertytype{alist}
440 Clef settings supported. The value is an association list clef
441 descriptions indexed by clef name (alto, baritone, etc.). A clef
442 description is a list with the glyph name, and the staff position
443 where it should go. For internal use.
445 @item @code{clefPitches}@indexcode{clefPitches} @propertytype{alist}
446 Settings for the position of the central C, relative to this clef
447 symbol. For internal use.
449 @item @code{defaultClef}@indexcode{defaultClef} @propertytype{string}
450 Clef setting to use when this context is created. If unset,
451 no clef is printed upon creation.
453 @item @code{marginDirection}@indexcode{marginDirection} @propertytype{direction}
454 Set to @code{\left} or @code{\right} to specify location of
457 @item @code{marginScriptPadding}@indexcode{marginScriptPadding}
458 Specify extra space for marginal scripts.
460 @item @code{forgetAccidentals}@indexcode{forgetAccidentals} @propertytype{boolean}
461 Causes accidentals to be printed at every note instead of
462 remembered for the duration of a measure.
464 @item @code{noResetKey}@indexcode{noResetKey} @propertytype{boolean}
465 Do not reset the key at the start of a measure. Accidentals will
466 be printed only once and are in effect until overridden, possibly
469 @item @code{staffSpace}@indexcode{staffLineLeading} @propertytype{number}
470 Specifies the distance (in points) between lines of the staff.
472 @item @code{numberOfStaffLines}@indexcode{numberOfStaffLines} @propertytype{integer}
473 Specifies the number of staff lines. The default is 5.
475 @item @code{postBreakPadding}@indexcode{postBreakPadding} @propertytype{number}
476 Extra space in points to be added after the clef, time signature
477 and key signature on the staff. Deprecated, do not use.
479 @item @code{noVoltaBraces}@indexcode{noVoltaBraces} @propertytype{boolean}
480 Set to true to suppress the printing of brackets over alternate
481 endings specified by the command @code{\alternative}.
484 @item @code{barAlways}@indexcode{barAlways} @propertytype{boolean}
485 If set to true a bar line is drawn after each note.
487 @item @code{defaultBarType}@indexcode{defaultBarType} @propertytype{string}
488 Sets the default type of bar line. See Section XREF-barlines [FIXME]
489 for a list of available bar types.
491 @item @code{instrument}, @code{instr} @propertytype{string}
492 @indexcode{instrument}@indexcode{instr}
493 If @code{Instrument_name_engraver}
494 @cindex Instrument_name_engraver
496 added to the Staff translator, then the @code{instrument} property
497 is used to label the first line of the staff and the @code{instr}
498 property is used to label subsequent lines. If the
499 @code{midiInstrument} property is not set, then @code{instrument}
500 is used to determine the instrument for MIDI output.
502 @item @code{keyOctaviation}@indexcode{keyOctaviation} @propertytype{boolean}
503 If set to false, then keys are the same in all octaves. If set
504 to true then the key signature for different octaves can be
505 different and is specified independently:
508 \keysignature bes fis'
511 The default value is @code{#f}. Can be set to @code{#t} with
512 @code{\specialkey} or reset with @code{\normalkey}.
514 @item @code{timeSignatureStyle}@indexcode{timeSignatureStyle} @propertytype{string}
515 Changes the default two-digit layout for time signatures. The
516 following values are recognized:
519 @item @code{C}@indexcode{C}
520 4/4 and 2/2 are typeset as C and struck C, respectively. All
521 other time signatures are written with two digits.
523 @item @code{old}@indexcode{old}
524 2/2, 3/2, 2/4, 3/4, 4/4, 6/4, 9/4, 4/8, 6/8 and 9/8 are
525 typeset with old-style mensuration marks. All other time
526 signatures are written with two digits.
528 @item @code{1}@indexcode{1}
529 All time signatures are typeset with a single
530 digit, e.g. 3/2 is written as 3.
532 @item @indexcode{CM/N}@code{C}@var{M}@code{/}@var{N},
533 @indexcode{oldM/N}@code{old}@var{M}@code{/}@var{N} or
534 @code{old6/8alt}@indexcode{old6/8alt}
535 Tells LilyPond to use a specific symbol as time signature.
538 The different time signature characters are shown below with its
541 @mudela[center,verbatim]
544 \notes\relative c'' {
545 \property Voice.textStyle = typewriter
546 \property Staff.timeSignatureStyle = "C2/2"
547 \time 2/2; a2^"C2/2" a2
548 \property Staff.timeSignatureStyle = "C4/4"
549 \time 2/2; a2^"C4/4" a2
550 \property Staff.timeSignatureStyle = "old2/2"
551 \time 2/2; a2^"old2/2" a2
552 \property Staff.timeSignatureStyle = "old3/2"
553 \time 2/2; a2^"old3/2" a2
554 \property Staff.timeSignatureStyle = "old2/4"
555 \time 2/2; a2^"old2/4" a2
556 \property Staff.timeSignatureStyle = "old4/4"
557 \time 2/2; a2^"old4/4" a2
558 \property Staff.timeSignatureStyle = "old6/4"
559 \time 2/2; a2^"old6/4" a2
560 \property Staff.timeSignatureStyle = "old9/4"
561 \time 2/2; a2^"old9/4" a2
562 \property Staff.timeSignatureStyle = "old4/8"
563 \time 2/2; a2^"old4/8" a2
564 \property Staff.timeSignatureStyle = "old6/8"
565 \time 2/2; a2^"old6/8" a2
566 \property Staff.timeSignatureStyle = "old6/8alt"
567 \time 2/2; a2^"old6/8alt" a2
568 \property Staff.timeSignatureStyle = "old9/8"
569 \time 2/2; a2^"old9/8" a2
578 @item @code{voltaSpannerDuration}@indexcode{voltaSpannerDuration} @propertytype{moment}
579 Set to an integer to control the size of the brackets printed by
580 @code{\alternative}. The integer specifies the number of whole
581 notes duration to use for the brackets. It is rounded to the
582 nearest measure. This can be used to shrink the length of
583 brackets in the situation where one alternative is very large.
584 It may have odd effects if the specified duration is longer than
585 the music given in an @code{\alternative}.
588 @subsubheading GrandStaff properties
590 @cindex properties!GrandStaff
593 @item @code{maxVerticalAlign}@indexcode{maxVerticalAlign} @propertytype{number}
594 Set the maximum vertical distance between staffs.
596 @item @code{minVerticalAlign}@indexcode{minVerticalAlign} @propertytype{number}
597 Set the minimum vertical distance between staffs.
600 @subsubheading Score properties
602 @cindex properties!Score
608 @item @code{skipBars}@indexcode{skipBars} @propertytype{boolean}
609 Set to 1 to skip the empty bars that are produced by
610 multimeasure notes and rests. These bars will not appear on the
611 printed output. Set to zero (the default) to expand multimeasure
612 notes and rests into their full length, printing the appropriate
613 number of empty bars so that synchronization with other voices is
618 @mudela[fragment,verbatim,center]
619 r1 r1*3 R1*3\property Score.skipBars=1 r1*3 R1*3
624 @item @code{breakAlignOrder}@indexcode{breakAlignOrder} @propertytype{list of string}
626 Defines the order in which prefatory matter (clefs, key signatures) appears, eg. this puts the key signatures after the bar lines:
628 \property Score.breakAlignOrder = #'(
639 @item @code{timing}@indexcode{timing} @propertytype{boolean}
640 Keep administration of measure length, position, bar number, etc?
641 Switch off for cadenzas.
643 @item @code{currentBarNumber}@indexcode{currentBarNumber} @propertytype{integer}
644 Contains the current barnumber. This property is incremented at
647 @item @code{measurePosition}@indexcode{measurePosition} @propertytype{Moment}
649 How much of the current measure (measured in whole notes) have we had?
651 @item @code{oneBeat}@indexcode{oneBeat} @propertytype{Moment}
653 How long does one beat in the current time signature last?
655 @item @code{measureLength}@indexcode{measureLength} @propertytype{Moment}
657 How long does one measure in the current time signature last?
661 @subsubheading ChordNamesVoice properties
663 @cindex properties!ChordNamesVoice
666 @item @code{chordInversion}@indexcode{chordInversion} @propertytype{boolean}
667 Determines whether LilyPond should look for chord inversions when
668 translating from notes to chord names. Set to 1 to find
669 inversions. The default is 0 which does not look for