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"
294 \bookOutputSuffix "Menuetto"
299 \bookOutputSuffix "Nocturne"
305 You can also specify a different output filename for @code{book} block,
306 by using @code{\bookOutputName} declarations
310 \bookOutputName "Romanze"
315 \bookOutputName "Menuetto"
320 \bookOutputName "Nocturne"
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 the same type
357 is entered at the top level the definitions are combined, but in
358 conflicting situations the later definitions take precedence. For
359 details of how this affects the @code{\layout} block see
360 @ref{The \layout block}.
363 A direct scheme expression, such as
364 @code{#(set-default-paper-size "a7" 'landscape)} or
365 @code{#(ly:set-option 'point-and-click #f)}.
368 A @code{\header} block. This sets the global (i.e. the top of
369 file) header block. This is the block containing the default
370 settings of titling fields like composer, title, etc. for all
371 books within the file (see @ref{Titles explained}).
374 A @code{\score} block. This score will be collected with other
375 toplevel scores, and combined as a single @code{\book}.
376 This behavior can be changed by setting the variable
377 @code{toplevel-score-handler} at toplevel. The default handler is
378 defined in the init file @file{../scm/lily.scm}.
381 A @code{\book} block logically combines multiple movements
382 (i.e., multiple @code{\score} blocks) in one document. If there
383 are a number of @code{\score}s, one output file will be created
384 for each @code{\book} block, in which all corresponding movements
385 are concatenated. The only reason to explicitly specify
386 @code{\book} blocks in a @file{.ly} file is if you wish to create
387 multiple output files from a single input file. One exception is
388 within lilypond-book documents, where you explicitly have to add
389 a @code{\book} block if you want more than a single @code{\score}
390 or @code{\markup} in the same example. This behavior can be
391 changed by setting the variable @code{toplevel-book-handler} at
392 toplevel. The default handler is defined in the init file
393 @file{../scm/lily.scm}.
396 A @code{\bookpart} block. A book may be divided into several parts,
397 using @code{\bookpart} blocks, in order to ease the page breaking,
398 or to use different @code{\paper} settings in different parts.
401 A compound music expression, such as
406 This will add the piece in a @code{\score} and format it in a
407 single book together with all other toplevel @code{\score}s and music
408 expressions. In other words, a file containing only the above
409 music expression will be translated into
426 This behavior can be changed by setting the variable
427 @code{toplevel-music-handler} at toplevel. The default handler is
428 defined in the init file @file{../scm/lily.scm}.
431 A markup text, a verse for example
434 2. The first line verse two.
438 Markup texts are rendered above, between or below the scores or music
439 expressions, wherever they appear.
449 This can be used later on in the file by entering @code{\foo}. The
450 name of a variable should have alphabetic characters only; no
451 numbers, underscores or dashes.
455 The following example shows three things that may be entered at
460 % Don't justify the output
472 At any point in a file, any of the following lexical instructions can
476 @item @code{\version}
477 @item @code{\include}
478 @item @code{\sourcefilename}
479 @item @code{\sourcefileline}
481 A single-line comment, introduced by a leading @code{%} sign.
484 A multi-line comment delimited by @code{%@{ .. %@}}.
490 Whitespace between items in the input stream is generally ignored,
491 and may be freely omitted or extended to enhance readability.
492 However, whitespace should always be used in the following
493 circumstances to avoid errors:
497 @item Around every opening and closing curly bracket.
499 @item After every command or variable, i.e. every item that
500 begins with a @code{\} sign.
502 @item After every item that is to be interpreted as a Scheme
503 expression, i.e. every item that begins with a @code{#}@tie{}sign.
505 @item To separate all elements of a Scheme expression.
507 @item In @code{lyricmode} before and after @code{\set} and
508 @code{\override} commands.
514 @rlearning{How LilyPond input files work}.
517 @ref{Titles explained},
518 @ref{The \layout block}.
521 @node Titles and headers
522 @section Titles and headers
524 Almost all printed music includes a title and the composer's name;
525 some pieces include a lot more information.
528 * Creating titles headers and footers::
529 * Custom titles headers and footers::
530 * Creating footnotes::
531 * Reference to page numbers::
532 * Table of contents::
536 @node Creating titles headers and footers
537 @subsection Creating titles headers and footers
541 * Default layout of bookpart and score titles::
542 * Default layout of headers and footers::
546 @node Titles explained
547 @unnumberedsubsubsec Titles explained
549 Each @code{\book} block in a single input file produces a separate
550 output file, see @ref{File structure}. Within each output file
551 three types of titling areas are provided: @emph{Book Titles} at the
552 beginning of each book, @emph{Bookpart Titles} at the beginning of
553 each bookpart and @emph{Score Titles} at the beginning of each score.
555 Values of titling fields such as @code{title} and @code{composer}
556 are set in @code{\header} blocks. (For the syntax of @code{\header}
557 blocks and a complete list of the fields available by default see
558 @ref{Default layout of bookpart and score titles}). Book Titles,
559 Bookpart Titles and Score Titles can all contain the same fields,
560 although by default the fields in Score Titles are limited to
561 @code{piece} and @code{opus}.
563 @code{\header} blocks may be placed in four different places to form
564 a descending hierarchy of @code{\header} blocks:
569 At the top of the input file, before all @code{\book},
570 @code{\bookpart}, and @code{\score} blocks.
573 Within a @code{\book} block but outside all the @code{\bookpart} and
574 @code{\score} blocks within that book.
577 Within a @code{\bookpart} block but outside all @code{\score} blocks
578 within that bookpart.
581 After the music expression in a @code{\score} block.
585 The values of the fields filter down this hierarchy, with the values
586 set higher in the hierarchy persisting unless they are over-ridden
587 by a value set lower in the hierarchy, so:
592 A Book Title is derived from fields set at the top of the input file,
593 modified by fields set in the @code{\book} block. The resulting
594 fields are used to print the Book Title for that book, providing that
595 there is other material which generates a page at the start of the
596 book, before the first bookpart. A single @code{\pageBreak} will
600 A Bookpart Title is derived from fields set at the top of the input
601 file, modified by fields set in the @code{\book} block, and further
602 modified by fields set in the @code{\bookpart} block. The resulting
603 values are used to print the Bookpart Title for that bookpart.
606 A Score Title is derived from fields set at the top of the input
607 file, modified by fields set in the @code{\book} block, further
608 modified by fields set in the @code{\bookpart} block and finally
609 modified by fields set in the @code{\score} block. The resulting
610 values are used to print the Score Title for that score. Note,
611 though, that only @code{piece} and @code{opus} fields are printed
612 by default in Score Titles unless the @code{\paper} variable,
613 @code{print-all-headers}, is set to @code{#t}.
617 @warning{Remember when placing a @bs{}@code{header} block inside a
618 @bs{}@code{score} block, that the music expression must come before the
619 @bs{}@code{header} block.}
621 It is not necessary to provide @code{\header} blocks in all four
622 places: any or even all of them may be omitted. Similarly, simple
623 input files may omit the @code{\book} and @code{\bookpart} blocks,
624 leaving them to be created implicitly.
626 If the book has only a single score, the @code{\header} block should
627 normally be placed at the top of the file so that just a Bookpart
628 Title is produced, making all the titling fields available for use.
630 If the book has multiple scores a number of different arrangements
631 of @code{\header} blocks are possible, corresponding to the various
632 types of musical publications. For example, if the publication
633 contains several pieces by the same composer a @code{\header} block
634 placed at the top of the file specifying the book title and the
635 composer with @code{\header} blocks in each @code{\score} block
636 specifying the @code{piece} and/or @code{opus} would be most
639 @lilypond[papersize=a5,quote,verbatim,noragged-right]
642 composer = "J. S. Bach."
646 \new Staff \relative g, {
649 \repeat unfold 2 { g16( d' b') a b d, b' d, } |
650 \repeat unfold 2 { g,16( e' c') b c e, c' e, } |
658 \new Staff \relative b {
662 <g, d' b'~>4 b'16 a( g fis) g( d e fis) g( a b c) |
663 d16( b g fis) g( e d c) b(c d e) fis( g a b) |
671 More complicated arrangements are possible. For example, text
672 fields from the @code{\header} block in a book can be displayed in
673 all Score Titles, with some fields over-ridden and some manually
676 @lilypond[papersize=a5,quote,verbatim,noragged-right]
679 print-all-headers = ##t
682 title = "DAS WOHLTEMPERIRTE CLAVIER"
684 % Do not display the tagline for this book
687 \markup { \vspace #1 }
691 \new Staff { \clef "bass" s1 }
694 title = "PRAELUDIUM I"
696 % Do not display the subtitle for this score
703 \new Staff { \clef "bass" s1 }
707 subsubtitle = "A 4 VOCI"
709 % Do not display the subtitle for this score
718 @ref{File structure},
719 @ref{Default layout of bookpart and score titles},
720 @ref{Custom layout for titles}.
723 @node Default layout of bookpart and score titles
724 @unnumberedsubsubsec Default layout of bookpart and score titles
726 This example demonstrates all @code{\header} variables:
728 @lilypond[papersize=a7,quote,verbatim,noragged-right]
731 % The following fields are centered
732 dedication = "Dedication"
734 subtitle = "Subtitle"
735 subsubtitle = "Subsubtitle"
736 % The following fields are evenly spread on one line
737 % the field "instrument" also appears on following pages
738 instrument = \markup \with-color #green "Instrument"
740 composer = "Composer"
741 % The following fields are placed at opposite ends of the same line
743 arranger = "Arranger"
744 % The following fields are centered at the bottom
745 tagline = "tagline goes at the bottom of the last page"
746 copyright = "copyright goes at the bottom of the first page"
751 % The following fields are placed at opposite ends of the same line
759 % The following fields are placed at opposite ends of the same line
760 piece = "Piece 2 on the same page"
768 % The following fields are placed at opposite ends of the same line
769 piece = "Piece 3 on a new page"
780 The instrument name will be repeated on every page.
783 Only @code{piece} and @code{opus} are printed in a @code{\score}
784 when the paper variable @code{print-all-headers} is set to
785 @code{##f} (the default).
788 @c Is the bit about \null markups true? -mp
789 Text fields left unset in a @code{\header} block are replaced with
790 @code{\null} markups so that the space is not wasted.
793 The default settings for @code{scoreTitleMarkup} place the @code{piece}
794 and @code{opus} text fields at opposite ends of the same line.
798 To change the default layout see @ref{Custom layout for titles}.
802 If a @code{\book} block starts immediately with a @code{\bookpart}
803 block, no Book Title will be printed, as there is no page on which
804 to print it. If a Book Title is required, begin the @code{\book}
805 block with some markup material or a @code{\pageBreak} command.
807 Use the @code{breakbefore} variable inside a @code{\header} block
808 that is itself in a @code{\score} block, to make the higher-level
809 @code{\header} block titles appear on the first page on their own, with
810 the music (defined in the @code{\score} block) starting on the next.
812 @lilypond[papersize=a8landscape,verbatim,noragged-right]
815 title = "This is my Title"
816 subtitle = "This is my Subtitle"
817 copyright = "This is the bottom of the first page"
820 \repeat unfold 4 { e'' e'' e'' e'' }
822 piece = "This is the Music"
831 @rlearning{How LilyPond input files work},
834 @ref{Custom layout for titles},
835 @ref{File structure}.
838 @file{ly/titling-init.ly}.
841 @node Default layout of headers and footers
842 @unnumberedsubsubsec Default layout of headers and footers
844 @emph{Headers} and @emph{footers} are lines of text appearing at
845 the top and bottom of pages, separate from the main text of a book.
846 They are controlled by the following @code{\paper} variables:
849 @item @code{oddHeaderMarkup}
850 @item @code{evenHeaderMarkup}
851 @item @code{oddFooterMarkup}
852 @item @code{evenFooterMarkup}
855 These markup variables can only access text fields from top-level
856 @code{\header} blocks (which apply to all scores in the book) and are
857 defined in @file{ly/titling-init.ly}. By default:
862 page numbers are automatically placed on the top far left (if even) or
863 top far right (if odd), starting from the second page.
866 the @code{instrument} text field is placed in the center of every
867 page, starting from the second page.
870 the @code{copyright} text is centered on the bottom of the first page.
873 the @code{tagline} is centered on the bottom of the last page, and below
874 the @code{copyright} text if there is only a single page.
878 @lilypond[papersize=a8landscape]
888 The default tagline can be changed by adding a @code{tagline} in the
889 top-level @code{\header} block.
891 @lilypond[papersize=a8landscape,verbatim]
894 tagline = "... music notation for Everyone"
904 To remove the @code{tagline} set the value to @code{##f}.
907 @node Custom titles headers and footers
908 @subsection Custom titles headers and footers
910 @c TODO: somewhere put a link to header spacing info
911 @c (you'll have to explain it more in NR 4).
914 * Custom text formatting for titles::
915 * Custom layout for titles::
916 * Custom layout for headers and footers::
920 @node Custom text formatting for titles
921 @unnumberedsubsubsec Custom text formatting for titles
923 Standard @code{\markup} commands can be used to customize any header,
924 footer and title text within the @code{\header} block.
926 @lilypond[quote,verbatim,noragged-right]
930 piece = \markup { \fontsize #4 \bold "PRAELUDIUM I" }
931 subtitle = \markup { \italic "(Excerpt)" }
938 @ref{Formatting text}.
941 @node Custom layout for titles
942 @unnumberedsubsubsec Custom layout for titles
944 @cindex bookTitleMarkup
945 @cindex scoreTitleMarkup
946 @funindex bookTitleMarkup
947 @funindex scoreTitleMarkup
949 @code{\markup} commands in the @code{\header} block are useful for
950 simple text formatting, but they do not allow precise control over the
951 placement of titles. To customize the placement of the text fields,
952 change either or both of the following @code{\paper} variables:
955 @item @code{bookTitleMarkup}
956 @item @code{scoreTitleMarkup}
959 The placement of titles when using the default values of these
960 @code{\markup} variables is shown in the examples in
961 @ref{Default layout of bookpart and score titles}.
963 The default settings for @code{scoreTitleMarkup} as defined in
964 @file{ly/titling-init.ly} are:
967 scoreTitleMarkup = \markup @{ \column @{
968 \on-the-fly \print-all-headers @{ \bookTitleMarkup \hspace #1 @}
970 \fromproperty #'header:piece
971 \fromproperty #'header:opus
977 This places the @code{piece} and @code{opus} text fields at opposite
978 ends of the same line:
980 @lilypond[quote,verbatim,noragged-right]
984 piece = "PRAELUDIUM I"
990 This example redefines @code{scoreTitleMarkup} so that the @code{piece}
991 text field is centered and in a large, bold font.
993 @lilypond[papersize=a5,quote,verbatim,noragged-right]
997 scoreTitleMarkup = \markup {
1000 \fontsize #4 \bold \fromproperty #'header:piece
1001 \fromproperty #'header:opus
1005 \header { tagline = ##f }
1009 piece = "PRAELUDIUM I"
1016 Text fields not normally effective in score @code{\header} blocks
1017 can be printed in the Score Title area if @code{print-all-headers} is
1018 placed inside the @code{\paper} block. A disadvantage of using this
1019 method is that text fields that are intended specifically for the
1020 Bookpart Title area need to be manually suppressed in every
1021 @code{\score} block. See @ref{Titles explained}.
1023 To avoid this, add the desired text field to the @code{scoreTitleMarkup}
1024 definition. In the following example, the @code{composer} text field
1025 (normally associated with @code{bookTitleMarkup}) is added to
1026 @code{scoreTitleMarkup}, allowing each score to list a different
1029 @lilypond[papersize=a5,quote,verbatim,noragged-right]
1033 scoreTitleMarkup = \markup {
1036 \fontsize #4 \bold \fromproperty #'header:piece
1037 \fromproperty #'header:composer
1041 \header { tagline = ##f }
1046 composer = "Christian Petzold"
1053 composer = "François Couperin"
1059 It is also possible to create your own custom text fields, and refer to
1060 them in the markup definition.
1062 @lilypond[papersize=a5,quote,verbatim,noragged-right]
1066 scoreTitleMarkup = \markup {
1069 \override #`(direction . ,UP) {
1071 \center-align \fontsize #-1 \bold
1072 \fromproperty #'header:mycustomtext %% User-defined field
1073 \center-align \fontsize #4 \bold
1074 \fromproperty #'header:piece
1077 \fromproperty #'header:opus
1081 \header { tagline = ##f }
1086 mycustomtext = "A 4 VOCI" %% User-defined field
1095 @ref{Titles explained}.
1098 @node Custom layout for headers and footers
1099 @unnumberedsubsubsec Custom layout for headers and footers
1101 @c can make-header and make-footer be removed from
1102 @c paper-defaults-init.ly? -mp
1104 @code{\markup} commands in the @code{\header} block are useful for
1105 simple text formatting, but they do not allow precise control over the
1106 placement of headers and footers. To customize the placement of
1107 the text fields, use either or both of the following @code{\paper}
1111 @item @code{oddHeaderMarkup}
1112 @item @code{evenHeaderMarkup}
1113 @item @code{oddFooterMarkup}
1114 @item @code{evenFooterMarkup}
1117 @cindex markup, conditional
1119 @funindex \on-the-fly
1121 The @code{\markup} command @code{\on-the-fly} can be used to add
1122 markup conditionally to header and footer text defined within the
1123 @code{\paper} block, using the following syntax:
1126 @code{variable} = @code{\markup} @{
1128 @code{\on-the-fly} \@var{procedure} @var{markup}
1133 The @var{procedure} is called each time the @code{\markup} command
1134 in which it appears is evaluated. The @var{procedure} should test
1135 for a particular condition and interpret (i.e. print) the
1136 @var{markup} argument if and only if the condition is true.
1138 A number of ready-made procedures for testing various conditions are
1142 @multitable {print-page-number-check-first-----} {should this page be printed-----}
1144 @headitem Procedure name @tab Condition tested
1146 @item print-page-number-check-first @tab should this page number be printed?
1147 @item create-page-number-stencil @tab print-page-numbers true?
1148 @item print-all-headers @tab print-all-headers true?
1149 @item first-page @tab first page in the book?
1150 @item (on-page nmbr) @tab page number = nmbr?
1151 @item last-page @tab last page in the book?
1152 @item not-first-page @tab not first page in the book?
1153 @item part-first-page @tab first page in the book part?
1154 @item part-last-page @tab last page in the book part?
1155 @item not-single-page @tab pages in book part > 1?
1160 The following example centers page numbers at the bottom of every
1161 page. First, the default settings for @code{oddHeaderMarkup} and
1162 @code{evenHeaderMarkup} are removed by defining each as a @emph{null}
1163 markup. Then, @code{oddFooterMarkup} is redefined with the page
1164 number centered. Finally, @code{evenFooterMarkup} is given the
1165 same layout by defining it as @code{\oddFooterMarkup}:
1167 @lilypond[papersize=a8,quote,verbatim,noragged-right]
1170 print-page-number = ##t
1171 print-first-page-number = ##t
1172 oddHeaderMarkup = \markup \null
1173 evenHeaderMarkup = \markup \null
1174 oddFooterMarkup = \markup {
1176 \on-the-fly \print-page-number-check-first
1177 \fromproperty #'page:page-number-string
1180 evenFooterMarkup = \oddFooterMarkup
1183 \new Staff { s1 \break s1 \break s1 }
1188 Several @code{\on-the-fly} conditions can be combined with an
1189 @q{and} operation, for example,
1192 @code{\on-the-fly \first-page}
1193 @code{\on-the-fly \last-page}
1194 @code{@{ \markup ... \fromproperty #'header: ... @}}
1197 determines if the output is a single page.
1201 @ref{Titles explained},
1202 @ref{Default layout of bookpart and score titles}.
1205 @file{../ly/titling-init.ly}.
1208 @node Creating footnotes
1209 @subsection Creating footnotes
1213 Footnotes may be used in many different situations. In all cases,
1214 a @q{footnote mark} is placed as a reference in text or music, and
1215 the corresponding @q{footnote text} appears at the bottom of the
1218 Footnotes within music expressions and footnotes in stand-alone text
1219 outside music expressions are created in different ways.
1222 * Footnotes in music expressions::
1223 * Footnotes in stand-alone text::
1226 @node Footnotes in music expressions
1227 @unnumberedsubsubsec Footnotes in music expressions
1229 @cindex footnotes in music expressions
1232 @subsubsubheading Music footnotes overview
1234 Footnotes in music expressions fall into two categories:
1237 @item Event-based footnotes
1238 are attached to a particular event. Examples for such events are
1239 single notes, articulations (like fingering indications, accents,
1240 dynamics), and post-events (like slurs and manual beams). The
1241 general form for event-based footnotes is as follows:
1244 [@var{direction}] \footnote [@var{mark}] @var{offset} @var{footnote} @var{music}
1247 @item Time-based footnotes
1248 are bound to a particular point of time in a musical context. Some
1249 commands like @code{\time} and @code{\clef} don't actually use events
1250 for creating objects like time signatures and clefs. Neither does a
1251 chord create an event of its own: its stem or flag is created at the
1252 end of a time step (nominally through one of the note events inside).
1253 Exactly which of a chord's multiple note events will be deemed the
1254 root cause of a stem or flag is undefined. So for annotating those,
1255 time-based footnotes are preferable as well.
1257 A time-based footnote allows such layout objects to be annotated
1258 without referring to an event. The general form for Time-based
1262 \footnote [@var{mark}] @var{offset} @var{footnote} [@var{Context}].@var{GrobName}
1267 The elements for both forms are:
1272 If (and only if) the @code{\footnote} is being applied to a
1273 post-event or articulation, it must be preceded with a direction
1274 indicator (@code{-, _, ^}) in order to attach @var{music} (with
1275 a footnote mark) to the preceding note or rest.
1278 is a markup or string specifying the footnote mark which is used for
1279 marking both the reference point and the footnote itself at the
1280 bottom of the page. It may be omitted (or equivalently replaced with
1281 @code{\default}) in which case a number in sequence will be generated
1282 automatically. Such numerical sequences restart on each page
1283 containing a footnote.
1286 is a number pair such as @samp{#(2 . 1)} specifying the X and
1287 Y@tie{}offsets in units of staff-spaces from the boundary of the
1288 object where the mark should be placed. Positive values of the
1289 offsets are taken from the right/top edge, negative values from the
1290 left/bottom edge and zero implies the mark is centered on the edge.
1293 is the context in which the grob being footnoted is created. It
1294 may be omitted if the grob is in a bottom context, e.g. a
1295 @code{Voice} context.
1298 specifies a type of grob to mark (like @samp{Flag}). If it is
1299 specified, the footnote is not attached to a music expression in
1300 particular, but rather to all grobs of the type specified which
1301 occur at that moment of musical time.
1304 is the markup or string specifying the footnote text to use at the
1308 is the music event or post-event or articulation
1309 that is being annotated.
1313 @subsubsubheading Event-based footnotes
1315 @cindex footnotes, event-based
1317 A footnote may be attached to a layout object directly caused
1318 by the event corresponding to @var{music} with the syntax:
1321 \footnote [@var{mark}] @var{offset} @var{footnote} @var{music}
1324 @lilypond[quote,verbatim,papersize=a8landscape]
1326 \header { tagline = ##f }
1328 \footnote #'(-1 . 3) "A note" a4
1330 \footnote #'(2 . 2) "A rest" r4
1336 Marking a @emph{whole} chord with an event-based footnote is not
1337 possible: a chord, even one containing just a single note, does
1338 not produce an actual event of its own. However, individual
1339 notes @emph{inside} of the chord can be marked:
1341 @lilypond[quote,verbatim,papersize=a8landscape]
1343 \header { tagline = ##f }
1345 \footnote #'(2 . 3) "Does not work" <a-3>2
1346 <\footnote #'(-2 . -3) "Does work" a-3>4
1347 <a-3 \footnote #'(3 . 1/2) "Also works" c-5>4
1352 If the footnote is to be attached to a post-event or articulation
1353 the @code{\footnote} command @emph{must} be preceded by a direction
1354 indicator, @code{-, _, ^}, and followed by the post-event or
1355 articulation to be annotated as the @var{music} argument. In this
1356 form the @code{\footnote} can be considered to be simply a copy of
1357 its last argument with a footnote mark attached to it. The syntax
1361 @var{direction} \footnote [@var{mark}] @var{offset} @var{footnote} @var{music}
1364 @lilypond[quote,verbatim,papersize=a8landscape]
1366 \header { tagline = ##f }
1368 a4_\footnote #'(0 . -1) "A slur forced down" (
1369 b8^\footnote #'(1 . 0.5) "A manual beam forced up" [
1372 c-\footnote #'(1 . 1) "Tenuto" --
1377 @subsubsubheading Time-based footnotes
1379 @cindex footnotes, time-based
1381 If the layout object being footmarked is @emph{indirectly} caused by
1382 an event (like an @code{Accidental} or @code{Stem} caused by a
1383 @code{NoteHead} event), the @var{GrobName} of the layout object
1384 is required after the footnote text instead of @var{music}:
1386 @lilypond[quote,verbatim,papersize=a8landscape]
1388 \header { tagline = ##f }
1390 \footnote #'(-1 . -3) "A flat" Accidental
1392 \footnote #'(-1 . 0.5) "Another flat" Accidental
1394 \footnote #'(1 . -2) "A stem" Stem
1400 Note, however, that when a GrobName is specified, a footnote
1401 will be attached to all grobs of that type at the current time step:
1403 @lilypond[quote,verbatim,papersize=a8landscape]
1405 \header { tagline = ##f }
1407 \footnote #'(-1 . 3) "A flat" Accidental
1409 \footnote #'(2 . 0.5) "Articulation" Script
1415 A note inside of a chord can be given an individual (event-based)
1416 footnote. A @samp{NoteHead} is the only grob directly caused
1417 from a chord note, so an event-based footnote command is
1418 @emph{only} suitable for adding a footnote to the @samp{NoteHead}
1419 within a chord. All other chord note grobs are indirectly caused.
1420 The @code{\footnote} command itself offers no syntax for
1421 specifying @emph{both} a particular grob type @emph{as well as} a
1422 particular event to attach to. However, one can use a time-based
1423 @code{\footnote} command for specifying the grob type, and then
1424 prefix this command with @code{\single} in order to have it
1425 applied to just the following event:
1427 @lilypond[quote,verbatim,papersize=a8landscape]
1429 \header { tagline = ##f }
1431 < \footnote #'(1 . -2) "An A" a
1432 \single \footnote #'(-1 . -1) "A sharp" Accidental
1434 \single \footnote #'(0.5 . 0.5) "A flat" Accidental
1441 @warning {When footnotes are attached to several musical elements at
1442 the same musical moment, as they are in the example above, the
1443 footnotes are numbered from the higher to the lower elements as they
1444 appear in the printed output, not in the order in which they are
1445 written in the input stream.}
1447 Layout objects like clefs and key-change signatures are mostly caused
1448 as a consequence of changed properties rather than actual events.
1449 Others, like bar lines and bar numbers, are a direct consequence of
1450 timing. For this reason, footnotes on such objects have to be based
1451 on their musical timing. Time-based footnotes are also preferable
1452 when marking features like stems and beams on @emph{chords}: while
1453 such per-chord features are nominally assigned to @emph{one} event
1454 inside the chord, relying on a particular choice would be imprudent.
1456 The layout object in question must always be explicitly specified
1457 for time-based footnotes, and the appropriate context must be
1458 specified if the grob is created in a context other than the bottom
1461 @lilypond[quote,verbatim,papersize=a8landscape]
1463 \header { tagline = ##f }
1466 \footnote #'(-0.5 . -1) "Meter change" Staff.TimeSignature
1468 \footnote #'(1 . -1) "Chord stem" Stem
1470 \footnote #'(-0.5 . 1) "Bar line" Staff.BarLine
1472 \footnote #'(0.5 . -1) "Key change" Staff.KeySignature
1479 Custom marks can be used as alternatives to numerical marks, and the
1480 annotation line joining the marked object to the mark can be
1483 @lilypond[quote,verbatim,papersize=a8landscape]
1485 \header { tagline = ##f }
1487 \footnote "*" #'(0.5 . -2) \markup { \italic "* The first note" } a'4
1489 \footnote \markup { \super "$" } #'(0.5 . 1)
1490 \markup { \super "$" \italic " The second note" } e
1492 \once \override Score.FootnoteItem.annotation-line = ##f
1493 b-\footnote \markup \tiny "+" #'(0.1 . 0.1)
1494 \markup { \super "+" \italic " Editorial" } \p
1499 More examples of custom marks are shown in
1500 @ref{Footnotes in stand-alone text}.
1503 @node Footnotes in stand-alone text
1504 @unnumberedsubsubsec Footnotes in stand-alone text
1506 @cindex footnotes in stand-alone text
1508 These are for use in markup outside of music expressions. They do
1509 not have a line drawn to their point of reference: their marks simply
1510 follow the referenced markup. Marks can be inserted automatically,
1511 in which case they are numerical. Alternatively, custom marks can be
1514 Footnotes to stand-alone text with automatic and custom marks are
1515 created in different ways.
1517 @subsubsubheading Footnotes in stand-alone text with automatic marks
1519 The syntax of a footnote in stand-alone text with automatic marks is
1522 \markup @{ ... \auto-footnote @var{text} @var{footnote} ... @}
1530 is the markup or string to be marked.
1533 is the markup or string specifying the footnote text to use at the bottom
1540 @lilypond[verbatim,quote,ragged-right,papersize=a8]
1542 \header { tagline = ##f }
1545 \auto-footnote "tune" \italic " By me"
1546 "is shown below. It is a"
1547 \auto-footnote "recent" \italic " Aug 2012"
1556 @subsubsubheading Footnotes in stand-alone text with custom marks
1558 The syntax of a footnote in stand-alone text with custom marks is
1561 \markup @{ ... \footnote @var{mark} @var{footnote} ... @}
1569 is a markup or string specifying the footnote mark which is used for
1570 marking the reference point. Note that this mark is @emph{not}
1571 inserted automatically before the footnote itself.
1574 is the markup or string specifying the footnote text to use at the
1575 bottom of the page, preceded by the @var{mark}.
1579 Any easy-to-type character such as * or + may be used as a mark, as
1580 shown in @ref{Footnotes in music expressions}. Alteratively, ASCII
1581 aliases may be used (see @ref{ASCII aliases}):
1583 @lilypond[verbatim,quote,ragged-right,papersize=a8]
1585 \paper { #(include-special-characters) }
1586 \header { tagline = ##f }
1589 \footnote "*" \italic "* By me"
1590 "is shown below. It is a recent"
1591 \footnote \super † \concat {
1592 \super † \italic " Aug 2012"
1602 Unicode character codes may also be used to specify marks
1603 (see @ref{Unicode}):
1605 @lilypond[verbatim,quote,ragged-right,papersize=a8]
1607 \header { tagline = ##f }
1610 \footnote \super \char##x00a7 \concat {
1611 \super \char##x00a7 \italic " By me"
1613 "is shown below. It is a recent"
1614 \footnote \super \char##x00b6 \concat {
1615 \super \char##x00b6 \italic " Aug 2012"
1627 @rlearning{Objects and interfaces}.
1630 @ref{ASCII aliases},
1632 @ref{List of special characters},
1637 Internals Reference:
1638 @rinternals{FootnoteEvent},
1639 @rinternals{FootnoteItem},
1640 @rinternals{FootnoteSpanner},
1641 @rinternals{Footnote_engraver}.
1644 Multiple footnotes for the same page can only be stacked, one above
1645 the other; they cannot be printed on the same line.
1647 Footnotes cannot be attached to @code{MultiMeasureRests} or
1648 automatic beams or lyrics.
1650 Footnote marks may collide with staves, @code{\markup} objects, other
1651 footnote marks and annotation lines.
1654 @node Reference to page numbers
1655 @subsection Reference to page numbers
1657 A particular place of a score can be marked using the @code{\label}
1658 command, either at top-level or inside music. This label can then be
1659 referred to in a markup, to get the number of the page where the marked
1660 point is placed, using the @code{\page-ref} markup command.
1662 @lilypond[verbatim,papersize=a8landscape]
1663 \header { tagline = ##f }
1669 \pageBreak \mark A \label #'markA
1673 \markup { The first score begins on page \page-ref #'firstScore "0" "?" }
1674 \markup { Mark A is on page \page-ref #'markA "0" "?" }
1678 The @code{\page-ref} markup command takes three arguments:
1680 @item the label, a scheme symbol, eg. @code{#'firstScore};
1681 @item a markup that will be used as a gauge to estimate the dimensions
1683 @item a markup that will be used in place of the page number if the label
1687 The reason why a gauge is needed is that, at the time markups are
1688 interpreted, the page breaking has not yet occurred, so the page numbers
1689 are not yet known. To work around this issue, the actual markup
1690 interpretation is delayed to a later time; however, the dimensions of
1691 the markup have to be known before, so a gauge is used to decide these
1692 dimensions. If the book has between 10 and 99 pages, it may be "00",
1693 ie. a two digit number.
1704 @node Table of contents
1705 @subsection Table of contents
1706 A table of contents is included using the @code{\markuplist \table-of-contents}
1707 command. The elements which should appear in the table of contents are
1708 entered with the @code{\tocItem} command, which may be used either at
1709 top-level, or inside a music expression.
1712 \markuplist \table-of-contents
1715 \tocItem \markup "First score"
1719 \tocItem \markup "Some particular point in the first score"
1724 \tocItem \markup "Second score"
1732 The markups which are used to format the table of contents are defined
1733 in the @code{\paper} block. The default ones are @code{tocTitleMarkup},
1734 for formatting the title of the table, and @code{tocItemMarkup}, for
1735 formatting the toc elements, composed of the element title and page
1736 number. These variables may be changed by the user:
1740 %% Translate the toc title into French:
1741 tocTitleMarkup = \markup \huge \column {
1742 \fill-line { \null "Table des matières" \null }
1745 %% use larger font size
1746 tocItemMarkup = \markup \large \fill-line {
1747 \fromproperty #'toc:text \fromproperty #'toc:page
1752 Note how the toc element text and page number are referred to in
1753 the @code{tocItemMarkup} definition.
1755 New commands and markups may also be defined to build more elaborated
1758 @item first, define a new markup variable in the @code{\paper} block
1759 @item then, define a music function which aims at adding a toc element
1760 using this markup paper variable.
1763 In the following example, a new style is defined for entering act names
1764 in the table of contents of an opera:
1768 tocActMarkup = \markup \large \column {
1770 \fill-line { \null \italic \fromproperty #'toc:text \null }
1776 #(define-music-function (parser location text) (markup?)
1777 (add-toc-item! 'tocActMarkup text))
1780 @lilypond[line-width=10.0\cm]
1781 \header { tagline = ##f }
1783 tocActMarkup = \markup \large \column {
1785 \fill-line { \null \italic \fromproperty #'toc:text \null }
1791 #(define-music-function (parser location text) (markup?)
1792 (add-toc-item! 'tocActMarkup text))
1795 \markuplist \table-of-contents
1796 \tocAct \markup { Atto Primo }
1797 \tocItem \markup { Coro. Viva il nostro Alcide }
1798 \tocItem \markup { Cesare. Presti omai l'Egizzia terra }
1799 \tocAct \markup { Atto Secondo }
1800 \tocItem \markup { Sinfonia }
1801 \tocItem \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
1806 Dots can be added to fill the line between an item and its page number:
1808 @lilypond[verbatim,line-width=10.0\cm]
1809 \header { tagline = ##f }
1811 tocItemMarkup = \tocItemWithDotsMarkup
1815 \markuplist \table-of-contents
1816 \tocItem \markup { Allegro }
1817 \tocItem \markup { Largo }
1824 @file{ly/toc-init.ly}.
1827 @funindex \table-of-contents
1828 @code{\table-of-contents},
1834 @node Working with input files
1835 @section Working with input files
1838 * Including LilyPond files::
1839 * Different editions from one source::
1840 * Special characters::
1844 @node Including LilyPond files
1845 @subsection Including LilyPond files
1848 @cindex including files
1850 A large project may be split up into separate files. To refer to
1854 \include "otherfile.ly"
1857 The line @code{\include "otherfile.ly"} is equivalent to pasting the
1858 contents of @file{otherfile.ly} into the current file at the place
1859 where the @code{\include} appears. For example, in a large
1860 project you might write separate files for each instrument part
1861 and create a @qq{full score} file which brings together the
1862 individual instrument files. Normally the included file will
1863 define a number of variables which then become available
1864 for use in the full score file. Tagged sections can be
1865 marked in included files to assist in making them usable in
1866 different places in a score, see @ref{Different editions from
1869 Files in the current working directory may be referenced by
1870 specifying just the file name after the @code{\include} command.
1871 Files in other locations may be included by giving either a full
1872 path reference or a relative path reference (but use the UNIX
1873 forward slash, /, rather than the DOS/Windows back slash, \, as the
1874 directory separator.) For example, if @file{stuff.ly} is located
1875 one directory higher than the current working directory, use
1878 \include "../stuff.ly"
1882 or if the included orchestral parts files are all located in a
1883 subdirectory called @file{parts} within the current directory, use
1886 \include "parts/VI.ly"
1887 \include "parts/VII.ly"
1891 Files which are to be included can also contain @code{\include}
1892 statements of their own. By default, these second-level
1893 @code{\include} statements are not interpreted until they have
1894 been brought into the main file, so the file names they specify
1895 must all be relative to the directory containing the main file,
1896 not the directory containing the included file. However,
1897 this behavior can be changed globally by passing the option
1898 @option{-drelative-includes} option at the command line
1899 (or by adding @code{#(ly:set-option 'relative-includes #t)}
1900 at the top of the main input file).
1902 When @code{relative-includes} is set to @code{#t}, the path for each
1903 @code{\include} command will be taken relative to the file containing
1904 that command. This behavior is recommended and it will become the
1905 default behavior in a future version of lilypond.
1907 Files relative to the main directory and files relative to some other
1908 directory may both be @code{\include}d by setting
1909 @code{relative-includes} to @code{#t} or @code{#f} at appropriate
1910 places in the files. For example, if a general library, libA, has
1911 been created which itself uses sub-files which are @code{\include}d
1912 by the entry file of that library, those @code{\include} statements
1913 will need to be preceded by
1914 @code{#(ly:set-option #relative-includes #t)} so they are interpreted
1915 correctly when brought into the main @code{.ly} file, like this:
1926 then the entry file, @code{libA.ly}, will contain
1929 #(ly:set-option 'relative-includes #t)
1933 % return to default setting
1934 #(ly:set-option 'relative-includes #f)
1937 Any @file{.ly} file can then include the entire library simply with
1940 \include "~/libA/libA.ly"
1943 More complex file structures may be devised by switching at
1946 Files can also be included from a directory in a search path
1947 specified as an option when invoking LilyPond from the command
1948 line. The included files are then specified using just their
1949 file name. For example, to compile @file{main.ly} which includes
1950 files located in a subdirectory called @file{parts} by this method,
1951 cd to the directory containing @file{main.ly} and enter
1954 lilypond --include=parts main.ly
1957 and in main.ly write
1965 Files which are to be included in many scores may be placed in
1966 the LilyPond directory @file{../ly}. (The location of this
1967 directory is installation-dependent - see
1968 @rlearning{Other sources of information}). These files can then
1969 be included simply by naming them on an @code{\include} statement.
1970 This is how the language-dependent files like @file{english.ly} are
1973 LilyPond includes a number of files by default when you start
1974 the program. These includes are not apparent to the user, but the
1975 files may be identified by running @code{lilypond --verbose} from
1976 the command line. This will display a list of paths and files that
1977 LilyPond uses, along with much other information. Alternatively,
1978 the more important of these files are discussed in
1979 @rlearning{Other sources of information}. These files may be
1980 edited, but changes to them will be lost on installing a new
1981 version of LilyPond.
1983 Some simple examples of using @code{\include} are shown in
1984 @rlearning{Scores and parts}.
1988 @rlearning{Other sources of information},
1989 @rlearning{Scores and parts}.
1992 If an included file is given a name which is the same as one in
1993 LilyPond's installation files, LilyPond's file from the
1994 installation files takes precedence.
1997 @node Different editions from one source
1998 @subsection Different editions from one source
2000 Several methods can be used to generate different versions of a score
2001 from the same music source. Variables are perhaps the most useful for
2002 combining lengthy sections of music and/or annotation. Tags are more
2003 useful for selecting one section from several alternative shorter
2004 sections of music, and can also be used for splicing pieces of music
2005 together at different points.
2007 Whichever method is used, separating the notation from the structure of
2008 the score will make it easier to change the structure while leaving the
2014 * Using global settings::
2017 @node Using variables
2018 @unnumberedsubsubsec Using variables
2020 @cindex variables, use of
2022 If sections of the music are defined in variables they can be
2023 reused in different parts of the score, see @rlearning{Organizing
2024 pieces with variables}. For example, an @notation{a cappella}
2025 vocal score frequently includes a piano reduction of the parts
2026 for rehearsal purposes which is identical to the vocal music, so
2027 the music need be entered only once. Music from two variables
2028 may be combined on one staff, see @ref{Automatic part combining}.
2031 @lilypond[verbatim,quote]
2032 sopranoMusic = \relative c'' { a4 b c b8( a) }
2033 altoMusic = \relative g' { e4 e e f }
2034 tenorMusic = \relative c' { c4 b e d8( c) }
2035 bassMusic = \relative c' { a4 gis a d, }
2036 allLyrics = \lyricmode {King of glo -- ry }
2038 \new Staff = "Soprano" \sopranoMusic
2039 \new Lyrics \allLyrics
2040 \new Staff = "Alto" \altoMusic
2041 \new Lyrics \allLyrics
2042 \new Staff = "Tenor" {
2046 \new Lyrics \allLyrics
2047 \new Staff = "Bass" {
2051 \new Lyrics \allLyrics
2054 \set Staff.printPartCombineTexts = ##f
2060 \set Staff.printPartCombineTexts = ##f
2070 Separate scores showing just the vocal parts or just the piano
2071 part can be produced by changing just the structural statements,
2072 leaving the musical notation unchanged.
2074 For lengthy scores, the variable definitions may be placed in
2075 separate files which are then included, see @ref{Including
2079 @unnumberedsubsubsec Using tags
2082 @funindex \keepWithTag
2083 @funindex \removeWithTag
2084 @funindex \pushToTag
2085 @funindex \appendToTag
2087 @cindex keep tagged music
2088 @cindex remove tagged music
2089 @cindex splice into tagged music
2091 The @code{\tag #'@var{partA}} command marks a music expression
2092 with the name @var{partA}.
2093 Expressions tagged in this way can be selected or filtered out by
2094 name later, using either @code{\keepWithTag #'@var{name}} or
2095 @code{\removeWithTag #'@var{name}}. The result of applying these filters
2096 to tagged music is as follows:
2097 @multitable @columnfractions .5 .5
2101 Tagged music preceded by @code{\keepWithTag #'@var{name}} or
2102 @code{\keepWithTag #'(@var{name1} @var{name2}@dots{})}
2103 @tab Untagged music and music tagged with any of the given tag
2105 music tagged with any other tag name is excluded.
2107 Tagged music preceded by @code{\removeWithTag #'@var{name}} or
2108 @code{\removeWithTag #'(@var{name1} @var{name2}@dots{})}
2109 @tab Untagged music and music not tagged with any of the given tag names
2110 is included; music tagged with any of the given tag names is
2113 Tagged music not preceded by either @code{\keepWithTag} or
2114 @code{\removeWithTag}
2115 @tab All tagged and untagged music is included.
2118 The arguments of the @code{\tag}, @code{\keepWithTag} and
2119 @code{\removeWithTag} commands should be a symbol
2120 (such as @code{#'score} or @code{#'part}), followed
2121 by a music expression.
2123 In the following example, we see two versions of a piece of music,
2124 one showing trills with the usual notation, and one with trills
2125 explicitly expanded:
2127 @lilypond[verbatim,quote]
2128 music = \relative g' {
2130 \tag #'trills { d8.\trill }
2131 \tag #'expand { \repeat unfold 3 { e32 d } }
2136 \keepWithTag #'trills \music
2139 \keepWithTag #'expand \music
2144 Alternatively, it is sometimes easier to exclude sections of music:
2146 @lilypond[verbatim,quote]
2147 music = \relative g' {
2149 \tag #'trills { d8.\trill }
2150 \tag #'expand {\repeat unfold 3 { e32 d } }
2155 \removeWithTag #'expand
2159 \removeWithTag #'trills
2164 Tagged filtering can be applied to articulations, texts, etc. by
2168 -\tag #'@var{your-tag}
2171 to an articulation. For example, this would define a note with a
2172 conditional fingering indication and a note with a conditional
2177 c1-\tag #'warn ^"Watch!"
2180 Multiple tags may be placed on expressions with multiple
2181 @code{\tag} entries, or by combining multiple tags into one symbol
2184 @lilypond[quote,verbatim]
2185 music = \relative c'' {
2186 \tag #'a \tag #'both { a4 a a a }
2187 \tag #'(b both) { b4 b b b }
2190 \keepWithTag #'a \music
2191 \keepWithTag #'b \music
2192 \keepWithTag #'both \music
2196 Multiple @code{\removeWithTag} filters may be applied to a single
2197 music expression to remove several differently named tagged
2198 sections. Alternatively, you can use a single
2199 @code{\removeWithTag} with a list of tags.
2201 @lilypond[verbatim,quote]
2202 music = \relative c'' {
2203 \tag #'A { a4 a a a }
2204 \tag #'B { b4 b b b }
2205 \tag #'C { c4 c c c }
2206 \tag #'D { d4 d d d }
2212 \removeWithTag #'(B C)
2217 Two or more @code{\keepWithTag} filters applied to a single music
2218 expression will cause @emph{all} tagged sections to be removed, as
2219 the first filter will remove all tagged sections except the one
2220 named, and the second filter will remove even that tagged section.
2221 Usually you would rather want to use a single @code{\keepWithTag}
2222 command with a list of multiple tags: this will only remove tagged
2223 sections not given in @emph{any} of the tags.
2225 Sometimes you want to splice some music at a particular place in an
2226 existing music expression. You can use @code{\pushToTag} and
2227 @code{\appendToTag} for adding material at the front or end of the
2228 @code{elements} of an existing music construct. Not every music
2229 construct has @code{elements}, but sequential and simultaneous music are
2232 @lilypond[verbatim,quote]
2233 test = { \tag #'here { \tag #'here <<c''>> } }
2236 \pushToTag #'here c'
2237 \pushToTag #'here e'
2238 \pushToTag #'here g' \test
2239 \appendToTag #'here c'
2240 \appendToTag #'here e'
2241 \appendToTag #'here g' \test
2245 Both commands get a tag, the material to splice in at every occurence of
2246 the tag, and the tagged expression. The commands make sure to
2247 copy everything that they change so that the original @code{\test}
2248 retains its meaning.
2252 @rlearning{Organizing pieces with variables}.
2255 @ref{Automatic part combining},
2256 @ref{Including LilyPond files}.
2259 Calling @code{\relative} on a music expression obtained by filtering
2260 music through @code{\keepWithTag} or @code{\removeWithTag} might cause
2261 the octave relations to change, as only the pitches actually
2262 remaining in the filtered expression will be considered. Applying
2263 @code{\relative} first, before @code{\keepWithTag} or
2264 @code{\removeWithTag}, avoids this danger as @code{\relative} then
2265 acts on all the pitches as-input.
2268 @node Using global settings
2269 @unnumberedsubsubsec Using global settings
2271 @cindex include-settings
2273 Global settings can be included from a separate file:
2276 lilypond -dinclude-settings=MY_SETTINGS.ly MY_SCORE.ly
2279 Groups of settings such as page size, font or type face can be stored
2280 in separate files. This allows different editions from the same score
2281 as well as standard settings to be applied to many scores, simply by
2282 specifying the proper settings file.
2284 This technique also works well with the use of style sheets, as
2285 discussed in @rlearning{Style sheets}.
2289 @rlearning{Organizing pieces with variables},
2290 @rlearning{Style sheets}.
2293 @ref{Including LilyPond files}.
2296 @node Special characters
2297 @subsection Special characters
2299 @cindex special characters
2300 @cindex non-ASCII characters
2310 @unnumberedsubsubsec Text encoding
2314 LilyPond uses the character repertoire defined by the Unicode
2315 consortium and ISO/IEC 10646. This defines a unique name and
2316 code point for the character sets used in virtually all modern
2317 languages and many others too. Unicode can be implemented using
2318 several different encodings. LilyPond uses the UTF-8 encoding
2319 (UTF stands for Unicode Transformation Format) which represents
2320 all common Latin characters in one byte, and represents other
2321 characters using a variable length format of up to four bytes.
2323 The actual appearance of the characters is determined by the
2324 glyphs defined in the particular fonts available - a font defines
2325 the mapping of a subset of the Unicode code points to glyphs.
2326 LilyPond uses the Pango library to layout and render multi-lingual
2329 LilyPond does not perform any input-encoding conversions. This
2330 means that any text, be it title, lyric text, or musical
2331 instruction containing non-ASCII characters, must be encoded in
2332 UTF-8. The easiest way to enter such text is by using a
2333 Unicode-aware editor and saving the file with UTF-8 encoding. Most
2334 popular modern editors have UTF-8 support, for example, vim, Emacs,
2335 jEdit, and GEdit do. All MS Windows systems later than NT use
2336 Unicode as their native character encoding, so even Notepad can
2337 edit and save a file in UTF-8 format. A more functional
2338 alternative for Windows is BabelPad.
2340 If a LilyPond input file containing a non-ASCII character is not
2341 saved in UTF-8 format the error message
2344 FT_Get_Glyph_Name () error: invalid argument
2349 Here is an example showing Cyrillic, Hebrew and Portuguese
2353 %c No verbatim here as the code does not display correctly in PDF
2355 bulgarian = \lyricmode {
2356 Жълтата дюля беше щастлива, че пухът, който цъфна, замръзна като гьон.
2360 hebrew = \lyricmode {
2361 זה כיף סתם לשמוע איך תנצח קרפד עץ טוב בגן.
2365 portuguese = \lyricmode {
2366 à vo -- cê uma can -- ção legal
2372 \addlyrics { \bulgarian }
2373 \addlyrics { \hebrew }
2374 \addlyrics { \portuguese }
2379 @unnumberedsubsubsec Unicode
2383 To enter a single character for which the Unicode code point is
2384 known but which is not available in the editor being used, use
2385 either @code{\char ##xhhhh} or @code{\char #dddd} within a
2386 @code{\markup} block, where @code{hhhh} is the hexadecimal code for
2387 the character required and @code{dddd} is the corresponding decimal
2388 value. Leading zeroes may be omitted, but it is usual to specify
2389 all four characters in the hexadecimal representation. (Note that
2390 the UTF-8 encoding of the code point should @emph{not} be used
2391 after @code{\char}, as UTF-8 encodings contain extra bits indicating
2392 the number of octets.) Unicode code charts and a character name
2393 index giving the code point in hexadecimal for any character can be
2394 found on the Unicode Consortium website,
2395 @uref{http://www.unicode.org/}.
2397 For example, @code{\char ##x03BE} and @code{\char #958} would both
2398 enter the Unicode U+03BE character, which has the Unicode name
2399 @qq{Greek Small Letter Xi}.
2401 Any Unicode code point may be entered in this way and if all special
2402 characters are entered in this format it is not necessary to save
2403 the input file in UTF-8 format. Of course, a font containing all
2404 such encoded characters must be installed and available to LilyPond.
2406 The following example shows Unicode hexadecimal values being entered
2407 in four places -- in a rehearsal mark, as articulation text, in
2408 lyrics and as stand-alone text below the score:
2410 @lilypond[quote,verbatim]
2413 c1 \mark \markup { \char ##x03EE }
2414 c1_\markup { \tiny { \char ##x03B1 " to " \char ##x03C9 } }
2416 \addlyrics { O \markup { \concat { Ph \char ##x0153 be! } } }
2418 \markup { "Copyright 2008--2012" \char ##x00A9 }
2421 @cindex copyright sign
2423 To enter the copyright sign in the copyright notice use:
2427 copyright = \markup @{ \char ##x00A9 "2008" @}
2433 @unnumberedsubsubsec ASCII aliases
2435 A list of ASCII aliases for special characters can be included:
2437 @lilypond[quote,verbatim]
2439 #(include-special-characters)
2442 \markup "&flqq; – &OE;uvre incomplète… &frqq;"
2445 \new Staff { \repeat unfold 9 a'4 }
2447 This is al -- so wor -- kin'~in ly -- rics: –_&OE;…
2452 "The replacement can be disabled:"
2453 "– &OE; …"
2454 \override #'(replacement-alist . ()) "– &OE; …"
2458 You can also make your own aliases, either globally:
2460 @lilypond[quote,verbatim]
2462 #(add-text-replacements!
2463 '(("100" . "hundred")
2464 ("dpi" . "dots per inch")))
2466 \markup "A 100 dpi."
2471 @lilypond[quote,verbatim]
2472 \markup \replace #'(("100" . "hundred")
2473 ("dpi" . "dots per inch")) "A 100 dpi."
2478 @ref{List of special characters}.
2481 @file{ly/text-replacements.ly}.
2484 @node Controlling output
2485 @section Controlling output
2488 * Extracting fragments of music::
2489 * Skipping corrected music::
2490 * Alternative output formats::
2491 * Replacing the notation font::
2494 @node Extracting fragments of music
2495 @subsection Extracting fragments of music
2497 It is possible to quote small fragments of a large score directly from
2498 the output. This can be compared to clipping a piece of a paper score
2501 This is done by defining the measures that need to be cut out
2502 separately. For example, including the following definition
2510 (make-rhythmic-location 5 1 2)
2511 (make-rhythmic-location 7 3 4)))
2516 will extract a fragment starting halfway the fifth measure, ending in
2517 the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note
2518 in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7.
2520 More clip regions can be defined by adding more pairs of
2521 rhythmic-locations to the list.
2523 In order to use this feature, LilyPond must be invoked with
2524 @option{-dclip-systems}. The clips are output as EPS files, and are
2525 converted to PDF and PNG if these formats are switched on as well.
2527 For more information on output formats, see @rprogram{Invoking lilypond}.
2529 @node Skipping corrected music
2530 @subsection Skipping corrected music
2533 @funindex skipTypesetting
2534 @funindex showFirstLength
2535 @funindex showLastLength
2537 When entering or copying music, usually only the music near the end (where
2539 are adding notes) is interesting to view and correct. To speed up
2540 this correction process, it is possible to skip typesetting of all but
2541 the last few measures. This is achieved by putting
2544 showLastLength = R1*5
2549 in your source file. This will render only the last 5 measures
2550 (assuming 4/4 time signature) of every @code{\score} in the input
2551 file. For longer pieces, rendering only a small part is often an order
2552 of magnitude quicker than rendering it completely. When working on the
2553 beginning of a score you have already typeset (e.g. to add a new part),
2554 the @code{showFirstLength} property may be useful as well.
2556 Skipping parts of a score can be controlled in a more fine-grained
2557 fashion with the property @code{Score.skipTypesetting}. When it is
2558 set, no typesetting is performed at all.
2560 This property is also used to control output to the MIDI file. Note that
2561 it skips all events, including tempo and instrument changes. You have
2564 @lilypond[quote,relative=2,ragged-right,verbatim]
2566 \set Score.skipTypesetting = ##t
2568 \set Score.skipTypesetting = ##f
2572 In polyphonic music, @code{Score.skipTypesetting} will affect all
2573 voices and staves, saving even more time.
2575 @node Alternative output formats
2576 @subsection Alternative output formats
2578 @cindex scalable vector graphics output
2580 @cindex encapsulated postscript output
2583 The default output formats for the printed score are Portable
2584 Document Format (PDF) and PostScript (PS). Scalable Vector
2585 Graphics (SVG), Encapsulated PostScript (EPS) and Portable
2586 Network Graphics (PNG) output formats are also available through
2587 command line options, see
2588 @rprogram{Basic command line options for LilyPond}.
2591 @node Replacing the notation font
2592 @subsection Replacing the notation font
2594 Gonville is an alternative to the Feta font used in LilyPond and can
2597 @uref{http://www.chiark.greenend.org.uk/~sgtatham/gonville/ ,http://www.chiark.greenend.org.uk/~sgtatham/gonville/}
2600 Here are a few sample bars of music set in Gonville:
2602 @c NOTE: these images are a bit big, but that's important
2603 @c for the font comparison. -gp
2604 @sourceimage{Gonville_after,15cm,,}
2606 Here are a few sample bars of music set in LilyPond's Feta font:
2608 @sourceimage{Gonville_before,15cm,,}
2610 @subsubheading Installation Instructions for MacOS
2612 Download and extract the zip file. Copy the @code{lilyfonts}
2613 directory to @file{@var{SHARE_DIR}/lilypond/current}; for more
2614 information, see @rlearning{Other sources of information}. Rename the
2615 existing @code{fonts} directory to @code{fonts_orig} and the
2616 @code{lilyfonts} directory to @code{fonts}. To revert back to Feta,
2617 reverse the process.
2621 @rlearning{Other sources of information}.
2624 Gonville cannot be used to typeset @q{Ancient Music} notation and it is
2625 likely newer glyphs in later releases of LilyPond may not exist in the
2626 Gonville font family. Please refer to the author's website for more
2627 information on these and other specifics, including licensing of
2632 @section MIDI output
2637 MIDI (Musical Instrument Digital Interface) is a standard for
2638 connecting and controlling digital instruments. A MIDI file is a
2639 series of notes in a number of tracks. It is not an actual
2640 sound file; you need special software to translate between the
2641 series of notes and actual sounds.
2643 Pieces of music can be converted to MIDI files, so you can listen to
2644 what was entered. This is convenient for checking the music; octaves
2645 that are off or accidentals that were mistyped stand out very much
2646 when listening to the MIDI output.
2648 Standard MIDI output is somewhat crude; optionally, an enhanced and
2649 more realistic MIDI output is available by means of
2650 @ref{The Articulate script}.
2652 The MIDI output allocates a channel for each staff, and reserves channel
2653 10 for drums. There are only 16 MIDI channels per device, so if the
2654 score contains more than 15 staves, MIDI channels will be reused.
2657 * Creating MIDI files::
2658 * MIDI Instruments::
2660 * What goes into the MIDI output?::
2662 * Controlling MIDI dynamics::
2663 * Percussion in MIDI::
2664 * The Articulate script::
2667 @node Creating MIDI files
2668 @subsection Creating MIDI files
2670 To create a MIDI output file from a LilyPond input file, add a
2671 @code{\midi} block to a score, for example,
2680 If there is a @code{\midi} block in a @code{\score} with no
2681 @code{\layout} block, only MIDI output will be produced. When
2682 notation is needed too, a @code{\layout} block must also be
2693 Pitches, rhythms, ties, dynamics, and tempo changes are interpreted
2694 and translated correctly to the MIDI output. Dynamic marks,
2695 crescendi and decrescendi translate into MIDI volume levels.
2696 Dynamic marks translate to a fixed fraction of the available MIDI
2697 volume range. Crescendi and decrescendi make the volume vary
2698 linearly between their two extremes. The effect of dynamic markings
2699 on the MIDI output can be removed completely, see @ref{MIDI block}.
2701 The initial tempo and later tempo changes can be specified
2702 with the @code{\tempo} command within the music notation. These
2703 are reflected in tempo changes in the MIDI output. This command
2704 will normally result in the metronome mark being printed, but this
2705 can be suppressed, see @ref{Metronome marks}. An alternative way
2706 of specifying the initial or overall MIDI tempo is described below,
2707 see @ref{MIDI block}.
2709 Due to some limitations on Windows, the default extension for
2710 MIDI files on Windows is @code{.mid}. Other operating systems still
2711 use the extension @code{.midi}. If a different extension is preferred,
2712 insert the following line at the top-level of the input file,
2713 before the start of any @code{\book}, @code{\bookpart} or @code{\score} blocks:
2716 #(ly:set-option 'midi-extension "midi")
2719 The line above will set the default extension for MIDI files to
2722 Alternatively, this option can also be supplied on the command line:
2725 lilypond … -dmidi-extension=midi lilyFile.ly
2731 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
2732 {changing-midi-output-to-one-channel-per-voice.ly}
2736 @c In 2.11 the following no longer seems to be a problem -td
2738 Unterminated (de)crescendos will not render properly in the midi file,
2739 resulting in silent passages of music. The workaround is to explicitly
2740 terminate the (de)crescendo. For example,
2747 will not work properly but
2750 @{ a4\< b c d\!\f @}
2757 Changes in the MIDI volume take place only on starting a note, so
2758 crescendi and decrescendi cannot affect the volume of a
2761 Not all midi players correctly handle tempo changes in the midi
2762 output. Players that are known to work include MS Windows Media
2763 Player and @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
2765 @node MIDI Instruments
2766 @subsection MIDI Instruments
2768 @cindex instrument names
2769 @cindex MIDI, instruments
2770 @funindex Staff.midiInstrument
2772 The MIDI instrument to be used is specified by setting the
2773 @code{Staff.midiInstrument} property to the instrument name.
2774 The name should be chosen from the list in @ref{MIDI instruments}.
2778 \set Staff.midiInstrument = #"glockenspiel"
2784 \new Staff \with @{midiInstrument = #"cello"@} @{
2789 If the selected instrument does not exactly match an instrument from
2790 the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
2794 @subsection MIDI block
2797 A @code{\midi} block must appear within a score block if MIDI output
2798 is required. It is analogous to the layout block, but somewhat
2799 simpler. Often, the @code{\midi} block is left empty, but it
2800 can contain context rearrangements, new context definitions or code
2801 to set the values of properties. For example, the following will
2802 set the initial tempo exported to a MIDI file without causing a tempo
2803 indication to be printed:
2814 In this example the tempo is set to 72 quarter note
2815 beats per minute. @code{\tempo} is actually a music command for
2816 setting properties during the interpretation of music: in the
2817 context of output definitions like a @code{\midi} block, as a matter of
2818 courtesy those are reinterpreted as if they were context modifications.
2820 @cindex MIDI context definitions
2822 Context definitions follow precisely the same syntax as those
2823 within a @code{\layout} block. Translation modules for sound are
2824 called performers. The contexts for MIDI output are defined in
2825 @file{../ly/performer-init.ly},
2826 see @rlearning{Other sources of information}.
2827 For example, to remove the effect of dynamics
2828 from the MIDI output, insert the following lines in the
2829 @code{\midi@{ @}} block.
2836 \remove "Dynamic_performer"
2841 MIDI output is created only when a @code{\midi} block is included
2842 within a score block defined with a @code{\score} command.
2846 @{ @dots{}notes@dots{} @}
2851 @node What goes into the MIDI output?
2852 @subsection What goes into the MIDI output?
2854 @c TODO Check grace notes - timing is suspect?
2857 * Supported in MIDI::
2858 * Unsupported in MIDI::
2861 @node Supported in MIDI
2862 @unnumberedsubsubsec Supported in MIDI
2864 @cindex Pitches in MIDI
2865 @cindex MIDI, Pitches
2866 @cindex Quarter tones in MIDI
2867 @cindex MIDI, quarter tones
2868 @cindex Microtones in MIDI
2869 @cindex MIDI, microtones
2870 @cindex Chord names in MIDI
2871 @cindex MIDI, chord names
2872 @cindex Rhythms in MIDI
2873 @cindex MIDI, Rhythms
2874 @cindex Articlulate scripts
2875 @cindex MIDI, articulations
2876 @cindex articulations in MIDI
2877 @cindex trills in MIDI
2878 @cindex turns in MIDI
2879 @cindex rallentando in MIDI
2880 @cindex accelerando in MIDI
2883 The following items of notation are reflected in the MIDI output:
2887 @item Microtones (See @ref{Accidentals}. Rendering needs a
2888 player that supports pitch bend.)
2889 @item Chords entered as chord names
2890 @item Rhythms entered as note durations, including tuplets
2891 @item Tremolos entered without @q{@code{:}[@var{number}]}
2894 @item Crescendi, decrescendi over multiple notes
2895 @item Tempo changes entered with a tempo marking
2899 Using @ref{The Articulate script}, a number of items are added to the
2903 @item Articulations (slurs, staccato, etc)
2905 @item Rallentando and accelerando
2909 @node Unsupported in MIDI
2910 @unnumberedsubsubsec Unsupported in MIDI
2912 @c TODO index as above
2914 The following items of notation have no effect on the MIDI output,
2915 unless you use @ref{The Articulate script}:
2918 @item Rhythms entered as annotations, e.g. swing
2919 @item Tempo changes entered as annotations with no tempo marking
2920 @item Staccato and other articulations and ornamentations
2921 @item Slurs and Phrasing slurs
2922 @item Crescendi, decrescendi over a single note
2923 @item Tremolos entered with @q{@code{:}[@var{number}]}
2925 @item Microtonal chords
2929 @node Repeats in MIDI
2930 @subsection Repeats in MIDI
2932 @cindex repeats in MIDI
2933 @funindex \unfoldRepeats
2935 With a few minor additions, all types of repeats can be represented
2936 in the MIDI output. This is achieved by applying the
2937 @code{\unfoldRepeats} music function. This function changes all
2938 repeats to unfold repeats.
2940 @lilypond[quote,verbatim]
2942 \repeat tremolo 8 { c'32 e' }
2943 \repeat percent 2 { c''8 d'' }
2944 \repeat volta 2 { c'4 d' e' f' }
2953 In scores containing multiple voices, unfolding of repeats in MIDI
2954 output will only occur correctly if @emph{each} voice contains fully
2955 notated repeat indications.
2957 When creating a score file using @code{\unfoldRepeats} for MIDI,
2958 it is necessary to make two @code{\score} blocks: one for MIDI
2959 (with unfolded repeats) and one for notation (with volta, tremolo,
2960 and percent repeats). For example,
2968 \unfoldRepeats @var{..music..}
2973 @node Controlling MIDI dynamics
2974 @subsection Controlling MIDI dynamics
2976 MIDI dynamics are implemented by the Dynamic_performer which lives
2977 by default in the Voice context. It is possible to control the
2978 overall MIDI volume, the relative volume of dynamic markings and
2979 the relative volume of different instruments.
2983 * Overall MIDI volume::
2984 * Equalizing different instruments (i)::
2985 * Equalizing different instruments (ii)::
2989 @unnumberedsubsubsec Dynamic marks
2991 Dynamic marks are translated to a fixed fraction of the available
2992 MIDI volume range. The default fractions range from 0.25 for
2993 @notation{ppppp} to 0.95 for @notation{fffff}. The set of dynamic
2994 marks and the associated fractions can be seen in
2995 @file{../scm/midi.scm}, see @rlearning{Other sources of information}.
2996 This set of fractions may be changed or extended by providing a
2997 function which takes a dynamic mark as its argument and returns the
2998 required fraction, and setting
2999 @code{Score.dynamicAbsoluteVolumeFunction} to this function.
3001 For example, if a @notation{rinforzando} dynamic marking,
3002 @code{\rfz}, is required, this will not by default
3003 have any effect on the MIDI volume, as this dynamic marking is not
3004 included in the default set. Similarly, if a new dynamic marking
3005 has been defined with @code{make-dynamic-script} that too will not
3006 be included in the default set. The following example shows how the
3007 MIDI volume for such dynamic markings might be added. The Scheme
3008 function sets the fraction to 0.9 if a dynamic mark of rfz is
3009 found, or calls the default function otherwise.
3011 @lilypond[verbatim,quote]
3012 #(define (myDynamics dynamic)
3013 (if (equal? dynamic "rfz")
3015 (default-dynamic-absolute-volume dynamic)))
3019 \set Staff.midiInstrument = #"cello"
3020 \set Score.dynamicAbsoluteVolumeFunction = #myDynamics
3032 Alternatively, if the whole table of fractions needs to be
3033 redefined, it would be better to use the
3034 @notation{default-dynamic-absolute-volume} procedure in
3035 @file{../scm/midi.scm} and the associated table as a model.
3036 The final example in this section shows how this might be done.
3038 @node Overall MIDI volume
3039 @unnumberedsubsubsec Overall MIDI volume
3041 The minimum and maximum overall volume of MIDI dynamic markings is
3042 controlled by setting the properties @code{midiMinimumVolume} and
3043 @code{midiMaximumVolume} at the @code{Score} level. These properties
3044 have an effect only at the start of a voice and on dynamic marks. The
3045 fraction corresponding to each dynamic mark is modified with this
3049 midiMinimumVolume + (midiMaximumVolume - midiMinimumVolume) * fraction
3052 In the following example the dynamic range of the overall MIDI
3053 volume is limited to the range 0.2 - 0.5.
3055 @lilypond[verbatim,quote]
3061 \set Staff.midiInstrument = #"flute"
3062 \new Voice \relative c''' {
3070 \set Staff.midiInstrument = #"clarinet"
3071 \new Voice \relative c'' {
3083 midiMinimumVolume = #0.2
3084 midiMaximumVolume = #0.5
3090 @node Equalizing different instruments (i)
3091 @unnumberedsubsubsec Equalizing different instruments (i)
3093 If the minimum and maximum MIDI volume properties are set in
3094 the @code{Staff} context the relative volumes of the MIDI
3095 instruments can be controlled. This gives a basic instrument
3096 equalizer, which can enhance the quality of the MIDI output
3099 In this example the volume of the clarinet is reduced relative
3100 to the volume of the flute.
3102 @lilypond[verbatim,quote]
3108 \set Staff.midiInstrument = #"flute"
3109 \set Staff.midiMinimumVolume = #0.7
3110 \set Staff.midiMaximumVolume = #0.9
3111 \new Voice \relative c''' {
3119 \set Staff.midiInstrument = #"clarinet"
3120 \set Staff.midiMinimumVolume = #0.3
3121 \set Staff.midiMaximumVolume = #0.6
3122 \new Voice \relative c'' {
3137 @node Equalizing different instruments (ii)
3138 @unnumberedsubsubsec Equalizing different instruments (ii)
3140 If the MIDI minimum and maximum volume properties are not set
3141 LilyPond will, by default, apply a small degree of equalization
3142 to a few instruments. The instruments and the equalization
3143 applied are shown in the table @notation{instrument-equalizer-alist}
3144 in @file{../scm/midi.scm}.
3146 This basic default equalizer can be replaced by setting
3147 @code{instrumentEqualizer} in the @code{Score} context to a new
3148 Scheme procedure which accepts a MIDI instrument name as its only
3149 argument and returns a pair of fractions giving the minimum and
3150 maximum volumes to be applied to that instrument. This replacement
3151 is done in the same way as shown for resetting the
3152 @code{dynamicAbsoluteVolumeFunction} at the start of this section.
3153 The default equalizer, @notation{default-instrument-equalizer}, in
3154 @file{../scm/midi.scm} shows how such a procedure might be written.
3156 The following example sets the relative flute and clarinet volumes
3157 to the same values as the previous example.
3159 @lilypond[verbatim,quote]
3160 #(define my-instrument-equalizer-alist '())
3162 #(set! my-instrument-equalizer-alist
3165 ("flute" . (0.7 . 0.9))
3166 ("clarinet" . (0.3 . 0.6)))
3167 my-instrument-equalizer-alist))
3169 #(define (my-instrument-equalizer s)
3170 (let ((entry (assoc s my-instrument-equalizer-alist)))
3179 \set Score.instrumentEqualizer = #my-instrument-equalizer
3180 \set Staff.midiInstrument = #"flute"
3181 \new Voice \relative c''' {
3189 \set Staff.midiInstrument = #"clarinet"
3190 \new Voice \relative c'' {
3205 @c Delete when satisfied this is adequately covered elsewhere -td
3207 @n ode Microtones in MIDI
3208 @s ubsection Microtones in MIDI
3210 @cindex microtones in MIDI
3212 Microtones consisting of half sharps and half flats are exported
3213 to the MIDI file and render correctly in MIDI players which support
3214 pitch bending. See @ref{Note names in other languages}. Here is
3215 an example showing all the half sharps and half flats. It can be
3216 copied out and compiled to test microtones in your MIDI player.
3218 @lilypond[verbatim,quote]
3235 @node Percussion in MIDI
3236 @subsection Percussion in MIDI
3238 Percussion instruments are generally notated in a @code{DrumStaff}
3239 context and when notated in this way they are outputted correctly
3240 to MIDI channel@tie{}10, but some pitched percussion instruments,
3241 like the xylophone, marimba, vibraphone, timpani, etc., are
3242 treated like @qq{normal} instruments and music for these instruments
3243 should be entered in a normal @code{Staff} context, not a
3244 @code{DrumStaff} context, to obtain the correct MIDI output.
3246 Some non-pitched percussion sounds included in the general MIDI
3247 standard, like melodic tom, taiko drum, synth drum, etc., cannot
3248 be reached via MIDI channel@tie{}10, so the notation for such
3249 instruments should also be entered in a normal @code{Staff}
3250 context, using suitable normal pitches.
3252 Many percussion instruments are not included in the general MIDI
3253 standard, e.g. castanets. The easiest, although unsatisfactory,
3254 method of producing some MIDI output when writing for such
3255 instruments is to substitute the nearest sound from the standard
3258 @c TODO Expand with examples, and any other issues
3262 Because the general MIDI standard does not contain rim shots, the
3263 sidestick is used for this purpose instead.
3265 @node The Articulate script
3266 @subsection The Articulate script
3268 A more realistic MIDI output is possible when using the Articulate
3269 script. It tries to take articulations (slurs, staccato, etc) into
3270 account, by replacing notes with sequential music of suitably
3271 time-scaled note plus skip. It also tries to unfold trills turns
3272 etc., and take rallentando and accelerando into account.
3274 To use the Articulate script, you have to include it at the top of
3278 \include "articulate.ly"
3281 and in the @code{\score} section do
3284 \unfoldRepeats \articulate <<
3285 all the rest of the score...
3289 After altering your input file this way, the visual output is heavily
3290 altered, but the standard @code{\midi} block will produce a better
3293 Although not essential for the Articulate script to work, you may want
3294 to insert the @code{\unfoldRepeats} command as it appears in the
3295 example shown above as it enables performing abbreviatures such as
3300 Articulate shortens chords and some music (esp. organ music) could
3304 @node Extracting musical information
3305 @section Extracting musical information
3307 In addition to creating graphical output and MIDI, LilyPond can
3308 display musical information as text.
3311 * Displaying LilyPond notation::
3312 * Displaying scheme music expressions::
3313 * Saving music events to a file::
3316 @node Displaying LilyPond notation
3317 @subsection Displaying LilyPond notation
3319 @funindex \displayLilyMusic
3320 Displaying a music expression in LilyPond notation can be
3321 done with the music function @code{\displayLilyMusic}. To see the
3322 output, you will typically want to call LilyPond using the command
3327 \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
3334 @{ a,4 cis e fis g @}
3337 By default, LilyPond will print these messages to the console
3338 along with all the other LilyPond compilation messages. To split
3339 up these messages and save the results of @code{\display@{STUFF@}},
3340 redirect the output to a file.
3343 lilypond file.ly >display.txt
3347 Note that Lilypond does not just display the music expression, but
3348 also interprets it (since @code{\displayLilyMusic} returns it in
3349 addition to displaying it). This is convenient since you can just
3350 insert @code{\displayLilyMusic} into existing music in order to get
3351 information about it. If you don't actually want Lilypond to
3352 interpret the displayed music as well as display it, use @code{\void}
3353 in order to have it ignored:
3357 \void \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
3362 @node Displaying scheme music expressions
3363 @subsection Displaying scheme music expressions
3365 See @rextend{Displaying music expressions}.
3368 @node Saving music events to a file
3369 @subsection Saving music events to a file
3371 Music events can be saved to a file on a per-staff basis by
3372 including a file in your main score.
3375 \include "event-listener.ly"
3378 This will create file(s) called @file{FILENAME-STAFFNAME.notes} or
3379 @file{FILENAME-unnamed-staff.notes} for each staff. Note that if
3380 you have multiple unnamed staves, the events for all staves will
3381 be mixed together in the same file. The output looks like this:
3384 0.000 note 57 4 p-c 2 12
3386 0.250 note 62 4 p-c 7 12
3387 0.500 note 66 8 p-c 9 12
3388 0.625 note 69 8 p-c 14 12
3393 The syntax is a tab-delimited line, with two fixed fields on each
3394 line followed by optional parameters.
3397 @var{time} @var{type} @var{...params...}
3400 This information can easily be read into other programs such as
3401 python scripts, and can be very useful for researchers wishing to
3402 perform musical analysis or playback experiments with LilyPond.
3407 Not all lilypond music events are supported by
3408 @file{event-listener.ly}. It is intended to be a well-crafted
3409 @qq{proof of concept}. If some events that you want to see are
3410 not included, copy @file{event-listener.ly} into your lilypond
3411 directory and modify the file so that it outputs the information