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} Defines names and types for
12 generic properties. These are properties than can be plugged into the
13 backend directly. See the init file @file{generic-property.scm} for
14 details. For internal use only.
16 @cindex properties!Lyrics
19 @item @code{textStyle}@indexcode{textStyle} @propertytype{string}
20 Set the font for lyrics. The available font choices are
21 @code{roman}, @code{italic}, @code{bold}, @code{large}, @code{Large},
22 @code{typewriter}, and @code{finger}. The @code{finger} font can
23 only display numbers. Note also that you must be careful when
24 using @code{\property} in Lyrics mode, because of the way strings
25 are parsed. Either put quotes around the arguments to
26 @code{\property} or be sure to leave a space on both sides of the
31 @cindex properties!Thread
34 @item @code{noteheadStyle}@indexcode{noteheadStyle} @propertytype{string}
35 Selects type of note head. Choices are @code{cross},
36 @code{diamond}, @code{harmonic}, @code{transparent}, and @code{""}.
37 They are shown in that order below.
39 @mudela[center,verbatim]
42 \property Staff.barNonAuto = 1
43 \property Voice.noteHeadStyle = cross
45 \property Voice.noteHeadStyle = diamond
47 \property Voice.noteHeadStyle = harmonic
49 \property Voice.noteHeadStyle = transparent
51 \property Voice.noteHeadStyle = ""
62 @subsubheading Grace properties
64 @cindex properties!Grace
68 @item @code{stemStyle}@indexcode{flagStyle} @propertytype{string}
69 By default set to @code{"grace"} meaning that all unbeamed
70 notes with flags are typeset with a slash through the flag.
71 Setting to @code{""} gives standard flags.
74 c'8 \property Voice.flagStyle = "grace" c'8
79 @subsubheading Voice properties
81 @cindex properties!Voice
84 @item @code{abbrev}@indexcode{abbrev} @propertytype{integer}
85 Set length for tremolo to be used if no length is explicitly
88 @item @code{articulationScriptPadding}@indexcode{articulationScriptPadding}
89 Determines the extra space added between articulation marks, such
90 as staccato, tenuto, trill, up/down bow or fermata, and the
91 closest staff line or note.
93 @item @code{articulationScriptVerticalDirection} @propertytype{direction}
94 @indexcode{articulationScriptVerticalDirection}
95 Determines the location of articulation marks. Set to @code{\up}
96 to print marks above the staff; set to @code{\down} to print marks
97 below the staff. This property does not override explicit
98 directions marked with `@code{^}' or `@code{_}' in the mudela file.
100 @item @code{noAutoBeaming}@indexcode{beamAuto} @propertytype{boolean}
101 If set to 1 then beams are not generated automatically.
103 @item @code{beamAutoEnd}@indexcode{beamAutoEnd} @propertytype{?}
104 Specifies when automatically generated beams can end. See
105 section XREF-autobeam [FIXME].
107 @item @code{beamAutoBegin}@indexcode{beamAutoBegin} @propertytype{?}
108 Specifies when automatically generated beams can start. See
109 section XREF-autobeam [FIXME].
113 @item @code{beamQuantisation}@indexcode{beamQuantisation} @propertytype{symbol}
114 Set to @code{\none} for no quantization. Set to @code{\normal} to
115 quantize position and slope. Set to @code{\traditional} to avoid
116 wedges. These three settings are available via
117 @code{\beamposfree}@keyindex{beamposfree},
118 @code{\beamposnormal}@keyindex{beamposnormal}, and
119 @code{\beampostraditional}@keyindex{beampostraditional}.
121 @item @code{beamSlopeDamping}@indexcode{beamSlopeDamping} @propertytype{number}
122 Set to @code{\none} for undamped beams. Set to @code{\normal} for
123 damped beams. Set to @code{\infinity} for beams with zero slope.
125 @code{\beamslopeproportional}@keyindex{beamslopeproportional},
126 @code{\beamslopedamped}@keyindex{beamslopedamped}, and
127 @code{\beamslopezero}@keyindex{beamslopezero} each set the
130 @item @code{dynamicDirection}@indexcode{dynamicDirection} @propertytype{direction}
131 Determines location of dynamic marks. Set to @code{\up} to print
132 marks above the staff; set to @code{\down} to print marks below
135 @item @code{dynamicStyle}@indexcode{dynamicStyle} @propertytype{string}
136 Set the text style for dynamics.
138 @item @code{fontSize}@indexcode{fontSize} @propertytype{number}
139 Can be used to select smaller font sizes for music. The normal
140 font size is 0, and the two smaller sizes are -1
144 c''16 \property Staff.fontSize = -2 c''16
147 @item @code{forceHorizontalShift}@indexcode{forceHorizontalShift}
148 Force horizontal shift for collision resolution. It overrides
149 automatic collision resolution. The value is the shift amount
150 expressed in @code{note_width}, as set in the paper section.
152 @mudelafile[verbatim]{force-hshift.sly}
155 [FIXME: this should be moved]
157 Lilypond always arranges note heads on alternate sides of a stem (that
158 is, within a single voice) as necessary to prevent collisions (note head
159 overlaps). For up stems, the upper note of a colliding pair is placed
160 on the right side of the stem, the lower on the left. For down stems,
161 the algorithm works in reverse.
163 Lily also attempts to prevent collisions of note heads in different
164 voices. A situation where chords of two or more voices are played
165 simultaneously within one staff.
167 By default, if only two voices (and both have opposite stem directions)
168 are in this 'collision group', the notes both are shifted by @code{0.5
169 \quartwidth} if there are unisons or seconds between the voices.
171 If there are more than two voices in a collision group, shifting is
172 inactive by default, since in this case, there are multiple chords with
173 the same stem direction. By distinguish between those chords, LilyPond
174 can do collision resolution in these cases as well.
176 Distinguishing between voices with the same stem direction, is done by
177 setting the property @code{Voice.horizontalNoteShift}. It must be set
178 to a different integer for each voice. Then, all note heads in collision
179 groups (not just unisons and seconds) will be offset, one voice relative
180 another. The following fragment of sheet music shows how shifting is
181 done, with values of @code{horizontalNoteShift} printed over and under
182 the notes. In this case the chords are just simple notes.
184 @c URG : mudela book bug.
185 @mudela[singleline,verbatim]
187 \notes \context Staff <
188 \context Voice = VA { \stemup f''4^"0" }
189 \context Voice = VB {\stemup
190 \property Voice.horizontalNoteShift = 1 d''4^" 1" }
191 \context Voice = VC { \stemup \property
192 Voice.horizontalNoteShift = 2 b'4^" 2" }
193 \context Voice = VD { \stemdown \property
194 Voice.horizontalNoteShift = 1 g'4_"1 " }
195 \context Voice = VE { \stemdown e'4_"0" }
200 If you are not satisfied with the collision resolution of LilyPond, you
201 can override the horizontal shift value of the chord of one Voice, by
202 setting @code{forceHorizontalShift}. This sets the amount shift,
203 measured in black note head widths.
205 To take complete control of note position shifts in complex passages,
206 you have set things up for normal collisions and override all shifts by
207 setting @code{forceHorizontalShift} to zero everywhere
209 \property Voice.horizontalNoteShift = <n>
210 \property Voice.forceHorizontalShift = "0.0"
213 Then you can set the force property to a suitable value before each note
214 that really needs it (unisons and seconds), and reset it to 0.0 after
217 @item @code{horizontalNoteShift}@indexcode{horizontalNoteShift} @propertytype{integer}
218 Enable LilyPond to shift notes horizontally if they collide with
219 other notes. This is useful when typesetting many voices on one
220 staff. The identifier @code{\shift}@keyindex{shift} is defined to
221 enable this. Traditionally, the outer chords (the upmost and
222 downmost voices), should have no @code{horizontalNoteShift}.
224 @item @code{markScriptPadding}@indexcode{markScriptPadding} @propertytype{number}
225 Determines the extra space added between the mark and the closest
228 @item @code{markDirection}@indexcode{markDirection} @propertytype{direction}
229 Determines if marks should be printed above or below the staff.
230 Set to @code{\up} to print marks above the staff; set to
231 @code{\down} to print marks below the staff.
233 @item @code{midiInstrument}@indexcode{midiInstrument} @propertytype{string}
234 Sets the instrument for MIDI output. If this property is not set
235 then LilyPond will use the @code{instrument} property. This must
236 be set to one of the strings on the list of MIDI instruments that
237 appears in section XREF-midilist [FIXME]. If you use a string which
238 is not listed, LilyPond will silently substitute piano.
240 @item @code{restStyle}@indexcode{restStyle} @propertytype{string}
241 Change the layout of rests shorter than quarter notes.
242 Currently, the standard layout @code{""} and mensural notation
243 @code{"mensural"} are available. Mensural rests of duration
244 32 or shorter are not available.
246 r\longa r\breve r1 r2 r4 r8 r16 r32 r64 r128 r128
247 \property Staff.restStyle = "mensural"
248 r\longa r\breve r1 r2 r4 r8 r16 r32 r64 r128 r128
251 @item @code{scriptHorizontal}@indexcode{scriptHorizontal} @propertytype{boolean}
252 Put scripts left or right of note heads. Support for this is
253 limited. Accidentals will collide with scripts.
255 @item @code{slurVerticalDirection}@indexcode{slurVerticalDirection} @propertytype{direction}
256 Set to @code{\free} for free choice of slur direction, set to
257 @code{\up} to force slurs up, set to @code{\down} to force slurs
258 down. The shorthands @code{\slurup}@keyindex{slurup},
259 @code{\slurdown}@keyindex{slurdown}, and
260 @code{\slurboth}@keyindex{slurboth} are available.
262 @item @code{slurDash}@indexcode{slurDash} @propertytype{number}
263 Set to NIL for normal slurs, 1 for dotted slurs, and a
264 larger value for dashed slurs. Identifiers
265 @code{\slurnormal}@keyindex{slurnormal} and
266 @code{\slurdotted}@keyindex{slurdotted} are predefined to set the
271 \property Voice.slurDash = 3
275 @item @code{stemLength}@indexcode{stemLength}
276 Set length of stems. Unit is `@code{interline}/2', so
277 @code{stemLength} defaults to 7.
279 g''4 \property Voice.stemLength = #14 g4 \property Voice.stemLength = #3 g4 g,,4
282 @item @code{stemLeftBeamCount}@indexcode{stemLeftBeamCount} @propertytype{integer}
283 Specify the number of beams to draw on the left side of the next
284 note. Overrides automatic beaming. The value is only used once,
285 and then it is erased.
287 @item @code{stemRightBeamCount}@indexcode{stemRightBeamCount} @propertytype{integer}
288 Specify the number of beams to draw on the right side of the next
289 note. Overrides automatic beaming. The value is only used once,
290 and then it is erased.
292 @item @code{tieVerticalDirection}@indexcode{tieVerticalDirection} @propertytype{direction}
293 Set to @code{\free} for free choice of tie direction, set to
294 @code{\up} to force ties up, set to @code{\down} to force ties
297 @item @code{transposing}@indexcode{transposing} @propertytype{integer}
298 Transpose the MIDI output. Set this property to the number of
299 half-steps to transpose by.
301 @item @code{textEmptyDimension}@indexcode{textEmptyDimension} @propertytype{boolean}
302 If set to true then text placed above or below the staff is
303 assumed to have zero width. @code{fatText} and @code{emptyText}
304 are predefined settings.
307 c4^"foo" \emptyText c4^"foo" c4
310 @item @code{textStyle}@indexcode{textStyle} @propertytype{string}
311 Set the text style for superscripts and subscripts. See above
312 for list of text styles.
314 @item @code{textScriptPadding}@indexcode{textScriptPadding} @propertytype{number}
315 Determines the extra space added between superscripted resp.
316 subscripted text and the closest staff line or note.
318 @item @code{verticalDirection}@indexcode{verticalDirection} @propertytype{direction}
319 Determines the direction of stems, subscripts, beams, slurs, and
320 ties. Set to @code{\down} to force them down, @code{\up} to force
321 them up, or @code{\free} to let LilyPond decide. This can be used
322 to distinguish between voices on the same staff. The
323 @code{\stemdown}@keyindex{stemdown}, @code{\stemup}@keyindex{stemup},
324 and @code{\stemboth}@keyindex{stemboth} identifiers set this
328 @item @code{tupletDirection}@indexcode{tupletDirection} @propertytype{direction}
329 Determines the direction of triplets and other tuplets. Set to
330 @code{\down} to force them below the staff, @code{\up} to force
331 them above, or @code{\free} to let LilyPond decide.
333 @item @code{tupletBracketVisibility}@indexcode{tupletBracketVisibility} @propertytype{boolean} or @propertytype{symbol}
334 @item @code{tupletNumberVisibility}@indexcode{tupletNumberVisibility} @propertytype{boolean} or @propertytype{symbol}
336 These properties the visibility of the tuplet bracket and its
337 number respectively. Setting it to false will prevent printing of the
338 associated element. Setting the property to 'if-no-beam will make it
339 print only if there is no beam associated with this tuplet bracket.
343 @item @code{tupletInvisible}@indexcode{tupletInvisible} @propertytype{boolean}
345 If set to true, tuplet bracket creation is switched off
346 entirely. This has the same effect as setting both
347 @code{tupletNumberVisibility} and @code{tupletBracketVisibility} to
348 @code{#f}, but as this does not even create elements, this setting
349 uses less memory and time.
352 @item @code{tupletSpannerDuration} @indexcode{tupletSpannerDuration}
353 @propertytype{moment}
355 Normally a tuplet bracket is as wide as the
356 @code{\times} expression that gave rise to it. By setting this
357 property, you can make brackets last shorter. Example
359 @mudela[verbatim,fragment]
360 \context Voice \times 2/3 { \property Voice.tupletSpannerDuration = #(make-moment 1 4) [c8 c c] [c c c] }
365 @subsubheading Staff properties
367 @cindex properties!Staff
371 @item @code{barNonAuto}@indexcode{barNonAuto} @propertytype{boolean}
372 If set to true then bar lines will not be printed
373 automatically; they must be explicitly created with @code{\bar}
374 keywords. Unlike with the @code{\cadenza} keyword, measures are
375 still counted. Bar generation will resume according to that
376 count if this property is set to zero.
378 @item @code{barNumberDirection}@indexcode{barNumberDirection} @propertytype{direction}
379 Set to @code{\up} or @code{\down} to put bar numbers above or below
382 @item @code{barNumberScriptPadding}@indexcode{barNumberScriptPadding}
383 Sets extra space between the bar number and the bar it labels.
385 @item @code{barSize}@indexcode{barSize}
386 Specify the height of the bar lines if it should be different
387 than the staff height.
389 c1 c1 \property Staff.barSize = 20 c1 c1
392 @item @code{barAtLineStart}@indexcode{barAtLineStart} @propertytype{boolean}
393 Set to true to produce a bar line after the clef at the start
394 of each line (but not at the beginning of the music).
398 @item @code{clefStyle}@indexcode{clefStyle} @propertytype{string}
399 Determines how clefs are typeset. If set to @code{transparent},
400 the clefs are not printed at all, if set to
401 @code{fullSizeChanges}, clef changes in the middle of a line are
402 typeset with a full size clef. By default, clef changes are
403 typeset in smaller size.
405 @item @code{supportedClefTypes}@indexcode{supportedClefTypes} @propertytype{alist}
407 Clef settings supported. The value is an association list clef
408 descriptions indexed by clef name (alto, baritone, etc.). A clef
409 description is a list with the glyph name, and the staff position
410 where it should go. For internal use.
412 @item @code{clefPitches}@indexcode{clefPitches} @propertytype{alist}
413 Settings for the position of the central C, relative to this clef
414 symbol. For internal use.
416 @item @code{defaultClef}@indexcode{defaultClef} @propertytype{string}
417 Clef setting to use when this context is created. If unset,
418 no clef is printed upon creation.
420 @item @code{marginDirection}@indexcode{marginDirection} @propertytype{direction}
421 Set to @code{\left} or @code{\right} to specify location of
424 @item @code{marginScriptPadding}@indexcode{marginScriptPadding}
425 Specify extra space for marginal scripts.
427 @item @code{forgetAccidentals}@indexcode{forgetAccidentals} @propertytype{boolean}
428 Causes accidentals to be printed at every note instead of
429 remembered for the duration of a measure.
431 @item @code{noResetKey}@indexcode{noResetKey} @propertytype{boolean}
432 Do not reset the key at the start of a measure. Accidentals will
433 be printed only once and are in effect until overridden, possibly
436 @item @code{staffSpace}@indexcode{staffLineLeading} @propertytype{number}
437 Specifies the distance (in points) between lines of the staff.
439 @item @code{numberOfStaffLines}@indexcode{numberOfStaffLines} @propertytype{integer}
440 Specifies the number of staff lines. The default is 5.
442 @item @code{postBreakPadding}@indexcode{postBreakPadding} @propertytype{number}
443 Extra space in points to be added after the clef, time signature
444 and key signature on the staff. Deprecated, do not use.
446 @item @code{noVoltaBraces}@indexcode{noVoltaBraces} @propertytype{boolean}
447 Set to true to suppress the printing of brackets over alternate
448 endings specified by the command @code{\alternative}.
451 @item @code{barAlways}@indexcode{barAlways} @propertytype{boolean}
452 If set to true a bar line is drawn after each note.
454 @item @code{defaultBarType}@indexcode{defaultBarType} @propertytype{string}
455 Sets the default type of bar line. See Section XREF-barlines [FIXME]
456 for a list of available bar types.
458 @item @code{instrument}, @code{instr} @propertytype{string}
459 @indexcode{instrument}@indexcode{instr}
460 If @code{Staff_margin_engraver}
461 @cindex Staff_margin_engraver
463 added to the Staff translator, then the @code{instrument} property
464 is used to label the first line of the staff and the @code{instr}
465 property is used to label subsequent lines. If the
466 @code{midiInstrument} property is not set, then @code{instrument}
467 is used to determine the instrument for MIDI output.
469 @item @code{keyOctaviation}@indexcode{keyOctaviation} @propertytype{boolean}
470 If set to TRUE, then keys are the same in all octaves. If set
471 to FALSE then the key signature for different octaves can be
472 different and is specified independently:
475 \keysignature bes fis'
478 The default value is 1. Can be set to zero with
479 @code{\specialkey} or reset to 1 with @code{\normalkey}.
481 @item @code{timeSignatureStyle}@indexcode{timeSignatureStyle} @propertytype{string}
482 Changes the default two-digit layout for time signatures. The
483 following values are recognized:
486 @item @code{C}@indexcode{C}
487 4/4 and 2/2 are typeset as C and struck C, respectively. All
488 other time signatures are written with two digits.
490 @item @code{old}@indexcode{old}
491 2/2, 3/2, 2/4, 3/4, 4/4, 6/4, 9/4, 4/8, 6/8 and 9/8 are
492 typeset with old-style mensuration marks. All other time
493 signatures are written with two digits.
495 @item @code{1}@indexcode{1}
496 All time signatures are typeset with a single
497 digit, e.g. 3/2 is written as 3.
499 @item @indexcode{CM/N}@code{C}@var{M}@code{/}@var{N},
500 @indexcode{oldM/N}@code{old}@var{M}@code{/}@var{N} or
501 @code{old6/8alt}@indexcode{old6/8alt}
502 Tells LilyPond to use a specific symbol as time signature.
505 The different time signature characters are shown below with its
508 @mudela[center,verbatim]
511 \notes\relative c'' {
512 \property Voice.textStyle = typewriter
513 \property Staff.timeSignatureStyle = "C2/2"
514 \time 2/2; a2^"C2/2" a2
515 \property Staff.timeSignatureStyle = "C4/4"
516 \time 2/2; a2^"C4/4" a2
517 \property Staff.timeSignatureStyle = "old2/2"
518 \time 2/2; a2^"old2/2" a2
519 \property Staff.timeSignatureStyle = "old3/2"
520 \time 2/2; a2^"old3/2" a2
521 \property Staff.timeSignatureStyle = "old2/4"
522 \time 2/2; a2^"old2/4" a2
523 \property Staff.timeSignatureStyle = "old4/4"
524 \time 2/2; a2^"old4/4" a2
525 \property Staff.timeSignatureStyle = "old6/4"
526 \time 2/2; a2^"old6/4" a2
527 \property Staff.timeSignatureStyle = "old9/4"
528 \time 2/2; a2^"old9/4" a2
529 \property Staff.timeSignatureStyle = "old4/8"
530 \time 2/2; a2^"old4/8" a2
531 \property Staff.timeSignatureStyle = "old6/8"
532 \time 2/2; a2^"old6/8" a2
533 \property Staff.timeSignatureStyle = "old6/8alt"
534 \time 2/2; a2^"old6/8alt" a2
535 \property Staff.timeSignatureStyle = "old9/8"
536 \time 2/2; a2^"old9/8" a2
545 @item @code{voltaSpannerDuration}@indexcode{voltaSpannerDuration} @propertytype{moment}
546 Set to an integer to control the size of the brackets printed by
547 @code{\alternative}. The integer specifies the number of whole
548 notes duration to use for the brackets. It is rounded to the
549 nearest measure. This can be used to shrink the length of
550 brackets in the situation where one alternative is very large.
551 It may have odd effects if the specified duration is longer than
552 the music given in an @code{\alternative}.
556 @cindex properties!GrandStaff
559 @item @code{alignmentReference}@indexcode{alignmentReference}
560 @propertytype{direction}
561 Set to @code{\center} for vertical alignment reference point to be
562 in the center of the vertical group. Set to @code{\up} to put the
563 reference point at the top of the group.
565 @item @code{maxVerticalAlign}@indexcode{maxVerticalAlign} @propertytype{number}
566 Set the maximum vertical distance between staffs.
568 @item @code{minVerticalAlign}@indexcode{minVerticalAlign} @propertytype{number}
569 Set the minimum vertical distance between staffs.
573 @cindex properties!Score
576 @item @code{skipBars}@indexcode{skipBars} @propertytype{boolean}
577 Set to 1 to skip the empty bars that are produced by
578 multimeasure notes and rests. These bars will not appear on the
579 printed output. Set to zero (the default) to expand multimeasure
580 notes and rests into their full length, printing the appropriate
581 number of empty bars so that synchronization with other voices is
586 @mudela[fragment,verbatim,center]
587 r1 r1*3 R1*3\property Score.skipBars=1 r1*3 R1*3
592 @item @code{breakAlignOrder}@indexcode{breakAlignOrder} @propertytype{list of string}
594 Defines the order in which prefatory matter (clefs, key signatures) appears, eg. this puts the key signatures after the bar lines:
596 \property Score.breakAlignOrder = #'(
608 @cindex properties!ChordNamesVoice
611 @item @code{chordInversion}@indexcode{chordInversion} @propertytype{boolean}
612 Determines whether LilyPond should look for chord inversions when
613 translating from notes to chord names. Set to 1 to find
614 inversions. The default is 0 which does not look for