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 transcription 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 tablature 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 behavior of the bar lines.
158 Each staff group context sets the property
159 @code{systemStartDelimiter} to one of the values
160 @code{SystemStartBar}, @code{SystemStartBrace},
161 and @code{SystemStartBracket}. A fourth delimiter,
162 @code{systemStartSquare}, is also available, but must be
163 instantiated manually. The usage of this last delimiter is shown further
164 down in the snippet section.
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 @c FIXME: not yet in master
250 @c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
251 @c {use-square-bracket-at-the-start-of-a-staff-group.ly}
253 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
254 {display-bracket-with-only-one-staff-in-a-system.ly}
256 @cindex mensurstriche layout
257 @cindex renaissance music
258 @cindex transcription of mensural music
259 @cindex mensural music, transcription of
261 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
262 {mensurstriche-layout-bar-lines-between-the-staves.ly}
267 Music Glossary: @rglos{brace},
270 Snippets: @lsrdir{Staff,Staff-notation}
272 Internals Reference: @internalsref{ChoirStaff},
273 @internalsref{GrandStaff}, @internalsref{StaffGroup},
274 @internalsref{SystemStartBar}, @internalsref{SystemStartBrace},
275 @internalsref{SystemStartBracket}, and @internalsref{systemStartSquare}.
278 @node Deeper nested staff groups
279 @subsubsection Deeper nested staff groups
281 There are also two inner staff contexts named @code{InnerStaffGroup}
282 and @code{InnerChoirStaffGroup} besides the grouping contexts mentioned
283 in @ref{Grouping staves}. They behave in the same way as their simple
284 counterparts, except that they are contained in another staff grouping
285 context, thus producing one more bracket on top of the existing one.
286 Note that @code{GrandStaff} and @code{PianoStaff} do not have any inner
287 grouping contexts. They can both be inside any other staff context,
288 including inner staff groups, though.
290 Here is an example of an orchestral score using groupings and nesting
291 of these groupings. Note that the instrument names are omitted from the
292 source code, see @ref{Instrument names} how to set them.
294 @cindex staff, nested
295 @cindex staves, nested
296 @cindex nesting of staves
297 @cindex system start delimiters, nested
298 @cindex nested staff brackets
299 @cindex brackets, nesting of
300 @cindex braces, nesting of
301 @cindex inner staff group
302 @cindex inner choir staff group
307 \new StaffGroup %woodwinds
309 \new Staff @{ c'1 d' @} %flute
310 \new InnerStaffGroup <<
311 \new Staff @{ c' d' @} %sax
312 \new Staff @{ c' d' @} %oboe
313 \new Staff @{ c' d' @} %English horn
315 \new Staff @{ \clef bass c d @} %bassoon
317 \new StaffGroup %the brass group
319 \new Staff @{ c' d' @} %trumpet
320 \new Staff @{ \clef bass c d @} %trombone
321 \new GrandStaff %the horns need a GrandStaff (same instrument)
323 \new Staff @{ c' d' @}
324 \new Staff @{ \clef bass c d @}
327 \new ChoirStaff %for setting vocal music
329 \new Staff @{ c' d' @}
330 \new InnerChoirStaff <<
331 \new Staff @{ c' d' @}
332 \new Staff @{ c' d' @}
334 \new Staff @{ c' d' @}
336 \new PianoStaff %for the piano
338 \new Staff @{ c' d' @}
339 \new Staff @{\clef bass c d @}
344 @c no verbatim so instrument names are only in the music
345 @lilypond[ragged-right,quote]
347 \new StaffGroup %woodwinds
349 \new Staff {\set Staff.instrumentName = "fl" c'1 d' } %flute
350 \new InnerStaffGroup <<
351 \new Staff { \set Staff.instrumentName = "sax" c' d' } %sax 1
352 \new Staff { \set Staff.instrumentName = "ob" c' d' } %sax 2
353 \new Staff { \set Staff.instrumentName = "ca" c' d' }
355 \new Staff {\set Staff.instrumentName = "bs" \clef bass c d } %bassoon
357 \new StaffGroup %the brass group
359 \new Staff {\set Staff.instrumentName = "tr" c' d' } %trumpet
360 \new Staff {\set Staff.instrumentName = "tb" \clef bass c d } %trombone
361 \new GrandStaff %the horns need a GrandStaff (same instrument)
363 \new Staff {\set Staff.instrumentName = "cor1" c' d' }
364 \new Staff {\set Staff.instrumentName = "cor2" \clef bass c d }
367 \new ChoirStaff %for setting vocal music
369 \new Staff {\set Staff.instrumentName = "S" c' d' }
370 \new InnerChoirStaff <<
371 \new Staff {\set Staff.instrumentName = "A1" c' d' }
372 \new Staff {\set Staff.instrumentName = "A2" c' d' }
374 \new Staff {\set Staff.instrumentName = "T" c' d' }
376 \new PianoStaff %for the piano
379 \new Staff {\clef bass c d }
387 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
393 Internals Reference: @internalsref{SystemStartBar},
394 @internalsref{SystemStartBrace}, @internalsref{SystemStartBracket},
395 @internalsref{systemStartDelimiterHierarchy}.
399 @node Modifying single staves
400 @subsection Modifying single staves
409 @subsubsection Staff symbol
411 @cindex adjusting staff symbol
412 @cindex drawing staff symbol
413 @cindex stop staff lines
414 @cindex start staff lines
415 @cindex staff lines, amount of
416 @cindex staff line, thickness of
417 @cindex amount of staff lines
418 @cindex thickness of staff lines
420 The layout object which draws the lines of a staff is called
421 @code{staff symbol}. The staff symbol may be tuned in the number,
422 thickness and distance of lines, using properties. This is
423 demonstrated in the example files
424 @c @lsr{staff,changing-the-number-of-lines-in-a-staff.ly} and
425 @c @lsr{staff,changing-the-staff-size.ly}.
427 In addition, staves may be started and stopped at will. This is
428 done with @code{\startStaff} and @code{\stopStaff}.
430 @lilypond[verbatim,relative=2,fragment]
432 \override Staff.StaffSymbol #'line-count = 2
433 \stopStaff \startStaff
435 \revert Staff.StaffSymbol #'line-count
436 \stopStaff \startStaff
441 @subsubsection Ossia staves
443 @cindex staves, Frenched
445 @cindex Frenched staves
447 In combination with Frenched staves, this may be used to typeset
448 @emph{ossia} sections. An example is shown here
450 @lilypond[verbatim,relative=2,quote]
454 \remove "Time_signature_engraver"
456 \override StaffSymbol #'staff-space = #(magstep -2)
465 bes8[^"ossia" g bes g]
482 @cindex staff lines, setting number of
483 @cindex staff lines, setting thickness of
484 @cindex thickness of staff lines, setting
485 @cindex number of staff lines, setting
489 @c lilypondfile{Making-some-staff-lines-thicker-than-the-others.ly}
494 Music Glossary: @rglos{ossia}, @rglos{staff}, @rglos{Frenched staff}.
496 Snippets: @lsrdir{Staff,Staff-notation}
498 Internals Reference: @internalsref{StaffSymbol},
499 @internalsref{DrumStaff}.
503 @subsubsection Hiding staves
505 @cindex Frenched scores
506 @cindex staves, hiding
507 @cindex staves, empty
509 In orchestral scores, staff lines that only have rests are usually
510 removed; this saves some space. This style is called @q{French
511 Score}. For @code{Lyrics}, @code{ChordNames} and
512 @code{FiguredBass}, this is switched on by default. When
513 the lines of these contexts turn out empty after the line-breaking
514 process, they are removed.
516 For normal staves, a specialized @code{Staff} context is
517 available, which does the same: staves containing nothing (or only
518 multi-measure rests) are removed. The context definition is
519 stored in @code{\RemoveEmptyStaffContext} variable. Observe how
520 the second staff in this example disappears in the second line
522 @lilypond[quote,ragged-right,verbatim]
524 \context { \RemoveEmptyStaffContext }
529 \new Staff { e4 f g a \break c1 }
530 \new Staff { c4 d e f \break R1 }
535 The first system shows all staves in full. If empty staves should
536 be removed from the first system too, set @code{remove-first} to
537 true in @code{VerticalAxisGroup}.
540 \override Score.VerticalAxisGroup #'remove-first = ##t
543 To remove other types of contexts, use
544 @code{\AncientRemoveEmptyStaffContext} or
545 @code{\RemoveEmptyRhythmicStaffContext}.
549 Another application of the @code{\RemoveEmptyStaffContext} is to
550 make ossia sections, i.e., alternative melodies on a separate
551 piece of staff, with help of a Frenched staff. See @ref{Staff
554 You can make the staff lines invisible by removing the
555 @code{Staff_symbol_engraver} from the @code{Staff} context.
558 @lilypond[quote,ragged-right,verbatim]
560 \context Staff \relative c'' { c8 c c16 c c c }
564 \remove Staff_symbol_engraver
572 Notation Reference: @ref{Staff symbol}.
574 Snippets: @lsrdir{Staff,Staff-notation}
576 Internals Reference: @internalsref{ChordNames},
577 @internalsref{FiguredBass}, @internalsref{Lyrics},
578 @internalsref{Staff}, @internalsref{VerticalAxisGroup}.
581 @subsection Writing parts
586 * Quoting other voices::
587 * Formatting cue notes::
590 @node Metronome marks
591 @subsubsection Metronome marks
594 @cindex beats per minute
595 @cindex metronome marking
597 Metronome settings can be entered as follows
600 \tempo @var{duration} = @var{per-minute}
603 In the MIDI output, they are interpreted as a tempo change. In
604 the layout output, a metronome marking is printed
608 @lilypond[quote,ragged-right,verbatim,fragment]
615 To change the tempo in the MIDI output without printing anything,
616 make the metronome marking invisible @example \once \override
617 Score.MetronomeMark #'transparent = ##t @end example
619 To print other metronome markings, use these markup commands
620 @lilypond[quote,ragged-right,verbatim,relative,fragment]
623 \smaller \general-align #Y #DOWN \note #"16." #1
625 \smaller \general-align #Y #DOWN \note #"8" #1
630 For more details, see @ref{Text markup}.
635 Music Glossary: @rglos{metronome}, @rglos{metronomic indication},
636 @rglos{tempo indication}, @rglos{metronome mark}.
638 Notation Reference: @ref{Text markup}.
640 Snippets: @lsrdir{Staff,Staff-notation}.
642 Internals Reference: @internalsref{MetronomeMark}, @ref{MIDI
648 Collisions are not checked. If you have notes above the top line
649 of the staff (or notes with articulations, slurs, text, etc), then
650 the metronome marking may be printed on top of musical symbols.
651 If this occurs, increase the padding of the metronome mark to
652 place it further away from the staff.
655 \override Score.MetronomeMark #'padding = #2.5
658 @c perhaps also an example of how to move it horizontally?
661 @node Instrument names
662 @subsubsection Instrument names
664 @cindex instrument names
665 @cindex instrument names, short
667 In an orchestral score, instrument names are printed at the left
670 This can be achieved by setting @code{Staff}.@code{instrumentName} and
671 @code{Staff}.@code{shortInstrumentName}, or
672 @code{PianoStaff}.@code{instrumentName} and
673 @code{PianoStaff}.@code{shortInstrumentName}. This will print text
674 before the start of the staff. For the first staff,
675 @code{instrumentName} is used. If set, @code{shortInstrumentName} is
676 used for the following staves.
678 @lilypond[quote,verbatim,ragged-right,relative=1,fragment]
679 \set Staff.instrumentName = "Ploink "
680 \set Staff.shortInstrumentName = "Plk "
686 You can also use markup texts to construct more complicated
687 instrument names, for example
689 @lilypond[quote,fragment,verbatim,ragged-right]
690 \set Staff.instrumentName = \markup {
691 \column { "Clarinetti"
692 \line { "in B" \smaller \flat } } }
696 @cindex instrument names, centering
698 As instrument names are centered by default, multi line names
699 are better entered using @code{\center-align}:
701 @lilypond[quote,verbatim,ragged-right]
704 \set Staff.instrumentName = \markup \center-align {
706 \line { "in B" \smaller \flat }
711 \set Staff.instrumentName = "Vibraphone"
718 For longer instrument names, it may be useful to increase the
719 @code{indent} setting in the @code{\layout} block.
721 Short instrument names, printed before the systems following the first
722 one, are also centered by default, in a space which width is given by
723 the @code{short-indent} variable of the @code{\layout} block.
725 To add instrument names to other contexts (such as
726 @code{GrandStaff}, @code{ChoirStaff}, or @code{StaffGroup}), the
727 engraver must be added to that context.
731 \context @{\GrandStaff \consists "Instrument_name_engraver"@}
736 More information about adding and removing engravers can be found
737 in @ref{Modifying context plug-ins}.
739 @cindex instrument names, changing
741 Instrument names may be changed in the middle of a piece,
743 @lilypond[quote,fragment,verbatim,ragged-right]
744 \set Staff.instrumentName = "First"
745 \set Staff.shortInstrumentName = "one"
748 \set Staff.instrumentName = "Second"
749 \set Staff.shortInstrumentName = "two"
757 Notation Reference: @ref{Modifying context plug-ins}.
759 Snippets: @lsrdir{Staff,Staff-notation}
761 Internals Reference: @internalsref{InstrumentName},
762 @internalsref{PianoStaff}, @internalsref{Staff}.
765 @node Quoting other voices
766 @subsubsection Quoting other voices
769 @cindex quoting other voices
773 With quotations, fragments of other parts can be inserted into a
774 part directly. Before a part can be quoted, it must be marked
775 especially as quotable. This is done with the @code{\addQuote}
779 \addQuote @var{name} @var{music}
784 Here, @var{name} is an identifying string. The @var{music} is any
785 kind of music. Here is an example of @code{\addQuote}
788 \addQuote clarinet \relative c' @{
793 This command must be entered at toplevel, i.e., outside any music
794 blocks. Typically, one would use an already defined music event
798 clarinet = \relative c' @{
801 \addQuote clarinet @{ \clarinet @}
805 After calling @code{\addQuote}, the quotation may then be done
806 with @code{\quoteDuring} or @code{\cueDuring},
809 \quoteDuring #@var{name} @var{music}
812 During a part, a piece of music can be quoted with the
813 @code{\quoteDuring} command.
816 \quoteDuring #"clarinet" @{ s2. @}
819 This would cite three quarter notes (the duration of @code{s2.})
820 of the previously added @code{clarinet} voice.
822 More precisely, it takes the current time-step of the part being
823 printed, and extracts the notes at the corresponding point of the
824 @code{\addQuote}d voice. Therefore, the argument to
825 @code{\addQuote} should be the entire part of the voice to be
826 quoted, including any rests at the beginning.
828 It is possible to use another music expression instead of
829 @code{s}, thus creating a polyphonic section, but this may not
830 always give the desired result.
832 Quotations take into account the transposition of both source and
833 target instruments, if they are specified using the
834 @code{\transposition} command.
836 @lilypond[quote,ragged-right,verbatim]
837 \addQuote clarinet \relative c' {
843 e'8 f'8 \quoteDuring #"clarinet" { s2 }
847 The type of events that are present in the quoted music can be
848 trimmed with the @code{quotedEventTypes} property. The default
849 value is @code{(note-event rest-event)}, which means that only
850 notes and rests of the quoted voice end up in the
851 @code{\quoteDuring}. Setting
854 \set Staff.quotedEventTypes =
855 #'(note-event articulation-event dynamic-event)
859 will quote notes (but no rests), together with scripts and
864 Only the contents of the first @code{Voice} occurring in an
865 @code{\addQuote} command will be considered for quotation, so
866 @var{music} can not contain @code{\new} and @code{\context Voice}
867 statements that would switch to a different Voice.
869 Quoting grace notes is broken and can even cause LilyPond to
872 Quoting nested triplets may result in poor notation.
874 In earlier versions of LilyPond (pre 2.11), @code{addQuote} was
875 written entirely in lower-case letters: @code{\addquote}.
879 Notation Reference: @ref{Instrument transpositions}.
881 Snippets: @lsrdir{Staff,Staff-notation}
883 Internals Reference: @internalsref{QuoteMusic}, @internalsref{Voice}.
886 @node Formatting cue notes
887 @subsubsection Formatting cue notes
891 @cindex cue notes, formatting
893 @cindex quoting other voices
894 @cindex cues, formatting
896 The previous section deals with inserting notes from another
897 voice. There is a more advanced music function called
898 @code{\cueDuring}, which makes formatting cue notes easier.
903 \cueDuring #@var{name} #@var{updown} @var{music}
906 This will insert notes from the part @var{name} into a
907 @code{Voice} called @code{cue}. This happens
908 simultaneously with @var{music}, which usually is a rest. When
909 the cue notes start, the staff in effect becomes polyphonic for a
910 moment. The argument @var{updown} determines whether the cue
911 notes should be notated as a first or second voice.
914 @lilypond[verbatim,ragged-right]
917 \override Stem #'length-fraction = #0.8
918 \override Beam #'thickness = #0.384
919 \override Beam #'length-fraction = #0.8
922 \addQuote clarinet \relative {
927 \new Staff \relative <<
929 % setup a context for cue notes.
930 \new Voice = "cue" { \smaller \skip 1*21 }
932 \set Score.skipBars = ##t
936 \cueDuring #"clarinet" #UP {
945 Here are a couple of hints for successful cue notes:
949 Cue notes have smaller font sizes.
952 The cued part is marked with the instrument playing the cue.
955 When the original part takes over again, this should be marked
956 with the name of the original instrument.
959 Any other changes introduced by the cued part should also be
960 undone. For example, if the cued instrument plays in a different
961 clef, the original clef should be stated once again.
965 The macro @code{\transposedCueDuring} is useful to add cues to
966 instruments which use a completely different octave range (for
967 example, having a cue of a piccolo flute within a contra bassoon
970 @lilypond[verbatim,ragged-right,quote]
971 picc = \relative c''' {
977 \addQuote "picc" { \picc }
979 cbsn = \relative c, {
982 \transposedCueDuring #"picc" #UP c,, { R1 } |
987 \context Staff = "picc" \picc
988 \context Staff = "cbsn" \cbsn
994 Snippets: @lsrdir{Staff,Staff-notation}.
996 Internals Reference: @internalsref{Voice}.