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::
24 * Creating MIDI 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{%@{ @dots{} %@}} 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,
136 @var{@dots{}music@dots{}}
140 and texts are entered with a @code{\markup} block,
144 @var{@dots{}text@dots{}}
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 @dots{}text of second verse@dots{}
188 @dots{}text of third verse@dots{}
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
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 outputs 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,,The @code{@bs{}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 file @file{../scm/lily-library.scm} and set in the file
379 @file{../ly/declarations-init.ly}.)
382 A @code{\book} block logically combines multiple movements
383 (i.e., multiple @code{\score} blocks) in one document. If there
384 are a number of @code{\score}s, one output file will be created
385 for each @code{\book} block, in which all corresponding movements
386 are concatenated. The only reason to explicitly specify
387 @code{\book} blocks in a @file{.ly} file is if you wish to create
388 multiple output files from a single input file. One exception is
389 within lilypond-book documents, where you explicitly have to add
390 a @code{\book} block if you want more than a single @code{\score}
391 or @code{\markup} in the same example. This behavior can be
392 changed by setting the variable @code{toplevel-book-handler} at
393 toplevel. The default handler is defined in the init file
394 @file{../scm/lily.scm}.
397 A @code{\bookpart} block. A book may be divided into several parts,
398 using @code{\bookpart} blocks, in order to ease the page breaking,
399 or to use different @code{\paper} settings in different parts.
402 A compound music expression, such as
407 This will add the piece in a @code{\score} and format it in a
408 single book together with all other toplevel @code{\score}s and music
409 expressions. In other words, a file containing only the above
410 music expression will be translated into
427 This behavior can be changed by setting the variable
428 @code{toplevel-music-handler} at toplevel. The default handler is
429 defined in the init file @file{../scm/lily.scm}.
432 A markup text, a verse for example
435 2. The first line verse two.
439 Markup texts are rendered above, between or below the scores or music
440 expressions, wherever they appear.
450 This can be used later on in the file by entering @code{\foo}. The
451 name of a variable should have alphabetic characters only; no
452 numbers, underscores or dashes.
456 The following example shows three things that may be entered at
461 % Don't justify the output
473 At any point in a file, any of the following lexical instructions can
477 @item @code{\version}
478 @item @code{\include}
479 @item @code{\sourcefilename}
480 @item @code{\sourcefileline}
482 A single-line comment, introduced by a leading @code{%} sign.
485 A multi-line comment delimited by @code{%@{ @dots{} %@}}.
491 Whitespace between items in the input stream is generally ignored,
492 and may be freely omitted or extended to enhance readability.
493 However, whitespace should always be used in the following
494 circumstances to avoid errors:
498 @item Around every opening and closing curly bracket.
500 @item After every command or variable, i.e., every item that
501 begins with a @code{\} sign.
503 @item After every item that is to be interpreted as a Scheme
504 expression, i.e., every item that begins with a @code{#}@tie{}sign.
506 @item To separate all elements of a Scheme expression.
508 @item In @code{lyricmode} before and after @code{\set} and
509 @code{\override} commands.
515 @rlearning{How LilyPond input files work}.
518 @ref{Titles explained},
519 @ref{The layout block,,The @code{@bs{}layout} block}.
522 @node Titles and headers
523 @section Titles and headers
529 Almost all printed music includes a title and the composer's name;
530 some pieces include a lot more information.
533 * Creating titles headers and footers::
534 * Custom titles headers and footers::
535 * Creating output file metadata::
536 * Creating footnotes::
537 * Reference to page numbers::
538 * Table of contents::
542 @node Creating titles headers and footers
543 @subsection Creating titles headers and footers
547 * Default layout of bookpart and score titles::
548 * Default layout of headers and footers::
552 @node Titles explained
553 @unnumberedsubsubsec Titles explained
555 Each @code{\book} block in a single input file produces a separate
556 output file, see @ref{File structure}. Within each output file
557 three types of titling areas are provided: @emph{Book Titles} at the
558 beginning of each book, @emph{Bookpart Titles} at the beginning of
559 each bookpart and @emph{Score Titles} at the beginning of each score.
561 Values of titling fields such as @code{title} and @code{composer}
562 are set in @code{\header} blocks. (For the syntax of @code{\header}
563 blocks and a complete list of the fields available by default see
564 @ref{Default layout of bookpart and score titles}). Book Titles,
565 Bookpart Titles and Score Titles can all contain the same fields,
566 although by default the fields in Score Titles are limited to
567 @code{piece} and @code{opus}.
569 @code{\header} blocks may be placed in four different places to form
570 a descending hierarchy of @code{\header} blocks:
575 At the top of the input file, before all @code{\book},
576 @code{\bookpart}, and @code{\score} blocks.
579 Within a @code{\book} block but outside all the @code{\bookpart} and
580 @code{\score} blocks within that book.
583 Within a @code{\bookpart} block but outside all @code{\score} blocks
584 within that bookpart.
587 After the music expression in a @code{\score} block.
591 The values of the fields filter down this hierarchy, with the values
592 set higher in the hierarchy persisting unless they are over-ridden
593 by a value set lower in the hierarchy, so:
598 A Book Title is derived from fields set at the top of the input file,
599 modified by fields set in the @code{\book} block. The resulting
600 fields are used to print the Book Title for that book, providing that
601 there is other material which generates a page at the start of the
602 book, before the first bookpart. A single @code{\pageBreak} will
606 A Bookpart Title is derived from fields set at the top of the input
607 file, modified by fields set in the @code{\book} block, and further
608 modified by fields set in the @code{\bookpart} block. The resulting
609 values are used to print the Bookpart Title for that bookpart.
612 A Score Title is derived from fields set at the top of the input
613 file, modified by fields set in the @code{\book} block, further
614 modified by fields set in the @code{\bookpart} block and finally
615 modified by fields set in the @code{\score} block. The resulting
616 values are used to print the Score Title for that score. Note,
617 though, that only @code{piece} and @code{opus} fields are printed
618 by default in Score Titles unless the @code{\paper} variable,
619 @code{print-all-headers}, is set to @code{#t}.
623 @warning{Remember when placing a @bs{}@code{header} block inside a
624 @bs{}@code{score} block, that the music expression must come before the
625 @bs{}@code{header} block.}
627 It is not necessary to provide @code{\header} blocks in all four
628 places: any or even all of them may be omitted. Similarly, simple
629 input files may omit the @code{\book} and @code{\bookpart} blocks,
630 leaving them to be created implicitly.
632 If the book has only a single score, the @code{\header} block should
633 normally be placed at the top of the file so that just a Bookpart
634 Title is produced, making all the titling fields available for use.
636 If the book has multiple scores a number of different arrangements
637 of @code{\header} blocks are possible, corresponding to the various
638 types of musical publications. For example, if the publication
639 contains several pieces by the same composer a @code{\header} block
640 placed at the top of the file specifying the book title and the
641 composer with @code{\header} blocks in each @code{\score} block
642 specifying the @code{piece} and/or @code{opus} would be most
645 @lilypond[papersize=a5,quote,verbatim,noragged-right]
648 composer = "J. S. Bach."
652 \new Staff \relative {
655 \repeat unfold 2 { g,16( d' b') a b d, b' d, } |
656 \repeat unfold 2 { g,16( e' c') b c e, c' e, } |
664 \new Staff \relative {
668 <g, d' b'~>4 b'16 a( g fis) g( d e fis) g( a b c) |
669 d16( b g fis) g( e d c) b(c d e) fis( g a b) |
677 More complicated arrangements are possible. For example, text
678 fields from the @code{\header} block in a book can be displayed in
679 all Score Titles, with some fields over-ridden and some manually
682 @lilypond[papersize=a5,quote,verbatim,noragged-right]
685 print-all-headers = ##t
688 title = "DAS WOHLTEMPERIRTE CLAVIER"
690 % Do not display the default LilyPond footer for this book
693 \markup { \vspace #1 }
697 \new Staff { \clef "bass" s1 }
700 title = "PRAELUDIUM I"
702 % Do not display the subtitle for this score
709 \new Staff { \clef "bass" s1 }
713 subsubtitle = "A 4 VOCI"
715 % Do not display the subtitle for this score
724 @ref{File structure},
725 @ref{Default layout of bookpart and score titles},
726 @ref{Custom layout for titles}.
729 @node Default layout of bookpart and score titles
730 @unnumberedsubsubsec Default layout of bookpart and score titles
732 This example demonstrates all printed @code{\header} variables:
734 @lilypond[papersize=a6landscape,quote,verbatim,noragged-right]
737 % The following fields are centered
738 dedication = "Dedication"
740 subtitle = "Subtitle"
741 subsubtitle = "Subsubtitle"
742 % The following fields are evenly spread on one line
743 % the field "instrument" also appears on following pages
744 instrument = \markup \with-color #green "Instrument"
746 composer = "Composer"
747 % The following fields are placed at opposite ends of the same line
749 arranger = "Arranger"
750 % The following fields are centered at the bottom
751 tagline = "The tagline goes at the bottom of the last page"
752 copyright = "The copyright goes at the bottom of the first page"
757 % The following fields are placed at opposite ends of the same line
765 % The following fields are placed at opposite ends of the same line
766 piece = "Piece 2 on the same page"
774 % The following fields are placed at opposite ends of the same line
775 piece = "Piece 3 on a new page"
786 The instrument name will be repeated on every page.
789 Only @code{piece} and @code{opus} are printed in a @code{\score}
790 when the paper variable @code{print-all-headers} is set to
791 @code{##f} (the default).
794 @c Is the bit about \null markups true? -mp
795 Text fields left unset in a @code{\header} block are replaced with
796 @code{\null} markups so that the space is not wasted.
799 The default settings for @code{scoreTitleMarkup} place the @code{piece}
800 and @code{opus} text fields at opposite ends of the same line.
804 To change the default layout see @ref{Custom layout for titles}.
808 If a @code{\book} block starts immediately with a @code{\bookpart}
809 block, no Book Title will be printed, as there is no page on which
810 to print it. If a Book Title is required, begin the @code{\book}
811 block with some markup material or a @code{\pageBreak} command.
813 Use the @code{breakbefore} variable inside a @code{\header} block
814 that is itself in a @code{\score} block, to make the higher-level
815 @code{\header} block titles appear on the first page on their own, with
816 the music (defined in the @code{\score} block) starting on the next.
818 @lilypond[papersize=c7landscape,verbatim,noragged-right]
821 title = "This is my Title"
822 subtitle = "This is my Subtitle"
823 copyright = "This is the bottom of the first page"
826 \repeat unfold 4 { e'' e'' e'' e'' }
828 piece = "This is the Music"
837 @rlearning{How LilyPond input files work},
840 @ref{Custom layout for titles},
841 @ref{File structure}.
844 @file{ly/titling-init.ly}.
847 @node Default layout of headers and footers
848 @unnumberedsubsubsec Default layout of headers and footers
850 @emph{Headers} and @emph{footers} are lines of text appearing at
851 the top and bottom of pages, separate from the main text of a book.
852 They are controlled by the following @code{\paper} variables:
855 @item @code{oddHeaderMarkup}
856 @item @code{evenHeaderMarkup}
857 @item @code{oddFooterMarkup}
858 @item @code{evenFooterMarkup}
861 These markup variables can only access text fields from top-level
862 @code{\header} blocks (which apply to all scores in the book) and are
863 defined in @file{ly/titling-init.ly}. By default:
868 page numbers are automatically placed on the top far left (if even) or
869 top far right (if odd), starting from the second page.
872 the @code{instrument} text field is placed in the center of every
873 page, starting from the second page.
876 the @code{copyright} text is centered on the bottom of the first page.
879 the @code{tagline} is centered on the bottom of the last page, and below
880 the @code{copyright} text if there is only a single page.
884 The default LilyPond footer text can be changed by adding a
885 @code{tagline} in the top-level @code{\header} block.
887 @lilypond[papersize=a8landscape,verbatim]
890 tagline = "... music notation for Everyone"
900 To remove the default LilyPond footer text, the @code{tagline} can be
904 @node Custom titles headers and footers
905 @subsection Custom titles headers and footers
907 @c TODO: somewhere put a link to header spacing info
908 @c (you'll have to explain it more in NR 4).
911 * Custom text formatting for titles::
912 * Custom layout for titles::
913 * Custom layout for headers and footers::
917 @node Custom text formatting for titles
918 @unnumberedsubsubsec Custom text formatting for titles
920 Standard @code{\markup} commands can be used to customize any header,
921 footer and title text within the @code{\header} block.
923 @lilypond[quote,verbatim,noragged-right]
927 piece = \markup { \fontsize #4 \bold "PRAELUDIUM I" }
928 opus = \markup { \italic "BWV 846" }
935 @ref{Formatting text}.
938 @node Custom layout for titles
939 @unnumberedsubsubsec Custom layout for titles
941 @cindex bookTitleMarkup
942 @cindex scoreTitleMarkup
943 @funindex bookTitleMarkup
944 @funindex scoreTitleMarkup
946 @code{\markup} commands in the @code{\header} block are useful for
947 simple text formatting, but they do not allow precise control over the
948 placement of titles. To customize the placement of the text fields,
949 change either or both of the following @code{\paper} variables:
952 @item @code{bookTitleMarkup}
953 @item @code{scoreTitleMarkup}
956 The placement of titles when using the default values of these
957 @code{\markup} variables is shown in the examples in
958 @ref{Default layout of bookpart and score titles}.
960 The default settings for @code{scoreTitleMarkup} as defined in
961 @file{ly/titling-init.ly} are:
964 scoreTitleMarkup = \markup @{ \column @{
965 \on-the-fly \print-all-headers @{ \bookTitleMarkup \hspace #1 @}
967 \fromproperty #'header:piece
968 \fromproperty #'header:opus
974 This places the @code{piece} and @code{opus} text fields at opposite
975 ends of the same line:
977 @lilypond[quote,verbatim,noragged-right]
981 piece = "PRAELUDIUM I"
987 This example redefines @code{scoreTitleMarkup} so that the @code{piece}
988 text field is centered and in a large, bold font.
990 @lilypond[papersize=a5,quote,verbatim,noragged-right]
994 scoreTitleMarkup = \markup {
997 \fontsize #4 \bold \fromproperty #'header:piece
998 \fromproperty #'header:opus
1002 \header { tagline = ##f }
1006 piece = "PRAELUDIUM I"
1013 Text fields not normally effective in score @code{\header} blocks
1014 can be printed in the Score Title area if @code{print-all-headers} is
1015 placed inside the @code{\paper} block. A disadvantage of using this
1016 method is that text fields that are intended specifically for the
1017 Bookpart Title area need to be manually suppressed in every
1018 @code{\score} block. See @ref{Titles explained}.
1020 To avoid this, add the desired text field to the @code{scoreTitleMarkup}
1021 definition. In the following example, the @code{composer} text field
1022 (normally associated with @code{bookTitleMarkup}) is added to
1023 @code{scoreTitleMarkup}, allowing each score to list a different
1026 @lilypond[papersize=a5,quote,verbatim,noragged-right]
1030 scoreTitleMarkup = \markup {
1033 \fontsize #4 \bold \fromproperty #'header:piece
1034 \fromproperty #'header:composer
1038 \header { tagline = ##f }
1043 composer = "Christian Petzold"
1050 composer = "François Couperin"
1056 It is also possible to create your own custom text fields, and refer to
1057 them in the markup definition.
1059 @lilypond[papersize=a5,quote,verbatim,noragged-right]
1063 scoreTitleMarkup = \markup {
1066 \override #`(direction . ,UP) {
1068 \center-align \fontsize #-1 \bold
1069 \fromproperty #'header:mycustomtext %% User-defined field
1070 \center-align \fontsize #4 \bold
1071 \fromproperty #'header:piece
1074 \fromproperty #'header:opus
1078 \header { tagline = ##f }
1083 mycustomtext = "A 4 VOCI" %% User-defined field
1092 @ref{Titles explained}.
1095 @node Custom layout for headers and footers
1096 @unnumberedsubsubsec Custom layout for headers and footers
1098 @c can make-header and make-footer be removed from
1099 @c paper-defaults-init.ly? -mp
1101 @code{\markup} commands in the @code{\header} block are useful for
1102 simple text formatting, but they do not allow precise control over the
1103 placement of headers and footers. To customize the placement of
1104 the text fields, use either or both of the following @code{\paper}
1108 @item @code{oddHeaderMarkup}
1109 @item @code{evenHeaderMarkup}
1110 @item @code{oddFooterMarkup}
1111 @item @code{evenFooterMarkup}
1114 @cindex markup, conditional
1116 @funindex \on-the-fly
1118 The @code{\markup} command @code{\on-the-fly} can be used to add
1119 markup conditionally to header and footer text defined within the
1120 @code{\paper} block, using the following syntax:
1123 variable = \markup @{
1125 \on-the-fly \@var{procedure} @var{markup}
1130 The @var{procedure} is called each time the @code{\markup} command
1131 in which it appears is evaluated. The @var{procedure} should test
1132 for a particular condition and interpret (i.e., print) the
1133 @var{markup} argument if and only if the condition is true.
1135 A number of ready-made procedures for testing various conditions are
1139 @multitable {print-page-number-check-first-----} {should this page be printed-----}
1141 @headitem Procedure name @tab Condition tested
1143 @item print-page-number-check-first @tab should this page number be printed?
1144 @item create-page-number-stencil @tab print-page-numbers true?
1145 @item print-all-headers @tab print-all-headers true?
1146 @item first-page @tab first page in the book?
1147 @item not-first-page @tab not first page in the book?
1148 @item (on-page nmbr) @tab page number = nmbr?
1149 @item last-page @tab last page in the book?
1150 @item part-first-page @tab first page in the book part?
1151 @item not-part-first-page @tab not first page in the book part?
1152 @item part-last-page @tab last page in the book part?
1153 @item not-single-page @tab pages in book part > 1?
1158 The following example centers page numbers at the bottom of every
1159 page. First, the default settings for @code{oddHeaderMarkup} and
1160 @code{evenHeaderMarkup} are removed by defining each as a @emph{null}
1161 markup. Then, @code{oddFooterMarkup} is redefined with the page
1162 number centered. Finally, @code{evenFooterMarkup} is given the
1163 same layout by defining it as @code{\oddFooterMarkup}:
1165 @lilypond[papersize=a8,quote,verbatim,noragged-right]
1168 print-page-number = ##t
1169 print-first-page-number = ##t
1170 oddHeaderMarkup = \markup \null
1171 evenHeaderMarkup = \markup \null
1172 oddFooterMarkup = \markup {
1174 \on-the-fly \print-page-number-check-first
1175 \fromproperty #'page:page-number-string
1178 evenFooterMarkup = \oddFooterMarkup
1181 \new Staff { s1 \break s1 \break s1 }
1186 Several @code{\on-the-fly} conditions can be combined with an
1187 @q{and} operation, for example,
1190 \on-the-fly \first-page
1191 \on-the-fly \last-page
1192 @code{@{ \markup @dots{} \fromproperty #'header: @dots{} @}}
1195 determines if the output is a single page.
1199 @ref{Titles explained},
1200 @ref{Default layout of bookpart and score titles}.
1203 @file{../ly/titling-init.ly}.
1205 @node Creating output file metadata
1206 @subsection Creating output file metadata
1208 @cindex PDF metadata
1209 @cindex MIDI metadata
1211 In addition to being shown in the printed output, @code{\header} variables
1212 are also used to set metadata for output files. For example, with PDF
1213 files, this metadata could be displayed by PDF readers as the
1214 @code{properties} of the PDF file. For each type of output file, only the
1215 @code{\header} definitions of blocks that define separate files of that
1216 type, and blocks higher in the block hierarchy, will be consulted.
1217 Therefore, for PDF files, only the @code{\book} level and the top level
1218 @code{\header} definitions affect the document-wide PDF metadata, whereas
1219 for MIDI files, all headers above or at the @code{\score} level are used.
1221 For example, setting the @code{title} property of the @code{header} block
1222 to @q{Symphony I} will also give this title to the PDF document, and use
1223 it as the sequence name of the MIDI file.
1227 title = "Symphony I"
1231 If you want to set the title of the printed output to one value, but have the
1232 title property of the PDF to have a different value, you can use
1233 @code{pdftitle}, as below.
1237 title = "Symphony I"
1238 pdftitle = "Symphony I by Beethoven"
1242 The variables @code{title}, @code{subject}, @code{keywords},
1243 @code{subtitle}, @code{composer}, @code{arranger}, @code{poet}, @code{author}
1244 and @code{copyright} all set PDF properties and can all be prefixed with
1245 @q{pdf} to set a PDF property to a value different from the printed output.
1247 The PDF property @code{Creator} is automatically set to @q{LilyPond} plus
1248 the current LilyPond version, and @code{CreationDate} and @code{ModDate} are
1249 both set to the current date and time. @code{ModDate} can be overridden by
1250 setting the header variable @code{moddate} (or @code{pdfmoddate}) to a
1251 valid PDF date string.
1253 The @code{title} variable sets also the sequence name for MIDI. The
1254 @code{midititle} variable can be used to set the sequence name
1255 independently of the value used for typeset output.
1257 @node Creating footnotes
1258 @subsection Creating footnotes
1262 Footnotes may be used in many different situations. In all cases,
1263 a @q{footnote mark} is placed as a reference in text or music, and
1264 the corresponding @q{footnote text} appears at the bottom of the
1267 Footnotes within music expressions and footnotes in stand-alone text
1268 outside music expressions are created in different ways.
1271 * Footnotes in music expressions::
1272 * Footnotes in stand-alone text::
1275 @node Footnotes in music expressions
1276 @unnumberedsubsubsec Footnotes in music expressions
1278 @cindex footnotes in music expressions
1281 @subsubsubheading Music footnotes overview
1283 Footnotes in music expressions fall into two categories:
1286 @item Event-based footnotes
1287 are attached to a particular event. Examples for such events are
1288 single notes, articulations (like fingering indications, accents,
1289 dynamics), and post-events (like slurs and manual beams). The
1290 general form for event-based footnotes is as follows:
1293 [@var{direction}] \footnote [@var{mark}] @var{offset} @var{footnote} @var{music}
1296 @item Time-based footnotes
1297 are bound to a particular point of time in a musical context. Some
1298 commands like @code{\time} and @code{\clef} don't actually use events
1299 for creating objects like time signatures and clefs. Neither does a
1300 chord create an event of its own: its stem or flag is created at the
1301 end of a time step (nominally through one of the note events inside).
1302 Exactly which of a chord's multiple note events will be deemed the
1303 root cause of a stem or flag is undefined. So for annotating those,
1304 time-based footnotes are preferable as well.
1306 A time-based footnote allows such layout objects to be annotated
1307 without referring to an event. The general form for Time-based
1311 \footnote [@var{mark}] @var{offset} @var{footnote} [@var{Context}].@var{GrobName}
1316 The elements for both forms are:
1321 If (and only if) the @code{\footnote} is being applied to a
1322 post-event or articulation, it must be preceded with a direction
1323 indicator (@code{-, _, ^}) in order to attach @var{music} (with
1324 a footnote mark) to the preceding note or rest.
1327 is a markup or string specifying the footnote mark which is used for
1328 marking both the reference point and the footnote itself at the
1329 bottom of the page. It may be omitted (or equivalently replaced with
1330 @code{\default}) in which case a number in sequence will be generated
1331 automatically. Such numerical sequences restart on each page
1332 containing a footnote.
1335 is a number pair such as @samp{#(2 . 1)} specifying the X and
1336 Y@tie{}offsets in units of staff-spaces from the boundary of the
1337 object where the mark should be placed. Positive values of the
1338 offsets are taken from the right/top edge, negative values from the
1339 left/bottom edge and zero implies the mark is centered on the edge.
1342 is the context in which the grob being footnoted is created. It
1343 may be omitted if the grob is in a bottom context, e.g., a
1344 @code{Voice} context.
1347 specifies a type of grob to mark (like @samp{Flag}). If it is
1348 specified, the footnote is not attached to a music expression in
1349 particular, but rather to all grobs of the type specified which
1350 occur at that moment of musical time.
1353 is the markup or string specifying the footnote text to use at the
1357 is the music event or post-event or articulation
1358 that is being annotated.
1362 @subsubsubheading Event-based footnotes
1364 @cindex footnotes, event-based
1366 A footnote may be attached to a layout object directly caused
1367 by the event corresponding to @var{music} with the syntax:
1370 \footnote [@var{mark}] @var{offset} @var{footnote} @var{music}
1373 @lilypond[quote,verbatim,papersize=a8landscape]
1375 \header { tagline = ##f }
1377 \footnote #'(-1 . 3) "A note" a4
1379 \footnote #'(2 . 2) "A rest" r4
1385 Marking a @emph{whole} chord with an event-based footnote is not
1386 possible: a chord, even one containing just a single note, does
1387 not produce an actual event of its own. However, individual
1388 notes @emph{inside} of the chord can be marked:
1390 @lilypond[quote,verbatim,papersize=a8landscape]
1392 \header { tagline = ##f }
1394 \footnote #'(2 . 3) "Does not work" <a-3>2
1395 <\footnote #'(-2 . -3) "Does work" a-3>4
1396 <a-3 \footnote #'(3 . 1/2) "Also works" c-5>4
1401 If the footnote is to be attached to a post-event or articulation
1402 the @code{\footnote} command @emph{must} be preceded by a direction
1403 indicator, @code{-, _, ^}, and followed by the post-event or
1404 articulation to be annotated as the @var{music} argument. In this
1405 form the @code{\footnote} can be considered to be simply a copy of
1406 its last argument with a footnote mark attached to it. The syntax
1410 @var{direction} \footnote [@var{mark}] @var{offset} @var{footnote} @var{music}
1413 @lilypond[quote,verbatim,papersize=a8landscape]
1415 \header { tagline = ##f }
1417 a'4_\footnote #'(0 . -1) "A slur forced down" (
1418 b8^\footnote #'(1 . 0.5) "A manual beam forced up" [
1421 c-\footnote #'(1 . 1) "Tenuto" --
1426 @subsubsubheading Time-based footnotes
1428 @cindex footnotes, time-based
1430 If the layout object being footmarked is @emph{indirectly} caused by
1431 an event (like an @code{Accidental} or @code{Stem} caused by a
1432 @code{NoteHead} event), the @var{GrobName} of the layout object
1433 is required after the footnote text instead of @var{music}:
1435 @lilypond[quote,verbatim,papersize=a8landscape]
1437 \header { tagline = ##f }
1439 \footnote #'(-1 . -3) "A flat" Accidental
1441 \footnote #'(-1 . 0.5) "Another flat" Accidental
1443 \footnote #'(1 . -2) "A stem" Stem
1449 Note, however, that when a GrobName is specified, a footnote
1450 will be attached to all grobs of that type at the current time step:
1452 @lilypond[quote,verbatim,papersize=a8landscape]
1454 \header { tagline = ##f }
1456 \footnote #'(-1 . 3) "A flat" Accidental
1458 \footnote #'(2 . 0.5) "Articulation" Script
1464 A note inside of a chord can be given an individual (event-based)
1465 footnote. A @samp{NoteHead} is the only grob directly caused
1466 from a chord note, so an event-based footnote command is
1467 @emph{only} suitable for adding a footnote to the @samp{NoteHead}
1468 within a chord. All other chord note grobs are indirectly caused.
1469 The @code{\footnote} command itself offers no syntax for
1470 specifying @emph{both} a particular grob type @emph{as well as} a
1471 particular event to attach to. However, one can use a time-based
1472 @code{\footnote} command for specifying the grob type, and then
1473 prefix this command with @code{\single} in order to have it
1474 applied to just the following event:
1476 @lilypond[quote,verbatim,papersize=a8landscape]
1478 \header { tagline = ##f }
1480 < \footnote #'(1 . -2) "An A" a
1481 \single \footnote #'(-1 . -1) "A sharp" Accidental
1483 \single \footnote #'(0.5 . 0.5) "A flat" Accidental
1490 @warning {When footnotes are attached to several musical elements at
1491 the same musical moment, as they are in the example above, the
1492 footnotes are numbered from the higher to the lower elements as they
1493 appear in the printed output, not in the order in which they are
1494 written in the input stream.}
1496 Layout objects like clefs and key-change signatures are mostly caused
1497 as a consequence of changed properties rather than actual events.
1498 Others, like bar lines and bar numbers, are a direct consequence of
1499 timing. For this reason, footnotes on such objects have to be based
1500 on their musical timing. Time-based footnotes are also preferable
1501 when marking features like stems and beams on @emph{chords}: while
1502 such per-chord features are nominally assigned to @emph{one} event
1503 inside the chord, relying on a particular choice would be imprudent.
1505 The layout object in question must always be explicitly specified
1506 for time-based footnotes, and the appropriate context must be
1507 specified if the grob is created in a context other than the bottom
1510 @lilypond[quote,verbatim,papersize=a8landscape]
1512 \header { tagline = ##f }
1515 \footnote #'(-0.5 . -1) "Meter change" Staff.TimeSignature
1517 \footnote #'(1 . -1) "Chord stem" Stem
1519 \footnote #'(-0.5 . 1) "Bar line" Staff.BarLine
1521 \footnote #'(0.5 . -1) "Key change" Staff.KeySignature
1528 Custom marks can be used as alternatives to numerical marks, and the
1529 annotation line joining the marked object to the mark can be
1532 @lilypond[quote,verbatim,papersize=a8landscape]
1534 \header { tagline = ##f }
1536 \footnote "*" #'(0.5 . -2) \markup { \italic "* The first note" } a'4
1538 \footnote \markup { \super "$" } #'(0.5 . 1)
1539 \markup { \super "$" \italic " The second note" } e
1541 \once \override Score.FootnoteItem.annotation-line = ##f
1542 b-\footnote \markup \tiny "+" #'(0.1 . 0.1)
1543 \markup { \super "+" \italic " Editorial" } \p
1548 More examples of custom marks are shown in
1549 @ref{Footnotes in stand-alone text}.
1552 @node Footnotes in stand-alone text
1553 @unnumberedsubsubsec Footnotes in stand-alone text
1555 @cindex footnotes in stand-alone text
1557 These are for use in markup outside of music expressions. They do
1558 not have a line drawn to their point of reference: their marks simply
1559 follow the referenced markup. Marks can be inserted automatically,
1560 in which case they are numerical. Alternatively, custom marks can be
1563 Footnotes to stand-alone text with automatic and custom marks are
1564 created in different ways.
1566 @subsubsubheading Footnotes in stand-alone text with automatic marks
1568 The syntax of a footnote in stand-alone text with automatic marks is
1571 \markup @{ @dots{} \auto-footnote @var{text} @var{footnote} @dots{} @}
1579 is the markup or string to be marked.
1582 is the markup or string specifying the footnote text to use at the bottom
1589 @lilypond[verbatim,quote,ragged-right,papersize=a8]
1591 \header { tagline = ##f }
1594 \auto-footnote "tune" \italic " By me"
1595 "is shown below. It is a"
1596 \auto-footnote "recent" \italic " Aug 2012"
1605 @subsubsubheading Footnotes in stand-alone text with custom marks
1607 The syntax of a footnote in stand-alone text with custom marks is
1610 \markup @{ @dots{} \footnote @var{mark} @var{footnote} @dots{} @}
1618 is a markup or string specifying the footnote mark which is used for
1619 marking the reference point. Note that this mark is @emph{not}
1620 inserted automatically before the footnote itself.
1623 is the markup or string specifying the footnote text to use at the
1624 bottom of the page, preceded by the @var{mark}.
1628 Any easy-to-type character such as * or + may be used as a mark, as
1629 shown in @ref{Footnotes in music expressions}. Alteratively, ASCII
1630 aliases may be used (see @ref{ASCII aliases}):
1632 @lilypond[verbatim,quote,ragged-right,papersize=a8]
1634 \paper { #(include-special-characters) }
1635 \header { tagline = ##f }
1638 \footnote "*" \italic "* By me"
1639 "is shown below. It is a recent"
1640 \footnote \super † \concat {
1641 \super † \italic " Aug 2012"
1651 Unicode character codes may also be used to specify marks
1652 (see @ref{Unicode}):
1654 @lilypond[verbatim,quote,ragged-right,papersize=a8]
1656 \header { tagline = ##f }
1659 \footnote \super \char##x00a7 \concat {
1660 \super \char##x00a7 \italic " By me"
1662 "is shown below. It is a recent"
1663 \footnote \super \char##x00b6 \concat {
1664 \super \char##x00b6 \italic " Aug 2012"
1676 @rlearning{Objects and interfaces}.
1679 @ref{ASCII aliases},
1681 @ref{List of special characters},
1686 Internals Reference:
1687 @rinternals{FootnoteEvent},
1688 @rinternals{FootnoteItem},
1689 @rinternals{FootnoteSpanner},
1690 @rinternals{Footnote_engraver}.
1693 Multiple footnotes for the same page can only be stacked, one above
1694 the other; they cannot be printed on the same line.
1696 Footnotes cannot be attached to @code{MultiMeasureRests} or
1697 automatic beams or lyrics.
1699 Footnote marks may collide with staves, @code{\markup} objects, other
1700 footnote marks and annotation lines.
1703 @node Reference to page numbers
1704 @subsection Reference to page numbers
1706 A particular place of a score can be marked using the @code{\label}
1707 command, either at top-level or inside music. This label can then be
1708 referred to in a markup, to get the number of the page where the marked
1709 point is placed, using the @code{\page-ref} markup command.
1711 @lilypond[verbatim,papersize=a8landscape]
1712 \header { tagline = ##f }
1718 \pageBreak \mark A \label #'markA
1722 \markup { The first score begins on page \page-ref #'firstScore "0" "?" }
1723 \markup { Mark A is on page \page-ref #'markA "0" "?" }
1727 The @code{\page-ref} markup command takes three arguments:
1729 @item the label, a scheme symbol, eg. @code{#'firstScore};
1730 @item a markup that will be used as a gauge to estimate the dimensions
1732 @item a markup that will be used in place of the page number if the label
1736 The reason why a gauge is needed is that, at the time markups are
1737 interpreted, the page breaking has not yet occurred, so the page numbers
1738 are not yet known. To work around this issue, the actual markup
1739 interpretation is delayed to a later time; however, the dimensions of
1740 the markup have to be known before, so a gauge is used to decide these
1741 dimensions. If the book has between 10 and 99 pages, it may be "00",
1742 ie. a two digit number.
1753 @node Table of contents
1754 @subsection Table of contents
1755 A table of contents is included using the
1756 @code{\markuplist \table-of-contents} command. The elements which
1757 should appear in the table of contents are entered with the
1758 @code{\tocItem} command, which may be used either at top-level, or
1759 inside a music expression.
1762 \markuplist \table-of-contents
1765 \tocItem \markup "First score"
1769 \tocItem \markup "Some particular point in the first score"
1774 \tocItem \markup "Second score"
1782 Markups used for formatting the table of contents are defined in the
1783 @code{\paper} block. There are two @q{pre-defined} markups already
1789 @code{tocTitleMarkup}
1792 Used for formatting the title of the table of contents.
1795 tocTitleMarkup = \markup \huge \column {
1796 \fill-line { \null "Table of Contents" \null }
1802 @code{tocItemMarkup}
1805 Used for formatting the elements within the table of contents.
1808 tocItemMarkup = \markup \fill-line {
1809 \fromproperty #'toc:text \fromproperty #'toc:page
1816 Both of these variables can be changed.
1818 Here is an example changing the table of contents' title into French;
1822 tocTitleMarkup = \markup \huge \column {
1823 \fill-line { \null "Table des matières" \null }
1828 Here is an example changing the font-size of the elements in the table
1832 tocItemMarkup = \markup \large \fill-line {
1833 \fromproperty #'toc:text \fromproperty #'toc:page
1837 Note how the element text and page numbers are referred to in the
1838 @code{tocItemMarkup} definition.
1840 The @code{\tocItemWithDotsMarkup} command can be included within the
1841 @code{tocItemMarkup} to fill the line, between a table of contents item
1842 and its corresponding page number, with dots;
1844 @lilypond[verbatim,line-width=10.0\cm]
1845 \header { tagline = ##f }
1847 tocItemMarkup = \tocItemWithDotsMarkup
1851 \markuplist \table-of-contents
1852 \tocItem \markup { Allegro }
1853 \tocItem \markup { Largo }
1858 Custom commands with their own markups can also be defined to build a
1859 more complex table of contents. In the following example, a new style
1860 is defined for entering act names in a table of contents of an opera;
1863 A new markup variable (called @code{tocActMarkup}) is defined in the
1864 @code{\paper} block;
1868 tocActMarkup = \markup \large \column {
1870 \fill-line { \null \italic \fromproperty #'toc:text \null }
1877 A custom music function (@code{tocAct}) is then created -- which uses
1878 the new @code{tocActMarkup} markup definition.
1882 #(define-music-function (text) (markup?)
1883 (add-toc-item! 'tocActMarkup text))
1887 A LilyPond input file, using these customer definitions, could look
1888 something like this;
1890 @lilypond[line-width=10.0\cm]
1891 \header { tagline = ##f }
1893 tocActMarkup = \markup \large \column {
1895 \fill-line { \null \italic \fromproperty #'toc:text \null }
1901 #(define-music-function (text) (markup?)
1902 (add-toc-item! 'tocActMarkup text))
1905 \markuplist \table-of-contents
1906 \tocAct \markup { Atto Primo }
1907 \tocItem \markup { Coro. Viva il nostro Alcide }
1908 \tocItem \markup { Cesare. Presti omai l'Egizia terra }
1909 \tocAct \markup { Atto Secondo }
1910 \tocItem \markup { Sinfonia }
1911 \tocItem \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
1917 Here is an example of the @code{\fill-with-pattern} command used within
1918 the context of a table of contents;
1922 tocItemMarkup = \markup { \fill-line {
1923 \override #'(line-width . 70)
1924 \fill-with-pattern #1.5 #CENTER . \fromproperty #'toc:text \fromproperty #'toc:page
1932 @file{ly/toc-init.ly}.
1935 @funindex \table-of-contents
1936 @code{\table-of-contents},
1942 @node Working with input files
1943 @section Working with input files
1946 * Including LilyPond files::
1947 * Different editions from one source::
1948 * Special characters::
1952 @node Including LilyPond files
1953 @subsection Including LilyPond files
1956 @cindex including files
1958 A large project may be split up into separate files. To refer to
1962 \include "otherfile.ly"
1965 The line @code{\include "otherfile.ly"} is equivalent to pasting the
1966 contents of @file{otherfile.ly} into the current file at the place
1967 where the @code{\include} appears. For example, in a large
1968 project you might write separate files for each instrument part
1969 and create a @qq{full score} file which brings together the
1970 individual instrument files. Normally the included file will
1971 define a number of variables which then become available
1972 for use in the full score file. Tagged sections can be
1973 marked in included files to assist in making them usable in
1974 different places in a score, see @ref{Different editions from
1977 Files in the current working directory may be referenced by
1978 specifying just the file name after the @code{\include} command.
1979 Files in other locations may be included by giving either a full
1980 path reference or a relative path reference (but use the UNIX
1981 forward slash, /, rather than the DOS/Windows back slash, \, as the
1982 directory separator.) For example, if @file{stuff.ly} is located
1983 one directory higher than the current working directory, use
1986 \include "../stuff.ly"
1990 or if the included orchestral parts files are all located in a
1991 subdirectory called @file{parts} within the current directory, use
1994 \include "parts/VI.ly"
1995 \include "parts/VII.ly"
1999 Files which are to be included can also contain @code{\include}
2000 statements of their own. By default, these second-level
2001 @code{\include} statements are not interpreted until they have
2002 been brought into the main file, so the file names they specify
2003 must all be relative to the directory containing the main file,
2004 not the directory containing the included file. However,
2005 this behavior can be changed globally by passing the option
2006 @option{-drelative-includes} option at the command line
2007 (or by adding @code{#(ly:set-option 'relative-includes #t)}
2008 at the top of the main input file).
2010 When @code{relative-includes} is set to @code{#t}, the path for each
2011 @code{\include} command will be taken relative to the file containing
2012 that command. This behavior is recommended and it will become the
2013 default behavior in a future version of lilypond.
2015 Files relative to the main directory and files relative to some other
2016 directory may both be @code{\include}d by setting
2017 @code{relative-includes} to @code{#t} or @code{#f} at appropriate
2018 places in the files. For example, if a general library, libA, has
2019 been created which itself uses sub-files which are @code{\include}d
2020 by the entry file of that library, those @code{\include} statements
2021 will need to be preceded by
2022 @code{#(ly:set-option #relative-includes #t)} so they are interpreted
2023 correctly when brought into the main @code{.ly} file, like this:
2034 then the entry file, @code{libA.ly}, will contain
2037 #(ly:set-option 'relative-includes #t)
2041 % return to default setting
2042 #(ly:set-option 'relative-includes #f)
2045 Any @file{.ly} file can then include the entire library simply with
2048 \include "~/libA/libA.ly"
2051 More complex file structures may be devised by switching at
2054 Files can also be included from a directory in a search path
2055 specified as an option when invoking LilyPond from the command
2056 line. The included files are then specified using just their
2057 file name. For example, to compile @file{main.ly} which includes
2058 files located in a subdirectory called @file{parts} by this method,
2059 cd to the directory containing @file{main.ly} and enter
2062 lilypond --include=parts main.ly
2065 and in main.ly write
2073 Files which are to be included in many scores may be placed in
2074 the LilyPond directory @file{../ly}. (The location of this
2075 directory is installation-dependent - see
2076 @rlearning{Other sources of information}). These files can then
2077 be included simply by naming them on an @code{\include} statement.
2078 This is how the language-dependent files like @file{english.ly} are
2081 LilyPond includes a number of files by default when you start
2082 the program. These includes are not apparent to the user, but the
2083 files may be identified by running @code{lilypond --verbose} from
2084 the command line. This will display a list of paths and files that
2085 LilyPond uses, along with much other information. Alternatively,
2086 the more important of these files are discussed in
2087 @rlearning{Other sources of information}. These files may be
2088 edited, but changes to them will be lost on installing a new
2089 version of LilyPond.
2091 Some simple examples of using @code{\include} are shown in
2092 @rlearning{Scores and parts}.
2096 @rlearning{Other sources of information},
2097 @rlearning{Scores and parts}.
2100 If an included file is given a name which is the same as one in
2101 LilyPond's installation files, LilyPond's file from the
2102 installation files takes precedence.
2105 @node Different editions from one source
2106 @subsection Different editions from one source
2108 Several methods can be used to generate different versions of a score
2109 from the same music source. Variables are perhaps the most useful for
2110 combining lengthy sections of music and/or annotation. Tags are more
2111 useful for selecting one section from several alternative shorter
2112 sections of music, and can also be used for splicing pieces of music
2113 together at different points.
2115 Whichever method is used, separating the notation from the structure of
2116 the score will make it easier to change the structure while leaving the
2122 * Using global settings::
2125 @node Using variables
2126 @unnumberedsubsubsec Using variables
2128 @cindex variables, use of
2130 If sections of the music are defined in variables they can be
2131 reused in different parts of the score, see @rlearning{Organizing
2132 pieces with variables}. For example, an @notation{a cappella}
2133 vocal score frequently includes a piano reduction of the parts
2134 for rehearsal purposes which is identical to the vocal music, so
2135 the music need be entered only once. Music from two variables
2136 may be combined on one staff, see @ref{Automatic part combining}.
2139 @lilypond[verbatim,quote]
2140 sopranoMusic = \relative { a'4 b c b8( a) }
2141 altoMusic = \relative { e'4 e e f }
2142 tenorMusic = \relative { c'4 b e d8( c) }
2143 bassMusic = \relative { a4 gis a d, }
2144 allLyrics = \lyricmode { King of glo -- ry }
2146 \new Staff = "Soprano" \sopranoMusic
2147 \new Lyrics \allLyrics
2148 \new Staff = "Alto" \altoMusic
2149 \new Lyrics \allLyrics
2150 \new Staff = "Tenor" {
2154 \new Lyrics \allLyrics
2155 \new Staff = "Bass" {
2159 \new Lyrics \allLyrics
2162 \partcombine \sopranoMusic \altoMusic
2166 \partcombine \tenorMusic \bassMusic
2172 Separate scores showing just the vocal parts or just the piano
2173 part can be produced by changing just the structural statements,
2174 leaving the musical notation unchanged.
2176 For lengthy scores, the variable definitions may be placed in
2177 separate files which are then included, see @ref{Including
2181 @unnumberedsubsubsec Using tags
2184 @funindex \keepWithTag
2185 @funindex \removeWithTag
2187 @cindex keep tagged music
2188 @cindex remove tagged music
2190 The @code{\tag #'@var{partA}} command marks a music expression
2191 with the name @var{partA}.
2192 Expressions tagged in this way can be selected or filtered out by
2193 name later, using either @code{\keepWithTag #'@var{name}} or
2194 @code{\removeWithTag #'@var{name}}. The result of applying these filters
2195 to tagged music is as follows:
2196 @multitable @columnfractions .5 .5
2200 Tagged music preceded by @code{\keepWithTag #'@var{name}} or
2201 @code{\keepWithTag #'(@var{name1} @var{name2}@dots{})}
2202 @tab Untagged music and music tagged with any of the given tag
2204 music tagged with any other tag name is excluded.
2206 Tagged music preceded by @code{\removeWithTag #'@var{name}} or
2207 @code{\removeWithTag #'(@var{name1} @var{name2}@dots{})}
2208 @tab Untagged music and music not tagged with any of the given tag names
2209 is included; music tagged with any of the given tag names is
2212 Tagged music not preceded by either @code{\keepWithTag} or
2213 @code{\removeWithTag}
2214 @tab All tagged and untagged music is included.
2217 The arguments of the @code{\tag}, @code{\keepWithTag} and
2218 @code{\removeWithTag} commands should be a symbol or list of
2219 symbols (such as @code{#'score} or @code{#'(violinI violinII}),
2220 followed by a music expression. If @emph{and only if} the symbols
2221 are valid LilyPond identifiers (alphabetic characters only, no
2222 numbers, underscores, or dashes) which cannot be confused with notes,
2223 the @code{#'} may be omitted and, as a shorthand, a list of symbols
2224 can use the dot separator: i.e., @code{\tag #'(violinI violinII)} can
2225 be written @code{\tag violinI.violinII}. The same applies to
2226 @code{\keepWithTag} and @code{\removeWithTag}.
2228 In the following example, we see two versions of a piece of music,
2229 one showing trills with the usual notation, and one with trills
2230 explicitly expanded:
2232 @lilypond[verbatim,quote]
2235 \tag #'trills { d8.\trill }
2236 \tag #'expand { \repeat unfold 3 { e32 d } }
2241 \keepWithTag #'trills \music
2244 \keepWithTag #'expand \music
2249 Alternatively, it is sometimes easier to exclude sections of music:
2251 @lilypond[verbatim,quote]
2254 \tag #'trills { d8.\trill }
2255 \tag #'expand {\repeat unfold 3 { e32 d } }
2260 \removeWithTag #'expand
2264 \removeWithTag #'trills
2269 Tagged filtering can be applied to articulations, texts, etc., by
2273 -\tag #'@var{your-tag}
2276 to an articulation. For example, this would define a note with a
2277 conditional fingering indication and a note with a conditional
2282 c1-\tag #'warn ^"Watch!"
2285 Multiple tags may be placed on expressions with multiple
2286 @code{\tag} entries, or by combining multiple tags into one symbol
2289 @lilypond[quote,verbatim]
2290 music = \relative c'' {
2291 \tag #'a \tag #'both { a4 a a a }
2292 \tag #'(b both) { b4 b b b }
2295 \keepWithTag #'a \music
2296 \keepWithTag #'b \music
2297 \keepWithTag #'both \music
2301 Multiple @code{\removeWithTag} filters may be applied to a single
2302 music expression to remove several differently named tagged
2303 sections. Alternatively, you can use a single @code{\removeWithTag}
2304 with a list of tags.
2306 @lilypond[verbatim,quote]
2307 music = \relative c'' {
2308 \tag #'A { a4 a a a }
2309 \tag #'B { b4 b b b }
2310 \tag #'C { c4 c c c }
2311 \tag #'D { d4 d d d }
2317 \removeWithTag #'(B C)
2322 Using two or more @code{\keepWithTag} filters on a single music
2323 expression will cause @emph{all} of the tagged sections to be removed.
2324 The first filter will remove all except the one named and any subsequent
2325 filters will remove the rest. Using one @code{\keepWithTag} command
2326 with a list of multiple tags will only remove tagged sections that are
2327 not specified in that list.
2329 @lilypond[verbatim,quote]
2330 music = \relative c'' {
2331 \tag #'violinI { a4 a a a }
2332 \tag #'violinII { b4 b b b }
2333 \tag #'viola { c4 c c c }
2334 \tag #'cello { d4 d d d }
2338 \keepWithTag #'(violinI violinII)
2344 will print @code{\tag}s @var{violinI} and @var{violinII} but not
2345 @var{viola} or @var{cello}.
2350 While @code{\keepWithTag} is convenient when dealing with @emph{one} set
2351 of alternatives, the removal of music tagged with @emph{unrelated} tags
2352 is problematic when using them for more than one purpose. In that case
2353 @q{groups} of tags can be declared:
2356 \tagGroup #'(violinI violinII viola cello)
2360 Now all the different tags belong to a single @q{tag group}. Note that
2361 individual tags cannot be members of more than one @emph{tag group}.
2364 \keepWithTag #'violinI @dots{}
2368 will now only show music tagged from @code{violinI}'s tag group and any
2369 music tagged with one of the @emph{other} tags will removed.
2371 @lilypond[verbatim,quote]
2373 \tagGroup #'(violinI violinII viola cello)
2374 \tag #'violinI { c''4^"violinI" c c c }
2375 \tag #'violinII { a2 a }
2376 \tag #'viola { e8 e e2. }
2377 \tag #'cello { d'2 d4 d }
2382 \keepWithTag #'violinI
2387 When using the @code{\keepWithTag} command, only tags from the tag
2388 groups of the tags given in the command are visible.
2390 @funindex \pushToTag
2391 @funindex \appendToTag
2392 @cindex splice into tagged music
2394 Sometimes you want to splice some music at a particular place in an
2395 existing music expression. You can use @code{\pushToTag} and
2396 @code{\appendToTag} for adding material at the front or end of the
2397 @code{elements} of an existing music construct. Not every music
2398 construct has @code{elements}, but sequential and simultaneous music are
2401 @lilypond[verbatim,quote]
2402 music = { \tag #'here { \tag #'here <<c''>> } }
2405 \pushToTag #'here c'
2406 \pushToTag #'here e'
2407 \pushToTag #'here g' \music
2408 \appendToTag #'here c'
2409 \appendToTag #'here e'
2410 \appendToTag #'here g' \music
2414 Both commands get a tag, the material to splice in at every occurence of
2415 the tag, and the tagged expression.
2419 @rlearning{Organizing pieces with variables}.
2422 @ref{Automatic part combining},
2423 @ref{Including LilyPond files}.
2426 Calling @code{\relative} on a music expression obtained by filtering
2427 music through @code{\keepWithTag} or @code{\removeWithTag} might cause
2428 the octave relations to change, as only the pitches actually
2429 remaining in the filtered expression will be considered. Applying
2430 @code{\relative} first, before @code{\keepWithTag} or
2431 @code{\removeWithTag}, avoids this danger as @code{\relative} then
2432 acts on all the pitches as-input.
2435 @node Using global settings
2436 @unnumberedsubsubsec Using global settings
2438 @cindex include-settings
2440 Global settings can be included from a separate file:
2443 lilypond -dinclude-settings=MY_SETTINGS.ly MY_SCORE.ly
2446 Groups of settings such as page size, font or type face can be stored
2447 in separate files. This allows different editions from the same score
2448 as well as standard settings to be applied to many scores, simply by
2449 specifying the proper settings file.
2451 This technique also works well with the use of style sheets, as
2452 discussed in @rlearning{Style sheets}.
2456 @rlearning{Organizing pieces with variables},
2457 @rlearning{Style sheets}.
2460 @ref{Including LilyPond files}.
2463 @node Special characters
2464 @subsection Special characters
2466 @cindex special characters
2467 @cindex non-ASCII characters
2477 @unnumberedsubsubsec Text encoding
2481 LilyPond uses the character repertoire defined by the Unicode
2482 consortium and ISO/IEC 10646. This defines a unique name and
2483 code point for the character sets used in virtually all modern
2484 languages and many others too. Unicode can be implemented using
2485 several different encodings. LilyPond uses the UTF-8 encoding
2486 (UTF stands for Unicode Transformation Format) which represents
2487 all common Latin characters in one byte, and represents other
2488 characters using a variable length format of up to four bytes.
2490 The actual appearance of the characters is determined by the
2491 glyphs defined in the particular fonts available - a font defines
2492 the mapping of a subset of the Unicode code points to glyphs.
2493 LilyPond uses the Pango library to layout and render multi-lingual
2496 LilyPond does not perform any input-encoding conversions. This
2497 means that any text, be it title, lyric text, or musical
2498 instruction containing non-ASCII characters, must be encoded in
2499 UTF-8. The easiest way to enter such text is by using a
2500 Unicode-aware editor and saving the file with UTF-8 encoding. Most
2501 popular modern editors have UTF-8 support, for example, vim, Emacs,
2502 jEdit, and Gedit do. All MS Windows systems later than NT use
2503 Unicode as their native character encoding, so even Notepad can
2504 edit and save a file in UTF-8 format. A more functional
2505 alternative for Windows is BabelPad.
2507 If a LilyPond input file containing a non-ASCII character is not
2508 saved in UTF-8 format the error message
2511 FT_Get_Glyph_Name () error: invalid argument
2516 Here is an example showing Cyrillic, Hebrew and Portuguese
2519 @c NOTE: No verbatim in the following example as the code does not
2520 @c display correctly in PDF Font settings for Cyrillic and Hebrew
2523 % Linux Libertine fonts contain Cyrillic and Hebrew glyphs.
2527 #:roman "Linux Libertine O,serif"
2528 #:sans "Linux Biolinum O,sans-serif"
2529 #:typewriter "Linux Libertine Mono O,monospace"
2534 bulgarian = \lyricmode {
2535 Жълтата дюля беше щастлива, че пухът, който цъфна, замръзна като гьон.
2539 hebrew = \lyricmode {
2540 זה כיף סתם לשמוע איך תנצח קרפד עץ טוב בגן.
2544 portuguese = \lyricmode {
2545 à vo -- cê uma can -- ção legal
2551 \addlyrics { \bulgarian }
2552 \addlyrics { \hebrew }
2553 \addlyrics { \portuguese }
2558 @unnumberedsubsubsec Unicode
2562 To enter a single character for which the Unicode code point is
2563 known but which is not available in the editor being used, use
2564 either @code{\char ##xhhhh} or @code{\char #dddd} within a
2565 @code{\markup} block, where @code{hhhh} is the hexadecimal code for
2566 the character required and @code{dddd} is the corresponding decimal
2567 value. Leading zeroes may be omitted, but it is usual to specify
2568 all four characters in the hexadecimal representation. (Note that
2569 the UTF-8 encoding of the code point should @emph{not} be used
2570 after @code{\char}, as UTF-8 encodings contain extra bits indicating
2571 the number of octets.) Unicode code charts and a character name
2572 index giving the code point in hexadecimal for any character can be
2573 found on the Unicode Consortium website,
2574 @uref{http://www.unicode.org/}.
2576 For example, @code{\char ##x03BE} and @code{\char #958} would both
2577 enter the Unicode U+03BE character, which has the Unicode name
2578 @qq{Greek Small Letter Xi}.
2580 Any Unicode code point may be entered in this way and if all special
2581 characters are entered in this format it is not necessary to save
2582 the input file in UTF-8 format. Of course, a font containing all
2583 such encoded characters must be installed and available to LilyPond.
2585 The following example shows Unicode hexadecimal values being entered
2586 in four places -- in a rehearsal mark, as articulation text, in
2587 lyrics and as stand-alone text below the score:
2589 @lilypond[quote,verbatim]
2592 c''1 \mark \markup { \char ##x03EE }
2593 c1_\markup { \tiny { \char ##x03B1 " to " \char ##x03C9 } }
2595 \addlyrics { O \markup { \concat { Ph \char ##x0153 be! } } }
2597 \markup { "Copyright 2008--2015" \char ##x00A9 }
2600 @cindex copyright sign
2602 To enter the copyright sign in the copyright notice use:
2606 copyright = \markup @{ \char ##x00A9 "2008" @}
2612 @unnumberedsubsubsec ASCII aliases
2614 A list of ASCII aliases for special characters can be included:
2616 @lilypond[quote,verbatim]
2618 #(include-special-characters)
2621 \markup "&flqq; – &OE;uvre incomplète… &frqq;"
2624 \new Staff { \repeat unfold 9 a'4 }
2626 This is al -- so wor -- kin'~in ly -- rics: –_&OE;…
2631 "The replacement can be disabled:"
2632 "– &OE; …"
2633 \override #'(replacement-alist . ()) "– &OE; …"
2637 You can also make your own aliases, either globally:
2639 @lilypond[quote,verbatim]
2641 #(add-text-replacements!
2642 '(("100" . "hundred")
2643 ("dpi" . "dots per inch")))
2645 \markup "A 100 dpi."
2650 @lilypond[quote,verbatim]
2651 \markup \replace #'(("100" . "hundred")
2652 ("dpi" . "dots per inch")) "A 100 dpi."
2657 @ref{List of special characters}.
2660 @file{ly/text-replacements.ly}.
2663 @node Controlling output
2664 @section Controlling output
2667 * Extracting fragments of music::
2668 * Skipping corrected music::
2669 * Alternative output formats::
2670 * Replacing the notation font::
2673 @funindex clip-regions
2674 @cindex Fragments, music
2675 @cindex Music fragments
2677 @node Extracting fragments of music
2678 @subsection Extracting fragments of music
2680 It is possible to output one or more fragments of a score by defining
2681 the explicit location of the music to be extracted within the
2682 @code{\layout} block of the input file using the @code{clip-regions}
2683 function, and then running LilyPond with the @option{-dclip-systems}
2691 (make-rhythmic-location 5 1 2)
2692 (make-rhythmic-location 7 3 4)))
2697 This example will extract a single fragment of the input file
2698 @emph{starting} after a half-note duration in fifth measure
2699 (@code{5 1 2}) and @emph{ending} after the third quarter-note in the
2700 seventh measure (@code{7 3 4}).
2702 Additional fragments can be extracted by adding more pairs of
2703 @code{make-rhythmic-location} entries to the @code{clip-regions} list in
2704 the @code{\layout} block.
2706 By default, each music fragment will be output as a separate @code{EPS}
2707 file, but other formats such as @code{PDF} or @code{PNG} can also be
2708 created if required. The extracted music is output as if had been
2709 literally @q{cut} from the original printed score so if a fragment runs
2710 over one or more lines, a separate output file for each line will be
2715 @ref{The layout block}.
2718 @rprogram{Command-line usage}.
2722 @node Skipping corrected music
2723 @subsection Skipping corrected music
2726 @funindex skipTypesetting
2727 @funindex showFirstLength
2728 @funindex showLastLength
2730 When entering or copying music, usually only the music near the end (where
2732 are adding notes) is interesting to view and correct. To speed up
2733 this correction process, it is possible to skip typesetting of all but
2734 the last few measures. This is achieved by putting
2737 showLastLength = R1*5
2738 \score @{ @dots{} @}
2742 in your source file. This will render only the last 5 measures
2743 (assuming 4/4 time signature) of every @code{\score} in the input
2744 file. For longer pieces, rendering only a small part is often an order
2745 of magnitude quicker than rendering it completely. When working on the
2746 beginning of a score you have already typeset (e.g., to add a new part),
2747 the @code{showFirstLength} property may be useful as well.
2749 Skipping parts of a score can be controlled in a more fine-grained
2750 fashion with the property @code{Score.skipTypesetting}. When it is
2751 set, no typesetting is performed at all.
2753 This property is also used to control output to the MIDI file. Note that
2754 it skips all events, including tempo and instrument changes. You have
2757 @lilypond[quote,ragged-right,verbatim]
2760 \set Score.skipTypesetting = ##t
2763 \set Score.skipTypesetting = ##f
2768 In polyphonic music, @code{Score.skipTypesetting} will affect all
2769 voices and staves, saving even more time.
2771 @node Alternative output formats
2772 @subsection Alternative output formats
2774 @cindex scalable vector graphics output
2776 @cindex encapsulated postscript output
2779 The default output formats for the printed score are Portable
2780 Document Format (PDF) and PostScript (PS). Portable
2781 Network Graphics (PNG), Scalable Vector Graphics (SVG) and Encapsulated
2782 PostScript (EPS) output is available through the command line option,
2783 see @rprogram{Basic command line options for LilyPond}.
2786 @node Replacing the notation font
2787 @subsection Replacing the notation font
2789 Gonville is an alternative set of glyphs to @emph{Feta}
2790 -- part of the Emmentaler font -- and used in LilyPond. They can be
2794 @uref{http://www.chiark.greenend.org.uk/~sgtatham/gonville/ ,http://www.chiark.greenend.org.uk/~sgtatham/gonville/}
2797 Here are a few sample bars of music set in Gonville:
2799 @c NOTE: these images are a bit big, but that's important
2800 @c for the font comparison. -gp
2801 @sourceimage{Gonville_after,15cm,,}
2803 Here are a few sample bars of music set in LilyPond's Feta glyphs:
2805 @sourceimage{Gonville_before,15cm,,}
2807 @subsubheading Installation Instructions for MacOS
2809 Download and extract the zip file. Copy the @code{lilyfonts}
2810 directory to @file{@var{SHARE_DIR}/lilypond/current}; for more
2811 information, see @rlearning{Other sources of information}. Rename the
2812 existing @code{fonts} directory to @code{fonts_orig} and the
2813 @code{lilyfonts} directory to @code{fonts}. To revert back to Feta,
2814 reverse the process.
2818 @rlearning{Other sources of information}.
2821 @ref{The Emmentaler font}.
2824 Gonville cannot be used to typeset @q{Ancient Music} notation and it is
2825 likely newer glyphs in later releases of LilyPond may not exist in the
2826 Gonville font family. Please refer to the author's website for more
2827 information on these and other specifics, including licensing of
2831 @node Creating MIDI output
2832 @section Creating MIDI output
2837 LilyPond can produce files that conform to the MIDI (Musical Instrument
2838 Digital Interface) standard and so allow for the checking of the music
2839 output aurally (with the help of an application or device that
2840 understands MIDI). Listening to MIDI output may also help in spotting
2841 errors such as notes that have been entered incorrectly or are missing
2842 accidentals and so on.
2844 MIDI files do not contain sound (like AAC, MP3 or Vorbis files) but
2845 require additional software to produce sound from them.
2848 * Supported notation for MIDI::
2849 * Unsupported notation for MIDI::
2851 * Controlling MIDI dynamics::
2852 * Using MIDI instruments::
2853 * Using repeats with MIDI::
2854 * MIDI channel mapping::
2855 * Context properties for MIDI effects::
2856 * Enhancing MIDI output::
2859 @cindex MIDI, Supported notation
2861 @node Supported notation for MIDI
2862 @subsection Supported notation for MIDI
2864 The following musical notation can be used with LilyPond's default
2865 capabilities to produce MIDI output;
2869 @item Chords entered as chord names
2870 @item Crescendi, decrescendi over multiple notes. The volume is altered
2871 linearly between the two extremes
2872 @item Dynamic markings from @code{ppppp} to @code{fffff}, including
2873 @code{mp}, @code{mf} and @code{sf}
2874 @item Microtones but @emph{not} microtonal chords. A MIDI player that
2875 supports pitch bending will also be required.
2878 @item Rhythms entered as note durations, including tuplets
2879 @item @q{Simple} articulations; staccato, staccatissimo, accent, marcato
2881 @item Tempo changes using the @code{\tempo} function
2883 @item Tremolos that are @emph{not} entered with a
2884 @q{@code{:}[@var{number}]} value
2887 Panning, balance, expression, reverb and chorus effects can also be
2888 controlled by setting context properties,
2889 see @ref{Context properties for MIDI effects}.
2891 When combined with the @file{articulate} script the following,
2892 additional musical notation can be output to MIDI;
2895 @item Appoggiaturas. These are made to take half the value of the note
2896 following (without taking dots into account). For example;
2899 \appoggiatura c8 d2.
2903 The c will take the value of a crotchet.
2905 @item Ornaments (i.e., mordents, trills and turns et al.)
2906 @item Rallentando, accelerando, ritardando and a tempo
2907 @item Slurs, including phrasing slurs
2912 See @ref{Enhancing MIDI output}.
2914 @cindex MIDI, Unsupported notation
2916 @node Unsupported notation for MIDI
2917 @subsection Unsupported notation for MIDI
2919 The following items of musical notation cannot be output to MIDI;
2922 @item Articulations other than staccato, staccatissimo, accent, marcato
2924 @item Crescendi and decrescendi over a @emph{single} note
2928 @item Falls and doits
2929 @item Microtonal chords
2930 @item Rhythms entered as annotations, e.g., swing
2931 @item Tempo changes without @code{\tempo} (e.g., entered as annotations)
2932 @item Tremolos that @emph{are} entered with a @q{@code{:}[@var{number}]}
2937 @node The MIDI block
2938 @subsection The MIDI block
2942 To create a MIDI output file from a LilyPond input file, insert a
2943 @code{\midi} block, which can be empty, within the @code{\score} block;
2947 @var{@dots{} music @dots{}}
2953 @warning{A @code{@bs{}score} block that, as well as the music, contains
2954 only a @code{@bs{}midi} block (i.e., @emph{without} the @code{@bs{}layout}
2955 block), will only produce MIDI output files. No notation will be
2958 The default output file extension (@code{.midi}) can be changed by using
2959 the @code{-dmidi-extension} option with the @code{lilypond} command:
2962 lilypond -dmidi-extension=mid MyFile.ly
2965 Alternatively, add the following Scheme expression before the start of
2966 either the @code{\book}, @code{\bookpart} or @code{\score} blocks. See
2967 @ref{File structure}.
2970 #(ly:set-option 'midi-extension "mid")
2975 @ref{File structure},
2976 @ref{Creating output file metadata}.
2979 @file{scm/midi.scm}.
2982 There are fifteen MIDI channels available and one additional channel
2983 (#10) for drums. Staves are assigned to channels in sequence, so a
2984 score that contains more than fifteen staves will result in the extra
2985 staves sharing (but not overwriting) the same MIDI channel. This may be
2986 a problem if the sharing staves have conflicting, channel-based, MIDI
2987 properties -- such as different MIDI instruments -- set.
2990 @node Controlling MIDI dynamics
2991 @subsection Controlling MIDI dynamics
2993 It is possible to control the overall MIDI volume, the relative volume
2994 of dynamic markings and the relative volume of different instruments.
2996 Dynamic marks translate automatically into volume levels in the
2997 available MIDI volume range whereas crescendi and decrescendi vary the
2998 volume linearly between their two extremes. It is possible to control
2999 the relative volume of dynamic markings, and the overall volume levels
3000 of different instruments.
3003 * Dynamic marks in MIDI::
3004 * Setting MIDI volume::
3005 * Setting MIDI block properties::
3009 @cindex MIDI equalization
3010 @cindex MIDI dynamics
3011 @cindex Dynamics in MIDI
3014 @node Dynamic marks in MIDI
3015 @unnumberedsubsubsec Dynamic marks in MIDI
3017 Only the dynamic markings from @code{ppppp} to @code{fffff}, including
3018 @code{mp}, @code{mf} and @code{sf} have values assigned to them. This
3019 value is then applied to the value of the overall MIDI volume range to
3020 obtain the final volume included in the MIDI output for that particular
3021 dynamic marking. The default fractions range from 0.25 for
3022 @notation{ppppp} to 0.95 for @notation{fffff}. The complete set of
3023 dynamic marks and their associated fractions can be found in
3024 @file{scm/midi.scm}.
3028 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
3029 {creating-custom-dynamics-in-midi-output.ly}
3032 @file{ly/script-init.ly}
3033 @file{scm/midi.scm}.
3038 Internals Reference:
3039 @rinternals{Dynamic_performer}.
3042 @node Setting MIDI volume
3043 @unnumberedsubsubsec Setting MIDI volume
3045 The minimum and maximum overall volume of MIDI dynamic markings is
3046 controlled by setting the properties @code{midiMinimumVolume} and
3047 @code{midiMaximumVolume} at the @code{Score} level. These properties
3048 have an effect only at the start of a voice and on dynamic marks. The
3049 fraction corresponding to each dynamic mark is modified with this
3053 midiMinimumVolume + (midiMaximumVolume - midiMinimumVolume) * fraction
3056 In the following example the dynamic range of the overall MIDI
3057 volume is limited to the range @code{0.2} - @code{0.5}.
3063 \set Staff.midiInstrument = #"flute"
3064 @var{@dots{} music @dots{}}
3067 \set Staff.midiInstrument = #"clarinet"
3068 @var{@dots{} music @dots{}}
3074 midiMinimumVolume = #0.2
3075 midiMaximumVolume = #0.5
3081 Simple MIDI instrument equalization can be achieved by setting
3082 @code{midiMinimumVolume} and @code{midiMaximumVolume} properties within
3083 the @code{Staff} context.
3088 \set Staff.midiInstrument = #"flute"
3089 \set Staff.midiMinimumVolume = #0.7
3090 \set Staff.midiMaximumVolume = #0.9
3091 @var{@dots{} music @dots{}}
3097 For scores with multiple staves and multiple MIDI instruments, the
3098 relative volumes of each instrument can be set individually;
3104 \set Staff.midiInstrument = #"flute"
3105 \set Staff.midiMinimumVolume = #0.7
3106 \set Staff.midiMaximumVolume = #0.9
3107 @var{@dots{} music @dots{}}
3110 \set Staff.midiInstrument = #"clarinet"
3111 \set Staff.midiMinimumVolume = #0.3
3112 \set Staff.midiMaximumVolume = #0.6
3113 @var{@dots{} music @dots{}}
3120 In this example the volume of the clarinet is reduced relative to the
3121 volume of the flute.
3123 If these volumes properties are not set then LilyPond still applies a
3124 @q{small degree} of equalization to certain instruments. See
3125 @file{scm/midi.scm}.
3128 @file{scm/midi.scm}.
3134 Internals Reference:
3135 @rinternals{Dynamic_performer}.
3138 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
3139 {replacing-default-midi-instrument-equalization.ly}
3142 Changes in the MIDI volume take place only on starting a note, so
3143 crescendi and decrescendi cannot affect the volume of a single note.
3146 @node Setting MIDI block properties
3147 @unnumberedsubsubsec Setting MIDI block properties
3149 The @code{\midi} block can contain context rearrangements, new context
3150 definitions or code that sets the values of certain properties.
3154 @var{@dots{} music @dots{}}
3161 Here the tempo is set to 72 quarter-note beats per minute. The tempo
3162 mark in the @code{\midi} block will not appear in the printed score.
3163 Although any other @code{\tempo} indications specified within the
3164 @code{\score} block will also be reflected in the MIDI output.
3166 In a @code{\midi} block the @code{\tempo} command is setting properties
3167 during the interpretation of the music and in the context of output
3168 definitions; so it is interpreted @emph{as if} it were a context
3171 @cindex MIDI context definitions
3172 @cindex context definitions with MIDI
3174 Context definitions follow the same syntax as those in a @code{\layout}
3179 @var{@dots{} music @dots{}}
3183 \remove "Dynamic_performer"
3189 This example removes the effect of dynamics from the MIDI output. Note:
3190 LilyPond's translation modules used for sound are called @q{performers}.
3194 @rlearning{Other sources of information}.
3197 @ref{Expressive marks},
3201 @file{ly/performer-init.ly}.
3206 Internals Reference:
3207 @rinternals{Dynamic_performer}.
3210 Some MIDI players do not always correctly handle tempo changes in the
3213 Changes to the @code{midiInstrument}, as well as some MIDI options, at
3214 the @emph{beginning} of a staff may appear twice in the MIDI output.
3218 @node Using MIDI instruments
3219 @subsection Using MIDI instruments
3221 MIDI instruments are set using the @code{midiInstrument} property within
3222 a @code{Staff} context.
3227 \set Staff.midiInstrument = #"glockenspiel"
3228 @var{@dots{} music @dots{}}
3238 \new Staff \with @{midiInstrument = #"cello"@} @{
3239 @var{@dots{} music @dots{}}
3245 If the instrument name does not match any of the instruments listed in
3246 the @q{MIDI instruments} section, the @code{acoustic grand} instrument
3247 will be used instead. See @ref{MIDI instruments}.
3251 @rlearning{Other sources of information}.
3254 @ref{MIDI instruments},
3258 @file{scm/midi.scm}.
3261 Percussion instruments that are notated in a @code{DrumStaff}
3262 context will be output, correctly, to MIDI channel@tie{}10 but some
3263 pitched, percussion instruments like the xylophone, marimba, vibraphone
3264 or timpani, are treated as @qq{normal} instruments so the music for
3265 these should be entered in a @code{Staff} (not @code{DrumStaff}) context
3266 to obtain correct MIDI output. A full list of
3267 @code{channel 10 drum-kits} entries can be found in @file{scm/midi.scm}.
3268 See @rlearning{Other sources of information}.
3271 @node Using repeats with MIDI
3272 @subsection Using repeats with MIDI
3274 @cindex repeats in MIDI
3275 @cindex MIDI using repeats
3276 @funindex \unfoldRepeats
3278 Repeats can be represented in the MIDI output by applying the
3279 @code{\unfoldRepeats} command.
3284 \repeat tremolo 8 @{ c'32 e' @}
3285 \repeat percent 2 @{ c''8 d'' @}
3286 \repeat volta 2 @{ c'4 d' e' f' @}
3296 In order to restrict the effect of @code{\unfoldRepeats} to the MIDI
3297 output only, while also generating printable scores, it is necessary to
3298 make @emph{two} @code{\score} blocks; one for MIDI (with unfolded
3299 repeats) and one for the notation (with volta, tremolo, and percent
3304 @var{@dots{} music @dots{}}
3309 @var{@dots{} music @dots{}}
3315 When using multiple voices, each of the voices must contain completely
3316 unfolded repeats for correct MIDI output.
3323 @node MIDI channel mapping
3324 @subsection MIDI channel mapping
3326 @cindex MIDI Channels
3328 @funindex midiChannelMapping
3330 When generating a MIDI file from a score, LilyPond will automatically
3331 assign every note in the score to a MIDI channel, the one on which it
3332 should be played when it is sent to a MIDI device. A MIDI channel has
3333 a number of controls available to select, for example, the instrument
3334 to be used to play the notes on that channel, or to request the MIDI
3335 device to apply various effects to the sound produced on the channel.
3336 At all times, every control on a MIDI channel can have only a single
3337 value assigned to it (which can be modified, however, for example,
3338 to switch to another instrument in the middle of a score).
3340 The MIDI standard supports only 16 channels per MIDI device. This
3341 limit on the number of channels also limits the number of different
3342 instruments which can be played at the same time.
3344 LilyPond creates separate MIDI tracks for each staff, (or discrete
3345 instrument or voice, depending on the value of
3346 @code{Score.midiChannelMapping}), and also for each lyrics context.
3347 There is no limit to the number of tracks.
3349 To work around the limited number of MIDI channels, LilyPond supports
3350 a number of different modes for MIDI channel allocation, selected using
3351 the @code{Score.midiChannelMapping} context property. In each case,
3352 if more MIDI channels than the limit are required, the allocated
3353 channel numbers wrap around back to 0, possibly causing the incorrect
3354 assignment of instruments to some notes. This context property can be
3355 set to one of the following values:
3361 Allocate a separate MIDI channel to each staff in the score (this is
3362 the default). All notes in all voices contained within each staff will
3363 share the MIDI channel of their enclosing staff, and all are encoded
3364 in the same MIDI track.
3366 The limit of 16 channels is applied to the total number of staff and
3367 lyrics contexts, even though MIDI lyrics do not take up a MIDI channel.
3369 @item @code{'instrument}
3371 Allocate a separate MIDI channel to each distinct MIDI instrument
3372 specified in the score. This means that all the notes played with the
3373 same MIDI instrument will share the same MIDI channel (and track), even
3374 if the notes come from different voices or staves.
3376 In this case the lyrics contexts do not count towards the MIDI channel
3377 limit of 16 (as they will not be assigned to a MIDI instrument), so
3378 this setting may allow a better allocation of MIDI channels when the
3379 number of staves and lyrics contexts in a score exceeds 16.
3383 Allocate a separate MIDI channel to each voice in the score that has a
3384 unique name among the voices in its enclosing staff. Voices in
3385 different staves are always assigned separate MIDI channels, but any two
3386 voices contained within the same staff will share the same MIDI channel
3387 if they have the same name. Because @code{midiInstrument} and the
3388 several MIDI controls for effects are properties of the staff context,
3389 they cannot be set separately for each voice. The first voice will be
3390 played with the instrument and effects specified for the staff, and
3391 voices with a different name from the first will be assigned the default
3392 instrument and effects.
3394 Note: different instruments and/or effects can be assigned to several
3395 voices on the same staff by moving the @code{Staff_performer} from the
3396 @code{Staff} to the @code{Voice} context, and leaving
3397 @code{midiChannelMapping} to default to @code{'staff} or set to
3398 @code{'instrument}; see the snippet below.
3402 For example, the default MIDI channel mapping of a score can be changed
3403 to the @code{'instrument} setting as shown:
3411 midiChannelMapping = #'instrument
3418 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
3419 {changing-midi-output-to-one-channel-per-voice.ly}
3422 @node Context properties for MIDI effects
3423 @subsection Context properties for MIDI effects
3425 @cindex Effects in MIDI
3426 @cindex Pan position in MIDI
3427 @cindex Stereo balance in MIDI
3428 @cindex Balance in MIDI
3429 @cindex Expression in MIDI
3430 @cindex Reverb in MIDI
3431 @cindex Chorus level in MIDI
3432 @funindex midiPanPosition
3433 @funindex midiBalance
3434 @funindex midiExpression
3435 @funindex midiReverbLevel
3436 @funindex midiChorusLevel
3438 The following context properties can be used to apply various MIDI
3439 effects to notes played on the MIDI channel associated with the
3440 current staff, MIDI instrument or voice (depending on the value of the
3441 @code{Score.midiChannelMapping} context property and the context in
3442 which the @code{Staff_performer} is located; see
3443 @ref{MIDI channel mapping}).
3445 Changing these context properties will affect all notes played on the
3446 channel after the change, however some of the effects may even apply
3447 also to notes which are already playing (depending on the
3448 implementation of the MIDI output device).
3450 The following context properties are supported:
3454 @item @code{Staff.midiPanPosition}
3456 The pan position controls how the sound on a MIDI channel is
3457 distributed between left and right stereo outputs. The context
3458 property accepts a number between -1.0 (@code{#LEFT}) and 1.0
3459 (@code{#RIGHT}); the value -1.0 will put all sound power to the left
3460 stereo output (keeping the right output silent), the value 0.0
3461 (@code{#CENTER}) will distribute the sound evenly between the left and
3462 right stereo outputs, and the value 1.0 will move all sound to the
3463 right stereo output. Values between -1.0 and 1.0 can be used to obtain
3464 mixed distributions between left and right stereo outputs.
3466 @item @code{Staff.midiBalance}
3468 The stereo balance of a MIDI channel. Similarly to the pan position,
3469 this context property accepts a number between -1.0 (@code{#LEFT}) and
3470 1.0 (@code{#RIGHT}). It varies the relative volume sent to the two
3471 stereo speakers without affecting the distribution of the stereo
3474 @item @code{Staff.midiExpression}
3476 Expression level (as a fraction of the maximum available level) to
3477 apply to a MIDI channel. A MIDI device combines the MIDI channel's
3478 expression level with a voice's current dynamic level (controlled using
3479 constructs such as @code{\p} or @code{\ff}) to obtain the total volume
3480 of each note within the voice. The expression control could be used, for
3481 example, to implement crescendo or decrescendo effects over single
3482 sustained notes (not supported automatically by LilyPond).
3484 @c Issue 4059 contains an attached snippet which shows how this might
3485 @c be done, but this is too large and complex for the NR, even as a
3486 @c referenced snippet. It could be added to the LSR.
3488 The expression level ranges from 0.0 (no expression, meaning zero
3489 volume) to 1.0 (full expression).
3491 @item @code{Staff.midiReverbLevel}
3493 Reverb level (as a fraction of the maximum available level) to apply
3494 to a MIDI channel. This property accepts numbers between 0.0 (no
3495 reverb) and 1.0 (full effect).
3497 @item @code{Staff.midiChorusLevel}
3499 Chorus level (as a fraction of the maximum available level) to apply to
3500 a MIDI channel. This property accepts numbers between 0.0 (no chorus
3501 effect) and 1.0 (full effect).
3508 As MIDI files do not contain any actual audio data, changes in these
3509 context properties translate only to requests for changing MIDI channel
3510 controls in the outputted MIDI files. Whether a particular MIDI device
3511 (such as a software MIDI player) can actually handle any of these
3512 requests in a MIDI file is entirely up to the implementation of the
3513 device: a device may choose to ignore some or all of these requests.
3514 Also, how a MIDI device will interpret different values for these
3515 controls (generally, the MIDI standard fixes the behavior only at the
3516 endpoints of the value range available for each control), and whether a
3517 change in the value of a control will affect notes already playing on
3518 that MIDI channel or not, is also specific to the MIDI device
3521 When generating MIDI files, LilyPond will simply transform the
3522 fractional values within each range linearly into values in a
3523 corresponding (7-bit, or 14-bit for MIDI channel controls which support
3524 fine resolution) integer range (0-127 or 0-32767, respectively),
3525 rounding fractional values towards the nearest integer away from zero.
3526 The converted integer values are stored as-is in the generated MIDI
3527 file. Please consult the documentation of your MIDI device for
3528 information about how the device interprets these values.
3531 @node Enhancing MIDI output
3532 @subsection Enhancing MIDI output
3535 * The articulate script::
3538 The default MIDI output is basic but can be improved by setting MIDI
3539 instruments, @code{\midi} block properties and/or using the
3540 @file{articulate} script.
3542 @cindex instrument names
3543 @cindex MIDI, instruments
3544 @cindex articulate script
3545 @cindex articulate.ly
3546 @funindex Staff.midiInstrument
3549 @node The articulate script
3550 @unnumberedsubsubsec The @file{articulate} script
3552 To use the @file{articulate} script add the appropriate @code{\include}
3553 command at the top of the input file;
3556 \include "articulate.ly"
3559 The script creates MIDI output into appropriately @q{time-scaled} notes
3560 to match many articulation and tempo indications. Engraved output
3561 however, will also be altered to literally match the MIDI output.
3566 @var{@dots{} music @dots{}}
3572 The @code{\articulate} command enables abbreviatures (such as trills and
3573 turns) to be processed. A full list of supported items can be found in
3574 the script itself. See @file{ly/articulate.ly}.
3578 @rlearning{Other sources of information}.
3584 @file{ly/articulate.ly}.
3586 @warning{The @file{articulate} script may shorten chords, which might
3587 not be appropriate for some types of instrument, such as organ music.
3588 Notes that do not have any articulations attached to them may also be
3589 shortened; so to allow for this, restrict the use of the
3590 @code{\articulate} function to shorter segments of music, or modify the
3591 values of the variables defined in the @file{articulate} script to
3592 compensate for the note-shortening behavior.}
3596 @node Extracting musical information
3597 @section Extracting musical information
3599 In addition to creating graphical output and MIDI, LilyPond can
3600 display musical information as text.
3603 * Displaying LilyPond notation::
3604 * Displaying scheme music expressions::
3605 * Saving music events to a file::
3608 @node Displaying LilyPond notation
3609 @subsection Displaying LilyPond notation
3611 @funindex \displayLilyMusic
3612 Displaying a music expression in LilyPond notation can be
3613 done with the music function @code{\displayLilyMusic}. To see the
3614 output, you will typically want to call LilyPond using the command
3619 \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
3626 @{ a,4 cis4 e4 fis4 g4 @}
3629 By default, LilyPond will print these messages to the console
3630 along with all the other LilyPond compilation messages. To split
3631 up these messages and save the results of @code{\displayLilyMusic},
3632 redirect the output to a file.
3635 lilypond file.ly >display.txt
3639 Note that LilyPond does not just display the music expression, but
3640 also interprets it (since @code{\displayLilyMusic} returns it in
3641 addition to displaying it). Just insert @code{\displayLilyMusic} into
3642 the existing music in order to get information about it.
3644 To interpret and display a music section in the console but, at the same
3645 time, remove it from the output file use the @code{\void} command.
3649 \void \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
3655 @node Displaying scheme music expressions
3656 @subsection Displaying scheme music expressions
3658 See @rextend{Displaying music expressions}.
3661 @node Saving music events to a file
3662 @subsection Saving music events to a file
3664 Music events can be saved to a file on a per-staff basis by
3665 including a file in your main score.
3668 \include "event-listener.ly"
3671 This will create file(s) called @file{FILENAME-STAFFNAME.notes} or
3672 @file{FILENAME-unnamed-staff.notes} for each staff. Note that if
3673 you have multiple unnamed staves, the events for all staves will
3674 be mixed together in the same file. The output looks like this:
3677 0.000 note 57 4 p-c 2 12
3679 0.250 note 62 4 p-c 7 12
3680 0.500 note 66 8 p-c 9 12
3681 0.625 note 69 8 p-c 14 12
3686 The syntax is a tab-delimited line, with two fixed fields on each
3687 line followed by optional parameters.
3690 @var{time} @var{type} @var{@dots{}params@dots{}}
3693 This information can easily be read into other programs such as
3694 python scripts, and can be very useful for researchers wishing to
3695 perform musical analysis or playback experiments with LilyPond.
3700 Not all lilypond music events are supported by
3701 @file{event-listener.ly}. It is intended to be a well-crafted
3702 @qq{proof of concept}. If some events that you want to see are
3703 not included, copy @file{event-listener.ly} into your lilypond
3704 directory and modify the file so that it outputs the information