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::
41 @node Instantiating new staves
42 @unnumberedsubsubsec Instantiating new staves
45 @cindex staff initiation
46 @cindex staff instantiation
50 @cindex staff, percussion
52 @cindex percussion staff
53 @cindex Gregorian transcription staff
54 @cindex rhythmic staff
61 @funindex RhythmicStaff
63 @funindex MensuralStaff
64 @funindex VaticanaStaff
65 @funindex GregorianTranscriptionStaff
67 @notation{Staves} (singular: @notation{staff}) are created with
68 the @code{\new} or @code{\context} commands. For details, see
69 @ref{Creating contexts}.
71 The basic staff context is @code{Staff}:
73 @lilypond[verbatim,quote,relative=2]
74 \new Staff { c4 d e f }
77 The @code{DrumStaff} context creates a five-line staff set up for
78 a typical drum set. Each instrument is shown with a different
79 symbol. The instruments are entered in drum mode following a
80 @code{\drummode} command, with each instrument specified by name.
81 For details, see @ref{Percussion staves}.
83 @lilypond[verbatim,quote]
85 \drummode { cymc hh ss tomh }
89 @code{RhythmicStaff} creates a single-line staff that only
90 displays the rhythmic values of the input. Real durations are
91 preserved. For details, see @ref{Showing melody rhythms}.
93 @lilypond[verbatim,quote,relative=2]
94 \new RhythmicStaff { c4 d e f }
97 @code{TabStaff} creates a tablature with six strings in standard
98 guitar tuning. For details, see @ref{Default tablatures}.
100 @lilypond[verbatim,quote,relative=2]
101 \new TabStaff { c4 d e f }
104 There are two staff contexts specific for the notation of ancient
105 music: @code{MensuralStaff} and @code{VaticanaStaff}. They are
106 described in @ref{Pre-defined contexts}.
108 The @code{GregorianTranscriptionStaff} context creates a staff to
109 notate modern Gregorian chant. It does not show bar lines.
111 @lilypond[verbatim,quote,relative=2]
112 \new GregorianTranscriptionStaff { c4 d e f e d }
115 New single staff contexts may be defined. For details, see
116 @ref{Defining new contexts}.
125 @ref{Creating contexts},
126 @ref{Percussion staves},
127 @ref{Showing melody rhythms},
128 @ref{Default tablatures},
129 @ref{Pre-defined contexts},
131 @ref{Gregorian chant contexts},
132 @ref{Mensural contexts},
133 @ref{Defining new contexts}.
136 @rlsr{Staff notation}.
140 @rinternals{DrumStaff},
141 @rinternals{GregorianTranscriptionStaff},
142 @rinternals{RhythmicStaff},
143 @rinternals{TabStaff},
144 @rinternals{MensuralStaff},
145 @rinternals{VaticanaStaff},
146 @rinternals{StaffSymbol}.
149 @node Grouping staves
150 @unnumberedsubsubsec Grouping staves
152 @cindex start of system
153 @cindex staff, multiple
154 @cindex staves, multiple
155 @cindex system start delimiters
156 @cindex bracket, vertical
157 @cindex brace, vertical
167 Various contexts exist to group single staves together in order to
168 form multi-stave systems. Each grouping context sets the style of
169 the system start delimiter and the behavior of bar lines.
171 If no context is specified, the default properties will be used:
172 the group is started with a vertical line, and the bar lines are
175 @lilypond[verbatim,quote,relative=2]
182 In the @code{StaffGroup} context, the group is started with a
183 bracket and bar lines are drawn through all the staves.
185 @lilypond[verbatim,quote,relative=2]
192 In a @code{ChoirStaff}, the group starts with a bracket, but bar
193 lines are not connected.
195 @lilypond[verbatim,quote,relative=2]
202 In a @code{GrandStaff}, the group begins with a brace, and bar
203 lines are connected between the staves.
205 @lilypond[verbatim,quote,relative=2]
212 The @code{PianoStaff} is identical to a @code{GrandStaff}, except
213 that it supports printing the instrument name directly. For
214 details, see @ref{Instrument names}.
216 @lilypond[verbatim,quote,relative=2]
218 \set PianoStaff.instrumentName = #"Piano"
224 Each staff group context sets the property
225 @code{systemStartDelimiter} to one of the following values:
226 @code{SystemStartBar}, @code{SystemStartBrace}, or
227 @code{SystemStartBracket}. A fourth delimiter,
228 @code{SystemStartSquare}, is also available, but it must be
229 explicitly specified.
231 New staff group contexts may be defined. For details, see
232 @ref{Defining new contexts}.
237 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
238 {use-square-bracket-at-the-start-of-a-staff-group.ly}
240 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
241 {display-bracket-with-only-one-staff-in-a-system.ly}
243 @cindex mensurstriche layout
244 @cindex renaissance music
245 @cindex transcription of mensural music
246 @cindex mensural music, transcription of
248 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
249 {mensurstriche-layout-bar-lines-between-the-staves.ly}
259 @ref{Instrument names},
260 @ref{Defining new contexts}.
263 @rlsr{Staff notation}.
267 @rinternals{StaffGroup},
268 @rinternals{ChoirStaff},
269 @rinternals{GrandStaff},
270 @rinternals{PianoStaff},
271 @rinternals{SystemStartBar},
272 @rinternals{SystemStartBrace},
273 @rinternals{SystemStartBracket},
274 @rinternals{SystemStartSquare}.
277 @node Nested staff groups
278 @unnumberedsubsubsec Nested staff groups
280 @cindex staff, nested
281 @cindex staves, nested
282 @cindex nesting of staves
283 @cindex system start delimiters, nested
284 @cindex nested staff brackets
285 @cindex brackets, nesting of
286 @cindex braces, nesting of
288 Staff-group contexts can be nested to arbitrary depths. In this
289 case, each child context creates a new bracket adjacent to the
290 bracket of its parent group.
292 @lilypond[verbatim,quote,relative=2]
294 \new Staff { c2 c | c2 c }
296 \new Staff { g2 g | g2 g }
297 \new StaffGroup \with {
298 systemStartDelimiter = #'SystemStartSquare
301 \new Staff { e2 e | e2 e }
302 \new Staff { c2 c | c2 c }
308 New nested staff group contexts can be defined. For details, see
309 @ref{Defining new contexts}.
314 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
320 @ref{Grouping staves},
321 @ref{Instrument names},
322 @ref{Defining new contexts}.
325 @rlsr{Staff notation}.
328 @rinternals{StaffGroup},
329 @rinternals{ChoirStaff},
330 @rinternals{SystemStartBar},
331 @rinternals{SystemStartBrace},
332 @rinternals{SystemStartBracket},
333 @rinternals{SystemStartSquare}.
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 staff symbol, drawing
358 @cindex stop staff lines
359 @cindex start staff lines
360 @cindex staff lines, amount of
361 @cindex staff lines, number of
362 @cindex staff line, thickness of
363 @cindex amount of staff lines
364 @cindex thickness of staff lines
365 @cindex ledger lines, setting
366 @cindex setting of ledger lines
367 @cindex spacing of ledger lines
368 @cindex number of staff lines
370 The lines of a staff belong to the @code{StaffSymbol} grob.
371 @code{StaffSymbol} properties can be modified to change the
372 appearance of a staff, but they must be modified before the staff
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 StaffSymbol #'line-count = #3
387 Staff line thickness can be modified. The thickness of ledger
388 lines and stems are also affected, since they depend on staff line
391 @lilypond[verbatim,quote,relative=1]
393 \override StaffSymbol #'thickness = #3
398 Ledger line thickness can be set independently of staff line
399 thickness. In the example the two numbers are factors multiplying
400 the staff line thickness and the staff line spacing. The two
401 contributions are added to give the ledger line thickness.
403 @lilypond[verbatim,quote,relative=1]
405 \override StaffSymbol #'ledger-line-thickness = #'(1 . 0.2)
410 The distance between staff lines can be changed. This setting
411 affects the spacing of ledger lines as well.
413 @lilypond[verbatim,quote,relative=1]
415 \override StaffSymbol #'staff-space = #1.5
420 Further details about the properties of @code{StaffSymbol} can be
421 found in @rinternals{staff-symbol-interface}.
423 @cindex stopping a staff
424 @cindex starting a staff
425 @cindex staff, starting
426 @cindex staff, stopping
428 @funindex \startStaff
433 Modifications to staff properties in the middle of a score can be
434 placed between @code{\stopStaff} and @code{\startStaff}:
436 @lilypond[verbatim,quote,relative=2]
439 \override Staff.StaffSymbol #'line-count = #2
443 \revert Staff.StaffSymbol #'line-count
449 In general, @code{\startStaff} and @code{\stopStaff} can be used
450 to stop or start a staff in the middle of a score.
452 @lilypond[verbatim,quote,relative=2]
469 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
470 {making-some-staff-lines-thicker-than-the-others.ly}
483 @rlsr{Staff notation}.
486 @rinternals{StaffSymbol},
487 @rinternals{staff-symbol-interface}.
491 @unnumberedsubsubsec Ossia staves
493 @cindex staff, Frenched
495 @cindex Frenched staves
496 @cindex staff, resizing of
497 @cindex resizing of staves
499 @funindex \startStaff
504 @notation{Ossia} staves can be set by creating a new simultaneous
505 staff in the appropriate location:
507 @lilypond[verbatim,quote]
508 \new Staff \relative c'' {
512 \new Staff { e4 d f e }
519 However, the above example is not what is usually desired. To
520 create ossia staves that are above the original staff, have no
521 time signature or clef, and have a smaller font size, tweaks must
522 be used. The Learning Manual describes a specific technique to
523 achieve this goal, beginning with
524 @rlearning{Nesting music expressions}.
526 The following example uses the @code{alignAboveContext} property
527 to align the ossia staff. This method is most appropriate when
528 only a few ossia staves are needed.
530 @lilypond[verbatim,quote]
531 \new Staff = main \relative c'' {
537 \remove "Time_signature_engraver"
538 alignAboveContext = #"main"
540 \override StaffSymbol #'staff-space = #(magstep -3)
541 \override StaffSymbol #'thickness = #(magstep -3)
550 If many isolated ossia staves are needed, creating an empty
551 @code{Staff} context with a specific @emph{context id} may be more
552 appropriate; the ossia staves may then be created by
553 @emph{calling} this context and using @code{\startStaff} and
554 @code{\stopStaff} at the desired locations. The benefits of this
555 method are more apparent if the piece is longer than the following
558 @lilypond[verbatim,quote,ragged-right]
560 \new Staff = ossia \with {
561 \remove "Time_signature_engraver"
562 \override Clef #'transparent = ##t
564 \override StaffSymbol #'staff-space = #(magstep -3)
565 \override StaffSymbol #'thickness = #(magstep -3)
569 \new Staff \relative c' {
573 \context Staff = ossia {
574 \startStaff e4 g8 f e2 \stopStaff
581 \context Staff = ossia {
582 \startStaff g4 e8 f g2 \stopStaff
591 Using the @code{\RemoveEmptyStaffContext} command to create ossia
592 staves may be used as an alternative. This method is most
593 convenient when ossia staves occur immediately following a line
594 break. For more information about
595 @code{\RemoveEmptyStaffContext}, see @ref{Hiding staves}.
597 @lilypond[verbatim,quote,ragged-right]
599 \new Staff = ossia \with {
600 \remove "Time_signature_engraver"
601 \override Clef #'transparent = ##t
603 \override StaffSymbol #'staff-space = #(magstep -3)
604 \override StaffSymbol #'thickness = #(magstep -3)
609 \new Staff \relative c' {
621 \RemoveEmptyStaffContext
622 \override VerticalAxisGroup #'remove-first = ##t
630 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
631 {vertically-aligning-ossias-and-lyrics.ly}
638 @rglos{Frenched staff}.
641 @rlearning{Nesting music expressions},
642 @rlearning{Size of objects},
643 @rlearning{Length and thickness of objects}.
649 @rlsr{Staff notation}.
652 @rinternals{StaffSymbol}.
656 @unnumberedsubsubsec Hiding staves
658 @cindex Frenched score
659 @cindex Frenched staff
660 @cindex staff, hiding
662 @cindex hiding of staves
665 @funindex \RemoveEmptyStaffContext
666 @funindex RemoveEmptyStaffContext
667 @funindex Staff_symbol_engraver
672 Staff lines can be hidden by removing the
673 @code{Staff_symbol_engraver} from the @code{Staff} context. As an
674 alternative, @code{\stopStaff} may be used.
676 @lilypond[verbatim,quote]
678 \remove "Staff_symbol_engraver"
680 \relative c''' { a8 f e16 d c b a2 }
684 Empty staves can be hidden by setting the
685 @code{\RemoveEmptyStaffContext} command in the @code{\layout}
686 block. In orchestral scores, this style is known as @q{Frenched
687 Score}. By default, this command hides and removes all empty
688 staves in a score except for those in the first system.
690 @warning{A staff is considered empty when it contains only
691 multi-measure rests, skips, spacer rests, or a combination of these
694 @lilypond[verbatim,quote,ragged-right]
697 \RemoveEmptyStaffContext
718 @code{\RemoveEmptyStaffContext} can also be used to create ossia
719 sections for a staff. For details, see @ref{Ossia staves}.
721 @cindex hiding ancient staves
722 @cindex hiding rhythmic staves
724 @funindex \RemoveEmptyStaffContext
725 @funindex RemoveEmptyStaffContext
726 @funindex \AncientRemoveEmptyStaffContext
727 @funindex AncientRemoveEmptyStaffContext
728 @funindex \RemoveEmptyRhythmicStaffContext
729 @funindex RemoveEmptyRhythmicStaffContext
731 The @code{\AncientRemoveEmptyStaffContext} command may be used to
732 hide empty staves in ancient music contexts. Similarly,
733 @code{\RemoveEmptyRhythmicStaffContext} may be used to hide empty
734 @code{RhythmicStaff} contexts.
738 @code{\RemoveEmptyStaffContext},
739 @code{\AncientRemoveEmptyStaffContext},
740 @code{\RemoveEmptyRhythmicStaffContext}.
746 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
747 {removing-the-first-empty-line.ly}
752 @rglos{Frenched staff}.
755 @rlearning{Visibility and color of objects}.
758 @ref{Changing context default settings},
762 @ref{Invisible rests},
763 @ref{Visibility of objects}.
766 @rlsr{Staff notation}.
769 @rinternals{ChordNames},
770 @rinternals{FiguredBass},
773 @rinternals{VerticalAxisGroup},
774 @rinternals{Staff_symbol_engraver}.
779 Removing @code{Staff_symbol_engraver} also hides bar lines. If
780 bar line visibility is forced, formatting errors may occur. In
781 this case, use the following overrides instead of removing the
785 \override StaffSymbol #'stencil = ##f
786 \override NoteHead #'no-ledgers = ##t
789 For the Known issues and warnings associated with
790 @code{\RemoveEmptyStaffContext} see @ref{Changing context default
794 @subsection Writing parts
796 This section explains how to insert tempo indications and
797 instrument names into a score. Methods to quote other voices and
798 format cue notes are also described.
802 * Quoting other voices::
803 * Formatting cue notes::
806 @node Instrument names
807 @unnumberedsubsubsec Instrument names
809 @cindex instrument names
810 @cindex instrument names, short
812 Instrument names can be printed on the left side of staves in the
813 @code{Staff} and @code{PianoStaff} contexts. The value of
814 @code{instrumentName} is used for the first staff, and the value
815 of @code{shortInstrumentName} is used for all succeeding staves.
817 @lilypond[verbatim,quote,ragged-right,relative=1]
818 \set Staff.instrumentName = #"Violin "
819 \set Staff.shortInstrumentName = #"Vln "
825 Markup mode can be used to create more complicated instrument
828 @lilypond[verbatim,quote,relative=2]
829 \set Staff.instrumentName = \markup {
830 \column { "Clarinetti"
831 \line { "in B" \smaller \flat } } }
835 @cindex instrument names, centering
837 When two or more staff contexts are grouped together, the
838 instrument names and short instrument names are centered by
839 default. To center multi-line instrument names,
840 @code{\center-column} must be used:
842 @lilypond[verbatim,quote,indent=1.5\cm,relative=2]
845 \set Staff.instrumentName = #"Flute"
849 \set Staff.instrumentName = \markup \center-column {
851 \line { "in B" \smaller \flat }
859 @funindex short-indent
861 However, if the instrument names are longer, the instrument names
862 in a staff group may not be centered unless the @code{indent} and
863 @code{short-indent} settings are increased. For details about
864 these settings, see @ref{Horizontal dimensions}.
866 @lilypond[verbatim,quote,ragged-right]
869 short-indent = 1.5\cm
874 \set Staff.instrumentName = #"Alto Flute in G"
875 \set Staff.shortInstrumentName = #"Fl."
880 \set Staff.instrumentName = #"Clarinet"
881 \set Staff.shortInstrumentName = #"Clar."
888 @cindex instrument names, adding to other contexts
890 To add instrument names to other contexts (such as
891 @code{GrandStaff}, @code{ChoirStaff}, or @code{StaffGroup}),
892 @code{Instrument_name_engraver} must be added to that context.
893 For details, see @ref{Modifying context plug-ins}.
895 @cindex instrument names, changing
896 @cindex changing instrument names
898 Instrument names may be changed in the middle of a piece.
899 However, remember that @code{instrumentName} will not be
900 displayed in the middle of the piece, as it only appears
903 @lilypond[verbatim,quote,ragged-right,relative=1]
904 \set Staff.instrumentName = #"First"
905 \set Staff.shortInstrumentName = #"one"
908 \set Staff.instrumentName = #"Second"
909 \set Staff.shortInstrumentName = #"two"
914 @cindex instrument switch
915 @cindex switching instruments
917 @funindex \addInstrumentDefinition
918 @funindex addInstrumentDefinition
919 @funindex \instrumentSwitch
920 @funindex instrumentSwitch
922 If an instrument @emph{switch} is needed,
923 @code{\addInstrumentDefinition} may be used in combination with
924 @code{\instrumentSwitch} to create a detailed list of the
925 necessary changes for the switch. The
926 @code{\addInstrumentDefinition} command has two arguments: an
927 identifying string, and an association list of context properties
928 and values to be used for the instrument. It must be placed in
929 the toplevel scope. @code{\instrumentSwitch} is used in the music
930 expression to declare the instrument switch:
932 @lilypond[verbatim,quote,ragged-right]
933 \addInstrumentDefinition #"contrabassoon"
934 #`((instrumentTransposition . ,(ly:make-pitch -1 0 0))
935 (shortInstrumentName . "Cbsn.")
936 (clefGlyph . "clefs.F")
937 (middleCPosition . 6)
939 (instrumentCueName . ,(make-bold-markup "cbsn."))
940 (midiInstrument . "bassoon"))
943 instrumentName = #"Bassoon"
947 \compressFullBarRests
950 \instrumentSwitch "contrabassoon"
959 @ref{Horizontal dimensions},
960 @ref{Modifying context plug-ins}.
963 @rlsr{Staff notation}.
966 @rinternals{InstrumentName},
967 @rinternals{PianoStaff},
971 @node Quoting other voices
972 @unnumberedsubsubsec Quoting other voices
975 @cindex quoting other voices
981 @funindex \quoteDuring
982 @funindex quoteDuring
983 @funindex \transposition
984 @funindex transposition
986 It is very common for one voice to double some of the music from
987 another voice. For example, the first and second violins may play the
988 same notes during a passage of music. In LilyPond this is accomplished
989 by letting one voice @emph{quote} the other voice without having to
992 Before a part can be quoted, the @code{\addQuote} command must be used
993 to initialize the quoted fragment. This command must be used in the
994 toplevel scope. The first argument is an identifying string, and the
995 second is a music expression:
998 flute = \relative c'' @{
1001 \addQuote "flute" @{ \flute @}
1004 The @code{\quoteDuring} command is used to indicate the point where the
1005 quotation begins. It is followed by two arguments: the name of the
1006 quoted voice, as defined with @code{\addQuote}, and a music expression
1007 that indicates the duration of the quote, usually spacer rests or
1008 multi-measure rests. The corresponding music (including all articulations,
1009 dynamics, markup, etc.) from the quoted voice is inserted into the music
1012 @lilypond[verbatim,quote]
1013 flute = \relative c'' {
1014 a4 gis g->\f gis^\markup{quoted}
1016 \addQuote "flute" { \flute }
1019 c4 cis \quoteDuring #"flute" { s2 }
1023 If the music expression used for @code{\quoteDuring} contains
1024 anything but a spacer rest or multi-measure rest, a polyphonic
1025 situation is created, which is often not desirable:
1027 @lilypond[verbatim,quote]
1028 flute = \relative c'' {
1031 \addQuote "flute" { \flute }
1034 c4 cis \quoteDuring #"flute" { c4 b }
1038 Quotations recognize instrument transposition settings for both
1039 the source and target instruments if the @code{\transposition}
1040 command is used. For details about @code{\transposition}, see
1041 @ref{Instrument transpositions}.
1043 @lilypond[verbatim,quote]
1044 clarinet = \relative c'' {
1048 \addQuote "clarinet" { \clarinet }
1051 c4 cis \quoteDuring #"clarinet" { s2 }
1055 It is possible to tag quotations with unique names in order to
1056 process them in different ways. For details about this procedure,
1057 see @ref{Using tags}.
1059 It is also possible to adjust which objects from the original voice are quoted
1060 by changing the @code{quotedEventTypes} property. By default, its value is
1061 @code{#'(StreamEvent)}, which means that everything is quoted. Setting it
1062 to e.g. @code{#'(note-event rest-event tie-event)} causes lilypond to quote
1063 only notes, rests and ties, but no articulations, markup or dynamics.
1065 @lilypond[verbatim,quote]
1066 clarinet = \relative c'' {
1067 a4 gis g->\f gis^\markup{quoted}
1069 \addQuote "clarinet" { \clarinet }
1072 \set Score.quotedEventTypes = #'(note-event rest-event tie-event)
1073 c4 cis \quoteDuring #"clarinet" { s2 }
1079 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
1080 {quoting-another-voice-with-transposition.ly}
1083 @cindex articulation-event
1084 @cindex dynamic-event
1087 @funindex quotedEventTypes
1088 @funindex quotedCueEventTypes
1090 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
1091 {quoting-another-voice.ly}
1096 @ref{Instrument transpositions},
1100 @rlsr{Staff notation}.
1102 Internals Reference:
1103 @rinternals{QuoteMusic},
1109 Only the contents of the first @code{Voice} occurring in an
1110 @code{\addQuote} command will be considered for quotation, so
1111 @var{music} cannot contain @code{\new} and @code{\context Voice}
1112 statements that would switch to a different Voice.
1114 Quoting grace notes is broken and can even cause LilyPond to
1117 Quoting nested triplets may result in poor notation.
1119 In earlier versions of LilyPond (pre 2.11), @code{addQuote} was
1120 written entirely in lower-case letters: @code{\addquote}.
1123 @node Formatting cue notes
1124 @unnumberedsubsubsec Formatting cue notes
1128 @cindex cue notes, formatting
1130 @cindex quoting other voices
1131 @cindex cues, formatting
1133 @funindex \cueDuring
1135 @funindex \quoteDuring
1136 @funindex quoteDuring
1138 The previous section explains how to create quotations. The
1139 @code{\cueDuring} command is a more specialized form of
1140 @code{\quoteDuring}, being particularly useful for inserting cue
1141 notes into a part. The syntax is as follows:
1144 \cueDuring #@var{partname} #@var{voice} @var{music}
1147 This command copies only the notes and rests from the corresponding measures
1148 from @var{partname} into a @code{CueVoice} context. The @code{CueVoice} is
1149 created implicitly, and occurs simultaneously with @var{music}, which
1150 creates a polyphonic situation. The @var{voice} argument
1151 determines whether the cue notes should be notated as a first or
1152 second voice; @code{UP} corresponds to the first voice, and
1153 @code{DOWN} corresponds to the second.
1155 @lilypond[verbatim,quote]
1156 oboe = \relative c'' {
1157 r2 r8 d16(\f f e g f a)
1160 \addQuote "oboe" { \oboe }
1162 \new Voice \relative c'' {
1163 \cueDuring #"oboe" #UP { R1 }
1169 In the above example, the @code{Voice} context had to be
1170 explicitly declared, or else the entire music expression would
1171 belong to the @code{CueVoice} context.
1173 It is possible to adjust which aspects of the music are quoted with
1174 @code{\cueDuring} by setting the @code{quotedCueEventTypes} property. Its
1175 default value is @code{#'(note-event rest-event tie-event beam-event
1176 tuplet-span-event)}, which means that only notes, rest, ties, beams and
1177 tuplets are quoted, but not articulations, dynamic marks, markup etc.
1179 @lilypond[verbatim,quote]
1180 oboe = \relative c'' {
1181 r2 r8 d16(\f f e g f a)
1184 \addQuote "oboe" { \oboe }
1186 \new Voice \relative c'' {
1187 \set Score.quotedCueEventTypes = #'(note-event rest-event tie-event
1188 beam-event tuplet-span-event
1189 dynamic-event slur-event)
1190 \cueDuring #"oboe" #UP { R1 }
1197 The name of the cued instrument can be printed by setting the
1198 @code{instrumentCueName} property in the @code{CueVoice} context.
1200 @lilypond[verbatim,quote]
1201 oboe = \relative c''' {
1204 \addQuote "oboe" { \oboe }
1206 \new Staff \relative c'' <<
1207 \new CueVoice \with {
1208 instrumentCueName = "ob."
1211 \cueDuring #"oboe" #UP { R1 }
1217 @cindex removing cues
1218 @cindex removing cue notes
1219 @cindex cue notes, removing
1223 @funindex \transposedCueDuring
1224 @funindex transposedCueDuring
1226 In addition to printing the name of the cued instrument, when cue
1227 notes end, the name of the original instrument should be printed,
1228 and any other changes introduced by the cued part should be
1229 undone. This can be accomplished by using
1230 @code{\addInstrumentDefinition} and @code{\instrumentSwitch}. For
1231 an example and explanation, see @ref{Instrument names}.
1233 The @code{\killCues} command removes cue notes from a music
1234 expression. This can be useful if cue notes need to be removed
1235 from a part but may be restored at a later time.
1237 @lilypond[verbatim,quote]
1238 flute = \relative c''' {
1241 \addQuote "flute" { \flute }
1243 \new Voice \relative c'' {
1245 \cueDuring #"flute" #UP { R1 }
1251 The @code{\transposedCueDuring} command is useful for adding
1252 instrumental cues from a completely different register. The
1253 syntax is similar to @code{\cueDuring}, but it requires one extra
1254 argument to specify the transposition of the cued instrument. For
1255 more information about transposition, see
1256 @ref{Instrument transpositions}.
1258 @lilypond[verbatim,quote]
1259 piccolo = \relative c''' {
1265 \addQuote "piccolo" { \piccolo }
1267 cbassoon = \relative c, {
1270 \transposedCueDuring #"piccolo" #UP c,, { R1 }
1275 \new Staff = "piccolo" \piccolo
1276 \new Staff = "cbassoon" \cbassoon
1280 It is possible to tag cued parts with unique names in order to
1281 process them in different ways. For details about this procedure,
1282 see @ref{Using tags}.
1284 @cindex notes, smaller
1285 @cindex smaller notes
1287 A @code{CueVoice} context may be created explicitly if notes of a
1288 smaller size are required, for example to set an alternative
1289 sequence of notes more suitable for a higher or lower voice.
1291 @lilypond[verbatim,relative=2]
1308 @ref{Instrument transpositions},
1309 @ref{Instrument names},
1313 @rlsr{Staff notation}.
1315 Internals Reference:
1316 @rinternals{CueVoice},
1322 Collisions can occur with rests, when using @code{\cueDuring},
1323 between @code{Voice} and @code{CueVoice} contexts.