]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/user/tutorial.itely
* lily/lookup.cc (LY_DEFINE): new function
[lilypond.git] / Documentation / user / tutorial.itely
1 @c -*-texinfo-*-
2
3 @c TODO:
4 @c   * LilyPond Lilypond lilypond (sometimes: the program)
5 @c   * more details about running lilypond; error messages,
6 @c     compiling/viewing (emacs?)
7 @c   * where to go from  First steps+More basics?
8
9 @node Tutorial
10 @chapter Tutorial
11
12 @html
13 <!--- @@WEB-TITLE@@=Tutorial --->
14 @end html
15
16 @menu
17 * First steps::                 Music language of LilyPond
18 * Running LilyPond::            Printing music
19 * More basics::                 
20 * Printing lyrics::             
21 * A lead sheet::                
22 * Listening to output::         
23 * More movements ::             Joining separate pieces of music
24 * Organising larger pieces::    
25 * A piano excerpt::             Piano music
26 * Fine tuning a piece::         
27 * An orchestral score::         Conductor's score and individual parts
28 * Integrating text and music::  Integrating text and music
29 @end menu
30
31 Operating is done through text files: To print a piece of music, you
32 enter the music in a file.  When LilyPond is run (normally using the
33 program @code{ly2dvi}) on that file, another file containing formatted
34 sheet music, is produced. That file may be printed or viewed.
35
36 This tutorial starts with a small introduction to the LilyPond music
37 language.  After this first contact, we will show which commands to
38 run to produce printed output, so you should then be able to create
39 your first sheets of music.  The tutorial continues with more and more
40 complex examples.
41
42
43 @node First steps
44 @section First steps
45
46 We start off by showing how very simple music is entered in LilyPond:
47 you get a note simply by typing its @htmlref{note name}, from @samp{a}
48 through @samp{g}.  So if you enter
49
50 @example
51 c d e f g a b
52 @end example
53
54 @noindent
55 then the result looks like this:
56
57 @c ?
58 @c \transpose c c' { c d e f g a b }
59 @c @lily pond[notime]
60 @c \property Score.timing = ##f
61 @lilypond[notime, relative=2]
62 c d e f g a b
63 @end lilypond
64
65 We will continue with this format: First we show a snippet of input,
66 then the resulting output.
67
68 The length of a note is specified by adding a number, @samp{1} for a
69 @rglos{whole note}, @samp{2} for a @rglos{half note}, and so on:
70
71 @example
72 a1 a2 a4 a16 a32
73 @end example
74
75 @lilypond[notime]
76 \property Score.timing = ##f
77 \property Staff.autoBeaming = ##f
78 \transpose c c' { a1 a2 a4 a16 a32 s16_" " }
79 @end lilypond
80
81 If you do not specify a @rglos{duration}, the previous one is used: 
82
83 @example
84 a4 a a2 a
85 @end example
86
87 @lilypond[notime]
88 \property Score.timing = ##f
89 \transpose c c' { a a a2 a s16_" " }
90 @end lilypond
91
92 A @rglos{sharp} (@texisharp{}) is made by adding @samp{is}, a
93 @rglos{flat} (@texiflat{}) by adding @samp{es}.  As you might expect,
94 a @rglos{double sharp} or @rglos{double flat} is made by adding
95 @samp{isis} or @samp{eses}:@footnote{This syntax derived from note
96 naming conventions in Nordic and Germanic languages, like German and
97 Dutch}
98
99 @example
100 cis1 ees fisis aeses
101 @end example
102
103 @lilypond[notime]
104 \property Score.timing = ##f
105 \transpose c c' { cis1 ees fisis aeses s16_" " }
106 @end lilypond
107
108 Add a dot @samp{.} after the duration to get a @rglos{dotted note}:
109
110 @example
111 a2. a4 a8. a16
112 @end example
113
114 @lilypond[notime]
115 \property Score.timing = ##f
116 \transpose c c' { a2. a4 a8. a16 s16_" " }
117 @end lilypond
118
119 Entering pitches and durations is fully explained in @ref{Pitches} and
120 @ref{Durations}.
121
122
123 The @rglos{meter} (or @rglos{time signature}) can be set with the
124 @code{\time} command:
125
126 @example
127 \time 3/4
128 \time 6/8
129 \time 4/4
130 @end example
131
132 @c a clef here may lead to confusion
133 @lilypond
134 \property Staff.Clef \set #'transparent = ##t 
135 \time 3/4
136 s4_" "
137 \time 6/8
138 s4_" "
139 \time 4/4
140 s16_" "
141 @end lilypond
142
143 Time signatures and other timing commands are described in @ref{Time
144 signature}.
145
146
147 The @rglos{clef} can be set using the @code{\clef} command:
148
149 @c what is more common name treble or violin?
150 @c in Dutch, its violin.
151 @c in English its definitely treble.
152 @example
153 \clef treble
154 \clef bass
155 \clef alto
156 \clef tenor
157 @end example
158
159 @lilypond[notime]
160 \property Score.timing = ##f
161 \clef violin
162 s4_" "
163 \clef bass
164 s4_" "
165 \clef alto
166 s4_" "
167 \clef tenor
168 s16_" "
169 @end lilypond
170
171 Clefs are fully explained in @ref{Clef}.
172
173
174 When you enter these commands in a file, you must to enclose them in
175 @code{\notes @{@dots{}@}}.  This lets LilyPond know that music (as
176 opposed to @rglos{lyrics}) follows:
177
178 @example
179 \notes @{
180   \time 3/4
181   \clef bass
182   c2 e4 g2.
183   f4 e d c2.
184 @}
185 @end example
186 Now the piece of music is almost ready to be printed.  The final step is to
187 combine the music with a printing command.
188
189 The printing command is the so-called @code{\paper} block.  Later on
190 you will see that the @code{\paper} block is used to customize
191 printing specifics.  The music and the @code{\paper} block are combined by
192 enclosing them in @code{\score @{ ... @}}.  This is what a full source file looks like:
193
194 @example
195 \score @{
196   \notes @{
197     \time 3/4
198     \clef bass
199     c2 e4 g2.
200     f4 e d c2.
201   @}
202   \paper @{ @}
203 @}
204 @end example
205
206 @lilypond[noindent]
207 \score {
208   \notes {
209      \time 3/4
210      \clef bass
211      c2 e4 g2.
212      f4 e d c2.
213   }
214   \paper {
215     linewidth = 55 * \staffspace
216   }
217 }
218 @end lilypond
219
220
221 @node Running LilyPond
222 @section Running LilyPond
223
224 In the last section we explained what kind of things you could enter
225 in a LilyPond file.  In this section we explain what commands to run
226 and how to view or print the output.  If you have not used LilyPond
227 before, want to test your setup, or want to run an example file
228 yourself, read this section.  The instructions that follow are for
229 Unix-like systems.  Some additional instructions for MS Windows are given
230 at the end of this section.
231
232 Begin by opening a terminal window and starting a text editor.
233 For example, you could open an xterm and execute @code{joe}.  In your
234 text editor, enter the following input and save the file as
235 @file{test.ly}:
236
237 @quotation
238 @example
239 \score @{
240   \notes @{ c'4 e' g' @}
241 @} 
242 @end example
243 @end quotation
244
245 @cindex ly2dvi
246
247 @c now this is weird, running ly2dvi to run LilyPond
248 @c (therefore name change proposal) 
249
250 LilyPond is the program that computes the sheet music. All other
251 things, such as adding titles, page breaking and other page layout,
252 are done by a small wrapper program called
253 @code{ly2dvi}. @code{ly2dvi} calls LilyPond to render the music, and
254 then adds the titling and page layout instructions.  To process
255 @file{test.ly} with @code{ly2dvi}, proceed as follows:
256
257 @quotation
258 @example
259 ly2dvi -p test.ly
260 @end example
261 @end quotation
262
263 You will see the following on your screen:
264
265 @quotation
266 @example
267 GNU LilyPond 1.7.16
268 Now processing: `/home/fred/ly/test.ly'
269 Parsing...
270 Interpreting music...[1]
271  @emph{ ... more interesting stuff ... }
272 PDF output to `test.pdf'...
273 DVI output to `test.dvi'...
274 @end example
275 @end quotation
276 @cindex DVI file
277 @cindex Viewing music
278 @cindex xdvi
279
280 The results of the ly2dvi run are two files, @file{test.dvi} and
281 @file{test.pdf}.  The PDF file (@file{test.pdf}) is the one you can
282 print or view.  For example, viewing PDF can be done with ghostview.
283 If a version of ghostview is installed on your system, one of these
284 commands will produce a window with some music notation on your
285 screen:
286 @c eeek
287 @quotation
288 @example
289   gv test.pdf
290   ghostview test.pdf
291   ggv test.pdf
292   kghostview test.pdf
293   xpdf test.pdf
294   gpdf test.pdf
295 @end example
296 @end quotation
297 If the music on your screen looks good, you can print it by clicking
298 File/Print inside ghostview.
299
300 The DVI file (@file{test.dvi}) contains the same sheet music in a
301 different format. DVI files are more easily processed by the computer,
302 so viewing them usually is quicker.  You can run @code{xdvi test.dvi}
303 @c KDVI doesn't grok the PS specials.
304 @c or
305 @c @code{kdvi test.dvi}
306 @c
307 to view the DVI file. In Xdvi, the mouse buttons
308 activate magnifying glasses.  Unfortunately, variable symbols (such as
309 beams and slurs) are not displayed in the magnifying glasses.
310
311
312 @cindex Ghostscript
313 @cindex @code{lpr}
314 @cindex Printing output
315 @cindex PostScript
316 @cindex PDF
317
318 If you are familiar with @TeX{}, be warned: do not use other DVI
319 drivers like @code{dvilj}.  LilyPond DVI use embedded PostScript code
320 and will not render correctly with other DVI drivers besides
321 @code{dvips}.
322
323 @cindex dvips
324 @cindex dvilj
325 @cindex DVI driver
326
327
328 Various commands for formatting and printing music are detailed in
329 @ref{Invoking LilyPond}.
330
331
332 @unnumberedsubsec Windows users
333
334 Windows users can start the terminal by clicking on the LilyPond or
335 Cygwin icon.  Any text editor (such as NotePad, Emacs or Vim) may be
336 used to edit the LilyPond file.  When Cygwin's @code{XFree86} X11
337 window system is installed along with @code{tetex-x11} and
338 @code{ghostscript-x11} packages, then the @code{dvi} output may be
339 viewed with @code{xdvi test.dvi} as described above.  If you have
340 installed a PostScript/PDF viewer, such as @code{GSView} from
341 @uref{http://www.cs.wisc.edu/~ghost}, viewing the PDF file can be done
342 with:
343 @quotation
344 @example
345 @code{gsview32 test.pdf}
346 @end example
347 @end quotation
348 Printing may be done by executing
349 @quotation
350 @example
351 @code{gsview32 /s test.pdf}
352 @end example
353 @end quotation
354
355
356 @node More basics
357 @section More basics 
358
359 We continue with the introduction of more musical constructs.  Normal
360 rests are entered just like notes with the name ``@code{r}'':
361
362 @quotation
363 @example
364 r2 r4 r8 r16
365 @end example
366
367 @lilypond[fragment]
368 \property Score.timing = ##f
369 \property Staff.Clef = \turnOff
370 \property Staff.TimeSignature = \turnOff
371 r2 r4 r8 r16
372 s16_" "
373 @end lilypond
374 @end quotation
375 @separate
376
377 Rests are described in full detail in @ref{Rests}. 
378
379
380 @c Tim wants to move this quotes example just before the: quotes-do not-work
381 @c score, but we'd need to remove quotes from the other two (key and
382 @c tie) examples...
383
384 @c better to have this just before the `octaves are bad' snipped
385 @c but we'd need to remove the ', from \key and tie 
386 To raise a note by an octave, add a high quote @code{'} (apostrophe) to
387 the note name, to lower a note one octave, add a ``low quote'' @code{,}
388 (a comma).  Middle C is @code{c'}:
389
390 @quotation
391 @example
392 c'4 c'' c''' \clef bass c c,
393 @end example
394
395 @lilypond[fragment]
396 \property Score.timing = ##f
397 \property Staff.TimeSignature = \turnOff
398 c'4 c'' c''' \clef bass c c,
399 @end lilypond
400 @end quotation
401 @separate
402
403 A tie is created by adding a tilde ``@code{~}'' to the first note
404 being tied.
405 @quotation
406 @lilypond[fragment,verbatim]
407 g'4-~ g' a'2-~ a'4
408 @end lilypond
409 @end quotation
410 @separate
411 A tie is different from a slur. A tie simply makes the first note
412 sound longer, and can only be used on pairs of notes with the same
413 pitch. Slurs indicate the articulations of notes, and can be used on
414 larger groups of notes. Slurs and ties are also nested in practice:
415 @lilypond[fragment, relative=1]
416 c2-~-( c8 fis fis4 ~ fis2 g2-)
417 @end lilypond
418
419 The notation manual discusses ties in @ref{Ties}.
420
421 The key signature is set with the command ``@code{\key}'', followed by
422 a pitch and  @code{\major} or @code{\minor}:
423 @quotation
424 @example
425 \key d \major
426 g'1
427 \key c \minor
428 g'
429 @end example
430
431 @lilypond[fragment]
432 \property Staff.TimeSignature = \turnOff
433 \key d \major
434 g'1
435 \key c \minor
436 g'
437 @end lilypond
438 @end quotation
439
440
441
442 @c bit on the long/complex/scary taste
443 @c cheating a bit: two lines makes for a friendlier look
444 This example shows notes, ties, octave marks, and rests in action.
445
446 @quotation
447 @example
448 \score @{
449   \notes @{
450     \time 4/4
451     \key d \minor
452     \clef violin
453     r4 r8 d''8 cis''4 e''
454     d''8 a'4.-~ a' b'8
455     cis''4 cis''8 cis'' bis'4 d''8 cis''-~
456     cis''2 r2
457   @}
458   \paper @{ @}
459 @}
460 @end example
461
462 @lilypond
463 \score {
464   \notes {
465     \time 4/4
466     \clef violin
467     \key d \minor
468     r4 r8 d''8 cis''4 e''
469     d''8 a'4.-~ a' b'8
470     cis''4 cis''8 cis'' bis'4 d''8 cis''-~
471     cis''2 r2
472   }
473   \paper { linewidth = 50*\staffspace }
474 }
475 @end lilypond
476 @end quotation
477
478 @c accidentals...
479 There are some interesting points to note in this example.
480 Accidentals (sharps and flats) do not have to be marked explicitly:
481 you just enter the note name, and an accidental is printed
482 automatically, only when necessary.  Bar lines and beams are drawn
483 automatically.  Line breaks are calculated automatically; it does not
484 matter where the lines breaks are in the source file. Finally, the
485 order of time, key and clef changes is not relevant: in the printout,
486 these are ordered using standard notation conventions.
487
488 The example also indicates that a piece of music written in a high
489 register needs lots of quotes.  This makes the input less readable,
490 and is also a potential source of errors.
491
492 The solution is to use ``relative octave'' mode.  In practice, this is
493 the most convenient way to copy existing music.  To use relative mode,
494 add @code{\relative} before the piece of music.  You must also give a
495 note from which relative starts, in this case @code{c''}.  If you do
496 not use octavation quotes (i.e. do not add ' or , after a note),
497 relative mode chooses the note that is closest to the previous one.
498 @c do not use commas or quotes in this sentence
499 For example: @code{c f} goes up; @code{c g} goes down:
500
501 @quotation
502 @example
503 \relative c'' @{
504   c f c g c
505 @}
506 @end example
507
508 @lilypond[fragment]
509 \property Score.timing = ##f
510 \property Staff.TimeSignature = \turnOff
511 \relative c'' {
512   c f c g c
513 }
514 @end lilypond
515 @end quotation
516 @separate
517
518
519 Since most music has small intervals, in relative mode pieces can be
520 written almost without using octavation quotes.
521
522 @c needed better, maybe even redundant explanation
523 @c   added another example below.
524 @c grappig: Pa vond het heel logies, en slim toen-i eenmaal begreep.
525 @c in eerste instantie drong het `relative' niet door zonder extra uitleg.
526 Larger intervals are made by adding octavation quotes.  Quotes or
527 commas do not determine the absolute height of a note; the height of a
528 note is relative to the previous one.
529 @c do not use commas or quotes in this sentence
530 For example: @code{c f,} goes down; @code{f, f} are both the same;
531 @code{c' c} are the same; and @code{c g'} goes up:
532
533 @quotation
534 @example
535 \relative c'' @{
536   c f, f c' c g' c,
537 @}
538 @end example
539
540 @lilypond[fragment]
541 \property Score.timing = ##f
542 \property Staff.TimeSignature = \turnOff
543 \relative c'' {
544   c f, f c' c g' c,
545 }
546 @end lilypond
547 @end quotation
548 @separate
549
550
551 Here is an example of the difference between relative mode and
552 ``normal'' (non-relative) mode:
553
554 @quotation
555 @example
556 \relative a @{
557 \clef bass
558   a d a e d c' d'
559 @}
560 @end example
561
562 @lilypond[fragment]
563 \property Score.timing = ##f
564 \property Staff.TimeSignature = \turnOff
565 \relative a {
566 \clef bass
567   a d a e d c' d'
568 }
569 @end lilypond
570 @end quotation
571 @separate
572
573 @quotation
574 @example
575 \clef bass
576   a d a e d c' d'
577 @end example
578
579 @lilypond[fragment]
580 \property Score.timing = ##f
581 \property Staff.TimeSignature = \turnOff
582 \clef bass
583   a d a e d c' d'
584 @end lilypond
585 @end quotation
586 @separate
587
588 A slur is drawn across many notes, and indicates bound articulation
589 (legato).  The starting note and ending note are marked with a
590 ``@code{(}'' and a ``@code{)}'' respectively:
591
592 @quotation
593 @lilypond[fragment,relative 1, verbatim]
594 d4-( c16-)-( cis d e c cis d e-)-( d4-)
595 @end lilypond
596 @end quotation
597 @separate
598
599 If you need two slurs at the same time (one for articulation, one for
600 phrasing), you can also make a phrasing slur with @code{\(} and
601 @code{\)}.
602
603 @c lousy example
604 @c ? --hwn
605 @c fragment of 1st hrn in Adams' The Chairman Dances, with creative
606 @c chromatic thing pasted in front.  (admittedly the original does not
607 @c have a phrasing slur. The problem is that we do not want the slur
608 @c and the Phrasing slur to collide. We are trying to make a good
609 @c impression here.
610
611 @quotation
612 @lilypond[fragment,relative 1, verbatim]
613 a8-(-\( ais b  c-) cis2 b'2 a4 cis,  c-\)
614 @end lilypond
615 @end quotation
616 @separate
617
618 Beams are drawn automatically, but if you do not like the choices, you
619 can enter beams by hand. Mark the first note to be beamed with
620 @code{[} and the last one with @code{]}:
621 @quotation
622 @lilypond[fragment,relative 1, verbatim]
623 a8-[ ais-] d-[ es r d-]
624 @end lilypond
625 @end quotation
626 @separate
627
628 To print more than one staff, each piece of music that makes up a staff
629 is marked by adding @code{\context Staff} before it.  These
630 @code{Staff}'s are then grouped inside @code{<} and @code{>}, as is
631 demonstrated here:
632
633 @quotation
634 @lilypond[fragment,verbatim]
635 <
636   \context Staff = staffA { \clef violin c'' }
637   \context Staff = staffB { \clef bass c }
638 >
639 @end lilypond
640 @end quotation
641
642 In this example, @code{staffA} and @code{staffB} are names that are
643 given to the staves.  It does not matter what names you give, as long
644 as each staff has a different name. If you give them the same name,
645 they are assumed to belong on the same staff, and will be printed like
646 that.
647
648 @separate
649
650 We can now typeset a melody with two staves:
651
652 @quotation
653 @lilypond[verbatim,singleline]
654 \score {
655   \notes 
656   < \context Staff = staffA {
657       \time 3/4
658       \clef violin
659       \relative c'' {
660         e2-( d4 c2 b4 a8-[ a-]
661         b-[ b-] g-[ g-] a2.-) }  
662     }
663     \context Staff = staffB {
664        \clef bass
665        c2 e4  g2.
666        f4 e d c2.
667     }
668   >
669   \paper {} 
670 }
671 @end lilypond
672 @end quotation
673
674 Notice that the time signature is specified in one melody staff only
675 (the top staff), but is printed on both.  LilyPond knows that the time
676 signature should be the same for all staves.
677
678 @separate
679
680 Common accents can be added to a note using @code{-.}, @code{--}, @code{->}:
681 @quotation
682 @lilypond[verbatim,relative 1]
683 c-. c-- c->
684 @end lilypond
685 @end quotation
686 @separate
687
688 Similarly, fingering indications can be added to a note using @code{-}
689 and the digit to be printed.
690 @lilypond[verbatim,relative 1]
691   c-3 e-5 b-2 a-1
692 @end lilypond
693
694
695   
696
697
698 Dynamic signs are made by adding the markings to the note:
699 @quotation
700 @lilypond[verbatim,relative 1]
701 c-\ff c-\mf
702 @end lilypond
703 @end quotation
704 @separate
705
706 Crescendi and decrescendi are started with the commands @code{\<} and
707 @code{\>}. The command @code{\!} finishes a crescendo on the note it
708 is attached to.
709 @quotation
710 @lilypond[verbatim,relative 1]
711 c2-\<  c2-\!-\ff  c2-\>  c2-\!
712 @end lilypond
713 @end quotation
714 @separate
715
716 Chords can be made by
717 surrounding pitches with @code{<<} and @code{>}>:
718 @quotation
719 @lilypond[relative 0, fragment,verbatim]
720 r4 <<c e g>>4 <<c f a>>8
721 @end lilypond
722 @end quotation
723 @separate
724
725
726 You can combine beams and ties with chords.  Beam and tie markings
727 must be placed outside the chord markers:
728 @quotation
729 @lilypond[relative 0, fragment,verbatim]
730 r4 <<c e g>>8-[ <<c f a>>-]-~ <<c f a>>
731 @end lilypond
732 @end quotation
733
734 @quotation
735 @example
736 r4 <<c e g>>8-\>-( <<c e g>> <<c e g>>  <<c f a>>8-\!-)
737 @end example
738 @lilypond[relative 0, fragment]
739 \slurUp
740 r4 <<c e g>>8-\>-( <<c e g>> <<c e g>>  <<c f a>>8-\!-)
741 @end lilypond
742 @end quotation
743 @separate
744
745
746 A pickup (or upstep) is entered with the keyword @code{\partial}. It
747 is followed by a duration: @code{\partial 4} is a quarter note upstep.
748 @lilypond[relative 1,verbatim,fragment]
749   \partial 8
750   f8 c2 d e
751 @end lilypond
752
753 Tuplets are made with the @code{\times} keyword.  It takes two
754 arguments: a fraction and a piece of music.  The duration of the piece
755 of music is multiplied by the fraction.  Triplets make notes occupy
756 2/3 of their notated duration, so for a triplet, the fraction is 2/3.
757 @c
758 @lilypond[relative 0,verbatim,fragment]
759   \times 2/3 { f8 g a }
760   \times 2/3 { c r c }
761 @end lilypond 
762
763
764
765
766 Comments are pieces of the input that are ignored.  There are two
767 types of comments. A line comments are introduced by @code{%}: after
768 that, the rest of that line is ignored.  Block comments span larger
769 sections of input.  Anything that is enclosed in @code{%@{} and
770 @code{%@}} is ignored too. The following fragment shows possible uses
771 for comments.
772
773 @example
774   % notes for twinkle twinkle follow:
775   c4 c   g' g  a a
776   
777   %@{
778   
779     This line, and the notes below
780     are ignored, since they are in a
781     block comment.
782
783     g g f f e e d d c2 
784   %@}
785 @end example
786
787
788
789
790
791 @node Printing lyrics
792 @section Printing lyrics
793 @cindex lyrics
794
795 Lyrics are entered by separating each syllable with a space, and
796 surrounding them with @code{\lyrics @{ @dots{} @}}, for example
797 @example
798   \lyrics @{ I want to break free @}
799 @end example
800
801 Like notes, lyrics are also a form of music, but they must not be
802 printed on a staff, which is the default way to print music. To print
803 them as lyrics, they must be marked with @code{ \context Lyrics}:
804 @example
805   \context Lyrics  \lyrics @{ I want to break free @}
806 @end example
807 The melody for this song is as follows
808 @lilypond[fragment,relative=1]
809    \partial 8
810      c8
811    \times 2/3 {  f4 g g } \times 2/3 { g4-( a2-) }
812 @end lilypond
813
814 The lyrics can be set to these notes, combining both with the
815 @code{\addlyrics} keyword:
816 @example
817  \addlyrics
818     \notes @{ @dots{} @}
819     \context Lyrics @dots{}
820 @end example
821
822 The final result is 
823 @lilypond[singleline,verbatim]
824 \score  {
825  \notes {
826   \addlyrics
827    \relative c' {
828      \partial 8
829      c8
830      \times 2/3 { f g g } \times 2/3 { g4-( a2-) }
831    }
832    \context Lyrics  \lyrics { I want to break free }
833  }
834  \paper{ }
835 }
836 @end lilypond
837
838 This melody ends on a @rglos{melisma}, a single syllable (``free'')
839 sung to more than one note. This is indicated with a @emph{extender
840 line}. It is entered as two  underscores, i.e.,
841 @example
842   \lyrics @{ I want to break free __ @}
843 @end example 
844 @lilypond[singleline]
845 \score  {
846  \notes {
847   \addlyrics
848    \relative c' {
849    \partial 8
850      c8
851      \times 2/3 { f g g } \times 2/3 { g4-( a2-) }
852    }
853    \context Lyrics  \lyrics { I want to break free __ }
854  }
855  \paper{ }
856 }
857 @end lilypond
858
859 Similarly, hyphens between words can be entered as two dashes,
860 resulting in a centered hyphen between two syllables.
861 @example
862   Twin -- kle twin -- kle
863 @end example
864 @lilypond[singleline]
865 \score {
866   \addlyrics \notes \relative f' { \time 2/4
867     f4 f c' c' }
868     \context Lyrics \lyrics { Twin -- kle twin -- kle
869  }}
870 @end lilypond
871
872 More options, like putting multiple lines of lyrics below a melody are
873 discussed in @ref{Vocal music}.
874
875
876 @node A lead sheet
877 @section A lead sheet
878
879 In popular music, it is common to denote accompaniment as chord-names.
880 Using them in LilyPond has two parts, just like lyrics: entering the
881 chords (with @code{\chords}), and printing them (with @code{\context
882 ChordNames}).
883
884 Chord names are entered by starting chords mode (with @code{\chords}).
885 In chords mode, you can enter chords with a letter (indicating the
886 root of the chord), and a durations following that.
887 @c
888 @lilypond[verbatim]
889   \chords { c2 f4. g8 } 
890 @end lilypond
891 The result of @code{\chords} is a list of chords, and is  equivalent
892 to entering chords with @code{<<@dots{}>>}.
893
894 Other chords can be created by adding modifiers, after a colon.  The
895 following example shows a few common modifiers
896 @c
897 @lilypond[verbatim]
898   \chords { c2 f4:m g4:maj7 gis1:dim7 }
899 @end lilypond
900
901 Printing chords is done by adding @code{\context ChordNames}
902 before the chords thus entered:
903 @c
904 @lilypond[verbatim]
905  \context ChordNames \chords \chords { c2 f4.:m g4.:maj7 gis8:dim7 }
906 @end lilypond
907
908 A complete list of modifiers, and other options for layout are in the
909 reference manual section @ref{Chords}.
910
911  
912 TODO: template example with chord names, lyrics and staff.
913
914
915 @node Listening to output
916 @section Listening to output
917  
918 @example 
919
920         \midi  @{ \tempo 4=72@}
921  
922 @end example 
923 MIDI (Musical Instrument Digital Interface) is a standard for
924 connecting and recording digital instruments.  A MIDI file is like a
925 tape recording of a MIDI instrument. The @code{\midi} block makes the
926 music go to a MIDI file, so you can listen to the music you entered.
927 It is great for checking the music: octaves that are off, or
928 accidentals that were mistyped, stand out very much when listening to
929 the musical transcription.
930
931 @code{\midi} is similar to @code{\paper @{ @}}, since it also
932 specifies an output method.  You can specify the tempo using the
933 @code{\tempo} command, in this case the tempo of quarter notes is set
934 to 72 beats per minute.
935
936
937
938
939 @node More movements 
940 @section More movements
941
942 The program @code{lilypond} only produces sheet music.  Titles,
943 subtitles, and the composer's name are created by a separate program,
944 called use @code{ly2dvi}.  @code{ly2dvi} creates the titles, then
945 calls @code{lilypond} to format the sheet music.  In this section, we
946 show you how to create titles like this:
947
948 @center @strong{Two miniatures}
949 @flushright
950 F. Bar Baz
951
952 Opus 1.
953 @end flushright
954 @flushleft
955 @var{Up}
956 @end flushleft
957 @lilypond
958   \score {
959     \notes { c'4 d'4 }
960     \paper { raggedright = ##t }
961   }
962 @end lilypond
963 @flushright
964 Opus 2.
965 @end flushright
966 @flushleft
967 @var{Down}
968 @end flushleft
969 @lilypond
970   \score {
971     \notes { d'4 c'4 }
972     \paper { linewidth = -1.0 }
973   }
974 @end lilypond
975
976 For example, consider the following file (@file{miniatures.ly}) 
977
978 @example
979 \header @{
980   title = "Two miniatures"
981   composer = "F. Bar Baz" 
982   tagline = "small is beautiful" @}
983
984 \score @{
985     \notes @{ c'4 d'4 @}
986     \header @{
987         opus = "Opus 1."
988         piece = "Up" @}
989 @}
990 \score @{
991     \notes @{ d'4 c'4 @}
992     \header @{
993         opus = "Opus 2."
994         piece = "Down" @}
995 @}
996 @end example
997
998
999 The information for the global titling is in a so-called header block.
1000 The information in this block is not used by LilyPond, but it is
1001 passed into @code{ly2dvi}, which uses this information to print titles
1002 above the music.
1003 @cindex assignments
1004 @cindex identifier assignment
1005 the @code{\header} block contains assignments.  In each assignment, a
1006 variable is set to a value. The header block for this file looks like
1007 this
1008 @cindex @code{\header}
1009 @example 
1010   \header @{
1011     title = "Two miniatures" 
1012     composer = "F. Bar Baz"
1013     tagline = "small is beautiful"
1014   @}
1015 @end example
1016
1017 When you process a file with ly2dvi, a signature line is printed at
1018 the bottom of the last page.  Many people find the default (``Lily was
1019 here'' with a version number) too droll.  If that is the case, you can
1020 change @code{tagline} in the @code{\header}, as shown above.
1021
1022 @cindex Lily was here
1023 @cindex signature line
1024 @cindex tag line
1025
1026
1027 @separate
1028 @example
1029     \header @{
1030 @end example
1031
1032 The @code{\header} is normally at the top of the file, where it sets
1033 values for the rest of the file.  If you want to typeset different
1034 pieces from one file (for example, if there are multiple movements, or
1035 if you are making an exercise book), you can put different
1036 @code{\score} blocks into the input file.  @code{ly2dvi} will assemble
1037 all LilyPond output files into a one document.  The contents of
1038 @code{\header} blocks specified within each score is used for the
1039 title of that movement.
1040 @separate
1041 @example
1042         opus = "Opus 1."
1043         piece = "Up" @}
1044 @end example
1045 For example, the Opus number is put at the right, and the "piece" string
1046 will be at the left.
1047
1048
1049
1050 @node Organising larger pieces
1051 @section Organising larger pieces
1052
1053 TODO: discuss identifiers, p&c, .
1054
1055 @separate
1056 @example 
1057 \version "1.5.72"
1058 @end example 
1059 Lilypond and its language are still under development, and
1060 occasionally details of the syntax are changed.  The @code{version}
1061 fragment indicates which LilyPond version the input file was written
1062 for.  When you compile this file, the version number will be checked
1063 and you will get a warning when the file is too old.  This version
1064 number is also used by the @code{convert-ly} program (See
1065 @ref{Invoking convert-ly}), which can used to update the file to the
1066 latest lily version.
1067
1068
1069 @node A piano excerpt
1070 @section A piano excerpt
1071
1072 Our eighth subject is a piece of piano music.  The fragment in the
1073 input file is a piano reduction of the G major Sinfonia by Giovanni
1074 Battista Sammartini, composed around 1740.  It's in the source
1075 package under the name @inputfileref{input/tutorial,sammartini.ly}.
1076
1077 @lilypondfile[smallverbatim]{sammartini.ly}
1078
1079 As you can see, this example features multiple voices on one staff.  To
1080 make room for those voices, their notes should be stemmed in opposite
1081 directions.
1082
1083
1084
1085 @separate
1086 @example 
1087 viola = \notes \relative c'  \context Voice = viola @{ 
1088 @end example 
1089 In this example you see multiple parts on a staff.  Each part is
1090 associated with one notation context.  This notation context handles
1091 stems and dynamics (among other things).  The type name of this
1092 context is @code{Voice}.  For each part we have to make sure that
1093 there is precisely one @code{Voice} context, so we give it a unique
1094 name (`@code{viola}').
1095
1096 @separate
1097
1098 @cindex arpeggio
1099
1100
1101
1102
1103
1104 @separate
1105 @example 
1106         g'8. b,16 
1107 @end example 
1108 Relative octaves work a little differently with chords.  The starting
1109 point for the note following a chord is the first note of the chord.  So
1110 the @code{g} gets an octave up quote: it is a fifth above the starting
1111 note of the previous chord (the central C).
1112
1113 @separate
1114 @example 
1115 s1 s2. r4 
1116 @end example 
1117 @code{s} is a spacer rest.  It does not print anything, but it does have
1118 the duration of a rest. It is useful for filling up voices that
1119 temporarily do not play. In this case, the viola does not come until one
1120 and a half measure later.
1121
1122 @separate
1123 @example 
1124 oboes = \notes \relative c'' \context Voice = oboe @{ 
1125 @end example 
1126 Now comes a part for two oboes.  They play homophonically, so we
1127 print the notes as one voice that makes chords. Again, we insure that
1128 these notes are indeed processed by precisely one context with
1129 @code{\context}.
1130 @separate
1131 @example 
1132   s4  g8. b,16 c8 r <<e' g>>8. <<f a>>16
1133 @end example
1134
1135 The oboes should have stems up to keep them from interfering with
1136 the staff-jumping bass figure.  To do that, we use @code{\voiceOne}.
1137
1138 @separate
1139 @example 
1140 \grace <<e g>>-( <<d f>>4-) <<c e>>2 
1141 @end example
1142 @cindex @code{\grace}
1143 @cindex ornaments
1144 @cindex grace notes
1145 @code{\grace} introduces grace notes.  It takes one argument, in this
1146 case a chord. A slur is introduced starting from the @code{\grace}
1147 ending on the following chord.
1148
1149 @separate
1150 @example 
1151 \times 2/3 
1152 @end example
1153 @cindex tuplet
1154 @cindex triplets
1155
1156 @separate
1157 @example 
1158 @{ <<d f>>8 <<e g>> <<f a>> @} 
1159 @end example 
1160 The piece of music to be `tripletted' is sequential music containing
1161 three chords.
1162
1163 @separate
1164 @example 
1165
1166 @end example 
1167 At this point, the homophonic music splits into two rhythmically
1168 different parts.  We cannot use a sequence of chords to enter this, so
1169 we make a "chord of sequences" to do it.  We start with the upper
1170 voice, which continues with upward stems:
1171 @separate
1172 @example 
1173  @{ \times 2/3 @{ a8 g c @} c2 @} 
1174 @end example
1175
1176 @separate
1177 @example
1178 \\
1179 @end example
1180 Entering multiple voices is demonstrated here. Separate the
1181 components of the voice (single notes or entire sequences) with
1182 @code{\\} in a simultaneous music expression. The @code{\\} separators
1183 split first voice, second voice, third voice, and so on.
1184
1185 As far as relative mode is concerned, the previous note is the
1186 @code{c'''2} of the upper voice, so we have to go an octave down for
1187 the @code{f}.
1188 @separate
1189 @example 
1190
1191   f,8 e e2
1192 @} > 
1193 @end example 
1194 This ends the two-part section.
1195 @separate
1196 @example 
1197 \grace <<c, e>>8-( <<b d>>8.-\trill <<c e>>16 |  
1198 @end example
1199 @cindex trill
1200 @cindex stemBoth
1201
1202 The bass has a little hoom-pah melody to demonstrate parts switching
1203 between staves.  Since it is repetitive, we use repeats:
1204 @separate
1205 @example 
1206 hoomPah  =  \repeat unfold 8
1207 @end example
1208 @cindex unfolded @code{\repeat}
1209 The unfolded repeat prints the notes in its argument as if they were
1210 written out in full eight times.
1211 @separate
1212
1213 @cindex staff switch, manual
1214 @cindex cross staff voice, manual
1215 @cindex @code{\translator}
1216
1217 @example
1218 \translator Staff = down
1219 \stemUp
1220 c8
1221 \translator Staff = up
1222 \stemDown
1223 c'8 @}
1224 @end example
1225 Voices can switch between staves.  Here you see two staff switching
1226 commands.  The first one moves to the lower staff, the second one to
1227 the lower one.  If you set the stem directions explicitly
1228 (using the identifiers @code{\stemUp} and @code{\stemDown}, the notes
1229 can be beamed together (despite jumping between staffs).
1230
1231 @separate
1232 @example 
1233 bassvoices = \notes \relative c' @{
1234 c4 g8. b,16
1235 \autochange Staff \hoomPah \context Voice
1236 @end example
1237
1238 @separate
1239 @example
1240         \translator Staff = down
1241 @end example
1242 @cindex staff switch
1243 @cindex cross staff voice
1244 We want the remaining part of this melody on the lower staff, so we do a
1245 manual staff switch here.
1246
1247
1248
1249
1250 @separate
1251 @example 
1252 \context PianoStaff 
1253 @end example 
1254  A special context is needed to get cross staff beaming right.  This
1255 context is called @code{PianoStaff}.
1256 @separate
1257 @example 
1258 \context Staff = bottom < \time 2/2 \clef bass 
1259 @end example 
1260 The bottom staff must have a different clef.
1261 @separate
1262 @example 
1263 indent = 0.0 
1264 @end example 
1265 To make some more room on the line, the first (in this case the only)
1266 line is not indented.  The line still looks very cramped, but that is due
1267 to the page layout of this document.
1268
1269
1270 @ignore
1271 [TODO:
1272
1273 * font-size
1274
1275 * Simple part combining in a Hymn
1276 @end ignore
1277
1278
1279 @node Fine tuning a piece
1280 @section  Fine tuning a piece
1281
1282 In this section we show some ways to fine tune the final output of a
1283 piece.  We do so using a single measure of a moderately complex piano
1284 piece: a Brahms intermezzo (opus 119, no. 1).  Both fragments (the
1285 tuned and the untuned versions) are in @file{input/tutorial/}.
1286
1287 The code for the untuned example shows us some new things.
1288
1289 @lilypondfile[verbatim]{brahms-original.ly}
1290
1291
1292 @cindex dynamics
1293 @cindex loudness
1294 @cindex forte
1295 @cindex crescendo
1296
1297
1298
1299
1300 Now that we have the basic piece of music entered, we want to fine
1301 tune it so that we get something that resembles the original printed
1302 edition by Schott/Universal Edition:
1303
1304 @lilypondfile{brahms-tweaked.ly}
1305
1306 @cindex tuning graphical objects
1307
1308 Fine tuning involves overriding the defaults of the printing system.
1309 We do this by setting variables which control how Lilypond prints
1310 symbols.  Printed symbols are called graphical objects (often
1311 abbreviated to @emph{grob}). Each object is described by a bunch of
1312 settings.  Every setting is a variable: it has a name and a value
1313 which you can change.  These values determine the fonts, offsets,
1314 sub-routines to be called on the object, etc.  The initial values of
1315 these settings are set in the Scheme file
1316 @file{scm/grob-description.scm}.
1317
1318 @cindex slur attachments
1319
1320 We start with the slur in the upper part, running from F sharp to A.  In
1321 the printed edition, this slur runs from stem to stem; in our version,
1322 the slur begins at the note head of the F sharp.  The following property
1323 setting forces all slurs to run from stem to stem (not from or to note
1324 heads!).
1325
1326 @example
1327   \property Voice.Slur \set #'attachment = #'(stem . stem)
1328 @end example
1329
1330 More precisely, this command modifies the definition of the @code{Slur}
1331 object in the current @code{Voice}.  The variable @code{attachment} is
1332 set to the pair of symbols @code{'(stem . stem)}. 
1333
1334 @cindex internal documentation
1335 @cindex finding graphical objects
1336 @cindex graphical object descriptions 
1337
1338 This command fixes one particular problem with a slur. The rest of
1339 this section explains how to figure out which properties to tune for
1340 your own scores. To discover this, you must have a copy of the
1341 internals document. This is a set of HTML pages which should be
1342 included if you installed a binary distribution.  [TODO: revise for
1343 new site.]  These HTML pages are also available on the web: go to the
1344 LilyPond website, click ``Documentation: Index'' on the side bar, look
1345 in the ``Information for uses'' section, and click on ``Documentation
1346 of internals''.
1347
1348 You might want to bookmark either the HTML files on your disk, or the
1349 one on the web (the HTML on your hard drive will load much faster than
1350 the ones on the web!).  One word of caution: the internals
1351 documentation is generated from the definitions that the program uses.
1352 Hence, the internals documentation is strongly tied to the version you
1353 use.  Before you proceed, make sure that the program and documentation
1354 have matching version numbers.
1355
1356 @c  TODO: the quote is incorrect, although that shouldn't be a big
1357 @c    problem for the reader.
1358 Suppose that you wanted to tune the behavior of the slur.  The first
1359 step is to get some general information on slurs in LilyPond.  Turn to
1360 the index, and look up ``slur''. The section on slurs says
1361 @quotation
1362 The grob for this object is @internalsref{Slur}, generally in
1363 @internalsref{Voice} context.
1364 @end quotation
1365
1366 So the graphical object for this object is called @code{Slur}, and
1367 slurs are created in the @code{Voice} context.  If you are reading
1368 this tutorial in the HTML version, then you can simply click Slur,
1369 otherwise, you should look it up the internal documentation: click
1370 ``grob overview'' and select ``slur'' (the list is alphabetical).
1371
1372 Now you get a list of all the properties that the slur object
1373 supports, along with their default values.  Among the properties we
1374 find the @code{attachment} property with its default setting.  
1375 The property documentation explains that the following setting will
1376 produce the desired effect:
1377 @example 
1378  \property Voice.Slur \set #'attachment = #'(stem . stem)
1379 @end example
1380
1381 @c this is a long section, and adding an extra space here helps to
1382 @c break it into smaller subsections and thus is easier to understand.
1383 @separate
1384
1385 Next we want to move the fingering `3'.  In the printed edition it is
1386 not above the stem, but a little lower and slightly left of the stem.
1387 From the user manual we find that the associated graphical object is
1388 called @code{Fingering}, but how do we know if we should use
1389 @code{Voice} or @code{Staff}?  In many cases, @code{Voice} is a safe
1390 bet, but you can also deduce this information from the internals
1391 documentation: if you visit the documentation of @code{Fingering}, you
1392 will notice
1393 @example
1394 Fingering grobs are created by: Fingering_engraver
1395 @end example
1396
1397 Clicking @code{Fingering_engraver} will show you the documentation of
1398 the module responsible for interpreting the fingering instructions and
1399 translating them to a @code{Fingering} object.  Such a module is called
1400 an @emph{engraver}.  The documentation of the @code{Fingering_engraver}
1401 says
1402 @example
1403 Fingering_engraver is part of contexts: Voice and TabVoice
1404 @end example
1405 so tuning the settings for Fingering should be done using either
1406 @example
1407   \property Voice.Fingering \set @dots{}
1408 @end example
1409 or
1410 @example
1411   \property TabVoice.Fingering \set @dots{}
1412 @end example
1413
1414 Since the @code{TabVoice} is only used for tab notation, we see that
1415 the first guess @code{Voice} was indeed correct.
1416
1417 @cindex setting object properties
1418 @cindex @code{extra-offset}
1419
1420 For shifting the fingering, we use the property @code{extra-offset}.
1421 The following command manually adds an offset to the object.  We move
1422 it a little to the left, and 1.8 staff space downwards.
1423 @example
1424  \once \property Voice.Fingering \set #'extra-offset = #'(-0.3 . -1.8) 
1425 @end example   
1426 The @code{extra-offset} is a low-level feature: it moves around
1427 objects in the printout; the formatting engine is completely oblivious
1428 to these offsets.  The unit of these offsets are staff-spaces.  The
1429 first number controls left-right movement; a positive number will move
1430 the object to the right.  The second number controls up-down movement;
1431 a positive number will move it higher.
1432 We only want to offset a single object, so this statement is adorned
1433 with @code{\once}.
1434
1435 @cindex property types
1436 @cindex translator properties
1437 @cindex grob properties
1438 @cindex music properties
1439 @separate
1440
1441 There are three different types of variables in LilyPond, something
1442 which can be confusing at first (and for some people it stays
1443 confusing).  Variables such as @code{extra-offset} and
1444 @code{attachment} are called grob properties.  They are not the same
1445 as translator properties, like @code{autoBeaming}.  Finally, music
1446 expressions are internally stored using properties (so-called music
1447 properties).  You will encounter music properties if you run Scheme
1448 functions on music using @code{\apply}.
1449
1450 The second fingering instruction should be moved up a little to avoid
1451 a collision with the slur.  This could be achieved with
1452 @code{extra-offset}, but in this case, a simpler mechanism also
1453 works.  We insert an empty text between the 5 and the note. The empty
1454 text pushes the fingering instruction away:
1455 @example
1456   a-)^" "^\markup @{ \finger "5" @} 
1457 @end example
1458
1459 A fingering instruction, which would be entered as @code{^5}, is put
1460 as close to the notes as possible, closer than the space entered to
1461 push away the 5. Hence, the 5 is entered as a normal text, with the
1462 formatting of fingering instructions.
1463  
1464 @separate
1465
1466 Normally one would specify all dynamics in the same voice, so that
1467 dynamics (such as @b{f} and @b{p}) will be aligned with hairpins.  But
1468 in this case, we do not want the decrescendo to be aligned with the
1469 piano sign.  We achieve this by putting the dynamic markings in different
1470 voices.  The crescendo should be above the upper staff.  This can be
1471 forced by using the precooked command 
1472 @example
1473   \dynamicsUp
1474 @end example
1475
1476 However, if you do that the decrescendo will be too close to the upper
1477 voice and collide with the stems.  Looking at the manual for dynamics,
1478 we notice that ``Vertical positioning of these symbols is handled by
1479 the @internalsref{DynamicLineSpanner} grob.''.  If we turn to the
1480 documentation of @code{DynamicLineSpanner}, we find that
1481 @code{DynamicLineSpanner} supports several so-called `interfaces'.
1482 This object not only puts objects next to the staff
1483 (@code{side-position-interface}), but it also groups dynamic objects
1484 (@code{axis-group-interface}), is considered a dynamic sign itself
1485 (@code{dynamic-interface}), and is an spanning object
1486 (@code{spanner-interface}).  It also has the standard
1487 @code{grob-interface} with all the variables that come with it.
1488
1489 For the moment we are interested in side positioning:
1490 @quotation
1491  side-position-interface
1492
1493   Position a victim object (this one) next to other objects (the
1494   support).  In this case, the direction signifies where to put the
1495   victim object relative to the support (left or right, up or down?)
1496 @end quotation
1497 Between the object and its support (in this case, the descending
1498 notes), there should be more space.  This space is controlled by
1499 @code{padding}, so we increase it.
1500 @example
1501  \property Voice.DynamicLineSpanner \override #'padding = #5.0
1502 @end example
1503
1504
1505 (TODO: huh? what's this: )
1506
1507 This command resembles the one for setting slur attachments, but
1508 subtly differs in its details.  Grob properties can be manipulated
1509 with two commands: @code{\override} extends the definition of a grob
1510 with one setting, and @code{\revert} releases this setting.  This has
1511 a theoretical appeal: the operations are simple and symmetric.  For
1512 practical use, it can be cumbersome.  The commands act like
1513 parentheses: you should carefully balance the use of @code{\override}
1514 and @code{\revert}.  The @code{\set} command is more friendly: it
1515 first does a @code{\revert} followed by @code{\override}.
1516
1517 @separate
1518
1519 Brahms uses music notation is a slightly unorthodox way.  Ties
1520 usually happen only within one voice.  In this piece, the composer
1521 gladly produces ties that jump voices.  We deal with this by faking
1522 these ties: whenever we need such a tie, we insert a notehead in a
1523 different voice, and blank the stem.  This is done in the following
1524 snippet of code.
1525
1526 @cindex transparent objects
1527 @cindex removing objects
1528 @cindex invisible objects
1529 @example
1530 \property Voice.Stem \set #'transparent = ##t
1531 d'
1532 @end example
1533 Blanking the stem should be done for only one object. One of the ways
1534 to achieve that, is by setting the property before a note. Reverting
1535 it afterwards is tedious, so for setting a property only once, we have
1536 the syntax @code{\once}: it reverts the property directly before
1537 proceeding to the next step in time.
1538
1539 The @code{\once} keyword is added to @code{\property}.
1540
1541
1542 Finally, the last tie is forced up using @code{\tieUp}.
1543
1544 @separate
1545
1546 Here is the complete ``fine tuned'' version, which includes all the
1547 modifications we discussed in this section:
1548
1549 @lilypondfile[verbatim]{brahms-tweaked.ly}
1550
1551
1552 @node An orchestral score
1553 @section An orchestral score
1554
1555 @menu
1556 * The full score::              
1557 * Extracting an individual part::  
1558 @end menu
1559
1560
1561 Our next two examples demonstrate one way to create an orchestral
1562 score in LilyPond.  When typesetting a piece for several instruments,
1563 you will want to create a full score (for the conductor) along with
1564 several individual parts (for the players).
1565
1566   We will declare the music for each instrument individually, giving
1567 the music of each instrument its own name.  These pieces of music are
1568 then combined in different @code{\score} blocks to produce different
1569 combinations of instruments (for example, one @code{\score} block may
1570 only include the cello part; another @code{\score} block may be for
1571 all the strings, and yet another @code{\score} block may be for all
1572 parts together).
1573
1574 This orchestral score example consists of three input files.  In the
1575 first file, @file{os-music.ly}, we define the music for all
1576 instruments.  This file will be used for producing the score and the
1577 separate parts, but the file does not produce any sheet music itself.
1578 Other files reference it by stating @code{\include "os-music.ly"}.
1579
1580 @example
1581 % os-music.ly
1582 \header @{
1583   title = "Zo, goed lieverd?"
1584   subtitle = "How's, this babe?"
1585   composer = "JCN"
1586   opus = "1"
1587   piece = "Laid back"
1588 @}
1589 global = @{
1590   \time 2/4
1591   \skip 2*4 \bar "|."
1592 @}
1593 Key = \notes \key as \major
1594 flautoI = \notes\relative c'' @{
1595   f8 g f g f g f g
1596   bes as bes as bes as bes as
1597 @}
1598 flautoII = \notes\relative c'' @{
1599   as8 bes as bes R1 d4 ~ d
1600 @}
1601 tromboI = \notes\relative c'' @{
1602   c4. c8 c8 c4. es4 r as, r
1603 @}
1604 tromboII = \notes\relative c'' @{
1605   as4. as8 as8 as4. R1*1/2 as4 es'
1606 @}
1607 timpani = \notes\relative c, @{
1608   \times 2/3 @{ f4 f f @}
1609   \times 4/5 @{ as8 as as as as @}
1610   R1
1611 @}
1612 corno = \notes\relative c' @{
1613    bes4 d f, bes d f, bes d
1614 @}
1615 @end example
1616
1617 We will not examine this example line by line, since you already know
1618 most of it.  We'll examine a few lines which contain new elements.
1619
1620
1621 @separate
1622 @example
1623 global = @{
1624   \time 2/4
1625   \skip 2*4 \bar "|."
1626 @}
1627 @end example
1628
1629 This declares settings to be used globally.  The @code{\skip} command
1630 produces no output, but moves forward in time: in this case, the
1631 duration of a half note (@code{2}), and that four times (@code{*4}).
1632 This brings us to the end of the piece, and we can set the end bar.
1633 You can use @code{s} as a shortcut for @code{\skip} (the last line of
1634 this section would be @code{s2*4 \bar"|."}).
1635
1636 @separate
1637 @example
1638 Key = \notes \key as \major
1639 @end example
1640 This declares the key signature of the piece and assign it to the
1641 identifier @var{Key}.  Later on we will use @code{\Key} for all staves
1642 except those for transposing instruments.
1643
1644 @node The full score
1645 @subsection The full score
1646
1647
1648 The second file, @inputfileref{input/tutorial,os-score.ly}, reads the
1649 definitions of the first (@inputfileref{input/tutorial,os-music.ly}), and
1650 defines the @code{\score} block for the full conductor's score.
1651
1652 @example
1653 \version "1.7.6"
1654
1655 \include "os-music.ly"
1656 \include "paper13.ly"
1657
1658 textFlat = \markup @{\smaller \musicglyph #"accidentals--1"@}
1659 \score @{
1660   <
1661     \global
1662     \property Score.BarNumber \override #'padding = #3
1663     \context StaffGroup = woodwind <
1664       \context Staff = flauti <
1665         \property Staff.midiInstrument = #"flute"
1666         \property Staff.instrument = "2 Flauti"
1667         \property Staff.instr = "Fl."
1668         \Key
1669         \context Voice=one @{ \voiceOne \flautoI @}
1670         \context Voice=two @{ \voiceTwo \flautoII @}
1671       >
1672     >
1673     \context StaffGroup = timpani <
1674       \context Staff = timpani <
1675         \property Staff.midiInstrument = #"timpani"
1676         \property Staff.instrument = \markup @{ \column <<  "Timpani" "(C-G)" >> @}
1677         \property Staff.instr = #"Timp."
1678         \clef bass
1679         \Key
1680         \timpani
1681       >
1682     >
1683     \context StaffGroup = brass <
1684       \context Staff = trombe <
1685         \property Staff.midiInstrument = #"trumpet"
1686         \property Staff.instrument = \markup @{ \column << "2 Trombe" "(C)" >> @}
1687         \property Staff.instr = \markup@{ \column << "Tbe." "(C)">> @}
1688         \Key
1689         \context Voice=one \partcombine Voice
1690           \context Thread=one \tromboI
1691           \context Thread=two \tromboII
1692       >
1693       \context Staff = corni <
1694         \property Staff.midiInstrument = #"french horn"
1695         \property Staff.instrument
1696         = \markup @{ \column << "Corno" @{ "(E"  \textFlat ")" @} >> @}
1697         \property Staff.instr =
1698         \markup @{ \column << "Cor." @{ "(E"  \textFlat ")" @} >> @}
1699         \property Staff.transposing = #3
1700         \notes \key bes \major
1701         \context Voice=one \corno
1702       >
1703     >
1704   >
1705   \paper @{
1706     indent = 15 * \staffspace
1707     linewidth = 60 * \staffspace
1708     textheight = 90 * \staffspace
1709     \translator@{
1710       \VoiceContext
1711       \consists "Multi_measure_rest_engraver"
1712     @}
1713     \translator@{
1714       \HaraKiriStaffContext
1715       \remove "Multi_measure_rest_engraver"
1716     @}
1717   @}
1718   \midi @{
1719     \tempo 4 = 75
1720   @}
1721 @}
1722 @end example
1723
1724 @center @strong{Zo, goed lieverd?}
1725 @sp 1
1726 @center How's, this babe?
1727 @flushright
1728 Opus 1.
1729 @end flushright
1730 @flushleft
1731 @sc{Laid back}
1732 @end flushleft
1733
1734 @lilypondfile{os-score.ly}
1735
1736 @separate
1737 @example
1738 \include "os-music.ly"
1739 @end example
1740 First we need to include the music definitions we made in
1741 @file{os-music.ly}.
1742
1743 @ignore
1744
1745 [TODO: mention in a more relevant place]
1746   
1747 @separate
1748 @example
1749 #(ly:set-point-and-click 'line-column)
1750 @end example
1751
1752 This piece of Scheme code executes the function
1753 @code{ly:set-point-and-click} with the argument
1754 @code{line-column}.  Editing input files can be complicated if you are
1755 working with large files: if you are digitizing existing music, you have
1756 to synchronize the .ly file, the sheet music on your lap and the sheet
1757 music on the screen.  The point-and-click mechanism makes it easy to
1758 find the origin of an error in the LY file: when you view the file with
1759 Xdvi and click on a note, your editor will jump to the spot where that
1760 note was entered.  For more information, see @ref{Point and click}.
1761 @end ignore
1762
1763
1764 @separate
1765 @example
1766 #(define text-flat '((font-relative-size . -2)
1767          (music "accidentals--1")))
1768 @end example
1769
1770 To name the transposition of the french horn, we will need a piece of
1771 text with a flat sign.  LilyPond has a mechanism for font selection and
1772 kerning called Scheme markup text (See @ref{Text markup}).  The flat
1773 sign is taken from the music font, and its name is @code{accidentals--1}
1774 (The natural sign is called @code{accidentals-0}).  The default font is
1775 too big for text, so we select a relative size of @code{-2}.
1776
1777 @separate
1778 @example
1779   <
1780     \global
1781 @end example
1782 All staves are simultaneous and use the same global settings.
1783
1784 @separate
1785 @example
1786     \property Score.BarNumber \override #'padding = #3
1787 @end example
1788 LilyPond prints bar numbers at the start of each line, but
1789 unfortunately they end up a bit too close to the staff in this
1790 example.  In LilyPond, a bar number is called @var{BarNumber}.
1791 BarNumber objects can be manipulated through their
1792 @var{side-position-interface}.  One of the properties of a
1793 @var{side-position-interface} that can be tweaked is @var{padding}:
1794 the amount of extra space that is put between this and other objects.
1795 We set the padding to three staff spaces.
1796
1797 You can find information on all these kind of properties in LilyPond's
1798 automatically generated documentation in
1799 @ifnottex
1800 @ref{ (lilypond-internals)lilypond-internals, LilyPond Internals}
1801 or in @ref{Fine tuning a piece}.
1802 @end ifnottex
1803 @iftex
1804 the online documentation or in the previous section of the tutorial.
1805 @end iftex
1806
1807 @c  REFERENCE MAO
1808
1809 @separate
1810 @example
1811     \context StaffGroup = woodwind <
1812       \context Staff = flauti <
1813 @end example
1814 A new notation context: the @code{StaffGroup}.  @code{StaffGroup} can
1815 hold one or more @code{Staff}s, and will print a big bracket at the
1816 left of the score.  This starts a new staff group for the woodwind
1817 section (just the flutes in this case).  Immediately after that, we
1818 start the staff for the two flutes, who also play simultaneously.
1819
1820 @separate
1821 @example
1822         \property Staff.midiInstrument = #"flute"
1823 @end example
1824 Specify the instrument for MIDI output (see @ref{MIDI instrument
1825 names}).
1826
1827 @separate
1828 @example
1829         \property Staff.instrument = "2 Flauti"
1830         \property Staff.instr = "Fl."
1831 @end example
1832 This defines the instrument names to be printed in the
1833 margin.  @code{instrument} specifies the name for the first line
1834 of the score, @code{instr} is used for the rest of the score.
1835
1836 @separate
1837 @example
1838         \Key
1839 @end example
1840 The flutes play in the default key.
1841
1842 @separate
1843 @example
1844         \context Voice=one @{ \voiceOne \flautoI @}
1845         \context Voice=two @{ \voiceTwo \flautoII @}
1846 @end example
1847 Last come the actual flute parts.  Remember that we are still in
1848 simultaneous mode.  We name both voices differently, so that LilyPond
1849 will create two Voice contexts.  The flute parts are simple, so
1850 we specify manually which voice is which: @code{\voiceOne} forces the
1851 direction of stems, beams, slurs and ties up, @code{\voiceTwo} sets
1852 directions down.
1853
1854 @separate
1855 @example
1856       >
1857     >
1858 @end example
1859 Close the flutes staff and woodwind staff group.
1860
1861 @separate
1862 @example
1863         \property Staff.instrument = #'(lines "Timpani" "(C-G)")
1864 @end example
1865 The timpani staff demonstrates a new piece of scheme markup, it sets two
1866 lines of text.
1867
1868 @separate
1869 @example
1870         \context Voice=one \partcombine Voice
1871           \context Thread=one \tromboI
1872           \context Thread=two \tromboII
1873 @end example
1874 You have seen the notation contexts Staff and Voice, but here is a new
1875 one: Thread.  One or more Threads can be part of a Voice.  Thread
1876 takes care of note heads and rests; Voice combine note heads onto a
1877 stem.
1878
1879 For the trumpets we use the automatic part combiner (see @ref{Automatic
1880 part combining}) to combine the two simultaneous trumpet parts onto the
1881 trumpet staff.  Each trumpet gets its own Thread context, which must be
1882 named @code{one} and @code{two}).  The part combiner makes these two
1883 threads share a Voice when they are similar, and splits the threads up
1884 when they are different.
1885
1886 @separate
1887 @example
1888 \property Staff.instrument = #`(lines "Corno"
1889   (columns "(E" ,text-flat ")"))
1890 @end example
1891 The french horn (``Corno'') has the most complex scheme markup name, made
1892 up of two lines of text.  The second line has three elements (columns) --
1893 the @code{(E}, the flat sign @code{text-flat} that we defined previously,
1894 and a final @code{")"}.  We use a backquote instead of an
1895 ordinary quote at the beginning of the Scheme expression to be able to
1896 access the @code{text-flat} identifier, `unquoting' it with a ``@code{,}''.
1897
1898 @separate
1899 @example
1900         \property Staff.transposing = #3
1901 @end example
1902 The french horn is to be tuned in E-flat, so we tell the MIDI back-end to
1903 transpose this staff by three steps.
1904
1905 Note how we can choose different tunings for the text input, sheet music
1906 output and, and MIDI output, using @code{\transpose} and the MIDI Staff
1907 property @var{transposing}.
1908
1909 @separate
1910 @example
1911         \notes \key bes \major
1912 @end example
1913 Since the horn is transposing, it is in a different key.
1914
1915 @separate
1916 @example
1917     indent = 15 * \staffspace
1918     linewidth = 55 * \staffspace
1919 @end example
1920 We specify a big indent for the first line and a small linewidth for this
1921 tutorial.
1922
1923 @separate
1924
1925 Usually the default setup of notation contexts (Thread, Voice, Staff,
1926 Staffgroup, Score) is just fine.  But in this case we want a different
1927 type of Staff context.
1928
1929 @example
1930     \translator@{
1931       \HaraKiriStaffContext
1932     @}
1933 @end example
1934
1935 In orchestral scores it often happens that one instrument only has
1936 rests during one line of the score.  @code{HaraKiriStaffContext} can
1937 be used as a regular @code{StaffContext} drop-in and will take care of
1938 the automatic removing of empty staves -- so if the strings are the
1939 only instruments playing for a line, LilyPond will only print the string
1940 parts for that line of the score.  This reduces the number of page turns
1941 (and the number of dead trees!) required in a score.
1942
1943 @node Extracting an individual part
1944 @subsection Extracting an individual part
1945
1946 The third file, @file{os-flute-2.ly} also reads the definitions of the
1947 first (@file{os-music.ly}), and defines the @code{\score} block for the
1948 second flute part.
1949
1950 @example
1951 \include "os-music.ly"
1952 \include "paper16.ly"
1953
1954 \score @{
1955   \context Staff <
1956     \property Score.skipBars = ##t
1957     \property Staff.midiInstrument = #"flute"
1958     \global
1959     \Key
1960     \flautoII
1961   >
1962   \header @{
1963     instrument = "Flauto II"
1964   @}
1965   \paper @{
1966     linewidth = 80 * \staffspace
1967     textheight = 200 * \staffspace
1968   @}
1969   \midi @{
1970     \tempo 4 = 75
1971   @}
1972 @}
1973 @end example
1974
1975 @center @strong{Zo, goed lieverd?}
1976 @sp 1
1977 @center How's, this babe?
1978 @center @emph{Flauto II}
1979 @flushright
1980 Opus 1.
1981 @end flushright
1982 @flushleft
1983 @sc{Laid back}
1984 @end flushleft
1985 @lilypondfile{os-flute-2.ly}
1986
1987
1988 Because we separated the music definitions from the @code{\score}
1989 instantiations, we can easily define a second score with the music of
1990 the second flute.  This is the part for the second flute player.  Of
1991 course, we would make separate parts for all individual instruments if
1992 we were preparing the score for an orchestra.
1993
1994 @separate
1995 @example
1996     \flautoII
1997 @end example
1998 In this individual part the second flute has a whole staff for itself,
1999 so we do not want to force stem or tie directions.
2000
2001 @separate
2002 @example
2003   \header @{
2004     instrument = "Flauto II"
2005   @}
2006 @end example
2007 The @code{\header} definitions were also read from @file{os-music.ly},
2008 but we need to set the instrument for this particular score.
2009
2010 @separate
2011 @example
2012     \property Score.skipBars = ##t
2013 @end example
2014 In the conductor's full score, all bars with rests are printed, but for
2015 the individual parts, we want to print one multimeasure rest instead of
2016 many consecutive empty bars.  LilyPond will do this if
2017 @code{Score.skipBars} is set to true (@code{##t}).
2018
2019
2020 @node Integrating text and music
2021 @section Integrating text and music
2022
2023
2024 @cindex La@TeX{}, music in
2025 @cindex HTML, music in
2026 @cindex Texinfo, music in
2027
2028 Sometimes you might want to use music examples in a text that you are
2029 writing (for example a musicological treatise, a songbook, or (like us)
2030 the LilyPond manual).  You can make such texts by hand, simply by
2031 importing a PostScript figure into your word processor.  However,
2032 there is an automated procedure to reduce the amount of work.
2033
2034 If you use HTML, La@TeX{}, or Texinfo, you can mix text and LilyPond
2035 code.  A script called @code{lilypond-book} will extract the music
2036 fragments, run LilyPond on them, and put back the resulting notation.
2037 This program is fully described in @ref{lilypond-book manual}.  Here
2038 we show a small example.  Since the example also contains explanatory
2039 text, we will not comment it further.
2040
2041 @example
2042 \documentclass[a4paper]@{article@}
2043 \begin@{document@}
2044
2045 In a lilypond-book document, you can freely mix music and text. For
2046 example:
2047 \begin@{lilypond@}
2048   \score @{ \notes \relative c' @{
2049      c2 g'2 \times 2/3 @{ f8 e d @} c'2 g4
2050   @} @}
2051 \end@{lilypond@}
2052
2053 Notice that the music line length matches the margin settings of the
2054 document.
2055
2056 If you have no \verb+\score+ block in the fragment,
2057 \texttt@{lilypond-book@} will supply one:
2058
2059 \begin@{lilypond@}
2060   c'4
2061 \end@{lilypond@}
2062
2063 In the example you see here, two things happened: a
2064 \verb+\score+ block was added, and the line width was set to natural
2065 length. You can specify many more options using  \LaTeX style options
2066 in brackets:
2067
2068 \begin[verbatim,11pt,singleline,
2069   fragment,relative,intertext="hi there!"]@{lilypond@}
2070   c'4 f bes es
2071 \end@{lilypond@}
2072
2073 The option \texttt@{verbatim@} prints the LilyPond code in addition to
2074 the graphical score, \texttt@{11pt@} selects the default music size,
2075 \texttt@{fragment@} adds a score block, \texttt@{relative@} uses
2076 relative mode for the fragment, and \texttt@{intertext@} specifies
2077 what to print between the \texttt@{verbatim@} code and the music.
2078
2079 If you want to include large examples into the text, it may be more
2080 convenient to put the example in a separate file:
2081
2082 \lilypondfile[printfilename]@{sammartini.ly@}
2083
2084 The \texttt@{printfilename@} option adds the file name to the output.
2085
2086 \end@{document@}
2087 @end example
2088
2089 Under Unix, you can view the results as follows.
2090 @example
2091 $ cd input/tutorial
2092 $ mkdir -p out/
2093 $ lilypond-book --outdir=out/ lilbook.tex
2094 lilypond-book (GNU LilyPond) 1.7.16
2095 Reading `input/tutorial/lilbook.tex'
2096 Reading `input/tutorial/sammartini.ly'
2097 @var{lots of stuff deleted}
2098 Writing `out/lilbook.latex'
2099 $ cd out
2100 $ latex lilbook.latex
2101 @var{lots of stuff deleted}
2102 $ xdvi lilbook 
2103 @end example
2104
2105 Notice the @code{outdir} option to lilypond-book. Running lilypond-book
2106 and running latex creates a lot of temporary files, and you would not want
2107 those to clutter up your working directory. Hence, we have them created
2108 in a separate subdirectory.
2109
2110 The result looks more or less like this: 
2111
2112 @separate
2113
2114 In a lilypond-book document, you can freely mix music and text. For
2115 example:
2116 @lilypond
2117 \score {
2118   \notes \relative c' {
2119     c2 g'2 \times 2/3 { f8 e d } c'2 g4
2120   }
2121   \paper {
2122     raggedright = ##t
2123   }
2124 }
2125 @end lilypond
2126
2127 Notice that the music line length matches the margin settings of the
2128 document.
2129
2130 If you have no @code{\score} block in the fragment,
2131 @code{lilypond-book} will supply one:
2132
2133 @lilypond
2134   c'4
2135 @end lilypond
2136
2137 In the example you see here, a number of things happened: a
2138 @code{\score} block was added, and the line width was set to natural
2139 length. You can specify many more options using  La@TeX{} style options
2140 in brackets:
2141
2142 @lilypond[verbatim,11pt,singleline,
2143   fragment,relative,intertext="hi there!"]
2144   c'4 f bes es
2145 @end lilypond
2146
2147 The option @code{verbatim} also shows the LilyPond code, @code{11pt} selects
2148 the default music size, @code{fragment} adds a score block,
2149 @code{relative} uses relative mode for the fragment, and
2150 @code{intertext} specifies what to print between the
2151 @code{verbatim} code and the music.
2152
2153 If you include large examples into the text, it may be more convenient
2154 to put the example in a separate file:
2155
2156 @lilypondfile[printfilename]{sammartini.ly}
2157
2158 The @code{printfilename} option adds the file name to the output.
2159
2160 [TODO: include excercises? ]