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]{staff-headword.ly}
15 This section explains how to influence the staff appearance,
16 print scores with more than one staff, and
17 how to apply specific performance marks to single staves.
21 * Modifying single staves::
26 @node Displaying staves
27 @subsection Displaying staves
29 This section shows the different possibilities to create and group
30 staves into groups, which can be marked in the beginning of each
31 line with either a bracket or a brace.
34 * Initiating new staves::
38 @node Initiating new staves
39 @subsubsection Initiating new staves
42 @cindex staff initiation
45 The lines of a staff (pl. staves) are produced by a @code{staff symbol}
47 LilyPond ensures that all music is printed on staff lines so if you just
48 type in some notes, the staff symbol is added automatically to the output.
49 This is just a shortcut to make the program usage more easy, but in most
50 cases where you want to print more complex music on more than on staff
51 it is better to create the staff explicitly at the beginning of your
52 music inside of the @code{\score} environment.
54 With the command @code{\new Staff @{ ... @}} you actually call a new
55 Staff context that has already everything set up to the default
56 engraving rules. @ref{Creating contexts} explains how different contexts
59 Once a staff is instantiated it can be started or stopped at every point
60 in the score. This is done with the commands @code{\startStaff} and
61 @code{\stopStaff}. How to use it is shown in @ref{Staff symbol}.
63 Besides the default @code{Staff} context there are also
64 specialized staff contexts for setting percussion, Guitar music,
66 See @ref{Printing chord names}, @ref{Percussion staves},
67 @ref{Tablatures basic}, @ref{Gregorian Chant contexts}, and
68 @ref{Mensural contexts} for an explanation.
72 Music Glossary: @rglos{staff}, @rglos{staves}.
74 Notation Reference: @ref{Printing chord names}, @ref{Percussion staves},
75 @ref{Tablatures basic}, @ref{Gregorian Chant contexts}, and
76 @ref{Mensural contexts}.
78 Snippets: @lsrdir{Staff,Staff-notation}.
80 Internals Reference: @internalsref{Staff}.
85 @subsubsection Grouping staves
87 @cindex start of system
88 @cindex staff, multiple
89 @cindex staves, multiple
90 @cindex system start delimiters
91 @cindex bracket, vertical
92 @cindex brace, vertical
100 LilyPond provides different types of contexts to group single staves
101 together. These contexts influence in the first place the appearance
102 of the system start delimiter, but they have also influence on the
103 behaviour of the bar lines.
108 If no context is specified, the default properties for the score
109 will be used: the group is started with a vertical line, and the
110 bar lines are not connected.
112 @lilypond[verbatim,ragged-right,quote]
120 In a @code{StaffGroup}, the bar lines will be drawn through
121 all the staves, and the group is started with a bracket.
123 @lilypond[verbatim,ragged-right,quote]
133 In a @code{ChoirStaff}, the group is
134 started with a bracket, but bar lines are not connected.
136 @lilypond[verbatim,ragged-right,quote]
146 In a @code{GrandStaff}, the group is started with a brace
147 at the left, and bar lines are connected between the staves.
149 @lilypond[verbatim,ragged-right,quote]
159 The @code{PianoStaff} behaves almost as the @code{GrandStaff} but is
160 optimized for setting piano music.
162 @lilypond[verbatim,ragged-right,quote]
172 According to classic engraver rules an orchestral score consists of
173 staves connected only with a single line at the beginning of the system.
174 In LilyPond this is produced grouping the @code{Staff} contexts with
177 Each instrument family is grouped inside of a @code{StaffGroup} with a
178 starting bracket. A group of same instruments or an instrument using
179 more than one staff is grouped with braces in a @code{GrandStaff}.
181 As the context names tell, @code{PianoStaff} is used for notating
182 piano music and @code{ChoirStaff} for all kind of vocal ensemble music.
184 Here is an example of an orchestral score using groupings. Note that the
185 instrument names are omited here, see @ref{Instrument names} how to set
188 @lilypond[verbatim,ragged-right,quote]
189 \score{ \relative c' {
191 \new StaffGroup %the woodwinds group
197 \new StaffGroup %the brass group
201 \new GrandStaff %the horns need a GrandStaff (same instrument)
204 \new Staff {\clef bass c c }
207 \new ChoirStaff %for a vocal part
210 \new Staff {\clef alto c c }
211 \new Staff {\clef bass c c }
213 \new PianoStaff %for the piano
216 \new Staff {\clef bass c c }
222 The different staff contexts are already nested in this example, as
223 the @q{horn section} is contained both in a @code{StaffGroup} and a
226 @cindex staff, nested
228 It is also possible to nest staves of the same type with the contexts
229 @code{InnerStaffGroup} and @code{InnerChoirStaffGroup}. These behave like
230 the corresponding normal staff groups but can only initiated inside of
231 another staff context. Again LilyPond would add a normal @code{StaffGroup}
232 to the output, if you would start a score with an @code{InnerStaffGroup}.
234 Note that @code{GrandStaff} and @code{PianoStaff} do not have any inner
235 grouping contexts. They can both be inside an inner staff context, though.
237 @c snippet staff-brackets.ly
238 @lilypond[verbatim,ragged-right,quote]
242 \new Staff {c' d' e' f'}
243 \new InnerStaffGroup <<
244 \new Staff {c' d' e' f'}
246 \new Staff {c' d' e' f'}
247 \new Staff {c' d' e' f'}
249 \new Staff {c' d' e' f'}
252 \new Staff {c' d' e' f'}
253 \new InnerStaffGroup <<
254 \new Staff {c' d' e' f'}
256 \new Staff {c' d' e' f'}
260 \new Staff {c' d' e' f'}
261 \new InnerChoirStaff <<
262 \new Staff {c' d' e' f'}
263 \new Staff {c' d' e' f'}
265 \new Staff {c' d' e' f'}
273 @c FIXME: not yet in master
274 @c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
275 @c {nesting-staves.ly}
278 More complex nesting can be accomplished using the property
279 @code{systemStartDelimiterHierarchy}:
281 @lilypond[quote,ragged-right,verbatim]
284 \set StaffGroup.systemStartDelimiterHierarchy
285 = #'(SystemStartSquare (SystemStartBracket a
286 (SystemStartSquare b)) d)
295 Each staff group context sets the property
296 @code{systemStartDelimiter} to one of the values
297 @internalsref{SystemStartBar}, @internalsref{SystemStartBrace},
298 and @internalsref{SystemStartBracket}. A fourth delimiter,
299 @code{systemStartSquare}, is also available, but must be
300 instantiated manually
304 @cindex mensurstriche layout
305 @cindex renaissance music
306 @cindex transcription of mensural music
307 @cindex mensural music, transcription of
310 @c FIXME: not yet in master
311 @c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
312 @c {mensurstriche-layout.ly}
314 Other groupings may be achieved by changing various properties.
316 @q{Mensurstriche} layout common in Renaissance music, with
317 bar lines running between but not through the staves, can be
318 produced from a @code{StaffGroup} or @code{GrandStaff} context if
319 the bar lines are made transparent in the @code{Staff} itself:
321 @lilypond[verbatim,ragged-right,quote]
322 global = {\override Staff.BarLine #'transparent = ##t
324 %the final bar line is not interupted
325 \once \override Staff.BarLine #'transparent = ##f
329 \new Staff {<< \global { c1 c } >>}
330 \new Staff {<< \global { c c } >>}
336 @c FIXME: Graham will deal with this. -gp
338 To display a bracket even if there is only one staff, see
339 @c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
340 @c {staff,display-bracket-with-only-one-staff-in-a system.ly}
344 Music Glossary: @rglos{brace},
347 Snippets: @lsrdir{Staff,Staff-notation}
349 Internals Reference: @internalsref{ChoirStaff},
350 @internalsref{GrandStaff}, @internalsref{PianoStaff},
351 @internalsref{StaffGroup},
352 @internalsref{SystemStartBar}, @internalsref{SystemStartBrace},
353 @internalsref{SystemStartBracket}, @internalsref{SystemStartSquare}.
357 @node Modifying single staves
358 @subsection Modifying single staves
367 @subsubsection Staff symbol
369 @cindex adjusting staff symbol
371 The layout object which draws the lines of a staff is called
372 @code{staff symbol}. The staff symbol may be tuned in the number,
373 thickness and distance of lines, using properties. This is
374 demonstrated in the example files
375 @c @lsr{staff,changing-the-number-of-lines-in-a-staff.ly} and
376 @c @lsr{staff,changing-the-staff-size.ly}.
378 In addition, staves may be started and stopped at will. This is
379 done with @code{\startStaff} and @code{\stopStaff}.
381 @lilypond[verbatim,relative=2,fragment]
383 \override Staff.StaffSymbol #'line-count = 2
384 \stopStaff \startStaff
386 \revert Staff.StaffSymbol #'line-count
387 \stopStaff \startStaff
392 @subsubsection Ossia staves
394 @cindex staves, Frenched
396 @cindex Frenched staves
398 In combination with Frenched staves, this may be used to typeset
399 @emph{ossia} sections. An example is shown here
401 @lilypond[verbatim,relative=2,quote]
405 \remove "Time_signature_engraver"
407 \override StaffSymbol #'staff-space = #(magstep -2)
416 bes8[^"ossia" g bes g]
433 @cindex staff lines, setting number of
434 @cindex staff lines, setting thickness of
435 @cindex thickness of staff lines, setting
436 @cindex number of staff lines, setting
440 Music Glossary: @rglos{ossia}, @rglos{staff}, @rglos{Frenched staff}.
442 Snippets: @lsrdir{Staff,Staff-notation}
444 Internals Reference: @internalsref{StaffSymbol},
445 @internalsref{DrumStaff}.
449 @subsubsection Hiding staves
451 @cindex Frenched scores
452 @cindex staves, hiding
453 @cindex staves, empty
455 In orchestral scores, staff lines that only have rests are usually
456 removed; this saves some space. This style is called @q{French
457 Score}. For @code{Lyrics}, @code{ChordNames} and
458 @code{FiguredBass}, this is switched on by default. When
459 the lines of these contexts turn out empty after the line-breaking
460 process, they are removed.
462 For normal staves, a specialized @code{Staff} context is
463 available, which does the same: staves containing nothing (or only
464 multi-measure rests) are removed. The context definition is
465 stored in @code{\RemoveEmptyStaffContext} variable. Observe how
466 the second staff in this example disappears in the second line
468 @lilypond[quote,ragged-right,verbatim]
470 \context { \RemoveEmptyStaffContext }
475 \new Staff { e4 f g a \break c1 }
476 \new Staff { c4 d e f \break R1 }
481 The first system shows all staves in full. If empty staves should
482 be removed from the first system too, set @code{remove-first} to
483 true in @code{VerticalAxisGroup}.
486 \override Score.VerticalAxisGroup #'remove-first = ##t
489 To remove other types of contexts, use
490 @code{\AncientRemoveEmptyStaffContext} or
491 @code{\RemoveEmptyRhythmicStaffContext}.
495 Another application of the @code{\RemoveEmptyStaffContext} is to
496 make ossia sections, i.e., alternative melodies on a separate
497 piece of staff, with help of a Frenched staff. See @ref{Staff
500 You can make the staff lines invisible by removing the
501 @code{Staff_symbol_engraver} from the @code{Staff} context.
504 @lilypond[quote,ragged-right,verbatim]
506 \context Staff \relative c'' { c8 c c16 c c c }
510 \remove Staff_symbol_engraver
518 Notation Reference: @ref{Staff symbol}.
520 Snippets: @lsrdir{Staff,Staff-notation}
522 Internals Reference: @internalsref{ChordNames},
523 @internalsref{FiguredBass}, @internalsref{Lyrics},
524 @internalsref{Staff}, @internalsref{VerticalAxisGroup}.
527 @subsection Writing parts
532 * Quoting other voices::
533 * Formatting cue notes::
536 @node Metronome marks
537 @subsubsection Metronome marks
540 @cindex beats per minute
541 @cindex metronome marking
543 Metronome settings can be entered as follows
546 \tempo @var{duration} = @var{per-minute}
549 In the MIDI output, they are interpreted as a tempo change. In
550 the layout output, a metronome marking is printed
554 @lilypond[quote,ragged-right,verbatim,fragment]
561 To change the tempo in the MIDI output without printing anything,
562 make the metronome marking invisible @example \once \override
563 Score.MetronomeMark #'transparent = ##t @end example
565 To print other metronome markings, use these markup commands
566 @lilypond[quote,ragged-right,verbatim,relative,fragment]
569 \smaller \general-align #Y #DOWN \note #"16." #1
571 \smaller \general-align #Y #DOWN \note #"8" #1
576 For more details, see @ref{Text markup}.
581 Music Glossary: @rglos{metronome}, @rglos{metronomic indication},
582 @rglos{tempo indication}, @rglos{metronome mark}.
584 Notation Reference: @ref{Text markup}.
586 Snippets: @lsrdir{Staff,Staff-notation}.
588 Internals Reference: @internalsref{MetronomeMark}, @ref{MIDI
594 Collisions are not checked. If you have notes above the top line
595 of the staff (or notes with articulations, slurs, text, etc), then
596 the metronome marking may be printed on top of musical symbols.
597 If this occurs, increase the padding of the metronome mark to
598 place it further away from the staff.
601 \override Score.MetronomeMark #'padding = #2.5
604 @c perhaps also an example of how to move it horizontally?
607 @node Instrument names
608 @subsubsection Instrument names
610 @cindex instrument names
611 @cindex instrument names, short
613 In an orchestral score, instrument names are printed at the left
616 This can be achieved by setting @code{Staff}.@code{instrumentName} and
617 @code{Staff}.@code{shortInstrumentName}, or
618 @code{PianoStaff}.@code{instrumentName} and
619 @code{PianoStaff}.@code{shortInstrumentName}. This will print text
620 before the start of the staff. For the first staff,
621 @code{instrumentName} is used. If set, @code{shortInstrumentName} is
622 used for the following staves.
624 @lilypond[quote,verbatim,ragged-right,relative=1,fragment]
625 \set Staff.instrumentName = "Ploink "
626 \set Staff.shortInstrumentName = "Plk "
632 You can also use markup texts to construct more complicated
633 instrument names, for example
635 @lilypond[quote,fragment,verbatim,ragged-right]
636 \set Staff.instrumentName = \markup {
637 \column { "Clarinetti"
638 \line { "in B" \smaller \flat } } }
642 @cindex instrument names, centering
644 As instrument names are centered by default, multi line names
645 are better entered using @code{\center-align}:
647 @lilypond[quote,verbatim,ragged-right]
650 \set Staff.instrumentName = \markup \center-align {
652 \line { "in B" \smaller \flat }
657 \set Staff.instrumentName = "Vibraphone"
664 For longer instrument names, it may be useful to increase the
665 @code{indent} setting in the @code{\layout} block.
667 Short instrument names, printed before the systems following the first
668 one, are also centered by default, in a space which width is given by
669 the @code{short-indent} variable of the @code{\layout} block.
671 To add instrument names to other contexts (such as
672 @code{GrandStaff}, @code{ChoirStaff}, or @code{StaffGroup}), the
673 engraver must be added to that context.
677 \context @{\GrandStaff \consists "Instrument_name_engraver"@}
682 More information about adding and removing engravers can be found
683 in @ref{Modifying context plug-ins}.
685 @cindex instrument names, changing
687 Instrument names may be changed in the middle of a piece,
689 @lilypond[quote,fragment,verbatim,ragged-right]
690 \set Staff.instrumentName = "First"
691 \set Staff.shortInstrumentName = "one"
694 \set Staff.instrumentName = "Second"
695 \set Staff.shortInstrumentName = "two"
703 Notation Reference: @ref{Modifying context plug-ins}.
705 Snippets: @lsrdir{Staff,Staff-notation}
707 Internals Reference: @internalsref{InstrumentName},
708 @internalsref{PianoStaff}, @internalsref{Staff}.
711 @node Quoting other voices
712 @subsubsection Quoting other voices
715 @cindex quoting other voices
719 With quotations, fragments of other parts can be inserted into a
720 part directly. Before a part can be quoted, it must be marked
721 especially as quotable. This is done with the @code{\addQuote}
725 \addQuote @var{name} @var{music}
730 Here, @var{name} is an identifying string. The @var{music} is any
731 kind of music. Here is an example of @code{\addQuote}
734 \addQuote clarinet \relative c' @{
739 This command must be entered at toplevel, i.e., outside any music
740 blocks. Typically, one would use an already defined music event
744 clarinet = \relative c' @{
747 \addQuote clarinet @{ \clarinet @}
751 After calling @code{\addQuote}, the quotation may then be done
752 with @code{\quoteDuring} or @code{\cueDuring},
755 \quoteDuring #@var{name} @var{music}
758 During a part, a piece of music can be quoted with the
759 @code{\quoteDuring} command.
762 \quoteDuring #"clarinet" @{ s2. @}
765 This would cite three quarter notes (the duration of @code{s2.})
766 of the previously added @code{clarinet} voice.
768 More precisely, it takes the current time-step of the part being
769 printed, and extracts the notes at the corresponding point of the
770 @code{\addQuote}d voice. Therefore, the argument to
771 @code{\addQuote} should be the entire part of the voice to be
772 quoted, including any rests at the beginning.
774 It is possible to use another music expression instead of
775 @code{s}, thus creating a polyphonic section, but this may not
776 always give the desired result.
778 Quotations take into account the transposition of both source and
779 target instruments, if they are specified using the
780 @code{\transposition} command.
782 @lilypond[quote,ragged-right,verbatim]
783 \addQuote clarinet \relative c' {
789 e'8 f'8 \quoteDuring #"clarinet" { s2 }
793 The type of events that are present in the quoted music can be
794 trimmed with the @code{quotedEventTypes} property. The default
795 value is @code{(note-event rest-event)}, which means that only
796 notes and rests of the quoted voice end up in the
797 @code{\quoteDuring}. Setting
800 \set Staff.quotedEventTypes =
801 #'(note-event articulation-event dynamic-event)
805 will quote notes (but no rests), together with scripts and
810 Only the contents of the first @code{Voice} occurring in an
811 @code{\addQuote} command will be considered for quotation, so
812 @var{music} can not contain @code{\new} and @code{\context Voice}
813 statements that would switch to a different Voice.
815 Quoting grace notes is broken and can even cause LilyPond to
818 Quoting nested triplets may result in poor notation.
820 In earlier versions of LilyPond (pre 2.11), @code{addQuote} was
821 written entirely in lower-case letters: @code{\addquote}.
825 Notation Reference: @ref{Instrument transpositions}.
827 Snippets: @lsrdir{Staff,Staff-notation}
829 Internals Reference: @internalsref{QuoteMusic}, @internalsref{Voice}.
832 @node Formatting cue notes
833 @subsubsection Formatting cue notes
837 @cindex cue notes, formatting
839 @cindex quoting other voices
840 @cindex cues, formatting
842 The previous section deals with inserting notes from another
843 voice. There is a more advanced music function called
844 @code{\cueDuring}, which makes formatting cue notes easier.
849 \cueDuring #@var{name} #@var{updown} @var{music}
852 This will insert notes from the part @var{name} into a
853 @code{Voice} called @code{cue}. This happens
854 simultaneously with @var{music}, which usually is a rest. When
855 the cue notes start, the staff in effect becomes polyphonic for a
856 moment. The argument @var{updown} determines whether the cue
857 notes should be notated as a first or second voice.
860 @lilypond[verbatim,ragged-right]
863 \override Stem #'length-fraction = #0.8
864 \override Beam #'thickness = #0.384
865 \override Beam #'length-fraction = #0.8
868 \addQuote clarinet \relative {
873 \new Staff \relative <<
875 % setup a context for cue notes.
876 \new Voice = "cue" { \smaller \skip 1*21 }
878 \set Score.skipBars = ##t
882 \cueDuring #"clarinet" #UP {
891 Here are a couple of hints for successful cue notes:
895 Cue notes have smaller font sizes.
898 The cued part is marked with the instrument playing the cue.
901 When the original part takes over again, this should be marked
902 with the name of the original instrument.
905 Any other changes introduced by the cued part should also be
906 undone. For example, if the cued instrument plays in a different
907 clef, the original clef should be stated once again.
911 The macro @code{\transposedCueDuring} is useful to add cues to
912 instruments which use a completely different octave range (for
913 example, having a cue of a piccolo flute within a contra bassoon
916 @lilypond[verbatim,ragged-right,quote]
917 picc = \relative c''' {
923 \addQuote "picc" { \picc }
925 cbsn = \relative c, {
928 \transposedCueDuring #"picc" #UP c,, { R1 } |
933 \context Staff = "picc" \picc
934 \context Staff = "cbsn" \cbsn
940 Snippets: @lsrdir{Staff,Staff-notation}.
942 Internals Reference: @internalsref{Voice}.