Documentation/user/properties.itely

   1 @node Properties, , , Top
   2
   3 @cindex properties!Lyrics
   4
   5 @table @samp
   6   @item @code{textStyle}@indexcode{textStyle}
   7     Set the font for lyrics.  The available font choices are
   8     @code{roman}, @code{italic}, @code{bold}, @code{large}, @code{Large},
   9     @code{typewriter}, and @code{finger}.  The @code{finger} font can
  10     only display numbers.  Note also that you must be careful when
  11     using @code{\property} in Lyrics mode, because of the way strings
  12     are parsed.  Either put quotes around the arguments to
  13     @code{\property} or be sure to leave a space on both sides of the
  14     dot.
  15 @end table
  16
  17
  18 @cindex properties!Thread
  19
  20 @table @samp
  21   @item @code{noteheadStyle}@indexcode{noteheadStyle}
  22     Selects type of note head.  Choices are @code{cross},
  23     @code{diamond}, @code{harmonic}, @code{transparent}, and @code{""}.
  24     They are shown in that order below.
  25
  26     @mudela[center]
  27
  28       \score {
  29         \notes {
  30           \property Staff.barNonAuto = 1
  31           \property Voice.noteHeadStyle = cross
  32           a'
  33           \property Voice.noteHeadStyle = diamond
  34           a'
  35           \property Voice.noteHeadStyle = harmonic
  36           a'
  37           \property Voice.noteHeadStyle = transparent
  38           a'
  39           \property Voice.noteHeadStyle = ""
  40           a'
  41         }
  42         \paper {
  43           linewidth = -1.;
  44         }
  45       }
  46
  47 @end mudela
  48 @end table
  49
  50 @subsubheading Grace properties
  51
  52 @cindex properties!Grace
  53
  54
  55 @table @samp
  56   @item @code{stemStyle}@indexcode{stemStyle}
  57     By default set to @code{"grace"} meaning that all unbeamed
  58     notes with flags are typeset with a slash through the flag.
  59     Setting to @code{""} gives standard flags.
  60 @end table
  61
  62
  63 @subsubheading Voice properties
  64
  65 @cindex properties!Voice
  66
  67 @table @samp
  68   @item @code{abbrev}@indexcode{abbrev}
  69     Set length for tremolo to be used if no length is explicitly
  70     specified.
  71
  72   @item @code{articulationScriptPadding}@indexcode{articulationScriptPadding}
  73
  74     Determines the extra space added between articulation marks, such
  75     as staccato, tenuto, trill, up/down bow or fermata, and the
  76     closest staff line or note.
  77
  78   @item @code{articulationScriptVerticalDirection}
  79     @indexcode{articulationScriptVerticalDirection}
  80     Determines the location of articulation marks.  Set to @code{\up}
  81     to print marks above the staff; set to @code{\down} to print marks
  82     below the staff.  This property does not override explicit
  83     directions marked with `@code{^}' or `@code{_}' in the mudela file.
  84
  85   @item @code{noAutoBeaming}@indexcode{beamAuto}
  86     If set to 1 then beams are not generated automatically.
  87
  88   @item @code{beamAutoEnd}@indexcode{beamAutoEnd}
  89     Specifies when automatically generated beams can end.  See
  90     section XREF-autobeam [FIXME].
  91
  92   @item @code{beamAutoBegin}@indexcode{beamAutoBegin}
  93     Specifies when automatically generated beams can start.  See
  94     section XREF-autobeam [FIXME].
  95
  96   @item @code{beamquantisation}@indexcode{beamquantisation}
  97     Set to @code{\none} for no quantization.  Set to @code{\normal} to
  98     quantize position and slope.  Set to @code{\traditional} to avoid
  99     wedges.  These three settings are available via
 100     @code{\beamposfree}@keyindex{beamposfree},
 101     @code{\beamposnormal}@keyindex{beamposnormal}, and
 102     @code{\beampostraditional}@keyindex{beampostraditional}.
 103
 104   @item @code{beamslopedamping}@indexcode{beamslopedamping}
 105     Set to @code{\none} for undamped beams.  Set to @code{\normal} for
 106     damped beams.  Set to @code{\infinity} for beams with zero slope.
 107     The identifiers
 108     @code{\beamslopeproportional}@keyindex{beamslopeproportional},
 109     @code{\beamslopedamped}@keyindex{beamslopedamped}, and
 110     @code{\beamslopezero}@keyindex{beamslopezero} each set the
 111     corresponding value.
 112
 113   @item @code{dynamicDirection}@indexcode{dynamicDirection}
 114     Determines location of dynamic marks.  Set to @code{\up} to print
 115     marks above the staff; set to @code{\down} to print marks below
 116     the staff.
 117
 118   @item @code{dynamicStyle}@indexcode{dynamicStyle}
 119     Set the text style for dynamics.
 120
 121   @item @code{fontSize}@indexcode{fontSize}
 122     Can be used to select smaller font sizes for music.  The normal
 123     font size is 0, and the two smaller sizes are -1
 124     and -2.
 125
 126    @item @code{forceHorizontalShift}@indexcode{forceHorizontalShift}
 127     Force horizontal shift for collision resolution.  It overrides
 128     automatic collision resolution.  The value is the shift amount
 129     expressed in @code{note_width}, as set in the paper section.
 130
 131 [FIXME: this should be moved]
 132
 133 Lilypond always arranges note heads on alternate sides of a stem (that
 134 is, within a single voice) as necessary to prevent collisions (note head
 135 overlaps).  For up stems, the upper note of a colliding pair is placed
 136 on the right side of the stem, the lower on the left. For down stems,
 137 the algorithm works in reverse.
 138
 139 Lily also attempts to prevent collisions of note heads in different
 140 voices. A situation where chords of two or more voices are played
 141 simultaneously within one staff.
 142
 143 By default, if only two voices (and both have opposite stem directions)
 144 are in this 'collision group', the notes both are shifted by @code{0.5
 145 \quartwidth} if there are unisons or seconds between the voices.
 146
 147 If there are more than two voices in a collision group, shifting is
 148 inactive by default, since in this case, there are multiple chords with
 149 the same stem direction. By  distinguish between those chords, LilyPond
 150 can do collision resolution in these cases as well.
 151
 152 Distinguishing between voices with the same stem direction, is done by
 153 setting the property @code{Voice.horizontalNoteShift}.  It must be set
 154 to a different integer for each voice. Then, all note heads in collision
 155 groups (not just unisons and seconds) will be offset, one voice relative
 156 another.  The following fragment of sheet music shows how shifting is
 157 done, with values of @code{horizontalNoteShift} printed over and under
 158 the notes. In this case the chords are just simple notes.
 159
 160 @c URG : mudela book bug.
 161 @mudela[singleline]
 162 \score {
 163         \notes \context Staff <
 164                 \context Voice  = VA { \stemup f''4^"0" }
 165                 \context Voice  = VB {\stemup
 166                 \property Voice.horizontalNoteShift = 1 d''4^" 1" }
 167                 \context Voice  = VC { \stemup \property
 168 Voice.horizontalNoteShift = 2 b'4^"  2" }
 169                 \context Voice  = VD { \stemdown \property
 170 Voice.horizontalNoteShift = 1 g'4_"1 " }
 171                 \context Voice  = VE { \stemdown e'4_"0" }
 172         >
 173 }
 174 @end mudela
 175
 176 If you are not satisfied with the collision resolution of LilyPond, you
 177 can override the horizontal shift value of the chord of one Voice, by
 178 setting @code{forceHorizontalShift}.  This sets the amount shift,
 179 measured in black note head widths.
 180
 181 To take complete control of note position shifts in complex passages,
 182 you have set things up for normal collisions and override all shifts by
 183 setting @code{forceHorizontalShift} to zero everywhere
 184 @example
 185 \property Voice.horizontalNoteShift = <n>
 186 \property Voice.forceHorizontalShift = "0.0"
 187 @end example
 188
 189 Then you can set the force property to a suitable value before each note
 190 that really needs it (unisons and seconds), and reset it to 0.0 after
 191 the note.
 192
 193   @item @code{horizontalNoteShift}@indexcode{horizontalNoteShift}
 194     Enable LilyPond to shift notes horizontally if they collide with
 195     other notes.  This is useful when typesetting many voices on one
 196     staff.  The identifier @code{\shift}@keyindex{shift} is defined to
 197     enable this.  Traditionally, the outer chords (the upmost and
 198     downmost voices), should have no @code{horizontalNoteShift}.
 199
 200   @item @code{markScriptPadding}@indexcode{markScriptPadding}
 201     Determines the extra space added between the mark and the closest
 202     staff line or note.
 203
 204   @item @code{markDirection}@indexcode{markDirection}
 205     Determines if marks should be printed above or below the staff.
 206     Set to @code{\up} to print marks above the staff; set to
 207     @code{\down} to print marks below the staff.
 208
 209   @item @code{midiInstrument}@indexcode{midiInstrument}
 210     Sets the instrument for MIDI output.  If this property is not set
 211     then LilyPond will use the @code{instrument} property.  This must
 212     be set to one of the strings on the list of MIDI instruments that
 213     appears in section XREF-midilist [FIXME].  If you use a string which
 214     is not listed, LilyPond will silently substitute piano.
 215
 216   @item @code{oldTieBehavior}@indexcode{oldTieBehavior}
 217     Set to 1 in order to get old tie behavior where ties would
 218     connect unequal pitches.  This property is deprecated, and its
 219     use is not recommended.
 220
 221   @item @code{restStyle}@indexcode{restStyle}
 222     Change the layout of rests shorter than quarter notes.
 223     Currently, the standard layout @code{""} and mensural notation
 224     @code{"mensural"} are available. Mensural rests of duration
 225     32 or shorter are not available.
 226
 227   @item @code{scriptHorizontal}@indexcode{scriptHorizontal}
 228     Put scripts left or right of note heads.  Support for this is
 229     limited.  Accidentals will collide with scripts.
 230
 231   @item @code{slurVerticalDirection}@indexcode{slurVerticalDirection}
 232     Set to @code{\free} for free choice of slur direction, set to
 233     @code{\up} to force slurs up, set to @code{\down} to force slurs
 234     down.  The shorthands @code{\slurup}@keyindex{slurup},
 235     @code{\slurdown}@keyindex{slurdown}, and
 236     @code{\slurboth}@keyindex{slurboth} are available.
 237
 238   @item @code{slurDash}@indexcode{slurDash}
 239     Set to 0 for normal slurs, 1 for dotted slurs, and a
 240     larger value for dashed slurs.  Identifiers
 241     @code{\slurnormal}@keyindex{slurnormal} and
 242     @code{\slurdotted}@keyindex{slurdotted} are predefined to set the
 243     first two settings.
 244
 245 @item @code{stemLength}@indexcode{stemLength}
 246     Set length of stems.  Unit is `@code{interline}/2', so
 247     @code{stemLength} defaults to 7.
 248
 249   @item @code{stemLeftBeamCount}@indexcode{stemLeftBeamCount}
 250     Specify the number of beams to draw on the left side of the next
 251     note.  Overrides automatic beaming.  The value is only used once,
 252     and then it is erased.
 253
 254   @item @code{stemRightBeamCount}@indexcode{stemRightBeamCount}
 255     Specify the number of beams to draw on the right side of the next
 256     note.  Overrides automatic beaming.  The value is only used once,
 257     and then it is erased.
 258   @item @code{tieVerticalDirection}@indexcode{tieVerticalDirection}
 259     Set to @code{\free} for free choice of tie direction, set to
 260     @code{\up} to force ties up, set to @code{\down} to force ties
 261     down.
 262
 263   @item @code{transposing}@indexcode{transposing}
 264     Transpose the MIDI output.  Set this property to the number of
 265     half-steps to transpose by.
 266
 267
 268   @item @code{textEmptyDimension}@indexcode{textEmptyDimension}
 269     If set to 1 then text placed above or below the staff is
 270     assumed to have zero width.
 271
 272   @item @code{textStyle}@indexcode{textStyle}
 273     Set the text style for superscripts and subscripts.  See above
 274     for list of text styles.
 275
 276   @item @code{textScriptPadding}@indexcode{textScriptPadding}
 277     Determines the extra space added between superscripted resp.
 278     subscripted text and the closest staff line or note.
 279
 280   @item @code{verticalDirection}@indexcode{verticalDirection}
 281     Determines the direction of stems, subscripts, beams, slurs, and
 282     ties.  Set to @code{\down} to force them down, @code{\up} to force
 283     them up, or @code{\free} to let LilyPond decide.  This can be used
 284     to distinguish between voices on the same staff.  The
 285     @code{\stemdown}@keyindex{stemdown}, @code{\stemup}@keyindex{stemup},
 286     and @code{\stemboth}@keyindex{stemboth} identifiers set this
 287     property.
 288
 289
 290   @item @code{tupletDirection}@indexcode{tupletDirection}
 291     Determines the direction of triplets and other tuplets.  Set to
 292     @code{\down} to force them below the staff, @code{\up} to force
 293     them above, or @code{\free} to let LilyPond decide.
 294
 295   @item @code{tupletVisibility}@indexcode{tupletVisibility}
 296     Determines whether tuplets of notes are labelled.  Setting
 297     to 0 shows nothing; setting to 1 shows a number;
 298     setting to 2 shows a number and a bracket if there is no
 299     beam; setting to 3 shows a number, and if there is no beam
 300     it adds a bracket; setting to 4 shows both a number and a
 301     bracket unconditionally.
 302
 303 @end table
 304
 305 @subsubheading Staff properties
 306
 307 @cindex properties!Staff
 308
 309 @table @samp
 310
 311   @item @code{barNonAuto}@indexcode{barNonAuto}
 312     If set to 1 then bar lines will not be printed
 313     automatically; they must be explicitly created with @code{\bar}
 314     keywords.  Unlike with the @code{\cadenza} keyword, measures are
 315     still counted.  Bar generation will resume according to that
 316     count if this property is set to zero.
 317
 318   @item @code{barNumberDirection}@indexcode{barNumberDirection}
 319     Set to @code{\up} or @code{\down} to put bar numbers above or below
 320     the staff.
 321
 322   @item @code{barNumberHangOnClef}@indexcode{barNumberHangOnClef}
 323     Set to 1 to cause bar numbers to appear above or below the
 324     clef instead of on the bar line.  This property is deprecated.
 325     Do not use.
 326
 327   @item @code{barNumberScriptPadding}@indexcode{barNumberScriptPadding}
 328     Sets extra space between the bar number and the bar it labels.
 329
 330   @item @code{barSize}@indexcode{barSize}
 331     Specify the height of the bar lines if it should be different
 332     than the staff height.
 333
 334   @item @code{barAtLineStart}@indexcode{barAtLineStart}
 335     Set to 1 to produce a bar line after the clef at the start
 336     of each line (but not at the beginning of the music).
 337
 338   @item @code{clefStyle}@indexcode{clefStyle}
 339     Determines how clefs are typeset.  If set to @code{transparent},
 340     the clefs are not printed at all, if set to
 341     @code{fullSizeChanges}, clef changes in the middle of a line are
 342     typeset with a full size clef.  By default, clef changes are
 343     typeset in smaller size.
 344
 345   @item @code{createKeyOnClefChange}@indexcode{createKeyOnClefChange}
 346     Set to a nonempty string if you want key signatures to be printed
 347     when the clef changes.  Set to the empty string if you do not
 348     want key signatures printed.
 349
 350   @item @code{createInitdefaultClef}@indexcode{createInitdefaultClef}
 351     Specify whether clefs are created on default?  (Doesn't seem to
 352     do anything.)
 353
 354   @item @code{defaultClef}@indexcode{defaultClef}
 355     Determines the default clef.  See @code{\clef} keyword.
 356
 357   @item @code{markHangOnClef}@indexcode{markHangOnClef}
 358     Set to 1 to cause marks to appear by clefs instead of by bar
 359     lines.  Deprecated, use is not recommended.
 360
 361   @item @code{marginDirection}@indexcode{marginDirection}
 362     Set to @code{\left} or @code{\right} to specify location of
 363     marginal scripts.
 364
 365   @item @code{marginScriptPadding}@indexcode{marginScriptPadding}
 366     Specify extra space for marginal scripts.
 367
 368   @item @code{forgetAccidentals}@indexcode{forgetAccidentals}
 369     Causes accidentals to be printed at every note instead of
 370     remembered for the duration of a measure.
 371
 372   @item @code{noResetKey}@indexcode{noResetKey}
 373     Do not reset the key at the start of a measure.  Accidentals will
 374     be printed only once and are in effect until overridden, possibly
 375     many measures later.
 376
 377   @item @code{staffLineLeading}@indexcode{staffLineLeading}
 378     Specifies the distance (in points) between lines of the staff.
 379
 380   @item @code{numberOfStaffLines}@indexcode{numberOfStaffLines}
 381     Specifies the number of staff lines.  The default is 5.
 382
 383   @item @code{postBreakPadding}@indexcode{postBreakPadding}
 384     Extra space in points to be added after the clef, time signature
 385     and key signature on the staff.  Deprecated, do not use.
 386
 387   @item @code{noVoltaBraces}@indexcode{noVoltaBraces}
 388     Set to true to suppress the printing of brackets over alternate
 389     endings specified by the command @code{\alternative}.
 390
 391   @item @code{numberOfStaffLines}@indexcode{numberOfStaffLines}
 392     Sets the number of lines that the staff has.
 393
 394   @item @code{barAlways}@indexcode{barAlways}
 395     If set to 1 a bar line is drawn after each note.
 396
 397   @item @code{defaultBarType}@indexcode{defaultBarType}
 398     Sets the default type of bar line. See Section XREF-barlines [FIXME]
 399     for a list of available bar types.
 400
 401   @item @code{instrument}, @code{instr}
 402     @indexcode{instrument}@indexcode{instr}
 403     If @code{Staff_margin_engraver}
 404 @cindex Staff_margin_engraver
 405  is
 406     added to the Staff translator, then the @code{instrument} property
 407     is used to label the first line of the staff and the @code{instr}
 408     property is used to label subsequent lines.  If the
 409     @code{midiInstrument} property is not set, then @code{instrument}
 410     is used to determine the instrument for MIDI output.
 411
 412   @item @code{keyOctaviation}@indexcode{keyOctaviation}
 413     If set to 1, then keys are the same in all octaves.  If set
 414     to 0 then the key signature for different octaves can be
 415     different and is specified independently:
 416
 417     @example
 418       \keysignature bes fis'
 419     @end example
 420
 421     The default value is 1.  Can be set to zero with
 422     @code{\specialkey} or reset to 1 with @code{\normalkey}.
 423
 424   @item @code{timeSignatureStyle}@indexcode{timeSignatureStyle}
 425     Changes the default two-digit layout for time signatures.  The
 426     following values are recognized:
 427
 428     @table @samp
 429       @item @code{C}@indexcode{C}
 430         4/4 and 2/2 are typeset as C and struck C, respectively.  All
 431         other time signatures are written with two digits.
 432
 433       @item @code{old}@indexcode{old}
 434         2/2, 3/2, 2/4, 3/4, 4/4, 6/4, 9/4, 4/8, 6/8 and 9/8 are
 435         typeset with old-style mensuration marks.  All other time
 436         signatures are written with two digits.
 437
 438       @item @code{1}@indexcode{1}
 439         All time signatures are typeset with a single
 440         digit, e.g. 3/2 is written as 3.
 441
 442       @item @indexcode{CM/N}@code{C}@var{M}@code{/}@var{N},
 443       @indexcode{oldM/N}@code{old}@var{M}@code{/}@var{N} or
 444       @code{old6/8alt}@indexcode{old6/8alt}
 445         Tells LilyPond to use a specific symbol as time signature.
 446     @end table
 447
 448     The different time signature characters are shown below with its
 449     names:
 450
 451     @mudela[center]
 452
 453       \score {
 454         \notes\relative c'' {
 455           \property Voice.textStyle = typewriter
 456           \property Staff.timeSignatureStyle = "C2/2"
 457           \time 2/2; a2^"C2/2" a2
 458           \property Staff.timeSignatureStyle = "C4/4"
 459           \time 2/2; a2^"C4/4" a2
 460           \property Staff.timeSignatureStyle = "old2/2"
 461           \time 2/2; a2^"old2/2" a2
 462           \property Staff.timeSignatureStyle = "old3/2"
 463           \time 2/2; a2^"old3/2" a2
 464           \property Staff.timeSignatureStyle = "old2/4"
 465           \time 2/2; a2^"old2/4" a2
 466           \property Staff.timeSignatureStyle = "old4/4"
 467           \time 2/2; a2^"old4/4" a2
 468           \property Staff.timeSignatureStyle = "old6/4"
 469           \time 2/2; a2^"old6/4" a2
 470           \property Staff.timeSignatureStyle = "old9/4"
 471           \time 2/2; a2^"old9/4" a2
 472           \property Staff.timeSignatureStyle = "old4/8"
 473           \time 2/2; a2^"old4/8" a2
 474           \property Staff.timeSignatureStyle = "old6/8"
 475           \time 2/2; a2^"old6/8" a2
 476           \property Staff.timeSignatureStyle = "old6/8alt"
 477           \time 2/2; a2^"old6/8alt" a2
 478           \property Staff.timeSignatureStyle = "old9/8"
 479           \time 2/2; a2^"old9/8" a2
 480         }
 481         \paper {
 482           linewidth = 4.5 \in;
 483         }
 484       }
 485
 486 @end mudela
 487
 488   @item @code{voltaSpannerDuration}@indexcode{voltaSpannerDuration}
 489     Set to an integer to control the size of the brackets printed by
 490     @code{\alternative}.  The integer specifies the number of whole
 491     notes duration to use for the brackets.  It is rounded to the
 492     nearest measure.  This can be used to shrink the length of
 493     brackets in the situation where one alternative is very large.
 494     It may have odd effects if the specified duration is longer than
 495     the music given in an @code{\alternative}.
 496 @end table
 497
 498
 499 @cindex properties!GrandStaff
 500
 501 @table @samp
 502   @item @code{alignmentReference}@indexcode{alignmentReference}
 503     Set to @code{\center} for vertical alignment reference point to be
 504     in the center of the vertical group.  Set to @code{\up} to put the
 505     reference point at the top of the group.
 506
 507   @item @code{maxVerticalAlign}@indexcode{maxVerticalAlign}
 508     Set the maximum vertical distance between staffs.
 509
 510   @item @code{minVerticalAlign}@indexcode{minVerticalAlign}
 511     Set the minimum vertical distance between staffs.
 512 @end table
 513
 514
 515 @cindex properties!Score
 516
 517 @table @samp
 518   @item @code{skipBars}@indexcode{skipBars}
 519     Set to 1 to skip the empty bars that are produced by
 520     multimeasure notes and rests.  These bars will not appear on the
 521     printed output.  Set to zero (the default) to expand multimeasure
 522     notes and rests into their full length, printing the appropriate
 523     number of empty bars so that synchronization with other voices is
 524     preserved.
 525
 526     @quotation
 527
 528 @mudela[fragment,verbatim,center]
 529 r1 r1*3 R1*3\property Score.skipBars=1 r1*3 R1*3
 530
 531 @end mudela
 532     @end quotation
 533
 534 @end table
 535
 536
 537 @cindex properties!ChordNamesVoice
 538
 539 @table @samp
 540   @item @code{chordInversion}@indexcode{chordInversion}
 541     Determines whether LilyPond should look for chord inversions when
 542     translating from notes to chord names.  Set to 1 to find
 543     inversions.  The default is 0 which does not look for
 544     inversions.
 545 @end table
 546