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 barlines 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 barlines running between but not through the staves, can be
105 produced from a @code{StaffGroup} or @code{GrandStaff} context if
106 the barlines 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 Each staff group context sets the property
138 @code{systemStartDelimiter} to one of the values
139 @internalsref{SystemStartBar}, @internalsref{SystemStartBrace},
140 and @internalsref{SystemStartBracket}. A fourth delimiter,
141 @code{systemStartSquare}, is also available, but must be
142 instantiated manually.
146 To display a bracket even if there is only one staff, see
147 @lsr{staff,display-bracket-with-only-one-staff-in-a
152 @unnumberedsubsubsec Staff symbol
154 @cindex adjusting staff symbol
156 The layout object which draws the lines of a staff is called
157 @code{staff symbol}. The staff symbol may be tuned in the number,
158 thickness and distance of lines, using properties. This is
159 demonstrated in the example files
160 @lsr{staff,changing-the-number-of-lines-in-a-staff.ly} and
161 @lsr{staff,changing-the-staff-size.ly}.
163 In addition, staves may be started and stopped at will. This is
164 done with @code{\startStaff} and @code{\stopStaff}.
166 @lilypond[verbatim,relative=2,fragment]
168 \override Staff.StaffSymbol #'line-count = 2
169 \stopStaff \startStaff
171 \revert Staff.StaffSymbol #'line-count
172 \stopStaff \startStaff
176 In combination with Frenched staves, this may be used to typeset
177 @emph{ossia} sections. An example is shown here
179 @cindex staves, Frenched
182 @lilypondfile{ossia.ly}
184 @cindex staff lines, setting number of
185 @cindex staff lines, setting thickness of
186 @cindex thickness of staff lines, setting
187 @cindex number of staff lines, setting
191 Program reference: @internalsref{StaffSymbol},
192 @internalsref{DrumStaff}.
194 Examples: @lsrdir{staff}
198 @unnumberedsubsubsec Hiding staves
200 @cindex Frenched scores
201 @cindex staves, hiding
203 In orchestral scores, staff lines that only have rests are usually
204 removed; this saves some space. This style is called @q{French
205 Score}. For @internalsref{Lyrics}, @internalsref{ChordNames} and
206 @internalsref{FiguredBass}, this is switched on by default. When
207 the lines of these contexts turn out empty after the line-breaking
208 process, they are removed.
210 For normal staves, a specialized @internalsref{Staff} context is
211 available, which does the same: staves containing nothing (or only
212 multi-measure rests) are removed. The context definition is
213 stored in @code{\RemoveEmptyStaffContext} variable. Observe how
214 the second staff in this example disappears in the second line
216 @lilypond[quote,ragged-right,verbatim]
218 \context { \RemoveEmptyStaffContext }
223 \new Staff { e4 f g a \break c1 }
224 \new Staff { c4 d e f \break R1 }
229 The first system shows all staves in full. If empty staves should
230 be removed from the first system too, set @code{remove-first} to
231 true in @internalsref{VerticalAxisGroup}.
234 \override Score.VerticalAxisGroup #'remove-first = ##t
237 To remove other types of contexts, use
238 @code{\AncientRemoveEmptyStaffContext} or
239 @code{\RemoveEmptyRhythmicStaffContext}.
241 Another application of the @code{\RemoveEmptyStaffContext} is to
242 make ossia sections, i.e., alternative melodies on a separate
243 piece of staff, with help of a Frenched staff. See @ref{Staff
246 You can make the staff lines invisible by removing the
247 @code{Staff_symbol_engraver} from the @code{Staff} context.
250 @lilypond[quote,ragged-right,verbatim]
252 \context Staff \relative c'' { c8 c c16 c c c }
256 \remove Staff_symbol_engraver
263 @subsection Writing parts
268 * Quoting other voices::
269 * Formatting cue notes::
272 @node Metronome marks
273 @unnumberedsubsubsec Metronome marks
276 @cindex beats per minute
277 @cindex metronome marking
279 Metronome settings can be entered as follows
282 \tempo @var{duration} = @var{per-minute}
285 In the MIDI output, they are interpreted as a tempo change. In
286 the layout output, a metronome marking is printed
290 @lilypond[quote,ragged-right,verbatim,fragment]
297 To change the tempo in the MIDI output without printing anything,
298 make the metronome marking invisible @example \once \override
299 Score.MetronomeMark #'transparent = ##t @end example
301 To print other metronome markings, use these markup commands
302 @lilypond[quote,ragged-right,verbatim,relative,fragment]
305 \smaller \general-align #Y #DOWN \note #"16." #1
307 \smaller \general-align #Y #DOWN \note #"8" #1
312 For more details, see @ref{Text markup}.
317 Program reference: @internalsref{MetronomeMark}.
322 Collisions are not checked. If you have notes above the top line
323 of the staff (or notes with articulations, slurs, text, etc), then
324 the metronome marking may be printed on top of musical symbols.
325 If this occurs, increase the padding of the metronome mark to
326 place it further away from the staff.
329 \override Score.MetronomeMark #'padding = #2.5
332 @c perhaps also an example of how to move it horizontally?
334 @node Instrument names
335 @unnumberedsubsubsec Instrument names
337 In an orchestral score, instrument names are printed at the left
340 This can be achieved by setting
341 @internalsref{Staff}.@code{instrumentName} and
342 @internalsref{Staff}.@code{shortInstrumentName}, or
343 @internalsref{PianoStaff}.@code{instrumentName} and
344 @internalsref{PianoStaff}.@code{shortInstrumentName}. This will
345 print text before the start of the staff. For the first staff,
346 @code{instrumentName} is used. If set, @code{shortInstrumentName}
347 is used for the following staves.
349 @lilypond[quote,verbatim,ragged-right,relative=1,fragment]
350 \set Staff.instrumentName = "Ploink "
351 \set Staff.shortInstrumentName = "Plk "
357 You can also use markup texts to construct more complicated
358 instrument names, for example
360 @lilypond[quote,fragment,verbatim,ragged-right]
361 \set Staff.instrumentName = \markup {
362 \column { "Clarinetti"
363 \line { "in B" \smaller \flat } } }
367 If you wish to center the instrument names, you must center all of
370 @lilypond[quote,verbatim,ragged-right]
373 \set Staff.instrumentName = \markup {
374 \center-align { "Clarinetti"
375 \line { "in B" \smaller \flat } } }
379 \set Staff.instrumentName =
380 \markup{ \center-align { Vibraphone }}
387 For longer instrument names, it may be useful to increase the
388 @code{indent} setting in the @code{\layout} block.
390 To center instrument names while leaving extra space to the right,
392 @lilypond[quote,verbatim,ragged-right]
393 \new StaffGroup \relative
396 \set Staff.instrumentName =
397 \markup { \hcenter-in #10 "blabla" }
401 \set Staff.instrumentName =
402 \markup { \hcenter-in #10 "blo" }
408 To add instrument names to other contexts (such as
409 @code{GrandStaff}, @code{ChoirStaff}, or @code{StaffGroup}), the
410 engraver must be added to that context.
414 \context @{\GrandStaff \consists "Instrument_name_engraver"@}
419 More information about adding and removing engravers can be found
420 in @ref{Modifying context plug-ins}.
422 Instrument names may be changed in the middle of a piece,
424 @lilypond[quote,fragment,verbatim,ragged-right]
425 \set Staff.instrumentName = "First"
426 \set Staff.shortInstrumentName = "one"
429 \set Staff.instrumentName = "Second"
430 \set Staff.shortInstrumentName = "two"
438 Program reference: @internalsref{InstrumentName}.
441 @node Quoting other voices
442 @unnumberedsubsubsec Quoting other voices
446 With quotations, fragments of other parts can be inserted into a
447 part directly. Before a part can be quoted, it must be marked
448 especially as quotable. This is done with the @code{\addQuote}
452 \addQuote @var{name} @var{music}
457 Here, @var{name} is an identifying string. The @var{music} is any
458 kind of music. Here is an example of @code{\addQuote}
461 \addQuote clarinet \relative c' @{
466 This command must be entered at toplevel, i.e., outside any music
467 blocks. Typically, one would use an already defined music event
471 clarinet = \relative c' @{
474 \addQuote clarinet @{ \clarinet @}
478 After calling @code{\addQuote}, the quotation may then be done
479 with @code{\quoteDuring} or @code{\cueDuring},
482 \quoteDuring #@var{name} @var{music}
485 During a part, a piece of music can be quoted with the
486 @code{\quoteDuring} command.
489 \quoteDuring #"clarinet" @{ s2. @}
492 This would cite three quarter notes (the duration of @code{s2.})
493 of the previously added @code{clarinet} voice.
495 More precisely, it takes the current time-step of the part being
496 printed, and extracts the notes at the corresponding point of the
497 @code{\addQuote}d voice. Therefore, the argument to
498 @code{\addQuote} should be the entire part of the voice to be
499 quoted, including any rests at the beginning.
501 It is possible to use another music expression instead of
502 @code{s}, thus creating a polyphonic section, but this may not
503 always give the desired result.
505 Quotations take into account the transposition of both source and
506 target instruments, if they are specified using the
507 @code{\transposition} command.
509 @lilypond[quote,ragged-right,verbatim]
510 \addQuote clarinet \relative c' {
516 e'8 f'8 \quoteDuring #"clarinet" { s2 }
520 The type of events that are present in the quoted music can be
521 trimmed with the @code{quotedEventTypes} property. The default
522 value is @code{(note-event rest-event)}, which means that only
523 notes and rests of the quoted voice end up in the
524 @code{\quoteDuring}. Setting
527 \set Staff.quotedEventTypes =
528 #'(note-event articulation-event dynamic-event)
532 will quote notes (but no rests), together with scripts and
537 Only the contents of the first @internalsref{Voice} occurring in
538 an @code{\addQuote} command will be considered for quotation, so
539 @var{music} can not contain @code{\new} and @code{\context Voice}
540 statements that would switch to a different Voice.
542 Quoting grace notes is broken and can even cause LilyPond to
545 Quoting nested triplets may result in poor notation.
547 In earlier versions of LilyPond (pre 2.11), @code{addQuote} was
548 written entirely in lower-case letters: @code{\addquote}.
552 In this manual: @ref{Instrument transpositions}.
554 Examples: @lsr{parts,quote.ly},
555 @lsr{parts,quote-transportation.ly}
557 Program reference: @internalsref{QuoteMusic}.
560 @node Formatting cue notes
561 @unnumberedsubsubsec Formatting cue notes
563 @cindex cues, formatting
565 The previous section deals with inserting notes from another
566 voice. There is a more advanced music function called
567 @code{\cueDuring}, which makes formatting cue notes easier.
572 \cueDuring #@var{name} #@var{updown} @var{music}
575 This will insert notes from the part @var{name} into a
576 @internalsref{Voice} called @code{cue}. This happens
577 simultaneously with @var{music}, which usually is a rest. When
578 the cue notes start, the staff in effect becomes polyphonic for a
579 moment. The argument @var{updown} determines whether the cue
580 notes should be notated as a first or second voice.
583 @lilypond[verbatim,ragged-right]
586 \override Stem #'length-fraction = #0.8
587 \override Beam #'thickness = #0.384
588 \override Beam #'length-fraction = #0.8
591 \addQuote clarinet \relative {
596 \new Staff \relative <<
598 % setup a context for cue notes.
599 \new Voice = "cue" { \smaller \skip 1*21 }
601 \set Score.skipBars = ##t
605 \cueDuring #"clarinet" #UP {
614 Here are a couple of hints for successful cue notes
618 Cue notes have smaller font sizes.
621 the cued part is marked with the instrument playing the cue.
624 when the original part takes over again, this should be marked
625 with the name of the original instrument.
627 Any other changes introduced by the cued part should also be
628 undone. For example, if the cued instrument plays in a different
629 clef, the original clef should be stated once again.
633 The macro @code{\transposedCueDuring} is useful to add cues to
634 instruments which use a completely different octave range (for
635 example, having a cue of a piccolo flute within a contra bassoon
638 @lilypond[verbatim,ragged-right,quote]
639 picc = \relative c''' {
645 \addQuote "picc" { \picc }
647 cbsn = \relative c, {
650 \transposedCueDuring #"picc" #UP c,, { R1 } |
655 \context Staff = "picc" \picc
656 \context Staff = "cbsn" \cbsn