1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond.tely
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. See TRANSLATION for details.
10 @c A menu is needed before every deeper *section nesting of @node's; run
11 @c M-x texinfo-all-menus-update
12 @c to automatically fill in these menus before saving changes
14 @node Non-musical notation
15 @chapter Non-musical notation
17 This section deals with general lilypond issues, rather than
22 * Titles and headers::
24 * Displaying LilyPond notation::
25 * Skipping corrected music::
32 The main format of input for LilyPond are text files. By convention,
33 these files end with ``@code{.ly}''.
36 * File structure (introduction)::
37 * Multiple scores in a book::
38 * Extracting fragments of notation::
40 * A single music expression::
41 * Including LilyPond files::
46 @node File structure (introduction)
47 @subsection File structure (introduction)
49 A basic example of a lilypond input file is
54 @{ @} % this is a single music expression;
55 % all the music goes in here.
63 There are many variations of this basic pattern, but this
64 example serves as a useful starting place.
66 The major part of this manual is concerned with entering various
67 forms of music in LilyPond. However, many music expressions are not
68 valid input on their own, for example, a @code{.ly} file containing
75 will result in a parsing error. Instead, music should be inside other
76 expressions, which may be put in a file by themselves. Such
77 expressions are called toplevel expressions. The next section enumerates
81 @node Multiple scores in a book
82 @subsection Multiple scores in a book
85 @cindex movements, multiple
87 A document may contain multiple pieces of music and texts. Examples
88 of these are an etude book, or an orchestral part with multiple
89 movements. Each movement is entered with a @code{\score} block,
97 and texts are entered with a @code{\markup} block,
107 All the movements and texts which appear in the same @code{.ly} file
108 will normally be typeset in the form of a single output file.
122 However, if you want multiple output files from the same @code{.ly}
123 file, then you can add multiple @code{\book} blocks, where each such
124 @code{\book} block will result in a separate output. If you do not
125 specify any @code{\book} block in the file, LilyPond will implicitly
126 treat the full file as a single @code{\book} block, see @ref{File
127 structure}. One important exception is within lilypond-book documents,
128 where you explicitly have to add a @code{\book} block, otherwise only
129 the first @code{\score} or @code{\markup} will appear in the output.
131 The header for each piece of music can be put inside the @code{\score}
132 block. The @code{piece} name from the header will be printed before
133 each movement. The title for the entire book can be put inside the
134 @code{\book}, but if it is not present, the @code{\header} which is at
135 the top of the file is inserted.
139 title = "Eight miniatures"
140 composer = "Igor Stravinsky"
144 \header @{ piece = "Romanze" @}
147 ..text of second verse..
150 ..text of third verse..
154 \header @{ piece = "Menuetto" @}
158 @node Extracting fragments of notation
159 @subsection Extracting fragments of notation
161 It is possible to quote small fragments of a large score directly from
162 the output. This can be compared to clipping a piece of a paper score
165 This is done by definining the measures that need to be cut out
166 separately. For example, including the following definition
174 (make-rhythmic-location 5 1 2)
175 (make-rhythmic-location 7 3 4)))
180 will extract a fragment starting halfway the fifth measure, ending in
181 the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note
182 in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7.
184 More clip regions can be defined by adding more pairs of
185 rhythmic-locations to the list.
187 In order to use this feature, LilyPond must be invoked with
188 @code{-dclip-systems}. The clips are output as EPS files, and are
189 converted to PDF and PNG if these formats are switched on as well.
191 For more information on output formats, see @ref{Invoking lilypond}.
195 Examples: @inputfileref{input/regression/,clip-systems.ly}
199 @subsection File structure
201 A @code{.ly} file contains any number of toplevel expressions, where a
202 toplevel expression is one of the following
206 An output definition, such as @code{\paper}, @code{\midi}, and
207 @code{\layout}. Such a definition at the toplevel changes the default
208 settings for the block entered.
211 A direct scheme expression, such as
212 @code{#(set-default-paper-size "a7" 'landscape)} or
213 @code{#(ly:set-option 'point-and-click #f)}.
216 A @code{\header} block. This sets the global header block. This
217 is the block containing the definitions for book-wide settings, like
218 composer, title, etc.
221 A @code{\score} block. This score will be collected with other
222 toplevel scores, and combined as a single @code{\book}.
224 This behavior can be changed by setting the variable
225 @code{toplevel-score-handler} at toplevel. The default handler is
226 defined in the init file @file{scm/@/lily@/.scm}.
228 The @code{\score} must begin with a music expression, and may
229 contain only one music expression.
232 A @code{\book} block logically combines multiple movements
233 (i.e., multiple @code{\score} blocks) in one document. If there are
234 a number of @code{\scores}, one output file will be created for
235 each @code{\book} block, in which all corresponding movements are
236 concatenated. The only reason to explicitly specify @code{\book} blocks
237 in a @code{.ly} file is if you wish multiple output files from a single
238 input file. One exception is within lilypond-book documents, where you
239 explicitly have to add a @code{\book} block if you want more than a
240 single @code{\score} or @code{\markup} in the same example.
242 This behavior can be changed by setting the variable
243 @code{toplevel-book-handler} at toplevel. The default handler is
244 defined in the init file @file{scm/@/lily@/.scm}.
247 A compound music expression, such as
252 This will add the piece in a @code{\score} and format it in a
253 single book together with all other toplevel @code{\score}s and music
254 expressions. In other words, a file containing only the above
255 music expression will be translated into
271 This behavior can be changed by setting the variable
272 @code{toplevel-music-handler} at toplevel. The default handler is
273 defined in the init file @file{scm/@/lily@/.scm}.
276 A markup text, a verse for example
279 2. The first line verse two.
283 Markup texts are rendered above, between or below the scores or music
284 expressions, wherever they appear.
290 An identifier, such as
295 This can be used later on in the file by entering @code{\foo}. The
296 name of an identifier should have alphabetic characters only; no
297 numbers, underscores or dashes.
301 The following example shows three things that may be entered at
306 % movements are non-justified by default
318 At any point in a file, any of the following lexical instructions can
322 @item @code{\version}
323 @item @code{\include}
324 @item @code{\sourcefilename}
325 @item @code{\sourcefileline}
330 @node A single music expression
331 @subsection A single music expression
333 A @code{\score} must contain a single music expression. However,
334 this music expression may be of any size. Recall that music
335 expressions may be included inside other expressions to form
336 larger expressions. All of these examples are single music
337 expressions; note the curly braces @{ @} or angle brackets <<
338 >> at the beginning and ending of the music.
344 @lilypond[ragged-right,verbatim,quote]
351 @lilypond[ragged-right,verbatim,quote]
353 \new Staff { c'4 c' c' c' }
354 \new Staff { d'4 d' d' d' }
362 \new Staff @{ \flute @}
363 \new Staff @{ \oboe @}
366 \new Staff @{ \violinI @}
367 \new Staff @{ \violinII @}
374 @node Including LilyPond files
375 @subsection Including LilyPond files
378 @cindex including files
380 A large project may be split up into separate files. To refer to another
384 \include "otherfile.ly"
387 The line @code{\include "file.ly"} is equivalent to pasting the contents
388 of file.ly into the current file at the place where you have the
389 \include. For example, for a large project you might write separate files
390 for each instrument part and create a ``full score'' file which brings
391 together the individual instrument files.
393 The initialization of LilyPond is done in a number of files that are
394 included by default when you start the program, normally transparent to the
395 user. Run lilypond --verbose to see a list of paths and files that Lily
398 Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where
399 VERSION is in the form ``2.6.1'') are on the path and available to
400 @code{\include}. Files in the
401 current working directory are available to \include, but a file of the same
402 name in LilyPond's installation takes precedence. Files are
403 available to \include from directories in the search path specified as an
404 option when invoking @code{lilypond --include=DIR} which adds DIR to the
407 The @code{\include} statement can use full path information, but with the Unix
408 convention @code{"/"} rather than the DOS/Windows @code{"\"}. For example,
409 if @file{stuff.ly} is located one directory higher than the current working
413 \include "../stuff.ly"
418 @subsection Text encoding
420 LilyPond uses the Pango library to format multi-lingual texts, and
421 does not perform any input-encoding conversions. This means that any
422 text, be it title, lyric text, or musical instruction containing
423 non-ASCII characters, must be utf-8. The easiest way to enter such text is
424 by using a Unicode-aware editor and saving the file with utf-8 encoding. Most
425 popular modern editors have utf-8 support, for example, vim, Emacs,
428 @c Currently not working
430 Depending on the fonts installed, the following fragment shows Hebrew
437 @li lypondfile[fontload]{utf-8.ly}
439 The @TeX{} backend does not handle encoding specially at all. Strings
440 in the input are put in the output as-is. Extents of text items in the
441 @TeX{} backend, are determined by reading a file created via the
442 @file{texstr} backend,
445 lilypond -b texstr input/les-nereides.ly
446 latex les-nereides.texstr
449 The last command produces @file{les-nereides.textmetrics}, which is
450 read when you execute
453 lilypond -b tex input/les-nereides.ly
456 Both @file{les-nereides.texstr} and @file{les-nereides.tex} need
457 suitable LaTeX wrappers to load appropriate La@TeX{} packages for
458 interpreting non-ASCII strings.
462 To use a Unicode escape sequence, use
465 #(ly:export (ly:wide-char->utf-8 #x2014))
471 @inputfileref{input/regression,utf-8.ly}
475 @node Titles and headers
476 @section Titles and headers
478 Almost all printed music includes a title and the composer's name;
479 some pieces include a lot more information.
487 @node Creating titles
488 @subsection Creating titles
490 Titles are created for each @code{\score} block, and for the full input
491 file (or @code{\book} block).
493 The contents of the titles are taken from the @code{\header} blocks.
494 The header block for a book supports the following
500 The dedicatee of the music, centered at the top of the first page.
504 The title of the music, centered just below the dedication.
508 Subtitle, centered below the title.
510 @funindex subsubtitle
512 Subsubtitle, centered below the subtitle.
516 Name of the poet, flush-left below the subtitle.
520 Name of the composer, flush-right below the subtitle.
524 Meter string, flush-left below the poet.
528 Name of the opus, flush-right below the composer.
532 Name of the arranger, flush-right below the opus.
536 Name of the instrument, centered below the arranger. Also
537 centered at the top of pages (other than the first page).
541 Name of the piece, flush-left below the instrument.
543 @cindex page breaks, forcing
544 @funindex breakbefore
546 This forces the title to start on a new page (set to ##t or ##f).
550 Copyright notice, centered at the bottom of the first page. To
551 insert the copyright symbol, see @ref{Text encoding}.
555 Centered at the bottom of the last page.
559 Here is a demonstration of the fields available. Note that you
560 may use any @ref{Text markup} commands in the header.
562 @lilypond[quote,verbatim,line-width=11.0\cm]
565 paper-height = 10.0\cm
570 dedication = "dedicated to me"
571 title = \markup \center-align { "Title first line" "Title second line,
573 subtitle = "the subtitle,"
574 subsubtitle = #(string-append "subsubtitle LilyPond version "
577 composer = \markup \center-align { "composer" \small "(1847-1973)" }
578 texttranslator = "Text Translator"
579 meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
581 arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize
582 #-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }
583 instrument = \markup \bold \italic "instrument"
607 As demonstrated before, you can use multiple @code{\header} blocks.
608 When same fields appear in different blocks, the latter is used.
609 Here is a short example.
613 composer = "Composer"
621 piece = "New piece" % overwrite previous one
626 If you define the @code{\header} inside the @code{\score} block, then
627 normally only the @code{piece} and @code{opus} headers will be printed.
628 Note that the music expression must come before the @code{\header}.
630 @lilypond[quote,verbatim,line-width=11.0\cm]
634 title = "title" % not printed
641 @funindex printallheaders
643 You may change this behavior (and print all the headers when defining
644 @code{\header} inside @code{\score}) by using
655 The default footer is empty, except for the first page, where the
656 @code{copyright} field from @code{\header} is inserted, and the last
657 page, where @code{tagline} from @code{\header} is added. The default
658 tagline is ``Music engraving by LilyPond (@var{version})''.@footnote{Nicely
659 printed parts are good PR for us, so please leave the tagline if you
662 Headers may be completely removed by setting them to false.
673 @subsection Custom titles
675 A more advanced option is to change the definitions of the following
676 variables in the @code{\paper} block. The init file
677 @file{ly/titling-init.ly} lists the default layout.
680 @funindex bookTitleMarkup
681 @item bookTitleMarkup
682 This is the title added at the top of the entire output document.
683 Typically, it has the composer and the title of the piece
685 @funindex scoreTitleMarkup
686 @item scoreTitleMarkup
687 This is the title put over a @code{\score} block. Typically, it has
688 the name of the movement (@code{piece} field).
690 @funindex oddHeaderMarkup
691 @item oddHeaderMarkup
692 This is the page header for odd-numbered pages.
694 @funindex evenHeaderMarkup
695 @item evenHeaderMarkup
696 This is the page header for even-numbered pages. If unspecified,
697 the odd header is used instead.
699 By default, headers are defined such that the page number is on the
700 outside edge, and the instrument is centered.
702 @funindex oddFooterMarkup
703 @item oddFooterMarkup
704 This is the page footer for odd-numbered pages.
706 @funindex evenFooterMarkup
707 @item evenFooterMarkup
708 This is the page footer for even-numbered pages. If unspecified,
709 the odd header is used instead.
711 By default, the footer has the copyright notice on the first, and
712 the tagline on the last page.
722 The following definition will put the title flush left, and the
723 composer flush right on a single line.
727 bookTitleMarkup = \markup {
729 \fromproperty #'header:title
730 \fromproperty #'header:composer
744 MIDI (Musical Instrument Digital Interface) is a standard for
745 connecting and controlling digital instruments. A MIDI file is a
746 series of notes in a number of tracks. It is not an actual
747 sound file; you need special software to translate between the
748 series of notes and actual sounds.
750 Pieces of music can be converted to MIDI files, so you can listen to
751 what was entered. This is convenient for checking the music; octaves
752 that are off or accidentals that were mistyped stand out very much
753 when listening to the MIDI output.
757 Many musically interesting effects, such as swing, articulation,
758 slurring, etc., are not translated to midi.
760 The midi output allocates a channel for each staff, and one for global
761 settings. Therefore the midi file should not have more than 15 staves
762 (or 14 if you do not use drums). Other staves will remain silent.
764 Not all midi players correctly handle tempo changes in the midi
765 output. Players that are known to work include
766 @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
769 * Creating MIDI files::
771 * MIDI instrument names::
774 @node Creating MIDI files
775 @subsection Creating MIDI files
777 To create a MIDI from a music piece of music, add a @code{\midi} block
778 to a score, for example,
786 tempoWholesPerMinute = #(ly:make-moment 72 4)
792 The tempo can be specified using the @code{\tempo} command within the
793 actual music, see @ref{Metronome marks}. An alternative, which does not
794 result in a metronome mark in the printed score, is shown in the example
795 above. In this example the tempo of quarter notes is set to 72 beats per
798 specification can not take dotted note lengths as an argument. In this
799 case, break the dotted notes into smaller units. For example, a tempo
800 of 90 dotted quarter notes per minute can be specified as 270 eighth
804 tempoWholesPerMinute = #(ly:make-moment 270 8)
807 If there is a @code{\midi} command in a @code{\score}, only MIDI will
808 be produced. When notation is needed too, a @code{\layout} block must
822 Ties, dynamics, and tempo changes are interpreted. Dynamic marks,
823 crescendi and decrescendi translate into MIDI volume levels. Dynamic
824 marks translate to a fixed fraction of the available MIDI volume
825 range, crescendi and decrescendi make the volume vary linearly between
826 their two extremes. The fractions can be adjusted by
827 @code{dynamicAbsoluteVolumeFunction} in @internalsref{Voice} context.
828 For each type of MIDI instrument, a volume range can be defined. This
829 gives a basic equalizer control, which can enhance the quality of
830 the MIDI output remarkably. The equalizer can be controlled by
831 setting @code{instrumentEqualizer}, or by setting
834 \set Staff.midiMinimumVolume = #0.2
835 \set Staff.midiMaximumVolume = #0.8
838 To remove dynamics from the MIDI output, insert the following lines
839 in the @code{\midi@{@}} section.
846 \remove "Dynamic_performer"
847 \remove "Span_dynamic_performer"
855 Unterminated (de)crescendos will not render properly in the midi file,
856 resulting in silent passages of music. The workaround is to explicitly
857 terminate the (de)crescendo. For example,
864 will not work properly but
875 @subsection MIDI block
879 The MIDI block is analogous to the layout block, but it is somewhat
880 simpler. The @code{\midi} block is similar to @code{\layout}. It can contain
884 @cindex context definition
886 Context definitions follow precisely the same syntax as within the
887 \layout block. Translation modules for sound are called performers.
888 The contexts for MIDI output are defined in @file{ly/@/performer@/-init@/.ly}.
891 @node MIDI instrument names
892 @subsection MIDI instrument names
894 @cindex instrument names
895 @funindex Staff.midiInstrument
897 The MIDI instrument name is set by the @code{Staff.midiInstrument}
898 property. The instrument name should be chosen from the list in
899 @ref{MIDI instruments}.
902 \set Staff.midiInstrument = "glockenspiel"
906 If the selected instrument does not exactly match an instrument from
907 the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
911 @c Yes, this is a cop-out; this info doesn't belong in the Scheme
912 @c chapter, but I'm not certain where to stick it.
913 @c I think I'll eventually split this chapter into a "paper/layout"
914 @c chapter and a "misc issues" chapter. -gp
915 @node Displaying LilyPond notation
916 @section Displaying LilyPond notation
918 @funindex \displayLilyMusc
919 Displaying a music expression in LilyPond notation can be
920 done using the music function @code{\displayLilyMusic}. For example,
924 \displayLilyMusic \transpose c a, @{ c e g a bes @}
934 By default, LilyPond will print these messages to the console along
935 with all the other messages. To split up these messages and save
936 the results of @code{\display@{STUFF@}}, redirect the output to
940 lilypond file.ly >display.txt
944 @node Skipping corrected music
945 @section Skipping corrected music
948 @funindex skipTypesetting
949 @funindex showLastLength
951 When entering or copying music, usually only the music near the end (where
953 are adding notes) is interesting to view and correct. To speed up
954 this correction process, it is possible to skip typesetting of all but
955 the last few measures. This is achieved by putting
958 showLastLength = R1*5
963 in your source file. This will render only the last 5 measures
964 (assuming 4/4 time signature) of every @code{\score} in the input
965 file. For longer pieces, rendering only a small part is often an order
966 of magnitude quicker than rendering it completely
968 Skipping parts of a score can be controlled in a more fine-grained
969 fashion with the property @code{Score.skipTypesetting}. When it is
970 set, no typesetting is performed at all.
972 This property is also used to control output to the MIDI file. Note that
973 it skips all events, including tempo and instrument changes. You have
976 @lilypond[quote,fragment,ragged-right,verbatim]
979 \set Score.skipTypesetting = ##t
981 \set Score.skipTypesetting = ##f
985 In polyphonic music, @code{Score.skipTypesetting} will affect all
986 voices and staves, saving even more time.