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.
284 An identifier, such as
289 This can be used later on in the file by entering @code{\foo}. The
290 name of an identifier should have alphabetic characters only; no
291 numbers, underscores or dashes.
295 The following example shows three things that may be entered at
300 % movements are non-justified by default
312 At any point in a file, any of the following lexical instructions can
316 @item @code{\version}
317 @item @code{\include}
318 @item @code{\sourcefilename}
319 @item @code{\sourcefileline}
324 @node A single music expression
325 @subsection A single music expression
327 A @code{\score} must contain a single music expression. However,
328 this music expression may be of any size. Recall that music
329 expressions may be included inside other expressions to form
330 larger expressions. All of these examples are single music
331 expressions; note the curly braces @{ @} or angle brackets <<
332 >> at the beginning and ending of the music.
338 @lilypond[ragged-right,verbatim,quote]
345 @lilypond[ragged-right,verbatim,quote]
347 \new Staff { c'4 c' c' c' }
348 \new Staff { d'4 d' d' d' }
356 \new Staff @{ \flute @}
357 \new Staff @{ \oboe @}
360 \new Staff @{ \violinI @}
361 \new Staff @{ \violinII @}
368 @node Including LilyPond files
369 @subsection Including LilyPond files
372 @cindex including files
374 A large project may be split up into separate files. To refer to another
378 \include "otherfile.ly"
381 The line @code{\include "file.ly"} is equivalent to pasting the contents
382 of file.ly into the current file at the place where you have the
383 \include. For example, for a large project you might write separate files
384 for each instrument part and create a ``full score'' file which brings
385 together the individual instrument files.
387 The initialization of LilyPond is done in a number of files that are
388 included by default when you start the program, normally transparent to the
389 user. Run lilypond --verbose to see a list of paths and files that Lily
392 Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where
393 VERSION is in the form ``2.6.1'') are on the path and available to
394 @code{\include}. Files in the
395 current working directory are available to \include, but a file of the same
396 name in LilyPond's installation takes precedence. Files are
397 available to \include from directories in the search path specified as an
398 option when invoking @code{lilypond --include=DIR} which adds DIR to the
401 The @code{\include} statement can use full path information, but with the Unix
402 convention @code{"/"} rather than the DOS/Windows @code{"\"}. For example,
403 if @file{stuff.ly} is located one directory higher than the current working
407 \include "../stuff.ly"
412 @subsection Text encoding
414 LilyPond uses the Pango library to format multi-lingual texts, and
415 does not perform any input-encoding conversions. This means that any
416 text, be it title, lyric text, or musical instruction containing
417 non-ASCII characters, must be utf-8. The easiest way to enter such text is
418 by using a Unicode-aware editor and saving the file with utf-8 encoding. Most
419 popular modern editors have utf-8 support, for example, vim, Emacs,
422 @c Currently not working
424 Depending on the fonts installed, the following fragment shows Hebrew
431 @li lypondfile[fontload]{utf-8.ly}
433 The @TeX{} backend does not handle encoding specially at all. Strings
434 in the input are put in the output as-is. Extents of text items in the
435 @TeX{} backend, are determined by reading a file created via the
436 @file{texstr} backend,
439 lilypond -b texstr input/les-nereides.ly
440 latex les-nereides.texstr
443 The last command produces @file{les-nereides.textmetrics}, which is
444 read when you execute
447 lilypond -b tex input/les-nereides.ly
450 Both @file{les-nereides.texstr} and @file{les-nereides.tex} need
451 suitable LaTeX wrappers to load appropriate La@TeX{} packages for
452 interpreting non-ASCII strings.
456 To use a Unicode escape sequence, use
459 #(ly:export (ly:wide-char->utf-8 #x2014))
465 @inputfileref{input/regression,utf-8.ly}
469 @node Titles and headers
470 @section Titles and headers
472 Almost all printed music includes a title and the composer's name;
473 some pieces include a lot more information.
481 @node Creating titles
482 @subsection Creating titles
484 Titles are created for each @code{\score} block, and for the full input
485 file (or @code{\book} block).
487 The contents of the titles are taken from the @code{\header} blocks.
488 The header block for a book supports the following
494 The dedicatee of the music, centered at the top of the first page.
498 The title of the music, centered just below the dedication.
502 Subtitle, centered below the title.
504 @funindex subsubtitle
506 Subsubtitle, centered below the subtitle.
510 Name of the poet, flush-left below the subtitle.
514 Name of the composer, flush-right below the subtitle.
518 Meter string, flush-left below the poet.
522 Name of the opus, flush-right below the composer.
526 Name of the arranger, flush-right below the opus.
530 Name of the instrument, centered below the arranger. Also
531 centered at the top of pages (other than the first page).
535 Name of the piece, flush-left below the instrument.
537 @cindex page breaks, forcing
538 @funindex breakbefore
540 This forces the title to start on a new page (set to ##t or ##f).
544 Copyright notice, centered at the bottom of the first page. To
545 insert the copyright symbol, see @ref{Text encoding}.
549 Centered at the bottom of the last page.
553 Here is a demonstration of the fields available. Note that you
554 may use any @ref{Text markup} commands in the header.
556 @lilypond[quote,verbatim,line-width=11.0\cm]
559 paper-height = 10.0\cm
564 dedication = "dedicated to me"
565 title = \markup \center-align { "Title first line" "Title second line,
567 subtitle = "the subtitle,"
568 subsubtitle = #(string-append "subsubtitle LilyPond version "
571 composer = \markup \center-align { "composer" \small "(1847-1973)" }
572 texttranslator = "Text Translator"
573 meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
575 arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize
576 #-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }
577 instrument = \markup \bold \italic "instrument"
601 As demonstrated before, you can use multiple @code{\header} blocks.
602 When same fields appear in different blocks, the latter is used.
603 Here is a short example.
607 composer = "Composer"
615 piece = "New piece" % overwrite previous one
620 If you define the @code{\header} inside the @code{\score} block, then
621 normally only the @code{piece} and @code{opus} headers will be printed.
622 Note that the music expression must come before the @code{\header}.
624 @lilypond[quote,verbatim,line-width=11.0\cm]
628 title = "title" % not printed
635 @funindex printallheaders
637 You may change this behavior (and print all the headers when defining
638 @code{\header} inside @code{\score}) by using
649 The default footer is empty, except for the first page, where the
650 @code{copyright} field from @code{\header} is inserted, and the last
651 page, where @code{tagline} from @code{\header} is added. The default
652 tagline is ``Music engraving by LilyPond (@var{version})''.@footnote{Nicely
653 printed parts are good PR for us, so please leave the tagline if you
656 Headers may be completely removed by setting them to false.
667 @subsection Custom titles
669 A more advanced option is to change the definitions of the following
670 variables in the @code{\paper} block. The init file
671 @file{ly/titling-init.ly} lists the default layout.
674 @funindex bookTitleMarkup
675 @item bookTitleMarkup
676 This is the title added at the top of the entire output document.
677 Typically, it has the composer and the title of the piece
679 @funindex scoreTitleMarkup
680 @item scoreTitleMarkup
681 This is the title put over a @code{\score} block. Typically, it has
682 the name of the movement (@code{piece} field).
684 @funindex oddHeaderMarkup
685 @item oddHeaderMarkup
686 This is the page header for odd-numbered pages.
688 @funindex evenHeaderMarkup
689 @item evenHeaderMarkup
690 This is the page header for even-numbered pages. If unspecified,
691 the odd header is used instead.
693 By default, headers are defined such that the page number is on the
694 outside edge, and the instrument is centered.
696 @funindex oddFooterMarkup
697 @item oddFooterMarkup
698 This is the page footer for odd-numbered pages.
700 @funindex evenFooterMarkup
701 @item evenFooterMarkup
702 This is the page footer for even-numbered pages. If unspecified,
703 the odd header is used instead.
705 By default, the footer has the copyright notice on the first, and
706 the tagline on the last page.
716 The following definition will put the title flush left, and the
717 composer flush right on a single line.
721 bookTitleMarkup = \markup {
723 \fromproperty #'header:title
724 \fromproperty #'header:composer
738 MIDI (Musical Instrument Digital Interface) is a standard for
739 connecting and controlling digital instruments. A MIDI file is a
740 series of notes in a number of tracks. It is not an actual
741 sound file; you need special software to translate between the
742 series of notes and actual sounds.
744 Pieces of music can be converted to MIDI files, so you can listen to
745 what was entered. This is convenient for checking the music; octaves
746 that are off or accidentals that were mistyped stand out very much
747 when listening to the MIDI output.
751 Many musically interesting effects, such as swing, articulation,
752 slurring, etc., are not translated to midi.
754 The midi output allocates a channel for each staff, and one for global
755 settings. Therefore the midi file should not have more than 15 staves
756 (or 14 if you do not use drums). Other staves will remain silent.
758 Not all midi players correctly handle tempo changes in the midi
759 output. Players that are known to work include
760 @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
763 * Creating MIDI files::
765 * MIDI instrument names::
768 @node Creating MIDI files
769 @subsection Creating MIDI files
771 To create a MIDI from a music piece of music, add a @code{\midi} block
772 to a score, for example,
780 tempoWholesPerMinute = #(ly:make-moment 72 4)
786 The tempo can be specified using the @code{\tempo} command within the
787 actual music, see @ref{Metronome marks}. An alternative, which does not
788 result in a metronome mark in the printed score, is shown in the example
789 above. In this example the tempo of quarter notes is set to 72 beats per
792 specification can not take dotted note lengths as an argument. In this
793 case, break the dotted notes into smaller units. For example, a tempo
794 of 90 dotted quarter notes per minute can be specified as 270 eighth
798 tempoWholesPerMinute = #(ly:make-moment 270 8)
801 If there is a @code{\midi} command in a @code{\score}, only MIDI will
802 be produced. When notation is needed too, a @code{\layout} block must
816 Ties, dynamics, and tempo changes are interpreted. Dynamic marks,
817 crescendi and decrescendi translate into MIDI volume levels. Dynamic
818 marks translate to a fixed fraction of the available MIDI volume
819 range, crescendi and decrescendi make the volume vary linearly between
820 their two extremes. The fractions can be adjusted by
821 @code{dynamicAbsoluteVolumeFunction} in @internalsref{Voice} context.
822 For each type of MIDI instrument, a volume range can be defined. This
823 gives a basic equalizer control, which can enhance the quality of
824 the MIDI output remarkably. The equalizer can be controlled by
825 setting @code{instrumentEqualizer}, or by setting
828 \set Staff.midiMinimumVolume = #0.2
829 \set Staff.midiMaximumVolume = #0.8
832 To remove dynamics from the MIDI output, insert the following lines
833 in the @code{\midi@{@}} section.
840 \remove "Dynamic_performer"
841 \remove "Span_dynamic_performer"
849 Unterminated (de)crescendos will not render properly in the midi file,
850 resulting in silent passages of music. The workaround is to explicitly
851 terminate the (de)crescendo. For example,
858 will not work properly but
869 @subsection MIDI block
873 The MIDI block is analogous to the layout block, but it is somewhat
874 simpler. The @code{\midi} block is similar to @code{\layout}. It can contain
878 @cindex context definition
880 Context definitions follow precisely the same syntax as within the
881 \layout block. Translation modules for sound are called performers.
882 The contexts for MIDI output are defined in @file{ly/@/performer@/-init@/.ly}.
885 @node MIDI instrument names
886 @subsection MIDI instrument names
888 @cindex instrument names
889 @funindex Staff.midiInstrument
891 The MIDI instrument name is set by the @code{Staff.midiInstrument}
892 property. The instrument name should be chosen from the list in
893 @ref{MIDI instruments}.
896 \set Staff.midiInstrument = "glockenspiel"
900 If the selected instrument does not exactly match an instrument from
901 the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
905 @c Yes, this is a cop-out; this info doesn't belong in the Scheme
906 @c chapter, but I'm not certain where to stick it.
907 @c I think I'll eventually split this chapter into a "paper/layout"
908 @c chapter and a "misc issues" chapter. -gp
909 @node Displaying LilyPond notation
910 @section Displaying LilyPond notation
912 @funindex \displayLilyMusc
913 Displaying a music expression in LilyPond notation can be
914 done using the music function @code{\displayLilyMusic}. For example,
918 \displayLilyMusic \transpose c a, @{ c e g a bes @}
928 By default, LilyPond will print these messages to the console along
929 with all the other messages. To split up these messages and save
930 the results of @code{\display@{STUFF@}}, redirect the output to
934 lilypond file.ly >display.txt
938 @node Skipping corrected music
939 @section Skipping corrected music
942 @funindex skipTypesetting
943 @funindex showLastLength
945 When entering or copying music, usually only the music near the end (where
947 are adding notes) is interesting to view and correct. To speed up
948 this correction process, it is possible to skip typesetting of all but
949 the last few measures. This is achieved by putting
952 showLastLength = R1*5
957 in your source file. This will render only the last 5 measures
958 (assuming 4/4 time signature) of every @code{\score} in the input
959 file. For longer pieces, rendering only a small part is often an order
960 of magnitude quicker than rendering it completely
962 Skipping parts of a score can be controlled in a more fine-grained
963 fashion with the property @code{Score.skipTypesetting}. When it is
964 set, no typesetting is performed at all.
966 This property is also used to control output to the MIDI file. Note that
967 it skips all events, including tempo and instrument changes. You have
970 @lilypond[quote,fragment,ragged-right,verbatim]
973 \set Score.skipTypesetting = ##t
975 \set Score.skipTypesetting = ##f
979 In polyphonic music, @code{Score.skipTypesetting} will affect all
980 voices and staves, saving even more time.