X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Ftutorial.itely;h=b220d2ca0a6ce138074b3d647c9350cc2f6ee0f4;hb=402045837e7134cdf90d1fcf31768c62227a4936;hp=30b530de78bb9988bb565204d89fa57a7c1d4fdf;hpb=5e566512883d7399766b6fd643c8e93146b96dcf;p=lilypond.git diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely index 30b530de78..b220d2ca0a 100644 --- a/Documentation/user/tutorial.itely +++ b/Documentation/user/tutorial.itely @@ -1,143 +1,157 @@ +\version "2.1.22" @c -*-texinfo-*- +@c This file is part of lilypond.tely -@c TODO: LilyPond LilyPond LilyPond +@c TODO: +@c * more details about running lilypond; error messages, +@c compiling/viewing (emacs?) +@c * where to go from First steps+More basics? @node Tutorial @chapter Tutorial -@html - -@end html + + +Using LilyPond comes down to encoding music in an input file. After +entering the music, the program is run on the file producing output +which can be viewed or printed. In this tutorial, we will show step +by step how to enter such files, and illustrate the process with +fragments of input and the corresponding output. At the end of every +section, a paragraph will list where to find further information on +the topics discussed. + +Many people learn programs by trying and fiddling around with the +program. This is also possible with LilyPond. If you click on a +picture in the HTML version of this manual, you will see the exact +LilyPond input that was used to generate that image. +@ifhtml +For example, consider the following input: +@example + c'^\markup @{ \bold \huge @{ Click on this image! @} @} +@end example +@c @lily pond[relative=1,raggedright,with the following output:] +with the following output: +@lilypond[relative=1,raggedright] + c'^\markup { \bold \huge { Click on this image! } } +@end lilypond + +@end ifhtml +By cutting and pasting the full input into a test file, you have a +starting template for experiments. If you like learning in this way, +you will probably want to print out or bookmark +@ifhtml +the +@end ifhtml +@ref{Cheat sheet}, which is a table listing all commands for quick +reference. + + +This tutorial starts with a short introduction to the LilyPond music +language. After this first contact, we will show you how to to +produce printed output. You should then be able to create and print +your first sheets of music. @menu -* First steps:: Music language of LilyPond -* Running LilyPond:: Printing music -* More basics:: +* First steps:: +* Running LilyPond:: +* More about pitches:: +* Octave entry:: +* Combining music into compound expressions:: +* Adding articulation marks to notes:: +* Combining notes into chords:: +* Basic rhythmical commands:: +* Commenting input files:: * Printing lyrics:: -* A melody with chords :: -* More stanzas:: -* More movements :: Joining separate pieces of music -* A piano excerpt:: Piano music -* Fine tuning a piece:: -* An orchestral score:: Conductor's score and individual parts -* Integrating text and music:: Integrating text and music -* End of tutorial:: The end +* A lead sheet:: +* Listening to output:: +* Titling:: +* Single staff polyphony:: +* Piano staves:: +* Setting variables:: +* Fine tuning layout:: +* Organizing larger pieces:: +* An orchestral part:: +* Integrating text and music:: @end menu -Operating lilypond is done through text files: to print a piece of -music, you enter the music in a file. When you run lilypond (normally -using the program @code{ly2dvi}) on that file, the program produces -another file which contains sheet music that you can print or view. - -This tutorial starts with a small introduction to the LilyPond music -language. After this first contact, we will show you how to run -LilyPond to produce printed output; you should then be able to create -your first sheets of music. The tutorial continues with more and more -complex examples. @node First steps @section First steps -We start off by showing how very simple music is entered in -LilyPond: you get a note simply by typing its note name, from -@code{a} through @code{g}. So if you enter -@quotation +We start off by showing how very simple music is entered in LilyPond: +you get a note simply by typing its note name, from @samp{a} +through @samp{g}. So if you enter + @example c d e f g a b @end example -@end quotation + +@noindent then the result looks like this: -@quotation -@lilypond[fragment] -\property Score.timing = ##f -\property Staff.TimeSignature = \turnOff -\transpose c'' { c d e f g a b } -@end lilypond -@end quotation -@separate -We will continue with this format: first we show a snippet of input, -then the resulting output. +@lilypond[notime,relative] +c d e f g a b +@end lilypond -The length of a note is specified by adding a number, ``@code{1}'' for a -whole note, ``@code{2}'' for a half note, and so on: +The length of a note is specified by adding a number, @samp{1} for a +@rglos{whole note}, @samp{2} for a @rglos{half note}, and so on: -@quotation @example a1 a2 a4 a16 a32 @end example -@c missing clef seems to raise more questions than actual pitch of notes, -@c as these are snippets anyway -@lilypond[fragment] -\property Score.timing = ##f -\property Staff.TimeSignature = \turnOff -\property Staff.autoBeaming = ##f -%\property Staff.Clef = \turnOff -\transpose c'' { a1 a2 a4 a16 a32 } -s16_" " +@lilypond[notime] +\set Score.timing = ##f +\set Staff.autoBeaming = ##f +\transpose c c' { a1 a2 a4 a16 a32 s16_" " } @end lilypond -@end quotation -@separate -If you don't specify a duration, the previous one is used: -@quotation +If you do not specify a @rglos{duration}, the previous one is used: + @example a4 a a2 a @end example -@c missing clef seems to raise more questions than actual pitch of notes, -@c as these are snippets anyway -@lilypond[fragment] -\property Score.timing = ##f -\property Staff.TimeSignature = \turnOff -%\property Staff.Clef = \turnOff -\transpose c'' { a a a2 a } -s16_" " +@lilypond[notime] +\set Score.timing = ##f +\transpose c c' { a a a2 a s16_" " } @end lilypond -@end quotation -@separate -A sharp (@texisharp{}) is made by adding ``@code{is}'', a flat -(@texiflat{}) by adding ``@code{es}''. As you would expect, a -double-sharp or double-flat is made by adding ``@code{isis}'' or -``@code{eses}'': +Rests are entered just like notes, but with the name ``@code{r}'': + +@cindex rests @quotation @example -cis1 ees fisis aeses +r2 r4 r8 r16 @end example @lilypond[fragment] -\property Score.timing = ##f -\property Staff.TimeSignature = \turnOff -\transpose c'' { cis1 ees fisis aeses } +\set Score.timing = ##f +\set Staff.Clef = \turnOff +\set Staff.TimeSignature = \turnOff +r2 r4 r8 r16 s16_" " @end lilypond @end quotation @separate -Add a dot ``@code{.}'' after the duration to get a dotted note: -@quotation + +Add a dot @samp{.} after the duration to get a @rglos{dotted note}: + @example a2. a4 a8. a16 @end example -@c missing clef seems to raise more questions than actual pitch of notes, -@c as these are snippets anyway -@lilypond[fragment] -\property Score.timing = ##f -\property Staff.TimeSignature \set #'transparent = ##t -%\property Staff.Clef = \turnOff -\transpose c'' { a2. a4 a8. a16 } -s16_" " +@lilypond[notime] +\set Score.timing = ##f +\transpose c c' { a2. a4 a8. a16 s16_" " } @end lilypond -@end quotation -@separate -The meter (or time signature) can be set with the @code{\time} command: -@quotation +The @rglos{meter} (or @rglos{time signature}) can be set with the +@code{\time} command: + @example \time 3/4 \time 6/8 @@ -145,8 +159,8 @@ The meter (or time signature) can be set with the @code{\time} command: @end example @c a clef here may lead to confusion -@lilypond[fragment] -\property Staff.Clef \set #'transparent = ##t +@lilypond +\override Staff.Clef #'transparent = ##t \time 3/4 s4_" " \time 6/8 @@ -154,15 +168,13 @@ s4_" " \time 4/4 s16_" " @end lilypond -@end quotation -@separate -The clef can be set using the ``@code{\clef}'' command: + +The @rglos{clef} can be set using the @code{\clef} command: @c what is more common name treble or violin? @c in Dutch, its violin. @c in English its definitely treble. -@quotation @example \clef treble \clef bass @@ -170,9 +182,8 @@ The clef can be set using the ``@code{\clef}'' command: \clef tenor @end example -@lilypond[fragment] -\property Score.timing = ##f -\property Staff.TimeSignature = \turnOff +@lilypond[notime] +\set Score.timing = ##f \clef violin s4_" " \clef bass @@ -182,80 +193,93 @@ s4_" " \clef tenor s16_" " @end lilypond -@end quotation -@separate -@c From these commands and notes, a piece of music can be formed. A piece -@c of music is made by enclosing it in ``@code{\notes @{ ... @}}''. -@c rephrased: -When you enter these commands in a file, you must to enclose them in -``@code{\notes @{ .. @}}''. This lets LilyPond know that music (and -not lyrics, for example) follows: +Notes and commands like @code{\clef} and @code{\time}, are enclosed +in @code{\notes @{@dots{}@}}. This indicates that music (as opposed +to @rglos{lyrics}) follows: -@quotation @example \notes @{ - \time 3/4 - \clef bass - c2 e4 g2. - f4 e d c2. + \time 3/4 + \clef bass + c2 e4 g2. + f4 e d c2 r4 @} @end example -@end quotation -@separate - Now the piece of music is almost ready to be printed. The final step is to combine the music with a printing command. -The printing command is the so-called ``@code{\paper}'' block. Later on -you will see that the @code{\paper} block is used to customize -printing specifics. The music and the @code{\paper} block are combined by -enclosing them in ``@code{\score @{ ... @}}''. This is what a full -LilyPond source file looks like: +The printing command is the so-called @code{\paper} block: + +@example +\paper @{ @} +@end example + +The @code{\paper} block is used to customize printing specifics. The +customization commands go between @code{@{} and @code{@}}, but for +now, we accept the defaults. The music and the @code{\paper} block +are combined by enclosing them in @code{\score @{ ... @}}, so the +following is a complete and valid input file: -@quotation @example \score @{ \notes @{ - \time 3/4 - \clef bass - c2 e4 g2. - f4 e d c2. + \time 3/4 + \clef bass + c2 e4 g2. + f4 e d c2 r4 @} \paper @{ @} @} @end example -@lilypond +@lilypond[noindent] \score { \notes { \time 3/4 \clef bass c2 e4 g2. - f4 e d c2. + f4 e d c2 r4 + } + \paper { + linewidth = 55 * \staffspace } - \paper { linewidth = 60 * \staffspace } } @end lilypond -@end quotation -@separate +In the rest of the tutorial we will often leave out @code{\score} +and @code{\paper} for clarity. However, both must be present when +feeding the file to LilyPond. + +For more elaborate information on + +@table @asis +@item entering pitches and durations +see +@ref{Pitches} and @ref{Durations}. +@item Clefs +see @ref{Clef} +@item Time signatures and other timing commands +see @ref{Time signature}. +@end table @node Running LilyPond @section Running LilyPond In the last section we explained what kind of things you could enter -in a lilypond file. In this section we explain how to run LilyPond -and how view or print the output. If you have not used LilyPond -before, want to test your setup of LilyPond, or want to run an example -file yourself, read this section. The instructions that follow -are for running LilyPond on Unix-like systems. Some additional -instructions for running LilyPond on Windows are given at the end of -this section. - -Begin by opening a terminal window and starting a text editor. -For example, you could open an xterm and execute @code{joe}. In your -text editor, enter the following input and save the file as +in a LilyPond file. In this section we explain what commands to run +and how to view or print the output. If you have not used LilyPond +before, want to test your setup, or want to run an example file +yourself, read this section. The instructions that follow are for +Unix-like systems. Some additional instructions for Microsoft Windows +are given at the end of this section. + +Begin by opening a terminal window and starting a text editor. For +example, you could open an xterm and execute +@code{joe}.@footnote{There are macro files for VIM addicts, and there +is a @code{LilyPond-mode} for Emacs addicts. If it has not been +installed already, then refer to the file @file{INSTALL.txt}}. In +your text editor, enter the following input and save the file as @file{test.ly}: @quotation @@ -266,34 +290,24 @@ text editor, enter the following input and save the file as @end example @end quotation -@cindex ly2dvi - -@c now this is weird, running ly2dvi to run LilyPond -@c (therefore name change proposal) - -LilyPond is the program that computes the sheet music. All other -things, such as adding titles, page breaking and other page layout, -are done by a small wrapper program called -@code{ly2dvi}. @code{ly2dvi} calls lilypond to render the music, and -then adds the titling and page layout instructions. To process -@file{test.ly} with @code{ly2dvi}, proceed as follows: +To process @file{test.ly}, proceed as follows: @quotation @example -ly2dvi -P test.ly +lilypond test.ly @end example @end quotation -You will see the following on your screen: +You will see something resembling: @quotation @example -GNU LilyPond 1.6.0 +GNU LilyPond 1.8.0 Now processing: `/home/fred/ly/test.ly' Parsing... Interpreting music...[1] @emph{ ... more interesting stuff ... } -PS output to `test.ps'... +PDF output to `test.pdf'... DVI output to `test.dvi'... @end example @end quotation @@ -301,239 +315,178 @@ DVI output to `test.dvi'... @cindex Viewing music @cindex xdvi -The results of the ly2dvi run are two files, @file{test.dvi} and -@file{test.ps}. The PS file (@file{test.ps}) is the one you can print. -You can view the PS file using the program ghostview. If a version of -ghostview is installed on your system, one of these commands will -produce a window with some music notation on your screen: -@c eeek +The result is the file @file{test.pdf}.@footnote{For @TeX{} +afficionados: there is also a @file{test.dvi} file. It can be viewed +with @code{xdvi}. The DVI uses a lot of PostScript specials, which do +not show up in the magnifying glass. The specials also mean that the +DVI file cannot be processed with @code{dvilj}. Use @code{dvips} for +printing. +@cindex dvips +@cindex dvilj +@cindex DVI driver +} One of the following commands should put the PDF on your +screen: @quotation @example - gv test.ps - ghostview test.ps - ggv test.ps - kghostview test.ps + gv test.pdf + ghostview test.pdf + ggv test.pdf + kghostview test.pdf + xpdf test.pdf + gpdf test.pdf + acroread test.pdf + gsview32 test.pdf @end example @end quotation -If the music on your screen looks good, you can print it by clicking -File/Print inside ghostview. - -The DVI file (@file{test.dvi}) contains the same sheet music in a -different format. DVI files are more easily processed by the computer, -so viewing them usually is quicker. You can run @code{xdvi test.dvi} or -@code{kdvi test.dvi} to view the DVI file. In Xdvi, the mouse buttons -activate magnifying glasses. Unfortunately, variable symbols (such as -beams and slurs) are not displayed in the magnifying glasses. - -If your DVI viewer does not have a "Print" button, you can print the -file by executing @code{lpr test.ps}. -@c volgende alinea schrappen? - -If your system does not support printing PostScript files, then you -can install GhostScript, a PostScript emulator. Refer to -GhostScript's website at @uref{http://www.ghostscript.com}. +@noindent +If the music on your screen looks good, you can print it by clicking +File/Print inside your viewing program. -@cindex GhostScript +@cindex Ghostscript @cindex @code{lpr} @cindex Printing output @cindex PostScript @cindex PDF -A final option is to use the popular PDF format. You can get a PDF -file by running @code{ly2dvi --pdf test.ly}. With @code{--pdf} -you will get DVI, PS and PDF files. Viewers for PS files also -accept PDF files, but there are also many other applications for -viewing PDF files. - -If you are familiar with @TeX{}, be warned: do not use other -DVI drivers like @code{dvilj}. The @TeX{} coming out of LilyPond -uses embedded PostScript code and will not render correctly if -you use anything other than @code{dvips}. - -@cindex dvips -@cindex dvilj -@cindex DVI driver -@unnumberedsubsec Windows users -Windows users can start the terminal by clicking on the LilyPond or -Cygwin icon. You can use any text editor (such as NotePad, Emacs or -Vim) to edit the LilyPond file. If you install the Cygwin's -@code{XFree86} X11 window system, @code{tetex-x11} and -@code{ghostscript-x11} packages too, you can view the @code{dvi} -output doing @code{xdvi test.dvi} as described above. If you have -installed a PostScript/PDF viewer, such as @code{GSView} from -@uref{http://www.cs.wisc.edu/~ghost}, viewing the PS file can be done -with: -@quotation -@example -@code{gsview32 test.ps} -@end example -@end quotation -You can also print from the command line by executing: -@quotation -@example -@code{gsview32 /s test.ps} -@end example -@end quotation +On Windows, the same procedure should work, the terminal is started by +clicking on the LilyPond or Cygwin icon. Any text editor (such as +NotePad, Emacs or Vim) may be used to edit the LilyPond file. +To view the PDF file, try the following: +@itemize +@item +If your system has a PDF viewer installed, open +@file{C:\Cygwin\home\@var{your-name}} in the explorer and double-click +@file{test.pdf}. +@item +If you prefer the keyboard, you can try to enter one of the commands +from the list shown before in the terminal. If none work, go to +@uref{http://www.cs.wisc.edu/~ghost/} to install the proper software. +@end itemize -@strong{SUMMARY} +The commands for formatting and printing music on all platforms are +detailed in @ref{Invoking LilyPond}. -To run LilyPond, input a text file, then run the command @code{ly2dvi} on -that file. The resulting files are either DVI or PostScript, and can -be viewed with @code{xdvi} (unix) and ghostview (unix and windows) -respectively. The following table summarizes the constructs that were -discussed in the previous two sections. +@node More about pitches +@section More about pitches -@multitable @columnfractions .3 .3 .4 +A @rglos{sharp} (@texisharp{}) pitch is made by adding @samp{is} to +the name, a @rglos{flat} (@texiflat{}) pitch by adding @samp{es}. As +you might expect, a @rglos{double sharp} or @rglos{double flat} is +made by adding @samp{isis} or @samp{eses}:@footnote{This syntax +derived from note naming conventions in Nordic and Germanic languages, +like German and Dutch.} -@item @b{Syntax} -@tab @b{Description} -@tab @b{Example} +@example +cis1 ees fisis aeses +@end example -@item @code{1 2 8 16} -@tab durations -@tab -@lilypond[fragment, relative 1] -\property Staff.TimeSignature = \turnOff -\property Staff.autoBeaming = ##f -\property Staff.Clef = \turnOff -c1 c2 c8 c16 +@lilypond[notime] +\set Score.timing = ##f +\transpose c c' { cis1 ees fisis aeses s16_" " } @end lilypond -@item @code{. ..} -@tab augmentation dots -@tab -@lilypond[fragment, relative 1] -\property Staff.TimeSignature = \turnOff -\property Staff.Clef = \turnOff -c4. c4.. -@end lilypond + +@cindex key signature, setting -@item @code{c d e f g a b } -@tab scale -@tab -@lilypond[fragment, relative 1] -\property Staff.TimeSignature = \turnOff -\property Staff.Clef = \turnOff -c d e f g a b -@end lilypond +The key signature is set with the command ``@code{\key}'', followed by +a pitch and @code{\major} or @code{\minor}: +@quotation +@example +\key d \major +g1 +\key c \minor +g +@end example -@item @code{\clef treble \clef bass } -@tab clefs -@tab @lilypond[fragment] -\property Staff.TimeSignature \set #'transparent = ##t -\clef treble -s4_" " -\clef bass -s4_" " +\set Staff.TimeSignature = \turnOff +\key d \major +g'1 +\key c \minor +g' @end lilypond +@end quotation -@item @code{\time 3/4 \time 4/4 } -@tab time signature -@tab -@lilypond[fragment] -\property Staff.Clef \set #'transparent = ##t -\time 3/4 -s4_" " -\time 4/4 -s16_" " -@end lilypond -@end multitable +Key signatures together with the pitch (including alterations) are +used together to determine when to print accidentals. This is a +feature that often causes confusion to newcomers, so let us explain it +in more detail: -@node More basics -@section More basics +LilyPond has a sharp distinction between musical content and +layout. The alteration (flat, natural or sharp) of a note is part of +the pitch, and is therefore musical content. Whether an accidental (a +flat, natural or sharp @emph{sign}) is a printed in front of the +corresponding note is a question of layout. Layout is something that +follows rules, so accidentals are printed automatically according to +those rules. The pitches in your music are works of art, so they will +not be added automatically, and you must enter what you want to hear. + +For example, in this example: +@lilypond[fragment] +\set Staff.TimeSignature = \turnOff +\key d \major +d' cis' fis' +@end lilypond -We continue with the introduction of the remaining musical constructs. -Normal rests are entered just like notes with the name ``@code{r}'': +@noindent +no note gets an explicit accidental, but still you enter -@quotation @example -r2 r4 r8 r16 +\key d \major +d cis fis @end example +The code @code{d} does not mean ``print a black dot just below the +staff.'' Rather, it means: ``a note with pitch D-natural.'' In the key +of A-flat, it gets an accidental: + @lilypond[fragment] -\property Score.timing = ##f -\property Staff.Clef = \turnOff -\property Staff.TimeSignature = \turnOff -r2 r4 r8 r16 -s16_" " +\set Staff.TimeSignature = \turnOff +\key as \major +d' @end lilypond -@end quotation -@separate - -@c Tim wants to move this quotes example just before the: quotes-don't-work -@c score, but we'd need to remove quotes from the other two (key and -@c tie) examples... - -@c better to have this just before the `octaves are bad' snipped -@c but we'd need to remove the ', from \key and tie -To raise a note by an octave, add a high quote @code{'} (apostrophe) to -the note name, to lower a note one octave, add a ``low quote'' @code{,} -(a comma). Middle C is @code{c'}: -@quotation +@noindent @example -c'4 c'' c''' \clef bass c c, +\key as \major +d @end example -@lilypond[fragment] -\property Score.timing = ##f -\property Staff.TimeSignature = \turnOff -c'4 c'' c''' \clef bass c c, -@end lilypond -@end quotation -@separate +Adding all alterations explicitly might require some more effort when +typing, but the advantage is that transposing is easier, and music can +be printed according to different conventions. See @ref{Accidentals} +for some examples how accidentals can be printed according to +different rules. -A tie is created by entering a tilde ``@code{~}'' between the notes to -be tied. A tie between two notes means that the second note must not be -played separately; it just makes the first note sound longer: +@cindex tie +A tie is created by adding a tilde ``@code{~}'' to the first note +being tied: @quotation -@lilypond[fragment,verbatim] -g'4 ~ g' a'2 ~ a'4 +@lilypond[fragment,verbatim,relative=2] +g4~ g a2~ a4 @end lilypond @end quotation @separate -The key signature is set with the command ``@code{\key}'': -@quotation -@example -\key d \major -g'1 -\key c \minor -g' -@end example - -@lilypond[fragment] -\property Staff.TimeSignature = \turnOff -\key d \major -g'1 -\key c \minor -g' -@end lilypond -@end quotation - - -@c bit on the long/complex/scary taste -@c cheating a bit: two lines makes for a friendlier look -This example shows notes, ties, octave marks, and rests in action. +This example shows the key signature, accidentals and ties in action: @quotation @example \score @{ \notes @{ \time 4/4 - \key d \minor + \key g \minor \clef violin - r4 r8 d''8 cis''4 e'' - d''8 a'4. ~ a' b'8 - cis''4 cis''8 cis'' bis'4 d''8 cis'' ~ - cis''2 r2 + r4 r8 a8 gis4 b + g8 d4.~ d e8 + fis4 fis8 fis8 eis4 a8 gis~ + gis2 r2 @} \paper @{ @} @} @@ -541,44 +494,103 @@ This example shows notes, ties, octave marks, and rests in action. @lilypond \score { - \notes { + \notes { \transpose c c' { \time 4/4 + \key g \minor \clef violin - \key d \minor - r4 r8 d''8 cis''4 e'' - d''8 a'4. ~ a' b'8 - cis''4 cis''8 cis'' bis'4 d''8 cis'' ~ - cis''2 r2 - } - \paper { linewidth = 50*\staffspace } + r4 r8 a8 gis4 b + g8 d4.~ d e8 + fis4 fis8 fis8 eis4 a8 gis~ + gis2 r2 + }} + \paper { linewidth = #(* 50 staffspace) } } @end lilypond @end quotation +@cindex accidentals + +There are some interesting points to note in this example. Bar lines +and beams are drawn automatically. Line breaks are calculated +automatically; it does not matter where the lines breaks are in the +source file. Finally, the order of time, key and clef changes is not +relevant: in the printout, these are ordered according to standard +notation conventions. + + +@cindex beams, by hand +Beams are drawn automatically, but if you do not like where they are +put, they can be entered by hand. Mark the first note to be beamed +with @code{[} and the last one with @code{]}: +@quotation +@lilypond[fragment,relative=1,verbatim] +a8[ ais] d[ es r d] +@end lilypond +@end quotation +@separate + +For more information on +@table @asis +@item Rests +see @ref{Rests}. + +@item Ties +see @ref{Ties}. + +@item Accidentals +see @ref{Accidentals} + +@item Key signature +see @ref{Key signature} + +@item Beams +see @ref{Beaming} +@end table + + +@node Octave entry +@section Octave entry + + +@c Tim wants to move this quotes example just before the: quotes-do not-work +@c score, but we'd need to remove quotes from the other two (key and +@c tie) examples... + +@c better to have this just before the `octaves are bad' snipped +@c but we'd need to remove the ', from \key and tie +To raise a note by an octave, add a high quote @code{'} (apostrophe) to +the note name, to lower a note one octave, add a ``low quote'' @code{,} +(a comma). Middle C is @code{c'}: + +@quotation +@example +c'4 c'' c''' \clef bass c c, +@end example + +@lilypond[fragment] +\set Score.timing = ##f +\set Staff.TimeSignature = \turnOff +c'4 c'' c''' \clef bass c c, +@end lilypond +@end quotation +@separate -@c accidentals... -There are some interesting points to note in this example. -Accidentals (sharps and flats) don't have to be marked explicitly: you -just enter the note name, and LilyPond determines whether or not to -print an accidental. Bar lines and beams are drawn automatically. -LilyPond calculates line breaks for you; it doesn't matter where you -make new lines in the source file. Finally, the order of time, key and -clef changes is not relevant: lilypond will use standard notation -conventions for ordering these items. - -The example also indicates that a piece of music written in a high -register needs lots of quotes. This makes the input less readable, -and is also a potential source of errors. - -The solution is to use ``relative octave'' mode. In practice, this is -the most convenient way to copy existing music. To use relative mode, -add @code{\relative} before the piece of music. You must also give a -note from which relative starts, in this case @code{c''}. If you don't -use octavation quotes (ie don't add ' or , after a note), relative mode -chooses the note that is closest to the previous one. Since most music -has small intervals, you can write quite a lot in relative mode without -using octavation quotes. -@c don't use commas or quotes in this sentence -For example: @code{c f} goes up; @code{c g} goes down: +An example of the use of quotes is in the following Mozart fragment: +@lilypond[raggedright,fragment,verbatim] + \key a \major + \time 6/8 + cis''8. d''16 cis''8 e''4 e''8 + b'8. cis''16 b'8 d''4 d''8 +@end lilypond + +This example shows that music in a high register needs lots of quotes. +This makes the input less readable, and it is a source of errors. The +solution is to use ``relative octave'' mode. In practice, this is the +most convenient way to copy existing music. To use relative mode, add +@code{\relative} before the piece of music. You must also give a note +from which relative starts, in this case @code{c''}. If you do not +use octavation quotes (i.e. do not add @code{'} or @code{,} after a +note), relative mode chooses the note that is closest to the previous +one. For example, @code{c f} goes up while @code{c g} goes down: @quotation @example @@ -588,8 +600,8 @@ For example: @code{c f} goes up; @code{c g} goes down: @end example @lilypond[fragment] -\property Score.timing = ##f -\property Staff.TimeSignature = \turnOff +\set Score.timing = ##f +\set Staff.TimeSignature = \turnOff \relative c'' { c f c g c } @@ -598,17 +610,25 @@ For example: @code{c f} goes up; @code{c g} goes down: @separate +Since most music has small intervals, pieces can be written almost +without octavation quotes in relative mode. The previous example is +entered as +@c +@lilypond[raggedright,fragment,verbatim] +\relative c'' { + \key a \major + \time 6/8 + cis8. d16 cis8 e4 e8 + b8. cis16 b8 d4 d8 +} +@end lilypond + + @c needed better, maybe even redundant explanation @c added another example below. @c grappig: Pa vond het heel logies, en slim toen-i eenmaal begreep. @c in eerste instantie drong het `relative' niet door zonder extra uitleg. -You can make larger intervals by adding octavation quotes. Note that -quotes or commas do not determine the absolute height of a note; -the height of a note is relative to the previous one. -@c don't use commas or quotes in this sentence -For example: @code{c f,} goes down; @code{f, f} are both the same; -@code{c' c} are the same; and @code{c g'} goes up: - +Larger intervals are made by adding octavation quotes. @quotation @example \relative c'' @{ @@ -617,8 +637,8 @@ For example: @code{c f,} goes down; @code{f, f} are both the same; @end example @lilypond[fragment] -\property Score.timing = ##f -\property Staff.TimeSignature = \turnOff +\set Score.timing = ##f +\set Staff.TimeSignature = \turnOff \relative c'' { c f, f c' c g' c, } @@ -626,8 +646,15 @@ For example: @code{c f,} goes down; @code{f, f} are both the same; @end quotation @separate +Quotes or commas do not determine the absolute height of a note; the +height of a note is relative to the previous one. +@c do not use commas or quotes in this sentence +For example: @code{c f,} goes down; @code{f, f} are both the same; +@code{c' c} are the same; and @code{c g'} goes up: + -Here's an example of the difference between relative mode and + +Here is an example of the difference between relative mode and ``normal'' (non-relative) mode: @quotation @@ -639,8 +666,8 @@ Here's an example of the difference between relative mode and @end example @lilypond[fragment] -\property Score.timing = ##f -\property Staff.TimeSignature = \turnOff +\set Score.timing = ##f +\set Staff.TimeSignature = \turnOff \relative a { \clef bass a d a e d c' d' @@ -656,2116 +683,1099 @@ Here's an example of the difference between relative mode and @end example @lilypond[fragment] -\property Score.timing = ##f -\property Staff.TimeSignature = \turnOff +\set Score.timing = ##f +\set Staff.TimeSignature = \turnOff \clef bass a d a e d c' d' @end lilypond @end quotation @separate -@strong{SUMMARY} -The following table summarizes the syntax learned so far in this section. +For more information on Relative octaves see @ref{Relative octaves} +and @ref{Octave check}. -@c Is it possible to avoid page breaks directly after the -@c table head? /Mats -@multitable @columnfractions .3 .3 .4 -@item @b{Syntax} -@tab @b{Description} -@tab @b{Example} -@item @code{r4 r8} -@tab rest -@tab -@lilypond[fragment, relative 1] -\property Staff.TimeSignature = \turnOff -\property Staff.Clef = \turnOff -r4 r8 -@end lilypond -@item @code{~} -@tab tie -@tab -@lilypond[fragment, relative 1] -\property Score.timing = ##f -\property Staff.TimeSignature = \turnOff -\property Staff.autoBeaming = ##f -\property Staff.Clef = \turnOff -d ~ d -@end lilypond +@node Combining music into compound expressions +@section Combining music into compound expressions +To print more than one staff, each piece of music that makes up a +staff is marked by adding @code{\context Staff} before it. These +@code{Staff}'s are then grouped inside @code{\simultaneous @{} and +@code{@}}, as is demonstrated here: -@item @code{\key es \major } -@tab key signature -@tab -@lilypond[fragment] -\property Staff.TimeSignature \set #'transparent = ##t -\clef treble -\key es \major -s4 +@quotation +@lilypond[fragment,verbatim] +\simultaneous { + \new Staff { \clef violin c'' } + \new Staff { \clef bass c } +} @end lilypond +@end quotation -@item @var{note}@code{'} -@tab raise octave -@tab -@lilypond[fragment, relative 1] -\property Score.timing = ##f -\property Staff.TimeSignature = \turnOff -\property Staff.autoBeaming = ##f -\property Staff.Clef = \turnOff -a a' -@end lilypond -@item @var{note}@code{,} -@tab lower octave -@tab -@lilypond[fragment, relative 1] -\property Score.timing = ##f -\property Staff.TimeSignature = \turnOff -\property Staff.autoBeaming = ##f -\property Staff.Clef = \turnOff -c c, -@end lilypond +In this example, @code{\simultaneous } indicates that both music +fragments happen at the same time, and must be printed stacked +vertically. The notation @code{<< .. >>} can also be used as a +shorthand for @code{\simultaneous @{ .. @}}. -@end multitable +The command @code{\new} introduces a ``notation context''. To +understand this concept, imagine that you are performing a piece of +music. When you are playing, you combine the symbols printed at a +certain point with contextual information. For example, without +knowing the current clef, and the accidentals in the last measure, it +would be impossible to determine the pitch of a note. In other words, +this information forms context that helps you decipher a +score. LilyPond produces notation from music, so in effect, it does +the inverse of reading scores. Therefore, it also needs to keep track +of contextual information. This information is maintained in +``notation contexts.'' There are several types of contexts, +e.g. @code{Staff}, @code{Voice} and @code{Score}, but also +@code{Lyrics} and @code{ChordNames}. Prepending @code{\new} to a chunk +of music indicates what kind of context to use for interpreting it, +and ensures that the argument is interpreted with a fresh instance of +the context indicated. -A slur is drawn across many notes, and indicates bound articulation -(legato). The starting note and ending note are marked with a -``@code{(}'' and a ``@code{)}'' respectively: -@quotation -@lilypond[fragment,relative 1, verbatim] -d4( )c16( cis d e c cis d )e( )d4 -@end lilypond -@end quotation @separate -If you need two slurs at the same time (one for articulation, one for -phrasing), you can also make a phrasing slur with @code{\(} and -@code{\)}. - -@c lousy example -@c ? --hwn -@c fragment of 1st hrn in Adams' The Chairman Dances, with creative -@c chromatic thing pasted in front. (admittedly the original doesn't -@c have a phrasing slur. The problem is that we don't want the slur -@c and the Phrasing slur to collide. We're trying to make a good -@c impression here. +We can now typeset a melody with two staves: @quotation -@lilypond[fragment,relative 1, verbatim] -a8(\( ais b ) c cis2 b'2 a4 cis, \) c +@lilypond[verbatim,raggedright] +\score { + \notes + << \new Staff { + \time 3/4 + \clef violin + \relative c'' { + e2( d4 c2 b4 a8[ a] + b[ b] g[ g] a2.) } + } + \new Staff { + \clef bass + c2 e4 g2. + f4 e d c2. + } + >> + \paper {} +} @end lilypond @end quotation -@separate -Beams are drawn automatically, but if you don't like the choices, you -can enter beams by hand. Surround the notes to be grouped with @code{[} -and @code{]}: +The example shows how small chunks of music, for example, the notes +@code{c2}, @code{e4}, etc. of the second staff, are combined to form a +larger chunk by enclosing it in braces. Again, a larger chunk is +formed by prefix @code{\new Staff} to it, and that chunk is combined +with @code{<< >>}. This mechanism is similar with mathematical +formulas: a big formula is created by composing small formulas. Such +formulas are called expressions, and their definition is recursive, so +you can make arbitrarily complex and large expressions. For example, + @quotation -@lilypond[fragment,relative 1, verbatim] -[a8 ais] [d es r d] -@end lilypond -@end quotation -@separate + 1 -To print more than one staff, each piece of music that makes up a staff -is marked by adding @code{\context Staff} before it. These -@code{Staff}'s are then grouped inside @code{<} and @code{>}, as is -demonstrated here: - -@quotation -@lilypond[fragment,verbatim] -< - \context Staff = staffA { \clef violin c'' } - \context Staff = staffB { \clef bass c } -> -@end lilypond + 1 + 2 + + (1 + 2) * 3 + + ((1 + 2) * 3) / (4 * 5) @end quotation +@cindex expression +@cindex music expression +This example shows a sequence of expressions, where each expression is +contained in the next one. The simplest expressions are numbers and +operators (like +, * and /). Parentheses are used to group +expressions. In LilyPond input, a similar mechanism is used. Here, +the simplest expressions are notes and rests. By enclosing +expressions in @code{<< >>} and @code{@{ @}}, more complex music is +formed. The @code{\new} command also forms new expressions; prepending +it to a music expression yields a new expression. + +Like mathematical expressions, music expressions can be nested +arbitrarily deep, e.g. +@lilypond[verbatim,relative=1] + { c <> + << { e f } { c <> } + >> + } +@end lilypond -In this example, @code{staffA} and @code{staffB} are names that are -given to the staves. It doesn't matter what names you give, as long -as each staff has a different name. -@separate +@cindex indent +When spreading expressions over multiple lines, it is customary to use +an indent that indicates the nesting level. Formatting music like this +eases reading, and helps you insert the right amount of closing +braces at the end of an expression. For example, +@example +\score @{ + \notes << + @{ + @dots{} + @} + @{ + @dots{} + @} + >> +@} +@end example -We can now typeset a melody with two staves: -@quotation -@lilypond[verbatim,singleline] -\score { - \notes - < \context Staff = staffA { - \time 3/4 - \clef violin - \relative c'' { e2 ( d4 c2 b4 [a8 a] [b b] [g g] )a2. } - } - \context Staff = staffB { - \clef bass - c2 e4 g2. - f4 e d c2. - } - > - \paper {} -} -@end lilypond -@end quotation +For more information on context see the Technical manual description +in @ref{Interpretation context}. -Notice that the time signature is specified in one melody staff only -(the top staff), but is printed on both. LilyPond knows that the time -signature should be the same for all staves. -@separate -Common accents can be added to a note using @code{-.}, @code{--}, @code{->}: -@quotation -@lilypond[verbatim,relative 1] -c-. c-- c-> -@end lilypond -@end quotation -@separate +@node Adding articulation marks to notes +@section Adding articulation marks to notes -Dynamic signs are made by adding the markings to the note: -@quotation -@lilypond[verbatim,relative 1] -c-\ff c-\mf -@end lilypond -@end quotation -@separate +@cindex articulation +@cindex accents +@cindex staccato -Crescendi and decrescendi are started with the commands @code{\<} and -@code{\>}. The command @code{\!} finishes a crescendo on the following -note. +Common accents can be added to a note using a dash (`@code{-}') and a +single character: @quotation -@lilypond[verbatim,relative 1] -c2\< \!c2-\ff \>c2 \!c2 +@lilypond[verbatim,relative=1] +c-. c-- c-> c-^ c-+ c-_ @end lilypond @end quotation @separate -Chords can be made by surrounding notes with @code{<} and @code{>}: -@quotation -@lilypond[relative 0, fragment,verbatim] -r4 +@cindex fingering +Similarly, fingering indications can be added to a note using a dash +(`@code{-}') and the digit to be printed: +@c +@lilypond[verbatim,relative=1] + c-3 e-5 b-2 a-1 @end lilypond -@end quotation -@separate -@ignore -@c te diepzinnig? -@c hmm, te losjes, iig -In general, @code{ < @var{stuff} > } is used when @var{stuff} all -happens at the same time, like in chords, or (like in the two-staff -example above) in a bunch of stacked staves. -@end ignore -You can combine beams and ties with chords. Beam and tie markings -must be placed outside the chord markers: +Dynamic signs are made by adding the markings to the note: @quotation -@lilypond[relative 0, fragment,verbatim] -r4 [ ] ~ +@lilypond[verbatim,relative=1] +c\ff c\mf @end lilypond @end quotation +@separate -When you want to combine chords with slurs and dynamics, technical -detail crops up: you have type these commands next to the notes, which -means that they have to be inside the @code{< >}. Don't get confused -by the chord @code{< >} and the dynamic @code{\< \>}! - +@cindex dynamics +@cindex decrescendo +@cindex crescendo +Crescendi and decrescendi are started with the commands @code{\<} and +@code{\>}. The command @code{\!} finishes a crescendo on the note it +is attached to: @quotation -@example -r4 ( > < ) \! c8 f a> -@end example -@lilypond[relative 0, fragment] -\slurUp -r4 ( > < ) \! c8 f a> +@lilypond[verbatim,relative=1] +c2\< c2\!\ff\> c2 c2\! @end lilypond @end quotation @separate -@c this example is a bit too strongly worded -- there's nothing wrong -@c with starting a piece with a chord; you just have to be careful when -@c you do so. I've rephrased this example below. -@c There is one golden rule that you should keep in mind when writing -@c LilyPond input: -@c @quotation -@c @strong{DO NOT START A PIECE WITH A CHORD} -@c @end quotation -@c Of course, it is a allowed, but the result might not be what you expect: -@c rephrased "don't start with a chord" -There is one caution when using chords: if you use a chord at the very -beginning of the piece, LilyPond might not understand what you want: -@quotation -@lilypond[verbatim,singleline] -\score { \notes } -@end lilypond -@end quotation -@separate +@cindex slur -If you have a piece that begins with a chord, you must explicitly -state that the notes of the chord are to be put on the same staff, in -the same voice. This is done by specifying @code{\context Staff} or -@code{\context Voice} for the notes: +A slur is drawn across many notes, and indicates bound articulation +(legato). The starting note and ending note are marked with a +``@code{(}'' and a ``@code{)}'' respectively: @quotation -@lilypond[verbatim,singleline] -\score { \notes \context Voice } +@lilypond[fragment,relative=1,verbatim] +d4( c16)( cis d e c cis d e)( d4) @end lilypond @end quotation @separate +@cindex slurs versus ties +A slur looks like a tie, but it has a different meaning. A tie simply +makes the first note sound longer, and can only be used on pairs of +notes with the same pitch. Slurs indicate the articulations of notes, +and can be used on larger groups of notes. Slurs and ties are also +nested in practice: +@c +@lilypond[fragment,relative=1] +c2~( c8 fis fis4 ~ fis2 g2) +@end lilypond +@cindex phrasing slurs +If you need two slurs at the same time (one for articulation, one for +phrasing), you can also make a phrasing slur with @code{\(} and +@code{\)}. -@strong{SUMMARY} - -@multitable @columnfractions .3 .3 .4 - -@item @b{Syntax} -@tab @b{Description} -@tab @b{Example} - - -@item @code{( )} -@tab slur -@tab -@lilypond[fragment, relative 1] -\property Score.timing = ##f -\property Staff.TimeSignature = \turnOff -\property Staff.autoBeaming = ##f -\property Staff.Clef = \turnOff -c( d )e -@end lilypond - - -@item @code{\( \)} -@tab phrasing slur -@tab -@lilypond[fragment, relative 1] -\property Score.timing = ##f -\property Staff.TimeSignature = \turnOff -\property Staff.autoBeaming = ##f -\property Staff.Clef = \turnOff -c\( c() d \)e -@end lilypond - - -@item @code{[ ]} -@tab beam -@tab -@lilypond[fragment, relative 1] -\property Score.timing = ##f -\property Staff.TimeSignature = \turnOff -\property Staff.autoBeaming = ##f -\property Staff.Clef = \turnOff -[a8 b] -@end lilypond - - -@item @code{< \context Staff ... >} -@tab more staffs -@tab -@lilypond[fragment] -< \context Staff = SA { c'1 } - \context Staff = SB { c'1 } > -@end lilypond - - -@item @code{-> -.} -@tab articulations -@tab -@lilypond[fragment, relative 1] -\property Staff.TimeSignature = \turnOff -\property Staff.Clef = \turnOff -c-> c-. -@end lilypond - - -@item @code{-\mf -\sfz} -@tab dynamics -@tab -@lilypond[fragment, relative 1] -\property Staff.TimeSignature = \turnOff -\property Staff.Clef = \turnOff -c-\mf c-\sfz -@end lilypond - - -@item @code{\< \!} -@tab crescendo -@tab -@lilypond[fragment, relative 1] -\property Score.timing = ##f -\property Staff.TimeSignature = \turnOff -\property Staff.autoBeaming = ##f -\property Staff.Clef = \turnOff -a\< a \!a -@end lilypond - -@item @code{\> \!} -@tab decrescendo -@tab -@lilypond[fragment, relative 1] -\property Score.timing = ##f -\property Staff.TimeSignature = \turnOff -\property Staff.autoBeaming = ##f -\property Staff.Clef = \turnOff -a\> a \!a -@end lilypond - - -@item @code{< >} -@tab chord -@tab -@lilypond[fragment, relative 1] -\context Voice -@end lilypond - -@end multitable - -Now you know the basic ingredients of a music file, so this is the right -moment to try your at hand at doing it yourself: try typing some -simple examples, and experiment a little. - -When you're comfortable with the basics, you might want to read -the rest of this chapter. It continues in tutorial-style, but it -is much more in-depth, dealing with more advanced topics such as -lyrics, chords, orchestral scores and parts, fine tuning of output, -polyphonic music, and integrating text and music. - - - - - -@node Printing lyrics -@section Printing lyrics -@cindex lyrics - -In this section we shall explain how to typeset the following -fragment of The Free Software Song: - -@lilypond[singleline] -\score { \notes { \addlyrics - \notes \relative c' { - \time 7/4 - d'2 c4 b16 ( a g a b a b ) c a2 - b2 c4 b8 ( a16 g ) a4 g2 } - \context Lyrics \lyrics { - Join us now __ and - share the soft -- ware; } -} -\paper { linewidth = -1. } -} -@end lilypond - - -@cindex lyric mode -@cindex @code{\lyrics} - - -To print lyrics, you must enter them and then instruct lilypond to -print the lyrics. -You can enter lyrics in a special input mode of LilyPond. This mode is -called Lyrics mode, and it is introduced by the keyword @code{\lyrics}. -The purpose of this mode is that you can enter lyrics as plain text, -punctuation, and accents without any hassle. - -Syllables are entered like notes, but with pitches replaced by text. For -example, @code{Twin- kle twin- kle} enters four syllables. Note that -the hyphen has no special meaning for lyrics, and does not introduce -special symbols. - -Spaces can be introduced into a lyric either by using quotes: -@code{"He could" not} or by using an underscore without quotes: -@code{He_could not}. All unquoted underscores are converted to -spaces. - -These are the lyrics for the free software song: - -@example - \lyrics @{ - Join us now __ and - share the soft -- ware; @} -@end example - -As you can see, extender lines are entered as @code{__}. This will -create an extender, which is a line that extends over the entire -duration of the lyric. This line will run all the way to the start -of the next lyric, so you may want to shorten it by using a blank -lyric (using @code{_}). - - -You can use ordinary hyphens at the end of a syllable, i.e. -@example - soft- ware -@end example -but then the hyphen will be attached to the end of the first syllable. - -If you want them centered between syllables you can use the special -`@code{-}@code{-}' lyric as a separate word between syllables. The -hyphen will have variable length depending on the space between -the syllables and it will be centered between the syllables. - -Normally the notes that you enter are transformed into note heads. -Note heads alone make no sense, so they need surrounding information: a -key signature, a clef, staff lines, etc. They need @emph{context}. In -LilyPond, these symbols are created by objects called `interpretation -contexts'. Interpretation contexts exist for generating notation -(`notation context') and for generating sound (`performance -context'). These objects only exist while LilyPond is executing. - -When LilyPond interprets music, it will create a Staff context. -We don't want that default here, because we want lyric. The -command -@example - \context Lyrics -@end example -explicitly creates an interpretation context of -@code{Lyrics} type to interpret the song text that we entered. - -The melody of the song doesn't offer anything new: -@example - \notes \relative c' @{ - \time 7/4 - d'2 c4 b16 ( a g a b a b ) c a2 - b2 c4 b8 ( a16 g ) a4 g2 @} -@end example - -Both can be combined with the @code{\addlyrics}: -@example -\addlyrics - \notes \relative c' @dots{} - \context Lyrics \lyrics @dots{} -@end example - -The lyrics are also music expressions, similar to notes. Each syllable -of the lyrics is put under a note of the melody. -The complete file is listed here: - -@example -\score @{ \notes @{ \addlyrics - \notes \relative c' @{ - \time 7/4 - d'2 c4 b16 ( a g a b a b ) c a2 - b2 c4 b8 ( a16 g ) a4 g2 @} - \context Lyrics \lyrics @{ - Join us now __ and - share the soft -- ware; @} -@} -\paper @{ linewidth = -1. @} -@} -@end example - - - -@node A melody with chords -@section A melody with chords - -In this section we show how to typeset a melody with chord -accompaniment. This file is included as @file{input/tutorial/flowing.ly}. - -@example -\include "paper16.ly" -melody = \notes \relative c' @{ - \partial 8 - \key c \minor - g8 | - c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g | - c4 c8 d [es () d] c4 | d4 es8 d c4. - \bar "|." -@} - -accompaniment =\chords @{ - r8 - c2:3- f:3-.7 d:min es4 c8:min r8 - c2:min f:min7 g:7^3.5 c:min @} - -\score @{ - \simultaneous @{ - %\accompaniment - \context ChordNames \accompaniment - \context Staff = mel @{ - \melody - @} - - @} - \midi @{ \tempo 4=72 @} - \paper @{ linewidth = 10.0\cm @} -@} -@end example - - -The result would look this. - -@lilypond[center] -\include "paper16.ly" -melody = \notes \relative c' { - \partial 8 - \key c \minor - g8 | - c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g | - c4 c8 d [es () d] c4 | d4 es8 d c4. - \bar "|." -} - -accompaniment =\chords { - r8 - c2:3- f:3-.7 d:min es4 c8:min r8 - c2:min f:min7 g:7^3.5 c:min } - -\score { - \simultaneous { - %\accompaniment - \context ChordNames \accompaniment - - \context Staff = mel { - \property Staff.autoBeaming = ##f - \melody - } - } - \midi { \tempo 4=72 } - \paper { linewidth = 10.0\cm } -} -@end lilypond - -We will dissect this file line by line. - -@separate -@example - - \include "paper16.ly" - -@end example -Smaller size (suitable for inclusion in a book). -@separate -@example - - melody = \notes \relative c' @{ - -@end example -The structure of the file will be the same as the previous one: a -@code{\score} block with music in it. To keep things readable, we will -give different names to the different parts of music, and use the names -to construct the music within the score block. - -@separate -@example - \partial 8 -@end example - -@cindex @code{\partial} -@cindex anacrusis -The piece starts with an anacrusis (or ``pickup'') of one eighth. -@separate - -@separate -@example - - c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g | - c4 c8 d [es () d] c4 | d4 es8 d c4. - \bar "|." - -@end example - -@cindex manual beaming -@cindex automatic beaming, turning off -We use explicit beaming. Since this is a song, we turn automatic -beams off and use explicit beaming where needed. -@separate -@example - - @} - -@end example -This ends the definition of @code{melody}. - -@separate -@example - - text = \lyrics @{ - -@end example -@cindex lyrics -@cindex identifier assignment -@cindex syllables, entering -This defines the lyrics, similar to what we have seen before. - -@separate -@example - - accompaniment =\chords @{ - -@end example -@cindex chords -@cindex mode, chords -We'll put chords over the music. To enter them, we use a special mode -analogous to @code{\lyrics} and @code{\notes} mode, where you can give -the names of the chords you want instead of listing the notes -comprising the chord. -@separate -@example - - r8 - -@end example -There is no accompaniment during the anacrusis. -@separate -@example - - c2:3- - -@end example - -@cindex tonic -@cindex chord modifier -@cindex modifier, chord -This is a c minor chord, lasting for a half note. Chords are entered using -the tonic. Notes can be changed to create different chords. In this case, -a lowered third is used (making a C major chord into a C minor chord). -The code for this is @code{3-}. - -@separate -@example -f:3-.7 -@end example -Similarly, @code{7} modifies (adds) a seventh, which is small by -default to create the @code{f a c es} chord. Multiple modifiers must be -separated by dots. -@separate -@example - - d:min es4 c8:min r8 - -@end example -Some modifiers have predefined names, e.g. @code{min} is the same as -@code{3-}, so @code{d-min} is a minor @code{d} chord. -@separate -@example - - c2:min f:min7 g:7^3.5 c:min @} - -@end example -@cindex named modifier - -A named modifier @code{min} and a normal modifier @code{7} do not have -to be separated by a dot. Tones from a chord are removed with chord -subtractions. Subtractions are started with a caret, and they are -also separated by dots. In this example, @code{g:7^3.5} produces a -minor seventh (a G7 chord without the third or the fifth). The -brace ends the sequential music. -@separate -@example - - \score @{ - \simultaneous @{ - -@end example -We assemble the music in the @code{\score} block. Melody, lyrics and -accompaniment have to sound at the same time, so they should be -@code{\simultaneous}. -@cindex @code{\simultaneous} -@separate -@example - - %\accompaniment - -@end example -Chord mode generates notes grouped in @code{\simultaneous} music. If -you remove the comment sign, you can see the chords in normal -notation: they will be printed as note heads on a separate -staff. To print them as chords names, they have to be interpreted as -being chords, not notes. This is done with the following command: -@separate -@example - - \context ChordNames \accompaniment - -@end example -@cindex context -@cindex interpretation context -@cindex notation context - - -Normally the notes that you enter are transformed into note heads. -Note heads alone make no sense, so they need surrounding information: a key -signature, a clef, staff lines, etc. They need @emph{context}. In -LilyPond, these symbols are created by objects called `interpretation -contexts'. Interpretation contexts exist for generating notation -(`notation context') and for generating sound (`performance -context'). These objects only exist while LilyPond is executing. - -When LilyPond interprets music, it will create a Staff context. If -the @code{%} sign in the previous line were removed, you could see -that mechanism in action. - -We don't want that default here, because we want chord names. The -command above explicitly creates an interpretation context of -@code{ChordNames} type to interpret the music @code{\accompaniment}. - -@separate -@example - - \context Staff = mel @{ - -@end example - -We place the melody on a staff called @code{mel}. We give it a name to -differentiate it from the one that would contain note heads for the -chords, if you would remove the comment before the ``note heads'' -version of the accompaniment. By giving this staff a name, it is -forced to be different. -@separate -@example - - \property Staff.autoBeaming = ##f - -@end example -@cindex \property -@cindex context variables -@cindex setting context variables -An interpretation context has variables, called properties, that tune -its behavior. One of the variables is @code{autoBeaming}. Setting -this @code{Staff}'s property to @code{##f}, which is the boolean value -@var{false}, turns the automatic beaming mechanism off for the current -staff. - - -@separate -@example - - \melody - @} - -@end example -Finally, we put the melody on the current staff. Note that the -@code{\property} directives and @code{\melody} are grouped in sequential -music, so the property settings are done before the melody is -processed. - -@separate -@example - - \midi @{ \tempo 4=72@} - -@end example -MIDI (Musical Instrument Digital Interface) is a standard for -connecting and recording digital instruments. So a MIDI file is like a -tape recording of an instrument. The @code{\midi} block makes the -music go to a MIDI file, so you can listen to the music you entered. It -is great for checking the music. Whenever you hear something weird, you -probably hear a typing error. - -Syntactically, @code{\midi} is similar to @code{\paper @{ @}}, since it -also specifies an output method. You can specify the tempo using the -@code{\tempo} command, in this case the tempo of quarter notes is set to -72 beats per minute. -@separate -@example - - \paper @{ linewidth = 10.0\cm @} - -@end example -We also want notation output. The linewidth is short so that the piece -will be set in two lines. - -@node More stanzas -@section More stanzas - - -@cindex phrasing - -If you have multiple stanzas printed underneath each other, the vertical -groups of syllables should be aligned around punctuation. LilyPond can -do this if you tell it which lyric lines belong to which melody. -We show how you can do this by showing how you could print a frivolous -fragment of a fictional Sesame Street duet. - -@lilypond[singleline,verbatim] -\score { -\addlyrics - \notes \relative c'' \context Voice = duet { \time 3/4 - g2 e4 a2 f4 g2. } - \lyrics \context Lyrics < - \context LyricsVoice = "duet-1" { - \property LyricsVoice . stanza = "Bert" - Hi, my name is bert. } - \context LyricsVoice = "duet-2" { - \property LyricsVoice . stanza = "Ernie" - Ooooo, ch\'e -- ri, je t'aime. } - > -} -@end lilypond - -To this end, give the Voice context an identity, and set the -LyricsVoice to a name starting with that identity followed by a dash. -In the following example, the Voice identity is @code{duet}, -@example -\context Voice = duet @{ - \time 3/4 - g2 e4 a2 f4 g2. @} -@end example -and the -identities of the LyricsVoices are @code{duet-1} and @code{duet-2}. -@example - \context LyricsVoice = "duet-1" @{ - Hi, my name is bert. @} - \context LyricsVoice = "duet-2" @{ - Ooooo, ch\'e -- ri, je t'aime. @} -@end example - -We add the names of the singers. This can be done by setting -@code{LyricsVoice.Stanza} (for the first system) and -@code{LyricsVoice.stz} for the following systems. Note that you must -surround dots with spaces in @code{\lyrics} mode. - -@example - \property LyricsVoice . stanza = "Bert" - @dots{} - \property LyricsVoice . stanza = "Ernie" -@end example - -The convention for naming @code{LyricsVoice} and @code{Voice} must -also be used to get melismata on rests correct. - - -@c I think we need to change the name of this section, but that -@c would probably involve a lot of changes in other places too. -@node More movements -@section More movements - -The program @code{lilypond} only produces sheet music and does not -create titles, subtitles, or print the composer's name. To do that, -you need to use @code{ly2dvi}, which comes with LilyPond. @code{ly2dvi} -creates the title, then calls @code{lilypond} to format the sheet music. -In this section, we show you how to create titles like this: - -@c Old version of the above paragraph. -@c LilyPond only produces sheet music; it doesn't concern itself with -@c producing titles. Titles are produced using a simply wrapper program -@c This is the jobs of a simple wrapper -@c program called ly2dvi. @code{ly2dvi} calls LilyPond to do the -@c sheet music formatting. Then it produces titles, and ties together all -@c inputs into a single @file{dvi} file. In this section, we show some of -@c the options for titling. We will show how you can produce a file -@c that looks like this: - -@center @strong{Two miniatures} -@flushright -Opus 1. -@end flushright -@flushleft -@var{Up} -@end flushleft -@lilypond - \score { - \notes { c'4 d'4 } - \paper { linewidth = -1.0 } - } -@end lilypond -@flushright -Opus 2. -@end flushright -@flushleft -@var{Down} -@end flushleft -@lilypond - \score { - \notes { d'4 c'4 } - \paper { linewidth = -1.0 } - } -@end lilypond - -For example, consider the following file (@file{miniatures.ly}) - -@example -\version "1.5.72" -\header @{ - title = "Two miniatures" - composer = "F. Bar Baz" - tagline = "small is beautiful" @} - -\paper @{ linewidth = -1.0 @} - -%@{ - -Mental note: discuss Schenkerian analysis of these key pieces. - -%@} - -\score @{ - \notes @{ c'4 d'4 @} - \header @{ - opus = "Opus 1." - piece = "Up" @} -@} -\score @{ - \notes @{ d'4 c'4 @} - \header @{ - opus = "Opus 2." - piece = "Down" @} -@} -@end example - - -The information for the global titling is in a so-called header block. -The information in this block is not used by LilyPond, but it is -passed into @code{ly2dvi}, which uses this information to print titles -above the music. -@cindex assignments -@cindex identifier assignment -the @code{\header} block contains assignments. In each assignment, a -variable is set to a value. The header block for this file looks like -this -@cindex @code{\header} -@example - \header @{ - title = "Two miniatures" - composer = "F. Bar Baz" - tagline = "small is beautiful" - @} -@end example - -When you process a file with ly2dvi, a signature line is printed at -the bottom of the last page. This signature is produced from the -@code{tagline} field of @code{\header}. The default "Lily was here, -@var{version number}" is convenient for programmers: archiving the -layouts of different versions allows programmers to compare the -versions using old print-outs. - -@cindex Lily was here -@cindex signature line -@cindex tag line - -Many people find the default tagline (``Lily was here'') too droll. -If that is the case, you can change @code{tagline} to somethign else, -as shown above. - -@separate -@example - \paper @{ - linewidth = -1.0 @} -@end example - -A paper block at top level (i.e. not in a @code{\score} block) sets the -default page layout. The following @code{\score} blocks don't have -@code{\paper} sections, so the settings of this block are used. - -The variable @code{linewidth} normally sets the length of the systems -on the page. However, a negative value has a special meaning. If -@code{linewidth} is less than 0, no line breaks are inserted into the -score, and the spacing is set to natural length: a short phrase takes -up little space, a longer phrase takes more space, all on the same line. - -@example -%@{ - -Mental note: discuss Schenkerian analysis of these key pieces. - -%@} -@end example - -Mental notes to yourself can be put into comments. There are two types -of comments. Line comments are introduced by @code{%}, and block -comments are delimited by @code{%@{} and @code{%@}}. - -@separate -@example - \score @{ - \notes @{ c'4 d'4 @} -@end example - -In previous examples, most notes were specified in relative octaves -(i.e. each note was put in the octave that is closest to its -predecessor). Besides relative, there is also absolute octave -specification, which you get when you don't include @code{\relative} in -your input file. In this input mode, the middle C is denoted by -@code{c'}. Going down, you get @code{c} @code{c,} @code{c,,} etc. -Going up, you get @code{c''} @code{c'''} etc. - -When you're copying music from existing sheet music, relative octaves -are probably the easiest to use: you have to do less typing, and errors are -easily spotted. However, if you write LilyPond input directly, either by -hand (i.e. composing) or by computer, absolute octaves may be easier to use. - - -@separate -@example - \header @{ -@end example - -The @code{\header} is normally at the top of the file, where it sets -values for the rest of the file. If you want to typeset different pieces -from one file (for example, if there are multiple movements, or if -you're making an exercise book), you can put different @code{\score} -blocks into the input file. @code{ly2dvi} will assemble all LilyPond -output files into a big document. The contents of @code{\header} blocks -specified within each score is used for the title of that movement. -@separate -@example - opus = "Opus 1." - piece = "Up" @} -@end example -For example, the Opus number is put at the right, and the "piece" string -will be at the left. - - - -@example -\version "1.5.72" -\header @{ - title = "Two miniatures" - composer = "F. Bar Baz" - tagline = "small is beautiful" @} - -\paper @{ linewidth = -1.0 @} - -\score @{ - \notes @{ c'4 d'4 @} - \header @{ - opus = "Opus 1." - piece = "Up" @} -@} -\score @{ - \notes @{ d'4 c'4 @} - \header @{ - opus = "Opus 2." - piece = "Down" @} -@} -@end example - - -@separate -@example -\version "1.5.72" -@end example -Lilypond and its language are still under development, and -occasionally details of the syntax are changed. The @code{version} -fragment indicates which version of lilypond the input file was written -for. When you compile this file, the version number will be checked -and you will get a warning when the file is too old. This version -number is also used by the @code{convert-ly} program (See -@ref{Invoking convert-ly}), which can used to update the file to the -latest lily version. - - -@node A piano excerpt -@section A piano excerpt - -Our eighth subject is a piece of piano music. The fragment in the -input file is a piano reduction of the G major Sinfonia by Giovanni -Battista Sammartini, composed around 1740. It's in the source -package under the name @file{input/tutorial/sammartini.ly}. - -@lilypondfile[smallverbatim]{sammartini.ly} - -As you can see, this example features multiple voices on one staff. To -make room for those voices, their notes should be stemmed in opposite -directions. - -LilyPond includes the identifiers @code{\stemUp}, @code{\stemDown} along -with some other commonly used formatting instructions, but to explain how -it works, we wrote our own here. Of course, you should use predefined -identifiers like these if possible: you will be less affected by changes -between different versions of LilyPond. - -@separate -@example -viola = \notes \relative c' \context Voice = viola @{ -@end example -In this example you can see multiple parts on a staff. Each part is -associated with one notation context. This notation context handles -stems and dynamics (among other things). The type name of this context -is @code{Voice}. For each part we have to make sure that there is -precisely one @code{Voice} context, so we give it a unique name -(`@code{viola}'). - -@separate -@example - -@end example -The delimiters @code{<} and @code{>} are shorthands for -@code{\simultaneous @{} and @code{@}}. The expression enclosed in -@code{<} and @code{>} is a chord. - -@cindex arpeggio - -@code{\arpeggio} typesets an arpeggio sign (a wavy vertical line) before -the chord. - -@separate -@example - \voiceTwo -@end example - -We want the viola to have stems down, and have all the other -characteristics of a second voice. This is enforced using the -@code{\voiceTwo} command: it inserts instructions that makes stem, -ties, slurs, etc. go down. - - - -@separate -@example - g'8. b,16 -@end example -Relative octaves work a little differently with chords. The starting -point for the note following a chord is the first note of the chord. So -the @code{g} gets an octave up quote: it is a fifth above the starting -note of the previous chord (the central C). - -@separate -@example -s1 s2. r4 -@end example -@code{s} is a spacer rest. It does not print anything, but it does have -the duration of a rest. It is useful for filling up voices that -temporarily don't play. In this case, the viola doesn't come until one -and a half measure later. - -@separate -@example -oboes = \notes \relative c'' \context Voice = oboe @{ -@end example -Now comes a part for two oboes. They play homophonically, so we -print the notes as one voice that makes chords. Again, we insure that -these notes are indeed processed by precisely one context with -@code{\context}. -@separate -@example -\voiceOne s4 g8. b,16 c8 r -@end example - -The oboes should have stems up to keep them from interfering with -the staff-jumping bass figure. To do that, we use @code{\voiceOne}. - -@separate -@example -\grace < d4 )f> -@end example -@cindex @code{\grace} -@cindex ornaments -@cindex grace notes -@code{\grace} introduces grace notes. It takes one argument, in this -case a chord. A slur is introduced starting from the @code{\grace} -ending on the following chord. - -@separate -@example -\times 2/3 -@end example -@cindex tuplet -@cindex triplets -Tuplets are made with the @code{\times} keyword. It takes two -arguments: a fraction and a piece of music. The duration of the piece -of music is multiplied by the fraction. Triplets make notes occupy 2/3 -of their notated duration, so in this case the fraction is 2/3. -@separate -@example -@{ @} -@end example -The piece of music to be `tripletted' is sequential music containing -three chords. - -@separate -@example -< -@end example -At this point, the homophonic music splits into two rhythmically -different parts. We can't use a sequence of chords to enter this, so -we make a "chord of sequences" to do it. We start with the upper -voice, which continues with upward stems: -@separate -@example - @{ \times 2/3 @{ a8 g c @} c2 @} -@end example - -@separate -@example -\\ -@end example -The easiest way to enter multiple voices is demonstrated -here. Separate the components of the voice (single notes or entire -sequences) with @code{\\} in a simultaneous music expression. The -a@code{\\} separators split first voice, second voice, third voice, and -so on. - -As far as relative mode is concerned, the previous note is the -@code{c'''2} of the upper voice, so we have to go an octave down for -the @code{f}. -@separate -@example - - f,8 e e2 -@} > -@end example -This ends the two-part section. -@separate -@example -\stemBoth -\grace <)b8. d8.-\trill> | -@end example -@cindex trill -@cindex stemBoth - -@code{\stemBoth} ends the forced stem directions. From here, stems are -positioned as if it were single part music. - -The bass has a little hoom-pah melody to demonstrate parts switching -between staves. Since it is repetitive, we use repeats: -@separate -@example -hoomPah = \repeat unfold 8 -@end example -@cindex unfolded @code{\repeat} -The unfolded repeat prints the notes in its argument as if they were -written out in full eight times. -@separate -@example -\notes \transpose c' @{ -@end example -@cindex transposing -@cindex relative mode and transposing - -Transposing can be done with @code{\transpose}, which takes two arguments. -The first specifies what central C should be transposed to. The second -is the to-be-transposed music. As you can see, in this case, the -transposition has no effect, as central C stays at central C. - -The purpose of this no-op is to protect it from being interpreted as -relative notes. Relative mode can not be used together with -transposition, so @code{\relative} will leave the contents of -@code{\hoomPah} alone. We can use it without having to worry about -getting the motive in a wrong octave. -@separate -@cindex staff switch, manual -@cindex cross staff voice, manual -@cindex @code{\translator} - -@example - \translator Staff = down - \stemUp - c8 - \translator Staff = up - \stemDown - c'8 @} -@end example -Voices can switch between staves. Here you see two staff switching -commands. The first one moves to the lower staff, the second one to -the lower one. If you set the stem directions explicitly -(using the identifiers @code{\stemUp} and @code{\stemDown}, the notes -can be beamed together (despite jumping between staffs). - -@separate -@example -bassvoices = \notes \relative c' @{ -c4 g8. b,16 -\autochange Staff \hoomPah \context Voice -@end example - -@separate -@example - \translator Staff = down -@end example -@cindex staff switch -@cindex cross staff voice -We want the remaining part of this melody on the lower staff, so we do a -manual staff switch here. - - -@separate -@example -\context Voice = reallyLow @{\stemDown g2 ~ | g4 c8 @} > -@end example -@cindex tie -@cindex @code{~} -After skipping some lines, we see @code{~}. This mark makes ties. Note -that ties and slurs are different things. A tie can only connect two -note heads of the same pitch, whereas a slur can connect many notes -with one curve. - -@separate -@example -\context PianoStaff -@end example - A special context is needed to get cross staff beaming right. This -context is called @code{PianoStaff}. -@separate -@example -\context Staff = bottom < \time 2/2 \clef bass -@end example -The bottom staff must have a different clef. -@separate -@example -indent = 0.0 -@end example -To make some more room on the line, the first (in this case the only) -line is not indented. The line still looks very cramped, but that is due -to the page layout of this document. - - -@ignore -[TODO: - -* font-size, multi-stanza. - -* Simple part combining in a Hymn -@end ignore - - -@node Fine tuning a piece -@section Fine tuning a piece - -In this section, we show some ways to fine tune the final output of a -piece. We do so using a single measure of a moderately complex piano -piece: a Brahms intermezzo (opus 119, no. 1). Both fragments (the -tuned and the untuned are in the @file{input/tutorial/}). +@quotation +@lilypond[fragment,relative=1,verbatim] +a8(\( ais b c) cis2 b'2 a4 cis, c\) +@end lilypond +@end quotation -The code for the untuned example shows us some new things. -@lilypondfile[verbatim]{brahms-original.ly} +For more information on +@table @asis +@item fingering + see @ref{Fingering instructions} +@item articulations + see @ref{Articulations} +@item slurs + see @ref{Slurs} +@item phrasing slurs + see @ref{Phrasing slurs} +@item dynamics + see @ref{Dynamics} +@item fingering +@end table + +@node Combining notes into chords +@section Combining notes into chords +@cindex chords +Chords can be made by +surrounding pitches with @code{<} and @code{>}: +@quotation +@lilypond[relative,fragment,verbatim] +r4 4 8 +@end lilypond +@end quotation +@separate -@cindex dynamics -@cindex loudness -@cindex forte -@cindex crescendo -@cindex @code{\<} -@cindex @code{\!} -The crescendo is ended at the half note by the escaped exclamation -mark @code{\!}. +You can combine beams and ties with chords. Beam and tie markings +must be placed outside the chord markers: +@quotation +@lilypond[relative,fragment,verbatim] +r4 8[ ]~ +@end lilypond +@end quotation -Hairpin dynamics can be indicated using @code{\>} to start a -decrescendo, and @code{\!} to end one. The crescendo is started using -@code{\<} and also ended using @code{\!}. Absolute dynamics can be -entered using @code{\p}, @code{\mf}, etc. All these commands apply to -the complete chord where they are entered, but for syntactical -reasons, they must be attached to one of the notes of the chord. +@quotation +@example +r4 8\>( 8\!) +@end example +@lilypond[relative,fragment] +\slurUp +r4 8\>( 8\!) +@end lilypond +@end quotation +@separate -@cindex fingering instructions -Fingering indications are entered simply using @code{-@var{N}}, where -@var{N} is a digit. -Now that we have the basic piece of music entered, we want to fine -tune it, so we get something that resembles the original printed -edition by Schott/Universal Edition: -@lilypondfile{brahms-tweaked.ly} +@node Basic rhythmical commands +@section Basic rhythmical commands -@cindex tuning grob behavior +@cindex pickup +@cindex anacruse +@cindex upstep +@cindex partial measure +A pickup (or upstep) is entered with the keyword @code{\partial}. It +is followed by a duration: @code{\partial 4} is a quarter note upstep +and @code{\partial 8} an eighth note: +@lilypond[relative=1,verbatim,fragment] + \partial 8 + f8 c2 d e +@end lilypond -The basic process that we follow is that we override defaults in the -printing system. We do this by setting variables in so-called grobs. -Printed symbols are internally represented by Graphical Objects -(Grobs). Each grob is described by a bunch of settings. Every -setting is a variable: it has a name, and you can assign a value to -the variable. These setting determine the fonts, offsets, sub-routines -to be called on the grob, etc. The initial values of these settings -are set in the Scheme file @file{scm/grob-description.scm}. +@cindex tuplets +@cindex triplets +Tuplets are made with the @code{\times} keyword. It takes two +arguments: a fraction and a piece of music. The duration of the piece +of music is multiplied by the fraction. Triplets make notes occupy +2/3 of their notated duration, so a triplet has 2/3 as its fraction: +@c +@lilypond[relative,verbatim,fragment] + \times 2/3 { f8 g a } + \times 2/3 { c r c } +@end lilypond -@cindex slur attachments +@cindex grace notes +@cindex accacciatura +Grace notes are also made by prefixing a note, or a set of notes with +a keyword. In this case, the keywords are @code{\appoggiatura} +and @code{\acciaccatura} +@cindex appoggiatura +@cindex acciaccatura + +@lilypond[relative=1,verbatim,fragment] + c4 \appoggiatura b16 c4 + c4 \acciaccatura b16 c4 +@end lilypond -We start with the slur: the slur in the upper part, running from the F -sharp to the A, runs from stem to stem in the printed edition, while -ours starts from the note head at the left. The following property -setting forces all slurs to run from stem to stem (and not from or to -note head) +@noindent -@example - \property Voice.Slur \set #'attachment = #'(stem . stem) -@end example +For more information on +@table @asis +@item grace notes +see @ref{Grace notes}, +@item tuplets +see @ref{Tuplets}, +@item upsteps +see @ref{Partial measures}. +@end table -More precisely, this command extends the definition of the @code{Slur} -object in the current @code{Voice}. The variable @code{attachment} is -set to the pair of symbols @code{'(stem . stem)}. - -Although this is useful information, it is not very helpful: the -lilypond back-end supports approximately 240 variables like -@code{attachment}, each with their own meaning and own type -(eg. number, symbol, list, etc). Besides slur, LilyPond has 80 -different types of Grobs, that may be created in 14 different context -types besides Voice. - -@cindex internal documentation -@cindex finding grobs -@cindex grob descriptions - -The interesting information is how you can figure out which properties -to tune for your own scores. To discover this, you must have a copy of -the internals document. This is a set of HTML pages, which should be -included if you run a binary distribution@footnote{You can also -compile them by executing @code{make -C Documentation/user/ -out/lilypond-internals.html} in the source package.}. This document is -also available on the web: go to the lilypond website, click -``Documentation: other'' on the side bar, click -``lilypond-internals'', under information for users. - -You might want to bookmark either the HTML files on disk, or the one -on the web. One word of caution is in place here: the internals -documentation is generated from the definitions that lily uses. For -that reason, it is strongly tied to the version of LilyPond that you -use. Before you proceed, please make sure that you are using the -documentation that corresponds to the LilyPond version that you use. - -Suppose that you wanted to tune the behavior of the slur. The first -step is to get some general information on slurs in lilypond. Turn to -the index, and look up ``slur''. The section on slurs says -@quotation -The grob for this object is @internalsref{Slur}, generally in -@internalsref{Voice} context. -@end quotation -So the grob for this object is called @code{Slur}, and slurs are -created in the @code{Voice} context. If you are reading this tutorial -in the HTML version, then you can simply click Slur, otherwise, you -must look it up the internal documentation: click ``grob overview'' , -and select ``slur'' (the list is alphabetical.) - -Now you get a list of all the properties that the slur object -supports, along with their default values. Among the properties we -find the @code{attachment} property with its default setting. -The property documentation explains that the following setting will -produce the desired effect: -@example - \property Voice.Slur \set #'attachment = #'(stem . stem) -@end example -If you ran the previous example, you have unknowingly already used -this kind of command. The @file{ly/property-init.ly} contains the -definition of @code{\stemUp} -@example - stemUp = \property Voice.Stem \set #'direction = #1 -@end example +@node Commenting input files +@section Commenting input files +@cindex comments +@cindex line comment +@cindex block comment +Comments are pieces of the input that are ignored. There are two +types of comments. A line comments is introduced by @code{%}: after +that, the rest of that line is ignored. Block comments span larger +sections of input. Anything that is enclosed in @code{%@{} and +@code{%@}} is ignored too. The following fragment shows possible uses +for comments: -We also want to move around the fingering `3'. In the printed edition -it is not above the stem, but a little lower, slightly left of the -stem. From the user manual, we find that the associated grob is called -@code{Fingering}, but how do we know if we should use @code{Voice} or -@code{Staff}. In many cases, @code{Voice} is a safe bet, but you can -also deduce this information from the internals documentation: if you -visit the documentation of @code{Fingering}, you will notice @example -Fingering grobs are created by: Fingering_engraver -@end example - - + % notes for twinkle twinkle follow: + c4 c g' g a a + + %@{ + + This line, and the notes below + are ignored, since they are in a + block comment. -Clicking @code{Fingering_engraver} will show you the documentation of -the module responsible for interpreting the fingering instructions and -translating them to a @code{Fingering} grob. Such a module is called -an @emph{engraver}. The documentation of the @code{Fingering_engraver} -says, -@example -Fingering_engraver is part of contexts: Voice and TabVoice -@end example -so tuning the settings for Fingering should be done using either -@example - \property Voice.Fingering \set @dots{} -@end example -or -@example - \property TabVoice.Fingering \set @dots{} + g g f f e e d d c2 + %@} @end example -Since the @code{TabVoice} is only used for tab notation, we see that -the first guess @code{Voice} was indeed correct. -@cindex setting grob properties -@cindex @code{extra-offset} -For shifting the fingering, we use the grob property -@code{extra-offset}. The following command manually adds an offset to -the object. We move it a little to the left, and 1.8 staff space -downwards. -@example - \property Voice.Fingering \set #'extra-offset = #'(-0.3 . -1.8) -@end example -The @code{extra-offset} is a low-level feature: it moves around -objects in the printout; the formatting engine is completely oblivious -to these offsets. The unit of these offsets are staff-spaces. -@cindex reverting grob properties -@cindex undoing grob properties +@node Printing lyrics +@section Printing lyrics +@cindex lyrics -We only want to offset a single grob, so after the F-sharp, we must -undo the setting. The technical term is to revert the grob property. +@cindex Lyrics +@cindex Songs +Lyrics are entered by separating each syllable with a space, and +surrounding them with @code{\lyrics @{ @dots{} @}}, for example, @example - \property Voice.Fingering \revert #'extra-offset + \lyrics @{ I want to break free @} @end example -@cindex property types -@cindex translator properties -@cindex grob properties -@cindex music properties - - -There is three different types of variables in LilyPond, something -which is confusing at first (and for some, it stays like that). -Variables such as @code{extra-offset} and @code{attachment} are called -grob properties. They are something different from the translator -properties, like @code{autoBeaming}. Finally, music expressions are -internally also stored using properties, so-called music -properties. You will encounter the latter type if you run Scheme -functions on music using @code{\apply}. - -The second fingering instruction should be moved up a little, to avoid -a collision with the slur. This could be achieved with -@code{extra-offset}, but in this case, a simpler mechanism also -works. We insert an empty text between the 5 and the note. The empty -text pushes the fingering instruction away: +Like notes, lyrics are also a form of music, but they must not be +printed on a staff, which is the default way to print music. To print +them as lyrics, they must be marked with @code{ \new Lyrics}: @example - a^" "^#'(finger "5") + \new Lyrics \lyrics @{ I want to break free @} @end example +The melody for this song is as follows: -Lilypond tries to put fingering instructions closer to the notes as -text instructions. To insert an empty text (@code{^" "}) between the -finger and the note, we have disguised the fingering instruction as a -text: @code{(finger "5")}. - -Normally, one would specify dynamics in a single voice, and start and -end dynamics (such as @b{f} and @b{p}) will be aligned with -hairpins. In this case, we want the decrescendo to be in a different -place from the piano sign. We achieve this by putting the dynamic -markings in different voices. The crescendo should be above the upper -staff. This can be forced by the precooked command -@example - \dynamicsUp -@end example +@lilypond[fragment,relative=1] + \partial 8 + c8 + \times 2/3 { f4 g g } \times 2/3 { g4( a2) } +@end lilypond -However, if you do that, the decrescendo will be too close to the -upper voice, and collide with the stems. Looking at the manual for -dynamics, we notice that ``Vertical positioning of these symbols is -handled by the @internalsref{DynamicLineSpanner} grob.''. If we turn -to the documentation of @code{DynamicLineSpanner}, we find that the -@code{DynamicLineSpanner} supports several so-called -`interfaces'. This grob not only puts dynamic objects next to the -staff (@code{side-position-interface}), but it also groups dynamic -objects (@code{axis-group-interface}), is considered a dynamic sign -itself (@code{dynamic-interface}) and is a grob: it has the -@code{grob-interface}, with all the variables that come with it. - -For the moment, we are interested in the side positioning: -@quotation - side-position-interface +The lyrics can be set to these notes, combining both with the +@code{\lyricsto} keyword: +@example + \lyricsto "@var{name}" \new Lyrics @dots{} +@end example +where @var{name} identifies to which melody the lyrics should be +aligned. In this case, there is only one melody, so we can leave it +empty. + +The final result is +@lilypond[verbatim,fragment] +\score { + \notes << + \relative c' \new Voice { + \partial 8 + c8 + \times 2/3 { f g g } \times 2/3 { g4( a2) } + } + \lyricsto "" \new Lyrics \lyrics { I want to break free } + >> + \paper{ } +} +@end lilypond - Position a victim object (this one) next to other objects (the - support). In this case, the direction signifies where to put the - victim object relative to the support (left or right, up or down?) -@end quotation -Between the grob and its support (in this case: the notes in the voice -going down), there should be more space. This space is controlled by -@code{padding}, so we increase it. +@cindex melisma +@cindex extender line +@c synonyms? +This melody ends on a @rglos{melisma}, a single syllable (``free'') +sung to more than one note. This is indicated with an @emph{extender +line}. It is entered as two underscores, i.e. @example - \property Voice.DynamicLineSpanner \override #'padding = #5.0 -@end example - -This command is almost like the command for setting slur attachments, -but subtly different in its details. Grob properties can be -manipulated with two commands: @code{\override} extends the grob -variables with a setting, and @code{\revert} releases this -setting. This has a certain theoretical appeal: the operations are -simple and symmetric. For practical use, it can be cumbersome. Both -commands act like parentheses: you should carefully balance the use of -@code{\override} and @code{\revert}. The @code{\set} command is more -friendly: it first does a @code{\revert} followed by @code{\override}. - -Finally, Brahms uses music notation is a slightly unorthodox way. Ties -usually happen only within one voice. In this piece, the composer -gladly produces ties that jump voices. We deal with this by faking -these ties: whenever we need such a tie, we insert a notehead in a -different voice, and blank the stem. This is done in the following -snippet of code. + \lyrics @{ I want to break free __ @} +@end example +@lilypond[raggedright] +\score { + \notes << + \relative c' \new Voice { + \partial 8 + c8 + \times 2/3 { f g g } \times 2/3 { g4( a2) } } + \lyricsto "" \new Lyrics \lyrics { I want to break free __ } + >> + \paper{ } +} +@end lilypond +Similarly, hyphens between words can be entered as two dashes, +resulting in a centered hyphen between two syllables: @example - \property Voice.Stem \set #'transparent = ##t - d' - \property Voice.Stem \revert #'transparent + Twin -- kle twin -- kle @end example +@lilypond[raggedright] +\score { + << \notes \relative f' { \time 2/4 + f4 f c' c' } + \new Lyrics \lyrics { Twin -- kle twin -- kle } + >> + \paper { raggedright = ##t } + } +@end lilypond -Finally, the last tie is forced up using @code{\tieUp}. +More options, like putting multiple lines of lyrics below a melody are +discussed in @ref{Vocal music}. -@node An orchestral score -@section An orchestral score -@menu -* The full score:: -* Extracting an individual part:: -@end menu +@node A lead sheet +@section A lead sheet +@cindex Lead sheets +@cindex chords +@cindex chord names + +In popular music, it is common to denote accompaniment as chord-names. +Using them in LilyPond has two parts, just like lyrics: entering the +chords (with @code{\chords}), and printing them (with @code{\new +ChordNames}). + +Chord names are entered by starting chords mode (with @code{\chords}). +In chords mode, you can enter chords with a letter (indicating the +root of the chord), and a durations following that: +@c +@lilypond[verbatim] + \chords { c2 f4. g8 } +@end lilypond -Our last two examples show a way to setup the music for an orchestral -score. When typesetting a piece for several instruments, you'll want to -create a conductor's full score, alongside several individual parts. +@noindent +The result of @code{\chords} is a list of chords, and is equivalent +to entering chords with @code{<@dots{}>}. -LilyPond is well suited for this task. We will declare the music for -each instrument individually, giving the music of each instrument its -own name. These pieces of music are then combined in different -@code{\score} blocks to produce different combinations of the score. +Other chords can be created by adding modifiers, after a colon. The +following example shows a few common modifiers: +@c +@lilypond[verbatim] + \chords { c2 f4:m g4:maj7 gis1:dim7 } +@end lilypond -This orchestral score example consists of three input files. In the -first file, @file{os-music.ly}, we define the music for all -instruments. This file will be used both for producing the score and -the separate parts. Other files reference this file by doing -@code{\include "os-music.ly"}. +Printing chords is done by adding @code{\context ChordNames} +before the chords thus entered: +@c +@lilypond[verbatim] + \context ChordNames \chords { c2 f4.:m g4.:maj7 gis8:dim7 } +@end lilypond -If you were to run LilyPond on this file, no printable output would be -produced. +@cindex lead sheet +@separate +When put together, chord names, lyrics and a melody form +a lead sheet, for example, @example -% os-music.ly -\header @{ - title = "Zo, goed lieverd?" - subtitle = "How's, this babe?" - composer = "JCN" - opus = "1" - piece = "Laid back" -@} -global = @{ - \time 2/4 - \skip 2*4 \bar "|." -@} -Key = \notes \key as \major -flautoI = \notes\relative c'' @{ - f8 g f g f g f g - bes as bes as bes as bes as -@} -flautoII = \notes\relative c'' @{ - as8 bes as bes R1 d4 ~ d -@} -tromboI = \notes\relative c'' @{ - c4. c8 c8 c4. es4 r as, r -@} -tromboII = \notes\relative c'' @{ - as4. as8 as8 as4. R1*1/2 as4 es' -@} -timpani = \notes\relative c, @{ - \times 2/3 @{ f4 f f @} - \times 4/5 @{ as8 as as as as @} - R1 -@} -corno = \notes\relative c' @{ - bes4 d f, bes d f, bes d +\score @{ + << + \context ChordNames \chords @{ @emph{chords} @} + \notes @emph{the melody} + \lyricsto "" \new Lyrics \lyrics @{ @emph{the text} @} + >> + \paper @{ @} @} @end example +@lilypond[] +\score { + << + \context ChordNames \chords { r8 c2:sus4 f } + \notes \relative c' { + \partial 8 + c8 + \times 2/3 { f g g } \times 2/3 { g4( a2) } } + \new Lyrics \lyricsto "" \lyrics { I want to break free __ } + >> + \paper{ raggedright = ##t } +} +@end lilypond -We will not go through the input line by line, but only indicate and -explain the new elements. +A complete list of modifiers, and other options for layout are in the +reference manual section @ref{Chords}. -@separate -@example -global = @{ - \time 2/4 - \skip 2*4 \bar "|."; +@node Listening to output +@section Listening to output + +@cindex sound +@cindex MIDI + +MIDI (Musical Instrument Digital Interface) is a standard for +connecting and recording digital instruments. A MIDI file is like a +tape recording of a MIDI instrument. The @code{\midi} block makes the +music go to a MIDI file, so you can listen to the music you entered. +It is great for checking the music: octaves that are off, or +accidentals that were mistyped, stand out very much when listening to +the musical transcription. + +@code{\midi} can be used in similarly to @code{\paper @{ @}}, for +example, +@example +\score @{ + @var{..music..} + \midi @{ \tempo 4=72 @} + \paper @{ @} @} -@end example +@end example -Declare setting to be used globally. The @code{\skip} command produces -no output, but moves forward in time: in this case, the duration of a -half note (@code{2}), and that four times (@code{*4}). This brings us -to the end of the piece, and we can set the end bar. +Here, the tempo is specified using the @code{\tempo} command. In this +case the tempo of quarter notes is set to 72 beats per minute. More +information on auditory output is in the @ref{Sound} section in the +notation manual. -@separate -@example -Key = \notes \key as \major -@end example -Declare the key signature of the piece and assign it to the identifier -@var{Key}. Later on, we'll use @code{\Key} for all staves except those -for transposing instruments. -@node The full score -@subsection The full score +@node Titling +@section Titling + +Bibliographic information is entered in a separate block, the +@code{\header} block. The name of the piece, its composer, etc. are +entered as an assignment, within @code{\header @{ @dots{} @}}. For +example, +@example + \header @{ + title = "Eight miniatures" + composer = "Igor Stravinsky" + tagline = "small is beautiful" + @} + + \score @{ @dots{} @} +@end example -The second file, @file{input/tutorial/os-score.ly} reads the definitions of the first -(@file{input/tutorial/os-music.ly}), and defines the @code{\score} block for the full -conductor's score. +@cindex bibliographic information +@cindex titles +@cindex composer +@cindex Engraved by LilyPond +When the file is processed by the @code{lilypond} wrapper script, then +the title and composer specified are printed above the music. The +`tagline' is a short line printed at bottom of the last page, which +normally says ``Engraved by LilyPond, version @dots{}''. In the +example above, it is replaced by the line ``small is +beautiful.''@footnote{Nicely printed parts are good PR for us, so do +us a favor, and leave the tagline if you can.} -@example -% os-score.ly -\include "os-music.ly" -\include "paper13.ly" +Normally, the @code{\header} is put at the top of the file. However, +for a document that contains multiple pieces (e.g. an etude book, or +an orchestral part with multiple movements), then the header can be +put into the @code{\score} block as follows; in this case, the name of +each piece will be printed before each movement: -#(set-point-and-click! 'line-column) -#(define text-flat '((font-relative-size . -2) - (music "accidentals--1"))) -\score @{ - < - \global - \property Score.BarNumber \override #'padding = #3 - \context StaffGroup = woodwind < - \context Staff = flauti < - \property Staff.midiInstrument = #"flute" - \property Staff.instrument = "2 Flauti" - \property Staff.instr = "Fl." - \Key - \context Voice=one @{ \voiceOne \flautoI @} - \context Voice=two @{ \voiceTwo \flautoII @} - > - > - \context StaffGroup = timpani < - \context Staff = timpani < - \property Staff.midiInstrument = #"timpani" - \property Staff.instrument = #'(lines "Timpani" "(C-G)") - \property Staff.instr = #"Timp." - \clef bass - \Key - \timpani - > - > - \context StaffGroup = brass < - \context Staff = trombe < - \property Staff.midiInstrument = #"trumpet" - \property Staff.instrument = #`(lines "2 Trombe" "(C)") - \property Staff.instr = #`(lines "Tbe." "(C)") - \Key - \context Voice=one \partcombine Voice - \context Thread=one \tromboI - \context Thread=two \tromboII - > - \context Staff = corni < - \property Staff.midiInstrument = #"french horn" - \property Staff.instrument = #`(lines "Corno" - (columns "(E" ,text-flat ")")) - \property Staff.instr = #`(lines "Cor." - (columns "(E" ,text-flat ")")) - \property Staff.transposing = #3 - \notes \key bes \major - \context Voice=one \corno - > - > - > - \paper @{ - indent = 15 * \staffspace - linewidth = 60 * \staffspace - textheight = 90 * \staffspace - \translator@{ - \HaraKiriStaffContext - @} +@cindex Engraved by LilyPond +@cindex signature line +@cindex tag line + +@example + \header @{ + title = "Eight miniatures" + composer = "Igor Stravinsky" + tagline = "small is beautiful" @} - \midi @{ - \tempo 4 = 75 + + \score @{ @dots{} + \header @{ piece = "Adagio" @} + @} + \score @{ @dots{} + \header @{ piece = "Menuetto" @} @} -@} @end example -@center @strong{Zo, goed lieverd?} -@sp 1 -@center How's, this babe? -@flushright -Opus 1. -@end flushright -@flushleft -@sc{Laid back} -@end flushleft +More information on titling can be found in @ref{Invoking lilypond}. -@lilypondfile{os-score.ly} -@separate +@node Single staff polyphony +@section Single staff polyphony + +@cindex polyphony +@cindex multiple voices +@cindex voices, more -- on a staff + +When different melodic lines are combined on a single staff, these are +printed as polyphonic voices: each voice has its own stems, slurs and +beams, and the top voice has the stems up, while the bottom voice has +them down. + +Entering such parts is done by entering each voice as a sequence (with +@code{@{ .. @}}), and combining those simultaneously, separating the +voices with @code{\\}: + @example -\include "os-music.ly" + << @{ a4 g2 f4~ f4 @} \\ + @{ r4 g4 f2 f4 @} >> @end example -First, we need to include the music definitions we made in -@file{os-music.ly}. +@lilypond[relative=1] +\context Staff << { a4 g2 f4~ f4 } \\ + { r4 g4 f2 f4 } >> +@end lilypond -@separate +For polyphonic music typesetting, spacer rests can also be convenient: these +are rests that do not print. It is useful for filling up voices that +temporarily do not play: @example -#(set-point-and-click! 'line-column) + << @{ a4 g2 f4~ f4 @} \\ + @{ s4 g4 f2 f4 @} >> @end example +@lilypond[relative=1] +\context Staff << { a4 g2 f4~ f4 } \\ + { s4 g4 f2 f4 } >> +@end lilypond -This piece of Scheme code executes the function -@code{set-point-and-click!}, with the argument @code{line-column}, a -symbol). +Again, these expressions can be nested arbitrarily: -Editing input files can be complicated if you're working with large -files: if you're digitizing existing music, you have to synchronize -the .ly file, the sheet music on your lap and the sheet music on the -screen. The point-and-click mechanism makes it easy to find the -origin of an error in the LY file: when you view the file with Xdvi -and click on a note, your editor will jump to the spot where that note -was entered. For more information, see @ref{Point and click}. +@lilypond[fragment] +<< + \new Staff + \relative c'' + << { a4 g2 f4~ f4 } \\ + { s4 g4 f2 f4 } >> + \new Staff + << { \clef bass 1 ~ 4 } \\ + { f4 d e2 ~ e4} + >> +>> +@end lilypond -@separate -@example -#(define text-flat '((font-relative-size . -2) - (music "accidentals--1"))) -@end example +More features of polyphonic typesetting are in the notation manual +in @ref{Polyphony}. -When naming the tuning of the french horn, we'll need a piece of text -with a flat sign. LilyPond has a mechanism for font selection and -kerning called Scheme markup text (See @ref{Text markup}). The flat -sign is taken from the music font, and its name is @code{accidentals--1} -(The natural sign is called @code{accidentals-0}). The default font is -too big for text, so we select a relative size of @code{-2}. +@node Piano staves +@section Piano staves -@separate -@example - < - \global -@end example -Of course, all staves are simultaneous and use the same global settings. +@cindex staff switch, manual +@cindex cross staff voice, manual +@cindex @code{\translator} -@separate +Piano music is always typeset in two staves connected by a brace. +Printing such a staff is done similar to the polyphonic example in +@ref{Combining music into compound expressions}: @example - \property Score.BarNumber \override #'padding = #3 + << \new Staff @{ @dots{} @} + \new Staff @{ @dots{} @} + >> @end example -LilyPond prints bar numbers at the start of each line, but -unfortunately, they end up a bit too close to the staff in this -example. A bar number internally is a Grob called @var{BarNumber}. -BarNumber Grobs can be manipulated through their -@var{side-position-interface}. One of the properties of a -@var{side-position-interface} that can be tweaked is the -@var{padding}: the amount of extra space that is put between this Grob -and other Grobs. We set the padding to three staff spaces. - -You can find information on all these kind of properties in LilyPond's -automatically generated documentation in -@ifnottex -@ref{ (lilypond-internals)lilypond-internals, LilyPond Internals}. -@end ifnottex -@iftex -the online documentation. -@end iftex - -@separate +but now this entire expression must be interpreted as a +@code{PianoStaff}: @example - \context StaffGroup = woodwind < - \context Staff = flauti < + \new PianoStaff << \new Staff @dots{} >> @end example -A new notation context: the @code{StaffGroup}. @code{StaffGroup} can -hold one or more @code{Staff}'s, and will print a big bracket at the -left of the score. Start a new staff group for the woodwind section -(just the flutes in this case). Immediately after that, we start the -staff for the two flutes, that also play simultaneously. -@separate -@example - \property Staff.midiInstrument = #"flute" -@end example -Specify the instrument for MIDI output (see @ref{MIDI instrument -names}). +Here is a full-fledged example: -@separate -@example - \property Staff.instrument = "2 Flauti" - \property Staff.instr = "Fl." -@end example -And define the instrument names to be printed in the margin, -@code{instrument} for the first line of the score, @code{instr} for the -rest of the score. +@lilypond[relative,fragment] +\new PianoStaff + << \new Staff { \time 2/4 + c4 c g' g } + \new Staff { + \clef bass c,, c' e c } + >> +@end lilypond -@separate +More information on formatting piano music is in @ref{Piano music}. + +@node Setting variables +@section Setting variables + +When the music is converted from notes to print, it is interpreted +from left-to-right order, similar to what happens when we read +music. During this step, context-sensitive information, such as the +accidentals to print, and where barlines must be placed, are stored in +variables. These variables are called @emph{context properties}. +The properties can also be manipulated from input files. Consider this input: @example - \Key -@end example -The flutes play in the default key. +\set Staff.autoBeaming = ##f +@end example -@separate +@noindent +It sets the property named @code{autoBeaming} in the current staff at +this point in the music to @code{##f}, which means `false'. This +property controls whether beams are printed automatically: +@c +@lilypond[relative=1,fragment,verbatim] + c8 c c c + \set Staff.autoBeaming = ##f + c8 c c c +@end lilypond + +@noindent +LilyPond includes a built-in programming language, namely, a dialect +of Scheme. The argument to @code{\property}, @code{##f}, is an +expression in that language. The first hash-mark signals that a piece +of Scheme code follows. The second hash character is part of the +boolean value true (@code{#t}). Values of other types may be +entered as follows: +@itemize @bullet +@item a string, enclosed in double quotes, for example, @example - \context Voice=one @{ \voiceOne \flautoI @} - \context Voice=two @{ \voiceTwo \flautoII @} + \set Staff.instrument = #"French Horn" @end example -Last come the actual flute parts. Remember that we're still in -simultaneous mode. We name both voices differently, so that LilyPond -will actually create two Voice contexts. The flute parts are simple, so -we specify manually which voice is which: @code{\voiceOne} forces the -direction of stems, beams, slurs and ties up, @code{\voiceTwo} sets -directions down. - -@separate +@item a boolean: either @code{#t} or @code{#f}, for true and false +respectively, e.g. @example - > - > + \set autoBeaming = ##f + \set Score.skipBars = ##t @end example -Close the flutes staff and woodwind staff group. -@separate +@item a number, such as @example - \property Staff.instrument = #'(lines "Timpani" "(C-G)") + \set Score.currentBarNumber = #20 @end example -The timpani staff only shows a new piece of scheme markup, it sets two -lines of text. -@separate +@item a symbol, which is introduced by a quote character, as in @example - \context Voice=one \partcombine Voice - \context Thread=one \tromboI - \context Thread=two \tromboII + \set Staff.crescendoSpanner = #'dashed-line @end example -You have seen the notation contexts Staff and Voice, but here's a new -one: Thread. One or more Threads can be part of a Voice. The Thread -takes care of note heads and rests, the Voice combine note heads onto a -stem. - -For the trumpets we use the automatic part combiner (see @ref{Automatic -part combining}) to combine the two simultaneous trumpet parts onto the -trumpet staff. Each trumpet gets its own Thread context, which must be -named @code{one} and @code{two}). The part combiner makes these two -threads share a Voice when they're similar, and splits the threads up -when they're different. -@separate +@item a pair, which is also introduced by a quote character, like in +the following statements, which set properties to the pairs (-7.5, 6) +and (3, 4) respectively: + @example - \property Staff.instrument = #`(lines "Corno" - (columns "(E" ,text-flat ")")) + \set Staff.minimumVerticalExtent = #'(-7.5 . 6) + \set Staff.timeSignatureFraction = #'(3 . 4) @end example -The french horn has the most complex scheme markup name, made up of two -lines of text. The second line has three elements (columns), the @code{(E}, -the flat sign @code{text-flat} that we defined before and a final @code{")"}. -Note that we use a backquote instead of an ordinary quote at the -beginning of the Scheme expression to be able to access the -@code{text-flat} identifier, `unquoting' it with a @code{,}. -@separate +@item a list, which is also introduced by a quote character. In the +following example, the @code{breakAlignOrder} property is set to a +list of symbols: @example - \property Staff.transposing = #3 + \set Score.breakAlignOrder = + #'(left-edge time-signature key-signatures) @end example -The french horn is to be tuned in E-flat, so we tell the MIDI back-end to -transpose this staff by three steps. -Note how we can choose different tuning for entering, printing and -playing, using @code{\transpose} and the MIDI Staff property -@var{transposing}. -@separate +@end itemize + +There are many different properties, and not all of them are listed in +this manual. However, the program reference lists them all in the +section @internalsref{Context-properties}, and most properties are +demonstrated in one of the +@ifhtml +@uref{../../../input/test/out-www/collated-files.html,tips-and-tricks} +@end ifhtml +@ifnothtml +tips-and-tricks +@end ifnothtml +examples. + + +@node Fine tuning layout +@section Fine tuning layout + +Sometimes it is necessary to change music layout by hand. When music +is formatted, layout objects are created for each symbol. For +example, every clef and every note head is represented by a layout +object. These layout objects also carry variables, which we call +@emph{layout properties}. By changing these variables from their +values, we can alter the look of a formatted score: + +@lilypond[verbatim,relative] + c4 + \override Stem #'thickness = #3.0 + c4 c4 c4 +@end lilypond + +@noindent +In the example shown here, the layout property @code{thickness} (a +symbol) is set to 3 in the @code{Stem} layout objects of the current + As a result, the notes following @code{\property} have thicker +stems. + +In most cases of manual overrides, only a single object must be +changed. This can be achieved by prefixing @code{\once} to the +@code{\property} statement, i.e. + @example - \notes \key bes \major + \once \override Stem #'thickness = #3.0 @end example -Therefore, it has a different key. -@separate +@lilypond[relative] + c4 + \once \override Stem #'thickness = #3.0 + c4 c4 c4 +@end lilypond + +@noindent +Some overrides are so common that predefined commands are provided as +a short cut. For example, @code{\slurUp} and @code{\stemDown}. These +commands are described in +@ifhtml +the +@end ifhtml +@ref{Notation manual}, under the sections for slurs and stems +respectively. + +The exact tuning possibilities for each type of layout object are +documented in the program reference of the respective +object. However, many layout objects share properties, which can be +used to apply generic tweaks. We mention a couple of these: + +@itemize @bullet +@item The @code{extra-offset} property, which +@cindex @code{extra-offset} +has a pair of numbers as value, moves around objects in the printout. +The first number controls left-right movement; a positive number will +move the object to the right. The second number controls up-down +movement; a positive number will move it higher. The unit of these +offsets are staff-spaces. The @code{extra-offset} property is a +low-level feature: the formatting engine is completely oblivious to +these offsets. + +In the following example, the second fingering is moved a little to +the left, and 1.8 staff space downwards: + +@cindex setting object properties + +@lilypond[relative=1,verbatim] +\stemUp +f-5 +\once \override Fingering + #'extra-offset = #'(-0.3 . -1.8) +f-5 +@end lilypond + +@item +Setting the @code{transparent} property will make an object be printed +in `invisible ink': the object is not printed, but all its other +behavior is retained. The object still takes space, it takes part in +collisions, and slurs, ties and beams can be attached to it. + +@cindex transparent objects +@cindex removing objects +@cindex invisible objects +The following example demonstrates how to connect different voices +using ties. Normally ties only happen between notes of the same +voice. By introducing a tie in a different voice, and blanking a stem +in that voice, the tie appears to cross voices: + +@lilypond[fragment,relative=1,verbatim] + c4 << { + \once \override Stem #'transparent = ##t + b8~ b8 + } \\ { + b[ g8] + } >> +@end lilypond + +@item +The @code{padding} property for objects with +@cindex @code{padding} +@code{side-position-interface} can be set to increase distance between +symbols that are printed above or below notes. We only give an +example; a more elaborate explanation is in @ref{Constructing a +tweak}: + +@lilypond[relative=1,verbatim] + c2\fermata + \override Script #'padding = #3 + b2\fermata +@end lilypond + +@end itemize + +More specific overrides are also possible. The notation manual +discusses in depth how to figure out these statements for yourself, in +@ref{Tuning output}. + +@node Organizing larger pieces +@section Organizing larger pieces + +When all of the elements discussed earlier are combined to produce +larger files, the @code{\score} blocks get a lot bigger, because the +music expressions are longer, and, in the case of polyphonic and/or +orchestral pieces, more deeply nested. Such large expressions can +become unwieldy. + +By using variables, also known as identifiers, it is possible to break +up complex music expressions. An identifier is assigned as follows: +@c @example - indent = 15 * \staffspace - linewidth = 60 * \staffspace + namedMusic = \notes @{ @dots{} @end example -We specify a big indent for the first line and a small linewidth for this -tutorial. -@separate +The contents of the music expression @code{namedMusic}, can be used +later by preceding the name with a backslash, i.e. @code{\namedMusic}. +In the next example, a two note motive is repeated two times by using +variable substitution: + +@lilypond[raggedright,verbatim] +seufzer = \notes { + dis'8 e'8 +} +\score { \notes { + \seufzer \seufzer +} } +@end lilypond -Usually, LilyPond's predefined setup of notation contexts (Thread, -Voice, Staff, Staffgroup, Score) is just fine. But in this case, we -want a different type of Staff context. +The name of an identifier should have alphabetic characters only, and +no numbers, underscores or dashes. The assignment should be outside of +the @code{\score} block. +It is possible to use variables for many other types of objects in the +input. For example, +@example + width = 4.5\cm + name = "Wendy" + aFivePaper = \paper @{ paperheight = 21.0 \cm @} +@end example +Depending on its contents, the identifier can be used in different +places. The following example uses the above variables: @example - \translator@{ - \HaraKiriStaffContext + \score @{ + \notes @{ c4^\name @} + \paper @{ + \aFivePaper + linewidth = \width @} + @} @end example -In orchestral scores, it often happens that one instrument has only -rests during one line of the score. The @code{HaraKiriStaffContext} can -be used as a regular @code{StaffContext} drop-in and will take care of -the automatic removing of empty staves. +More information on the possible uses of identifiers is in the +technical manual, in @ref{Scheme datatypes}. + -@node Extracting an individual part -@subsection Extracting an individual part +@node An orchestral part +@section An orchestral part -The third file, @file{os-flute-2.ly} also reads the definitions of the -first (@file{os-music.ly}), and defines the @code{\score} block for the -second flute part. +In orchestral music, all notes are printed twice: both in a part for +the musicians, and in a full score for the conductor. Identifiers can +be used to avoid double work: the music is entered once, and stored in +variable. The contents of that variable is then used to generate +both the part and the score. +It is convenient to define the notes in a special file, for example, +suppose that the @file{horn-music.ly} contains the following part of a +horn/bassoon duo. @example -\include "os-music.ly" -\include "paper16.ly" +hornNotes = \notes \relative c @{ + \time 2/4 + r4 f8 a cis4 f e d +@} +@end example +Then, an individual part is made by putting the following in a file: +@example +\include "horn-music.lyinc" +\header @{ + instrument = "Horn in F" +@} \score @{ - \context Staff < - \property Score.skipBars = ##t - \property Staff.midiInstrument = #"flute" - \global - \Key - \flautoII - > - \header @{ - instrument = "Flauto II" - @} - \paper @{ - linewidth = 80 * \staffspace - textheight = 200 * \staffspace - @} - \midi @{ - \tempo 4 = 75 - @} + \notes \transpose f c' \hornNotes @} @end example +The @code{\include} command substitutes the contents of the file at +this position in the file, so that @code{hornNotes} is defined +afterwards. The code @code{\transpose f c'} indicates that the +argument, being @code{\hornNotes}, should be transposed by a fifth +downwards: sounding @code{f} is denoted by notated @code{c'}, which +corresponds with tuning of a normal French Horn in F. The +transposition can be seen in the following output: -@center @strong{Zo, goed lieverd?} -@sp 1 -@center How's, this babe? -@center @emph{Flauto II} -@flushright -Opus 1. -@end flushright -@flushleft -@sc{Laid back} -@end flushleft -@lilypondfile{os-flute-2.ly} - - -Because we separated the music definitions from the @code{\score} -instantiations, we can easily define a second score with the music of -the second flute. This then is the part for the second flute player. -Of course, we make separate parts for all individual instruments. +@lilypond[raggedright] +\score { + \notes \transpose f c' \notes \relative c { + \time 2/4 + r4 f8 a cis4 f e d +} +} +@end lilypond -@separate +In ensemble pieces, one of the voices often does not play for many +measures. This is denoted by a special rest, the multi-measure +rest. It is entered with a capital R, and followed by a duration (1 +for a whole note, 2 for a half note, etc.) By multiplying the +duration, longer rests can be constructed. For example, the next rest +takes 3 measures in 2/4 time: @example - \flautoII + R2*3 @end example -In this individual part the second flute has a whole staff for itself, -so we don't want to force stem or tie directions. -@separate +When printing the part, the following @code{skipBars} property must be +set to false, to prevent the rest from being expanded in three one bar +rests: @example - \header @{ - instrument = "Flauto II" - @} + \set Score.skipBars = ##t @end example -The @code{\header} definitions were also read from @file{os-music.ly}, -but we need to set the instrument for this particular score. +Prepending the rest and the property setting above, leads to the +following result: -@separate +@lilypond[raggedright] +\score {\notes { \transpose f c' \relative c { \time 2/4 +\set Score.skipBars = ##t + R2*3 + r4 f8 a cis4 f e d } }} +@end lilypond + +The score is made by combining all of the music in a @code{\score} +block, assuming that the other voice is in @code{bassoonNotes}, in the +file @file{bassoon-music.ly}: @example - \property Score.skipBars = ##t +\include "bassoon-music.lyinc" +\include "horn-music.lyinc" + +\score @{ + \simultaneous @{ + \new Staff \hornNotes + \new Staff \bassoonNotes + @} @} @end example -In the conductor's full score, all bars with rests are printed, but for -the individual parts, we want to contract pieces of consecutive empty -bars. LilyPond will do this if Score's @var{skipBars} property to -true. + +This would lead to the simple score depicted below: + +@lilypond[raggedright] +\score { + \notes \relative c \simultaneous { + \new Staff { \time 2/4 + R2*3 + r4 f8 a cis4 f e d } + \new Staff { \clef bass + r4 d,8 f | gis4 c | b bes | + a8 e f4 | g d | gis f } + } } +@end lilypond + +More in-depth information on preparing parts and scores is in the +notation manual, in @ref{Orchestral music}. @node Integrating text and music @section Integrating text and music - @cindex La@TeX{}, music in @cindex HTML, music in @cindex Texinfo, music in -Sometimes, you might want to use music examples in a text that you are -writing. For example, if you are writing a musicological treatise, a -songbook, or (like us) the LilyPond manual. You can make such texts by -hand, simply by importing a PostScript figure into your word processor. -However, there is a also an automated procedure: +Sometimes you might want to use music examples in a text that you are +writing (for example, a musicological treatise, a songbook, or (like us) +the LilyPond manual). You can make such texts by hand, simply by +importing a PostScript figure into your word processor. However, +there is an automated procedure to reduce the amount of work. -If you use HTML, La@TeX{} or texinfo, you can mix text and LilyPond -code. A script called @code{lilypond-book} will extract the music +If you use HTML, La@TeX{}, or Texinfo, you can mix text and LilyPond +code. A script called @code{lilypond-book} will extract the music fragments, run LilyPond on them, and put back the resulting notation. -This utility program is described fully in the chapter @ref{Insert -music snippets into your texts using lilypond-book}. Here we show a -small example. Since the example also contains explanatory text, we -won't comment on the contents. +This program is fully described in @ref{lilypond-book manual}. Here +we show a small example. The example contains also explanatory text, +so we will not comment it further: @example \documentclass[a4paper]@{article@} @@ -2778,8 +1788,6 @@ example: c2 g'2 \times 2/3 @{ f8 e d @} c'2 g4 @} @} \end@{lilypond@} -Notice that the music line length matches the margin settings of the -document. If you have no \verb+\score+ block in the fragment, \texttt@{lilypond-book@} will supply one: @@ -2788,67 +1796,67 @@ If you have no \verb+\score+ block in the fragment, c'4 \end@{lilypond@} -In the example you see here, a number of things happened: a +In the example you see here, two things happened: a \verb+\score+ block was added, and the line width was set to natural -length. You can specify many more options using \LaTeX style options -in brackets: +length. You can specify options by putting them in brackets: -\begin[verbatim,11pt,singleline, - fragment,relative,intertext="hi there!"]@{lilypond@} - c'4 f bes es +\begin[staffsize=26,verbatim]@{lilypond@} + c'4 f16 \end@{lilypond@} -\texttt@{verbatim@} also shows the LilyPond code, \texttt@{11pt@} selects -the default music size, \texttt@{fragment@} adds a score block, -\texttt@{relative@} uses relative mode for the fragment, and -\texttt@{intertext@} specifies what to print between the -\texttt@{verbatim@} code and the music. - -If you include large examples into the text, it may be more convenient -to put the example in a separate file: +If you want to include large examples into the text, it is more +convenient to put it in a separate file: -\lilypondfile[printfilename]@{sammartini.ly@} - -The \texttt@{printfilename@} option adds the file name to the output. +\lilypondfile@{screech-boink.ly@} \end@{document@} @end example -Under Unix, you can view the results as follows. +Under Unix, you can view the results as follows: @example $ cd input/tutorial -$ mkdir out/ -@var{..may complain that @file{out/} already exists..} -$ lilypond-book --outdir=out/ lilbook.tex -lilypond-book (GNU LilyPond) 1.3.146 -Reading `input/tutorial/lilbook.tex' -Reading `input/tutorial/sammartini.ly' +$ mkdir -p out/ +$ lilypond-book --output=out/ lilybook.tex +lilypond-book (GNU LilyPond) 2.1.19 +Reading `input/tutorial/lilybook.tex' +Reading `input/screech-boink.ly' @var{lots of stuff deleted} -Writing `out/lilbook.latex' +Writing `out/lilybook.latex' $ cd out -$ latex lilbook.latex +$ latex lilybook.latex @var{lots of stuff deleted} -$ xdvi lilbook +$ xdvi lilybook +@end example + +To convert the file into a nice PDF document, run the following +commands: +@example +$ dvips -Ppdf -u +lilypond lilybook +$ ps2pdf lilybook.ps @end example -Notice the @code{outdir} option to lilypond-book. Running lilypond-book -and running latex creates a lot of temporary files, and you wouldn't want -those to clutter up your working directory. Hence, we have them created -in a separate subdirectory. -The result more or less looks like this: +Running lilypond-book and running latex creates a lot of temporary +files, and you would not want those to clutter up your working +directory. The @code{outdir} option to lilypond-book creates the +temporary files in a separate subdirectory @file{out}. + +The result looks more or less like this: @separate In a lilypond-book document, you can freely mix music and text. For example: @lilypond - \score { \notes \relative c' { - c2 g'2 \times 2/3 { f8 e d } c'2 g4 - } } +\score { + \notes \relative c' { + c2 g'2 \times 2/3 { f8 e d } c'2 g4 + } + \paper { + raggedright = ##t + } +} @end lilypond -Notice that the music line length matches the margin settings of the -document. If you have no @code{\score} block in the fragment, @code{lilypond-book} will supply one: @@ -2857,47 +1865,15 @@ If you have no @code{\score} block in the fragment, c'4 @end lilypond -In the example you see here, a number of things happened: a -@code{\score} block was added, and the line width was set to natural -length. You can specify many more options using La@TeX{} style options -in brackets: +In the example you see here, two things happened: a +@code{score} block was added, and the line width was set to natural +length. You can specify options by putting them in brackets: -@lilypond[verbatim,11pt,singleline, - fragment,relative,intertext="hi there!"] - c'4 f bes es +@lilypond[staffsize=26,verbatim] + c'4 f16 @end lilypond -@code{verbatim} also shows the LilyPond code, @code{11pt} selects -the default music size, @code{fragment} adds a score block, -@code{relative} uses relative mode for the fragment, and -@code{intertext} specifies what to print between the -@code{verbatim} code and the music. - -If you include large examples into the text, it may be more convenient -to put the example in a separate file: - -@lilypondfile[printfilename]{sammartini.ly} - -The @code{printfilename} option adds the file name to the output. -@node End of tutorial -@section End of tutorial - -This is the end of the tutorial. If you came up till here, and -have understood everything, then you're now an accomplished lilypond -hacker. From here, you can try fiddling with input -files, coming back to the reference manual for information. -Also don't forget to check out the -@ifhtml -@uref{../../templates/out-www/templates.html,templates}, -@uref{../../test/out-www/test.html,example} and -@uref{../../regression/out-www/regression.html,feature test} -snippets. -@end ifhtml -@ifnothtml -templates, example and feature test snippets. -@end ifnothtml -If you want to see real action lilypond, then head over to -@uref{http://www.mutopiaproject.org}, which has many examples of -classical music typeset by LilyPond. - +If you want to include large examples into the text, it is more +convenient to put it in a separate file: +@lilypondfile{screech-boink.ly}