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. For details, see the Contributors'
7 Guide, node Updating translation committishes..
13 @section Staff notation
15 @lilypondfile[quote]{staff-headword.ly}
17 This section explains how to influence the appearance of staves,
18 how to print scores with more than one staff, and how to add tempo
19 indications and cue notes to staves.
23 * Modifying single staves::
28 @node Displaying staves
29 @subsection Displaying staves
31 This section describes the different methods of creating and
35 * Instantiating new staves::
37 * Nested staff groups::
38 * Separating systems::
42 @node Instantiating new staves
43 @unnumberedsubsubsec Instantiating new staves
46 @cindex staff initiation
47 @cindex staff instantiation
51 @cindex staff, percussion
53 @cindex percussion staff
54 @cindex Gregorian transcription staff
55 @cindex rhythmic staff
62 @funindex RhythmicStaff
64 @funindex MensuralStaff
65 @funindex VaticanaStaff
66 @funindex GregorianTranscriptionStaff
68 @notation{Staves} (singular: @notation{staff}) are created with
69 the @code{\new} or @code{\context} commands. For details, see
70 @ref{Creating contexts}.
72 The basic staff context is @code{Staff}:
74 @lilypond[verbatim,quote,relative=2]
75 \new Staff { c4 d e f }
78 The @code{DrumStaff} context creates a five-line staff set up for
79 a typical drum set. Each instrument is shown with a different
80 symbol. The instruments are entered in drum mode following a
81 @code{\drummode} command, with each instrument specified by name.
82 For details, see @ref{Percussion staves}.
84 @lilypond[verbatim,quote]
86 \drummode { cymc hh ss tomh }
90 @code{RhythmicStaff} creates a single-line staff that only
91 displays the rhythmic values of the input. Real durations are
92 preserved. For details, see @ref{Showing melody rhythms}.
94 @lilypond[verbatim,quote,relative=2]
95 \new RhythmicStaff { c4 d e f }
98 @code{TabStaff} creates a tablature with six strings in standard
99 guitar tuning. For details, see @ref{Default tablatures}.
101 @lilypond[verbatim,quote,relative=2]
102 \new TabStaff { c4 d e f }
105 There are two staff contexts specific for the notation of ancient
106 music: @code{MensuralStaff} and @code{VaticanaStaff}. They are
107 described in @ref{Pre-defined contexts}.
109 The @code{GregorianTranscriptionStaff} context creates a staff to
110 notate modern Gregorian chant. It does not show bar lines.
112 @lilypond[verbatim,quote,relative=2]
113 \new GregorianTranscriptionStaff { c4 d e f e d }
116 New single staff contexts may be defined. For details, see
117 @ref{Defining new contexts}.
126 @ref{Creating contexts},
127 @ref{Percussion staves},
128 @ref{Showing melody rhythms},
129 @ref{Default tablatures},
130 @ref{Pre-defined contexts},
132 @ref{Gregorian chant contexts},
133 @ref{Mensural contexts},
134 @ref{Defining new contexts}.
137 @rlsr{Staff notation}.
141 @rinternals{DrumStaff},
142 @rinternals{GregorianTranscriptionStaff},
143 @rinternals{RhythmicStaff},
144 @rinternals{TabStaff},
145 @rinternals{MensuralStaff},
146 @rinternals{VaticanaStaff},
147 @rinternals{StaffSymbol}.
150 @node Grouping staves
151 @unnumberedsubsubsec Grouping staves
153 @cindex start of system
154 @cindex staff, multiple
155 @cindex staves, multiple
156 @cindex system start delimiters
157 @cindex bracket, vertical
158 @cindex brace, vertical
168 Various contexts exist to group single staves together in order to
169 form multi-stave systems. Each grouping context sets the style of
170 the system start delimiter and the behavior of bar lines.
172 If no context is specified, the default properties will be used:
173 the group is started with a vertical line, and the bar lines are
176 @lilypond[verbatim,quote,relative=2]
183 In the @code{StaffGroup} context, the group is started with a
184 bracket and bar lines are drawn through all the staves.
186 @lilypond[verbatim,quote,relative=2]
193 In a @code{ChoirStaff}, the group starts with a bracket, but bar
194 lines are not connected.
196 @lilypond[verbatim,quote,relative=2]
203 In a @code{GrandStaff}, the group begins with a brace, and bar
204 lines are connected between the staves.
206 @lilypond[verbatim,quote,relative=2]
213 The @code{PianoStaff} is identical to a @code{GrandStaff}, except
214 that it supports printing the instrument name directly. For
215 details, see @ref{Instrument names}.
217 @lilypond[verbatim,quote,relative=2]
219 \set PianoStaff.instrumentName = #"Piano"
225 Each staff group context sets the property
226 @code{systemStartDelimiter} to one of the following values:
227 @code{SystemStartBar}, @code{SystemStartBrace}, or
228 @code{SystemStartBracket}. A fourth delimiter,
229 @code{SystemStartSquare}, is also available, but it must be
230 explicitly specified.
232 New staff group contexts may be defined. For details, see
233 @ref{Defining new contexts}.
238 @lilypondfile[verbatim,quote,texidoc,doctitle]
239 {use-square-bracket-at-the-start-of-a-staff-group.ly}
241 @lilypondfile[verbatim,quote,texidoc,doctitle]
242 {display-bracket-with-only-one-staff-in-a-system.ly}
244 @cindex mensurstriche layout
245 @cindex renaissance music
246 @cindex transcription of mensural music
247 @cindex mensural music, transcription of
249 @lilypondfile[verbatim,quote,texidoc,doctitle]
250 {mensurstriche-layout-bar-lines-between-the-staves.ly}
260 @ref{Instrument names},
261 @ref{Defining new contexts}.
264 @rlsr{Staff notation}.
268 @rinternals{StaffGroup},
269 @rinternals{ChoirStaff},
270 @rinternals{GrandStaff},
271 @rinternals{PianoStaff},
272 @rinternals{SystemStartBar},
273 @rinternals{SystemStartBrace},
274 @rinternals{SystemStartBracket},
275 @rinternals{SystemStartSquare}.
278 @code{PianoStaff} does not, by default, accept @code{ChordNames}.
281 @node Nested staff groups
282 @unnumberedsubsubsec Nested staff groups
284 @cindex staff, nested
285 @cindex staves, nested
286 @cindex nesting of staves
287 @cindex system start delimiters, nested
288 @cindex nested staff brackets
289 @cindex brackets, nesting of
290 @cindex braces, nesting of
292 Staff-group contexts can be nested to arbitrary depths. In this
293 case, each child context creates a new bracket adjacent to the
294 bracket of its parent group.
296 @lilypond[verbatim,quote,relative=2]
298 \new Staff { c2 c | c2 c }
300 \new Staff { g2 g | g2 g }
301 \new StaffGroup \with {
302 systemStartDelimiter = #'SystemStartSquare
305 \new Staff { e2 e | e2 e }
306 \new Staff { c2 c | c2 c }
312 New nested staff group contexts can be defined. For details, see
313 @ref{Defining new contexts}.
318 @lilypondfile[verbatim,quote,texidoc,doctitle]
324 @ref{Grouping staves},
325 @ref{Instrument names},
326 @ref{Defining new contexts}.
329 @rlsr{Staff notation}.
332 @rinternals{StaffGroup},
333 @rinternals{ChoirStaff},
334 @rinternals{SystemStartBar},
335 @rinternals{SystemStartBrace},
336 @rinternals{SystemStartBracket},
337 @rinternals{SystemStartSquare}.
339 @node Separating systems
340 @unnumberedsubsubsec Separating systems
342 @cindex system separator mark
344 If the number of systems per page changes from page to page it is
345 customary to separate the systems by placing a system separator mark
346 between them. By default the system separator is blank, but can be
347 turned on with a @code{\paper} option.
349 @c \book is required here to display the system separator
350 @c ragged-right is required as there are two systems
351 @lilypond[verbatim,quote,ragged-right]
372 system-separator-markup = \slashSeparator
373 % following commands are needed only to format this documentation
375 paper-height = 100\mm
386 @rlsr{Staff notation}.
389 @node Modifying single staves
390 @subsection Modifying single staves
392 This section explains how to change specific attributes of one
393 staff: for example, modifying the number of staff lines or the
394 staff size. Methods to start and stop staves and set ossia
395 sections are also described.
405 @unnumberedsubsubsec Staff symbol
407 @cindex adjusting staff symbol
408 @cindex drawing staff symbol
409 @cindex staff symbol, setting of
410 @cindex staff symbol, drawing
411 @cindex stop staff lines
412 @cindex start staff lines
413 @cindex staff lines, amount of
414 @cindex staff lines, number of
415 @cindex staff line, thickness of
416 @cindex amount of staff lines
417 @cindex thickness of staff lines
418 @cindex ledger lines, setting
419 @cindex setting of ledger lines
420 @cindex spacing of ledger lines
421 @cindex number of staff lines
423 The lines of a staff belong to the @code{StaffSymbol} grob.
424 @code{StaffSymbol} properties can be modified to change the
425 appearance of a staff, but they must be modified before the staff
428 The number of staff lines may be changed. The clef position and
429 the position of middle C may need to be modified to fit the new
430 staff. For an explanation, refer to the snippet section in
433 @lilypond[verbatim,quote,relative=2]
435 \override StaffSymbol #'line-count = #3
440 Staff line thickness can be modified. The thickness of ledger
441 lines and stems are also affected, since they depend on staff line
444 @lilypond[verbatim,quote,relative=1]
446 \override StaffSymbol #'thickness = #3
451 Ledger line thickness can be set independently of staff line
452 thickness. In the example the two numbers are factors multiplying
453 the staff line thickness and the staff line spacing. The two
454 contributions are added to give the ledger line thickness.
456 @lilypond[verbatim,quote,relative=1]
458 \override StaffSymbol #'ledger-line-thickness = #'(1 . 0.2)
463 The distance between staff lines can be changed. This setting
464 affects the spacing of ledger lines as well.
466 @lilypond[verbatim,quote,relative=1]
468 \override StaffSymbol #'staff-space = #1.5
473 Further details about the properties of @code{StaffSymbol} can be
474 found in @rinternals{staff-symbol-interface}.
476 @cindex stopping a staff
477 @cindex starting a staff
478 @cindex staff, starting
479 @cindex staff, stopping
481 @funindex \startStaff
486 Modifications to staff properties in the middle of a score can be
487 placed between @code{\stopStaff} and @code{\startStaff}:
489 @lilypond[verbatim,quote,relative=2]
492 \override Staff.StaffSymbol #'line-count = #2
496 \revert Staff.StaffSymbol #'line-count
502 In general, @code{\startStaff} and @code{\stopStaff} can be used
503 to stop or start a staff in the middle of a score.
505 @lilypond[verbatim,quote,relative=2]
522 @lilypondfile[verbatim,quote,texidoc,doctitle]
523 {making-some-staff-lines-thicker-than-the-others.ly}
536 @rlsr{Staff notation}.
539 @rinternals{StaffSymbol},
540 @rinternals{staff-symbol-interface}.
544 @unnumberedsubsubsec Ossia staves
546 @cindex staff, Frenched
548 @cindex Frenched staves
549 @cindex staff, resizing of
550 @cindex resizing of staves
552 @funindex \startStaff
557 @notation{Ossia} staves can be set by creating a new simultaneous
558 staff in the appropriate location:
560 @lilypond[verbatim,quote]
561 \new Staff \relative c'' {
565 \new Staff { e4 d f e }
572 However, the above example is not what is usually desired. To
573 create ossia staves that are above the original staff, have no
574 time signature or clef, and have a smaller font size, tweaks must
575 be used. The Learning Manual describes a specific technique to
576 achieve this goal, beginning with
577 @rlearning{Nesting music expressions}.
579 The following example uses the @code{alignAboveContext} property
580 to align the ossia staff. This method is most appropriate when
581 only a few ossia staves are needed.
583 @lilypond[verbatim,quote]
584 \new Staff = main \relative c'' {
590 \remove "Time_signature_engraver"
591 alignAboveContext = #"main"
593 \override StaffSymbol #'staff-space = #(magstep -3)
594 \override StaffSymbol #'thickness = #(magstep -3)
603 If many isolated ossia staves are needed, creating an empty
604 @code{Staff} context with a specific @emph{context id} may be more
605 appropriate; the ossia staves may then be created by
606 @emph{calling} this context and using @code{\startStaff} and
607 @code{\stopStaff} at the desired locations. The benefits of this
608 method are more apparent if the piece is longer than the following
611 @lilypond[verbatim,quote,ragged-right]
613 \new Staff = ossia \with {
614 \remove "Time_signature_engraver"
615 \override Clef #'transparent = ##t
617 \override StaffSymbol #'staff-space = #(magstep -3)
618 \override StaffSymbol #'thickness = #(magstep -3)
622 \new Staff \relative c' {
626 \context Staff = ossia {
627 \startStaff e4 g8 f e2 \stopStaff
634 \context Staff = ossia {
635 \startStaff g4 e8 f g2 \stopStaff
644 Using the @code{\Staff \RemoveEmptyStaves} command to create ossia
645 staves may be used as an alternative. This method is most
646 convenient when ossia staves occur immediately following a line
647 break. For more information about
648 @code{\Staff \RemoveEmptyStaves}, see @ref{Hiding staves}.
650 @lilypond[verbatim,quote,ragged-right]
652 \new Staff = ossia \with {
653 \remove "Time_signature_engraver"
654 \override Clef #'transparent = ##t
656 \override StaffSymbol #'staff-space = #(magstep -3)
657 \override StaffSymbol #'thickness = #(magstep -3)
662 \new Staff \relative c' {
674 \Staff \RemoveEmptyStaves
675 \override VerticalAxisGroup #'remove-first = ##t
683 @lilypondfile[verbatim,quote,texidoc,doctitle]
684 {vertically-aligning-ossias-and-lyrics.ly}
691 @rglos{Frenched staff}.
694 @rlearning{Nesting music expressions},
695 @rlearning{Size of objects},
696 @rlearning{Length and thickness of objects}.
702 @rlsr{Staff notation}.
705 @rinternals{StaffSymbol}.
709 @unnumberedsubsubsec Hiding staves
711 @cindex Frenched score
712 @cindex Frenched staff
713 @cindex staff, hiding
715 @cindex hiding of staves
718 @funindex \RemoveEmptyStaves
719 @funindex Staff_symbol_engraver
724 Staff lines can be hidden by removing the
725 @code{Staff_symbol_engraver} from the @code{Staff} context. As an
726 alternative, @code{\stopStaff} may be used.
728 @lilypond[verbatim,quote]
730 \remove "Staff_symbol_engraver"
732 \relative c''' { a8 f e16 d c b a2 }
736 Empty staves can be hidden by setting the
737 @code{\Staff \RemoveEmptyStaves} command in the @code{\layout}
738 block. In orchestral scores, this style is known as @q{Frenched
739 Score}. By default, this command hides and removes all empty
740 staves in a score except for those in the first system.
742 @warning{A staff is considered empty when it contains only
743 multi-measure rests, rests, skips, spacer rests, or a combination of these
746 @lilypond[verbatim,quote,ragged-right]
749 \Staff \RemoveEmptyStaves
770 @code{\Staff \RemoveEmptyStaves} can also be used to create ossia
771 sections for a staff. For details, see @ref{Ossia staves}.
773 @cindex hiding ancient staves
774 @cindex hiding rhythmic staves
776 @funindex \RemoveEmptyStaves
778 The @code{\VaticanaStaff \RemoveEmptyStaves} command may be used to
779 hide empty staves in ancient music contexts. Similarly,
780 @code{\RhythmicStaff \RemoveEmptyStaves} may be used to hide empty
781 @code{RhythmicStaff} contexts.
785 @code{\Staff \RemoveEmptyStaves},
786 @code{\VaticanaStaff \RemoveEmptyStaves},
787 @code{\RhythmicStaff \RemoveEmptyStaves}.
793 @lilypondfile[verbatim,quote,texidoc,doctitle]
794 {removing-the-first-empty-line.ly}
799 @rglos{Frenched staff}.
802 @rlearning{Visibility and color of objects}.
805 @ref{Changing context default settings},
809 @ref{Invisible rests},
810 @ref{Visibility of objects}.
813 @rlsr{Staff notation}.
816 @rinternals{ChordNames},
817 @rinternals{FiguredBass},
820 @rinternals{VerticalAxisGroup},
821 @rinternals{Staff_symbol_engraver}.
826 Removing @code{Staff_symbol_engraver} also hides bar lines. If
827 bar line visibility is forced, formatting errors may occur. In
828 this case, use the following overrides instead of removing the
832 \override StaffSymbol #'stencil = ##f
833 \override NoteHead #'no-ledgers = ##t
836 For the Known issues and warnings associated with
837 @code{\Staff \RemoveEmptyStaves} see
838 @ref{Changing context default settings}.
841 @subsection Writing parts
843 This section explains how to insert tempo indications and
844 instrument names into a score. Methods to quote other voices and
845 format cue notes are also described.
849 * Quoting other voices::
850 * Formatting cue notes::
853 @node Instrument names
854 @unnumberedsubsubsec Instrument names
856 @cindex instrument names
857 @cindex instrument names, short
859 Instrument names can be printed on the left side of staves in the
860 @code{Staff}, @code{PianoStaff}, @code{StaffGroup}, @code{GrandStaff}
861 and @code{ChoirStaff} contexts. The value of
862 @code{instrumentName} is used for the first staff, and the value
863 of @code{shortInstrumentName} is used for all succeeding staves.
865 @lilypond[verbatim,quote,ragged-right,relative=1]
867 instrumentName = #"Violin "
868 shortInstrumentName = #"Vln. "
870 { c4.. g'16 c4.. g'16 \break | c1 }
873 @cindex instrument names, complex
875 @code{\markup} can be used to create more complex instrument names:
877 @lilypond[verbatim,quote,relative=2]
879 instrumentName = \markup {
880 \column { "Clarinetti"
881 \line { "in B" \smaller \flat }
888 @cindex instrument names, centering
890 When two or more staff contexts are grouped together, the instrument
891 names and short instrument names are centered by default. To center
892 multi-line instrument names, @code{\center-column} must be used:
894 @lilypond[verbatim,quote,indent=1.5\cm,relative=2]
897 instrumentName = #"Flute"
901 instrumentName = \markup {
902 \center-column { "Clarinet" }
903 \line { "in B" \smaller \flat }
911 @funindex short-indent
913 However, if the instrument names are longer, the instrument names in a
914 staff group may not be centered unless the @code{indent} and
915 @code{short-indent} settings are increased. For details about these
916 settings, see @ref{\paper variables for shifts and indents}.
918 @lilypond[verbatim,quote,ragged-right]
922 instrumentName = #"Alto Flute in G"
923 shortInstrumentName = #"Flt."
930 instrumentName = #"Clarinet"
931 shortInstrumentName = #"Clar."
942 short-indent = 1.5\cm
946 @cindex instrument names, adding to other contexts
948 To add instrument names to other contexts (such as @code{ChordNames} or
949 @code{FiguredBass}), @code{Instrument_name_engraver} must be added to
950 that context. For details, see @ref{Modifying context plug-ins}.
952 @cindex instrument names, changing
953 @cindex changing instrument names
955 The @code{shortInstrumentName} may be changed in the middle of a piece.
956 However, only the first instance of @code{instrumentName} will be
957 printed and subsequent changes will be ignored:
959 @lilypond[verbatim,quote,ragged-right,relative=1]
961 instrumentName = #"Flute"
962 shortInstrumentName = #"Flt."
967 \set Staff.instrumentName = #"Clarinet"
968 \set Staff.shortInstrumentName = #"Clt."
974 @cindex instrument switch
975 @cindex switching instruments
977 @funindex \addInstrumentDefinition
978 @funindex addInstrumentDefinition
979 @funindex \instrumentSwitch
980 @funindex instrumentSwitch
982 If an instrument @emph{switch} is needed,
983 @code{\addInstrumentDefinition} may be used in combination with
984 @code{\instrumentSwitch} to create a detailed list of the
985 necessary changes for the switch. The
986 @code{\addInstrumentDefinition} command has two arguments: an
987 identifying string, and an association list of context properties
988 and values to be used for the instrument. It must be placed in
989 the toplevel scope. @code{\instrumentSwitch} is used in the music
990 expression to declare the instrument switch:
992 @lilypond[verbatim,quote,ragged-right]
993 \addInstrumentDefinition #"contrabassoon"
994 #`((instrumentTransposition . ,(ly:make-pitch -1 0 0))
995 (shortInstrumentName . "Cbsn.")
996 (clefGlyph . "clefs.F")
997 (middleCPosition . 6)
999 (instrumentCueName . ,(make-bold-markup "cbsn."))
1000 (midiInstrument . "bassoon"))
1003 instrumentName = #"Bassoon"
1007 \compressFullBarRests
1010 \instrumentSwitch "contrabassoon"
1019 @ref{\paper variables for shifts and indents},
1020 @ref{Modifying context plug-ins}.
1023 @rlsr{Staff notation}.
1025 Internals Reference:
1026 @rinternals{InstrumentName},
1027 @rinternals{PianoStaff},
1031 @node Quoting other voices
1032 @unnumberedsubsubsec Quoting other voices
1034 @cindex quote, voices
1035 @cindex voices, quoting
1036 @cindex fragments, quoting
1041 @funindex \quoteDuring
1042 @funindex quoteDuring
1043 @funindex \transposition
1044 @funindex transposition
1046 It is very common for one voice to use the same notes as those from
1047 another voice. For example, first and second violins playing the same
1048 phrase during a particular passage of the music. This is done by
1049 letting one voice @emph{quote} the other, without having to re-enter the
1050 music all over again for the second voice.
1052 The @code{\addQuote} command, used in the top level scope, defines a
1053 stream of music from which fragments can be quoted.
1055 The @code{\quoteDuring} command is used to indicate the point where the
1056 quotation begins. It is followed by two arguments: the name of the
1057 quoted voice, as defined with @code{\addQuote}, and a music expression
1058 for the duration of the quote.
1060 @lilypond[verbatim,quote]
1061 fluteNotes = \relative c'' {
1062 a4 gis g gis | b4^"quoted" r8 ais\p a4( f)
1065 oboeNotes = \relative c'' {
1066 c4 cis c b \quoteDuring #"flute" { s1 }
1069 \addQuote "flute" { \fluteNotes }
1073 \new Staff \with { instrumentName = "Flute" } \fluteNotes
1074 \new Staff \with { instrumentName = "Oboe" } \oboeNotes
1079 If the music expression used in @code{\quoteDuring} contains notes
1080 instead of spacer or multimeasure rests then the quote will appear as
1081 polyphony and may produce unexpected results.
1083 @lilypond[verbatim,quote]
1084 fluteNotes = \relative c'' {
1085 a4 gis g gis | b4^"quoted" r8 ais\p a4( f)
1088 oboeNotes = \relative c'' {
1089 c4 cis c b \quoteDuring #"flute" { e4 r8 ais b4 a }
1092 \addQuote "flute" { \fluteNotes }
1096 \new Staff \with { instrumentName = "Flute" } \fluteNotes
1097 \new Staff \with { instrumentName = "Oboe" } \oboeNotes
1102 The @code{\quoteDuring} command uses the @code{\transposition} settings
1103 of both quoted and quoting parts to produce notes for the quoting part
1104 that have the same sounding pitch as those in the quoted part.
1106 @lilypond[verbatim,quote]
1107 clarinetNotes = \relative c'' {
1110 b4 ais a ais | cis4^"quoted" r8 bis\p b4( f)
1113 oboeNotes = \relative c'' {
1114 c4 cis c b \quoteDuring #"clarinet" { s1 }
1117 \addQuote "clarinet" { \clarinetNotes }
1122 \new Staff \with { instrumentName = "Clarinet" } \clarinetNotes
1123 \new Staff \with { instrumentName = "Oboe" } \oboeNotes
1129 @cindex articulation-event
1130 @cindex dynamic-event
1133 @cindex crescendo-event
1135 @funindex quotedEventTypes
1136 @funindex quotedCueEventTypes
1138 By default quoted music will include all articulations, dynamics,
1139 markups, etc., in the quoted expression. It is possible to choose which
1140 of these objects from the quoted music are displayed by using the
1141 @code{quotedEventTypes} context property.
1143 @lilypond[verbatim,quote]
1144 fluteNotes = \relative c'' {
1146 b4\<^"quoted" r8 ais a4\f( c->)
1149 oboeNotes = \relative c'' {
1151 \quoteDuring #"flute" { s1 }
1154 \addQuote "flute" { \fluteNotes }
1158 \set Score.quotedEventTypes = #'(note-event articulation-event
1159 crescendo-event rest-event
1160 slur-event dynamic-event)
1161 \new Staff \with { instrumentName = "Flute" } \fluteNotes
1162 \new Staff \with { instrumentName = "Oboe" } \oboeNotes
1167 Quotes can also be tagged, see @ref{Using tags}.
1171 @ref{Instrument transpositions},
1175 @rlsr{Staff notation}.
1177 Internals Reference:
1178 @rinternals{Music classes},
1179 @rinternals{QuoteMusic},
1183 @file{scm/define-event-classes.scm}.
1187 Only the contents of the first @code{Voice} occurring in an
1188 @code{\addQuote} command will be considered for quotation, so if the music
1189 expression contains @code{\new} or @code{\context Voice}
1190 statements, their contents will not be quoted. Quoting grace notes
1191 is unsupported and may cause LilyPond to crash whereas quoting nested
1192 triplets may result in poor notation.
1195 @node Formatting cue notes
1196 @unnumberedsubsubsec Formatting cue notes
1200 @cindex cue notes, formatting
1201 @cindex formatting, cue notes
1202 @cindex voices, quoting
1205 @funindex \cueDuring
1209 @funindex \cueDuringWithClef
1210 @funindex cueDuringWithClef
1211 @funindex \quoteDuring
1212 @funindex quoteDuring
1214 @cindex notes, smaller
1215 @cindex smaller notes
1218 The simplest way to format cue notes is to explicitly create a
1219 @code{CueVoice} context within the part.
1221 @lilypond[verbatim,relative=1]
1226 \stemUp d'8^"flute" c d e fis2
1232 The @code{\cueClef} command can also be used with an explict
1233 @code{CueVoice} context if a change of clef is required and will print
1234 an appropriately sized clef for the cue notes. The @code{\cueClefUnset}
1235 command can then be used to switch back to the original clef, again with
1236 an appropriately sized clef.
1238 @lilypond[verbatim,noragged-right,relative=1]
1242 { e2\rest r4. \cueClefUnset e,8 }
1244 \cueClef "treble" \stemUp d''8^"flute" c d e fis2
1250 The @code{\cueClef} and @code{\cueClefUnset} command can also be used
1251 without a @code{CueVoice} if required.
1253 @lilypond[verbatim,noragged-right,relative=1]
1257 d'8^"flute" c d e fis2
1262 For more complex cue note placement, e.g including transposition, or
1263 inserting cue notes from multiple music sources the @code{\cueDuring} or
1264 @code{\cueDuringWithClef} commands can be used. These are more
1265 specialized form of @code{\quoteDuring}, see @ref{Quoting other voices}
1266 in the previous section.
1271 \cueDuring #@var{quotename} #@var{direction} #@var{music}
1277 \cueDuringWithClef #@var{quotename} #@var{direction} #@var{clef} #@var{music}
1280 The music from the corresponding measures of the @code{@var{quote name}}
1281 is added as a @code{CueVoice} context and occurs simultaneously with the
1282 @code{@var{music}}, which then creates a polyphonic situation. The
1283 @code{@var{direction}} takes the argument @code{UP} or @code{DOWN}, and
1284 corresponds to the first and second voices respectively, determining how
1285 the cue notes are printed in relation to the other voice.
1287 @lilypond[verbatim,quote]
1288 fluteNotes = \relative c'' {
1289 r2. c4 | d8 c d e fis2 | g2 d |
1292 oboeNotes = \relative c'' {
1294 s1*0^\markup { \tiny "flute" }
1295 \cueDuring #"flute" #UP { R1 }
1299 \addQuote "flute" { \fluteNotes }
1309 It is possible to adjust which aspects of the music are quoted with
1310 @code{\cueDuring} by setting the @code{quotedCueEventTypes}
1311 property. Its default value is @code{'(note-event rest-event
1312 tie-event beam-event tuplet-span-event)}, which means that only
1313 notes, rests, ties, beams and tuplets are quoted, but not
1314 articulations, dynamic marks, markup etc.
1316 @warning{When a @code{Voice} starts with @code{\cueDuring}, as in the
1317 following example, the @code{Voice} context must be explicitly declared,
1318 or else the entire music expression would belong to the @code{CueVoice}
1321 @lilypond[verbatim,quote]
1322 oboeNotes = \relative c'' {
1323 r2 r8 d16(\f f e g f a)
1326 \addQuote "oboe" { \oboeNotes }
1328 \new Voice \relative c'' {
1329 \set Score.quotedCueEventTypes = #'(note-event rest-event tie-event
1330 beam-event tuplet-span-event
1331 dynamic-event slur-event)
1332 \cueDuring #"oboe" #UP { R1 }
1337 Markup can be used to show the name of the quoted instrument. Also,
1338 if the cue notes require a change in clef, this can be done manually but
1339 the original clef should also be restored manually at the end of the cue
1342 @lilypond[verbatim,quote]
1343 fluteNotes = \relative c'' {
1344 r2. c4 d8 c d e fis2 g2 d2
1347 bassoonNotes = \relative c {
1351 s1*0^\markup { \tiny "flute" }
1352 \cueDuring #"flute" #UP { R1 }
1357 \addQuote "flute" { \fluteNotes }
1364 Alternatively, the @code{\cueDuringWithClef} function can be used
1365 instead. This command takes an extra argument to specify the change of
1366 clef that needs to be printed for the cue notes but will automatically
1367 print the original clef once the cue notes have finished.
1369 @lilypond[verbatim,quote]
1370 fluteNotes = \relative c'' {
1371 r2. c4 d8 c d e fis2 g2 d2
1374 bassoonNotes = \relative c {
1377 s1*0^\markup { \tiny "flute" }
1378 \cueDuringWithClef #"flute" #UP #"treble" { R1 }
1382 \addQuote "flute" { \fluteNotes }
1389 @funindex \transposedCueDuring
1390 @funindex transposedCueDuring
1392 Like @code{\quoteDuring}, @code{\cueDuring} takes instrument
1393 transpositions into account. Cue notes are produced at the
1394 pitches that would be written for the instrument receiving the cue
1395 to produce the sounding pitches of the source instrument.
1397 To transpose cue notes differently, use
1398 @code{\transposedCueDuring}. This command takes an extra argument
1399 to specify (in absolute mode) the printed pitch that you want to
1400 represent the sound of a concert middle C. This is useful for
1401 taking cues from an instrument in a completely different register.
1403 @lilypond[verbatim,quote]
1404 piccoloNotes = \relative c''' {
1411 bassClarinetNotes = \relative c' {
1415 \transposedCueDuring #"piccolo" #UP d { R1 }
1419 \addQuote "piccolo" { \piccoloNotes }
1422 \new Staff \piccoloNotes
1423 \new Staff \bassClarinetNotes
1427 @cindex removing cue notes
1428 @cindex cue notes, removing
1432 @funindex \addInstrumentDefinition
1433 @funindex addInstrumentDefinition
1435 The @code{\killCues} command removes cue notes from a music
1436 expression, so the same music expression can be used to produce
1437 the instrument part with cues and the score. The @code{\killCues}
1438 command removes only the notes and events that were quoted by
1439 @code{\cueDuring}. Other markup associated with cues, such as clef
1440 changes and a label identifying the source instrument, can be
1441 tagged for selective inclusion in the score; see @ref{Using tags}.
1443 @lilypond[verbatim,quote]
1444 fluteNotes = \relative c'' {
1445 r2. c4 d8 c d e fis2 g2 d2
1448 bassoonNotes = \relative c {
1453 s1*0^\markup { \tiny "flute" }
1455 \cueDuring #"flute" #UP { R1 }
1456 \tag #'part \clef bass
1460 \addQuote "flute" { \fluteNotes }
1471 \removeWithTag #'part { \killCues { \bassoonNotes } }
1476 Alternatively, Clef changes and instrument labels can be
1477 collected into an instrument definition for repeated use, using
1478 @code{\addInstrumentDefinition} described in @ref{Instrument names}.
1483 @ref{Quoting other voices},
1484 @ref{Instrument transpositions},
1485 @ref{Instrument names},
1491 @rlsr{Staff notation}.
1493 Internals Reference:
1494 @rinternals{CueVoice},
1500 Collisions can occur with rests, when using @code{\cueDuring},
1501 between @code{Voice} and @code{CueVoice} contexts. When using
1502 @code{\cueDuringWithClef} or @code{\transposedCueDuring} the extra
1503 argument required for each case must come after the quote and the