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.
142 This can be used later on in the file by entering @code{\foo}. The
143 name of an variable should have alphabetic characters only; no
144 numbers, underscores or dashes.
148 The following example shows three things that may be entered at
153 % movements are non-justified by default
165 At any point in a file, any of the following lexical instructions can
169 @item @code{\version}
170 @item @code{\include}
171 @item @code{\sourcefilename}
172 @item @code{\sourcefileline}
177 @node A single music expression
178 @subsection A single music expression
180 A @code{\score} must contain a single music expression. However,
181 this music expression may be of any size. Recall that music
182 expressions may be included inside other expressions to form
183 larger expressions. All of these examples are single music
184 expressions; note the curly braces @{ @} or angle brackets <<
185 >> at the beginning and ending of the music.
191 @lilypond[ragged-right,verbatim,quote]
198 @lilypond[ragged-right,verbatim,quote]
200 \new Staff { c'4 c' c' c' }
201 \new Staff { d'4 d' d' d' }
209 \new Staff @{ \flute @}
210 \new Staff @{ \oboe @}
213 \new Staff @{ \violinI @}
214 \new Staff @{ \violinII @}
221 @node Multiple scores in a book
222 @subsection Multiple scores in a book
225 @cindex movements, multiple
227 A document may contain multiple pieces of music and texts. Examples
228 of these are an etude book, or an orchestral part with multiple
229 movements. Each movement is entered with a @code{\score} block,
237 and texts are entered with a @code{\markup} block,
247 All the movements and texts which appear in the same @code{.ly} file
248 will normally be typeset in the form of a single output file.
262 However, if you want multiple output files from the same @code{.ly}
263 file, then you can add multiple @code{\book} blocks, where each such
264 @code{\book} block will result in a separate output. If you do not
265 specify any @code{\book} block in the file, LilyPond will implicitly
266 treat the full file as a single @code{\book} block, see @ref{File
267 structure}. One important exception is within lilypond-book documents,
268 where you explicitly have to add a @code{\book} block, otherwise only
269 the first @code{\score} or @code{\markup} will appear in the output.
271 The header for each piece of music can be put inside the @code{\score}
272 block. The @code{piece} name from the header will be printed before
273 each movement. The title for the entire book can be put inside the
274 @code{\book}, but if it is not present, the @code{\header} which is at
275 the top of the file is inserted.
279 title = "Eight miniatures"
280 composer = "Igor Stravinsky"
284 \header @{ piece = "Romanze" @}
287 ..text of second verse..
290 ..text of third verse..
294 \header @{ piece = "Menuetto" @}
298 @node Extracting fragments of notation
299 @subsection Extracting fragments of notation
301 It is possible to quote small fragments of a large score directly from
302 the output. This can be compared to clipping a piece of a paper score
305 This is done by definining the measures that need to be cut out
306 separately. For example, including the following definition
314 (make-rhythmic-location 5 1 2)
315 (make-rhythmic-location 7 3 4)))
320 will extract a fragment starting halfway the fifth measure, ending in
321 the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note
322 in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7.
324 More clip regions can be defined by adding more pairs of
325 rhythmic-locations to the list.
327 In order to use this feature, LilyPond must be invoked with
328 @code{-dclip-systems}. The clips are output as EPS files, and are
329 converted to PDF and PNG if these formats are switched on as well.
331 For more information on output formats, see @rprogram{Invoking lilypond}.
335 Examples: @lsr{non-notation,clip-systems.ly}
338 @node Including LilyPond files
339 @subsection Including LilyPond files
342 @cindex including files
344 A large project may be split up into separate files. To refer to another
348 \include "otherfile.ly"
351 The line @code{\include "file.ly"} is equivalent to pasting the contents
352 of file.ly into the current file at the place where you have the
353 \include. For example, for a large project you might write separate files
354 for each instrument part and create a @q{full score} file which brings
355 together the individual instrument files.
357 The initialization of LilyPond is done in a number of files that are
358 included by default when you start the program, normally transparent to the
359 user. Run lilypond --verbose to see a list of paths and files that Lily
362 Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where
363 VERSION is in the form @q{2.6.1}) are on the path and available to
364 @code{\include}. Files in the
365 current working directory are available to \include, but a file of the same
366 name in LilyPond's installation takes precedence. Files are
367 available to \include from directories in the search path specified as an
368 option when invoking @code{lilypond --include=DIR} which adds DIR to the
371 The @code{\include} statement can use full path information, but with the Unix
372 convention @samp{/} rather than the DOS/Windows @samp{\}. For example,
373 if @file{stuff.ly} is located one directory higher than the current working
377 \include "../stuff.ly"
382 @subsection Text encoding
384 LilyPond uses the Pango library to format multi-lingual texts, and
385 does not perform any input-encoding conversions. This means that any
386 text, be it title, lyric text, or musical instruction containing
387 non-ASCII characters, must be utf-8. The easiest way to enter such text is
388 by using a Unicode-aware editor and saving the file with utf-8 encoding. Most
389 popular modern editors have utf-8 support, for example, vim, Emacs,
392 @c Currently not working
394 Depending on the fonts installed, the following fragment shows Hebrew
401 @li lypondfile[fontload]{utf-8.ly}
403 The @TeX{} backend does not handle encoding specially at all. Strings
404 in the input are put in the output as-is. Extents of text items in the
405 @TeX{} backend, are determined by reading a file created via the
406 @file{texstr} backend,
409 lilypond -dbackend=texstr input/les-nereides.ly
410 latex les-nereides.texstr
413 The last command produces @file{les-nereides.textmetrics}, which is
414 read when you execute
417 lilypond -dbackend=tex input/les-nereides.ly
420 Both @file{les-nereides.texstr} and @file{les-nereides.tex} need
421 suitable LaTeX wrappers to load appropriate La@TeX{} packages for
422 interpreting non-ASCII strings.
426 To use a Unicode escape sequence, use
429 #(ly:export (ly:wide-char->utf-8 #x2014))
438 @node Different editions from one source
439 @subsection Different editions from one source
444 The @code{\tag} command marks music expressions with a name. These
445 tagged expressions can be filtered out later. With this mechanism it
446 is possible to make different versions of the same music source.
448 In the following example, we see two versions of a piece of music, one
449 for the full score, and one with cue notes for the instrumental part
465 The same can be applied to articulations, texts, etc.: they are
468 -\tag #@var{your-tag}
470 to an articulation, for example,
475 This defines a note with a conditional fingering indication.
478 @cindex removeWithTag
479 By applying the @code{\keepWithTag} and @code{\removeWithTag}
480 commands, tagged expressions can be filtered. For example,
484 \keepWithTag #'score @var{the music}
485 \keepWithTag #'part @var{the music}
490 @lilypondfile[ragged-right,quote]{tag-filter.ly}
492 The arguments of the @code{\tag} command should be a symbol
493 (such as @code{#'score} or @code{#'part}), followed by a
494 music expression. It is possible to put multiple tags on
495 a piece of music with multiple @code{\tag} entries,
498 \tag #'original-part \tag #'transposed-part @dots{}
504 Examples: @lsr{parts,tag@/-filter@/.ly}
509 Multiple rests are not merged if you create the score with both tagged
513 @node Titles and headers
514 @section Titles and headers
516 Almost all printed music includes a title and the composer's name;
517 some pieces include a lot more information.
522 * Reference to page numbers::
523 * Table of contents::
527 @node Creating titles
528 @subsection Creating titles
530 Titles are created for each @code{\score} block, as well as for the full
531 input file (or @code{\book} block).
533 The contents of the titles are taken from the @code{\header} blocks.
534 The header block for a book supports the following
540 The dedicatee of the music, centered at the top of the first page.
544 The title of the music, centered just below the dedication.
548 Subtitle, centered below the title.
550 @funindex subsubtitle
552 Subsubtitle, centered below the subtitle.
556 Name of the poet, flush-left below the subtitle.
560 Name of the composer, flush-right below the subtitle.
564 Meter string, flush-left below the poet.
568 Name of the opus, flush-right below the composer.
572 Name of the arranger, flush-right below the opus.
576 Name of the instrument, centered below the arranger. Also
577 centered at the top of pages (other than the first page).
581 Name of the piece, flush-left below the instrument.
583 @cindex page breaks, forcing
584 @funindex breakbefore
586 This forces the title to start on a new page (set to ##t or ##f).
590 Copyright notice, centered at the bottom of the first page. To
591 insert the copyright symbol, see @ref{Text encoding}.
595 Centered at the bottom of the last page.
599 Here is a demonstration of the fields available. Note that you
600 may use any @ref{Text markup}, commands in the header.
602 @lilypond[quote,verbatim,line-width=11.0\cm]
605 paper-height = 10.0\cm
610 dedication = "dedicated to me"
611 title = \markup \center-align { "Title first line" "Title second line,
613 subtitle = "the subtitle,"
614 subsubtitle = #(string-append "subsubtitle LilyPond version "
617 composer = \markup \center-align { "composer" \small "(1847-1973)" }
618 texttranslator = "Text Translator"
619 meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
621 arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize
622 #-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }
623 instrument = \markup \bold \italic "instrument"
647 As demonstrated before, you can use multiple @code{\header} blocks.
648 When same fields appear in different blocks, the latter is used.
649 Here is a short example.
653 composer = "Composer"
661 piece = "New piece" % overwrite previous one
666 If you define the @code{\header} inside the @code{\score} block, then
667 normally only the @code{piece} and @code{opus} headers will be printed.
668 Note that the music expression must come before the @code{\header}.
670 @lilypond[quote,verbatim,line-width=11.0\cm]
674 title = "title" % not printed
681 @funindex printallheaders
683 You may change this behavior (and print all the headers when defining
684 @code{\header} inside @code{\score}) by using
695 The default footer is empty, except for the first page, where the
696 @code{copyright} field from @code{\header} is inserted, and the last
697 page, where @code{tagline} from @code{\header} is added. The default
698 tagline is @qq{Music engraving by LilyPond (@var{version})}.@footnote{Nicely
699 printed parts are good PR for us, so please leave the tagline if you
702 Headers may be completely removed by setting them to false.
713 @subsection Custom titles
715 A more advanced option is to change the definitions of the following
716 variables in the @code{\paper} block. The init file
717 @file{ly/titling-init.ly} lists the default layout.
720 @funindex bookTitleMarkup
721 @item bookTitleMarkup
722 This is the title added at the top of the entire output document.
723 Typically, it has the composer and the title of the piece
725 @funindex scoreTitleMarkup
726 @item scoreTitleMarkup
727 This is the title put over a @code{\score} block. Typically, it has
728 the name of the movement (@code{piece} field).
730 @funindex oddHeaderMarkup
731 @item oddHeaderMarkup
732 This is the page header for odd-numbered pages.
734 @funindex evenHeaderMarkup
735 @item evenHeaderMarkup
736 This is the page header for even-numbered pages. If unspecified,
737 the odd header is used instead.
739 By default, headers are defined such that the page number is on the
740 outside edge, and the instrument is centered.
742 @funindex oddFooterMarkup
743 @item oddFooterMarkup
744 This is the page footer for odd-numbered pages.
746 @funindex evenFooterMarkup
747 @item evenFooterMarkup
748 This is the page footer for even-numbered pages. If unspecified,
749 the odd header is used instead.
751 By default, the footer has the copyright notice on the first, and
752 the tagline on the last page.
762 The following definition will put the title flush left, and the
763 composer flush right on a single line.
767 bookTitleMarkup = \markup {
769 \fromproperty #'header:title
770 \fromproperty #'header:composer
776 @node Reference to page numbers
777 @subsection Reference to page numbers
779 A particular place of a score can be marked using the @code{\label}
780 command, either at top-level or inside music. This label can then be
781 refered to in a markup, to get the number of the page where the marked
782 point is placed, using the @code{\page-ref} markup command.
784 @lilypond[verbatim,line-width=11.0\cm]
785 \header { tagline = ##f }
791 \pageBreak \mark A \label #'markA
796 \markup { The first score begins on page \page-ref #'firstScore "0" "?" }
797 \markup { Mark A is on page \page-ref #'markA "0" "?" }
801 The @code{\page-ref} markup command takes three arguments:
803 @item the label, a scheme symbol, eg. @code{#'firstScore};
804 @item a markup that will be used as a gauge to estimate the dimensions
806 @item a markup that will be used in place of the page number if the label
810 The reason why a gauge is needed is that, at the time markups are
811 interpreted, the page breaking has not yet occured, so the page numbers
812 are not yet known. To work around this issue, the actual markup
813 interpretation is delayed to a later time; however, the dimensions of
814 the markup have to be known before, so a gauge is used to decide these
815 dimensions. If the book has between 10 and 99 pages, it may be "00",
816 ie. a two digit number.
825 @node Table of contents
826 @subsection Table of contents
827 A table of contents is included using the @code{\markuplines \table-of-contents}
828 command. The elements which should appear in the table of contents are
829 entered with the @code{\tocItem} command, which may be used either at
830 top-level, or inside a music expression.
833 \markuplines \table-of-contents
836 \tocItem \markup "First score"
840 \tocItem \markup "Some particular point in the first score"
845 \tocItem \markup "Second score"
853 The markups which are used to format the table of contents are defined
854 in the @code{\paper} block. The default ones are @code{tocTitleMarkup},
855 for formatting the title of the table, and @code{tocItemMarkup}, for
856 formatting the toc elements, composed of the element title and page
857 number. These variables may be changed by the user:
861 %% Translate the toc title into French:
862 tocTitleMarkup = \markup \huge \column {
863 \fill-line { \null "Table des matières" \null }
866 %% use larfer font size
867 tocItemMarkup = \markup \large \fill-line {
868 \fromproperty #'toc:text \fromproperty #'toc:page
873 Note how the toc element text and page number are refered to in
874 the @code{tocItemMarkup} definition.
876 New commands and markups may also be defined to build more elaborated
879 @item first, define a new markup variable in the @code{\paper} block
880 @item then, define a music function which aims at adding a toc element
881 using this markup paper variable.
884 In the following example, a new style is defined for entering act names
885 in the table of contents of an opera:
889 tocActMarkup = \markup \large \column {
891 \fill-line { \null \italic \fromproperty #'toc:text \null }
897 #(define-music-function (parser location text) (markup?)
898 (add-toc-item! 'tocActMarkup text))
901 @lilypond[line-width=11.0\cm]
902 \header { tagline = ##f }
904 tocActMarkup = \markup \large \column {
906 \fill-line { \null \italic \fromproperty #'toc:text \null }
912 #(define-music-function (parser location text) (markup?)
913 (add-toc-item! 'tocActMarkup text))
916 \markuplines \table-of-contents
917 \tocAct \markup { Atto Primo }
918 \tocItem \markup { Coro. Viva il nostro Alcide }
919 \tocItem \markup { Cesare. Presti omai l'Egizzia terra }
920 \tocAct \markup { Atto Secondo }
921 \tocItem \markup { Sinfonia }
922 \tocItem \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
929 Init files: @file{ly/@/toc@/-init@/.ly}.
933 @funindex \table-of-contents
934 @code{\table-of-contents}
944 MIDI (Musical Instrument Digital Interface) is a standard for
945 connecting and controlling digital instruments. A MIDI file is a
946 series of notes in a number of tracks. It is not an actual
947 sound file; you need special software to translate between the
948 series of notes and actual sounds.
950 Pieces of music can be converted to MIDI files, so you can listen to
951 what was entered. This is convenient for checking the music; octaves
952 that are off or accidentals that were mistyped stand out very much
953 when listening to the MIDI output.
957 Many musically interesting effects, such as swing, articulation,
958 slurring, etc., are not translated to midi.
960 The midi output allocates a channel for each staff, and one for global
961 settings. Therefore the midi file should not have more than 15 staves
962 (or 14 if you do not use drums). Other staves will remain silent.
964 Not all midi players correctly handle tempo changes in the midi
965 output. Players that are known to work include
966 @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
969 * Creating MIDI files::
971 * MIDI instrument names::
974 @node Creating MIDI files
975 @subsection Creating MIDI files
977 To create a MIDI from a music piece of music, add a @code{\midi} block
978 to a score, for example,
986 tempoWholesPerMinute = #(ly:make-moment 72 4)
992 The tempo can be specified using the @code{\tempo} command within the
993 actual music, see @ref{Metronome marks}. An alternative, which does not
994 result in a metronome mark in the printed score, is shown in the example
995 above. In this example the tempo of quarter notes is set to 72 beats per
998 specification can not take dotted note lengths as an argument. In this
999 case, break the dotted notes into smaller units. For example, a tempo
1000 of 90 dotted quarter notes per minute can be specified as 270 eighth
1004 tempoWholesPerMinute = #(ly:make-moment 270 8)
1007 If there is a @code{\midi} command in a @code{\score}, only MIDI will
1008 be produced. When notation is needed too, a @code{\layout} block must
1018 @cindex layout block
1022 Ties, dynamics, and tempo changes are interpreted. Dynamic marks,
1023 crescendi and decrescendi translate into MIDI volume levels. Dynamic
1024 marks translate to a fixed fraction of the available MIDI volume
1025 range, crescendi and decrescendi make the volume vary linearly between
1026 their two extremes. The fractions can be adjusted by
1027 @code{dynamicAbsoluteVolumeFunction} in @internalsref{Voice} context.
1028 For each type of MIDI instrument, a volume range can be defined. This
1029 gives a basic equalizer control, which can enhance the quality of
1030 the MIDI output remarkably. The equalizer can be controlled by
1031 setting @code{instrumentEqualizer}, or by setting
1034 \set Staff.midiMinimumVolume = #0.2
1035 \set Staff.midiMaximumVolume = #0.8
1038 To remove dynamics from the MIDI output, insert the following lines
1039 in the @code{\midi@{@}} section.
1046 \remove "Dynamic_performer"
1054 Unterminated (de)crescendos will not render properly in the midi file,
1055 resulting in silent passages of music. The workaround is to explicitly
1056 terminate the (de)crescendo. For example,
1063 will not work properly but
1073 MIDI output is only created when the @code{\midi} command is within
1074 a @code{\score} block. If you put it within an explicitly instantiated
1075 context ( i.e. @code{\new Score} ) the file will fail. To solve this,
1076 enclose the @code{\new Score} and the @code{\midi} in a @code{\score} block.
1080 \new Score @{ @dots{}notes@dots{} @}
1087 @subsection MIDI block
1091 The MIDI block is analogous to the layout block, but it is somewhat
1092 simpler. The @code{\midi} block is similar to @code{\layout}. It can contain
1093 context definitions.
1096 @cindex context definition
1098 Context definitions follow precisely the same syntax as within the
1099 \layout block. Translation modules for sound are called performers.
1100 The contexts for MIDI output are defined in @file{ly/@/performer@/-init@/.ly}.
1103 @node MIDI instrument names
1104 @subsection MIDI instrument names
1106 @cindex instrument names
1107 @funindex Staff.midiInstrument
1109 The MIDI instrument name is set by the @code{Staff.midiInstrument}
1110 property. The instrument name should be chosen from the list in
1111 @ref{MIDI instruments}.
1114 \set Staff.midiInstrument = "glockenspiel"
1118 If the selected instrument does not exactly match an instrument from
1119 the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
1123 @c Yes, this is a cop-out; this info doesn't belong in the Scheme
1124 @c chapter, but I'm not certain where to stick it.
1125 @c I think I'll eventually split this chapter into a "paper/layout"
1126 @c chapter and a "misc issues" chapter. -gp
1127 @node Displaying LilyPond notation
1128 @section Displaying LilyPond notation
1130 @funindex \displayLilyMusic
1131 Displaying a music expression in LilyPond notation can be
1132 done using the music function @code{\displayLilyMusic}. For example,
1136 \displayLilyMusic \transpose c a, @{ c e g a bes @}
1143 @{ a, cis e fis g @}
1146 By default, LilyPond will print these messages to the console along
1147 with all the other messages. To split up these messages and save
1148 the results of @code{\display@{STUFF@}}, redirect the output to
1152 lilypond file.ly >display.txt
1156 @node Skipping corrected music
1157 @section Skipping corrected music
1160 @funindex skipTypesetting
1161 @funindex showLastLength
1163 When entering or copying music, usually only the music near the end (where
1165 are adding notes) is interesting to view and correct. To speed up
1166 this correction process, it is possible to skip typesetting of all but
1167 the last few measures. This is achieved by putting
1170 showLastLength = R1*5
1175 in your source file. This will render only the last 5 measures
1176 (assuming 4/4 time signature) of every @code{\score} in the input
1177 file. For longer pieces, rendering only a small part is often an order
1178 of magnitude quicker than rendering it completely
1180 Skipping parts of a score can be controlled in a more fine-grained
1181 fashion with the property @code{Score.skipTypesetting}. When it is
1182 set, no typesetting is performed at all.
1184 This property is also used to control output to the MIDI file. Note that
1185 it skips all events, including tempo and instrument changes. You have
1188 @lilypond[quote,fragment,ragged-right,verbatim]
1191 \set Score.skipTypesetting = ##t
1193 \set Score.skipTypesetting = ##f
1197 In polyphonic music, @code{Score.skipTypesetting} will affect all
1198 voices and staves, saving even more time.