1 @c -*- coding: utf-8; mode: texinfo; -*-
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. For details, see the Contributors'
8 Guide, node Updating translation committishes..
13 @node General input and output
14 @chapter General input and output
16 This section deals with general LilyPond input and output issues,
17 rather than specific notation.
21 * Titles and headers::
22 * Working with input files::
23 * Controlling output::
25 * Extracting musical information::
30 @section Input structure
32 The main format of input for LilyPond are text files. By convention,
33 these files end with @file{.ly}.
36 * Structure of a score::
37 * Multiple scores in a book::
38 * Multiple output files from one input file::
44 @node Structure of a score
45 @subsection Structure of a score
49 A @code{\score} block must contain a single music expression
50 delimited by curly brackets:
58 @warning{There must be @strong{only one} outer music expression in
59 a @code{\score} block, and it @strong{must} be surrounded by
62 This single music expression may be of any size, and may contain
63 other music expressions to any complexity. All of these examples
64 are music expressions:
70 @lilypond[verbatim,quote]
77 @lilypond[verbatim,quote]
79 \new Staff { c'4 c' c' c' }
80 \new Staff { d'4 d' d' d' }
88 \new Staff @{ \flute @}
89 \new Staff @{ \oboe @}
92 \new Staff @{ \violinI @}
93 \new Staff @{ \violinII @}
99 Comments are one exception to this general rule. (For others see
100 @ref{File structure}.) Both single-line comments and comments
101 delimited by @code{%@{ .. %@}} may be placed anywhere within an
102 input file. They may be placed inside or outside a @code{\score}
103 block, and inside or outside the single music expression within a
106 Remember that even in a file containing only a @code{\score} block, it
107 is implicitly enclosed in a \book block. A \book block in a source
108 file produces at least one output file, and by default the name of the
109 output file produced is derived from the name of the input file, so
110 @file{fandangoforelephants.ly} will produce
111 @file{fandangoforelephants.pdf}.
113 (For more details about @code{\book} blocks, see
114 @ref{Multiple scores in a book},
115 @ref{Multiple output files from one input file} @ref{File structure}.)
119 @rlearning{Working on input files},
120 @rlearning{Music expressions explained},
121 @rlearning{Score is a (single) compound musical expression}.
124 @node Multiple scores in a book
125 @subsection Multiple scores in a book
128 @cindex movements, multiple
130 A document may contain multiple pieces of music and text. Examples
131 of these are an etude book, or an orchestral part with multiple
132 movements. Each movement is entered with a @code{\score} block,
140 and texts are entered with a @code{\markup} block,
150 All the movements and texts which appear in the same @file{.ly} file
151 will normally be typeset in the form of a single output file.
165 One important exception is within lilypond-book documents,
166 where you explicitly have to add a @code{\book} block, otherwise only
167 the first @code{\score} or @code{\markup} will appear in the output.
169 The header for each piece of music can be put inside the @code{\score}
170 block. The @code{piece} name from the header will be printed before
171 each movement. The title for the entire book can be put inside the
172 @code{\book}, but if it is not present, the @code{\header} which is at
173 the top of the file is inserted.
177 title = "Eight miniatures"
178 composer = "Igor Stravinsky"
182 \header @{ piece = "Romanze" @}
185 ..text of second verse..
188 ..text of third verse..
192 \header @{ piece = "Menuetto" @}
198 Pieces of music may be grouped into book parts using @code{\bookpart}
199 blocks. Book parts are separated by a page break, and can start with a
200 title, like the book itself, by specifying a @code{\header} block.
206 subtitle = "First part"
213 subtitle = "Second part"
220 @node Multiple output files from one input file
221 @subsection Multiple output files from one input file
223 If you want multiple output files from the same @file{.ly} file,
224 then you can add multiple @code{\book} blocks, where each
225 such \book block will result in a separate output file.
226 If you do not specify any @code{\book} block in the
227 input file, LilyPond will implicitly treat the whole
228 file as a single \book block, see
229 @ref{File structure}.
231 When producing multiple files from a single source file, Lilypond
232 ensures that none of the output files from any @code{\book} block
233 overwrites the output file produced by a preceding @code{\book} from
236 It does this by adding a suffix to the output name for each
237 @code{\book} which uses the default output file name derived from the
240 The default behaviour is to append a version-number suffix for each
241 name which may clash, so
246 \layout @{ @dots{} @}
250 \layout @{ @dots{} @}
254 \layout @{ @dots{} @}
258 in source file @file{eightminiatures.ly}
263 @file{eightminiatures.pdf},
265 @file{eightminiatures-1.pdf} and
267 @file{eightminiatures-2.pdf}.
270 @node Output file names
271 @subsection Output file names
273 @funindex \bookOutputSuffix
274 @funindex \bookOutputName
276 Lilypond provides facilities to allow you to control what file names
277 are used by the various back-ends when producing output files.
279 In the previous section, we saw how Lilypond prevents name-clashes when
280 producing several ouputs from a single source file. You also have the
281 ability to specify your own suffixes for each @code{\book} block, so
282 for example you can produce files called
283 @file{eightminiatures-Romanze.pdf}, @file{eightminiatures-Menuetto.pdf}
284 and @file{eightminiatures-Nocturne.pdf} by adding a
285 @code{\bookOutputSuffix} declaration inside each @code{\book} block.
289 \bookOutputSuffix "Romanze"
291 \layout @{ @dots{} @}
294 \bookOutputSuffix "Menuetto"
296 \layout @{ @dots{} @}
299 \bookOutputSuffix "Nocturne"
301 \layout @{ @dots{} @}
305 You can also specify a different output filename for @code{book} block,
306 by using @code{\bookOutputName} declarations
310 \bookOutputName "Romanze"
312 \layout @{ @dots{} @}
315 \bookOutputName "Menuetto"
317 \layout @{ @dots{} @}
320 \bookOutputName "Nocturne"
322 \layout @{ @dots{} @}
326 The file above will produce these output files:
332 @file{Menuetto.pdf} and
339 @subsection File structure
349 A @file{.ly} file may contain any number of toplevel expressions, where a
350 toplevel expression is one of the following:
354 An output definition, such as @code{\paper}, @code{\midi}, and
355 @code{\layout}. Such a definition at the toplevel changes the default
356 book-wide settings. If more than one such definition of
357 the same type is entered at the top level any definitions in the later
358 expressions have precedence.
361 A direct scheme expression, such as
362 @code{#(set-default-paper-size "a7" 'landscape)} or
363 @code{#(ly:set-option 'point-and-click #f)}.
366 A @code{\header} block. This sets the global header block. This
367 is the block containing the definitions for book-wide settings, like
368 composer, title, etc.
371 A @code{\score} block. This score will be collected with other
372 toplevel scores, and combined as a single @code{\book}.
373 This behavior can be changed by setting the variable
374 @code{toplevel-score-handler} at toplevel. The default handler is
375 defined in the init file @file{../scm/lily.scm}.
378 A @code{\book} block logically combines multiple movements
379 (i.e., multiple @code{\score} blocks) in one document. If there
380 are a number of @code{\score}s, one output file will be created
381 for each @code{\book} block, in which all corresponding movements
382 are concatenated. The only reason to explicitly specify
383 @code{\book} blocks in a @file{.ly} file is if you wish to create
384 multiple output files from a single input file. One exception is
385 within lilypond-book documents, where you explicitly have to add
386 a @code{\book} block if you want more than a single @code{\score}
387 or @code{\markup} in the same example. This behavior can be
388 changed by setting the variable @code{toplevel-book-handler} at
389 toplevel. The default handler is defined in the init file
390 @file{../scm/lily.scm}.
393 A @code{\bookpart} block. A book may be divided into several parts,
394 using @code{\bookpart} blocks, in order to ease the page breaking,
395 or to use different @code{\paper} settings in different parts.
398 A compound music expression, such as
403 This will add the piece in a @code{\score} and format it in a
404 single book together with all other toplevel @code{\score}s and music
405 expressions. In other words, a file containing only the above
406 music expression will be translated into
423 This behavior can be changed by setting the variable
424 @code{toplevel-music-handler} at toplevel. The default handler is
425 defined in the init file @file{../scm/lily.scm}.
428 A markup text, a verse for example
431 2. The first line verse two.
435 Markup texts are rendered above, between or below the scores or music
436 expressions, wherever they appear.
446 This can be used later on in the file by entering @code{\foo}. The
447 name of a variable should have alphabetic characters only; no
448 numbers, underscores or dashes.
452 The following example shows three things that may be entered at
457 % Don't justify the output
469 At any point in a file, any of the following lexical instructions can
473 @item @code{\version}
474 @item @code{\include}
475 @item @code{\sourcefilename}
476 @item @code{\sourcefileline}
478 A single-line comment, introduced by a leading @code{%} sign.
481 A multi-line comment delimited by @code{%@{ .. %@}}.
487 Whitespace between items in the input stream is generally ignored,
488 and may be freely omitted or extended to enhance readability.
489 However, whitespace should always be used in the following
490 circumstances to avoid errors:
493 @item Around every opening and closing curly bracket.
494 @item After every command or variable, i.e. every item that
495 begins with a @code{\} sign.
496 @item After every item that is to be interpreted as a Scheme
497 expression, i.e. every item that begins with a @code{#}@tie{}sign.
498 @item To separate all elements of a Scheme expression.
499 @item In @code{lyricmode} to separate all the terms in both
500 @code{\override} and @code{\set} commands. In particular, spaces
501 must be used around the dot and the equals sign in commands like
502 @code{\override Score . LyricText #'font-size = #5} and before and
503 after the entire command.
510 @rlearning{How LilyPond input files work}.
513 @node Titles and headers
514 @section Titles and headers
516 Almost all printed music includes a title and the composer's name;
517 some pieces include a lot more information.
520 * Creating titles headers and footers::
521 * Custom headers footers and titles::
522 * Creating footnotes::
523 * Reference to page numbers::
524 * Table of contents::
528 @node Creating titles headers and footers
529 @subsection Creating titles headers and footers
532 * Title blocks explained::
533 * Default layout of book and score title blocks::
534 * Default layout of headers and footers::
538 @node Title blocks explained
539 @unnumberedsubsubsec Title blocks explained
541 @c TODO: figure out how \bookpart titles work
543 There are two types of title blocks: the main title block that appears
544 above of the first @code{\score} of a book, and individual title
545 blocks that appear within each @code{\score} block. Text fields for
546 both types are entered using a @code{\header} block.
548 If the book only has a single score, the @code{\header} block may be
549 placed inside or outside of the @code{\score} block.
551 @warning{Remember when adding a @bs{}@code{header} block inside a
552 @bs{}@code{score} block, that the music expression must come before the
553 @bs{}@code{header} block.}
555 @lilypond[papersize=a5,quote,verbatim,noragged-right]
558 composer = "J. S. Bach."
562 \new Staff \relative g, {
565 \repeat unfold 2 { g16( d' b') a b d, b' d, } |
566 \repeat unfold 2 { g,16( e' c') b c e, c' e, } |
574 \new Staff \relative b {
578 <g, d' b'~>4 b'16 a( g fis) g( d e fis) g( a b c) |
579 d16( b g fis) g( e d c) b(c d e) fis( g a b) |
587 Text fields from the main title block of a book can be displayed in all
588 @code{\score} blocks, or manually suppressed:
590 @lilypond[papersize=a5,quote,verbatim,noragged-right]
593 print-all-headers = ##t
596 title = "DAS WOHLTEMPERIRTE CLAVIER"
598 % Do not display the tagline for this book
601 \markup { \vspace #1 }
605 \new Staff { \clef "bass" s1 }
608 title = "PRAELUDIUM I"
610 % Do not display the subtitle for this score
617 \new Staff { \clef "bass" s1 }
621 subsubtitle = "A 4 VOCI"
623 % Do not display the subtitle for this score
632 @ref{File structure},
633 @ref{Custom layout for title blocks}.
636 @node Default layout of book and score title blocks
637 @unnumberedsubsubsec Default layout of book and score title blocks
639 The layout and formatting of title blocks are controlled by two
640 @code{\paper} variables; @code{bookTitleMarkup} for the main
641 @code{\header} title block and @code{scoreTitleMarkup} for individual
642 @code{\header} blocks within a @code{\score}.
644 @lilypond[papersize=a6,quote,verbatim,noragged-right]
646 % The following fields are centered
647 dedication = "Dedication"
649 subtitle = "Subtitle"
650 subsubtitle = "Subsubtitle"
651 instrument = "Instrument"
653 % The following fields are left-aligned on the left side
657 % The following fields are right-aligned on the right side
658 composer = "Composer"
659 arranger = "Arranger"
665 % The following fields are placed at opposite ends of the same line
672 @c Is the bit about \null markups true? -mp
674 Text fields left unset in a @code{\header} block are replaced with
675 @code{\null} markups so that the space is not wasted.
677 The default settings for @code{scoreTitleMarkup} place the @code{piece}
678 and @code{opus} text fields at opposite ends of the same line.
682 Use the @code{breakbefore} variable inside a @code{\header} block
683 that is itself in a @code{\score} block, to make the top-level
684 @code{\header} block titles appear on the first page on their own, with
685 the music (defined in the @code{\score} block) starting on the next.
687 @lilypond[papersize=a8landscape,verbatim,noragged-right]
690 title = "This is my Title"
691 subtitle = "This is my Subtitle"
692 copyright = "This is the bottom of the first page"
695 \repeat unfold 4 { e'' e'' e'' e'' }
697 piece = "This is the Music"
706 @rlearning{How LilyPond input files work},
709 @ref{File structure}.
712 @file{ly/titling-init.ly}.
714 @node Default layout of headers and footers
715 @unnumberedsubsubsec Default layout of headers and footers
717 @emph{Headers} and @emph{footers} are lines of text appearing at
718 the top and bottom of pages, separate from the main text of a book.
719 They are controlled by the following @code{\paper} variables:
722 @item @code{oddHeaderMarkup}
723 @item @code{evenHeaderMarkup}
724 @item @code{oddFooterMarkup}
725 @item @code{evenFooterMarkup}
728 These markup variables can only access text fields from top-level
729 @code{\header} blocks (which apply to all scores in the book) and are
730 defined in @file{ly/titling-init.ly}. By default:
735 page numbers are automatically placed on the top far left (if even) or
736 top far right (if odd), starting from the second page.
739 the @code{instrument} text field is placed in the center of every
740 page, starting from the second page.
743 the @code{copyright} text is centered on the bottom of the first page.
746 the @code{tagline} is centered on the bottom of the last page, and below
747 the @code{copyright} text if there is only a single page.
751 @lilypond[papersize=a8landscape]
761 The default tagline can be changed by adding a @code{tagline} in the
762 top-level @code{\header} block.
764 @lilypond[papersize=a8landscape,verbatim]
767 tagline = "... music notation for Everyone"
777 To remove the @code{tagline} set the value to @code{##f}.
780 @node Custom headers footers and titles
781 @subsection Custom headers footers and titles
783 @c TODO: somewhere put a link to header spacing info
784 @c (you'll have to explain it more in NR 4).
787 * Custom text formatting for title blocks::
788 * Custom layout for title blocks::
789 * Custom layout for headers and footers::
793 @node Custom text formatting for title blocks
794 @unnumberedsubsubsec Custom text formatting for title blocks
796 Standard @code{\markup} commands can be used to customize any header,
797 footer and title text within the @code{\header} block.
799 @lilypond[quote,verbatim,noragged-right]
803 piece = \markup { \fontsize #4 \bold "PRAELUDIUM I" }
804 subtitle = \markup { \italic "(Excerpt)" }
811 @ref{Formatting text}.
814 @node Custom layout for title blocks
815 @unnumberedsubsubsec Custom layout for title blocks
817 @code{\markup} commands in the @code{\header} block are useful for
818 simple text formatting, but they do not allow precise control over the
819 placement of titles. To customize the placement of the text fields,
820 use either or both of the following @code{\paper} variables:
823 @item @code{bookTitleMarkup}
824 @item @code{scoreTitleMarkup}
827 These markup variables are discussed in
828 @ref{Default layout of book and score title blocks}.
830 The default settings for @code{scoreTitleMarkup} as defined in
831 @file{ly/titling-init.ly} are:
834 scoreTitleMarkup = \markup @{ \column @{
835 \on-the-fly #print-all-headers @{ \bookTitleMarkup \hspace #1 @}
837 \fromproperty #'header:piece
838 \fromproperty #'header:opus
844 This places the @code{piece} and @code{opus} text fields at opposite
845 ends of the same line:
847 @lilypond[quote,verbatim,noragged-right]
851 piece = "PRAELUDIUM I"
857 This example redefines @code{scoreTitleMarkup} so that the @code{piece}
858 text field is centered and in a large, bold font.
860 @lilypond[papersize=a5,quote,verbatim,noragged-right]
864 scoreTitleMarkup = \markup {
867 \fontsize #4 \bold \fromproperty #'header:piece
868 \fromproperty #'header:opus
872 \header { tagline = ##f }
876 piece = "PRAELUDIUM I"
883 Text fields normally reserved for the main title block can be included
884 in individual score title blocks with the @code{print-all-headers}
885 placed inside the @code{\paper} block. A disadvantage of using this
886 method is that the text fields that are intended specifically for the
887 top-level @code{\header} block need to be manually suppressed in every
888 @code{\score} block. See @ref{Title blocks explained}.
890 To avoid this, add the desired text field to the @code{scoreTitleMarkup}
891 definition. In the following example, the @code{composer} text field
892 (normally associated with @code{bookTitleMarkup}) is added to
893 @code{scoreTitleMarkup}, allowing each score to list a different
896 @lilypond[papersize=a5,quote,verbatim,noragged-right]
900 scoreTitleMarkup = \markup {
903 \fontsize #4 \bold \fromproperty #'header:piece
904 \fromproperty #'header:composer
908 \header { tagline = ##f }
913 composer = "Christian Petzold"
920 composer = "François Couperin"
926 It is also possible to create your own custom text fields, and refer to
927 them in the markup definition.
929 @lilypond[papersize=a5,quote,verbatim,noragged-right]
933 scoreTitleMarkup = \markup {
936 \override #`(direction . ,UP) {
938 \center-align \fontsize #-1 \bold
939 \fromproperty #'header:mycustomtext %% User-defined field
940 \center-align \fontsize #4 \bold
941 \fromproperty #'header:piece
944 \fromproperty #'header:opus
948 \header { tagline = ##f }
953 mycustomtext = "A 4 VOCI" %% User-defined field
962 @ref{Title blocks explained}.
965 @node Custom layout for headers and footers
966 @unnumberedsubsubsec Custom layout for headers and footers
968 @c can make-header and make-footer be removed from
969 @c paper-defaults-init.ly? -mp
971 @code{\markup} commands in the @code{\header} block are useful for
972 simple text formatting, but they do not allow precise control over the
973 placement of headers and footers. To customize the placement of
974 the text fields, use either or both of the following @code{\paper}
978 @item @code{oddHeaderMarkup}
979 @item @code{evenHeaderMarkup}
980 @item @code{oddFooterMarkup}
981 @item @code{evenFooterMarkup}
984 The following example centers page numbers at the bottom of every
985 page. First, the default settings for @code{oddHeaderMarkup} and
986 @code{evenHeaderMarkup} are removed by defining each as a @emph{null}
987 markup. Then, @code{oddFooterMarkup} is redefined with the page
988 number centered. Finally, @code{evenFooterMarkup} is given the
989 same layout by defining it as @code{\oddFooterMarkup}:
991 @lilypond[papersize=a8,quote,verbatim,noragged-right]
994 print-page-number = ##t
995 print-first-page-number = ##t
996 oddHeaderMarkup = \markup \null
997 evenHeaderMarkup = \markup \null
998 oddFooterMarkup = \markup {
1000 \on-the-fly #print-page-number-check-first
1001 \fromproperty #'page:page-number-string
1004 evenFooterMarkup = \oddFooterMarkup
1007 \new Staff { s1 \break s1 \break s1 }
1014 @ref{Title blocks explained},
1015 @ref{Default layout of book and score title blocks}.
1017 @node Creating footnotes
1018 @subsection Creating footnotes
1020 There are two types of footnotes that can be created; automatic
1021 footnotes and manual footnotes.
1024 * Footnotes overview::
1025 * Automatic footnotes::
1026 * Manual footnotes::
1029 @node Footnotes overview
1030 @unnumberedsubsubsec Footnotes overview
1032 Automatic footnotes create incrementing, numerical indicators and
1033 manual footnotes allow a custom indicator to be created instead. All
1034 grobs, top-level @code{\markup} and chorded notes can be annotated.
1036 The order in which each grob is drawn determines the order in which each
1037 indicator and so footnotes are created during compilation.
1040 @node Automatic footnotes
1041 @unnumberedsubsubsec Automatic footnotes
1043 Of the two commands used to create automatic footnotes, use
1044 @code{\autoFootnoteGrob} for individual grobs (i.e. note heads, stems,
1045 slurs, dynamics and @code{\markup} when using @code{TextScripts});
1046 and @code{\autoFootnote} for annotating chorded notes.
1048 Both commands take three arguments; the @var{Layout Object} to be
1049 annotated, the @var{(x . y)} position of the indicator and a
1050 @code{\markup} that will appear in the footnote at the bottom of the
1053 The command @code{\autoFootnoteGrob} must come @emph{before} the grob
1054 that the footnote is being attached to:
1056 @lilypond[verbatim,quote,ragged-right,papersize=a8]
1058 \header { tagline = ##f }
1060 \autoFootnoteGrob #'NoteHead #'(0.5 . -2)
1061 \markup { The first note }
1063 \autoFootnoteGrob #'NoteHead #'(0.5 . 1)
1064 \markup { The third note }
1070 To annotate chorded notes, the @code{\autoFootnote} must come
1071 @emph{after} the note to which the footnote is being attached as a
1074 @lilypond[verbatim,quote,ragged-right,papersize=a8]
1076 \header { tagline = ##f }
1079 c-\autoFootnote #'(1 . -1.25) "Here is a C"
1080 es-\autoFootnote #'(2 . -0.25) \markup { \italic "An E-flat" }
1081 g-\autoFootnote #'(2 . 3) \markup { \bold "This is a G" }
1087 @warning {When footnotes have the same vertical position, the footnotes
1088 are printed in order of descendancy; the higher the footnote, the
1089 higher up in the list.}
1091 Here are some examples of automatically footnoted grobs, also showing
1092 the relative position of the footnotes to the tagline and copyright.
1094 @lilypond[verbatim,quote,ragged-right,papersize=a8]
1096 \header { copyright = \markup { "Copyright 1970" } }
1098 \autoFootnoteGrob #'DynamicText #'(-3 . 0)
1099 \markup { \bold Forte }
1101 \autoFootnoteGrob #'Slur #'(0 . 1.5)
1105 \autoFootnoteGrob #'Beam #'(0 . -2)
1109 \autoFootnoteGrob #'Stem #'(1 . -1)
1110 \markup { \teeny { This is a stem } }
1113 \autoFootnoteGrob #'AccidentalCautionary #'(0 . 0.5)
1114 \markup \italic { A cautionary accidental }
1116 \autoFootnoteGrob #'TextScript #'(0.5 . -0.5)
1117 \markup \italic { Slow Down }
1123 For top-level @code{\markup}, the @code{\auto-footnote} command is
1126 @lilypond[verbatim,quote,ragged-right,papersize=a8]
1128 \header { tagline = ##f }
1129 \markup { \auto-footnote "A simple tune" \italic "By me" }
1137 @node Manual footnotes
1138 @unnumberedsubsubsec Manual footnotes
1141 @funindex \footnoteGrob
1142 @cindex footnotes, manual
1144 There are two commands used to create manual footnotes; @code{\footnote}
1145 for top-level @code{\markup} and chorded notes; and @code{\footnoteGrob}
1146 for individual grobs (and @code{\markup} when using @code{TextScripts}).
1148 When annotating grobs, the @code{\footnote} command takes four
1149 arguments; the @var{Layout Object} to be annotated, the @var{(x . y)}
1150 position of the indicator and two @code{\markup} commands; the first is
1151 the indicator attached to the note or grob and the second is the
1152 footnote at the bottom of the page.
1154 The command @code{\footnoteGrob} must come @emph{after} the grob that
1155 the footnote is annotating and attached as a @code{TextScript}:
1157 @lilypond[verbatim,quote,ragged-right,papersize=a8]
1159 \header { tagline = ##f }
1161 a'4-\footnoteGrob #'NoteHead #'(0.5 . -2)
1162 "1" \markup { \italic "1. The first note" }
1164 e-\footnoteGrob #'NoteHead #'(0.5 . 1)
1165 \markup { \bold "2" } "2. The second note"
1167 d\p-\footnoteGrob #'DynamicText #'(0.5 . -1) "3" "3. Piano"
1172 To annotate chorded notes, the @code{\footnote} must come @emph{after}
1173 the note that the footnote is annotating and attached as a
1176 @lilypond[verbatim,quote,ragged-right,papersize=a8]
1178 \header { tagline = ##f }
1181 c-\footnote #'(1 . -1.25) "1" "1. C"
1182 es-\footnote #'(2 . -0.25)
1183 \markup { \bold "b" } "b. E-flat"
1184 g-\footnote #'(2 . 3) "3" \markup { \italic "iii. G" }
1190 @warning {When footnotes have the same vertical position, the footnotes
1191 are printed in order of descendancy; the higher the footnote, the
1192 higher up in the list.}
1194 Here are some examples of manually footnoted grobs, also showing
1195 the relative position of the footnotes to the tagline and copyright
1197 @lilypond[verbatim,quote,ragged-right,papersize=a8]
1199 \header { tagline = ##f }
1201 \footnoteGrob #'DynamicText #'(-3 . 0)
1202 \markup { \teeny 1 }
1203 \markup { 1. \bold Forte }
1205 \footnoteGrob #'Slur #'(0 . 1.5)
1206 \markup { \teeny b }
1207 \markup { b. A slur }
1210 \footnoteGrob #'Beam #'(0 . -2)
1211 \markup { \teeny 3 }
1215 \footnoteGrob #'Stem #'(1 . -1)
1217 \markup { \bold 4. { This is a stem } }
1220 \footnoteGrob #'AccidentalCautionary #'(0 . 0.5)
1221 \markup \concat \teeny { "sharp (v)" }
1222 \markup \italic { v. A cautionary accidental }
1224 \footnoteGrob #'TextScript #'(0.5 . -0.5)
1225 \markup \concat \teeny { "a" }
1226 \markup \italic { a. Slow Down }
1230 \footnoteGrob #'BreathingSign #'(1.5 . -0.25)
1231 \markup { \teeny \musicglyph #"rests.4" }
1237 To manually footnote a top-level @code{\markup}:
1239 @lilypond[verbatim,quote,ragged-right,papersize=a8]
1241 \header { tagline = ##f }
1242 \markup { "A simple tune" \footnote "*" \italic "* By me" }
1251 @rlearning{Objects and interfaces}.
1258 @ref{Titles and headers}.
1260 Internals Reference:
1261 @rinternals{FootnoteEvent},
1262 @rinternals{FootnoteItem},
1263 @rinternals{FootnoteSpanner},
1264 @rinternals{Footnote_engraver}.
1267 Multiple footnotes for the same page can only be stacked, one on top of
1268 the other, and cannot be printed on the same line. Footnotes cannot be
1269 attached to @code{MultiMeasureRests} and may collide with @code{Staff},
1270 @code{\markup} objects and other @code{footnote} annotations. When
1271 using any manual @code{footnote} command a @code{\paper} block
1272 containing @code{footnote-auto-number = ##f} is required.
1275 @node Reference to page numbers
1276 @subsection Reference to page numbers
1278 A particular place of a score can be marked using the @code{\label}
1279 command, either at top-level or inside music. This label can then be
1280 referred to in a markup, to get the number of the page where the marked
1281 point is placed, using the @code{\page-ref} markup command.
1284 \header { tagline = ##f }
1290 \pageBreak \mark A \label #'markA
1294 \markup { The first score begins on page \page-ref #'firstScore "0" "?" }
1295 \markup { Mark A is on page \page-ref #'markA "0" "?" }
1299 The @code{\page-ref} markup command takes three arguments:
1301 @item the label, a scheme symbol, eg. @code{#'firstScore};
1302 @item a markup that will be used as a gauge to estimate the dimensions
1304 @item a markup that will be used in place of the page number if the label
1308 The reason why a gauge is needed is that, at the time markups are
1309 interpreted, the page breaking has not yet occurred, so the page numbers
1310 are not yet known. To work around this issue, the actual markup
1311 interpretation is delayed to a later time; however, the dimensions of
1312 the markup have to be known before, so a gauge is used to decide these
1313 dimensions. If the book has between 10 and 99 pages, it may be "00",
1314 ie. a two digit number.
1325 @node Table of contents
1326 @subsection Table of contents
1327 A table of contents is included using the @code{\markuplist \table-of-contents}
1328 command. The elements which should appear in the table of contents are
1329 entered with the @code{\tocItem} command, which may be used either at
1330 top-level, or inside a music expression.
1333 \markuplist \table-of-contents
1336 \tocItem \markup "First score"
1340 \tocItem \markup "Some particular point in the first score"
1345 \tocItem \markup "Second score"
1353 The markups which are used to format the table of contents are defined
1354 in the @code{\paper} block. The default ones are @code{tocTitleMarkup},
1355 for formatting the title of the table, and @code{tocItemMarkup}, for
1356 formatting the toc elements, composed of the element title and page
1357 number. These variables may be changed by the user:
1361 %% Translate the toc title into French:
1362 tocTitleMarkup = \markup \huge \column {
1363 \fill-line { \null "Table des matières" \null }
1366 %% use larger font size
1367 tocItemMarkup = \markup \large \fill-line {
1368 \fromproperty #'toc:text \fromproperty #'toc:page
1373 Note how the toc element text and page number are referred to in
1374 the @code{tocItemMarkup} definition.
1376 New commands and markups may also be defined to build more elaborated
1379 @item first, define a new markup variable in the @code{\paper} block
1380 @item then, define a music function which aims at adding a toc element
1381 using this markup paper variable.
1384 In the following example, a new style is defined for entering act names
1385 in the table of contents of an opera:
1389 tocActMarkup = \markup \large \column {
1391 \fill-line { \null \italic \fromproperty #'toc:text \null }
1397 #(define-music-function (parser location text) (markup?)
1398 (add-toc-item! 'tocActMarkup text))
1401 @lilypond[line-width=11.0\cm]
1402 \header { tagline = ##f }
1404 tocActMarkup = \markup \large \column {
1406 \fill-line { \null \italic \fromproperty #'toc:text \null }
1412 #(define-music-function (parser location text) (markup?)
1413 (add-toc-item! 'tocActMarkup text))
1416 \markuplist \table-of-contents
1417 \tocAct \markup { Atto Primo }
1418 \tocItem \markup { Coro. Viva il nostro Alcide }
1419 \tocItem \markup { Cesare. Presti omai l'Egizzia terra }
1420 \tocAct \markup { Atto Secondo }
1421 \tocItem \markup { Sinfonia }
1422 \tocItem \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
1427 Dots can be added to fill the line between an item and its page number:
1429 @lilypond[verbatim,quote]
1430 \header { tagline = ##f }
1432 tocItemMarkup = \tocItemWithDotsMarkup
1436 \markuplist \table-of-contents
1437 \tocItem \markup { Allegro }
1438 \tocItem \markup { Largo }
1445 Init files: @file{../ly/toc-init.ly}.
1449 @funindex \table-of-contents
1450 @code{\table-of-contents},
1456 @node Working with input files
1457 @section Working with input files
1460 * Including LilyPond files::
1461 * Different editions from one source::
1462 * Special characters::
1466 @node Including LilyPond files
1467 @subsection Including LilyPond files
1470 @cindex including files
1472 A large project may be split up into separate files. To refer to
1476 \include "otherfile.ly"
1479 The line @code{\include "otherfile.ly"} is equivalent to pasting the
1480 contents of @file{otherfile.ly} into the current file at the place
1481 where the @code{\include} appears. For example, in a large
1482 project you might write separate files for each instrument part
1483 and create a @qq{full score} file which brings together the
1484 individual instrument files. Normally the included file will
1485 define a number of variables which then become available
1486 for use in the full score file. Tagged sections can be
1487 marked in included files to assist in making them usable in
1488 different places in a score, see @ref{Different editions from
1491 Files in the current working directory may be referenced by
1492 specifying just the file name after the @code{\include} command.
1493 Files in other locations may be included by giving either a full
1494 path reference or a relative path reference (but use the UNIX
1495 forward slash, /, rather than the DOS/Windows back slash, \, as the
1496 directory separator.) For example, if @file{stuff.ly} is located
1497 one directory higher than the current working directory, use
1500 \include "../stuff.ly"
1504 or if the included orchestral parts files are all located in a
1505 subdirectory called @file{parts} within the current directory, use
1508 \include "parts/VI.ly"
1509 \include "parts/VII.ly"
1513 Files which are to be included can also contain @code{\include}
1514 statements of their own. By default, these second-level
1515 @code{\include} statements are not interpreted until they have
1516 been brought into the main file, so the file names they specify
1517 must all be relative to the directory containing the main file,
1518 not the directory containing the included file. However,
1519 this behavior can be changed by passing the option
1520 @option{-drelative-includes} option at the command line
1521 (or by adding @code{#(ly:set-option 'relative-includes #t)}
1522 at the top of the main input file). With @code{relative-includes}
1523 set, the path for each @code{\include} command will be taken
1524 relative to the file containing that command. This behavior is
1525 recommended and it will become the default behavior in a future
1526 version of lilypond.
1528 Files can also be included from a directory in a search path
1529 specified as an option when invoking LilyPond from the command
1530 line. The included files are then specified using just their
1531 file name. For example, to compile @file{main.ly} which includes
1532 files located in a subdirectory called @file{parts} by this method,
1533 cd to the directory containing @file{main.ly} and enter
1536 lilypond --include=parts main.ly
1539 and in main.ly write
1547 Files which are to be included in many scores may be placed in
1548 the LilyPond directory @file{../ly}. (The location of this
1549 directory is installation-dependent - see
1550 @rlearning{Other sources of information}). These files can then
1551 be included simply by naming them on an @code{\include} statement.
1552 This is how the language-dependent files like @file{english.ly} are
1555 LilyPond includes a number of files by default when you start
1556 the program. These includes are not apparent to the user, but the
1557 files may be identified by running @code{lilypond --verbose} from
1558 the command line. This will display a list of paths and files that
1559 LilyPond uses, along with much other information. Alternatively,
1560 the more important of these files are discussed in
1561 @rlearning{Other sources of information}. These files may be
1562 edited, but changes to them will be lost on installing a new
1563 version of LilyPond.
1565 Some simple examples of using @code{\include} are shown in
1566 @rlearning{Scores and parts}.
1570 @rlearning{Other sources of information},
1571 @rlearning{Scores and parts}.
1574 If an included file is given a name which is the same as one in
1575 LilyPond's installation files, LilyPond's file from the
1576 installation files takes precedence.
1579 @node Different editions from one source
1580 @subsection Different editions from one source
1582 Several methods can be used to generate different versions of a score
1583 from the same music source. Variables are perhaps the most useful for
1584 combining lengthy sections of music and/or annotation. Tags are more
1585 useful for selecting one section from several alternative shorter
1586 sections of music, and can also be used for splicing pieces of music
1587 together at different points.
1589 Whichever method is used, separating the notation from the structure of
1590 the score will make it easier to change the structure while leaving the
1596 * Using global settings::
1599 @node Using variables
1600 @unnumberedsubsubsec Using variables
1602 @cindex variables, use of
1604 If sections of the music are defined in variables they can be
1605 reused in different parts of the score, see @rlearning{Organizing
1606 pieces with variables}. For example, an @notation{a cappella}
1607 vocal score frequently includes a piano reduction of the parts
1608 for rehearsal purposes which is identical to the vocal music, so
1609 the music need be entered only once. Music from two variables
1610 may be combined on one staff, see @ref{Automatic part combining}.
1613 @lilypond[verbatim,quote]
1614 sopranoMusic = \relative c'' { a4 b c b8( a) }
1615 altoMusic = \relative g' { e4 e e f }
1616 tenorMusic = \relative c' { c4 b e d8( c) }
1617 bassMusic = \relative c' { a4 gis a d, }
1618 allLyrics = \lyricmode {King of glo -- ry }
1620 \new Staff = "Soprano" \sopranoMusic
1621 \new Lyrics \allLyrics
1622 \new Staff = "Alto" \altoMusic
1623 \new Lyrics \allLyrics
1624 \new Staff = "Tenor" {
1628 \new Lyrics \allLyrics
1629 \new Staff = "Bass" {
1633 \new Lyrics \allLyrics
1636 \set Staff.printPartCombineTexts = ##f
1642 \set Staff.printPartCombineTexts = ##f
1652 Separate scores showing just the vocal parts or just the piano
1653 part can be produced by changing just the structural statements,
1654 leaving the musical notation unchanged.
1656 For lengthy scores, the variable definitions may be placed in
1657 separate files which are then included, see @ref{Including
1661 @unnumberedsubsubsec Using tags
1664 @funindex \keepWithTag
1665 @funindex \removeWithTag
1666 @funindex \pushToTag
1667 @funindex \appendToTag
1669 @cindex keep tagged music
1670 @cindex remove tagged music
1671 @cindex splice into tagged music
1673 The @code{\tag #'@var{partA}} command marks a music expression
1674 with the name @var{partA}.
1675 Expressions tagged in this way can be selected or filtered out by
1676 name later, using either @code{\keepWithTag #'@var{name}} or
1677 @code{\removeWithTag #'@var{name}}. The result of applying these filters
1678 to tagged music is as follows:
1679 @multitable @columnfractions .5 .5
1683 Tagged music preceded by @code{\keepWithTag #'@var{name}}
1684 @tab Untagged music and music tagged with @var{name} is included;
1685 music tagged with any other tag name is excluded.
1687 Tagged music preceded by @code{\removeWithTag #'@var{name}}
1688 @tab Untagged music and music tagged with any tag name other than
1689 @var{name} is included; music tagged with @var{name} is
1692 Tagged music not preceded by either @code{\keepWithTag} or
1693 @code{\removeWithTag}
1694 @tab All tagged and untagged music is included.
1697 The arguments of the @code{\tag}, @code{\keepWithTag} and
1698 @code{\removeWithTag} commands should be a symbol
1699 (such as @code{#'score} or @code{#'part}), followed
1700 by a music expression.
1702 In the following example, we see two versions of a piece of music,
1703 one showing trills with the usual notation, and one with trills
1704 explicitly expanded:
1706 @lilypond[verbatim,quote]
1707 music = \relative g' {
1709 \tag #'trills { d8.\trill }
1710 \tag #'expand { \repeat unfold 3 { e32 d } }
1715 \keepWithTag #'trills \music
1718 \keepWithTag #'expand \music
1723 Alternatively, it is sometimes easier to exclude sections of music:
1725 @lilypond[verbatim,quote]
1726 music = \relative g' {
1728 \tag #'trills { d8.\trill }
1729 \tag #'expand {\repeat unfold 3 { e32 d } }
1734 \removeWithTag #'expand
1738 \removeWithTag #'trills
1743 Tagged filtering can be applied to articulations, texts, etc. by
1747 -\tag #'@var{your-tag}
1750 to an articulation. For example, this would define a note with a
1751 conditional fingering indication and a note with a conditional
1756 c1-\tag #'warn ^"Watch!"
1759 Multiple tags may be placed on expressions with multiple
1760 @code{\tag} entries:
1762 @lilypond[quote,verbatim]
1763 music = \relative c'' {
1764 \tag #'a \tag #'both { a4 a a a }
1765 \tag #'b \tag #'both { b4 b b b }
1768 \keepWithTag #'a \music
1769 \keepWithTag #'b \music
1770 \keepWithTag #'both \music
1774 Multiple @code{\removeWithTag} filters may be applied to a single
1775 music expression to remove several differently named tagged sections:
1777 @lilypond[verbatim,quote]
1778 music = \relative c'' {
1779 \tag #'A { a4 a a a }
1780 \tag #'B { b4 b b b }
1781 \tag #'C { c4 c c c }
1782 \tag #'D { d4 d d d }
1791 Two or more @code{\keepWithTag} filters applied to a single music
1792 expression will cause @emph{all} tagged sections to be removed, as
1793 the first filter will remove all tagged sections except the one
1794 named, and the second filter will remove even that tagged section.
1796 Sometimes you want to splice some music at a particular place in an
1797 existing music expression. You can use @code{\pushToTag} and
1798 @code{\appendToTag} for adding material at the front or end of the
1799 @code{elements} of an existing music construct. Not every music
1800 construct has @code{elements}, but sequential and simultaneous music are
1803 @lilypond[verbatim,quote]
1804 test = { \tag #'here { \tag #'here <<c''>> } }
1807 \pushToTag #'here c'
1808 \pushToTag #'here e'
1809 \pushToTag #'here g' \test
1810 \appendToTag #'here c'
1811 \appendToTag #'here e'
1812 \appendToTag #'here g' \test
1816 Both commands get a tag, the material to splice in at every occurence of
1817 the tag, and the tagged expression. The commands make sure to
1818 copy everything that they change so that the original @code{\test}
1819 retains its meaning.
1823 @rlearning{Organizing pieces with variables}.
1826 @ref{Automatic part combining},
1827 @ref{Including LilyPond files}.
1831 @c This warning is more general than this placement implies.
1832 @c Rests are not merged whether or not they come from tagged sections.
1833 @c Should be deleted? -td
1837 Multiple rests are not merged if you create a score with more
1838 than one tagged section at the same place.
1842 @node Using global settings
1843 @unnumberedsubsubsec Using global settings
1845 @cindex include-settings
1847 Global settings can be included from a separate file:
1850 lilypond -dinclude-settings=MY_SETTINGS.ly MY_SCORE.ly
1853 Groups of settings such as page size, font or type face can be stored
1854 in separate files. This allows different editions from the same score
1855 as well as standard settings to be applied to many scores, simply by
1856 specifying the proper settings file.
1858 This technique also works well with the use of style sheets, as
1859 discussed in @rlearning{Style sheets}.
1863 @rlearning{Organizing pieces with variables},
1864 @rlearning{Style sheets}.
1867 @ref{Including LilyPond files}.
1869 @node Special characters
1870 @subsection Special characters
1872 @cindex special characters
1873 @cindex non-ASCII characters
1883 @unnumberedsubsubsec Text encoding
1887 LilyPond uses the character repertoire defined by the Unicode
1888 consortium and ISO/IEC 10646. This defines a unique name and
1889 code point for the character sets used in virtually all modern
1890 languages and many others too. Unicode can be implemented using
1891 several different encodings. LilyPond uses the UTF-8 encoding
1892 (UTF stands for Unicode Transformation Format) which represents
1893 all common Latin characters in one byte, and represents other
1894 characters using a variable length format of up to four bytes.
1896 The actual appearance of the characters is determined by the
1897 glyphs defined in the particular fonts available - a font defines
1898 the mapping of a subset of the Unicode code points to glyphs.
1899 LilyPond uses the Pango library to layout and render multi-lingual
1902 LilyPond does not perform any input-encoding conversions. This
1903 means that any text, be it title, lyric text, or musical
1904 instruction containing non-ASCII characters, must be encoded in
1905 UTF-8. The easiest way to enter such text is by using a
1906 Unicode-aware editor and saving the file with UTF-8 encoding. Most
1907 popular modern editors have UTF-8 support, for example, vim, Emacs,
1908 jEdit, and GEdit do. All MS Windows systems later than NT use
1909 Unicode as their native character encoding, so even Notepad can
1910 edit and save a file in UTF-8 format. A more functional
1911 alternative for Windows is BabelPad.
1913 If a LilyPond input file containing a non-ASCII character is not
1914 saved in UTF-8 format the error message
1917 FT_Get_Glyph_Name () error: invalid argument
1922 Here is an example showing Cyrillic, Hebrew and Portuguese
1926 %c No verbatim here as the code does not display correctly in PDF
1928 bulgarian = \lyricmode {
1929 Жълтата дюля беше щастлива, че пухът, който цъфна, замръзна като гьон.
1933 hebrew = \lyricmode {
1934 זה כיף סתם לשמוע איך תנצח קרפד עץ טוב בגן.
1938 portuguese = \lyricmode {
1939 à vo -- cê uma can -- ção legal
1945 \addlyrics { \bulgarian }
1946 \addlyrics { \hebrew }
1947 \addlyrics { \portuguese }
1952 @unnumberedsubsubsec Unicode
1956 To enter a single character for which the Unicode code point is
1957 known but which is not available in the editor being used, use
1958 either @code{\char ##xhhhh} or @code{\char #dddd} within a
1959 @code{\markup} block, where @code{hhhh} is the hexadecimal code for
1960 the character required and @code{dddd} is the corresponding decimal
1961 value. Leading zeroes may be omitted, but it is usual to specify
1962 all four characters in the hexadecimal representation. (Note that
1963 the UTF-8 encoding of the code point should @emph{not} be used
1964 after @code{\char}, as UTF-8 encodings contain extra bits indicating
1965 the number of octets.) Unicode code charts and a character name
1966 index giving the code point in hexadecimal for any character can be
1967 found on the Unicode Consortium website,
1968 @uref{http://www.unicode.org/}.
1970 For example, @code{\char ##x03BE} and @code{\char #958} would both
1971 enter the Unicode U+03BE character, which has the Unicode name
1972 @qq{Greek Small Letter Xi}.
1974 Any Unicode code point may be entered in this way and if all special
1975 characters are entered in this format it is not necessary to save
1976 the input file in UTF-8 format. Of course, a font containing all
1977 such encoded characters must be installed and available to LilyPond.
1979 The following example shows Unicode hexadecimal values being entered
1980 in four places -- in a rehearsal mark, as articulation text, in
1981 lyrics and as stand-alone text below the score:
1983 @lilypond[quote,verbatim]
1986 c1 \mark \markup { \char ##x03EE }
1987 c1_\markup { \tiny { \char ##x03B1 " to " \char ##x03C9 } }
1989 \addlyrics { O \markup { \concat { Ph \char ##x0153 be! } } }
1991 \markup { "Copyright 2008--2012" \char ##x00A9 }
1994 @cindex copyright sign
1996 To enter the copyright sign in the copyright notice use:
2000 copyright = \markup @{ \char ##x00A9 "2008" @}
2006 @unnumberedsubsubsec ASCII aliases
2008 A list of ASCII aliases for special characters can be included:
2010 @lilypond[quote,verbatim]
2012 #(include-special-characters)
2015 \markup "&flqq; – &OE;uvre incomplète… &frqq;"
2018 \new Staff { \repeat unfold 9 a'4 }
2020 This is al -- so wor -- kin'~in ly -- rics: –_&OE;…
2025 "The replacement can be disabled:"
2026 "– &OE; …"
2027 \override #'(replacement-alist . ()) "– &OE; …"
2031 You can also make your own aliases, either globally:
2033 @lilypond[quote,verbatim]
2035 #(add-text-replacements!
2036 '(("100" . "hundred")
2037 ("dpi" . "dots per inch")))
2039 \markup "A 100 dpi."
2044 @lilypond[quote,verbatim]
2045 \markup \replace #'(("100" . "hundred")
2046 ("dpi" . "dots per inch")) "A 100 dpi."
2051 @ref{List of special characters}.
2054 @file{ly/text-replacements.ly}.
2058 @node Controlling output
2059 @section Controlling output
2062 * Extracting fragments of music::
2063 * Skipping corrected music::
2064 * Alternative output formats::
2065 * Replacing the notation font::
2068 @node Extracting fragments of music
2069 @subsection Extracting fragments of music
2071 It is possible to quote small fragments of a large score directly from
2072 the output. This can be compared to clipping a piece of a paper score
2075 This is done by defining the measures that need to be cut out
2076 separately. For example, including the following definition
2084 (make-rhythmic-location 5 1 2)
2085 (make-rhythmic-location 7 3 4)))
2090 will extract a fragment starting halfway the fifth measure, ending in
2091 the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note
2092 in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7.
2094 More clip regions can be defined by adding more pairs of
2095 rhythmic-locations to the list.
2097 In order to use this feature, LilyPond must be invoked with
2098 @option{-dclip-systems}. The clips are output as EPS files, and are
2099 converted to PDF and PNG if these formats are switched on as well.
2101 For more information on output formats, see @rprogram{Invoking lilypond}.
2103 @node Skipping corrected music
2104 @subsection Skipping corrected music
2107 @funindex skipTypesetting
2108 @funindex showFirstLength
2109 @funindex showLastLength
2111 When entering or copying music, usually only the music near the end (where
2113 are adding notes) is interesting to view and correct. To speed up
2114 this correction process, it is possible to skip typesetting of all but
2115 the last few measures. This is achieved by putting
2118 showLastLength = R1*5
2123 in your source file. This will render only the last 5 measures
2124 (assuming 4/4 time signature) of every @code{\score} in the input
2125 file. For longer pieces, rendering only a small part is often an order
2126 of magnitude quicker than rendering it completely. When working on the
2127 beginning of a score you have already typeset (e.g. to add a new part),
2128 the @code{showFirstLength} property may be useful as well.
2130 Skipping parts of a score can be controlled in a more fine-grained
2131 fashion with the property @code{Score.skipTypesetting}. When it is
2132 set, no typesetting is performed at all.
2134 This property is also used to control output to the MIDI file. Note that
2135 it skips all events, including tempo and instrument changes. You have
2138 @lilypond[quote,relative=2,ragged-right,verbatim]
2140 \set Score.skipTypesetting = ##t
2142 \set Score.skipTypesetting = ##f
2146 In polyphonic music, @code{Score.skipTypesetting} will affect all
2147 voices and staves, saving even more time.
2149 @node Alternative output formats
2150 @subsection Alternative output formats
2152 @cindex scalable vector graphics output
2154 @cindex encapsulated postscript output
2157 The default output formats for the printed score are Portable
2158 Document Format (PDF) and PostScript (PS). Scalable Vector
2159 Graphics (SVG), Encapsulated PostScript (EPS) and Portable
2160 Network Graphics (PNG) output formats are also available through
2161 command line options, see @rprogram{Command line options for
2165 @node Replacing the notation font
2166 @subsection Replacing the notation font
2168 Gonville is an alternative to the Feta font used in LilyPond and can
2171 @uref{http://www.chiark.greenend.org.uk/~sgtatham/gonville/ ,http://www.chiark.greenend.org.uk/~sgtatham/gonville/}
2174 Here are a few sample bars of music set in Gonville:
2176 @c NOTE: these images are a bit big, but that's important
2177 @c for the font comparison. -gp
2178 @sourceimage{Gonville_after,,,}
2180 Here are a few sample bars of music set in LilyPond's Feta font:
2182 @sourceimage{Gonville_before,,,}
2184 @subsubheading Installation Instructions for MacOS
2186 Download and extract the zip file. Copy the @code{lilyfonts}
2187 directory to @file{@var{SHARE_DIR}/lilypond/current}; for more
2188 information, see @rlearning{Other sources of information}. Rename the
2189 existing @code{fonts} directory to @code{fonts_orig} and the
2190 @code{lilyfonts} directory to @code{fonts}. To revert back to Feta,
2191 reverse the process.
2194 Learning Manual: @rlearning{Other sources of information}.
2197 Gonville cannot be used to typeset @q{Ancient Music} notation and it is
2198 likely newer glyphs in later releases of LilyPond may not exist in the
2199 Gonville font family. Please refer to the author's website for more
2200 information on these and other specifics, including licensing of
2205 @section MIDI output
2210 MIDI (Musical Instrument Digital Interface) is a standard for
2211 connecting and controlling digital instruments. A MIDI file is a
2212 series of notes in a number of tracks. It is not an actual
2213 sound file; you need special software to translate between the
2214 series of notes and actual sounds.
2216 Pieces of music can be converted to MIDI files, so you can listen to
2217 what was entered. This is convenient for checking the music; octaves
2218 that are off or accidentals that were mistyped stand out very much
2219 when listening to the MIDI output.
2221 Standard MIDI oputput is somewhat crude; optionally, an enhanced and
2222 more realistic MIDI output is available by means of
2223 @ref{The Articulate script}.
2225 The MIDI output allocates a channel for each staff, and reserves channel
2226 10 for drums. There are only 16 MIDI channels per device, so if the
2227 score contains more than 15 staves, MIDI channels will be reused.
2230 * Creating MIDI files::
2232 * What goes into the MIDI output?::
2234 * Controlling MIDI dynamics::
2235 * Percussion in MIDI::
2236 * The Articulate script::
2239 @node Creating MIDI files
2240 @subsection Creating MIDI files
2242 To create a MIDI output file from a LilyPond input file, add a
2243 @code{\midi} block to a score, for example,
2252 If there is a @code{\midi} block in a @code{\score} with no
2253 @code{\layout} block, only MIDI output will be produced. When
2254 notation is needed too, a @code{\layout} block must also be
2265 Pitches, rhythms, ties, dynamics, and tempo changes are interpreted
2266 and translated correctly to the MIDI output. Dynamic marks,
2267 crescendi and decrescendi translate into MIDI volume levels.
2268 Dynamic marks translate to a fixed fraction of the available MIDI
2269 volume range. Crescendi and decrescendi make the volume vary
2270 linearly between their two extremes. The effect of dynamic markings
2271 on the MIDI output can be removed completely, see @ref{MIDI block}.
2273 The initial tempo and later tempo changes can be specified
2274 with the @code{\tempo} command within the music notation. These
2275 are reflected in tempo changes in the MIDI output. This command
2276 will normally result in the metronome mark being printed, but this
2277 can be suppressed, see @ref{Metronome marks}. An alternative way
2278 of specifying the initial or overall MIDI tempo is described below,
2279 see @ref{MIDI block}.
2281 Due to some limitations on Windows, the default extension for
2282 MIDI files on Windows is @code{.mid}. Other operating systems still
2283 use the extension @code{.midi}. If a different extension is preferred,
2284 insert the following line at the top-level of the input file,
2285 before the start of any @code{\book}, @code{\bookpart} or @code{\score} blocks:
2288 #(ly:set-option 'midi-extension "midi")
2291 The line above will set the default extension for MIDI files to
2294 Alternatively, this option can also be supplied on the command line:
2297 lilypond … -dmidi-extension=midi lilyFile.ly
2301 @unnumberedsubsubsec Instrument names
2303 @cindex instrument names
2304 @funindex Staff.midiInstrument
2306 The MIDI instrument to be used is specified by setting the
2307 @code{Staff.midiInstrument} property to the instrument name.
2308 The name should be chosen from the list in @ref{MIDI instruments}.
2312 \set Staff.midiInstrument = #"glockenspiel"
2318 \new Staff \with @{midiInstrument = #"cello"@} @{
2323 If the selected instrument does not exactly match an instrument from
2324 the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
2330 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
2331 {changing-midi-output-to-one-channel-per-voice.ly}
2335 @c In 2.11 the following no longer seems to be a problem -td
2337 Unterminated (de)crescendos will not render properly in the midi file,
2338 resulting in silent passages of music. The workaround is to explicitly
2339 terminate the (de)crescendo. For example,
2346 will not work properly but
2349 @{ a4\< b c d\!\f @}
2356 Changes in the MIDI volume take place only on starting a note, so
2357 crescendi and decrescendi cannot affect the volume of a
2360 Not all midi players correctly handle tempo changes in the midi
2361 output. Players that are known to work include MS Windows Media
2362 Player and @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
2365 @subsection MIDI block
2368 A @code{\midi} block must appear within a score block if MIDI output
2369 is required. It is analogous to the layout block, but somewhat
2370 simpler. Often, the @code{\midi} block is left empty, but it
2371 can contain context rearrangements, new context definitions or code
2372 to set the values of properties. For example, the following will
2373 set the initial tempo exported to a MIDI file without causing a tempo
2374 indication to be printed:
2382 tempoWholesPerMinute = #(ly:make-moment 72 4)
2388 In this example the tempo is set to 72 quarter note
2389 beats per minute. This kind of tempo specification cannot take
2390 a dotted note length as an argument. If one is required, break
2391 the dotted note into smaller units. For example, a tempo of 90
2392 dotted quarter notes per minute can be specified as 270 eighth
2396 tempoWholesPerMinute = #(ly:make-moment 270 8)
2399 @cindex MIDI context definitions
2401 Context definitions follow precisely the same syntax as those
2402 within a @code{\layout} block. Translation modules for sound are
2403 called performers. The contexts for MIDI output are defined in
2404 @file{../ly/performer-init.ly},
2405 see @rlearning{Other sources of information}.
2406 For example, to remove the effect of dynamics
2407 from the MIDI output, insert the following lines in the
2408 @code{\midi@{ @}} block.
2415 \remove "Dynamic_performer"
2420 MIDI output is created only when a @code{\midi} block is included
2421 within a score block defined with a @code{\score} command.
2425 @{ @dots{}notes@dots{} @}
2430 @node What goes into the MIDI output?
2431 @subsection What goes into the MIDI output?
2433 @c TODO Check grace notes - timing is suspect?
2435 @unnumberedsubsubsec Supported in MIDI
2437 @cindex Pitches in MIDI
2438 @cindex MIDI, Pitches
2439 @cindex Quarter tones in MIDI
2440 @cindex MIDI, quarter tones
2441 @cindex Microtones in MIDI
2442 @cindex MIDI, microtones
2443 @cindex Chord names in MIDI
2444 @cindex MIDI, chord names
2445 @cindex Rhythms in MIDI
2446 @cindex MIDI, Rhythms
2447 @cindex Articlulate scripts
2448 @cindex MIDI, articulations
2449 @cindex articulations in MIDI
2450 @cindex trills in MIDI
2451 @cindex turns in MIDI
2452 @cindex rallentando in MIDI
2453 @cindex accelerando in MIDI
2456 The following items of notation are reflected in the MIDI output:
2460 @item Microtones (See @ref{Accidentals}. Rendering needs a
2461 player that supports pitch bend.)
2462 @item Chords entered as chord names
2463 @item Rhythms entered as note durations, including tuplets
2464 @item Tremolos entered without @q{@code{:}[@var{number}]}
2467 @item Crescendi, decrescendi over multiple notes
2468 @item Tempo changes entered with a tempo marking
2472 Using @ref{The Articulate script}, a number of items are added to the
2476 @item Articulations (slurs, staccato, etc)
2478 @item Rallentando and accelerando
2482 @unnumberedsubsubsec Unsupported in MIDI
2484 @c TODO index as above
2486 The following items of notation have no effect on the MIDI output,
2487 unless you use @ref{The Articulate script}:
2490 @item Rhythms entered as annotations, e.g. swing
2491 @item Tempo changes entered as annotations with no tempo marking
2492 @item Staccato and other articulations and ornamentations
2493 @item Slurs and Phrasing slurs
2494 @item Crescendi, decrescendi over a single note
2495 @item Tremolos entered with @q{@code{:}[@var{number}]}
2497 @item Microtonal chords
2501 @node Repeats in MIDI
2502 @subsection Repeats in MIDI
2504 @cindex repeats in MIDI
2505 @funindex \unfoldRepeats
2507 With a few minor additions, all types of repeats can be represented
2508 in the MIDI output. This is achieved by applying the
2509 @code{\unfoldRepeats} music function. This function changes all
2510 repeats to unfold repeats.
2512 @lilypond[quote,verbatim]
2514 \repeat tremolo 8 { c'32 e' }
2515 \repeat percent 2 { c''8 d'' }
2516 \repeat volta 2 { c'4 d' e' f' }
2525 In scores containing multiple voices, unfolding of repeats in MIDI
2526 output will only occur correctly if @emph{each} voice contains fully
2527 notated repeat indications.
2529 When creating a score file using @code{\unfoldRepeats} for MIDI,
2530 it is necessary to make two @code{\score} blocks: one for MIDI
2531 (with unfolded repeats) and one for notation (with volta, tremolo,
2532 and percent repeats). For example,
2540 \unfoldRepeats @var{..music..}
2545 @node Controlling MIDI dynamics
2546 @subsection Controlling MIDI dynamics
2548 MIDI dynamics are implemented by the Dynamic_performer which lives
2549 by default in the Voice context. It is possible to control the
2550 overall MIDI volume, the relative volume of dynamic markings and
2551 the relative volume of different instruments.
2553 @unnumberedsubsubsec Dynamic marks
2555 Dynamic marks are translated to a fixed fraction of the available
2556 MIDI volume range. The default fractions range from 0.25 for
2557 @notation{ppppp} to 0.95 for @notation{fffff}. The set of dynamic
2558 marks and the associated fractions can be seen in
2559 @file{../scm/midi.scm}, see @rlearning{Other sources of information}.
2560 This set of fractions may be changed or extended by providing a
2561 function which takes a dynamic mark as its argument and returns the
2562 required fraction, and setting
2563 @code{Score.dynamicAbsoluteVolumeFunction} to this function.
2565 For example, if a @notation{rinforzando} dynamic marking,
2566 @code{\rfz}, is required, this will not by default
2567 have any effect on the MIDI volume, as this dynamic marking is not
2568 included in the default set. Similarly, if a new dynamic marking
2569 has been defined with @code{make-dynamic-script} that too will not
2570 be included in the default set. The following example shows how the
2571 MIDI volume for such dynamic markings might be added. The Scheme
2572 function sets the fraction to 0.9 if a dynamic mark of rfz is
2573 found, or calls the default function otherwise.
2575 @lilypond[verbatim,quote]
2576 #(define (myDynamics dynamic)
2577 (if (equal? dynamic "rfz")
2579 (default-dynamic-absolute-volume dynamic)))
2583 \set Staff.midiInstrument = #"cello"
2584 \set Score.dynamicAbsoluteVolumeFunction = #myDynamics
2596 Alternatively, if the whole table of fractions needs to be
2597 redefined, it would be better to use the
2598 @notation{default-dynamic-absolute-volume} procedure in
2599 @file{../scm/midi.scm} and the associated table as a model.
2600 The final example in this section shows how this might be done.
2602 @unnumberedsubsubsec Overall MIDI volume
2604 The minimum and maximum overall volume of MIDI dynamic markings is
2605 controlled by setting the properties @code{midiMinimumVolume} and
2606 @code{midiMaximumVolume} at the @code{Score} level. These
2607 properties have an effect only on dynamic marks, so if they
2608 are to apply from the start of the score a dynamic mark must be
2609 placed there. The fraction corresponding to each dynamic mark is
2610 modified with this formula
2613 midiMinimumVolume + (midiMaximumVolume - midiMinimumVolume) * fraction
2616 In the following example the dynamic range of the overall MIDI
2617 volume is limited to the range 0.2 - 0.5.
2619 @lilypond[verbatim,quote]
2625 \set Staff.midiInstrument = #"flute"
2626 \new Voice \relative c''' {
2634 \set Staff.midiInstrument = #"clarinet"
2635 \new Voice \relative c'' {
2646 tempoWholesPerMinute = #(ly:make-moment 72 2)
2647 midiMinimumVolume = #0.2
2648 midiMaximumVolume = #0.5
2654 @unnumberedsubsubsec Equalizing different instruments (i)
2656 If the minimum and maximum MIDI volume properties are set in
2657 the @code{Staff} context the relative volumes of the MIDI
2658 instruments can be controlled. This gives a basic instrument
2659 equalizer, which can enhance the quality of the MIDI output
2662 In this example the volume of the clarinet is reduced relative
2663 to the volume of the flute. There must be a dynamic
2664 mark on the first note of each instrument for this to work
2667 @lilypond[verbatim,quote]
2673 \set Staff.midiInstrument = #"flute"
2674 \set Staff.midiMinimumVolume = #0.7
2675 \set Staff.midiMaximumVolume = #0.9
2676 \new Voice \relative c''' {
2684 \set Staff.midiInstrument = #"clarinet"
2685 \set Staff.midiMinimumVolume = #0.3
2686 \set Staff.midiMaximumVolume = #0.6
2687 \new Voice \relative c'' {
2698 tempoWholesPerMinute = #(ly:make-moment 72 2)
2704 @unnumberedsubsubsec Equalizing different instruments (ii)
2706 If the MIDI minimum and maximum volume properties are not set
2707 LilyPond will, by default, apply a small degree of equalization
2708 to a few instruments. The instruments and the equalization
2709 applied are shown in the table @notation{instrument-equalizer-alist}
2710 in @file{../scm/midi.scm}.
2712 This basic default equalizer can be replaced by setting
2713 @code{instrumentEqualizer} in the @code{Score} context to a new
2714 Scheme procedure which accepts a MIDI instrument name as its only
2715 argument and returns a pair of fractions giving the minimum and
2716 maximum volumes to be applied to that instrument. This replacement
2717 is done in the same way as shown for resetting the
2718 @code{dynamicAbsoluteVolumeFunction} at the start of this section.
2719 The default equalizer, @notation{default-instrument-equalizer}, in
2720 @file{../scm/midi.scm} shows how such a procedure might be written.
2722 The following example sets the relative flute and clarinet volumes
2723 to the same values as the previous example.
2725 @lilypond[verbatim,quote]
2726 #(define my-instrument-equalizer-alist '())
2728 #(set! my-instrument-equalizer-alist
2731 ("flute" . (0.7 . 0.9))
2732 ("clarinet" . (0.3 . 0.6)))
2733 my-instrument-equalizer-alist))
2735 #(define (my-instrument-equalizer s)
2736 (let ((entry (assoc s my-instrument-equalizer-alist)))
2745 \set Score.instrumentEqualizer = #my-instrument-equalizer
2746 \set Staff.midiInstrument = #"flute"
2747 \new Voice \relative c''' {
2755 \set Staff.midiInstrument = #"clarinet"
2756 \new Voice \relative c'' {
2767 tempoWholesPerMinute = #(ly:make-moment 72 2)
2774 @c Delete when satisfied this is adequately covered elsewhere -td
2776 @n ode Microtones in MIDI
2777 @s ubsection Microtones in MIDI
2779 @cindex microtones in MIDI
2781 Microtones consisting of half sharps and half flats are exported
2782 to the MIDI file and render correctly in MIDI players which support
2783 pitch bending. See @ref{Note names in other languages}. Here is
2784 an example showing all the half sharps and half flats. It can be
2785 copied out and compiled to test microtones in your MIDI player.
2787 @lilypond[verbatim,quote]
2804 @node Percussion in MIDI
2805 @subsection Percussion in MIDI
2807 Percussion instruments are generally notated in a @code{DrumStaff}
2808 context and when notated in this way they are outputted correctly
2809 to MIDI channel@tie{}10, but some pitched percussion instruments,
2810 like the xylophone, marimba, vibraphone, timpani, etc., are
2811 treated like @qq{normal} instruments and music for these instruments
2812 should be entered in a normal @code{Staff} context, not a
2813 @code{DrumStaff} context, to obtain the correct MIDI output.
2815 Some non-pitched percussion sounds included in the general MIDI
2816 standard, like melodic tom, taiko drum, synth drum, etc., cannot
2817 be reached via MIDI channel@tie{}10, so the notation for such
2818 instruments should also be entered in a normal @code{Staff}
2819 context, using suitable normal pitches.
2821 Many percussion instruments are not included in the general MIDI
2822 standard, e.g. castanets. The easiest, although unsatisfactory,
2823 method of producing some MIDI output when writing for such
2824 instruments is to substitute the nearest sound from the standard
2827 @c TODO Expand with examples, and any other issues
2831 Because the general MIDI standard does not contain rim shots, the
2832 sidestick is used for this purpose instead.
2834 @node The Articulate script
2835 @subsection The Articulate script
2837 A more realistic MIDI output is possible when using the Articulate
2838 script. It tries to take articulations (slurs, staccato, etc) into
2839 account, by replacing notes with sequential music of suitably
2840 time-scaled note plus skip. It also tries to unfold trills turns
2841 etc., and take rallentando and accelerando into account.
2843 To use the Articulate script, you have to include it at the top of
2847 \include "articulate.ly"
2850 and in the @code{\score} section do
2853 \unfoldRepeats \articulate <<
2854 all the rest of the score...
2858 After altering your input file this way, the visual output is heavily
2859 altered, but the standard @code{\midi} block will produce a better
2862 Although not essential for the Articulate script to work, you may want
2863 to insert the @code{\unfoldRepeats} command as it appears in the
2864 example shown above as it enables performing abbreviatures such as
2869 Articulate shortens chords and some music (esp. organ music) could
2873 @node Extracting musical information
2874 @section Extracting musical information
2876 In addition to creating graphical output and MIDI, LilyPond can
2877 display musical information as text.
2880 * Displaying LilyPond notation::
2881 * Displaying scheme music expressions::
2882 * Saving music events to a file::
2885 @node Displaying LilyPond notation
2886 @subsection Displaying LilyPond notation
2888 @funindex \displayLilyMusic
2889 Displaying a music expression in LilyPond notation can be
2890 done with the music function @code{\displayLilyMusic}. To see the
2891 output, you will typically want to call LilyPond using the command
2896 \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
2903 @{ a,4 cis e fis g @}
2906 By default, LilyPond will print these messages to the console
2907 along with all the other LilyPond compilation messages. To split
2908 up these messages and save the results of @code{\display@{STUFF@}},
2909 redirect the output to a file.
2912 lilypond file.ly >display.txt
2916 Note that Lilypond does not just display the music expression, but
2917 also interprets it (since @code{\displayLilyMusic} returns it in
2918 addition to displaying it). This is convenient since you can just
2919 insert @code{\displayLilyMusic} into existing music in order to get
2920 information about it. If you don't actually want Lilypond to
2921 interpret the displayed music as well as display it, use @code{\void}
2922 in order to have it ignored:
2926 \void \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
2931 @node Displaying scheme music expressions
2932 @subsection Displaying scheme music expressions
2934 See @rextend{Displaying music expressions}.
2937 @node Saving music events to a file
2938 @subsection Saving music events to a file
2940 Music events can be saved to a file on a per-staff basis by
2941 including a file in your main score.
2944 \include "event-listener.ly"
2947 This will create file(s) called @file{FILENAME-STAFFNAME.notes} or
2948 @file{FILENAME-unnamed-staff.notes} for each staff. Note that if
2949 you have multiple unnamed staves, the events for all staves will
2950 be mixed together in the same file. The output looks like this:
2953 0.000 note 57 4 p-c 2 12
2955 0.250 note 62 4 p-c 7 12
2956 0.500 note 66 8 p-c 9 12
2957 0.625 note 69 8 p-c 14 12
2962 The syntax is a tab-delimited line, with two fixed fields on each
2963 line followed by optional parameters.
2966 @var{time} @var{type} @var{...params...}
2969 This information can easily be read into other programs such as
2970 python scripts, and can be very useful for researchers wishing to
2971 perform musical analysis or playback experiments with LilyPond.
2976 Not all lilypond music events are supported by
2977 @file{event-listener.ly}. It is intended to be a well-crafted
2978 @qq{proof of concept}. If some events that you want to see are
2979 not included, copy @file{event-listener.ly} into your lilypond
2980 directory and modify the file so that it outputs the information