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 @lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16]
16 This section explains how to influence the staff appearance,
17 print scores with more than one staff, and
18 how to apply specific performance marks to single staves.
22 * Modifying single staves::
27 @node Displaying staves
28 @subsection Displaying staves
30 This section shows the different possibilities to create and group
31 staves into groups, which can be marked in the beginning of each
32 line with either a bracket or a brace.
35 * Initiating new staves::
39 @node Initiating new staves
40 @subsubsection Initiating new staves
43 @cindex staff initiation
46 The lines of a staff (pl. staves) are produced by a @code{staff symbol}
48 LilyPond ensures that all music is printed on staff lines so if you just
49 type in some notes, the staff symbol is added automatically to the output.
50 This is just a shortcut to make the program usage more easy, but in most
51 cases where you want to print more complex music on more than on staff
52 it is better to create the staff explicitly at the beginning of your
53 music inside of the @code{\score} environment.
55 With the command @code{\new Staff @{ ... @}} you actually call a new
56 Staff context that has already everything set up to the default
57 engraving rules. @ref{Creating contexts} explains how different contexts
60 Once a staff is instantiated it can be started or stopped at every point
61 in the score. This is done with the commands @code{\startStaff} and
62 @code{\stopStaff}. How to use it is shown in @ref{Staff symbol}.
64 Besides the default @code{Staff} context there are also
65 specialized staff contexts for setting percussion, Guitar music,
67 See @ref{Printing chord names}, @ref{Percussion staves},
68 @ref{Tablatures basic}, @ref{Gregorian Chant contexts}, and
69 @ref{Mensural contexts} for an explanation.
73 Music Glossary: @rglos{staff}, @rglos{staves}.
75 Notation Reference: @ref{Printing chord names}, @ref{Percussion staves},
76 @ref{Tablatures basic}, @ref{Gregorian Chant contexts}, and
77 @ref{Mensural contexts}.
79 Snippets: @lsrdir{Staff,Staff-notation}.
81 Internals Reference: @internalsref{Staff}.
86 @subsubsection Grouping staves
88 @cindex start of system
89 @cindex staff, multiple
90 @cindex staves, multiple
91 @cindex system start delimiters
92 @cindex bracket, vertical
93 @cindex brace, vertical
101 LilyPond provides different types of contexts to group single staves
102 together. These contexts influence in the first place the appearance
103 of the system start delimiter, but they have also influence on the
104 behaviour of the bar lines.
109 If no context is specified, the default properties for the score
110 will be used: the group is started with a vertical line, and the
111 bar lines are not connected.
113 @lilypond[verbatim,ragged-right,quote]
121 In a @code{StaffGroup}, the bar lines will be drawn through
122 all the staves, and the group is started with a bracket.
124 @lilypond[verbatim,ragged-right,quote]
134 In a @code{ChoirStaff}, the group is
135 started with a bracket, but bar lines are not connected.
137 @lilypond[verbatim,ragged-right,quote]
147 In a @code{GrandStaff}, the group is started with a brace
148 at the left, and bar lines are connected between the staves.
150 @lilypond[verbatim,ragged-right,quote]
160 The @code{PianoStaff} behaves almost as the @code{GrandStaff} but is
161 optimized for setting piano music.
163 @lilypond[verbatim,ragged-right,quote]
173 According to classic engraver rules an orchestral score consists of
174 staves connected only with a single line at the beginning of the system.
175 In LilyPond this is produced grouping the @code{Staff} contexts with
178 Each instrument family is grouped inside of a @code{StaffGroup} with a
179 starting bracket. A group of same instruments or an instrument using
180 more than one staff is grouped with braces in a @code{GrandStaff}.
182 As the context names tell, @code{PianoStaff} is used for notating
183 piano music and @code{ChoirStaff} for all kind of vocal ensemble music.
185 Here is an example of an orchestral score using groupings. Note that the
186 instrument names are omited here, see @ref{Instrument names} how to set
189 @lilypond[verbatim,ragged-right,quote]
190 \score{ \relative c' {
192 \new StaffGroup %the woodwinds group
198 \new StaffGroup %the brass group
202 \new GrandStaff %the horns need a GrandStaff (same instrument)
205 \new Staff {\clef bass c c }
208 \new ChoirStaff %for a vocal part
211 \new Staff {\clef alto c c }
212 \new Staff {\clef bass c c }
214 \new PianoStaff %for the piano
217 \new Staff {\clef bass c c }
223 The different staff contexts are already nested in this example, as
224 the @q{horn section} is contained both in a @code{StaffGroup} and a
227 @cindex staff, nested
229 It is also possible to nest staves of the same type with the contexts
230 @code{InnerStaffGroup} and @code{InnerChoirStaffGroup}. These behave like
231 the corresponding normal staff groups but can only initiated inside of
232 another staff context. Again LilyPond would add a normal @code{StaffGroup}
233 to the output, if you would start a score with an @code{InnerStaffGroup}.
235 Note that @code{GrandStaff} and @code{PianoStaff} do not have any inner
236 grouping contexts. They can both be inside an inner staff context, though.
238 @c snippet staff-brackets.ly
239 @lilypond[verbatim,ragged-right,quote]
243 \new Staff {c' d' e' f'}
244 \new InnerStaffGroup <<
245 \new Staff {c' d' e' f'}
247 \new Staff {c' d' e' f'}
248 \new Staff {c' d' e' f'}
250 \new Staff {c' d' e' f'}
253 \new Staff {c' d' e' f'}
254 \new InnerStaffGroup <<
255 \new Staff {c' d' e' f'}
257 \new Staff {c' d' e' f'}
261 \new Staff {c' d' e' f'}
262 \new InnerChoirStaff <<
263 \new Staff {c' d' e' f'}
264 \new Staff {c' d' e' f'}
266 \new Staff {c' d' e' f'}
274 @c FIXME: not yet in master
275 @c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
276 @c {nesting-staves.ly}
279 More complex nesting can be accomplished using the property
280 @code{systemStartDelimiterHierarchy}:
282 @lilypond[quote,ragged-right,verbatim]
285 \set StaffGroup.systemStartDelimiterHierarchy
286 = #'(SystemStartSquare (SystemStartBracket a
287 (SystemStartSquare b)) d)
296 Each staff group context sets the property
297 @code{systemStartDelimiter} to one of the values
298 @internalsref{SystemStartBar}, @internalsref{SystemStartBrace},
299 and @internalsref{SystemStartBracket}. A fourth delimiter,
300 @code{systemStartSquare}, is also available, but must be
301 instantiated manually
305 @cindex mensurstriche layout
306 @cindex renaissance music
307 @cindex transcription of mensural music
308 @cindex mensural music, transcription of
311 @c FIXME: not yet in master
312 @c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
313 @c {mensurstriche-layout.ly}
315 Other groupings may be achieved by changing various properties.
317 @q{Mensurstriche} layout common in Renaissance music, with
318 bar lines running between but not through the staves, can be
319 produced from a @code{StaffGroup} or @code{GrandStaff} context if
320 the bar lines are made transparent in the @code{Staff} itself:
322 @lilypond[verbatim,ragged-right,quote]
323 global = {\override Staff.BarLine #'transparent = ##t
325 %the final bar line is not interupted
326 \once \override Staff.BarLine #'transparent = ##f
330 \new Staff {<< \global { c1 c } >>}
331 \new Staff {<< \global { c c } >>}
337 @c FIXME: Graham will deal with this. -gp
339 To display a bracket even if there is only one staff, see
340 @c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
341 @c {staff,display-bracket-with-only-one-staff-in-a system.ly}
345 Music Glossary: @rglos{brace},
348 Snippets: @lsrdir{Staff,Staff-notation}
350 Internals Reference: @internalsref{ChoirStaff},
351 @internalsref{GrandStaff}, @internalsref{PianoStaff},
352 @internalsref{StaffGroup},
353 @internalsref{SystemStartBar}, @internalsref{SystemStartBrace},
354 @internalsref{SystemStartBracket}, @internalsref{SystemStartSquare}.
358 @node Modifying single staves
359 @subsection Modifying single staves
368 @subsubsection Staff symbol
370 @cindex adjusting staff symbol
372 The layout object which draws the lines of a staff is called
373 @code{staff symbol}. The staff symbol may be tuned in the number,
374 thickness and distance of lines, using properties. This is
375 demonstrated in the example files
376 @c @lsr{staff,changing-the-number-of-lines-in-a-staff.ly} and
377 @c @lsr{staff,changing-the-staff-size.ly}.
379 In addition, staves may be started and stopped at will. This is
380 done with @code{\startStaff} and @code{\stopStaff}.
382 @lilypond[verbatim,relative=2,fragment]
384 \override Staff.StaffSymbol #'line-count = 2
385 \stopStaff \startStaff
387 \revert Staff.StaffSymbol #'line-count
388 \stopStaff \startStaff
393 @subsubsection Ossia staves
395 @cindex staves, Frenched
397 @cindex Frenched staves
399 In combination with Frenched staves, this may be used to typeset
400 @emph{ossia} sections. An example is shown here
402 @lilypond[verbatim,relative=2,quote]
406 \remove "Time_signature_engraver"
408 \override StaffSymbol #'staff-space = #(magstep -2)
417 bes8[^"ossia" g bes g]
434 @cindex staff lines, setting number of
435 @cindex staff lines, setting thickness of
436 @cindex thickness of staff lines, setting
437 @cindex number of staff lines, setting
441 Music Glossary: @rglos{ossia}, @rglos{staff}, @rglos{Frenched staff}.
443 Snippets: @lsrdir{Staff,Staff-notation}
445 Internals Reference: @internalsref{StaffSymbol},
446 @internalsref{DrumStaff}.
450 @subsubsection Hiding staves
452 @cindex Frenched scores
453 @cindex staves, hiding
454 @cindex staves, empty
456 In orchestral scores, staff lines that only have rests are usually
457 removed; this saves some space. This style is called @q{French
458 Score}. For @code{Lyrics}, @code{ChordNames} and
459 @code{FiguredBass}, this is switched on by default. When
460 the lines of these contexts turn out empty after the line-breaking
461 process, they are removed.
463 For normal staves, a specialized @code{Staff} context is
464 available, which does the same: staves containing nothing (or only
465 multi-measure rests) are removed. The context definition is
466 stored in @code{\RemoveEmptyStaffContext} variable. Observe how
467 the second staff in this example disappears in the second line
469 @lilypond[quote,ragged-right,verbatim]
471 \context { \RemoveEmptyStaffContext }
476 \new Staff { e4 f g a \break c1 }
477 \new Staff { c4 d e f \break R1 }
482 The first system shows all staves in full. If empty staves should
483 be removed from the first system too, set @code{remove-first} to
484 true in @code{VerticalAxisGroup}.
487 \override Score.VerticalAxisGroup #'remove-first = ##t
490 To remove other types of contexts, use
491 @code{\AncientRemoveEmptyStaffContext} or
492 @code{\RemoveEmptyRhythmicStaffContext}.
496 Another application of the @code{\RemoveEmptyStaffContext} is to
497 make ossia sections, i.e., alternative melodies on a separate
498 piece of staff, with help of a Frenched staff. See @ref{Staff
501 You can make the staff lines invisible by removing the
502 @code{Staff_symbol_engraver} from the @code{Staff} context.
505 @lilypond[quote,ragged-right,verbatim]
507 \context Staff \relative c'' { c8 c c16 c c c }
511 \remove Staff_symbol_engraver
519 Notation Reference: @ref{Staff symbol}.
521 Snippets: @lsrdir{Staff,Staff-notation}
523 Internals Reference: @internalsref{ChordNames},
524 @internalsref{FiguredBass}, @internalsref{Lyrics},
525 @internalsref{Staff}, @internalsref{VerticalAxisGroup}.
528 @subsection Writing parts
533 * Quoting other voices::
534 * Formatting cue notes::
537 @node Metronome marks
538 @subsubsection Metronome marks
541 @cindex beats per minute
542 @cindex metronome marking
544 Metronome settings can be entered as follows
547 \tempo @var{duration} = @var{per-minute}
550 In the MIDI output, they are interpreted as a tempo change. In
551 the layout output, a metronome marking is printed
555 @lilypond[quote,ragged-right,verbatim,fragment]
562 To change the tempo in the MIDI output without printing anything,
563 make the metronome marking invisible @example \once \override
564 Score.MetronomeMark #'transparent = ##t @end example
566 To print other metronome markings, use these markup commands
567 @lilypond[quote,ragged-right,verbatim,relative,fragment]
570 \smaller \general-align #Y #DOWN \note #"16." #1
572 \smaller \general-align #Y #DOWN \note #"8" #1
577 For more details, see @ref{Text markup}.
582 Music Glossary: @rglos{metronome}, @rglos{metronomic indication},
583 @rglos{tempo indication}, @rglos{metronome mark}.
585 Notation Reference: @ref{Text markup}.
587 Snippets: @lsrdir{Staff,Staff-notation}.
589 Internals Reference: @internalsref{MetronomeMark}, @ref{MIDI
595 Collisions are not checked. If you have notes above the top line
596 of the staff (or notes with articulations, slurs, text, etc), then
597 the metronome marking may be printed on top of musical symbols.
598 If this occurs, increase the padding of the metronome mark to
599 place it further away from the staff.
602 \override Score.MetronomeMark #'padding = #2.5
605 @c perhaps also an example of how to move it horizontally?
608 @node Instrument names
609 @subsubsection Instrument names
611 @cindex instrument names
612 @cindex instrument names, short
614 In an orchestral score, instrument names are printed at the left
617 This can be achieved by setting @code{Staff}.@code{instrumentName} and
618 @code{Staff}.@code{shortInstrumentName}, or
619 @code{PianoStaff}.@code{instrumentName} and
620 @code{PianoStaff}.@code{shortInstrumentName}. This will print text
621 before the start of the staff. For the first staff,
622 @code{instrumentName} is used. If set, @code{shortInstrumentName} is
623 used for the following staves.
625 @lilypond[quote,verbatim,ragged-right,relative=1,fragment]
626 \set Staff.instrumentName = "Ploink "
627 \set Staff.shortInstrumentName = "Plk "
633 You can also use markup texts to construct more complicated
634 instrument names, for example
636 @lilypond[quote,fragment,verbatim,ragged-right]
637 \set Staff.instrumentName = \markup {
638 \column { "Clarinetti"
639 \line { "in B" \smaller \flat } } }
643 @cindex instrument names, centering
645 As instrument names are centered by default, multi line names
646 are better entered using @code{\center-align}:
648 @lilypond[quote,verbatim,ragged-right]
651 \set Staff.instrumentName = \markup \center-align {
653 \line { "in B" \smaller \flat }
658 \set Staff.instrumentName = "Vibraphone"
665 For longer instrument names, it may be useful to increase the
666 @code{indent} setting in the @code{\layout} block.
668 Short instrument names, printed before the systems following the first
669 one, are also centered by default, in a space which width is given by
670 the @code{short-indent} variable of the @code{\layout} block.
672 To add instrument names to other contexts (such as
673 @code{GrandStaff}, @code{ChoirStaff}, or @code{StaffGroup}), the
674 engraver must be added to that context.
678 \context @{\GrandStaff \consists "Instrument_name_engraver"@}
683 More information about adding and removing engravers can be found
684 in @ref{Modifying context plug-ins}.
686 @cindex instrument names, changing
688 Instrument names may be changed in the middle of a piece,
690 @lilypond[quote,fragment,verbatim,ragged-right]
691 \set Staff.instrumentName = "First"
692 \set Staff.shortInstrumentName = "one"
695 \set Staff.instrumentName = "Second"
696 \set Staff.shortInstrumentName = "two"
704 Notation Reference: @ref{Modifying context plug-ins}.
706 Snippets: @lsrdir{Staff,Staff-notation}
708 Internals Reference: @internalsref{InstrumentName},
709 @internalsref{PianoStaff}, @internalsref{Staff}.
712 @node Quoting other voices
713 @subsubsection Quoting other voices
716 @cindex quoting other voices
720 With quotations, fragments of other parts can be inserted into a
721 part directly. Before a part can be quoted, it must be marked
722 especially as quotable. This is done with the @code{\addQuote}
726 \addQuote @var{name} @var{music}
731 Here, @var{name} is an identifying string. The @var{music} is any
732 kind of music. Here is an example of @code{\addQuote}
735 \addQuote clarinet \relative c' @{
740 This command must be entered at toplevel, i.e., outside any music
741 blocks. Typically, one would use an already defined music event
745 clarinet = \relative c' @{
748 \addQuote clarinet @{ \clarinet @}
752 After calling @code{\addQuote}, the quotation may then be done
753 with @code{\quoteDuring} or @code{\cueDuring},
756 \quoteDuring #@var{name} @var{music}
759 During a part, a piece of music can be quoted with the
760 @code{\quoteDuring} command.
763 \quoteDuring #"clarinet" @{ s2. @}
766 This would cite three quarter notes (the duration of @code{s2.})
767 of the previously added @code{clarinet} voice.
769 More precisely, it takes the current time-step of the part being
770 printed, and extracts the notes at the corresponding point of the
771 @code{\addQuote}d voice. Therefore, the argument to
772 @code{\addQuote} should be the entire part of the voice to be
773 quoted, including any rests at the beginning.
775 It is possible to use another music expression instead of
776 @code{s}, thus creating a polyphonic section, but this may not
777 always give the desired result.
779 Quotations take into account the transposition of both source and
780 target instruments, if they are specified using the
781 @code{\transposition} command.
783 @lilypond[quote,ragged-right,verbatim]
784 \addQuote clarinet \relative c' {
790 e'8 f'8 \quoteDuring #"clarinet" { s2 }
794 The type of events that are present in the quoted music can be
795 trimmed with the @code{quotedEventTypes} property. The default
796 value is @code{(note-event rest-event)}, which means that only
797 notes and rests of the quoted voice end up in the
798 @code{\quoteDuring}. Setting
801 \set Staff.quotedEventTypes =
802 #'(note-event articulation-event dynamic-event)
806 will quote notes (but no rests), together with scripts and
811 Only the contents of the first @code{Voice} occurring in an
812 @code{\addQuote} command will be considered for quotation, so
813 @var{music} can not contain @code{\new} and @code{\context Voice}
814 statements that would switch to a different Voice.
816 Quoting grace notes is broken and can even cause LilyPond to
819 Quoting nested triplets may result in poor notation.
821 In earlier versions of LilyPond (pre 2.11), @code{addQuote} was
822 written entirely in lower-case letters: @code{\addquote}.
826 Notation Reference: @ref{Instrument transpositions}.
828 Snippets: @lsrdir{Staff,Staff-notation}
830 Internals Reference: @internalsref{QuoteMusic}, @internalsref{Voice}.
833 @node Formatting cue notes
834 @subsubsection Formatting cue notes
838 @cindex cue notes, formatting
840 @cindex quoting other voices
841 @cindex cues, formatting
843 The previous section deals with inserting notes from another
844 voice. There is a more advanced music function called
845 @code{\cueDuring}, which makes formatting cue notes easier.
850 \cueDuring #@var{name} #@var{updown} @var{music}
853 This will insert notes from the part @var{name} into a
854 @code{Voice} called @code{cue}. This happens
855 simultaneously with @var{music}, which usually is a rest. When
856 the cue notes start, the staff in effect becomes polyphonic for a
857 moment. The argument @var{updown} determines whether the cue
858 notes should be notated as a first or second voice.
861 @lilypond[verbatim,ragged-right]
864 \override Stem #'length-fraction = #0.8
865 \override Beam #'thickness = #0.384
866 \override Beam #'length-fraction = #0.8
869 \addQuote clarinet \relative {
874 \new Staff \relative <<
876 % setup a context for cue notes.
877 \new Voice = "cue" { \smaller \skip 1*21 }
879 \set Score.skipBars = ##t
883 \cueDuring #"clarinet" #UP {
892 Here are a couple of hints for successful cue notes:
896 Cue notes have smaller font sizes.
899 The cued part is marked with the instrument playing the cue.
902 When the original part takes over again, this should be marked
903 with the name of the original instrument.
906 Any other changes introduced by the cued part should also be
907 undone. For example, if the cued instrument plays in a different
908 clef, the original clef should be stated once again.
912 The macro @code{\transposedCueDuring} is useful to add cues to
913 instruments which use a completely different octave range (for
914 example, having a cue of a piccolo flute within a contra bassoon
917 @lilypond[verbatim,ragged-right,quote]
918 picc = \relative c''' {
924 \addQuote "picc" { \picc }
926 cbsn = \relative c, {
929 \transposedCueDuring #"picc" #UP c,, { R1 } |
934 \context Staff = "picc" \picc
935 \context Staff = "cbsn" \cbsn
941 Snippets: @lsrdir{Staff,Staff-notation}.
943 Internals Reference: @internalsref{Voice}.