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 @file{.ly}.
35 * Structure of a score::
36 * Multiple scores in a book::
37 * Multiple output files from one input file::
43 @node Structure of a score
44 @subsection Structure of a score
48 A @code{\score} block must contain a single music expression
49 delimited by curly brackets:
57 @warning{There must be @strong{only one} outer music expression in
58 a @code{\score} block, and it @strong{must} be surrounded by
61 This single music expression may be of any size, and may contain
62 other music expressions to any complexity. All of these examples
63 are music expressions:
69 @lilypond[verbatim,quote]
76 @lilypond[verbatim,quote]
78 \new Staff { c'4 c' c' c' }
79 \new Staff { d'4 d' d' d' }
87 \new Staff @{ \flute @}
88 \new Staff @{ \oboe @}
91 \new Staff @{ \violinI @}
92 \new Staff @{ \violinII @}
98 Comments are one exception to this general rule. (For others see
99 @ref{File structure}.) Both single-line comments and comments
100 delimited by @code{%@{ .. %@}} may be placed anywhere within an
101 input file. They may be placed inside or outside a @code{\score}
102 block, and inside or outside the single music expression within a
105 Remember that even in a file containing only a @code{\score} block, it
106 is implicitly enclosed in a \book block. A \book block in a source
107 file produces at least one output file, and by default the name of the
108 output file produced is derived from the name of the input file, so
109 @file{fandangoforelephants.ly} will produce
110 @file{fandangoforelephants.pdf}.
112 (For more details about @code{\book} blocks, see
113 @ref{Multiple scores in a book},
114 @ref{Multiple output files from one input file} @ref{File structure}.)
118 @rlearning{Working on input files},
119 @rlearning{Music expressions explained},
120 @rlearning{Score is a (single) compound musical expression}.
123 @node Multiple scores in a book
124 @subsection Multiple scores in a book
127 @cindex movements, multiple
129 A document may contain multiple pieces of music and text. Examples
130 of these are an etude book, or an orchestral part with multiple
131 movements. Each movement is entered with a @code{\score} block,
139 and texts are entered with a @code{\markup} block,
149 All the movements and texts which appear in the same @file{.ly} file
150 will normally be typeset in the form of a single output file.
164 One important exception is within lilypond-book documents,
165 where you explicitly have to add a @code{\book} block, otherwise only
166 the first @code{\score} or @code{\markup} will appear in the output.
168 The header for each piece of music can be put inside the @code{\score}
169 block. The @code{piece} name from the header will be printed before
170 each movement. The title for the entire book can be put inside the
171 @code{\book}, but if it is not present, the @code{\header} which is at
172 the top of the file is inserted.
176 title = "Eight miniatures"
177 composer = "Igor Stravinsky"
181 \header @{ piece = "Romanze" @}
184 ..text of second verse..
187 ..text of third verse..
191 \header @{ piece = "Menuetto" @}
197 Pieces of music may be grouped into book parts using @code{\bookpart}
198 blocks. Book parts are separated by a page break, and can start with a
199 title, like the book itself, by specifying a @code{\header} block.
205 subtitle = "First part"
212 subtitle = "Second part"
219 @node Multiple output files from one input file
220 @subsection Multiple output files from one input file
222 If you want multiple output files from the same @file{.ly} file,
223 then you can add multiple @code{\book} blocks, where each
224 such \book block will result in a separate output file.
225 If you do not specify any @code{\book} block in the
226 input file, LilyPond will implicitly treat the whole
227 file as a single \book block, see
228 @ref{File structure}.
230 When producing multiple files from a single source file, Lilypond
231 ensures that none of the output files from any @code{\book} block
232 overwrites the output file produced by a preceding @code{\book} from
235 It does this by adding a suffix to the output name for each
236 @code{\book} which uses the default output file name derived from the
239 The default behaviour is to append a version-number suffix for each
240 name which may clash, so
245 \layout @{ @dots{} @}
249 \layout @{ @dots{} @}
253 \layout @{ @dots{} @}
257 in source file @file{eightminiatures.ly}
262 @file{eightminiatures.pdf},
264 @file{eightminiatures-1.pdf} and
266 @file{eightminiatures-2.pdf}.
269 @node Output file names
270 @subsection Output file names
272 @funindex \bookOutputSuffix
273 @funindex \bookOutputName
275 Lilypond provides facilities to allow you to control what file names
276 are used by the various back-ends when producing output files.
278 In the previous section, we saw how Lilypond prevents name-clashes when
279 producing several ouputs from a single source file. You also have the
280 ability to specify your own suffixes for each @code{\book} block, so
281 for example you can produce files called
282 @file{eightminiatures-Romanze.pdf}, @file{eightminiatures-Menuetto.pdf}
283 and @file{eightminiatures-Nocturne.pdf} by adding a
284 @code{\bookOutputSuffix} declaration inside each @code{\book} block.
288 \bookOutputSuffix "Romanze"
290 \layout @{ @dots{} @}
293 \bookOutputSuffix "Menuetto"
295 \layout @{ @dots{} @}
298 \bookOutputSuffix "Nocturne"
300 \layout @{ @dots{} @}
304 You can also specify a different output filename for @code{book} block,
305 by using @code{\bookOutputName} declarations
309 \bookOutputName "Romanze"
311 \layout @{ @dots{} @}
314 \bookOutputName "Menuetto"
316 \layout @{ @dots{} @}
319 \bookOutputName "Nocturne"
321 \layout @{ @dots{} @}
325 The file above will produce these output files:
331 @file{Menuetto.pdf} and
338 @subsection File structure
348 A @file{.ly} file may contain any number of toplevel expressions, where a
349 toplevel expression is one of the following:
353 An output definition, such as @code{\paper}, @code{\midi}, and
354 @code{\layout}. Such a definition at the toplevel changes the default
355 book-wide settings. If more than one such definition of
356 the same type is entered at the top level any definitions in the later
357 expressions have precedence.
360 A direct scheme expression, such as
361 @code{#(set-default-paper-size "a7" 'landscape)} or
362 @code{#(ly:set-option 'point-and-click #f)}.
365 A @code{\header} block. This sets the global header block. This
366 is the block containing the definitions for book-wide settings, like
367 composer, title, etc.
370 A @code{\score} block. This score will be collected with other
371 toplevel scores, and combined as a single @code{\book}.
372 This behavior can be changed by setting the variable
373 @code{toplevel-score-handler} at toplevel. The default handler is
374 defined in the init file @file{../scm/lily.scm}.
377 A @code{\book} block logically combines multiple movements
378 (i.e., multiple @code{\score} blocks) in one document. If there
379 are a number of @code{\score}s, one output file will be created
380 for each @code{\book} block, in which all corresponding movements
381 are concatenated. The only reason to explicitly specify
382 @code{\book} blocks in a @file{.ly} file is if you wish to create
383 multiple output files from a single input file. One exception is
384 within lilypond-book documents, where you explicitly have to add
385 a @code{\book} block if you want more than a single @code{\score}
386 or @code{\markup} in the same example. This behavior can be
387 changed by setting the variable @code{toplevel-book-handler} at
388 toplevel. The default handler is defined in the init file
389 @file{../scm/lily.scm}.
392 A @code{\bookpart} block. A book may be divided into several parts,
393 using @code{\bookpart} blocks, in order to ease the page breaking,
394 or to use different @code{\paper} settings in different parts.
397 A compound music expression, such as
402 This will add the piece in a @code{\score} and format it in a
403 single book together with all other toplevel @code{\score}s and music
404 expressions. In other words, a file containing only the above
405 music expression will be translated into
421 This behavior can be changed by setting the variable
422 @code{toplevel-music-handler} at toplevel. The default handler is
423 defined in the init file @file{../scm/lily.scm}.
426 A markup text, a verse for example
429 2. The first line verse two.
433 Markup texts are rendered above, between or below the scores or music
434 expressions, wherever they appear.
444 This can be used later on in the file by entering @code{\foo}. The
445 name of a variable should have alphabetic characters only; no
446 numbers, underscores or dashes.
450 The following example shows three things that may be entered at
455 % Don't justify the output
467 At any point in a file, any of the following lexical instructions can
471 @item @code{\version}
472 @item @code{\include}
473 @item @code{\sourcefilename}
474 @item @code{\sourcefileline}
476 A single-line comment, introduced by a leading @code{%} sign.
479 A multi-line comment delimited by @code{%@{ .. %@}}.
485 Whitespace between items in the input stream is generally ignored,
486 and may be freely omitted or extended to enhance readability.
487 However, whitespace should always be used in the following
488 circumstances to avoid errors:
491 @item Around every opening and closing curly bracket.
492 @item After every command or variable, i.e. every item that
493 begins with a @code{\} sign.
494 @item After every item that is to be interpreted as a Scheme
495 expression, i.e. every item that begins with a @code{#} sign.
496 @item To separate all elements of a Scheme expression.
497 @item In @code{lyricmode} to separate all the terms in both
498 @code{\override} and @code{\set} commands. In particular, spaces
499 must be used around the dot and the equals sign in commands like
500 @code{\override Score . LyricText #'font-size = #5} and before and
501 after the entire command.
508 @rlearning{How LilyPond input files work}.
511 @node Titles and headers
512 @section Titles and headers
514 Almost all printed music includes a title and the composer's name;
515 some pieces include a lot more information.
518 * Creating titles headers and footers::
519 * Custom headers footers and titles::
520 * Reference to page numbers::
521 * Table of contents::
525 @node Creating titles headers and footers
526 @subsection Creating titles, headers, and footers
529 * Title blocks explained::
530 * Default layout of book and score title blocks::
531 * Default layout of headers and footers::
535 @node Title blocks explained
536 @unnumberedsubsubsec Title blocks explained
538 @c TODO: figure out how \bookpart titles work
540 There are two types of title blocks: the main title block that appears
541 above of the first @code{\score} of a book, and individual title
542 blocks that appear within each @code{\score} block. Text fields for
543 both types are entered using a @code{\header} block.
545 If the book only has a single score, the @code{\header} block may be
546 placed inside or outside of the @code{\score} block.
548 @warning{Remember when adding a @bs{}@code{header} block inside a
549 @bs{}@code{score} block, that the music expression must come before the
550 @bs{}@code{header} block.}
552 @lilypond[papersize=a5,quote,verbatim,noragged-right]
555 composer = "J. S. Bach."
559 \new Staff \relative g, {
562 \repeat unfold 2 { g16( d' b') a b d, b' d, } |
563 \repeat unfold 2 { g,16( e' c') b c e, c' e, } |
571 \new Staff \relative b {
575 <g, d' b'~>4 b'16 a( g fis) g( d e fis) g( a b c) |
576 d16( b g fis) g( e d c) b(c d e) fis( g a b) |
584 Text fields from the main title block of a book can be displayed in all
585 @code{\score} blocks, or manually suppressed:
587 @lilypond[papersize=a5,quote,verbatim,noragged-right]
590 print-all-headers = ##t
593 title = "DAS WOHLTEMPERIRTE CLAVIER"
595 % Do not display the tagline for this book
598 \markup { \vspace #1 }
602 \new Staff { \clef "bass" s1 }
605 title = "PRAELUDIUM I"
607 % Do not display the subtitle for this score
614 \new Staff { \clef "bass" s1 }
618 subsubtitle = "A 4 VOCI"
620 % Do not display the subtitle for this score
629 @ref{File structure},
630 @ref{Custom layout for title blocks}.
633 @node Default layout of book and score title blocks
634 @unnumberedsubsubsec Default layout of book and score title blocks
636 The layout and formatting of title blocks are controlled by two
637 @code{\paper} variables; @code{bookTitleMarkup} for the main
638 @code{\header} title block and @code{scoreTitleMarkup} for individual
639 @code{\header} blocks within a @code{\score}.
641 @lilypond[papersize=a6,quote,verbatim,noragged-right]
643 % The following fields are centered
644 dedication = "Dedication"
646 subtitle = "Subtitle"
647 subsubtitle = "Subsubtitle"
648 instrument = "Instrument"
650 % The following fields are left-aligned on the left side
654 % The following fields are right-aligned on the right side
655 composer = "Composer"
656 arranger = "Arranger"
662 % The following fields are placed at opposite ends of the same line
669 @c Is the bit about \null markups true? -mp
671 Text fields left unset in a @code{\header} block are replaced with
672 @code{\null} markups so that the space is not wasted.
674 The default settings for @code{scoreTitleMarkup} place the @code{piece}
675 and @code{opus} text fields at opposite ends of the same line.
679 Use the @code{breakbefore} variable inside a @code{\header} block
680 that is itself in a @code{\score} block, to make the top-level
681 @code{\header} block titles appear on the first page on their own, with
682 the music (defined in the @code{\score} block) starting on the next.
684 @lilypond[papersize=a8landscape,verbatim,noragged-right]
687 title = "This is my Title"
688 subtitle = "This is my Subtitle"
689 copyright = "This is the bottom of the first page"
692 \repeat unfold 4 { e'' e'' e'' e'' }
694 piece = "This is the Music"
703 @rlearning{How LilyPond input files work},
706 @ref{File structure}.
709 @file{ly/titling-init.ly}.
711 @node Default layout of headers and footers
712 @unnumberedsubsubsec Default layout of headers and footers
714 @emph{Headers} and @emph{footers} are lines of text appearing at
715 the top and bottom of pages, separate from the main text of a book.
716 They are controlled by the following @code{\paper} variables:
719 @item @code{oddHeaderMarkup}
720 @item @code{evenHeaderMarkup}
721 @item @code{oddFooterMarkup}
722 @item @code{evenFooterMarkup}
725 These markup variables can only access text fields from top-level
726 @code{\header} blocks (which apply to all scores in the book) and are
727 defined in @file{ly/titling-init.ly}. By default:
732 page numbers are automatically placed on the top far left (if even) or
733 top far right (if odd), starting from the second page.
736 the @code{instrument} text field is placed in the center of every
737 page, starting from the second page.
740 the @code{copyright} text is centered on the bottom of the first page.
743 the @code{tagline} is centered on the bottom of the last page, and below
744 the @code{copyright} text if there is only a single page.
748 @lilypond[papersize=a8landscape]
758 The default tagline can be changed by adding a @code{tagline} in the
759 top-level @code{\header} block.
761 @lilypond[papersize=a8landscape,verbatim]
764 tagline = "... music notation for Everyone"
774 To remove the @code{tagline} set the value to @code{##f}.
777 @node Custom headers footers and titles
778 @subsection Custom headers, footers, and titles
780 @c TODO: somewhere put a link to header spacing info
781 @c (you'll have to explain it more in NR 4).
784 * Custom text formatting for title blocks::
785 * Custom layout for title blocks::
786 * Custom layout for headers and footers::
790 @node Custom text formatting for title blocks
791 @unnumberedsubsubsec Custom text formatting for title blocks
793 Standard @code{\markup} commands can be used to customize any header,
794 footer and title text within the @code{\header} block.
796 @lilypond[quote,verbatim,noragged-right]
800 piece = \markup { \fontsize #4 \bold "PRAELUDIUM I" }
801 subtitle = \markup { \italic "(Excerpt)" }
808 @ref{Formatting text}.
811 @node Custom layout for title blocks
812 @unnumberedsubsubsec Custom layout for title blocks
814 @code{\markup} commands in the @code{\header} block are useful for
815 simple text formatting, but they do not allow precise control over the
816 placement of titles. To customize the placement of the text fields,
817 use either or both of the following @code{\paper} variables:
820 @item @code{bookTitleMarkup}
821 @item @code{scoreTitleMarkup}
824 These markup variables are discussed in
825 @ref{Default layout of book and score title blocks}.
827 The default settings for @code{scoreTitleMarkup} as defined in
828 @file{ly/titling-init.ly} are:
831 scoreTitleMarkup = \markup @{ \column @{
832 \on-the-fly #print-all-headers @{ \bookTitleMarkup \hspace #1 @}
834 \fromproperty #'header:piece
835 \fromproperty #'header:opus
841 This places the @code{piece} and @code{opus} text fields at opposite
842 ends of the same line:
844 @lilypond[quote,verbatim,noragged-right]
848 piece = "PRAELUDIUM I"
854 This example redefines @code{scoreTitleMarkup} so that the @code{piece}
855 text field is centered and in a large, bold font.
857 @lilypond[papersize=a5,quote,verbatim,noragged-right]
861 scoreTitleMarkup = \markup {
864 \fontsize #4 \bold \fromproperty #'header:piece
865 \fromproperty #'header:opus
869 \header { tagline = ##f }
873 piece = "PRAELUDIUM I"
880 Text fields normally reserved for the main title block can be included
881 in individual score title blocks with the @code{print-all-headers}
882 placed inside the @code{\paper} block. A disadvantage of using this
883 method is that the text fields that are intended specifically for the
884 top-level @code{\header} block need to be manually suppressed in every
885 @code{\score} block. See @ref{Title blocks explained}.
887 To avoid this, add the desired text field to the @code{scoreTitleMarkup}
888 definition. In the following example, the @code{composer} text field
889 (normally associated with @code{bookTitleMarkup}) is added to
890 @code{scoreTitleMarkup}, allowing each score to list a different
893 @lilypond[papersize=a5,quote,verbatim,noragged-right]
897 scoreTitleMarkup = \markup {
900 \fontsize #4 \bold \fromproperty #'header:piece
901 \fromproperty #'header:composer
905 \header { tagline = ##f }
910 composer = "Christian Petzold"
917 composer = "François Couperin"
923 It is also possible to create your own custom text fields, and refer to
924 them in the markup definition.
926 @lilypond[papersize=a5,quote,verbatim,noragged-right]
930 scoreTitleMarkup = \markup {
933 \override #`(direction . ,UP) {
935 \center-align \fontsize #-1 \bold
936 \fromproperty #'header:mycustomtext %% User-defined field
937 \center-align \fontsize #4 \bold
938 \fromproperty #'header:piece
941 \fromproperty #'header:opus
945 \header { tagline = ##f }
950 mycustomtext = "A 4 VOCI" %% User-defined field
959 @ref{Title blocks explained}.
962 @node Custom layout for headers and footers
963 @unnumberedsubsubsec Custom layout for headers and footers
965 @c can make-header and make-footer be removed from
966 @c paper-defaults-init.ly? -mp
968 @code{\markup} commands in the @code{\header} block are useful for
969 simple text formatting, but they do not allow precise control over the
970 placement of headers and footers. To customize the placement of
971 the text fields, use either or both of the following @code{\paper}
975 @item @code{oddHeaderMarkup}
976 @item @code{evenHeaderMarkup}
977 @item @code{oddFooterMarkup}
978 @item @code{evenFooterMarkup}
981 The following example centers page numbers at the bottom of every
982 page. First, the default settings for @code{oddHeaderMarkup} and
983 @code{evenHeaderMarkup} are removed by defining each as a @emph{null}
984 markup. Then, @code{oddFooterMarkup} is redefined with the page
985 number centered. Finally, @code{evenFooterMarkup} is given the
986 same layout by defining it as @code{\oddFooterMarkup}:
988 @lilypond[papersize=a8,quote,verbatim,noragged-right]
991 print-page-number = ##t
992 print-first-page-number = ##t
993 oddHeaderMarkup = \markup \null
994 evenHeaderMarkup = \markup \null
995 oddFooterMarkup = \markup {
997 \on-the-fly #print-page-number-check-first
998 \fromproperty #'page:page-number-string
1001 evenFooterMarkup = \oddFooterMarkup
1004 \new Staff { s1 \break s1 \break s1 }
1011 @ref{Title blocks explained},
1012 @ref{Default layout of book and score title blocks}.
1015 @node Reference to page numbers
1016 @subsection Reference to page numbers
1018 A particular place of a score can be marked using the @code{\label}
1019 command, either at top-level or inside music. This label can then be
1020 referred to in a markup, to get the number of the page where the marked
1021 point is placed, using the @code{\page-ref} markup command.
1024 \header { tagline = ##f }
1030 \pageBreak \mark A \label #'markA
1034 \markup { The first score begins on page \page-ref #'firstScore "0" "?" }
1035 \markup { Mark A is on page \page-ref #'markA "0" "?" }
1039 The @code{\page-ref} markup command takes three arguments:
1041 @item the label, a scheme symbol, eg. @code{#'firstScore};
1042 @item a markup that will be used as a gauge to estimate the dimensions
1044 @item a markup that will be used in place of the page number if the label
1048 The reason why a gauge is needed is that, at the time markups are
1049 interpreted, the page breaking has not yet occurred, so the page numbers
1050 are not yet known. To work around this issue, the actual markup
1051 interpretation is delayed to a later time; however, the dimensions of
1052 the markup have to be known before, so a gauge is used to decide these
1053 dimensions. If the book has between 10 and 99 pages, it may be "00",
1054 ie. a two digit number.
1065 @node Table of contents
1066 @subsection Table of contents
1067 A table of contents is included using the @code{\markuplines \table-of-contents}
1068 command. The elements which should appear in the table of contents are
1069 entered with the @code{\tocItem} command, which may be used either at
1070 top-level, or inside a music expression.
1073 \markuplines \table-of-contents
1076 \tocItem \markup "First score"
1080 \tocItem \markup "Some particular point in the first score"
1085 \tocItem \markup "Second score"
1093 The markups which are used to format the table of contents are defined
1094 in the @code{\paper} block. The default ones are @code{tocTitleMarkup},
1095 for formatting the title of the table, and @code{tocItemMarkup}, for
1096 formatting the toc elements, composed of the element title and page
1097 number. These variables may be changed by the user:
1101 %% Translate the toc title into French:
1102 tocTitleMarkup = \markup \huge \column {
1103 \fill-line { \null "Table des matières" \null }
1106 %% use larger font size
1107 tocItemMarkup = \markup \large \fill-line {
1108 \fromproperty #'toc:text \fromproperty #'toc:page
1113 Note how the toc element text and page number are referred to in
1114 the @code{tocItemMarkup} definition.
1116 New commands and markups may also be defined to build more elaborated
1119 @item first, define a new markup variable in the @code{\paper} block
1120 @item then, define a music function which aims at adding a toc element
1121 using this markup paper variable.
1124 In the following example, a new style is defined for entering act names
1125 in the table of contents of an opera:
1129 tocActMarkup = \markup \large \column {
1131 \fill-line { \null \italic \fromproperty #'toc:text \null }
1137 #(define-music-function (parser location text) (markup?)
1138 (add-toc-item! 'tocActMarkup text))
1141 @lilypond[line-width=11.0\cm]
1142 \header { tagline = ##f }
1144 tocActMarkup = \markup \large \column {
1146 \fill-line { \null \italic \fromproperty #'toc:text \null }
1152 #(define-music-function (parser location text) (markup?)
1153 (add-toc-item! 'tocActMarkup text))
1156 \markuplines \table-of-contents
1157 \tocAct \markup { Atto Primo }
1158 \tocItem \markup { Coro. Viva il nostro Alcide }
1159 \tocItem \markup { Cesare. Presti omai l'Egizzia terra }
1160 \tocAct \markup { Atto Secondo }
1161 \tocItem \markup { Sinfonia }
1162 \tocItem \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
1167 Dots can be added to fill the line between an item and its page number:
1169 @lilypond[verbatim,quote]
1170 \header { tagline = ##f }
1172 tocItemMarkup = \tocItemWithDotsMarkup
1176 \markuplines \table-of-contents
1177 \tocItem \markup { Allegro }
1178 \tocItem \markup { Largo }
1185 Init files: @file{../ly/toc-init.ly}.
1189 @funindex \table-of-contents
1190 @code{\table-of-contents},
1196 @node Working with input files
1197 @section Working with input files
1200 * Including LilyPond files::
1201 * Different editions from one source::
1203 * Displaying LilyPond notation::
1207 @node Including LilyPond files
1208 @subsection Including LilyPond files
1211 @cindex including files
1213 A large project may be split up into separate files. To refer to
1217 \include "otherfile.ly"
1220 The line @code{\include "otherfile.ly"} is equivalent to pasting the
1221 contents of @file{otherfile.ly} into the current file at the place
1222 where the @code{\include} appears. For example, in a large
1223 project you might write separate files for each instrument part
1224 and create a @qq{full score} file which brings together the
1225 individual instrument files. Normally the included file will
1226 define a number of variables which then become available
1227 for use in the full score file. Tagged sections can be
1228 marked in included files to assist in making them usable in
1229 different places in a score, see @ref{Different editions from
1232 Files in the current working directory may be referenced by
1233 specifying just the file name after the @code{\include} command.
1234 Files in other locations may be included by giving either a full
1235 path reference or a relative path reference (but use the UNIX
1236 forward slash, /, rather than the DOS/Windows back slash, \, as the
1237 directory separator.) For example, if @file{stuff.ly} is located
1238 one directory higher than the current working directory, use
1241 \include "../stuff.ly"
1245 or if the included orchestral parts files are all located in a
1246 subdirectory called @file{parts} within the current directory, use
1249 \include "parts/VI.ly"
1250 \include "parts/VII.ly"
1254 Files which are to be included can also contain @code{\include}
1255 statements of their own. By default, these second-level
1256 @code{\include} statements are not interpreted until they have
1257 been brought into the main file, so the file names they specify
1258 must all be relative to the directory containing the main file,
1259 not the directory containing the included file. However,
1260 this behavior can be changed by passing the option
1261 @code{-drelative-includes} option at the command line
1262 (or by adding @code{#(ly:set-option 'relative-includes #t)}
1263 at the top of the main input file). With @code{relative-includes}
1264 set, the path for each @code{\include} command will be taken
1265 relative to the file containing that command. This behavior is
1266 recommended and it will become the default behavior in a future
1267 version of lilypond.
1269 Files can also be included from a directory in a search path
1270 specified as an option when invoking LilyPond from the command
1271 line. The included files are then specified using just their
1272 file name. For example, to compile @file{main.ly} which includes
1273 files located in a subdirectory called @file{parts} by this method,
1274 cd to the directory containing @file{main.ly} and enter
1277 lilypond --include=parts main.ly
1280 and in main.ly write
1288 Files which are to be included in many scores may be placed in
1289 the LilyPond directory @file{../ly}. (The location of this
1290 directory is installation-dependent - see
1291 @rlearning{Other sources of information}). These files can then
1292 be included simply by naming them on an @code{\include} statement.
1293 This is how the language-dependent files like @file{english.ly} are
1296 LilyPond includes a number of files by default when you start
1297 the program. These includes are not apparent to the user, but the
1298 files may be identified by running @code{lilypond --verbose} from
1299 the command line. This will display a list of paths and files that
1300 LilyPond uses, along with much other information. Alternatively,
1301 the more important of these files are discussed in
1302 @rlearning{Other sources of information}. These files may be
1303 edited, but changes to them will be lost on installing a new
1304 version of LilyPond.
1306 Some simple examples of using @code{\include} are shown in
1307 @rlearning{Scores and parts}.
1312 @rlearning{Other sources of information},
1313 @rlearning{Scores and parts}.
1318 If an included file is given a name which is the same as one in
1319 LilyPond's installation files, LilyPond's file from the
1320 installation files takes precedence.
1324 @node Different editions from one source
1325 @subsection Different editions from one source
1327 Several mechanisms are available to facilitate the generation
1328 of different versions of a score from the same music source.
1329 Variables are perhaps most useful for combining lengthy sections
1330 of music and/or annotation in various ways, while tags are more
1331 useful for selecting one from several alternative shorter sections
1332 of music. Whichever method is used, separating the notation from
1333 the structure of the score will make it easier to change the
1334 structure while leaving the notation untouched.
1339 * Using global settings::
1342 @node Using variables
1343 @unnumberedsubsubsec Using variables
1345 @cindex variables, use of
1347 If sections of the music are defined in variables they can be
1348 reused in different parts of the score, see @rlearning{Organizing
1349 pieces with variables}. For example, an @notation{a cappella}
1350 vocal score frequently includes a piano reduction of the parts
1351 for rehearsal purposes which is identical to the vocal music, so
1352 the music need be entered only once. Music from two variables
1353 may be combined on one staff, see @ref{Automatic part combining}.
1356 @lilypond[verbatim,quote]
1357 sopranoMusic = \relative c'' { a4 b c b8( a) }
1358 altoMusic = \relative g' { e4 e e f }
1359 tenorMusic = \relative c' { c4 b e d8( c) }
1360 bassMusic = \relative c' { a4 gis a d, }
1361 allLyrics = \lyricmode {King of glo -- ry }
1363 \new Staff = "Soprano" \sopranoMusic
1364 \new Lyrics \allLyrics
1365 \new Staff = "Alto" \altoMusic
1366 \new Lyrics \allLyrics
1367 \new Staff = "Tenor" {
1371 \new Lyrics \allLyrics
1372 \new Staff = "Bass" {
1376 \new Lyrics \allLyrics
1379 \set Staff.printPartCombineTexts = ##f
1385 \set Staff.printPartCombineTexts = ##f
1395 Separate scores showing just the vocal parts or just the piano
1396 part can be produced by changing just the structural statements,
1397 leaving the musical notation unchanged.
1399 For lengthy scores, the variable definitions may be placed in
1400 separate files which are then included, see @ref{Including
1404 @unnumberedsubsubsec Using tags
1407 @funindex \keepWithTag
1408 @funindex \removeWithTag
1410 @cindex keep tagged music
1411 @cindex remove tagged music
1413 The @code{\tag #'@var{partA}} command marks a music expression
1414 with the name @var{partA}.
1415 Expressions tagged in this way can be selected or filtered out by
1416 name later, using either @code{\keepWithTag #'@var{name}} or
1417 @code{\removeWithTag #'@var{name}}. The result of applying these filters
1418 to tagged music is as follows:
1419 @multitable @columnfractions .5 .5
1423 Tagged music preceded by @code{\keepWithTag #'@var{name}}
1424 @tab Untagged music and music tagged with @var{name} is included;
1425 music tagged with any other tag name is excluded.
1427 Tagged music preceded by @code{\removeWithTag #'@var{name}}
1428 @tab Untagged music and music tagged with any tag name other than
1429 @var{name} is included; music tagged with @var{name} is
1432 Tagged music not preceded by either @code{\keepWithTag} or
1433 @code{\removeWithTag}
1434 @tab All tagged and untagged music is included.
1437 The arguments of the @code{\tag}, @code{\keepWithTag} and
1438 @code{\removeWithTag} commands should be a symbol
1439 (such as @code{#'score} or @code{#'part}), followed
1440 by a music expression.
1442 In the following example, we see two versions of a piece of music,
1443 one showing trills with the usual notation, and one with trills
1444 explicitly expanded:
1446 @lilypond[verbatim,quote]
1447 music = \relative g' {
1449 \tag #'trills { d8.\trill }
1450 \tag #'expand { \repeat unfold 3 { e32 d } }
1455 \keepWithTag #'trills \music
1458 \keepWithTag #'expand \music
1463 Alternatively, it is sometimes easier to exclude sections of music:
1465 @lilypond[verbatim,quote]
1466 music = \relative g' {
1468 \tag #'trills { d8.\trill }
1469 \tag #'expand {\repeat unfold 3 { e32 d } }
1474 \removeWithTag #'expand
1478 \removeWithTag #'trills
1483 Tagged filtering can be applied to articulations, texts, etc. by
1487 -\tag #'@var{your-tag}
1490 to an articulation. For example, this would define a note with a
1491 conditional fingering indication and a note with a conditional
1496 c1-\tag #'warn ^"Watch!"
1499 Multiple tags may be placed on expressions with multiple
1500 @code{\tag} entries:
1502 @lilypond[quote,verbatim]
1503 music = \relative c'' {
1504 \tag #'a \tag #'both { a4 a a a }
1505 \tag #'b \tag #'both { b4 b b b }
1508 \keepWithTag #'a \music
1509 \keepWithTag #'b \music
1510 \keepWithTag #'both \music
1514 Multiple @code{\removeWithTag} filters may be applied to a single
1515 music expression to remove several differently named tagged sections:
1517 @lilypond[verbatim,quote]
1518 music = \relative c'' {
1519 \tag #'A { a4 a a a }
1520 \tag #'B { b4 b b b }
1521 \tag #'C { c4 c c c }
1522 \tag #'D { d4 d d d }
1531 Two or more @code{\keepWithTag} filters applied to a single music
1532 expression will cause @emph{all} tagged sections to be removed, as
1533 the first filter will remove all tagged sections except the one
1534 named, and the second filter will remove even that tagged section.
1539 @rlearning{Organizing pieces with variables}.
1542 @ref{Automatic part combining},
1543 @ref{Including LilyPond files}.
1547 @c This warning is more general than this placement implies.
1548 @c Rests are not merged whether or not they come from tagged sections.
1549 @c Should be deleted? -td
1553 Multiple rests are not merged if you create a score with more
1554 than one tagged section at the same place.
1558 @node Using global settings
1559 @unnumberedsubsubsec Using global settings
1561 @cindex include-settings
1563 Global settings can be included from a separate file:
1566 lilypond -dinclude-settings=MY_SETTINGS.ly MY_SCORE.ly
1569 Groups of settings such as page size, font or type face can be stored
1570 in separate files. This allows different editions from the same score
1571 as well as standard settings to be applied to many scores, simply by
1572 specifying the proper settings file.
1574 This technique also works well with the use of style sheets, as
1575 discussed in @rlearning{Style sheets}.
1579 @rlearning{Organizing pieces with variables},
1580 @rlearning{Style sheets}.
1583 @ref{Including LilyPond files}.
1586 @subsection Text encoding
1590 @cindex non-ASCII characters
1592 LilyPond uses the character repertoire defined by the Unicode
1593 consortium and ISO/IEC 10646. This defines a unique name and
1594 code point for the character sets used in virtually all modern
1595 languages and many others too. Unicode can be implemented using
1596 several different encodings. LilyPond uses the UTF-8 encoding
1597 (UTF stands for Unicode Transformation Format) which represents
1598 all common Latin characters in one byte, and represents other
1599 characters using a variable length format of up to four bytes.
1601 The actual appearance of the characters is determined by the
1602 glyphs defined in the particular fonts available - a font defines
1603 the mapping of a subset of the Unicode code points to glyphs.
1604 LilyPond uses the Pango library to layout and render multi-lingual
1607 LilyPond does not perform any input-encoding conversions. This
1608 means that any text, be it title, lyric text, or musical
1609 instruction containing non-ASCII characters, must be encoded in
1610 UTF-8. The easiest way to enter such text is by using a
1611 Unicode-aware editor and saving the file with UTF-8 encoding. Most
1612 popular modern editors have UTF-8 support, for example, vim, Emacs,
1613 jEdit, and GEdit do. All MS Windows systems later than NT use
1614 Unicode as their native character encoding, so even Notepad can
1615 edit and save a file in UTF-8 format. A more functional
1616 alternative for Windows is BabelPad.
1618 If a LilyPond input file containing a non-ASCII character is not
1619 saved in UTF-8 format the error message
1622 FT_Get_Glyph_Name () error: invalid argument
1627 Here is an example showing Cyrillic, Hebrew and Portuguese
1631 %c No verbatim here as the code does not display correctly in PDF
1633 bulgarian = \lyricmode {
1634 Жълтата дюля беше щастлива, че пухът, който цъфна, замръзна като гьон.
1638 hebrew = \lyricmode {
1639 זה כיף סתם לשמוע איך תנצח קרפד עץ טוב בגן.
1643 portuguese = \lyricmode {
1644 à vo -- cê uma can -- ção legal
1650 \addlyrics { \bulgarian }
1651 \addlyrics { \hebrew }
1652 \addlyrics { \portuguese }
1655 To enter a single character for which the Unicode code point is
1656 known but which is not available in the editor being used, use
1657 either @code{\char ##xhhhh} or @code{\char #dddd} within a
1658 @code{\markup} block, where @code{hhhh} is the hexadecimal code for
1659 the character required and @code{dddd} is the corresponding decimal
1660 value. Leading zeroes may be omitted, but it is usual to specify
1661 all four characters in the hexadecimal representation. (Note that
1662 the UTF-8 encoding of the code point should @emph{not} be used
1663 after @code{\char}, as UTF-8 encodings contain extra bits indicating
1664 the number of octets.) Unicode code charts and a character name
1665 index giving the code point in hexadecimal for any character can be
1666 found on the Unicode Consortium website,
1667 @uref{http://www.unicode.org/}.
1669 For example, @code{\char ##x03BE} and @code{\char #958} would both
1670 enter the Unicode U+03BE character, which has the Unicode name
1671 @qq{Greek Small Letter Xi}.
1673 Any Unicode code point may be entered in this way and if all special
1674 characters are entered in this format it is not necessary to save
1675 the input file in UTF-8 format. Of course, a font containing all
1676 such encoded characters must be installed and available to LilyPond.
1678 The following example shows Unicode hexadecimal values being entered
1679 in four places -- in a rehearsal mark, as articulation text, in
1680 lyrics and as stand-alone text below the score:
1682 @lilypond[quote,verbatim]
1685 c1 \mark \markup { \char ##x03EE }
1686 c1_\markup { \tiny { \char ##x03B1 " to " \char ##x03C9 } }
1688 \addlyrics { O \markup { \concat { Ph \char ##x0153 be! } } }
1690 \markup { "Copyright 2008--2011" \char ##x00A9 }
1693 @cindex copyright sign
1695 To enter the copyright sign in the copyright notice use:
1699 copyright = \markup @{ \char ##x00A9 "2008" @}
1703 @node Displaying LilyPond notation
1704 @subsection Displaying LilyPond notation
1706 @funindex \displayLilyMusic
1707 Displaying a music expression in LilyPond notation can be
1708 done with the music function @code{\displayLilyMusic} but only when
1709 using the command line. For example,
1713 \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
1720 @{ a,4 cis e fis g @}
1723 By default, LilyPond will print these messages to the console
1724 along with all the other LilyPond compilation messages. To split
1725 up these messages and save the results of @code{\display@{STUFF@}},
1726 redirect the output to a file.
1729 lilypond file.ly >display.txt
1734 @node Controlling output
1735 @section Controlling output
1738 * Extracting fragments of music::
1739 * Skipping corrected music::
1740 * Alternative output formats::
1741 * Replacing the notation font::
1744 @node Extracting fragments of music
1745 @subsection Extracting fragments of music
1747 It is possible to quote small fragments of a large score directly from
1748 the output. This can be compared to clipping a piece of a paper score
1751 This is done by defining the measures that need to be cut out
1752 separately. For example, including the following definition
1760 (make-rhythmic-location 5 1 2)
1761 (make-rhythmic-location 7 3 4)))
1766 will extract a fragment starting halfway the fifth measure, ending in
1767 the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note
1768 in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7.
1770 More clip regions can be defined by adding more pairs of
1771 rhythmic-locations to the list.
1773 In order to use this feature, LilyPond must be invoked with
1774 @code{-dclip-systems}. The clips are output as EPS files, and are
1775 converted to PDF and PNG if these formats are switched on as well.
1777 For more information on output formats, see @rprogram{Invoking lilypond}.
1779 @node Skipping corrected music
1780 @subsection Skipping corrected music
1783 @funindex skipTypesetting
1784 @funindex showFirstLength
1785 @funindex showLastLength
1787 When entering or copying music, usually only the music near the end (where
1789 are adding notes) is interesting to view and correct. To speed up
1790 this correction process, it is possible to skip typesetting of all but
1791 the last few measures. This is achieved by putting
1794 showLastLength = R1*5
1799 in your source file. This will render only the last 5 measures
1800 (assuming 4/4 time signature) of every @code{\score} in the input
1801 file. For longer pieces, rendering only a small part is often an order
1802 of magnitude quicker than rendering it completely. When working on the
1803 beginning of a score you have already typeset (e.g. to add a new part),
1804 the @code{showFirstLength} property may be useful as well.
1806 Skipping parts of a score can be controlled in a more fine-grained
1807 fashion with the property @code{Score.skipTypesetting}. When it is
1808 set, no typesetting is performed at all.
1810 This property is also used to control output to the MIDI file. Note that
1811 it skips all events, including tempo and instrument changes. You have
1814 @lilypond[quote,relative=2,ragged-right,verbatim]
1816 \set Score.skipTypesetting = ##t
1818 \set Score.skipTypesetting = ##f
1822 In polyphonic music, @code{Score.skipTypesetting} will affect all
1823 voices and staves, saving even more time.
1825 @node Alternative output formats
1826 @subsection Alternative output formats
1828 @cindex scalable vector graphics output
1830 @cindex encapsulated postscript output
1833 The default output formats for the printed score are Portable
1834 Document Format (PDF) and PostScript (PS). Scalable Vector
1835 Graphics (SVG), Encapsulated PostScript (EPS) and Portable
1836 Network Graphics (PNG) output formats are also available through
1837 command line options, see @rprogram{Command line options for
1841 @node Replacing the notation font
1842 @subsection Replacing the notation font
1844 Gonville is an alternative to the Feta font used in LilyPond and can
1847 @uref{http://www.chiark.greenend.org.uk/~sgtatham/gonville/ ,http://www.chiark.greenend.org.uk/~sgtatham/gonville/}
1850 Here are a few sample bars of music set in Gonville:
1852 @c NOTE: these images are a bit big, but that's important
1853 @c for the font comparison. -gp
1854 @sourceimage{Gonville_after,,,}
1856 Here are a few sample bars of music set in LilyPond's Feta font:
1858 @sourceimage{Gonville_before,,,}
1860 @subsubheading Installation Instructions for MacOS
1862 Download and extract the zip file. Copy the @code{lilyfonts}
1863 directory to @file{@var{SHARE_DIR}/lilypond/current}; for more
1864 information, see @rlearning{Other sources of information}.
1865 Move the existing @code{fonts} directory to @code{fonts_orig} and
1866 move the @code{lilyfonts} directory to @code{fonts}. Simply move
1867 @code{fonts_orig} back to @code{fonts} to revert back to Feta.
1870 Learning Manual: @rlearning{Other sources of information}.
1874 Gonville cannot be used to typeset @q{Ancient Music} notation. Please
1875 refer to the author's website for more information on this and other
1876 specifics including licensing of Gonville.
1880 @section MIDI output
1885 MIDI (Musical Instrument Digital Interface) is a standard for
1886 connecting and controlling digital instruments. A MIDI file is a
1887 series of notes in a number of tracks. It is not an actual
1888 sound file; you need special software to translate between the
1889 series of notes and actual sounds.
1891 Pieces of music can be converted to MIDI files, so you can listen to
1892 what was entered. This is convenient for checking the music; octaves
1893 that are off or accidentals that were mistyped stand out very much
1894 when listening to the MIDI output.
1896 Standard MIDI oputput is somewhat crude; optionally, an enhanced and
1897 more realistic MIDI output is available by means of
1898 @ref{The Articulate script}.
1901 The midi output allocates a channel for each staff, and one for global
1902 settings. Therefore the midi file should not have more than 15 staves
1903 (or 14 if you do not use drums). Other staves will remain silent.
1906 * Creating MIDI files::
1908 * What goes into the MIDI output?::
1910 * Controlling MIDI dynamics::
1911 * Percussion in MIDI::
1912 * The Articulate script::
1915 @node Creating MIDI files
1916 @subsection Creating MIDI files
1918 To create a MIDI output file from a LilyPond input file, add a
1919 @code{\midi} block to a score, for example,
1928 If there is a @code{\midi} block in a @code{\score} with no
1929 @code{\layout} block, only MIDI output will be produced. When
1930 notation is needed too, a @code{\layout} block must also be
1941 Pitches, rhythms, ties, dynamics, and tempo changes are interpreted
1942 and translated correctly to the MIDI output. Dynamic marks,
1943 crescendi and decrescendi translate into MIDI volume levels.
1944 Dynamic marks translate to a fixed fraction of the available MIDI
1945 volume range. Crescendi and decrescendi make the volume vary
1946 linearly between their two extremes. The effect of dynamic markings
1947 on the MIDI output can be removed completely, see @ref{MIDI block}.
1949 The initial tempo and later tempo changes can be specified
1950 with the @code{\tempo} command within the music notation. These
1951 are reflected in tempo changes in the MIDI output. This command
1952 will normally result in the metronome mark being printed, but this
1953 can be suppressed, see @ref{Metronome marks}. An alternative way
1954 of specifying the initial or overall MIDI tempo is described below,
1955 see @ref{MIDI block}.
1957 Due to some limitations on Windows, the default extension for
1958 MIDI files on Windows is @code{.mid}. Other operating systems still
1959 use the extension @code{.midi}. If a different extension is preferred,
1960 insert the following line at the top-level of the input file,
1961 before the start of any @code{\book}, @code{\bookpart} or @code{\score} blocks:
1964 #(ly:set-option 'midi-extension "midi")
1967 The line above will set the default extension for MIDI files to
1970 Alternatively, this option can also be supplied on the command line:
1973 lilypond … -dmidi-extension=midi lilyFile.ly
1977 @unnumberedsubsubsec Instrument names
1979 @cindex instrument names
1980 @funindex Staff.midiInstrument
1982 The MIDI instrument to be used is specified by setting the
1983 @code{Staff.midiInstrument} property to the instrument name.
1984 The name should be chosen from the list in @ref{MIDI instruments}.
1988 \set Staff.midiInstrument = #"glockenspiel"
1994 \new Staff \with @{midiInstrument = #"cello"@} @{
1999 If the selected instrument does not exactly match an instrument from
2000 the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
2006 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
2007 {changing-midi-output-to-one-channel-per-voice.ly}
2011 @c In 2.11 the following no longer seems to be a problem -td
2013 Unterminated (de)crescendos will not render properly in the midi file,
2014 resulting in silent passages of music. The workaround is to explicitly
2015 terminate the (de)crescendo. For example,
2022 will not work properly but
2025 @{ a4\< b c d\!\f @}
2032 Changes in the MIDI volume take place only on starting a note, so
2033 crescendi and decrescendi cannot affect the volume of a
2036 Not all midi players correctly handle tempo changes in the midi
2037 output. Players that are known to work include MS Windows Media
2038 Player and @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
2041 @subsection MIDI block
2044 A @code{\midi} block must appear within a score block if MIDI output
2045 is required. It is analogous to the layout block, but somewhat
2046 simpler. Often, the @code{\midi} block is left empty, but it
2047 can contain context rearrangements, new context definitions or code
2048 to set the values of properties. For example, the following will
2049 set the initial tempo exported to a MIDI file without causing a tempo
2050 indication to be printed:
2058 tempoWholesPerMinute = #(ly:make-moment 72 4)
2064 In this example the tempo is set to 72 quarter note
2065 beats per minute. This kind of tempo specification cannot take
2066 a dotted note length as an argument. If one is required, break
2067 the dotted note into smaller units. For example, a tempo of 90
2068 dotted quarter notes per minute can be specified as 270 eighth
2072 tempoWholesPerMinute = #(ly:make-moment 270 8)
2075 @cindex MIDI context definitions
2077 Context definitions follow precisely the same syntax as those
2078 within a @code{\layout} block. Translation modules for sound are
2079 called performers. The contexts for MIDI output are defined in
2080 @file{../ly/performer-init.ly},
2081 see @rlearning{Other sources of information}.
2082 For example, to remove the effect of dynamics
2083 from the MIDI output, insert the following lines in the
2084 @code{\midi@{ @}} block.
2091 \remove "Dynamic_performer"
2096 MIDI output is created only when a @code{\midi} block is included
2097 within a score block defined with a @code{\score} command.
2101 @{ @dots{}notes@dots{} @}
2106 @node What goes into the MIDI output?
2107 @subsection What goes into the MIDI output?
2109 @c TODO Check grace notes - timing is suspect?
2111 @unnumberedsubsubsec Supported in MIDI
2113 @cindex Pitches in MIDI
2114 @cindex MIDI, Pitches
2115 @cindex Quarter tones in MIDI
2116 @cindex MIDI, quarter tones
2117 @cindex Microtones in MIDI
2118 @cindex MIDI, microtones
2119 @cindex Chord names in MIDI
2120 @cindex MIDI, chord names
2121 @cindex Rhythms in MIDI
2122 @cindex MIDI, Rhythms
2123 @cindex Articlulate scripts
2124 @cindex MIDI, articulations
2125 @cindex articulations in MIDI
2126 @cindex trills in MIDI
2127 @cindex turns in MIDI
2128 @cindex rallentando in MIDI
2129 @cindex accelerando in MIDI
2132 The following items of notation are reflected in the MIDI output:
2136 @item Microtones (See @ref{Accidentals}. Rendering needs a
2137 player that supports pitch bend.)
2138 @item Chords entered as chord names
2139 @item Rhythms entered as note durations, including tuplets
2140 @item Tremolos entered without @q{@code{:}[@var{number}]}
2143 @item Crescendi, decrescendi over multiple notes
2144 @item Tempo changes entered with a tempo marking
2148 Using @ref{The Articulate script}, a number of items are added to the
2152 @item Articulations (slurs, staccato, etc)
2154 @item Rallentando and accelerando
2158 @unnumberedsubsubsec Unsupported in MIDI
2160 @c TODO index as above
2162 The following items of notation have no effect on the MIDI output,
2163 unless you use @ref{The Articulate script}:
2166 @item Rhythms entered as annotations, e.g. swing
2167 @item Tempo changes entered as annotations with no tempo marking
2168 @item Staccato and other articulations and ornamentations
2169 @item Slurs and Phrasing slurs
2170 @item Crescendi, decrescendi over a single note
2171 @item Tremolos entered with @q{@code{:}[@var{number}]}
2173 @item Microtonal chords
2177 @node Repeats in MIDI
2178 @subsection Repeats in MIDI
2180 @cindex repeats in MIDI
2181 @funindex \unfoldRepeats
2183 With a few minor additions, all types of repeats can be represented
2184 in the MIDI output. This is achieved by applying the
2185 @code{\unfoldRepeats} music function. This function changes all
2186 repeats to unfold repeats.
2188 @lilypond[quote,verbatim]
2190 \repeat tremolo 8 { c'32 e' }
2191 \repeat percent 2 { c''8 d'' }
2192 \repeat volta 2 { c'4 d' e' f' }
2201 In scores containing multiple voices, unfolding of repeats in MIDI
2202 output will only occur correctly if @emph{each} voice contains fully
2203 notated repeat indications.
2205 When creating a score file using @code{\unfoldRepeats} for MIDI,
2206 it is necessary to make two @code{\score} blocks: one for MIDI
2207 (with unfolded repeats) and one for notation (with volta, tremolo,
2208 and percent repeats). For example,
2216 \unfoldRepeats @var{..music..}
2221 @node Controlling MIDI dynamics
2222 @subsection Controlling MIDI dynamics
2224 MIDI dynamics are implemented by the Dynamic_performer which lives
2225 by default in the Voice context. It is possible to control the
2226 overall MIDI volume, the relative volume of dynamic markings and
2227 the relative volume of different instruments.
2229 @unnumberedsubsubsec Dynamic marks
2231 Dynamic marks are translated to a fixed fraction of the available
2232 MIDI volume range. The default fractions range from 0.25 for
2233 @notation{ppppp} to 0.95 for @notation{fffff}. The set of dynamic
2234 marks and the associated fractions can be seen in
2235 @file{../scm/midi.scm}, see @rlearning{Other sources of information}.
2236 This set of fractions may be changed or extended by providing a
2237 function which takes a dynamic mark as its argument and returns the
2238 required fraction, and setting
2239 @code{Score.dynamicAbsoluteVolumeFunction} to this function.
2241 For example, if a @notation{rinforzando} dynamic marking,
2242 @code{\rfz}, is required, this will not by default
2243 have any effect on the MIDI volume, as this dynamic marking is not
2244 included in the default set. Similarly, if a new dynamic marking
2245 has been defined with @code{make-dynamic-script} that too will not
2246 be included in the default set. The following example shows how the
2247 MIDI volume for such dynamic markings might be added. The Scheme
2248 function sets the fraction to 0.9 if a dynamic mark of rfz is
2249 found, or calls the default function otherwise.
2251 @lilypond[verbatim,quote]
2252 #(define (myDynamics dynamic)
2253 (if (equal? dynamic "rfz")
2255 (default-dynamic-absolute-volume dynamic)))
2259 \set Staff.midiInstrument = #"cello"
2260 \set Score.dynamicAbsoluteVolumeFunction = #myDynamics
2272 Alternatively, if the whole table of fractions needs to be
2273 redefined, it would be better to use the
2274 @notation{default-dynamic-absolute-volume} procedure in
2275 @file{../scm/midi.scm} and the associated table as a model.
2276 The final example in this section shows how this might be done.
2278 @unnumberedsubsubsec Overall MIDI volume
2280 The minimum and maximum overall volume of MIDI dynamic markings is
2281 controlled by setting the properties @code{midiMinimumVolume} and
2282 @code{midiMaximumVolume} at the @code{Score} level. These
2283 properties have an effect only on dynamic marks, so if they
2284 are to apply from the start of the score a dynamic mark must be
2285 placed there. The fraction corresponding to each dynamic mark is
2286 modified with this formula
2289 midiMinimumVolume + (midiMaximumVolume - midiMinimumVolume) * fraction
2292 In the following example the dynamic range of the overall MIDI
2293 volume is limited to the range 0.2 - 0.5.
2295 @lilypond[verbatim,quote]
2301 \set Staff.midiInstrument = #"flute"
2302 \new Voice \relative c''' {
2310 \set Staff.midiInstrument = #"clarinet"
2311 \new Voice \relative c'' {
2322 tempoWholesPerMinute = #(ly:make-moment 72 2)
2323 midiMinimumVolume = #0.2
2324 midiMaximumVolume = #0.5
2330 @unnumberedsubsubsec Equalizing different instruments (i)
2332 If the minimum and maximum MIDI volume properties are set in
2333 the @code{Staff} context the relative volumes of the MIDI
2334 instruments can be controlled. This gives a basic instrument
2335 equalizer, which can enhance the quality of the MIDI output
2338 In this example the volume of the clarinet is reduced relative
2339 to the volume of the flute. There must be a dynamic
2340 mark on the first note of each instrument for this to work
2343 @lilypond[verbatim,quote]
2349 \set Staff.midiInstrument = #"flute"
2350 \set Staff.midiMinimumVolume = #0.7
2351 \set Staff.midiMaximumVolume = #0.9
2352 \new Voice \relative c''' {
2360 \set Staff.midiInstrument = #"clarinet"
2361 \set Staff.midiMinimumVolume = #0.3
2362 \set Staff.midiMaximumVolume = #0.6
2363 \new Voice \relative c'' {
2374 tempoWholesPerMinute = #(ly:make-moment 72 2)
2380 @unnumberedsubsubsec Equalizing different instruments (ii)
2382 If the MIDI minimum and maximum volume properties are not set
2383 LilyPond will, by default, apply a small degree of equalization
2384 to a few instruments. The instruments and the equalization
2385 applied are shown in the table @notation{instrument-equalizer-alist}
2386 in @file{../scm/midi.scm}.
2388 This basic default equalizer can be replaced by setting
2389 @code{instrumentEqualizer} in the @code{Score} context to a new
2390 Scheme procedure which accepts a MIDI instrument name as its only
2391 argument and returns a pair of fractions giving the minimum and
2392 maximum volumes to be applied to that instrument. This replacement
2393 is done in the same way as shown for resetting the
2394 @code{dynamicAbsoluteVolumeFunction} at the start of this section.
2395 The default equalizer, @notation{default-instrument-equalizer}, in
2396 @file{../scm/midi.scm} shows how such a procedure might be written.
2398 The following example sets the relative flute and clarinet volumes
2399 to the same values as the previous example.
2401 @lilypond[verbatim,quote]
2402 #(define my-instrument-equalizer-alist '())
2404 #(set! my-instrument-equalizer-alist
2407 ("flute" . (0.7 . 0.9))
2408 ("clarinet" . (0.3 . 0.6)))
2409 my-instrument-equalizer-alist))
2411 #(define (my-instrument-equalizer s)
2412 (let ((entry (assoc s my-instrument-equalizer-alist)))
2421 \set Score.instrumentEqualizer = #my-instrument-equalizer
2422 \set Staff.midiInstrument = #"flute"
2423 \new Voice \relative c''' {
2431 \set Staff.midiInstrument = #"clarinet"
2432 \new Voice \relative c'' {
2443 tempoWholesPerMinute = #(ly:make-moment 72 2)
2450 @c Delete when satisfied this is adequately covered elsewhere -td
2452 @n ode Microtones in MIDI
2453 @s ubsection Microtones in MIDI
2455 @cindex microtones in MIDI
2457 Microtones consisting of half sharps and half flats are exported
2458 to the MIDI file and render correctly in MIDI players which support
2459 pitch bending. See @ref{Note names in other languages}. Here is
2460 an example showing all the half sharps and half flats. It can be
2461 copied out and compiled to test microtones in your MIDI player.
2463 @lilypond[verbatim,quote]
2480 @node Percussion in MIDI
2481 @subsection Percussion in MIDI
2483 Percussion instruments are generally notated in a @code{DrumStaff}
2484 context and when notated in this way they are outputted correctly
2485 to MIDI channel@tie{}10, but some pitched percussion instruments,
2486 like the xylophone, marimba, vibraphone, timpani, etc., are
2487 treated like @qq{normal} instruments and music for these instruments
2488 should be entered in a normal @code{Staff} context, not a
2489 @code{DrumStaff} context, to obtain the correct MIDI output.
2491 Some non-pitched percussion sounds included in the general MIDI
2492 standard, like melodic tom, taiko drum, synth drum, etc., cannot
2493 be reached via MIDI channel@tie{}10, so the notation for such
2494 instruments should also be entered in a normal @code{Staff}
2495 context, using suitable normal pitches.
2497 Many percussion instruments are not included in the general MIDI
2498 standard, e.g. castanets. The easiest, although unsatisfactory,
2499 method of producing some MIDI output when writing for such
2500 instruments is to substitute the nearest sound from the standard
2503 @c TODO Expand with examples, and any other issues
2507 Because the general MIDI standard does not contain rim shots, the
2508 sidestick is used for this purpose instead.
2510 @node The Articulate script
2511 @subsection The Articulate script
2513 A more realistic MIDI output is possible when using the Articulate
2514 script. It tries to take articulations (slurs, staccato, etc) into
2515 account, by replacing notes with sequential music of suitably
2516 time-scaled note plus skip. It also tries to unfold trills turns
2517 etc., and take rallentando and accelerando into account.
2519 To use the Articulate script, you have to include it at the top of
2523 \include "articulate.ly"
2526 and in the @code{\score} section do
2529 \unfoldRepeats \articulate <<
2530 all the rest of the score...
2534 After altering your input file this way, the visual output is heavily
2535 altered, but the standard @code{\midi} block will produce a better
2538 Although not essential for the Articulate script to work, you may want
2539 to insert the @code{\unfoldRepeats} command as it appears in the
2540 example shown above as it enables performing abbreviatures such as
2545 Articulate shortens chords and some music (esp. organ music) could