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{string}
51 Selects type of note head. Choices are @code{cross},
52 @code{diamond}, @code{harmonic}, @code{transparent}, and @code{""}.
53 They are shown in that order below.
55 @mudela[center,verbatim]
58 \property Staff.barNonAuto = 1
59 \property Voice.noteHeadStyle = cross
61 \property Voice.noteHeadStyle = diamond
63 \property Voice.noteHeadStyle = harmonic
65 \property Voice.noteHeadStyle = transparent
67 \property Voice.noteHeadStyle = ""
78 @subsubheading Grace properties
80 @cindex properties!Grace
84 @item @code{stemStyle}@indexcode{flagStyle} @propertytype{string}
85 By default set to @code{"grace"} meaning that all unbeamed
86 notes with flags are typeset with a slash through the flag.
87 Setting to @code{""} gives standard flags.
90 c'8 \property Voice.flagStyle = "grace" c'8
95 @subsubheading Voice properties
97 @cindex properties!Voice
100 @item @code{abbrev}@indexcode{abbrev} @propertytype{integer}
101 Set length for tremolo to be used if no length is explicitly
104 @item @code{articulationScriptPadding}@indexcode{articulationScriptPadding}
105 Determines the extra space added between articulation marks, such
106 as staccato, tenuto, trill, up/down bow or fermata, and the
107 closest staff line or note.
109 @item @code{articulationScriptVerticalDirection} @propertytype{direction}
110 @indexcode{articulationScriptVerticalDirection}
111 Determines the location of articulation marks. Set to @code{\up}
112 to print marks above the staff; set to @code{\down} to print marks
113 below the staff. This property does not override explicit
114 directions marked with `@code{^}' or `@code{_}' in the mudela file.
116 @item @code{noAutoBeaming}@indexcode{beamAuto} @propertytype{boolean}
117 If set to 1 then beams are not generated automatically.
119 @item @code{beamAutoEnd}@indexcode{beamAutoEnd} @propertytype{?}
120 Specifies when automatically generated beams can end. See
121 section XREF-autobeam [FIXME].
123 @item @code{beamAutoBegin}@indexcode{beamAutoBegin} @propertytype{?}
124 Specifies when automatically generated beams can start. See
125 section XREF-autobeam [FIXME].
129 @item @code{beamQuantisation}@indexcode{beamQuantisation} @propertytype{symbol}
130 Set to @code{\none} for no quantization. Set to @code{\normal} to
131 quantize position and slope. Set to @code{\traditional} to avoid
132 wedges. These three settings are available via
133 @code{\beamposfree}@keyindex{beamposfree},
134 @code{\beamposnormal}@keyindex{beamposnormal}, and
135 @code{\beampostraditional}@keyindex{beampostraditional}.
137 @item @code{beamSlopeDamping}@indexcode{beamSlopeDamping} @propertytype{number}
138 Set to @code{\none} for undamped beams. Set to @code{\normal} for
139 damped beams. Set to @code{\infinity} for beams with zero slope.
141 @code{\beamslopeproportional}@keyindex{beamslopeproportional},
142 @code{\beamslopedamped}@keyindex{beamslopedamped}, and
143 @code{\beamslopezero}@keyindex{beamslopezero} each set the
146 @item @code{dynamicDirection}@indexcode{dynamicDirection} @propertytype{direction}
147 Determines location of dynamic marks. Set to @code{\up} to print
148 marks above the staff; set to @code{\down} to print marks below
151 @item @code{dynamicStyle}@indexcode{dynamicStyle} @propertytype{string}
152 Set the text style for dynamics.
154 @item @code{fontSize}@indexcode{fontSize} @propertytype{number}
155 Can be used to select smaller font sizes for music. The normal
156 font size is 0, and the two smaller sizes are -1
160 c''16 \property Staff.fontSize = -2 c''16
163 @item @code{forceHorizontalShift}@indexcode{forceHorizontalShift}
164 Force horizontal shift for collision resolution. It overrides
165 automatic collision resolution. The value is the shift amount
166 expressed in @code{note_width}, as set in the paper section.
168 @item @code{collisionMergeDotted}@indexcode{collisionMergeDotted} @propertytype{boolean}
170 Merge noteheads in collisions, even if they have a different number of
171 dots. This normal notation for polyphonic guitar music.
173 @mudelafile[verbatim]{force-hshift.ly}
176 [FIXME: this should be moved]
178 Lilypond always arranges note heads on alternate sides of a stem (that
179 is, within a single voice) as necessary to prevent collisions (note head
180 overlaps). For up stems, the upper note of a colliding pair is placed
181 on the right side of the stem, the lower on the left. For down stems,
182 the algorithm works in reverse.
184 Lily also attempts to prevent collisions of note heads in different
185 voices. A situation where chords of two or more voices are played
186 simultaneously within one staff.
188 By default, if only two voices (and both have opposite stem directions)
189 are in this 'collision group', the notes both are shifted by @code{0.5
190 \quartwidth} if there are unisons or seconds between the voices.
192 If there are more than two voices in a collision group, shifting is
193 inactive by default, since in this case, there are multiple chords with
194 the same stem direction. By distinguish between those chords, LilyPond
195 can do collision resolution in these cases as well.
197 Distinguishing between voices with the same stem direction, is done by
198 setting the property @code{Voice.horizontalNoteShift}. It must be set
199 to a different integer for each voice. Then, all note heads in collision
200 groups (not just unisons and seconds) will be offset, one voice relative
201 another. The following fragment of sheet music shows how shifting is
202 done, with values of @code{horizontalNoteShift} printed over and under
203 the notes. In this case the chords are just simple notes.
205 @c URG : mudela book bug.
206 @mudela[singleline,verbatim]
208 \notes \context Staff <
209 \context Voice = VA { \stemup f''4^"0" }
210 \context Voice = VB {\stemup
211 \property Voice.horizontalNoteShift = 1 d''4^" 1" }
212 \context Voice = VC { \stemup \property
213 Voice.horizontalNoteShift = 2 b'4^" 2" }
214 \context Voice = VD { \stemdown \property
215 Voice.horizontalNoteShift = 1 g'4_"1 " }
216 \context Voice = VE { \stemdown e'4_"0" }
221 If you are not satisfied with the collision resolution of LilyPond, you
222 can override the horizontal shift value of the chord of one Voice, by
223 setting @code{forceHorizontalShift}. This sets the amount shift,
224 measured in black note head widths.
226 To take complete control of note position shifts in complex passages,
227 you have set things up for normal collisions and override all shifts by
228 setting @code{forceHorizontalShift} to zero everywhere
230 \property Voice.horizontalNoteShift = <n>
231 \property Voice.forceHorizontalShift = "0.0"
234 Then you can set the force property to a suitable value before each note
235 that really needs it (unisons and seconds), and reset it to 0.0 after
238 @item @code{horizontalNoteShift}@indexcode{horizontalNoteShift} @propertytype{integer}
239 Enable LilyPond to shift notes horizontally if they collide with
240 other notes. This is useful when typesetting many voices on one
241 staff. The identifier @code{\shift}@keyindex{shift} is defined to
242 enable this. Traditionally, the outer chords (the upmost and
243 downmost voices), should have no @code{horizontalNoteShift}.
245 @item @code{markScriptPadding}@indexcode{markScriptPadding} @propertytype{number}
246 Determines the extra space added between the mark and the closest
249 @item @code{markDirection}@indexcode{markDirection} @propertytype{direction}
250 Determines if marks should be printed above or below the staff.
251 Set to @code{\up} to print marks above the staff; set to
252 @code{\down} to print marks below the staff.
254 @item @code{midiInstrument}@indexcode{midiInstrument} @propertytype{string}
255 Sets the instrument for MIDI output. If this property is not set
256 then LilyPond will use the @code{instrument} property. This must
257 be set to one of the strings on the list of MIDI instruments that
258 appears in section XREF-midilist [FIXME]. If you use a string which
259 is not listed, LilyPond will silently substitute piano.
261 @item @code{restStyle}@indexcode{restStyle} @propertytype{string}
262 Change the layout of rests shorter than quarter notes.
263 Currently, the standard layout @code{""} and mensural notation
264 @code{"mensural"} are available. Mensural rests of duration
265 32 or shorter are not available.
267 r\longa r\breve r1 r2 r4 r8 r16 r32 r64 r128 r128
268 \property Staff.restStyle = "mensural"
269 r\longa r\breve r1 r2 r4 r8 r16 r32 r64 r128 r128
272 @item @code{scriptHorizontal}@indexcode{scriptHorizontal} @propertytype{boolean}
273 Put scripts left or right of note heads. Support for this is
274 limited. Accidentals will collide with scripts.
276 @item @code{slurVerticalDirection}@indexcode{slurVerticalDirection} @propertytype{direction}
277 Set to @code{\free} for free choice of slur direction, set to
278 @code{\up} to force slurs up, set to @code{\down} to force slurs
279 down. The shorthands @code{\slurup}@keyindex{slurup},
280 @code{\slurdown}@keyindex{slurdown}, and
281 @code{\slurboth}@keyindex{slurboth} are available.
283 @item @code{slurDash}@indexcode{slurDash} @propertytype{number}
284 Set to NIL for normal slurs, 1 for dotted slurs, and a
285 larger value for dashed slurs. Identifiers
286 @code{\slurnormal}@keyindex{slurnormal} and
287 @code{\slurdotted}@keyindex{slurdotted} are predefined to set the
292 \property Voice.slurDash = 3
296 @item @code{stemLength}@indexcode{stemLength}
297 Set length of stems. Unit is `@code{interline}/2', so
298 @code{stemLength} defaults to 7.
300 g''4 \property Voice.stemLength = #14 g4 \property Voice.stemLength = #3 g4 g,,4
303 @item @code{stemLeftBeamCount}@indexcode{stemLeftBeamCount} @propertytype{integer}
304 Specify the number of beams to draw on the left side of the next
305 note. Overrides automatic beaming. The value is only used once,
306 and then it is erased.
308 @item @code{stemRightBeamCount}@indexcode{stemRightBeamCount} @propertytype{integer}
309 Specify the number of beams to draw on the right side of the next
310 note. Overrides automatic beaming. The value is only used once,
311 and then it is erased.
313 @item @code{tieDash}@indexcode{tieDash} @propertytype{integer}
314 Set dashing of ties. See also @code{slurDash}
316 @item @code{tieVerticalDirection}@indexcode{tieVerticalDirection} @propertytype{direction}
317 Set to @code{\free} for free choice of tie direction, set to
318 @code{\up} to force ties up, set to @code{\down} to force ties
321 @item @code{transposing}@indexcode{transposing} @propertytype{integer}
322 Transpose the MIDI output. Set this property to the number of
323 half-steps to transpose by.
325 @item @code{textEmptyDimension}@indexcode{textEmptyDimension} @propertytype{boolean}
326 If set to true then text placed above or below the staff is
327 assumed to have zero width. @code{fatText} and @code{emptyText}
328 are predefined settings.
331 c4^"foo" \emptyText c4^"foo" c4
334 @item @code{textStyle}@indexcode{textStyle} @propertytype{string}
335 Set the text style for superscripts and subscripts. See above
336 for list of text styles.
338 @item @code{textScriptPadding}@indexcode{textScriptPadding} @propertytype{number}
339 Determines the extra space added between superscripted resp.
340 subscripted text and the closest staff line or note.
342 @item @code{verticalDirection}@indexcode{verticalDirection} @propertytype{direction}
343 Determines the direction of stems, subscripts, beams, slurs, and
344 ties. Set to @code{\down} to force them down, @code{\up} to force
345 them up, or @code{\free} to let LilyPond decide. This can be used
346 to distinguish between voices on the same staff. The
347 @code{\stemdown}@keyindex{stemdown}, @code{\stemup}@keyindex{stemup},
348 and @code{\stemboth}@keyindex{stemboth} identifiers set this
352 @item @code{tupletDirection}@indexcode{tupletDirection} @propertytype{direction}
353 Determines the direction of triplets and other tuplets. Set to
354 @code{\down} to force them below the staff, @code{\up} to force
355 them above, or @code{\free} to let LilyPond decide.
357 @item @code{tupletBracketVisibility}@indexcode{tupletBracketVisibility} @propertytype{boolean} or @propertytype{symbol}
358 @item @code{tupletNumberVisibility}@indexcode{tupletNumberVisibility} @propertytype{boolean} or @propertytype{symbol}
360 These properties the visibility of the tuplet bracket and its
361 number respectively. Setting it to false will prevent printing of the
362 associated element. Setting the property to 'if-no-beam will make it
363 print only if there is no beam associated with this tuplet bracket.
367 @item @code{tupletInvisible}@indexcode{tupletInvisible} @propertytype{boolean}
369 If set to true, tuplet bracket creation is switched off
370 entirely. This has the same effect as setting both
371 @code{tupletNumberVisibility} and @code{tupletBracketVisibility} to
372 @code{#f}, but as this does not even create elements, this setting
373 uses less memory and time.
376 @item @code{tupletSpannerDuration} @indexcode{tupletSpannerDuration}
377 @propertytype{moment}
379 Normally a tuplet bracket is as wide as the
380 @code{\times} expression that gave rise to it. By setting this
381 property, you can make brackets last shorter. Example
383 @mudela[verbatim,fragment]
384 \context Voice \times 2/3 {
385 \property Voice.tupletSpannerDuration = #(make-moment 1 4)
392 @subsubheading Staff properties
394 @cindex properties!Staff
398 @item @code{barNonAuto}@indexcode{barNonAuto} @propertytype{boolean}
399 If set to true then bar lines will not be printed
400 automatically; they must be explicitly created with @code{\bar}
401 keywords. Unlike with the @code{\cadenza} keyword, measures are
402 still counted. Bar generation will resume according to that
403 count if this property is set to zero.
405 @item @code{barNumberDirection}@indexcode{barNumberDirection} @propertytype{direction}
406 Set to @code{\up} or @code{\down} to put bar numbers above or below
409 @item @code{barNumberScriptPadding}@indexcode{barNumberScriptPadding}
410 Sets extra space between the bar number and the bar it labels.
412 @item @code{barSize}@indexcode{barSize}
413 Specify the height of the bar lines if it should be different
414 than the staff height.
416 c1 c1 \property Staff.barSize = 20 c1 c1
419 @item @code{barAtLineStart}@indexcode{barAtLineStart} @propertytype{boolean}
420 Set to true to produce a bar line after the clef at the start
421 of each line (but not at the beginning of the music).
425 @item @code{clefStyle}@indexcode{clefStyle} @propertytype{string}
426 Determines how clefs are typeset. If set to @code{transparent},
427 the clefs are not printed at all, if set to
428 @code{fullSizeChanges}, clef changes in the middle of a line are
429 typeset with a full size clef. By default, clef changes are
430 typeset in smaller size.
432 @item @code{supportedClefTypes}@indexcode{supportedClefTypes} @propertytype{alist}
434 Clef settings supported. The value is an association list clef
435 descriptions indexed by clef name (alto, baritone, etc.). A clef
436 description is a list with the glyph name, and the staff position
437 where it should go. For internal use.
439 @item @code{clefPitches}@indexcode{clefPitches} @propertytype{alist}
440 Settings for the position of the central C, relative to this clef
441 symbol. For internal use.
443 @item @code{defaultClef}@indexcode{defaultClef} @propertytype{string}
444 Clef setting to use when this context is created. If unset,
445 no clef is printed upon creation.
447 @item @code{marginDirection}@indexcode{marginDirection} @propertytype{direction}
448 Set to @code{\left} or @code{\right} to specify location of
451 @item @code{marginScriptPadding}@indexcode{marginScriptPadding}
452 Specify extra space for marginal scripts.
454 @item @code{forgetAccidentals}@indexcode{forgetAccidentals} @propertytype{boolean}
455 Causes accidentals to be printed at every note instead of
456 remembered for the duration of a measure.
458 @item @code{noResetKey}@indexcode{noResetKey} @propertytype{boolean}
459 Do not reset the key at the start of a measure. Accidentals will
460 be printed only once and are in effect until overridden, possibly
463 @item @code{staffSpace}@indexcode{staffLineLeading} @propertytype{number}
464 Specifies the distance (in points) between lines of the staff.
466 @item @code{numberOfStaffLines}@indexcode{numberOfStaffLines} @propertytype{integer}
467 Specifies the number of staff lines. The default is 5.
469 @item @code{postBreakPadding}@indexcode{postBreakPadding} @propertytype{number}
470 Extra space in points to be added after the clef, time signature
471 and key signature on the staff. Deprecated, do not use.
473 @item @code{noVoltaBraces}@indexcode{noVoltaBraces} @propertytype{boolean}
474 Set to true to suppress the printing of brackets over alternate
475 endings specified by the command @code{\alternative}.
478 @item @code{barAlways}@indexcode{barAlways} @propertytype{boolean}
479 If set to true a bar line is drawn after each note.
481 @item @code{defaultBarType}@indexcode{defaultBarType} @propertytype{string}
482 Sets the default type of bar line. See Section XREF-barlines [FIXME]
483 for a list of available bar types.
485 @item @code{instrument}, @code{instr} @propertytype{string}
486 @indexcode{instrument}@indexcode{instr}
487 If @code{Instrument_name_engraver}
488 @cindex Instrument_name_engraver
490 added to the Staff translator, then the @code{instrument} property
491 is used to label the first line of the staff and the @code{instr}
492 property is used to label subsequent lines. If the
493 @code{midiInstrument} property is not set, then @code{instrument}
494 is used to determine the instrument for MIDI output.
496 @item @code{keyOctaviation}@indexcode{keyOctaviation} @propertytype{boolean}
497 If set to false, then keys are the same in all octaves. If set
498 to true then the key signature for different octaves can be
499 different and is specified independently:
502 \keysignature bes fis'
505 The default value is @code{#f}. Can be set to @code{#t} with
506 @code{\specialkey} or reset with @code{\normalkey}.
508 @item @code{timeSignatureStyle}@indexcode{timeSignatureStyle} @propertytype{string}
509 Changes the default two-digit layout for time signatures. The
510 following values are recognized:
513 @item @code{C}@indexcode{C}
514 4/4 and 2/2 are typeset as C and struck C, respectively. All
515 other time signatures are written with two digits.
517 @item @code{old}@indexcode{old}
518 2/2, 3/2, 2/4, 3/4, 4/4, 6/4, 9/4, 4/8, 6/8 and 9/8 are
519 typeset with old-style mensuration marks. All other time
520 signatures are written with two digits.
522 @item @code{1}@indexcode{1}
523 All time signatures are typeset with a single
524 digit, e.g. 3/2 is written as 3.
526 @item @indexcode{CM/N}@code{C}@var{M}@code{/}@var{N},
527 @indexcode{oldM/N}@code{old}@var{M}@code{/}@var{N} or
528 @code{old6/8alt}@indexcode{old6/8alt}
529 Tells LilyPond to use a specific symbol as time signature.
532 The different time signature characters are shown below with its
535 @mudela[center,verbatim]
538 \notes\relative c'' {
539 \property Voice.textStyle = typewriter
540 \property Staff.timeSignatureStyle = "C2/2"
541 \time 2/2; a2^"C2/2" a2
542 \property Staff.timeSignatureStyle = "C4/4"
543 \time 2/2; a2^"C4/4" a2
544 \property Staff.timeSignatureStyle = "old2/2"
545 \time 2/2; a2^"old2/2" a2
546 \property Staff.timeSignatureStyle = "old3/2"
547 \time 2/2; a2^"old3/2" a2
548 \property Staff.timeSignatureStyle = "old2/4"
549 \time 2/2; a2^"old2/4" a2
550 \property Staff.timeSignatureStyle = "old4/4"
551 \time 2/2; a2^"old4/4" a2
552 \property Staff.timeSignatureStyle = "old6/4"
553 \time 2/2; a2^"old6/4" a2
554 \property Staff.timeSignatureStyle = "old9/4"
555 \time 2/2; a2^"old9/4" a2
556 \property Staff.timeSignatureStyle = "old4/8"
557 \time 2/2; a2^"old4/8" a2
558 \property Staff.timeSignatureStyle = "old6/8"
559 \time 2/2; a2^"old6/8" a2
560 \property Staff.timeSignatureStyle = "old6/8alt"
561 \time 2/2; a2^"old6/8alt" a2
562 \property Staff.timeSignatureStyle = "old9/8"
563 \time 2/2; a2^"old9/8" a2
572 @item @code{voltaSpannerDuration}@indexcode{voltaSpannerDuration} @propertytype{moment}
573 Set to an integer to control the size of the brackets printed by
574 @code{\alternative}. The integer specifies the number of whole
575 notes duration to use for the brackets. It is rounded to the
576 nearest measure. This can be used to shrink the length of
577 brackets in the situation where one alternative is very large.
578 It may have odd effects if the specified duration is longer than
579 the music given in an @code{\alternative}.
582 @subsubheading GrandStaff properties
584 @cindex properties!GrandStaff
587 @item @code{maxVerticalAlign}@indexcode{maxVerticalAlign} @propertytype{number}
588 Set the maximum vertical distance between staffs.
590 @item @code{minVerticalAlign}@indexcode{minVerticalAlign} @propertytype{number}
591 Set the minimum vertical distance between staffs.
594 @subsubheading Score properties
596 @cindex properties!Score
602 @item @code{skipBars}@indexcode{skipBars} @propertytype{boolean}
603 Set to 1 to skip the empty bars that are produced by
604 multimeasure notes and rests. These bars will not appear on the
605 printed output. Set to zero (the default) to expand multimeasure
606 notes and rests into their full length, printing the appropriate
607 number of empty bars so that synchronization with other voices is
612 @mudela[fragment,verbatim,center]
613 r1 r1*3 R1*3\property Score.skipBars=1 r1*3 R1*3
618 @item @code{breakAlignOrder}@indexcode{breakAlignOrder} @propertytype{list of string}
620 Defines the order in which prefatory matter (clefs, key signatures) appears, eg. this puts the key signatures after the bar lines:
622 \property Score.breakAlignOrder = #'(
633 @item @code{timing}@indexcode{timing} @propertytype{boolean}
634 Keep administration of measure length, position, bar number, etc?
635 Switch off for cadenzas.
637 @item @code{currentBarNumber}@indexcode{currentBarNumber} @propertytype{integer}
638 Contains the current barnumber. This property is incremented at
641 @item @code{measurePosition}@indexcode{measurePosition} @propertytype{Moment}
643 How much of the current measure (measured in whole notes) have we had?
645 @item @code{oneBeat}@indexcode{oneBeat} @propertytype{Moment}
647 How long does one beat in the current time signature last?
649 @item @code{measureLength}@indexcode{measureLength} @propertytype{Moment}
651 How long does one measure in the current time signature last?
655 @subsubheading ChordNamesVoice properties
657 @cindex properties!ChordNamesVoice
660 @item @code{chordInversion}@indexcode{chordInversion} @propertytype{boolean}
661 Determines whether LilyPond should look for chord inversions when
662 translating from notes to chord names. Set to 1 to find
663 inversions. The default is 0 which does not look for