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 @c FIXME: Graham will deal with this. -gp
251 To display a bracket even if there is only one staff, see
252 @c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
253 @c {staff,display-bracket-with-only-one-staff-in-a system.ly}
254 @lilypond[verbatim,ragged-right,quote]
257 % Must be one lower than your actual amount off staff lines
258 \override StaffGroup.SystemStartBracket #'collapse-height = #4
266 \override PianoStaff.SystemStartBrace #'collapse-height = #4
275 @cindex mensurstriche layout
276 @cindex renaissance music
277 @cindex transcription of mensural music
278 @cindex mensural music, transcription of
281 @c FIXME: not yet in master
282 @c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
283 @c {mensurstriche-layout.ly}
285 Other groupings may be achieved by changing various properties.
287 @q{Mensurstriche} layout common in Renaissance music, with
288 bar lines running between but not through the staves, can be
289 produced from a @code{StaffGroup} or @code{GrandStaff} context if
290 the bar lines are made transparent in the @code{Staff} itself:
292 @lilypond[verbatim,ragged-right,quote]
293 global = {\override Staff.BarLine #'transparent = ##t
295 %the final bar line is not interupted
296 \once \override Staff.BarLine #'transparent = ##f
300 \new Staff {<< \global { c1 c } >>}
301 \new Staff {<< \global { c c } >>}
308 Music Glossary: @rglos{brace},
311 Snippets: @lsrdir{Staff,Staff-notation}
313 Internals Reference: @internalsref{ChoirStaff},
314 @internalsref{GrandStaff}, @internalsref{StaffGroup},
315 @internalsref{SystemStartBar}, @internalsref{SystemStartBrace},
316 @internalsref{SystemStartBracket}.
320 @node Deeper nested staff groups
321 @subsubsection Deeper nested staff groups
323 There are also two inner staff contexts named @code{InnerStaffGroup}
324 and @code{InnerChoirStaffGroup} besides the grouping contexts mentioned
325 in @ref{Grouping staves}. They behave in the same way as their simple
326 counterparts, except that they are contained in another staff grouping
327 context, thus producing one more bracket on top of the existing one.
328 Note that @code{GrandStaff} and @code{PianoStaff} do not have any inner
329 grouping contexts. They can both be inside any other staff context,
330 including inner staff groups, though.
332 Here is an example of an orchestral score using groupings and nesting
333 of these groupings. Note that the instrument names are omited from the
334 source code, see @ref{Instrument names} how to set them.
337 @cindex staff, nested
338 @cindex staves, nested
339 @cindex nesting of staves
344 \new StaffGroup %woodwinds
346 \new Staff @{ c'1 d' @} %flute
347 \new InnerStaffGroup <<
348 \new Staff @{ c' d' @} %sax
349 \new Staff @{ c' d' @} %oboe
350 \new Staff @{ c' d' @} %English horn
352 \new Staff @{ \clef bass c d @} %bassoon
354 \new StaffGroup %the brass group
356 \new Staff @{ c' d' @} %trumpet
357 \new Staff @{ \clef bass c d @} %trombone
358 \new GrandStaff %the horns need a GrandStaff (same instrument)
360 \new Staff @{ c' d' @}
361 \new Staff @{ \clef bass c d @}
364 \new ChoirStaff %for setting vocal music
366 \new Staff @{ c' d' @}
367 \new InnerChoirStaff <<
368 \new Staff @{ c' d' @}
369 \new Staff @{ c' d' @}
371 \new Staff @{ c' d' @}
373 \new PianoStaff %for the piano
375 \new Staff @{ c' d' @}
376 \new Staff @{\clef bass c d @}
381 @c no verbatim so instrument names are only in the music
382 @lilypond[ragged-right,quote]
384 \new StaffGroup %woodwinds
386 \new Staff {\set Staff.instrumentName = "fl" c'1 d' } %flute
387 \new InnerStaffGroup <<
388 \new Staff { \set Staff.instrumentName = "sax" c' d' } %sax 1
389 \new Staff { \set Staff.instrumentName = "ob" c' d' } %sax 2
390 \new Staff { \set Staff.instrumentName = "ca" c' d' }
392 \new Staff {\set Staff.instrumentName = "bs" \clef bass c d } %bassoon
394 \new StaffGroup %the brass group
396 \new Staff {\set Staff.instrumentName = "tr" c' d' } %trumpet
397 \new Staff {\set Staff.instrumentName = "tb" \clef bass c d } %trombone
398 \new GrandStaff %the horns need a GrandStaff (same instrument)
400 \new Staff {\set Staff.instrumentName = "cor1" c' d' }
401 \new Staff {\set Staff.instrumentName = "cor2" \clef bass c d }
404 \new ChoirStaff %for setting vocal music
406 \new Staff {\set Staff.instrumentName = "S" c' d' }
407 \new InnerChoirStaff <<
408 \new Staff {\set Staff.instrumentName = "A1" c' d' }
409 \new Staff {\set Staff.instrumentName = "A2" c' d' }
411 \new Staff {\set Staff.instrumentName = "T" c' d' }
413 \new PianoStaff %for the piano
416 \new Staff {\clef bass c d }
424 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
430 Internals Reference: @internalsref{SystemStartBar},
431 @internalsref{SystemStartBrace}, @internalsref{SystemStartBracket},
432 @internalsref{systemStartDelimiterHierarchy}.
436 @node Modifying single staves
437 @subsection Modifying single staves
446 @subsubsection Staff symbol
448 @cindex adjusting staff symbol
449 @cindex drawing staff symbol
450 @cindex stop staff lines
451 @cindex start staff lines
452 @cindex staff lines, amount of
453 @cindex staff line, thickness of
454 @cindex amount of staff lines
455 @cindex thickness of staff lines
457 The layout object which draws the lines of a staff is called
458 @code{staff symbol}. The staff symbol may be tuned in the number,
459 thickness and distance of lines, using properties. This is
460 demonstrated in the example files
461 @c @lsr{staff,changing-the-number-of-lines-in-a-staff.ly} and
462 @c @lsr{staff,changing-the-staff-size.ly}.
464 In addition, staves may be started and stopped at will. This is
465 done with @code{\startStaff} and @code{\stopStaff}.
467 @lilypond[verbatim,relative=2,fragment]
469 \override Staff.StaffSymbol #'line-count = 2
470 \stopStaff \startStaff
472 \revert Staff.StaffSymbol #'line-count
473 \stopStaff \startStaff
478 @subsubsection Ossia staves
480 @cindex staves, Frenched
482 @cindex Frenched staves
484 In combination with Frenched staves, this may be used to typeset
485 @emph{ossia} sections. An example is shown here
487 @lilypond[verbatim,relative=2,quote]
491 \remove "Time_signature_engraver"
493 \override StaffSymbol #'staff-space = #(magstep -2)
502 bes8[^"ossia" g bes g]
519 @cindex staff lines, setting number of
520 @cindex staff lines, setting thickness of
521 @cindex thickness of staff lines, setting
522 @cindex number of staff lines, setting
526 @c lilypondfile{Making-some-staff-lines-thicker-than-the-others.ly}
531 Music Glossary: @rglos{ossia}, @rglos{staff}, @rglos{Frenched staff}.
533 Snippets: @lsrdir{Staff,Staff-notation}
535 Internals Reference: @internalsref{StaffSymbol},
536 @internalsref{DrumStaff}.
540 @subsubsection Hiding staves
542 @cindex Frenched scores
543 @cindex staves, hiding
544 @cindex staves, empty
546 In orchestral scores, staff lines that only have rests are usually
547 removed; this saves some space. This style is called @q{French
548 Score}. For @code{Lyrics}, @code{ChordNames} and
549 @code{FiguredBass}, this is switched on by default. When
550 the lines of these contexts turn out empty after the line-breaking
551 process, they are removed.
553 For normal staves, a specialized @code{Staff} context is
554 available, which does the same: staves containing nothing (or only
555 multi-measure rests) are removed. The context definition is
556 stored in @code{\RemoveEmptyStaffContext} variable. Observe how
557 the second staff in this example disappears in the second line
559 @lilypond[quote,ragged-right,verbatim]
561 \context { \RemoveEmptyStaffContext }
566 \new Staff { e4 f g a \break c1 }
567 \new Staff { c4 d e f \break R1 }
572 The first system shows all staves in full. If empty staves should
573 be removed from the first system too, set @code{remove-first} to
574 true in @code{VerticalAxisGroup}.
577 \override Score.VerticalAxisGroup #'remove-first = ##t
580 To remove other types of contexts, use
581 @code{\AncientRemoveEmptyStaffContext} or
582 @code{\RemoveEmptyRhythmicStaffContext}.
586 Another application of the @code{\RemoveEmptyStaffContext} is to
587 make ossia sections, i.e., alternative melodies on a separate
588 piece of staff, with help of a Frenched staff. See @ref{Staff
591 You can make the staff lines invisible by removing the
592 @code{Staff_symbol_engraver} from the @code{Staff} context.
595 @lilypond[quote,ragged-right,verbatim]
597 \context Staff \relative c'' { c8 c c16 c c c }
601 \remove Staff_symbol_engraver
609 Notation Reference: @ref{Staff symbol}.
611 Snippets: @lsrdir{Staff,Staff-notation}
613 Internals Reference: @internalsref{ChordNames},
614 @internalsref{FiguredBass}, @internalsref{Lyrics},
615 @internalsref{Staff}, @internalsref{VerticalAxisGroup}.
618 @subsection Writing parts
623 * Quoting other voices::
624 * Formatting cue notes::
627 @node Metronome marks
628 @subsubsection Metronome marks
631 @cindex beats per minute
632 @cindex metronome marking
634 Metronome settings can be entered as follows
637 \tempo @var{duration} = @var{per-minute}
640 In the MIDI output, they are interpreted as a tempo change. In
641 the layout output, a metronome marking is printed
645 @lilypond[quote,ragged-right,verbatim,fragment]
652 To change the tempo in the MIDI output without printing anything,
653 make the metronome marking invisible @example \once \override
654 Score.MetronomeMark #'transparent = ##t @end example
656 To print other metronome markings, use these markup commands
657 @lilypond[quote,ragged-right,verbatim,relative,fragment]
660 \smaller \general-align #Y #DOWN \note #"16." #1
662 \smaller \general-align #Y #DOWN \note #"8" #1
667 For more details, see @ref{Text markup}.
672 Music Glossary: @rglos{metronome}, @rglos{metronomic indication},
673 @rglos{tempo indication}, @rglos{metronome mark}.
675 Notation Reference: @ref{Text markup}.
677 Snippets: @lsrdir{Staff,Staff-notation}.
679 Internals Reference: @internalsref{MetronomeMark}, @ref{MIDI
685 Collisions are not checked. If you have notes above the top line
686 of the staff (or notes with articulations, slurs, text, etc), then
687 the metronome marking may be printed on top of musical symbols.
688 If this occurs, increase the padding of the metronome mark to
689 place it further away from the staff.
692 \override Score.MetronomeMark #'padding = #2.5
695 @c perhaps also an example of how to move it horizontally?
698 @node Instrument names
699 @subsubsection Instrument names
701 @cindex instrument names
702 @cindex instrument names, short
704 In an orchestral score, instrument names are printed at the left
707 This can be achieved by setting @code{Staff}.@code{instrumentName} and
708 @code{Staff}.@code{shortInstrumentName}, or
709 @code{PianoStaff}.@code{instrumentName} and
710 @code{PianoStaff}.@code{shortInstrumentName}. This will print text
711 before the start of the staff. For the first staff,
712 @code{instrumentName} is used. If set, @code{shortInstrumentName} is
713 used for the following staves.
715 @lilypond[quote,verbatim,ragged-right,relative=1,fragment]
716 \set Staff.instrumentName = "Ploink "
717 \set Staff.shortInstrumentName = "Plk "
723 You can also use markup texts to construct more complicated
724 instrument names, for example
726 @lilypond[quote,fragment,verbatim,ragged-right]
727 \set Staff.instrumentName = \markup {
728 \column { "Clarinetti"
729 \line { "in B" \smaller \flat } } }
733 @cindex instrument names, centering
735 As instrument names are centered by default, multi line names
736 are better entered using @code{\center-align}:
738 @lilypond[quote,verbatim,ragged-right]
741 \set Staff.instrumentName = \markup \center-align {
743 \line { "in B" \smaller \flat }
748 \set Staff.instrumentName = "Vibraphone"
755 For longer instrument names, it may be useful to increase the
756 @code{indent} setting in the @code{\layout} block.
758 Short instrument names, printed before the systems following the first
759 one, are also centered by default, in a space which width is given by
760 the @code{short-indent} variable of the @code{\layout} block.
762 To add instrument names to other contexts (such as
763 @code{GrandStaff}, @code{ChoirStaff}, or @code{StaffGroup}), the
764 engraver must be added to that context.
768 \context @{\GrandStaff \consists "Instrument_name_engraver"@}
773 More information about adding and removing engravers can be found
774 in @ref{Modifying context plug-ins}.
776 @cindex instrument names, changing
778 Instrument names may be changed in the middle of a piece,
780 @lilypond[quote,fragment,verbatim,ragged-right]
781 \set Staff.instrumentName = "First"
782 \set Staff.shortInstrumentName = "one"
785 \set Staff.instrumentName = "Second"
786 \set Staff.shortInstrumentName = "two"
794 Notation Reference: @ref{Modifying context plug-ins}.
796 Snippets: @lsrdir{Staff,Staff-notation}
798 Internals Reference: @internalsref{InstrumentName},
799 @internalsref{PianoStaff}, @internalsref{Staff}.
802 @node Quoting other voices
803 @subsubsection Quoting other voices
806 @cindex quoting other voices
810 With quotations, fragments of other parts can be inserted into a
811 part directly. Before a part can be quoted, it must be marked
812 especially as quotable. This is done with the @code{\addQuote}
816 \addQuote @var{name} @var{music}
821 Here, @var{name} is an identifying string. The @var{music} is any
822 kind of music. Here is an example of @code{\addQuote}
825 \addQuote clarinet \relative c' @{
830 This command must be entered at toplevel, i.e., outside any music
831 blocks. Typically, one would use an already defined music event
835 clarinet = \relative c' @{
838 \addQuote clarinet @{ \clarinet @}
842 After calling @code{\addQuote}, the quotation may then be done
843 with @code{\quoteDuring} or @code{\cueDuring},
846 \quoteDuring #@var{name} @var{music}
849 During a part, a piece of music can be quoted with the
850 @code{\quoteDuring} command.
853 \quoteDuring #"clarinet" @{ s2. @}
856 This would cite three quarter notes (the duration of @code{s2.})
857 of the previously added @code{clarinet} voice.
859 More precisely, it takes the current time-step of the part being
860 printed, and extracts the notes at the corresponding point of the
861 @code{\addQuote}d voice. Therefore, the argument to
862 @code{\addQuote} should be the entire part of the voice to be
863 quoted, including any rests at the beginning.
865 It is possible to use another music expression instead of
866 @code{s}, thus creating a polyphonic section, but this may not
867 always give the desired result.
869 Quotations take into account the transposition of both source and
870 target instruments, if they are specified using the
871 @code{\transposition} command.
873 @lilypond[quote,ragged-right,verbatim]
874 \addQuote clarinet \relative c' {
880 e'8 f'8 \quoteDuring #"clarinet" { s2 }
884 The type of events that are present in the quoted music can be
885 trimmed with the @code{quotedEventTypes} property. The default
886 value is @code{(note-event rest-event)}, which means that only
887 notes and rests of the quoted voice end up in the
888 @code{\quoteDuring}. Setting
891 \set Staff.quotedEventTypes =
892 #'(note-event articulation-event dynamic-event)
896 will quote notes (but no rests), together with scripts and
901 Only the contents of the first @code{Voice} occurring in an
902 @code{\addQuote} command will be considered for quotation, so
903 @var{music} can not contain @code{\new} and @code{\context Voice}
904 statements that would switch to a different Voice.
906 Quoting grace notes is broken and can even cause LilyPond to
909 Quoting nested triplets may result in poor notation.
911 In earlier versions of LilyPond (pre 2.11), @code{addQuote} was
912 written entirely in lower-case letters: @code{\addquote}.
916 Notation Reference: @ref{Instrument transpositions}.
918 Snippets: @lsrdir{Staff,Staff-notation}
920 Internals Reference: @internalsref{QuoteMusic}, @internalsref{Voice}.
923 @node Formatting cue notes
924 @subsubsection Formatting cue notes
928 @cindex cue notes, formatting
930 @cindex quoting other voices
931 @cindex cues, formatting
933 The previous section deals with inserting notes from another
934 voice. There is a more advanced music function called
935 @code{\cueDuring}, which makes formatting cue notes easier.
940 \cueDuring #@var{name} #@var{updown} @var{music}
943 This will insert notes from the part @var{name} into a
944 @code{Voice} called @code{cue}. This happens
945 simultaneously with @var{music}, which usually is a rest. When
946 the cue notes start, the staff in effect becomes polyphonic for a
947 moment. The argument @var{updown} determines whether the cue
948 notes should be notated as a first or second voice.
951 @lilypond[verbatim,ragged-right]
954 \override Stem #'length-fraction = #0.8
955 \override Beam #'thickness = #0.384
956 \override Beam #'length-fraction = #0.8
959 \addQuote clarinet \relative {
964 \new Staff \relative <<
966 % setup a context for cue notes.
967 \new Voice = "cue" { \smaller \skip 1*21 }
969 \set Score.skipBars = ##t
973 \cueDuring #"clarinet" #UP {
982 Here are a couple of hints for successful cue notes:
986 Cue notes have smaller font sizes.
989 The cued part is marked with the instrument playing the cue.
992 When the original part takes over again, this should be marked
993 with the name of the original instrument.
996 Any other changes introduced by the cued part should also be
997 undone. For example, if the cued instrument plays in a different
998 clef, the original clef should be stated once again.
1002 The macro @code{\transposedCueDuring} is useful to add cues to
1003 instruments which use a completely different octave range (for
1004 example, having a cue of a piccolo flute within a contra bassoon
1007 @lilypond[verbatim,ragged-right,quote]
1008 picc = \relative c''' {
1014 \addQuote "picc" { \picc }
1016 cbsn = \relative c, {
1019 \transposedCueDuring #"picc" #UP c,, { R1 } |
1024 \context Staff = "picc" \picc
1025 \context Staff = "cbsn" \cbsn
1031 Snippets: @lsrdir{Staff,Staff-notation}.
1033 Internals Reference: @internalsref{Voice}.