@menu
* First steps::
-* Running LilyPond::
+* Running LilyPond for the first time::
* More about pitches::
* Entering ties::
* Automatic and manual beams::
* More staves::
* Adding articulation marks to notes::
* Combining notes into chords::
-* Basic rhythmical commands::
+* Advanced rhythmic commands::
* Commenting input files::
* Printing lyrics::
* A lead sheet::
-* Listening to output::
* Adding titles::
* Single staff polyphony::
* Piano staves::
* Organizing larger pieces::
* An orchestral part::
-* Integrating text and music::
@end menu
@end example
@c FIXME: have NOTIME also remove Score.timing?
-@lilypond[fragment,quote,notime,relative=1]
+@lilypond[fragment,quote,notime,relative=2]
\set Score.timing = ##f
\set Staff.autoBeaming = ##f
{ a1 a2 a4 a16 a32 s16_" " }
a a8 a a2 a
@end example
-@lilypond[fragment,quote,notime,relative=1]
+@lilypond[fragment,quote,notime,relative=2]
\set Score.timing = ##f
{ a a8 a a2 a s16_" " }
@end lilypond
@end quotation
-@node Running LilyPond
-@section Running LilyPond
+@node Running LilyPond for the first time
+@section Running LilyPond for the first time
-@c FIXME: let's not be so casual about Emacs and VIM, but rather
-@c instruct (how) to use them; let advanced user figure-out what
-@c commands to type?
-
-@c
-@c We don't have enough space to explain either VIM
-@c or Emacs non-advanced users, and I fear that both editors will only
-@c confuse newbies. I vote for keeping the material in footnotes.
-@c
-@c --hwn
+@c cheesy title to avoid clash with chapter name.
In the last section we explained what kind of things you could enter
in a LilyPond file. In this section we will explain what commands to
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
+is a @code{LilyPond-mode} for Emacs addicts. If they have not been
installed already, refer to
@c FIXME lousy reference.
the file @file{INSTALL.txt}.} In your text editor, enter the following
On Windows, start up a text-editor@footnote{Any simple or
programmer-oriented editor will do, for example Notepad. Do not use a
-word processor, its formatting codes will confuse LilyPond.} and enter
+word processor, since these insert formatting codes that will confuse
+LilyPond.} and enter
@example
@{ c'4 e' g' @}
@end lilypond
@noindent
-no note gets an explicit accidental, but you still must enter
+no note has an explicit accidental, but you still must enter
@example
\key d \major
Adding all alterations explicitly might require a little more effort
when typing, but the advantage is that transposing is easier, and
-music can be printed according to different conventions. See
+accidentals can be printed according to different conventions. See
@ref{Accidentals}, for some examples how accidentals can be printed
according to different rules.
@noindent
The last 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.
-@ignore
-FIXME: move to notation manual?
- You must also give a note
-from which relative mode starts, in this case @code{c''}.
-@end ignore
-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, @samp{c f} goes up while @samp{c g} goes down
+solution is to use `relative octave' mode. This is the
+most convenient way to copy existing music.
+
+In relative mode, a note without octavation quotes (i.e. the @code{'}
+or @code{,} after a note) is chosen so it it is closest to the
+previous one. For example, @samp{c f} goes up while @samp{c g} goes
+down
+
+To use relative mode, add @code{\relative} before the piece of
+music. The first note is taken relative to the middle C
+@c no , for this sentence
+(i.e. @code{c'})
+
+
@lilypond[quote,notime,fragment,verbatim]
\relative {
without octavation quotes in relative mode. The previous example is
entered as
-@lilypond[quote,raggedright,fragment,verbatim]
+@lilypond[quote,raggedright,verbatim]
\relative {
\key a \major
\time 6/8
- cis''8. d16 cis8 e4 e8
+ cis'8. d16 cis8 e4 e8
b8. cis16 b8 d4 d8
}
@end lilypond
as a simultaneous combination of two sequences. A `simultaneous'
music expression is formed by enclosing expressions in @code{<<} and
@code{>>}. In the following example, three sequences (all containing
-two notes) are combined simultaneously
+two other notes) are combined simultaneously
@lilypond[fragment,quote,verbatim,relative=3]
<<
@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 @samp{+}, @samp{*} and @samp{/}). Parentheses are used
-to group expressions.
-
-Like mathematical expressions, music expressions can be nested
-arbitrarily deep@footnote{The reason for getting three staves in the
-previous example but just a single staff in the current one will be
-explained later.}
+This is a sequence of expressions, where each expression is contained
+in the next 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.
+
+Note that this example only has one staff, whereas
+the previous example had three seperate staves. That is because this
+example begins with a single note. To determine the number of staves,
+LilyPond looks at the first element. If it is a single note, there is one
+staff; if there is a simultaneous expression, there is more than one staff.
@lilypond[fragment,quote,verbatim,relative=2]
{
}
@end lilypond
-
-@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 number of closing
-braces at the end of an expression. For example,
+Music files with deep nesting can be confusing to enter and
+maintain. One convention that helps against this confusion is
+indenting. When entering a file with deep nesting of braces and
+angles, it is customary to use an indent that indicates the nesting
+level. Formatting music like this eases reading and helps you insert
+the right number of closing braces at the end of an expression. For
+example,
@example
-\book @{
- \score @{
- <<
- @{
- @dots{}
- @}
- @{
- @dots{}
- @}
- \paper @{
- @dots{}
- @}
- >>
+<<
+ @{
+ @dots{}
@}
-@}
+ @{
+ @dots{}
+ @}
+>>
@end example
Some editors have special support for entering LilyPond, and can help
-indenting source files. See @ref{Editor support}, for more information.
+indenting source files. See @ref{Editor support} for more information.
@node More staves
@section More staves
@lilypond[quote,fragment,verbatim]
<<
- \new Staff { \clef violin c'' }
+ \new Staff { \clef treble c'' }
\new Staff { \clef bass c }
>>
@end lilypond
The command @code{\new} introduces a `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 implicitly. For more complex pieces, it
+notation contexts are created automatically. For more complex pieces, it
is best to mark contexts explicitly. This ensures that each fragment
gets its own stave.
There are several types of contexts: @code{Staff}, @code{Voice} and
-@code{Score} handle normal music notation. Other contexts are also
+@code{Score} handle melodic notation. Other contexts are also
@code{Lyrics} (for setting lyric texts) and @code{ChordNames} (for
printing chord names).
@c TODO: (c) status of this Paul McCartney (?) song (let's all stand together)
@lilypond[fragment,quote,verbatim,raggedright]
-<<
+\relative <<
\new Staff {
\time 3/4
- \clef violin
- \relative {
- e''2 d4 c2 b4 a8[ a]
- b[ b] g[ g] a2. }
+ \clef treble
+
+ e'2 d4 c2 b4 a8[ a]
+ b[ b] g[ g] a2.
}
\new Staff {
\clef bass
- c2 e4 g2.
+ c,,2 e4 g2.
f4 e d c2.
}
>>
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. In most cases, it is
+best to let LilyPond determine the articulation directions.
+
+@lilypond[fragment,quote,verbatim,relative=2]
+c_-^1 d^. f^4_2-> e^-_+
+@end lilypond
Dynamic signs are made by adding the markings (with a backslash) to
the note
@samp{(} and @samp{)}, respectively
@lilypond[fragment,quote,fragment,relative=2,verbatim]
-d4( c16)( cis d e c cis d e)( d4)
+d4( c16) cis( d e c cis d) e( d4)
@end lilypond
@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
+and can be used on larger groups of notes. Slurs and ties can be
+nested
@lilypond[quote,fragment,relative=2]
c2~( c8 fis fis4 ~ fis2 g2)
@end lilypond
@example
-r4 <c e g>8\>( <c e g> <c e g> <c f a>8\!)
+r4 <c e g>8\>( <c e g> <c e g> <c f a>\!)
@end example
@lilypond[quote,relative=1,fragment]
\slurUp
-r4 <c e g>8\>( <c e g> <c e g> <c f a>8\!)
+r4 <c e g>8\>( <c e g> <c e g> <c f a>\!)
@end lilypond
-
-
-@node Basic rhythmical commands
-@section Basic rhythmical commands
+@node Advanced rhythmic commands
+@section Advanced rhythmic commands
@cindex pickup
@cindex anacruse
@cindex line comment
@cindex block comment
A comment is a remark for the human reader of the music input; it is
-ignored and has no effect on the printed output. There are two types
-of comments. The percent symbol @samp{%} introduces a line comment;
-the rest of the line is ignored. A block comments marks a whole
-section of music input---anything that is enclosed in @code{%@{} and
-@code{%@}} is ignored. The following fragment shows possible uses for
-comments
+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; after @code{%} the rest of the line is
+ignored. A block comments marks a whole section of music
+input. Anything that is enclosed in @code{%@{} and @code{%@}} is
+ignored. The following fragment shows possible uses for comments
@example
% notes for twinkle twinkle follow
-c4 c g' g a a
+c4 c g' g a a g2
%@{
This line, and the notes below
%@}
@end example
-There is a special statement that really is a kind of comment. The
-version statement marks for which version of LilyPond the file was
-written. To mark a file for version 2.1.17, use
+@c FIXME
+@c This is good info, but I wouldn't call it a comment. IMO it should
+@c be moved somewhere else. I don't know exactly where yet, but I'll
+@c resolve it soon. -gp
+
+@cindex versioning
+
+There is a special statement that is a kind of comment. The @code{\version}
+statement marks for which version of LilyPond the file was written.
+To mark a file for version 2.1.17, use
@example
-\version "2.1.17"
+\version "2.3.16"
@end example
@noindent
These annotations make future upgrades of LilyPond go more
-smoothly. Changes in the syntax are handled with a special program,
+smoothly. Changes in the syntax are handled with a special program,
@file{convert-ly} (see @ref{Invoking convert-ly}), and it uses
@code{\version} to determine what rules to apply.
More options, like putting multiple lines of lyrics below a melody are
discussed in @ref{Vocal music}.
-@c FIXME: too geeky, for notation manual?
-@c or introduce using foo = \lyrics { a b c } ?
-
-When using variables for a piece of lyrics
-To prevent certain words (for example `as') as being read as a
-pitch, the input-mode must be switched. This is done with
-@code{\lyrics}. In @code{\lyrics} mode, all words are read as lyric
-syllables.
-
-@example
-myText = \lyrics @{ I want to break free @}
-@end example
-
-@noindent
-The braces @code{@{@}} signify that the syllables are sung in
-sequence.
-
-@ignore
-By default, music expressions are interpreted in @code{Staff} context. For
-lyrics, this is obviously not desirable, so it is necessary
-to explicitly specify a @code{Lyrics} context,
-
-@example
-\lyrics @{ I want to break free @}
-@end example
-
-The melody for this song is as follows
-
-@lilypond[fragment,quote,fragment,relative=2]
-r4 c \times 2/3 { f4 g g }
-\times 2/3 { g4( a2) }
-@end lilypond
-
-@end ignore
-
@node A lead sheet
@section A lead sheet
@cindex chords
@cindex chord names
-In popular music, it is common to denote accompaniment as chord names.
+In popular music, it is common to denote accompaniment with chord names.
Such chords can be entered like notes,
-@example
-c2 f4. g8
-@end example
+@lilypond[quote,verbatim,raggedright]
+\chordmode { c2 f4. g8 }
+@end lilypond
@noindent
-but now, each pitch is read as the root of a chord instead of a note.
-This mode is switched on with @code{\chords}
+Now each pitch is read as the root of a chord instead of a note.
+This mode is switched on with @code{\chordmode}
-@lilypond[quote,verbatim,raggedright]
-\chords { c2 f4. g8 }
-@end lilypond
Other chords can be created by adding modifiers after a colon. The
following example shows a few common modifiers
@lilypond[quote,verbatim]
-\chords { c2 f4:m g4:maj7 gis1:dim7 }
+\chordmode { c2 f4:m g4:maj7 gis1:dim7 }
@end lilypond
For lead sheets, chords are not printed on staves, but as names on a
context
@lilypond[quote,verbatim]
-\new ChordNames \chords { c2 f4.:m g4.:maj7 gis8:dim7 }
+\chordmode { c2 f4.:m g4.:maj7 gis8:dim7 }
@end lilypond
@cindex lead sheet
@example
<<
- \new ChordNames \chords @{ @emph{chords} @}
+ \chordmode @{ @emph{chords} @}
@emph{the melody}
\addlyrics @{ @emph{the text} @}
>>
@lilypond[quote,raggedright]
<<
- \new ChordNames \chords { r2 c:sus4 f }
+ \chordmode { r2 c:sus4 f }
\relative {
r4 c' \times 2/3 { f g g }
\times 2/3 { g4( a2) }
A complete list of modifiers and other options for layout can be found
in @ref{Chords}.
-@c FIXME: we talk about \midi before mentioning \paper (or \layout?)
-@node Listening to output
-@section Listening to output
-
-@cindex sound
-@cindex MIDI
-
-MIDI (Musical Instrument Digital Interface) is a standard for
-connecting and controlling digital instruments. A MIDI file is like a
-tape recording of a MIDI instrument.
-
-To create a MIDI from a music piece of music, add a @code{\midi}
-block. This causes LilyPond to create a MIDI file, so you can listen
-to what you just 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.
-
-The @code{\midi} block is added to @code{\score}, for example,
-
-@example
-\score @{
- @var{...music...}
- \midi @{ \tempo 4=72 @}
-@}
-@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 in the notation manual can be found in
-@ref{Sound}.
-
-If there is a @code{\midi} command in a @code{\score}, only MIDI will
-be produced. If notation is needed too, a @code{\paper} block must be
-added
-
-@example
-\score @{
- @var{...music...}
- \midi @{ \tempo 4=72 @}
- \paper @{ @}
-@}
-@end example
-@cindex paper block
-
@node Adding titles
@section Adding titles
@example
\header @{
- title = "Eight miniatures"
+ title = "Miniature"
composer = "Igor Stravinsky"
- tagline = "small is beautiful"
@}
@{ @dots{} @}
@end example
-@cindex bibliographic information
-@cindex titles
-@cindex composer
-@cindex Engraved by LilyPond
When the file is processed the title and composer 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
-please leave the tagline if you can.}
-
-
-The @code{\header} block is usually put at the top of the file.
-
-A document may contains multiple pieces of music, examples are an
-etude book, or an orchestral part with multiple movements.
-@c FIXME: ugh. \header can only live at toplevel, or inside \score.
-@c If we allow it also to live inside \book, we do not need \score here?
-The @code{\book} block is used to group the individual @code{\score}
-blocks.
-
-The header for each piece of music can be put inside the @code{\score}
-block. The @code{piece} name from the header will be printed before
-each movement.
-
-@ignore
-
-FIXME: introduce \BOOK
-
-FIXME: Using "Adagio" as a name is confusing, it's more common to be
-a plain tempo indication.
-
-Since today (CVS-1.211) we also allow headers and composite music
-inside book:
-
- \header { ... }
- \book {
- \header { ... }
- { ... }
- \header { ... }
- { ... }
- }
-
-@end ignore
-
-@cindex Engraved by LilyPond
-@cindex signature line
-@cindex tag line
-
-@example
-\header @{
- title = "Eight miniatures"
- composer = "Igor Stravinsky"
- tagline = "small is beautiful"
-@}
-
-\book @{
- \score @{
- @dots{}
- \header @{ piece = "Adagio" @}
- @}
- \score @{
- @dots{}
- \header @{ piece = "Menuetto" @}
- @}
-@}
-@end example
-
-More information on titling can be found in @ref{Invoking lilypond}.
+the music. More information on titling can be found in @ref{Creating
+titles}.
@node Single staff polyphony
@code{@{...@}}), and combining those simultaneously, separating the
voices with @code{\\}
-@lilypond[quote,verbatim,relative=3]
+@lilypond[quote,verbatim,relative=2,fragment]
<< { 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. Here is the same example with a spacer rest
-instead of a normal rest---just use @samp{s} instead of @samp{r}
+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 (@code{s}) instead of a normal rest (@code{r}),
-@lilypond[quote,verbatim,relative=3]
+@lilypond[quote,verbatim,relative=2,fragment]
<< { a4 g2 f4~ f4 } \\
{ s4 g4 f2 f4 } >>
@end lilypond
@noindent
Again, these expressions can be nested arbitrarily
-@lilypond[quote,fragment,verbatim,relative=3]
+@lilypond[quote,fragment,verbatim,relative=2,fragment]
<<
\new Staff <<
{ a4 g2 f4~ f4 } \\
\new PianoStaff << \new Staff @dots{} >>
@end example
-Here is a full-fledged example
+Here is a small example
@lilypond[quote,verbatim,relative=1,fragment]
\new PianoStaff <<
{ \seufzer \seufzer }
@end lilypond
-The name of an identifier should have alphabetic characters only;
-no numbers, underscores or dashes. The assignment should be outside of
+The name of an identifier should have alphabetic characters only; no
+numbers, underscores or dashes. The assignment should be outside of
running music.
It is possible to use variables for many other types of objects in the
@end example
More information on the possible uses of identifiers is in the
-technical manual, in TODO.
+technical manual, in @ref{Input variables and Scheme}.
+@c fixme: the ref is too technical.
@node An orchestral part
@section An orchestral part
-In orchestral music, all notes are printed twice; 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
+In orchestral music, all notes are printed twice. Once in a part for
+the musicians, and once in a full score for the conductor. Identifiers can
+be used to avoid double work. The music is entered once, and stored in
a variable. The contents of that variable is then used to generate
both the part and the score.
substitutes the contents of @file{horn-music.ly} at this position in
the file, so @code{hornNotes} is defined afterwards. The command
@code{\transpose f@tie{}c'} indicates that the argument, being
-@code{\hornNotes}, should be transposed by a fifth downwards. Sounding
+@code{\hornNotes}, should be transposed by a fifth downwards. Sounding
@samp{f} is denoted by notated @code{c'}, which corresponds with
tuning of a normal French Horn in@tie{}F. The transposition can be seen
in the following output
More in-depth information on preparing parts and scores can be found
in the notation manual; see @ref{Orchestral music}.
-Setting run-time variables (`properties') is discussed in ref-TODO.
-
+Setting run-time variables (`properties') is discussed in
+@ref{Changing context properties on the fly}.
-@node Integrating text and music
-@section Integrating text and music
-@cindex La@TeX{}, music in
-@cindex HTML, music in
-@cindex Texinfo, music in
-Some texts contain music examples. These texts are musicological
-treatises, songbooks or manuals like this. Such texts can be made by
-hand, simply by importing a PostScript figure into the word processor.
-However, there is an automated procedure to reduce the amount of work
-involved HTML, La@TeX{}, and Texinfo documents.
-
-A script called @code{lilypond-book} will extract the music fragments,
-run format them, and put back the resulting notation. This program is
-fully described in @ref{lilypond-book manual}. Here we show a small
-example. The example also contains explanatory text, so we will not
-comment on it further
-
-@example
-\documentclass[a4paper]@{article@}
-\begin@{document@}
-
-Documents for lilypond-book may freely mix music and text. For
-example,
-
-\begin@{lilypond@}
- @{ \relative c' @{
- c2 g'2 \times 2/3 @{ f8 e d @} c'2 g4
- @}
-\end@{lilypond@}
-
-Options are put in brackets.
-
-\begin[fragment,quote,staffsize=26,verbatim]@{lilypond@}
- c'4 f16
-\end@{lilypond@}
-
-Larger examples can be put in a separate file, and introduced with
-\verb+\lilypondfile+.
-
-\lilypondfile[quote,noindent]@{screech-boink.ly@}
-
-\end@{document@}
-@end example
-
-Under Unix, you can view the results as follows
-
-@example
-$ cd input/tutorial
-$ 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/lilybook.tex'
-$ cd out
-$ latex lilybook
-@var{lots of stuff deleted}
-$ xdvi lilybook
-@end example
-
-To convert the file into a nice PDF document, run the following
-commands
-
-@example
-$ dvips -Ppdf -u+lilypond -u+ec-mftrace lilybook
-$ ps2pdf lilybook.ps
-@end example
-
-Running lilypond-book and running latex creates a lot of temporary
-files, which would clutter up the working directory. To remedy this,
-use the @code{--output=@var{dir}} option. It will create the files in
-a separate subdirectory @file{dir}.
-
-Finally the result of the La@TeX{} example shown above.@footnote{Note
-that in this tutorial the example is processed with Texinfo. This gives
-slightly different results in layout.} This finishes the tutorial
-section.
-
-@page
+@ignore
-Documents for lilypond-book may freely mix music and text. For
-example,
+* longer example
-@lilypond
-\relative c' {
- c2 g'2 \times 2/3 { f8 e d } c'2 g4
-}
-@end lilypond
+* discuss expectations (?)
-Options are put in brackets.
+* conclude tutorial
-@lilypond[fragment,quote,staffsize=26,verbatim]
-c'4 f16
-@end lilypond
-
-Larger examples can be put in a separate file, and introduced with
-@code{\lilypondfile}.
+* overview of chapters?
-@lilypondfile[quote,noindent]{screech-boink.ly}
+@end ignore
projects / lilypond.git / blobdiff