1 @c -*- coding: utf-8; mode: texinfo; -*-
3 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
5 When revising a translation, copy the HEAD committish of the
6 version that you are working on. See TRANSLATION for details.
10 @section Staff notation
12 Notes, dynamic signs, etc., are grouped with a set of horizontal
13 lines, called a staff (plural @q{staves}). In LilyPond, these
14 lines are drawn using a separate layout object called @code{staff
17 Two or more staves can be grouped vertically in a
18 @internalsref{GrandStaff}, a @internalsref{StaffGroup}, or a
19 @internalsref{ChoirStaff}.
28 @node Displaying staves
29 @subsection Displaying staves
32 * System start delimiters::
37 @node System start delimiters
38 @unnumberedsubsubsec System start delimiters
40 @cindex start of system
41 @cindex Staff, multiple
42 @cindex bracket, vertical
43 @cindex brace, vertical
48 Many scores consist of more than one staff. These staves can be
49 grouped in several different ways:
53 In a @internalsref{GrandStaff}, the group is started with a brace
54 at the left, and bar lines are connected between the staves.
56 @lilypond[verbatim,ragged-right,quote]
65 In a @internalsref{StaffGroup}, the bar lines will be drawn through
66 all the staves, but the group is started with a bracket.
68 @lilypond[verbatim,ragged-right,quote]
77 In a @internalsref{ChoirStaff}, the group is started with a
78 bracket, but bar lines are not connected.
80 @lilypond[verbatim,ragged-right,quote]
89 If no context is specified, the default properties for the score
90 will be used: the group is started with a vertical line, and the
91 bar lines are not connected.
93 @lilypond[verbatim,ragged-right,quote]
101 In addition to these four staff group types, other groupings can
102 be produced by changing various properties. E.g., the
103 @q{Mensurstriche} layout common in Renaissance music, with
104 bar lines running between but not through the staves, can be
105 produced from a @code{StaffGroup} or @code{GrandStaff} context if
106 the bar lines are made transparent in the @code{Staff} itself, with
107 the command @code{\override Staff.BarLine #'transparent = ##t}
109 @cindex staff, nested
111 Staff groups can be nested, using the context
112 @code{InnerStaffGroup} or @code{InnerChoirStaff}; see
113 @lsr{staff,staff-brackets.ly}
118 More complex nesting can be accomplished using the property
119 @internalsref{systemStartDelimiterHierarchy}:
121 @lilypond[quote,ragged-right,verbatim]
124 \set StaffGroup.systemStartDelimiterHierarchy
125 = #'(SystemStartSquare (SystemStartBracket a
126 (SystemStartSquare b)) d)
137 Snippets: @lsrdir{staff}
139 Each staff group context sets the property
140 @code{systemStartDelimiter} to one of the values
141 @internalsref{SystemStartBar}, @internalsref{SystemStartBrace},
142 and @internalsref{SystemStartBracket}. A fourth delimiter,
143 @code{systemStartSquare}, is also available, but must be
144 instantiated manually.
148 To display a bracket even if there is only one staff, see
149 @lsr{staff,display-bracket-with-only-one-staff-in-a
154 @unnumberedsubsubsec Staff symbol
156 @cindex adjusting staff symbol
158 The layout object which draws the lines of a staff is called
159 @code{staff symbol}. The staff symbol may be tuned in the number,
160 thickness and distance of lines, using properties. This is
161 demonstrated in the example files
162 @lsr{staff,changing-the-number-of-lines-in-a-staff.ly} and
163 @lsr{staff,changing-the-staff-size.ly}.
165 In addition, staves may be started and stopped at will. This is
166 done with @code{\startStaff} and @code{\stopStaff}.
168 @lilypond[verbatim,relative=2,fragment]
170 \override Staff.StaffSymbol #'line-count = 2
171 \stopStaff \startStaff
173 \revert Staff.StaffSymbol #'line-count
174 \stopStaff \startStaff
178 In combination with Frenched staves, this may be used to typeset
179 @emph{ossia} sections. An example is shown here
181 @cindex staves, Frenched
184 @lilypond[verbatim,relative=2,quote]
188 \remove "Time_signature_engraver"
190 \override StaffSymbol #'staff-space = #(magstep -2)
199 bes8[^"ossia" g bes g]
216 @cindex staff lines, setting number of
217 @cindex staff lines, setting thickness of
218 @cindex thickness of staff lines, setting
219 @cindex number of staff lines, setting
223 Snippets: @lsrdir{staff}
225 Internals Reference: @internalsref{StaffSymbol},
226 @internalsref{DrumStaff}.
228 Examples: @lsrdir{staff}
232 @unnumberedsubsubsec Hiding staves
234 @cindex Frenched scores
235 @cindex staves, hiding
237 In orchestral scores, staff lines that only have rests are usually
238 removed; this saves some space. This style is called @q{French
239 Score}. For @internalsref{Lyrics}, @internalsref{ChordNames} and
240 @internalsref{FiguredBass}, this is switched on by default. When
241 the lines of these contexts turn out empty after the line-breaking
242 process, they are removed.
244 For normal staves, a specialized @internalsref{Staff} context is
245 available, which does the same: staves containing nothing (or only
246 multi-measure rests) are removed. The context definition is
247 stored in @code{\RemoveEmptyStaffContext} variable. Observe how
248 the second staff in this example disappears in the second line
250 @lilypond[quote,ragged-right,verbatim]
252 \context { \RemoveEmptyStaffContext }
257 \new Staff { e4 f g a \break c1 }
258 \new Staff { c4 d e f \break R1 }
263 The first system shows all staves in full. If empty staves should
264 be removed from the first system too, set @code{remove-first} to
265 true in @internalsref{VerticalAxisGroup}.
268 \override Score.VerticalAxisGroup #'remove-first = ##t
271 To remove other types of contexts, use
272 @code{\AncientRemoveEmptyStaffContext} or
273 @code{\RemoveEmptyRhythmicStaffContext}.
275 Another application of the @code{\RemoveEmptyStaffContext} is to
276 make ossia sections, i.e., alternative melodies on a separate
277 piece of staff, with help of a Frenched staff. See @ref{Staff
280 You can make the staff lines invisible by removing the
281 @code{Staff_symbol_engraver} from the @code{Staff} context.
284 @lilypond[quote,ragged-right,verbatim]
286 \context Staff \relative c'' { c8 c c16 c c c }
290 \remove Staff_symbol_engraver
298 Snippets: @lsrdir{staff}
301 @subsection Writing parts
306 * Quoting other voices::
307 * Formatting cue notes::
310 @node Metronome marks
311 @unnumberedsubsubsec Metronome marks
314 @cindex beats per minute
315 @cindex metronome marking
317 Metronome settings can be entered as follows
320 \tempo @var{duration} = @var{per-minute}
323 In the MIDI output, they are interpreted as a tempo change. In
324 the layout output, a metronome marking is printed
328 @lilypond[quote,ragged-right,verbatim,fragment]
335 To change the tempo in the MIDI output without printing anything,
336 make the metronome marking invisible @example \once \override
337 Score.MetronomeMark #'transparent = ##t @end example
339 To print other metronome markings, use these markup commands
340 @lilypond[quote,ragged-right,verbatim,relative,fragment]
343 \smaller \general-align #Y #DOWN \note #"16." #1
345 \smaller \general-align #Y #DOWN \note #"8" #1
350 For more details, see @ref{Text markup}.
355 Internals Reference: @internalsref{MetronomeMark}, @ref{MIDI
361 Collisions are not checked. If you have notes above the top line
362 of the staff (or notes with articulations, slurs, text, etc), then
363 the metronome marking may be printed on top of musical symbols.
364 If this occurs, increase the padding of the metronome mark to
365 place it further away from the staff.
368 \override Score.MetronomeMark #'padding = #2.5
371 @c perhaps also an example of how to move it horizontally?
375 Snippets: @lsrdir{staff}
377 @node Instrument names
378 @unnumberedsubsubsec Instrument names
380 In an orchestral score, instrument names are printed at the left
383 This can be achieved by setting
384 @internalsref{Staff}.@code{instrumentName} and
385 @internalsref{Staff}.@code{shortInstrumentName}, or
386 @internalsref{PianoStaff}.@code{instrumentName} and
387 @internalsref{PianoStaff}.@code{shortInstrumentName}. This will
388 print text before the start of the staff. For the first staff,
389 @code{instrumentName} is used. If set, @code{shortInstrumentName}
390 is used for the following staves.
392 @lilypond[quote,verbatim,ragged-right,relative=1,fragment]
393 \set Staff.instrumentName = "Ploink "
394 \set Staff.shortInstrumentName = "Plk "
400 You can also use markup texts to construct more complicated
401 instrument names, for example
403 @lilypond[quote,fragment,verbatim,ragged-right]
404 \set Staff.instrumentName = \markup {
405 \column { "Clarinetti"
406 \line { "in B" \smaller \flat } } }
410 If you wish to center the instrument names, you must center all of
413 @lilypond[quote,verbatim,ragged-right]
416 \set Staff.instrumentName = \markup {
417 \center-align { "Clarinetti"
418 \line { "in B" \smaller \flat } } }
422 \set Staff.instrumentName =
423 \markup{ \center-align { Vibraphone }}
430 For longer instrument names, it may be useful to increase the
431 @code{indent} setting in the @code{\layout} block.
433 To center instrument names while leaving extra space to the right,
435 @lilypond[quote,verbatim,ragged-right]
436 \new StaffGroup \relative
439 \set Staff.instrumentName =
440 \markup { \hcenter-in #10 "blabla" }
444 \set Staff.instrumentName =
445 \markup { \hcenter-in #10 "blo" }
451 To add instrument names to other contexts (such as
452 @code{GrandStaff}, @code{ChoirStaff}, or @code{StaffGroup}), the
453 engraver must be added to that context.
457 \context @{\GrandStaff \consists "Instrument_name_engraver"@}
462 More information about adding and removing engravers can be found
463 in @ref{Modifying context plug-ins}.
465 Instrument names may be changed in the middle of a piece,
467 @lilypond[quote,fragment,verbatim,ragged-right]
468 \set Staff.instrumentName = "First"
469 \set Staff.shortInstrumentName = "one"
472 \set Staff.instrumentName = "Second"
473 \set Staff.shortInstrumentName = "two"
481 Snippets: @lsrdir{staff}
483 Internals Reference: @internalsref{InstrumentName}.
486 @node Quoting other voices
487 @unnumberedsubsubsec Quoting other voices
491 With quotations, fragments of other parts can be inserted into a
492 part directly. Before a part can be quoted, it must be marked
493 especially as quotable. This is done with the @code{\addQuote}
497 \addQuote @var{name} @var{music}
502 Here, @var{name} is an identifying string. The @var{music} is any
503 kind of music. Here is an example of @code{\addQuote}
506 \addQuote clarinet \relative c' @{
511 This command must be entered at toplevel, i.e., outside any music
512 blocks. Typically, one would use an already defined music event
516 clarinet = \relative c' @{
519 \addQuote clarinet @{ \clarinet @}
523 After calling @code{\addQuote}, the quotation may then be done
524 with @code{\quoteDuring} or @code{\cueDuring},
527 \quoteDuring #@var{name} @var{music}
530 During a part, a piece of music can be quoted with the
531 @code{\quoteDuring} command.
534 \quoteDuring #"clarinet" @{ s2. @}
537 This would cite three quarter notes (the duration of @code{s2.})
538 of the previously added @code{clarinet} voice.
540 More precisely, it takes the current time-step of the part being
541 printed, and extracts the notes at the corresponding point of the
542 @code{\addQuote}d voice. Therefore, the argument to
543 @code{\addQuote} should be the entire part of the voice to be
544 quoted, including any rests at the beginning.
546 It is possible to use another music expression instead of
547 @code{s}, thus creating a polyphonic section, but this may not
548 always give the desired result.
550 Quotations take into account the transposition of both source and
551 target instruments, if they are specified using the
552 @code{\transposition} command.
554 @lilypond[quote,ragged-right,verbatim]
555 \addQuote clarinet \relative c' {
561 e'8 f'8 \quoteDuring #"clarinet" { s2 }
565 The type of events that are present in the quoted music can be
566 trimmed with the @code{quotedEventTypes} property. The default
567 value is @code{(note-event rest-event)}, which means that only
568 notes and rests of the quoted voice end up in the
569 @code{\quoteDuring}. Setting
572 \set Staff.quotedEventTypes =
573 #'(note-event articulation-event dynamic-event)
577 will quote notes (but no rests), together with scripts and
582 Only the contents of the first @internalsref{Voice} occurring in
583 an @code{\addQuote} command will be considered for quotation, so
584 @var{music} can not contain @code{\new} and @code{\context Voice}
585 statements that would switch to a different Voice.
587 Quoting grace notes is broken and can even cause LilyPond to
590 Quoting nested triplets may result in poor notation.
592 In earlier versions of LilyPond (pre 2.11), @code{addQuote} was
593 written entirely in lower-case letters: @code{\addquote}.
597 Notation Reference: @ref{Instrument transpositions}.
599 Snippets: @lsrdir{staff}
601 Internals Reference: @internalsref{QuoteMusic}.
604 @node Formatting cue notes
605 @unnumberedsubsubsec Formatting cue notes
607 @cindex cues, formatting
609 The previous section deals with inserting notes from another
610 voice. There is a more advanced music function called
611 @code{\cueDuring}, which makes formatting cue notes easier.
616 \cueDuring #@var{name} #@var{updown} @var{music}
619 This will insert notes from the part @var{name} into a
620 @internalsref{Voice} called @code{cue}. This happens
621 simultaneously with @var{music}, which usually is a rest. When
622 the cue notes start, the staff in effect becomes polyphonic for a
623 moment. The argument @var{updown} determines whether the cue
624 notes should be notated as a first or second voice.
627 @lilypond[verbatim,ragged-right]
630 \override Stem #'length-fraction = #0.8
631 \override Beam #'thickness = #0.384
632 \override Beam #'length-fraction = #0.8
635 \addQuote clarinet \relative {
640 \new Staff \relative <<
642 % setup a context for cue notes.
643 \new Voice = "cue" { \smaller \skip 1*21 }
645 \set Score.skipBars = ##t
649 \cueDuring #"clarinet" #UP {
658 Here are a couple of hints for successful cue notes
662 Cue notes have smaller font sizes.
665 the cued part is marked with the instrument playing the cue.
668 when the original part takes over again, this should be marked
669 with the name of the original instrument.
671 Any other changes introduced by the cued part should also be
672 undone. For example, if the cued instrument plays in a different
673 clef, the original clef should be stated once again.
677 The macro @code{\transposedCueDuring} is useful to add cues to
678 instruments which use a completely different octave range (for
679 example, having a cue of a piccolo flute within a contra bassoon
682 @lilypond[verbatim,ragged-right,quote]
683 picc = \relative c''' {
689 \addQuote "picc" { \picc }
691 cbsn = \relative c, {
694 \transposedCueDuring #"picc" #UP c,, { R1 } |
699 \context Staff = "picc" \picc
700 \context Staff = "cbsn" \cbsn
706 Snippets: @lsrdir{staff}