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 @samp{.ly}.
36 * File structure (introduction)::
38 * A single music expression::
39 * Multiple scores in a book::
40 * Extracting fragments of notation::
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; see @ref{File structure}, for
78 a list of all such expressions.
82 @subsection File structure
84 A @code{.ly} file contains any number of toplevel expressions, where a
85 toplevel expression is one of the following
89 An output definition, such as @code{\paper}, @code{\midi}, and
90 @code{\layout}. Such a definition at the toplevel changes the default
91 settings for the block entered.
94 A direct scheme expression, such as
95 @code{#(set-default-paper-size "a7" 'landscape)} or
96 @code{#(ly:set-option 'point-and-click #f)}.
99 A @code{\header} block. This sets the global header block. This
100 is the block containing the definitions for book-wide settings, like
101 composer, title, etc.
104 A @code{\score} block. This score will be collected with other
105 toplevel scores, and combined as a single @code{\book}.
107 This behavior can be changed by setting the variable
108 @code{toplevel-score-handler} at toplevel. The default handler is
109 defined in the init file @file{scm/@/lily@/.scm}.
111 The @code{\score} must begin with a music expression, and may
112 contain only one music expression.
115 A @code{\book} block logically combines multiple movements
116 (i.e., multiple @code{\score} blocks) in one document. If there are
117 a number of @code{\scores}, one output file will be created for
118 each @code{\book} block, in which all corresponding movements are
119 concatenated. The only reason to explicitly specify @code{\book} blocks
120 in a @code{.ly} file is if you wish multiple output files from a single
121 input file. One exception is within lilypond-book documents, where you
122 explicitly have to add a @code{\book} block if you want more than a
123 single @code{\score} or @code{\markup} in the same example.
125 This behavior can be changed by setting the variable
126 @code{toplevel-book-handler} at toplevel. The default handler is
127 defined in the init file @file{scm/@/lily@/.scm}.
130 A compound music expression, such as
135 This will add the piece in a @code{\score} and format it in a
136 single book together with all other toplevel @code{\score}s and music
137 expressions. In other words, a file containing only the above
138 music expression will be translated into
154 This behavior can be changed by setting the variable
155 @code{toplevel-music-handler} at toplevel. The default handler is
156 defined in the init file @file{scm/@/lily@/.scm}.
159 A markup text, a verse for example
162 2. The first line verse two.
166 Markup texts are rendered above, between or below the scores or music
167 expressions, wherever they appear.
173 An identifier, such as
178 This can be used later on in the file by entering @code{\foo}. The
179 name of an identifier should have alphabetic characters only; no
180 numbers, underscores or dashes.
184 The following example shows three things that may be entered at
189 % movements are non-justified by default
201 At any point in a file, any of the following lexical instructions can
205 @item @code{\version}
206 @item @code{\include}
207 @item @code{\sourcefilename}
208 @item @code{\sourcefileline}
213 @node A single music expression
214 @subsection A single music expression
216 A @code{\score} must contain a single music expression. However,
217 this music expression may be of any size. Recall that music
218 expressions may be included inside other expressions to form
219 larger expressions. All of these examples are single music
220 expressions; note the curly braces @{ @} or angle brackets <<
221 >> at the beginning and ending of the music.
227 @lilypond[ragged-right,verbatim,quote]
234 @lilypond[ragged-right,verbatim,quote]
236 \new Staff { c'4 c' c' c' }
237 \new Staff { d'4 d' d' d' }
245 \new Staff @{ \flute @}
246 \new Staff @{ \oboe @}
249 \new Staff @{ \violinI @}
250 \new Staff @{ \violinII @}
257 @node Multiple scores in a book
258 @subsection Multiple scores in a book
261 @cindex movements, multiple
263 A document may contain multiple pieces of music and texts. Examples
264 of these are an etude book, or an orchestral part with multiple
265 movements. Each movement is entered with a @code{\score} block,
273 and texts are entered with a @code{\markup} block,
283 All the movements and texts which appear in the same @code{.ly} file
284 will normally be typeset in the form of a single output file.
298 However, if you want multiple output files from the same @code{.ly}
299 file, then you can add multiple @code{\book} blocks, where each such
300 @code{\book} block will result in a separate output. If you do not
301 specify any @code{\book} block in the file, LilyPond will implicitly
302 treat the full file as a single @code{\book} block, see @ref{File
303 structure}. One important exception is within lilypond-book documents,
304 where you explicitly have to add a @code{\book} block, otherwise only
305 the first @code{\score} or @code{\markup} will appear in the output.
307 The header for each piece of music can be put inside the @code{\score}
308 block. The @code{piece} name from the header will be printed before
309 each movement. The title for the entire book can be put inside the
310 @code{\book}, but if it is not present, the @code{\header} which is at
311 the top of the file is inserted.
315 title = "Eight miniatures"
316 composer = "Igor Stravinsky"
320 \header @{ piece = "Romanze" @}
323 ..text of second verse..
326 ..text of third verse..
330 \header @{ piece = "Menuetto" @}
334 @node Extracting fragments of notation
335 @subsection Extracting fragments of notation
337 It is possible to quote small fragments of a large score directly from
338 the output. This can be compared to clipping a piece of a paper score
341 This is done by definining the measures that need to be cut out
342 separately. For example, including the following definition
350 (make-rhythmic-location 5 1 2)
351 (make-rhythmic-location 7 3 4)))
356 will extract a fragment starting halfway the fifth measure, ending in
357 the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note
358 in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7.
360 More clip regions can be defined by adding more pairs of
361 rhythmic-locations to the list.
363 In order to use this feature, LilyPond must be invoked with
364 @code{-dclip-systems}. The clips are output as EPS files, and are
365 converted to PDF and PNG if these formats are switched on as well.
367 For more information on output formats, see @rprogram{Invoking lilypond}.
371 Examples: @lsr{non-notation,clip-systems.ly}
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 @q{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 @q{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 @samp{/} rather than the DOS/Windows @samp{\}. 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 -dbackend=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 -dbackend=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))
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.
484 * Reference to page numbers::
485 * Table of contents::
489 @node Creating titles
490 @subsection Creating titles
492 Titles are created for each @code{\score} block, as well as for the full
493 input file (or @code{\book} block).
495 The contents of the titles are taken from the @code{\header} blocks.
496 The header block for a book supports the following
502 The dedicatee of the music, centered at the top of the first page.
506 The title of the music, centered just below the dedication.
510 Subtitle, centered below the title.
512 @funindex subsubtitle
514 Subsubtitle, centered below the subtitle.
518 Name of the poet, flush-left below the subtitle.
522 Name of the composer, flush-right below the subtitle.
526 Meter string, flush-left below the poet.
530 Name of the opus, flush-right below the composer.
534 Name of the arranger, flush-right below the opus.
538 Name of the instrument, centered below the arranger. Also
539 centered at the top of pages (other than the first page).
543 Name of the piece, flush-left below the instrument.
545 @cindex page breaks, forcing
546 @funindex breakbefore
548 This forces the title to start on a new page (set to ##t or ##f).
552 Copyright notice, centered at the bottom of the first page. To
553 insert the copyright symbol, see @ref{Text encoding}.
557 Centered at the bottom of the last page.
561 Here is a demonstration of the fields available. Note that you
562 may use any @ref{Text markup}, commands in the header.
564 @lilypond[quote,verbatim,line-width=11.0\cm]
567 paper-height = 10.0\cm
572 dedication = "dedicated to me"
573 title = \markup \center-align { "Title first line" "Title second line,
575 subtitle = "the subtitle,"
576 subsubtitle = #(string-append "subsubtitle LilyPond version "
579 composer = \markup \center-align { "composer" \small "(1847-1973)" }
580 texttranslator = "Text Translator"
581 meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
583 arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize
584 #-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }
585 instrument = \markup \bold \italic "instrument"
609 As demonstrated before, you can use multiple @code{\header} blocks.
610 When same fields appear in different blocks, the latter is used.
611 Here is a short example.
615 composer = "Composer"
623 piece = "New piece" % overwrite previous one
628 If you define the @code{\header} inside the @code{\score} block, then
629 normally only the @code{piece} and @code{opus} headers will be printed.
630 Note that the music expression must come before the @code{\header}.
632 @lilypond[quote,verbatim,line-width=11.0\cm]
636 title = "title" % not printed
643 @funindex printallheaders
645 You may change this behavior (and print all the headers when defining
646 @code{\header} inside @code{\score}) by using
657 The default footer is empty, except for the first page, where the
658 @code{copyright} field from @code{\header} is inserted, and the last
659 page, where @code{tagline} from @code{\header} is added. The default
660 tagline is @qq{Music engraving by LilyPond (@var{version})}.@footnote{Nicely
661 printed parts are good PR for us, so please leave the tagline if you
664 Headers may be completely removed by setting them to false.
675 @subsection Custom titles
677 A more advanced option is to change the definitions of the following
678 variables in the @code{\paper} block. The init file
679 @file{ly/titling-init.ly} lists the default layout.
682 @funindex bookTitleMarkup
683 @item bookTitleMarkup
684 This is the title added at the top of the entire output document.
685 Typically, it has the composer and the title of the piece
687 @funindex scoreTitleMarkup
688 @item scoreTitleMarkup
689 This is the title put over a @code{\score} block. Typically, it has
690 the name of the movement (@code{piece} field).
692 @funindex oddHeaderMarkup
693 @item oddHeaderMarkup
694 This is the page header for odd-numbered pages.
696 @funindex evenHeaderMarkup
697 @item evenHeaderMarkup
698 This is the page header for even-numbered pages. If unspecified,
699 the odd header is used instead.
701 By default, headers are defined such that the page number is on the
702 outside edge, and the instrument is centered.
704 @funindex oddFooterMarkup
705 @item oddFooterMarkup
706 This is the page footer for odd-numbered pages.
708 @funindex evenFooterMarkup
709 @item evenFooterMarkup
710 This is the page footer for even-numbered pages. If unspecified,
711 the odd header is used instead.
713 By default, the footer has the copyright notice on the first, and
714 the tagline on the last page.
724 The following definition will put the title flush left, and the
725 composer flush right on a single line.
729 bookTitleMarkup = \markup {
731 \fromproperty #'header:title
732 \fromproperty #'header:composer
738 @node Reference to page numbers
739 @subsection Reference to page numbers
741 A particular place of a score can be marked using the @code{\label}
742 command, either at top-level or inside music. This label can then be
743 refered to in a markup, to get the number of the page where the marked
744 point is placed, using the @code{\page-ref} markup command.
746 @lilypond[verbatim,line-width=11.0\cm]
747 \header { tagline = ##f }
753 \pageBreak \mark A \label #'markA
758 \markup { The first score begins on page \page-ref #'firstScore "0" "?" }
759 \markup { Mark A is on page \page-ref #'markA "0" "?" }
763 The @code{\page-ref} markup command takes three arguments:
765 @item the label, a scheme symbol, eg. @code{#'firstScore};
766 @item a markup that will be used as a gauge to estimate the dimensions
768 @item a markup that will be used in place of the page number if the label
772 The reason why a gauge is needed is that, at the time markups are
773 interpreted, the page breaking has not yet occured, so the page numbers
774 are not yet known. To work around this issue, the actual markup
775 interpretation is delayed to a later time; however, the dimensions of
776 the markup have to be known before, so a gauge is used to decide these
777 dimensions. If the book has between 10 and 99 pages, it may be "00",
778 ie. a two digit number.
787 @node Table of contents
788 @subsection Table of contents
789 A table of contents is included using the @code{\markuplines \table-of-contents}
790 command. The elements which should appear in the table of contents are
791 entered with the @code{\tocItem} command, which may be used either at
792 top-level, or inside a music expression.
795 \markuplines \table-of-contents
798 \tocItem \markup "First score"
802 \tocItem \markup "Some particular point in the first score"
807 \tocItem \markup "Second score"
815 The markups which are used to format the table of contents are defined
816 in the @code{\paper} block. The default ones are @code{tocTitleMarkup},
817 for formatting the title of the table, and @code{tocItemMarkup}, for
818 formatting the toc elements, composed of the element title and page
819 number. These variables may be changed by the user:
823 %% Translate the toc title into French:
824 tocTitleMarkup = \markup \huge \column {
825 \fill-line { \null "Table des matières" \null }
828 %% use larfer font size
829 tocItemMarkup = \markup \large \fill-line {
830 \fromproperty #'toc:text \fromproperty #'toc:page
835 Note how the toc element text and page number are refered to in
836 the @code{tocItemMarkup} definition.
838 New commands and markups may also be defined to build more elaborated
841 @item first, define a new markup variable in the @code{\paper} block
842 @item then, define a music function which aims at adding a toc element
843 using this markup paper variable.
846 In the following example, a new style is defined for entering act names
847 in the table of contents of an opera:
851 tocActMarkup = \markup \large \column {
853 \fill-line { \null \italic \fromproperty #'toc:text \null }
859 #(define-music-function (parser location text) (markup?)
860 (add-toc-item! 'tocActMarkup text))
863 @lilypond[line-width=11.0\cm]
864 \header { tagline = ##f }
866 tocActMarkup = \markup \large \column {
868 \fill-line { \null \italic \fromproperty #'toc:text \null }
874 #(define-music-function (parser location text) (markup?)
875 (add-toc-item! 'tocActMarkup text))
878 \markuplines \table-of-contents
879 \tocAct \markup { Atto Primo }
880 \tocItem \markup { Coro. Viva il nostro Alcide }
881 \tocItem \markup { Cesare. Presti omai l'Egizzia terra }
882 \tocAct \markup { Atto Secondo }
883 \tocItem \markup { Sinfonia }
884 \tocItem \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
891 Init files: @file{ly/@/toc@/-init@/.ly}.
895 @funindex \table-of-contents
896 @code{\table-of-contents}
906 MIDI (Musical Instrument Digital Interface) is a standard for
907 connecting and controlling digital instruments. A MIDI file is a
908 series of notes in a number of tracks. It is not an actual
909 sound file; you need special software to translate between the
910 series of notes and actual sounds.
912 Pieces of music can be converted to MIDI files, so you can listen to
913 what was entered. This is convenient for checking the music; octaves
914 that are off or accidentals that were mistyped stand out very much
915 when listening to the MIDI output.
919 Many musically interesting effects, such as swing, articulation,
920 slurring, etc., are not translated to midi.
922 The midi output allocates a channel for each staff, and one for global
923 settings. Therefore the midi file should not have more than 15 staves
924 (or 14 if you do not use drums). Other staves will remain silent.
926 Not all midi players correctly handle tempo changes in the midi
927 output. Players that are known to work include
928 @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
931 * Creating MIDI files::
933 * MIDI instrument names::
936 @node Creating MIDI files
937 @subsection Creating MIDI files
939 To create a MIDI from a music piece of music, add a @code{\midi} block
940 to a score, for example,
948 tempoWholesPerMinute = #(ly:make-moment 72 4)
954 The tempo can be specified using the @code{\tempo} command within the
955 actual music, see @ref{Metronome marks}. An alternative, which does not
956 result in a metronome mark in the printed score, is shown in the example
957 above. In this example the tempo of quarter notes is set to 72 beats per
960 specification can not take dotted note lengths as an argument. In this
961 case, break the dotted notes into smaller units. For example, a tempo
962 of 90 dotted quarter notes per minute can be specified as 270 eighth
966 tempoWholesPerMinute = #(ly:make-moment 270 8)
969 If there is a @code{\midi} command in a @code{\score}, only MIDI will
970 be produced. When notation is needed too, a @code{\layout} block must
984 Ties, dynamics, and tempo changes are interpreted. Dynamic marks,
985 crescendi and decrescendi translate into MIDI volume levels. Dynamic
986 marks translate to a fixed fraction of the available MIDI volume
987 range, crescendi and decrescendi make the volume vary linearly between
988 their two extremes. The fractions can be adjusted by
989 @code{dynamicAbsoluteVolumeFunction} in @internalsref{Voice} context.
990 For each type of MIDI instrument, a volume range can be defined. This
991 gives a basic equalizer control, which can enhance the quality of
992 the MIDI output remarkably. The equalizer can be controlled by
993 setting @code{instrumentEqualizer}, or by setting
996 \set Staff.midiMinimumVolume = #0.2
997 \set Staff.midiMaximumVolume = #0.8
1000 To remove dynamics from the MIDI output, insert the following lines
1001 in the @code{\midi@{@}} section.
1008 \remove "Dynamic_performer"
1016 Unterminated (de)crescendos will not render properly in the midi file,
1017 resulting in silent passages of music. The workaround is to explicitly
1018 terminate the (de)crescendo. For example,
1025 will not work properly but
1035 MIDI output is only created when the @code{\midi} command is within
1036 a @code{\score} block. If you put it within an explicitly instantiated
1037 context ( i.e. @code{\new Score} ) the file will fail. To solve this,
1038 enclose the @code{\new Score} and the @code{\midi} in a @code{\score} block.
1042 \new Score @{ @dots{}notes@dots{} @}
1049 @subsection MIDI block
1053 The MIDI block is analogous to the layout block, but it is somewhat
1054 simpler. The @code{\midi} block is similar to @code{\layout}. It can contain
1055 context definitions.
1058 @cindex context definition
1060 Context definitions follow precisely the same syntax as within the
1061 \layout block. Translation modules for sound are called performers.
1062 The contexts for MIDI output are defined in @file{ly/@/performer@/-init@/.ly}.
1065 @node MIDI instrument names
1066 @subsection MIDI instrument names
1068 @cindex instrument names
1069 @funindex Staff.midiInstrument
1071 The MIDI instrument name is set by the @code{Staff.midiInstrument}
1072 property. The instrument name should be chosen from the list in
1073 @ref{MIDI instruments}.
1076 \set Staff.midiInstrument = "glockenspiel"
1080 If the selected instrument does not exactly match an instrument from
1081 the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
1085 @c Yes, this is a cop-out; this info doesn't belong in the Scheme
1086 @c chapter, but I'm not certain where to stick it.
1087 @c I think I'll eventually split this chapter into a "paper/layout"
1088 @c chapter and a "misc issues" chapter. -gp
1089 @node Displaying LilyPond notation
1090 @section Displaying LilyPond notation
1092 @funindex \displayLilyMusc
1093 Displaying a music expression in LilyPond notation can be
1094 done using the music function @code{\displayLilyMusic}. For example,
1098 \displayLilyMusic \transpose c a, @{ c e g a bes @}
1105 @{ a, cis e fis g @}
1108 By default, LilyPond will print these messages to the console along
1109 with all the other messages. To split up these messages and save
1110 the results of @code{\display@{STUFF@}}, redirect the output to
1114 lilypond file.ly >display.txt
1118 @node Skipping corrected music
1119 @section Skipping corrected music
1122 @funindex skipTypesetting
1123 @funindex showLastLength
1125 When entering or copying music, usually only the music near the end (where
1127 are adding notes) is interesting to view and correct. To speed up
1128 this correction process, it is possible to skip typesetting of all but
1129 the last few measures. This is achieved by putting
1132 showLastLength = R1*5
1137 in your source file. This will render only the last 5 measures
1138 (assuming 4/4 time signature) of every @code{\score} in the input
1139 file. For longer pieces, rendering only a small part is often an order
1140 of magnitude quicker than rendering it completely
1142 Skipping parts of a score can be controlled in a more fine-grained
1143 fashion with the property @code{Score.skipTypesetting}. When it is
1144 set, no typesetting is performed at all.
1146 This property is also used to control output to the MIDI file. Note that
1147 it skips all events, including tempo and instrument changes. You have
1150 @lilypond[quote,fragment,ragged-right,verbatim]
1153 \set Score.skipTypesetting = ##t
1155 \set Score.skipTypesetting = ##f
1159 In polyphonic music, @code{Score.skipTypesetting} will affect all
1160 voices and staves, saving even more time.