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}.
113 @ref{Creating contexts},
114 @ref{Percussion staves},
115 @ref{Showing melody rhythms},
116 @ref{Default tablatures},
117 @ref{Pre-defined contexts},
119 @ref{Gregorian chant contexts},
120 @ref{Mensural contexts},
121 @ref{Defining new contexts}.
124 @rlsr{Staff notation}.
128 @rinternals{DrumStaff},
129 @rinternals{GregorianTranscriptionStaff},
130 @rinternals{RhythmicStaff},
131 @rinternals{TabStaff},
132 @rinternals{MensuralStaff},
133 @rinternals{VaticanaStaff},
134 @rinternals{StaffSymbol}.
137 @node Grouping staves
138 @unnumberedsubsubsec 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
154 Various contexts exist to group single staves together in order to
155 form multi-stave systems. Each grouping context sets the style of
156 the system start delimiter and the behavior of bar lines.
158 If no context is specified, the default properties will be used:
159 the group is started with a vertical line, and the bar lines are
162 @lilypond[verbatim,quote,relative=2]
169 In the @code{StaffGroup} context, the group is started with a
170 bracket and bar lines are drawn through all the staves.
172 @lilypond[verbatim,quote,relative=2]
179 In a @code{ChoirStaff}, the group starts with a bracket, but bar
180 lines are not connected.
182 @lilypond[verbatim,quote,relative=2]
189 In a @code{GrandStaff}, the group begins with a brace, and bar
190 lines are connected between the staves.
192 @lilypond[verbatim,quote,relative=2]
199 The @code{PianoStaff} is identical to a @code{GrandStaff}, except
200 that it supports printing the instrument name directly. For
201 details, see @ref{Instrument names}.
203 @lilypond[verbatim,quote,relative=2]
205 \set PianoStaff.instrumentName = #"Piano"
211 Each staff group context sets the property
212 @code{systemStartDelimiter} to one of the following values:
213 @code{SystemStartBar}, @code{SystemStartBrace}, or
214 @code{SystemStartBracket}. A fourth delimiter,
215 @code{SystemStartSquare}, is also available, but it must be
216 explicitly specified.
218 New staff group contexts may be defined. For details, see
219 @ref{Defining new contexts}.
224 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
225 {use-square-bracket-at-the-start-of-a-staff-group.ly}
227 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
228 {display-bracket-with-only-one-staff-in-a-system.ly}
230 @cindex mensurstriche layout
231 @cindex renaissance music
232 @cindex transcription of mensural music
233 @cindex mensural music, transcription of
235 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
236 {mensurstriche-layout-bar-lines-between-the-staves.ly}
246 @ref{Instrument names},
247 @ref{Defining new contexts}.
250 @rlsr{Staff notation}.
254 @rinternals{StaffGroup},
255 @rinternals{ChoirStaff},
256 @rinternals{GrandStaff},
257 @rinternals{PianoStaff},
258 @rinternals{SystemStartBar},
259 @rinternals{SystemStartBrace},
260 @rinternals{SystemStartBracket},
261 @rinternals{SystemStartSquare}.
264 @node Nested staff groups
265 @unnumberedsubsubsec Nested staff groups
267 @cindex staff, nested
268 @cindex staves, nested
269 @cindex nesting of staves
270 @cindex system start delimiters, nested
271 @cindex nested staff brackets
272 @cindex brackets, nesting of
273 @cindex braces, nesting of
275 Staff-group contexts can be nested to arbitrary depths. In this
276 case, each child context creates a new bracket adjacent to the
277 bracket of its parent group.
279 @lilypond[verbatim,quote,relative=2]
281 \new Staff { c2 c | c2 c }
283 \new Staff { g2 g | g2 g }
284 \new StaffGroup \with {
285 systemStartDelimiter = #'SystemStartSquare
288 \new Staff { e2 e | e2 e }
289 \new Staff { c2 c | c2 c }
295 New nested staff group contexts can be defined. For details, see
296 @ref{Defining new contexts}.
301 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
307 @ref{Grouping staves},
308 @ref{Instrument names},
309 @ref{Defining new contexts}.
312 @rlsr{Staff notation}.
315 @rinternals{StaffGroup},
316 @rinternals{ChoirStaff},
317 @rinternals{SystemStartBar},
318 @rinternals{SystemStartBrace},
319 @rinternals{SystemStartBracket},
320 @rinternals{SystemStartSquare}.
323 @node Modifying single staves
324 @subsection Modifying single staves
326 This section explains how to change specific attributes of one
327 staff: for example, modifying the number of staff lines or the
328 staff size. Methods to start and stop staves and set ossia
329 sections are also described.
339 @unnumberedsubsubsec Staff symbol
341 @cindex adjusting staff symbol
342 @cindex drawing staff symbol
343 @cindex staff symbol, setting of
344 @cindex stop staff lines
345 @cindex start staff lines
346 @cindex staff lines, amount of
347 @cindex staff lines, number of
348 @cindex staff line, thickness of
349 @cindex amount of staff lines
350 @cindex thickness of staff lines
351 @cindex ledger lines, setting
352 @cindex setting of ledger lines
353 @cindex spacing of ledger lines
354 @cindex number of staff lines
356 The lines of a staff belong to the @code{StaffSymbol} grob.
357 @code{StaffSymbol} properties can be modified to change the
358 appearance of a staff, but they must be modified before the staff
361 The number of staff lines may be changed. The clef position and
362 the position of middle C may need to be modified to fit the new
363 staff. For an explanation, refer to the snippet section in
366 @lilypond[verbatim,quote,relative=2]
368 \override StaffSymbol #'line-count = #3
373 Staff line thickness can be modified. The thickness of ledger
374 lines and stems are also affected, since they depend on staff line
377 @lilypond[verbatim,quote,relative=1]
379 \override StaffSymbol #'thickness = #3
384 Ledger line thickness can be set independently of staff line
385 thickness. In the example the two numbers are factors multiplying
386 the staff line thickness and the staff line spacing. The two
387 contributions are added to give the ledger line thickness.
389 @lilypond[verbatim,quote,relative=1]
391 \override StaffSymbol #'ledger-line-thickness = #'(1 . 0.2)
396 The distance between staff lines can be changed. This setting
397 affects the spacing of ledger lines as well.
399 @lilypond[verbatim,quote,relative=1]
401 \override StaffSymbol #'staff-space = #1.5
406 Further details about the properties of @code{StaffSymbol} can be
407 found in @rinternals{staff-symbol-interface}.
409 @funindex \startStaff
412 Modifications to staff properties in the middle of a score can be
413 placed between @code{\stopStaff} and @code{\startStaff}:
415 @lilypond[verbatim,quote,relative=2]
418 \override Staff.StaffSymbol #'line-count = #2
422 \revert Staff.StaffSymbol #'line-count
427 @cindex stopping a staff
430 In general, @code{\startStaff} and @code{\stopStaff} can be used
431 to stop or start a staff in the middle of a score.
433 @lilypond[verbatim,quote,relative=2]
450 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
451 {making-some-staff-lines-thicker-than-the-others.ly}
464 @rlsr{Staff notation}.
467 @rinternals{StaffSymbol},
468 @rinternals{staff-symbol-interface}.
473 When setting vertical staff line positions manually, bar lines are
474 always centered on position 0, so the maximum distance between the
475 outermost bar lines in either direction must be equal.
479 @unnumberedsubsubsec Ossia staves
481 @cindex staff, Frenched
483 @cindex Frenched staves
484 @cindex staff, resizing of
485 @cindex resizing of staves
487 @notation{Ossia} staves can be set by creating a new simultaneous
488 staff in the appropriate location:
490 @lilypond[verbatim,quote]
491 \new Staff \relative c'' {
495 \new Staff { e4 d f e }
502 However, the above example is not what is usually desired. To
503 create ossia staves that are above the original staff, have no
504 time signature or clef, and have a smaller font size, tweaks must
505 be used. The Learning Manual describes a specific technique to
506 achieve this goal, beginning with
507 @rlearning{Nesting music expressions}.
509 The following example uses the @code{alignAboveContext} property
510 to align the ossia staff. This method is most appropriate when
511 only a few ossia staves are needed.
513 @lilypond[verbatim,quote]
514 \new Staff = main \relative c'' {
520 \remove "Time_signature_engraver"
521 alignAboveContext = #"main"
523 \override StaffSymbol #'staff-space = #(magstep -3)
524 \override StaffSymbol #'thickness = #(magstep -3)
533 If many isolated ossia staves are needed, creating an empty
534 @code{Staff} context with a specific @emph{context id} may be more
535 appropriate; the ossia staves may then be created by
536 @emph{calling} this context and using @code{\startStaff} and
537 @code{\stopStaff} at the desired locations. The benefits of this
538 method are more apparent if the piece is longer than the following
541 @lilypond[verbatim,quote,ragged-right]
543 \new Staff = ossia \with {
544 \remove "Time_signature_engraver"
545 \override Clef #'transparent = ##t
547 \override StaffSymbol #'staff-space = #(magstep -3)
548 \override StaffSymbol #'thickness = #(magstep -3)
552 \new Staff \relative c' {
556 \context Staff = ossia {
557 \startStaff e4 g8 f e2 \stopStaff
564 \context Staff = ossia {
565 \startStaff g4 e8 f g2 \stopStaff
573 Using the @code{\RemoveEmptyStaffContext} command to create ossia
574 staves may be used as an alternative. This method is most
575 convenient when ossia staves occur immediately following a line
576 break. In this case, spacer rests do not need to be used at all;
577 only @code{\startStaff} and @code{\stopStaff} are necessary. For
578 more information about @code{\RemoveEmptyStaffContext}, see
581 @lilypond[verbatim,quote,ragged-right]
583 \new Staff = ossia \with {
584 \remove "Time_signature_engraver"
585 \override Clef #'transparent = ##t
587 \override StaffSymbol #'staff-space = #(magstep -3)
588 \override StaffSymbol #'thickness = #(magstep -3)
590 \new Staff \relative c' {
596 \context Staff = ossia {
597 c4 e8 d c2 \stopStaff
607 \RemoveEmptyStaffContext
608 \override VerticalAxisGroup #'remove-first = ##t
616 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
617 {vertically-aligning-ossias-and-lyrics.ly}
624 @rglos{Frenched staff}.
627 @rlearning{Nesting music expressions},
628 @rlearning{Size of objects},
629 @rlearning{Length and thickness of objects}.
635 @rlsr{Staff notation}.
638 @rinternals{StaffSymbol}.
642 @unnumberedsubsubsec Hiding staves
644 @cindex Frenched score
645 @cindex Frenched staff
646 @cindex staff, hiding
648 @cindex hiding of staves
651 Staff lines can be hidden by removing the
652 @code{Staff_symbol_engraver} from the @code{Staff} context. As an
653 alternative, @code{\stopStaff} may be used.
655 @lilypond[verbatim,quote]
657 \remove "Staff_symbol_engraver"
659 \relative c''' { a8 f e16 d c b a2 }
662 @funindex \RemoveEmptyStaffContext
664 Empty staves can be hidden by setting the
665 @code{\RemoveEmptyStaffContext} command in the @code{\layout}
666 block. In orchestral scores, this style is known as @q{Frenched
667 Score}. By default, this command hides and removes all empty
668 staves in a score except for those in the first system.
670 @warning{A staff is considered empty when it contains only
671 multi-measure rests, skips, spacer rests, or a combination of these
674 @lilypond[verbatim,quote,ragged-right]
677 \RemoveEmptyStaffContext
698 @code{\RemoveEmptyStaffContext} can also be used to create ossia
699 sections for a staff. For details, see @ref{Ossia staves}.
701 @cindex hiding ancient staves
702 @cindex hiding rhythmic staves
703 @funindex \AncientRemoveEmptyStaffContext
704 @funindex \RemoveEmptyRhythmicStaffContext
706 The @code{\AncientRemoveEmptyStaffContext} command may be used to
707 hide empty staves in ancient music contexts. Similarly,
708 @code{\RemoveEmptyRhythmicStaffContext} may be used to hide empty
709 @code{RhythmicStaff} contexts.
713 @code{\RemoveEmptyStaffContext},
714 @code{\AncientRemoveEmptyStaffContext},
715 @code{\RemoveEmptyRhythmicStaffContext}.
721 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
722 {removing-the-first-empty-line.ly}
727 @rglos{Frenched staff}.
734 @rlsr{Staff notation}.
737 @rinternals{ChordNames},
738 @rinternals{FiguredBass},
741 @rinternals{VerticalAxisGroup},
742 @rinternals{Staff_symbol_engraver}.
747 Removing @code{Staff_symbol_engraver} also hides bar lines. If
748 bar line visibility is forced, formatting errors may occur. In
749 this case, use the following overrides instead of removing the
753 \override StaffSymbol #'stencil = ##f
754 \override NoteHead #'no-ledgers = ##t
759 @subsection Writing parts
761 This section explains how to insert tempo indications and
762 instrument names into a score. Methods to quote other voices and
763 format cue notes are also described.
768 * Quoting other voices::
769 * Formatting cue notes::
773 @node Metronome marks
774 @unnumberedsubsubsec Metronome marks
777 @cindex beats per minute
778 @cindex metronome marking
779 @cindex metronome marking with text
782 A basic metronome mark is simple to write:
784 @lilypond[verbatim,quote,relative=1]
790 Tempo indications with text can be used instead:
792 @lilypond[verbatim,quote,relative=2]
798 Combining a metronome mark and text will automatically place the
799 metronome mark within parentheses:
801 @lilypond[verbatim,quote,relative=2]
802 \tempo "Allegro" 4 = 160
807 In general, the text can be any markup object:
809 @lilypond[verbatim,quote,relative=2]
810 \tempo \markup { \italic Faster } 4 = 132
811 a8-. r8 b-. r gis-. r a-. r
814 A parenthesized metronome mark with no textual indication may be
815 written by including an empty string in the input:
817 @lilypond[verbatim,quote,relative=2]
825 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
826 {printing-metronome-and-rehearsal-marks-below-the-staff.ly}
828 @c perhaps also an example of how to move it horizontally?
830 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
831 {changing-the-tempo-without-a-metronome-mark.ly}
833 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
834 {creating-metronome-marks-in-markup-mode.ly}
836 For more details, see @ref{Formatting text}.
842 @rglos{metronomic indication},
843 @rglos{tempo indication},
844 @rglos{metronome mark}.
847 @ref{Formatting text},
851 @rlsr{Staff notation}.
854 @rinternals{MetronomeMark}.
857 @node Instrument names
858 @unnumberedsubsubsec Instrument names
860 @cindex instrument names
861 @cindex instrument names, short
863 Instrument names can be printed on the left side of staves in the
864 @code{Staff} and @code{PianoStaff} contexts. The value of
865 @code{instrumentName} is used for the first staff, and the value
866 of @code{shortInstrumentName} is used for all succeeding staves.
868 @lilypond[verbatim,quote,ragged-right,relative=1]
869 \set Staff.instrumentName = #"Violin "
870 \set Staff.shortInstrumentName = #"Vln "
876 Markup mode can be used to create more complicated instrument
879 @lilypond[verbatim,quote,relative=2]
880 \set Staff.instrumentName = \markup {
881 \column { "Clarinetti"
882 \line { "in B" \smaller \flat } } }
886 @cindex instrument names, centering
888 When two or more staff contexts are grouped together, the
889 instrument names and short instrument names are centered by
890 default. To center multi-line instrument names,
891 @code{\center-column} must be used:
893 @lilypond[verbatim,quote,indent=1.5\cm,relative=2]
896 \set Staff.instrumentName = #"Flute"
900 \set Staff.instrumentName = \markup \center-column {
902 \line { "in B" \smaller \flat }
912 However, if the instrument names are longer, the instrument names
913 in a staff group may not be centered unless the @code{indent} and
914 @code{short-indent} settings are increased. For details about
915 these settings, see @ref{Horizontal dimensions}.
917 @lilypond[verbatim,quote,ragged-right]
920 short-indent = 1.5\cm
925 \set Staff.instrumentName = #"Alto Flute in G"
926 \set Staff.shortInstrumentName = #"Fl."
931 \set Staff.instrumentName = #"Clarinet"
932 \set Staff.shortInstrumentName = #"Clar."
939 To add instrument names to other contexts (such as
940 @code{GrandStaff}, @code{ChoirStaff}, or @code{StaffGroup}),
941 @code{Instrument_name_engraver} must be added to that context.
942 For details, see @ref{Modifying context plug-ins}.
944 @cindex instrument names, changing
946 Instrument names may be changed in the middle of a piece:
948 @lilypond[verbatim,quote,ragged-right,relative=1]
949 \set Staff.instrumentName = #"First"
950 \set Staff.shortInstrumentName = #"one"
953 \set Staff.instrumentName = #"Second"
954 \set Staff.shortInstrumentName = #"two"
959 @cindex instrument switch
960 @cindex switching instruments
962 If an instrument @emph{switch} is needed,
963 @code{\addInstrumentDefinition} may be used in combination with
964 @code{\instrumentSwitch} to create a detailed list of the
965 necessary changes for the switch. The
966 @code{\addInstrumentDefinition} command has two arguments: an
967 identifying string, and an association list of context properties
968 and values to be used for the instrument. It must be placed in
969 the toplevel scope. @code{\instrumentSwitch} is used in the music
970 expression to declare the instrument switch:
972 @lilypond[verbatim,quote,ragged-right]
973 \addInstrumentDefinition #"contrabassoon"
974 #`((instrumentTransposition . ,(ly:make-pitch -1 0 0))
975 (shortInstrumentName . "Cbsn.")
976 (clefGlyph . "clefs.F")
977 (middleCPosition . 6)
979 (instrumentCueName . ,(make-bold-markup "cbsn."))
980 (midiInstrument . "bassoon"))
983 instrumentName = #"Bassoon"
987 \compressFullBarRests
990 \instrumentSwitch "contrabassoon"
999 @ref{Horizontal dimensions},
1000 @ref{Modifying context plug-ins}.
1003 @rlsr{Staff notation}.
1005 Internals Reference:
1006 @rinternals{InstrumentName},
1007 @rinternals{PianoStaff},
1011 @node Quoting other voices
1012 @unnumberedsubsubsec Quoting other voices
1015 @cindex quoting other voices
1019 It is very common for one voice to double some of the music from
1020 another voice. For example, the first and second violins may play the
1021 same notes during a passage of music. In LilyPond this is accomplished
1022 by letting one voice @emph{quote} the other voice without having to
1025 Before a part can be quoted, the @code{\addQuote} command must be used
1026 to initialize the quoted fragment. This command must be used in the
1027 toplevel scope. The first argument is an identifying string, and the
1028 second is a music expression:
1031 flute = \relative c'' @{
1034 \addQuote "flute" @{ \flute @}
1037 The @code{\quoteDuring} command is used to indicate the point where the
1038 quotation begins. It is followed by two arguments: the name of the
1039 quoted voice, as defined with @code{\addQuote}, and a music expression
1040 that indicates the duration of the quote, usually spacer rests or
1041 multi-measure rests. The corresponding music from the quoted voice is
1042 inserted into the music expression:
1044 @lilypond[verbatim,quote]
1045 flute = \relative c'' {
1048 \addQuote "flute" { \flute }
1051 c4 cis \quoteDuring #"flute" { s2 }
1055 If the music expression used for @code{\quoteDuring} contains
1056 anything but a spacer rest or multi-measure rest, a polyphonic
1057 situation is created, which is often not desirable:
1059 @lilypond[verbatim,quote]
1060 flute = \relative c'' {
1063 \addQuote "flute" { \flute }
1066 c4 cis \quoteDuring #"flute" { c4 b }
1070 Quotations recognize instrument transposition settings for both
1071 the source and target instruments if the @code{\transposition}
1072 command is used. For details about @code{\transposition}, see
1073 @ref{Instrument transpositions}.
1075 @lilypond[verbatim,quote]
1076 clarinet = \relative c'' {
1080 \addQuote "clarinet" { \clarinet }
1083 c4 cis \quoteDuring #"clarinet" { s2 }
1087 It is possible to tag quotations with unique names in order to
1088 process them in different ways. For details about this procedure,
1089 see @ref{Using tags}.
1094 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
1095 {quoting-another-voice-with-transposition.ly}
1098 @cindex articulation-event
1099 @cindex dynamic-event
1101 @funindex quotedEventTypes
1103 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
1104 {quoting-another-voice.ly}
1109 @ref{Instrument transpositions},
1113 @rlsr{Staff notation}.
1115 Internals Reference:
1116 @rinternals{QuoteMusic},
1122 Only the contents of the first @code{Voice} occurring in an
1123 @code{\addQuote} command will be considered for quotation, so
1124 @var{music} cannot contain @code{\new} and @code{\context Voice}
1125 statements that would switch to a different Voice.
1127 Quoting grace notes is broken and can even cause LilyPond to
1130 Quoting nested triplets may result in poor notation.
1132 In earlier versions of LilyPond (pre 2.11), @code{addQuote} was
1133 written entirely in lower-case letters: @code{\addquote}.
1136 @node Formatting cue notes
1137 @unnumberedsubsubsec Formatting cue notes
1141 @cindex cue notes, formatting
1143 @cindex quoting other voices
1144 @cindex cues, formatting
1146 The previous section explains how to create quotations. The
1147 @code{\cueDuring} command is a more specialized form of
1148 @code{\quoteDuring}, being particularly useful for inserting cue
1149 notes into a part. The syntax is as follows:
1152 \cueDuring #@var{partname} #@var{voice} @var{music}
1155 This command copies the corresponding measures from @var{partname}
1156 into a @code{CueVoice} context. The @code{CueVoice} is created
1157 implicitly, and occurs simultaneously with @var{music}, which
1158 creates a polyphonic situation. The @var{voice} argument
1159 determines whether the cue notes should be notated as a first or
1160 second voice; @code{UP} corresponds to the first voice, and
1161 @code{DOWN} corresponds to the second.
1163 @lilypond[verbatim,quote]
1164 oboe = \relative c'' {
1168 \addQuote "oboe" { \oboe }
1170 \new Voice \relative c'' {
1171 \cueDuring #"oboe" #UP { R1 }
1177 In the above example, the @code{Voice} context had to be
1178 explicitly declared, or else the entire music expression would
1179 belong to the @code{CueVoice} context.
1181 The name of the cued instrument can be printed by setting the
1182 @code{instrumentCueName} property in the @code{CueVoice} context.
1184 @lilypond[verbatim,quote]
1185 oboe = \relative c''' {
1188 \addQuote "oboe" { \oboe }
1190 \new Staff \relative c'' <<
1191 \new CueVoice \with {
1192 instrumentCueName = "ob."
1195 \cueDuring #"oboe" #UP { R1 }
1201 In addition to printing the name of the cued instrument, when cue
1202 notes end, the name of the original instrument should be printed,
1203 and any other changes introduced by the cued part should be
1204 undone. This can be accomplished by using
1205 @code{\addInstrumentDefinition} and @code{\instrumentSwitch}. For
1206 an example and explanation, see @ref{Instrument names}.
1208 The @code{\killCues} command removes cue notes from a music
1209 expression. This can be useful if cue notes need to be removed
1210 from a part but may be restored at a later time.
1212 @lilypond[verbatim,quote]
1213 flute = \relative c''' {
1216 \addQuote "flute" { \flute }
1218 \new Voice \relative c'' {
1220 \cueDuring #"flute" #UP { R1 }
1226 The @code{\transposedCueDuring} command is useful for adding
1227 instrumental cues from a completely different register. The
1228 syntax is similar to @code{\cueDuring}, but it requires one extra
1229 argument to specify the transposition of the cued instrument. For
1230 more information about transposition, see
1231 @ref{Instrument transpositions}.
1233 @lilypond[verbatim,quote]
1234 piccolo = \relative c''' {
1240 \addQuote "piccolo" { \piccolo }
1242 cbassoon = \relative c, {
1245 \transposedCueDuring #"piccolo" #UP c,, { R1 }
1250 \new Staff = "piccolo" \piccolo
1251 \new Staff = "cbassoon" \cbassoon
1255 It is possible to tag cued parts with unique names in order to
1256 process them in different ways. For details about this procedure,
1257 see @ref{Using tags}.
1262 @ref{Instrument transpositions},
1263 @ref{Instrument names},
1267 @rlsr{Staff notation}.
1269 Internals Reference:
1270 @rinternals{CueVoice},
1276 Collisions can occur with rests, when using @code{\cueDuring},
1277 between @code{Voice} and @code{CueVoice} contexts.