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::
25 * Extracting musical information::
30 @section Input structure
32 The main format of input for LilyPond are text files. By convention,
33 these files end with @file{.ly}.
36 * Structure of a score::
37 * Multiple scores in a book::
38 * Multiple output files from one input file::
44 @node Structure of a score
45 @subsection Structure of a score
49 A @code{\score} block must contain a single music expression
50 delimited by curly brackets:
58 @warning{There must be @strong{only one} outer music expression in
59 a @code{\score} block, and it @strong{must} be surrounded by
62 This single music expression may be of any size, and may contain
63 other music expressions to any complexity. All of these examples
64 are music expressions:
70 @lilypond[verbatim,quote]
77 @lilypond[verbatim,quote]
79 \new Staff { c'4 c' c' c' }
80 \new Staff { d'4 d' d' d' }
88 \new Staff @{ \flute @}
89 \new Staff @{ \oboe @}
92 \new Staff @{ \violinI @}
93 \new Staff @{ \violinII @}
99 Comments are one exception to this general rule. (For others see
100 @ref{File structure}.) Both single-line comments and comments
101 delimited by @code{%@{ .. %@}} may be placed anywhere within an
102 input file. They may be placed inside or outside a @code{\score}
103 block, and inside or outside the single music expression within a
106 Remember that even in a file containing only a @code{\score} block, it
107 is implicitly enclosed in a \book block. A \book block in a source
108 file produces at least one output file, and by default the name of the
109 output file produced is derived from the name of the input file, so
110 @file{fandangoforelephants.ly} will produce
111 @file{fandangoforelephants.pdf}.
113 (For more details about @code{\book} blocks, see
114 @ref{Multiple scores in a book},
115 @ref{Multiple output files from one input file} @ref{File structure}.)
119 @rlearning{Working on input files},
120 @rlearning{Music expressions explained},
121 @rlearning{Score is a (single) compound musical expression}.
124 @node Multiple scores in a book
125 @subsection Multiple scores in a book
128 @cindex movements, multiple
130 A document may contain multiple pieces of music and text. Examples
131 of these are an etude book, or an orchestral part with multiple
132 movements. Each movement is entered with a @code{\score} block,
140 and texts are entered with a @code{\markup} block,
150 All the movements and texts which appear in the same @file{.ly} file
151 will normally be typeset in the form of a single output file.
165 One important exception is within lilypond-book documents,
166 where you explicitly have to add a @code{\book} block, otherwise only
167 the first @code{\score} or @code{\markup} will appear in the output.
169 The header for each piece of music can be put inside the @code{\score}
170 block. The @code{piece} name from the header will be printed before
171 each movement. The title for the entire book can be put inside the
172 @code{\book}, but if it is not present, the @code{\header} which is at
173 the top of the file is inserted.
177 title = "Eight miniatures"
178 composer = "Igor Stravinsky"
182 \header @{ piece = "Romanze" @}
185 ..text of second verse..
188 ..text of third verse..
192 \header @{ piece = "Menuetto" @}
198 Pieces of music may be grouped into book parts using @code{\bookpart}
199 blocks. Book parts are separated by a page break, and can start with a
200 title, like the book itself, by specifying a @code{\header} block.
206 subtitle = "First part"
213 subtitle = "Second part"
220 @node Multiple output files from one input file
221 @subsection Multiple output files from one input file
223 If you want multiple output files from the same @file{.ly} file,
224 then you can add multiple @code{\book} blocks, where each
225 such \book block will result in a separate output file.
226 If you do not specify any @code{\book} block in the
227 input file, LilyPond will implicitly treat the whole
228 file as a single \book block, see
229 @ref{File structure}.
231 When producing multiple files from a single source file, Lilypond
232 ensures that none of the output files from any @code{\book} block
233 overwrites the output file produced by a preceding @code{\book} from
236 It does this by adding a suffix to the output name for each
237 @code{\book} which uses the default output file name derived from the
240 The default behaviour is to append a version-number suffix for each
241 name which may clash, so
246 \layout @{ @dots{} @}
250 \layout @{ @dots{} @}
254 \layout @{ @dots{} @}
258 in source file @file{eightminiatures.ly}
263 @file{eightminiatures.pdf},
265 @file{eightminiatures-1.pdf} and
267 @file{eightminiatures-2.pdf}.
270 @node Output file names
271 @subsection Output file names
273 @funindex \bookOutputSuffix
274 @funindex \bookOutputName
276 Lilypond provides facilities to allow you to control what file names
277 are used by the various back-ends when producing output files.
279 In the previous section, we saw how Lilypond prevents name-clashes when
280 producing several ouputs from a single source file. You also have the
281 ability to specify your own suffixes for each @code{\book} block, so
282 for example you can produce files called
283 @file{eightminiatures-Romanze.pdf}, @file{eightminiatures-Menuetto.pdf}
284 and @file{eightminiatures-Nocturne.pdf} by adding a
285 @code{\bookOutputSuffix} declaration inside each @code{\book} block.
289 \bookOutputSuffix "Romanze"
291 \layout @{ @dots{} @}
294 \bookOutputSuffix "Menuetto"
296 \layout @{ @dots{} @}
299 \bookOutputSuffix "Nocturne"
301 \layout @{ @dots{} @}
305 You can also specify a different output filename for @code{book} block,
306 by using @code{\bookOutputName} declarations
310 \bookOutputName "Romanze"
312 \layout @{ @dots{} @}
315 \bookOutputName "Menuetto"
317 \layout @{ @dots{} @}
320 \bookOutputName "Nocturne"
322 \layout @{ @dots{} @}
326 The file above will produce these output files:
332 @file{Menuetto.pdf} and
339 @subsection File structure
349 A @file{.ly} file may contain any number of toplevel expressions, where a
350 toplevel expression is one of the following:
354 An output definition, such as @code{\paper}, @code{\midi}, and
355 @code{\layout}. Such a definition at the toplevel changes the default
356 book-wide settings. If more than one such definition of
357 the same type is entered at the top level any definitions in the later
358 expressions have precedence.
361 A direct scheme expression, such as
362 @code{#(set-default-paper-size "a7" 'landscape)} or
363 @code{#(ly:set-option 'point-and-click #f)}.
366 A @code{\header} block. This sets the global header block. This
367 is the block containing the definitions for book-wide settings, like
368 composer, title, etc.
371 A @code{\score} block. This score will be collected with other
372 toplevel scores, and combined as a single @code{\book}.
373 This behavior can be changed by setting the variable
374 @code{toplevel-score-handler} at toplevel. The default handler is
375 defined in the init file @file{../scm/lily.scm}.
378 A @code{\book} block logically combines multiple movements
379 (i.e., multiple @code{\score} blocks) in one document. If there
380 are a number of @code{\score}s, one output file will be created
381 for each @code{\book} block, in which all corresponding movements
382 are concatenated. The only reason to explicitly specify
383 @code{\book} blocks in a @file{.ly} file is if you wish to create
384 multiple output files from a single input file. One exception is
385 within lilypond-book documents, where you explicitly have to add
386 a @code{\book} block if you want more than a single @code{\score}
387 or @code{\markup} in the same example. This behavior can be
388 changed by setting the variable @code{toplevel-book-handler} at
389 toplevel. The default handler is defined in the init file
390 @file{../scm/lily.scm}.
393 A @code{\bookpart} block. A book may be divided into several parts,
394 using @code{\bookpart} blocks, in order to ease the page breaking,
395 or to use different @code{\paper} settings in different parts.
398 A compound music expression, such as
403 This will add the piece in a @code{\score} and format it in a
404 single book together with all other toplevel @code{\score}s and music
405 expressions. In other words, a file containing only the above
406 music expression will be translated into
422 This behavior can be changed by setting the variable
423 @code{toplevel-music-handler} at toplevel. The default handler is
424 defined in the init file @file{../scm/lily.scm}.
427 A markup text, a verse for example
430 2. The first line verse two.
434 Markup texts are rendered above, between or below the scores or music
435 expressions, wherever they appear.
445 This can be used later on in the file by entering @code{\foo}. The
446 name of a variable should have alphabetic characters only; no
447 numbers, underscores or dashes.
451 The following example shows three things that may be entered at
456 % Don't justify the output
468 At any point in a file, any of the following lexical instructions can
472 @item @code{\version}
473 @item @code{\include}
474 @item @code{\sourcefilename}
475 @item @code{\sourcefileline}
477 A single-line comment, introduced by a leading @code{%} sign.
480 A multi-line comment delimited by @code{%@{ .. %@}}.
486 Whitespace between items in the input stream is generally ignored,
487 and may be freely omitted or extended to enhance readability.
488 However, whitespace should always be used in the following
489 circumstances to avoid errors:
492 @item Around every opening and closing curly bracket.
493 @item After every command or variable, i.e. every item that
494 begins with a @code{\} sign.
495 @item After every item that is to be interpreted as a Scheme
496 expression, i.e. every item that begins with a @code{#}@tie{}sign.
497 @item To separate all elements of a Scheme expression.
498 @item In @code{lyricmode} to separate all the terms in both
499 @code{\override} and @code{\set} commands. In particular, spaces
500 must be used around the dot and the equals sign in commands like
501 @code{\override Score . LyricText #'font-size = #5} and before and
502 after the entire command.
509 @rlearning{How LilyPond input files work}.
512 @node Titles and headers
513 @section Titles and headers
515 Almost all printed music includes a title and the composer's name;
516 some pieces include a lot more information.
519 * Creating titles headers and footers::
520 * Custom headers footers and titles::
521 * Reference to page numbers::
522 * Table of contents::
526 @node Creating titles headers and footers
527 @subsection Creating titles headers and footers
530 * Title blocks explained::
531 * Default layout of book and score title blocks::
532 * Default layout of headers and footers::
536 @node Title blocks explained
537 @unnumberedsubsubsec Title blocks explained
539 @c TODO: figure out how \bookpart titles work
541 There are two types of title blocks: the main title block that appears
542 above of the first @code{\score} of a book, and individual title
543 blocks that appear within each @code{\score} block. Text fields for
544 both types are entered using a @code{\header} block.
546 If the book only has a single score, the @code{\header} block may be
547 placed inside or outside of the @code{\score} block.
549 The default behavior, when the @code{\header} has been defined inside
550 the @code{\score} block, is to print only the @code{piece} and
553 @lilypond[papersize=a5,quote,verbatim,noragged-right]
557 title = "title" % not printed
564 @funindex print-all-headers
566 You may change this behavior (and print all the headers when defining
567 @code{\header} inside @code{\score}) by using
571 print-all-headers = ##t
575 @warning{Remember when adding a @bs{}@code{header} block inside a
576 @bs{}@code{score} block, that the music expression must come before the
577 @bs{}@code{header} block.}
579 @lilypond[papersize=a5,quote,verbatim,noragged-right]
582 composer = "J. S. Bach."
586 \new Staff \relative g, {
589 \repeat unfold 2 { g16( d' b') a b d, b' d, } |
590 \repeat unfold 2 { g,16( e' c') b c e, c' e, } |
598 \new Staff \relative b {
602 <g, d' b'~>4 b'16 a( g fis) g( d e fis) g( a b c) |
603 d16( b g fis) g( e d c) b(c d e) fis( g a b) |
611 Text fields from the main title block of a book can be displayed in all
612 @code{\score} blocks, or manually suppressed:
614 @lilypond[papersize=a5,quote,verbatim,noragged-right]
617 print-all-headers = ##t
620 title = "DAS WOHLTEMPERIRTE CLAVIER"
622 % Do not display the tagline for this book
625 \markup { \vspace #1 }
629 \new Staff { \clef "bass" s1 }
632 title = "PRAELUDIUM I"
634 % Do not display the subtitle for this score
641 \new Staff { \clef "bass" s1 }
645 subsubtitle = "A 4 VOCI"
647 % Do not display the subtitle for this score
656 @ref{File structure},
657 @ref{Custom layout for title blocks}.
660 @node Default layout of book and score title blocks
661 @unnumberedsubsubsec Default layout of book and score title blocks
663 The layout and formatting of title blocks are controlled by two
664 @code{\paper} variables; @code{bookTitleMarkup} for the main
665 @code{\header} title block and @code{scoreTitleMarkup} for individual
666 @code{\header} blocks within a @code{\score}.
668 @lilypond[papersize=a6,quote,verbatim,noragged-right]
670 % The following fields are centered
671 dedication = "Dedication"
673 subtitle = "Subtitle"
674 subsubtitle = "Subsubtitle"
675 instrument = "Instrument"
677 % The following fields are left-aligned on the left side
681 % The following fields are right-aligned on the right side
682 composer = "Composer"
683 arranger = "Arranger"
689 % The following fields are placed at opposite ends of the same line
696 @c Is the bit about \null markups true? -mp
698 Text fields left unset in a @code{\header} block are replaced with
699 @code{\null} markups so that the space is not wasted.
701 The default settings for @code{scoreTitleMarkup} place the @code{piece}
702 and @code{opus} text fields at opposite ends of the same line.
706 Use the @code{breakbefore} variable inside a @code{\header} block
707 that is itself in a @code{\score} block, to make the top-level
708 @code{\header} block titles appear on the first page on their own, with
709 the music (defined in the @code{\score} block) starting on the next.
711 @lilypond[papersize=a8landscape,verbatim,noragged-right]
714 title = "This is my Title"
715 subtitle = "This is my Subtitle"
716 copyright = "This is the bottom of the first page"
719 \repeat unfold 4 { e'' e'' e'' e'' }
721 piece = "This is the Music"
730 @rlearning{How LilyPond input files work},
733 @ref{File structure}.
736 @file{ly/titling-init.ly}.
738 @node Default layout of headers and footers
739 @unnumberedsubsubsec Default layout of headers and footers
741 @emph{Headers} and @emph{footers} are lines of text appearing at
742 the top and bottom of pages, separate from the main text of a book.
743 They are controlled by the following @code{\paper} variables:
746 @item @code{oddHeaderMarkup}
747 @item @code{evenHeaderMarkup}
748 @item @code{oddFooterMarkup}
749 @item @code{evenFooterMarkup}
752 These markup variables can only access text fields from top-level
753 @code{\header} blocks (which apply to all scores in the book) and are
754 defined in @file{ly/titling-init.ly}. By default:
759 page numbers are automatically placed on the top far left (if even) or
760 top far right (if odd), starting from the second page.
763 the @code{instrument} text field is placed in the center of every
764 page, starting from the second page.
767 the @code{copyright} text is centered on the bottom of the first page.
770 the @code{tagline} is centered on the bottom of the last page, and below
771 the @code{copyright} text if there is only a single page.
775 @lilypond[papersize=a8landscape]
785 The default tagline can be changed by adding a @code{tagline} in the
786 top-level @code{\header} block.
788 @lilypond[papersize=a8landscape,verbatim]
791 tagline = "... music notation for Everyone"
801 To remove the @code{tagline} set the value to @code{##f}.
804 @node Custom headers footers and titles
805 @subsection Custom headers footers and titles
807 @c TODO: somewhere put a link to header spacing info
808 @c (you'll have to explain it more in NR 4).
811 * Custom text formatting for title blocks::
812 * Custom layout for title blocks::
813 * Custom layout for headers and footers::
817 @node Custom text formatting for title blocks
818 @unnumberedsubsubsec Custom text formatting for title blocks
820 Standard @code{\markup} commands can be used to customize any header,
821 footer and title text within the @code{\header} block.
823 @lilypond[quote,verbatim,noragged-right]
827 piece = \markup { \fontsize #4 \bold "PRAELUDIUM I" }
828 opus = \markup { \italic "(Excerpt)" }
835 @ref{Formatting text}.
838 @node Custom layout for title blocks
839 @unnumberedsubsubsec Custom layout for title blocks
841 @code{\markup} commands in the @code{\header} block are useful for
842 simple text formatting, but they do not allow precise control over the
843 placement of titles. To customize the placement of the text fields,
844 use either or both of the following @code{\paper} variables:
847 @item @code{bookTitleMarkup}
848 @item @code{scoreTitleMarkup}
851 These markup variables are discussed in
852 @ref{Default layout of book and score title blocks}.
854 The default settings for @code{scoreTitleMarkup} as defined in
855 @file{ly/titling-init.ly} are:
858 scoreTitleMarkup = \markup @{ \column @{
859 \on-the-fly #print-all-headers @{ \bookTitleMarkup \hspace #1 @}
861 \fromproperty #'header:piece
862 \fromproperty #'header:opus
868 This places the @code{piece} and @code{opus} text fields at opposite
869 ends of the same line:
871 @lilypond[quote,verbatim,noragged-right]
875 piece = "PRAELUDIUM I"
881 This example redefines @code{scoreTitleMarkup} so that the @code{piece}
882 text field is centered and in a large, bold font.
884 @lilypond[papersize=a5,quote,verbatim,noragged-right]
888 scoreTitleMarkup = \markup {
891 \fontsize #4 \bold \fromproperty #'header:piece
892 \fromproperty #'header:opus
896 \header { tagline = ##f }
900 piece = "PRAELUDIUM I"
907 Text fields normally reserved for the main title block can be included
908 in individual score title blocks with the @code{print-all-headers}
909 placed inside the @code{\paper} block. A disadvantage of using this
910 method is that the text fields that are intended specifically for the
911 top-level @code{\header} block need to be manually suppressed in every
912 @code{\score} block. See @ref{Title blocks explained}.
914 To avoid this, add the desired text field to the @code{scoreTitleMarkup}
915 definition. In the following example, the @code{composer} text field
916 (normally associated with @code{bookTitleMarkup}) is added to
917 @code{scoreTitleMarkup}, allowing each score to list a different
920 @lilypond[papersize=a5,quote,verbatim,noragged-right]
924 scoreTitleMarkup = \markup {
927 \fontsize #4 \bold \fromproperty #'header:piece
928 \fromproperty #'header:composer
932 \header { tagline = ##f }
937 composer = "Christian Petzold"
944 composer = "François Couperin"
950 It is also possible to create your own custom text fields, and refer to
951 them in the markup definition.
953 @lilypond[papersize=a5,quote,verbatim,noragged-right]
957 scoreTitleMarkup = \markup {
960 \override #`(direction . ,UP) {
962 \center-align \fontsize #-1 \bold
963 \fromproperty #'header:mycustomtext %% User-defined field
964 \center-align \fontsize #4 \bold
965 \fromproperty #'header:piece
968 \fromproperty #'header:opus
972 \header { tagline = ##f }
977 mycustomtext = "A 4 VOCI" %% User-defined field
986 @ref{Title blocks explained}.
989 @node Custom layout for headers and footers
990 @unnumberedsubsubsec Custom layout for headers and footers
992 @c can make-header and make-footer be removed from
993 @c paper-defaults-init.ly? -mp
995 @code{\markup} commands in the @code{\header} block are useful for
996 simple text formatting, but they do not allow precise control over the
997 placement of headers and footers. To customize the placement of
998 the text fields, use either or both of the following @code{\paper}
1002 @item @code{oddHeaderMarkup}
1003 @item @code{evenHeaderMarkup}
1004 @item @code{oddFooterMarkup}
1005 @item @code{evenFooterMarkup}
1008 The following example centers page numbers at the bottom of every
1009 page. First, the default settings for @code{oddHeaderMarkup} and
1010 @code{evenHeaderMarkup} are removed by defining each as a @emph{null}
1011 markup. Then, @code{oddFooterMarkup} is redefined with the page
1012 number centered. Finally, @code{evenFooterMarkup} is given the
1013 same layout by defining it as @code{\oddFooterMarkup}:
1015 @lilypond[papersize=a8,quote,verbatim,noragged-right]
1018 print-page-number = ##t
1019 print-first-page-number = ##t
1020 oddHeaderMarkup = \markup \null
1021 evenHeaderMarkup = \markup \null
1022 oddFooterMarkup = \markup {
1024 \on-the-fly #print-page-number-check-first
1025 \fromproperty #'page:page-number-string
1028 evenFooterMarkup = \oddFooterMarkup
1031 \new Staff { s1 \break s1 \break s1 }
1038 @ref{Title blocks explained},
1039 @ref{Default layout of book and score title blocks}.
1042 @node Reference to page numbers
1043 @subsection Reference to page numbers
1045 A particular place of a score can be marked using the @code{\label}
1046 command, either at top-level or inside music. This label can then be
1047 referred to in a markup, to get the number of the page where the marked
1048 point is placed, using the @code{\page-ref} markup command.
1051 \header { tagline = ##f }
1057 \pageBreak \mark A \label #'markA
1061 \markup { The first score begins on page \page-ref #'firstScore "0" "?" }
1062 \markup { Mark A is on page \page-ref #'markA "0" "?" }
1066 The @code{\page-ref} markup command takes three arguments:
1068 @item the label, a scheme symbol, eg. @code{#'firstScore};
1069 @item a markup that will be used as a gauge to estimate the dimensions
1071 @item a markup that will be used in place of the page number if the label
1075 The reason why a gauge is needed is that, at the time markups are
1076 interpreted, the page breaking has not yet occurred, so the page numbers
1077 are not yet known. To work around this issue, the actual markup
1078 interpretation is delayed to a later time; however, the dimensions of
1079 the markup have to be known before, so a gauge is used to decide these
1080 dimensions. If the book has between 10 and 99 pages, it may be "00",
1081 ie. a two digit number.
1092 @node Table of contents
1093 @subsection Table of contents
1094 A table of contents is included using the @code{\markuplines \table-of-contents}
1095 command. The elements which should appear in the table of contents are
1096 entered with the @code{\tocItem} command, which may be used either at
1097 top-level, or inside a music expression.
1100 \markuplines \table-of-contents
1103 \tocItem \markup "First score"
1107 \tocItem \markup "Some particular point in the first score"
1112 \tocItem \markup "Second score"
1120 The markups which are used to format the table of contents are defined
1121 in the @code{\paper} block. The default ones are @code{tocTitleMarkup},
1122 for formatting the title of the table, and @code{tocItemMarkup}, for
1123 formatting the toc elements, composed of the element title and page
1124 number. These variables may be changed by the user:
1128 %% Translate the toc title into French:
1129 tocTitleMarkup = \markup \huge \column {
1130 \fill-line { \null "Table des matières" \null }
1133 %% use larger font size
1134 tocItemMarkup = \markup \large \fill-line {
1135 \fromproperty #'toc:text \fromproperty #'toc:page
1140 Note how the toc element text and page number are referred to in
1141 the @code{tocItemMarkup} definition.
1143 New commands and markups may also be defined to build more elaborated
1146 @item first, define a new markup variable in the @code{\paper} block
1147 @item then, define a music function which aims at adding a toc element
1148 using this markup paper variable.
1151 In the following example, a new style is defined for entering act names
1152 in the table of contents of an opera:
1156 tocActMarkup = \markup \large \column {
1158 \fill-line { \null \italic \fromproperty #'toc:text \null }
1164 #(define-music-function (parser location text) (markup?)
1165 (add-toc-item! 'tocActMarkup text))
1168 @lilypond[line-width=11.0\cm]
1169 \header { tagline = ##f }
1171 tocActMarkup = \markup \large \column {
1173 \fill-line { \null \italic \fromproperty #'toc:text \null }
1179 #(define-music-function (parser location text) (markup?)
1180 (add-toc-item! 'tocActMarkup text))
1183 \markuplines \table-of-contents
1184 \tocAct \markup { Atto Primo }
1185 \tocItem \markup { Coro. Viva il nostro Alcide }
1186 \tocItem \markup { Cesare. Presti omai l'Egizzia terra }
1187 \tocAct \markup { Atto Secondo }
1188 \tocItem \markup { Sinfonia }
1189 \tocItem \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
1194 Dots can be added to fill the line between an item and its page number:
1196 @lilypond[verbatim,quote]
1197 \header { tagline = ##f }
1199 tocItemMarkup = \tocItemWithDotsMarkup
1203 \markuplines \table-of-contents
1204 \tocItem \markup { Allegro }
1205 \tocItem \markup { Largo }
1212 Init files: @file{../ly/toc-init.ly}.
1216 @funindex \table-of-contents
1217 @code{\table-of-contents},
1223 @node Working with input files
1224 @section Working with input files
1227 * Including LilyPond files::
1228 * Different editions from one source::
1233 @node Including LilyPond files
1234 @subsection Including LilyPond files
1237 @cindex including files
1239 A large project may be split up into separate files. To refer to
1243 \include "otherfile.ly"
1246 The line @code{\include "otherfile.ly"} is equivalent to pasting the
1247 contents of @file{otherfile.ly} into the current file at the place
1248 where the @code{\include} appears. For example, in a large
1249 project you might write separate files for each instrument part
1250 and create a @qq{full score} file which brings together the
1251 individual instrument files. Normally the included file will
1252 define a number of variables which then become available
1253 for use in the full score file. Tagged sections can be
1254 marked in included files to assist in making them usable in
1255 different places in a score, see @ref{Different editions from
1258 Files in the current working directory may be referenced by
1259 specifying just the file name after the @code{\include} command.
1260 Files in other locations may be included by giving either a full
1261 path reference or a relative path reference (but use the UNIX
1262 forward slash, /, rather than the DOS/Windows back slash, \, as the
1263 directory separator.) For example, if @file{stuff.ly} is located
1264 one directory higher than the current working directory, use
1267 \include "../stuff.ly"
1271 or if the included orchestral parts files are all located in a
1272 subdirectory called @file{parts} within the current directory, use
1275 \include "parts/VI.ly"
1276 \include "parts/VII.ly"
1280 Files which are to be included can also contain @code{\include}
1281 statements of their own. By default, these second-level
1282 @code{\include} statements are not interpreted until they have
1283 been brought into the main file, so the file names they specify
1284 must all be relative to the directory containing the main file,
1285 not the directory containing the included file. However,
1286 this behavior can be changed by passing the option
1287 @option{-drelative-includes} option at the command line
1288 (or by adding @code{#(ly:set-option 'relative-includes #t)}
1289 at the top of the main input file). With @code{relative-includes}
1290 set, the path for each @code{\include} command will be taken
1291 relative to the file containing that command. This behavior is
1292 recommended and it will become the default behavior in a future
1293 version of lilypond.
1295 Files can also be included from a directory in a search path
1296 specified as an option when invoking LilyPond from the command
1297 line. The included files are then specified using just their
1298 file name. For example, to compile @file{main.ly} which includes
1299 files located in a subdirectory called @file{parts} by this method,
1300 cd to the directory containing @file{main.ly} and enter
1303 lilypond --include=parts main.ly
1306 and in main.ly write
1314 Files which are to be included in many scores may be placed in
1315 the LilyPond directory @file{../ly}. (The location of this
1316 directory is installation-dependent - see
1317 @rlearning{Other sources of information}). These files can then
1318 be included simply by naming them on an @code{\include} statement.
1319 This is how the language-dependent files like @file{english.ly} are
1322 LilyPond includes a number of files by default when you start
1323 the program. These includes are not apparent to the user, but the
1324 files may be identified by running @code{lilypond --verbose} from
1325 the command line. This will display a list of paths and files that
1326 LilyPond uses, along with much other information. Alternatively,
1327 the more important of these files are discussed in
1328 @rlearning{Other sources of information}. These files may be
1329 edited, but changes to them will be lost on installing a new
1330 version of LilyPond.
1332 Some simple examples of using @code{\include} are shown in
1333 @rlearning{Scores and parts}.
1338 @rlearning{Other sources of information},
1339 @rlearning{Scores and parts}.
1344 If an included file is given a name which is the same as one in
1345 LilyPond's installation files, LilyPond's file from the
1346 installation files takes precedence.
1350 @node Different editions from one source
1351 @subsection Different editions from one source
1353 Several mechanisms are available to facilitate the generation
1354 of different versions of a score from the same music source.
1355 Variables are perhaps most useful for combining lengthy sections
1356 of music and/or annotation in various ways, while tags are more
1357 useful for selecting one from several alternative shorter sections
1358 of music. Whichever method is used, separating the notation from
1359 the structure of the score will make it easier to change the
1360 structure while leaving the notation untouched.
1365 * Using global settings::
1368 @node Using variables
1369 @unnumberedsubsubsec Using variables
1371 @cindex variables, use of
1373 If sections of the music are defined in variables they can be
1374 reused in different parts of the score, see @rlearning{Organizing
1375 pieces with variables}. For example, an @notation{a cappella}
1376 vocal score frequently includes a piano reduction of the parts
1377 for rehearsal purposes which is identical to the vocal music, so
1378 the music need be entered only once. Music from two variables
1379 may be combined on one staff, see @ref{Automatic part combining}.
1382 @lilypond[verbatim,quote]
1383 sopranoMusic = \relative c'' { a4 b c b8( a) }
1384 altoMusic = \relative g' { e4 e e f }
1385 tenorMusic = \relative c' { c4 b e d8( c) }
1386 bassMusic = \relative c' { a4 gis a d, }
1387 allLyrics = \lyricmode {King of glo -- ry }
1389 \new Staff = "Soprano" \sopranoMusic
1390 \new Lyrics \allLyrics
1391 \new Staff = "Alto" \altoMusic
1392 \new Lyrics \allLyrics
1393 \new Staff = "Tenor" {
1397 \new Lyrics \allLyrics
1398 \new Staff = "Bass" {
1402 \new Lyrics \allLyrics
1405 \set Staff.printPartCombineTexts = ##f
1411 \set Staff.printPartCombineTexts = ##f
1421 Separate scores showing just the vocal parts or just the piano
1422 part can be produced by changing just the structural statements,
1423 leaving the musical notation unchanged.
1425 For lengthy scores, the variable definitions may be placed in
1426 separate files which are then included, see @ref{Including
1430 @unnumberedsubsubsec Using tags
1433 @funindex \keepWithTag
1434 @funindex \removeWithTag
1436 @cindex keep tagged music
1437 @cindex remove tagged music
1439 The @code{\tag #'@var{partA}} command marks a music expression
1440 with the name @var{partA}.
1441 Expressions tagged in this way can be selected or filtered out by
1442 name later, using either @code{\keepWithTag #'@var{name}} or
1443 @code{\removeWithTag #'@var{name}}. The result of applying these filters
1444 to tagged music is as follows:
1445 @multitable @columnfractions .5 .5
1449 Tagged music preceded by @code{\keepWithTag #'@var{name}}
1450 @tab Untagged music and music tagged with @var{name} is included;
1451 music tagged with any other tag name is excluded.
1453 Tagged music preceded by @code{\removeWithTag #'@var{name}}
1454 @tab Untagged music and music tagged with any tag name other than
1455 @var{name} is included; music tagged with @var{name} is
1458 Tagged music not preceded by either @code{\keepWithTag} or
1459 @code{\removeWithTag}
1460 @tab All tagged and untagged music is included.
1463 The arguments of the @code{\tag}, @code{\keepWithTag} and
1464 @code{\removeWithTag} commands should be a symbol
1465 (such as @code{#'score} or @code{#'part}), followed
1466 by a music expression.
1468 In the following example, we see two versions of a piece of music,
1469 one showing trills with the usual notation, and one with trills
1470 explicitly expanded:
1472 @lilypond[verbatim,quote]
1473 music = \relative g' {
1475 \tag #'trills { d8.\trill }
1476 \tag #'expand { \repeat unfold 3 { e32 d } }
1481 \keepWithTag #'trills \music
1484 \keepWithTag #'expand \music
1489 Alternatively, it is sometimes easier to exclude sections of music:
1491 @lilypond[verbatim,quote]
1492 music = \relative g' {
1494 \tag #'trills { d8.\trill }
1495 \tag #'expand {\repeat unfold 3 { e32 d } }
1500 \removeWithTag #'expand
1504 \removeWithTag #'trills
1509 Tagged filtering can be applied to articulations, texts, etc. by
1513 -\tag #'@var{your-tag}
1516 to an articulation. For example, this would define a note with a
1517 conditional fingering indication and a note with a conditional
1522 c1-\tag #'warn ^"Watch!"
1525 Multiple tags may be placed on expressions with multiple
1526 @code{\tag} entries:
1528 @lilypond[quote,verbatim]
1529 music = \relative c'' {
1530 \tag #'a \tag #'both { a4 a a a }
1531 \tag #'b \tag #'both { b4 b b b }
1534 \keepWithTag #'a \music
1535 \keepWithTag #'b \music
1536 \keepWithTag #'both \music
1540 Multiple @code{\removeWithTag} filters may be applied to a single
1541 music expression to remove several differently named tagged sections:
1543 @lilypond[verbatim,quote]
1544 music = \relative c'' {
1545 \tag #'A { a4 a a a }
1546 \tag #'B { b4 b b b }
1547 \tag #'C { c4 c c c }
1548 \tag #'D { d4 d d d }
1557 Two or more @code{\keepWithTag} filters applied to a single music
1558 expression will cause @emph{all} tagged sections to be removed, as
1559 the first filter will remove all tagged sections except the one
1560 named, and the second filter will remove even that tagged section.
1565 @rlearning{Organizing pieces with variables}.
1568 @ref{Automatic part combining},
1569 @ref{Including LilyPond files}.
1573 @c This warning is more general than this placement implies.
1574 @c Rests are not merged whether or not they come from tagged sections.
1575 @c Should be deleted? -td
1579 Multiple rests are not merged if you create a score with more
1580 than one tagged section at the same place.
1584 @node Using global settings
1585 @unnumberedsubsubsec Using global settings
1587 @cindex include-settings
1589 Global settings can be included from a separate file:
1592 lilypond -dinclude-settings=MY_SETTINGS.ly MY_SCORE.ly
1595 Groups of settings such as page size, font or type face can be stored
1596 in separate files. This allows different editions from the same score
1597 as well as standard settings to be applied to many scores, simply by
1598 specifying the proper settings file.
1600 This technique also works well with the use of style sheets, as
1601 discussed in @rlearning{Style sheets}.
1605 @rlearning{Organizing pieces with variables},
1606 @rlearning{Style sheets}.
1609 @ref{Including LilyPond files}.
1612 @subsection Text encoding
1616 @cindex non-ASCII characters
1618 LilyPond uses the character repertoire defined by the Unicode
1619 consortium and ISO/IEC 10646. This defines a unique name and
1620 code point for the character sets used in virtually all modern
1621 languages and many others too. Unicode can be implemented using
1622 several different encodings. LilyPond uses the UTF-8 encoding
1623 (UTF stands for Unicode Transformation Format) which represents
1624 all common Latin characters in one byte, and represents other
1625 characters using a variable length format of up to four bytes.
1627 The actual appearance of the characters is determined by the
1628 glyphs defined in the particular fonts available - a font defines
1629 the mapping of a subset of the Unicode code points to glyphs.
1630 LilyPond uses the Pango library to layout and render multi-lingual
1633 LilyPond does not perform any input-encoding conversions. This
1634 means that any text, be it title, lyric text, or musical
1635 instruction containing non-ASCII characters, must be encoded in
1636 UTF-8. The easiest way to enter such text is by using a
1637 Unicode-aware editor and saving the file with UTF-8 encoding. Most
1638 popular modern editors have UTF-8 support, for example, vim, Emacs,
1639 jEdit, and GEdit do. All MS Windows systems later than NT use
1640 Unicode as their native character encoding, so even Notepad can
1641 edit and save a file in UTF-8 format. A more functional
1642 alternative for Windows is BabelPad.
1644 If a LilyPond input file containing a non-ASCII character is not
1645 saved in UTF-8 format the error message
1648 FT_Get_Glyph_Name () error: invalid argument
1653 Here is an example showing Cyrillic, Hebrew and Portuguese
1657 %c No verbatim here as the code does not display correctly in PDF
1659 bulgarian = \lyricmode {
1660 Жълтата дюля беше щастлива, че пухът, който цъфна, замръзна като гьон.
1664 hebrew = \lyricmode {
1665 זה כיף סתם לשמוע איך תנצח קרפד עץ טוב בגן.
1669 portuguese = \lyricmode {
1670 à vo -- cê uma can -- ção legal
1676 \addlyrics { \bulgarian }
1677 \addlyrics { \hebrew }
1678 \addlyrics { \portuguese }
1681 To enter a single character for which the Unicode code point is
1682 known but which is not available in the editor being used, use
1683 either @code{\char ##xhhhh} or @code{\char #dddd} within a
1684 @code{\markup} block, where @code{hhhh} is the hexadecimal code for
1685 the character required and @code{dddd} is the corresponding decimal
1686 value. Leading zeroes may be omitted, but it is usual to specify
1687 all four characters in the hexadecimal representation. (Note that
1688 the UTF-8 encoding of the code point should @emph{not} be used
1689 after @code{\char}, as UTF-8 encodings contain extra bits indicating
1690 the number of octets.) Unicode code charts and a character name
1691 index giving the code point in hexadecimal for any character can be
1692 found on the Unicode Consortium website,
1693 @uref{http://www.unicode.org/}.
1695 For example, @code{\char ##x03BE} and @code{\char #958} would both
1696 enter the Unicode U+03BE character, which has the Unicode name
1697 @qq{Greek Small Letter Xi}.
1699 Any Unicode code point may be entered in this way and if all special
1700 characters are entered in this format it is not necessary to save
1701 the input file in UTF-8 format. Of course, a font containing all
1702 such encoded characters must be installed and available to LilyPond.
1704 The following example shows Unicode hexadecimal values being entered
1705 in four places -- in a rehearsal mark, as articulation text, in
1706 lyrics and as stand-alone text below the score:
1708 @lilypond[quote,verbatim]
1711 c1 \mark \markup { \char ##x03EE }
1712 c1_\markup { \tiny { \char ##x03B1 " to " \char ##x03C9 } }
1714 \addlyrics { O \markup { \concat { Ph \char ##x0153 be! } } }
1716 \markup { "Copyright 2008--2011" \char ##x00A9 }
1719 @cindex copyright sign
1721 To enter the copyright sign in the copyright notice use:
1725 copyright = \markup @{ \char ##x00A9 "2008" @}
1731 @node Controlling output
1732 @section Controlling output
1735 * Extracting fragments of music::
1736 * Skipping corrected music::
1737 * Alternative output formats::
1738 * Replacing the notation font::
1741 @node Extracting fragments of music
1742 @subsection Extracting fragments of music
1744 It is possible to quote small fragments of a large score directly from
1745 the output. This can be compared to clipping a piece of a paper score
1748 This is done by defining the measures that need to be cut out
1749 separately. For example, including the following definition
1757 (make-rhythmic-location 5 1 2)
1758 (make-rhythmic-location 7 3 4)))
1763 will extract a fragment starting halfway the fifth measure, ending in
1764 the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note
1765 in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7.
1767 More clip regions can be defined by adding more pairs of
1768 rhythmic-locations to the list.
1770 In order to use this feature, LilyPond must be invoked with
1771 @option{-dclip-systems}. The clips are output as EPS files, and are
1772 converted to PDF and PNG if these formats are switched on as well.
1774 For more information on output formats, see @rprogram{Invoking lilypond}.
1776 @node Skipping corrected music
1777 @subsection Skipping corrected music
1780 @funindex skipTypesetting
1781 @funindex showFirstLength
1782 @funindex showLastLength
1784 When entering or copying music, usually only the music near the end (where
1786 are adding notes) is interesting to view and correct. To speed up
1787 this correction process, it is possible to skip typesetting of all but
1788 the last few measures. This is achieved by putting
1791 showLastLength = R1*5
1796 in your source file. This will render only the last 5 measures
1797 (assuming 4/4 time signature) of every @code{\score} in the input
1798 file. For longer pieces, rendering only a small part is often an order
1799 of magnitude quicker than rendering it completely. When working on the
1800 beginning of a score you have already typeset (e.g. to add a new part),
1801 the @code{showFirstLength} property may be useful as well.
1803 Skipping parts of a score can be controlled in a more fine-grained
1804 fashion with the property @code{Score.skipTypesetting}. When it is
1805 set, no typesetting is performed at all.
1807 This property is also used to control output to the MIDI file. Note that
1808 it skips all events, including tempo and instrument changes. You have
1811 @lilypond[quote,relative=2,ragged-right,verbatim]
1813 \set Score.skipTypesetting = ##t
1815 \set Score.skipTypesetting = ##f
1819 In polyphonic music, @code{Score.skipTypesetting} will affect all
1820 voices and staves, saving even more time.
1822 @node Alternative output formats
1823 @subsection Alternative output formats
1825 @cindex scalable vector graphics output
1827 @cindex encapsulated postscript output
1830 The default output formats for the printed score are Portable
1831 Document Format (PDF) and PostScript (PS). Scalable Vector
1832 Graphics (SVG), Encapsulated PostScript (EPS) and Portable
1833 Network Graphics (PNG) output formats are also available through
1834 command line options, see @rprogram{Command line options for
1838 @node Replacing the notation font
1839 @subsection Replacing the notation font
1841 Gonville is an alternative to the Feta font used in LilyPond and can
1844 @uref{http://www.chiark.greenend.org.uk/~sgtatham/gonville/ ,http://www.chiark.greenend.org.uk/~sgtatham/gonville/}
1847 Here are a few sample bars of music set in Gonville:
1849 @c NOTE: these images are a bit big, but that's important
1850 @c for the font comparison. -gp
1851 @sourceimage{Gonville_after,,,}
1853 Here are a few sample bars of music set in LilyPond's Feta font:
1855 @sourceimage{Gonville_before,,,}
1857 @subsubheading Installation Instructions for MacOS
1859 Download and extract the zip file. Copy the @code{lilyfonts}
1860 directory to @file{@var{SHARE_DIR}/lilypond/current}; for more
1861 information, see @rlearning{Other sources of information}. Rename the
1862 existing @code{fonts} directory to @code{fonts_orig} and the
1863 @code{lilyfonts} directory to @code{fonts}. To revert back to Feta,
1864 reverse the process.
1867 Learning Manual: @rlearning{Other sources of information}.
1870 Gonville cannot be used to typeset @q{Ancient Music} notation and it is
1871 likely newer glyphs in later releases of LilyPond may not exist in the
1872 Gonville font family. Please refer to the author's website for more
1873 information on these and other specifics, including licensing of
1878 @section MIDI output
1883 MIDI (Musical Instrument Digital Interface) is a standard for
1884 connecting and controlling digital instruments. A MIDI file is a
1885 series of notes in a number of tracks. It is not an actual
1886 sound file; you need special software to translate between the
1887 series of notes and actual sounds.
1889 Pieces of music can be converted to MIDI files, so you can listen to
1890 what was entered. This is convenient for checking the music; octaves
1891 that are off or accidentals that were mistyped stand out very much
1892 when listening to the MIDI output.
1894 Standard MIDI oputput is somewhat crude; optionally, an enhanced and
1895 more realistic MIDI output is available by means of
1896 @ref{The Articulate script}.
1899 The midi output allocates a channel for each staff, and one for global
1900 settings. Therefore the midi file should not have more than 15 staves
1901 (or 14 if you do not use drums). Other staves will remain silent.
1904 * Creating MIDI files::
1906 * What goes into the MIDI output?::
1908 * Controlling MIDI dynamics::
1909 * Percussion in MIDI::
1910 * The Articulate script::
1913 @node Creating MIDI files
1914 @subsection Creating MIDI files
1916 To create a MIDI output file from a LilyPond input file, add a
1917 @code{\midi} block to a score, for example,
1926 If there is a @code{\midi} block in a @code{\score} with no
1927 @code{\layout} block, only MIDI output will be produced. When
1928 notation is needed too, a @code{\layout} block must also be
1939 Pitches, rhythms, ties, dynamics, and tempo changes are interpreted
1940 and translated correctly to the MIDI output. Dynamic marks,
1941 crescendi and decrescendi translate into MIDI volume levels.
1942 Dynamic marks translate to a fixed fraction of the available MIDI
1943 volume range. Crescendi and decrescendi make the volume vary
1944 linearly between their two extremes. The effect of dynamic markings
1945 on the MIDI output can be removed completely, see @ref{MIDI block}.
1947 The initial tempo and later tempo changes can be specified
1948 with the @code{\tempo} command within the music notation. These
1949 are reflected in tempo changes in the MIDI output. This command
1950 will normally result in the metronome mark being printed, but this
1951 can be suppressed, see @ref{Metronome marks}. An alternative way
1952 of specifying the initial or overall MIDI tempo is described below,
1953 see @ref{MIDI block}.
1955 Due to some limitations on Windows, the default extension for
1956 MIDI files on Windows is @code{.mid}. Other operating systems still
1957 use the extension @code{.midi}. If a different extension is preferred,
1958 insert the following line at the top-level of the input file,
1959 before the start of any @code{\book}, @code{\bookpart} or @code{\score} blocks:
1962 #(ly:set-option 'midi-extension "midi")
1965 The line above will set the default extension for MIDI files to
1968 Alternatively, this option can also be supplied on the command line:
1971 lilypond … -dmidi-extension=midi lilyFile.ly
1975 @unnumberedsubsubsec Instrument names
1977 @cindex instrument names
1978 @funindex Staff.midiInstrument
1980 The MIDI instrument to be used is specified by setting the
1981 @code{Staff.midiInstrument} property to the instrument name.
1982 The name should be chosen from the list in @ref{MIDI instruments}.
1986 \set Staff.midiInstrument = #"glockenspiel"
1992 \new Staff \with @{midiInstrument = #"cello"@} @{
1997 If the selected instrument does not exactly match an instrument from
1998 the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
2004 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
2005 {changing-midi-output-to-one-channel-per-voice.ly}
2009 @c In 2.11 the following no longer seems to be a problem -td
2011 Unterminated (de)crescendos will not render properly in the midi file,
2012 resulting in silent passages of music. The workaround is to explicitly
2013 terminate the (de)crescendo. For example,
2020 will not work properly but
2023 @{ a4\< b c d\!\f @}
2030 Changes in the MIDI volume take place only on starting a note, so
2031 crescendi and decrescendi cannot affect the volume of a
2034 Not all midi players correctly handle tempo changes in the midi
2035 output. Players that are known to work include MS Windows Media
2036 Player and @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
2039 @subsection MIDI block
2042 A @code{\midi} block must appear within a score block if MIDI output
2043 is required. It is analogous to the layout block, but somewhat
2044 simpler. Often, the @code{\midi} block is left empty, but it
2045 can contain context rearrangements, new context definitions or code
2046 to set the values of properties. For example, the following will
2047 set the initial tempo exported to a MIDI file without causing a tempo
2048 indication to be printed:
2056 tempoWholesPerMinute = #(ly:make-moment 72 4)
2062 In this example the tempo is set to 72 quarter note
2063 beats per minute. This kind of tempo specification cannot take
2064 a dotted note length as an argument. If one is required, break
2065 the dotted note into smaller units. For example, a tempo of 90
2066 dotted quarter notes per minute can be specified as 270 eighth
2070 tempoWholesPerMinute = #(ly:make-moment 270 8)
2073 @cindex MIDI context definitions
2075 Context definitions follow precisely the same syntax as those
2076 within a @code{\layout} block. Translation modules for sound are
2077 called performers. The contexts for MIDI output are defined in
2078 @file{../ly/performer-init.ly},
2079 see @rlearning{Other sources of information}.
2080 For example, to remove the effect of dynamics
2081 from the MIDI output, insert the following lines in the
2082 @code{\midi@{ @}} block.
2089 \remove "Dynamic_performer"
2094 MIDI output is created only when a @code{\midi} block is included
2095 within a score block defined with a @code{\score} command.
2099 @{ @dots{}notes@dots{} @}
2104 @node What goes into the MIDI output?
2105 @subsection What goes into the MIDI output?
2107 @c TODO Check grace notes - timing is suspect?
2109 @unnumberedsubsubsec Supported in MIDI
2111 @cindex Pitches in MIDI
2112 @cindex MIDI, Pitches
2113 @cindex Quarter tones in MIDI
2114 @cindex MIDI, quarter tones
2115 @cindex Microtones in MIDI
2116 @cindex MIDI, microtones
2117 @cindex Chord names in MIDI
2118 @cindex MIDI, chord names
2119 @cindex Rhythms in MIDI
2120 @cindex MIDI, Rhythms
2121 @cindex Articlulate scripts
2122 @cindex MIDI, articulations
2123 @cindex articulations in MIDI
2124 @cindex trills in MIDI
2125 @cindex turns in MIDI
2126 @cindex rallentando in MIDI
2127 @cindex accelerando in MIDI
2130 The following items of notation are reflected in the MIDI output:
2134 @item Microtones (See @ref{Accidentals}. Rendering needs a
2135 player that supports pitch bend.)
2136 @item Chords entered as chord names
2137 @item Rhythms entered as note durations, including tuplets
2138 @item Tremolos entered without @q{@code{:}[@var{number}]}
2141 @item Crescendi, decrescendi over multiple notes
2142 @item Tempo changes entered with a tempo marking
2146 Using @ref{The Articulate script}, a number of items are added to the
2150 @item Articulations (slurs, staccato, etc)
2152 @item Rallentando and accelerando
2156 @unnumberedsubsubsec Unsupported in MIDI
2158 @c TODO index as above
2160 The following items of notation have no effect on the MIDI output,
2161 unless you use @ref{The Articulate script}:
2164 @item Rhythms entered as annotations, e.g. swing
2165 @item Tempo changes entered as annotations with no tempo marking
2166 @item Staccato and other articulations and ornamentations
2167 @item Slurs and Phrasing slurs
2168 @item Crescendi, decrescendi over a single note
2169 @item Tremolos entered with @q{@code{:}[@var{number}]}
2171 @item Microtonal chords
2175 @node Repeats in MIDI
2176 @subsection Repeats in MIDI
2178 @cindex repeats in MIDI
2179 @funindex \unfoldRepeats
2181 With a few minor additions, all types of repeats can be represented
2182 in the MIDI output. This is achieved by applying the
2183 @code{\unfoldRepeats} music function. This function changes all
2184 repeats to unfold repeats.
2186 @lilypond[quote,verbatim]
2188 \repeat tremolo 8 { c'32 e' }
2189 \repeat percent 2 { c''8 d'' }
2190 \repeat volta 2 { c'4 d' e' f' }
2199 In scores containing multiple voices, unfolding of repeats in MIDI
2200 output will only occur correctly if @emph{each} voice contains fully
2201 notated repeat indications.
2203 When creating a score file using @code{\unfoldRepeats} for MIDI,
2204 it is necessary to make two @code{\score} blocks: one for MIDI
2205 (with unfolded repeats) and one for notation (with volta, tremolo,
2206 and percent repeats). For example,
2214 \unfoldRepeats @var{..music..}
2219 @node Controlling MIDI dynamics
2220 @subsection Controlling MIDI dynamics
2222 MIDI dynamics are implemented by the Dynamic_performer which lives
2223 by default in the Voice context. It is possible to control the
2224 overall MIDI volume, the relative volume of dynamic markings and
2225 the relative volume of different instruments.
2227 @unnumberedsubsubsec Dynamic marks
2229 Dynamic marks are translated to a fixed fraction of the available
2230 MIDI volume range. The default fractions range from 0.25 for
2231 @notation{ppppp} to 0.95 for @notation{fffff}. The set of dynamic
2232 marks and the associated fractions can be seen in
2233 @file{../scm/midi.scm}, see @rlearning{Other sources of information}.
2234 This set of fractions may be changed or extended by providing a
2235 function which takes a dynamic mark as its argument and returns the
2236 required fraction, and setting
2237 @code{Score.dynamicAbsoluteVolumeFunction} to this function.
2239 For example, if a @notation{rinforzando} dynamic marking,
2240 @code{\rfz}, is required, this will not by default
2241 have any effect on the MIDI volume, as this dynamic marking is not
2242 included in the default set. Similarly, if a new dynamic marking
2243 has been defined with @code{make-dynamic-script} that too will not
2244 be included in the default set. The following example shows how the
2245 MIDI volume for such dynamic markings might be added. The Scheme
2246 function sets the fraction to 0.9 if a dynamic mark of rfz is
2247 found, or calls the default function otherwise.
2249 @lilypond[verbatim,quote]
2250 #(define (myDynamics dynamic)
2251 (if (equal? dynamic "rfz")
2253 (default-dynamic-absolute-volume dynamic)))
2257 \set Staff.midiInstrument = #"cello"
2258 \set Score.dynamicAbsoluteVolumeFunction = #myDynamics
2270 Alternatively, if the whole table of fractions needs to be
2271 redefined, it would be better to use the
2272 @notation{default-dynamic-absolute-volume} procedure in
2273 @file{../scm/midi.scm} and the associated table as a model.
2274 The final example in this section shows how this might be done.
2276 @unnumberedsubsubsec Overall MIDI volume
2278 The minimum and maximum overall volume of MIDI dynamic markings is
2279 controlled by setting the properties @code{midiMinimumVolume} and
2280 @code{midiMaximumVolume} at the @code{Score} level. These
2281 properties have an effect only on dynamic marks, so if they
2282 are to apply from the start of the score a dynamic mark must be
2283 placed there. The fraction corresponding to each dynamic mark is
2284 modified with this formula
2287 midiMinimumVolume + (midiMaximumVolume - midiMinimumVolume) * fraction
2290 In the following example the dynamic range of the overall MIDI
2291 volume is limited to the range 0.2 - 0.5.
2293 @lilypond[verbatim,quote]
2299 \set Staff.midiInstrument = #"flute"
2300 \new Voice \relative c''' {
2308 \set Staff.midiInstrument = #"clarinet"
2309 \new Voice \relative c'' {
2320 tempoWholesPerMinute = #(ly:make-moment 72 2)
2321 midiMinimumVolume = #0.2
2322 midiMaximumVolume = #0.5
2328 @unnumberedsubsubsec Equalizing different instruments (i)
2330 If the minimum and maximum MIDI volume properties are set in
2331 the @code{Staff} context the relative volumes of the MIDI
2332 instruments can be controlled. This gives a basic instrument
2333 equalizer, which can enhance the quality of the MIDI output
2336 In this example the volume of the clarinet is reduced relative
2337 to the volume of the flute. There must be a dynamic
2338 mark on the first note of each instrument for this to work
2341 @lilypond[verbatim,quote]
2347 \set Staff.midiInstrument = #"flute"
2348 \set Staff.midiMinimumVolume = #0.7
2349 \set Staff.midiMaximumVolume = #0.9
2350 \new Voice \relative c''' {
2358 \set Staff.midiInstrument = #"clarinet"
2359 \set Staff.midiMinimumVolume = #0.3
2360 \set Staff.midiMaximumVolume = #0.6
2361 \new Voice \relative c'' {
2372 tempoWholesPerMinute = #(ly:make-moment 72 2)
2378 @unnumberedsubsubsec Equalizing different instruments (ii)
2380 If the MIDI minimum and maximum volume properties are not set
2381 LilyPond will, by default, apply a small degree of equalization
2382 to a few instruments. The instruments and the equalization
2383 applied are shown in the table @notation{instrument-equalizer-alist}
2384 in @file{../scm/midi.scm}.
2386 This basic default equalizer can be replaced by setting
2387 @code{instrumentEqualizer} in the @code{Score} context to a new
2388 Scheme procedure which accepts a MIDI instrument name as its only
2389 argument and returns a pair of fractions giving the minimum and
2390 maximum volumes to be applied to that instrument. This replacement
2391 is done in the same way as shown for resetting the
2392 @code{dynamicAbsoluteVolumeFunction} at the start of this section.
2393 The default equalizer, @notation{default-instrument-equalizer}, in
2394 @file{../scm/midi.scm} shows how such a procedure might be written.
2396 The following example sets the relative flute and clarinet volumes
2397 to the same values as the previous example.
2399 @lilypond[verbatim,quote]
2400 #(define my-instrument-equalizer-alist '())
2402 #(set! my-instrument-equalizer-alist
2405 ("flute" . (0.7 . 0.9))
2406 ("clarinet" . (0.3 . 0.6)))
2407 my-instrument-equalizer-alist))
2409 #(define (my-instrument-equalizer s)
2410 (let ((entry (assoc s my-instrument-equalizer-alist)))
2419 \set Score.instrumentEqualizer = #my-instrument-equalizer
2420 \set Staff.midiInstrument = #"flute"
2421 \new Voice \relative c''' {
2429 \set Staff.midiInstrument = #"clarinet"
2430 \new Voice \relative c'' {
2441 tempoWholesPerMinute = #(ly:make-moment 72 2)
2448 @c Delete when satisfied this is adequately covered elsewhere -td
2450 @n ode Microtones in MIDI
2451 @s ubsection Microtones in MIDI
2453 @cindex microtones in MIDI
2455 Microtones consisting of half sharps and half flats are exported
2456 to the MIDI file and render correctly in MIDI players which support
2457 pitch bending. See @ref{Note names in other languages}. Here is
2458 an example showing all the half sharps and half flats. It can be
2459 copied out and compiled to test microtones in your MIDI player.
2461 @lilypond[verbatim,quote]
2478 @node Percussion in MIDI
2479 @subsection Percussion in MIDI
2481 Percussion instruments are generally notated in a @code{DrumStaff}
2482 context and when notated in this way they are outputted correctly
2483 to MIDI channel@tie{}10, but some pitched percussion instruments,
2484 like the xylophone, marimba, vibraphone, timpani, etc., are
2485 treated like @qq{normal} instruments and music for these instruments
2486 should be entered in a normal @code{Staff} context, not a
2487 @code{DrumStaff} context, to obtain the correct MIDI output.
2489 Some non-pitched percussion sounds included in the general MIDI
2490 standard, like melodic tom, taiko drum, synth drum, etc., cannot
2491 be reached via MIDI channel@tie{}10, so the notation for such
2492 instruments should also be entered in a normal @code{Staff}
2493 context, using suitable normal pitches.
2495 Many percussion instruments are not included in the general MIDI
2496 standard, e.g. castanets. The easiest, although unsatisfactory,
2497 method of producing some MIDI output when writing for such
2498 instruments is to substitute the nearest sound from the standard
2501 @c TODO Expand with examples, and any other issues
2505 Because the general MIDI standard does not contain rim shots, the
2506 sidestick is used for this purpose instead.
2508 @node The Articulate script
2509 @subsection The Articulate script
2511 A more realistic MIDI output is possible when using the Articulate
2512 script. It tries to take articulations (slurs, staccato, etc) into
2513 account, by replacing notes with sequential music of suitably
2514 time-scaled note plus skip. It also tries to unfold trills turns
2515 etc., and take rallentando and accelerando into account.
2517 To use the Articulate script, you have to include it at the top of
2521 \include "articulate.ly"
2524 and in the @code{\score} section do
2527 \unfoldRepeats \articulate <<
2528 all the rest of the score...
2532 After altering your input file this way, the visual output is heavily
2533 altered, but the standard @code{\midi} block will produce a better
2536 Although not essential for the Articulate script to work, you may want
2537 to insert the @code{\unfoldRepeats} command as it appears in the
2538 example shown above as it enables performing abbreviatures such as
2543 Articulate shortens chords and some music (esp. organ music) could
2547 @node Extracting musical information
2548 @section Extracting musical information
2550 In addition to creating graphical output and MIDI, LilyPond can
2551 display musical information as text.
2554 * Displaying LilyPond notation::
2555 * Displaying scheme music expressions::
2556 * Saving music events to a file::
2559 @node Displaying LilyPond notation
2560 @subsection Displaying LilyPond notation
2562 @funindex \displayLilyMusic
2563 Displaying a music expression in LilyPond notation can be
2564 done with the music function @code{\displayLilyMusic} but only when
2565 using the command line. For example,
2569 \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
2576 @{ a,4 cis e fis g @}
2579 By default, LilyPond will print these messages to the console
2580 along with all the other LilyPond compilation messages. To split
2581 up these messages and save the results of @code{\display@{STUFF@}},
2582 redirect the output to a file.
2585 lilypond file.ly >display.txt
2589 @node Displaying scheme music expressions
2590 @subsection Displaying scheme music expressions
2592 See @rextend{Displaying music expressions}.
2595 @node Saving music events to a file
2596 @subsection Saving music events to a file
2598 Music events can be saved to a file on a per-staff basis by
2599 including a file in your main score.
2602 \include "event-listener.ly"
2605 This will create file(s) called @file{FILENAME-STAFFNAME.notes} or
2606 @file{FILENAME-unnamed-staff.notes} for each staff. Note that if
2607 you have multiple unnamed staves, the events for all staves will
2608 be mixed together in the same file. The output looks like this:
2611 0.000 note 57 4 p-c 2 12
2613 0.250 note 62 4 p-c 7 12
2614 0.500 note 66 8 p-c 9 12
2615 0.625 note 69 8 p-c 14 12
2620 The syntax is a tab-delimited line, with two fixed fields on each
2621 line followed by optional parameters.
2624 @var{time} @var{type} @var{...params...}
2627 This information can easily be read into other programs such as
2628 python scripts, and can be very useful for researchers wishing to
2629 perform musical analysis or playback experiments with LilyPond.
2634 Not all lilypond music events are supported by
2635 @file{event-listener.ly}. It is intended to be a well-crafted
2636 @qq{proof of concept}. If some events that you want to see are
2637 not included, copy @file{event-listener.ly} into your lilypond
2638 directory and modify the file so that it outputs the information