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 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 two types of titling areas are provided: @emph{Bookpart Titles} at
552 the beginning of each bookpart and @emph{Score Titles} at the
553 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}). Both Bookpart
559 Titles and Score Titles can contain the same fields, although by
560 default the fields in Score Titles are limited to @code{piece} and
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 Bookpart Title is derived from fields set at the top of the input
593 file, modified by fields set in the @code{\book} block, and further
594 modified by fields set in the @code{\bookpart} block. The resulting
595 values are used to print the Bookpart Title for that bookpart.
598 A Score Title is derived from fields set at the top of the input
599 file, modified by fields set in the @code{\book} block, further
600 modified by fields set in the @code{\bookpart} block and finally
601 modified by fields set in the @code{\score} block. The resulting
602 values are used to print the Score Title for that score. Note,
603 though, that only @code{piece} and @code{opus} fields are printed
604 by default in Score Titles unless the @code{\paper} variable,
605 @code{print-all-headers}, is set to @code{#t}.
609 @warning{Remember when placing a @bs{}@code{header} block inside a
610 @bs{}@code{score} block, that the music expression must come before the
611 @bs{}@code{header} block.}
613 It is not necessary to provide @code{\header} blocks in all four
614 places: any or even all of them may be omitted. Similarly, simple
615 input files may omit the @code{\book} and @code{\bookpart} blocks,
616 leaving them to be created implicitly.
618 If the book has only a single score, the @code{\header} block should
619 normally be placed at the top of the file so that just a Bookpart
620 Title is produced, making all the titling fields available for use.
622 If the book has multiple scores a number of different arrangements
623 of @code{\header} blocks are possible, corresponding to the various
624 types of musical publications. For example, if the publication
625 contains several pieces by the same composer a @code{\header} block
626 placed at the top of the file specifying the book title and the
627 composer with @code{\header} blocks in each @code{\score} block
628 specifying the @code{piece} and/or @code{opus} would be most
631 @lilypond[papersize=a5,quote,verbatim,noragged-right]
634 composer = "J. S. Bach."
638 \new Staff \relative g, {
641 \repeat unfold 2 { g16( d' b') a b d, b' d, } |
642 \repeat unfold 2 { g,16( e' c') b c e, c' e, } |
650 \new Staff \relative b {
654 <g, d' b'~>4 b'16 a( g fis) g( d e fis) g( a b c) |
655 d16( b g fis) g( e d c) b(c d e) fis( g a b) |
663 More complicated arrangements are possible. For example, text
664 fields from the @code{\header} block in a book can be displayed in
665 all Score Titles, with some fields over-ridden and some manually
668 @lilypond[papersize=a5,quote,verbatim,noragged-right]
671 print-all-headers = ##t
674 title = "DAS WOHLTEMPERIRTE CLAVIER"
676 % Do not display the tagline for this book
679 \markup { \vspace #1 }
683 \new Staff { \clef "bass" s1 }
686 title = "PRAELUDIUM I"
688 % Do not display the subtitle for this score
695 \new Staff { \clef "bass" s1 }
699 subsubtitle = "A 4 VOCI"
701 % Do not display the subtitle for this score
710 @ref{File structure},
711 @ref{Default layout of bookpart and score titles},
712 @ref{Custom layout for titles}.
715 @node Default layout of bookpart and score titles
716 @unnumberedsubsubsec Default layout of bookpart and score titles
718 This example demonstrates all @code{\header} variables:
720 @lilypond[papersize=a7,quote,verbatim,noragged-right]
723 % The following fields are centered
724 dedication = "Dedication"
726 subtitle = "Subtitle"
727 subsubtitle = "Subsubtitle"
728 % The following fields are evenly spread on one line
729 % the field "instrument" also appears on following pages
730 instrument = \markup \with-color #green "Instrument"
732 composer = "Composer"
733 % The following fields are placed at opposite ends of the same line
735 arranger = "Arranger"
736 % The following fields are centered at the bottom
737 tagline = "tagline goes at the bottom of the last page"
738 copyright = "copyright goes at the bottom of the first page"
743 % The following fields are placed at opposite ends of the same line
751 % The following fields are placed at opposite ends of the same line
752 piece = "Piece 2 on the same page"
760 % The following fields are placed at opposite ends of the same line
761 piece = "Piece 3 on a new page"
772 The instrument name will be repeated on every page.
775 Only @code{piece} and @code{opus} are printed in a @code{\score}
776 when the paper variable @code{print-all-headers} is set to
777 @code{##f} (the default).
780 @c Is the bit about \null markups true? -mp
781 Text fields left unset in a @code{\header} block are replaced with
782 @code{\null} markups so that the space is not wasted.
785 The default settings for @code{scoreTitleMarkup} place the @code{piece}
786 and @code{opus} text fields at opposite ends of the same line.
790 To change the default layout see @ref{Custom layout for titles}.
794 Use the @code{breakbefore} variable inside a @code{\header} block
795 that is itself in a @code{\score} block, to make the top-level
796 @code{\header} block titles appear on the first page on their own, with
797 the music (defined in the @code{\score} block) starting on the next.
799 @lilypond[papersize=a8landscape,verbatim,noragged-right]
802 title = "This is my Title"
803 subtitle = "This is my Subtitle"
804 copyright = "This is the bottom of the first page"
807 \repeat unfold 4 { e'' e'' e'' e'' }
809 piece = "This is the Music"
818 @rlearning{How LilyPond input files work},
821 @ref{Custom layout for titles},
822 @ref{File structure}.
825 @file{ly/titling-init.ly}.
828 @node Default layout of headers and footers
829 @unnumberedsubsubsec Default layout of headers and footers
831 @emph{Headers} and @emph{footers} are lines of text appearing at
832 the top and bottom of pages, separate from the main text of a book.
833 They are controlled by the following @code{\paper} variables:
836 @item @code{oddHeaderMarkup}
837 @item @code{evenHeaderMarkup}
838 @item @code{oddFooterMarkup}
839 @item @code{evenFooterMarkup}
842 These markup variables can only access text fields from top-level
843 @code{\header} blocks (which apply to all scores in the book) and are
844 defined in @file{ly/titling-init.ly}. By default:
849 page numbers are automatically placed on the top far left (if even) or
850 top far right (if odd), starting from the second page.
853 the @code{instrument} text field is placed in the center of every
854 page, starting from the second page.
857 the @code{copyright} text is centered on the bottom of the first page.
860 the @code{tagline} is centered on the bottom of the last page, and below
861 the @code{copyright} text if there is only a single page.
865 @lilypond[papersize=a8landscape]
875 The default tagline can be changed by adding a @code{tagline} in the
876 top-level @code{\header} block.
878 @lilypond[papersize=a8landscape,verbatim]
881 tagline = "... music notation for Everyone"
891 To remove the @code{tagline} set the value to @code{##f}.
894 @node Custom titles headers and footers
895 @subsection Custom titles headers and footers
897 @c TODO: somewhere put a link to header spacing info
898 @c (you'll have to explain it more in NR 4).
901 * Custom text formatting for titles::
902 * Custom layout for titles::
903 * Custom layout for headers and footers::
907 @node Custom text formatting for titles
908 @unnumberedsubsubsec Custom text formatting for titles
910 Standard @code{\markup} commands can be used to customize any header,
911 footer and title text within the @code{\header} block.
913 @lilypond[quote,verbatim,noragged-right]
917 piece = \markup { \fontsize #4 \bold "PRAELUDIUM I" }
918 subtitle = \markup { \italic "(Excerpt)" }
925 @ref{Formatting text}.
928 @node Custom layout for titles
929 @unnumberedsubsubsec Custom layout for titles
931 @cindex bookTitleMarkup
932 @cindex scoreTitleMarkup
933 @funindex bookTitleMarkup
934 @funindex scoreTitleMarkup
936 @code{\markup} commands in the @code{\header} block are useful for
937 simple text formatting, but they do not allow precise control over the
938 placement of titles. To customize the placement of the text fields,
939 change either or both of the following @code{\paper} variables:
942 @item @code{bookTitleMarkup}
943 @item @code{scoreTitleMarkup}
946 The placement of titles when using the default values of these
947 @code{\markup} variables is shown in the examples in
948 @ref{Default layout of bookpart and score titles}.
950 The default settings for @code{scoreTitleMarkup} as defined in
951 @file{ly/titling-init.ly} are:
954 scoreTitleMarkup = \markup @{ \column @{
955 \on-the-fly #print-all-headers @{ \bookTitleMarkup \hspace #1 @}
957 \fromproperty #'header:piece
958 \fromproperty #'header:opus
964 This places the @code{piece} and @code{opus} text fields at opposite
965 ends of the same line:
967 @lilypond[quote,verbatim,noragged-right]
971 piece = "PRAELUDIUM I"
977 This example redefines @code{scoreTitleMarkup} so that the @code{piece}
978 text field is centered and in a large, bold font.
980 @lilypond[papersize=a5,quote,verbatim,noragged-right]
984 scoreTitleMarkup = \markup {
987 \fontsize #4 \bold \fromproperty #'header:piece
988 \fromproperty #'header:opus
992 \header { tagline = ##f }
996 piece = "PRAELUDIUM I"
1003 Text fields not normally effective in score @code{\header} blocks
1004 can be printed in the Score Title area if @code{print-all-headers} is
1005 placed inside the @code{\paper} block. A disadvantage of using this
1006 method is that text fields that are intended specifically for the
1007 Bookpart Title area need to be manually suppressed in every
1008 @code{\score} block. See @ref{Titles explained}.
1010 To avoid this, add the desired text field to the @code{scoreTitleMarkup}
1011 definition. In the following example, the @code{composer} text field
1012 (normally associated with @code{bookTitleMarkup}) is added to
1013 @code{scoreTitleMarkup}, allowing each score to list a different
1016 @lilypond[papersize=a5,quote,verbatim,noragged-right]
1020 scoreTitleMarkup = \markup {
1023 \fontsize #4 \bold \fromproperty #'header:piece
1024 \fromproperty #'header:composer
1028 \header { tagline = ##f }
1033 composer = "Christian Petzold"
1040 composer = "François Couperin"
1046 It is also possible to create your own custom text fields, and refer to
1047 them in the markup definition.
1049 @lilypond[papersize=a5,quote,verbatim,noragged-right]
1053 scoreTitleMarkup = \markup {
1056 \override #`(direction . ,UP) {
1058 \center-align \fontsize #-1 \bold
1059 \fromproperty #'header:mycustomtext %% User-defined field
1060 \center-align \fontsize #4 \bold
1061 \fromproperty #'header:piece
1064 \fromproperty #'header:opus
1068 \header { tagline = ##f }
1073 mycustomtext = "A 4 VOCI" %% User-defined field
1082 @ref{Titles explained}.
1085 @node Custom layout for headers and footers
1086 @unnumberedsubsubsec Custom layout for headers and footers
1088 @c can make-header and make-footer be removed from
1089 @c paper-defaults-init.ly? -mp
1091 @code{\markup} commands in the @code{\header} block are useful for
1092 simple text formatting, but they do not allow precise control over the
1093 placement of headers and footers. To customize the placement of
1094 the text fields, use either or both of the following @code{\paper}
1098 @item @code{oddHeaderMarkup}
1099 @item @code{evenHeaderMarkup}
1100 @item @code{oddFooterMarkup}
1101 @item @code{evenFooterMarkup}
1104 @cindex markup, conditional
1106 @funindex \on-the-fly
1108 The @code{\markup} command @code{\on-the-fly} can be used to add
1109 markup conditionally to header and footer text defined within the
1110 @code{\paper} block, using the following syntax:
1113 @code{variable} = @code{\markup} @{
1115 @code{\on-the-fly} #@var{procedure} @var{markup}
1120 The @var{procedure} is called each time the @code{\markup} command
1121 in which it appears is evaluated. The @var{procedure} should test
1122 for a particular condition and interpret (i.e. print) the
1123 @var{markup} argument if and only if the condition is true.
1125 A number of ready-made procedures for testing various conditions are
1129 @multitable {print-page-number-check-first-----} {should this page be printed-----}
1131 @headitem Procedure name @tab Condition tested
1133 @item print-page-number-check-first @tab should this page number be printed?
1134 @item create-page-number-stencil @tab print-page-numbers true?
1135 @item print-all-headers @tab print-all-headers true?
1136 @item first-page @tab first page in the book?
1137 @item (on-page nmbr) @tab page number = nmbr?
1138 @item last-page @tab last page in the book?
1139 @item not-first-page @tab not first page in the book?
1140 @item part-first-page @tab first page in the book part?
1141 @item part-last-page @tab last page in the book part?
1142 @item not-single-page @tab pages in book part > 1?
1147 The following example centers page numbers at the bottom of every
1148 page. First, the default settings for @code{oddHeaderMarkup} and
1149 @code{evenHeaderMarkup} are removed by defining each as a @emph{null}
1150 markup. Then, @code{oddFooterMarkup} is redefined with the page
1151 number centered. Finally, @code{evenFooterMarkup} is given the
1152 same layout by defining it as @code{\oddFooterMarkup}:
1154 @lilypond[papersize=a8,quote,verbatim,noragged-right]
1157 print-page-number = ##t
1158 print-first-page-number = ##t
1159 oddHeaderMarkup = \markup \null
1160 evenHeaderMarkup = \markup \null
1161 oddFooterMarkup = \markup {
1163 \on-the-fly #print-page-number-check-first
1164 \fromproperty #'page:page-number-string
1167 evenFooterMarkup = \oddFooterMarkup
1170 \new Staff { s1 \break s1 \break s1 }
1175 Several @code{\on-the-fly} conditions can be combined with an
1176 @q{and} operation, for example,
1179 @code{\on-the-fly #first-page}
1180 @code{\on-the-fly #last-page}
1181 @code{@{ \markup ... \fromproperty #'header: ... @}}
1184 determines if the output is a single page.
1188 @ref{Titles explained},
1189 @ref{Default layout of bookpart and score titles}.
1192 @file{../ly/titling-init.ly}.
1195 @node Creating footnotes
1196 @subsection Creating footnotes
1200 Footnotes may be used in many different situations. In all cases,
1201 a @q{footnote mark} is placed as a reference in text or music, and
1202 the corresponding @q{footnote text} appears at the bottom of the
1205 Footnotes within music expressions and footnotes in stand-alone text
1206 outside music expressions are created in different ways.
1209 * Footnotes in music expressions::
1210 * Footnotes in stand-alone text::
1213 @node Footnotes in music expressions
1214 @unnumberedsubsubsec Footnotes in music expressions
1216 @cindex footnotes in music expressions
1219 @subsubsubheading Music footnotes overview
1221 Footnotes in music expressions fall into two categories:
1224 @item Event-based footnotes
1225 are attached to a particular event. Examples for such events are
1226 single notes, articulations (like fingering indications, accents,
1227 dynamics), and post-events (like slurs and manual beams). The
1228 general form for event-based footnotes is as follows:
1231 [@var{direction}] \footnote [@var{mark}] @var{offset} @var{footnote} @var{music}
1234 @item Time-based footnotes
1235 are bound to a particular point of time in a musical context. Some
1236 commands like @code{\time} and @code{\clef} don't actually use events
1237 for creating objects like time signatures and clefs. Neither does a
1238 chord create an event of its own: its stem or flag is created at the
1239 end of a time step (nominally through one of the note events inside).
1240 Exactly which of a chord's multiple note events will be deemed the
1241 root cause of a stem or flag is undefined. So for annotating those,
1242 time-based footnotes are preferable as well.
1244 A time-based footnote allows such layout objects to be annotated
1245 without referring to an event. The general form for Time-based
1249 \footnote [@var{mark}] @var{offset} @var{footnote} [@var{Context}].@var{GrobName}
1254 The elements for both forms are:
1259 If (and only if) the @code{\footnote} is being applied to a
1260 post-event or articulation, it must be preceded with a direction
1261 indicator (@code{-, _, ^}) in order to attach @var{music} (with
1262 a footnote mark) to the preceding note or rest.
1265 is a markup or string specifying the footnote mark which is used for
1266 marking both the reference point and the footnote itself at the
1267 bottom of the page. It may be omitted (or equivalently replaced with
1268 @code{\default}) in which case a number in sequence will be generated
1269 automatically. Such numerical sequences restart on each page
1270 containing a footnote.
1273 is a number pair such as @samp{#(2 . 1)} specifying the X and
1274 Y@tie{}offsets in units of staff-spaces from the boundary of the
1275 object where the mark should be placed. Positive values of the
1276 offsets are taken from the right/top edge, negative values from the
1277 left/bottom edge and zero implies the mark is centered on the edge.
1280 is the context in which the grob being footnoted is created. It
1281 may be omitted if the grob is in a bottom context, e.g. a
1282 @code{Voice} context.
1285 specifies a type of grob to mark (like @samp{Flag}). If it is
1286 specified, the footnote is not attached to a music expression in
1287 particular, but rather to all grobs of the type specified which
1288 occur at that moment of musical time.
1291 is the markup or string specifying the footnote text to use at the
1295 is the music event or post-event or articulation
1296 that is being annotated.
1300 @subsubsubheading Event-based footnotes
1302 @cindex footnotes, event-based
1304 A footnote may be attached to a layout object directly caused
1305 by the event corresponding to @var{music} with the syntax:
1308 \footnote [@var{mark}] @var{offset} @var{footnote} @var{music}
1311 @lilypond[quote,verbatim,papersize=a8landscape]
1313 \header { tagline = ##f }
1315 \footnote #'(-1 . 3) "A note" a4
1317 \footnote #'(2 . 2) "A rest" r4
1323 Marking a @emph{whole} chord with an event-based footnote is not
1324 possible: a chord, even one containing just a single note, does
1325 not produce an actual event of its own. However, individual
1326 notes @emph{inside} of the chord can be marked:
1328 @lilypond[quote,verbatim,papersize=a8landscape]
1330 \header { tagline = ##f }
1332 \footnote #'(2 . 3) "Does not work" <a-3>2
1333 <\footnote #'(-2 . -3) "Does work" a-3>4
1334 <a-3 \footnote #'(3 . 1/2) "Also works" c-5>4
1339 If the footnote is to be attached to a post-event or articulation
1340 the @code{\footnote} command @emph{must} be preceded by a direction
1341 indicator, @code{-, _, ^}, and followed by the post-event or
1342 articulation to be annotated as the @var{music} argument. In this
1343 form the @code{\footnote} can be considered to be simply a copy of
1344 its last argument with a footnote mark attached to it. The syntax
1348 @var{direction} \footnote [@var{mark}] @var{offset} @var{footnote} @var{music}
1351 @lilypond[quote,verbatim,papersize=a8landscape]
1353 \header { tagline = ##f }
1355 a4_\footnote #'(0 . -1) "A slur forced down" (
1356 b8^\footnote #'(1 . 0.5) "A manual beam forced up" [
1359 c-\footnote #'(1 . 1) "Tenuto" --
1364 @subsubsubheading Time-based footnotes
1366 @cindex footnotes, time-based
1368 If the layout object being footmarked is @emph{indirectly} caused by
1369 an event (like an @code{Accidental} or @code{Stem} caused by a
1370 @code{NoteHead} event), the @var{GrobName} of the layout object
1371 is required after the footnote text instead of @var{music}:
1373 @lilypond[quote,verbatim,papersize=a8landscape]
1375 \header { tagline = ##f }
1377 \footnote #'(-1 . -3) "A flat" Accidental
1379 \footnote #'(-1 . 0.5) "Another flat" Accidental
1381 \footnote #'(1 . -2) "A stem" Stem
1387 Note, however, that when a GrobName is specified, a footnote
1388 will be attached to all grobs of that type at the current time step:
1390 @lilypond[quote,verbatim,papersize=a8landscape]
1392 \header { tagline = ##f }
1394 \footnote #'(-1 . 3) "A flat" Accidental
1396 \footnote #'(2 . 0.5) "Articulation" Script
1402 A note inside of a chord can be given an individual (event-based)
1403 footnote. A @samp{NoteHead} is the only grob directly caused
1404 from a chord note, so an event-based footnote command is
1405 @emph{only} suitable for adding a footnote to the @samp{NoteHead}
1406 within a chord. All other chord note grobs are indirectly caused.
1407 The @code{\footnote} command itself offers no syntax for
1408 specifying @emph{both} a particular grob type @emph{as well as} a
1409 particular event to attach to. However, one can use a time-based
1410 @code{\footnote} command for specifying the grob type, and then
1411 prefix this command with @code{\single} in order to have it
1412 applied to just the following event:
1414 @lilypond[quote,verbatim,papersize=a8landscape]
1416 \header { tagline = ##f }
1418 < \footnote #'(1 . -2) "An A" a
1419 \single \footnote #'(-1 . -1) "A sharp" Accidental
1421 \single \footnote #'(0.5 . 0.5) "A flat" Accidental
1428 @warning {When footnotes are attached to several musical elements at
1429 the same musical moment, as they are in the example above, the
1430 footnotes are numbered from the higher to the lower elements as they
1431 appear in the printed output, not in the order in which they are
1432 written in the input stream.}
1434 Layout objects like clefs and key-change signatures are mostly caused
1435 as a consequence of changed properties rather than actual events.
1436 Others, like bar lines and bar numbers, are a direct consequence of
1437 timing. For this reason, footnotes on such objects have to be based
1438 on their musical timing. Time-based footnotes are also preferable
1439 when marking features like stems and beams on @emph{chords}: while
1440 such per-chord features are nominally assigned to @emph{one} event
1441 inside the chord, relying on a particular choice would be imprudent.
1443 The layout object in question must always be explicitly specified
1444 for time-based footnotes, and the appropriate context must be
1445 specified if the grob is created in a context other than the bottom
1448 @lilypond[quote,verbatim,papersize=a8landscape]
1450 \header { tagline = ##f }
1453 \footnote #'(-0.5 . -1) "Meter change" Staff.TimeSignature
1455 \footnote #'(1 . -1) "Chord stem" Stem
1457 \footnote #'(-0.5 . 1) "Bar line" Staff.BarLine
1459 \footnote #'(0.5 . -1) "Key change" Staff.KeySignature
1466 Custom marks can be used as alternatives to numerical marks, and the
1467 annotation line joining the marked object to the mark can be
1470 @lilypond[quote,verbatim,papersize=a8landscape]
1472 \header { tagline = ##f }
1474 \footnote "*" #'(0.5 . -2) \markup { \italic "* The first note" } a'4
1476 \footnote \markup { \super "$" } #'(0.5 . 1)
1477 \markup { \super "$" \italic " The second note" } e
1479 \once \override Score.FootnoteItem.annotation-line = ##f
1480 b-\footnote \markup \tiny "+" #'(0.1 . 0.1)
1481 \markup { \super "+" \italic " Editorial" } \p
1486 More examples of custom marks are shown in
1487 @ref{Footnotes in stand-alone text}.
1490 @node Footnotes in stand-alone text
1491 @unnumberedsubsubsec Footnotes in stand-alone text
1493 @cindex footnotes in stand-alone text
1495 These are for use in markup outside of music expressions. They do
1496 not have a line drawn to their point of reference: their marks simply
1497 follow the referenced markup. Marks can be inserted automatically,
1498 in which case they are numerical. Alternatively, custom marks can be
1501 Footnotes to stand-alone text with automatic and custom marks are
1502 created in different ways.
1504 @subsubsubheading Footnotes in stand-alone text with automatic marks
1506 The syntax of a footnote in stand-alone text with automatic marks is
1509 \markup @{ ... \auto-footnote @var{text} @var{footnote} ... @}
1517 is the markup or string to be marked.
1520 is the markup or string specifying the footnote text to use at the bottom
1527 @lilypond[verbatim,quote,ragged-right,papersize=a8]
1529 \header { tagline = ##f }
1532 \auto-footnote "tune" \italic " By me"
1533 "is shown below. It is a"
1534 \auto-footnote "recent" \italic " Aug 2012"
1543 @subsubsubheading Footnotes in stand-alone text with custom marks
1545 The syntax of a footnote in stand-alone text with custom marks is
1548 \markup @{ ... \footnote @var{mark} @var{footnote} ... @}
1556 is a markup or string specifying the footnote mark which is used for
1557 marking the reference point. Note that this mark is @emph{not}
1558 inserted automatically before the footnote itself.
1561 is the markup or string specifying the footnote text to use at the
1562 bottom of the page, preceded by the @var{mark}.
1566 Any easy-to-type character such as * or + may be used as a mark, as
1567 shown in @ref{Footnotes in music expressions}. Alteratively, ASCII
1568 aliases may be used (see @ref{ASCII aliases}):
1570 @lilypond[verbatim,quote,ragged-right,papersize=a8]
1572 \paper { #(include-special-characters) }
1573 \header { tagline = ##f }
1576 \footnote "*" \italic "* By me"
1577 "is shown below. It is a recent"
1578 \footnote \super † \concat {
1579 \super † \italic " Aug 2012"
1589 Unicode character codes may also be used to specify marks
1590 (see @ref{Unicode}):
1592 @lilypond[verbatim,quote,ragged-right,papersize=a8]
1594 \header { tagline = ##f }
1597 \footnote \super \char##x00a7 \concat {
1598 \super \char##x00a7 \italic " By me"
1600 "is shown below. It is a recent"
1601 \footnote \super \char##x00b6 \concat {
1602 \super \char##x00b6 \italic " Aug 2012"
1614 @rlearning{Objects and interfaces}.
1617 @ref{ASCII aliases},
1619 @ref{List of special characters},
1624 Internals Reference:
1625 @rinternals{FootnoteEvent},
1626 @rinternals{FootnoteItem},
1627 @rinternals{FootnoteSpanner},
1628 @rinternals{Footnote_engraver}.
1631 Multiple footnotes for the same page can only be stacked, one above
1632 the other; they cannot be printed on the same line.
1634 Footnotes cannot be attached to @code{MultiMeasureRests} or
1635 automatic beams or lyrics.
1637 Footnote marks may collide with staves, @code{\markup} objects, other
1638 footnote marks and annotation lines.
1641 @node Reference to page numbers
1642 @subsection Reference to page numbers
1644 A particular place of a score can be marked using the @code{\label}
1645 command, either at top-level or inside music. This label can then be
1646 referred to in a markup, to get the number of the page where the marked
1647 point is placed, using the @code{\page-ref} markup command.
1649 @lilypond[verbatim,papersize=a8landscape]
1650 \header { tagline = ##f }
1656 \pageBreak \mark A \label #'markA
1660 \markup { The first score begins on page \page-ref #'firstScore "0" "?" }
1661 \markup { Mark A is on page \page-ref #'markA "0" "?" }
1665 The @code{\page-ref} markup command takes three arguments:
1667 @item the label, a scheme symbol, eg. @code{#'firstScore};
1668 @item a markup that will be used as a gauge to estimate the dimensions
1670 @item a markup that will be used in place of the page number if the label
1674 The reason why a gauge is needed is that, at the time markups are
1675 interpreted, the page breaking has not yet occurred, so the page numbers
1676 are not yet known. To work around this issue, the actual markup
1677 interpretation is delayed to a later time; however, the dimensions of
1678 the markup have to be known before, so a gauge is used to decide these
1679 dimensions. If the book has between 10 and 99 pages, it may be "00",
1680 ie. a two digit number.
1691 @node Table of contents
1692 @subsection Table of contents
1693 A table of contents is included using the @code{\markuplist \table-of-contents}
1694 command. The elements which should appear in the table of contents are
1695 entered with the @code{\tocItem} command, which may be used either at
1696 top-level, or inside a music expression.
1699 \markuplist \table-of-contents
1702 \tocItem \markup "First score"
1706 \tocItem \markup "Some particular point in the first score"
1711 \tocItem \markup "Second score"
1719 The markups which are used to format the table of contents are defined
1720 in the @code{\paper} block. The default ones are @code{tocTitleMarkup},
1721 for formatting the title of the table, and @code{tocItemMarkup}, for
1722 formatting the toc elements, composed of the element title and page
1723 number. These variables may be changed by the user:
1727 %% Translate the toc title into French:
1728 tocTitleMarkup = \markup \huge \column {
1729 \fill-line { \null "Table des matières" \null }
1732 %% use larger font size
1733 tocItemMarkup = \markup \large \fill-line {
1734 \fromproperty #'toc:text \fromproperty #'toc:page
1739 Note how the toc element text and page number are referred to in
1740 the @code{tocItemMarkup} definition.
1742 New commands and markups may also be defined to build more elaborated
1745 @item first, define a new markup variable in the @code{\paper} block
1746 @item then, define a music function which aims at adding a toc element
1747 using this markup paper variable.
1750 In the following example, a new style is defined for entering act names
1751 in the table of contents of an opera:
1755 tocActMarkup = \markup \large \column {
1757 \fill-line { \null \italic \fromproperty #'toc:text \null }
1763 #(define-music-function (parser location text) (markup?)
1764 (add-toc-item! 'tocActMarkup text))
1767 @lilypond[line-width=10.0\cm]
1768 \header { tagline = ##f }
1770 tocActMarkup = \markup \large \column {
1772 \fill-line { \null \italic \fromproperty #'toc:text \null }
1778 #(define-music-function (parser location text) (markup?)
1779 (add-toc-item! 'tocActMarkup text))
1782 \markuplist \table-of-contents
1783 \tocAct \markup { Atto Primo }
1784 \tocItem \markup { Coro. Viva il nostro Alcide }
1785 \tocItem \markup { Cesare. Presti omai l'Egizzia terra }
1786 \tocAct \markup { Atto Secondo }
1787 \tocItem \markup { Sinfonia }
1788 \tocItem \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
1793 Dots can be added to fill the line between an item and its page number:
1795 @lilypond[verbatim,line-width=10.0\cm]
1796 \header { tagline = ##f }
1798 tocItemMarkup = \tocItemWithDotsMarkup
1802 \markuplist \table-of-contents
1803 \tocItem \markup { Allegro }
1804 \tocItem \markup { Largo }
1811 @file{ly/toc-init.ly}.
1814 @funindex \table-of-contents
1815 @code{\table-of-contents},
1821 @node Working with input files
1822 @section Working with input files
1825 * Including LilyPond files::
1826 * Different editions from one source::
1827 * Special characters::
1831 @node Including LilyPond files
1832 @subsection Including LilyPond files
1835 @cindex including files
1837 A large project may be split up into separate files. To refer to
1841 \include "otherfile.ly"
1844 The line @code{\include "otherfile.ly"} is equivalent to pasting the
1845 contents of @file{otherfile.ly} into the current file at the place
1846 where the @code{\include} appears. For example, in a large
1847 project you might write separate files for each instrument part
1848 and create a @qq{full score} file which brings together the
1849 individual instrument files. Normally the included file will
1850 define a number of variables which then become available
1851 for use in the full score file. Tagged sections can be
1852 marked in included files to assist in making them usable in
1853 different places in a score, see @ref{Different editions from
1856 Files in the current working directory may be referenced by
1857 specifying just the file name after the @code{\include} command.
1858 Files in other locations may be included by giving either a full
1859 path reference or a relative path reference (but use the UNIX
1860 forward slash, /, rather than the DOS/Windows back slash, \, as the
1861 directory separator.) For example, if @file{stuff.ly} is located
1862 one directory higher than the current working directory, use
1865 \include "../stuff.ly"
1869 or if the included orchestral parts files are all located in a
1870 subdirectory called @file{parts} within the current directory, use
1873 \include "parts/VI.ly"
1874 \include "parts/VII.ly"
1878 Files which are to be included can also contain @code{\include}
1879 statements of their own. By default, these second-level
1880 @code{\include} statements are not interpreted until they have
1881 been brought into the main file, so the file names they specify
1882 must all be relative to the directory containing the main file,
1883 not the directory containing the included file. However,
1884 this behavior can be changed globally by passing the option
1885 @option{-drelative-includes} option at the command line
1886 (or by adding @code{#(ly:set-option 'relative-includes #t)}
1887 at the top of the main input file).
1889 When @code{relative-includes} is set to @code{#t}, the path for each
1890 @code{\include} command will be taken relative to the file containing
1891 that command. This behavior is recommended and it will become the
1892 default behavior in a future version of lilypond.
1894 Files relative to the main directory and files relative to some other
1895 directory may both be @code{\include}d by setting
1896 @code{relative-includes} to @code{#t} or @code{#f} at appropriate
1897 places in the files. For example, if a general library, libA, has
1898 been created which itself uses sub-files which are @code{\include}d
1899 by the entry file of that library, those @code{\include} statements
1900 will need to be preceded by
1901 @code{#(ly:set-option #relative-includes #t)} so they are interpreted
1902 correctly when brought into the main @code{.ly} file, like this:
1913 then the entry file, @code{libA.ly}, will contain
1916 #(ly:set-option 'relative-includes #t)
1920 % return to default setting
1921 #(ly:set-option 'relative-includes #f)
1924 Any @file{.ly} file can then include the entire library simply with
1927 \include "~/libA/libA.ly"
1930 More complex file structures may be devised by switching at
1933 Files can also be included from a directory in a search path
1934 specified as an option when invoking LilyPond from the command
1935 line. The included files are then specified using just their
1936 file name. For example, to compile @file{main.ly} which includes
1937 files located in a subdirectory called @file{parts} by this method,
1938 cd to the directory containing @file{main.ly} and enter
1941 lilypond --include=parts main.ly
1944 and in main.ly write
1952 Files which are to be included in many scores may be placed in
1953 the LilyPond directory @file{../ly}. (The location of this
1954 directory is installation-dependent - see
1955 @rlearning{Other sources of information}). These files can then
1956 be included simply by naming them on an @code{\include} statement.
1957 This is how the language-dependent files like @file{english.ly} are
1960 LilyPond includes a number of files by default when you start
1961 the program. These includes are not apparent to the user, but the
1962 files may be identified by running @code{lilypond --verbose} from
1963 the command line. This will display a list of paths and files that
1964 LilyPond uses, along with much other information. Alternatively,
1965 the more important of these files are discussed in
1966 @rlearning{Other sources of information}. These files may be
1967 edited, but changes to them will be lost on installing a new
1968 version of LilyPond.
1970 Some simple examples of using @code{\include} are shown in
1971 @rlearning{Scores and parts}.
1975 @rlearning{Other sources of information},
1976 @rlearning{Scores and parts}.
1979 If an included file is given a name which is the same as one in
1980 LilyPond's installation files, LilyPond's file from the
1981 installation files takes precedence.
1984 @node Different editions from one source
1985 @subsection Different editions from one source
1987 Several methods can be used to generate different versions of a score
1988 from the same music source. Variables are perhaps the most useful for
1989 combining lengthy sections of music and/or annotation. Tags are more
1990 useful for selecting one section from several alternative shorter
1991 sections of music, and can also be used for splicing pieces of music
1992 together at different points.
1994 Whichever method is used, separating the notation from the structure of
1995 the score will make it easier to change the structure while leaving the
2001 * Using global settings::
2004 @node Using variables
2005 @unnumberedsubsubsec Using variables
2007 @cindex variables, use of
2009 If sections of the music are defined in variables they can be
2010 reused in different parts of the score, see @rlearning{Organizing
2011 pieces with variables}. For example, an @notation{a cappella}
2012 vocal score frequently includes a piano reduction of the parts
2013 for rehearsal purposes which is identical to the vocal music, so
2014 the music need be entered only once. Music from two variables
2015 may be combined on one staff, see @ref{Automatic part combining}.
2018 @lilypond[verbatim,quote]
2019 sopranoMusic = \relative c'' { a4 b c b8( a) }
2020 altoMusic = \relative g' { e4 e e f }
2021 tenorMusic = \relative c' { c4 b e d8( c) }
2022 bassMusic = \relative c' { a4 gis a d, }
2023 allLyrics = \lyricmode {King of glo -- ry }
2025 \new Staff = "Soprano" \sopranoMusic
2026 \new Lyrics \allLyrics
2027 \new Staff = "Alto" \altoMusic
2028 \new Lyrics \allLyrics
2029 \new Staff = "Tenor" {
2033 \new Lyrics \allLyrics
2034 \new Staff = "Bass" {
2038 \new Lyrics \allLyrics
2041 \set Staff.printPartCombineTexts = ##f
2047 \set Staff.printPartCombineTexts = ##f
2057 Separate scores showing just the vocal parts or just the piano
2058 part can be produced by changing just the structural statements,
2059 leaving the musical notation unchanged.
2061 For lengthy scores, the variable definitions may be placed in
2062 separate files which are then included, see @ref{Including
2066 @unnumberedsubsubsec Using tags
2069 @funindex \keepWithTag
2070 @funindex \removeWithTag
2071 @funindex \pushToTag
2072 @funindex \appendToTag
2074 @cindex keep tagged music
2075 @cindex remove tagged music
2076 @cindex splice into tagged music
2078 The @code{\tag #'@var{partA}} command marks a music expression
2079 with the name @var{partA}.
2080 Expressions tagged in this way can be selected or filtered out by
2081 name later, using either @code{\keepWithTag #'@var{name}} or
2082 @code{\removeWithTag #'@var{name}}. The result of applying these filters
2083 to tagged music is as follows:
2084 @multitable @columnfractions .5 .5
2088 Tagged music preceded by @code{\keepWithTag #'@var{name}}
2089 @tab Untagged music and music tagged with @var{name} is included;
2090 music tagged with any other tag name is excluded.
2092 Tagged music preceded by @code{\removeWithTag #'@var{name}}
2093 @tab Untagged music and music tagged with any tag name other than
2094 @var{name} is included; music tagged with @var{name} is
2097 Tagged music not preceded by either @code{\keepWithTag} or
2098 @code{\removeWithTag}
2099 @tab All tagged and untagged music is included.
2102 The arguments of the @code{\tag}, @code{\keepWithTag} and
2103 @code{\removeWithTag} commands should be a symbol
2104 (such as @code{#'score} or @code{#'part}), followed
2105 by a music expression.
2107 In the following example, we see two versions of a piece of music,
2108 one showing trills with the usual notation, and one with trills
2109 explicitly expanded:
2111 @lilypond[verbatim,quote]
2112 music = \relative g' {
2114 \tag #'trills { d8.\trill }
2115 \tag #'expand { \repeat unfold 3 { e32 d } }
2120 \keepWithTag #'trills \music
2123 \keepWithTag #'expand \music
2128 Alternatively, it is sometimes easier to exclude sections of music:
2130 @lilypond[verbatim,quote]
2131 music = \relative g' {
2133 \tag #'trills { d8.\trill }
2134 \tag #'expand {\repeat unfold 3 { e32 d } }
2139 \removeWithTag #'expand
2143 \removeWithTag #'trills
2148 Tagged filtering can be applied to articulations, texts, etc. by
2152 -\tag #'@var{your-tag}
2155 to an articulation. For example, this would define a note with a
2156 conditional fingering indication and a note with a conditional
2161 c1-\tag #'warn ^"Watch!"
2164 Multiple tags may be placed on expressions with multiple
2165 @code{\tag} entries:
2167 @lilypond[quote,verbatim]
2168 music = \relative c'' {
2169 \tag #'a \tag #'both { a4 a a a }
2170 \tag #'b \tag #'both { b4 b b b }
2173 \keepWithTag #'a \music
2174 \keepWithTag #'b \music
2175 \keepWithTag #'both \music
2179 Multiple @code{\removeWithTag} filters may be applied to a single
2180 music expression to remove several differently named tagged sections:
2182 @lilypond[verbatim,quote]
2183 music = \relative c'' {
2184 \tag #'A { a4 a a a }
2185 \tag #'B { b4 b b b }
2186 \tag #'C { c4 c c c }
2187 \tag #'D { d4 d d d }
2196 Two or more @code{\keepWithTag} filters applied to a single music
2197 expression will cause @emph{all} tagged sections to be removed, as
2198 the first filter will remove all tagged sections except the one
2199 named, and the second filter will remove even that tagged section.
2201 Sometimes you want to splice some music at a particular place in an
2202 existing music expression. You can use @code{\pushToTag} and
2203 @code{\appendToTag} for adding material at the front or end of the
2204 @code{elements} of an existing music construct. Not every music
2205 construct has @code{elements}, but sequential and simultaneous music are
2208 @lilypond[verbatim,quote]
2209 test = { \tag #'here { \tag #'here <<c''>> } }
2212 \pushToTag #'here c'
2213 \pushToTag #'here e'
2214 \pushToTag #'here g' \test
2215 \appendToTag #'here c'
2216 \appendToTag #'here e'
2217 \appendToTag #'here g' \test
2221 Both commands get a tag, the material to splice in at every occurence of
2222 the tag, and the tagged expression. The commands make sure to
2223 copy everything that they change so that the original @code{\test}
2224 retains its meaning.
2228 @rlearning{Organizing pieces with variables}.
2231 @ref{Automatic part combining},
2232 @ref{Including LilyPond files}.
2235 @c This warning is more general than this placement implies.
2236 @c Rests are not merged whether or not they come from tagged sections.
2237 @c Should be deleted? -td
2240 Multiple rests are not merged if you create a score with more
2241 than one tagged section at the same place.
2246 @node Using global settings
2247 @unnumberedsubsubsec Using global settings
2249 @cindex include-settings
2251 Global settings can be included from a separate file:
2254 lilypond -dinclude-settings=MY_SETTINGS.ly MY_SCORE.ly
2257 Groups of settings such as page size, font or type face can be stored
2258 in separate files. This allows different editions from the same score
2259 as well as standard settings to be applied to many scores, simply by
2260 specifying the proper settings file.
2262 This technique also works well with the use of style sheets, as
2263 discussed in @rlearning{Style sheets}.
2267 @rlearning{Organizing pieces with variables},
2268 @rlearning{Style sheets}.
2271 @ref{Including LilyPond files}.
2274 @node Special characters
2275 @subsection Special characters
2277 @cindex special characters
2278 @cindex non-ASCII characters
2288 @unnumberedsubsubsec Text encoding
2292 LilyPond uses the character repertoire defined by the Unicode
2293 consortium and ISO/IEC 10646. This defines a unique name and
2294 code point for the character sets used in virtually all modern
2295 languages and many others too. Unicode can be implemented using
2296 several different encodings. LilyPond uses the UTF-8 encoding
2297 (UTF stands for Unicode Transformation Format) which represents
2298 all common Latin characters in one byte, and represents other
2299 characters using a variable length format of up to four bytes.
2301 The actual appearance of the characters is determined by the
2302 glyphs defined in the particular fonts available - a font defines
2303 the mapping of a subset of the Unicode code points to glyphs.
2304 LilyPond uses the Pango library to layout and render multi-lingual
2307 LilyPond does not perform any input-encoding conversions. This
2308 means that any text, be it title, lyric text, or musical
2309 instruction containing non-ASCII characters, must be encoded in
2310 UTF-8. The easiest way to enter such text is by using a
2311 Unicode-aware editor and saving the file with UTF-8 encoding. Most
2312 popular modern editors have UTF-8 support, for example, vim, Emacs,
2313 jEdit, and GEdit do. All MS Windows systems later than NT use
2314 Unicode as their native character encoding, so even Notepad can
2315 edit and save a file in UTF-8 format. A more functional
2316 alternative for Windows is BabelPad.
2318 If a LilyPond input file containing a non-ASCII character is not
2319 saved in UTF-8 format the error message
2322 FT_Get_Glyph_Name () error: invalid argument
2327 Here is an example showing Cyrillic, Hebrew and Portuguese
2331 %c No verbatim here as the code does not display correctly in PDF
2333 bulgarian = \lyricmode {
2334 Жълтата дюля беше щастлива, че пухът, който цъфна, замръзна като гьон.
2338 hebrew = \lyricmode {
2339 זה כיף סתם לשמוע איך תנצח קרפד עץ טוב בגן.
2343 portuguese = \lyricmode {
2344 à vo -- cê uma can -- ção legal
2350 \addlyrics { \bulgarian }
2351 \addlyrics { \hebrew }
2352 \addlyrics { \portuguese }
2357 @unnumberedsubsubsec Unicode
2361 To enter a single character for which the Unicode code point is
2362 known but which is not available in the editor being used, use
2363 either @code{\char ##xhhhh} or @code{\char #dddd} within a
2364 @code{\markup} block, where @code{hhhh} is the hexadecimal code for
2365 the character required and @code{dddd} is the corresponding decimal
2366 value. Leading zeroes may be omitted, but it is usual to specify
2367 all four characters in the hexadecimal representation. (Note that
2368 the UTF-8 encoding of the code point should @emph{not} be used
2369 after @code{\char}, as UTF-8 encodings contain extra bits indicating
2370 the number of octets.) Unicode code charts and a character name
2371 index giving the code point in hexadecimal for any character can be
2372 found on the Unicode Consortium website,
2373 @uref{http://www.unicode.org/}.
2375 For example, @code{\char ##x03BE} and @code{\char #958} would both
2376 enter the Unicode U+03BE character, which has the Unicode name
2377 @qq{Greek Small Letter Xi}.
2379 Any Unicode code point may be entered in this way and if all special
2380 characters are entered in this format it is not necessary to save
2381 the input file in UTF-8 format. Of course, a font containing all
2382 such encoded characters must be installed and available to LilyPond.
2384 The following example shows Unicode hexadecimal values being entered
2385 in four places -- in a rehearsal mark, as articulation text, in
2386 lyrics and as stand-alone text below the score:
2388 @lilypond[quote,verbatim]
2391 c1 \mark \markup { \char ##x03EE }
2392 c1_\markup { \tiny { \char ##x03B1 " to " \char ##x03C9 } }
2394 \addlyrics { O \markup { \concat { Ph \char ##x0153 be! } } }
2396 \markup { "Copyright 2008--2012" \char ##x00A9 }
2399 @cindex copyright sign
2401 To enter the copyright sign in the copyright notice use:
2405 copyright = \markup @{ \char ##x00A9 "2008" @}
2411 @unnumberedsubsubsec ASCII aliases
2413 A list of ASCII aliases for special characters can be included:
2415 @lilypond[quote,verbatim]
2417 #(include-special-characters)
2420 \markup "&flqq; – &OE;uvre incomplète… &frqq;"
2423 \new Staff { \repeat unfold 9 a'4 }
2425 This is al -- so wor -- kin'~in ly -- rics: –_&OE;…
2430 "The replacement can be disabled:"
2431 "– &OE; …"
2432 \override #'(replacement-alist . ()) "– &OE; …"
2436 You can also make your own aliases, either globally:
2438 @lilypond[quote,verbatim]
2440 #(add-text-replacements!
2441 '(("100" . "hundred")
2442 ("dpi" . "dots per inch")))
2444 \markup "A 100 dpi."
2449 @lilypond[quote,verbatim]
2450 \markup \replace #'(("100" . "hundred")
2451 ("dpi" . "dots per inch")) "A 100 dpi."
2456 @ref{List of special characters}.
2459 @file{ly/text-replacements.ly}.
2462 @node Controlling output
2463 @section Controlling output
2466 * Extracting fragments of music::
2467 * Skipping corrected music::
2468 * Alternative output formats::
2469 * Replacing the notation font::
2472 @node Extracting fragments of music
2473 @subsection Extracting fragments of music
2475 It is possible to quote small fragments of a large score directly from
2476 the output. This can be compared to clipping a piece of a paper score
2479 This is done by defining the measures that need to be cut out
2480 separately. For example, including the following definition
2488 (make-rhythmic-location 5 1 2)
2489 (make-rhythmic-location 7 3 4)))
2494 will extract a fragment starting halfway the fifth measure, ending in
2495 the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note
2496 in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7.
2498 More clip regions can be defined by adding more pairs of
2499 rhythmic-locations to the list.
2501 In order to use this feature, LilyPond must be invoked with
2502 @option{-dclip-systems}. The clips are output as EPS files, and are
2503 converted to PDF and PNG if these formats are switched on as well.
2505 For more information on output formats, see @rprogram{Invoking lilypond}.
2507 @node Skipping corrected music
2508 @subsection Skipping corrected music
2511 @funindex skipTypesetting
2512 @funindex showFirstLength
2513 @funindex showLastLength
2515 When entering or copying music, usually only the music near the end (where
2517 are adding notes) is interesting to view and correct. To speed up
2518 this correction process, it is possible to skip typesetting of all but
2519 the last few measures. This is achieved by putting
2522 showLastLength = R1*5
2527 in your source file. This will render only the last 5 measures
2528 (assuming 4/4 time signature) of every @code{\score} in the input
2529 file. For longer pieces, rendering only a small part is often an order
2530 of magnitude quicker than rendering it completely. When working on the
2531 beginning of a score you have already typeset (e.g. to add a new part),
2532 the @code{showFirstLength} property may be useful as well.
2534 Skipping parts of a score can be controlled in a more fine-grained
2535 fashion with the property @code{Score.skipTypesetting}. When it is
2536 set, no typesetting is performed at all.
2538 This property is also used to control output to the MIDI file. Note that
2539 it skips all events, including tempo and instrument changes. You have
2542 @lilypond[quote,relative=2,ragged-right,verbatim]
2544 \set Score.skipTypesetting = ##t
2546 \set Score.skipTypesetting = ##f
2550 In polyphonic music, @code{Score.skipTypesetting} will affect all
2551 voices and staves, saving even more time.
2553 @node Alternative output formats
2554 @subsection Alternative output formats
2556 @cindex scalable vector graphics output
2558 @cindex encapsulated postscript output
2561 The default output formats for the printed score are Portable
2562 Document Format (PDF) and PostScript (PS). Scalable Vector
2563 Graphics (SVG), Encapsulated PostScript (EPS) and Portable
2564 Network Graphics (PNG) output formats are also available through
2565 command line options, see
2566 @rprogram{Basic command line options for LilyPond}.
2569 @node Replacing the notation font
2570 @subsection Replacing the notation font
2572 Gonville is an alternative to the Feta font used in LilyPond and can
2575 @uref{http://www.chiark.greenend.org.uk/~sgtatham/gonville/ ,http://www.chiark.greenend.org.uk/~sgtatham/gonville/}
2578 Here are a few sample bars of music set in Gonville:
2580 @c NOTE: these images are a bit big, but that's important
2581 @c for the font comparison. -gp
2582 @sourceimage{Gonville_after,,,}
2584 Here are a few sample bars of music set in LilyPond's Feta font:
2586 @sourceimage{Gonville_before,,,}
2588 @subsubheading Installation Instructions for MacOS
2590 Download and extract the zip file. Copy the @code{lilyfonts}
2591 directory to @file{@var{SHARE_DIR}/lilypond/current}; for more
2592 information, see @rlearning{Other sources of information}. Rename the
2593 existing @code{fonts} directory to @code{fonts_orig} and the
2594 @code{lilyfonts} directory to @code{fonts}. To revert back to Feta,
2595 reverse the process.
2599 @rlearning{Other sources of information}.
2602 Gonville cannot be used to typeset @q{Ancient Music} notation and it is
2603 likely newer glyphs in later releases of LilyPond may not exist in the
2604 Gonville font family. Please refer to the author's website for more
2605 information on these and other specifics, including licensing of
2610 @section MIDI output
2615 MIDI (Musical Instrument Digital Interface) is a standard for
2616 connecting and controlling digital instruments. A MIDI file is a
2617 series of notes in a number of tracks. It is not an actual
2618 sound file; you need special software to translate between the
2619 series of notes and actual sounds.
2621 Pieces of music can be converted to MIDI files, so you can listen to
2622 what was entered. This is convenient for checking the music; octaves
2623 that are off or accidentals that were mistyped stand out very much
2624 when listening to the MIDI output.
2626 Standard MIDI output is somewhat crude; optionally, an enhanced and
2627 more realistic MIDI output is available by means of
2628 @ref{The Articulate script}.
2630 The MIDI output allocates a channel for each staff, and reserves channel
2631 10 for drums. There are only 16 MIDI channels per device, so if the
2632 score contains more than 15 staves, MIDI channels will be reused.
2635 * Creating MIDI files::
2636 * MIDI Instruments::
2638 * What goes into the MIDI output?::
2640 * Controlling MIDI dynamics::
2641 * Percussion in MIDI::
2642 * The Articulate script::
2645 @node Creating MIDI files
2646 @subsection Creating MIDI files
2648 To create a MIDI output file from a LilyPond input file, add a
2649 @code{\midi} block to a score, for example,
2658 If there is a @code{\midi} block in a @code{\score} with no
2659 @code{\layout} block, only MIDI output will be produced. When
2660 notation is needed too, a @code{\layout} block must also be
2671 Pitches, rhythms, ties, dynamics, and tempo changes are interpreted
2672 and translated correctly to the MIDI output. Dynamic marks,
2673 crescendi and decrescendi translate into MIDI volume levels.
2674 Dynamic marks translate to a fixed fraction of the available MIDI
2675 volume range. Crescendi and decrescendi make the volume vary
2676 linearly between their two extremes. The effect of dynamic markings
2677 on the MIDI output can be removed completely, see @ref{MIDI block}.
2679 The initial tempo and later tempo changes can be specified
2680 with the @code{\tempo} command within the music notation. These
2681 are reflected in tempo changes in the MIDI output. This command
2682 will normally result in the metronome mark being printed, but this
2683 can be suppressed, see @ref{Metronome marks}. An alternative way
2684 of specifying the initial or overall MIDI tempo is described below,
2685 see @ref{MIDI block}.
2687 Due to some limitations on Windows, the default extension for
2688 MIDI files on Windows is @code{.mid}. Other operating systems still
2689 use the extension @code{.midi}. If a different extension is preferred,
2690 insert the following line at the top-level of the input file,
2691 before the start of any @code{\book}, @code{\bookpart} or @code{\score} blocks:
2694 #(ly:set-option 'midi-extension "midi")
2697 The line above will set the default extension for MIDI files to
2700 Alternatively, this option can also be supplied on the command line:
2703 lilypond … -dmidi-extension=midi lilyFile.ly
2709 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
2710 {changing-midi-output-to-one-channel-per-voice.ly}
2714 @c In 2.11 the following no longer seems to be a problem -td
2716 Unterminated (de)crescendos will not render properly in the midi file,
2717 resulting in silent passages of music. The workaround is to explicitly
2718 terminate the (de)crescendo. For example,
2725 will not work properly but
2728 @{ a4\< b c d\!\f @}
2735 Changes in the MIDI volume take place only on starting a note, so
2736 crescendi and decrescendi cannot affect the volume of a
2739 Not all midi players correctly handle tempo changes in the midi
2740 output. Players that are known to work include MS Windows Media
2741 Player and @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
2743 @node MIDI Instruments
2744 @subsection MIDI Instruments
2746 @cindex instrument names
2747 @cindex MIDI, instruments
2748 @funindex Staff.midiInstrument
2750 The MIDI instrument to be used is specified by setting the
2751 @code{Staff.midiInstrument} property to the instrument name.
2752 The name should be chosen from the list in @ref{MIDI instruments}.
2756 \set Staff.midiInstrument = #"glockenspiel"
2762 \new Staff \with @{midiInstrument = #"cello"@} @{
2767 If the selected instrument does not exactly match an instrument from
2768 the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
2772 @subsection MIDI block
2775 A @code{\midi} block must appear within a score block if MIDI output
2776 is required. It is analogous to the layout block, but somewhat
2777 simpler. Often, the @code{\midi} block is left empty, but it
2778 can contain context rearrangements, new context definitions or code
2779 to set the values of properties. For example, the following will
2780 set the initial tempo exported to a MIDI file without causing a tempo
2781 indication to be printed:
2792 In this example the tempo is set to 72 quarter note
2793 beats per minute. @code{\tempo} is actually a music command for
2794 setting properties during the interpretation of music: in the
2795 context of output definitions like a @code{\midi} block, as a matter of
2796 courtesy those are reinterpreted as if they were context modifications.
2798 @cindex MIDI context definitions
2800 Context definitions follow precisely the same syntax as those
2801 within a @code{\layout} block. Translation modules for sound are
2802 called performers. The contexts for MIDI output are defined in
2803 @file{../ly/performer-init.ly},
2804 see @rlearning{Other sources of information}.
2805 For example, to remove the effect of dynamics
2806 from the MIDI output, insert the following lines in the
2807 @code{\midi@{ @}} block.
2814 \remove "Dynamic_performer"
2819 MIDI output is created only when a @code{\midi} block is included
2820 within a score block defined with a @code{\score} command.
2824 @{ @dots{}notes@dots{} @}
2829 @node What goes into the MIDI output?
2830 @subsection What goes into the MIDI output?
2832 @c TODO Check grace notes - timing is suspect?
2835 * Supported in MIDI::
2836 * Unsupported in MIDI::
2839 @node Supported in MIDI
2840 @unnumberedsubsubsec Supported in MIDI
2842 @cindex Pitches in MIDI
2843 @cindex MIDI, Pitches
2844 @cindex Quarter tones in MIDI
2845 @cindex MIDI, quarter tones
2846 @cindex Microtones in MIDI
2847 @cindex MIDI, microtones
2848 @cindex Chord names in MIDI
2849 @cindex MIDI, chord names
2850 @cindex Rhythms in MIDI
2851 @cindex MIDI, Rhythms
2852 @cindex Articlulate scripts
2853 @cindex MIDI, articulations
2854 @cindex articulations in MIDI
2855 @cindex trills in MIDI
2856 @cindex turns in MIDI
2857 @cindex rallentando in MIDI
2858 @cindex accelerando in MIDI
2861 The following items of notation are reflected in the MIDI output:
2865 @item Microtones (See @ref{Accidentals}. Rendering needs a
2866 player that supports pitch bend.)
2867 @item Chords entered as chord names
2868 @item Rhythms entered as note durations, including tuplets
2869 @item Tremolos entered without @q{@code{:}[@var{number}]}
2872 @item Crescendi, decrescendi over multiple notes
2873 @item Tempo changes entered with a tempo marking
2877 Using @ref{The Articulate script}, a number of items are added to the
2881 @item Articulations (slurs, staccato, etc)
2883 @item Rallentando and accelerando
2887 @node Unsupported in MIDI
2888 @unnumberedsubsubsec Unsupported in MIDI
2890 @c TODO index as above
2892 The following items of notation have no effect on the MIDI output,
2893 unless you use @ref{The Articulate script}:
2896 @item Rhythms entered as annotations, e.g. swing
2897 @item Tempo changes entered as annotations with no tempo marking
2898 @item Staccato and other articulations and ornamentations
2899 @item Slurs and Phrasing slurs
2900 @item Crescendi, decrescendi over a single note
2901 @item Tremolos entered with @q{@code{:}[@var{number}]}
2903 @item Microtonal chords
2907 @node Repeats in MIDI
2908 @subsection Repeats in MIDI
2910 @cindex repeats in MIDI
2911 @funindex \unfoldRepeats
2913 With a few minor additions, all types of repeats can be represented
2914 in the MIDI output. This is achieved by applying the
2915 @code{\unfoldRepeats} music function. This function changes all
2916 repeats to unfold repeats.
2918 @lilypond[quote,verbatim]
2920 \repeat tremolo 8 { c'32 e' }
2921 \repeat percent 2 { c''8 d'' }
2922 \repeat volta 2 { c'4 d' e' f' }
2931 In scores containing multiple voices, unfolding of repeats in MIDI
2932 output will only occur correctly if @emph{each} voice contains fully
2933 notated repeat indications.
2935 When creating a score file using @code{\unfoldRepeats} for MIDI,
2936 it is necessary to make two @code{\score} blocks: one for MIDI
2937 (with unfolded repeats) and one for notation (with volta, tremolo,
2938 and percent repeats). For example,
2946 \unfoldRepeats @var{..music..}
2951 @node Controlling MIDI dynamics
2952 @subsection Controlling MIDI dynamics
2954 MIDI dynamics are implemented by the Dynamic_performer which lives
2955 by default in the Voice context. It is possible to control the
2956 overall MIDI volume, the relative volume of dynamic markings and
2957 the relative volume of different instruments.
2961 * Overall MIDI volume::
2962 * Equalizing different instruments (i)::
2963 * Equalizing different instruments (ii)::
2967 @unnumberedsubsubsec Dynamic marks
2969 Dynamic marks are translated to a fixed fraction of the available
2970 MIDI volume range. The default fractions range from 0.25 for
2971 @notation{ppppp} to 0.95 for @notation{fffff}. The set of dynamic
2972 marks and the associated fractions can be seen in
2973 @file{../scm/midi.scm}, see @rlearning{Other sources of information}.
2974 This set of fractions may be changed or extended by providing a
2975 function which takes a dynamic mark as its argument and returns the
2976 required fraction, and setting
2977 @code{Score.dynamicAbsoluteVolumeFunction} to this function.
2979 For example, if a @notation{rinforzando} dynamic marking,
2980 @code{\rfz}, is required, this will not by default
2981 have any effect on the MIDI volume, as this dynamic marking is not
2982 included in the default set. Similarly, if a new dynamic marking
2983 has been defined with @code{make-dynamic-script} that too will not
2984 be included in the default set. The following example shows how the
2985 MIDI volume for such dynamic markings might be added. The Scheme
2986 function sets the fraction to 0.9 if a dynamic mark of rfz is
2987 found, or calls the default function otherwise.
2989 @lilypond[verbatim,quote]
2990 #(define (myDynamics dynamic)
2991 (if (equal? dynamic "rfz")
2993 (default-dynamic-absolute-volume dynamic)))
2997 \set Staff.midiInstrument = #"cello"
2998 \set Score.dynamicAbsoluteVolumeFunction = #myDynamics
3010 Alternatively, if the whole table of fractions needs to be
3011 redefined, it would be better to use the
3012 @notation{default-dynamic-absolute-volume} procedure in
3013 @file{../scm/midi.scm} and the associated table as a model.
3014 The final example in this section shows how this might be done.
3016 @node Overall MIDI volume
3017 @unnumberedsubsubsec Overall MIDI volume
3019 The minimum and maximum overall volume of MIDI dynamic markings is
3020 controlled by setting the properties @code{midiMinimumVolume} and
3021 @code{midiMaximumVolume} at the @code{Score} level. These
3022 properties have an effect only on dynamic marks, so if they
3023 are to apply from the start of the score a dynamic mark must be
3024 placed there. The fraction corresponding to each dynamic mark is
3025 modified with this formula
3028 midiMinimumVolume + (midiMaximumVolume - midiMinimumVolume) * fraction
3031 In the following example the dynamic range of the overall MIDI
3032 volume is limited to the range 0.2 - 0.5.
3034 @lilypond[verbatim,quote]
3040 \set Staff.midiInstrument = #"flute"
3041 \new Voice \relative c''' {
3049 \set Staff.midiInstrument = #"clarinet"
3050 \new Voice \relative c'' {
3062 midiMinimumVolume = #0.2
3063 midiMaximumVolume = #0.5
3069 @node Equalizing different instruments (i)
3070 @unnumberedsubsubsec Equalizing different instruments (i)
3072 If the minimum and maximum MIDI volume properties are set in
3073 the @code{Staff} context the relative volumes of the MIDI
3074 instruments can be controlled. This gives a basic instrument
3075 equalizer, which can enhance the quality of the MIDI output
3078 In this example the volume of the clarinet is reduced relative
3079 to the volume of the flute. There must be a dynamic
3080 mark on the first note of each instrument for this to work
3083 @lilypond[verbatim,quote]
3089 \set Staff.midiInstrument = #"flute"
3090 \set Staff.midiMinimumVolume = #0.7
3091 \set Staff.midiMaximumVolume = #0.9
3092 \new Voice \relative c''' {
3100 \set Staff.midiInstrument = #"clarinet"
3101 \set Staff.midiMinimumVolume = #0.3
3102 \set Staff.midiMaximumVolume = #0.6
3103 \new Voice \relative c'' {
3118 @node Equalizing different instruments (ii)
3119 @unnumberedsubsubsec Equalizing different instruments (ii)
3121 If the MIDI minimum and maximum volume properties are not set
3122 LilyPond will, by default, apply a small degree of equalization
3123 to a few instruments. The instruments and the equalization
3124 applied are shown in the table @notation{instrument-equalizer-alist}
3125 in @file{../scm/midi.scm}.
3127 This basic default equalizer can be replaced by setting
3128 @code{instrumentEqualizer} in the @code{Score} context to a new
3129 Scheme procedure which accepts a MIDI instrument name as its only
3130 argument and returns a pair of fractions giving the minimum and
3131 maximum volumes to be applied to that instrument. This replacement
3132 is done in the same way as shown for resetting the
3133 @code{dynamicAbsoluteVolumeFunction} at the start of this section.
3134 The default equalizer, @notation{default-instrument-equalizer}, in
3135 @file{../scm/midi.scm} shows how such a procedure might be written.
3137 The following example sets the relative flute and clarinet volumes
3138 to the same values as the previous example.
3140 @lilypond[verbatim,quote]
3141 #(define my-instrument-equalizer-alist '())
3143 #(set! my-instrument-equalizer-alist
3146 ("flute" . (0.7 . 0.9))
3147 ("clarinet" . (0.3 . 0.6)))
3148 my-instrument-equalizer-alist))
3150 #(define (my-instrument-equalizer s)
3151 (let ((entry (assoc s my-instrument-equalizer-alist)))
3160 \set Score.instrumentEqualizer = #my-instrument-equalizer
3161 \set Staff.midiInstrument = #"flute"
3162 \new Voice \relative c''' {
3170 \set Staff.midiInstrument = #"clarinet"
3171 \new Voice \relative c'' {
3186 @c Delete when satisfied this is adequately covered elsewhere -td
3188 @n ode Microtones in MIDI
3189 @s ubsection Microtones in MIDI
3191 @cindex microtones in MIDI
3193 Microtones consisting of half sharps and half flats are exported
3194 to the MIDI file and render correctly in MIDI players which support
3195 pitch bending. See @ref{Note names in other languages}. Here is
3196 an example showing all the half sharps and half flats. It can be
3197 copied out and compiled to test microtones in your MIDI player.
3199 @lilypond[verbatim,quote]
3216 @node Percussion in MIDI
3217 @subsection Percussion in MIDI
3219 Percussion instruments are generally notated in a @code{DrumStaff}
3220 context and when notated in this way they are outputted correctly
3221 to MIDI channel@tie{}10, but some pitched percussion instruments,
3222 like the xylophone, marimba, vibraphone, timpani, etc., are
3223 treated like @qq{normal} instruments and music for these instruments
3224 should be entered in a normal @code{Staff} context, not a
3225 @code{DrumStaff} context, to obtain the correct MIDI output.
3227 Some non-pitched percussion sounds included in the general MIDI
3228 standard, like melodic tom, taiko drum, synth drum, etc., cannot
3229 be reached via MIDI channel@tie{}10, so the notation for such
3230 instruments should also be entered in a normal @code{Staff}
3231 context, using suitable normal pitches.
3233 Many percussion instruments are not included in the general MIDI
3234 standard, e.g. castanets. The easiest, although unsatisfactory,
3235 method of producing some MIDI output when writing for such
3236 instruments is to substitute the nearest sound from the standard
3239 @c TODO Expand with examples, and any other issues
3243 Because the general MIDI standard does not contain rim shots, the
3244 sidestick is used for this purpose instead.
3246 @node The Articulate script
3247 @subsection The Articulate script
3249 A more realistic MIDI output is possible when using the Articulate
3250 script. It tries to take articulations (slurs, staccato, etc) into
3251 account, by replacing notes with sequential music of suitably
3252 time-scaled note plus skip. It also tries to unfold trills turns
3253 etc., and take rallentando and accelerando into account.
3255 To use the Articulate script, you have to include it at the top of
3259 \include "articulate.ly"
3262 and in the @code{\score} section do
3265 \unfoldRepeats \articulate <<
3266 all the rest of the score...
3270 After altering your input file this way, the visual output is heavily
3271 altered, but the standard @code{\midi} block will produce a better
3274 Although not essential for the Articulate script to work, you may want
3275 to insert the @code{\unfoldRepeats} command as it appears in the
3276 example shown above as it enables performing abbreviatures such as
3281 Articulate shortens chords and some music (esp. organ music) could
3285 @node Extracting musical information
3286 @section Extracting musical information
3288 In addition to creating graphical output and MIDI, LilyPond can
3289 display musical information as text.
3292 * Displaying LilyPond notation::
3293 * Displaying scheme music expressions::
3294 * Saving music events to a file::
3297 @node Displaying LilyPond notation
3298 @subsection Displaying LilyPond notation
3300 @funindex \displayLilyMusic
3301 Displaying a music expression in LilyPond notation can be
3302 done with the music function @code{\displayLilyMusic}. To see the
3303 output, you will typically want to call LilyPond using the command
3308 \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
3315 @{ a,4 cis e fis g @}
3318 By default, LilyPond will print these messages to the console
3319 along with all the other LilyPond compilation messages. To split
3320 up these messages and save the results of @code{\display@{STUFF@}},
3321 redirect the output to a file.
3324 lilypond file.ly >display.txt
3328 Note that Lilypond does not just display the music expression, but
3329 also interprets it (since @code{\displayLilyMusic} returns it in
3330 addition to displaying it). This is convenient since you can just
3331 insert @code{\displayLilyMusic} into existing music in order to get
3332 information about it. If you don't actually want Lilypond to
3333 interpret the displayed music as well as display it, use @code{\void}
3334 in order to have it ignored:
3338 \void \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
3343 @node Displaying scheme music expressions
3344 @subsection Displaying scheme music expressions
3346 See @rextend{Displaying music expressions}.
3349 @node Saving music events to a file
3350 @subsection Saving music events to a file
3352 Music events can be saved to a file on a per-staff basis by
3353 including a file in your main score.
3356 \include "event-listener.ly"
3359 This will create file(s) called @file{FILENAME-STAFFNAME.notes} or
3360 @file{FILENAME-unnamed-staff.notes} for each staff. Note that if
3361 you have multiple unnamed staves, the events for all staves will
3362 be mixed together in the same file. The output looks like this:
3365 0.000 note 57 4 p-c 2 12
3367 0.250 note 62 4 p-c 7 12
3368 0.500 note 66 8 p-c 9 12
3369 0.625 note 69 8 p-c 14 12
3374 The syntax is a tab-delimited line, with two fixed fields on each
3375 line followed by optional parameters.
3378 @var{time} @var{type} @var{...params...}
3381 This information can easily be read into other programs such as
3382 python scripts, and can be very useful for researchers wishing to
3383 perform musical analysis or playback experiments with LilyPond.
3388 Not all lilypond music events are supported by
3389 @file{event-listener.ly}. It is intended to be a well-crafted
3390 @qq{proof of concept}. If some events that you want to see are
3391 not included, copy @file{event-listener.ly} into your lilypond
3392 directory and modify the file so that it outputs the information