1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond.tely
4 @c A menu is needed before every deeper *section nesting of @node's; run
5 @c M-x texinfo-all-menus-update
6 @c to automatically fill in these menus before saving changes
8 @node Non-musical notation
9 @chapter Non-musical notation
11 This section deals with general lilypond issues, rather than
16 * Titles and headers::
18 * Displaying LilyPond notation::
19 * Skipping corrected music::
26 The main format of input for LilyPond are text files. By convention,
27 these files end with ``@code{.ly}''.
30 * File structure (introduction)::
31 * Multiple scores in a book::
33 * A single music expression::
34 * Including LilyPond files::
39 @node File structure (introduction)
40 @subsection File structure (introduction)
42 A basic example of a lilypond input file is
47 @{ @} % this is a single music expression;
48 % all the music goes in here.
56 There are many variations of this basic pattern, but this
57 example serves as a useful starting place.
59 The major part of this manual is concerned with entering various
60 forms of music in LilyPond. However, many music expressions are not
61 valid input on their own, for example, a @code{.ly} file containing
68 will result in a parsing error. Instead, music should be inside other
69 expressions, which may be put in a file by themselves. Such
70 expressions are called toplevel expressions. The next section enumerates
74 @node Multiple scores in a book
75 @subsection Multiple scores in a book
78 @cindex movements, multiple
80 A document may contain multiple pieces of music and texts. Examples
81 of these are an etude book, or an orchestral part with multiple
82 movements. Each movement is entered with a @code{\score} block,
90 and texts are entered with a @code{\markup} block,
100 The movements and texts are combined together in a @code{\book} block,
118 The header for each piece of music can be put inside the @code{\score}
119 block. The @code{piece} name from the header will be printed before
120 each movement. The title for the entire book can be put inside the
121 @code{\book}, but if it is not present, the @code{\header} which is at
122 the top of the file is inserted.
127 title = "Eight miniatures"
128 composer = "Igor Stravinsky"
132 \header @{ piece = "Romanze" @}
135 ..text of second verse..
138 ..text of third verse..
142 \header @{ piece = "Menuetto" @}
150 @subsection File structure
152 A @code{.ly} file contains any number of toplevel expressions, where a
153 toplevel expression is one of the following
157 An output definition, such as @code{\paper}, @code{\midi}, and
158 @code{\layout}. Such a definition at the toplevel changes the default
159 settings for the block entered.
162 A direct scheme expression, such as
163 @code{#(set-default-paper-size "a7" 'landscape)} or
164 @code{#(ly:set-option 'point-and-click #f)}.
167 A @code{\header} block. This sets the global header block. This
168 is the block containing the definitions for book-wide settings, like
169 composer, title, etc.
172 An @code{\addquote} statement. See @ref{Quoting other voices}
173 for more information.
176 A @code{\score} block. This score will be collected with other
177 toplevel scores, and combined as a single @code{\book}.
179 This behavior can be changed by setting the variable
180 @code{toplevel-score-handler} at toplevel. The default handler is
181 defined in the init file @file{scm/@/lily@/.scm}.
183 The @code{\score} must begin with a music expression, and may
184 contain only one music expression.
187 A @code{\book} block logically combines multiple movements
188 (i.e., multiple @code{\score} blocks) in one document. If there are
189 a number of @code{\scores}, a single output file will be created
190 in which all movements are concatenated.
192 This behavior can be changed by setting the variable
193 @code{toplevel-book-handler} at toplevel. The default handler is
194 defined in the init file @file{scm/@/lily@/.scm}.
197 A compound music expression, such as
202 This will add the piece in a @code{\score} and format it in a
203 single book together with all other toplevel @code{\score}s and music
204 expressions. In other words, a file containing only the above
205 music expression will be translated into
221 This behavior can be changed by setting the variable
222 @code{toplevel-music-handler} at toplevel. The default handler is
223 defined in the init file @file{scm/@/lily@/.scm}.
226 A markup text, a verse for example
229 2. The first line verse two.
233 Markup texts are rendered above, between or below the scores or music
234 expressions, wherever they appear.
237 An identifier, such as
242 This can be used later on in the file by entering @code{\foo}. The
243 name of an identifier should have alphabetic characters only; no
244 numbers, underscores or dashes.
248 The following example shows three things that may be entered at
253 % movements are non-justified by default
265 At any point in a file, any of the following lexical instructions can
269 @item @code{\version}
270 @item @code{\include}
271 @item @code{\renameinput}
275 @node A single music expression
276 @subsection A single music expression
278 A @code{\score} must contain a single music expression. However,
279 this music expression may be of any size. Recall that music
280 expressions may be included inside other expressions to form
281 larger expressions. All of these examples are single music
282 expressions; note the curly braces @{ @} or angle brackets <<
283 >> at the beginning and ending of the music.
289 @lilypond[ragged-right,verbatim,quote]
296 @lilypond[ragged-right,verbatim,quote]
298 \new Staff { c'4 c' c' c' }
299 \new Staff { d'4 d' d' d' }
307 \new Staff @{ \flute @}
308 \new Staff @{ \oboe @}
311 \new Staff @{ \violinI @}
312 \new Staff @{ \violinII @}
319 @node Including LilyPond files
320 @subsection Including LilyPond files
323 @cindex including files
325 A large project may be split up into separate files. To refer to another
329 \include "otherfile.ly"
332 The line @code{\include "file.ly"} is equivalent to pasting the contents
333 of file.ly into the current file at the place where you have the
334 \include. For example, for a large project you might write separate files
335 for each instrument part and create a ``full score'' file which brings
336 together the individual instrument files.
338 The initialization of LilyPond is done in a number of files that are
339 included by default when you start the program, normally transparent to the
340 user. Run lilypond --verbose to see a list of paths and files that Lily
343 Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where
344 VERSION is in the form ``2.6.1'') are on the path and available to
345 @code{\include}. Files in the
346 current working directory are available to \include, but a file of the same
347 name in LilyPond's installation takes precedence. Files are
348 available to \include from directories in the search path specified as an
349 option when invoking @code{lilypond --include=DIR} which adds DIR to the
352 The @code{\include} statement can use full path information, but with the Unix
353 convention @code{"/"} rather than the DOS/Windows @code{"\"}. For example,
354 if @file{stuff.ly} is located one directory higher than the current working
358 \include "../stuff.ly"
363 @subsection Text encoding
365 LilyPond uses the Pango library to format multi-lingual texts, and
366 does not perform any input-encoding conversions. This means that any
367 text, be it title, lyric text, or musical instruction containing
368 non-ASCII characters, must be utf-8. The easiest way to enter such text is
369 by using a Unicode-aware editor and saving the file with utf-8 encoding. Most
370 popular modern editors have utf-8 support, for example, vim, Emacs,
373 Depending on the fonts installed, the following fragment shows Hebrew
380 @lilypondfile[fontload]{utf-8.ly}
382 The @TeX{} backend does not handle encoding specially at all. Strings
383 in the input are put in the output as-is. Extents of text items in the
384 @TeX{} backend, are determined by reading a file created via the
385 @file{texstr} backend,
388 lilypond -b texstr input/les-nereides.ly
389 latex les-nereides.texstr
392 The last command produces @file{les-nereides.textmetrics}, which is
393 read when you execute
396 lilypond -b tex input/les-nereides.ly
399 Both @file{les-nereides.texstr} and @file{les-nereides.tex} need
400 suitable LaTeX wrappers to load appropriate La@TeX{} packages for
401 interpreting non-ASCII strings.
403 To use a Unicode escape sequence, use
406 #(ly:export (ly:wide-char->utf-8 #x2014))
412 @inputfileref{input/regression,utf-8.ly}
416 @node Titles and headers
417 @section Titles and headers
419 Almost all printed music includes a title and the composer's name;
420 some pieces include a lot more information.
428 @node Creating titles
429 @subsection Creating titles
431 Titles are created for each @code{\score} block, and over a
434 The contents of the titles are taken from the @code{\header} blocks.
435 The header block for a book supports the following
441 The dedicatee of the music, centered at the top of the first page.
445 The title of the music, centered just below the dedication.
449 Subtitle, centered below the title.
451 @funindex subsubtitle
453 Subsubtitle, centered below the subtitle.
457 Name of the poet, flush-left below the subtitle.
461 Name of the composer, flush-right below the subtitle.
465 Meter string, flush-left below the poet.
469 Name of the opus, flush-right below the composer.
473 Name of the arranger, flush-right below the opus.
477 Name of the instrument, centered below the arranger. Also
478 centered at the top of pages (other than the first page).
482 Name of the piece, flush-left below the instrument.
484 @cindex page breaks, forcing
485 @funindex breakbefore
487 This forces the title to start on a new page (set to ##t or ##f).
491 Copyright notice, centered at the bottom of the first page. To
492 insert the copyright symbol, see @ref{Text encoding}.
496 Centered at the bottom of the last page.
500 Here is a demonstration of the fields available. Note that you
501 may use any @ref{Text markup} commands in the header.
503 @lilypond[quote,verbatim,line-width=11.0\cm]
506 paper-height = 10.0\cm
511 dedication = "dedicated to me"
512 title = \markup \center-align { "Title first line" "Title second line,
514 subtitle = "the subtitle,"
515 subsubtitle = #(string-append "subsubtitle LilyPond version "
518 composer = \markup \center-align { "composer" \small "(1847-1973)" }
519 texttranslator = "Text Translator"
520 meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
522 arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize
523 #-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }
524 instrument = \markup \bold \italic "instrument"
548 As demonstrated before, you can use multiple @code{\header} blocks.
549 When same fields appear in different blocks, the latter is used.
550 Here is a short example.
554 composer = "Composer"
562 piece = "New piece" % overwrite previous one
567 If you define the @code{\header} inside the @code{\score} block, then
568 normally only the @code{piece} and @code{opus} headers will be printed.
569 Note that the music expression must come before the @code{\header}.
571 @lilypond[quote,verbatim,line-width=11.0\cm]
575 title = "title" % not printed
582 @funindex printallheaders
584 You may change this behavior (and print all the headers when defining
585 @code{\header} inside @code{\score}) by using
596 The default footer is empty, except for the first page, where the
597 @code{copyright} field from @code{\header} is inserted, and the last
598 page, where @code{tagline} from @code{\header} is added. The default
599 tagline is ``Music engraving by LilyPond (@var{version})''.@footnote{Nicely
600 printed parts are good PR for us, so please leave the tagline if you
605 @subsection Custom titles
607 A more advanced option is to change the definitions of the following
608 variables in the @code{\paper} block. The init file
609 @file{ly/titling-init.ly} lists the default layout.
612 @funindex bookTitleMarkup
613 @item bookTitleMarkup
614 This is the title put over an entire @code{\book} block. Typically,
615 it has the composer and the title of the piece
617 @funindex scoreTitleMarkup
618 @item scoreTitleMarkup
619 This is the title put over a @code{\score} block within a
620 @code{\book}. Typically, it has the name of the movement (@code{piece}
623 @funindex oddHeaderMarkup
624 @item oddHeaderMarkup
625 This is the page header for odd-numbered pages.
627 @funindex evenHeaderMarkup
628 @item evenHeaderMarkup
629 This is the page header for even-numbered pages. If unspecified,
630 the odd header is used instead.
632 By default, headers are defined such that the page number is on the
633 outside edge, and the instrument is centered.
635 @funindex oddFooterMarkup
636 @item oddFooterMarkup
637 This is the page footer for odd-numbered pages.
639 @funindex evenFotterMarkup
640 @item evenFooterMarkup
641 This is the page footer for even-numbered pages. If unspecified,
642 the odd header is used instead.
644 By default, the footer has the copyright notice on the first, and
645 the tagline on the last page.
655 The following definition will put the title flush left, and the
656 composer flush right on a single line.
660 bookTitleMarkup = \markup {
662 \fromproperty #'header:title
663 \fromproperty #'header:composer
672 The @code{breakbefore=##t} header requires that there is a @code{piece}
673 header as well. It may be used as a normal header, or left blank
674 (@code{=""}) as in the example above, but it must be present.
684 MIDI (Musical Instrument Digital Interface) is a standard for
685 connecting and controlling digital instruments. A MIDI file is a
686 series of notes in a number of tracks. It is not an actual
687 sound file; you need special software to translate between the
688 series of notes and actual sounds.
690 Pieces of music can be converted to MIDI files, so you can listen to
691 what was entered. This is convenient for checking the music; octaves
692 that are off or accidentals that were mistyped stand out very much
693 when listening to the MIDI output.
697 Many musically interesting effects, such as swing, articulation,
698 slurring, etc., are not translated to midi.
700 The midi output allocates a channel for each staff, and one for global
701 settings. Therefore the midi file should not have more than 15 staves
702 (or 14 if you do not use drums). Other staves will remain silent.
704 Not all midi players correctly handle tempo changes in the midi
705 output. Players that are known to work include
706 @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
709 * Creating MIDI files::
711 * MIDI instrument names::
714 @node Creating MIDI files
715 @subsection Creating MIDI files
717 To create a MIDI from a music piece of music, add a @code{\midi} block
718 to a score, for example,
723 \midi @{ \tempo 4=72 @}
727 The tempo is specified using the @code{\tempo} command. In this
728 example the tempo of quarter notes is set to 72 beats per minute.
731 If there is a @code{\midi} command in a @code{\score}, only MIDI will
732 be produced. When notation is needed too, a @code{\layout} block must
738 \midi @{ \tempo 4=72 @}
746 Ties, dynamics, and tempo changes are interpreted. Dynamic marks,
747 crescendi and decrescendi translate into MIDI volume levels. Dynamic
748 marks translate to a fixed fraction of the available MIDI volume
749 range, crescendi and decrescendi make the volume vary linearly between
750 their two extremes. The fractions can be adjusted by
751 @code{dynamicAbsoluteVolumeFunction} in @internalsref{Voice} context.
752 For each type of MIDI instrument, a volume range can be defined. This
753 gives a basic equalizer control, which can enhance the quality of
754 the MIDI output remarkably. The equalizer can be controlled by
755 setting @code{instrumentEqualizer}, or by setting
758 \set Staff.midiMinimumVolume = #0.2
759 \set Staff.midiMaximumVolume = #0.8
762 To remove dynamics from the MIDI output, insert the following lines
763 in the @code{\midi@{@}} section.
770 \remove "Dynamic_performer"
771 \remove "Span_dynamic_performer"
779 Unterminated (de)crescendos will not render properly in the midi file,
780 resulting in silent passages of music. The workaround is to explicitly
781 terminate the (de)crescendo. For example,
788 will not work properly but
799 @subsection MIDI block
803 The MIDI block is analogous to the layout block, but it is somewhat
804 simpler. The @code{\midi} block can contain
808 @item a @code{\tempo} definition, and
809 @item context definitions.
812 A number followed by a period is interpreted as a real number, so
813 for setting the tempo for dotted notes, an extra space should be
814 inserted, for example
817 \midi @{ \tempo 4 . = 120 @}
821 @cindex context definition
823 Context definitions follow precisely the same syntax as within the
824 \layout block. Translation modules for sound are called performers.
825 The contexts for MIDI output are defined in @file{ly/@/performer@/-init@/.ly}.
828 @node MIDI instrument names
829 @subsection MIDI instrument names
831 @cindex instrument names
832 @funindex Staff.midiInstrument
834 The MIDI instrument name is set by the @code{Staff.midiInstrument}
835 property. The instrument name should be chosen from the list in
836 @ref{MIDI instruments}.
839 \set Staff.midiInstrument = "glockenspiel"
843 If the selected instrument does not exactly match an instrument from
844 the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
848 @c Yes, this is a cop-out; this info doesn't belong in the Scheme
849 @c chapter, but I'm not certain where to stick it.
850 @c I think I'll eventually split this chapter into a "paper/layout"
851 @c chapter and a "misc issues" chapter. -gp
852 @node Displaying LilyPond notation
853 @section Displaying LilyPond notation
855 @funindex \displayLilyMusc
856 Displaying a music expression in LilyPond notation can be
857 done using the music function @code{\displayLilyMusic}. For example,
861 \displayLilyMusic \transpose c a, @{ c e g a bes @}
871 By default, LilyPond will print these messages to the console along
872 with all the other messages. To split up these messages and save
873 the results of @code{\display@{STUFF@}}, redirect the output to
877 lilypond file.ly >display.txt
881 @node Skipping corrected music
882 @section Skipping corrected music
885 @funindex skipTypesetting
886 @funindex showLastLength
888 When entering or copying music, usually only the music near the end (where
890 are adding notes) is interesting to view and correct. To speed up
891 this correction process, it is possible to skip typesetting of all but
892 the last few measures. This is achieved by putting
895 showLastLength = R1*5
900 in your source file. This will render only the last 5 measures
901 (assuming 4/4 time signature) of every @code{\score} in the input
902 file. For longer pieces, rendering only a small part is often an order
903 of magnitude quicker than rendering it completely
905 Skipping parts of a score can be controlled in a more fine-grained
906 fashion with the property @code{Score.skipTypesetting}. When it is
907 set, no typesetting is performed at all.
909 This property is also used to control output to the MIDI file. Note that
910 it skips all events, including tempo and instrument changes. You have
913 @lilypond[quote,fragment,ragged-right,verbatim]
916 \set Score.skipTypesetting = ##t
918 \set Score.skipTypesetting = ##f
922 In polyphonic music, @code{Score.skipTypesetting} will affect all
923 voices and staves, saving even more time.