]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/notation/simultaneous.itely
707e071b293b4f5bb6abc0df5e4c484f15ba48da
[lilypond.git] / Documentation / notation / simultaneous.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.19.16"
11
12
13 @node Simultaneous notes
14 @section Simultaneous notes
15
16 @lilypondfile[quote,ragged-right,line-width=16\cm]{simultaneous-headword.ly}
17
18 Polyphony in music refers to having more than one voice occurring
19 in a piece of music.  Polyphony in LilyPond refers to having more
20 than one voice on the same staff.
21
22 @menu
23 * Single voice::
24 * Multiple voices::
25 @end menu
26
27
28 @node Single voice
29 @subsection Single voice
30
31 This section discusses simultaneous notes inside the same voice.
32
33 @menu
34 * Chorded notes::
35 * Chord repetition::
36 * Simultaneous expressions::
37 * Clusters::
38 @end menu
39
40
41 @node Chorded notes
42 @unnumberedsubsubsec Chorded notes
43
44 @cindex chords
45 @cindex brackets, angle
46
47 @funindex <
48 @funindex >
49 @funindex <...>
50
51 A chord is formed by enclosing a set of pitches between @code{<}
52 and @code{>}.  A chord may be followed by a duration just like simple
53 notes.
54
55 @lilypond[verbatim,quote,relative=2]
56 <a c e>1 <a c e>2 <f a c e>4 <a c>8. <g c e>16
57 @end lilypond
58
59 Chords may also be followed by articulations, again just like simple
60 notes.
61
62 @lilypond[verbatim,quote,relative=2]
63 <a c e>1\fermata <a c e>2-> <f a c e>4\prall <a c>8.^! <g c e>16-.
64 @end lilypond
65
66 The notes within the chord themselves can also be followed by articulation
67 and ornamentation.
68
69 @lilypond[verbatim,quote,relative=2]
70 <a c\prall e>1 <a-> c-^ e>2 <f-. a c-. e-.>4
71 <a-+ c-->8. <g\fermata c e\turn>16
72 @end lilypond
73
74 However some notation, such as dynamics, hairpins and slurs must be
75 attached to the chord, rather than notes within the chord, otherwise
76 they will not print.
77
78 @lilypond[verbatim,quote,relative=2]
79 <a\f c( e>1 <a c) e>\f <a\< c e>( <a\! c e>)
80 <a c e>\< <a c e> <a c e>\!
81 @end lilypond
82
83 @cindex chords, empty
84 @cindex placeholder events
85
86 A chord acts merely as a container for its notes, its articulations and
87 other attached elements.  Consequently, a chord without notes inside
88 does not actually have a duration.  Any attached articulations will
89 happen at the same musical time as the next following note or chord and
90 be combined with them (for more complex possibilities of combining such
91 elements, see @ref{Simultaneous expressions}):
92
93 @lilypond[verbatim,quote,relative=2]
94 \grace { g8( a b }
95 <> ) \p \< -. -\markup \italic "sempre staccato"
96 \repeat unfold 4 { c4 e }  c1\f
97 @end lilypond
98
99 @cindex relative pitch, chords
100 @cindex chords, relative pitch
101
102 Relative mode can be used for pitches in chords.  The first note of
103 each chord is always relative to the first note of the chord that
104 came before it, or in the case where no preceding chord exists, the
105 pitch of the last note that came before the chord.  All remaining notes
106 in the chord are relative to the note that came before it
107 @emph{within the same chord}.
108
109 @lilypond[verbatim,quote,relative=2]
110 <a c e>1 <f a c> <a c e> <f' a c> <b, e b,>
111 @end lilypond
112
113 For more information about chords, see @ref{Chord notation}.
114
115 @seealso
116 Music Glossary:
117 @rglos{chord}.
118
119 Learning Manual:
120 @rlearning{Combining notes into chords}.
121
122 Notation Reference:
123 @ref{Chord notation},
124 @ref{Articulations and ornamentations},
125 @ref{Relative octave entry},
126 @ref{Multiple voices}.
127
128 Snippets:
129 @rlsr{Simultaneous notes}.
130
131 @knownissues
132 Chords containing more than two pitches within a staff space,
133 such as @samp{<e f! fis!>}, create overlapping noteheads.
134 Depending on the situation, better representations might involve
135
136 @itemize
137
138 @item
139 temporary use of @ref{Multiple voices},
140 @samp{<< f! \\ <e fis!> >>},
141
142 @item
143 enharmonic transcription of one or more pitches,
144 @samp{<e f ges>}, or
145
146 @item
147 @ref{Clusters}.
148
149 @end itemize
150
151
152 @node Chord repetition
153 @unnumberedsubsubsec Chord repetition
154
155 @cindex chord, repetition
156 @cindex repetition, using @code{q}
157 @cindex @code{q}, chord repetition
158
159 In order to save typing, a shortcut can be used to repeat the preceding
160 chord.  The chord repetition symbol is @code{q}:
161
162 @lilypond[verbatim,quote,relative=2]
163 <a c e>1 q <f a c>2 q
164 @end lilypond
165
166 As with regular chords, the chord repetition symbol can be used with
167 durations, articulations, markups, slurs, beams, etc. as only the
168 pitches of the previous chord are duplicated.
169
170 @lilypond[verbatim,quote,relative=2]
171 <a c e>1\p^"text" q2\<( q8)[-! q8.]\! q16-1-2-3 q8\prall
172 @end lilypond
173
174 The chord repetition symbol always remembers the last instance of
175 a chord so it is possible to repeat the most recent chord even if
176 other non-chorded notes or rests have been added since.
177
178 @lilypond[verbatim,quote,relative=2]
179 <a c e>1 c'4 q2 r8 q8 |
180 q2 c, |
181 @end lilypond
182
183 However, the chord repetition symbol does not retain any dynamics,
184 articulation or ornamentation within, or attached to, the previous
185 chord.
186
187 @lilypond[verbatim,quote,relative=2]
188 <a-. c\prall e>1\sfz c'4 q2 r8 q8 |
189 q2 c, |
190 @end lilypond
191
192 To have some of them retained, the @code{\chordRepeats} function can be
193 be called explicitly with an extra argument specifying a list of
194 @var{event types} to keep unless events of that type are already
195 present on the @code{q} chord itself.
196
197 @lilypond[verbatim,quote]
198 \relative c'' {
199   \chordRepeats #'(articulation-event)
200   { <a-. c\prall e>1\sfz c'4 q2 r8 q8-. } |
201   q2 c, |
202 }
203 @end lilypond
204
205 Here using @code{\chordRepeats} inside of a @code{\relative} construction
206 produces unexpected results: once chord events have been expanded, they
207 are indistinguishable from having been entered as regular chords, making
208 @code{\relative} assign an octave based on their current context.
209
210 Since nested instances of @code{\relative} don't affect one another,
211 another @code{\relative} inside of @code{\chordRepeats} can be used for
212 establishing the octave relations before expanding the repeat chords.
213 In that case, the whole content of the inner @code{\relative} does not
214 affect the outer one; hence the different octave entry of the final note
215 in this example.
216
217 @c Without \new Voice, implicit voice creation does the dumbest thing.
218 @lilypond[verbatim,quote]
219 \new Voice
220 \relative c'' {
221   \chordRepeats #'(articulation-event)
222   \relative c''
223   { <a-. c\prall e>1\sfz c'4 q2 r8 q8-. } |
224   q2 c |
225 }
226 @end lilypond
227
228 Interactions with @code{\relative} occur only with explicit calls of
229 @code{\chordRepeats}: the implicit expansion at the start of typesetting
230 is done at a time where all instances of @code{\relative} have already
231 been processed.
232
233 @seealso
234 Notation Reference:
235 @ref{Chord notation},
236 @ref{Articulations and ornamentations}.
237
238 Installed Files:
239 @file{ly/chord-repetition-init.ly}.
240
241
242 @node Simultaneous expressions
243 @unnumberedsubsubsec Simultaneous expressions
244
245 One or more music expressions enclosed in double angle brackets are
246 taken to be simultaneous.  If the first expression begins with a
247 single note or if the whole simultaneous expression appears
248 explicitly within a single voice, the whole expression is placed on
249 a single staff; otherwise the elements of the simultaneous
250 expression are placed on separate staves.
251
252 The following examples show simultaneous expressions on one staff:
253
254 @lilypond[quote,verbatim,relative=2]
255 \new Voice {  % explicit single voice
256   << { a4 b g2 } { d4 g c,2 } >>
257 }
258 @end lilypond
259
260 @lilypond[quote,verbatim,relative=2]
261 % single first note
262 a << { a4 b g } { d4 g c, } >>
263 @end lilypond
264
265 This can be useful if the simultaneous sections have identical
266 rhythms, but attempts to attach notes with different durations to
267 the same stem will cause errors.  Notes, articulations, and property
268 changes in a @emph{single} @samp{Voice} are collected and engraved in
269 musical order:
270
271 @lilypond[quote,verbatim,relative=2]
272 <a c>4-.  <>-. << c a >>  << { c-. <c a> } { a s-. } >>
273 @end lilypond
274
275 Multiple stems or beams or different note durations or properties at
276 the same musical time require the use of multiple voices.
277
278 The following example shows how simultaneous expressions can
279 generate multiple staves implicitly:
280
281 @lilypond[quote,verbatim,relative=2]
282 % no single first note
283 << { a4 b g2 } { d4 g2 c,4 } >>
284 @end lilypond
285
286 Here different rhythms cause no problems because they are
287 interpreted in different voices.
288
289 @cindex collisions, ignoring
290
291 @knownissues
292 If notes from two or more voices, with no shifts specified,
293 have stems in the same direction, the message
294
295 @example
296 warning: This voice needs a \voiceXx or \shiftXx setting
297 @end example
298
299 will appear during compilation.  This message can be suppressed by:
300
301 @example
302 \override NoteColumn.ignore-collision = ##t
303 @end example
304
305 However, this not only suppresses the warning but will prevent any
306 collision resolution whatsover and may have other unintended effects
307 (also see @emph{Known Issues} in @ref{Collision resolution}).
308
309
310 @node Clusters
311 @unnumberedsubsubsec Clusters
312
313 @cindex cluster
314 @cindex note cluster
315
316 @funindex \makeClusters
317 @funindex makeClusters
318
319 A cluster indicates a continuous range of pitches to be played.
320 They can be denoted as the envelope of a set of notes.  They are
321 entered by applying the function @code{\makeClusters} to a sequence
322 of chords, e.g.,
323
324 @lilypond[quote,relative=2,verbatim]
325 \makeClusters { <g b>2 <c g'> }
326 @end lilypond
327
328 Ordinary notes and clusters can be put together in the same staff,
329 even simultaneously.  In such a case no attempt is made to
330 automatically avoid collisions between ordinary notes and clusters.
331
332 @seealso
333 Music Glossary:
334 @rglos{cluster}.
335
336 Snippets:
337 @rlsr{Simultaneous notes}.
338
339 Internals Reference:
340 @rinternals{ClusterSpanner},
341 @rinternals{ClusterSpannerBeacon},
342 @rinternals{Cluster_spanner_engraver}.
343
344 @knownissues
345 Clusters look good only if they span at least two chords; otherwise
346 they appear too narrow.
347
348 Clusters do not have a stem and cannot indicate durations by
349 themselves, but the length of the printed cluster is determined by
350 the durations of the defining chords.  Separate clusters need a
351 separating rest between them.
352
353 Clusters do not produce MIDI output.
354
355
356 @node Multiple voices
357 @subsection Multiple voices
358
359 This section discusses simultaneous notes in multiple voices or
360 multiple staves.
361
362 @menu
363 * Single-staff polyphony::
364 * Voice styles::
365 * Collision resolution::
366 * Automatic part combining::
367 * Writing music in parallel::
368 @end menu
369
370
371 @node Single-staff polyphony
372 @unnumberedsubsubsec Single-staff polyphony
373
374 @cindex single-staff polyphony
375 @cindex polyphony, single-staff
376 @cindex voice
377 @cindex lyrics assigned to one voice
378
379 @funindex \voiceOne
380 @funindex voiceOne
381 @funindex \voiceOne ... \voiceFour
382 @funindex Voice
383 @funindex \oneVoice
384 @funindex oneVoice
385
386 @subsubsubheading Explicitly instantiating voices
387
388 The basic structure needed to achieve multiple independent
389 voices in a single staff is illustrated in the following example:
390
391 @lilypond[quote,relative=3,verbatim]
392 \new Staff <<
393   \new Voice = "first"
394     { \voiceOne r8 r16 g e8. f16 g8[ c,] f e16 d }
395   \new Voice= "second"
396     { \voiceTwo d16 c d8~ 16 b c8~ 16 b c8~ 16 b8. }
397 >>
398 @end lilypond
399
400 @noindent
401 Here, voices are instantiated explicitly and are given names.  The
402 @code{\voiceOne} @dots{} @code{\voiceFour} commands set up the voices
403 so that first and third voices get stems up, second and fourth
404 voices get stems down, third and fourth voice note heads are
405 horizontally shifted, and rests in the respective voices are
406 automatically moved to avoid collisions.  The @code{\oneVoice}
407 command returns all the voice settings to the neutral default
408 directions.
409
410 @subsubsubheading Temporary polyphonic passages
411
412 A temporary polyphonic passage can be created with the following
413 construct:
414
415 @example
416 << @{ \voiceOne @dots{} @}
417   \new Voice @{ \voiceTwo @dots{} @}
418 >> \oneVoice
419 @end example
420
421 @noindent
422 Here, the first expression within a temporary polyphonic passage is
423 placed into the @code{Voice} context which was in use immediately
424 before the polyphonic passage, and that same @code{Voice} context
425 continues after the temporary section.  Other expressions within
426 the angle brackets are assigned to distinct temporary voices.
427 This allows lyrics to be assigned to one continuing voice before,
428 during and after a polyphonic section:
429
430 @lilypond[quote, verbatim, relative=2]
431 <<
432   \new Voice = "melody" {
433     a4
434     <<
435       {
436         \voiceOne
437         g f
438       }
439       \new Voice {
440         \voiceTwo
441         d2
442       }
443     >>
444     \oneVoice
445     e4
446   }
447   \new Lyrics \lyricsto "melody" {
448   This is my song.
449   }
450 >>
451 @end lilypond
452
453 @noindent
454 Here, the @code{\voiceOne} and @code{\voiceTwo} commands are
455 required to define the settings of each voice.
456
457 @subsubsubheading The double backslash construct
458
459 The @code{<< @{@dots{}@} \\ @{@dots{}@} >>} construct, where the two (or
460 more) expressions are separated by double backslashes, behaves
461 differently to the similar construct without the double backslashes:
462 @emph{all} the expressions within this construct are assigned
463 to new @code{Voice} contexts.  These new @code{Voice} contexts
464 are created implicitly and are given the fixed names @code{"1"},
465 @code{"2"}, etc.
466
467 The first example could be typeset as follows:
468
469 @lilypond[quote,relative=3,verbatim]
470 <<
471   { r8 r16 g e8. f16 g8[ c,] f e16 d }
472   \\
473   { d16 c d8~ 16 b c8~ 16 b c8~ 16 b8. }
474 >>
475 @end lilypond
476
477 This syntax can be used where it does not matter that temporary
478 voices are created and then discarded.  These implicitly created
479 voices are given the settings equivalent to the effect of the
480 @code{\voiceOne} @dots{} @code{\voiceFour} commands, in the order in
481 which they appear in the code.
482
483 In the following example, the intermediate voice has stems up,
484 therefore we enter it in the third place, so it becomes voice
485 three, which has the stems up as desired.  Spacer rests are
486 used to avoid printing doubled rests.
487
488 @lilypond[quote,relative=3,verbatim]
489 <<
490   { r8 g g  g g f16 ees f8 d }
491   \\
492   { ees,8 r ees r d r d r }
493   \\
494   { d'8 s c s bes s a s }
495 >>
496 @end lilypond
497
498 In all but the simplest works it is advisable to create explicit
499 @code{Voice} contexts as explained in @rlearning{Contexts and engravers} and
500 @rlearning{Explicitly instantiating voices}.
501
502 @subsubsubheading Voice order
503
504 When entering multiple voices in the input file, use the following
505 order:
506
507 @example
508 Voice 1: highest
509 Voice 2: lowest
510 Voice 3: second highest
511 Voice 4: second lowest
512 Voice 5: third highest
513 Voice 6: third lowest
514 etc.
515 @end example
516
517 Though this may seem counterintuitive, it simplifies the automatic
518 layout process.  Note that the odd-numbered voices are given
519 upstems, and the even-numbered voices are given downstems:
520
521 @lilypond[quote,verbatim]
522 \new Staff <<
523   \time 2/4
524   { f''2 }  % 1: highest
525   \\
526   { c'2  }  % 2: lowest
527   \\
528   { d''2 }  % 3: second-highest
529   \\
530   { e'2  }  % 4: second-lowest
531   \\
532   { b'2  }  % 5: third-highest
533   \\
534   { g'2  }  % 6: third-lowest
535 >>
536 @end lilypond
537
538 @warning{Lyrics, spanners (such as slurs, ties, hairpins etc.) cannot be
539 created @q{across} voices.}
540
541 @subsubsubheading Identical rhythms
542
543 In the special case that we want to typeset parallel pieces of music
544 that have the same rhythm, we can combine them into a single
545 @code{Voice} context, thus forming chords.  To achieve this, enclose
546 them in a simple simultaneous music construct within an explicit voice:
547
548 @lilypond[quote,relative=2,verbatim]
549 \new Voice <<
550   { e4 f8 d e16 f g8 d4 }
551   { c4 d8 b c16 d e8 b4 }
552 >>
553 @end lilypond
554
555 This method leads to strange beamings and warnings if the pieces of
556 music do not have the same rhythm.
557
558
559 @predefined
560 @code{\voiceOne},
561 @code{\voiceTwo},
562 @code{\voiceThree},
563 @code{\voiceFour},
564 @code{\oneVoice}.
565 @endpredefined
566
567 @seealso
568 Learning Manual:
569 @rlearning{Voices contain music},
570 @rlearning{Explicitly instantiating voices}.
571
572 Notation Reference:
573 @ref{Percussion staves},
574 @ref{Invisible rests},
575 @ref{Stems}.
576
577 Snippets:
578 @rlsr{Simultaneous notes}.
579
580
581 @node Voice styles
582 @unnumberedsubsubsec Voice styles
583
584 @cindex voice styles
585 @cindex styles, voice
586 @cindex coloring voices
587 @funindex \voiceOneStyle
588 @funindex \voiceTwoStyle
589 @funindex \voiceThreeStyle
590 @funindex \voiceFourStyle
591 @funindex \voiceNeutralStyle
592
593 Voices may be given distinct colors and shapes, allowing them to be
594 easily identified:
595
596 @lilypond[quote,relative=2,verbatim]
597 <<
598   { \voiceOneStyle d4 c2 b4 }
599   \\
600   { \voiceTwoStyle e,2 e }
601   \\
602   { \voiceThreeStyle b2. c4 }
603   \\
604   { \voiceFourStyle g'2 g }
605 >>
606 @end lilypond
607
608 The @code{\voiceNeutralStyle} command is used to revert to the
609 standard presentation.
610
611
612 @predefined
613 @code{\voiceOneStyle},
614 @code{\voiceTwoStyle},
615 @code{\voiceThreeStyle},
616 @code{\voiceFourStyle},
617 @code{\voiceNeutralStyle}.
618 @endpredefined
619
620 @seealso
621 Learning Manual:
622 @rlearning{I'm hearing Voices},
623 @rlearning{Other sources of information}.
624
625 Snippets:
626 @rlsr{Simultaneous notes}.
627
628
629 @node Collision resolution
630 @unnumberedsubsubsec Collision resolution
631
632 @cindex merging notes
633 @cindex note collisions
634 @cindex collisions
635 @cindex shift note
636 @cindex multiple voices
637 @cindex voices, multiple
638 @cindex polyphonic music
639 @cindex shifting voices
640 @cindex voices, multiple
641 @cindex shift rest, automatic
642 @funindex \shiftOn
643 @funindex shiftOn
644 @funindex \shiftOnn
645 @funindex shiftOnn
646 @funindex \shiftOnnn
647 @funindex shiftOnnn
648 @funindex \shiftOff
649 @funindex shiftOff
650 @funindex \mergeDifferentlyDottedOn
651 @funindex mergeDifferentlyDottedOn
652 @funindex \mergeDifferentlyDottedOff
653 @funindex mergeDifferentlyDottedOff
654 @funindex \mergeDifferentlyHeadedOn
655 @funindex mergeDifferentlyHeadedOn
656 @funindex \mergeDifferentlyHeadedOff
657 @funindex mergeDifferentlyHeadedOff
658
659 The note heads of notes in different voices with the same pitch,
660 same note head and opposite stem direction are automatically
661 merged, but notes with different note heads or the same stem
662 direction are not.  Rests opposite a stem in a different voice
663 are shifted vertically.  The following example shows three
664 different circumstances, on beats 1 and 3 in bar 1 and beat 1
665 in bar 2, where the automatic merging fails.
666
667 @lilypond[quote,verbatim,relative=2]
668 <<
669   {
670     c8 d e d c d c4
671     g'2 fis
672   } \\ {
673     c2 c8. b16 c4
674     e,2 r
675   } \\ {
676     \oneVoice
677     s1
678     e8 a b c d2
679   }
680 >>
681 @end lilypond
682
683 Notes with different note heads may be merged as shown
684 below.  In this example the note heads on beat 1 of bar 1 are now merged:
685
686 @lilypond[quote,verbatim,relative=2]
687 <<
688   {
689     \mergeDifferentlyHeadedOn
690     c8 d e d c d c4
691     g'2 fis
692   } \\ {
693     c2 c8. b16 c4
694     e,2 r
695   } \\ {
696     \oneVoice
697     s1
698     e8 a b c d2
699   }
700 >>
701 @end lilypond
702
703 Quarter and half notes are not merged in this way, since it would be difficult
704 to tell them apart.
705
706 Note heads with different dots as shown in beat 3 of bar 1 may be
707 also be merged:
708
709 @lilypond[quote,relative=2,verbatim]
710 <<
711   {
712     \mergeDifferentlyHeadedOn
713     \mergeDifferentlyDottedOn
714     c8 d e d c d c4
715     g'2 fis
716   } \\ {
717     c2 c8. b16 c4
718     e,2 r
719   } \\ {
720     \oneVoice
721     s1
722     e8 a b c d2
723   }
724 >>
725 @end lilypond
726
727 The half note and eighth note at the start of the second measure
728 are incorrectly merged because the automatic merge cannot
729 successfully complete the merge when three or more notes line up in
730 the same note column, and in this case the merged note head is
731 incorrect.  To allow the merge to select the correct note head
732 a @code{\shift} must be applied to the note that should not be
733 merged.  Here, @code{\shiftOn} is applied to move the top
734 @notation{g} out of the column, and @code{\mergeDifferentlyHeadedOn}
735 then works properly.
736
737 @lilypond[quote,relative=2,verbatim]
738 <<
739   {
740     \mergeDifferentlyHeadedOn
741     \mergeDifferentlyDottedOn
742     c8 d e d c d c4
743     \shiftOn
744     g'2 fis
745   } \\ {
746     c2 c8. b16 c4
747     e,2 r
748   } \\ {
749     \oneVoice
750     s1
751     e8 a b c d2
752   }
753 >>
754 @end lilypond
755
756 The @code{\shiftOn} command allows (but does not force) the notes
757 in a voice to be shifted.  When @code{\shiftOn} is applied to a
758 voice, a note or chord in that voice is shifted only if its stem
759 would otherwise collide with a stem from another voice, and only
760 if the colliding stems point in the same direction.  The
761 @code{\shiftOff} command prevents this type of shifting from
762 occurring.
763
764 By default, the outer voices (normally voices one and two) have
765 @code{\shiftOff} specified, while the inner voices (three and
766 above) have @code{\shiftOn} specified.  When a shift is applied,
767 voices with upstems (odd-numbered voices) are shifted to the
768 right, and voices with downstems (even-numbered voices) are
769 shifted to the left.
770
771 Here is an example to help you visualize how an abbreviated
772 polyphonic expression would be expanded internally.
773
774 @warning{Note that with three or more voices, the vertical order
775 of voices in your input file should not be the same as the
776 vertical order of voices on the staff!}
777
778 @lilypond[quote,verbatim]
779 \new Staff \relative c'' {
780   %% abbreviated entry
781   <<
782     { f2  }  % 1: highest
783     \\
784     { g,2 }  % 2: lowest
785     \\
786     { d'2 }  % 3: upper middle
787     \\
788     { b2  }  % 4: lower middle
789   >>
790   %% internal expansion of the above
791   <<
792     \new Voice = "1" { \voiceOne   \shiftOff f'2 }
793     \new Voice = "2" { \voiceTwo   \shiftOff g,2 }
794     \new Voice = "3" { \voiceThree \shiftOn  d'2 } % shifts right
795     \new Voice = "4" { \voiceFour  \shiftOn  b2  } % shifts left
796   >>
797 }
798 @end lilypond
799
800 Two additional commands, @code{\shiftOnn} and @code{\shiftOnnn}
801 provide further shift levels which may be specified temporarily to
802 resolve collisions in complex situations -- see
803 @rlearning{Real music example}.
804
805 Notes are only merged if they have opposing stem directions (as
806 they have, for example, in voices one and two by default or when
807 the stems are explicitly set in opposite directions).
808
809 @predefined
810 @code{\mergeDifferentlyDottedOn},
811 @code{\mergeDifferentlyDottedOff},
812 @code{\mergeDifferentlyHeadedOn},
813 @code{\mergeDifferentlyHeadedOff}.
814
815 @code{\shiftOn},
816 @code{\shiftOnn},
817 @code{\shiftOnnn},
818 @code{\shiftOff}.
819 @endpredefined
820
821 @snippets
822 @lilypondfile[verbatim,quote,texidoc,doctitle]
823 {additional-voices-to-avoid-collisions.ly}
824
825 @lilypondfile[verbatim,quote,texidoc,doctitle]
826 {forcing-horizontal-shift-of-notes.ly}
827
828 @seealso
829 Music Glossary:
830 @rglos{polyphony}.
831
832 Learning Manual:
833 @rlearning{Multiple notes at once},
834 @rlearning{Voices contain music},
835 @rlearning{Real music example}.
836
837 Snippets:
838 @rlsr{Simultaneous notes}.
839
840 Internals Reference:
841 @rinternals{NoteColumn},
842 @rinternals{NoteCollision},
843 @rinternals{RestCollision}.
844
845 @cindex collisions, ignoring
846
847 @knownissues
848 Using @code{\override NoteColumn.ignore-collision = ##t} will cause
849 differently headed notes in different voices to merge incorrectly.
850
851 @lilypond[quote,relative=1,verbatim]
852 \mergeDifferentlyHeadedOn
853 << { c16 a' b a } \\ { c,2 } >>
854 \override NoteColumn.ignore-collision = ##t
855 << { c16 a' b a } \\ { c,2 } >>
856 @end lilypond
857
858 @ignore
859 @knownissues
860 @c TODO investigate! Sometimes it works, sometimes not. --FV
861 The requirements for successfully merging different note heads that
862 are at the same time differently dotted are not clear.
863 @end ignore
864
865
866 @node Automatic part combining
867 @unnumberedsubsubsec Automatic part combining
868
869 @cindex automatic part combining
870 @cindex part combiner
871 @cindex combining parts
872 @cindex a due part
873 @cindex solo part
874 @funindex \partcombine
875 @funindex partcombine
876
877 Automatic part combining is used to merge two separate parts of music
878 onto a single staff. This can be especially helpful when typesetting
879 orchestral scores.  A single @code{Voice} is printed while the two parts
880 of music are the same, but in places where they differ, a second
881 @code{Voice} is printed.  Stem directions are set up & down accordingly
882 while Solo and @notation{a due} parts are also identified and marked
883 appropriately.
884
885 The syntax for automatic part combining is:
886
887 @example
888 \partcombine @var{musicexpr1} @var{musicexpr2}
889 @end example
890
891 The following example demonstrates the basic functionality, putting
892 parts on a single staff as polyphony and setting stem directions
893 accordingly.  The same variables are used for the independent parts and
894 the combined staff.
895
896 @lilypond[quote,verbatim]
897 instrumentOne = \relative c' {
898   c4 d e f |
899   R1 |
900   d'4 c b a |
901   b4 g2 f4 |
902   e1 |
903 }
904
905 instrumentTwo = \relative g' {
906   R1 |
907   g4 a b c |
908   d4 c b a |
909   g4 f( e) d |
910   e1 |
911 }
912
913 <<
914   \new Staff \instrumentOne
915   \new Staff \instrumentTwo
916   \new Staff \partcombine \instrumentOne \instrumentTwo
917 >>
918 @end lilypond
919
920 Both parts have identical notes in the third measure, so only one
921 instance of the notes is printed.  Stem, slur, and tie directions are
922 set automatically, depending on whether the parts are playing solo or in
923 unison.  When needed in polyphony situations, the first part (with
924 context called @code{one}) gets @qq{up} stems, while the second (called
925 @code{two}) always gets @qq{down} stems.  In solo situations, the first
926 and second parts get marked with @qq{Solo} and @qq{Solo II},
927 respectively.  The unison (@notation{a due}) parts are marked with the
928 text @qq{a2}.
929
930 By default, the partcombiner merges two notes of the same pitch as an
931 @notation{a due} note, combines notes with the same
932 rhythm less than a ninth apart as chords and separates notes more than
933 a ninth apart (or when the voices cross) into
934 separate voices.  This can be overridden with an optional argument of a pair
935 of numbers after the @code{\partcombine} command: the first specifies
936 the interval where notes start to be combined (the default is zero) and the
937 second where the notes are split into separate voices.  Setting the second
938 argument to zero means that the partcombiner splits notes with an interval of
939 a second or more, setting it to one splits notes of a third or more, and so on.
940
941 @lilypond[quote,verbatim]
942 instrumentOne = \relative c' {
943   a4 b c d |
944   e f g a |
945   b c d e |
946 }
947
948 instrumentTwo = \relative c' {
949   c4 c c c |
950   c c c c |
951   c c c c |
952 }
953
954 <<
955   \new Staff \partcombine \instrumentOne \instrumentTwo
956   \new Staff \partcombine #'(2 . 3) \instrumentOne \instrumentTwo
957 >>
958 @end lilypond
959
960
961 Both arguments to @code{\partcombine} will be interpreted as separate
962 @code{Voice} contexts, so if the music is being specified in relative
963 mode then @emph{both} parts must contain a @code{\relative} function,
964 i.e.,
965
966 @example
967 \partcombine
968   \relative @dots{} @var{musicexpr1}
969   \relative @dots{} @var{musicexpr2}
970 @end example
971
972 @noindent
973 A @code{\relative} section that encloses a @code{\partcombine} has no
974 effect on the pitches of @code{@var{musicexpr1}} or
975 @code{@var{musicexpr2}}.
976
977 @funindex \partcombineChords
978 @funindex partcombineChords
979 @funindex \partcombineApart
980 @funindex partcombineApart
981 @funindex \partcombineUnisono
982 @funindex partcombineUnisono
983 @funindex \partcombineSoloI
984 @funindex partcombineSoloI
985 @funindex \partcombineSoloII
986 @funindex partcombineSoloII
987 @funindex \partcombineAutomatic
988 @funindex partcombineAutomatic
989
990 In professional scores, voices are often kept apart from each other for
991 long passages of music even if some of the notes are the same in both
992 voices, and could just as easily be printed as unison. Combining notes
993 into a chord, or showing one voice as solo is, therefore, not ideal as
994 the @code{\partcombine} function considers each note separately. In this
995 case the @code{\partcombine} function can be overriden with the
996 following commands:
997
998 Commands ending in @code{@dots{}Once} apply only to the next note in the
999 music expression.
1000
1001 @itemize
1002 @item
1003 @code{\partcombineApart} and @code{\partcombineApartOnce} keep the
1004 notes as two separate voices, even if they can be combined into a chord
1005 or unison.
1006
1007 @item
1008 @code{\partcombineChords} and @code{\partcombineChordsOnce} combine the
1009 notes into a chord.
1010
1011 @item
1012 @code{\partcombineUnisono} and @code{\partcombineUnisonoOnce} combine
1013 both voices as @qq{unison}.
1014
1015 @item
1016 @code{\partcombineSoloI} and @code{\partcombineSoloIOnce} print only
1017 voice one, and mark it as a @qq{Solo}.
1018
1019 @item
1020 @code{\partcombineSoloII} or @code{\partcombineSoloIIOnce} print only
1021 voice two and mark it as a @qq{Solo}.
1022
1023 @item
1024 @code{\partcombineAutomatic} and @code{\partcombineAutomaticOnce} end
1025 the functions of the commands above, and revert back to the standard
1026 @code{\partcombine} functionality.
1027 @end itemize
1028
1029 @lilypond[quote,verbatim]
1030 instrumentOne = \relative c' {
1031   \partcombineApart c2^"apart" e |
1032   \partcombineAutomatic e2^"auto" e |
1033   \partcombineChords e'2^"chord" e |
1034   \partcombineAutomatic c2^"auto" c |
1035   \partcombineApart c2^"apart" \partcombineChordsOnce e^"chord once" |
1036   c2 c |
1037 }
1038 instrumentTwo = \relative c' {
1039   c2 c |
1040   e2 e |
1041   a,2 c |
1042   c2 c' |
1043   c2 c |
1044   c2 c |
1045 }
1046
1047 <<
1048   \new Staff { \instrumentOne }
1049   \new Staff { \instrumentTwo }
1050   \new Staff { \partcombine \instrumentOne \instrumentTwo }
1051 >>
1052 @end lilypond
1053
1054
1055 @subsubsubheading Using \partcombine with lyrics
1056
1057 @cindex \partcombine and lyrics
1058
1059 The @code{\partcombine} command is not designed to work with
1060 lyrics; if one of the voices is explicitly named in order to
1061 attach lyrics to it, the partcombiner will stop working.  However,
1062 this effect can be achieved using a @code{NullVoice} context.  See
1063 @ref{Polyphony with shared lyrics}.
1064
1065
1066 @snippets
1067
1068 @lilypondfile[verbatim,quote,texidoc,doctitle]
1069 {combining-two-parts-on-the-same-staff.ly}
1070
1071 @lilypondfile[verbatim,quote,texidoc,doctitle]
1072 {changing-partcombine-texts.ly}
1073
1074 @seealso
1075 Music Glossary:
1076 @rglos{a due},
1077 @rglos{part}.
1078
1079 Notation Reference:
1080 @ref{Writing parts}.
1081
1082 Snippets:
1083 @rlsr{Simultaneous notes}.
1084
1085 Internals Reference:
1086 @rinternals{PartCombineMusic},
1087 @rinternals{Voice}.
1088
1089 @knownissues
1090 All @code{\partcombine@dots{}} functions can only accept two voices.
1091
1092 @code{\partcombine@dots{}} functions cannot be placed inside a @code{\tuplet}
1093 or @code{\relative} block.
1094
1095 If @code{printPartCombineTexts} is set and the two voices play the same
1096 notes @qq{on and off}, in the same measure, the part combiner may
1097 typeset @code{a2} more than once in that measure.
1098
1099 @code{\partcombine} only knows when a note starts in a @code{Voice}; it
1100 cannot, for example, remember if a note in one @code{Voice} has already
1101 started when combining notes that have just started in the other
1102 @code{Voice}.  This can lead to a number of unexpected issues including
1103 @qq{Solo} or @qq{Unison} marks being printed incorrectly.
1104
1105 @code{\partcombine} keeps all spanners (slurs, ties, hairpins etc.) in
1106 the same @code{Voice} so that if any such spanners start or end in a
1107 different @code{Voice}, they may not be printed properly or at all.
1108
1109 If the @code{\partcombine} function cannot combine both music
1110 expressions (i.e. when both voices have different durations), it will
1111 give the voices, internally, its own custom names: @code{one} and
1112 @code{two} respectively.  This means if there is any @qq{switch} to a
1113 differently named @code{Voice} context, the events in that differently
1114 named @code{Voice} will be ignored.
1115
1116 Refer also to @emph{Known issues and warnings} when using
1117 @code{\partcombine} with tablature in @ref{Default tablatures} and the
1118 @emph{Note} in @ref{Automatic beams} when using automatic beaming.
1119
1120
1121 @node Writing music in parallel
1122 @unnumberedsubsubsec Writing music in parallel
1123
1124 @cindex writing music in parallel
1125 @cindex interleaved music
1126 @cindex parallel music
1127 @funindex \parallelMusic
1128 @funindex parallelMusic
1129
1130 Music for multiple parts can be interleaved in input code.  The
1131 function @code{\parallelMusic} accepts a list with the names of a
1132 number of variables to be created, and a musical expression.  The
1133 content of alternate measures from the expression become the value
1134 of the respective variables, so you can use them afterwards to
1135 print the music.
1136
1137 @warning{Bar checks @code{|} must be used, and the measures must
1138 be of the same length.}
1139
1140 @lilypond[quote,verbatim]
1141 \parallelMusic #'(voiceA voiceB voiceC) {
1142   % Bar 1
1143   r8 g'16 c'' e'' g' c'' e'' r8 g'16 c'' e'' g' c'' e'' |
1144   r16 e'8.~   4              r16 e'8.~   4              |
1145   c'2                        c'2                        |
1146
1147   % Bar 2
1148   r8 a'16 d'' f'' a' d'' f'' r8 a'16 d'' f'' a' d'' f'' |
1149   r16 d'8.~   4              r16 d'8.~   4              |
1150   c'2                        c'2                        |
1151
1152 }
1153 \new StaffGroup <<
1154   \new Staff << \voiceA \\ \voiceB >>
1155   \new Staff { \clef bass \voiceC }
1156 >>
1157 @end lilypond
1158
1159 Relative mode may be used.  Note that the @code{\relative} command
1160 is not used inside @code{\parallelMusic} itself.  The notes are
1161 relative to the preceding note in the voice, not to the previous
1162 note in the input -- in other words, relative notes for
1163 @code{voiceA} ignore the notes in @code{voiceB}.
1164
1165 @lilypond[quote,verbatim]
1166 \parallelMusic #'(voiceA voiceB voiceC) {
1167   % Bar 1
1168   r8 g16 c e g, c e r8 g,16 c e g, c e  |
1169   r16 e8.~ 4        r16 e8.~  4         |
1170   c2                c                   |
1171
1172   % Bar 2
1173   r8 a,16 d f a, d f r8 a,16 d f a, d f |
1174   r16 d8.~  4        r16 d8.~  4        |
1175   c2                 c                  |
1176
1177  }
1178 \new StaffGroup <<
1179   \new Staff << \relative c'' \voiceA \\ \relative c' \voiceB >>
1180   \new Staff \relative c' { \clef bass \voiceC }
1181 >>
1182 @end lilypond
1183
1184 This works quite well for piano music.  This example maps four
1185 consecutive measures to four variables:
1186
1187 @lilypond[quote,verbatim]
1188 global = {
1189   \key g \major
1190   \time 2/4
1191 }
1192
1193 \parallelMusic #'(voiceA voiceB voiceC voiceD) {
1194   % Bar 1
1195   a8    b     c   d     |
1196   d4          e         |
1197   c16 d e fis d e fis g |
1198   a4          a         |
1199
1200   % Bar 2
1201   e8      fis  g     a   |
1202   fis4         g         |
1203   e16 fis g  a fis g a b |
1204   a4           a         |
1205
1206   % Bar 3 ...
1207 }
1208
1209 \score {
1210   \new PianoStaff <<
1211      \new Staff {
1212        \global
1213        <<
1214          \relative c'' \voiceA
1215          \\
1216          \relative c'  \voiceB
1217        >>
1218      }
1219      \new Staff {
1220        \global \clef bass
1221        <<
1222          \relative c \voiceC
1223          \\
1224          \relative c \voiceD
1225        >>
1226      }
1227   >>
1228 }
1229 @end lilypond
1230
1231 @seealso
1232 Learning Manual:
1233 @rlearning{Organizing pieces with variables}.
1234
1235 Snippets:
1236 @rlsr{Simultaneous notes}.