1 @c -*- coding: utf-8; mode: texinfo; -*-
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.
12 @node General input and output
13 @chapter General input and output
15 This section deals with general LilyPond input and output issues,
16 rather than specific notation.
20 * Titles and headers::
21 * Working with input files::
22 * Controlling output::
28 @section Input structure
30 The main format of input for LilyPond are text files. By convention,
31 these files end with @code{.ly}.
34 * Structure of a score::
35 * Multiple scores in a book::
40 @node Structure of a score
41 @subsection Structure of a score
45 A @code{\score} block must contain a single music expression
46 delimited by curly brackets:
54 @warning{There must be @strong{only one} outer music expression in
55 a @code{\score} block, and it @strong{must} be surrounded by
58 This single music expression may be of any size, and may contain
59 other music expressions to any complexity. All of these examples
60 are music expressions:
66 @lilypond[verbatim,quote]
73 @lilypond[verbatim,quote]
75 \new Staff { c'4 c' c' c' }
76 \new Staff { d'4 d' d' d' }
84 \new Staff @{ \flute @}
85 \new Staff @{ \oboe @}
88 \new Staff @{ \violinI @}
89 \new Staff @{ \violinII @}
95 Comments are one exception to this general rule. (For others see
96 @ref{File structure}.) Both single-line comments and comments
97 delimited by @code{%@{ .. %@}} may be placed anywhere within an
98 input file. They may be placed inside or outside a @code{\score}
99 block, and inside or outside the single music expression within a
105 @rlearning{Working on input files},
106 @rlearning{Music expressions explained},
107 @rlearning{Score is a (single) compound musical expression}.
110 @node Multiple scores in a book
111 @subsection Multiple scores in a book
114 @cindex movements, multiple
116 A document may contain multiple pieces of music and text. Examples
117 of these are an etude book, or an orchestral part with multiple
118 movements. Each movement is entered with a @code{\score} block,
126 and texts are entered with a @code{\markup} block,
136 All the movements and texts which appear in the same @code{.ly} file
137 will normally be typeset in the form of a single output file.
151 However, if you want multiple output files from the same @code{.ly}
152 file, then you can add multiple @code{\book} blocks, where each such
153 @code{\book} block will result in a separate output. If you do not
154 specify any @code{\book} block in the file, LilyPond will implicitly
155 treat the full file as a single @code{\book} block, see @ref{File
156 structure}. One important exception is within lilypond-book documents,
157 where you explicitly have to add a @code{\book} block, otherwise only
158 the first @code{\score} or @code{\markup} will appear in the output.
160 The header for each piece of music can be put inside the @code{\score}
161 block. The @code{piece} name from the header will be printed before
162 each movement. The title for the entire book can be put inside the
163 @code{\book}, but if it is not present, the @code{\header} which is at
164 the top of the file is inserted.
168 title = "Eight miniatures"
169 composer = "Igor Stravinsky"
173 \header @{ piece = "Romanze" @}
176 ..text of second verse..
179 ..text of third verse..
183 \header @{ piece = "Menuetto" @}
189 Pieces of music may be grouped into book parts using @code{\bookpart}
190 blocks. Book parts are separated by a page break, and can start with a
191 title, like the book itself, by specifying a @code{\header} block.
197 subtitle = "First part"
204 subtitle = "Second part"
212 @subsection File structure
222 A @code{.ly} file may contain any number of toplevel expressions, where a
223 toplevel expression is one of the following:
227 An output definition, such as @code{\paper}, @code{\midi}, and
228 @code{\layout}. Such a definition at the toplevel changes the default
229 book-wide settings. If more than one such definition of
230 the same type is entered at the top level any definitions in the later
231 expressions have precedence.
234 A direct scheme expression, such as
235 @code{#(set-default-paper-size "a7" 'landscape)} or
236 @code{#(ly:set-option 'point-and-click #f)}.
239 A @code{\header} block. This sets the global header block. This
240 is the block containing the definitions for book-wide settings, like
241 composer, title, etc.
244 A @code{\score} block. This score will be collected with other
245 toplevel scores, and combined as a single @code{\book}.
246 This behavior can be changed by setting the variable
247 @code{toplevel-score-handler} at toplevel. The default handler is
248 defined in the init file @file{../@/scm/@/lily@/.scm}.
251 A @code{\book} block logically combines multiple movements
252 (i.e., multiple @code{\score} blocks) in one document. If there
253 are a number of @code{\score}s, one output file will be created
254 for each @code{\book} block, in which all corresponding movements
255 are concatenated. The only reason to explicitly specify
256 @code{\book} blocks in a @code{.ly} file is if you wish to create
257 multiple output files from a single input file. One exception is
258 within lilypond-book documents, where you explicitly have to add
259 a @code{\book} block if you want more than a single @code{\score}
260 or @code{\markup} in the same example. This behavior can be
261 changed by setting the variable @code{toplevel-book-handler} at
262 toplevel. The default handler is defined in the init file
263 @file{../@/scm/@/lily@/.scm}.
266 A @code{\bookpart} block. A book may be divided into several parts,
267 using @code{\bookpart} blocks, in order to ease the page breaking,
268 or to use different @code{\paper} settings in different parts.
271 A compound music expression, such as
276 This will add the piece in a @code{\score} and format it in a
277 single book together with all other toplevel @code{\score}s and music
278 expressions. In other words, a file containing only the above
279 music expression will be translated into
295 This behavior can be changed by setting the variable
296 @code{toplevel-music-handler} at toplevel. The default handler is
297 defined in the init file @file{../@/scm/@/lily@/.scm}.
300 A markup text, a verse for example
303 2. The first line verse two.
307 Markup texts are rendered above, between or below the scores or music
308 expressions, wherever they appear.
318 This can be used later on in the file by entering @code{\foo}. The
319 name of a variable should have alphabetic characters only; no
320 numbers, underscores or dashes.
324 The following example shows three things that may be entered at
329 % Don't justify the output
341 At any point in a file, any of the following lexical instructions can
345 @item @code{\version}
346 @item @code{\include}
347 @item @code{\sourcefilename}
348 @item @code{\sourcefileline}
350 A single-line comment, introduced by a leading @code{%} sign.
353 A multi-line comment delimited by @code{%@{ .. %@}}.
359 Whitespace between items in the input stream is generally ignored,
360 and may be freely omitted or extended to enhance readability.
361 However, whitespace should always be used in the following
362 circumstances to avoid errors:
365 @item Around every opening and closing curly bracket.
366 @item After every command or variable, i.e. every item that
367 begins with a @code{\} sign.
368 @item After every item that is to be interpreted as a Scheme
369 expression, i.e. every item that begins with a @code{#} sign.
370 @item To separate all elements of a Scheme expression.
371 @item In @code{lyricmode} to separate all the terms in both
372 @code{\override} and @code{\set} commands. In particular, spaces
373 must be used around the dot and the equals sign in commands like
374 @code{\override Score . LyricText #'font-size = #5} and before and
375 after the entire command.
382 @rlearning{How LilyPond input files work}.
385 @node Titles and headers
386 @section Titles and headers
388 Almost all printed music includes a title and the composer's name;
389 some pieces include a lot more information.
394 * Reference to page numbers::
395 * Table of contents::
399 @node Creating titles
400 @subsection Creating titles
402 Titles are created for each @code{\score} block, as well as for the full
403 input file (or @code{\book} block) and book parts (created by
404 @code{\bookpart} blocks).
406 The contents of the titles are taken from the @code{\header} blocks.
407 The header block for a book supports the following
413 The dedicatee of the music, centered at the top of the first page.
417 The title of the music, centered just below the dedication.
421 Subtitle, centered below the title.
423 @funindex subsubtitle
425 Subsubtitle, centered below the subtitle.
429 Name of the poet, flush-left below the subsubtitle.
433 Name of the instrument, centered below the subsubtitle. Also
434 centered at the top of pages (other than the first page).
438 Name of the composer, flush-right below the subsubtitle.
442 Meter string, flush-left below the poet.
446 Name of the arranger, flush-right below the composer.
450 Name of the piece, flush-left below the meter.
454 Name of the opus, flush-right below the arranger.
456 @cindex page breaks, forcing
457 @funindex breakbefore
459 This forces the title to start on a new page (set to ##t or ##f).
463 Copyright notice, centered at the bottom of the first page. To
464 insert the copyright symbol, see @ref{Text encoding}.
468 Centered at the bottom of the last page.
472 Here is a demonstration of the fields available. Note that you
473 may use any @ref{Formatting text}, commands in the header.
475 @lilypond[quote,verbatim,line-width=11.0\cm]
478 paper-height = 10.0\cm
483 dedication = "dedicated to me"
484 title = \markup \center-column { "Title first line" "Title second line,
486 subtitle = "the subtitle,"
487 subsubtitle = #(string-append "subsubtitle LilyPond version "
490 composer = \markup \center-column { "composer" \small "(1847-1973)" }
491 texttranslator = "Text Translator"
492 meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
494 arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize
495 #-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }
496 instrument = \markup \bold \italic "instrument"
520 As demonstrated before, you can use multiple @code{\header} blocks.
521 When same fields appear in different blocks, the latter is used.
522 Here is a short example.
526 composer = "Composer"
534 piece = "New piece" % overwrite previous one
539 If you define the @code{\header} inside the @code{\score} block, then
540 normally only the @code{piece} and @code{opus} headers will be printed.
541 Note that the music expression must come before the @code{\header}.
543 @lilypond[quote,verbatim,line-width=11.0\cm]
547 title = "title" % not printed
554 @funindex print-all-headers
556 You may change this behavior (and print all the headers when defining
557 @code{\header} inside @code{\score}) by using
561 print-all-headers = ##t
568 The default footer is empty, except for the first page, where the
569 @code{copyright} field from @code{\header} is inserted, and the last
570 page, where @code{tagline} from @code{\header} is added. The default
571 tagline is @qq{Music engraving by LilyPond (@var{version})}.@footnote{Nicely
572 printed parts are good PR for us, so please leave the tagline if you
575 Headers may be completely removed by setting them to false.
586 @subsection Custom titles
588 A more advanced option is to change the definitions of the following
589 variables in the @code{\paper} block. The init file
590 @file{../@/ly/@/titling@/-init@/.ly} lists the default layout.
593 @funindex bookTitleMarkup
594 @item bookTitleMarkup
595 This is the title added at the top of the entire output document.
596 Typically, it has the composer and the title of the piece
598 @funindex scoreTitleMarkup
599 @item scoreTitleMarkup
600 This is the title put over a @code{\score} block. Typically, it has
601 the name of the movement (@code{piece} field).
603 @funindex oddHeaderMarkup
604 @item oddHeaderMarkup
605 This is the page header for odd-numbered pages.
607 @funindex evenHeaderMarkup
608 @item evenHeaderMarkup
609 This is the page header for even-numbered pages. If unspecified,
610 the odd header is used instead.
612 By default, headers are defined such that the page number is on the
613 outside edge, and the instrument is centered.
615 @funindex oddFooterMarkup
616 @item oddFooterMarkup
617 This is the page footer for odd-numbered pages.
619 @funindex evenFooterMarkup
620 @item evenFooterMarkup
621 This is the page footer for even-numbered pages. If unspecified,
622 the odd header is used instead.
624 By default, the footer has the copyright notice on the first, and
625 the tagline on the last page.
635 The following definition will put the title flush left, and the
636 composer flush right on a single line.
640 bookTitleMarkup = \markup {
642 \fromproperty #'header:title
643 \fromproperty #'header:composer
649 @node Reference to page numbers
650 @subsection Reference to page numbers
652 A particular place of a score can be marked using the @code{\label}
653 command, either at top-level or inside music. This label can then be
654 referred to in a markup, to get the number of the page where the marked
655 point is placed, using the @code{\page-ref} markup command.
657 @lilypond[verbatim,line-width=11.0\cm]
658 \header { tagline = ##f }
664 \pageBreak \mark A \label #'markA
669 \markup { The first score begins on page \page-ref #'firstScore "0" "?" }
670 \markup { Mark A is on page \page-ref #'markA "0" "?" }
674 The @code{\page-ref} markup command takes three arguments:
676 @item the label, a scheme symbol, eg. @code{#'firstScore};
677 @item a markup that will be used as a gauge to estimate the dimensions
679 @item a markup that will be used in place of the page number if the label
683 The reason why a gauge is needed is that, at the time markups are
684 interpreted, the page breaking has not yet occurred, so the page numbers
685 are not yet known. To work around this issue, the actual markup
686 interpretation is delayed to a later time; however, the dimensions of
687 the markup have to be known before, so a gauge is used to decide these
688 dimensions. If the book has between 10 and 99 pages, it may be "00",
689 ie. a two digit number.
700 @node Table of contents
701 @subsection Table of contents
702 A table of contents is included using the @code{\markuplines \table-of-contents}
703 command. The elements which should appear in the table of contents are
704 entered with the @code{\tocItem} command, which may be used either at
705 top-level, or inside a music expression.
708 \markuplines \table-of-contents
711 \tocItem \markup "First score"
715 \tocItem \markup "Some particular point in the first score"
720 \tocItem \markup "Second score"
728 The markups which are used to format the table of contents are defined
729 in the @code{\paper} block. The default ones are @code{tocTitleMarkup},
730 for formatting the title of the table, and @code{tocItemMarkup}, for
731 formatting the toc elements, composed of the element title and page
732 number. These variables may be changed by the user:
736 %% Translate the toc title into French:
737 tocTitleMarkup = \markup \huge \column {
738 \fill-line { \null "Table des matières" \null }
741 %% use larger font size
742 tocItemMarkup = \markup \large \fill-line {
743 \fromproperty #'toc:text \fromproperty #'toc:page
748 Note how the toc element text and page number are referred to in
749 the @code{tocItemMarkup} definition.
751 New commands and markups may also be defined to build more elaborated
754 @item first, define a new markup variable in the @code{\paper} block
755 @item then, define a music function which aims at adding a toc element
756 using this markup paper variable.
759 In the following example, a new style is defined for entering act names
760 in the table of contents of an opera:
764 tocActMarkup = \markup \large \column {
766 \fill-line { \null \italic \fromproperty #'toc:text \null }
772 #(define-music-function (parser location text) (markup?)
773 (add-toc-item! 'tocActMarkup text))
776 @lilypond[line-width=11.0\cm]
777 \header { tagline = ##f }
779 tocActMarkup = \markup \large \column {
781 \fill-line { \null \italic \fromproperty #'toc:text \null }
787 #(define-music-function (parser location text) (markup?)
788 (add-toc-item! 'tocActMarkup text))
791 \markuplines \table-of-contents
792 \tocAct \markup { Atto Primo }
793 \tocItem \markup { Coro. Viva il nostro Alcide }
794 \tocItem \markup { Cesare. Presti omai l'Egizzia terra }
795 \tocAct \markup { Atto Secondo }
796 \tocItem \markup { Sinfonia }
797 \tocItem \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
804 Init files: @file{../@/ly/@/toc@/-init@/.ly}.
808 @funindex \table-of-contents
809 @code{\table-of-contents},
815 @node Working with input files
816 @section Working with input files
819 * Including LilyPond files::
820 * Different editions from one source::
822 * Displaying LilyPond notation::
826 @node Including LilyPond files
827 @subsection Including LilyPond files
830 @cindex including files
832 A large project may be split up into separate files. To refer to
836 \include "otherfile.ly"
839 The line @code{\include "otherfile.ly"} is equivalent to pasting the
840 contents of @file{otherfile.ly} into the current file at the place
841 where the @code{\include} appears. For example, in a large
842 project you might write separate files for each instrument part
843 and create a @qq{full score} file which brings together the
844 individual instrument files. Normally the included file will
845 define a number of variables which then become available
846 for use in the full score file. Tagged sections can be
847 marked in included files to assist in making them usable in
848 different places in a score, see @ref{Different editions from
851 Files in the current working directory may be referenced by
852 specifying just the file name after the @code{\include} command.
853 Files in other locations may be included by giving either a full
854 path reference or a relative path reference (but use the UNIX
855 forward slash, /, rather than the DOS/Windows back slash, \, as the
856 directory separator.) For example, if @file{stuff.ly} is located
857 one directory higher than the current working directory, use
860 \include "../stuff.ly"
864 or if the included orchestral parts files are all located in a
865 subdirectory called @file{parts} within the current directory, use
868 \include "parts/VI.ly"
869 \include "parts/VII.ly"
873 Files which are to be included can also contain @code{\include}
874 statements of their own. By default, these second-level
875 @code{\include} statements are not interpreted until they have
876 been brought into the main file, so the file names they specify
877 must all be relative to the directory containing the main file,
878 not the directory containing the included file. However,
879 this behavior can be changed by passing the option
880 @code{-drelative-includes} option at the command line
881 (or by adding @code{#(ly:set-option 'relative-includes #t)}
882 at the top of the main input file). With @code{relative-includes}
883 set, the path for each @code{\include} command will be taken
884 relative to the file containing that command. This behavior is
885 recommended and it will become the default behavior in a future
888 Files can also be included from a directory in a search path
889 specified as an option when invoking LilyPond from the command
890 line. The included files are then specified using just their
891 file name. For example, to compile @file{main.ly} which includes
892 files located in a subdirectory called @file{parts} by this method,
893 cd to the directory containing @file{main.ly} and enter
896 lilypond --include=parts main.ly
907 Files which are to be included in many scores may be placed in
908 the LilyPond directory @file{../ly}. (The location of this
909 directory is installation-dependent - see
910 @rlearning{Other sources of information}). These files can then
911 be included simply by naming them on an @code{\include} statement.
912 This is how the language-dependent files like @file{english.ly} are
915 LilyPond includes a number of files by default when you start
916 the program. These includes are not apparent to the user, but the
917 files may be identified by running @code{lilypond --verbose} from
918 the command line. This will display a list of paths and files that
919 LilyPond uses, along with much other information. Alternatively,
920 the more important of these files are discussed in
921 @rlearning{Other sources of information}. These files may be
922 edited, but changes to them will be lost on installing a new
925 Some simple examples of using @code{\include} are shown in
926 @rlearning{Scores and parts}.
931 @rlearning{Other sources of information},
932 @rlearning{Scores and parts}.
937 If an included file is given a name which is the same as one in
938 LilyPond's installation files, LilyPond's file from the
939 installation files takes precedence.
943 @node Different editions from one source
944 @subsection Different editions from one source
946 Several mechanisms are available to facilitate the generation
947 of different versions of a score from the same music source.
948 Variables are perhaps most useful for combining lengthy sections
949 of music and/or annotation in various ways, while tags are more
950 useful for selecting one from several alternative shorter sections
951 of music. Whichever method is used, separating the notation from
952 the structure of the score will make it easier to change the
953 structure while leaving the notation untouched.
960 @node Using variables
961 @unnumberedsubsubsec Using variables
963 @cindex variables, use of
965 If sections of the music are defined in variables they can be
966 reused in different parts of the score, see @rlearning{Organizing
967 pieces with variables}. For example, an @notation{a cappella}
968 vocal score frequently includes a piano reduction of the parts
969 for rehearsal purposes which is identical to the vocal music, so
970 the music need be entered only once. Music from two variables
971 may be combined on one staff, see @ref{Automatic part combining}.
974 @lilypond[verbatim,quote]
975 sopranoMusic = \relative c'' { a4 b c b8( a)}
976 altoMusic = \relative g' { e4 e e f }
977 tenorMusic = \relative c' { c4 b e d8( c) }
978 bassMusic = \relative c' { a4 gis a d, }
979 allLyrics = \lyricmode {King of glo -- ry }
981 \new Staff = "Soprano" \sopranoMusic
982 \new Lyrics \allLyrics
983 \new Staff = "Alto" \altoMusic
984 \new Lyrics \allLyrics
985 \new Staff = "Tenor" {
989 \new Lyrics \allLyrics
990 \new Staff = "Bass" {
994 \new Lyrics \allLyrics
997 \set Staff.printPartCombineTexts = ##f
1003 \set Staff.printPartCombineTexts = ##f
1013 Separate scores showing just the vocal parts or just the piano
1014 part can be produced by changing just the structural statements,
1015 leaving the musical notation unchanged.
1017 For lengthy scores, the variable definitions may be placed in
1018 separate files which are then included, see @ref{Including
1022 @unnumberedsubsubsec Using tags
1025 @funindex \keepWithTag
1026 @funindex \removeWithTag
1028 @cindex keep tagged music
1029 @cindex remove tagged music
1031 The @code{\tag #'@var{partA}} command marks a music expression
1032 with the name @var{partA}.
1033 Expressions tagged in this way can be selected or filtered out by
1034 name later, using either @code{\keepWithTag #'@var{name}} or
1035 @code{\removeWithTag #'@var{name}}. The result of applying these filters
1036 to tagged music is as follows:
1037 @multitable @columnfractions .5 .5
1041 Tagged music preceded by @code{\keepWithTag #'@var{name}}
1042 @tab Untagged music and music tagged with @var{name} is included;
1043 music tagged with any other tag name is excluded.
1045 Tagged music preceded by @code{\removeWithTag #'@var{name}}
1046 @tab Untagged music and music tagged with any tag name other than
1047 @var{name} is included; music tagged with @var{name} is
1050 Tagged music not preceded by either @code{\keepWithTag} or
1051 @code{\removeWithTag}
1052 @tab All tagged and untagged music is included.
1055 The arguments of the @code{\tag}, @code{\keepWithTag} and
1056 @code{\removeWithTag} commands should be a symbol
1057 (such as @code{#'score} or @code{#'part}), followed
1058 by a music expression.
1060 In the following example, we see two versions of a piece of music,
1061 one showing trills with the usual notation, and one with trills
1062 explicitly expanded:
1064 @lilypond[verbatim,quote]
1065 music = \relative g' {
1067 \tag #'trills {d8.\trill }
1068 \tag #'expand {\repeat unfold 3 {e32 d} }
1073 \keepWithTag #'trills \music
1076 \keepWithTag #'expand \music
1081 Alternatively, it is sometimes easier to exclude sections of music:
1083 @lilypond[verbatim,quote]
1084 music = \relative g' {
1086 \tag #'trills {d8.\trill }
1087 \tag #'expand {\repeat unfold 3 {e32 d} }
1092 \removeWithTag #'expand
1096 \removeWithTag #'trills
1101 Tagged filtering can be applied to articulations, texts, etc. by
1105 -\tag #'@var{your-tag}
1108 to an articulation. For example, this would define a note with a
1109 conditional fingering indication and a note with a conditional
1114 c1-\tag #'warn ^"Watch!"
1117 Multiple tags may be placed on expressions with multiple
1118 @code{\tag} entries:
1120 @lilypond[quote,verbatim]
1121 music = \relative c'' {
1122 \tag #'a \tag #'both { a a a a }
1123 \tag #'b \tag #'both { b b b b }
1126 \keepWithTag #'a \music
1127 \keepWithTag #'b \music
1128 \keepWithTag #'both \music
1132 Multiple @code{\removeWithTag} filters may be applied to a single
1133 music expression to remove several differently named tagged sections:
1135 @lilypond[verbatim,quote]
1136 music = \relative c'' {
1137 \tag #'A { a a a a }
1138 \tag #'B { b b b b }
1139 \tag #'C { c c c c }
1140 \tag #'D { d d d d }
1149 Two or more @code{\keepWithTag} filters applied to a single music
1150 expression will cause @emph{all} tagged sections to be removed, as
1151 the first filter will remove all tagged sections except the one
1152 named, and the second filter will remove even that tagged section.
1157 @rlearning{Organizing pieces with variables}.
1160 @ref{Automatic part combining},
1161 @ref{Including LilyPond files}.
1165 @c This warning is more general than this placement implies.
1166 @c Rests are not merged whether or not they come from tagged sections.
1167 @c Should be deleted? -td
1171 Multiple rests are not merged if you create a score with more
1172 than one tagged section at the same place.
1177 @subsection Text encoding
1181 @cindex non-ASCII characters
1183 LilyPond uses the character repertoire defined by the Unicode
1184 consortium and ISO/IEC 10646. This defines a unique name and
1185 code point for the character sets used in virtually all modern
1186 languages and many others too. Unicode can be implemented using
1187 several different encodings. LilyPond uses the UTF-8 encoding
1188 (UTF stands for Unicode Transformation Format) which represents
1189 all common Latin characters in one byte, and represents other
1190 characters using a variable length format of up to four bytes.
1192 The actual appearance of the characters is determined by the
1193 glyphs defined in the particular fonts available - a font defines
1194 the mapping of a subset of the Unicode code points to glyphs.
1195 LilyPond uses the Pango library to layout and render multi-lingual
1198 LilyPond does not perform any input-encoding conversions. This
1199 means that any text, be it title, lyric text, or musical
1200 instruction containing non-ASCII characters, must be encoded in
1201 UTF-8. The easiest way to enter such text is by using a
1202 Unicode-aware editor and saving the file with UTF-8 encoding. Most
1203 popular modern editors have UTF-8 support, for example, vim, Emacs,
1204 jEdit, and GEdit do. All MS Windows systems later than NT use
1205 Unicode as their native character encoding, so even Notepad can
1206 edit and save a file in UTF-8 format. A more functional
1207 alternative for Windows is BabelPad.
1209 If a LilyPond input file containing a non-ASCII character is not
1210 saved in UTF-8 format the error message
1213 FT_Get_Glyph_Name () error: invalid argument
1218 Here is an example showing Cyrillic, Hebrew and Portuguese
1222 %c No verbatim here as the code does not display correctly in PDF
1224 bulgarian = \lyricmode {
1225 Жълтата дюля беше щастлива, че пухът, който цъфна, замръзна като гьон.
1229 hebrew = \lyricmode {
1230 זה כיף סתם לשמוע איך תנצח קרפד עץ טוב בגן.
1234 portuguese = \lyricmode {
1235 à vo -- cê uma can -- ção legal
1241 \addlyrics { \bulgarian }
1242 \addlyrics { \hebrew }
1243 \addlyrics { \portuguese }
1246 To enter a single character for which the Unicode code point is
1247 known but which is not available in the editor being used, use
1248 either @code{\char ##xhhhh} or @code{\char #dddd} within a
1249 @code{\markup} block, where @code{hhhh} is the hexadecimal code for
1250 the character required and @code{dddd} is the corresponding decimal
1251 value. Leading zeroes may be omitted, but it is usual to specify
1252 all four characters in the hexadecimal representation. (Note that
1253 the UTF-8 encoding of the code point should @emph{not} be used
1254 after @code{\char}, as UTF-8 encodings contain extra bits indicating
1255 the number of octets.) Unicode code charts and a character name
1256 index giving the code point in hexadecimal for any character can be
1257 found on the Unicode Consortium website,
1258 @uref{http://www.unicode.org/}.
1260 For example, @code{\char ##x03BE} and @code{\char #958} would both
1261 enter the Unicode U+03BE character, which has the Unicode name
1262 @qq{Greek Small Letter Xi}.
1264 Any Unicode code point may be entered in this way and if all special
1265 characters are entered in this format it is not necessary to save
1266 the input file in UTF-8 format. Of course, a font containing all
1267 such encoded characters must be installed and available to LilyPond.
1269 The following example shows Unicode hexadecimal values being entered
1270 in four places -- in a rehearsal mark, as articulation text, in
1271 lyrics and as stand-alone text below the score:
1273 @lilypond[quote,verbatim]
1276 c1 \mark \markup { \char ##x03EE }
1277 c1_\markup { \tiny { \char ##x03B1 " to " \char ##x03C9 } }
1279 \addlyrics { O \markup { \concat{ Ph \char ##x0153 be! } } }
1281 \markup { "Copyright 2008--2009" \char ##x00A9 }
1284 @cindex copyright sign
1286 To enter the copyright sign in the copyright notice use:
1290 copyright = \markup @{ \char ##x00A9 "2008" @}
1294 @node Displaying LilyPond notation
1295 @subsection Displaying LilyPond notation
1297 @funindex \displayLilyMusic
1298 Displaying a music expression in LilyPond notation can be
1299 done using the music function @code{\displayLilyMusic}. For example,
1303 \displayLilyMusic \transpose c a, @{ c e g a bes @}
1310 @{ a, cis e fis g @}
1313 By default, LilyPond will print these messages to the console along
1314 with all the other messages. To split up these messages and save
1315 the results of @code{\display@{STUFF@}}, redirect the output to
1318 @c TODO What happens under Windows?
1321 lilypond file.ly >display.txt
1326 @node Controlling output
1327 @section Controlling output
1330 * Extracting fragments of music::
1331 * Skipping corrected music::
1332 * Alternative output formats::
1335 @node Extracting fragments of music
1336 @subsection Extracting fragments of music
1338 It is possible to quote small fragments of a large score directly from
1339 the output. This can be compared to clipping a piece of a paper score
1342 This is done by defining the measures that need to be cut out
1343 separately. For example, including the following definition
1351 (make-rhythmic-location 5 1 2)
1352 (make-rhythmic-location 7 3 4)))
1357 will extract a fragment starting halfway the fifth measure, ending in
1358 the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note
1359 in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7.
1361 More clip regions can be defined by adding more pairs of
1362 rhythmic-locations to the list.
1364 In order to use this feature, LilyPond must be invoked with
1365 @code{-dclip-systems}. The clips are output as EPS files, and are
1366 converted to PDF and PNG if these formats are switched on as well.
1368 For more information on output formats, see @rprogram{Invoking lilypond}.
1370 @node Skipping corrected music
1371 @subsection Skipping corrected music
1374 @funindex skipTypesetting
1375 @funindex showFirstLength
1376 @funindex showLastLength
1378 When entering or copying music, usually only the music near the end (where
1380 are adding notes) is interesting to view and correct. To speed up
1381 this correction process, it is possible to skip typesetting of all but
1382 the last few measures. This is achieved by putting
1385 showLastLength = R1*5
1390 in your source file. This will render only the last 5 measures
1391 (assuming 4/4 time signature) of every @code{\score} in the input
1392 file. For longer pieces, rendering only a small part is often an order
1393 of magnitude quicker than rendering it completely. When working on the
1394 beginning of a score you have already typeset (e.g. to add a new part),
1395 the @code{showFirstLength} property may be useful as well.
1397 Skipping parts of a score can be controlled in a more fine-grained
1398 fashion with the property @code{Score.skipTypesetting}. When it is
1399 set, no typesetting is performed at all.
1401 This property is also used to control output to the MIDI file. Note that
1402 it skips all events, including tempo and instrument changes. You have
1405 @lilypond[quote,fragment,ragged-right,verbatim]
1408 \set Score.skipTypesetting = ##t
1410 \set Score.skipTypesetting = ##f
1414 In polyphonic music, @code{Score.skipTypesetting} will affect all
1415 voices and staves, saving even more time.
1417 @node Alternative output formats
1418 @subsection Alternative output formats
1420 @cindex scalable vector graphics output
1422 @cindex encapsulated postscript output
1425 The default output formats for the printed score are Portable
1426 Document Format (PDF) and PostScript (PS). Scalable Vector
1427 Graphics (SVG), Encapsulated PostScript (EPS) and Portable
1428 Network Graphics (PNG) output formats are also available through
1429 command line options, see @rprogram{Command line options for
1434 @section MIDI output
1439 MIDI (Musical Instrument Digital Interface) is a standard for
1440 connecting and controlling digital instruments. A MIDI file is a
1441 series of notes in a number of tracks. It is not an actual
1442 sound file; you need special software to translate between the
1443 series of notes and actual sounds.
1445 Pieces of music can be converted to MIDI files, so you can listen to
1446 what was entered. This is convenient for checking the music; octaves
1447 that are off or accidentals that were mistyped stand out very much
1448 when listening to the MIDI output.
1451 The midi output allocates a channel for each staff, and one for global
1452 settings. Therefore the midi file should not have more than 15 staves
1453 (or 14 if you do not use drums). Other staves will remain silent.
1456 * Creating MIDI files::
1458 * What goes into the MIDI output?::
1460 * Controlling MIDI dynamics::
1461 * Percussion in MIDI::
1464 @node Creating MIDI files
1465 @subsection Creating MIDI files
1467 To create a MIDI output file from a LilyPond input file, add a
1468 @code{\midi} block to a score, for example,
1477 If there is a @code{\midi} block in a @code{\score} with no
1478 @code{\layout} block, only MIDI output will be produced. When
1479 notation is needed too, a @code{\layout} block must be also be
1490 Pitches, rhythms, ties, dynamics, and tempo changes are interpreted
1491 and translated correctly to the MIDI output. Dynamic marks,
1492 crescendi and decrescendi translate into MIDI volume levels.
1493 Dynamic marks translate to a fixed fraction of the available MIDI
1494 volume range. Crescendi and decrescendi make the volume vary
1495 linearly between their two extremes. The effect of dynamic markings
1496 on the MIDI output can be removed completely, see @ref{MIDI block}.
1498 The initial tempo and later tempo changes can be specified
1499 with the @code{\tempo} command within the music notation. These
1500 are reflected in tempo changes in the MIDI output. This command
1501 will normally result in the metronome mark being printed, but this
1502 can be suppressed, see @ref{Metronome marks}. An alternative way
1503 of specifying the inital or overall MIDI tempo is described below,
1504 see @ref{MIDI block}.
1506 Due to some limitations on Windows, the default extension for
1507 MIDI files on Windows is @code{.mid}. Other operating systems still
1508 use the extension @code{.midi}. If a different extension is preferred,
1509 insert the following line at the top-level of the input file,
1510 before the start of any @code{\book}, @code{\bookpart} or @code{\score} blocks:
1513 #(ly:set-option 'midi-extension "midi")
1516 The line above will set the default extension for MIDI files to
1519 Alternatively, this option can also be supplied on the command line:
1522 lilypond … -dmidi-extension=midi lilyFile.ly
1526 @unnumberedsubsubsec Instrument names
1528 @cindex instrument names
1529 @funindex Staff.midiInstrument
1531 The MIDI instrument to be used is specified by setting the
1532 @code{Staff.midiInstrument} property to the instrument name.
1533 The name should be chosen from the list in @ref{MIDI instruments}.
1537 \set Staff.midiInstrument = #"glockenspiel"
1543 \new Staff \with @{midiInstrument = #"cello"@} @{
1548 If the selected instrument does not exactly match an instrument from
1549 the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
1555 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
1556 {changing-midi-output-to-one-channel-per-voice.ly}
1560 @c In 2.11 the following no longer seems to be a problem -td
1562 Unterminated (de)crescendos will not render properly in the midi file,
1563 resulting in silent passages of music. The workaround is to explicitly
1564 terminate the (de)crescendo. For example,
1571 will not work properly but
1581 Changes in the MIDI volume take place only on starting a note, so
1582 crescendi and decrescendi cannot affect the volume of a
1585 Not all midi players correctly handle tempo changes in the midi
1586 output. Players that are known to work include MS Windows Media
1587 Player and @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
1590 @subsection MIDI block
1593 A @code{\midi} block must appear within a score block if MIDI output
1594 is required. It is analogous to the layout block, but somewhat
1595 simpler. Often, the @code{\midi} block is left empty, but it
1596 can contain context rearrangements, new context definitions or code
1597 to set the values of properties. For example, the following will
1598 set the initial tempo exported to a MIDI file without causing a tempo
1599 indication to be printed:
1607 tempoWholesPerMinute = #(ly:make-moment 72 4)
1613 In this example the tempo is set to 72 quarter note
1614 beats per minute. This kind of tempo specification cannot take
1615 a dotted note length as an argument. If one is required, break
1616 the dotted note into smaller units. For example, a tempo of 90
1617 dotted quarter notes per minute can be specified as 270 eighth
1621 tempoWholesPerMinute = #(ly:make-moment 270 8)
1624 @cindex MIDI context definitions
1626 Context definitions follow precisely the same syntax as those
1627 within a @code{\layout} block. Translation modules for sound are
1628 called performers. The contexts for MIDI output are defined in
1629 @file{../@/ly/@/performer@/-init@/.ly},
1630 see @rlearning{Other sources of information}.
1631 For example, to remove the effect of dynamics
1632 from the MIDI output, insert the following lines in the
1633 @code{\midi@{ @}} block.
1640 \remove "Dynamic_performer"
1645 MIDI output is created only when a @code{\midi} block is included
1646 within a score block defined with a @code{\score} command. If it
1647 is placed within an explicitly instantiated score context (i.e.
1648 within a @code{\new Score} block) the file will fail. To solve
1649 this, enclose the @code{\new Score} and the @code{\midi} commands
1650 in a @code{\score} block.
1654 \new Score @{ @dots{}notes@dots{} @}
1659 @node What goes into the MIDI output?
1660 @subsection What goes into the MIDI output?
1662 @c TODO Check grace notes - timing is suspect?
1664 @unnumberedsubsubsec Supported in MIDI
1666 @cindex Pitches in MIDI
1667 @cindex MIDI, Pitches
1668 @cindex Quarter tones in MIDI
1669 @cindex MIDI, quarter tones
1670 @cindex Microtones in MIDI
1671 @cindex MIDI, microtones
1672 @cindex Chord names in MIDI
1673 @cindex MIDI, chord names
1674 @cindex Rhythms in MIDI
1675 @cindex MIDI, Rhythms
1678 The following items of notation are reflected in the MIDI output:
1682 @item Microtones (See @ref{Accidentals}. Rendering needs a
1683 player that supports pitch bend.)
1684 @item Chords entered as chord names
1685 @item Rhythms entered as note durations, including tuplets
1686 @item Tremolos entered without @q{@code{:}[@var{number}]}
1689 @item Crescendi, decrescendi over multiple notes
1690 @item Tempo changes entered with a tempo marking
1694 @unnumberedsubsubsec Unsupported in MIDI
1696 @c TODO index as above
1698 The following items of notation have no effect on the MIDI output:
1701 @item Rhythms entered as annotations, e.g. swing
1702 @item Tempo changes entered as annotations with no tempo marking
1703 @item Staccato and other articulations and ornamentations
1704 @item Slurs and Phrasing slurs
1705 @item Crescendi, decrescendi over a single note
1706 @item Tremolos entered with @q{@code{:}[@var{number}]}
1708 @item Microtonal chords
1712 @node Repeats in MIDI
1713 @subsection Repeats in MIDI
1715 @cindex repeats in MIDI
1716 @funindex \unfoldRepeats
1718 With a few minor additions, all types of repeats can be represented
1719 in the MIDI output. This is achieved by applying the
1720 @code{\unfoldRepeats} music function. This function changes all
1721 repeats to unfold repeats.
1723 @lilypond[quote,verbatim]
1725 \repeat tremolo 8 {c'32 e' }
1726 \repeat percent 2 { c''8 d'' }
1727 \repeat volta 2 {c'4 d' e' f'}
1736 When creating a score file using @code{\unfoldRepeats} for MIDI,
1737 it is necessary to make two @code{\score} blocks: one for MIDI
1738 (with unfolded repeats) and one for notation (with volta, tremolo,
1739 and percent repeats). For example,
1747 \unfoldRepeats @var{..music..}
1752 @node Controlling MIDI dynamics
1753 @subsection Controlling MIDI dynamics
1755 MIDI dynamics are implemented by the Dynamic_performer which lives
1756 by default in the Voice context. It is possible to control the
1757 overall MIDI volume, the relative volume of dynamic markings and
1758 the relative volume of different instruments.
1760 @unnumberedsubsubsec Dynamic marks
1762 Dynamic marks are translated to a fixed fraction of the available
1763 MIDI volume range. The default fractions range from 0.25 for
1764 @notation{ppppp} to 0.95 for @notation{fffff}. The set of dynamic
1765 marks and the associated fractions can be seen in
1766 @file{../@/scm/@/midi.scm}, see @rlearning{Other sources of information}.
1767 This set of fractions may be changed or extended by providing a
1768 function which takes a dynamic mark as its argument and returns the
1769 required fraction, and setting
1770 @code{Score.dynamicAbsoluteVolumeFunction} to this function.
1772 For example, if a @notation{rinforzando} dynamic marking,
1773 @code{\rfz}, is required, this will not by default
1774 have any effect on the MIDI volume, as this dynamic marking is not
1775 included in the default set. Similarly, if a new dynamic marking
1776 has been defined with @code{make-dynamic-script} that too will not
1777 be included in the default set. The following example shows how the
1778 MIDI volume for such dynamic markings might be added. The Scheme
1779 function sets the fraction to 0.9 if a dynamic mark of rfz is
1780 found, or calls the default function otherwise.
1782 @lilypond[verbatim,quote]
1783 #(define (myDynamics dynamic)
1784 (if (equal? dynamic "rfz")
1786 (default-dynamic-absolute-volume dynamic)))
1790 \set Staff.midiInstrument = #"cello"
1791 \set Score.dynamicAbsoluteVolumeFunction = #myDynamics
1803 Alternatively, if the whole table of fractions needs to be
1804 redefined, it would be better to use the
1805 @notation{default-dynamic-absolute-volume} procedure in
1806 @file{../@/scm/@/midi.scm} and the associated table as a model.
1807 The final example in this section shows how this might be done.
1809 @unnumberedsubsubsec Overall MIDI volume
1811 The minimum and maximum overall volume of MIDI dynamic markings is
1812 controlled by setting the properties @code{midiMinimumVolume} and
1813 @code{midiMaximumVolume} at the @code{Score} level. These
1814 properties have an effect only on dynamic marks, so if they
1815 are to apply from the start of the score a dynamic mark must be
1816 placed there. The fraction corresponding to each dynamic mark is
1817 modified with this formula
1820 midiMinimumVolume + (midiMaximumVolume - midiMinimumVolume) * fraction
1823 In the following example the dynamic range of the overall MIDI
1824 volume is limited to the range 0.2 - 0.5.
1826 @lilypond[verbatim,quote]
1832 \set Staff.midiInstrument = #"flute"
1833 \new Voice \relative c''' {
1841 \set Staff.midiInstrument = #"clarinet"
1842 \new Voice \relative c'' {
1853 tempoWholesPerMinute = #(ly:make-moment 72 2)
1854 midiMinimumVolume = #0.2
1855 midiMaximumVolume = #0.5
1861 @unnumberedsubsubsec Equalizing different instruments (i)
1863 If the minimum and maximum MIDI volume properties are set in
1864 the @code{Staff} context the relative volumes of the MIDI
1865 instruments can be controlled. This gives a basic instrument
1866 equalizer, which can enhance the quality of the MIDI output
1869 In this example the volume of the clarinet is reduced relative
1870 to the volume of the flute. There must be a dynamic
1871 mark on the first note of each instrument for this to work
1874 @lilypond[verbatim,quote]
1880 \set Staff.midiInstrument = #"flute"
1881 \set Staff.midiMinimumVolume = #0.7
1882 \set Staff.midiMaximumVolume = #0.9
1883 \new Voice \relative c''' {
1891 \set Staff.midiInstrument = #"clarinet"
1892 \set Staff.midiMinimumVolume = #0.3
1893 \set Staff.midiMaximumVolume = #0.6
1894 \new Voice \relative c'' {
1905 tempoWholesPerMinute = #(ly:make-moment 72 2)
1911 @unnumberedsubsubsec Equalizing different instruments (ii)
1913 If the MIDI minimum and maximum volume properties are not set
1914 LilyPond will, by default, apply a small degree of equalization
1915 to a few instruments. The instruments and the equalization
1916 applied are shown in the table @notation{instrument-equalizer-alist}
1917 in @file{../@/scm/@/midi.scm}.
1919 This basic default equalizer can be replaced by setting
1920 @code{instrumentEqualizer} in the @code{Score} context to a new
1921 Scheme procedure which accepts a MIDI instrument name as its only
1922 argument and returns a pair of fractions giving the minimum and
1923 maximum volumes to be applied to that instrument. This replacement
1924 is done in the same way as shown for resetting the
1925 @code{dynamicAbsoluteVolumeFunction} at the start of this section.
1926 The default equalizer, @notation{default-instrument-equalizer}, in
1927 @file{../@/scm/@/midi.scm} shows how such a procedure might be written.
1929 The following example sets the relative flute and clarinet volumes
1930 to the same values as the previous example.
1932 @lilypond[verbatim,quote]
1933 #(define my-instrument-equalizer-alist '())
1935 #(set! my-instrument-equalizer-alist
1938 ("flute" . (0.7 . 0.9))
1939 ("clarinet" . (0.3 . 0.6)))
1940 my-instrument-equalizer-alist))
1942 #(define (my-instrument-equalizer s)
1943 (let ((entry (assoc s my-instrument-equalizer-alist)))
1952 \set Score.instrumentEqualizer = #my-instrument-equalizer
1953 \set Staff.midiInstrument = #"flute"
1954 \new Voice \relative c''' {
1962 \set Staff.midiInstrument = #"clarinet"
1963 \new Voice \relative c'' {
1974 tempoWholesPerMinute = #(ly:make-moment 72 2)
1981 @c Delete when satisfied this is adequately covered elsewhere -td
1983 @n ode Microtones in MIDI
1984 @s ubsection Microtones in MIDI
1986 @cindex microtones in MIDI
1988 Microtones consisting of half sharps and half flats are exported
1989 to the MIDI file and render correctly in MIDI players which support
1990 pitch bending. See @ref{Note names in other languages}. Here is
1991 an example showing all the half sharps and half flats. It can be
1992 copied out and compiled to test microtones in your MIDI player.
1994 @lilypond[verbatim,quote]
2011 @node Percussion in MIDI
2012 @subsection Percussion in MIDI
2014 Percussion instruments are generally notated in a @code{DrumStaff}
2015 context and when notated in this way they are outputted correctly
2016 to MIDI channel@tie{}10, but some pitched percussion instruments,
2017 like the xylophone, marimba, vibraphone, timpani, etc., are
2018 treated like @qq{normal} instruments and music for these instruments
2019 should be entered in a normal @code{Staff} context, not a
2020 @code{DrumStaff} context, to obtain the correct MIDI output.
2022 Some non-pitched percussion sounds included in the general MIDI
2023 standard, like melodic tom, taiko drum, synth drum, etc., cannot
2024 be reached via MIDI channel@tie{}10, so the notation for such
2025 instruments should also be entered in a normal @code{Staff}
2026 context, using suitable normal pitches.
2028 Many percussion instruments are not included in the general MIDI
2029 standard, e.g. castanets. The easiest, although unsatisfactory,
2030 method of producing some MIDI output when writing for such
2031 instruments is to substitute the nearest sound from the standard
2034 @c TODO Expand with examples, and any other issues
2038 Because the general MIDI standard does not contain rim shots, the
2039 sidestick is used for this purpose instead.