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 appearance of staves,
17 how to print scores with more than one staff, and how to add tempo
18 indications and cue notes to staves.
22 * Modifying single staves::
27 @node Displaying staves
28 @subsection Displaying staves
30 This section describes the different methods of creating and
34 * Instantiating new staves::
36 * 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 The @code{DrumStaff} context creates a five-line staff set up for
66 a typical drum set. Each instrument is shown with a different
67 symbol. The instruments are entered in drum mode following a
68 @code{\drummode} command, with each instrument specified by name.
69 For details, see @ref{Percussion staves}.
71 @lilypond[verbatim,quote]
73 \drummode { cymc hh ss tomh }
77 @code{RhythmicStaff} creates a single-line staff that only
78 displays the rhythmic values of the input. Real durations are
79 preserved. For details, see @ref{Showing melody rhythms}.
81 @lilypond[verbatim,quote,relative=2]
82 \new RhythmicStaff { c4 d e f }
85 @code{TabStaff} creates a tablature with six strings in standard
86 guitar tuning. For details, see @ref{Default tablatures}.
88 @lilypond[verbatim,quote,relative=2]
89 \new TabStaff { c4 d e f }
92 There are two staff contexts specific for the notation of ancient
93 music: @code{MensuralStaff} and @code{VaticanaStaff}. They are
94 described in @ref{Pre-defined contexts}.
96 The @code{GregorianTranscriptionStaff} context creates a staff to
97 notate modern Gregorian chant. It does not show bar lines.
99 @lilypond[verbatim,quote,relative=2]
100 \new GregorianTranscriptionStaff { c4 d e f e d }
103 New single staff contexts may be defined. For details, see
104 @ref{Defining new contexts}.
114 @ref{Creating contexts},
115 @ref{Percussion staves},
116 @ref{Showing melody rhythms},
117 @ref{Default tablatures},
118 @ref{Pre-defined contexts},
120 @ref{Gregorian chant contexts},
121 @ref{Mensural contexts},
122 @ref{Defining new contexts}.
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 identical to a @code{GrandStaff}, except
201 that it supports printing the instrument name directly. For
202 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.
219 New staff group contexts may be defined. For details, see
220 @ref{Defining new contexts}.
225 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
226 {use-square-bracket-at-the-start-of-a-staff-group.ly}
228 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
229 {display-bracket-with-only-one-staff-in-a-system.ly}
231 @cindex mensurstriche layout
232 @cindex renaissance music
233 @cindex transcription of mensural music
234 @cindex mensural music, transcription of
236 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
237 {mensurstriche-layout-bar-lines-between-the-staves.ly}
248 @ref{Instrument names},
249 @ref{Defining new contexts}.
252 @rlsr{Staff notation}.
256 @rinternals{StaffGroup},
257 @rinternals{ChoirStaff},
258 @rinternals{GrandStaff},
259 @rinternals{PianoStaff},
260 @rinternals{SystemStartBar},
261 @rinternals{SystemStartBrace},
262 @rinternals{SystemStartBracket},
263 @rinternals{SystemStartSquare}.
266 @node Nested staff groups
267 @unnumberedsubsubsec Nested staff groups
269 @cindex staff, nested
270 @cindex staves, nested
271 @cindex nesting of staves
272 @cindex system start delimiters, nested
273 @cindex nested staff brackets
274 @cindex brackets, nesting of
275 @cindex braces, nesting of
277 Staff-group contexts can be nested to arbitrary depths. In this
278 case, each child context creates a new bracket adjacent to the
279 bracket of its parent group.
281 @lilypond[verbatim,quote,relative=2]
283 \new Staff { c2 c | c2 c }
285 \new Staff { g2 g | g2 g }
286 \new StaffGroup \with {
287 systemStartDelimiter = #'SystemStartSquare
290 \new Staff { e2 e | e2 e }
291 \new Staff { c2 c | c2 c }
297 New nested staff group contexts can be defined. For details, see
298 @ref{Defining new contexts}.
303 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
310 @ref{Grouping staves},
311 @ref{Instrument names},
312 @ref{Defining new contexts}.
315 @rlsr{Staff notation}.
318 @rinternals{StaffGroup},
319 @rinternals{ChoirStaff},
320 @rinternals{SystemStartBar},
321 @rinternals{SystemStartBrace},
322 @rinternals{SystemStartBracket},
323 @rinternals{SystemStartSquare}.
326 @node Modifying single staves
327 @subsection Modifying single staves
329 This section explains how to change specific attributes of one
330 staff: for example, modifying the number of staff lines or the
331 staff size. Methods to start and stop staves and set ossia
332 sections are also described.
342 @unnumberedsubsubsec Staff symbol
344 @cindex adjusting staff symbol
345 @cindex drawing staff symbol
346 @cindex staff symbol, setting of
347 @cindex stop staff lines
348 @cindex start staff lines
349 @cindex staff lines, amount of
350 @cindex staff lines, number of
351 @cindex staff line, thickness of
352 @cindex amount of staff lines
353 @cindex thickness of staff lines
354 @cindex ledger lines, setting
355 @cindex setting of ledger lines
356 @cindex spacing of ledger lines
357 @cindex number of staff lines
359 The lines of a staff belong to the @code{StaffSymbol} grob.
360 @code{StaffSymbol} properties can be modified to change the
361 appearance of a staff, but they must be modified before the staff
364 The number of staff lines may be changed. The clef position and
365 the position of middle C may need to be modified to fit the new
366 staff. For an explanation, refer to the snippet section in
369 @lilypond[verbatim,quote,relative=2]
371 \override StaffSymbol #'line-count = #3
376 Staff line thickness can be modified. The thickness of ledger
377 lines and stems are also affected, since they depend on staff line
380 @lilypond[verbatim,quote,relative=1]
382 \override StaffSymbol #'thickness = #3
387 Ledger line thickness can be set independently of staff line
388 thickness. In the example the two numbers are factors multiplying
389 the staff line thickness and the staff line spacing. The two
390 contributions are added to give the ledger line thickness.
392 @lilypond[verbatim,quote,relative=1]
394 \override StaffSymbol #'ledger-line-thickness = #'(1 . 0.2)
399 The distance between staff lines can be changed. This setting
400 affects the spacing of ledger lines as well.
402 @lilypond[verbatim,quote,relative=1]
404 \override StaffSymbol #'staff-space = #1.5
409 Further details about the properties of @code{StaffSymbol} can be
410 found in @rinternals{staff-symbol-interface}.
412 @funindex \startStaff
415 Modifications to staff properties in the middle of a score can be
416 placed between @code{\stopStaff} and @code{\startStaff}:
418 @lilypond[verbatim,quote,relative=2]
421 \override Staff.StaffSymbol #'line-count = #2
425 \revert Staff.StaffSymbol #'line-count
430 @cindex stopping a staff
433 In general, @code{\startStaff} and @code{\stopStaff} can be used
434 to stop or start a staff in the middle of a score.
436 @lilypond[verbatim,quote,relative=2]
453 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
454 {making-some-staff-lines-thicker-than-the-others.ly}
468 @rlsr{Staff notation}.
471 @rinternals{StaffSymbol},
472 @rinternals{staff-symbol-interface}.
477 When setting vertical staff line positions manually, bar lines are
478 always centered on position 0, so the maximum distance between the
479 outermost bar lines in either direction must be equal.
483 @unnumberedsubsubsec Ossia staves
485 @cindex staff, Frenched
487 @cindex Frenched staves
488 @cindex staff, resizing of
489 @cindex resizing of staves
491 @notation{Ossia} staves can be set by creating a new simultaneous
492 staff in the appropriate location:
494 @lilypond[verbatim,quote]
495 \new Staff \relative c'' {
499 \new Staff { e4 d f e }
506 However, the above example is not what is usually desired. To
507 create ossia staves that are above the original staff, have no
508 time signature or clef, and have a smaller font size, tweaks must
509 be used. The Learning Manual describes a specific technique to
510 achieve this goal, beginning with
511 @rlearning{Nesting music expressions}.
513 The following example uses the @code{alignAboveContext} property
514 to align the ossia staff. This method is most appropriate when
515 only a few ossia staves are needed.
517 @lilypond[verbatim,quote]
518 \new Staff = main \relative c'' {
524 \remove "Time_signature_engraver"
525 alignAboveContext = #"main"
527 \override StaffSymbol #'staff-space = #(magstep -3)
528 \override StaffSymbol #'thickness = #(magstep -3)
537 If many isolated ossia staves are needed, creating an empty
538 @code{Staff} context with a specific @emph{context id} may be more
539 appropriate; the ossia staves may then be created by
540 @emph{calling} this context and using @code{\startStaff} and
541 @code{\stopStaff} at the desired locations. The benefits of this
542 method are more apparent if the piece is longer than the following
545 @lilypond[verbatim,quote,ragged-right]
547 \new Staff = ossia \with {
548 \remove "Time_signature_engraver"
549 \override Clef #'transparent = ##t
551 \override StaffSymbol #'staff-space = #(magstep -3)
552 \override StaffSymbol #'thickness = #(magstep -3)
556 \new Staff \relative c' {
560 \context Staff = ossia {
561 \startStaff e4 g8 f e2 \stopStaff
568 \context Staff = ossia {
569 \startStaff g4 e8 f g2 \stopStaff
577 Using the @code{\RemoveEmptyStaffContext} command to create ossia
578 staves may be used as an alternative. This method is most
579 convenient when ossia staves occur immediately following a line
580 break. In this case, spacer rests do not need to be used at all;
581 only @code{\startStaff} and @code{\stopStaff} are necessary. For
582 more information about @code{\RemoveEmptyStaffContext}, see
585 @lilypond[verbatim,quote,ragged-right]
587 \new Staff = ossia \with {
588 \remove "Time_signature_engraver"
589 \override Clef #'transparent = ##t
591 \override StaffSymbol #'staff-space = #(magstep -3)
592 \override StaffSymbol #'thickness = #(magstep -3)
594 \new Staff \relative c' {
600 \context Staff = ossia {
601 c4 e8 d c2 \stopStaff
611 \RemoveEmptyStaffContext
612 \override VerticalAxisGroup #'remove-first = ##t
620 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
621 {vertically-aligning-ossias-and-lyrics.ly}
629 @rglos{Frenched staff}.
632 @rlearning{Nesting music expressions},
633 @rlearning{Size of objects},
634 @rlearning{Length and thickness of objects}.
640 @rlsr{Staff notation}.
643 @rinternals{StaffSymbol}.
647 @unnumberedsubsubsec Hiding staves
649 @cindex Frenched score
650 @cindex Frenched staff
651 @cindex staff, hiding
653 @cindex hiding of staves
656 Staff lines can be hidden by removing the
657 @code{Staff_symbol_engraver} from the @code{Staff} context. As an
658 alternative, @code{\stopStaff} may be used.
660 @lilypond[verbatim,quote]
662 \remove "Staff_symbol_engraver"
664 \relative c''' { a8 f e16 d c b a2 }
667 @funindex \RemoveEmptyStaffContext
669 Empty staves can be hidden by setting the
670 @code{\RemoveEmptyStaffContext} command in the @code{\layout}
671 block. In orchestral scores, this style is known as @q{Frenched
672 Score}. By default, this command hides and removes all empty
673 staves in a score except for those in the first system.
675 @warning{A staff is considered empty when it contains only
676 multi-measure rests, skips, spacer rests, or a combination of these
679 @lilypond[verbatim,quote,ragged-right]
682 \RemoveEmptyStaffContext
703 @code{\RemoveEmptyStaffContext} can also be used to create ossia
704 sections for a staff. For details, see @ref{Ossia staves}.
706 @cindex hiding ancient staves
707 @cindex hiding rhythmic staves
708 @funindex \AncientRemoveEmptyStaffContext
709 @funindex \RemoveEmptyRhythmicStaffContext
711 The @code{\AncientRemoveEmptyStaffContext} command may be used to
712 hide empty staves in ancient music contexts. Similarly,
713 @code{\RemoveEmptyRhythmicStaffContext} may be used to hide empty
714 @code{RhythmicStaff} contexts.
719 @code{\RemoveEmptyStaffContext},
720 @code{\AncientRemoveEmptyStaffContext},
721 @code{\RemoveEmptyRhythmicStaffContext}.
726 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
727 {removing-the-first-empty-line.ly}
733 @rglos{Frenched staff}.
740 @rlsr{Staff notation}.
743 @rinternals{ChordNames},
744 @rinternals{FiguredBass},
747 @rinternals{VerticalAxisGroup},
748 @rinternals{Staff_symbol_engraver}.
753 Removing @code{Staff_symbol_engraver} also hides bar lines. If
754 bar line visibility is forced, formatting errors may occur. In
755 this case, use the following overrides instead of removing the
759 \override StaffSymbol #'stencil = ##f
760 \override NoteHead #'no-ledgers = ##t
765 @subsection Writing parts
767 This section explains how to insert tempo indications and
768 instrument names into a score. Methods to quote other voices and
769 format cue notes are also described.
774 * Quoting other voices::
775 * Formatting cue notes::
779 @node Metronome marks
780 @unnumberedsubsubsec Metronome marks
783 @cindex beats per minute
784 @cindex metronome marking
785 @cindex metronome marking with text
788 A basic metronome mark is simple to write:
790 @lilypond[verbatim,quote,relative=1]
796 Tempo indications with text can be used instead:
798 @lilypond[verbatim,quote,relative=2]
804 Combining a metronome mark and text will automatically place the
805 metronome mark within parentheses:
807 @lilypond[verbatim,quote,relative=2]
808 \tempo "Allegro" 4 = 160
813 In general, the text can be any markup object:
815 @lilypond[verbatim,quote,relative=2]
816 \tempo \markup { \italic Faster } 4 = 132
817 a8-. r8 b-. r gis-. r a-. r
820 A parenthesized metronome mark with no textual indication may be
821 written by including an empty string in the input:
823 @lilypond[verbatim,quote,relative=2]
831 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
832 {printing-metronome-and-rehearsal-marks-below-the-staff.ly}
834 @c perhaps also an example of how to move it horizontally?
836 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
837 {changing-the-tempo-without-a-metronome-mark.ly}
839 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
840 {creating-metronome-marks-in-markup-mode.ly}
842 For more details, see @ref{Formatting text}.
849 @rglos{metronomic indication},
850 @rglos{tempo indication},
851 @rglos{metronome mark}.
854 @ref{Formatting text},
858 @rlsr{Staff notation}.
861 @rinternals{MetronomeMark}.
864 @node Instrument names
865 @unnumberedsubsubsec Instrument names
867 @cindex instrument names
868 @cindex instrument names, short
870 Instrument names can be printed on the left side of staves in the
871 @code{Staff} and @code{PianoStaff} contexts. The value of
872 @code{instrumentName} is used for the first staff, and the value
873 of @code{shortInstrumentName} is used for all succeeding staves.
875 @lilypond[verbatim,quote,ragged-right,relative=1]
876 \set Staff.instrumentName = "Violin "
877 \set Staff.shortInstrumentName = "Vln "
883 Markup mode can be used to create more complicated instrument
886 @lilypond[verbatim,quote,relative=2]
887 \set Staff.instrumentName = \markup {
888 \column { "Clarinetti"
889 \line { "in B" \smaller \flat } } }
893 @cindex instrument names, centering
895 When two or more staff contexts are grouped together, the
896 instrument names and short instrument names are centered by
897 default. To center multi-line instrument names,
898 @code{\center-column} must be used:
900 @lilypond[verbatim,quote,indent=1.5\cm,relative=2]
903 \set Staff.instrumentName = "Flute"
907 \set Staff.instrumentName = \markup \center-column {
909 \line { "in B" \smaller \flat }
919 However, if the instrument names are longer, the instrument names
920 in a staff group may not be centered unless the @code{indent} and
921 @code{short-indent} settings are increased. For details about
922 these settings, see @ref{Horizontal dimensions}.
924 @lilypond[verbatim,quote,ragged-right]
927 short-indent = 1.5\cm
932 \set Staff.instrumentName = "Alto Flute in G"
933 \set Staff.shortInstrumentName = "Fl."
938 \set Staff.instrumentName = "Clarinet"
939 \set Staff.shortInstrumentName = "Clar."
946 To add instrument names to other contexts (such as
947 @code{GrandStaff}, @code{ChoirStaff}, or @code{StaffGroup}),
948 @code{Instrument_name_engraver} must be added to that context.
949 For details, see @ref{Modifying context plug-ins}.
951 @cindex instrument names, changing
953 Instrument names may be changed in the middle of a piece:
955 @lilypond[verbatim,quote,ragged-right,relative=1]
956 \set Staff.instrumentName = "First"
957 \set Staff.shortInstrumentName = "one"
960 \set Staff.instrumentName = "Second"
961 \set Staff.shortInstrumentName = "two"
966 @cindex instrument switch
967 @cindex switching instruments
969 If an instrument @emph{switch} is needed,
970 @code{\addInstrumentDefinition} may be used in combination with
971 @code{\instrumentSwitch} to create a detailed list of the
972 necessary changes for the switch. The
973 @code{\addInstrumentDefinition} command has two arguments: an
974 identifying string, and an association list of context properties
975 and values to be used for the instrument. It must be placed in
976 the toplevel scope. @code{\instrumentSwitch} is used in the music
977 expression to declare the instrument switch:
979 @lilypond[verbatim,quote,ragged-right]
980 \addInstrumentDefinition #"contrabassoon"
981 #`((instrumentTransposition . ,(ly:make-pitch -1 0 0))
982 (shortInstrumentName . "Cbsn.")
983 (clefGlyph . "clefs.F")
984 (middleCPosition . 6)
986 (instrumentCueName . ,(make-bold-markup "cbsn."))
987 (midiInstrument . "bassoon"))
990 instrumentName = "Bassoon"
994 \compressFullBarRests
997 \instrumentSwitch "contrabassoon"
1007 @ref{Horizontal dimensions},
1008 @ref{Modifying context plug-ins}.
1011 @rlsr{Staff notation}.
1013 Internals Reference:
1014 @rinternals{InstrumentName},
1015 @rinternals{PianoStaff},
1019 @node Quoting other voices
1020 @unnumberedsubsubsec Quoting other voices
1023 @cindex quoting other voices
1027 It is very common for one voice to double some of the music from
1028 another voice. For example, the first and second violins may play the
1029 same notes during a passage of music. In LilyPond this is accomplished
1030 by letting one voice @emph{quote} the other voice without having to
1033 Before a part can be quoted, the @code{\addQuote} command must be used
1034 to initialize the quoted fragment. This command must be used in the
1035 toplevel scope. The first argument is an identifying string, and the
1036 second is a music expression:
1039 flute = \relative c'' @{
1042 \addQuote "flute" @{ \flute @}
1045 The @code{\quoteDuring} command is used to indicate the point where the
1046 quotation begins. It is followed by two arguments: the name of the
1047 quoted voice, as defined with @code{\addQuote}, and a music expression
1048 that indicates the duration of the quote, usually spacer rests or
1049 multi-measure rests. The corresponding music from the quoted voice is
1050 inserted into the music expression:
1052 @lilypond[verbatim,quote]
1053 flute = \relative c'' {
1056 \addQuote "flute" { \flute }
1059 c4 cis \quoteDuring #"flute" { s2 }
1063 If the music expression used for @code{\quoteDuring} contains
1064 anything but a spacer rest or multi-measure rest, a polyphonic
1065 situation is created, which is often not desirable:
1067 @lilypond[verbatim,quote]
1068 flute = \relative c'' {
1071 \addQuote "flute" { \flute }
1074 c4 cis \quoteDuring #"flute" { c4 b }
1078 Quotations recognize instrument transposition settings for both
1079 the source and target instruments if the @code{\transposition}
1080 command is used. For details about @code{\transposition}, see
1081 @ref{Instrument transpositions}.
1083 @lilypond[verbatim,quote]
1084 clarinet = \relative c'' {
1088 \addQuote "clarinet" { \clarinet }
1091 c4 cis \quoteDuring #"clarinet" { s2 }
1095 It is possible to tag quotations with unique names in order to
1096 process them in different ways. For details about this procedure,
1097 see @ref{Using tags}.
1102 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
1103 {quoting-another-voice-with-transposition.ly}
1106 @cindex articulation-event
1107 @cindex dynamic-event
1109 @funindex quotedEventTypes
1111 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
1112 {quoting-another-voice.ly}
1118 @ref{Instrument transpositions},
1122 @rlsr{Staff notation}.
1124 Internals Reference:
1125 @rinternals{QuoteMusic},
1131 Only the contents of the first @code{Voice} occurring in an
1132 @code{\addQuote} command will be considered for quotation, so
1133 @var{music} cannot contain @code{\new} and @code{\context Voice}
1134 statements that would switch to a different Voice.
1136 Quoting grace notes is broken and can even cause LilyPond to
1139 Quoting nested triplets may result in poor notation.
1141 In earlier versions of LilyPond (pre 2.11), @code{addQuote} was
1142 written entirely in lower-case letters: @code{\addquote}.
1145 @node Formatting cue notes
1146 @unnumberedsubsubsec Formatting cue notes
1150 @cindex cue notes, formatting
1152 @cindex quoting other voices
1153 @cindex cues, formatting
1155 The previous section explains how to create quotations. The
1156 @code{\cueDuring} command is a more specialized form of
1157 @code{\quoteDuring}, being particularly useful for inserting cue
1158 notes into a part. The syntax is as follows:
1161 \cueDuring #@var{partname} #@var{voice} @var{music}
1164 This command copies the corresponding measures from @var{partname}
1165 into a @code{CueVoice} context. The @code{CueVoice} is created
1166 implicitly, and occurs simultaneously with @var{music}, which
1167 creates a polyphonic situation. The @var{voice} argument
1168 determines whether the cue notes should be notated as a first or
1169 second voice; @code{UP} corresponds to the first voice, and
1170 @code{DOWN} corresponds to the second.
1172 @lilypond[verbatim,quote]
1173 oboe = \relative c'' {
1177 \addQuote "oboe" { \oboe }
1179 \new Voice \relative c'' {
1180 \cueDuring #"oboe" #UP { R1 }
1186 In the above example, the @code{Voice} context had to be
1187 explicitly declared, or else the entire music expression would
1188 belong to the @code{CueVoice} context.
1190 The name of the cued instrument can be printed by setting the
1191 @code{instrumentCueName} property in the @code{CueVoice} context.
1193 @lilypond[verbatim,quote]
1194 oboe = \relative c''' {
1197 \addQuote "oboe" { \oboe }
1199 \new Staff \relative c'' <<
1200 \new CueVoice \with {
1201 instrumentCueName = "ob."
1204 \cueDuring #"oboe" #UP { R1 }
1210 In addition to printing the name of the cued instrument, when cue
1211 notes end, the name of the original instrument should be printed,
1212 and any other changes introduced by the cued part should be
1213 undone. This can be accomplished by using
1214 @code{\addInstrumentDefinition} and @code{\instrumentSwitch}. For
1215 an example and explanation, see @ref{Instrument names}.
1217 The @code{\killCues} command removes cue notes from a music
1218 expression. This can be useful if cue notes need to be removed
1219 from a part but may be restored at a later time.
1221 @lilypond[verbatim,quote]
1222 flute = \relative c''' {
1225 \addQuote "flute" { \flute }
1227 \new Voice \relative c'' {
1229 \cueDuring #"flute" #UP { R1 }
1235 The @code{\transposedCueDuring} command is useful for adding
1236 instrumental cues from a completely different register. The
1237 syntax is similar to @code{\cueDuring}, but it requires one extra
1238 argument to specify the transposition of the cued instrument. For
1239 more information about transposition, see
1240 @ref{Instrument transpositions}.
1242 @lilypond[verbatim,quote]
1243 piccolo = \relative c''' {
1249 \addQuote "piccolo" { \piccolo }
1251 cbassoon = \relative c, {
1254 \transposedCueDuring #"piccolo" #UP c,, { R1 }
1259 \new Staff = "piccolo" \piccolo
1260 \new Staff = "cbassoon" \cbassoon
1264 It is possible to tag cued parts with unique names in order to
1265 process them in different ways. For details about this procedure,
1266 see @ref{Using tags}.
1272 @ref{Instrument transpositions},
1273 @ref{Instrument names},
1277 @rlsr{Staff notation}.
1279 Internals Reference:
1280 @rinternals{CueVoice},
1286 Collisions can occur with rests, when using @code{\cueDuring},
1287 between @code{Voice} and @code{CueVoice} contexts.