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