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. For details, see the Contributors'
8 Guide, node Updating translation committishes..
13 @node General input and output
14 @chapter General input and output
16 This section deals with general LilyPond input and output issues,
17 rather than specific notation.
21 * Titles and headers::
22 * Working with input files::
23 * Controlling output::
29 @section Input structure
31 The main format of input for LilyPond are text files. By convention,
32 these files end with @code{.ly}.
35 * Structure of a score::
36 * Multiple scores in a book::
41 @node Structure of a score
42 @subsection Structure of a score
46 A @code{\score} block must contain a single music expression
47 delimited by curly brackets:
55 @warning{There must be @strong{only one} outer music expression in
56 a @code{\score} block, and it @strong{must} be surrounded by
59 This single music expression may be of any size, and may contain
60 other music expressions to any complexity. All of these examples
61 are music expressions:
67 @lilypond[verbatim,quote]
74 @lilypond[verbatim,quote]
76 \new Staff { c'4 c' c' c' }
77 \new Staff { d'4 d' d' d' }
85 \new Staff @{ \flute @}
86 \new Staff @{ \oboe @}
89 \new Staff @{ \violinI @}
90 \new Staff @{ \violinII @}
96 Comments are one exception to this general rule. (For others see
97 @ref{File structure}.) Both single-line comments and comments
98 delimited by @code{%@{ .. %@}} may be placed anywhere within an
99 input file. They may be placed inside or outside a @code{\score}
100 block, and inside or outside the single music expression within a
106 @rlearning{Working on input files},
107 @rlearning{Music expressions explained},
108 @rlearning{Score is a (single) compound musical expression}.
111 @node Multiple scores in a book
112 @subsection Multiple scores in a book
115 @cindex movements, multiple
117 A document may contain multiple pieces of music and text. Examples
118 of these are an etude book, or an orchestral part with multiple
119 movements. Each movement is entered with a @code{\score} block,
127 and texts are entered with a @code{\markup} block,
137 All the movements and texts which appear in the same @code{.ly} file
138 will normally be typeset in the form of a single output file.
152 However, if you want multiple output files from the same @code{.ly}
153 file, then you can add multiple @code{\book} blocks, where each such
154 @code{\book} block will result in a separate output. If you do not
155 specify any @code{\book} block in the file, LilyPond will implicitly
156 treat the full file as a single @code{\book} block, see @ref{File
157 structure}. One important exception is within lilypond-book documents,
158 where you explicitly have to add a @code{\book} block, otherwise only
159 the first @code{\score} or @code{\markup} will appear in the output.
161 The header for each piece of music can be put inside the @code{\score}
162 block. The @code{piece} name from the header will be printed before
163 each movement. The title for the entire book can be put inside the
164 @code{\book}, but if it is not present, the @code{\header} which is at
165 the top of the file is inserted.
169 title = "Eight miniatures"
170 composer = "Igor Stravinsky"
174 \header @{ piece = "Romanze" @}
177 ..text of second verse..
180 ..text of third verse..
184 \header @{ piece = "Menuetto" @}
190 Pieces of music may be grouped into book parts using @code{\bookpart}
191 blocks. Book parts are separated by a page break, and can start with a
192 title, like the book itself, by specifying a @code{\header} block.
198 subtitle = "First part"
205 subtitle = "Second part"
213 @subsection File structure
223 A @code{.ly} file may contain any number of toplevel expressions, where a
224 toplevel expression is one of the following:
228 An output definition, such as @code{\paper}, @code{\midi}, and
229 @code{\layout}. Such a definition at the toplevel changes the default
230 book-wide settings. If more than one such definition of
231 the same type is entered at the top level any definitions in the later
232 expressions have precedence.
235 A direct scheme expression, such as
236 @code{#(set-default-paper-size "a7" 'landscape)} or
237 @code{#(ly:set-option 'point-and-click #f)}.
240 A @code{\header} block. This sets the global header block. This
241 is the block containing the definitions for book-wide settings, like
242 composer, title, etc.
245 A @code{\score} block. This score will be collected with other
246 toplevel scores, and combined as a single @code{\book}.
247 This behavior can be changed by setting the variable
248 @code{toplevel-score-handler} at toplevel. The default handler is
249 defined in the init file @file{../@/scm/@/lily@/.scm}.
252 A @code{\book} block logically combines multiple movements
253 (i.e., multiple @code{\score} blocks) in one document. If there
254 are a number of @code{\score}s, one output file will be created
255 for each @code{\book} block, in which all corresponding movements
256 are concatenated. The only reason to explicitly specify
257 @code{\book} blocks in a @code{.ly} file is if you wish to create
258 multiple output files from a single input file. One exception is
259 within lilypond-book documents, where you explicitly have to add
260 a @code{\book} block if you want more than a single @code{\score}
261 or @code{\markup} in the same example. This behavior can be
262 changed by setting the variable @code{toplevel-book-handler} at
263 toplevel. The default handler is defined in the init file
264 @file{../@/scm/@/lily@/.scm}.
267 A @code{\bookpart} block. A book may be divided into several parts,
268 using @code{\bookpart} blocks, in order to ease the page breaking,
269 or to use different @code{\paper} settings in different parts.
272 A compound music expression, such as
277 This will add the piece in a @code{\score} and format it in a
278 single book together with all other toplevel @code{\score}s and music
279 expressions. In other words, a file containing only the above
280 music expression will be translated into
296 This behavior can be changed by setting the variable
297 @code{toplevel-music-handler} at toplevel. The default handler is
298 defined in the init file @file{../@/scm/@/lily@/.scm}.
301 A markup text, a verse for example
304 2. The first line verse two.
308 Markup texts are rendered above, between or below the scores or music
309 expressions, wherever they appear.
319 This can be used later on in the file by entering @code{\foo}. The
320 name of a variable should have alphabetic characters only; no
321 numbers, underscores or dashes.
325 The following example shows three things that may be entered at
330 % Don't justify the output
342 At any point in a file, any of the following lexical instructions can
346 @item @code{\version}
347 @item @code{\include}
348 @item @code{\sourcefilename}
349 @item @code{\sourcefileline}
351 A single-line comment, introduced by a leading @code{%} sign.
354 A multi-line comment delimited by @code{%@{ .. %@}}.
360 Whitespace between items in the input stream is generally ignored,
361 and may be freely omitted or extended to enhance readability.
362 However, whitespace should always be used in the following
363 circumstances to avoid errors:
366 @item Around every opening and closing curly bracket.
367 @item After every command or variable, i.e. every item that
368 begins with a @code{\} sign.
369 @item After every item that is to be interpreted as a Scheme
370 expression, i.e. every item that begins with a @code{#} sign.
371 @item To separate all elements of a Scheme expression.
372 @item In @code{lyricmode} to separate all the terms in both
373 @code{\override} and @code{\set} commands. In particular, spaces
374 must be used around the dot and the equals sign in commands like
375 @code{\override Score . LyricText #'font-size = #5} and before and
376 after the entire command.
383 @rlearning{How LilyPond input files work}.
386 @node Titles and headers
387 @section Titles and headers
389 Almost all printed music includes a title and the composer's name;
390 some pieces include a lot more information.
395 * Reference to page numbers::
396 * Table of contents::
400 @node Creating titles
401 @subsection Creating titles
403 Titles are created for each @code{\score} block, as well as for the full
404 input file (or @code{\book} block) and book parts (created by
405 @code{\bookpart} blocks).
407 The contents of the titles are taken from the @code{\header} blocks.
408 The header block for a book supports the following
414 The dedicatee of the music, centered at the top of the first page.
418 The title of the music, centered just below the dedication.
422 Subtitle, centered below the title.
424 @funindex subsubtitle
426 Subsubtitle, centered below the subtitle.
430 Name of the poet, flush-left below the subsubtitle.
434 Name of the instrument, centered below the subsubtitle. Also
435 centered at the top of pages (other than the first page).
439 Name of the composer, flush-right below the subsubtitle.
443 Meter string, flush-left below the poet.
447 Name of the arranger, flush-right below the composer.
451 Name of the piece, flush-left below the meter.
455 Name of the opus, flush-right below the arranger.
457 @cindex page breaks, forcing
458 @funindex breakbefore
460 This forces the title to start on a new page (set to ##t or ##f).
464 Copyright notice, centered at the bottom of the first page. To
465 insert the copyright symbol, see @ref{Text encoding}.
469 Centered at the bottom of the last page.
473 Here is a demonstration of the fields available. Note that you
474 may use any @ref{Formatting text}, commands in the header.
476 @lilypond[quote,verbatim,line-width=11.0\cm]
479 paper-height = 10.0\cm
484 dedication = "dedicated to me"
485 title = \markup \center-column { "Title first line" "Title second line,
487 subtitle = "the subtitle,"
488 subsubtitle = #(string-append "subsubtitle LilyPond version "
491 composer = \markup \center-column { "composer" \small "(1847-1973)" }
492 texttranslator = "Text Translator"
493 meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
495 arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize
496 #-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }
497 instrument = \markup \bold \italic "instrument"
521 As demonstrated before, you can use multiple @code{\header} blocks.
522 When same fields appear in different blocks, the latter is used.
523 Here is a short example.
527 composer = "Composer"
535 piece = "New piece" % overwrite previous one
540 If you define the @code{\header} inside the @code{\score} block, then
541 normally only the @code{piece} and @code{opus} headers will be printed.
542 Note that the music expression must come before the @code{\header}.
544 @lilypond[quote,verbatim,line-width=11.0\cm]
548 title = "title" % not printed
555 @funindex print-all-headers
557 You may change this behavior (and print all the headers when defining
558 @code{\header} inside @code{\score}) by using
562 print-all-headers = ##t
569 The default footer is empty, except for the first page, where the
570 @code{copyright} field from @code{\header} is inserted, and the last
571 page, where @code{tagline} from @code{\header} is added. The default
572 tagline is @qq{Music engraving by LilyPond (@var{version})}.@footnote{Nicely
573 printed parts are good PR for us, so please leave the tagline if you
576 Headers may be completely removed by setting them to false.
587 @subsection Custom titles
589 A more advanced option is to change the definitions of the following
590 variables in the @code{\paper} block. The init file
591 @file{../@/ly/@/titling@/-init@/.ly} lists the default layout.
594 @funindex bookTitleMarkup
595 @item bookTitleMarkup
596 This is the title added at the top of the entire output document.
597 Typically, it has the composer and the title of the piece
599 @funindex scoreTitleMarkup
600 @item scoreTitleMarkup
601 This is the title put over a @code{\score} block. Typically, it has
602 the name of the movement (@code{piece} field).
604 @funindex oddHeaderMarkup
605 @item oddHeaderMarkup
606 This is the page header for odd-numbered pages.
608 @funindex evenHeaderMarkup
609 @item evenHeaderMarkup
610 This is the page header for even-numbered pages. If unspecified,
611 the odd header is used instead.
613 By default, headers are defined such that the page number is on the
614 outside edge, and the instrument is centered.
616 @funindex oddFooterMarkup
617 @item oddFooterMarkup
618 This is the page footer for odd-numbered pages.
620 @funindex evenFooterMarkup
621 @item evenFooterMarkup
622 This is the page footer for even-numbered pages. If unspecified,
623 the odd header is used instead.
625 By default, the footer has the copyright notice on the first, and
626 the tagline on the last page.
636 The following definition will put the title flush left, and the
637 composer flush right on a single line.
641 bookTitleMarkup = \markup {
643 \fromproperty #'header:title
644 \fromproperty #'header:composer
650 @node Reference to page numbers
651 @subsection Reference to page numbers
653 A particular place of a score can be marked using the @code{\label}
654 command, either at top-level or inside music. This label can then be
655 referred to in a markup, to get the number of the page where the marked
656 point is placed, using the @code{\page-ref} markup command.
658 @lilypond[verbatim,line-width=11.0\cm]
659 \header { tagline = ##f }
665 \pageBreak \mark A \label #'markA
670 \markup { The first score begins on page \page-ref #'firstScore "0" "?" }
671 \markup { Mark A is on page \page-ref #'markA "0" "?" }
675 The @code{\page-ref} markup command takes three arguments:
677 @item the label, a scheme symbol, eg. @code{#'firstScore};
678 @item a markup that will be used as a gauge to estimate the dimensions
680 @item a markup that will be used in place of the page number if the label
684 The reason why a gauge is needed is that, at the time markups are
685 interpreted, the page breaking has not yet occurred, so the page numbers
686 are not yet known. To work around this issue, the actual markup
687 interpretation is delayed to a later time; however, the dimensions of
688 the markup have to be known before, so a gauge is used to decide these
689 dimensions. If the book has between 10 and 99 pages, it may be "00",
690 ie. a two digit number.
701 @node Table of contents
702 @subsection Table of contents
703 A table of contents is included using the @code{\markuplines \table-of-contents}
704 command. The elements which should appear in the table of contents are
705 entered with the @code{\tocItem} command, which may be used either at
706 top-level, or inside a music expression.
709 \markuplines \table-of-contents
712 \tocItem \markup "First score"
716 \tocItem \markup "Some particular point in the first score"
721 \tocItem \markup "Second score"
729 The markups which are used to format the table of contents are defined
730 in the @code{\paper} block. The default ones are @code{tocTitleMarkup},
731 for formatting the title of the table, and @code{tocItemMarkup}, for
732 formatting the toc elements, composed of the element title and page
733 number. These variables may be changed by the user:
737 %% Translate the toc title into French:
738 tocTitleMarkup = \markup \huge \column {
739 \fill-line { \null "Table des matières" \null }
742 %% use larger font size
743 tocItemMarkup = \markup \large \fill-line {
744 \fromproperty #'toc:text \fromproperty #'toc:page
749 Note how the toc element text and page number are referred to in
750 the @code{tocItemMarkup} definition.
752 New commands and markups may also be defined to build more elaborated
755 @item first, define a new markup variable in the @code{\paper} block
756 @item then, define a music function which aims at adding a toc element
757 using this markup paper variable.
760 In the following example, a new style is defined for entering act names
761 in the table of contents of an opera:
765 tocActMarkup = \markup \large \column {
767 \fill-line { \null \italic \fromproperty #'toc:text \null }
773 #(define-music-function (parser location text) (markup?)
774 (add-toc-item! 'tocActMarkup text))
777 @lilypond[line-width=11.0\cm]
778 \header { tagline = ##f }
780 tocActMarkup = \markup \large \column {
782 \fill-line { \null \italic \fromproperty #'toc:text \null }
788 #(define-music-function (parser location text) (markup?)
789 (add-toc-item! 'tocActMarkup text))
792 \markuplines \table-of-contents
793 \tocAct \markup { Atto Primo }
794 \tocItem \markup { Coro. Viva il nostro Alcide }
795 \tocItem \markup { Cesare. Presti omai l'Egizzia terra }
796 \tocAct \markup { Atto Secondo }
797 \tocItem \markup { Sinfonia }
798 \tocItem \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
805 Init files: @file{../@/ly/@/toc@/-init@/.ly}.
809 @funindex \table-of-contents
810 @code{\table-of-contents},
816 @node Working with input files
817 @section Working with input files
820 * Including LilyPond files::
821 * Different editions from one source::
823 * Displaying LilyPond notation::
827 @node Including LilyPond files
828 @subsection Including LilyPond files
831 @cindex including files
833 A large project may be split up into separate files. To refer to
837 \include "otherfile.ly"
840 The line @code{\include "otherfile.ly"} is equivalent to pasting the
841 contents of @file{otherfile.ly} into the current file at the place
842 where the @code{\include} appears. For example, in a large
843 project you might write separate files for each instrument part
844 and create a @qq{full score} file which brings together the
845 individual instrument files. Normally the included file will
846 define a number of variables which then become available
847 for use in the full score file. Tagged sections can be
848 marked in included files to assist in making them usable in
849 different places in a score, see @ref{Different editions from
852 Files in the current working directory may be referenced by
853 specifying just the file name after the @code{\include} command.
854 Files in other locations may be included by giving either a full
855 path reference or a relative path reference (but use the UNIX
856 forward slash, /, rather than the DOS/Windows back slash, \, as the
857 directory separator.) For example, if @file{stuff.ly} is located
858 one directory higher than the current working directory, use
861 \include "../stuff.ly"
865 or if the included orchestral parts files are all located in a
866 subdirectory called @file{parts} within the current directory, use
869 \include "parts/VI.ly"
870 \include "parts/VII.ly"
874 Files which are to be included can also contain @code{\include}
875 statements of their own. By default, these second-level
876 @code{\include} statements are not interpreted until they have
877 been brought into the main file, so the file names they specify
878 must all be relative to the directory containing the main file,
879 not the directory containing the included file. However,
880 this behavior can be changed by passing the option
881 @code{-drelative-includes} option at the command line
882 (or by adding @code{#(ly:set-option 'relative-includes #t)}
883 at the top of the main input file). With @code{relative-includes}
884 set, the path for each @code{\include} command will be taken
885 relative to the file containing that command. This behavior is
886 recommended and it will become the default behavior in a future
889 Files can also be included from a directory in a search path
890 specified as an option when invoking LilyPond from the command
891 line. The included files are then specified using just their
892 file name. For example, to compile @file{main.ly} which includes
893 files located in a subdirectory called @file{parts} by this method,
894 cd to the directory containing @file{main.ly} and enter
897 lilypond --include=parts main.ly
908 Files which are to be included in many scores may be placed in
909 the LilyPond directory @file{../ly}. (The location of this
910 directory is installation-dependent - see
911 @rlearning{Other sources of information}). These files can then
912 be included simply by naming them on an @code{\include} statement.
913 This is how the language-dependent files like @file{english.ly} are
916 LilyPond includes a number of files by default when you start
917 the program. These includes are not apparent to the user, but the
918 files may be identified by running @code{lilypond --verbose} from
919 the command line. This will display a list of paths and files that
920 LilyPond uses, along with much other information. Alternatively,
921 the more important of these files are discussed in
922 @rlearning{Other sources of information}. These files may be
923 edited, but changes to them will be lost on installing a new
926 Some simple examples of using @code{\include} are shown in
927 @rlearning{Scores and parts}.
932 @rlearning{Other sources of information},
933 @rlearning{Scores and parts}.
938 If an included file is given a name which is the same as one in
939 LilyPond's installation files, LilyPond's file from the
940 installation files takes precedence.
944 @node Different editions from one source
945 @subsection Different editions from one source
947 Several mechanisms are available to facilitate the generation
948 of different versions of a score from the same music source.
949 Variables are perhaps most useful for combining lengthy sections
950 of music and/or annotation in various ways, while tags are more
951 useful for selecting one from several alternative shorter sections
952 of music. Whichever method is used, separating the notation from
953 the structure of the score will make it easier to change the
954 structure while leaving the notation untouched.
961 @node Using variables
962 @unnumberedsubsubsec Using variables
964 @cindex variables, use of
966 If sections of the music are defined in variables they can be
967 reused in different parts of the score, see @rlearning{Organizing
968 pieces with variables}. For example, an @notation{a cappella}
969 vocal score frequently includes a piano reduction of the parts
970 for rehearsal purposes which is identical to the vocal music, so
971 the music need be entered only once. Music from two variables
972 may be combined on one staff, see @ref{Automatic part combining}.
975 @lilypond[verbatim,quote]
976 sopranoMusic = \relative c'' { a4 b c b8( a) }
977 altoMusic = \relative g' { e4 e e f }
978 tenorMusic = \relative c' { c4 b e d8( c) }
979 bassMusic = \relative c' { a4 gis a d, }
980 allLyrics = \lyricmode {King of glo -- ry }
982 \new Staff = "Soprano" \sopranoMusic
983 \new Lyrics \allLyrics
984 \new Staff = "Alto" \altoMusic
985 \new Lyrics \allLyrics
986 \new Staff = "Tenor" {
990 \new Lyrics \allLyrics
991 \new Staff = "Bass" {
995 \new Lyrics \allLyrics
998 \set Staff.printPartCombineTexts = ##f
1004 \set Staff.printPartCombineTexts = ##f
1014 Separate scores showing just the vocal parts or just the piano
1015 part can be produced by changing just the structural statements,
1016 leaving the musical notation unchanged.
1018 For lengthy scores, the variable definitions may be placed in
1019 separate files which are then included, see @ref{Including
1023 @unnumberedsubsubsec Using tags
1026 @funindex \keepWithTag
1027 @funindex \removeWithTag
1029 @cindex keep tagged music
1030 @cindex remove tagged music
1032 The @code{\tag #'@var{partA}} command marks a music expression
1033 with the name @var{partA}.
1034 Expressions tagged in this way can be selected or filtered out by
1035 name later, using either @code{\keepWithTag #'@var{name}} or
1036 @code{\removeWithTag #'@var{name}}. The result of applying these filters
1037 to tagged music is as follows:
1038 @multitable @columnfractions .5 .5
1042 Tagged music preceded by @code{\keepWithTag #'@var{name}}
1043 @tab Untagged music and music tagged with @var{name} is included;
1044 music tagged with any other tag name is excluded.
1046 Tagged music preceded by @code{\removeWithTag #'@var{name}}
1047 @tab Untagged music and music tagged with any tag name other than
1048 @var{name} is included; music tagged with @var{name} is
1051 Tagged music not preceded by either @code{\keepWithTag} or
1052 @code{\removeWithTag}
1053 @tab All tagged and untagged music is included.
1056 The arguments of the @code{\tag}, @code{\keepWithTag} and
1057 @code{\removeWithTag} commands should be a symbol
1058 (such as @code{#'score} or @code{#'part}), followed
1059 by a music expression.
1061 In the following example, we see two versions of a piece of music,
1062 one showing trills with the usual notation, and one with trills
1063 explicitly expanded:
1065 @lilypond[verbatim,quote]
1066 music = \relative g' {
1068 \tag #'trills { d8.\trill }
1069 \tag #'expand { \repeat unfold 3 { e32 d } }
1074 \keepWithTag #'trills \music
1077 \keepWithTag #'expand \music
1082 Alternatively, it is sometimes easier to exclude sections of music:
1084 @lilypond[verbatim,quote]
1085 music = \relative g' {
1087 \tag #'trills { d8.\trill }
1088 \tag #'expand {\repeat unfold 3 { e32 d } }
1093 \removeWithTag #'expand
1097 \removeWithTag #'trills
1102 Tagged filtering can be applied to articulations, texts, etc. by
1106 -\tag #'@var{your-tag}
1109 to an articulation. For example, this would define a note with a
1110 conditional fingering indication and a note with a conditional
1115 c1-\tag #'warn ^"Watch!"
1118 Multiple tags may be placed on expressions with multiple
1119 @code{\tag} entries:
1121 @lilypond[quote,verbatim]
1122 music = \relative c'' {
1123 \tag #'a \tag #'both { a4 a a a }
1124 \tag #'b \tag #'both { b4 b b b }
1127 \keepWithTag #'a \music
1128 \keepWithTag #'b \music
1129 \keepWithTag #'both \music
1133 Multiple @code{\removeWithTag} filters may be applied to a single
1134 music expression to remove several differently named tagged sections:
1136 @lilypond[verbatim,quote]
1137 music = \relative c'' {
1138 \tag #'A { a4 a a a }
1139 \tag #'B { b4 b b b }
1140 \tag #'C { c4 c c c }
1141 \tag #'D { d4 d d d }
1150 Two or more @code{\keepWithTag} filters applied to a single music
1151 expression will cause @emph{all} tagged sections to be removed, as
1152 the first filter will remove all tagged sections except the one
1153 named, and the second filter will remove even that tagged section.
1158 @rlearning{Organizing pieces with variables}.
1161 @ref{Automatic part combining},
1162 @ref{Including LilyPond files}.
1166 @c This warning is more general than this placement implies.
1167 @c Rests are not merged whether or not they come from tagged sections.
1168 @c Should be deleted? -td
1172 Multiple rests are not merged if you create a score with more
1173 than one tagged section at the same place.
1178 @subsection Text encoding
1182 @cindex non-ASCII characters
1184 LilyPond uses the character repertoire defined by the Unicode
1185 consortium and ISO/IEC 10646. This defines a unique name and
1186 code point for the character sets used in virtually all modern
1187 languages and many others too. Unicode can be implemented using
1188 several different encodings. LilyPond uses the UTF-8 encoding
1189 (UTF stands for Unicode Transformation Format) which represents
1190 all common Latin characters in one byte, and represents other
1191 characters using a variable length format of up to four bytes.
1193 The actual appearance of the characters is determined by the
1194 glyphs defined in the particular fonts available - a font defines
1195 the mapping of a subset of the Unicode code points to glyphs.
1196 LilyPond uses the Pango library to layout and render multi-lingual
1199 LilyPond does not perform any input-encoding conversions. This
1200 means that any text, be it title, lyric text, or musical
1201 instruction containing non-ASCII characters, must be encoded in
1202 UTF-8. The easiest way to enter such text is by using a
1203 Unicode-aware editor and saving the file with UTF-8 encoding. Most
1204 popular modern editors have UTF-8 support, for example, vim, Emacs,
1205 jEdit, and GEdit do. All MS Windows systems later than NT use
1206 Unicode as their native character encoding, so even Notepad can
1207 edit and save a file in UTF-8 format. A more functional
1208 alternative for Windows is BabelPad.
1210 If a LilyPond input file containing a non-ASCII character is not
1211 saved in UTF-8 format the error message
1214 FT_Get_Glyph_Name () error: invalid argument
1219 Here is an example showing Cyrillic, Hebrew and Portuguese
1223 %c No verbatim here as the code does not display correctly in PDF
1225 bulgarian = \lyricmode {
1226 Жълтата дюля беше щастлива, че пухът, който цъфна, замръзна като гьон.
1230 hebrew = \lyricmode {
1231 זה כיף סתם לשמוע איך תנצח קרפד עץ טוב בגן.
1235 portuguese = \lyricmode {
1236 à vo -- cê uma can -- ção legal
1242 \addlyrics { \bulgarian }
1243 \addlyrics { \hebrew }
1244 \addlyrics { \portuguese }
1247 To enter a single character for which the Unicode code point is
1248 known but which is not available in the editor being used, use
1249 either @code{\char ##xhhhh} or @code{\char #dddd} within a
1250 @code{\markup} block, where @code{hhhh} is the hexadecimal code for
1251 the character required and @code{dddd} is the corresponding decimal
1252 value. Leading zeroes may be omitted, but it is usual to specify
1253 all four characters in the hexadecimal representation. (Note that
1254 the UTF-8 encoding of the code point should @emph{not} be used
1255 after @code{\char}, as UTF-8 encodings contain extra bits indicating
1256 the number of octets.) Unicode code charts and a character name
1257 index giving the code point in hexadecimal for any character can be
1258 found on the Unicode Consortium website,
1259 @uref{http://www.unicode.org/}.
1261 For example, @code{\char ##x03BE} and @code{\char #958} would both
1262 enter the Unicode U+03BE character, which has the Unicode name
1263 @qq{Greek Small Letter Xi}.
1265 Any Unicode code point may be entered in this way and if all special
1266 characters are entered in this format it is not necessary to save
1267 the input file in UTF-8 format. Of course, a font containing all
1268 such encoded characters must be installed and available to LilyPond.
1270 The following example shows Unicode hexadecimal values being entered
1271 in four places -- in a rehearsal mark, as articulation text, in
1272 lyrics and as stand-alone text below the score:
1274 @lilypond[quote,verbatim]
1277 c1 \mark \markup { \char ##x03EE }
1278 c1_\markup { \tiny { \char ##x03B1 " to " \char ##x03C9 } }
1280 \addlyrics { O \markup { \concat { Ph \char ##x0153 be! } } }
1282 \markup { "Copyright 2008--2010" \char ##x00A9 }
1285 @cindex copyright sign
1287 To enter the copyright sign in the copyright notice use:
1291 copyright = \markup @{ \char ##x00A9 "2008" @}
1295 @node Displaying LilyPond notation
1296 @subsection Displaying LilyPond notation
1298 @funindex \displayLilyMusic
1299 Displaying a music expression in LilyPond notation can be
1300 done with the music function @code{\displayLilyMusic} but only when
1301 using the command line. For example,
1305 \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
1312 @{ a,4 cis e fis g @}
1315 By default, LilyPond will print these messages to the console
1316 along with all the other LilyPond compilation messages. To split
1317 up these messages and save the results of @code{\display@{STUFF@}},
1318 redirect the output to a file.
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::
1333 * Replacing the notation font::
1336 @node Extracting fragments of music
1337 @subsection Extracting fragments of music
1339 It is possible to quote small fragments of a large score directly from
1340 the output. This can be compared to clipping a piece of a paper score
1343 This is done by defining the measures that need to be cut out
1344 separately. For example, including the following definition
1352 (make-rhythmic-location 5 1 2)
1353 (make-rhythmic-location 7 3 4)))
1358 will extract a fragment starting halfway the fifth measure, ending in
1359 the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note
1360 in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7.
1362 More clip regions can be defined by adding more pairs of
1363 rhythmic-locations to the list.
1365 In order to use this feature, LilyPond must be invoked with
1366 @code{-dclip-systems}. The clips are output as EPS files, and are
1367 converted to PDF and PNG if these formats are switched on as well.
1369 For more information on output formats, see @rprogram{Invoking lilypond}.
1371 @node Skipping corrected music
1372 @subsection Skipping corrected music
1375 @funindex skipTypesetting
1376 @funindex showFirstLength
1377 @funindex showLastLength
1379 When entering or copying music, usually only the music near the end (where
1381 are adding notes) is interesting to view and correct. To speed up
1382 this correction process, it is possible to skip typesetting of all but
1383 the last few measures. This is achieved by putting
1386 showLastLength = R1*5
1391 in your source file. This will render only the last 5 measures
1392 (assuming 4/4 time signature) of every @code{\score} in the input
1393 file. For longer pieces, rendering only a small part is often an order
1394 of magnitude quicker than rendering it completely. When working on the
1395 beginning of a score you have already typeset (e.g. to add a new part),
1396 the @code{showFirstLength} property may be useful as well.
1398 Skipping parts of a score can be controlled in a more fine-grained
1399 fashion with the property @code{Score.skipTypesetting}. When it is
1400 set, no typesetting is performed at all.
1402 This property is also used to control output to the MIDI file. Note that
1403 it skips all events, including tempo and instrument changes. You have
1406 @lilypond[quote,fragment,ragged-right,verbatim]
1409 \set Score.skipTypesetting = ##t
1411 \set Score.skipTypesetting = ##f
1416 In polyphonic music, @code{Score.skipTypesetting} will affect all
1417 voices and staves, saving even more time.
1419 @node Alternative output formats
1420 @subsection Alternative output formats
1422 @cindex scalable vector graphics output
1424 @cindex encapsulated postscript output
1427 The default output formats for the printed score are Portable
1428 Document Format (PDF) and PostScript (PS). Scalable Vector
1429 Graphics (SVG), Encapsulated PostScript (EPS) and Portable
1430 Network Graphics (PNG) output formats are also available through
1431 command line options, see @rprogram{Command line options for
1435 @node Replacing the notation font
1436 @subsection Replacing the notation font
1438 Gonville is an alternative to the Feta font used in LilyPond and can
1441 @uref{http://www.chiark.greenend.org.uk/~sgtatham/gonville/ ,http://www.chiark.greenend.org.uk/~sgtatham/gonville/}
1444 Here are a few sample bars of music set in Gonville:
1446 @c NOTE: these images are a bit big, but that's important
1447 @c for the font comparison. -gp
1448 @sourceimage{Gonville_after,,,}
1450 Here are a few sample bars of music set in LilyPond's Feta font:
1452 @sourceimage{Gonville_before,,,}
1454 @subsubheading Installation Instructions for MacOS
1456 Download and extract the zip file. Copy the @code{lilyfonts}
1457 directory to @file{@var{SHARE_DIR}/lilypond/current}; for more
1458 information, see @rlearning{Other sources of information}.
1459 Move the existing @code{fonts} directory to @code{fonts_orig} and
1460 move the @code{lilyfonts} directory to @code{fonts}. Simply move
1461 @code{fonts_orig} back to @code{fonts} to revert back to Feta.
1464 Learning Manual: @rlearning{Other sources of information}.
1468 Gonville cannot be used to typeset @q{Ancient Music} notation. Please
1469 refer to the author's website for more information on this and other
1470 specifics including licensing of Gonville.
1474 @section MIDI output
1479 MIDI (Musical Instrument Digital Interface) is a standard for
1480 connecting and controlling digital instruments. A MIDI file is a
1481 series of notes in a number of tracks. It is not an actual
1482 sound file; you need special software to translate between the
1483 series of notes and actual sounds.
1485 Pieces of music can be converted to MIDI files, so you can listen to
1486 what was entered. This is convenient for checking the music; octaves
1487 that are off or accidentals that were mistyped stand out very much
1488 when listening to the MIDI output.
1491 The midi output allocates a channel for each staff, and one for global
1492 settings. Therefore the midi file should not have more than 15 staves
1493 (or 14 if you do not use drums). Other staves will remain silent.
1496 * Creating MIDI files::
1498 * What goes into the MIDI output?::
1500 * Controlling MIDI dynamics::
1501 * Percussion in MIDI::
1504 @node Creating MIDI files
1505 @subsection Creating MIDI files
1507 To create a MIDI output file from a LilyPond input file, add a
1508 @code{\midi} block to a score, for example,
1517 If there is a @code{\midi} block in a @code{\score} with no
1518 @code{\layout} block, only MIDI output will be produced. When
1519 notation is needed too, a @code{\layout} block must also be
1530 Pitches, rhythms, ties, dynamics, and tempo changes are interpreted
1531 and translated correctly to the MIDI output. Dynamic marks,
1532 crescendi and decrescendi translate into MIDI volume levels.
1533 Dynamic marks translate to a fixed fraction of the available MIDI
1534 volume range. Crescendi and decrescendi make the volume vary
1535 linearly between their two extremes. The effect of dynamic markings
1536 on the MIDI output can be removed completely, see @ref{MIDI block}.
1538 The initial tempo and later tempo changes can be specified
1539 with the @code{\tempo} command within the music notation. These
1540 are reflected in tempo changes in the MIDI output. This command
1541 will normally result in the metronome mark being printed, but this
1542 can be suppressed, see @ref{Metronome marks}. An alternative way
1543 of specifying the inital or overall MIDI tempo is described below,
1544 see @ref{MIDI block}.
1546 Due to some limitations on Windows, the default extension for
1547 MIDI files on Windows is @code{.mid}. Other operating systems still
1548 use the extension @code{.midi}. If a different extension is preferred,
1549 insert the following line at the top-level of the input file,
1550 before the start of any @code{\book}, @code{\bookpart} or @code{\score} blocks:
1553 #(ly:set-option 'midi-extension "midi")
1556 The line above will set the default extension for MIDI files to
1559 Alternatively, this option can also be supplied on the command line:
1562 lilypond … -dmidi-extension=midi lilyFile.ly
1566 @unnumberedsubsubsec Instrument names
1568 @cindex instrument names
1569 @funindex Staff.midiInstrument
1571 The MIDI instrument to be used is specified by setting the
1572 @code{Staff.midiInstrument} property to the instrument name.
1573 The name should be chosen from the list in @ref{MIDI instruments}.
1577 \set Staff.midiInstrument = #"glockenspiel"
1583 \new Staff \with @{midiInstrument = #"cello"@} @{
1588 If the selected instrument does not exactly match an instrument from
1589 the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
1595 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
1596 {changing-midi-output-to-one-channel-per-voice.ly}
1600 @c In 2.11 the following no longer seems to be a problem -td
1602 Unterminated (de)crescendos will not render properly in the midi file,
1603 resulting in silent passages of music. The workaround is to explicitly
1604 terminate the (de)crescendo. For example,
1611 will not work properly but
1614 @{ a4\< b c d\!\f @}
1621 Changes in the MIDI volume take place only on starting a note, so
1622 crescendi and decrescendi cannot affect the volume of a
1625 Not all midi players correctly handle tempo changes in the midi
1626 output. Players that are known to work include MS Windows Media
1627 Player and @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
1630 @subsection MIDI block
1633 A @code{\midi} block must appear within a score block if MIDI output
1634 is required. It is analogous to the layout block, but somewhat
1635 simpler. Often, the @code{\midi} block is left empty, but it
1636 can contain context rearrangements, new context definitions or code
1637 to set the values of properties. For example, the following will
1638 set the initial tempo exported to a MIDI file without causing a tempo
1639 indication to be printed:
1647 tempoWholesPerMinute = #(ly:make-moment 72 4)
1653 In this example the tempo is set to 72 quarter note
1654 beats per minute. This kind of tempo specification cannot take
1655 a dotted note length as an argument. If one is required, break
1656 the dotted note into smaller units. For example, a tempo of 90
1657 dotted quarter notes per minute can be specified as 270 eighth
1661 tempoWholesPerMinute = #(ly:make-moment 270 8)
1664 @cindex MIDI context definitions
1666 Context definitions follow precisely the same syntax as those
1667 within a @code{\layout} block. Translation modules for sound are
1668 called performers. The contexts for MIDI output are defined in
1669 @file{../@/ly/@/performer@/-init@/.ly},
1670 see @rlearning{Other sources of information}.
1671 For example, to remove the effect of dynamics
1672 from the MIDI output, insert the following lines in the
1673 @code{\midi@{ @}} block.
1680 \remove "Dynamic_performer"
1685 MIDI output is created only when a @code{\midi} block is included
1686 within a score block defined with a @code{\score} command. If it
1687 is placed within an explicitly instantiated score context (i.e.
1688 within a @code{\new Score} block) the file will fail. To solve
1689 this, enclose the @code{\new Score} and the @code{\midi} commands
1690 in a @code{\score} block.
1694 \new Score @{ @dots{}notes@dots{} @}
1699 @node What goes into the MIDI output?
1700 @subsection What goes into the MIDI output?
1702 @c TODO Check grace notes - timing is suspect?
1704 @unnumberedsubsubsec Supported in MIDI
1706 @cindex Pitches in MIDI
1707 @cindex MIDI, Pitches
1708 @cindex Quarter tones in MIDI
1709 @cindex MIDI, quarter tones
1710 @cindex Microtones in MIDI
1711 @cindex MIDI, microtones
1712 @cindex Chord names in MIDI
1713 @cindex MIDI, chord names
1714 @cindex Rhythms in MIDI
1715 @cindex MIDI, Rhythms
1718 The following items of notation are reflected in the MIDI output:
1722 @item Microtones (See @ref{Accidentals}. Rendering needs a
1723 player that supports pitch bend.)
1724 @item Chords entered as chord names
1725 @item Rhythms entered as note durations, including tuplets
1726 @item Tremolos entered without @q{@code{:}[@var{number}]}
1729 @item Crescendi, decrescendi over multiple notes
1730 @item Tempo changes entered with a tempo marking
1734 @unnumberedsubsubsec Unsupported in MIDI
1736 @c TODO index as above
1738 The following items of notation have no effect on the MIDI output:
1741 @item Rhythms entered as annotations, e.g. swing
1742 @item Tempo changes entered as annotations with no tempo marking
1743 @item Staccato and other articulations and ornamentations
1744 @item Slurs and Phrasing slurs
1745 @item Crescendi, decrescendi over a single note
1746 @item Tremolos entered with @q{@code{:}[@var{number}]}
1748 @item Microtonal chords
1752 @node Repeats in MIDI
1753 @subsection Repeats in MIDI
1755 @cindex repeats in MIDI
1756 @funindex \unfoldRepeats
1758 With a few minor additions, all types of repeats can be represented
1759 in the MIDI output. This is achieved by applying the
1760 @code{\unfoldRepeats} music function. This function changes all
1761 repeats to unfold repeats.
1763 @lilypond[quote,verbatim]
1765 \repeat tremolo 8 { c'32 e' }
1766 \repeat percent 2 { c''8 d'' }
1767 \repeat volta 2 { c'4 d' e' f' }
1776 When creating a score file using @code{\unfoldRepeats} for MIDI,
1777 it is necessary to make two @code{\score} blocks: one for MIDI
1778 (with unfolded repeats) and one for notation (with volta, tremolo,
1779 and percent repeats). For example,
1787 \unfoldRepeats @var{..music..}
1792 @node Controlling MIDI dynamics
1793 @subsection Controlling MIDI dynamics
1795 MIDI dynamics are implemented by the Dynamic_performer which lives
1796 by default in the Voice context. It is possible to control the
1797 overall MIDI volume, the relative volume of dynamic markings and
1798 the relative volume of different instruments.
1800 @unnumberedsubsubsec Dynamic marks
1802 Dynamic marks are translated to a fixed fraction of the available
1803 MIDI volume range. The default fractions range from 0.25 for
1804 @notation{ppppp} to 0.95 for @notation{fffff}. The set of dynamic
1805 marks and the associated fractions can be seen in
1806 @file{../@/scm/@/midi.scm}, see @rlearning{Other sources of information}.
1807 This set of fractions may be changed or extended by providing a
1808 function which takes a dynamic mark as its argument and returns the
1809 required fraction, and setting
1810 @code{Score.dynamicAbsoluteVolumeFunction} to this function.
1812 For example, if a @notation{rinforzando} dynamic marking,
1813 @code{\rfz}, is required, this will not by default
1814 have any effect on the MIDI volume, as this dynamic marking is not
1815 included in the default set. Similarly, if a new dynamic marking
1816 has been defined with @code{make-dynamic-script} that too will not
1817 be included in the default set. The following example shows how the
1818 MIDI volume for such dynamic markings might be added. The Scheme
1819 function sets the fraction to 0.9 if a dynamic mark of rfz is
1820 found, or calls the default function otherwise.
1822 @lilypond[verbatim,quote]
1823 #(define (myDynamics dynamic)
1824 (if (equal? dynamic "rfz")
1826 (default-dynamic-absolute-volume dynamic)))
1830 \set Staff.midiInstrument = #"cello"
1831 \set Score.dynamicAbsoluteVolumeFunction = #myDynamics
1843 Alternatively, if the whole table of fractions needs to be
1844 redefined, it would be better to use the
1845 @notation{default-dynamic-absolute-volume} procedure in
1846 @file{../@/scm/@/midi.scm} and the associated table as a model.
1847 The final example in this section shows how this might be done.
1849 @unnumberedsubsubsec Overall MIDI volume
1851 The minimum and maximum overall volume of MIDI dynamic markings is
1852 controlled by setting the properties @code{midiMinimumVolume} and
1853 @code{midiMaximumVolume} at the @code{Score} level. These
1854 properties have an effect only on dynamic marks, so if they
1855 are to apply from the start of the score a dynamic mark must be
1856 placed there. The fraction corresponding to each dynamic mark is
1857 modified with this formula
1860 midiMinimumVolume + (midiMaximumVolume - midiMinimumVolume) * fraction
1863 In the following example the dynamic range of the overall MIDI
1864 volume is limited to the range 0.2 - 0.5.
1866 @lilypond[verbatim,quote]
1872 \set Staff.midiInstrument = #"flute"
1873 \new Voice \relative c''' {
1881 \set Staff.midiInstrument = #"clarinet"
1882 \new Voice \relative c'' {
1893 tempoWholesPerMinute = #(ly:make-moment 72 2)
1894 midiMinimumVolume = #0.2
1895 midiMaximumVolume = #0.5
1901 @unnumberedsubsubsec Equalizing different instruments (i)
1903 If the minimum and maximum MIDI volume properties are set in
1904 the @code{Staff} context the relative volumes of the MIDI
1905 instruments can be controlled. This gives a basic instrument
1906 equalizer, which can enhance the quality of the MIDI output
1909 In this example the volume of the clarinet is reduced relative
1910 to the volume of the flute. There must be a dynamic
1911 mark on the first note of each instrument for this to work
1914 @lilypond[verbatim,quote]
1920 \set Staff.midiInstrument = #"flute"
1921 \set Staff.midiMinimumVolume = #0.7
1922 \set Staff.midiMaximumVolume = #0.9
1923 \new Voice \relative c''' {
1931 \set Staff.midiInstrument = #"clarinet"
1932 \set Staff.midiMinimumVolume = #0.3
1933 \set Staff.midiMaximumVolume = #0.6
1934 \new Voice \relative c'' {
1945 tempoWholesPerMinute = #(ly:make-moment 72 2)
1951 @unnumberedsubsubsec Equalizing different instruments (ii)
1953 If the MIDI minimum and maximum volume properties are not set
1954 LilyPond will, by default, apply a small degree of equalization
1955 to a few instruments. The instruments and the equalization
1956 applied are shown in the table @notation{instrument-equalizer-alist}
1957 in @file{../@/scm/@/midi.scm}.
1959 This basic default equalizer can be replaced by setting
1960 @code{instrumentEqualizer} in the @code{Score} context to a new
1961 Scheme procedure which accepts a MIDI instrument name as its only
1962 argument and returns a pair of fractions giving the minimum and
1963 maximum volumes to be applied to that instrument. This replacement
1964 is done in the same way as shown for resetting the
1965 @code{dynamicAbsoluteVolumeFunction} at the start of this section.
1966 The default equalizer, @notation{default-instrument-equalizer}, in
1967 @file{../@/scm/@/midi.scm} shows how such a procedure might be written.
1969 The following example sets the relative flute and clarinet volumes
1970 to the same values as the previous example.
1972 @lilypond[verbatim,quote]
1973 #(define my-instrument-equalizer-alist '())
1975 #(set! my-instrument-equalizer-alist
1978 ("flute" . (0.7 . 0.9))
1979 ("clarinet" . (0.3 . 0.6)))
1980 my-instrument-equalizer-alist))
1982 #(define (my-instrument-equalizer s)
1983 (let ((entry (assoc s my-instrument-equalizer-alist)))
1992 \set Score.instrumentEqualizer = #my-instrument-equalizer
1993 \set Staff.midiInstrument = #"flute"
1994 \new Voice \relative c''' {
2002 \set Staff.midiInstrument = #"clarinet"
2003 \new Voice \relative c'' {
2014 tempoWholesPerMinute = #(ly:make-moment 72 2)
2021 @c Delete when satisfied this is adequately covered elsewhere -td
2023 @n ode Microtones in MIDI
2024 @s ubsection Microtones in MIDI
2026 @cindex microtones in MIDI
2028 Microtones consisting of half sharps and half flats are exported
2029 to the MIDI file and render correctly in MIDI players which support
2030 pitch bending. See @ref{Note names in other languages}. Here is
2031 an example showing all the half sharps and half flats. It can be
2032 copied out and compiled to test microtones in your MIDI player.
2034 @lilypond[verbatim,quote]
2051 @node Percussion in MIDI
2052 @subsection Percussion in MIDI
2054 Percussion instruments are generally notated in a @code{DrumStaff}
2055 context and when notated in this way they are outputted correctly
2056 to MIDI channel@tie{}10, but some pitched percussion instruments,
2057 like the xylophone, marimba, vibraphone, timpani, etc., are
2058 treated like @qq{normal} instruments and music for these instruments
2059 should be entered in a normal @code{Staff} context, not a
2060 @code{DrumStaff} context, to obtain the correct MIDI output.
2062 Some non-pitched percussion sounds included in the general MIDI
2063 standard, like melodic tom, taiko drum, synth drum, etc., cannot
2064 be reached via MIDI channel@tie{}10, so the notation for such
2065 instruments should also be entered in a normal @code{Staff}
2066 context, using suitable normal pitches.
2068 Many percussion instruments are not included in the general MIDI
2069 standard, e.g. castanets. The easiest, although unsatisfactory,
2070 method of producing some MIDI output when writing for such
2071 instruments is to substitute the nearest sound from the standard
2074 @c TODO Expand with examples, and any other issues
2078 Because the general MIDI standard does not contain rim shots, the
2079 sidestick is used for this purpose instead.