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 @c The line width is a bit of a hack to allow space for the
17 @lilypondfile[quote,ragged-right,line-width=14.5\cm,staffsize=16]{staff-headword.ly}
19 This section explains how to influence the appearance of staves,
20 how to print scores with more than one staff, and how to add tempo
21 indications and cue notes to staves.
25 * Modifying single staves::
30 @node Displaying staves
31 @subsection Displaying staves
33 This section describes the different methods of creating and
37 * Instantiating new staves::
39 * Nested staff groups::
40 * Separating systems::
44 @node Instantiating new staves
45 @unnumberedsubsubsec Instantiating new staves
48 @cindex staff initiation
49 @cindex staff instantiation
53 @cindex staff, percussion
55 @cindex percussion staff
56 @cindex Gregorian transcription staff
57 @cindex rhythmic staff
64 @funindex RhythmicStaff
66 @funindex MensuralStaff
67 @funindex VaticanaStaff
68 @funindex GregorianTranscriptionStaff
70 @notation{Staves} (singular: @notation{staff}) are created with
71 the @code{\new} or @code{\context} commands. For details, see
72 @ref{Creating contexts}.
74 The basic staff context is @code{Staff}:
76 @lilypond[verbatim,quote,relative=2]
77 \new Staff { c4 d e f }
80 The @code{DrumStaff} context creates a five-line staff set up for
81 a typical drum set. Each instrument is shown with a different
82 symbol. The instruments are entered in drum mode following a
83 @code{\drummode} command, with each instrument specified by name.
84 For details, see @ref{Percussion staves}.
86 @lilypond[verbatim,quote]
88 \drummode { cymc hh ss tomh }
92 @code{RhythmicStaff} creates a single-line staff that only
93 displays the rhythmic values of the input. Real durations are
94 preserved. For details, see @ref{Showing melody rhythms}.
96 @lilypond[verbatim,quote,relative=2]
97 \new RhythmicStaff { c4 d e f }
100 @code{TabStaff} creates a tablature with six strings in standard
101 guitar tuning. For details, see @ref{Default tablatures}.
103 @lilypond[verbatim,quote,relative=2]
104 \new TabStaff { c4 d e f }
107 There are two staff contexts specific for the notation of ancient
108 music: @code{MensuralStaff} and @code{VaticanaStaff}. They are
109 described in @ref{Pre-defined contexts}.
111 The @code{GregorianTranscriptionStaff} context creates a staff to
112 notate modern Gregorian chant. It does not show bar lines.
114 @lilypond[verbatim,quote,relative=2]
115 \new GregorianTranscriptionStaff { c4 d e f e d }
118 New single staff contexts may be defined. For details, see
119 @ref{Defining new contexts}.
127 @ref{Creating contexts},
128 @ref{Percussion staves},
129 @ref{Showing melody rhythms},
130 @ref{Default tablatures},
131 @ref{Pre-defined contexts},
133 @ref{Gregorian chant contexts},
134 @ref{Mensural contexts},
135 @ref{Defining new contexts}.
138 @rlsr{Staff notation}.
142 @rinternals{DrumStaff},
143 @rinternals{GregorianTranscriptionStaff},
144 @rinternals{RhythmicStaff},
145 @rinternals{TabStaff},
146 @rinternals{MensuralStaff},
147 @rinternals{VaticanaStaff},
148 @rinternals{StaffSymbol}.
151 @node Grouping staves
152 @unnumberedsubsubsec Grouping staves
154 @cindex start of system
155 @cindex staff, multiple
156 @cindex staves, multiple
157 @cindex system start delimiters
158 @cindex bracket, vertical
159 @cindex brace, vertical
169 Various contexts exist to group single staves together in order to
170 form multi-stave systems. Each grouping context sets the style of
171 the system start delimiter and the behavior of bar lines.
173 If no context is specified, the default properties will be used:
174 the group is started with a vertical line, and the bar lines are
177 @lilypond[verbatim,quote,relative=2]
184 In the @code{StaffGroup} context, the group is started with a
185 bracket and bar lines are drawn through all the staves.
187 @lilypond[verbatim,quote,relative=2]
194 In a @code{ChoirStaff}, the group starts with a bracket, but bar
195 lines are not connected.
197 @lilypond[verbatim,quote,relative=2]
204 In a @code{GrandStaff}, the group begins with a brace, and bar
205 lines are connected between the staves.
207 @lilypond[verbatim,quote,relative=2]
214 The @code{PianoStaff} is identical to a @code{GrandStaff}, except
215 that it supports printing the instrument name directly. For
216 details, see @ref{Instrument names}.
218 @lilypond[verbatim,quote,relative=2]
220 \set PianoStaff.instrumentName = #"Piano"
226 Each staff group context sets the property
227 @code{systemStartDelimiter} to one of the following values:
228 @code{SystemStartBar}, @code{SystemStartBrace}, or
229 @code{SystemStartBracket}. A fourth delimiter,
230 @code{SystemStartSquare}, is also available, but it must be
231 explicitly specified.
233 New staff group contexts may be defined. For details, see
234 @ref{Defining new contexts}.
239 @lilypondfile[verbatim,quote,texidoc,doctitle]
240 {use-square-bracket-at-the-start-of-a-staff-group.ly}
242 @lilypondfile[verbatim,quote,texidoc,doctitle]
243 {display-bracket-with-only-one-staff-in-a-system.ly}
245 @cindex mensurstriche layout
246 @cindex renaissance music
247 @cindex transcription of mensural music
248 @cindex mensural music, transcription of
250 @lilypondfile[verbatim,quote,texidoc,doctitle]
251 {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]
323 @ref{Grouping staves},
324 @ref{Instrument names},
325 @ref{Defining new contexts}.
328 @rlsr{Staff notation}.
331 @rinternals{StaffGroup},
332 @rinternals{ChoirStaff},
333 @rinternals{SystemStartBar},
334 @rinternals{SystemStartBrace},
335 @rinternals{SystemStartBracket},
336 @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
408 @cindex staff lines, stopping and starting
409 @cindex staff lines, modifying
411 @cindex ledger lines, internal
412 @cindex ledger lines, modifying
414 @funindex \startStaff
419 The @code{\stopStaff} and @code{\startStaff} commands can be used to
420 stop or (re)start the staff lines respectively, from being printed at
421 any point witin a score.
423 @lilypond[verbatim,quote,relative=2]
424 \stopStaff f4 d \startStaff g, e
425 f'4 d \stopStaff g, e
426 f'4 d \startStaff g, e
434 The lines of a staff belong to the @code{StaffSymbol} grob (including
435 ledger lines) can be modified using @code{StaffSymbol} properties, but
436 these modifications must be made before the staff is (re)started.
438 The number of staff lines can be altered,
440 @lilypond[verbatim,quote,relative=2]
442 \override Staff.StaffSymbol #'line-count = #2
446 \revert Staff.StaffSymbol #'line-count
450 The position of each the staff lines can also be altered. The values
451 used are @emph{half} staff line spaces and the new position is relative
452 to the normal center line. A single staff line is printed for every
453 value entered so that the number of staff lines, as well as their
454 position in the staff, can be changed with a single override.
456 @lilypond[verbatim,quote,relative=2]
458 \override Staff.StaffSymbol #'line-positions = #'(1 3 5 -1 -3)
461 \override Staff.StaffSymbol #'line-positions = #'(8 6.5 -6 -8 -0.5)
465 The clef position and the position of middle C may need to be adjusted
466 accordingly to fit the new lines. See @ref{Clef}.
468 Staff line thickness can be altered. Ledger lines and note stems, by
469 default, are also affected.
471 @lilypond[verbatim,quote,relative=2]
473 \override StaffSymbol #'thickness = #3
478 However, it is possible to set ledger line thickness independently of
479 staff lines. The two values required multiply the staff line thickness
480 with the staff line spacing and are then added together to give the
481 ledger line thickness.
483 @lilypond[verbatim,quote,relative=2]
485 \override StaffSymbol #'thickness = #2
486 \override StaffSymbol #'ledger-line-thickness = #'(0.5 . 0.4)
491 The vertical positions of ledger lines can be altered,
493 @lilypond[verbatim,quote,relative=2]
495 \override StaffSymbol #'ledger-positions = #'(-3 -2 -1 2 5 6)
500 Additional ledger lines can be made to appear above or below note heads
501 depending on the current position relative to other note heads that
502 also have their own ledger lines.
504 @lilypond[verbatim,quote,relative=2]
506 \override StaffSymbol #'ledger-extra = #4
511 Legder lines can also be made to appear inside the staff where custom
512 staff lines are required. The example shows the default position of
513 ledger lines when the explicit @code{legder-position} is and is not set.
514 The @code{stopStaff} is needed in the example to revert the
515 @code{\override} for the whole @code{StaffSymbol}.
517 @lilypond[fragment,quote,relative=1]
518 \override Staff.StaffSymbol #'line-positions = #'(-8 0 2 4)
522 \override Staff.StaffSymbol #'ledger-positions = #'(-8 -6 (-4 -2) 0)
526 The distance between staff lines can be altered. This affects ledger
527 line spacing as well.
529 @lilypond[verbatim,quote,relative=2]
531 \override StaffSymbol #'staff-space = #1.5
537 @lilypondfile[verbatim,quote,texidoc,doctitle]
538 {making-some-staff-lines-thicker-than-the-others.ly}
550 @rlsr{Staff notation}.
553 @rinternals{StaffSymbol},
554 @rinternals{staff-symbol-interface}.
558 @unnumberedsubsubsec Ossia staves
560 @cindex staff, Frenched
562 @cindex Frenched staves
563 @cindex staff, resizing of
564 @cindex resizing of staves
566 @funindex \startStaff
571 @notation{Ossia} staves can be set by creating a new simultaneous
572 staff in the appropriate location:
574 @lilypond[verbatim,quote]
575 \new Staff \relative c'' {
579 \new Staff { e4 d f e }
586 However, the above example is not what is usually desired. To
587 create ossia staves that are above the original staff, have no
588 time signature or clef, and have a smaller font size, tweaks must
589 be used. The Learning Manual describes a specific technique to
590 achieve this goal, beginning with
591 @rlearning{Nesting music expressions}.
593 The following example uses the @code{alignAboveContext} property
594 to align the ossia staff. This method is most appropriate when
595 only a few ossia staves are needed.
597 @lilypond[verbatim,quote]
598 \new Staff = main \relative c'' {
604 \remove "Time_signature_engraver"
605 alignAboveContext = #"main"
607 \override StaffSymbol #'staff-space = #(magstep -3)
608 \override StaffSymbol #'thickness = #(magstep -3)
617 If many isolated ossia staves are needed, creating an empty
618 @code{Staff} context with a specific @emph{context id} may be more
619 appropriate; the ossia staves may then be created by
620 @emph{calling} this context and using @code{\startStaff} and
621 @code{\stopStaff} at the desired locations. The benefits of this
622 method are more apparent if the piece is longer than the following
625 @lilypond[verbatim,quote,ragged-right]
627 \new Staff = ossia \with {
628 \remove "Time_signature_engraver"
629 \override Clef #'transparent = ##t
631 \override StaffSymbol #'staff-space = #(magstep -3)
632 \override StaffSymbol #'thickness = #(magstep -3)
636 \new Staff \relative c' {
640 \context Staff = ossia {
641 \startStaff e4 g8 f e2 \stopStaff
648 \context Staff = ossia {
649 \startStaff g4 e8 f g2 \stopStaff
658 Using the @code{\Staff \RemoveEmptyStaves} command to create ossia
659 staves may be used as an alternative. This method is most
660 convenient when ossia staves occur immediately following a line
661 break. For more information about
662 @code{\Staff \RemoveEmptyStaves}, see @ref{Hiding staves}.
664 @lilypond[verbatim,quote,ragged-right]
666 \new Staff = ossia \with {
667 \remove "Time_signature_engraver"
668 \override Clef #'transparent = ##t
670 \override StaffSymbol #'staff-space = #(magstep -3)
671 \override StaffSymbol #'thickness = #(magstep -3)
676 \new Staff \relative c' {
688 \Staff \RemoveEmptyStaves
689 \override VerticalAxisGroup #'remove-first = ##t
697 @lilypondfile[verbatim,quote,texidoc,doctitle]
698 {vertically-aligning-ossias-and-lyrics.ly}
704 @rglos{Frenched staff}.
707 @rlearning{Nesting music expressions},
708 @rlearning{Size of objects},
709 @rlearning{Length and thickness of objects}.
715 @rlsr{Staff notation}.
718 @rinternals{StaffSymbol}.
722 @unnumberedsubsubsec Hiding staves
724 @cindex Frenched score
725 @cindex Frenched staff
726 @cindex staff, hiding
728 @cindex hiding of staves
731 @funindex \RemoveEmptyStaves
732 @funindex Staff_symbol_engraver
737 Staff lines can be hidden by removing the
738 @code{Staff_symbol_engraver} from the @code{Staff} context. As an
739 alternative, @code{\stopStaff} may be used.
741 @lilypond[verbatim,quote]
743 \remove "Staff_symbol_engraver"
745 \relative c''' { a8 f e16 d c b a2 }
749 Empty staves can be hidden by setting the
750 @code{\Staff \RemoveEmptyStaves} command in the @code{\layout}
751 block. In orchestral scores, this style is known as @q{Frenched
752 Score}. By default, this command hides and removes all empty
753 staves in a score except for those in the first system.
755 @warning{A staff is considered empty when it contains only
756 multi-measure rests, rests, skips, spacer rests, or a combination of these
759 @lilypond[verbatim,quote,ragged-right]
762 \Staff \RemoveEmptyStaves
783 @code{\Staff \RemoveEmptyStaves} can also be used to create ossia
784 sections for a staff. For details, see @ref{Ossia staves}.
786 @cindex hiding ancient staves
787 @cindex hiding rhythmic staves
789 @funindex \RemoveEmptyStaves
791 The @code{\VaticanaStaff \RemoveEmptyStaves} command may be used to
792 hide empty staves in ancient music contexts. Similarly,
793 @code{\RhythmicStaff \RemoveEmptyStaves} may be used to hide empty
794 @code{RhythmicStaff} contexts.
798 @code{\Staff \RemoveEmptyStaves},
799 @code{\VaticanaStaff \RemoveEmptyStaves},
800 @code{\RhythmicStaff \RemoveEmptyStaves}.
806 @lilypondfile[verbatim,quote,texidoc,doctitle]
807 {removing-the-first-empty-line.ly}
811 @rglos{Frenched staff}.
814 @rlearning{Visibility and color of objects}.
817 @ref{Changing context default settings},
821 @ref{Invisible rests},
822 @ref{Visibility of objects}.
825 @rlsr{Staff notation}.
828 @rinternals{ChordNames},
829 @rinternals{FiguredBass},
832 @rinternals{VerticalAxisGroup},
833 @rinternals{Staff_symbol_engraver}.
836 Removing @code{Staff_symbol_engraver} also hides bar lines. If
837 bar line visibility is forced, formatting errors may occur. In
838 this case, use the following overrides instead of removing the
842 \override StaffSymbol #'stencil = ##f
843 \override NoteHead #'no-ledgers = ##t
846 For the Known issues and warnings associated with
847 @code{\Staff \RemoveEmptyStaves} see
848 @ref{Changing context default settings}.
852 @subsection Writing parts
854 This section explains how to insert tempo indications and
855 instrument names into a score. Methods to quote other voices and
856 format cue notes are also described.
860 * Quoting other voices::
861 * Formatting cue notes::
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}, @code{PianoStaff}, @code{StaffGroup}, @code{GrandStaff}
872 and @code{ChoirStaff} contexts. The value of
873 @code{instrumentName} is used for the first staff, and the value
874 of @code{shortInstrumentName} is used for all succeeding staves.
876 @lilypond[verbatim,quote,ragged-right,relative=1]
878 instrumentName = #"Violin "
879 shortInstrumentName = #"Vln. "
881 { c4.. g'16 c4.. g'16 \break | c1 }
884 @cindex instrument names, complex
886 @code{\markup} can be used to create more complex instrument names:
888 @lilypond[verbatim,quote,relative=2]
890 instrumentName = \markup {
891 \column { "Clarinetti"
892 \line { "in B" \smaller \flat }
899 @cindex instrument names, centering
901 When two or more staff contexts are grouped together, the instrument
902 names and short instrument names are centered by default. To center
903 multi-line instrument names, @code{\center-column} must be used:
905 @lilypond[verbatim,quote,indent=1.5\cm,relative=2]
908 instrumentName = #"Flute"
912 instrumentName = \markup {
913 \center-column { "Clarinet" }
914 \line { "in B" \smaller \flat }
922 @funindex short-indent
924 However, if the instrument names are longer, the instrument names in a
925 staff group may not be centered unless the @code{indent} and
926 @code{short-indent} settings are increased. For details about these
927 settings, see @ref{\paper variables for shifts and indents}.
929 @lilypond[verbatim,quote,ragged-right]
933 instrumentName = #"Alto Flute in G"
934 shortInstrumentName = #"Flt."
941 instrumentName = #"Clarinet"
942 shortInstrumentName = #"Clar."
953 short-indent = 1.5\cm
957 @cindex instrument names, adding to other contexts
959 To add instrument names to other contexts (such as @code{ChordNames} or
960 @code{FiguredBass}), @code{Instrument_name_engraver} must be added to
961 that context. For details, see @ref{Modifying context plug-ins}.
963 @cindex instrument names, changing
964 @cindex changing instrument names
966 The @code{shortInstrumentName} may be changed in the middle of a piece.
967 However, only the first instance of @code{instrumentName} will be
968 printed and subsequent changes will be ignored:
970 @lilypond[verbatim,quote,ragged-right,relative=1]
972 instrumentName = #"Flute"
973 shortInstrumentName = #"Flt."
978 \set Staff.instrumentName = #"Clarinet"
979 \set Staff.shortInstrumentName = #"Clt."
985 @cindex instrument switch
986 @cindex switching instruments
988 @funindex \addInstrumentDefinition
989 @funindex addInstrumentDefinition
990 @funindex \instrumentSwitch
991 @funindex instrumentSwitch
993 If an instrument @emph{switch} is needed,
994 @code{\addInstrumentDefinition} may be used in combination with
995 @code{\instrumentSwitch} to create a detailed list of the
996 necessary changes for the switch. The
997 @code{\addInstrumentDefinition} command has two arguments: an
998 identifying string, and an association list of context properties
999 and values to be used for the instrument. It must be placed in
1000 the toplevel scope. @code{\instrumentSwitch} is used in the music
1001 expression to declare the instrument switch:
1003 @lilypond[verbatim,quote,ragged-right]
1004 \addInstrumentDefinition #"contrabassoon"
1005 #`((instrumentTransposition . ,(ly:make-pitch -1 0 0))
1006 (shortInstrumentName . "Cbsn.")
1007 (clefGlyph . "clefs.F")
1008 (middleCPosition . 6)
1010 (instrumentCueName . ,(make-bold-markup "cbsn."))
1011 (midiInstrument . "bassoon"))
1014 instrumentName = #"Bassoon"
1018 \compressFullBarRests
1021 \instrumentSwitch "contrabassoon"
1029 @ref{\paper variables for shifts and indents},
1030 @ref{Modifying context plug-ins}.
1033 @rlsr{Staff notation}.
1035 Internals Reference:
1036 @rinternals{InstrumentName},
1037 @rinternals{PianoStaff},
1041 @node Quoting other voices
1042 @unnumberedsubsubsec Quoting other voices
1044 @cindex quote, voices
1045 @cindex voices, quoting
1046 @cindex fragments, quoting
1051 @funindex \quoteDuring
1052 @funindex quoteDuring
1053 @funindex \transposition
1054 @funindex transposition
1056 It is very common for one voice to use the same notes as those from
1057 another voice. For example, first and second violins playing the same
1058 phrase during a particular passage of the music. This is done by
1059 letting one voice @emph{quote} the other, without having to re-enter the
1060 music all over again for the second voice.
1062 The @code{\addQuote} command, used in the top level scope, defines a
1063 stream of music from which fragments can be quoted.
1065 The @code{\quoteDuring} command is used to indicate the point where the
1066 quotation begins. It is followed by two arguments: the name of the
1067 quoted voice, as defined with @code{\addQuote}, and a music expression
1068 for the duration of the quote.
1070 @lilypond[verbatim,quote]
1071 fluteNotes = \relative c'' {
1072 a4 gis g gis | b4^"quoted" r8 ais\p a4( f)
1075 oboeNotes = \relative c'' {
1076 c4 cis c b \quoteDuring #"flute" { s1 }
1079 \addQuote "flute" { \fluteNotes }
1083 \new Staff \with { instrumentName = "Flute" } \fluteNotes
1084 \new Staff \with { instrumentName = "Oboe" } \oboeNotes
1089 If the music expression used in @code{\quoteDuring} contains notes
1090 instead of spacer or multimeasure rests then the quote will appear as
1091 polyphony and may produce unexpected results.
1093 @lilypond[verbatim,quote]
1094 fluteNotes = \relative c'' {
1095 a4 gis g gis | b4^"quoted" r8 ais\p a4( f)
1098 oboeNotes = \relative c'' {
1099 c4 cis c b \quoteDuring #"flute" { e4 r8 ais b4 a }
1102 \addQuote "flute" { \fluteNotes }
1106 \new Staff \with { instrumentName = "Flute" } \fluteNotes
1107 \new Staff \with { instrumentName = "Oboe" } \oboeNotes
1112 The @code{\quoteDuring} command uses the @code{\transposition} settings
1113 of both quoted and quoting parts to produce notes for the quoting part
1114 that have the same sounding pitch as those in the quoted part.
1116 @lilypond[verbatim,quote]
1117 clarinetNotes = \relative c'' {
1120 b4 ais a ais | cis4^"quoted" r8 bis\p b4( f)
1123 oboeNotes = \relative c'' {
1124 c4 cis c b \quoteDuring #"clarinet" { s1 }
1127 \addQuote "clarinet" { \clarinetNotes }
1132 \new Staff \with { instrumentName = "Clarinet" } \clarinetNotes
1133 \new Staff \with { instrumentName = "Oboe" } \oboeNotes
1139 @cindex articulation-event
1140 @cindex dynamic-event
1143 @cindex crescendo-event
1145 @funindex quotedEventTypes
1146 @funindex quotedCueEventTypes
1148 By default quoted music will include all articulations, dynamics,
1149 markups, etc., in the quoted expression. It is possible to choose which
1150 of these objects from the quoted music are displayed by using the
1151 @code{quotedEventTypes} context property.
1153 @lilypond[verbatim,quote]
1154 fluteNotes = \relative c'' {
1156 b4\<^"quoted" r8 ais a4\f( c->)
1159 oboeNotes = \relative c'' {
1161 \quoteDuring #"flute" { s1 }
1164 \addQuote "flute" { \fluteNotes }
1168 \set Score.quotedEventTypes = #'(note-event articulation-event
1169 crescendo-event rest-event
1170 slur-event dynamic-event)
1171 \new Staff \with { instrumentName = "Flute" } \fluteNotes
1172 \new Staff \with { instrumentName = "Oboe" } \oboeNotes
1177 Quotes can also be tagged, see @ref{Using tags}.
1181 @ref{Instrument transpositions},
1185 @file{scm/define-event-classes.scm}.
1188 @rlsr{Staff notation}.
1190 Internals Reference:
1191 @rinternals{Music classes},
1192 @rinternals{QuoteMusic},
1196 Only the contents of the first @code{Voice} occurring in an
1197 @code{\addQuote} command will be considered for quotation, so if the music
1198 expression contains @code{\new} or @code{\context Voice}
1199 statements, their contents will not be quoted. Quoting grace notes
1200 is unsupported and may cause LilyPond to crash whereas quoting nested
1201 triplets may result in poor notation.
1204 @node Formatting cue notes
1205 @unnumberedsubsubsec Formatting cue notes
1209 @cindex cue notes, formatting
1210 @cindex formatting, cue notes
1211 @cindex voices, quoting
1214 @funindex \cueDuring
1218 @funindex \cueDuringWithClef
1219 @funindex cueDuringWithClef
1220 @funindex \quoteDuring
1221 @funindex quoteDuring
1223 @cindex notes, smaller
1224 @cindex smaller notes
1227 The simplest way to format cue notes is to explicitly create a
1228 @code{CueVoice} context within the part.
1230 @lilypond[verbatim,relative=1]
1235 \stemUp d'8^"flute" c d e fis2
1241 The @code{\cueClef} command can also be used with an explict
1242 @code{CueVoice} context if a change of clef is required and will print
1243 an appropriately sized clef for the cue notes. The @code{\cueClefUnset}
1244 command can then be used to switch back to the original clef, again with
1245 an appropriately sized clef.
1247 @lilypond[verbatim,noragged-right,relative=1]
1251 { e2\rest r4. \cueClefUnset e,8 }
1253 \cueClef "treble" \stemUp d''8^"flute" c d e fis2
1259 The @code{\cueClef} and @code{\cueClefUnset} command can also be used
1260 without a @code{CueVoice} if required.
1262 @lilypond[verbatim,noragged-right,relative=1]
1266 d'8^"flute" c d e fis2
1271 For more complex cue note placement, e.g including transposition, or
1272 inserting cue notes from multiple music sources the @code{\cueDuring} or
1273 @code{\cueDuringWithClef} commands can be used. These are more
1274 specialized form of @code{\quoteDuring}, see @ref{Quoting other voices}
1275 in the previous section.
1280 \cueDuring #@var{quotename} #@var{direction} #@var{music}
1286 \cueDuringWithClef #@var{quotename} #@var{direction} #@var{clef} #@var{music}
1289 The music from the corresponding measures of the @code{@var{quote name}}
1290 is added as a @code{CueVoice} context and occurs simultaneously with the
1291 @code{@var{music}}, which then creates a polyphonic situation. The
1292 @code{@var{direction}} takes the argument @code{UP} or @code{DOWN}, and
1293 corresponds to the first and second voices respectively, determining how
1294 the cue notes are printed in relation to the other voice.
1296 @lilypond[verbatim,quote]
1297 fluteNotes = \relative c'' {
1298 r2. c4 | d8 c d e fis2 | g2 d |
1301 oboeNotes = \relative c'' {
1303 \new CueVoice { \set instrumentCueName = "flute" }
1304 \cueDuring #"flute" #UP { R1 }
1308 \addQuote "flute" { \fluteNotes }
1318 It is possible to adjust which aspects of the music are quoted with
1319 @code{\cueDuring} by setting the @code{quotedCueEventTypes}
1320 property. Its default value is @code{'(note-event rest-event
1321 tie-event beam-event tuplet-span-event)}, which means that only
1322 notes, rests, ties, beams and tuplets are quoted, but not
1323 articulations, dynamic marks, markup etc.
1325 @warning{When a @code{Voice} starts with @code{\cueDuring}, as in the
1326 following example, the @code{Voice} context must be explicitly declared,
1327 or else the entire music expression would belong to the @code{CueVoice}
1330 @lilypond[verbatim,quote]
1331 oboeNotes = \relative c'' {
1332 r2 r8 d16(\f f e g f a)
1335 \addQuote "oboe" { \oboeNotes }
1337 \new Voice \relative c'' {
1338 \set Score.quotedCueEventTypes = #'(note-event rest-event tie-event
1339 beam-event tuplet-span-event
1340 dynamic-event slur-event)
1341 \cueDuring #"oboe" #UP { R1 }
1346 The name of the instrument playing the cue can be printed by setting
1347 the @code{instrumentCueName} property in a temporary @code{CueVoice}
1348 context. The placement and style of the @code{instrumentCueName} is
1349 controlled by the @code{\instrumentSwitch} object, see
1350 @ref{Instrument names}. If the cue notes require a change in clef,
1351 this can be done manually but the original clef should also be
1352 restored manually at the end of the cue notes.
1354 @lilypond[verbatim,quote]
1355 fluteNotes = \relative c'' {
1356 r2. c4 d8 c d e fis2 g2 d2
1359 bassoonNotes = \relative c {
1363 \new CueVoice { \set instrumentCueName = "flute" }
1364 \cueDuring #"flute" #UP { R1 }
1369 \addQuote "flute" { \fluteNotes }
1376 Alternatively, the @code{\cueDuringWithClef} function can be used
1377 instead. This command takes an extra argument to specify the change of
1378 clef that needs to be printed for the cue notes but will automatically
1379 print the original clef once the cue notes have finished.
1381 @lilypond[verbatim,quote]
1382 fluteNotes = \relative c'' {
1383 r2. c4 d8 c d e fis2 g2 d2
1386 bassoonNotes = \relative c {
1389 \new CueVoice { \set instrumentCueName = "flute" }
1390 \cueDuringWithClef #"flute" #UP #"treble" { R1 }
1394 \addQuote "flute" { \fluteNotes }
1401 @funindex \transposedCueDuring
1402 @funindex transposedCueDuring
1404 Like @code{\quoteDuring}, @code{\cueDuring} takes instrument
1405 transpositions into account. Cue notes are produced at the
1406 pitches that would be written for the instrument receiving the cue
1407 to produce the sounding pitches of the source instrument.
1409 To transpose cue notes differently, use
1410 @code{\transposedCueDuring}. This command takes an extra argument
1411 to specify (in absolute mode) the printed pitch that you want to
1412 represent the sound of a concert middle C. This is useful for
1413 taking cues from an instrument in a completely different register.
1415 @lilypond[verbatim,quote]
1416 piccoloNotes = \relative c''' {
1423 bassClarinetNotes = \relative c' {
1427 \transposedCueDuring #"piccolo" #UP d { R1 }
1431 \addQuote "piccolo" { \piccoloNotes }
1434 \new Staff \piccoloNotes
1435 \new Staff \bassClarinetNotes
1439 @cindex removing cue notes
1440 @cindex cue notes, removing
1444 @funindex \addInstrumentDefinition
1445 @funindex addInstrumentDefinition
1447 The @code{\killCues} command removes cue notes from a music
1448 expression, so the same music expression can be used to produce
1449 the instrument part with cues and the score. The @code{\killCues}
1450 command removes only the notes and events that were quoted by
1451 @code{\cueDuring}. Other markup associated with cues, such as clef
1452 changes and a label identifying the source instrument, can be
1453 tagged for selective inclusion in the score; see @ref{Using tags}.
1455 @lilypond[verbatim,quote]
1456 fluteNotes = \relative c'' {
1457 r2. c4 d8 c d e fis2 g2 d2
1460 bassoonNotes = \relative c {
1465 \new CueVoice { \set instrumentCueName = "flute" }
1467 \cueDuring #"flute" #UP { R1 }
1468 \tag #'part \clef bass
1472 \addQuote "flute" { \fluteNotes }
1483 \removeWithTag #'part { \killCues { \bassoonNotes } }
1488 Alternatively, Clef changes and instrument labels can be
1489 collected into an instrument definition for repeated use, using
1490 @code{\addInstrumentDefinition} described in @ref{Instrument names}.
1494 @ref{Quoting other voices},
1495 @ref{Instrument transpositions},
1496 @ref{Instrument names},
1502 @rlsr{Staff notation}.
1504 Internals Reference:
1505 @rinternals{CueVoice},
1509 Collisions can occur with rests, when using @code{\cueDuring},
1510 between @code{Voice} and @code{CueVoice} contexts. When using
1511 @code{\cueDuringWithClef} or @code{\transposedCueDuring} the extra
1512 argument required for each case must come after the quote and the