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}.
37 * A single music expression::
38 * Multiple scores in a book::
39 * Extracting fragments of notation::
40 * Including LilyPond files::
42 * Different editions from one source::
47 @subsection File structure
49 A @code{.ly} file contains any number of toplevel expressions, where a
50 toplevel expression is one of the following
54 An output definition, such as @code{\paper}, @code{\midi}, and
55 @code{\layout}. Such a definition at the toplevel changes the default
56 settings for the block entered.
59 A direct scheme expression, such as
60 @code{#(set-default-paper-size "a7" 'landscape)} or
61 @code{#(ly:set-option 'point-and-click #f)}.
64 A @code{\header} block. This sets the global header block. This
65 is the block containing the definitions for book-wide settings, like
69 A @code{\score} block. This score will be collected with other
70 toplevel scores, and combined as a single @code{\book}.
72 This behavior can be changed by setting the variable
73 @code{toplevel-score-handler} at toplevel. The default handler is
74 defined in the init file @file{scm/@/lily@/.scm}.
76 The @code{\score} must begin with a music expression, and may
77 contain only one music expression.
80 A @code{\book} block logically combines multiple movements
81 (i.e., multiple @code{\score} blocks) in one document. If there are
82 a number of @code{\scores}, one output file will be created for
83 each @code{\book} block, in which all corresponding movements are
84 concatenated. The only reason to explicitly specify @code{\book} blocks
85 in a @code{.ly} file is if you wish multiple output files from a single
86 input file. One exception is within lilypond-book documents, where you
87 explicitly have to add a @code{\book} block if you want more than a
88 single @code{\score} or @code{\markup} in the same example.
90 This behavior can be changed by setting the variable
91 @code{toplevel-book-handler} at toplevel. The default handler is
92 defined in the init file @file{scm/@/lily@/.scm}.
95 A compound music expression, such as
100 This will add the piece in a @code{\score} and format it in a
101 single book together with all other toplevel @code{\score}s and music
102 expressions. In other words, a file containing only the above
103 music expression will be translated into
119 This behavior can be changed by setting the variable
120 @code{toplevel-music-handler} at toplevel. The default handler is
121 defined in the init file @file{scm/@/lily@/.scm}.
124 A markup text, a verse for example
127 2. The first line verse two.
131 Markup texts are rendered above, between or below the scores or music
132 expressions, wherever they appear.
138 An identifier, such as
143 This can be used later on in the file by entering @code{\foo}. The
144 name of an identifier should have alphabetic characters only; no
145 numbers, underscores or dashes.
149 The following example shows three things that may be entered at
154 % movements are non-justified by default
166 At any point in a file, any of the following lexical instructions can
170 @item @code{\version}
171 @item @code{\include}
172 @item @code{\sourcefilename}
173 @item @code{\sourcefileline}
178 @node A single music expression
179 @subsection A single music expression
181 A @code{\score} must contain a single music expression. However,
182 this music expression may be of any size. Recall that music
183 expressions may be included inside other expressions to form
184 larger expressions. All of these examples are single music
185 expressions; note the curly braces @{ @} or angle brackets <<
186 >> at the beginning and ending of the music.
192 @lilypond[ragged-right,verbatim,quote]
199 @lilypond[ragged-right,verbatim,quote]
201 \new Staff { c'4 c' c' c' }
202 \new Staff { d'4 d' d' d' }
210 \new Staff @{ \flute @}
211 \new Staff @{ \oboe @}
214 \new Staff @{ \violinI @}
215 \new Staff @{ \violinII @}
222 @node Multiple scores in a book
223 @subsection Multiple scores in a book
226 @cindex movements, multiple
228 A document may contain multiple pieces of music and texts. Examples
229 of these are an etude book, or an orchestral part with multiple
230 movements. Each movement is entered with a @code{\score} block,
238 and texts are entered with a @code{\markup} block,
248 All the movements and texts which appear in the same @code{.ly} file
249 will normally be typeset in the form of a single output file.
263 However, if you want multiple output files from the same @code{.ly}
264 file, then you can add multiple @code{\book} blocks, where each such
265 @code{\book} block will result in a separate output. If you do not
266 specify any @code{\book} block in the file, LilyPond will implicitly
267 treat the full file as a single @code{\book} block, see @ref{File
268 structure}. One important exception is within lilypond-book documents,
269 where you explicitly have to add a @code{\book} block, otherwise only
270 the first @code{\score} or @code{\markup} will appear in the output.
272 The header for each piece of music can be put inside the @code{\score}
273 block. The @code{piece} name from the header will be printed before
274 each movement. The title for the entire book can be put inside the
275 @code{\book}, but if it is not present, the @code{\header} which is at
276 the top of the file is inserted.
280 title = "Eight miniatures"
281 composer = "Igor Stravinsky"
285 \header @{ piece = "Romanze" @}
288 ..text of second verse..
291 ..text of third verse..
295 \header @{ piece = "Menuetto" @}
299 @node Extracting fragments of notation
300 @subsection Extracting fragments of notation
302 It is possible to quote small fragments of a large score directly from
303 the output. This can be compared to clipping a piece of a paper score
306 This is done by definining the measures that need to be cut out
307 separately. For example, including the following definition
315 (make-rhythmic-location 5 1 2)
316 (make-rhythmic-location 7 3 4)))
321 will extract a fragment starting halfway the fifth measure, ending in
322 the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note
323 in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7.
325 More clip regions can be defined by adding more pairs of
326 rhythmic-locations to the list.
328 In order to use this feature, LilyPond must be invoked with
329 @code{-dclip-systems}. The clips are output as EPS files, and are
330 converted to PDF and PNG if these formats are switched on as well.
332 For more information on output formats, see @rprogram{Invoking lilypond}.
336 Examples: @lsr{non-notation,clip-systems.ly}
339 @node Including LilyPond files
340 @subsection Including LilyPond files
343 @cindex including files
345 A large project may be split up into separate files. To refer to another
349 \include "otherfile.ly"
352 The line @code{\include "file.ly"} is equivalent to pasting the contents
353 of file.ly into the current file at the place where you have the
354 \include. For example, for a large project you might write separate files
355 for each instrument part and create a @q{full score} file which brings
356 together the individual instrument files.
358 The initialization of LilyPond is done in a number of files that are
359 included by default when you start the program, normally transparent to the
360 user. Run lilypond --verbose to see a list of paths and files that Lily
363 Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where
364 VERSION is in the form @q{2.6.1}) are on the path and available to
365 @code{\include}. Files in the
366 current working directory are available to \include, but a file of the same
367 name in LilyPond's installation takes precedence. Files are
368 available to \include from directories in the search path specified as an
369 option when invoking @code{lilypond --include=DIR} which adds DIR to the
372 The @code{\include} statement can use full path information, but with the Unix
373 convention @samp{/} rather than the DOS/Windows @samp{\}. For example,
374 if @file{stuff.ly} is located one directory higher than the current working
378 \include "../stuff.ly"
383 @subsection Text encoding
385 LilyPond uses the Pango library to format multi-lingual texts, and
386 does not perform any input-encoding conversions. This means that any
387 text, be it title, lyric text, or musical instruction containing
388 non-ASCII characters, must be utf-8. The easiest way to enter such text is
389 by using a Unicode-aware editor and saving the file with utf-8 encoding. Most
390 popular modern editors have utf-8 support, for example, vim, Emacs,
393 @c Currently not working
395 Depending on the fonts installed, the following fragment shows Hebrew
402 @li lypondfile[fontload]{utf-8.ly}
404 The @TeX{} backend does not handle encoding specially at all. Strings
405 in the input are put in the output as-is. Extents of text items in the
406 @TeX{} backend, are determined by reading a file created via the
407 @file{texstr} backend,
410 lilypond -dbackend=texstr input/les-nereides.ly
411 latex les-nereides.texstr
414 The last command produces @file{les-nereides.textmetrics}, which is
415 read when you execute
418 lilypond -dbackend=tex input/les-nereides.ly
421 Both @file{les-nereides.texstr} and @file{les-nereides.tex} need
422 suitable LaTeX wrappers to load appropriate La@TeX{} packages for
423 interpreting non-ASCII strings.
427 To use a Unicode escape sequence, use
430 #(ly:export (ly:wide-char->utf-8 #x2014))
439 @node Different editions from one source
440 @subsection Different editions from one source
445 The @code{\tag} command marks music expressions with a name. These
446 tagged expressions can be filtered out later. With this mechanism it
447 is possible to make different versions of the same music source.
449 In the following example, we see two versions of a piece of music, one
450 for the full score, and one with cue notes for the instrumental part
466 The same can be applied to articulations, texts, etc.: they are
469 -\tag #@var{your-tag}
471 to an articulation, for example,
476 This defines a note with a conditional fingering indication.
479 @cindex removeWithTag
480 By applying the @code{\keepWithTag} and @code{\removeWithTag}
481 commands, tagged expressions can be filtered. For example,
485 \keepWithTag #'score @var{the music}
486 \keepWithTag #'part @var{the music}
491 @lilypondfile[ragged-right,quote]{tag-filter.ly}
493 The arguments of the @code{\tag} command should be a symbol
494 (such as @code{#'score} or @code{#'part}), followed by a
495 music expression. It is possible to put multiple tags on
496 a piece of music with multiple @code{\tag} entries,
499 \tag #'original-part \tag #'transposed-part @dots{}
505 Examples: @lsr{parts,tag@/-filter@/.ly}
510 Multiple rests are not merged if you create the score with both tagged
514 @node Titles and headers
515 @section Titles and headers
517 Almost all printed music includes a title and the composer's name;
518 some pieces include a lot more information.
523 * Reference to page numbers::
524 * Table of contents::
528 @node Creating titles
529 @subsection Creating titles
531 Titles are created for each @code{\score} block, as well as for the full
532 input file (or @code{\book} block).
534 The contents of the titles are taken from the @code{\header} blocks.
535 The header block for a book supports the following
541 The dedicatee of the music, centered at the top of the first page.
545 The title of the music, centered just below the dedication.
549 Subtitle, centered below the title.
551 @funindex subsubtitle
553 Subsubtitle, centered below the subtitle.
557 Name of the poet, flush-left below the subtitle.
561 Name of the composer, flush-right below the subtitle.
565 Meter string, flush-left below the poet.
569 Name of the opus, flush-right below the composer.
573 Name of the arranger, flush-right below the opus.
577 Name of the instrument, centered below the arranger. Also
578 centered at the top of pages (other than the first page).
582 Name of the piece, flush-left below the instrument.
584 @cindex page breaks, forcing
585 @funindex breakbefore
587 This forces the title to start on a new page (set to ##t or ##f).
591 Copyright notice, centered at the bottom of the first page. To
592 insert the copyright symbol, see @ref{Text encoding}.
596 Centered at the bottom of the last page.
600 Here is a demonstration of the fields available. Note that you
601 may use any @ref{Text markup}, commands in the header.
603 @lilypond[quote,verbatim,line-width=11.0\cm]
606 paper-height = 10.0\cm
611 dedication = "dedicated to me"
612 title = \markup \center-align { "Title first line" "Title second line,
614 subtitle = "the subtitle,"
615 subsubtitle = #(string-append "subsubtitle LilyPond version "
618 composer = \markup \center-align { "composer" \small "(1847-1973)" }
619 texttranslator = "Text Translator"
620 meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
622 arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize
623 #-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }
624 instrument = \markup \bold \italic "instrument"
648 As demonstrated before, you can use multiple @code{\header} blocks.
649 When same fields appear in different blocks, the latter is used.
650 Here is a short example.
654 composer = "Composer"
662 piece = "New piece" % overwrite previous one
667 If you define the @code{\header} inside the @code{\score} block, then
668 normally only the @code{piece} and @code{opus} headers will be printed.
669 Note that the music expression must come before the @code{\header}.
671 @lilypond[quote,verbatim,line-width=11.0\cm]
675 title = "title" % not printed
682 @funindex printallheaders
684 You may change this behavior (and print all the headers when defining
685 @code{\header} inside @code{\score}) by using
696 The default footer is empty, except for the first page, where the
697 @code{copyright} field from @code{\header} is inserted, and the last
698 page, where @code{tagline} from @code{\header} is added. The default
699 tagline is @qq{Music engraving by LilyPond (@var{version})}.@footnote{Nicely
700 printed parts are good PR for us, so please leave the tagline if you
703 Headers may be completely removed by setting them to false.
714 @subsection Custom titles
716 A more advanced option is to change the definitions of the following
717 variables in the @code{\paper} block. The init file
718 @file{ly/titling-init.ly} lists the default layout.
721 @funindex bookTitleMarkup
722 @item bookTitleMarkup
723 This is the title added at the top of the entire output document.
724 Typically, it has the composer and the title of the piece
726 @funindex scoreTitleMarkup
727 @item scoreTitleMarkup
728 This is the title put over a @code{\score} block. Typically, it has
729 the name of the movement (@code{piece} field).
731 @funindex oddHeaderMarkup
732 @item oddHeaderMarkup
733 This is the page header for odd-numbered pages.
735 @funindex evenHeaderMarkup
736 @item evenHeaderMarkup
737 This is the page header for even-numbered pages. If unspecified,
738 the odd header is used instead.
740 By default, headers are defined such that the page number is on the
741 outside edge, and the instrument is centered.
743 @funindex oddFooterMarkup
744 @item oddFooterMarkup
745 This is the page footer for odd-numbered pages.
747 @funindex evenFooterMarkup
748 @item evenFooterMarkup
749 This is the page footer for even-numbered pages. If unspecified,
750 the odd header is used instead.
752 By default, the footer has the copyright notice on the first, and
753 the tagline on the last page.
763 The following definition will put the title flush left, and the
764 composer flush right on a single line.
768 bookTitleMarkup = \markup {
770 \fromproperty #'header:title
771 \fromproperty #'header:composer
777 @node Reference to page numbers
778 @subsection Reference to page numbers
780 A particular place of a score can be marked using the @code{\label}
781 command, either at top-level or inside music. This label can then be
782 refered to in a markup, to get the number of the page where the marked
783 point is placed, using the @code{\page-ref} markup command.
785 @lilypond[verbatim,line-width=11.0\cm]
786 \header { tagline = ##f }
792 \pageBreak \mark A \label #'markA
797 \markup { The first score begins on page \page-ref #'firstScore "0" "?" }
798 \markup { Mark A is on page \page-ref #'markA "0" "?" }
802 The @code{\page-ref} markup command takes three arguments:
804 @item the label, a scheme symbol, eg. @code{#'firstScore};
805 @item a markup that will be used as a gauge to estimate the dimensions
807 @item a markup that will be used in place of the page number if the label
811 The reason why a gauge is needed is that, at the time markups are
812 interpreted, the page breaking has not yet occured, so the page numbers
813 are not yet known. To work around this issue, the actual markup
814 interpretation is delayed to a later time; however, the dimensions of
815 the markup have to be known before, so a gauge is used to decide these
816 dimensions. If the book has between 10 and 99 pages, it may be "00",
817 ie. a two digit number.
826 @node Table of contents
827 @subsection Table of contents
828 A table of contents is included using the @code{\markuplines \table-of-contents}
829 command. The elements which should appear in the table of contents are
830 entered with the @code{\tocItem} command, which may be used either at
831 top-level, or inside a music expression.
834 \markuplines \table-of-contents
837 \tocItem \markup "First score"
841 \tocItem \markup "Some particular point in the first score"
846 \tocItem \markup "Second score"
854 The markups which are used to format the table of contents are defined
855 in the @code{\paper} block. The default ones are @code{tocTitleMarkup},
856 for formatting the title of the table, and @code{tocItemMarkup}, for
857 formatting the toc elements, composed of the element title and page
858 number. These variables may be changed by the user:
862 %% Translate the toc title into French:
863 tocTitleMarkup = \markup \huge \column {
864 \fill-line { \null "Table des matières" \null }
867 %% use larfer font size
868 tocItemMarkup = \markup \large \fill-line {
869 \fromproperty #'toc:text \fromproperty #'toc:page
874 Note how the toc element text and page number are refered to in
875 the @code{tocItemMarkup} definition.
877 New commands and markups may also be defined to build more elaborated
880 @item first, define a new markup variable in the @code{\paper} block
881 @item then, define a music function which aims at adding a toc element
882 using this markup paper variable.
885 In the following example, a new style is defined for entering act names
886 in the table of contents of an opera:
890 tocActMarkup = \markup \large \column {
892 \fill-line { \null \italic \fromproperty #'toc:text \null }
898 #(define-music-function (parser location text) (markup?)
899 (add-toc-item! 'tocActMarkup text))
902 @lilypond[line-width=11.0\cm]
903 \header { tagline = ##f }
905 tocActMarkup = \markup \large \column {
907 \fill-line { \null \italic \fromproperty #'toc:text \null }
913 #(define-music-function (parser location text) (markup?)
914 (add-toc-item! 'tocActMarkup text))
917 \markuplines \table-of-contents
918 \tocAct \markup { Atto Primo }
919 \tocItem \markup { Coro. Viva il nostro Alcide }
920 \tocItem \markup { Cesare. Presti omai l'Egizzia terra }
921 \tocAct \markup { Atto Secondo }
922 \tocItem \markup { Sinfonia }
923 \tocItem \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
930 Init files: @file{ly/@/toc@/-init@/.ly}.
934 @funindex \table-of-contents
935 @code{\table-of-contents}
945 MIDI (Musical Instrument Digital Interface) is a standard for
946 connecting and controlling digital instruments. A MIDI file is a
947 series of notes in a number of tracks. It is not an actual
948 sound file; you need special software to translate between the
949 series of notes and actual sounds.
951 Pieces of music can be converted to MIDI files, so you can listen to
952 what was entered. This is convenient for checking the music; octaves
953 that are off or accidentals that were mistyped stand out very much
954 when listening to the MIDI output.
958 Many musically interesting effects, such as swing, articulation,
959 slurring, etc., are not translated to midi.
961 The midi output allocates a channel for each staff, and one for global
962 settings. Therefore the midi file should not have more than 15 staves
963 (or 14 if you do not use drums). Other staves will remain silent.
965 Not all midi players correctly handle tempo changes in the midi
966 output. Players that are known to work include
967 @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
970 * Creating MIDI files::
972 * MIDI instrument names::
975 @node Creating MIDI files
976 @subsection Creating MIDI files
978 To create a MIDI from a music piece of music, add a @code{\midi} block
979 to a score, for example,
987 tempoWholesPerMinute = #(ly:make-moment 72 4)
993 The tempo can be specified using the @code{\tempo} command within the
994 actual music, see @ref{Metronome marks}. An alternative, which does not
995 result in a metronome mark in the printed score, is shown in the example
996 above. In this example the tempo of quarter notes is set to 72 beats per
999 specification can not take dotted note lengths as an argument. In this
1000 case, break the dotted notes into smaller units. For example, a tempo
1001 of 90 dotted quarter notes per minute can be specified as 270 eighth
1005 tempoWholesPerMinute = #(ly:make-moment 270 8)
1008 If there is a @code{\midi} command in a @code{\score}, only MIDI will
1009 be produced. When notation is needed too, a @code{\layout} block must
1019 @cindex layout block
1023 Ties, dynamics, and tempo changes are interpreted. Dynamic marks,
1024 crescendi and decrescendi translate into MIDI volume levels. Dynamic
1025 marks translate to a fixed fraction of the available MIDI volume
1026 range, crescendi and decrescendi make the volume vary linearly between
1027 their two extremes. The fractions can be adjusted by
1028 @code{dynamicAbsoluteVolumeFunction} in @internalsref{Voice} context.
1029 For each type of MIDI instrument, a volume range can be defined. This
1030 gives a basic equalizer control, which can enhance the quality of
1031 the MIDI output remarkably. The equalizer can be controlled by
1032 setting @code{instrumentEqualizer}, or by setting
1035 \set Staff.midiMinimumVolume = #0.2
1036 \set Staff.midiMaximumVolume = #0.8
1039 To remove dynamics from the MIDI output, insert the following lines
1040 in the @code{\midi@{@}} section.
1047 \remove "Dynamic_performer"
1055 Unterminated (de)crescendos will not render properly in the midi file,
1056 resulting in silent passages of music. The workaround is to explicitly
1057 terminate the (de)crescendo. For example,
1064 will not work properly but
1074 MIDI output is only created when the @code{\midi} command is within
1075 a @code{\score} block. If you put it within an explicitly instantiated
1076 context ( i.e. @code{\new Score} ) the file will fail. To solve this,
1077 enclose the @code{\new Score} and the @code{\midi} in a @code{\score} block.
1081 \new Score @{ @dots{}notes@dots{} @}
1088 @subsection MIDI block
1092 The MIDI block is analogous to the layout block, but it is somewhat
1093 simpler. The @code{\midi} block is similar to @code{\layout}. It can contain
1094 context definitions.
1097 @cindex context definition
1099 Context definitions follow precisely the same syntax as within the
1100 \layout block. Translation modules for sound are called performers.
1101 The contexts for MIDI output are defined in @file{ly/@/performer@/-init@/.ly}.
1104 @node MIDI instrument names
1105 @subsection MIDI instrument names
1107 @cindex instrument names
1108 @funindex Staff.midiInstrument
1110 The MIDI instrument name is set by the @code{Staff.midiInstrument}
1111 property. The instrument name should be chosen from the list in
1112 @ref{MIDI instruments}.
1115 \set Staff.midiInstrument = "glockenspiel"
1119 If the selected instrument does not exactly match an instrument from
1120 the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
1124 @c Yes, this is a cop-out; this info doesn't belong in the Scheme
1125 @c chapter, but I'm not certain where to stick it.
1126 @c I think I'll eventually split this chapter into a "paper/layout"
1127 @c chapter and a "misc issues" chapter. -gp
1128 @node Displaying LilyPond notation
1129 @section Displaying LilyPond notation
1131 @funindex \displayLilyMusic
1132 Displaying a music expression in LilyPond notation can be
1133 done using the music function @code{\displayLilyMusic}. For example,
1137 \displayLilyMusic \transpose c a, @{ c e g a bes @}
1144 @{ a, cis e fis g @}
1147 By default, LilyPond will print these messages to the console along
1148 with all the other messages. To split up these messages and save
1149 the results of @code{\display@{STUFF@}}, redirect the output to
1153 lilypond file.ly >display.txt
1157 @node Skipping corrected music
1158 @section Skipping corrected music
1161 @funindex skipTypesetting
1162 @funindex showLastLength
1164 When entering or copying music, usually only the music near the end (where
1166 are adding notes) is interesting to view and correct. To speed up
1167 this correction process, it is possible to skip typesetting of all but
1168 the last few measures. This is achieved by putting
1171 showLastLength = R1*5
1176 in your source file. This will render only the last 5 measures
1177 (assuming 4/4 time signature) of every @code{\score} in the input
1178 file. For longer pieces, rendering only a small part is often an order
1179 of magnitude quicker than rendering it completely
1181 Skipping parts of a score can be controlled in a more fine-grained
1182 fashion with the property @code{Score.skipTypesetting}. When it is
1183 set, no typesetting is performed at all.
1185 This property is also used to control output to the MIDI file. Note that
1186 it skips all events, including tempo and instrument changes. You have
1189 @lilypond[quote,fragment,ragged-right,verbatim]
1192 \set Score.skipTypesetting = ##t
1194 \set Score.skipTypesetting = ##f
1198 In polyphonic music, @code{Score.skipTypesetting} will affect all
1199 voices and staves, saving even more time.