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 * Instantiating new staves::
36 * Deeper nested staff groups::
39 @node Instantiating new staves
40 @subsubsection Instantiating new staves
43 @cindex staff initiation
44 @cindex staff instantiation
48 @cindex percussion staff
49 @cindex Gregorian transciption staff
50 @cindex rhythmic staff
54 The lines of a staff (pl. staves) are produced by the @code{staff symbol}
55 layout object. Staves are created with the @code{\new} or
56 @code{\context} commands. For an explanation on these commands,
57 see @ref{Creating contexts}.
59 There are different predefined staff contexts available in Lilypond:
63 The default is @code{Staff}:
64 @lilypond[verbatim,ragged-right,quote]
66 \new Staff { c d e f }
71 @code{DrumStaff} creates a five line staff set up for a typical drum set.
72 It uses different names for each instrument. The instrument names have to
73 be set using the @code{drummode}. See @ref{Percussion staves}.
74 @lilypond[verbatim,ragged-right,quote]
76 \drummode { cymc hh ss tomh }
81 @code{GregorianTranscriptionStaff} sets up a staff to notate modern
82 Gregorian chant. It does not show bar lines.
83 @lilypond[verbatim,ragged-right,quote]
85 \new GregorianTranscriptionStaff { c d e f }
90 @code{RhythmicStaff} can be used to show the rhythm of some music. The
91 notes are printed on one line regardless of their pitch, but the duration
92 is preserved. See @ref{Showing melody rhythms}.
93 @lilypond[verbatim,ragged-right,quote]
95 \new RhythmicStaff { c d e f }
100 @code{TabStaff} creates by default a tabulature with six strings in
101 standard guitar tuning. See @ref{Tablatures basic}.
102 @lilypond[verbatim,ragged-right,quote]
104 \new TabStaff { c d e f }
111 Besides these staves there are two staff contexts specific for the notation
112 of ancient music: @code{MensuralStaff} and @code{VaticanaStaff}. They are
113 described in @ref{Pre-defined contexts}.
115 Once a staff is instantiated it can be started or stopped at every point
116 in the score. This is done with the commands @code{\startStaff} and
117 @code{\stopStaff}. How to use it is explained in @ref{Staff symbol}.
122 Music Glossary: @rglos{staff}, @rglos{staves}.
124 Notation Reference: @ref{Percussion staves},
125 @ref{Tablatures basic}, @ref{Gregorian Chant contexts}, and
126 @ref{Mensural contexts}.
128 Snippets: @lsrdir{Staff,Staff-notation}.
130 Internals Reference: @internalsref{Staff}, @internalsref{DrumStaff},
131 @internalsref{GregorianTranscriptionStaff}, @internalsref{RhythmicStaff},
132 @internalsref{TabStaff}, @internalsref{MensuralStaff},
133 @internalsref{VaticanaStaff}.
137 @node Grouping staves
138 @subsubsection Grouping staves
140 @cindex start of system
141 @cindex staff, multiple
142 @cindex staves, multiple
143 @cindex system start delimiters
144 @cindex bracket, vertical
145 @cindex brace, vertical
153 LilyPond provides different types of contexts to group single staves
154 together. These contexts influence in the first place the appearance
155 of the system start delimiter, but they have also influence on the
156 behaviour of the bar lines.
158 Each staff group context sets the property
159 @code{systemStartDelimiter} to one of the values
160 @internalsref{SystemStartBar}, @internalsref{SystemStartBrace},
161 and @internalsref{SystemStartBracket}. A fourth delimiter,
162 @code{systemStartSquare}, is also available, but must be
163 instantiated manually. The usage of this last delimiter is shown in the
164 snippet section in @ref{Deeper nested staff groups}.
169 If no context is specified, the default properties for the score
170 will be used: the group is started with a vertical line, and the
171 bar lines are not connected.
173 @lilypond[verbatim,ragged-right,quote]
181 In a @code{StaffGroup}, the bar lines will be drawn through
182 all the staves, and the group is started with a bracket.
184 @lilypond[verbatim,ragged-right,quote]
194 In a @code{ChoirStaff}, the group is
195 started with a bracket, but bar lines are not connected.
197 @lilypond[verbatim,ragged-right,quote]
207 In a @code{GrandStaff}, the group is started with a brace
208 at the left, and bar lines are connected between the staves.
210 @lilypond[verbatim,ragged-right,quote]
220 The @code{PianoStaff} behaves almost as the @code{GrandStaff} but is
221 optimized for setting piano music.
223 @lilypond[verbatim,ragged-right,quote]
234 According to classic engraver rules an orchestral score consists of
235 staves connected only with a single line at the beginning of the system.
236 In LilyPond this is produced grouping the @code{Staff} contexts with
239 Each instrument family is grouped inside of a @code{StaffGroup} with a
240 starting bracket. A group of same instruments or an instrument using
241 more than one staff is grouped with braces in a @code{GrandStaff}.
243 As the context names tell, @code{PianoStaff} is used for notating
244 piano music and @code{ChoirStaff} for all kind of vocal ensemble music.
249 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
250 {display-bracket-with-only-one-staff-in-a-system.ly}
252 @c need this additional line: \override Score.SystemStartBar #'collapse-height = #1
254 @cindex mensurstriche layout
255 @cindex renaissance music
256 @cindex transcription of mensural music
257 @cindex mensural music, transcription of
259 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
260 {mensurstriche-layout-bar-lines-between-the-staves.ly}
265 Music Glossary: @rglos{brace},
268 Snippets: @lsrdir{Staff,Staff-notation}
270 Internals Reference: @internalsref{ChoirStaff},
271 @internalsref{GrandStaff}, @internalsref{StaffGroup},
272 @internalsref{SystemStartBar}, @internalsref{SystemStartBrace},
273 @internalsref{SystemStartBracket}.
277 @node Deeper nested staff groups
278 @subsubsection Deeper nested staff groups
280 There are also two inner staff contexts named @code{InnerStaffGroup}
281 and @code{InnerChoirStaffGroup} besides the grouping contexts mentioned
282 in @ref{Grouping staves}. They behave in the same way as their simple
283 counterparts, except that they are contained in another staff grouping
284 context, thus producing one more bracket on top of the existing one.
285 Note that @code{GrandStaff} and @code{PianoStaff} do not have any inner
286 grouping contexts. They can both be inside any other staff context,
287 including inner staff groups, though.
289 Here is an example of an orchestral score using groupings and nesting
290 of these groupings. Note that the instrument names are omited from the
291 source code, see @ref{Instrument names} how to set them.
294 @cindex staff, nested
295 @cindex staves, nested
296 @cindex nesting of staves
301 \new StaffGroup %woodwinds
303 \new Staff @{ c'1 d' @} %flute
304 \new InnerStaffGroup <<
305 \new Staff @{ c' d' @} %sax
306 \new Staff @{ c' d' @} %oboe
307 \new Staff @{ c' d' @} %English horn
309 \new Staff @{ \clef bass c d @} %bassoon
311 \new StaffGroup %the brass group
313 \new Staff @{ c' d' @} %trumpet
314 \new Staff @{ \clef bass c d @} %trombone
315 \new GrandStaff %the horns need a GrandStaff (same instrument)
317 \new Staff @{ c' d' @}
318 \new Staff @{ \clef bass c d @}
321 \new ChoirStaff %for setting vocal music
323 \new Staff @{ c' d' @}
324 \new InnerChoirStaff <<
325 \new Staff @{ c' d' @}
326 \new Staff @{ c' d' @}
328 \new Staff @{ c' d' @}
330 \new PianoStaff %for the piano
332 \new Staff @{ c' d' @}
333 \new Staff @{\clef bass c d @}
338 @c no verbatim so instrument names are only in the music
339 @lilypond[ragged-right,quote]
341 \new StaffGroup %woodwinds
343 \new Staff {\set Staff.instrumentName = "fl" c'1 d' } %flute
344 \new InnerStaffGroup <<
345 \new Staff { \set Staff.instrumentName = "sax" c' d' } %sax 1
346 \new Staff { \set Staff.instrumentName = "ob" c' d' } %sax 2
347 \new Staff { \set Staff.instrumentName = "ca" c' d' }
349 \new Staff {\set Staff.instrumentName = "bs" \clef bass c d } %bassoon
351 \new StaffGroup %the brass group
353 \new Staff {\set Staff.instrumentName = "tr" c' d' } %trumpet
354 \new Staff {\set Staff.instrumentName = "tb" \clef bass c d } %trombone
355 \new GrandStaff %the horns need a GrandStaff (same instrument)
357 \new Staff {\set Staff.instrumentName = "cor1" c' d' }
358 \new Staff {\set Staff.instrumentName = "cor2" \clef bass c d }
361 \new ChoirStaff %for setting vocal music
363 \new Staff {\set Staff.instrumentName = "S" c' d' }
364 \new InnerChoirStaff <<
365 \new Staff {\set Staff.instrumentName = "A1" c' d' }
366 \new Staff {\set Staff.instrumentName = "A2" c' d' }
368 \new Staff {\set Staff.instrumentName = "T" c' d' }
370 \new PianoStaff %for the piano
373 \new Staff {\clef bass c d }
381 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
387 Internals Reference: @internalsref{SystemStartBar},
388 @internalsref{SystemStartBrace}, @internalsref{SystemStartBracket},
389 @internalsref{systemStartDelimiterHierarchy}.
393 @node Modifying single staves
394 @subsection Modifying single staves
403 @subsubsection Staff symbol
405 @cindex adjusting staff symbol
406 @cindex drawing staff symbol
407 @cindex stop staff lines
408 @cindex start staff lines
409 @cindex staff lines, amount of
410 @cindex staff line, thickness of
411 @cindex amount of staff lines
412 @cindex thickness of staff lines
414 The layout object which draws the lines of a staff is called
415 @code{staff symbol}. The staff symbol may be tuned in the number,
416 thickness and distance of lines, using properties. This is
417 demonstrated in the example files
418 @c @lsr{staff,changing-the-number-of-lines-in-a-staff.ly} and
419 @c @lsr{staff,changing-the-staff-size.ly}.
421 In addition, staves may be started and stopped at will. This is
422 done with @code{\startStaff} and @code{\stopStaff}.
424 @lilypond[verbatim,relative=2,fragment]
426 \override Staff.StaffSymbol #'line-count = 2
427 \stopStaff \startStaff
429 \revert Staff.StaffSymbol #'line-count
430 \stopStaff \startStaff
435 @subsubsection Ossia staves
437 @cindex staves, Frenched
439 @cindex Frenched staves
441 In combination with Frenched staves, this may be used to typeset
442 @emph{ossia} sections. An example is shown here
444 @lilypond[verbatim,relative=2,quote]
448 \remove "Time_signature_engraver"
450 \override StaffSymbol #'staff-space = #(magstep -2)
459 bes8[^"ossia" g bes g]
476 @cindex staff lines, setting number of
477 @cindex staff lines, setting thickness of
478 @cindex thickness of staff lines, setting
479 @cindex number of staff lines, setting
483 @c lilypondfile{Making-some-staff-lines-thicker-than-the-others.ly}
488 Music Glossary: @rglos{ossia}, @rglos{staff}, @rglos{Frenched staff}.
490 Snippets: @lsrdir{Staff,Staff-notation}
492 Internals Reference: @internalsref{StaffSymbol},
493 @internalsref{DrumStaff}.
497 @subsubsection Hiding staves
499 @cindex Frenched scores
500 @cindex staves, hiding
501 @cindex staves, empty
503 In orchestral scores, staff lines that only have rests are usually
504 removed; this saves some space. This style is called @q{French
505 Score}. For @code{Lyrics}, @code{ChordNames} and
506 @code{FiguredBass}, this is switched on by default. When
507 the lines of these contexts turn out empty after the line-breaking
508 process, they are removed.
510 For normal staves, a specialized @code{Staff} context is
511 available, which does the same: staves containing nothing (or only
512 multi-measure rests) are removed. The context definition is
513 stored in @code{\RemoveEmptyStaffContext} variable. Observe how
514 the second staff in this example disappears in the second line
516 @lilypond[quote,ragged-right,verbatim]
518 \context { \RemoveEmptyStaffContext }
523 \new Staff { e4 f g a \break c1 }
524 \new Staff { c4 d e f \break R1 }
529 The first system shows all staves in full. If empty staves should
530 be removed from the first system too, set @code{remove-first} to
531 true in @code{VerticalAxisGroup}.
534 \override Score.VerticalAxisGroup #'remove-first = ##t
537 To remove other types of contexts, use
538 @code{\AncientRemoveEmptyStaffContext} or
539 @code{\RemoveEmptyRhythmicStaffContext}.
543 Another application of the @code{\RemoveEmptyStaffContext} is to
544 make ossia sections, i.e., alternative melodies on a separate
545 piece of staff, with help of a Frenched staff. See @ref{Staff
548 You can make the staff lines invisible by removing the
549 @code{Staff_symbol_engraver} from the @code{Staff} context.
552 @lilypond[quote,ragged-right,verbatim]
554 \context Staff \relative c'' { c8 c c16 c c c }
558 \remove Staff_symbol_engraver
566 Notation Reference: @ref{Staff symbol}.
568 Snippets: @lsrdir{Staff,Staff-notation}
570 Internals Reference: @internalsref{ChordNames},
571 @internalsref{FiguredBass}, @internalsref{Lyrics},
572 @internalsref{Staff}, @internalsref{VerticalAxisGroup}.
575 @subsection Writing parts
580 * Quoting other voices::
581 * Formatting cue notes::
584 @node Metronome marks
585 @subsubsection Metronome marks
588 @cindex beats per minute
589 @cindex metronome marking
591 Metronome settings can be entered as follows
594 \tempo @var{duration} = @var{per-minute}
597 In the MIDI output, they are interpreted as a tempo change. In
598 the layout output, a metronome marking is printed
602 @lilypond[quote,ragged-right,verbatim,fragment]
609 To change the tempo in the MIDI output without printing anything,
610 make the metronome marking invisible @example \once \override
611 Score.MetronomeMark #'transparent = ##t @end example
613 To print other metronome markings, use these markup commands
614 @lilypond[quote,ragged-right,verbatim,relative,fragment]
617 \smaller \general-align #Y #DOWN \note #"16." #1
619 \smaller \general-align #Y #DOWN \note #"8" #1
624 For more details, see @ref{Text markup}.
629 Music Glossary: @rglos{metronome}, @rglos{metronomic indication},
630 @rglos{tempo indication}, @rglos{metronome mark}.
632 Notation Reference: @ref{Text markup}.
634 Snippets: @lsrdir{Staff,Staff-notation}.
636 Internals Reference: @internalsref{MetronomeMark}, @ref{MIDI
642 Collisions are not checked. If you have notes above the top line
643 of the staff (or notes with articulations, slurs, text, etc), then
644 the metronome marking may be printed on top of musical symbols.
645 If this occurs, increase the padding of the metronome mark to
646 place it further away from the staff.
649 \override Score.MetronomeMark #'padding = #2.5
652 @c perhaps also an example of how to move it horizontally?
655 @node Instrument names
656 @subsubsection Instrument names
658 @cindex instrument names
659 @cindex instrument names, short
661 In an orchestral score, instrument names are printed at the left
664 This can be achieved by setting @code{Staff}.@code{instrumentName} and
665 @code{Staff}.@code{shortInstrumentName}, or
666 @code{PianoStaff}.@code{instrumentName} and
667 @code{PianoStaff}.@code{shortInstrumentName}. This will print text
668 before the start of the staff. For the first staff,
669 @code{instrumentName} is used. If set, @code{shortInstrumentName} is
670 used for the following staves.
672 @lilypond[quote,verbatim,ragged-right,relative=1,fragment]
673 \set Staff.instrumentName = "Ploink "
674 \set Staff.shortInstrumentName = "Plk "
680 You can also use markup texts to construct more complicated
681 instrument names, for example
683 @lilypond[quote,fragment,verbatim,ragged-right]
684 \set Staff.instrumentName = \markup {
685 \column { "Clarinetti"
686 \line { "in B" \smaller \flat } } }
690 @cindex instrument names, centering
692 As instrument names are centered by default, multi line names
693 are better entered using @code{\center-align}:
695 @lilypond[quote,verbatim,ragged-right]
698 \set Staff.instrumentName = \markup \center-align {
700 \line { "in B" \smaller \flat }
705 \set Staff.instrumentName = "Vibraphone"
712 For longer instrument names, it may be useful to increase the
713 @code{indent} setting in the @code{\layout} block.
715 Short instrument names, printed before the systems following the first
716 one, are also centered by default, in a space which width is given by
717 the @code{short-indent} variable of the @code{\layout} block.
719 To add instrument names to other contexts (such as
720 @code{GrandStaff}, @code{ChoirStaff}, or @code{StaffGroup}), the
721 engraver must be added to that context.
725 \context @{\GrandStaff \consists "Instrument_name_engraver"@}
730 More information about adding and removing engravers can be found
731 in @ref{Modifying context plug-ins}.
733 @cindex instrument names, changing
735 Instrument names may be changed in the middle of a piece,
737 @lilypond[quote,fragment,verbatim,ragged-right]
738 \set Staff.instrumentName = "First"
739 \set Staff.shortInstrumentName = "one"
742 \set Staff.instrumentName = "Second"
743 \set Staff.shortInstrumentName = "two"
751 Notation Reference: @ref{Modifying context plug-ins}.
753 Snippets: @lsrdir{Staff,Staff-notation}
755 Internals Reference: @internalsref{InstrumentName},
756 @internalsref{PianoStaff}, @internalsref{Staff}.
759 @node Quoting other voices
760 @subsubsection Quoting other voices
763 @cindex quoting other voices
767 With quotations, fragments of other parts can be inserted into a
768 part directly. Before a part can be quoted, it must be marked
769 especially as quotable. This is done with the @code{\addQuote}
773 \addQuote @var{name} @var{music}
778 Here, @var{name} is an identifying string. The @var{music} is any
779 kind of music. Here is an example of @code{\addQuote}
782 \addQuote clarinet \relative c' @{
787 This command must be entered at toplevel, i.e., outside any music
788 blocks. Typically, one would use an already defined music event
792 clarinet = \relative c' @{
795 \addQuote clarinet @{ \clarinet @}
799 After calling @code{\addQuote}, the quotation may then be done
800 with @code{\quoteDuring} or @code{\cueDuring},
803 \quoteDuring #@var{name} @var{music}
806 During a part, a piece of music can be quoted with the
807 @code{\quoteDuring} command.
810 \quoteDuring #"clarinet" @{ s2. @}
813 This would cite three quarter notes (the duration of @code{s2.})
814 of the previously added @code{clarinet} voice.
816 More precisely, it takes the current time-step of the part being
817 printed, and extracts the notes at the corresponding point of the
818 @code{\addQuote}d voice. Therefore, the argument to
819 @code{\addQuote} should be the entire part of the voice to be
820 quoted, including any rests at the beginning.
822 It is possible to use another music expression instead of
823 @code{s}, thus creating a polyphonic section, but this may not
824 always give the desired result.
826 Quotations take into account the transposition of both source and
827 target instruments, if they are specified using the
828 @code{\transposition} command.
830 @lilypond[quote,ragged-right,verbatim]
831 \addQuote clarinet \relative c' {
837 e'8 f'8 \quoteDuring #"clarinet" { s2 }
841 The type of events that are present in the quoted music can be
842 trimmed with the @code{quotedEventTypes} property. The default
843 value is @code{(note-event rest-event)}, which means that only
844 notes and rests of the quoted voice end up in the
845 @code{\quoteDuring}. Setting
848 \set Staff.quotedEventTypes =
849 #'(note-event articulation-event dynamic-event)
853 will quote notes (but no rests), together with scripts and
858 Only the contents of the first @code{Voice} occurring in an
859 @code{\addQuote} command will be considered for quotation, so
860 @var{music} can not contain @code{\new} and @code{\context Voice}
861 statements that would switch to a different Voice.
863 Quoting grace notes is broken and can even cause LilyPond to
866 Quoting nested triplets may result in poor notation.
868 In earlier versions of LilyPond (pre 2.11), @code{addQuote} was
869 written entirely in lower-case letters: @code{\addquote}.
873 Notation Reference: @ref{Instrument transpositions}.
875 Snippets: @lsrdir{Staff,Staff-notation}
877 Internals Reference: @internalsref{QuoteMusic}, @internalsref{Voice}.
880 @node Formatting cue notes
881 @subsubsection Formatting cue notes
885 @cindex cue notes, formatting
887 @cindex quoting other voices
888 @cindex cues, formatting
890 The previous section deals with inserting notes from another
891 voice. There is a more advanced music function called
892 @code{\cueDuring}, which makes formatting cue notes easier.
897 \cueDuring #@var{name} #@var{updown} @var{music}
900 This will insert notes from the part @var{name} into a
901 @code{Voice} called @code{cue}. This happens
902 simultaneously with @var{music}, which usually is a rest. When
903 the cue notes start, the staff in effect becomes polyphonic for a
904 moment. The argument @var{updown} determines whether the cue
905 notes should be notated as a first or second voice.
908 @lilypond[verbatim,ragged-right]
911 \override Stem #'length-fraction = #0.8
912 \override Beam #'thickness = #0.384
913 \override Beam #'length-fraction = #0.8
916 \addQuote clarinet \relative {
921 \new Staff \relative <<
923 % setup a context for cue notes.
924 \new Voice = "cue" { \smaller \skip 1*21 }
926 \set Score.skipBars = ##t
930 \cueDuring #"clarinet" #UP {
939 Here are a couple of hints for successful cue notes:
943 Cue notes have smaller font sizes.
946 The cued part is marked with the instrument playing the cue.
949 When the original part takes over again, this should be marked
950 with the name of the original instrument.
953 Any other changes introduced by the cued part should also be
954 undone. For example, if the cued instrument plays in a different
955 clef, the original clef should be stated once again.
959 The macro @code{\transposedCueDuring} is useful to add cues to
960 instruments which use a completely different octave range (for
961 example, having a cue of a piccolo flute within a contra bassoon
964 @lilypond[verbatim,ragged-right,quote]
965 picc = \relative c''' {
971 \addQuote "picc" { \picc }
973 cbsn = \relative c, {
976 \transposedCueDuring #"picc" #UP c,, { R1 } |
981 \context Staff = "picc" \picc
982 \context Staff = "cbsn" \cbsn
988 Snippets: @lsrdir{Staff,Staff-notation}.
990 Internals Reference: @internalsref{Voice}.