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::
32 * Extracting fragments of notation::
34 * A single music expression::
35 * Including LilyPond files::
40 @node File structure (introduction)
41 @subsection File structure (introduction)
43 A basic example of a lilypond input file is
48 @{ @} % this is a single music expression;
49 % all the music goes in here.
57 There are many variations of this basic pattern, but this
58 example serves as a useful starting place.
60 The major part of this manual is concerned with entering various
61 forms of music in LilyPond. However, many music expressions are not
62 valid input on their own, for example, a @code{.ly} file containing
69 will result in a parsing error. Instead, music should be inside other
70 expressions, which may be put in a file by themselves. Such
71 expressions are called toplevel expressions. The next section enumerates
75 @node Multiple scores in a book
76 @subsection Multiple scores in a book
79 @cindex movements, multiple
81 A document may contain multiple pieces of music and texts. Examples
82 of these are an etude book, or an orchestral part with multiple
83 movements. Each movement is entered with a @code{\score} block,
91 and texts are entered with a @code{\markup} block,
101 All the movements and texts which appear in the same @code{.ly} file
102 will normally be typeset in the form of a single output file.
116 However, if you want multiple output files from the same @code{.ly}
117 file, then you can add multiple @code{\book} blocks, where each such
118 @code{\book} block will result in a separate output. If you do not
119 specify any @code{\book} block in the file, LilyPond will implicitly
120 treat the full file as a single @code{\book} block, see @ref{File
121 structure}. One important exception is within lilypond-book documents,
122 where you explicitly have to add a @code{\book} block, otherwise only
123 the first @code{\score} or @code{\markup} will appear in the output.
125 The header for each piece of music can be put inside the @code{\score}
126 block. The @code{piece} name from the header will be printed before
127 each movement. The title for the entire book can be put inside the
128 @code{\book}, but if it is not present, the @code{\header} which is at
129 the top of the file is inserted.
133 title = "Eight miniatures"
134 composer = "Igor Stravinsky"
138 \header @{ piece = "Romanze" @}
141 ..text of second verse..
144 ..text of third verse..
148 \header @{ piece = "Menuetto" @}
152 @node Extracting fragments of notation
153 @subsection Extracting fragments of notation
155 It is possible to quote small fragments of a large score directly from
156 the output. This can be compared to clipping a piece of a paper score
159 This is done by definining the measures that need to be cut out
160 separately. For example, including the following definition
168 (make-rhythmic-location 5 1 2)
169 (make-rhythmic-location 7 3 4)))
174 will extract a fragment starting halfway the fifth measure, ending in
175 the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note
176 in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7.
178 More clip regions can be defined by adding more pairs of
179 rhythmic-locations to the list.
181 In order to use this feature, LilyPond must be invoked with
182 @code{-dclip-systems}. The clips are output as EPS files, and are
183 converted to PDF and PNG if these formats are switched on as well.
185 For more information on output formats, see @ref{Invoking lilypond}.
189 Examples: @inputfileref{input/regression/,clip-systems.ly}
193 @subsection File structure
195 A @code{.ly} file contains any number of toplevel expressions, where a
196 toplevel expression is one of the following
200 An output definition, such as @code{\paper}, @code{\midi}, and
201 @code{\layout}. Such a definition at the toplevel changes the default
202 settings for the block entered.
205 A direct scheme expression, such as
206 @code{#(set-default-paper-size "a7" 'landscape)} or
207 @code{#(ly:set-option 'point-and-click #f)}.
210 A @code{\header} block. This sets the global header block. This
211 is the block containing the definitions for book-wide settings, like
212 composer, title, etc.
215 A @code{\score} block. This score will be collected with other
216 toplevel scores, and combined as a single @code{\book}.
218 This behavior can be changed by setting the variable
219 @code{toplevel-score-handler} at toplevel. The default handler is
220 defined in the init file @file{scm/@/lily@/.scm}.
222 The @code{\score} must begin with a music expression, and may
223 contain only one music expression.
226 A @code{\book} block logically combines multiple movements
227 (i.e., multiple @code{\score} blocks) in one document. If there are
228 a number of @code{\scores}, one output file will be created for
229 each @code{\book} block, in which all corresponding movements are
230 concatenated. The only reason to explicitly specify @code{\book} blocks
231 in a @code{.ly} file is if you wish multiple output files from a single
232 input file. One exception is within lilypond-book documents, where you
233 explicitly have to add a @code{\book} block if you want more than a
234 single @code{\score} or @code{\markup} in the same example.
236 This behavior can be changed by setting the variable
237 @code{toplevel-book-handler} at toplevel. The default handler is
238 defined in the init file @file{scm/@/lily@/.scm}.
241 A compound music expression, such as
246 This will add the piece in a @code{\score} and format it in a
247 single book together with all other toplevel @code{\score}s and music
248 expressions. In other words, a file containing only the above
249 music expression will be translated into
265 This behavior can be changed by setting the variable
266 @code{toplevel-music-handler} at toplevel. The default handler is
267 defined in the init file @file{scm/@/lily@/.scm}.
270 A markup text, a verse for example
273 2. The first line verse two.
277 Markup texts are rendered above, between or below the scores or music
278 expressions, wherever they appear.
281 An identifier, such as
286 This can be used later on in the file by entering @code{\foo}. The
287 name of an identifier should have alphabetic characters only; no
288 numbers, underscores or dashes.
292 The following example shows three things that may be entered at
297 % movements are non-justified by default
309 At any point in a file, any of the following lexical instructions can
313 @item @code{\version}
314 @item @code{\include}
315 @item @code{\sourcefilename}
316 @item @code{\sourcefileline}
321 @node A single music expression
322 @subsection A single music expression
324 A @code{\score} must contain a single music expression. However,
325 this music expression may be of any size. Recall that music
326 expressions may be included inside other expressions to form
327 larger expressions. All of these examples are single music
328 expressions; note the curly braces @{ @} or angle brackets <<
329 >> at the beginning and ending of the music.
335 @lilypond[ragged-right,verbatim,quote]
342 @lilypond[ragged-right,verbatim,quote]
344 \new Staff { c'4 c' c' c' }
345 \new Staff { d'4 d' d' d' }
353 \new Staff @{ \flute @}
354 \new Staff @{ \oboe @}
357 \new Staff @{ \violinI @}
358 \new Staff @{ \violinII @}
365 @node Including LilyPond files
366 @subsection Including LilyPond files
369 @cindex including files
371 A large project may be split up into separate files. To refer to another
375 \include "otherfile.ly"
378 The line @code{\include "file.ly"} is equivalent to pasting the contents
379 of file.ly into the current file at the place where you have the
380 \include. For example, for a large project you might write separate files
381 for each instrument part and create a ``full score'' file which brings
382 together the individual instrument files.
384 The initialization of LilyPond is done in a number of files that are
385 included by default when you start the program, normally transparent to the
386 user. Run lilypond --verbose to see a list of paths and files that Lily
389 Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where
390 VERSION is in the form ``2.6.1'') are on the path and available to
391 @code{\include}. Files in the
392 current working directory are available to \include, but a file of the same
393 name in LilyPond's installation takes precedence. Files are
394 available to \include from directories in the search path specified as an
395 option when invoking @code{lilypond --include=DIR} which adds DIR to the
398 The @code{\include} statement can use full path information, but with the Unix
399 convention @code{"/"} rather than the DOS/Windows @code{"\"}. For example,
400 if @file{stuff.ly} is located one directory higher than the current working
404 \include "../stuff.ly"
409 @subsection Text encoding
411 LilyPond uses the Pango library to format multi-lingual texts, and
412 does not perform any input-encoding conversions. This means that any
413 text, be it title, lyric text, or musical instruction containing
414 non-ASCII characters, must be utf-8. The easiest way to enter such text is
415 by using a Unicode-aware editor and saving the file with utf-8 encoding. Most
416 popular modern editors have utf-8 support, for example, vim, Emacs,
419 @c Currently not working
421 Depending on the fonts installed, the following fragment shows Hebrew
428 @li lypondfile[fontload]{utf-8.ly}
430 The @TeX{} backend does not handle encoding specially at all. Strings
431 in the input are put in the output as-is. Extents of text items in the
432 @TeX{} backend, are determined by reading a file created via the
433 @file{texstr} backend,
436 lilypond -b texstr input/les-nereides.ly
437 latex les-nereides.texstr
440 The last command produces @file{les-nereides.textmetrics}, which is
441 read when you execute
444 lilypond -b tex input/les-nereides.ly
447 Both @file{les-nereides.texstr} and @file{les-nereides.tex} need
448 suitable LaTeX wrappers to load appropriate La@TeX{} packages for
449 interpreting non-ASCII strings.
453 To use a Unicode escape sequence, use
456 #(ly:export (ly:wide-char->utf-8 #x2014))
462 @inputfileref{input/regression,utf-8.ly}
466 @node Titles and headers
467 @section Titles and headers
469 Almost all printed music includes a title and the composer's name;
470 some pieces include a lot more information.
478 @node Creating titles
479 @subsection Creating titles
481 Titles are created for each @code{\score} block, and for the full input
482 file (or @code{\book} block).
484 The contents of the titles are taken from the @code{\header} blocks.
485 The header block for a book supports the following
491 The dedicatee of the music, centered at the top of the first page.
495 The title of the music, centered just below the dedication.
499 Subtitle, centered below the title.
501 @funindex subsubtitle
503 Subsubtitle, centered below the subtitle.
507 Name of the poet, flush-left below the subtitle.
511 Name of the composer, flush-right below the subtitle.
515 Meter string, flush-left below the poet.
519 Name of the opus, flush-right below the composer.
523 Name of the arranger, flush-right below the opus.
527 Name of the instrument, centered below the arranger. Also
528 centered at the top of pages (other than the first page).
532 Name of the piece, flush-left below the instrument.
534 @cindex page breaks, forcing
535 @funindex breakbefore
537 This forces the title to start on a new page (set to ##t or ##f).
541 Copyright notice, centered at the bottom of the first page. To
542 insert the copyright symbol, see @ref{Text encoding}.
546 Centered at the bottom of the last page.
550 Here is a demonstration of the fields available. Note that you
551 may use any @ref{Text markup} commands in the header.
553 @lilypond[quote,verbatim,line-width=11.0\cm]
556 paper-height = 10.0\cm
561 dedication = "dedicated to me"
562 title = \markup \center-align { "Title first line" "Title second line,
564 subtitle = "the subtitle,"
565 subsubtitle = #(string-append "subsubtitle LilyPond version "
568 composer = \markup \center-align { "composer" \small "(1847-1973)" }
569 texttranslator = "Text Translator"
570 meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
572 arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize
573 #-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }
574 instrument = \markup \bold \italic "instrument"
598 As demonstrated before, you can use multiple @code{\header} blocks.
599 When same fields appear in different blocks, the latter is used.
600 Here is a short example.
604 composer = "Composer"
612 piece = "New piece" % overwrite previous one
617 If you define the @code{\header} inside the @code{\score} block, then
618 normally only the @code{piece} and @code{opus} headers will be printed.
619 Note that the music expression must come before the @code{\header}.
621 @lilypond[quote,verbatim,line-width=11.0\cm]
625 title = "title" % not printed
632 @funindex printallheaders
634 You may change this behavior (and print all the headers when defining
635 @code{\header} inside @code{\score}) by using
646 The default footer is empty, except for the first page, where the
647 @code{copyright} field from @code{\header} is inserted, and the last
648 page, where @code{tagline} from @code{\header} is added. The default
649 tagline is ``Music engraving by LilyPond (@var{version})''.@footnote{Nicely
650 printed parts are good PR for us, so please leave the tagline if you
653 Headers may be completely removed by setting them to false.
664 @subsection Custom titles
666 A more advanced option is to change the definitions of the following
667 variables in the @code{\paper} block. The init file
668 @file{ly/titling-init.ly} lists the default layout.
671 @funindex bookTitleMarkup
672 @item bookTitleMarkup
673 This is the title added at the top of the entire output document.
674 Typically, it has the composer and the title of the piece
676 @funindex scoreTitleMarkup
677 @item scoreTitleMarkup
678 This is the title put over a @code{\score} block. Typically, it has
679 the name of the movement (@code{piece} field).
681 @funindex oddHeaderMarkup
682 @item oddHeaderMarkup
683 This is the page header for odd-numbered pages.
685 @funindex evenHeaderMarkup
686 @item evenHeaderMarkup
687 This is the page header for even-numbered pages. If unspecified,
688 the odd header is used instead.
690 By default, headers are defined such that the page number is on the
691 outside edge, and the instrument is centered.
693 @funindex oddFooterMarkup
694 @item oddFooterMarkup
695 This is the page footer for odd-numbered pages.
697 @funindex evenFooterMarkup
698 @item evenFooterMarkup
699 This is the page footer for even-numbered pages. If unspecified,
700 the odd header is used instead.
702 By default, the footer has the copyright notice on the first, and
703 the tagline on the last page.
713 The following definition will put the title flush left, and the
714 composer flush right on a single line.
718 bookTitleMarkup = \markup {
720 \fromproperty #'header:title
721 \fromproperty #'header:composer
735 MIDI (Musical Instrument Digital Interface) is a standard for
736 connecting and controlling digital instruments. A MIDI file is a
737 series of notes in a number of tracks. It is not an actual
738 sound file; you need special software to translate between the
739 series of notes and actual sounds.
741 Pieces of music can be converted to MIDI files, so you can listen to
742 what was entered. This is convenient for checking the music; octaves
743 that are off or accidentals that were mistyped stand out very much
744 when listening to the MIDI output.
748 Many musically interesting effects, such as swing, articulation,
749 slurring, etc., are not translated to midi.
751 The midi output allocates a channel for each staff, and one for global
752 settings. Therefore the midi file should not have more than 15 staves
753 (or 14 if you do not use drums). Other staves will remain silent.
755 Not all midi players correctly handle tempo changes in the midi
756 output. Players that are known to work include
757 @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
760 * Creating MIDI files::
762 * MIDI instrument names::
765 @node Creating MIDI files
766 @subsection Creating MIDI files
768 To create a MIDI from a music piece of music, add a @code{\midi} block
769 to a score, for example,
777 tempoWholesPerMinute = #(ly:make-moment 72 4)
783 The tempo is specified using the @code{\tempo} command. In this
784 example the tempo of quarter notes is set to 72 beats per minute.
787 If there is a @code{\midi} command in a @code{\score}, only MIDI will
788 be produced. When notation is needed too, a @code{\layout} block must
802 Ties, dynamics, and tempo changes are interpreted. Dynamic marks,
803 crescendi and decrescendi translate into MIDI volume levels. Dynamic
804 marks translate to a fixed fraction of the available MIDI volume
805 range, crescendi and decrescendi make the volume vary linearly between
806 their two extremes. The fractions can be adjusted by
807 @code{dynamicAbsoluteVolumeFunction} in @internalsref{Voice} context.
808 For each type of MIDI instrument, a volume range can be defined. This
809 gives a basic equalizer control, which can enhance the quality of
810 the MIDI output remarkably. The equalizer can be controlled by
811 setting @code{instrumentEqualizer}, or by setting
814 \set Staff.midiMinimumVolume = #0.2
815 \set Staff.midiMaximumVolume = #0.8
818 To remove dynamics from the MIDI output, insert the following lines
819 in the @code{\midi@{@}} section.
826 \remove "Dynamic_performer"
827 \remove "Span_dynamic_performer"
835 Unterminated (de)crescendos will not render properly in the midi file,
836 resulting in silent passages of music. The workaround is to explicitly
837 terminate the (de)crescendo. For example,
844 will not work properly but
855 @subsection MIDI block
859 The MIDI block is analogous to the layout block, but it is somewhat
860 simpler. The @code{\midi} block is similar to @code{\layout}. It can contain
864 @cindex context definition
866 Context definitions follow precisely the same syntax as within the
867 \layout block. Translation modules for sound are called performers.
868 The contexts for MIDI output are defined in @file{ly/@/performer@/-init@/.ly}.
871 @node MIDI instrument names
872 @subsection MIDI instrument names
874 @cindex instrument names
875 @funindex Staff.midiInstrument
877 The MIDI instrument name is set by the @code{Staff.midiInstrument}
878 property. The instrument name should be chosen from the list in
879 @ref{MIDI instruments}.
882 \set Staff.midiInstrument = "glockenspiel"
886 If the selected instrument does not exactly match an instrument from
887 the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
891 @c Yes, this is a cop-out; this info doesn't belong in the Scheme
892 @c chapter, but I'm not certain where to stick it.
893 @c I think I'll eventually split this chapter into a "paper/layout"
894 @c chapter and a "misc issues" chapter. -gp
895 @node Displaying LilyPond notation
896 @section Displaying LilyPond notation
898 @funindex \displayLilyMusc
899 Displaying a music expression in LilyPond notation can be
900 done using the music function @code{\displayLilyMusic}. For example,
904 \displayLilyMusic \transpose c a, @{ c e g a bes @}
914 By default, LilyPond will print these messages to the console along
915 with all the other messages. To split up these messages and save
916 the results of @code{\display@{STUFF@}}, redirect the output to
920 lilypond file.ly >display.txt
924 @node Skipping corrected music
925 @section Skipping corrected music
928 @funindex skipTypesetting
929 @funindex showLastLength
931 When entering or copying music, usually only the music near the end (where
933 are adding notes) is interesting to view and correct. To speed up
934 this correction process, it is possible to skip typesetting of all but
935 the last few measures. This is achieved by putting
938 showLastLength = R1*5
943 in your source file. This will render only the last 5 measures
944 (assuming 4/4 time signature) of every @code{\score} in the input
945 file. For longer pieces, rendering only a small part is often an order
946 of magnitude quicker than rendering it completely
948 Skipping parts of a score can be controlled in a more fine-grained
949 fashion with the property @code{Score.skipTypesetting}. When it is
950 set, no typesetting is performed at all.
952 This property is also used to control output to the MIDI file. Note that
953 it skips all events, including tempo and instrument changes. You have
956 @lilypond[quote,fragment,ragged-right,verbatim]
959 \set Score.skipTypesetting = ##t
961 \set Score.skipTypesetting = ##f
965 In polyphonic music, @code{Score.skipTypesetting} will affect all
966 voices and staves, saving even more time.