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::
17 * Multiple movements::
19 * Displaying LilyPond notation::
20 * Skipping corrected music::
27 The main format of input for LilyPond are text files. By convention,
28 these files end with ``@code{.ly}''.
31 * File structure (introduction)::
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
75 @subsection File structure
77 A @code{.ly} file contains any number of toplevel expressions, where a
78 toplevel expression is one of the following
82 An output definition, such as @code{\paper}, @code{\midi}, and
83 @code{\layout}. Such a definition at the toplevel changes the default
84 settings for the block entered.
87 A direct scheme expression, such as
88 @code{#(set-default-paper-size "a7" 'landscape)} or
89 @code{#(ly:set-option 'point-and-click #f)}.
92 A @code{\header} block. This sets the global header block. This
93 is the block containing the definitions for book-wide settings, like
97 An @code{\addquote} statement. See @ref{Quoting other voices}
101 A @code{\score} block. This score will be collected with other
102 toplevel scores, and combined as a single @code{\book}.
104 This behavior can be changed by setting the variable
105 @code{toplevel-score-handler} at toplevel. The default handler is
106 defined in the init file @file{scm/@/lily@/.scm}.
108 The @code{\score} must begin with a music expression, and may
109 contain only one music expression.
112 A @code{\book} block logically combines multiple movements
113 (i.e., multiple @code{\score} blocks) in one document. If there are
114 a number of @code{\scores}, a single output file will be created
115 in which all movements are concatenated.
117 This behavior can be changed by setting the variable
118 @code{toplevel-book-handler} at toplevel. The default handler is
119 defined in the init file @file{scm/@/lily@/.scm}.
122 A compound music expression, such as
127 This will add the piece in a @code{\score} and format it in a
128 single book together with all other toplevel @code{\score}s and music
129 expressions. In other words, a file containing only the above
130 music expression will be translated into
146 This behavior can be changed by setting the variable
147 @code{toplevel-music-handler} at toplevel. The default handler is
148 defined in the init file @file{scm/@/lily@/.scm}.
151 A markup text, a verse for example
154 2. The first line verse two.
158 Markup texts are rendered above, between or below the scores or music
159 expressions, wherever they appear.
162 An identifier, such as
167 This can be used later on in the file by entering @code{\foo}. The
168 name of an identifier should have alphabetic characters only; no
169 numbers, underscores or dashes.
173 The following example shows three things that may be entered at
178 % movements are non-justified by default
190 At any point in a file, any of the following lexical instructions can
194 @item @code{\version}
195 @item @code{\include}
196 @item @code{\renameinput}
200 @node A single music expression
201 @subsection A single music expression
203 A @code{\score} must contain a single music expression. However,
204 this music expression may be of any size. Recall that music
205 expressions may be included inside other expressions to form
206 larger expressions. All of these examples are single music
207 expressions; note the curly braces @{ @} or angle brackets <<
208 >> at the beginning and ending of the music.
214 @lilypond[ragged-right,verbatim,quote]
221 @lilypond[ragged-right,verbatim,quote]
223 \new Staff { c'4 c' c' c' }
224 \new Staff { d'4 d' d' d' }
232 \new Staff @{ \flute @}
233 \new Staff @{ \oboe @}
236 \new Staff @{ \violinI @}
237 \new Staff @{ \violinII @}
244 @node Including LilyPond files
245 @subsection Including LilyPond files
248 @cindex including files
250 A large project may be split up into separate files. To refer to another
254 \include "otherfile.ly"
257 The line @code{\include "file.ly"} is equivalent to pasting the contents
258 of file.ly into the current file at the place where you have the
259 \include. For example, for a large project you might write separate files
260 for each instrument part and create a ``full score'' file which brings
261 together the individual instrument files.
263 The initialization of LilyPond is done in a number of files that are
264 included by default when you start the program, normally transparent to the
265 user. Run lilypond --verbose to see a list of paths and files that Lily
268 Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where
269 VERSION is in the form ``2.6.1'') are on the path and available to
270 @code{\include}. Files in the
271 current working directory are available to \include, but a file of the same
272 name in LilyPond's installation takes precedence. Files are
273 available to \include from directories in the search path specified as an
274 option when invoking @code{lilypond --include=DIR} which adds DIR to the
277 The @code{\include} statement can use full path information, but with the Unix
278 convention @code{"/"} rather than the DOS/Windows @code{"\"}. For example,
279 if @file{stuff.ly} is located one directory higher than the current working
283 \include "../stuff.ly"
288 @subsection Text encoding
290 LilyPond uses the Pango library to format multi-lingual texts, and
291 does not perform any input-encoding conversions. This means that any
292 text, be it title, lyric text, or musical instruction containing
293 non-ASCII characters, must be utf-8. The easiest way to enter such text is
294 by using a Unicode-aware editor and saving the file with utf-8 encoding. Most
295 popular modern editors have utf-8 support, for example, vim, Emacs,
298 Depending on the fonts installed, the following fragment shows Hebrew
305 @lilypondfile[fontload]{utf-8.ly}
307 The @TeX{} backend does not handle encoding specially at all. Strings
308 in the input are put in the output as-is. Extents of text items in the
309 @TeX{} backend, are determined by reading a file created via the
310 @file{texstr} backend,
313 lilypond -b texstr input/les-nereides.ly
314 latex les-nereides.texstr
317 The last command produces @file{les-nereides.textmetrics}, which is
318 read when you execute
321 lilypond -b tex input/les-nereides.ly
324 Both @file{les-nereides.texstr} and @file{les-nereides.tex} need
325 suitable LaTeX wrappers to load appropriate La@TeX{} packages for
326 interpreting non-ASCII strings.
328 To use a Unicode escape sequence, use
331 #(ly:export (ly:wide-char->utf-8 #x2014))
337 @inputfileref{input/regression,utf-8.ly}
341 @node Titles and headers
342 @section Titles and headers
344 Almost all printed music includes a title and the composer's name;
345 some pieces include a lot more information.
353 @node Creating titles
354 @subsection Creating titles
356 Titles are created for each @code{\score} block, and over a
359 The contents of the titles are taken from the @code{\header} blocks.
360 The header block for a book supports the following
366 The dedicatee of the music, centered at the top of the first page.
370 The title of the music, centered just below the dedication.
374 Subtitle, centered below the title.
378 Subsubtitle, centered below the subtitle.
382 Name of the poet, flush-left below the subtitle.
386 Name of the composer, flush-right below the subtitle.
390 Meter string, flush-left below the poet.
394 Name of the opus, flush-right below the composer.
398 Name of the arranger, flush-right below the opus.
402 Name of the instrument, centered below the arranger. Also
403 centered at the top of pages (other than the first page).
407 Name of the piece, flush-left below the instrument.
409 @cindex page breaks, forcing
412 This forces the title to start on a new page (set to ##t or ##f).
416 Copyright notice, centered at the bottom of the first page. To
417 insert the copyright symbol, see @ref{Text encoding}.
421 Centered at the bottom of the last page.
425 Here is a demonstration of the fields available. Note that you
426 may use any @ref{Text markup} commands in the header.
428 @lilypond[quote,verbatim,line-width=11.0\cm]
431 paper-height = 10.0\cm
436 dedication = "dedicated to me"
437 title = \markup \center-align { "Title first line" "Title second line,
439 subtitle = "the subtitle,"
440 subsubtitle = #(string-append "subsubtitle LilyPond version "
443 composer = \markup \center-align { "composer" \small "(1847-1973)" }
444 texttranslator = "Text Translator"
445 meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
447 arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize
448 #-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }
449 instrument = \markup \bold \italic "instrument"
473 As demonstrated before, you can use multiple @code{\header} blocks.
474 When same fields appear in different blocks, the latter is used.
475 Here is a short example.
479 composer = "Composer"
487 piece = "New piece" % overwrite previous one
492 If you define the @code{\header} inside the @code{\score} block, then
493 normally only the @code{piece} and @code{opus} headers will be printed.
494 Note that the music expression must come before the @code{\header}.
496 @lilypond[quote,verbatim,line-width=11.0\cm]
500 title = "title" % not printed
507 @findex printallheaders
509 You may change this behavior (and print all the headers when defining
510 @code{\header} inside @code{\score}) by using
521 The default footer is empty, except for the first page, where the
522 @code{copyright} field from @code{\header} is inserted, and the last
523 page, where @code{tagline} from @code{\header} is added. The default
524 tagline is ``Music engraving by LilyPond (@var{version})''.@footnote{Nicely
525 printed parts are good PR for us, so please leave the tagline if you
530 @subsection Custom titles
532 A more advanced option is to change the definitions of the following
533 variables in the @code{\paper} block. The init file
534 @file{ly/titling-init.ly} lists the default layout.
537 @findex bookTitleMarkup
538 @item bookTitleMarkup
539 This is the title put over an entire @code{\book} block. Typically,
540 it has the composer and the title of the piece
542 @findex scoreTitleMarkup
543 @item scoreTitleMarkup
544 This is the title put over a @code{\score} block within a
545 @code{\book}. Typically, it has the name of the movement (@code{piece}
548 @findex oddHeaderMarkup
549 @item oddHeaderMarkup
550 This is the page header for odd-numbered pages.
552 @findex evenHeaderMarkup
553 @item evenHeaderMarkup
554 This is the page header for even-numbered pages. If unspecified,
555 the odd header is used instead.
557 By default, headers are defined such that the page number is on the
558 outside edge, and the instrument is centered.
560 @findex oddFooterMarkup
561 @item oddFooterMarkup
562 This is the page footer for odd-numbered pages.
564 @findex evenFotterMarkup
565 @item evenFooterMarkup
566 This is the page footer for even-numbered pages. If unspecified,
567 the odd header is used instead.
569 By default, the footer has the copyright notice on the first, and
570 the tagline on the last page.
580 The following definition will put the title flush left, and the
581 composer flush right on a single line.
585 bookTitleMarkup = \markup {
587 \fromproperty #'header:title
588 \fromproperty #'header:composer
597 The @code{breakbefore=##t} header requires that there is a @code{piece}
598 header as well. It may be used as a normal header, or left blank
599 (@code{=""}) as in the example above, but it must be present.
603 @node Multiple movements
604 @section Multiple movements
606 @cindex bibliographic information
609 @cindex Music engraving by LilyPond
611 A document may contain multiple pieces of music and texts. Examples
612 of these are an etude book, or an orchestral part with multiple
613 movements. Each movement is entered with a @code{\score} block,
621 and texts are entered with a @code{\markup} block,
631 The movements and texts are combined together in a @code{\book} block,
649 The header for each piece of music can be put inside the @code{\score}
650 block. The @code{piece} name from the header will be printed before
651 each movement. The title for the entire book can be put inside the
652 @code{\book}, but if it is not present, the @code{\header} which is at
653 the top of the file is inserted.
655 @cindex Engraved by LilyPond
656 @cindex signature line
661 title = "Eight miniatures"
662 composer = "Igor Stravinsky"
666 \header @{ piece = "Romanze" @}
669 ..text of second verse..
672 ..text of third verse..
676 \header @{ piece = "Menuetto" @}
689 MIDI (Musical Instrument Digital Interface) is a standard for
690 connecting and controlling digital instruments. A MIDI file is a
691 series of notes in a number of tracks. It is not an actual
692 sound file; you need special software to translate between the
693 series of notes and actual sounds.
695 Pieces of music can be converted to MIDI files, so you can listen to
696 what was entered. This is convenient for checking the music; octaves
697 that are off or accidentals that were mistyped stand out very much
698 when listening to the MIDI output.
702 Many musically interesting effects, such as swing, articulation,
703 slurring, etc., are not translated to midi.
705 The midi output allocates a channel for each staff, and one for global
706 settings. Therefore the midi file should not have more than 15 staves
707 (or 14 if you do not use drums). Other staves will remain silent.
709 Not all midi players correctly handle tempo changes in the midi
710 output. Players that are known to work include
711 @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
714 * Creating MIDI files::
716 * MIDI instrument names::
719 @node Creating MIDI files
720 @subsection Creating MIDI files
722 To create a MIDI from a music piece of music, add a @code{\midi} block
723 to a score, for example,
728 \midi @{ \tempo 4=72 @}
732 The tempo is specified using the @code{\tempo} command. In this
733 example the tempo of quarter notes is set to 72 beats per minute.
736 If there is a @code{\midi} command in a @code{\score}, only MIDI will
737 be produced. When notation is needed too, a @code{\layout} block must
743 \midi @{ \tempo 4=72 @}
751 Ties, dynamics, and tempo changes are interpreted. Dynamic marks,
752 crescendi and decrescendi translate into MIDI volume levels. Dynamic
753 marks translate to a fixed fraction of the available MIDI volume
754 range, crescendi and decrescendi make the volume vary linearly between
755 their two extremes. The fractions can be adjusted by
756 @code{dynamicAbsoluteVolumeFunction} in @internalsref{Voice} context.
757 For each type of MIDI instrument, a volume range can be defined. This
758 gives a basic equalizer control, which can enhance the quality of
759 the MIDI output remarkably. The equalizer can be controlled by
760 setting @code{instrumentEqualizer}, or by setting
763 \set Staff.midiMinimumVolume = #0.2
764 \set Staff.midiMaximumVolume = #0.8
767 To remove dynamics from the MIDI output, insert the following lines
768 in the @code{\midi@{@}} section.
775 \remove "Dynamic_performer"
776 \remove "Span_dynamic_performer"
784 Unterminated (de)crescendos will not render properly in the midi file,
785 resulting in silent passages of music. The workaround is to explicitly
786 terminate the (de)crescendo. For example,
793 will not work properly but
804 @subsection MIDI block
808 The MIDI block is analogous to the layout block, but it is somewhat
809 simpler. The @code{\midi} block can contain
813 @item a @code{\tempo} definition, and
814 @item context definitions.
817 A number followed by a period is interpreted as a real number, so
818 for setting the tempo for dotted notes, an extra space should be
819 inserted, for example
822 \midi @{ \tempo 4 . = 120 @}
826 @cindex context definition
828 Context definitions follow precisely the same syntax as within the
829 \layout block. Translation modules for sound are called performers.
830 The contexts for MIDI output are defined in @file{ly/@/performer@/-init@/.ly}.
833 @node MIDI instrument names
834 @subsection MIDI instrument names
836 @cindex instrument names
837 @findex Staff.midiInstrument
839 The MIDI instrument name is set by the @code{Staff.midiInstrument}
840 property. The instrument name should be chosen from the list in
841 @ref{MIDI instruments}.
844 \set Staff.midiInstrument = "glockenspiel"
848 If the selected instrument does not exactly match an instrument from
849 the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
853 @c Yes, this is a cop-out; this info doesn't belong in the Scheme
854 @c chapter, but I'm not certain where to stick it.
855 @c I think I'll eventually split this chapter into a "paper/layout"
856 @c chapter and a "misc issues" chapter. -gp
857 @node Displaying LilyPond notation
858 @section Displaying LilyPond notation
860 @findex \displayLilyMusc
861 Displaying a music expression in LilyPond notation can be
862 done using the music function @code{\displayLilyMusic}. For example,
866 \displayLilyMusic \transpose c a, @{ c e g a bes @}
876 By default, LilyPond will print these messages to the console along
877 with all the other messages. To split up these messages and save
878 the results of @code{\display@{STUFF@}}, redirect the output to
882 lilypond file.ly >display.txt
886 @node Skipping corrected music
887 @section Skipping corrected music
890 @findex skipTypesetting
891 @findex showLastLength
893 When entering or copying music, usually only the music near the end (where
895 are adding notes) is interesting to view and correct. To speed up
896 this correction process, it is possible to skip typesetting of all but
897 the last few measures. This is achieved by putting
900 showLastLength = R1*5
905 in your source file. This will render only the last 5 measures
906 (assuming 4/4 time signature) of every @code{\score} in the input
907 file. For longer pieces, rendering only a small part is often an order
908 of magnitude quicker than rendering it completely
910 Skipping parts of a score can be controlled in a more fine-grained
911 fashion with the property @code{Score.skipTypesetting}. When it is
912 set, no typesetting is performed at all.
914 This property is also used to control output to the MIDI file. Note that
915 it skips all events, including tempo and instrument changes. You have
918 @lilypond[quote,fragment,ragged-right,verbatim]
921 \set Score.skipTypesetting = ##t
923 \set Score.skipTypesetting = ##f
927 In polyphonic music, @code{Score.skipTypesetting} will affect all
928 voices and staves, saving even more time.