X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Ftutorial.itely;h=1a93fe25526a3f5c6f6b00bc92cdb3a8ddd7daff;hb=a327a1212bd28d350e7648fbbcbe593d8ceaeb3e;hp=cf56e931c029888268a2e4f7e089a5308e27ba52;hpb=237583408aaf3b2192c388c3183d9c57fb051bd0;p=lilypond.git diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely index cf56e931c0..8b5e570b5b 100644 --- a/Documentation/user/tutorial.itely +++ b/Documentation/user/tutorial.itely @@ -1,1795 +1,1490 @@ -@c -*-texinfo-*- - +@c -*- coding: utf-8; mode: texinfo; -*- +@c This file is part of lilypond.tely +@ignore + Translation of GIT committish: FILL-IN-HEAD-COMMITTISH + + When revising a translation, copy the HEAD committish of the + version that you are working on. See TRANSLATION for details. +@end ignore + +@ignore +Tutorial guidelines: +- unless you have a really good reason, use either + @l ilypond[quote,ragged-right,verbatim] + or + @l ilypond[quote,ragged-right,verbatim,fragment,relative=2] + (without spaces) + Don't use any other relative=X commands (make it a non-fragment + example), and don't use fragment without relative=2. +- use "aes" and "ees" instead of "as" and "aes". I know it's not + correct Dutch naming, but let's not confuse people with this until + we get to the Basic notation chapter. +@end ignore + + + +@c old info that will probably be removed. @c TODO: @c * more details about running lilypond; error messages, @c compiling/viewing (emacs?) -@c * where to go from First steps+More basics? +@c * where to go from First steps+More basics? -@node Tutorial -@chapter Tutorial +@c wherever possible, do not include index entries here; the +@c index should point to stuff in the reference manual. -gp +@c Your first LilyPond score in 10 minutes? +@node Tutorial +@chapter Tutorial -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, by showing 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. +This tutorial starts with an introduction to the LilyPond music +language and how to produce printed music. After this first contact we +will explain how to create common musical notation. +@ifhtml Many people learn programs by trying and fiddling around with the -program. This is also possible with LilyPond. If you click on a +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: -@c TODO: intertext fixme -@lilypond[relative 1,singleline,verbatim,intertext="with the following output:"] - c'^\markup { \bold \huge { Click on this image! } } +Try it on this image + +@lilypond[fragment,quote,ragged-right,relative=2] +c-\markup { \bold \huge { Click here. } } @end lilypond +By cutting and pasting everything from the @qq{Start cut-&-pastable-section} +to the end of the file, you have a +starting template for experiments. If you like learning in this way, +you will probably want to print out or bookmark the +@ref{Cheat sheet}, which is a table listing of the most common +commands for quick reference. @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, normally using the program @code{ly2dvi}. 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 about pitches and accidentals:: -* Octave entry:: -* Combining music into compound expressions:: -* Adding articulation marks to notes:: -* Combining notes into chords:: -* Printing lyrics:: -* 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:: Integrating text and music. +* First steps:: +* Single staff notation:: +* Multiple notes at once:: +* Songs:: +* Final touches:: @end menu @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 @samp{a} -through @samp{g}. So if you enter +This section gives a basic introduction to working with LilyPond. -@example -c d e f g a b -@end example +@menu +* Compiling a file:: +* Simple notation:: +* Working on text files:: +* How to read the tutorial:: +@end menu -@noindent -then the result looks like this: - -@c ? -@c \transpose c c' { c d e f g a b } -@c @lily pond[notime] -@c \property Score.timing = ##f -@lilypond[notime, relative=2] -c d e f g a b -@end lilypond -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: +@node Compiling a file +@subsection Compiling a file + +The first example demonstrates how to start working with LilyPond. To +create sheet music, we write a text file that specifies the +notation. For example, if we write @example -a1 a2 a4 a16 a32 +@{ + c' e' g' e' +@} @end example -@lilypond[notime] -\property Score.timing = ##f -\property Staff.autoBeaming = ##f -\transpose c c' { a1 a2 a4 a16 a32 s16_" " } +@noindent +the result looks like this + +@lilypond[quote,ragged-right] +{ + c' e' g' e' +} @end lilypond -If you do not specify a @rglos{duration}, the previous one is used: +@strong{Warning:} Every piece of LilyPond input needs to have @strong{@{ curly +braces @}} placed around the input. The braces should be also be +surrounded by a space unless they are at the beginning or end of a +line to avoid ambiguities. These may be omitted in some examples in this +manual, but don't forget them in your own music! -@example -a4 a a2 a -@end example +@cindex Case sensitive +In addition, LilyPond input is @strong{case sensitive}. @code{ @{ c d e @} } +is valid input; @code{ @{ C D E @} } will produce an error message. -@lilypond[notime] -\property Score.timing = ##f -\transpose c c' { a a a2 a s16_" " } -@end lilypond +@sp 1 +@subheading Entering music and viewing output -Rests are entered just like notes, but with the name ``@code{r}'': +In this section we will explain what commands to run +and how to view or print the output. -@cindex rests -@quotation -@example -r2 r4 r8 r16 -@end example +@subsubheading MacOS X -@lilypond[fragment] -\property Score.timing = ##f -\property Staff.Clef = \turnOff -\property Staff.TimeSignature = \turnOff -r2 r4 r8 r16 -s16_" " -@end lilypond -@end quotation -@separate +If you double click LilyPond.app, it will open with an example +file. Save it, for example, to @file{test.ly} on your Desktop, and +then process it with the menu command @samp{Compile > Typeset File}. +The resulting PDF file will be displayed on your screen. +Be warned that the first time you ever run lilypond will take a minute +or two because all of the system fonts have to be analyzed first. -Add a dot @samp{.} after the duration to get a @rglos{dotted note}: +For future use of LilyPond, you should begin by selecting "New" +or "Open". -@example -a2. a4 a8. a16 -@end example +@subsubheading Windows -@lilypond[notime] -\property Score.timing = ##f -\transpose c c' { a2. a4 a8. a16 s16_" " } -@end lilypond +On Windows, start up a text-editor@footnote{Any simple or +programmer-oriented editor with UTF-8 support will do, for example +Notepad. Do not use a word processor, since these insert formatting +codes that will confuse LilyPond.} and enter +@verbatim +{ + c' e' g' e' +} +@end verbatim -The @rglos{meter} (or @rglos{time signature}) can be set with the -@code{\time} command: +Save it on the desktop as @file{test.ly} and make sure that it is not +called @file{test.ly.TXT}. Double clicking @file{test.ly} will process +the file and show the resulting PDF file. -@example -\time 3/4 -\time 6/8 -\time 4/4 -@end example -@c a clef here may lead to confusion -@lilypond -\property Staff.Clef \set #'transparent = ##t -\time 3/4 -s4_" " -\time 6/8 -s4_" " -\time 4/4 -s16_" " -@end lilypond +@subsubheading Unix +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 they have not been +installed already, refer to the file @file{INSTALL.txt}. These +easiest editing environment is @file{LilyPondTool}. See +@ref{Editor support} for more information.}. In your +text editor, enter the following input and save the file as +@file{test.ly} + +@verbatim +{ + c' e' g' e' +} +@end verbatim -The @rglos{clef} can be set using the @code{\clef} command: +@noindent +To process @file{test.ly}, proceed as follows -@c what is more common name treble or violin? -@c in Dutch, its violin. -@c in English its definitely treble. @example -\clef treble -\clef bass -\clef alto -\clef tenor +lilypond test.ly @end example -@lilypond[notime] -\property Score.timing = ##f -\clef violin -s4_" " -\clef bass -s4_" " -\clef alto -s4_" " -\clef tenor -s16_" " -@end lilypond - -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: +@noindent +You will see something resembling @example -\notes @{ - \time 3/4 - \clef bass - c2 e4 g2. - f4 e d c2 r4 -@} +lilypond test.ly +GNU LilyPond 2.10.0 +Processing `test.ly' +Parsing... +Interpreting music... [1] +Preprocessing graphical objects... +Calculating line breaks... [2] +Layout output to `test.ps'... +Converting to `test.pdf'... @end example -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. The -@code{\paper} block is used to customize printing specifics, but we -accept the defaults for now. The music and the @code{\paper} block -are combined by enclosing them in @code{\score @{ ... @}}. The -following is a complete and valid input file. +@cindex PDF file +@cindex Viewing music + +@noindent +The result is the file @file{test.pdf} which you can print or view +with the standard facilities of your operating system.@footnote{If +your system does not have any tools installed, you can try +@uref{http://@/www@/.cs@/.wisc@/.edu/@/~ghost/,Ghostscript}, a freely +available package for viewing and printing PDF and PostScript files.} -@example -\score @{ - \notes @{ - \time 3/4 - \clef bass - c2 e4 g2. - f4 e d c2 r4 - @} - \paper @{ @} -@} -@end example -@lilypond[noindent] -\score { - \notes { - \time 3/4 - \clef bass - c2 e4 g2. - f4 e d c2 r4 - } - \paper { - linewidth = 55 * \staffspace - } +@node Simple notation +@subsection Simple notation + +LilyPond will add some notation elements automatically. In the next +example, we have only specified four pitches, but LilyPond has +added a clef, time signature, and rhythms. + +@lilypond[quote,ragged-right,verbatim] +{ + c' e' g' e' } @end lilypond -During 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. +@noindent +This behavior may be altered, but in most cases these automatic values +are useful. -More elaborate information on entering pitches and durations is in -@ref{Pitches} and @ref{Durations}. Clefs are fully explained in -@ref{Clef}. Time signatures and other timing commands are described -in @ref{Time signature}. +@subheading Pitches -@node Running LilyPond -@section Running LilyPond +The easiest way to enter notes is by using @code{\relative} mode. In +this mode, the @rglos{interval} between the previous note and the +current note is assumed to be within a @rglos{fourth}. We begin by +entering the most elementary piece of music, a @rglos{scale}. -In the last section we explained what kind of things you could enter -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. +@lilypond[quote,ragged-right,verbatim] +\relative c' { + c d e f + g a b c +} +@end lilypond -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}: +The initial note is @rglos{middle C}. Each successive note +is within a fourth of the previous note -- in other words, the first +@samp{c} is the closest C to middle C. This is followed by the closest +D to the previous note. We can create melodies which have larger intervals: -@quotation -@example -\score @{ - \notes @{ c'4 e' g' @} -@} -@end example -@end quotation +@lilypond[quote,ragged-right,verbatim] +\relative c' { + d f a g + c b f d +} +@end lilypond -@cindex ly2dvi +@noindent +As you may notice, this example does not start on middle C. The first +note -- the @samp{d} -- is the closest D to middle C. -@c now this is weird, running ly2dvi to run LilyPond -@c (therefore name change proposal) +To add intervals that are larger than a fourth, we can raise the octave +by adding a single quote @code{'} (or apostrophe) to the note name. We can +lower the octave by adding a comma @code{,} to the note name. -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: +@lilypond[quote,ragged-right,verbatim] +\relative c'' { + a a, c' f, + g g'' a,, f' +} +@end lilypond -@quotation -@example -ly2dvi -p test.ly -@end example -@end quotation +@noindent +To change a note by two (or more!) octaves, we use multiple @code{''} or +@code{,,} -- but be careful that you use two single quotes @code{''} and +not one double quote @code{"}@tie{}! The initial value in +@code{\relative c'} may also be modified like this. -You will see something resembling: -@quotation -@example -GNU LilyPond 1.8.0 -Now processing: `/home/fred/ly/test.ly' -Parsing... -Interpreting music...[1] - @emph{ ... more interesting stuff ... } -PDF output to `test.pdf'... -DVI output to `test.dvi'... -@end example -@end quotation -@cindex DVI file -@cindex Viewing music -@cindex xdvi - -The result of the ly2dvi 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.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 your viewing program. +@subheading Durations (rhythms) -@cindex Ghostscript -@cindex @code{lpr} -@cindex Printing output -@cindex PostScript -@cindex PDF +The @rglos{duration} of a note is specified by a number after the note +name. @samp{1} for a @rglos{whole note}, @samp{2} for a @rglos{half note}, +@samp{4} for a @rglos{quarter note} and so on. Beams are added +automatically. +@lilypond[quote,ragged-right,verbatim] +\relative c'' { + a1 + a2 a4 a8 a + a16 a a a a32 a a a a64 a a a a a a a a2 +} +@end lilypond -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. +@noindent +If you do not specify a duration, the previous duration is used +for the next note. The duration of the first note defaults to a quarter. -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 also try the list of commands -shown before. If none work, go to -@uref{http://www.cs.wisc.edu/~ghost/} to install the proper software. -@end itemize +To create @rglos{dotted notes}, add a dot @samp{.} to the duration number. -The commands for formatting and printing music on all platforms are -detailed in @ref{Invoking LilyPond}. +@lilypond[quote,ragged-right,verbatim] +\relative c'' { + a a a4. a8 + a8. a16 a a8. a8 a4. +} +@end lilypond -@node More about pitches and accidentals -@section More about pitches and accidentals -A @rglos{sharp} (@texisharp{}) is made by adding @samp{is}, a -@rglos{flat} (@texiflat{}) 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.} +@subheading Rests -@example -cis1 ees fisis aeses -@end example +A @rglos{rest} is entered just like a note with the name @samp{r}: -@lilypond[notime] -\property Score.timing = ##f -\transpose c c' { cis1 ees fisis aeses s16_" " } +@lilypond[quote,ragged-right,verbatim] +\relative c'' { + a r r2 + r8 a r4 r4. r8 +} @end lilypond - -@cindex key signature, setting -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 +@subheading Time signature -@lilypond[fragment] -\property Staff.TimeSignature = \turnOff -\key d \major -g'1 -\key c \minor -g' +The @rglos{time signature}) can be set with the @code{\time} command: + +@lilypond[quote,ragged-right,verbatim] +\relative c'' { + \time 3/4 + a4 a a + \time 6/8 + a4. a + \time 4/4 + a4 a a a +} @end lilypond -@end quotation -@cindex tie -A tie is created by adding a tilde ``@code{~}'' to the first note -being tied: -@quotation -@lilypond[fragment,verbatim,relative 2] -g4-~ g a2-~ a4 +@subheading Clef + +The @rglos{clef} can be set using the @code{\clef} command: + +@lilypond[quote,ragged-right,verbatim] +\relative c' { + \clef treble + c1 + \clef alto + c1 + \clef tenor + c1 + \clef bass + c1 +} @end lilypond -@end quotation -@separate -This example shows the key signature, accidentals and ties in action: -@quotation -@example -\score @{ - \notes @{ - \time 4/4 - \key g \minor - \clef violin - r4 r8 a8 gis4 b - g8 d4.-~ d' e'8 - fis4 fis8 fis8 eis4 a8 gis-~ - gis2 r2 - @} - \paper @{ @} -@} -@end example +@subheading All together -@lilypond -\score { - \notes { \transpose c c' { - \time 4/4 - \key g \minor - \clef violin - r4 r8 a8 gis4 b - g8 d4.-~ d e8 - fis4 fis8 fis8 eis4 a8 gis-~ - gis2 r2 - }} - \paper { linewidth = #(* 50 staffspace) } +Here is a small example showing all these elements together: + +@lilypond[quote,ragged-right,verbatim] +\relative c, { + \time 3/4 + \clef bass + c2 e8 c' g'2. + f4 e d c4 c, r4 } @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. - -Accidentals (sharps and flats) do not have to be marked explicitly: -you just enter the pitch of the note, and an accidental is printed -only when necessary. The flip side of this mechanism, is that you have -to mark notes as sharp or flat, even when they do not get accidentals. -For example, in this example: -@lilypond[fragment] -\clef bass -\property Staff.TimeSignature = #'() -\key cis \major -cis dis eis fis gis ais bis -@end lilypond -no note gets an explicit accidental, but still you enter -@example -\clef bass -\key cis \major -cis dis eis fis gis ais bis -@end example - -Adding all alterations explicitly might require some more effort when -typing, but the advantage is that transposing is easier. It also makes -it possible to use different conventions for when to print -accidentals. -@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{]}: +@moreinfo @quotation -@lilypond[fragment,relative 1, verbatim] -a8[ ais] d[ es r d] -@end lilypond +@table @asis +@item Entering pitches and durations +see @ref{Pitches} and @ref{Durations}. +@item Rests +see @ref{Rests}. +@item Time signatures and other timing commands +see @ref{Time signature}. +@item Clefs +see @ref{Clef}. +@end table @end quotation -@separate - -Rests are described in full detail in @ref{Rests}. -The notation manual discusses ties in @ref{Ties}. +@node Working on text files +@subsection Working on text files -@node Octave entry -@section Octave entry +LilyPond input files are treated like files in most programming languages: +they are case sensitive, white-space insensitive, expressions are +formed with curly braces @{ @}, and comments are denoted with @code{%} or +@code{%@{ .. %@}}. +If the previous sentence sounds like nonsense, don't worry! We'll explain +what all these terms mean: -@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... +@itemize -@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'}: +@cindex Case sensitive +@item @strong{Case sensitive}: +it matters whether you enter a letter +in lower case (i.e. @code{a, b, s, t}) or upper case (i.e. +@code{A, B, S, T}). Notes are lower case: @code{ @{ c d e @} } +is valid input; @code{ @{ C D E @} } will produce an error message. + +@item @strong{Whitespace insensitive}: +it does not matter how many +spaces (or new lines) you add. @code{ @{ c d e @}} means the same thing +as @code{ @{ c @ @ @ @ @ d e @} } and +@example + @{ +c d + e @} +@end example -@quotation +@noindent +Of course, the previous example is hard to read. A good rule of thumb +is to indent code blocks with either a tab or two spaces: @example -c'4 c'' c''' \clef bass c c, +@{ + c d e +@} @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 +@item @strong{Expressions:} +Every piece of LilyPond input needs to have +@strong{@{ curly braces @}} placed around the input. These braces tell +LilyPond that the input is a single music expression, just like +parenthesis @samp{()} in mathematics. The braces should +be surrounded by a space unless they are at the beginning or end of a +line to avoid ambiguities. -An example of the use of quotes is in the following Mozart fragment: -@lilypond[singleline,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 ' or , 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: +A function (such as @code{\relative @{ @}} ) also counts as a single +music expression. + +@cindex comments +@cindex line comment +@cindex block comment +@item @strong{Comments}: +A comment is a remark for the human reader of the music input; it is +ignored while parsing, so it has no effect on the printed output. +There are two types of comments. The percent symbol @samp{%} +introduces a line comment; anything after @samp{%} on that line is +ignored. A block comment marks a whole section of music +input as a comment. Anything that is enclosed in @code{%@{} and @code{%@}} is +ignored. The following fragment shows possible uses for comments -@quotation @example -\relative c'' @{ - c f c g c -@} +% notes for twinkle twinkle follow + c4 c g' g a a g2 + +%@{ + This line, and the notes below + are ignored, since they are in a + block comment. + + g g f f e e d d c2 +%@} @end example -@lilypond[fragment] -\property Score.timing = ##f -\property Staff.TimeSignature = \turnOff -\relative c'' { - c f c g c -} -@end lilypond -@end quotation -@separate +@end itemize +There are more tips for constructing input files in +@ref{Suggestions for writing LilyPond files}. -Since most music has small intervals, in relative mode pieces can be -written almost without using octavation quotes. In relative mode, the -Mozart example is entered as -@c -@lilypond[singleline,fragment,verbatim] -\relative c'' { - \key a \major - \time 6/8 - cis8. d16 cis8 e4 e8 - b8. cis16 b8 d4 d8 -} -@end lilypond +@node How to read the tutorial +@subsection How to read the tutorial -@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. -Larger intervals are made by adding octavation quotes. 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: +As we saw in @ref{Working on text files}, LilyPond input must be +surrounded by @{ @} marks or a @code{\relative c'' @{ ... @}}. For the +rest of this manual, most examples will omit this. + +If you are reading the HTML documentation and wish to see the exact +exact LilyPond code that was used to create the example, simply click +on the picture. If you are not reading the HTML version, you could +copy and paste the displayed input, but you @strong{must} add the +@code{\relative c'' @{ @}} like this: -@quotation @example \relative c'' @{ - c f, f c' c g' c, + ... example goes here... @} @end example -@lilypond[fragment] -\property Score.timing = ##f -\property Staff.TimeSignature = \turnOff -\relative c'' { - c f, f c' c g' c, -} +Why omit the braces? Most examples +in this manual can be inserted into the middle of a longer piece of +music. For these examples, it does not make sense to add +@code{\relative c'' @{ @}} -- you should not place a @code{\relative} +inside another @code{\relative}, so you would not be able to copy +a small documentation example and paste it inside a longer piece +of your own. + + +@node Single staff notation +@section Single staff notation + +This section introduces common notation that is used for one voice +on one staff. + +@menu +* Relative note names:: +* Accidentals and key signatures:: +* Ties and slurs:: +* Articulation and dynamics:: +* Automatic and manual beams:: +* Advanced rhythmic commands:: +@end menu + + +@node Relative note names +@subsection Relative note names + +As we saw in @ref{Simple notation}, LilyPond calculates the pitch of +each note relative to the previous one@footnote{There is another mode of +entering pitches, @ref{Absolute note names}, but in practice relative +mode is much easier and safer to use.}. If no extra octave marks +(@code{'} and @code{,}) are added, it assumes that each pitch is within +a fourth of the previous note. + +LilyPond examines pitches based on the note names -- in other words, +an augmented fourth is @emph{not} the same as a diminished fifth. If we +begin at a C, then an F-sharp will be placed a higher than the C, while +a G-flat will be placed lower than the C. + +@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +c2 fis +c2 ges @end lilypond + +@moreinfo +@quotation +@table @asis +@item Relative octaves +see @ref{Relative octaves}. +@item Octave check +see @ref{Octave check}. +@end table @end quotation -@separate -Here is an example of the difference between relative mode and -``normal'' (non-relative) mode: -@quotation -@example -\relative a @{ -\clef bass - a d a e d c' d' -@} -@end example +@node Accidentals and key signatures +@subsection Accidentals and key signatures -@lilypond[fragment] -\property Score.timing = ##f -\property Staff.TimeSignature = \turnOff -\relative a { -\clef bass - a d a e d c' d' -} +@subheading Accidentals + +A @rglos{sharp} pitch is made by adding @samp{is} to +the name, and a @rglos{flat} 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. To use other names for accidentals, see +@ref{Note names in other languages}.} + +@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +cis1 ees fisis, aeses @end lilypond -@end quotation -@separate -@quotation -@example -\clef bass - a d a e d c' d' -@end example +@cindex key signature, setting +@subheading Key signatures + +The key signature is set with the command @code{\key} followed by +a pitch and @code{\major} or @code{\minor}. -@lilypond[fragment] -\property Score.timing = ##f -\property Staff.TimeSignature = \turnOff -\clef bass - a d a e d c' d' +@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +\key d \major +a1 +\key c \minor +a @end lilypond -@end quotation -@separate +@sp 1 +@subheading Warning: key signatures and pitches +To determine whether to print an accidental, LilyPond examines the +pitches and the key signature. The key signature only effects +the @emph{printed} accidentals, not the actual pitches! This is a +feature that often causes confusion to newcomers, so let us explain it +in more detail. +LilyPond makes 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 +@emph{printed} flat, natural or sharp sign) is 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. +In this example +@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +\key d \major +d cis fis +@end lilypond +@noindent +No note has a printed accidental, but you must still add the @samp{is} to +@code{cis} and @code{fis}. +The code @samp{e} does not mean @qq{print a black dot just below the +first line of the staff.} Rather, it means: @qq{there is a note with +pitch E-natural.} In the key of A-flat major, it @emph{does} get an +accidental: -@node Combining music into compound expressions -@section Combining music into compound expressions +@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +\key aes \major +e +@end lilypond -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: +Adding all alterations explicitly might require a little more effort +when typing, but the advantage is that transposing is easier, and +accidentals can be printed according to different conventions. See +@ref{Automatic accidentals} for some examples how accidentals can be printed +according to different rules. +@moreinfo @quotation -@lilypond[fragment,verbatim] -\simultaneous { - \context Staff = staffA { \clef violin c'' } - \context Staff = staffB { \clef bass c } -} -@end lilypond +@table @asis +@item Accidentals +see @ref{Accidentals} and @ref{Automatic accidentals}. +@item Key signature +see @ref{Key signature}. +@end table @end quotation -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 @{ .. @}}. - -@code{\context} introduces a ``notation context''. To understand this -concept, imagine that you are performing a piece of music. When you -perform the music, 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{\context} to a chunk of music -indicates what kind of context to use for interpreting it. - -By specifying different names (in this case @code{staffA} and -@code{staffB}), two different contexts are created, leading to two -staves. It does not matter which names they are given, as long as they -are different. If they get the same name, the chunks of music are -assumed to belong on the same staff, and will be printed like that. - -@separate - -We can now typeset a melody with two staves: +@node Ties and slurs +@subsection Ties and slurs -@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 {} -} +@cindex ties +@subheading Ties +A @rglos{tie} is created by appending a tilde @samp{~} to the first +note being tied + +@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +g4~ g c2~ +c4 ~ c8 a8 ~ a2 @end lilypond -@end quotation -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{\context Staff} to it, and that chunk is -combined with @code{< >}. This mechanism is similar with mathematical -formulas: in a formula, a so-called expression is formed by combining -simpler expressions into larger expressions. For example, +@cindex slurs +@subheading Slurs -@quotation - 1 +A @rglos{slur} is a curve drawn across many notes. The starting note +and ending note are marked with @samp{(} and @samp{)} respectively. - 1 + 2 - - (1 + 2) * 3 - - ((1 + 2) * 3) / (4 * 5) -@end quotation -@cindex expression -@cindex music expression -is 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{\context} -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 +@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +d4( c16) cis( d e c cis d) e( d4) +@end lilypond +@cindex slurs, phrasing +@cindex phrasing slurs +@subheading Phrasing slurs -@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 +@cindex phrasing slurs +Slurs to indicate longer phrasing can be entered with @code{\(} and +@code{\)}. You can have both legato slurs and phrasing slurs at the +same time, but you cannot have simultaneous slurs or simultaneous +phrasing slurs. + +@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +a8(\( ais b c) cis2 b'2 a4 cis,\) +@end lilypond + +@sp 1 +@cindex slurs versus ties +@subheading Warnings: slurs vs. ties + +A slur looks like a @rglos{tie}, but it has a different meaning. A +tie simply makes the first note 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 +can be nested. + +@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +c2~( c8 fis fis4 ~ fis2 g2) +@end lilypond +@moreinfo +@quotation +@table @asis +@item Ties +see @ref{Ties}. +@item Slurs +see @ref{Slurs}. +@item Phrasing slurs +see @ref{Phrasing slurs}. +@end table +@end quotation -@node Adding articulation marks to notes -@section Adding articulation marks to notes +@node Articulation and dynamics +@subsection Articulation and dynamics @cindex articulation @cindex accents @cindex staccato +@subheading Articulations -Common accents can be added to a note using a dash (`@code{-}') and a -single character: -@quotation -@lilypond[verbatim,relative 1] +Common @rglos{articulations} can be added to a note using a dash @samp{-} +and a single character: + +@lilypond[quote,ragged-right,verbatim,fragment,relative=2] c-. c-- c-> c-^ c-+ c-_ @end lilypond -@end quotation -@separate @cindex fingering +@subheading Fingerings 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 +(@samp{-}) and the digit to be printed: + +@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +c-3 e-5 b-2 a-1 @end lilypond +Articulations and fingerings are usually placed automatically, but you +can specify a direction using @samp{^} (up) or @samp{_} (down). You can +also use multiple articulations on the same note. However, in most cases +it is best to let LilyPond determine the articulation directions. -Dynamic signs are made by adding the markings to the note: -@quotation -@lilypond[verbatim,relative 1] -c-\ff c-\mf +@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +c_-^1 d^. f^4_2-> e^-_+ +@end lilypond + +@subheading Dynamics +Dynamic signs are made by adding the markings (with a backslash) to +the note + +@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +c\ff c\mf c\p c\pp @end lilypond -@end quotation -@separate @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 -@lilypond[verbatim,relative 1] -c2-\< c2-\!-\ff c2-\> c2-\! -@end lilypond -@end quotation -@separate - - +@code{\>}. An ending dynamic, for example @code{\f}, will finish the +(de)crescendo, or the command @code{\!} can be used -@cindex slur - -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 -@cindex slurs versus ties -A slur is different from a tie. 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: -@lilypond[fragment, relative=1] -c2-~( c8 fis fis4 ~ fis2 g2) +@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +c2\< c2\ff\> c2 c2\! @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{\)}. - +@moreinfo @quotation -@lilypond[fragment,relative 1, verbatim] -a8(-\( ais b c) cis2 b'2 a4 cis, c-\) -@end lilypond +@table @asis +@item Articulations +see @ref{Articulations}. +@item Fingering +see @ref{Fingering instructions}. +@item Dynamics +see @ref{Dynamics}. +@end table @end quotation -More information on fingering, articulation, slurs, phrasing slurs, -and dynamics can be found in @ref{Fingering instructions}, -@ref{Articulations}, @ref{Slurs}, @ref{Phrasing slurs}, and @ref{Dynamics}, -respectively. +@node Automatic and manual beams +@subsection Automatic and manual beams -@node Combining notes into chords -@section Combining notes into chords +@cindex beams, by hand +All @rglos{beam}s are drawn automatically: -@cindex chords -Chords can be made by -surrounding pitches with @code{<<} and @code{>}>: -@quotation -@lilypond[relative 0, fragment,verbatim] -r4 <>4 <>8 +@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +a8 ais d ees r d c16 b a8 @end lilypond -@end quotation -@separate +@noindent +If you do not like the automatic beams, they may be overridden +manually. Mark the first note to be beamed with @samp{[} and the last one +with @samp{]}. -You can combine beams and ties with chords. Beam and tie markings -must be placed outside the chord markers: -@quotation -@lilypond[relative 0, fragment,verbatim] -r4 <>8[ <>]-~ <> +@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +a8[ ais] d[ ees r d] a b @end lilypond -@end quotation +@moreinfo @quotation -@example -r4 <>8-\>( <> <> <>8-\!) -@end example -@lilypond[relative 0, fragment] -\slurUp -r4 <>8-\>( <> <> <>8-\!) -@end lilypond +@table @asis +@item Automatic beams +see @ref{Automatic beams}. +@item Manual beams +see @ref{Manual beams}. +@end table @end quotation -@separate - -@menu -* Basic rhythmical commands:: -* Commenting input files:: -@end menu - -@node Basic rhythmical commands -@subsection Basic rhythmical commands +@node Advanced rhythmic commands +@subsection Advanced rhythmic commands @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 +@subheading Partial measure + +A pickup (or @rglos{anacrusis}) is entered with the keyword +@code{\partial}. It is followed by a duration: @code{\partial 4} is +a quarter note pickup and @code{\partial 8} an eighth note. + +@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +\partial 8 +f8 c2 d @end lilypond @cindex tuplets @cindex triplets +@subheading Tuplets + 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 0,verbatim,fragment] - \times 2/3 { f8 g a } - \times 2/3 { c r c } -@end lilypond +2/3 of their notated duration, so a triplet has 2/3 as its fraction + +@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +\times 2/3 { f8 g a } +\times 2/3 { c r c } +\times 2/3 { f,8 g16 a g a } +\times 2/3 { d4 a8 } +@end lilypond @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 keyword is @code{\grace}: -@lilypond[relative 1, verbatim,fragment] - c4 \grace b16( c4) - \grace { d16( e } d4) +@cindex acciaccatura +@cindex appoggiatura +@subheading Grace notes + +Grace notes are created with the @code{\grace} command, although they +can also be created by prefixing a music expression with the +keyword @code{\appoggiatura} or @code{\acciaccatura} + +@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +c2 \grace { a32 b} c2 +c2 \appoggiatura b16 c2 +c2 \acciaccatura b16 c2 @end lilypond -@noindent -More information on grace notes, tuplets and upsteps are in @ref{Grace -notes}, @ref{Tuplets} and @ref{Partial measures}. +@moreinfo +@quotation +@table @asis +@item Grace notes +see @ref{Grace notes}, +@item Tuplets +see @ref{Tuplets}, +@item Pickups +see @ref{Partial measures}. +@end table +@end quotation +@node Multiple notes at once +@section Multiple notes at once -@node Commenting input files -@subsection Commenting input files +This section introduces having more than one note at the same time: +multiple instruments, multiple staves for a single instrument (i.e. piano), +and chords. -@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: +Polyphony in music refers to having more than one voice occurring in +a piece of music. Polyphony in LilyPond refers to having more than +one voice on the same staff. -@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. +@menu +* Music expressions explained:: +* Multiple staves:: +* Piano staves:: +* Single staff polyphony:: +* Combining notes into chords:: +@end menu - g g f f e e d d c2 - %@} -@end example +@node Music expressions explained +@subsection Music expressions explained +In LilyPond input files, music is represented by @emph{music +expressions}. A single note is a music expression, although it is not +valid input all on its own. +@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +a4 +@end lilypond -@node Printing lyrics -@section Printing lyrics -@cindex lyrics +Enclosing a group of notes in braces creates a new music expression: -@cindex Lyrics -@cindex Songs -Lyrics are entered by separating each syllable with a space, and -surrounding them with @code{\lyrics @{ @dots{} @}}, for example, -@example - \lyrics @{ I want to break free @} -@end example +@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +{ a4 g4 } +@end lilypond -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{ \context Lyrics}: -@example - \context Lyrics \lyrics @{ I want to break free @} -@end example -The melody for this song is as follows: +Putting a group of music expressions (e.g. notes) in braces means that +are in sequence (i.e. each one follows the previous one). The result +is another music expression: -@lilypond[fragment,relative=1] - \partial 8 - c8 - \times 2/3 { f4 g g } \times 2/3 { g4( a2) } +@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +{ { a4 g } f g } @end lilypond -The lyrics can be set to these notes, combining both with the -@code{\addlyrics} keyword: -@example - \addlyrics - \notes @{ @dots{} @} - \context Lyrics @dots{} -@end example +@subheading Simultaneous music expressions: multiple staves -The final result is -@lilypond[verbatim,linewidth=6.0cm] -\score { - \notes { - \addlyrics - \relative c' { - \partial 8 - c8 - \times 2/3 { f g g } \times 2/3 { g4( a2) } - } - \context Lyrics \lyrics { I want to break free } - } - \paper{ } +This technique is useful for polyphonic music. To enter music +with more voices or more staves, we combine expressions in +parallel. To indicate that two voices should play at the same time +simple enter a simultaneous combination of music expressions. A +@q{simultaneous} music expression is formed by enclosing expressions inside +@code{<<} and @code{>>}. In the following example, three sequences (all +containing two separate notes) are combined simultaneously: + +@lilypond[quote,ragged-right,verbatim] +\relative c'' { + << + { a4 g } + { f e } + { d b } + >> } @end lilypond -@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 a @emph{extender -line}. It is entered as two underscores, i.e. -@example - \lyrics @{ I want to break free __ @} -@end example -@lilypond[] -\score { - \notes { - \addlyrics - \relative c' { - \partial 8 - c8 - \times 2/3 { f g g } \times 2/3 { g4( a2) } - - %% ugh, this is to deal with bugs in the extender implementation - \hideNotes - c32 - } - \context Lyrics \lyrics { I want to break free __ } - } - \paper{ linewidth = 9.0 \cm } +Note that we have indented each level of the input with a different +amount of space. LilyPond does not care how much (or little) space there +is at the beginning of a line, but indenting LilyPond code like this makes +it much easier for humans to read. + +@subheading Simultaneous music expressions: single staff + +To determine the number of staves in a piece, LilyPond looks at the first +exression. If it is a single note, there is one staff; if there is a +simultaneous expression, there is more than one staff. + +@lilypond[quote,ragged-right,verbatim] +\relative c'' { + c2 <> + << { e f } { c <> } >> } @end lilypond -Similarly, hyphens between words can be entered as two dashes, -resulting in a centered hyphen between two syllables: +@cindex expression +@cindex music expression +@subheading Analogy: mathematical expressions + +This mechanism is similar to 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, + @example - Twin -- kle twin -- kle +1 + +1 + 2 + +(1 + 2) * 3 + +((1 + 2) * 3) / (4 * 5) @end example -@lilypond[singleline] -\score { - \addlyrics \notes \relative f' { \time 2/4 - f4 f c' c' } - \context Lyrics \lyrics { Twin -- kle twin -- kle - } -\paper { linewidth = 6.0 \cm } - } - -@end lilypond -More options, like putting multiple lines of lyrics below a melody are -discussed in @ref{Vocal music}. +This is a sequence of expressions, where each expression is contained +in the next (larger) one. The simplest expressions are numbers, and larger +ones are made by combining expressions with operators (like @samp{+}, +@samp{*} and @samp{/}) and parentheses. Like mathematical expressions, +music expressions can be nested arbitrarily deep, which is necessary +for complex music like polyphonic scores. +@node Multiple staves +@subsection Multiple staves -@node A lead sheet -@section A lead sheet +As we saw in @ref{Music expressions explained}, LilyPond input files +are constructed out of music expressions. If the score begins with +simultaneous music expressions, LilyPond creates multiples staves. However, +it is easier to see what happens if we create each staff explicitly. -@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{\context -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 +To print more than one staff, each piece of music that makes up a +staff is marked by adding @code{\new Staff} before it. These +@code{Staff} elements are then combined in parallel with @code{<<} and +@code{>>}: -@noindent -The result of @code{\chords} is a list of chords, and is equivalent -to entering chords with @code{<<@dots{}>>}. - -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 } +@lilypond[quote,ragged-right,verbatim] +\relative c'' { + << + \new Staff { \clef treble c } + \new Staff { \clef bass c,, } + >> +} @end lilypond -Printing chords is done by adding @code{\context ChordNames} -before the chords thus entered: -@c -@lilypond[verbatim] - \context ChordNames \chords \chords { c2 f4.:m g4.:maj7 gis8:dim7 } -@end lilypond +The command @code{\new} introduces a @q{notation context.} A notation +context is an environment in which musical events (like notes or +@code{\clef} commands) are interpreted. For simple pieces, such +notation contexts are created automatically. For more complex pieces, it +is best to mark contexts explicitly. -@cindex lead sheet -When put together, chord names, lyrics and a melody form -a lead sheet, for example, +There are several types of contexts. @code{Score}, @code{Staff}, +and @code{Voice} handle melodic notation, while @code{Lyrics} sets lyric +texts and @code{ChordNames} prints chord names. -@example -\score @{ - < - \context ChordNames \chords @{ @emph{chords} @} - \addlyrics - \notes @emph{the melody} - \context Lyrics \lyrics @{ @emph{the text} @} - > - \paper @{ @} -@} -@end example -@lilypond[] -\score { - < - \context ChordNames \chords { r8 c2:sus4 f } - \addlyrics - \notes \relative c' { - \partial 8 - c8 - \times 2/3 { f g g } \times 2/3 { g4( a2) } } - \context Lyrics \lyrics { I want to break free __ } - > - \paper{ raggedright = ##t } +In terms of syntax, prepending @code{\new} to a music expression +creates a bigger music expression. In this way it resembles the minus +sign in mathematics. The formula @math{(4+5)} is an expression, so +@math{-(4+5)} is a bigger expression. + +Time signatures entered in one staff affects all other staves, but +the key signature of one staff does @emph{not} affect other +staves@footnote{This behavior may be changed if desired; see +@ref{Changing defaults} for details.}. + +@lilypond[quote,ragged-right,verbatim] +\relative c'' { + << + \new Staff { \clef treble \time 3/4 c } + \new Staff { \clef bass \key d \major c,, } + >> } @end lilypond -A complete list of modifiers, and other options for layout are in the -reference manual section @ref{Chords}. -@node Listening to output -@section Listening to output -@cindex sound -@cindex MIDI +@node Piano staves +@subsection Piano staves -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. +@cindex staff switch, manual +@cindex cross staff voice, manual +Piano music is typeset in two staves connected by a brace. Printing +such a staff is similar to the polyphonic example in @ref{Multiple staves}, +but now this entire expression is inserted inside a @code{PianoStaff}: -@code{\midi} can be used in similarly to @code{\paper @{ @}}, for -example, -@example -\score @{ - @var{..music..} - \midi @{ \tempo 4=72 @} - \paper @{ @} -@} -@end example - -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. - - - -@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 assignment, within @code{\header @{ @dots{} @}}. For -example, -@example - \header @{ - title = "Eight miniatures" - composer = "Igor Stravinsky" - tagline = "small is beautiful" - @} - - \score @{ @dots{} @} +@example +\new PianoStaff << + \new Staff @dots{} + \new Staff @dots{} +>> @end example -@cindex bibliographic information -@cindex titles -@cindex composer -@cindex ly2dvi - - -When the file is processed by @code{ly2dvi}, 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 ``Lily was -here, version @dots{}''. In the example above, it is replaced by the -line ``small is beautiful''. - -Normally, the @code{\header} is put at the top of the file. However, -for a document that contains multiple pieces (e.g. a etude book, or -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: - - -@cindex Lily was here -@cindex signature line -@cindex tag line - -@example - \header @{ - title = "Eight miniatures" - composer = "Igor Stravinsky" - tagline = "small is beautiful" - @} - - \score @{ @dots{} - \header @{ piece = "Adagio" @} - @} - \score @{ @dots{} - \header @{ piece = "Menuetto" @} - @} -@end example +Here is a small example + +@lilypond[quote,ragged-right,verbatim] +\relative c'' { + \new PianoStaff << + \new Staff { \time 2/4 c4 e g g, } + \new Staff { \clef bass c,, c' e c } + >> +} +@end lilypond -More information on titling can be found in @ref{Invoking ly2dvi}. +@moreinfo +@quotation +See @ref{Piano music}. +@end quotation @node Single staff polyphony -@section Single staff polyphony +@subsection 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 stems down. +When different melodic lines are combined on a single staff they 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 - < @{ a4 g2 f4-~ f4 @} \\ - @{ r4 g4 f2 f4 @} > -@end example -@lilypond[relative 1] -\context Staff < { a4 g2 f4-~ f4 } \\ - { r4 g4 f2 f4 } > +@code{@{...@}}) and combining these simultaneously, separating the +voices with @code{\\} + +@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +<< + { a4 g2 f4~ f4 } \\ + { r4 g4 f2 f4 } +>> @end lilypond -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 - < @{ 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 +For polyphonic music typesetting, spacer rests can also be convenient; +these are rests that do not print. They are useful for filling up +voices that temporarily do not play. Here is the same example with a +spacer rest (@samp{s}) instead of a normal rest (@samp{r}), -Again, these expressions can be nested arbitrarily: - -@lilypond[fragment] -< - \context Staff = staffA - \relative c'' - < { a4 g2 f4-~ f4 } \\ - { s4 g4 f2 f4 } > - \context Staff = staffB - < { \clef bass <>1 } \\ - { f4 d e2 } - > -> +@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +<< + { a4 g2 f4~ f4 } \\ + { s4 g4 f2 f4 } +>> @end lilypond +@noindent +Again, these expressions can be nested arbitrarily. + +@lilypond[quote,fragment,verbatim,relative=2,fragment] +<< + \new Staff << + { a4 g2 f4~ f4 } \\ + { s4 g4 f2 f4 } + >> + \new Staff << + \clef bass + { 1 ~ 4 } \\ + { e,,4 d e2 ~ e4} + >> +>> +@end lilypond -More features of polyphonic typesetting are in the notation manual -in @ref{Polyphony}. - -@node Piano staves -@section Piano staves +@moreinfo +@quotation +See @ref{Basic polyphony}. +@end quotation -@cindex staff switch, manual -@cindex cross staff voice, manual -@cindex @code{\translator} -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 - < \context Staff = up @{ @dots{} @} - \context Staff = down @{ @dots{} @} - > -@end example -but now this entire expression must be interpreted as a -@code{PianoStaff}: -@example - \context PianoStaff < \context Staff @dots{} > -@end example +@node Combining notes into chords +@subsection Combining notes into chords -Here is a full-fledged example: +@cindex chords +Chords can be made by surrounding pitches with single angle brackets. Angle +brackets are the symbols @samp{<} and @samp{>}. -@lilypond[relative 0,fragment] -\context PianoStaff - < \context Staff = up { \time 2/4 - c4 c g' g } - \context Staff = down { - \clef bass c,, c' e c } - > +@lilypond[quote,fragment,verbatim,relative=2,fragment] +r4 4 2 @end lilypond -More information on formatting piano music is in @ref{Piano music}. +You can combine markings like beams and ties with chords. They must +be placed outside the angled brackets -@node Setting variables -@section Setting variables +@lilypond[quote,fragment,verbatim,relative=2,fragment] +r4 8[ ]~ 2 +@end lilypond -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{translation properties}. -The properties can also be manipulated from input files. Consider this input: -@example -\property Staff.autoBeaming = ##f -@end example -It sets the property named @code{autoBeaming} in the current staff to -@code{##f}, which means `false'. This property controls whether beams -are printed automatically: -@lilypond[relative 1,fragment,verbatim] - c8 c c c - \property Staff.autoBeaming = ##f - c8 c c c +@lilypond[quote,fragment,verbatim,relative=2,fragment] +r4 8\>( 4 \!) @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 - \property Staff.instrument = #"French Horn" -@end example -@item a boolean: either @code{#t} or @code{#f}, for true and false -respectively, e.g. -@example - \property Voice.autoBeaming = ##f - \property Score.skipBars = ##t -@end example -@item a number, such as -@example - \property Score.currentBarNumber = #20 -@end example +@node Songs +@section Songs -@item a symbol, which is introduced by a quote character, as in -@example - \property Staff.crescendoSpanner = #'dashed-line -@end example +This section introduces vocal music and simple song sheets. + +@menu +* Printing lyrics:: +* A lead sheet:: +@end menu -@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.minimumVerticalExtent = #'(-7.5 . 6) - \property Staff.timeSignatureFraction = #'(3 . 4) -@end example +@node Printing lyrics +@subsection Printing lyrics +@cindex Lyrics +@cindex Songs +Consider a simple melody: -@end itemize +@lilypond[quote,ragged-right,verbatim] +\relative c'' { + a4 e c r4 + b2 c4( d) +} +@end lilypond -There are many different properties, and not all of them are listed in -this manual. However, the internal documentation lists them all in the -@internalsref{All translation 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 0] - c4 - \property Voice.Stem \override #'thickness = #3.0 - c4 c4 c4 +The lyrics can be set to these notes, combining both with the +@code{\addlyrics} keyword. Lyrics are entered by separating each +syllable with a space. + +@lilypond[quote,ragged-right,verbatim] +<< + \relative c'' { + a4 e c r4 + b2 c4( d) + } + \addlyrics { One day this shall be free } +>> @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 -Voice. As a result, the notes following @code{\property} have thicker -stems. +@cindex melisma +@cindex extender line +This melody ends on a @rglos{melisma}, a single syllable (@q{free}) +sung to more than one note. This is indicated with an @emph{extender +line}. It is entered as two underscores @code{__}: + +@lilypond[quote,ragged-right,verbatim] +<< + \relative c'' { + a4 e c r4 + b2 c4( d) + } + \addlyrics { One day this shall be free __ } +>> +@end lilypond -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. +Similarly, hyphens between words can be entered as two dashes, +resulting in a centered hyphen between two syllables @example - \once \property Voice.Stem \set #'thickness = #3.0 +A -- le gri -- a @end example -@lilypond[relative 0] - c4 - \once \property Voice.Stem \set #'thickness = #3.0 - c4 c4 c4 +@c no ragged-right here because otherwise the hypens get lost. +@lilypond[quote,verbatim] +<< + \relative c' { + \time 2/4 + f4 f c c + } + \addlyrics { A -- le gri -- a } +>> +@end lilypond + +@moreinfo +@quotation +More options, such as putting multiple stanzas below a melody, are +discussed in @ref{Vocal music}. +@end quotation + + +@node A lead sheet +@subsection A lead sheet + +@cindex Lead sheets +@cindex chords +@cindex chord names + +@c TODO: revise this, \chords { } is shorter and more intuitive. +@c I need help for this. -gp + +In popular music it is common to denote accompaniment with chord names. +Such chords can be entered like notes, + +@lilypond[quote,ragged-right,verbatim] +\chordmode { c2 f4. g8 } @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 internal documentation 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 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 \property Voice.Fingering - \set #'extra-offset = #'(-0.3 . -1.8) -f-5 +Now each pitch is read as the root of a chord instead of a note. +This mode is switched on with @code{\chordmode} + +Other chords can be created by adding modifiers after a colon. The +following example shows a few common modifiers + +@lilypond[quote,verbatim,ragged-right] +\chordmode { c2 f4:m g4:maj7 gis1:dim7 } @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] -\context Staff < { - \once \property Voice.Stem \set #'transparent = ##t - b8~ b8 - } \\ { - b[ g8] - } > +For lead sheets, chords are not printed on staves, but as names on a +line for themselves. This is achieved by using @code{\chords} instead +of @code{\chordmode}. This uses the same syntax as @code{\chordmode}, +but renders the notes in a @code{ChordNames} context, with the +following result. + +@lilypond[quote,verbatim,ragged-right] +\chords { c2 f4.:m g4.:maj7 gis8:dim7 } @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] - c2-\fermata - \property Voice.Script \set #'padding = #3 - b2-\fermata +@cindex lead sheet +When put together, chord names, lyrics and a melody form +a lead sheet, for example, + +@lilypond[quote,verbatim,ragged-right] +% this melody needs to be changed. See my new example in 2.4.1. -gp +<< + \chords { r2 c:sus4 f } + \relative { + r4 c' \times 2/3 { f g g } + \times 2/3 { g4( a2) } + } + \addlyrics { I want to break free __ } +>> @end lilypond -@end itemize +A complete list of modifiers and other options for layout can be found +in @ref{Chords}. -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 +@node Final touches +@section Final touches -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. +This is the final section of the tutorial; it demonstrates how to add the +final touches to simple pieces, and provides an introduction to the rest +of the manual. -By using variables, also known as identifiers, it is possible to break -up complex music expressions. -An identifier is assigned as follows: -@example - namedMusic = \notes @{ @dots{} -@end example +@menu +* Version number:: +* Adding titles:: +* Absolute note names:: +* Organizing pieces with identifiers:: +* After the tutorial:: +* How to read the manual:: +@end menu -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 thrice by using -variable substitution: -@lilypond[singleline,verbatim] -seufzer = \notes { - dis'8 e'8 -} -\score { \notes { - \seufzer \seufzer \seufzer -} } -@end lilypond +@node Version number +@subsection Version number -The name of an identifier should only have alphabetic characters only, -and no numbers, underscores or dashes. The assignment should be -outside of the @code{\score} block. +@cindex versioning +The @code{\version} statement marks for which version of LilyPond the file +was written. To mark a file for version 2.10.1, place -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 - \score @{ - \notes @{ c4^\name @} - \paper @{ - \aFivePaper - linewidth = \width - @} - @} +\version "2.10.1" @end example -More information on the possible uses of identifiers is in the -technical manual, in @ref{Scheme datatypes}. +@noindent +at the top of your LilyPond file. +These annotations make future upgrades of LilyPond go more +smoothly. Changes in the syntax are handled with a special program, +@file{convert-ly} (see @ref{Updating files with convert-ly}), and it uses +@code{\version} to determine what rules to apply. -@node An orchestral part -@section An orchestral 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. +@node Adding titles +@subsection Adding titles -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 -hornNotes = \notes \relative c @{ - \time 2/4 - r4 f8 a cis4 f e d -@} -@end example +The title, composer, opus number, and similar information are entered +in the @code{\header} block. This exists outside of the main +music expression; the @code{\header} block is usually placed underneath +the @ref{Version number}. -Then, an individual part is made by putting the following in a file: @example -\include "horn-music.ly" +\version "2.10.1" \header @{ - instrument = "Horn in F" + title = "Symphony" + composer = "Me" + opus = "Op. 9" @} -\score @{ - \notes \transpose c' f \hornNotes + +@{ + @dots{} music @dots{} @} @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: - -@lilypond[singleline] -\score { - \notes \transpose f c' \notes \relative c { - \time 2/4 - r4 f8 a cis4 f e d -} -} -@end lilypond -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 - R2*3 -@end example +When the file is processed, the title and composer are printed above +the music. More information on titling can be found in @ref{Creating +titles}. -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 - \property Score.skipBars = ##t -@end example -Prepending the rest and the property setting above, leads to the -following result: - -@lilypond[singleline] -\score {\notes { \transpose f c' \relative c { \time 2/4 -\property 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 -\include "bassoon-music.ly" -\include "horn-music.ly" - -\score @{ - \simultaneous @{ - \context Staff = hornStaff \hornNotes - \context Staff = bsnStaff \bassoonNotes - @} @} -@end example +@node Absolute note names +@subsection Absolute note names -This would lead to the simple score depicted below: +So far we have always used @code{\relative} to define pitches. This is +the easiest way to enter most music, but another way of defining pitches +exists: absolute mode. -@lilypond[singleline] -\score { - \notes \relative c \simultaneous { - \context Staff = hornStaff { \time 2/4 - R2*3 - r4 f8 a cis4 f e d } - \context Staff = fagStaff { \clef bass - r4 d,8 f | gis4 c | b bes | - a8 e f4 | g d | gis f } - } } -@end lilypond +If you omit the @code{\relative}, LilyPond treats all pitches as +absolute values. A @code{c'} will always mean middle C, a @code{b} will +always mean the note one step below middle C, and a @code{g,} will +always mean the note on the bottom staff of the bass clef. -More in-depth information on preparing parts and scores is in the -notation manual, in @ref{Orchestral music}. +@lilypond[quote,verbatim,ragged-right] +{ + \clef bass + c' b g, g, + g, f, f c' +} +@end lilypond +Here is a four-octave scale: -@node Integrating text and music -@section Integrating text and music +@lilypond[quote,verbatim,ragged-right] +{ + \clef bass + c, d, e, f, + g, a, b, c + d e f g + a b c' d' + \clef treble + e' f' g' a' + b' c'' d'' e'' + f'' g'' a'' b'' + c'''1 +} +@end lilypond -@cindex La@TeX{}, music in -@cindex HTML, music in -@cindex Texinfo, music in +As you can see, writing a melody in the treble clef involves a lot of +quote ' marks. Consider this fragment from Mozart: -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. +@lilypond[quote,verbatim,ragged-right] +{ + \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 -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 program is fully described in @ref{lilypond-book manual}. Here -we show a small example; since the example contains also explanatory -text, we will not comment it further: +All these quotes makes the input less readable and it is a source of +errors. With @code{\relative}, the previous example is much easier +to read: -@example -\documentclass[a4paper]@{article@} -\begin@{document@} +@lilypond[quote,verbatim,ragged-right] +\relative c'' { + \key a \major + \time 6/8 + cis8. d16 cis8 e4 e8 + b8. cis16 b8 d4 d8 +} +@end lilypond -In a lilypond-book document, you can freely mix music and text. For -example: -\begin@{lilypond@} - \score @{ \notes \relative c' @{ - c2 g'2 \times 2/3 @{ f8 e d @} c'2 g4 - @} @} -\end@{lilypond@} +If you make a mistake with an octave mark (@code{'} or @code{,}) while +working in @code{\relative} mode, it is very obvious -- many notes will +be in the wrong octave. When working in absolute mode, a single mistake +will not be as visible, and will not be as easy to find. -Notice that the music line length matches the margin settings of the -document. +However, absolute mode is useful for music which has large intervals, and +is extremely useful for computer-generated LilyPond files. -If you have no \verb+\score+ block in the fragment, -\texttt@{lilypond-book@} will supply one: -\begin@{lilypond@} - c'4 -\end@{lilypond@} +@node Organizing pieces with identifiers +@subsection Organizing pieces with identifiers -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 options by putting them in brackets: +When all of the elements discussed earlier are combined to produce +larger files, the music expressions get a lot bigger. In polyphonic +music with many staves, the input files can become very confusing. We can +reduce this confusion by using @emph{identifiers}. -\begin[26pt,verbatim]@{lilypond@} - c'4 f16 -\end@{lilypond@} +Identifiers (also known as variables or macros), we can break up +complex music expressions. An identifier is assigned as follows -If you want to include large examples into the text, it is more -convenient to put it in a separate file: +@example +namedMusic = @{ @dots{} @} +@end example -\lilypondfile@{screech-boink.ly@} +The contents of the music expression @code{namedMusic} can be used +later by placing a backslash in front of the name +(@code{\namedMusic}, just like a normal LilyPond command). Identifiers +must be defined @emph{before} the main music expression. -\end@{document@} -@end example +@lilypond[quote,verbatim,ragged-right] +violin = \new Staff { \relative c'' { + a4 b c b +}} +cello = \new Staff { \relative c { + \clef bass + e2 d +}} +{ + << + \violin + \cello + >> +} +@end lilypond + +@noindent +The name of an identifier should have alphabetic characters only: no +numbers, underscores, or dashes. + +It is possible to use variables for many other types of objects in the +input. For example, -Under Unix, you can view the results as follows: @example -$ cd input/tutorial -$ mkdir -p out/ -$ lilypond-book --outdir=out/ lilbook.tex -lilypond-book (GNU LilyPond) 1.7.23 -Reading `input/tutorial/lilbook.tex' -Reading `input/screech-boink6.ly' -@var{lots of stuff deleted} -Writing `out/lilbook.latex' -$ cd out -$ latex lilbook.latex -@var{lots of stuff deleted} -$ xdvi lilbook +width = 4.5\cm +name = "Wendy" +aFivePaper = \paper @{ paperheight = 21.0 \cm @} @end example -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}. +Depending on its contents, the identifier can be used in different +places. The following example uses the above variables: -The result looks more or less like this: +@example +\paper @{ + \aFivePaper + line-width = \width +@} +@{ c4^\name @} +@end example -@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 - } - \paper { - raggedright = ##t - } -} -@end lilypond +@node After the tutorial +@subsection After the tutorial -Notice that the music line length matches the margin settings of the -document. +After finishing the tutorial, you should probably try writing a +piece or two. Start with one of the @ref{Templates} and +add notes. If you need any notation that was not covered in the +tutorial, look at the Notation Reference, starting with +@ref{Basic notation}. If you want to write for an instrument +ensemble which is not covered in the templates, +take a look at @ref{Extending the templates}. -If you have no @code{\score} block in the fragment, -@code{lilypond-book} will supply one: +Once you have written a few short pieces, read the rest of +the Learning Manual (chapters 3-5). There's nothing wrong +with reading them now, of course! However, the rest of the +Learning Manual assumes that you are familiar with +LilyPond input. You may wish to skim these chapters right +now, and come back to them after you have more experience. -@lilypond - c'4 -@end lilypond -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: +@node How to read the manual +@subsection How to read the manual -@lilypond[26pt,verbatim] - c'4 f16 -@end lilypond +As we saw in @ref{How to read the tutorial}, many examples in the +tutorial omitted a @code{\relative c'' @{ ... @}} around the printed +example. + +In the rest of the manual, we are much more lax about the +printed examples: sometimes they may have omitted a +@code{\relative c'' @{ ... @}}, but in other times a different initial +pitch may be used (such as @code{c'} or @code{c,,}), and in some cases +the whole example is in absolute note mode! However, ambiguities like +this only exist where the pitches are not important. In any example +where the pitch matters, we have explicitly stated our @code{\relative} +our our absolute-mode @code{@{ @}}. -If you want to include large examples into the text, it is more -convenient to put it in a separate file: +If you are still confused about the exact LilyPond input that was +used in an example, read the HTML version (if you are not already doing +so) and click on the picture of the music. This will display the exact +input that LilyPond used to generate this manual. -@lilypondfile{screech-boink.ly}