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 ouputs from a single source file. You also have the
281 ability to specify your own suffixes for each @code{\book} block, so
282 for example you can produce files called
283 @file{eightminiatures-Romanze.pdf}, @file{eightminiatures-Menuetto.pdf}
284 and @file{eightminiatures-Nocturne.pdf} by adding a
285 @code{\bookOutputSuffix} declaration inside each @code{\book} block.
289 \bookOutputSuffix "Romanze"
294 \bookOutputSuffix "Menuetto"
299 \bookOutputSuffix "Nocturne"
305 You can also specify a different output filename for @code{book} block,
306 by using @code{\bookOutputName} declarations
310 \bookOutputName "Romanze"
315 \bookOutputName "Menuetto"
320 \bookOutputName "Nocturne"
326 The file above will produce these output files:
332 @file{Menuetto.pdf} and
339 @subsection File structure
349 A @file{.ly} file may contain any number of toplevel expressions, where a
350 toplevel expression is one of the following:
354 An output definition, such as @code{\paper}, @code{\midi}, and
355 @code{\layout}. Such a definition at the toplevel changes the default
356 book-wide settings. If more than one such definition of the same type
357 is entered at the top level the definitions are combined, but in
358 conflicting situations the later definitions take precedence. For
359 details of how this affects the @code{\layout} block see
360 @ref{The layout block,,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 init file @file{../scm/lily.scm}.
381 A @code{\book} block logically combines multiple movements
382 (i.e., multiple @code{\score} blocks) in one document. If there
383 are a number of @code{\score}s, one output file will be created
384 for each @code{\book} block, in which all corresponding movements
385 are concatenated. The only reason to explicitly specify
386 @code{\book} blocks in a @file{.ly} file is if you wish to create
387 multiple output files from a single input file. One exception is
388 within lilypond-book documents, where you explicitly have to add
389 a @code{\book} block if you want more than a single @code{\score}
390 or @code{\markup} in the same example. This behavior can be
391 changed by setting the variable @code{toplevel-book-handler} at
392 toplevel. The default handler is defined in the init file
393 @file{../scm/lily.scm}.
396 A @code{\bookpart} block. A book may be divided into several parts,
397 using @code{\bookpart} blocks, in order to ease the page breaking,
398 or to use different @code{\paper} settings in different parts.
401 A compound music expression, such as
406 This will add the piece in a @code{\score} and format it in a
407 single book together with all other toplevel @code{\score}s and music
408 expressions. In other words, a file containing only the above
409 music expression will be translated into
426 This behavior can be changed by setting the variable
427 @code{toplevel-music-handler} at toplevel. The default handler is
428 defined in the init file @file{../scm/lily.scm}.
431 A markup text, a verse for example
434 2. The first line verse two.
438 Markup texts are rendered above, between or below the scores or music
439 expressions, wherever they appear.
449 This can be used later on in the file by entering @code{\foo}. The
450 name of a variable should have alphabetic characters only; no
451 numbers, underscores or dashes.
455 The following example shows three things that may be entered at
460 % Don't justify the output
472 At any point in a file, any of the following lexical instructions can
476 @item @code{\version}
477 @item @code{\include}
478 @item @code{\sourcefilename}
479 @item @code{\sourcefileline}
481 A single-line comment, introduced by a leading @code{%} sign.
484 A multi-line comment delimited by @code{%@{ @dots{} %@}}.
490 Whitespace between items in the input stream is generally ignored,
491 and may be freely omitted or extended to enhance readability.
492 However, whitespace should always be used in the following
493 circumstances to avoid errors:
497 @item Around every opening and closing curly bracket.
499 @item After every command or variable, i.e. every item that
500 begins with a @code{\} sign.
502 @item After every item that is to be interpreted as a Scheme
503 expression, i.e. every item that begins with a @code{#}@tie{}sign.
505 @item To separate all elements of a Scheme expression.
507 @item In @code{lyricmode} before and after @code{\set} and
508 @code{\override} commands.
514 @rlearning{How LilyPond input files work}.
517 @ref{Titles explained},
518 @ref{The layout block,,The @code{@bs{}layout} block}.
521 @node Titles and headers
522 @section Titles and headers
524 Almost all printed music includes a title and the composer's name;
525 some pieces include a lot more information.
528 * Creating titles headers and footers::
529 * Custom titles headers and footers::
530 * Creating footnotes::
531 * Reference to page numbers::
532 * Table of contents::
536 @node Creating titles headers and footers
537 @subsection Creating titles headers and footers
541 * Default layout of bookpart and score titles::
542 * Default layout of headers and footers::
546 @node Titles explained
547 @unnumberedsubsubsec Titles explained
549 Each @code{\book} block in a single input file produces a separate
550 output file, see @ref{File structure}. Within each output file
551 three types of titling areas are provided: @emph{Book Titles} at the
552 beginning of each book, @emph{Bookpart Titles} at the beginning of
553 each bookpart and @emph{Score Titles} at the beginning of each score.
555 Values of titling fields such as @code{title} and @code{composer}
556 are set in @code{\header} blocks. (For the syntax of @code{\header}
557 blocks and a complete list of the fields available by default see
558 @ref{Default layout of bookpart and score titles}). Book Titles,
559 Bookpart Titles and Score Titles can all contain the same fields,
560 although by default the fields in Score Titles are limited to
561 @code{piece} and @code{opus}.
563 @code{\header} blocks may be placed in four different places to form
564 a descending hierarchy of @code{\header} blocks:
569 At the top of the input file, before all @code{\book},
570 @code{\bookpart}, and @code{\score} blocks.
573 Within a @code{\book} block but outside all the @code{\bookpart} and
574 @code{\score} blocks within that book.
577 Within a @code{\bookpart} block but outside all @code{\score} blocks
578 within that bookpart.
581 After the music expression in a @code{\score} block.
585 The values of the fields filter down this hierarchy, with the values
586 set higher in the hierarchy persisting unless they are over-ridden
587 by a value set lower in the hierarchy, so:
592 A Book Title is derived from fields set at the top of the input file,
593 modified by fields set in the @code{\book} block. The resulting
594 fields are used to print the Book Title for that book, providing that
595 there is other material which generates a page at the start of the
596 book, before the first bookpart. A single @code{\pageBreak} will
600 A Bookpart Title is derived from fields set at the top of the input
601 file, modified by fields set in the @code{\book} block, and further
602 modified by fields set in the @code{\bookpart} block. The resulting
603 values are used to print the Bookpart Title for that bookpart.
606 A Score Title is derived from fields set at the top of the input
607 file, modified by fields set in the @code{\book} block, further
608 modified by fields set in the @code{\bookpart} block and finally
609 modified by fields set in the @code{\score} block. The resulting
610 values are used to print the Score Title for that score. Note,
611 though, that only @code{piece} and @code{opus} fields are printed
612 by default in Score Titles unless the @code{\paper} variable,
613 @code{print-all-headers}, is set to @code{#t}.
617 @warning{Remember when placing a @bs{}@code{header} block inside a
618 @bs{}@code{score} block, that the music expression must come before the
619 @bs{}@code{header} block.}
621 It is not necessary to provide @code{\header} blocks in all four
622 places: any or even all of them may be omitted. Similarly, simple
623 input files may omit the @code{\book} and @code{\bookpart} blocks,
624 leaving them to be created implicitly.
626 If the book has only a single score, the @code{\header} block should
627 normally be placed at the top of the file so that just a Bookpart
628 Title is produced, making all the titling fields available for use.
630 If the book has multiple scores a number of different arrangements
631 of @code{\header} blocks are possible, corresponding to the various
632 types of musical publications. For example, if the publication
633 contains several pieces by the same composer a @code{\header} block
634 placed at the top of the file specifying the book title and the
635 composer with @code{\header} blocks in each @code{\score} block
636 specifying the @code{piece} and/or @code{opus} would be most
639 @lilypond[papersize=a5,quote,verbatim,noragged-right]
642 composer = "J. S. Bach."
646 \new Staff \relative {
649 \repeat unfold 2 { g,16( d' b') a b d, b' d, } |
650 \repeat unfold 2 { g,16( e' c') b c e, c' e, } |
658 \new Staff \relative {
662 <g, d' b'~>4 b'16 a( g fis) g( d e fis) g( a b c) |
663 d16( b g fis) g( e d c) b(c d e) fis( g a b) |
671 More complicated arrangements are possible. For example, text
672 fields from the @code{\header} block in a book can be displayed in
673 all Score Titles, with some fields over-ridden and some manually
676 @lilypond[papersize=a5,quote,verbatim,noragged-right]
679 print-all-headers = ##t
682 title = "DAS WOHLTEMPERIRTE CLAVIER"
684 % Do not display the tagline for this book
687 \markup { \vspace #1 }
691 \new Staff { \clef "bass" s1 }
694 title = "PRAELUDIUM I"
696 % Do not display the subtitle for this score
703 \new Staff { \clef "bass" s1 }
707 subsubtitle = "A 4 VOCI"
709 % Do not display the subtitle for this score
718 @ref{File structure},
719 @ref{Default layout of bookpart and score titles},
720 @ref{Custom layout for titles}.
723 @node Default layout of bookpart and score titles
724 @unnumberedsubsubsec Default layout of bookpart and score titles
726 This example demonstrates all @code{\header} variables:
728 @lilypond[papersize=a6landscape,quote,verbatim,noragged-right]
731 % The following fields are centered
732 dedication = "Dedication"
734 subtitle = "Subtitle"
735 subsubtitle = "Subsubtitle"
736 % The following fields are evenly spread on one line
737 % the field "instrument" also appears on following pages
738 instrument = \markup \with-color #green "Instrument"
740 composer = "Composer"
741 % The following fields are placed at opposite ends of the same line
743 arranger = "Arranger"
744 % The following fields are centered at the bottom
745 tagline = "tagline goes at the bottom of the last page"
746 copyright = "copyright goes at the bottom of the first page"
751 % The following fields are placed at opposite ends of the same line
759 % The following fields are placed at opposite ends of the same line
760 piece = "Piece 2 on the same page"
768 % The following fields are placed at opposite ends of the same line
769 piece = "Piece 3 on a new page"
780 The instrument name will be repeated on every page.
783 Only @code{piece} and @code{opus} are printed in a @code{\score}
784 when the paper variable @code{print-all-headers} is set to
785 @code{##f} (the default).
788 @c Is the bit about \null markups true? -mp
789 Text fields left unset in a @code{\header} block are replaced with
790 @code{\null} markups so that the space is not wasted.
793 The default settings for @code{scoreTitleMarkup} place the @code{piece}
794 and @code{opus} text fields at opposite ends of the same line.
798 To change the default layout see @ref{Custom layout for titles}.
802 If a @code{\book} block starts immediately with a @code{\bookpart}
803 block, no Book Title will be printed, as there is no page on which
804 to print it. If a Book Title is required, begin the @code{\book}
805 block with some markup material or a @code{\pageBreak} command.
807 Use the @code{breakbefore} variable inside a @code{\header} block
808 that is itself in a @code{\score} block, to make the higher-level
809 @code{\header} block titles appear on the first page on their own, with
810 the music (defined in the @code{\score} block) starting on the next.
812 @lilypond[papersize=c7landscape,verbatim,noragged-right]
815 title = "This is my Title"
816 subtitle = "This is my Subtitle"
817 copyright = "This is the bottom of the first page"
820 \repeat unfold 4 { e'' e'' e'' e'' }
822 piece = "This is the Music"
831 @rlearning{How LilyPond input files work},
834 @ref{Custom layout for titles},
835 @ref{File structure}.
838 @file{ly/titling-init.ly}.
841 @node Default layout of headers and footers
842 @unnumberedsubsubsec Default layout of headers and footers
844 @emph{Headers} and @emph{footers} are lines of text appearing at
845 the top and bottom of pages, separate from the main text of a book.
846 They are controlled by the following @code{\paper} variables:
849 @item @code{oddHeaderMarkup}
850 @item @code{evenHeaderMarkup}
851 @item @code{oddFooterMarkup}
852 @item @code{evenFooterMarkup}
855 These markup variables can only access text fields from top-level
856 @code{\header} blocks (which apply to all scores in the book) and are
857 defined in @file{ly/titling-init.ly}. By default:
862 page numbers are automatically placed on the top far left (if even) or
863 top far right (if odd), starting from the second page.
866 the @code{instrument} text field is placed in the center of every
867 page, starting from the second page.
870 the @code{copyright} text is centered on the bottom of the first page.
873 the @code{tagline} is centered on the bottom of the last page, and below
874 the @code{copyright} text if there is only a single page.
878 The default tagline can be changed by adding a @code{tagline} in the
879 top-level @code{\header} block.
881 @lilypond[papersize=a8landscape,verbatim]
884 tagline = "... music notation for Everyone"
894 To remove the @code{tagline} set the value to @code{##f}.
897 @node Custom titles headers and footers
898 @subsection Custom titles headers and footers
900 @c TODO: somewhere put a link to header spacing info
901 @c (you'll have to explain it more in NR 4).
904 * Custom text formatting for titles::
905 * Custom layout for titles::
906 * Custom layout for headers and footers::
910 @node Custom text formatting for titles
911 @unnumberedsubsubsec Custom text formatting for titles
913 Standard @code{\markup} commands can be used to customize any header,
914 footer and title text within the @code{\header} block.
916 @lilypond[quote,verbatim,noragged-right]
920 piece = \markup { \fontsize #4 \bold "PRAELUDIUM I" }
921 opus = \markup { \italic "BWV 846" }
928 @ref{Formatting text}.
931 @node Custom layout for titles
932 @unnumberedsubsubsec Custom layout for titles
934 @cindex bookTitleMarkup
935 @cindex scoreTitleMarkup
936 @funindex bookTitleMarkup
937 @funindex scoreTitleMarkup
939 @code{\markup} commands in the @code{\header} block are useful for
940 simple text formatting, but they do not allow precise control over the
941 placement of titles. To customize the placement of the text fields,
942 change either or both of the following @code{\paper} variables:
945 @item @code{bookTitleMarkup}
946 @item @code{scoreTitleMarkup}
949 The placement of titles when using the default values of these
950 @code{\markup} variables is shown in the examples in
951 @ref{Default layout of bookpart and score titles}.
953 The default settings for @code{scoreTitleMarkup} as defined in
954 @file{ly/titling-init.ly} are:
957 scoreTitleMarkup = \markup @{ \column @{
958 \on-the-fly \print-all-headers @{ \bookTitleMarkup \hspace #1 @}
960 \fromproperty #'header:piece
961 \fromproperty #'header:opus
967 This places the @code{piece} and @code{opus} text fields at opposite
968 ends of the same line:
970 @lilypond[quote,verbatim,noragged-right]
974 piece = "PRAELUDIUM I"
980 This example redefines @code{scoreTitleMarkup} so that the @code{piece}
981 text field is centered and in a large, bold font.
983 @lilypond[papersize=a5,quote,verbatim,noragged-right]
987 scoreTitleMarkup = \markup {
990 \fontsize #4 \bold \fromproperty #'header:piece
991 \fromproperty #'header:opus
995 \header { tagline = ##f }
999 piece = "PRAELUDIUM I"
1006 Text fields not normally effective in score @code{\header} blocks
1007 can be printed in the Score Title area if @code{print-all-headers} is
1008 placed inside the @code{\paper} block. A disadvantage of using this
1009 method is that text fields that are intended specifically for the
1010 Bookpart Title area need to be manually suppressed in every
1011 @code{\score} block. See @ref{Titles explained}.
1013 To avoid this, add the desired text field to the @code{scoreTitleMarkup}
1014 definition. In the following example, the @code{composer} text field
1015 (normally associated with @code{bookTitleMarkup}) is added to
1016 @code{scoreTitleMarkup}, allowing each score to list a different
1019 @lilypond[papersize=a5,quote,verbatim,noragged-right]
1023 scoreTitleMarkup = \markup {
1026 \fontsize #4 \bold \fromproperty #'header:piece
1027 \fromproperty #'header:composer
1031 \header { tagline = ##f }
1036 composer = "Christian Petzold"
1043 composer = "François Couperin"
1049 It is also possible to create your own custom text fields, and refer to
1050 them in the markup definition.
1052 @lilypond[papersize=a5,quote,verbatim,noragged-right]
1056 scoreTitleMarkup = \markup {
1059 \override #`(direction . ,UP) {
1061 \center-align \fontsize #-1 \bold
1062 \fromproperty #'header:mycustomtext %% User-defined field
1063 \center-align \fontsize #4 \bold
1064 \fromproperty #'header:piece
1067 \fromproperty #'header:opus
1071 \header { tagline = ##f }
1076 mycustomtext = "A 4 VOCI" %% User-defined field
1085 @ref{Titles explained}.
1088 @node Custom layout for headers and footers
1089 @unnumberedsubsubsec Custom layout for headers and footers
1091 @c can make-header and make-footer be removed from
1092 @c paper-defaults-init.ly? -mp
1094 @code{\markup} commands in the @code{\header} block are useful for
1095 simple text formatting, but they do not allow precise control over the
1096 placement of headers and footers. To customize the placement of
1097 the text fields, use either or both of the following @code{\paper}
1101 @item @code{oddHeaderMarkup}
1102 @item @code{evenHeaderMarkup}
1103 @item @code{oddFooterMarkup}
1104 @item @code{evenFooterMarkup}
1107 @cindex markup, conditional
1109 @funindex \on-the-fly
1111 The @code{\markup} command @code{\on-the-fly} can be used to add
1112 markup conditionally to header and footer text defined within the
1113 @code{\paper} block, using the following syntax:
1116 @code{variable} = @code{\markup} @{
1118 @code{\on-the-fly} \@var{procedure} @var{markup}
1123 The @var{procedure} is called each time the @code{\markup} command
1124 in which it appears is evaluated. The @var{procedure} should test
1125 for a particular condition and interpret (i.e. print) the
1126 @var{markup} argument if and only if the condition is true.
1128 A number of ready-made procedures for testing various conditions are
1132 @multitable {print-page-number-check-first-----} {should this page be printed-----}
1134 @headitem Procedure name @tab Condition tested
1136 @item print-page-number-check-first @tab should this page number be printed?
1137 @item create-page-number-stencil @tab print-page-numbers true?
1138 @item print-all-headers @tab print-all-headers true?
1139 @item first-page @tab first page in the book?
1140 @item (on-page nmbr) @tab page number = nmbr?
1141 @item last-page @tab last page in the book?
1142 @item not-first-page @tab not first page in the book?
1143 @item part-first-page @tab first page in the book part?
1144 @item part-last-page @tab last page in the book part?
1145 @item not-single-page @tab pages in book part > 1?
1150 The following example centers page numbers at the bottom of every
1151 page. First, the default settings for @code{oddHeaderMarkup} and
1152 @code{evenHeaderMarkup} are removed by defining each as a @emph{null}
1153 markup. Then, @code{oddFooterMarkup} is redefined with the page
1154 number centered. Finally, @code{evenFooterMarkup} is given the
1155 same layout by defining it as @code{\oddFooterMarkup}:
1157 @lilypond[papersize=a8,quote,verbatim,noragged-right]
1160 print-page-number = ##t
1161 print-first-page-number = ##t
1162 oddHeaderMarkup = \markup \null
1163 evenHeaderMarkup = \markup \null
1164 oddFooterMarkup = \markup {
1166 \on-the-fly \print-page-number-check-first
1167 \fromproperty #'page:page-number-string
1170 evenFooterMarkup = \oddFooterMarkup
1173 \new Staff { s1 \break s1 \break s1 }
1178 Several @code{\on-the-fly} conditions can be combined with an
1179 @q{and} operation, for example,
1182 @code{\on-the-fly \first-page}
1183 @code{\on-the-fly \last-page}
1184 @code{@{ \markup @dots{} \fromproperty #'header: @dots{} @}}
1187 determines if the output is a single page.
1191 @ref{Titles explained},
1192 @ref{Default layout of bookpart and score titles}.
1195 @file{../ly/titling-init.ly}.
1198 @node Creating footnotes
1199 @subsection Creating footnotes
1203 Footnotes may be used in many different situations. In all cases,
1204 a @q{footnote mark} is placed as a reference in text or music, and
1205 the corresponding @q{footnote text} appears at the bottom of the
1208 Footnotes within music expressions and footnotes in stand-alone text
1209 outside music expressions are created in different ways.
1212 * Footnotes in music expressions::
1213 * Footnotes in stand-alone text::
1216 @node Footnotes in music expressions
1217 @unnumberedsubsubsec Footnotes in music expressions
1219 @cindex footnotes in music expressions
1222 @subsubsubheading Music footnotes overview
1224 Footnotes in music expressions fall into two categories:
1227 @item Event-based footnotes
1228 are attached to a particular event. Examples for such events are
1229 single notes, articulations (like fingering indications, accents,
1230 dynamics), and post-events (like slurs and manual beams). The
1231 general form for event-based footnotes is as follows:
1234 [@var{direction}] \footnote [@var{mark}] @var{offset} @var{footnote} @var{music}
1237 @item Time-based footnotes
1238 are bound to a particular point of time in a musical context. Some
1239 commands like @code{\time} and @code{\clef} don't actually use events
1240 for creating objects like time signatures and clefs. Neither does a
1241 chord create an event of its own: its stem or flag is created at the
1242 end of a time step (nominally through one of the note events inside).
1243 Exactly which of a chord's multiple note events will be deemed the
1244 root cause of a stem or flag is undefined. So for annotating those,
1245 time-based footnotes are preferable as well.
1247 A time-based footnote allows such layout objects to be annotated
1248 without referring to an event. The general form for Time-based
1252 \footnote [@var{mark}] @var{offset} @var{footnote} [@var{Context}].@var{GrobName}
1257 The elements for both forms are:
1262 If (and only if) the @code{\footnote} is being applied to a
1263 post-event or articulation, it must be preceded with a direction
1264 indicator (@code{-, _, ^}) in order to attach @var{music} (with
1265 a footnote mark) to the preceding note or rest.
1268 is a markup or string specifying the footnote mark which is used for
1269 marking both the reference point and the footnote itself at the
1270 bottom of the page. It may be omitted (or equivalently replaced with
1271 @code{\default}) in which case a number in sequence will be generated
1272 automatically. Such numerical sequences restart on each page
1273 containing a footnote.
1276 is a number pair such as @samp{#(2 . 1)} specifying the X and
1277 Y@tie{}offsets in units of staff-spaces from the boundary of the
1278 object where the mark should be placed. Positive values of the
1279 offsets are taken from the right/top edge, negative values from the
1280 left/bottom edge and zero implies the mark is centered on the edge.
1283 is the context in which the grob being footnoted is created. It
1284 may be omitted if the grob is in a bottom context, e.g. a
1285 @code{Voice} context.
1288 specifies a type of grob to mark (like @samp{Flag}). If it is
1289 specified, the footnote is not attached to a music expression in
1290 particular, but rather to all grobs of the type specified which
1291 occur at that moment of musical time.
1294 is the markup or string specifying the footnote text to use at the
1298 is the music event or post-event or articulation
1299 that is being annotated.
1303 @subsubsubheading Event-based footnotes
1305 @cindex footnotes, event-based
1307 A footnote may be attached to a layout object directly caused
1308 by the event corresponding to @var{music} with the syntax:
1311 \footnote [@var{mark}] @var{offset} @var{footnote} @var{music}
1314 @lilypond[quote,verbatim,papersize=a8landscape]
1316 \header { tagline = ##f }
1318 \footnote #'(-1 . 3) "A note" a4
1320 \footnote #'(2 . 2) "A rest" r4
1326 Marking a @emph{whole} chord with an event-based footnote is not
1327 possible: a chord, even one containing just a single note, does
1328 not produce an actual event of its own. However, individual
1329 notes @emph{inside} of the chord can be marked:
1331 @lilypond[quote,verbatim,papersize=a8landscape]
1333 \header { tagline = ##f }
1335 \footnote #'(2 . 3) "Does not work" <a-3>2
1336 <\footnote #'(-2 . -3) "Does work" a-3>4
1337 <a-3 \footnote #'(3 . 1/2) "Also works" c-5>4
1342 If the footnote is to be attached to a post-event or articulation
1343 the @code{\footnote} command @emph{must} be preceded by a direction
1344 indicator, @code{-, _, ^}, and followed by the post-event or
1345 articulation to be annotated as the @var{music} argument. In this
1346 form the @code{\footnote} can be considered to be simply a copy of
1347 its last argument with a footnote mark attached to it. The syntax
1351 @var{direction} \footnote [@var{mark}] @var{offset} @var{footnote} @var{music}
1354 @lilypond[quote,verbatim,papersize=a8landscape]
1356 \header { tagline = ##f }
1358 a'4_\footnote #'(0 . -1) "A slur forced down" (
1359 b8^\footnote #'(1 . 0.5) "A manual beam forced up" [
1362 c-\footnote #'(1 . 1) "Tenuto" --
1367 @subsubsubheading Time-based footnotes
1369 @cindex footnotes, time-based
1371 If the layout object being footmarked is @emph{indirectly} caused by
1372 an event (like an @code{Accidental} or @code{Stem} caused by a
1373 @code{NoteHead} event), the @var{GrobName} of the layout object
1374 is required after the footnote text instead of @var{music}:
1376 @lilypond[quote,verbatim,papersize=a8landscape]
1378 \header { tagline = ##f }
1380 \footnote #'(-1 . -3) "A flat" Accidental
1382 \footnote #'(-1 . 0.5) "Another flat" Accidental
1384 \footnote #'(1 . -2) "A stem" Stem
1390 Note, however, that when a GrobName is specified, a footnote
1391 will be attached to all grobs of that type at the current time step:
1393 @lilypond[quote,verbatim,papersize=a8landscape]
1395 \header { tagline = ##f }
1397 \footnote #'(-1 . 3) "A flat" Accidental
1399 \footnote #'(2 . 0.5) "Articulation" Script
1405 A note inside of a chord can be given an individual (event-based)
1406 footnote. A @samp{NoteHead} is the only grob directly caused
1407 from a chord note, so an event-based footnote command is
1408 @emph{only} suitable for adding a footnote to the @samp{NoteHead}
1409 within a chord. All other chord note grobs are indirectly caused.
1410 The @code{\footnote} command itself offers no syntax for
1411 specifying @emph{both} a particular grob type @emph{as well as} a
1412 particular event to attach to. However, one can use a time-based
1413 @code{\footnote} command for specifying the grob type, and then
1414 prefix this command with @code{\single} in order to have it
1415 applied to just the following event:
1417 @lilypond[quote,verbatim,papersize=a8landscape]
1419 \header { tagline = ##f }
1421 < \footnote #'(1 . -2) "An A" a
1422 \single \footnote #'(-1 . -1) "A sharp" Accidental
1424 \single \footnote #'(0.5 . 0.5) "A flat" Accidental
1431 @warning {When footnotes are attached to several musical elements at
1432 the same musical moment, as they are in the example above, the
1433 footnotes are numbered from the higher to the lower elements as they
1434 appear in the printed output, not in the order in which they are
1435 written in the input stream.}
1437 Layout objects like clefs and key-change signatures are mostly caused
1438 as a consequence of changed properties rather than actual events.
1439 Others, like bar lines and bar numbers, are a direct consequence of
1440 timing. For this reason, footnotes on such objects have to be based
1441 on their musical timing. Time-based footnotes are also preferable
1442 when marking features like stems and beams on @emph{chords}: while
1443 such per-chord features are nominally assigned to @emph{one} event
1444 inside the chord, relying on a particular choice would be imprudent.
1446 The layout object in question must always be explicitly specified
1447 for time-based footnotes, and the appropriate context must be
1448 specified if the grob is created in a context other than the bottom
1451 @lilypond[quote,verbatim,papersize=a8landscape]
1453 \header { tagline = ##f }
1456 \footnote #'(-0.5 . -1) "Meter change" Staff.TimeSignature
1458 \footnote #'(1 . -1) "Chord stem" Stem
1460 \footnote #'(-0.5 . 1) "Bar line" Staff.BarLine
1462 \footnote #'(0.5 . -1) "Key change" Staff.KeySignature
1469 Custom marks can be used as alternatives to numerical marks, and the
1470 annotation line joining the marked object to the mark can be
1473 @lilypond[quote,verbatim,papersize=a8landscape]
1475 \header { tagline = ##f }
1477 \footnote "*" #'(0.5 . -2) \markup { \italic "* The first note" } a'4
1479 \footnote \markup { \super "$" } #'(0.5 . 1)
1480 \markup { \super "$" \italic " The second note" } e
1482 \once \override Score.FootnoteItem.annotation-line = ##f
1483 b-\footnote \markup \tiny "+" #'(0.1 . 0.1)
1484 \markup { \super "+" \italic " Editorial" } \p
1489 More examples of custom marks are shown in
1490 @ref{Footnotes in stand-alone text}.
1493 @node Footnotes in stand-alone text
1494 @unnumberedsubsubsec Footnotes in stand-alone text
1496 @cindex footnotes in stand-alone text
1498 These are for use in markup outside of music expressions. They do
1499 not have a line drawn to their point of reference: their marks simply
1500 follow the referenced markup. Marks can be inserted automatically,
1501 in which case they are numerical. Alternatively, custom marks can be
1504 Footnotes to stand-alone text with automatic and custom marks are
1505 created in different ways.
1507 @subsubsubheading Footnotes in stand-alone text with automatic marks
1509 The syntax of a footnote in stand-alone text with automatic marks is
1512 \markup @{ @dots{} \auto-footnote @var{text} @var{footnote} @dots{} @}
1520 is the markup or string to be marked.
1523 is the markup or string specifying the footnote text to use at the bottom
1530 @lilypond[verbatim,quote,ragged-right,papersize=a8]
1532 \header { tagline = ##f }
1535 \auto-footnote "tune" \italic " By me"
1536 "is shown below. It is a"
1537 \auto-footnote "recent" \italic " Aug 2012"
1546 @subsubsubheading Footnotes in stand-alone text with custom marks
1548 The syntax of a footnote in stand-alone text with custom marks is
1551 \markup @{ @dots{} \footnote @var{mark} @var{footnote} @dots{} @}
1559 is a markup or string specifying the footnote mark which is used for
1560 marking the reference point. Note that this mark is @emph{not}
1561 inserted automatically before the footnote itself.
1564 is the markup or string specifying the footnote text to use at the
1565 bottom of the page, preceded by the @var{mark}.
1569 Any easy-to-type character such as * or + may be used as a mark, as
1570 shown in @ref{Footnotes in music expressions}. Alteratively, ASCII
1571 aliases may be used (see @ref{ASCII aliases}):
1573 @lilypond[verbatim,quote,ragged-right,papersize=a8]
1575 \paper { #(include-special-characters) }
1576 \header { tagline = ##f }
1579 \footnote "*" \italic "* By me"
1580 "is shown below. It is a recent"
1581 \footnote \super † \concat {
1582 \super † \italic " Aug 2012"
1592 Unicode character codes may also be used to specify marks
1593 (see @ref{Unicode}):
1595 @lilypond[verbatim,quote,ragged-right,papersize=a8]
1597 \header { tagline = ##f }
1600 \footnote \super \char##x00a7 \concat {
1601 \super \char##x00a7 \italic " By me"
1603 "is shown below. It is a recent"
1604 \footnote \super \char##x00b6 \concat {
1605 \super \char##x00b6 \italic " Aug 2012"
1617 @rlearning{Objects and interfaces}.
1620 @ref{ASCII aliases},
1622 @ref{List of special characters},
1627 Internals Reference:
1628 @rinternals{FootnoteEvent},
1629 @rinternals{FootnoteItem},
1630 @rinternals{FootnoteSpanner},
1631 @rinternals{Footnote_engraver}.
1634 Multiple footnotes for the same page can only be stacked, one above
1635 the other; they cannot be printed on the same line.
1637 Footnotes cannot be attached to @code{MultiMeasureRests} or
1638 automatic beams or lyrics.
1640 Footnote marks may collide with staves, @code{\markup} objects, other
1641 footnote marks and annotation lines.
1644 @node Reference to page numbers
1645 @subsection Reference to page numbers
1647 A particular place of a score can be marked using the @code{\label}
1648 command, either at top-level or inside music. This label can then be
1649 referred to in a markup, to get the number of the page where the marked
1650 point is placed, using the @code{\page-ref} markup command.
1652 @lilypond[verbatim,papersize=a8landscape]
1653 \header { tagline = ##f }
1659 \pageBreak \mark A \label #'markA
1663 \markup { The first score begins on page \page-ref #'firstScore "0" "?" }
1664 \markup { Mark A is on page \page-ref #'markA "0" "?" }
1668 The @code{\page-ref} markup command takes three arguments:
1670 @item the label, a scheme symbol, eg. @code{#'firstScore};
1671 @item a markup that will be used as a gauge to estimate the dimensions
1673 @item a markup that will be used in place of the page number if the label
1677 The reason why a gauge is needed is that, at the time markups are
1678 interpreted, the page breaking has not yet occurred, so the page numbers
1679 are not yet known. To work around this issue, the actual markup
1680 interpretation is delayed to a later time; however, the dimensions of
1681 the markup have to be known before, so a gauge is used to decide these
1682 dimensions. If the book has between 10 and 99 pages, it may be "00",
1683 ie. a two digit number.
1694 @node Table of contents
1695 @subsection Table of contents
1696 A table of contents is included using the @code{\markuplist \table-of-contents}
1697 command. The elements which should appear in the table of contents are
1698 entered with the @code{\tocItem} command, which may be used either at
1699 top-level, or inside a music expression.
1702 \markuplist \table-of-contents
1705 \tocItem \markup "First score"
1709 \tocItem \markup "Some particular point in the first score"
1714 \tocItem \markup "Second score"
1722 The markups which are used to format the table of contents are defined
1723 in the @code{\paper} block. The default ones are @code{tocTitleMarkup},
1724 for formatting the title of the table, and @code{tocItemMarkup}, for
1725 formatting the toc elements, composed of the element title and page
1726 number. These variables may be changed by the user:
1730 %% Translate the toc title into French:
1731 tocTitleMarkup = \markup \huge \column {
1732 \fill-line { \null "Table des matières" \null }
1735 %% use larger font size
1736 tocItemMarkup = \markup \large \fill-line {
1737 \fromproperty #'toc:text \fromproperty #'toc:page
1742 Note how the toc element text and page number are referred to in
1743 the @code{tocItemMarkup} definition.
1745 New commands and markups may also be defined to build more elaborated
1748 @item first, define a new markup variable in the @code{\paper} block
1749 @item then, define a music function which aims at adding a toc element
1750 using this markup paper variable.
1753 In the following example, a new style is defined for entering act names
1754 in the table of contents of an opera:
1758 tocActMarkup = \markup \large \column {
1760 \fill-line { \null \italic \fromproperty #'toc:text \null }
1766 #(define-music-function (text) (markup?)
1767 (add-toc-item! 'tocActMarkup text))
1770 @lilypond[line-width=10.0\cm]
1771 \header { tagline = ##f }
1773 tocActMarkup = \markup \large \column {
1775 \fill-line { \null \italic \fromproperty #'toc:text \null }
1781 #(define-music-function (text) (markup?)
1782 (add-toc-item! 'tocActMarkup text))
1785 \markuplist \table-of-contents
1786 \tocAct \markup { Atto Primo }
1787 \tocItem \markup { Coro. Viva il nostro Alcide }
1788 \tocItem \markup { Cesare. Presti omai l'Egizzia terra }
1789 \tocAct \markup { Atto Secondo }
1790 \tocItem \markup { Sinfonia }
1791 \tocItem \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
1796 Dots can be added to fill the line between an item and its page number:
1798 @lilypond[verbatim,line-width=10.0\cm]
1799 \header { tagline = ##f }
1801 tocItemMarkup = \tocItemWithDotsMarkup
1805 \markuplist \table-of-contents
1806 \tocItem \markup { Allegro }
1807 \tocItem \markup { Largo }
1814 @file{ly/toc-init.ly}.
1817 @funindex \table-of-contents
1818 @code{\table-of-contents},
1824 @node Working with input files
1825 @section Working with input files
1828 * Including LilyPond files::
1829 * Different editions from one source::
1830 * Special characters::
1834 @node Including LilyPond files
1835 @subsection Including LilyPond files
1838 @cindex including files
1840 A large project may be split up into separate files. To refer to
1844 \include "otherfile.ly"
1847 The line @code{\include "otherfile.ly"} is equivalent to pasting the
1848 contents of @file{otherfile.ly} into the current file at the place
1849 where the @code{\include} appears. For example, in a large
1850 project you might write separate files for each instrument part
1851 and create a @qq{full score} file which brings together the
1852 individual instrument files. Normally the included file will
1853 define a number of variables which then become available
1854 for use in the full score file. Tagged sections can be
1855 marked in included files to assist in making them usable in
1856 different places in a score, see @ref{Different editions from
1859 Files in the current working directory may be referenced by
1860 specifying just the file name after the @code{\include} command.
1861 Files in other locations may be included by giving either a full
1862 path reference or a relative path reference (but use the UNIX
1863 forward slash, /, rather than the DOS/Windows back slash, \, as the
1864 directory separator.) For example, if @file{stuff.ly} is located
1865 one directory higher than the current working directory, use
1868 \include "../stuff.ly"
1872 or if the included orchestral parts files are all located in a
1873 subdirectory called @file{parts} within the current directory, use
1876 \include "parts/VI.ly"
1877 \include "parts/VII.ly"
1881 Files which are to be included can also contain @code{\include}
1882 statements of their own. By default, these second-level
1883 @code{\include} statements are not interpreted until they have
1884 been brought into the main file, so the file names they specify
1885 must all be relative to the directory containing the main file,
1886 not the directory containing the included file. However,
1887 this behavior can be changed globally by passing the option
1888 @option{-drelative-includes} option at the command line
1889 (or by adding @code{#(ly:set-option 'relative-includes #t)}
1890 at the top of the main input file).
1892 When @code{relative-includes} is set to @code{#t}, the path for each
1893 @code{\include} command will be taken relative to the file containing
1894 that command. This behavior is recommended and it will become the
1895 default behavior in a future version of lilypond.
1897 Files relative to the main directory and files relative to some other
1898 directory may both be @code{\include}d by setting
1899 @code{relative-includes} to @code{#t} or @code{#f} at appropriate
1900 places in the files. For example, if a general library, libA, has
1901 been created which itself uses sub-files which are @code{\include}d
1902 by the entry file of that library, those @code{\include} statements
1903 will need to be preceded by
1904 @code{#(ly:set-option #relative-includes #t)} so they are interpreted
1905 correctly when brought into the main @code{.ly} file, like this:
1916 then the entry file, @code{libA.ly}, will contain
1919 #(ly:set-option 'relative-includes #t)
1923 % return to default setting
1924 #(ly:set-option 'relative-includes #f)
1927 Any @file{.ly} file can then include the entire library simply with
1930 \include "~/libA/libA.ly"
1933 More complex file structures may be devised by switching at
1936 Files can also be included from a directory in a search path
1937 specified as an option when invoking LilyPond from the command
1938 line. The included files are then specified using just their
1939 file name. For example, to compile @file{main.ly} which includes
1940 files located in a subdirectory called @file{parts} by this method,
1941 cd to the directory containing @file{main.ly} and enter
1944 lilypond --include=parts main.ly
1947 and in main.ly write
1955 Files which are to be included in many scores may be placed in
1956 the LilyPond directory @file{../ly}. (The location of this
1957 directory is installation-dependent - see
1958 @rlearning{Other sources of information}). These files can then
1959 be included simply by naming them on an @code{\include} statement.
1960 This is how the language-dependent files like @file{english.ly} are
1963 LilyPond includes a number of files by default when you start
1964 the program. These includes are not apparent to the user, but the
1965 files may be identified by running @code{lilypond --verbose} from
1966 the command line. This will display a list of paths and files that
1967 LilyPond uses, along with much other information. Alternatively,
1968 the more important of these files are discussed in
1969 @rlearning{Other sources of information}. These files may be
1970 edited, but changes to them will be lost on installing a new
1971 version of LilyPond.
1973 Some simple examples of using @code{\include} are shown in
1974 @rlearning{Scores and parts}.
1978 @rlearning{Other sources of information},
1979 @rlearning{Scores and parts}.
1982 If an included file is given a name which is the same as one in
1983 LilyPond's installation files, LilyPond's file from the
1984 installation files takes precedence.
1987 @node Different editions from one source
1988 @subsection Different editions from one source
1990 Several methods can be used to generate different versions of a score
1991 from the same music source. Variables are perhaps the most useful for
1992 combining lengthy sections of music and/or annotation. Tags are more
1993 useful for selecting one section from several alternative shorter
1994 sections of music, and can also be used for splicing pieces of music
1995 together at different points.
1997 Whichever method is used, separating the notation from the structure of
1998 the score will make it easier to change the structure while leaving the
2004 * Using global settings::
2007 @node Using variables
2008 @unnumberedsubsubsec Using variables
2010 @cindex variables, use of
2012 If sections of the music are defined in variables they can be
2013 reused in different parts of the score, see @rlearning{Organizing
2014 pieces with variables}. For example, an @notation{a cappella}
2015 vocal score frequently includes a piano reduction of the parts
2016 for rehearsal purposes which is identical to the vocal music, so
2017 the music need be entered only once. Music from two variables
2018 may be combined on one staff, see @ref{Automatic part combining}.
2021 @lilypond[verbatim,quote]
2022 sopranoMusic = \relative { a'4 b c b8( a) }
2023 altoMusic = \relative { e'4 e e f }
2024 tenorMusic = \relative { c'4 b e d8( c) }
2025 bassMusic = \relative { a4 gis a d, }
2026 allLyrics = \lyricmode {King of glo -- ry }
2028 \new Staff = "Soprano" \sopranoMusic
2029 \new Lyrics \allLyrics
2030 \new Staff = "Alto" \altoMusic
2031 \new Lyrics \allLyrics
2032 \new Staff = "Tenor" {
2036 \new Lyrics \allLyrics
2037 \new Staff = "Bass" {
2041 \new Lyrics \allLyrics
2044 \set Staff.printPartCombineTexts = ##f
2050 \set Staff.printPartCombineTexts = ##f
2060 Separate scores showing just the vocal parts or just the piano
2061 part can be produced by changing just the structural statements,
2062 leaving the musical notation unchanged.
2064 For lengthy scores, the variable definitions may be placed in
2065 separate files which are then included, see @ref{Including
2069 @unnumberedsubsubsec Using tags
2072 @funindex \keepWithTag
2073 @funindex \removeWithTag
2075 @cindex keep tagged music
2076 @cindex remove tagged music
2078 The @code{\tag #'@var{partA}} command marks a music expression
2079 with the name @var{partA}.
2080 Expressions tagged in this way can be selected or filtered out by
2081 name later, using either @code{\keepWithTag #'@var{name}} or
2082 @code{\removeWithTag #'@var{name}}. The result of applying these filters
2083 to tagged music is as follows:
2084 @multitable @columnfractions .5 .5
2088 Tagged music preceded by @code{\keepWithTag #'@var{name}} or
2089 @code{\keepWithTag #'(@var{name1} @var{name2}@dots{})}
2090 @tab Untagged music and music tagged with any of the given tag
2092 music tagged with any other tag name is excluded.
2094 Tagged music preceded by @code{\removeWithTag #'@var{name}} or
2095 @code{\removeWithTag #'(@var{name1} @var{name2}@dots{})}
2096 @tab Untagged music and music not tagged with any of the given tag names
2097 is included; music tagged with any of the given tag names is
2100 Tagged music not preceded by either @code{\keepWithTag} or
2101 @code{\removeWithTag}
2102 @tab All tagged and untagged music is included.
2105 The arguments of the @code{\tag}, @code{\keepWithTag} and
2106 @code{\removeWithTag} commands should be a symbol or list of
2107 symbols (such as @code{#'score} or @code{#'(violinI violinII}),
2108 followed by a music expression. If @emph{and only if} the symbols
2109 are valid LilyPond identifiers (alphabetic characters only, no
2110 numbers, underscores, or dashes) which cannot be confused with notes,
2111 the @code{#'} may be omitted and, as a shorthand, a list of symbols
2112 can use the dot separator: i.e. @code{\tag #'(violinI violinII)} can
2113 be written @code{\tag violinI.violinII}. The same applies to
2114 @code{\keepWithTag} and @code{\removeWithTag}.
2116 In the following example, we see two versions of a piece of music,
2117 one showing trills with the usual notation, and one with trills
2118 explicitly expanded:
2120 @lilypond[verbatim,quote]
2123 \tag #'trills { d8.\trill }
2124 \tag #'expand { \repeat unfold 3 { e32 d } }
2129 \keepWithTag #'trills \music
2132 \keepWithTag #'expand \music
2137 Alternatively, it is sometimes easier to exclude sections of music:
2139 @lilypond[verbatim,quote]
2142 \tag #'trills { d8.\trill }
2143 \tag #'expand {\repeat unfold 3 { e32 d } }
2148 \removeWithTag #'expand
2152 \removeWithTag #'trills
2157 Tagged filtering can be applied to articulations, texts, etc. by
2161 -\tag #'@var{your-tag}
2164 to an articulation. For example, this would define a note with a
2165 conditional fingering indication and a note with a conditional
2170 c1-\tag #'warn ^"Watch!"
2173 Multiple tags may be placed on expressions with multiple
2174 @code{\tag} entries, or by combining multiple tags into one symbol
2177 @lilypond[quote,verbatim]
2178 music = \relative c'' {
2179 \tag #'a \tag #'both { a4 a a a }
2180 \tag #'(b both) { b4 b b b }
2183 \keepWithTag #'a \music
2184 \keepWithTag #'b \music
2185 \keepWithTag #'both \music
2189 Multiple @code{\removeWithTag} filters may be applied to a single
2190 music expression to remove several differently named tagged
2191 sections. Alternatively, you can use a single
2192 @code{\removeWithTag} with a list of tags.
2194 @lilypond[verbatim,quote]
2195 music = \relative c'' {
2196 \tag #'A { a4 a a a }
2197 \tag #'B { b4 b b b }
2198 \tag #'C { c4 c c c }
2199 \tag #'D { d4 d d d }
2205 \removeWithTag #'(B C)
2210 Two or more @code{\keepWithTag} filters applied to a single music
2211 expression will cause @emph{all} tagged sections to be removed, as
2212 the first filter will remove all tagged sections except the one
2213 named, and the second filter will remove even that tagged section.
2214 Usually you would rather want to use a single @code{\keepWithTag}
2215 command with a list of multiple tags: this will only remove tagged
2216 sections not given in @emph{any} of the tags.
2220 While @code{\keepWithTag} is convenient when dealing with
2221 @emph{one} set of alternatives, the removal of music tagged with
2222 @emph{unrelated} tags is problematic when using tags for more than
2223 one purpose. For that reason, @q{tag groups} of related tags can
2227 \tagGroup #'(violinI violinII viola cello)
2230 declares the respective tags as belonging to one tag group.
2233 \keepWithTag #'violinI @dots{}
2236 will then only be concerned with tags from @code{violinI}'s tag
2237 group: any element of the included music that is tagged with one
2238 or more of tags from this set but @emph{not} with @code{violinI}
2241 To any @code{\keepWithTag} command, only tags from the tag groups
2242 of the tags given in the command are visible.
2244 Tags cannot be members of more than one tag group.
2246 @funindex \pushToTag
2247 @funindex \appendToTag
2248 @cindex splice into tagged music
2250 Sometimes you want to splice some music at a particular place in an
2251 existing music expression. You can use @code{\pushToTag} and
2252 @code{\appendToTag} for adding material at the front or end of the
2253 @code{elements} of an existing music construct. Not every music
2254 construct has @code{elements}, but sequential and simultaneous music are
2257 @lilypond[verbatim,quote]
2258 test = { \tag #'here { \tag #'here <<c''>> } }
2261 \pushToTag #'here c'
2262 \pushToTag #'here e'
2263 \pushToTag #'here g' \test
2264 \appendToTag #'here c'
2265 \appendToTag #'here e'
2266 \appendToTag #'here g' \test
2270 Both commands get a tag, the material to splice in at every occurence of
2271 the tag, and the tagged expression.
2275 @rlearning{Organizing pieces with variables}.
2278 @ref{Automatic part combining},
2279 @ref{Including LilyPond files}.
2282 Calling @code{\relative} on a music expression obtained by filtering
2283 music through @code{\keepWithTag} or @code{\removeWithTag} might cause
2284 the octave relations to change, as only the pitches actually
2285 remaining in the filtered expression will be considered. Applying
2286 @code{\relative} first, before @code{\keepWithTag} or
2287 @code{\removeWithTag}, avoids this danger as @code{\relative} then
2288 acts on all the pitches as-input.
2291 @node Using global settings
2292 @unnumberedsubsubsec Using global settings
2294 @cindex include-settings
2296 Global settings can be included from a separate file:
2299 lilypond -dinclude-settings=MY_SETTINGS.ly MY_SCORE.ly
2302 Groups of settings such as page size, font or type face can be stored
2303 in separate files. This allows different editions from the same score
2304 as well as standard settings to be applied to many scores, simply by
2305 specifying the proper settings file.
2307 This technique also works well with the use of style sheets, as
2308 discussed in @rlearning{Style sheets}.
2312 @rlearning{Organizing pieces with variables},
2313 @rlearning{Style sheets}.
2316 @ref{Including LilyPond files}.
2319 @node Special characters
2320 @subsection Special characters
2322 @cindex special characters
2323 @cindex non-ASCII characters
2333 @unnumberedsubsubsec Text encoding
2337 LilyPond uses the character repertoire defined by the Unicode
2338 consortium and ISO/IEC 10646. This defines a unique name and
2339 code point for the character sets used in virtually all modern
2340 languages and many others too. Unicode can be implemented using
2341 several different encodings. LilyPond uses the UTF-8 encoding
2342 (UTF stands for Unicode Transformation Format) which represents
2343 all common Latin characters in one byte, and represents other
2344 characters using a variable length format of up to four bytes.
2346 The actual appearance of the characters is determined by the
2347 glyphs defined in the particular fonts available - a font defines
2348 the mapping of a subset of the Unicode code points to glyphs.
2349 LilyPond uses the Pango library to layout and render multi-lingual
2352 LilyPond does not perform any input-encoding conversions. This
2353 means that any text, be it title, lyric text, or musical
2354 instruction containing non-ASCII characters, must be encoded in
2355 UTF-8. The easiest way to enter such text is by using a
2356 Unicode-aware editor and saving the file with UTF-8 encoding. Most
2357 popular modern editors have UTF-8 support, for example, vim, Emacs,
2358 jEdit, and GEdit do. All MS Windows systems later than NT use
2359 Unicode as their native character encoding, so even Notepad can
2360 edit and save a file in UTF-8 format. A more functional
2361 alternative for Windows is BabelPad.
2363 If a LilyPond input file containing a non-ASCII character is not
2364 saved in UTF-8 format the error message
2367 FT_Get_Glyph_Name () error: invalid argument
2372 Here is an example showing Cyrillic, Hebrew and Portuguese
2376 %c No verbatim here as the code does not display correctly in PDF
2378 bulgarian = \lyricmode {
2379 Жълтата дюля беше щастлива, че пухът, който цъфна, замръзна като гьон.
2383 hebrew = \lyricmode {
2384 זה כיף סתם לשמוע איך תנצח קרפד עץ טוב בגן.
2388 portuguese = \lyricmode {
2389 à vo -- cê uma can -- ção legal
2395 \addlyrics { \bulgarian }
2396 \addlyrics { \hebrew }
2397 \addlyrics { \portuguese }
2402 @unnumberedsubsubsec Unicode
2406 To enter a single character for which the Unicode code point is
2407 known but which is not available in the editor being used, use
2408 either @code{\char ##xhhhh} or @code{\char #dddd} within a
2409 @code{\markup} block, where @code{hhhh} is the hexadecimal code for
2410 the character required and @code{dddd} is the corresponding decimal
2411 value. Leading zeroes may be omitted, but it is usual to specify
2412 all four characters in the hexadecimal representation. (Note that
2413 the UTF-8 encoding of the code point should @emph{not} be used
2414 after @code{\char}, as UTF-8 encodings contain extra bits indicating
2415 the number of octets.) Unicode code charts and a character name
2416 index giving the code point in hexadecimal for any character can be
2417 found on the Unicode Consortium website,
2418 @uref{http://www.unicode.org/}.
2420 For example, @code{\char ##x03BE} and @code{\char #958} would both
2421 enter the Unicode U+03BE character, which has the Unicode name
2422 @qq{Greek Small Letter Xi}.
2424 Any Unicode code point may be entered in this way and if all special
2425 characters are entered in this format it is not necessary to save
2426 the input file in UTF-8 format. Of course, a font containing all
2427 such encoded characters must be installed and available to LilyPond.
2429 The following example shows Unicode hexadecimal values being entered
2430 in four places -- in a rehearsal mark, as articulation text, in
2431 lyrics and as stand-alone text below the score:
2433 @lilypond[quote,verbatim]
2436 c''1 \mark \markup { \char ##x03EE }
2437 c1_\markup { \tiny { \char ##x03B1 " to " \char ##x03C9 } }
2439 \addlyrics { O \markup { \concat { Ph \char ##x0153 be! } } }
2441 \markup { "Copyright 2008--2015" \char ##x00A9 }
2444 @cindex copyright sign
2446 To enter the copyright sign in the copyright notice use:
2450 copyright = \markup @{ \char ##x00A9 "2008" @}
2456 @unnumberedsubsubsec ASCII aliases
2458 A list of ASCII aliases for special characters can be included:
2460 @lilypond[quote,verbatim]
2462 #(include-special-characters)
2465 \markup "&flqq; – &OE;uvre incomplète… &frqq;"
2468 \new Staff { \repeat unfold 9 a'4 }
2470 This is al -- so wor -- kin'~in ly -- rics: –_&OE;…
2475 "The replacement can be disabled:"
2476 "– &OE; …"
2477 \override #'(replacement-alist . ()) "– &OE; …"
2481 You can also make your own aliases, either globally:
2483 @lilypond[quote,verbatim]
2485 #(add-text-replacements!
2486 '(("100" . "hundred")
2487 ("dpi" . "dots per inch")))
2489 \markup "A 100 dpi."
2494 @lilypond[quote,verbatim]
2495 \markup \replace #'(("100" . "hundred")
2496 ("dpi" . "dots per inch")) "A 100 dpi."
2501 @ref{List of special characters}.
2504 @file{ly/text-replacements.ly}.
2507 @node Controlling output
2508 @section Controlling output
2511 * Extracting fragments of music::
2512 * Skipping corrected music::
2513 * Alternative output formats::
2514 * Replacing the notation font::
2517 @funindex clip-regions
2518 @cindex Fragments, music
2519 @cindex Music fragments
2521 @node Extracting fragments of music
2522 @subsection Extracting fragments of music
2524 It is possible to output one or more fragments of a score by defining
2525 the explicit location of the music to be extracted within the
2526 @code{\layout} block of the the input file using the @code{clip-regions}
2527 function, and then running LilyPond with the @option{-dclip-systems}
2535 (make-rhythmic-location 5 1 2)
2536 (make-rhythmic-location 7 3 4)))
2541 This example will extract a single fragment of the input file
2542 @emph{starting} after a half-note duration in fifth measure
2543 (@code{5 1 2}) and @emph{ending} after the third quarter-note in the
2544 seventh measure (@code{7 3 4}).
2546 Additional fragments can be extracted by adding more pairs of
2547 @code{make-rhythmic-location} entries to the @code{clip-regions} list in
2548 the @code{\layout} block.
2550 By default, each music fragment will be output as a separate @code{EPS}
2551 file, but other formats such as @code{PDF} or @code{PNG} can also be
2552 created if required. The extracted music is output as if had been
2553 literally @q{cut} from the original printed score so if a fragment runs
2554 over one or more lines, a separate ouput file for each line will be
2559 @ref{The layout block}.
2562 @rprogram{Command-line usage}.
2566 @node Skipping corrected music
2567 @subsection Skipping corrected music
2570 @funindex skipTypesetting
2571 @funindex showFirstLength
2572 @funindex showLastLength
2574 When entering or copying music, usually only the music near the end (where
2576 are adding notes) is interesting to view and correct. To speed up
2577 this correction process, it is possible to skip typesetting of all but
2578 the last few measures. This is achieved by putting
2581 showLastLength = R1*5
2582 \score @{ @dots{} @}
2586 in your source file. This will render only the last 5 measures
2587 (assuming 4/4 time signature) of every @code{\score} in the input
2588 file. For longer pieces, rendering only a small part is often an order
2589 of magnitude quicker than rendering it completely. When working on the
2590 beginning of a score you have already typeset (e.g. to add a new part),
2591 the @code{showFirstLength} property may be useful as well.
2593 Skipping parts of a score can be controlled in a more fine-grained
2594 fashion with the property @code{Score.skipTypesetting}. When it is
2595 set, no typesetting is performed at all.
2597 This property is also used to control output to the MIDI file. Note that
2598 it skips all events, including tempo and instrument changes. You have
2601 @lilypond[quote,ragged-right,verbatim]
2604 \set Score.skipTypesetting = ##t
2606 \set Score.skipTypesetting = ##f
2611 In polyphonic music, @code{Score.skipTypesetting} will affect all
2612 voices and staves, saving even more time.
2614 @node Alternative output formats
2615 @subsection Alternative output formats
2617 @cindex scalable vector graphics output
2619 @cindex encapsulated postscript output
2622 The default output formats for the printed score are Portable
2623 Document Format (PDF) and PostScript (PS). Scalable Vector
2624 Graphics (SVG), Encapsulated PostScript (EPS) and Portable
2625 Network Graphics (PNG) output formats are also available through
2626 command line options, see
2627 @rprogram{Basic command line options for LilyPond}.
2630 @node Replacing the notation font
2631 @subsection Replacing the notation font
2633 Gonville is an alternative to the Feta font used in LilyPond and can
2636 @uref{http://www.chiark.greenend.org.uk/~sgtatham/gonville/ ,http://www.chiark.greenend.org.uk/~sgtatham/gonville/}
2639 Here are a few sample bars of music set in Gonville:
2641 @c NOTE: these images are a bit big, but that's important
2642 @c for the font comparison. -gp
2643 @sourceimage{Gonville_after,15cm,,}
2645 Here are a few sample bars of music set in LilyPond's Feta font:
2647 @sourceimage{Gonville_before,15cm,,}
2649 @subsubheading Installation Instructions for MacOS
2651 Download and extract the zip file. Copy the @code{lilyfonts}
2652 directory to @file{@var{SHARE_DIR}/lilypond/current}; for more
2653 information, see @rlearning{Other sources of information}. Rename the
2654 existing @code{fonts} directory to @code{fonts_orig} and the
2655 @code{lilyfonts} directory to @code{fonts}. To revert back to Feta,
2656 reverse the process.
2660 @rlearning{Other sources of information}.
2663 Gonville cannot be used to typeset @q{Ancient Music} notation and it is
2664 likely newer glyphs in later releases of LilyPond may not exist in the
2665 Gonville font family. Please refer to the author's website for more
2666 information on these and other specifics, including licensing of
2670 @node Creating MIDI output
2671 @section Creating MIDI output
2676 LilyPond can produce files that conform to the MIDI (Musical Instrument
2677 Digital Interface) standard and so allow for the checking of the music
2678 output aurally (with the help of an application or device that
2679 understands MIDI). Listening to MIDI output may also help in spotting
2680 errors such as notes that have been entered incorrectly or are missing
2681 accidentals and so on.
2683 MIDI files do not contain sound (like AAC, MP3 or Vorbis files) but
2684 require additional software to produce sound from them.
2687 * Supported notation for MIDI::
2688 * Unsupported notation for MIDI::
2690 * Controlling MIDI dynamics::
2691 * Using MIDI instruments::
2692 * Using repeats with MIDI::
2693 * MIDI channel mapping::
2694 * Context properties for MIDI effects::
2695 * Enhancing MIDI output::
2698 @cindex MIDI, Supported notation
2700 @node Supported notation for MIDI
2701 @subsection Supported notation for MIDI
2703 The following musical notation can be used with LilyPond's default
2704 capabilities to produce MIDI output;
2708 @item Chords entered as chord names
2709 @item Crescendi, decrescendi over multiple notes. The volume is altered
2710 linearly between the two extremes
2711 @item Dynamic markings from @code{ppppp} to @code{fffff}, including
2712 @code{mp}, @code{mf} and @code{sf}
2713 @item Microtones but @emph{not} microtonal chords. A MIDI player that
2714 supports pitch bending will also be required.
2717 @item Rhythms entered as note durations, including tuplets
2718 @item @q{Simple} articulations; staccato, staccatissimo, accent, marcato
2720 @item Tempo changes using the @code{\tempo} function
2722 @item Tremolos that are @emph{not} entered with a
2723 @q{@code{:}[@var{number}]} value
2726 Panning, balance, expression, reverb and chorus effects can also be
2727 controlled by setting context properties,
2728 see @ref{Context properties for MIDI effects}.
2730 When combined with the @file{articulate} script the following,
2731 additional musical notation can be output to MIDI;
2734 @item Appogiaturas. These are made to take half the value of the note
2735 following (without taking dots into account). For example;
2738 \appoggiatura c8 d2.
2742 The c will take the value of a crotchet.
2744 @item Ornaments (i.e. mordents, trills and turns et al.)
2745 @item Rallentando, accelerando, ritardando and a tempo
2746 @item Slurs, including phrasing slurs
2751 See @ref{Enhancing MIDI output}.
2753 @cindex MIDI, Unsupported notation
2755 @node Unsupported notation for MIDI
2756 @subsection Unsupported notation for MIDI
2758 The following items of musical notation cannot be output to MIDI;
2761 @item Articulations other than staccato, staccatissimo, accent, marcato
2763 @item Crescendi and decrescendi over a @emph{single} note
2767 @item Falls and doits
2768 @item Microtonal chords
2769 @item Rhythms entered as annotations, e.g. swing
2770 @item Tempo changes without @code{\tempo} (e.g. entered as annotations)
2771 @item Tremolos that @emph{are} entered with a @q{@code{:}[@var{number}]}
2776 @node The MIDI block
2777 @subsection The MIDI block
2781 To create a MIDI output file from a LilyPond input file, insert a
2782 @code{\midi} block, which can be empty, within the @code{\score} block;
2786 @var{@dots{} music @dots{}}
2792 @warning{ A @code{@bs{}score} block that, as well as the music, contains
2793 only a @code{@bs{}midi} block (i.e. @emph{without} the @code{@bs{}layout}
2794 block), will only produce MIDI output files. No notation will be
2797 The default output file extension (@code{.midi}) can be changed by using
2798 the @code{-dmidi-extension} option with the @code{lilypond} command:
2801 lilypond -dmidi-extension=mid MyFile.ly
2804 Alternatively, add the following Scheme expression before the start of
2805 either the @code{\book}, @code{\bookpart} or @code{\score} blocks. See
2806 @ref{File structure}.
2809 #(ly:set-option 'midi-extension "mid")
2814 @ref{File structure}.
2817 @file{scm/midi.scm}.
2820 There are fifteen MIDI channels available and one additional channel
2821 (#10) for drums. Staves are assigned to channels in sequence, so a
2822 score that contains more than fifteen staves will result in the extra
2823 staves sharing (but not overwriting) the same MIDI channel. This may be
2824 a problem if the sharing staves have conflicting, channel-based, MIDI
2825 properties -- such as different MIDI instruments -- set.
2828 @node Controlling MIDI dynamics
2829 @subsection Controlling MIDI dynamics
2831 It is possible to control the overall MIDI volume, the relative volume
2832 of dynamic markings and the relative volume of different instruments.
2834 Dynamic marks translate automatically into volume levels in the
2835 available MIDI volume range whereas crescendi and decrescendi vary the
2836 volume linearly between their two extremes. It is possible to control
2837 the relative volume of dynamic markings, and the overall volume levels
2838 of different instruments.
2841 * Dynamic marks in MIDI::
2842 * Setting MIDI volume::
2843 * Setting MIDI block properties::
2847 @cindex MIDI equalization
2848 @cindex MIDI dynamics
2849 @cindex Dynamics in MIDI
2852 @node Dynamic marks in MIDI
2853 @unnumberedsubsubsec Dynamic marks in MIDI
2855 Only the dynamic markings from @code{ppppp} to @code{fffff}, including
2856 @code{mp}, @code{mf} and @code{sf} have values assigned to them. This
2857 value is then applied to the value of the overall MIDI volume range to
2858 obtain the final volume included in the MIDI output for that particular
2859 dynamic marking. The default fractions range from 0.25 for
2860 @notation{ppppp} to 0.95 for @notation{fffff}. The complete set of
2861 dynamic marks and their associated fractions can be found in
2862 @file{scm/midi.scm}.
2866 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
2867 {creating-custom-dynamics-in-midi-output.ly}
2870 @file{ly/script-init.ly}
2871 @file{scm/midi.scm}.
2876 Internals Reference:
2877 @rinternals{Dynamic_performer}.
2880 @node Setting MIDI volume
2881 @unnumberedsubsubsec Setting MIDI volume
2883 The minimum and maximum overall volume of MIDI dynamic markings is
2884 controlled by setting the properties @code{midiMinimumVolume} and
2885 @code{midiMaximumVolume} at the @code{Score} level. These properties
2886 have an effect only at the start of a voice and on dynamic marks. The
2887 fraction corresponding to each dynamic mark is modified with this
2891 midiMinimumVolume + (midiMaximumVolume - midiMinimumVolume) * fraction
2894 In the following example the dynamic range of the overall MIDI
2895 volume is limited to the range @code{0.2} - @code{0.5}.
2901 \set Staff.midiInstrument = #"flute"
2902 @var{@dots{} music @dots{}}
2905 \set Staff.midiInstrument = #"clarinet"
2906 @var{@dots{} music @dots{}}
2912 midiMinimumVolume = #0.2
2913 midiMaximumVolume = #0.5
2919 Simple MIDI instrument equalization can be achieved by setting
2920 @code{midiMinimumVolume} and @code{midiMaximumVolume} properties within
2921 the @code{Staff} context.
2926 \set Staff.midiInstrument = #"flute"
2927 \set Staff.midiMinimumVolume = #0.7
2928 \set Staff.midiMaximumVolume = #0.9
2929 @var{@dots{} music @dots{}}
2935 For scores with multiple staves and multiple MIDI instruments, the
2936 relative volumes of each instrument can be set individually;
2942 \set Staff.midiInstrument = #"flute"
2943 \set Staff.midiMinimumVolume = #0.7
2944 \set Staff.midiMaximumVolume = #0.9
2945 @var{@dots{} music @dots{}}
2948 \set Staff.midiInstrument = #"clarinet"
2949 \set Staff.midiMinimumVolume = #0.3
2950 \set Staff.midiMaximumVolume = #0.6
2951 @var{@dots{} music @dots{}}
2958 In this example the volume of the clarinet is reduced relative to the
2959 volume of the flute.
2961 If these volumes properties are not set then LilyPond still applies a
2962 @q{small degree} of equalization to certain instruments. See
2963 @file{scm/midi.scm}.
2966 @file{scm/midi.scm}.
2972 Internals Reference:
2973 @rinternals{Dynamic_performer}.
2976 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
2977 {replacing-default-midi-instrument-equalization.ly}
2980 Changes in the MIDI volume take place only on starting a note, so
2981 crescendi and decrescendi cannot affect the volume of a single note.
2984 @node Setting MIDI block properties
2985 @unnumberedsubsubsec Setting MIDI block properties
2987 The @code{\midi} block can contain context rearrangements, new context
2988 definitions or code that sets the values of certain properties.
2992 @var{@dots{} music @dots{}}
2999 Here the tempo is set to 72 quarter-note beats per minute. The tempo
3000 mark in the @code{\midi} block will not appear in the printed score.
3001 Although any other @code{\tempo} indications specified within the
3002 @code{\score} block will also be reflected in the MIDI output.
3004 In a @code{\midi} block the @code{\tempo} command is setting properties
3005 during the interpretation of the music and in the context of output
3006 definitions; so it is interpreted @emph{as if} it were a context
3009 @cindex MIDI context definitions
3010 @cindex context definitions with MIDI
3012 Context definitions follow the same syntax as those in a @code{\layout}
3017 @var{@dots{} music @dots{}}
3021 \remove "Dynamic_performer"
3027 This example removes the effect of dynamics from the MIDI output. Note:
3028 LilyPond's translation modules used for sound are called @q{performers}.
3032 @rlearning{Other sources of information}.
3035 @ref{Expressive marks},
3039 @file{ly/performer-init.ly}.
3044 Internals Reference:
3045 @rinternals{Dynamic_performer}.
3048 Some MIDI players do not always correctly handle tempo changes in the
3051 Changes to the @code{midiInstrument}, as well as some MIDI options, at
3052 the @emph{beginning} of a staff may appear twice in the MIDI output.
3056 @node Using MIDI instruments
3057 @subsection Using MIDI instruments
3059 MIDI instruments are set using the @code{midiInstrument} property within
3060 a @code{Staff} context.
3065 \set Staff.midiInstrument = #"glockenspiel"
3066 @var{@dots{} music @dots{}}
3076 \new Staff \with @{midiInstrument = #"cello"@} @{
3077 @var{@dots{} music @dots{}}
3083 If the instrument name does not match any of the instruments listed in
3084 the @q{MIDI instruments} section, the @code{acoustic grand} instrument
3085 will be used instead. See @ref{MIDI instruments}.
3089 @rlearning{Other sources of information}.
3092 @ref{MIDI instruments},
3096 @file{scm/midi.scm}.
3099 Percussion instruments that are notated in a @code{DrumStaff}
3100 context will be output, correctly, to MIDI channel@tie{}10 but some
3101 pitched, percussion instruments like the xylophone, marimba, vibraphone
3102 or timpani, are treated as @qq{normal} instruments so the music for
3103 these should be entered in a @code{Staff} (not @code{DrumStaff}) context
3104 to obtain correct MIDI output. A full list of
3105 @code{channel 10 drum-kits} entries can be found in @file{scm/midi.scm}.
3106 See @rlearning{Other sources of information}.
3109 @node Using repeats with MIDI
3110 @subsection Using repeats with MIDI
3112 @cindex repeats in MIDI
3113 @cindex MIDI using repeats
3114 @funindex \unfoldRepeats
3116 Repeats can be represented in the MIDI output by applying the
3117 @code{\unfoldRepeats} command.
3122 \repeat tremolo 8 @{ c'32 e' @}
3123 \repeat percent 2 @{ c''8 d'' @}
3124 \repeat volta 2 @{ c'4 d' e' f' @}
3134 In order to restrict the effect of @code{\unfoldRepeats} to the MIDI
3135 output only, while also generating printable scores, it is necessary to
3136 make @emph{two} @code{\score} blocks; one for MIDI (with unfolded
3137 repeats) and one for the notation (with volta, tremolo, and percent
3142 @var{@dots{} music @dots{}}
3147 @var{@dots{} music @dots{}}
3153 When using multiple voices, each of the voices must contain completely
3154 unfolded repeats for correct MIDI output.
3161 @node MIDI channel mapping
3162 @subsection MIDI channel mapping
3164 @cindex MIDI Channels
3166 @funindex midiChannelMapping
3168 When generating a MIDI file from a score, LilyPond will automatically
3169 assign every note in the score to a MIDI channel, the one on which it
3170 should be played when it is sent to a MIDI device. A MIDI channel has
3171 a number of controls available to select, for example, the instrument
3172 to be used to play the notes on that channel, or to request the MIDI
3173 device to apply various effects to the sound produced on the channel.
3174 At all times, every control on a MIDI channel can have only a single
3175 value assigned to it (which can be modified, however, for example,
3176 to switch to another instrument in the middle of a score).
3178 The MIDI standard supports only 16 channels per MIDI device. This
3179 limit on the number of channels also limits the number of different
3180 instruments which can be played at the same time.
3182 LilyPond creates separate MIDI tracks for each staff, (or discrete
3183 instrument or voice, depending on the value of
3184 @code{Score.midiChannelMapping}), and also for each lyrics context.
3185 There is no limit to the number of tracks.
3187 To work around the limited number of MIDI channels, LilyPond supports
3188 a number of different modes for MIDI channel allocation, selected using
3189 the @code{Score.midiChannelMapping} context property. In each case,
3190 if more MIDI channels than the limit are required, the allocated
3191 channel numbers wrap around back to 0, possibly causing the incorrect
3192 assignment of instruments to some notes. This context property can be
3193 set to one of the following values:
3199 Allocate a separate MIDI channel to each staff in the score (this is
3200 the default). All notes in all voices contained within each staff will
3201 share the MIDI channel of their enclosing staff, and all are encoded
3202 in the same MIDI track.
3204 The limit of 16 channels is applied to the total number of staff and
3205 lyrics contexts, even though MIDI lyrics do not take up a MIDI channel.
3207 @item @code{'instrument}
3209 Allocate a separate MIDI channel to each distinct MIDI instrument
3210 specified in the score. This means that all the notes played with the
3211 same MIDI instrument will share the same MIDI channel (and track), even
3212 if the notes come from different voices or staves.
3214 In this case the lyrics contexts do not count towards the MIDI channel
3215 limit of 16 (as they will not be assigned to a MIDI instrument), so
3216 this setting may allow a better allocation of MIDI channels when the
3217 number of staves and lyrics contexts in a score exceeds 16.
3221 Allocate a separate MIDI channel to each voice in the score that has a
3222 unique name among the voices in its enclosing staff. Voices in
3223 different staves are always assigned separate MIDI channels, but any two
3224 voices contained within the same staff will share the same MIDI channel
3225 if they have the same name. Because @code{midiInstrument} and the
3226 several MIDI controls for effects are properties of the staff context,
3227 they cannot be set separately for each voice. The first voice will be
3228 played with the instrument and effects specified for the staff, and
3229 voices with a different name from the first will be assigned the default
3230 instrument and effects.
3232 Note: different instruments and/or effects can be assigned to several
3233 voices on the same staff by moving the @code{Staff_performer} from the
3234 @code{Staff} to the @code{Voice} context, and leaving
3235 @code{midiChannelMapping} to default to @code{'staff} or set to
3236 @code{'instrument}; see the snippet below.
3240 For example, the default MIDI channel mapping of a score can be changed
3241 to the @code{'instrument} setting as shown:
3249 midiChannelMapping = #'instrument
3256 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
3257 {changing-midi-output-to-one-channel-per-voice.ly}
3260 @node Context properties for MIDI effects
3261 @subsection Context properties for MIDI effects
3263 @cindex Effects in MIDI
3264 @cindex Pan position in MIDI
3265 @cindex Stereo balance in MIDI
3266 @cindex Balance in MIDI
3267 @cindex Expression in MIDI
3268 @cindex Reverb in MIDI
3269 @cindex Chorus level in MIDI
3270 @funindex midiPanPosition
3271 @funindex midiBalance
3272 @funindex midiExpression
3273 @funindex midiReverbLevel
3274 @funindex midiChorusLevel
3276 The following context properties can be used to apply various MIDI
3277 effects to notes played on the MIDI channel associated with the
3278 current staff, MIDI instrument or voice (depending on the value of the
3279 @code{Score.midiChannelMapping} context property and the context in
3280 which the @code{Staff_performer} is located; see
3281 @ref{MIDI channel mapping}).
3283 Changing these context properties will affect all notes played on the
3284 channel after the change, however some of the effects may even apply
3285 also to notes which are already playing (depending on the
3286 implementation of the MIDI output device).
3288 The following context properties are supported:
3292 @item @code{Staff.midiPanPosition}
3294 The pan position controls how the sound on a MIDI channel is
3295 distributed between left and right stereo outputs. The context
3296 property accepts a number between -1.0 (@code{#LEFT}) and 1.0
3297 (@code{#RIGHT}); the value -1.0 will put all sound power to the left
3298 stereo output (keeping the right output silent), the value 0.0
3299 (@code{#CENTER}) will distribute the sound evenly between the left and
3300 right stereo outputs, and the value 1.0 will move all sound to the
3301 right stereo output. Values between -1.0 and 1.0 can be used to obtain
3302 mixed distributions between left and right stereo outputs.
3304 @item @code{Staff.midiBalance}
3306 The stereo balance of a MIDI channel. Similarly to the pan position,
3307 this context property accepts a number between -1.0 (@code{#LEFT}) and
3308 1.0 (@code{#RIGHT}). It varies the relative volume sent to the two
3309 stereo speakers without affecting the distribution of the stereo
3312 @item @code{Staff.midiExpression}
3314 Expression level (as a fraction of the maximum available level) to
3315 apply to a MIDI channel. A MIDI device combines the MIDI channel's
3316 expression level with a voice's current dynamic level (controlled using
3317 constructs such as @code{\p} or @code{\ff}) to obtain the total volume
3318 of each note within the voice. The expression control could be used, for
3319 example, to implement crescendo or decrescendo effects over single
3320 sustained notes (not supported automatically by LilyPond).
3322 @c Issue 4059 contains an attached snippet which shows how this might
3323 @c be done, but this is too large and complex for the NR, even as a
3324 @c referenced snippet. It could be added to the LSR.
3326 The expression level ranges from 0.0 (no expression, meaning zero
3327 volume) to 1.0 (full expression).
3329 @item @code{Staff.midiReverbLevel}
3331 Reverb level (as a fraction of the maximum available level) to apply
3332 to a MIDI channel. This property accepts numbers between 0.0 (no
3333 reverb) and 1.0 (full effect).
3335 @item @code{Staff.midiChorusLevel}
3337 Chorus level (as a fraction of the maximum available level) to apply to
3338 a MIDI channel. This property accepts numbers between 0.0 (no chorus
3339 effect) and 1.0 (full effect).
3346 As MIDI files do not contain any actual audio data, changes in these
3347 context properties translate only to requests for changing MIDI channel
3348 controls in the outputted MIDI files. Whether a particular MIDI device
3349 (such as a software MIDI player) can actually handle any of these
3350 requests in a MIDI file is entirely up to the implementation of the
3351 device: a device may choose to ignore some or all of these requests.
3352 Also, how a MIDI device will interpret different values for these
3353 controls (generally, the MIDI standard fixes the behavior only at the
3354 endpoints of the value range available for each control), and whether a
3355 change in the value of a control will affect notes already playing on
3356 that MIDI channel or not, is also specific to the MIDI device
3359 When generating MIDI files, LilyPond will simply transform the
3360 fractional values within each range linearly into values in a
3361 corresponding (7-bit, or 14-bit for MIDI channel controls which support
3362 fine resolution) integer range (0-127 or 0-32767, respectively),
3363 rounding fractional values towards the nearest integer away from zero.
3364 The converted integer values are stored as-is in the generated MIDI
3365 file. Please consult the documentation of your MIDI device for
3366 information about how the device interprets these values.
3369 @node Enhancing MIDI output
3370 @subsection Enhancing MIDI output
3373 * The articulate script::
3376 The default MIDI output is basic but can be improved by setting MIDI
3377 instruments, @code{\midi} block properties and/or using the
3378 @file{articulate} script.
3380 @cindex instrument names
3381 @cindex MIDI, instruments
3382 @cindex articulate script
3383 @cindex articulate.ly
3384 @funindex Staff.midiInstrument
3387 @node The articulate script
3388 @unnumberedsubsubsec The @file{articulate} script
3390 To use the @file{articulate} script add the appropriate @code{\include}
3391 command at the top of the input file;
3394 \include "articulate.ly"
3397 The script creates MIDI output into appropriately @q{time-scaled} notes
3398 to match many articulation and tempo indications. Engraved output
3399 however, will also be altered to literally match the MIDI output.
3404 @var{@dots{} music @dots{}}
3410 The @code{\articulate} command enables abbreviatures (such as trills and
3411 turns) to be processed. A full list of supported items can be found in
3412 the script itself. See @file{ly/articulate.ly}.
3416 @rlearning{Other sources of information}.
3422 @file{ly/articulate.ly}.
3424 @warning{The @file{articulate} script may shorten chords, which might
3425 not be appropriate for some types of instrument, such as organ music.
3426 Notes that do not have any articulations attached to them may also be
3427 shortened; so to compensate for this, restrict the use of the
3428 @code{\articulate} function to shorter segments of music or modify the
3429 values of the variables defined in the @file{articulate} script to
3430 compenstate for the note-shortening behavior.}
3434 @node Extracting musical information
3435 @section Extracting musical information
3437 In addition to creating graphical output and MIDI, LilyPond can
3438 display musical information as text.
3441 * Displaying LilyPond notation::
3442 * Displaying scheme music expressions::
3443 * Saving music events to a file::
3446 @node Displaying LilyPond notation
3447 @subsection Displaying LilyPond notation
3449 @funindex \displayLilyMusic
3450 Displaying a music expression in LilyPond notation can be
3451 done with the music function @code{\displayLilyMusic}. To see the
3452 output, you will typically want to call LilyPond using the command
3457 \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
3464 @{ a,4 cis4 e4 fis4 g4 @}
3467 By default, LilyPond will print these messages to the console
3468 along with all the other LilyPond compilation messages. To split
3469 up these messages and save the results of @code{\displayLilyMusic},
3470 redirect the output to a file.
3473 lilypond file.ly >display.txt
3477 Note that Lilypond does not just display the music expression, but
3478 also interprets it (since @code{\displayLilyMusic} returns it in
3479 addition to displaying it). This is convenient since you can just
3480 insert @code{\displayLilyMusic} into existing music in order to get
3481 information about it. If you don't actually want Lilypond to
3482 interpret the displayed music as well as display it, use @code{\void}
3483 in order to have it ignored:
3487 \void \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
3492 @node Displaying scheme music expressions
3493 @subsection Displaying scheme music expressions
3495 See @rextend{Displaying music expressions}.
3498 @node Saving music events to a file
3499 @subsection Saving music events to a file
3501 Music events can be saved to a file on a per-staff basis by
3502 including a file in your main score.
3505 \include "event-listener.ly"
3508 This will create file(s) called @file{FILENAME-STAFFNAME.notes} or
3509 @file{FILENAME-unnamed-staff.notes} for each staff. Note that if
3510 you have multiple unnamed staves, the events for all staves will
3511 be mixed together in the same file. The output looks like this:
3514 0.000 note 57 4 p-c 2 12
3516 0.250 note 62 4 p-c 7 12
3517 0.500 note 66 8 p-c 9 12
3518 0.625 note 69 8 p-c 14 12
3523 The syntax is a tab-delimited line, with two fixed fields on each
3524 line followed by optional parameters.
3527 @var{time} @var{type} @var{@dots{}params@dots{}}
3530 This information can easily be read into other programs such as
3531 python scripts, and can be very useful for researchers wishing to
3532 perform musical analysis or playback experiments with LilyPond.
3537 Not all lilypond music events are supported by
3538 @file{event-listener.ly}. It is intended to be a well-crafted
3539 @qq{proof of concept}. If some events that you want to see are
3540 not included, copy @file{event-listener.ly} into your lilypond
3541 directory and modify the file so that it outputs the information