]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/notation/staff.itely
Doc: [de] Append -de to weblink macros. Fixes web link translations.
[lilypond.git] / Documentation / notation / staff.itely
1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @ignore
3     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
4
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..
8 @end ignore
9
10 @c \version "2.12.0"
11
12 @node Staff notation
13 @section Staff notation
14
15 @lilypondfile[quote]{staff-headword.ly}
16
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.
20
21 @menu
22 * Displaying staves::
23 * Modifying single staves::
24 * Writing parts::
25 @end menu
26
27
28 @node Displaying staves
29 @subsection Displaying staves
30
31 This section describes the different methods of creating and
32 grouping staves.
33
34 @menu
35 * Instantiating new staves::
36 * Grouping staves::
37 * Nested staff groups::
38 @end menu
39
40
41 @node Instantiating new staves
42 @unnumberedsubsubsec Instantiating new staves
43
44 @cindex new staff
45 @cindex staff initiation
46 @cindex staff instantiation
47 @cindex staff, new
48 @cindex staff, single
49 @cindex staff, drum
50 @cindex staff, percussion
51 @cindex drum staff
52 @cindex percussion staff
53 @cindex Gregorian transcription staff
54 @cindex rhythmic staff
55 @cindex tabstaff
56 @cindex tablature
57
58 @funindex \drummode
59 @funindex drummode
60 @funindex DrumStaff
61 @funindex RhythmicStaff
62 @funindex TabStaff
63 @funindex MensuralStaff
64 @funindex VaticanaStaff
65 @funindex GregorianTranscriptionStaff
66
67 @notation{Staves} (singular: @notation{staff}) are created with
68 the @code{\new} or @code{\context} commands.  For details, see
69 @ref{Creating contexts}.
70
71 The basic staff context is @code{Staff}:
72
73 @lilypond[verbatim,quote,relative=2]
74 \new Staff { c4 d e f }
75 @end lilypond
76
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}.
82
83 @lilypond[verbatim,quote]
84 \new DrumStaff {
85   \drummode { cymc hh ss tomh }
86 }
87 @end lilypond
88
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}.
92
93 @lilypond[verbatim,quote,relative=2]
94 \new RhythmicStaff { c4 d e f }
95 @end lilypond
96
97 @code{TabStaff} creates a tablature with six strings in standard
98 guitar tuning.  For details, see @ref{Default tablatures}.
99
100 @lilypond[verbatim,quote,relative=2]
101 \new TabStaff { c4 d e f }
102 @end lilypond
103
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}.
107
108 The @code{GregorianTranscriptionStaff} context creates a staff to
109 notate modern Gregorian chant.  It does not show bar lines.
110
111 @lilypond[verbatim,quote,relative=2]
112 \new GregorianTranscriptionStaff { c4 d e f e d }
113 @end lilypond
114
115 New single staff contexts may be defined.  For details, see
116 @ref{Defining new contexts}.
117
118
119 @seealso
120 Music Glossary:
121 @rglos{staff},
122 @rglos{staves}.
123
124 Notation Reference:
125 @ref{Creating contexts},
126 @ref{Percussion staves},
127 @ref{Showing melody rhythms},
128 @ref{Default tablatures},
129 @ref{Pre-defined contexts},
130 @ref{Staff symbol},
131 @ref{Gregorian chant contexts},
132 @ref{Mensural contexts},
133 @ref{Defining new contexts}.
134
135 Snippets:
136 @rlsr{Staff notation}.
137
138 Internals Reference:
139 @rinternals{Staff},
140 @rinternals{DrumStaff},
141 @rinternals{GregorianTranscriptionStaff},
142 @rinternals{RhythmicStaff},
143 @rinternals{TabStaff},
144 @rinternals{MensuralStaff},
145 @rinternals{VaticanaStaff},
146 @rinternals{StaffSymbol}.
147
148
149 @node Grouping staves
150 @unnumberedsubsubsec Grouping staves
151
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
158 @cindex choir staff
159 @cindex grand staff
160 @cindex piano staff
161 @cindex staff group
162 @cindex staff, choir
163 @cindex staff, piano
164 @cindex staff, grand
165 @cindex system
166
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.
170
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
173 not connected.
174
175 @lilypond[verbatim,quote,relative=2]
176 <<
177   \new Staff { c1 c }
178   \new Staff { c1 c }
179 >>
180 @end lilypond
181
182 In the @code{StaffGroup} context, the group is started with a
183 bracket and bar lines are drawn through all the staves.
184
185 @lilypond[verbatim,quote,relative=2]
186 \new StaffGroup <<
187   \new Staff { c1 c }
188   \new Staff { c1 c }
189 >>
190 @end lilypond
191
192 In a @code{ChoirStaff}, the group starts with a bracket, but bar
193 lines are not connected.
194
195 @lilypond[verbatim,quote,relative=2]
196 \new ChoirStaff <<
197   \new Staff { c1 c }
198   \new Staff { c1 c }
199 >>
200 @end lilypond
201
202 In a @code{GrandStaff}, the group begins with a brace, and bar
203 lines are connected between the staves.
204
205 @lilypond[verbatim,quote,relative=2]
206 \new GrandStaff <<
207   \new Staff { c1 c }
208   \new Staff { c1 c }
209 >>
210 @end lilypond
211
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}.
215
216 @lilypond[verbatim,quote,relative=2]
217 \new PianoStaff <<
218   \set PianoStaff.instrumentName = #"Piano"
219   \new Staff { c1 c }
220   \new Staff { c1 c }
221 >>
222 @end lilypond
223
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.
230
231 New staff group contexts may be defined.  For details, see
232 @ref{Defining new contexts}.
233
234
235 @snippets
236
237 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
238 {use-square-bracket-at-the-start-of-a-staff-group.ly}
239
240 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
241 {display-bracket-with-only-one-staff-in-a-system.ly}
242
243 @cindex mensurstriche layout
244 @cindex renaissance music
245 @cindex transcription of mensural music
246 @cindex mensural music, transcription of
247
248 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
249 {mensurstriche-layout-bar-lines-between-the-staves.ly}
250
251
252 @seealso
253 Music Glossary:
254 @rglos{brace},
255 @rglos{bracket},
256 @rglos{grand staff}.
257
258 Notation Reference:
259 @ref{Instrument names},
260 @ref{Defining new contexts}.
261
262 Snippets:
263 @rlsr{Staff notation}.
264
265 Internals Reference:
266 @rinternals{Staff},
267 @rinternals{StaffGroup},
268 @rinternals{ChoirStaff},
269 @rinternals{GrandStaff},
270 @rinternals{PianoStaff},
271 @rinternals{SystemStartBar},
272 @rinternals{SystemStartBrace},
273 @rinternals{SystemStartBracket},
274 @rinternals{SystemStartSquare}.
275
276
277 @node Nested staff groups
278 @unnumberedsubsubsec Nested staff groups
279
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
287
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.
291
292 @lilypond[verbatim,quote,relative=2]
293 \new StaffGroup <<
294   \new Staff { c2 c | c2 c }
295   \new StaffGroup <<
296     \new Staff { g2 g | g2 g }
297     \new StaffGroup \with {
298       systemStartDelimiter = #'SystemStartSquare
299     }
300     <<
301       \new Staff { e2 e | e2 e }
302       \new Staff { c2 c | c2 c }
303     >>
304   >>
305 >>
306 @end lilypond
307
308 New nested staff group contexts can be defined.  For details, see
309 @ref{Defining new contexts}.
310
311
312 @snippets
313
314 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
315 {nesting-staves.ly}
316
317
318 @seealso
319 Notation Reference:
320 @ref{Grouping staves},
321 @ref{Instrument names},
322 @ref{Defining new contexts}.
323
324 Snippets:
325 @rlsr{Staff notation}.
326
327 Internals Reference:
328 @rinternals{StaffGroup},
329 @rinternals{ChoirStaff},
330 @rinternals{SystemStartBar},
331 @rinternals{SystemStartBrace},
332 @rinternals{SystemStartBracket},
333 @rinternals{SystemStartSquare}.
334
335
336 @node Modifying single staves
337 @subsection Modifying single staves
338
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.
343
344 @menu
345 * Staff symbol::
346 * Ossia staves::
347 * Hiding staves::
348 @end menu
349
350
351 @node Staff symbol
352 @unnumberedsubsubsec Staff symbol
353
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
369
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
373 is created.
374
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
378 @ref{Clef}.
379
380 @lilypond[verbatim,quote,relative=2]
381 \new Staff \with {
382   \override StaffSymbol #'line-count = #3
383 }
384 { d4 d d d }
385 @end lilypond
386
387 Staff line thickness can be modified.  The thickness of ledger
388 lines and stems are also affected, since they depend on staff line
389 thickness.
390
391 @lilypond[verbatim,quote,relative=1]
392 \new Staff \with {
393   \override StaffSymbol #'thickness = #3
394 }
395 { e4 d c b }
396 @end lilypond
397
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.
402
403 @lilypond[verbatim,quote,relative=1]
404 \new Staff \with {
405   \override StaffSymbol #'ledger-line-thickness = #'(1 . 0.2)
406 }
407 { e4 d c b }
408 @end lilypond
409
410 The distance between staff lines can be changed.  This setting
411 affects the spacing of ledger lines as well.
412
413 @lilypond[verbatim,quote,relative=1]
414 \new Staff \with {
415   \override StaffSymbol #'staff-space = #1.5
416 }
417 { a4 b c d }
418 @end lilypond
419
420 Further details about the properties of @code{StaffSymbol} can be
421 found in @rinternals{staff-symbol-interface}.
422
423 @cindex stopping a staff
424 @cindex starting a staff
425 @cindex staff, starting
426 @cindex staff, stopping
427
428 @funindex \startStaff
429 @funindex startStaff
430 @funindex \stopStaff
431 @funindex stopStaff
432
433 Modifications to staff properties in the middle of a score can be
434 placed between @code{\stopStaff} and @code{\startStaff}:
435
436 @lilypond[verbatim,quote,relative=2]
437 c2 c
438 \stopStaff
439 \override Staff.StaffSymbol #'line-count = #2
440 \startStaff
441 b2 b
442 \stopStaff
443 \revert Staff.StaffSymbol #'line-count
444 \startStaff
445 a2 a
446 @end lilypond
447
448 @noindent
449 In general, @code{\startStaff} and @code{\stopStaff} can be used
450 to stop or start a staff in the middle of a score.
451
452 @lilypond[verbatim,quote,relative=2]
453 c4 b a2
454 \stopStaff
455 b4 c d2
456 \startStaff
457 e4 d c2
458 @end lilypond
459
460
461 @predefined
462 @code{\startStaff},
463 @code{\stopStaff}.
464 @endpredefined
465
466
467 @snippets
468
469 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
470 {making-some-staff-lines-thicker-than-the-others.ly}
471
472
473 @seealso
474 Music Glossary:
475 @rglos{line},
476 @rglos{ledger line},
477 @rglos{staff}.
478
479 Notation Reference:
480 @ref{Clef}.
481
482 Snippets:
483 @rlsr{Staff notation}.
484
485 Internals Reference:
486 @rinternals{StaffSymbol},
487 @rinternals{staff-symbol-interface}.
488
489
490 @node Ossia staves
491 @unnumberedsubsubsec Ossia staves
492
493 @cindex staff, Frenched
494 @cindex ossia
495 @cindex Frenched staves
496 @cindex staff, resizing of
497 @cindex resizing of staves
498
499 @funindex \startStaff
500 @funindex startStaff
501 @funindex \stopStaff
502 @funindex stopStaff
503
504 @notation{Ossia} staves can be set by creating a new simultaneous
505 staff in the appropriate location:
506
507 @lilypond[verbatim,quote]
508 \new Staff \relative c'' {
509   c4 b d c
510   <<
511     { c4 b d c }
512     \new Staff { e4 d f e }
513   >>
514   c4 b c2
515 }
516 @end lilypond
517
518 @noindent
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}.
525
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.
529
530 @lilypond[verbatim,quote]
531 \new Staff = main \relative c'' {
532   c4 b d c
533   <<
534     { c4 b d c }
535
536     \new Staff \with {
537       \remove "Time_signature_engraver"
538       alignAboveContext = #"main"
539       fontSize = #-3
540       \override StaffSymbol #'staff-space = #(magstep -3)
541       \override StaffSymbol #'thickness = #(magstep -3)
542       firstClef = ##f
543     }
544     { e4 d f e }
545   >>
546   c4 b c2
547 }
548 @end lilypond
549
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
556 example.
557
558 @lilypond[verbatim,quote,ragged-right]
559 <<
560   \new Staff = ossia \with {
561     \remove "Time_signature_engraver"
562     \override Clef #'transparent = ##t
563     fontSize = #-3
564     \override StaffSymbol #'staff-space = #(magstep -3)
565     \override StaffSymbol #'thickness = #(magstep -3)
566   }
567   { \stopStaff s1*6 }
568
569   \new Staff \relative c' {
570     c4 b c2
571     <<
572       { e4 f e2 }
573       \context Staff = ossia {
574         \startStaff e4 g8 f e2 \stopStaff
575       }
576     >>
577     g4 a g2 \break
578     c4 b c2
579     <<
580       { g4 a g2 }
581       \context Staff = ossia {
582         \startStaff g4 e8 f g2 \stopStaff
583       }
584     >>
585     e4 d c2
586   }
587 >>
588 @end lilypond
589
590
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}.
596
597 @lilypond[verbatim,quote,ragged-right]
598 <<
599   \new Staff = ossia \with {
600     \remove "Time_signature_engraver"
601     \override Clef #'transparent = ##t
602     fontSize = #-3
603     \override StaffSymbol #'staff-space = #(magstep -3)
604     \override StaffSymbol #'thickness = #(magstep -3)
605   } \relative c'' {
606     R1*3
607     c4 e8 d c2
608   }
609   \new Staff \relative c' {
610     c4 b c2
611     e4 f e2
612     g4 a g2 \break
613     c4 b c2
614     g4 a g2
615     e4 d c2
616   }
617 >>
618
619 \layout {
620   \context {
621     \RemoveEmptyStaffContext
622     \override VerticalAxisGroup #'remove-first = ##t
623   }
624 }
625 @end lilypond
626
627
628 @snippets
629
630 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
631 {vertically-aligning-ossias-and-lyrics.ly}
632
633
634 @seealso
635 Music Glossary:
636 @rglos{ossia},
637 @rglos{staff},
638 @rglos{Frenched staff}.
639
640 Learning Manual:
641 @rlearning{Nesting music expressions},
642 @rlearning{Size of objects},
643 @rlearning{Length and thickness of objects}.
644
645 Notation Reference:
646 @ref{Hiding staves}.
647
648 Snippets:
649 @rlsr{Staff notation}.
650
651 Internals Reference:
652 @rinternals{StaffSymbol}.
653
654
655 @node Hiding staves
656 @unnumberedsubsubsec Hiding staves
657
658 @cindex Frenched score
659 @cindex Frenched staff
660 @cindex staff, hiding
661 @cindex staff, empty
662 @cindex hiding of staves
663 @cindex empty staves
664
665 @funindex \RemoveEmptyStaffContext
666 @funindex RemoveEmptyStaffContext
667 @funindex Staff_symbol_engraver
668 @funindex \stopStaff
669 @funindex stopStaff
670
671
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.
675
676 @lilypond[verbatim,quote]
677 \new Staff \with {
678   \remove "Staff_symbol_engraver"
679 }
680 \relative c''' { a8 f e16 d c b a2 }
681 @end lilypond
682
683
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.
689
690 @warning{A staff is considered empty when it contains only
691 multi-measure rests, skips, spacer rests, or a combination of these
692 elements.}
693
694 @lilypond[verbatim,quote,ragged-right]
695 \layout {
696   \context {
697     \RemoveEmptyStaffContext
698   }
699 }
700
701 \relative c' <<
702   \new Staff {
703     e4 f g a \break
704     b1 \break
705     a4 b c2
706   }
707   \new Staff {
708     c,4 d e f \break
709     R1 \break
710     f4 g c,2
711   }
712 >>
713 @end lilypond
714
715 @cindex ossia
716
717 @noindent
718 @code{\RemoveEmptyStaffContext} can also be used to create ossia
719 sections for a staff.  For details, see @ref{Ossia staves}.
720
721 @cindex hiding ancient staves
722 @cindex hiding rhythmic staves
723
724 @funindex \RemoveEmptyStaffContext
725 @funindex RemoveEmptyStaffContext
726 @funindex \AncientRemoveEmptyStaffContext
727 @funindex AncientRemoveEmptyStaffContext
728 @funindex \RemoveEmptyRhythmicStaffContext
729 @funindex RemoveEmptyRhythmicStaffContext
730
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.
735
736
737 @predefined
738 @code{\RemoveEmptyStaffContext},
739 @code{\AncientRemoveEmptyStaffContext},
740 @code{\RemoveEmptyRhythmicStaffContext}.
741 @endpredefined
742
743
744 @snippets
745
746 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
747 {removing-the-first-empty-line.ly}
748
749
750 @seealso
751 Music Glossary:
752 @rglos{Frenched staff}.
753
754 Learning Manual:
755 @rlearning{Visibility and color of objects}.
756
757 Notation Reference:
758 @ref{Changing context default settings},
759 @ref{Staff symbol},
760 @ref{Ossia staves},
761 @ref{Hidden notes},
762 @ref{Invisible rests},
763 @ref{Visibility of objects}.
764
765 Snippets:
766 @rlsr{Staff notation}.
767
768 Internals Reference:
769 @rinternals{ChordNames},
770 @rinternals{FiguredBass},
771 @rinternals{Lyrics},
772 @rinternals{Staff},
773 @rinternals{VerticalAxisGroup},
774 @rinternals{Staff_symbol_engraver}.
775
776
777 @knownissues
778
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
782 engraver:
783
784 @example
785 \override StaffSymbol #'stencil = ##f
786 \override NoteHead #'no-ledgers = ##t
787 @end example
788
789 For the Known issues and warnings associated with
790 @code{\RemoveEmptyStaffContext} see @ref{Changing context default
791 settings}.
792
793 @node Writing parts
794 @subsection Writing parts
795
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.
799
800 @menu
801 * Metronome marks::
802 * Instrument names::
803 * Quoting other voices::
804 * Formatting cue notes::
805 @end menu
806
807
808 @node Metronome marks
809 @unnumberedsubsubsec Metronome marks
810
811 @cindex tempo
812 @cindex beats per minute
813 @cindex metronome mark
814 @cindex metronome marking with text
815
816 @funindex \tempo
817 @funindex tempo
818
819 A basic metronome mark is simple to write:
820
821 @lilypond[verbatim,quote,relative=1]
822 \tempo 4 = 120
823 c2 d
824 e4. d8 c2
825 @end lilypond
826
827 Tempo indications with text can be used instead:
828
829 @lilypond[verbatim,quote,relative=2]
830 \tempo "Allegretto"
831 c4 e d c
832 b4. a16 b c4 r4
833 @end lilypond
834
835 Combining a metronome mark and text will automatically place the
836 metronome mark within parentheses:
837
838 @lilypond[verbatim,quote,relative=2]
839 \tempo "Allegro" 4 = 160
840 g4 c d e
841 d4 b g2
842 @end lilypond
843
844 In general, the text can be any markup object:
845
846 @lilypond[verbatim,quote,relative=2]
847 \tempo \markup { \italic Faster } 4 = 132
848 a8-. r8 b-. r gis-. r a-. r
849 @end lilypond
850
851 A parenthesized metronome mark with no textual indication may be
852 written by including an empty string in the input:
853
854 @lilypond[verbatim,quote,relative=2]
855 \tempo "" 8 = 96
856 d4 g e c
857 @end lilypond
858
859
860 @snippets
861
862 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
863 {printing-metronome-and-rehearsal-marks-below-the-staff.ly}
864
865 @c perhaps also an example of how to move it horizontally?
866
867 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
868 {changing-the-tempo-without-a-metronome-mark.ly}
869
870 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
871 {creating-metronome-marks-in-markup-mode.ly}
872
873 For more details, see @ref{Formatting text}.
874
875
876 @seealso
877 Music Glossary:
878 @rglos{metronome},
879 @rglos{metronomic indication},
880 @rglos{tempo indication},
881 @rglos{metronome mark}.
882
883 Notation Reference:
884 @ref{Formatting text},
885 @ref{MIDI output}.
886
887 Snippets:
888 @rlsr{Staff notation}.
889
890 Internals Reference:
891 @rinternals{MetronomeMark}.
892
893
894 @node Instrument names
895 @unnumberedsubsubsec Instrument names
896
897 @cindex instrument names
898 @cindex instrument names, short
899
900 Instrument names can be printed on the left side of staves in the
901 @code{Staff} and @code{PianoStaff} contexts.  The value of
902 @code{instrumentName} is used for the first staff, and the value
903 of @code{shortInstrumentName} is used for all succeeding staves.
904
905 @lilypond[verbatim,quote,ragged-right,relative=1]
906 \set Staff.instrumentName = #"Violin "
907 \set Staff.shortInstrumentName = #"Vln "
908 c4.. g'16 c4.. g'16
909 \break
910 c1
911 @end lilypond
912
913 Markup mode can be used to create more complicated instrument
914 names:
915
916 @lilypond[verbatim,quote,relative=2]
917 \set Staff.instrumentName = \markup {
918   \column { "Clarinetti"
919             \line { "in B" \smaller \flat } } }
920 c4 c,16 d e f g2
921 @end lilypond
922
923 @cindex instrument names, centering
924
925 When two or more staff contexts are grouped together, the
926 instrument names and short instrument names are centered by
927 default.  To center multi-line instrument names,
928 @code{\center-column} must be used:
929
930 @lilypond[verbatim,quote,indent=1.5\cm,relative=2]
931 <<
932   \new Staff {
933     \set Staff.instrumentName = #"Flute"
934     f2 g4 f
935   }
936   \new Staff {
937     \set Staff.instrumentName = \markup \center-column {
938       Clarinet
939       \line { "in B" \smaller \flat }
940     }
941     c4 b c2
942   }
943 >>
944 @end lilypond
945
946 @funindex indent
947 @funindex short-indent
948
949 However, if the instrument names are longer, the instrument names
950 in a staff group may not be centered unless the @code{indent} and
951 @code{short-indent} settings are increased.  For details about
952 these settings, see @ref{Horizontal dimensions}.
953
954 @lilypond[verbatim,quote,ragged-right]
955 \layout {
956   indent = 3.0\cm
957   short-indent = 1.5\cm
958 }
959
960 \relative c'' <<
961   \new Staff {
962     \set Staff.instrumentName = #"Alto Flute in G"
963     \set Staff.shortInstrumentName = #"Fl."
964     f2 g4 f \break
965     g4 f g2
966   }
967   \new Staff {
968     \set Staff.instrumentName = #"Clarinet"
969     \set Staff.shortInstrumentName = #"Clar."
970     c,4 b c2 \break
971     c2 b4 c
972   }
973 >>
974 @end lilypond
975
976 @cindex instrument names, adding to other contexts
977
978 To add instrument names to other contexts (such as
979 @code{GrandStaff}, @code{ChoirStaff}, or @code{StaffGroup}),
980 @code{Instrument_name_engraver} must be added to that context.
981 For details, see @ref{Modifying context plug-ins}.
982
983 @cindex instrument names, changing
984 @cindex changing instrument names
985
986 Instrument names may be changed in the middle of a piece.
987 However, remember that @code{instrumentName} will not be
988 displayed in the middle of the piece, as it only appears
989 on the first staff:
990
991 @lilypond[verbatim,quote,ragged-right,relative=1]
992 \set Staff.instrumentName = #"First"
993 \set Staff.shortInstrumentName = #"one"
994 c1 c c c \break
995 c1 c c c \break
996 \set Staff.instrumentName = #"Second"
997 \set Staff.shortInstrumentName = #"two"
998 c1 c c c \break
999 c1 c c c \break
1000 @end lilypond
1001
1002 @cindex instrument switch
1003 @cindex switching instruments
1004
1005 @funindex \addInstrumentDefinition
1006 @funindex addInstrumentDefinition
1007 @funindex \instrumentSwitch
1008 @funindex instrumentSwitch
1009
1010 If an instrument @emph{switch} is needed,
1011 @code{\addInstrumentDefinition} may be used in combination with
1012 @code{\instrumentSwitch} to create a detailed list of the
1013 necessary changes for the switch.  The
1014 @code{\addInstrumentDefinition} command has two arguments: an
1015 identifying string, and an association list of context properties
1016 and values to be used for the instrument.  It must be placed in
1017 the toplevel scope.  @code{\instrumentSwitch} is used in the music
1018 expression to declare the instrument switch:
1019
1020 @lilypond[verbatim,quote,ragged-right]
1021 \addInstrumentDefinition #"contrabassoon"
1022   #`((instrumentTransposition . ,(ly:make-pitch -1 0 0))
1023      (shortInstrumentName . "Cbsn.")
1024      (clefGlyph . "clefs.F")
1025      (middleCPosition . 6)
1026      (clefPosition . 2)
1027      (instrumentCueName . ,(make-bold-markup "cbsn."))
1028      (midiInstrument . "bassoon"))
1029
1030 \new Staff \with {
1031   instrumentName = #"Bassoon"
1032 }
1033 \relative c' {
1034   \clef tenor
1035   \compressFullBarRests
1036   c2 g'
1037   R1*16
1038   \instrumentSwitch "contrabassoon"
1039   c,,2 g \break
1040   c,1 ~ | c1
1041 }
1042 @end lilypond
1043
1044
1045 @seealso
1046 Notation Reference:
1047 @ref{Horizontal dimensions},
1048 @ref{Modifying context plug-ins}.
1049
1050 Snippets:
1051 @rlsr{Staff notation}.
1052
1053 Internals Reference:
1054 @rinternals{InstrumentName},
1055 @rinternals{PianoStaff},
1056 @rinternals{Staff}.
1057
1058
1059 @node Quoting other voices
1060 @unnumberedsubsubsec Quoting other voices
1061
1062 @cindex cues
1063 @cindex quoting other voices
1064 @cindex fragments
1065 @cindex cue notes
1066
1067 @funindex \addQuote
1068 @funindex addQuote
1069 @funindex \quoteDuring
1070 @funindex quoteDuring
1071 @funindex \transposition
1072 @funindex transposition
1073
1074 It is very common for one voice to double some of the music from
1075 another voice.  For example, the first and second violins may play the
1076 same notes during a passage of music.  In LilyPond this is accomplished
1077 by letting one voice @emph{quote} the other voice without having to
1078 re-enter it.
1079
1080 Before a part can be quoted, the @code{\addQuote} command must be used
1081 to initialize the quoted fragment.  This command must be used in the
1082 toplevel scope.  The first argument is an identifying string, and the
1083 second is a music expression:
1084
1085 @example
1086 flute = \relative c'' @{
1087   a4 gis g gis
1088 @}
1089 \addQuote "flute" @{ \flute @}
1090 @end example
1091
1092 The @code{\quoteDuring} command is used to indicate the point where the
1093 quotation begins.  It is followed by two arguments: the name of the
1094 quoted voice, as defined with @code{\addQuote}, and a music expression
1095 that indicates the duration of the quote, usually spacer rests or
1096 multi-measure rests.  The corresponding music (including all articulations,
1097 dynamics, markup, etc.) from the quoted voice is inserted into the music
1098 expression:
1099
1100 @lilypond[verbatim,quote]
1101 flute = \relative c'' {
1102   a4 gis g->\f gis^\markup{quoted}
1103 }
1104 \addQuote "flute" { \flute }
1105
1106 \relative c' {
1107   c4 cis \quoteDuring #"flute" { s2 }
1108 }
1109 @end lilypond
1110
1111 If the music expression used for @code{\quoteDuring} contains
1112 anything but a spacer rest or multi-measure rest, a polyphonic
1113 situation is created, which is often not desirable:
1114
1115 @lilypond[verbatim,quote]
1116 flute = \relative c'' {
1117   a4 gis g gis
1118 }
1119 \addQuote "flute" { \flute }
1120
1121 \relative c' {
1122   c4 cis \quoteDuring #"flute" { c4 b }
1123 }
1124 @end lilypond
1125
1126 Quotations recognize instrument transposition settings for both
1127 the source and target instruments if the @code{\transposition}
1128 command is used.  For details about @code{\transposition}, see
1129 @ref{Instrument transpositions}.
1130
1131 @lilypond[verbatim,quote]
1132 clarinet = \relative c'' {
1133   \transposition bes
1134   a4 gis g gis
1135 }
1136 \addQuote "clarinet" { \clarinet }
1137
1138 \relative c' {
1139   c4 cis \quoteDuring #"clarinet" { s2 }
1140 }
1141 @end lilypond
1142
1143 It is possible to tag quotations with unique names in order to
1144 process them in different ways.  For details about this procedure,
1145 see @ref{Using tags}.
1146
1147 It is also possible to adjust which objects from the original voice are quoted
1148 by changing the @code{quotedEventTypes} property.  By default, its value is
1149 @code{#'(StreamEvent)}, which means that everything is quoted.  Setting it
1150 to e.g. @code{#'(note-event rest-event tie-event)} causes lilypond to quote
1151 only notes, rests and ties, but no articulations, markup or dynamics.
1152
1153 @lilypond[verbatim,quote]
1154 clarinet = \relative c'' {
1155   a4 gis g->\f gis^\markup{quoted}
1156 }
1157 \addQuote "clarinet" { \clarinet }
1158
1159 \relative c' {
1160   \set Score.quotedEventTypes = #'(note-event rest-event tie-event)
1161   c4 cis \quoteDuring #"clarinet" { s2 }
1162 }
1163 @end lilypond
1164
1165 @snippets
1166
1167 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
1168 {quoting-another-voice-with-transposition.ly}
1169
1170 @cindex note-event
1171 @cindex articulation-event
1172 @cindex dynamic-event
1173 @cindex rest-event
1174
1175 @funindex quotedEventTypes
1176 @funindex quotedCueEventTypes
1177
1178 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
1179 {quoting-another-voice.ly}
1180
1181
1182 @seealso
1183 Notation Reference:
1184 @ref{Instrument transpositions},
1185 @ref{Using tags}.
1186
1187 Snippets:
1188 @rlsr{Staff notation}.
1189
1190 Internals Reference:
1191 @rinternals{QuoteMusic},
1192 @rinternals{Voice}.
1193
1194
1195 @knownissues
1196
1197 Only the contents of the first @code{Voice} occurring in an
1198 @code{\addQuote} command will be considered for quotation, so
1199 @var{music} cannot contain @code{\new} and @code{\context Voice}
1200 statements that would switch to a different Voice.
1201
1202 Quoting grace notes is broken and can even cause LilyPond to
1203 crash.
1204
1205 Quoting nested triplets may result in poor notation.
1206
1207 In earlier versions of LilyPond (pre 2.11), @code{addQuote} was
1208 written entirely in lower-case letters: @code{\addquote}.
1209
1210
1211 @node Formatting cue notes
1212 @unnumberedsubsubsec Formatting cue notes
1213
1214 @cindex cues
1215 @cindex cue notes
1216 @cindex cue notes, formatting
1217 @cindex fragments
1218 @cindex quoting other voices
1219 @cindex cues, formatting
1220
1221 @funindex \cueDuring
1222 @funindex cueDuring
1223 @funindex \quoteDuring
1224 @funindex quoteDuring
1225
1226 The previous section explains how to create quotations.  The
1227 @code{\cueDuring} command is a more specialized form of
1228 @code{\quoteDuring}, being particularly useful for inserting cue
1229 notes into a part.  The syntax is as follows:
1230
1231 @example
1232 \cueDuring #@var{partname} #@var{voice} @var{music}
1233 @end example
1234
1235 This command copies only the notes and rests from the corresponding measures
1236 from @var{partname} into a @code{CueVoice} context.  The @code{CueVoice} is
1237 created implicitly, and occurs simultaneously with @var{music}, which
1238 creates a polyphonic situation.  The @var{voice} argument
1239 determines whether the cue notes should be notated as a first or
1240 second voice; @code{UP} corresponds to the first voice, and
1241 @code{DOWN} corresponds to the second.
1242
1243 @lilypond[verbatim,quote]
1244 oboe = \relative c'' {
1245   r2 r8 d16(\f f e g f a)
1246   g8 g16 g g2.
1247 }
1248 \addQuote "oboe" { \oboe }
1249
1250 \new Voice \relative c'' {
1251   \cueDuring #"oboe" #UP { R1 }
1252   g2 c,
1253 }
1254 @end lilypond
1255
1256 @noindent
1257 In the above example, the @code{Voice} context had to be
1258 explicitly declared, or else the entire music expression would
1259 belong to the @code{CueVoice} context.
1260
1261 It is possible to adjust which aspects of the music are quoted with
1262 @code{\cueDuring} by setting the @code{quotedCueEventTypes} property.  Its
1263 default value is @code{#'(note-event rest-event tie-event beam-event
1264 tuplet-span-event)}, which means that only notes, rest, ties, beams and
1265 tuplets are quoted, but not articulations, dynamic marks, markup etc.
1266
1267 @lilypond[verbatim,quote]
1268 oboe = \relative c'' {
1269   r2 r8 d16(\f f e g f a)
1270   g8 g16 g g2.
1271 }
1272 \addQuote "oboe" { \oboe }
1273
1274 \new Voice \relative c'' {
1275   \set Score.quotedCueEventTypes = #'(note-event rest-event tie-event
1276                                       beam-event tuplet-span-event
1277                                       dynamic-event slur-event)
1278   \cueDuring #"oboe" #UP { R1 }
1279   g2 c,
1280 }
1281 @end lilypond
1282
1283
1284
1285 The name of the cued instrument can be printed by setting the
1286 @code{instrumentCueName} property in the @code{CueVoice} context.
1287
1288 @lilypond[verbatim,quote]
1289 oboe = \relative c''' {
1290   g4 r8 e16 f e4 d
1291 }
1292 \addQuote "oboe" { \oboe }
1293
1294 \new Staff \relative c'' <<
1295   \new CueVoice \with {
1296     instrumentCueName = "ob."
1297   }
1298   \new Voice {
1299     \cueDuring #"oboe" #UP { R1 }
1300     g4. b8 d2
1301   }
1302 >>
1303 @end lilypond
1304
1305 @cindex removing cues
1306 @cindex removing cue notes
1307 @cindex cue notes, removing
1308
1309 @funindex \killCues
1310 @funindex killCues
1311 @funindex \transposedCueDuring
1312 @funindex transposedCueDuring
1313
1314 In addition to printing the name of the cued instrument, when cue
1315 notes end, the name of the original instrument should be printed,
1316 and any other changes introduced by the cued part should be
1317 undone.  This can be accomplished by using
1318 @code{\addInstrumentDefinition} and @code{\instrumentSwitch}.  For
1319 an example and explanation, see @ref{Instrument names}.
1320
1321 The @code{\killCues} command removes cue notes from a music
1322 expression.  This can be useful if cue notes need to be removed
1323 from a part but may be restored at a later time.
1324
1325 @lilypond[verbatim,quote]
1326 flute = \relative c''' {
1327   r2 cis2 r2 dis2
1328 }
1329 \addQuote "flute" { \flute }
1330
1331 \new Voice \relative c'' {
1332   \killCues {
1333     \cueDuring #"flute" #UP { R1 }
1334     g4. b8 d2
1335   }
1336 }
1337 @end lilypond
1338
1339 The @code{\transposedCueDuring} command is useful for adding
1340 instrumental cues from a completely different register.  The
1341 syntax is similar to @code{\cueDuring}, but it requires one extra
1342 argument to specify the transposition of the cued instrument.  For
1343 more information about transposition, see
1344 @ref{Instrument transpositions}.
1345
1346 @lilypond[verbatim,quote]
1347 piccolo = \relative c''' {
1348   \clef "treble^8"
1349   R1
1350   c8 c c e g2
1351   a4 g g2
1352 }
1353 \addQuote "piccolo" { \piccolo }
1354
1355 cbassoon = \relative c, {
1356   \clef "bass_8"
1357   c4 r g r
1358   \transposedCueDuring #"piccolo" #UP c,, { R1 }
1359   c4 r g r
1360 }
1361
1362 <<
1363   \new Staff = "piccolo" \piccolo
1364   \new Staff = "cbassoon" \cbassoon
1365 >>
1366 @end lilypond
1367
1368 It is possible to tag cued parts with unique names in order to
1369 process them in different ways.  For details about this procedure,
1370 see @ref{Using tags}.
1371
1372 @cindex notes, smaller
1373 @cindex smaller notes
1374
1375 A @code{CueVoice} context may be created explicitly if notes of a
1376 smaller size are required, for example to set an alternative
1377 sequence of notes more suitable for a higher or lower voice.
1378
1379 @lilypond[verbatim,relative=2]
1380 \time 12/8
1381 \key ees \major
1382 g4 ees8 f4 g8
1383 \stemDown
1384 <<
1385   { d4. bes4 c8 }
1386   \new CueVoice
1387   { g'4. f4 ees8 }
1388 >>
1389 \stemUp
1390 d2. d2.
1391 @end lilypond
1392
1393
1394 @seealso
1395 Notation Reference:
1396 @ref{Instrument transpositions},
1397 @ref{Instrument names},
1398 @ref{Using tags}.
1399
1400 Snippets:
1401 @rlsr{Staff notation}.
1402
1403 Internals Reference:
1404 @rinternals{CueVoice},
1405 @rinternals{Voice}.
1406
1407
1408 @knownissues
1409
1410 Collisions can occur with rests, when using @code{\cueDuring},
1411 between @code{Voice} and @code{CueVoice} contexts.
1412