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{flagStyle}@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 true 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{stemLength}@indexcode{stemLength}
290 Set length of stems. Unit is `@code{staffspace}/2', so
291 @code{stemLength} defaults to 7.
293 g''4 \property Voice.stemLength = #14 g4 \property Voice.stemLength = #3 g4 g,,4
296 @item @code{stemLeftBeamCount}@indexcode{stemLeftBeamCount} @propertytype{integer}
297 Specify the number of beams to draw on the left side of the next
298 note. Overrides automatic beaming. The value is only used once,
299 and then it is erased.
301 @item @code{stemRightBeamCount}@indexcode{stemRightBeamCount} @propertytype{integer}
302 Specify the number of beams to draw on the right side of the next
303 note. Overrides automatic beaming. The value is only used once,
304 and then it is erased.
306 @item @code{tieDash}@indexcode{tieDash} @propertytype{integer}
307 Set dashing of ties. See also @code{slurDash}
309 @item @code{tieVerticalDirection}@indexcode{tieVerticalDirection} @propertytype{direction}
310 Set to @code{\free} for free choice of tie direction, set to
311 @code{\up} to force ties up, set to @code{\down} to force ties
314 @item @code{transposing}@indexcode{transposing} @propertytype{integer}
315 Transpose the MIDI output. Set this property to the number of
316 half-steps to transpose by.
318 @item @code{textEmptyDimension}@indexcode{textEmptyDimension} @propertytype{boolean}
319 If set to true then text placed above or below the staff is
320 assumed to have zero width. @code{fatText} and @code{emptyText}
321 are predefined settings.
324 c4^"foo" \emptyText c4^"foo" c4
327 @item @code{textStyle}@indexcode{textStyle} @propertytype{string}
328 Set the text style for superscripts and subscripts. See above
329 for list of text styles.
331 @item @code{textScriptPadding}@indexcode{textScriptPadding} @propertytype{number}
332 Determines the extra space added between superscripted resp.
333 subscripted text and the closest staff line or note.
335 @item @code{verticalDirection}@indexcode{verticalDirection} @propertytype{direction}
336 Determines the direction of stems, subscripts, beams, slurs, and
337 ties. Set to @code{\down} to force them down, @code{\up} to force
338 them up, or @code{\free} to let LilyPond decide. This can be used
339 to distinguish between voices on the same staff. The
340 @code{\stemDown}@keyindex{stemDown}, @code{\stemUp}@keyindex{stemUp},
341 and @code{\stemBoth}@keyindex{stemBoth} identifiers set this
345 @item @code{tupletDirection}@indexcode{tupletDirection} @propertytype{direction}
346 Determines the direction of triplets and other tuplets. Set to
347 @code{\down} to force them below the staff, @code{\up} to force
348 them above, or @code{\free} to let LilyPond decide.
350 @item @code{tupletBracketVisibility}@indexcode{tupletBracketVisibility} @propertytype{boolean} or @propertytype{symbol}
351 @item @code{tupletNumberVisibility}@indexcode{tupletNumberVisibility} @propertytype{boolean} or @propertytype{symbol}
353 These properties the visibility of the tuplet bracket and its
354 number respectively. Setting it to false will prevent printing of the
355 associated element. Setting the property to 'if-no-beam will make it
356 print only if there is no beam associated with this tuplet bracket.
358 @mudelafile[verbatim]{tuplet.ly}
360 @item @code{tupletInvisible}@indexcode{tupletInvisible} @propertytype{boolean}
362 If set to true, tuplet bracket creation is switched off
363 entirely. This has the same effect as setting both
364 @code{tupletNumberVisibility} and @code{tupletBracketVisibility} to
365 @code{#f}, but as this does not even create elements, this setting
366 uses less memory and time.
369 @item @code{tupletSpannerDuration} @indexcode{tupletSpannerDuration}
370 @propertytype{moment}
372 Normally a tuplet bracket is as wide as the
373 @code{\times} expression that gave rise to it. By setting this
374 property, you can make brackets last shorter. Example
376 @mudela[verbatim,fragment]
377 \context Voice \times 2/3 {
378 \property Voice.tupletSpannerDuration = #(make-moment 1 4)
385 @subsubheading Staff properties
387 @cindex properties!Staff
391 @item @code{barNonAuto}@indexcode{barNonAuto} @propertytype{boolean}
392 If set to true then bar lines will not be printed
393 automatically; they must be explicitly created with @code{\bar}
394 keywords. Unlike with the @code{\cadenza} keyword, measures are
395 still counted. Bar generation will resume according to that
396 count if this property is set to zero.
398 @item @code{barNumberDirection}@indexcode{barNumberDirection} @propertytype{direction}
399 Set to @code{\up} or @code{\down} to put bar numbers above or below
402 @item @code{barNumberScriptPadding}@indexcode{barNumberScriptPadding}
403 Sets extra space between the bar number and the bar it labels.
405 @item @code{barSize}@indexcode{barSize}
406 Specify the height of the bar lines if it should be different
407 than the staff height.
409 c1 c1 \property Staff.barSize = 20 c1 c1
412 @item @code{barAtLineStart}@indexcode{barAtLineStart} @propertytype{boolean}
413 Set to true to produce a bar line after the clef at the start
414 of each line (but not at the beginning of the music).
418 @item @code{clefStyle}@indexcode{clefStyle} @propertytype{string}
419 Determines how clefs are typeset. If set to @code{transparent},
420 the clefs are not printed at all [FIXME], if set to
421 @code{fullSizeChanges}, clef changes in the middle of a line are
422 typeset with a full size clef. By default, clef changes are
423 typeset in smaller size.
426 @item @code{staffSpace}@indexcode{staffLineLeading} @propertytype{number}
427 Specifies the distance (in points) between lines of the staff.
429 @item @code{numberOfStaffLines}@indexcode{numberOfStaffLines} @propertytype{integer}
430 Specifies the number of staff lines. The default is 5.
432 @item @code{postBreakPadding}@indexcode{postBreakPadding} @propertytype{number}
433 Extra space in points to be added after the clef, time signature
434 and key signature on the staff. Deprecated, do not use.
436 @item @code{noVoltaBraces}@indexcode{noVoltaBraces} @propertytype{boolean}
437 Set to true to suppress the printing of brackets over alternate
438 endings specified by the command @code{\alternative}. [BROKEN]
441 @item @code{barAlways}@indexcode{barAlways} @propertytype{boolean}
442 If set to true a bar line is drawn after each note.
444 @item @code{defaultBarType}@indexcode{defaultBarType} @propertytype{string}
445 Sets the default type of bar line. See Section XREF-barlines [FIXME]
446 for a list of available bar types.
448 @item @code{instrument}, @code{instr} @propertytype{string}
449 @indexcode{instrument}@indexcode{instr}
450 If @code{Instrument_name_engraver}
451 @cindex Instrument_name_engraver
453 added to the Staff translator, then the @code{instrument} property
454 is used to label the first line of the staff and the @code{instr}
455 property is used to label subsequent lines. If the
456 @code{midiInstrument} property is not set, then @code{instrument}
457 is used to determine the instrument for MIDI output.
459 @item @code{keyOctaviation}@indexcode{keyOctaviation} @propertytype{boolean}
460 If set to false, then keys are the same in all octaves. If set
461 to true then the key signature for different octaves can be
462 different and is specified independently:
465 \keysignature bes fis'
468 The default value is @code{#f}. Can be set to @code{#t} with
469 @code{\specialkey} or reset with @code{\normalkey}.
471 @item @code{timeSignatureStyle}@indexcode{timeSignatureStyle} @propertytype{string}
472 Changes the default two-digit layout for time signatures. The
473 following values are recognized:
476 @item @code{C}@indexcode{C}
477 4/4 and 2/2 are typeset as C and struck C, respectively. All
478 other time signatures are written with two digits.
480 @item @code{old}@indexcode{old}
481 2/2, 3/2, 2/4, 3/4, 4/4, 6/4, 9/4, 4/8, 6/8 and 9/8 are
482 typeset with old-style mensuration marks. All other time
483 signatures are written with two digits.
485 @item @code{1}@indexcode{1}
486 All time signatures are typeset with a single
487 digit, e.g. 3/2 is written as 3.
489 @item @indexcode{CM/N}@code{C}@var{M}@code{/}@var{N},
490 @indexcode{oldM/N}@code{old}@var{M}@code{/}@var{N} or
491 @code{old6/8alt}@indexcode{old6/8alt}
492 Tells LilyPond to use a specific symbol as time signature.
495 The different time signature characters are shown below with its
498 @mudela[center,verbatim]
501 \notes\relative c'' {
502 \property Voice.textStyle = typewriter
503 \property Staff.timeSignatureStyle = "C2/2"
504 \time 2/2; a2^"C2/2" a2
505 \property Staff.timeSignatureStyle = "C4/4"
506 \time 2/2; a2^"C4/4" a2
507 \property Staff.timeSignatureStyle = "old2/2"
508 \time 2/2; a2^"old2/2" a2
509 \property Staff.timeSignatureStyle = "old3/2"
510 \time 2/2; a2^"old3/2" a2
511 \property Staff.timeSignatureStyle = "old2/4"
512 \time 2/2; a2^"old2/4" a2
513 \property Staff.timeSignatureStyle = "old4/4"
514 \time 2/2; a2^"old4/4" a2
515 \property Staff.timeSignatureStyle = "old6/4"
516 \time 2/2; a2^"old6/4" a2
517 \property Staff.timeSignatureStyle = "old9/4"
518 \time 2/2; a2^"old9/4" a2
519 \property Staff.timeSignatureStyle = "old4/8"
520 \time 2/2; a2^"old4/8" a2
521 \property Staff.timeSignatureStyle = "old6/8"
522 \time 2/2; a2^"old6/8" a2
523 \property Staff.timeSignatureStyle = "old6/8alt"
524 \time 2/2; a2^"old6/8alt" a2
525 \property Staff.timeSignatureStyle = "old9/8"
526 \time 2/2; a2^"old9/8" a2
535 @item @code{voltaSpannerDuration}@indexcode{voltaSpannerDuration} @propertytype{moment}
539 @subsubheading GrandStaff properties
541 @cindex properties!GrandStaff
544 @item @code{maxVerticalAlign}@indexcode{maxVerticalAlign} @propertytype{number}
545 Set the maximum vertical distance between staffs.
547 @item @code{minVerticalAlign}@indexcode{minVerticalAlign} @propertytype{number}
548 Set the minimum vertical distance between staffs.
551 @subsubheading Score properties
553 @cindex properties!Score
559 @item @code{skipBars}@indexcode{skipBars} @propertytype{boolean}
560 Set to 1 to skip the empty bars that are produced by
561 multimeasure notes and rests. These bars will not appear on the
562 printed output. Set to zero (the default) to expand multimeasure
563 notes and rests into their full length, printing the appropriate
564 number of empty bars so that synchronization with other voices is
569 @mudela[fragment,verbatim,center]
570 r1 r1*3 R1*3\property Score.skipBars=1 r1*3 R1*3
575 @item @code{breakAlignOrder}@indexcode{breakAlignOrder} @propertytype{list of string}
577 Defines the order in which prefatory matter (clefs, key signatures) appears, eg. this puts the key signatures after the bar lines:
579 \property Score.breakAlignOrder = #'(
590 @item @code{timing}@indexcode{timing} @propertytype{boolean}
591 Keep administration of measure length, position, bar number, etc?
592 Switch off for cadenzas.
594 @item @code{currentBarNumber}@indexcode{currentBarNumber} @propertytype{integer}
595 Contains the current barnumber. This property is incremented at
598 @item @code{measurePosition}@indexcode{measurePosition} @propertytype{Moment}
600 How much of the current measure (measured in whole notes) have we had?
602 @item @code{oneBeat}@indexcode{oneBeat} @propertytype{Moment}
604 How long does one beat in the current time signature last?
606 @item @code{measureLength}@indexcode{measureLength} @propertytype{Moment}
608 How long does one measure in the current time signature last?
612 @subsubheading ChordNamesVoice properties
614 @cindex properties!ChordNamesVoice
617 @item @code{chordInversion}@indexcode{chordInversion} @propertytype{boolean}
618 Determines whether LilyPond should look for chord inversions when
619 translating from notes to chord names. Set to 1 to find
620 inversions. The default is 0 which does not look for