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.
12 @section Staff notation
14 @lilypondfile[quote]{staff-headword.ly}
16 This section explains how to influence the staff appearance, print
17 scores with more than one staff, and how to apply specific
18 performance marks to single staves.
22 * Modifying single staves::
27 @node Displaying staves
28 @subsection Displaying staves
30 This section shows the different possibilities of creating and
31 grouping staves, which are marked at the beginning of each line
32 with either a bracket or a brace.
35 * Instantiating new staves::
37 * Deeper nested staff groups::
40 @node Instantiating new staves
41 @unnumberedsubsubsec Instantiating new staves
44 @cindex staff initiation
45 @cindex staff instantiation
49 @cindex percussion staff
50 @cindex Gregorian transcription staff
51 @cindex rhythmic staff
55 @notation{Staves} (singular: @notation{staff}) are created with
56 the @code{\new} or @code{\context} commands. For details, see
57 @ref{Creating contexts}.
59 The basic staff context is @code{Staff}:
61 @lilypond[verbatim,quote,relative=2]
62 \new Staff { c4 d e f }
65 @code{DrumStaff} creates a five-line staff set up for a
66 typical drum set. It uses different names for each instrument.
67 The instrument names are set using the @code{\drummode} command.
68 For details, see @ref{Percussion staves}.
70 @lilypond[verbatim,quote]
72 \drummode { cymc hh ss tomh }
76 @c FIXME: remove when mentioned in NR 2.8
77 @code{GregorianTranscriptionStaff} creates a staff to notate
78 modern Gregorian chant. It does not show bar lines.
80 @lilypond[verbatim,quote,relative=2]
81 \new GregorianTranscriptionStaff { c4 d e f }
84 @code{RhythmicStaff} creates a single-line staff that only
85 displays the rhythmic values of the input. Real durations are
86 preserved. For details, see @ref{Showing melody rhythms}.
88 @lilypond[verbatim,quote,relative=2]
89 \new RhythmicStaff { c4 d e f }
92 @code{TabStaff} creates a tablature with six strings in standard
93 guitar tuning. For details, see @ref{Default tablatures}.
95 @lilypond[verbatim,quote,relative=2]
96 \new TabStaff { c4 d e f }
99 There are two staff contexts specific for the notation of ancient
100 music: @code{MensuralStaff} and @code{VaticanaStaff}. They are
101 described in @ref{Pre-defined contexts}.
103 Staves can be started or stopped at any point in the score. The
104 commands @code{\startStaff} and @code{\stopStaff} are used for
105 this purpose. For details, see @ref{Staff symbol}.
115 @ref{Creating contexts},
116 @ref{Percussion staves},
117 @ref{Default tablatures},
118 @ref{Gregorian chant contexts},
119 @ref{Mensural contexts},
121 @ref{Pre-defined contexts},
122 @ref{Showing melody rhythms}.
125 @rlsr{Staff notation}.
129 @rinternals{DrumStaff},
130 @rinternals{GregorianTranscriptionStaff},
131 @rinternals{RhythmicStaff},
132 @rinternals{TabStaff},
133 @rinternals{MensuralStaff},
134 @rinternals{VaticanaStaff},
135 @rinternals{StaffSymbol}.
138 @node Grouping staves
139 @unnumberedsubsubsec Grouping staves
141 @cindex start of system
142 @cindex staff, multiple
143 @cindex staves, multiple
144 @cindex system start delimiters
145 @cindex bracket, vertical
146 @cindex brace, vertical
155 Various contexts exist to group single staves together in order to
156 form multi-stave systems. Each grouping context sets the style of
157 the system start delimiter and the behavior of bar lines.
159 If no context is specified, the default properties will be used:
160 the group is started with a vertical line, and the bar lines are
163 @lilypond[verbatim,quote,relative=2]
170 In the @code{StaffGroup} context, the group is started with a
171 bracket and bar lines are drawn through all the staves.
173 @lilypond[verbatim,quote,relative=2]
180 In a @code{ChoirStaff}, the group starts with a bracket, but bar
181 lines are not connected.
183 @lilypond[verbatim,quote,relative=2]
190 In a @code{GrandStaff}, the group begins with a brace, and bar
191 lines are connected between the staves.
193 @lilypond[verbatim,quote,relative=2]
200 The @code{PianoStaff} is almost identical to a @code{GrandStaff},
201 except that it supports printing the instrument name directly.
202 For details, see @ref{Instrument names}.
204 @lilypond[verbatim,quote,relative=2]
206 \set PianoStaff.instrumentName = "Piano"
212 Each staff group context sets the property
213 @code{systemStartDelimiter} to one of the following values:
214 @code{SystemStartBar}, @code{SystemStartBrace}, or
215 @code{SystemStartBracket}. A fourth delimiter,
216 @code{SystemStartSquare}, is also available, but it must be
217 explicitly specified.
222 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
223 {use-square-bracket-at-the-start-of-a-staff-group.ly}
225 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
226 {display-bracket-with-only-one-staff-in-a-system.ly}
228 @cindex mensurstriche layout
229 @cindex renaissance music
230 @cindex transcription of mensural music
231 @cindex mensural music, transcription of
233 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
234 {mensurstriche-layout-bar-lines-between-the-staves.ly}
235 @c FIXME: move to NR 2.8.x when sectioning is ready
246 @ref{Instrument names}.
249 @rlsr{Staff notation}.
253 @rinternals{ChoirStaff},
254 @rinternals{GrandStaff},
255 @rinternals{PianoStaff},
256 @rinternals{StaffGroup},
257 @rinternals{SystemStartBar},
258 @rinternals{SystemStartBrace},
259 @rinternals{SystemStartBracket},
260 @rinternals{SystemStartSquare}.
263 @node Deeper nested staff groups
264 @unnumberedsubsubsec Deeper nested staff groups
266 @cindex staff, nested
267 @cindex staves, nested
268 @cindex nesting of staves
269 @cindex system start delimiters, nested
270 @cindex nested staff brackets
271 @cindex brackets, nesting of
272 @cindex braces, nesting of
273 @cindex inner staff group
274 @cindex inner choir staff group
276 Two additional staff-group contexts are available that can be
277 nested within a @code{StaffGroup} or @code{ChoirStaff} context:
278 @code{InnerStaffGroup} and @code{InnerChoirStaff}. These contexts
279 create an additional bracket next to the original bracket of their
282 An @code{InnerStaffGroup} is treated similarly to a
283 @code{StaffGroup}; bar lines are connected between each stave
286 @lilypond[verbatim,quote,relative=2]
289 \new InnerStaffGroup <<
296 Bar lines are @emph{not} connected between staves of an
297 @code{InnerChoirStaff}, just like a @code{ChoirStaff}:
299 @lilypond[verbatim,quote,relative=2]
302 \new InnerChoirStaff <<
313 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
320 @rlsr{Staff notation}.
323 @ref{Grouping staves},
324 @ref{Instrument names}.
327 @rinternals{InnerStaffGroup},
328 @rinternals{StaffGroup},
329 @rinternals{InnerChoirStaff},
330 @rinternals{ChoirStaff},
331 @rinternals{SystemStartBar},
332 @rinternals{SystemStartBrace},
333 @rinternals{SystemStartBracket}.
336 @node Modifying single staves
337 @subsection Modifying single staves
339 This section explains how to change specific attributes of one
340 staff: for example, modifying the number of staff lines or the
341 staff size. Methods to start and stop staves and set ossia
342 sections are also described.
352 @unnumberedsubsubsec Staff symbol
354 @cindex adjusting staff symbol
355 @cindex drawing staff symbol
356 @cindex staff symbol, setting of
357 @cindex stop staff lines
358 @cindex start staff lines
359 @cindex staff lines, amount of
360 @cindex staff lines, number of
361 @cindex staff line, thickness of
362 @cindex amount of staff lines
363 @cindex thickness of staff lines
364 @cindex ledger lines, setting
365 @cindex setting of ledger lines
366 @cindex spacing of ledger lines
367 @cindex number of staff lines
369 The grob @code{StaffSymbol} is responsible for drawing the lines
370 of a staff. Its properties can be altered in order to change the
371 appearance of a staff, but they must be changed before the staff
372 is created. A staff may be started or stopped at any point in the
375 The number of staff lines may be changed. The clef position and
376 the position of middle C may need to be modified to fit the new
377 staff. For an explanation, refer to the snippet section in
380 @lilypond[verbatim,quote,relative=2]
382 \override Staff.StaffSymbol #'line-count = #3
387 The vertical position of staff lines and the number of staff lines
388 can be defined at the same time. As the example shows, the
389 positions of the notes are not influenced by the position of the
390 staff lines. Details for modifying this property are found in
391 @rinternals{staff-symbol-interface}.
393 @warning{The @code{'line-positions} property overrides the
394 @code{'line-count} property. The number of staff lines is
395 implicitly defined by the number of elements in the list of values
396 for @code{'line-positions}}
398 @lilypond[verbatim,quote,relative=1]
400 \override StaffSymbol #'line-positions = #'(7 3 0 -4 -6 -7)
405 The staff line thickness can be modified. The thickness of ledger
406 lines and stems are also affected, since they depend on staff line
409 @lilypond[verbatim,quote,relative=1]
411 \override StaffSymbol #'thickness = #3
416 The thickness of ledger lines can be set independently of staff
417 line thickness. A description of this property is also found in
418 @rinternals{staff-symbol-interface}.
420 @lilypond[verbatim,quote,relative=1]
422 \override StaffSymbol #'ledger-line-thickness = #'(1 . 0.2)
427 The distance between staff lines can be changed. The setting has
428 influence on ledger lines as well.
430 @lilypond[verbatim,quote,relative=1]
432 \override StaffSymbol #'staff-space = #1.5
437 The width of a staff can be adjusted. The unit is one staff
438 space. The spacing of objects inside the staff is not influenced
441 @lilypond[verbatim,quote,relative=1]
443 \override StaffSymbol #'width = #23
448 Modifications to staff properties in the middle of a score can be
449 placed between @code{\stopStaff} and @code{\startStaff}:
451 @lilypond[verbatim,quote,relative=2]
454 \override Staff.StaffSymbol #'line-count = #2
458 \revert Staff.StaffSymbol #'line-count
466 @funindex \startStaff
474 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
475 {making-some-staff-lines-thicker-than-the-others.ly}
486 @ref{Displaying pitches}.
489 @rinternals{StaffSymbol},
490 @rinternals{staff-symbol-interface}.
495 When setting staff lines manually, bar lines are always drawn
496 centered on the position 0, so the maximum distance of the bar
497 lines in either direction must be equal.
501 @unnumberedsubsubsec Ossia staves
503 @cindex staff, Frenched
505 @cindex Frenched staves
506 @cindex staff, resizing of
507 @cindex resizing of staves
509 Tweaking the staff object allows to resize the staff:
511 @lilypond[verbatim,quote]
514 \override StaffSymbol #'staff-space = #(magstep -3)
515 \override StaffSymbol #'thickness = #(magstep -3)
523 This involves shrinking the staff spaces, the staff lines and the
524 font size by the factor 3. You find a more precise explanation in
525 @ref{Setting the staff size}.
527 The @emph{ossia} section in the next example are just put parallel
528 to the main staff with @code{<<} and @code{>>} brackets. The
529 @emph{ossia} staff is stopped and started explicitely and white
530 space is inserted with the @code{\skip} command.
532 @lilypond[verbatim,quote]
536 %No time signature in the ossia staff
537 \remove "Time_signature_engraver"
539 \override StaffSymbol #'staff-space = #(magstep -3)
540 \override StaffSymbol #'thickness = #(magstep -3)
549 bes8[^"ossia" g bes g]
557 \new Staff \relative c'' {
567 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
568 {vertically-aligning-ossias-and-lyrics.ly}
576 @rglos{Frenched staff}.
579 @rlearning{Nesting music expressions},
580 @rlearning{Size of objects},
581 @rlearning{Length and thickness of objects}.
584 @ref{Setting the staff size}.
587 @rlsr{Staff notation}.
590 @rinternals{StaffSymbol}.
594 @unnumberedsubsubsec Hiding staves
596 @cindex Frenched scores
597 @cindex staff, hiding
599 @cindex hiding of staves
601 @cindex Frenched staves
603 In orchestral scores, staff lines that only have rests are usually
604 removed; this saves some space. This style is called @q{French
605 Score}. For the @code{Lyrics}, @code{ChordNames}, and
606 @code{FiguredBass} contexts, this is switched on by default. When
607 the lines of these contexts turn out empty after the line-breaking
608 process, they are removed.
610 For normal staves this behaviour is called with the
611 @code{\RemoveEmptyStaffContext} command. It is set in the
612 @code{\layout} block. As a result staves containing nothing or
613 whole mesure rests are removed after a line break.
615 @lilypond[verbatim,quote]
618 \RemoveEmptyStaffContext
623 \new Staff { e4 f g a \break c1 }
624 \new Staff { c4 d e f \break R1 }
629 To remove other types of contexts, use
630 @code{\AncientRemoveEmptyStaffContext} or
631 @code{\RemoveEmptyRhythmicStaffContext}.
635 @c FIXME Really? I need to see about this. -pm
637 Another application of the @code{\RemoveEmptyStaffContext} is to
638 make ossia sections, i.e., alternative melodies on a separate
639 piece of staff, with help of a Frenched staff. See
642 @c FIXME Is this in the right section?
643 @c maybe move to Staff symbol -pm
645 You can make the staff lines invisible by removing the
646 @code{Staff_symbol_engraver} from the @code{Staff} context.
648 @lilypond[verbatim,quote]
650 \new Staff \relative c'' { c8 c c16 c c c }
654 \remove Staff_symbol_engraver
663 The first empty staff can also be removed from the score with a
664 setting in the @code{VerticalAxisGroup} property. This can be
665 done globally inside the @code{\layout} block, or locally inside
666 the specific staff that should be removed. In the latter case, you
667 have to specify the context (@code{Staff} applies only to the
668 current staff) in front of the property.
670 The lower staff of the second staff group is not removed, because
671 the setting applies only to the specific staff inside of which it
674 @lilypond[verbatim,quote]
677 \RemoveEmptyStaffContext
678 %To use the setting globally, uncomment the following line:
679 %\override VerticalAxisGroup #'remove-first = ##t
687 %To use the setting globally, comment this line, uncomment the line above
688 \override Staff.VerticalAxisGroup #'remove-first = ##t
693 \new Staff { e4 f g a \break c1 }
694 \new Staff { R \break R1 }
698 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
699 {removing-the-first-empty-line.ly}
704 @funindex \RemoveEmptyStaffContext
705 @code{\RemoveEmptyStaffContext},
706 @funindex \AncientRemoveEmptyStaffContext
707 @code{\AncientRemoveEmptyStaffContext},
708 @funindex \RemoveEmptyRhythmicStaffContext
709 @code{\RemoveEmptyRhythmicStaffContext}.
719 @rlsr{Staff notation}.
722 @rinternals{ChordNames},
723 @rinternals{FiguredBass},
726 @rinternals{VerticalAxisGroup}.
730 @subsection Writing parts
735 * Quoting other voices::
736 * Formatting cue notes::
740 @node Metronome marks
741 @unnumberedsubsubsec Metronome marks
744 @cindex beats per minute
745 @cindex metronome marking
747 Metronome settings can be entered as follows
750 \tempo @var{duration} = @var{per-minute}
753 In the MIDI output, they are interpreted as a tempo change. In
754 the layout output, a metronome marking is printed
758 @lilypond[verbatim,quote,relative=2]
766 To change the tempo in the MIDI output without printing anything,
767 make the metronome marking invisible @example \once \override
768 Score.MetronomeMark #'transparent = ##t @end example
770 To print other metronome markings, use these markup commands
771 @lilypond[verbatim,quote,relative=1]
774 \smaller \general-align #Y #DOWN \note #"16." #1
776 \smaller \general-align #Y #DOWN \note #"8" #1
780 For more details, see @ref{Formatting text}.
787 @rglos{metronomic indication},
788 @rglos{tempo indication},
789 @rglos{metronome mark}.
792 @ref{Formatting text},
796 @rlsr{Staff notation}.
799 @rinternals{MetronomeMark}.
804 Collisions are not checked. If you have notes above the top line
805 of the staff (or notes with articulations, slurs, text, etc), then
806 the metronome marking may be printed on top of musical symbols.
807 If this occurs, increase the padding of the metronome mark to
808 place it further away from the staff.
811 \override Score.MetronomeMark #'padding = #2.5
814 @c perhaps also an example of how to move it horizontally?
817 @node Instrument names
818 @unnumberedsubsubsec Instrument names
820 @cindex instrument names
821 @cindex instrument names, short
823 In an orchestral score, instrument names are printed at the left
826 This can be achieved by setting @code{Staff}.@code{instrumentName}
827 and @code{Staff}.@code{shortInstrumentName}, or
828 @code{PianoStaff}.@code{instrumentName} and
829 @code{PianoStaff}.@code{shortInstrumentName}. This will print
830 text before the start of the staff. For the first staff,
831 @code{instrumentName} is used. If set, @code{shortInstrumentName}
832 is used for the following staves.
834 @lilypond[verbatim,quote,relative=1]
835 \set Staff.instrumentName = "Ploink "
836 \set Staff.shortInstrumentName = "Plk "
842 Markup mode can be used to create more complicated instrument
845 @lilypond[verbatim,quote,relative=2]
846 \set Staff.instrumentName = \markup {
847 \column { "Clarinetti"
848 \line { "in B" \smaller \flat } } }
852 @cindex instrument names, centering
854 As instrument names are centered by default, multi line names are
855 better entered using @code{\center-align}:
857 @lilypond[verbatim,quote,relative=2]
860 \set Staff.instrumentName = \markup \center-align {
862 \line { "in B" \smaller \flat }
867 \set Staff.instrumentName = "Vibraphone"
873 For longer instrument names, it may be useful to increase the
874 @code{indent} setting in the @code{\layout} block.
876 Short instrument names, printed before the systems following the
877 first one, are also centered by default, in a space which width is
878 given by the @code{short-indent} variable of the @code{\layout}
881 To add instrument names to other contexts (such as
882 @code{GrandStaff}, @code{ChoirStaff}, or @code{StaffGroup}), the
883 engraver must be added to that context.
887 \context @{\GrandStaff \consists "Instrument_name_engraver"@}
892 More information about adding and removing engravers can be found
893 in @ref{Modifying context plug-ins}.
895 @cindex instrument names, changing
897 Instrument names may be changed in the middle of a piece:
899 @lilypond[verbatim,quote,relative=1]
900 \set Staff.instrumentName = "First"
901 \set Staff.shortInstrumentName = "one"
904 \set Staff.instrumentName = "Second"
905 \set Staff.shortInstrumentName = "two"
914 @ref{Modifying context plug-ins}.
917 @rlsr{Staff notation}.
920 @rinternals{InstrumentName},
921 @rinternals{PianoStaff},
925 @node Quoting other voices
926 @unnumberedsubsubsec Quoting other voices
929 @cindex quoting other voices
933 With quotations, fragments of other parts can be inserted into a
934 part directly. Before a part can be quoted, it must be marked
935 especially as quotable. This is done with the @code{\addQuote}
939 \addQuote @var{name} @var{music}
943 Here, @var{name} is an identifying string. The @var{music} is any
944 kind of music. Here is an example of @code{\addQuote}
947 \addQuote clarinet \relative c' @{
952 This command must be entered at toplevel, i.e., outside any music
953 blocks. Typically, one would use an already defined music event
957 clarinet = \relative c' @{
960 \addQuote clarinet @{ \clarinet @}
963 After calling @code{\addQuote}, the quotation may then be done
964 with @code{\quoteDuring} or @code{\cueDuring},
967 \quoteDuring #@var{name} @var{music}
970 During a part, a piece of music can be quoted with the
971 @code{\quoteDuring} command.
974 \quoteDuring #"clarinet" @{ s2. @}
977 This would cite three quarter notes (the duration of @code{s2.})
978 of the previously added @code{clarinet} voice.
980 More precisely, it takes the current time-step of the part being
981 printed, and extracts the notes at the corresponding point of the
982 @code{\addQuote}d voice. Therefore, the argument to
983 @code{\addQuote} should be the entire part of the voice to be
984 quoted, including any rests at the beginning.
986 It is possible to use another music expression instead of
987 @code{s}, thus creating a polyphonic section, but this may not
988 always give the desired result.
990 Quotations take into account the transposition of both source and
991 target instruments, if they are specified using the
992 @code{\transposition} command.
994 @lilypond[verbatim,quote,relative=1]
1002 e8 f8 \quoteDuring #"clarinet" { s2 }
1006 The type of events that are present in the quoted music can be
1007 trimmed with the @code{quotedEventTypes} property. The default
1008 value is @code{(note-event rest-event)}, which means that only
1009 notes and rests of the quoted voice end up in the
1010 @code{\quoteDuring}. Setting
1013 \set Staff.quotedEventTypes =
1014 #'(note-event articulation-event dynamic-event)
1018 will quote notes (but no rests), together with scripts and
1025 @ref{Instrument transpositions}.
1028 @rlsr{Staff notation}.
1030 Internals Reference:
1031 @rinternals{QuoteMusic},
1037 Only the contents of the first @code{Voice} occurring in an
1038 @code{\addQuote} command will be considered for quotation, so
1039 @var{music} can not contain @code{\new} and @code{\context Voice}
1040 statements that would switch to a different Voice.
1042 Quoting grace notes is broken and can even cause LilyPond to
1045 Quoting nested triplets may result in poor notation.
1047 In earlier versions of LilyPond (pre 2.11), @code{addQuote} was
1048 written entirely in lower-case letters: @code{\addquote}.
1051 @node Formatting cue notes
1052 @unnumberedsubsubsec Formatting cue notes
1056 @cindex cue notes, formatting
1058 @cindex quoting other voices
1059 @cindex cues, formatting
1061 The previous section deals with inserting notes from another
1062 voice. There is a more advanced music function called
1063 @code{\cueDuring}, which makes formatting cue notes easier.
1068 \cueDuring #@var{name} #@var{updown} @var{music}
1071 This will insert notes from the part @var{name} into a
1072 @code{Voice} called @code{cue}. This happens simultaneously with
1073 @var{music}, which usually is a rest. When the cue notes start,
1074 the staff in effect becomes polyphonic for a moment. The argument
1075 @var{updown} determines whether the cue notes should be notated as
1076 a first or second voice.
1081 \override Stem #'length-fraction = #0.8
1082 \override Beam #'thickness = #0.384
1083 \override Beam #'length-fraction = #0.8
1092 \new Staff \relative c' <<
1094 % setup a context for cue notes.
1095 \new Voice = "cue" { \smaller \skip 1*21 }
1097 \set Score.skipBars = ##t
1101 \cueDuring #"clarinet" #UP {
1109 Here are a couple of hints for successful cue notes:
1113 Cue notes have smaller font sizes.
1116 The cued part is marked with the instrument playing the cue.
1119 When the original part takes over again, this should be marked
1120 with the name of the original instrument.
1123 Any other changes introduced by the cued part should also be
1124 undone. For example, if the cued instrument plays in a different
1125 clef, the original clef should be stated once again.
1129 The macro @code{\transposedCueDuring} is useful to add cues to
1130 instruments which use a completely different octave range (for
1131 example, having a cue of a piccolo flute within a contra bassoon
1134 @lilypond[verbatim,quote]
1135 picc = \relative c''' {
1141 \addQuote "picc" { \picc }
1143 cbsn = \relative c, {
1146 \transposedCueDuring #"picc" #UP c,, { R1 } |
1151 \new Staff = "picc" \picc
1152 \new Staff = "cbsn" \cbsn
1160 @rlsr{Staff notation}.
1162 Internals Reference: