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