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::
29 @section Input structure
31 The main format of input for LilyPond are text files. By convention,
32 these files end with @file{.ly}.
35 * Structure of a score::
36 * Multiple scores in a book::
37 * Multiple output files from one input file::
43 @node Structure of a score
44 @subsection Structure of a score
48 A @code{\score} block must contain a single music expression
49 delimited by curly brackets:
57 @warning{There must be @strong{only one} outer music expression in
58 a @code{\score} block, and it @strong{must} be surrounded by
61 This single music expression may be of any size, and may contain
62 other music expressions to any complexity. All of these examples
63 are music expressions:
69 @lilypond[verbatim,quote]
76 @lilypond[verbatim,quote]
78 \new Staff { c'4 c' c' c' }
79 \new Staff { d'4 d' d' d' }
87 \new Staff @{ \flute @}
88 \new Staff @{ \oboe @}
91 \new Staff @{ \violinI @}
92 \new Staff @{ \violinII @}
98 Comments are one exception to this general rule. (For others see
99 @ref{File structure}.) Both single-line comments and comments
100 delimited by @code{%@{ .. %@}} may be placed anywhere within an
101 input file. They may be placed inside or outside a @code{\score}
102 block, and inside or outside the single music expression within a
105 Remember that even in a file containing only a @code{\score} block, it
106 is implicitly enclosed in a \book block. A \book block in a source
107 file produces at least one output file, and by default the name of the
108 output file produced is derived from the name of the input file, so
109 @file{fandangoforelephants.ly} will produce
110 @file{fandangoforelephants.pdf}.
112 (For more details about @code{\book} blocks, see
113 @ref{Multiple scores in a book},
114 @ref{Multiple output files from one input file} @ref{File structure}.)
118 @rlearning{Working on input files},
119 @rlearning{Music expressions explained},
120 @rlearning{Score is a (single) compound musical expression}.
123 @node Multiple scores in a book
124 @subsection Multiple scores in a book
127 @cindex movements, multiple
129 A document may contain multiple pieces of music and text. Examples
130 of these are an etude book, or an orchestral part with multiple
131 movements. Each movement is entered with a @code{\score} block,
139 and texts are entered with a @code{\markup} block,
149 All the movements and texts which appear in the same @file{.ly} file
150 will normally be typeset in the form of a single output file.
164 One important exception is within lilypond-book documents,
165 where you explicitly have to add a @code{\book} block, otherwise only
166 the first @code{\score} or @code{\markup} will appear in the output.
168 The header for each piece of music can be put inside the @code{\score}
169 block. The @code{piece} name from the header will be printed before
170 each movement. The title for the entire book can be put inside the
171 @code{\book}, but if it is not present, the @code{\header} which is at
172 the top of the file is inserted.
176 title = "Eight miniatures"
177 composer = "Igor Stravinsky"
181 \header @{ piece = "Romanze" @}
184 ..text of second verse..
187 ..text of third verse..
191 \header @{ piece = "Menuetto" @}
197 Pieces of music may be grouped into book parts using @code{\bookpart}
198 blocks. Book parts are separated by a page break, and can start with a
199 title, like the book itself, by specifying a @code{\header} block.
205 subtitle = "First part"
212 subtitle = "Second part"
219 @node Multiple output files from one input file
220 @subsection Multiple output files from one input file
222 If you want multiple output files from the same @file{.ly} file,
223 then you can add multiple @code{\book} blocks, where each
224 such \book block will result in a separate output file.
225 If you do not specify any @code{\book} block in the
226 input file, LilyPond will implicitly treat the whole
227 file as a single \book block, see
228 @ref{File structure}.
230 When producing multiple files from a single source file, Lilypond
231 ensures that none of the output files from any @code{\book} block
232 overwrites the output file produced by a preceding @code{\book} from
235 It does this by adding a suffix to the output name for each
236 @code{\book} which uses the default output file name derived from the
239 The default behaviour is to append a version-number suffix for each
240 name which may clash, so
245 \layout @{ @dots{} @}
249 \layout @{ @dots{} @}
253 \layout @{ @dots{} @}
257 in source file @file{eightminiatures.ly}
262 @file{eightminiatures.pdf},
264 @file{eightminiatures-1.pdf} and
266 @file{eightminiatures-2.pdf}.
269 @node Output file names
270 @subsection Output file names
272 @funindex \bookOutputSuffix
273 @funindex \bookOutputName
275 Lilypond provides facilities to allow you to control what file names
276 are used by the various back-ends when producing output files.
278 In the previous section, we saw how Lilypond prevents name-clashes when
279 producing several ouputs from a single source file. You also have the
280 ability to specify your own suffixes for each @code{\book} block, so
281 for example you can produce files called
282 @file{eightminiatures-Romanze.pdf}, @file{eightminiatures-Menuetto.pdf}
283 and @file{eightminiatures-Nocturne.pdf} by adding a
284 @code{\bookOutputSuffix} declaration inside each @code{\book} block.
288 \bookOutputSuffix "Romanze"
290 \layout @{ @dots{} @}
293 \bookOutputSuffix "Menuetto"
295 \layout @{ @dots{} @}
298 \bookOutputSuffix "Nocturne"
300 \layout @{ @dots{} @}
304 You can also specify a different output filename for @code{book} block,
305 by using @code{\bookOutputName} declarations
309 \bookOutputName "Romanze"
311 \layout @{ @dots{} @}
314 \bookOutputName "Menuetto"
316 \layout @{ @dots{} @}
319 \bookOutputName "Nocturne"
321 \layout @{ @dots{} @}
325 The file above will produce these output files:
331 @file{Menuetto.pdf} and
338 @subsection File structure
348 A @file{.ly} file may contain any number of toplevel expressions, where a
349 toplevel expression is one of the following:
353 An output definition, such as @code{\paper}, @code{\midi}, and
354 @code{\layout}. Such a definition at the toplevel changes the default
355 book-wide settings. If more than one such definition of
356 the same type is entered at the top level any definitions in the later
357 expressions have precedence.
360 A direct scheme expression, such as
361 @code{#(set-default-paper-size "a7" 'landscape)} or
362 @code{#(ly:set-option 'point-and-click #f)}.
365 A @code{\header} block. This sets the global header block. This
366 is the block containing the definitions for book-wide settings, like
367 composer, title, etc.
370 A @code{\score} block. This score will be collected with other
371 toplevel scores, and combined as a single @code{\book}.
372 This behavior can be changed by setting the variable
373 @code{toplevel-score-handler} at toplevel. The default handler is
374 defined in the init file @file{../scm/lily.scm}.
377 A @code{\book} block logically combines multiple movements
378 (i.e., multiple @code{\score} blocks) in one document. If there
379 are a number of @code{\score}s, one output file will be created
380 for each @code{\book} block, in which all corresponding movements
381 are concatenated. The only reason to explicitly specify
382 @code{\book} blocks in a @file{.ly} file is if you wish to create
383 multiple output files from a single input file. One exception is
384 within lilypond-book documents, where you explicitly have to add
385 a @code{\book} block if you want more than a single @code{\score}
386 or @code{\markup} in the same example. This behavior can be
387 changed by setting the variable @code{toplevel-book-handler} at
388 toplevel. The default handler is defined in the init file
389 @file{../scm/lily.scm}.
392 A @code{\bookpart} block. A book may be divided into several parts,
393 using @code{\bookpart} blocks, in order to ease the page breaking,
394 or to use different @code{\paper} settings in different parts.
397 A compound music expression, such as
402 This will add the piece in a @code{\score} and format it in a
403 single book together with all other toplevel @code{\score}s and music
404 expressions. In other words, a file containing only the above
405 music expression will be translated into
421 This behavior can be changed by setting the variable
422 @code{toplevel-music-handler} at toplevel. The default handler is
423 defined in the init file @file{../scm/lily.scm}.
426 A markup text, a verse for example
429 2. The first line verse two.
433 Markup texts are rendered above, between or below the scores or music
434 expressions, wherever they appear.
444 This can be used later on in the file by entering @code{\foo}. The
445 name of a variable should have alphabetic characters only; no
446 numbers, underscores or dashes.
450 The following example shows three things that may be entered at
455 % Don't justify the output
467 At any point in a file, any of the following lexical instructions can
471 @item @code{\version}
472 @item @code{\include}
473 @item @code{\sourcefilename}
474 @item @code{\sourcefileline}
476 A single-line comment, introduced by a leading @code{%} sign.
479 A multi-line comment delimited by @code{%@{ .. %@}}.
485 Whitespace between items in the input stream is generally ignored,
486 and may be freely omitted or extended to enhance readability.
487 However, whitespace should always be used in the following
488 circumstances to avoid errors:
491 @item Around every opening and closing curly bracket.
492 @item After every command or variable, i.e. every item that
493 begins with a @code{\} sign.
494 @item After every item that is to be interpreted as a Scheme
495 expression, i.e. every item that begins with a @code{#} sign.
496 @item To separate all elements of a Scheme expression.
497 @item In @code{lyricmode} to separate all the terms in both
498 @code{\override} and @code{\set} commands. In particular, spaces
499 must be used around the dot and the equals sign in commands like
500 @code{\override Score . LyricText #'font-size = #5} and before and
501 after the entire command.
508 @rlearning{How LilyPond input files work}.
511 @node Titles and headers
512 @section Titles and headers
514 Almost all printed music includes a title and the composer's name;
515 some pieces include a lot more information.
519 * Custom headers footers and titles::
520 * Reference to page numbers::
521 * Table of contents::
525 @node Creating titles
526 @subsection Creating titles
528 Titles are created for each @code{\score} block, as well as for the full
529 input file (or @code{\book} block) and book parts (created by
530 @code{\bookpart} blocks).
532 The contents of the titles are taken from the @code{\header} blocks.
533 The header block for a book supports the following
539 The dedicatee of the music, centered at the top of the first page.
543 The title of the music, centered just below the dedication.
547 Subtitle, centered below the title.
549 @funindex subsubtitle
551 Subsubtitle, centered below the subtitle.
555 Name of the poet, flush-left below the subsubtitle.
559 Name of the instrument, centered below the subsubtitle. Also
560 centered at the top of pages (other than the first page).
564 Name of the composer, flush-right below the subsubtitle.
568 Meter string, flush-left below the poet.
572 Name of the arranger, flush-right below the composer.
576 Name of the piece, flush-left below the meter.
580 Name of the opus, flush-right below the arranger.
582 @cindex page breaks, forcing
583 @funindex breakbefore
585 This forces the title to start on a new page (set to ##t or ##f).
589 Copyright notice, centered at the bottom of the first page. To
590 insert the copyright symbol, see @ref{Text encoding}.
594 Centered at the bottom of the last page.
598 Here is a demonstration of the fields available. Note that you
599 may use any @ref{Formatting text}, commands in the header.
601 @lilypond[quote,verbatim,line-width=11.0\cm]
604 paper-height = 10.0\cm
609 dedication = "dedicated to me"
610 title = \markup \center-column { "Title first line" "Title second line,
612 subtitle = "the subtitle,"
613 subsubtitle = #(string-append "subsubtitle LilyPond version "
616 composer = \markup \center-column { "composer" \small "(1847-1973)" }
617 texttranslator = "Text Translator"
618 meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
620 arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize
621 #-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }
622 instrument = \markup \bold \italic "instrument"
646 As demonstrated before, you can use multiple @code{\header} blocks.
647 When same fields appear in different blocks, the latter is used.
648 Here is a short example.
652 composer = "Composer"
660 piece = "New piece" % overwrite previous one
665 If you define the @code{\header} inside the @code{\score} block, then
666 normally only the @code{piece} and @code{opus} headers will be printed.
667 Note that the music expression must come before the @code{\header}.
669 @lilypond[quote,verbatim,line-width=11.0\cm]
673 title = "title" % not printed
680 @funindex print-all-headers
682 You may change this behavior (and print all the headers when defining
683 @code{\header} inside @code{\score}) by using
687 print-all-headers = ##t
694 The default footer is empty, except for the first page, where the
695 @code{copyright} field from @code{\header} is inserted, and the last
696 page, where @code{tagline} from @code{\header} is added. The default
697 tagline is @qq{Music engraving by LilyPond (@var{version})}.@footnote{Nicely
698 printed parts are good PR for us, so please leave the tagline if you
701 Headers may be completely removed by setting them to false.
711 @node Custom headers footers and titles
712 @subsection Custom headers, footers, and titles
714 A more advanced option is to change the definitions of the following
715 variables in the @code{\paper} block. The init file
716 @file{../ly/titling-init.ly} lists the default layout.
719 @funindex bookTitleMarkup
720 @item bookTitleMarkup
721 This is the title added at the top of the entire output document.
722 Typically, it has the composer and the title of the piece
724 @funindex scoreTitleMarkup
725 @item scoreTitleMarkup
726 This is the title put over a @code{\score} block. Typically, it has
727 the name of the movement (@code{piece} field).
729 @funindex oddHeaderMarkup
730 @item oddHeaderMarkup
731 This is the page header for odd-numbered pages.
733 @funindex evenHeaderMarkup
734 @item evenHeaderMarkup
735 This is the page header for even-numbered pages. If unspecified,
736 the odd header is used instead.
738 By default, headers are defined such that the page number is on the
739 outside edge, and the instrument is centered.
741 @funindex oddFooterMarkup
742 @item oddFooterMarkup
743 This is the page footer for odd-numbered pages.
745 @funindex evenFooterMarkup
746 @item evenFooterMarkup
747 This is the page footer for even-numbered pages. If unspecified,
748 the odd header is used instead.
750 By default, the footer has the copyright notice on the first, and
751 the tagline on the last page.
761 The following definition will put the title flush left, and the
762 composer flush right on a single line.
766 bookTitleMarkup = \markup @{
768 \fromproperty #'header:title
769 \fromproperty #'header:composer
775 The header and footer are created by the functions
776 @code{make-header} and @code{make-footer}, defined in
777 @code{\paper}. The default implementations are in
778 @file{ly/paper-defaults-init.ly} and
779 @file{ly/titling-init.ly}.
781 This example centers page numbers at the bottom of every page.
785 print-page-number = ##t
786 print-first-page-number = ##t
787 oddHeaderMarkup = \markup \fill-line @{ " " @}
788 evenHeaderMarkup = \markup \fill-line @{ " " @}
789 oddFooterMarkup = \markup @{
792 \on-the-fly #print-page-number-check-first
793 \fromproperty #'page:page-number-string
796 evenFooterMarkup = \markup @{
799 \on-the-fly #print-page-number-check-first
800 \fromproperty #'page:page-number-string
807 @node Reference to page numbers
808 @subsection Reference to page numbers
810 A particular place of a score can be marked using the @code{\label}
811 command, either at top-level or inside music. This label can then be
812 referred to in a markup, to get the number of the page where the marked
813 point is placed, using the @code{\page-ref} markup command.
815 @lilypond[verbatim,line-width=11.0\cm]
816 \header { tagline = ##f }
822 \pageBreak \mark A \label #'markA
827 \markup { The first score begins on page \page-ref #'firstScore "0" "?" }
828 \markup { Mark A is on page \page-ref #'markA "0" "?" }
832 The @code{\page-ref} markup command takes three arguments:
834 @item the label, a scheme symbol, eg. @code{#'firstScore};
835 @item a markup that will be used as a gauge to estimate the dimensions
837 @item a markup that will be used in place of the page number if the label
841 The reason why a gauge is needed is that, at the time markups are
842 interpreted, the page breaking has not yet occurred, so the page numbers
843 are not yet known. To work around this issue, the actual markup
844 interpretation is delayed to a later time; however, the dimensions of
845 the markup have to be known before, so a gauge is used to decide these
846 dimensions. If the book has between 10 and 99 pages, it may be "00",
847 ie. a two digit number.
858 @node Table of contents
859 @subsection Table of contents
860 A table of contents is included using the @code{\markuplines \table-of-contents}
861 command. The elements which should appear in the table of contents are
862 entered with the @code{\tocItem} command, which may be used either at
863 top-level, or inside a music expression.
866 \markuplines \table-of-contents
869 \tocItem \markup "First score"
873 \tocItem \markup "Some particular point in the first score"
878 \tocItem \markup "Second score"
886 The markups which are used to format the table of contents are defined
887 in the @code{\paper} block. The default ones are @code{tocTitleMarkup},
888 for formatting the title of the table, and @code{tocItemMarkup}, for
889 formatting the toc elements, composed of the element title and page
890 number. These variables may be changed by the user:
894 %% Translate the toc title into French:
895 tocTitleMarkup = \markup \huge \column {
896 \fill-line { \null "Table des matières" \null }
899 %% use larger font size
900 tocItemMarkup = \markup \large \fill-line {
901 \fromproperty #'toc:text \fromproperty #'toc:page
906 Note how the toc element text and page number are referred to in
907 the @code{tocItemMarkup} definition.
909 New commands and markups may also be defined to build more elaborated
912 @item first, define a new markup variable in the @code{\paper} block
913 @item then, define a music function which aims at adding a toc element
914 using this markup paper variable.
917 In the following example, a new style is defined for entering act names
918 in the table of contents of an opera:
922 tocActMarkup = \markup \large \column {
924 \fill-line { \null \italic \fromproperty #'toc:text \null }
930 #(define-music-function (parser location text) (markup?)
931 (add-toc-item! 'tocActMarkup text))
934 @lilypond[line-width=11.0\cm]
935 \header { tagline = ##f }
937 tocActMarkup = \markup \large \column {
939 \fill-line { \null \italic \fromproperty #'toc:text \null }
945 #(define-music-function (parser location text) (markup?)
946 (add-toc-item! 'tocActMarkup text))
949 \markuplines \table-of-contents
950 \tocAct \markup { Atto Primo }
951 \tocItem \markup { Coro. Viva il nostro Alcide }
952 \tocItem \markup { Cesare. Presti omai l'Egizzia terra }
953 \tocAct \markup { Atto Secondo }
954 \tocItem \markup { Sinfonia }
955 \tocItem \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
962 Init files: @file{../ly/toc-init.ly}.
966 @funindex \table-of-contents
967 @code{\table-of-contents},
973 @node Working with input files
974 @section Working with input files
977 * Including LilyPond files::
978 * Different editions from one source::
980 * Displaying LilyPond notation::
984 @node Including LilyPond files
985 @subsection Including LilyPond files
988 @cindex including files
990 A large project may be split up into separate files. To refer to
994 \include "otherfile.ly"
997 The line @code{\include "otherfile.ly"} is equivalent to pasting the
998 contents of @file{otherfile.ly} into the current file at the place
999 where the @code{\include} appears. For example, in a large
1000 project you might write separate files for each instrument part
1001 and create a @qq{full score} file which brings together the
1002 individual instrument files. Normally the included file will
1003 define a number of variables which then become available
1004 for use in the full score file. Tagged sections can be
1005 marked in included files to assist in making them usable in
1006 different places in a score, see @ref{Different editions from
1009 Files in the current working directory may be referenced by
1010 specifying just the file name after the @code{\include} command.
1011 Files in other locations may be included by giving either a full
1012 path reference or a relative path reference (but use the UNIX
1013 forward slash, /, rather than the DOS/Windows back slash, \, as the
1014 directory separator.) For example, if @file{stuff.ly} is located
1015 one directory higher than the current working directory, use
1018 \include "../stuff.ly"
1022 or if the included orchestral parts files are all located in a
1023 subdirectory called @file{parts} within the current directory, use
1026 \include "parts/VI.ly"
1027 \include "parts/VII.ly"
1031 Files which are to be included can also contain @code{\include}
1032 statements of their own. By default, these second-level
1033 @code{\include} statements are not interpreted until they have
1034 been brought into the main file, so the file names they specify
1035 must all be relative to the directory containing the main file,
1036 not the directory containing the included file. However,
1037 this behavior can be changed by passing the option
1038 @code{-drelative-includes} option at the command line
1039 (or by adding @code{#(ly:set-option 'relative-includes #t)}
1040 at the top of the main input file). With @code{relative-includes}
1041 set, the path for each @code{\include} command will be taken
1042 relative to the file containing that command. This behavior is
1043 recommended and it will become the default behavior in a future
1044 version of lilypond.
1046 Files can also be included from a directory in a search path
1047 specified as an option when invoking LilyPond from the command
1048 line. The included files are then specified using just their
1049 file name. For example, to compile @file{main.ly} which includes
1050 files located in a subdirectory called @file{parts} by this method,
1051 cd to the directory containing @file{main.ly} and enter
1054 lilypond --include=parts main.ly
1057 and in main.ly write
1065 Files which are to be included in many scores may be placed in
1066 the LilyPond directory @file{../ly}. (The location of this
1067 directory is installation-dependent - see
1068 @rlearning{Other sources of information}). These files can then
1069 be included simply by naming them on an @code{\include} statement.
1070 This is how the language-dependent files like @file{english.ly} are
1073 LilyPond includes a number of files by default when you start
1074 the program. These includes are not apparent to the user, but the
1075 files may be identified by running @code{lilypond --verbose} from
1076 the command line. This will display a list of paths and files that
1077 LilyPond uses, along with much other information. Alternatively,
1078 the more important of these files are discussed in
1079 @rlearning{Other sources of information}. These files may be
1080 edited, but changes to them will be lost on installing a new
1081 version of LilyPond.
1083 Some simple examples of using @code{\include} are shown in
1084 @rlearning{Scores and parts}.
1089 @rlearning{Other sources of information},
1090 @rlearning{Scores and parts}.
1095 If an included file is given a name which is the same as one in
1096 LilyPond's installation files, LilyPond's file from the
1097 installation files takes precedence.
1101 @node Different editions from one source
1102 @subsection Different editions from one source
1104 Several mechanisms are available to facilitate the generation
1105 of different versions of a score from the same music source.
1106 Variables are perhaps most useful for combining lengthy sections
1107 of music and/or annotation in various ways, while tags are more
1108 useful for selecting one from several alternative shorter sections
1109 of music. Whichever method is used, separating the notation from
1110 the structure of the score will make it easier to change the
1111 structure while leaving the notation untouched.
1116 * Using global settings::
1119 @node Using variables
1120 @unnumberedsubsubsec Using variables
1122 @cindex variables, use of
1124 If sections of the music are defined in variables they can be
1125 reused in different parts of the score, see @rlearning{Organizing
1126 pieces with variables}. For example, an @notation{a cappella}
1127 vocal score frequently includes a piano reduction of the parts
1128 for rehearsal purposes which is identical to the vocal music, so
1129 the music need be entered only once. Music from two variables
1130 may be combined on one staff, see @ref{Automatic part combining}.
1133 @lilypond[verbatim,quote]
1134 sopranoMusic = \relative c'' { a4 b c b8( a) }
1135 altoMusic = \relative g' { e4 e e f }
1136 tenorMusic = \relative c' { c4 b e d8( c) }
1137 bassMusic = \relative c' { a4 gis a d, }
1138 allLyrics = \lyricmode {King of glo -- ry }
1140 \new Staff = "Soprano" \sopranoMusic
1141 \new Lyrics \allLyrics
1142 \new Staff = "Alto" \altoMusic
1143 \new Lyrics \allLyrics
1144 \new Staff = "Tenor" {
1148 \new Lyrics \allLyrics
1149 \new Staff = "Bass" {
1153 \new Lyrics \allLyrics
1156 \set Staff.printPartCombineTexts = ##f
1162 \set Staff.printPartCombineTexts = ##f
1172 Separate scores showing just the vocal parts or just the piano
1173 part can be produced by changing just the structural statements,
1174 leaving the musical notation unchanged.
1176 For lengthy scores, the variable definitions may be placed in
1177 separate files which are then included, see @ref{Including
1181 @unnumberedsubsubsec Using tags
1184 @funindex \keepWithTag
1185 @funindex \removeWithTag
1187 @cindex keep tagged music
1188 @cindex remove tagged music
1190 The @code{\tag #'@var{partA}} command marks a music expression
1191 with the name @var{partA}.
1192 Expressions tagged in this way can be selected or filtered out by
1193 name later, using either @code{\keepWithTag #'@var{name}} or
1194 @code{\removeWithTag #'@var{name}}. The result of applying these filters
1195 to tagged music is as follows:
1196 @multitable @columnfractions .5 .5
1200 Tagged music preceded by @code{\keepWithTag #'@var{name}}
1201 @tab Untagged music and music tagged with @var{name} is included;
1202 music tagged with any other tag name is excluded.
1204 Tagged music preceded by @code{\removeWithTag #'@var{name}}
1205 @tab Untagged music and music tagged with any tag name other than
1206 @var{name} is included; music tagged with @var{name} is
1209 Tagged music not preceded by either @code{\keepWithTag} or
1210 @code{\removeWithTag}
1211 @tab All tagged and untagged music is included.
1214 The arguments of the @code{\tag}, @code{\keepWithTag} and
1215 @code{\removeWithTag} commands should be a symbol
1216 (such as @code{#'score} or @code{#'part}), followed
1217 by a music expression.
1219 In the following example, we see two versions of a piece of music,
1220 one showing trills with the usual notation, and one with trills
1221 explicitly expanded:
1223 @lilypond[verbatim,quote]
1224 music = \relative g' {
1226 \tag #'trills { d8.\trill }
1227 \tag #'expand { \repeat unfold 3 { e32 d } }
1232 \keepWithTag #'trills \music
1235 \keepWithTag #'expand \music
1240 Alternatively, it is sometimes easier to exclude sections of music:
1242 @lilypond[verbatim,quote]
1243 music = \relative g' {
1245 \tag #'trills { d8.\trill }
1246 \tag #'expand {\repeat unfold 3 { e32 d } }
1251 \removeWithTag #'expand
1255 \removeWithTag #'trills
1260 Tagged filtering can be applied to articulations, texts, etc. by
1264 -\tag #'@var{your-tag}
1267 to an articulation. For example, this would define a note with a
1268 conditional fingering indication and a note with a conditional
1273 c1-\tag #'warn ^"Watch!"
1276 Multiple tags may be placed on expressions with multiple
1277 @code{\tag} entries:
1279 @lilypond[quote,verbatim]
1280 music = \relative c'' {
1281 \tag #'a \tag #'both { a4 a a a }
1282 \tag #'b \tag #'both { b4 b b b }
1285 \keepWithTag #'a \music
1286 \keepWithTag #'b \music
1287 \keepWithTag #'both \music
1291 Multiple @code{\removeWithTag} filters may be applied to a single
1292 music expression to remove several differently named tagged sections:
1294 @lilypond[verbatim,quote]
1295 music = \relative c'' {
1296 \tag #'A { a4 a a a }
1297 \tag #'B { b4 b b b }
1298 \tag #'C { c4 c c c }
1299 \tag #'D { d4 d d d }
1308 Two or more @code{\keepWithTag} filters applied to a single music
1309 expression will cause @emph{all} tagged sections to be removed, as
1310 the first filter will remove all tagged sections except the one
1311 named, and the second filter will remove even that tagged section.
1316 @rlearning{Organizing pieces with variables}.
1319 @ref{Automatic part combining},
1320 @ref{Including LilyPond files}.
1324 @c This warning is more general than this placement implies.
1325 @c Rests are not merged whether or not they come from tagged sections.
1326 @c Should be deleted? -td
1330 Multiple rests are not merged if you create a score with more
1331 than one tagged section at the same place.
1335 @node Using global settings
1336 @unnumberedsubsubsec Using global settings
1338 @cindex include-settings
1340 Global settings can be incuded from a separate file:
1343 lilypond -dinclude-settings=MY_SETTINGS.ly MY_SCORE.ly
1346 Groups of settings such as page size, font or type face can be stored
1347 in separate files. This allows different editions from the same score
1348 as well as standard settings to be applied to many scores, simply by
1349 specifying the proper settings file.
1351 This technique also works well with the use of style sheets, as
1352 discussed in @rlearning{Style sheets}.
1356 @rlearning{Organizing pieces with variables},
1357 @rlearning{Style sheets}.
1360 @ref{Including LilyPond files}.
1363 @subsection Text encoding
1367 @cindex non-ASCII characters
1369 LilyPond uses the character repertoire defined by the Unicode
1370 consortium and ISO/IEC 10646. This defines a unique name and
1371 code point for the character sets used in virtually all modern
1372 languages and many others too. Unicode can be implemented using
1373 several different encodings. LilyPond uses the UTF-8 encoding
1374 (UTF stands for Unicode Transformation Format) which represents
1375 all common Latin characters in one byte, and represents other
1376 characters using a variable length format of up to four bytes.
1378 The actual appearance of the characters is determined by the
1379 glyphs defined in the particular fonts available - a font defines
1380 the mapping of a subset of the Unicode code points to glyphs.
1381 LilyPond uses the Pango library to layout and render multi-lingual
1384 LilyPond does not perform any input-encoding conversions. This
1385 means that any text, be it title, lyric text, or musical
1386 instruction containing non-ASCII characters, must be encoded in
1387 UTF-8. The easiest way to enter such text is by using a
1388 Unicode-aware editor and saving the file with UTF-8 encoding. Most
1389 popular modern editors have UTF-8 support, for example, vim, Emacs,
1390 jEdit, and GEdit do. All MS Windows systems later than NT use
1391 Unicode as their native character encoding, so even Notepad can
1392 edit and save a file in UTF-8 format. A more functional
1393 alternative for Windows is BabelPad.
1395 If a LilyPond input file containing a non-ASCII character is not
1396 saved in UTF-8 format the error message
1399 FT_Get_Glyph_Name () error: invalid argument
1404 Here is an example showing Cyrillic, Hebrew and Portuguese
1408 %c No verbatim here as the code does not display correctly in PDF
1410 bulgarian = \lyricmode {
1411 Жълтата дюля беше щастлива, че пухът, който цъфна, замръзна като гьон.
1415 hebrew = \lyricmode {
1416 זה כיף סתם לשמוע איך תנצח קרפד עץ טוב בגן.
1420 portuguese = \lyricmode {
1421 à vo -- cê uma can -- ção legal
1427 \addlyrics { \bulgarian }
1428 \addlyrics { \hebrew }
1429 \addlyrics { \portuguese }
1432 To enter a single character for which the Unicode code point is
1433 known but which is not available in the editor being used, use
1434 either @code{\char ##xhhhh} or @code{\char #dddd} within a
1435 @code{\markup} block, where @code{hhhh} is the hexadecimal code for
1436 the character required and @code{dddd} is the corresponding decimal
1437 value. Leading zeroes may be omitted, but it is usual to specify
1438 all four characters in the hexadecimal representation. (Note that
1439 the UTF-8 encoding of the code point should @emph{not} be used
1440 after @code{\char}, as UTF-8 encodings contain extra bits indicating
1441 the number of octets.) Unicode code charts and a character name
1442 index giving the code point in hexadecimal for any character can be
1443 found on the Unicode Consortium website,
1444 @uref{http://www.unicode.org/}.
1446 For example, @code{\char ##x03BE} and @code{\char #958} would both
1447 enter the Unicode U+03BE character, which has the Unicode name
1448 @qq{Greek Small Letter Xi}.
1450 Any Unicode code point may be entered in this way and if all special
1451 characters are entered in this format it is not necessary to save
1452 the input file in UTF-8 format. Of course, a font containing all
1453 such encoded characters must be installed and available to LilyPond.
1455 The following example shows Unicode hexadecimal values being entered
1456 in four places -- in a rehearsal mark, as articulation text, in
1457 lyrics and as stand-alone text below the score:
1459 @lilypond[quote,verbatim]
1462 c1 \mark \markup { \char ##x03EE }
1463 c1_\markup { \tiny { \char ##x03B1 " to " \char ##x03C9 } }
1465 \addlyrics { O \markup { \concat { Ph \char ##x0153 be! } } }
1467 \markup { "Copyright 2008--2011" \char ##x00A9 }
1470 @cindex copyright sign
1472 To enter the copyright sign in the copyright notice use:
1476 copyright = \markup @{ \char ##x00A9 "2008" @}
1480 @node Displaying LilyPond notation
1481 @subsection Displaying LilyPond notation
1483 @funindex \displayLilyMusic
1484 Displaying a music expression in LilyPond notation can be
1485 done with the music function @code{\displayLilyMusic} but only when
1486 using the command line. For example,
1490 \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
1497 @{ a,4 cis e fis g @}
1500 By default, LilyPond will print these messages to the console
1501 along with all the other LilyPond compilation messages. To split
1502 up these messages and save the results of @code{\display@{STUFF@}},
1503 redirect the output to a file.
1506 lilypond file.ly >display.txt
1511 @node Controlling output
1512 @section Controlling output
1515 * Extracting fragments of music::
1516 * Skipping corrected music::
1517 * Alternative output formats::
1518 * Replacing the notation font::
1521 @node Extracting fragments of music
1522 @subsection Extracting fragments of music
1524 It is possible to quote small fragments of a large score directly from
1525 the output. This can be compared to clipping a piece of a paper score
1528 This is done by defining the measures that need to be cut out
1529 separately. For example, including the following definition
1537 (make-rhythmic-location 5 1 2)
1538 (make-rhythmic-location 7 3 4)))
1543 will extract a fragment starting halfway the fifth measure, ending in
1544 the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note
1545 in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7.
1547 More clip regions can be defined by adding more pairs of
1548 rhythmic-locations to the list.
1550 In order to use this feature, LilyPond must be invoked with
1551 @code{-dclip-systems}. The clips are output as EPS files, and are
1552 converted to PDF and PNG if these formats are switched on as well.
1554 For more information on output formats, see @rprogram{Invoking lilypond}.
1556 @node Skipping corrected music
1557 @subsection Skipping corrected music
1560 @funindex skipTypesetting
1561 @funindex showFirstLength
1562 @funindex showLastLength
1564 When entering or copying music, usually only the music near the end (where
1566 are adding notes) is interesting to view and correct. To speed up
1567 this correction process, it is possible to skip typesetting of all but
1568 the last few measures. This is achieved by putting
1571 showLastLength = R1*5
1576 in your source file. This will render only the last 5 measures
1577 (assuming 4/4 time signature) of every @code{\score} in the input
1578 file. For longer pieces, rendering only a small part is often an order
1579 of magnitude quicker than rendering it completely. When working on the
1580 beginning of a score you have already typeset (e.g. to add a new part),
1581 the @code{showFirstLength} property may be useful as well.
1583 Skipping parts of a score can be controlled in a more fine-grained
1584 fashion with the property @code{Score.skipTypesetting}. When it is
1585 set, no typesetting is performed at all.
1587 This property is also used to control output to the MIDI file. Note that
1588 it skips all events, including tempo and instrument changes. You have
1591 @lilypond[quote,relative=2,ragged-right,verbatim]
1593 \set Score.skipTypesetting = ##t
1595 \set Score.skipTypesetting = ##f
1599 In polyphonic music, @code{Score.skipTypesetting} will affect all
1600 voices and staves, saving even more time.
1602 @node Alternative output formats
1603 @subsection Alternative output formats
1605 @cindex scalable vector graphics output
1607 @cindex encapsulated postscript output
1610 The default output formats for the printed score are Portable
1611 Document Format (PDF) and PostScript (PS). Scalable Vector
1612 Graphics (SVG), Encapsulated PostScript (EPS) and Portable
1613 Network Graphics (PNG) output formats are also available through
1614 command line options, see @rprogram{Command line options for
1618 @node Replacing the notation font
1619 @subsection Replacing the notation font
1621 Gonville is an alternative to the Feta font used in LilyPond and can
1624 @uref{http://www.chiark.greenend.org.uk/~sgtatham/gonville/ ,http://www.chiark.greenend.org.uk/~sgtatham/gonville/}
1627 Here are a few sample bars of music set in Gonville:
1629 @c NOTE: these images are a bit big, but that's important
1630 @c for the font comparison. -gp
1631 @sourceimage{Gonville_after,,,}
1633 Here are a few sample bars of music set in LilyPond's Feta font:
1635 @sourceimage{Gonville_before,,,}
1637 @subsubheading Installation Instructions for MacOS
1639 Download and extract the zip file. Copy the @code{lilyfonts}
1640 directory to @file{@var{SHARE_DIR}/lilypond/current}; for more
1641 information, see @rlearning{Other sources of information}.
1642 Move the existing @code{fonts} directory to @code{fonts_orig} and
1643 move the @code{lilyfonts} directory to @code{fonts}. Simply move
1644 @code{fonts_orig} back to @code{fonts} to revert back to Feta.
1647 Learning Manual: @rlearning{Other sources of information}.
1651 Gonville cannot be used to typeset @q{Ancient Music} notation. Please
1652 refer to the author's website for more information on this and other
1653 specifics including licensing of Gonville.
1657 @section MIDI output
1662 MIDI (Musical Instrument Digital Interface) is a standard for
1663 connecting and controlling digital instruments. A MIDI file is a
1664 series of notes in a number of tracks. It is not an actual
1665 sound file; you need special software to translate between the
1666 series of notes and actual sounds.
1668 Pieces of music can be converted to MIDI files, so you can listen to
1669 what was entered. This is convenient for checking the music; octaves
1670 that are off or accidentals that were mistyped stand out very much
1671 when listening to the MIDI output.
1674 The midi output allocates a channel for each staff, and one for global
1675 settings. Therefore the midi file should not have more than 15 staves
1676 (or 14 if you do not use drums). Other staves will remain silent.
1679 * Creating MIDI files::
1681 * What goes into the MIDI output?::
1683 * Controlling MIDI dynamics::
1684 * Percussion in MIDI::
1687 @node Creating MIDI files
1688 @subsection Creating MIDI files
1690 To create a MIDI output file from a LilyPond input file, add a
1691 @code{\midi} block to a score, for example,
1700 If there is a @code{\midi} block in a @code{\score} with no
1701 @code{\layout} block, only MIDI output will be produced. When
1702 notation is needed too, a @code{\layout} block must also be
1713 Pitches, rhythms, ties, dynamics, and tempo changes are interpreted
1714 and translated correctly to the MIDI output. Dynamic marks,
1715 crescendi and decrescendi translate into MIDI volume levels.
1716 Dynamic marks translate to a fixed fraction of the available MIDI
1717 volume range. Crescendi and decrescendi make the volume vary
1718 linearly between their two extremes. The effect of dynamic markings
1719 on the MIDI output can be removed completely, see @ref{MIDI block}.
1721 The initial tempo and later tempo changes can be specified
1722 with the @code{\tempo} command within the music notation. These
1723 are reflected in tempo changes in the MIDI output. This command
1724 will normally result in the metronome mark being printed, but this
1725 can be suppressed, see @ref{Metronome marks}. An alternative way
1726 of specifying the initial or overall MIDI tempo is described below,
1727 see @ref{MIDI block}.
1729 Due to some limitations on Windows, the default extension for
1730 MIDI files on Windows is @code{.mid}. Other operating systems still
1731 use the extension @code{.midi}. If a different extension is preferred,
1732 insert the following line at the top-level of the input file,
1733 before the start of any @code{\book}, @code{\bookpart} or @code{\score} blocks:
1736 #(ly:set-option 'midi-extension "midi")
1739 The line above will set the default extension for MIDI files to
1742 Alternatively, this option can also be supplied on the command line:
1745 lilypond … -dmidi-extension=midi lilyFile.ly
1749 @unnumberedsubsubsec Instrument names
1751 @cindex instrument names
1752 @funindex Staff.midiInstrument
1754 The MIDI instrument to be used is specified by setting the
1755 @code{Staff.midiInstrument} property to the instrument name.
1756 The name should be chosen from the list in @ref{MIDI instruments}.
1760 \set Staff.midiInstrument = #"glockenspiel"
1766 \new Staff \with @{midiInstrument = #"cello"@} @{
1771 If the selected instrument does not exactly match an instrument from
1772 the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
1778 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
1779 {changing-midi-output-to-one-channel-per-voice.ly}
1783 @c In 2.11 the following no longer seems to be a problem -td
1785 Unterminated (de)crescendos will not render properly in the midi file,
1786 resulting in silent passages of music. The workaround is to explicitly
1787 terminate the (de)crescendo. For example,
1794 will not work properly but
1797 @{ a4\< b c d\!\f @}
1804 Changes in the MIDI volume take place only on starting a note, so
1805 crescendi and decrescendi cannot affect the volume of a
1808 Not all midi players correctly handle tempo changes in the midi
1809 output. Players that are known to work include MS Windows Media
1810 Player and @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
1813 @subsection MIDI block
1816 A @code{\midi} block must appear within a score block if MIDI output
1817 is required. It is analogous to the layout block, but somewhat
1818 simpler. Often, the @code{\midi} block is left empty, but it
1819 can contain context rearrangements, new context definitions or code
1820 to set the values of properties. For example, the following will
1821 set the initial tempo exported to a MIDI file without causing a tempo
1822 indication to be printed:
1830 tempoWholesPerMinute = #(ly:make-moment 72 4)
1836 In this example the tempo is set to 72 quarter note
1837 beats per minute. This kind of tempo specification cannot take
1838 a dotted note length as an argument. If one is required, break
1839 the dotted note into smaller units. For example, a tempo of 90
1840 dotted quarter notes per minute can be specified as 270 eighth
1844 tempoWholesPerMinute = #(ly:make-moment 270 8)
1847 @cindex MIDI context definitions
1849 Context definitions follow precisely the same syntax as those
1850 within a @code{\layout} block. Translation modules for sound are
1851 called performers. The contexts for MIDI output are defined in
1852 @file{../ly/performer-init.ly},
1853 see @rlearning{Other sources of information}.
1854 For example, to remove the effect of dynamics
1855 from the MIDI output, insert the following lines in the
1856 @code{\midi@{ @}} block.
1863 \remove "Dynamic_performer"
1868 MIDI output is created only when a @code{\midi} block is included
1869 within a score block defined with a @code{\score} command.
1873 @{ @dots{}notes@dots{} @}
1878 @node What goes into the MIDI output?
1879 @subsection What goes into the MIDI output?
1881 @c TODO Check grace notes - timing is suspect?
1883 @unnumberedsubsubsec Supported in MIDI
1885 @cindex Pitches in MIDI
1886 @cindex MIDI, Pitches
1887 @cindex Quarter tones in MIDI
1888 @cindex MIDI, quarter tones
1889 @cindex Microtones in MIDI
1890 @cindex MIDI, microtones
1891 @cindex Chord names in MIDI
1892 @cindex MIDI, chord names
1893 @cindex Rhythms in MIDI
1894 @cindex MIDI, Rhythms
1897 The following items of notation are reflected in the MIDI output:
1901 @item Microtones (See @ref{Accidentals}. Rendering needs a
1902 player that supports pitch bend.)
1903 @item Chords entered as chord names
1904 @item Rhythms entered as note durations, including tuplets
1905 @item Tremolos entered without @q{@code{:}[@var{number}]}
1908 @item Crescendi, decrescendi over multiple notes
1909 @item Tempo changes entered with a tempo marking
1913 @unnumberedsubsubsec Unsupported in MIDI
1915 @c TODO index as above
1917 The following items of notation have no effect on the MIDI output:
1920 @item Rhythms entered as annotations, e.g. swing
1921 @item Tempo changes entered as annotations with no tempo marking
1922 @item Staccato and other articulations and ornamentations
1923 @item Slurs and Phrasing slurs
1924 @item Crescendi, decrescendi over a single note
1925 @item Tremolos entered with @q{@code{:}[@var{number}]}
1927 @item Microtonal chords
1931 @node Repeats in MIDI
1932 @subsection Repeats in MIDI
1934 @cindex repeats in MIDI
1935 @funindex \unfoldRepeats
1937 With a few minor additions, all types of repeats can be represented
1938 in the MIDI output. This is achieved by applying the
1939 @code{\unfoldRepeats} music function. This function changes all
1940 repeats to unfold repeats.
1942 @lilypond[quote,verbatim]
1944 \repeat tremolo 8 { c'32 e' }
1945 \repeat percent 2 { c''8 d'' }
1946 \repeat volta 2 { c'4 d' e' f' }
1955 When creating a score file using @code{\unfoldRepeats} for MIDI,
1956 it is necessary to make two @code{\score} blocks: one for MIDI
1957 (with unfolded repeats) and one for notation (with volta, tremolo,
1958 and percent repeats). For example,
1966 \unfoldRepeats @var{..music..}
1971 @node Controlling MIDI dynamics
1972 @subsection Controlling MIDI dynamics
1974 MIDI dynamics are implemented by the Dynamic_performer which lives
1975 by default in the Voice context. It is possible to control the
1976 overall MIDI volume, the relative volume of dynamic markings and
1977 the relative volume of different instruments.
1979 @unnumberedsubsubsec Dynamic marks
1981 Dynamic marks are translated to a fixed fraction of the available
1982 MIDI volume range. The default fractions range from 0.25 for
1983 @notation{ppppp} to 0.95 for @notation{fffff}. The set of dynamic
1984 marks and the associated fractions can be seen in
1985 @file{../scm/midi.scm}, see @rlearning{Other sources of information}.
1986 This set of fractions may be changed or extended by providing a
1987 function which takes a dynamic mark as its argument and returns the
1988 required fraction, and setting
1989 @code{Score.dynamicAbsoluteVolumeFunction} to this function.
1991 For example, if a @notation{rinforzando} dynamic marking,
1992 @code{\rfz}, is required, this will not by default
1993 have any effect on the MIDI volume, as this dynamic marking is not
1994 included in the default set. Similarly, if a new dynamic marking
1995 has been defined with @code{make-dynamic-script} that too will not
1996 be included in the default set. The following example shows how the
1997 MIDI volume for such dynamic markings might be added. The Scheme
1998 function sets the fraction to 0.9 if a dynamic mark of rfz is
1999 found, or calls the default function otherwise.
2001 @lilypond[verbatim,quote]
2002 #(define (myDynamics dynamic)
2003 (if (equal? dynamic "rfz")
2005 (default-dynamic-absolute-volume dynamic)))
2009 \set Staff.midiInstrument = #"cello"
2010 \set Score.dynamicAbsoluteVolumeFunction = #myDynamics
2022 Alternatively, if the whole table of fractions needs to be
2023 redefined, it would be better to use the
2024 @notation{default-dynamic-absolute-volume} procedure in
2025 @file{../scm/midi.scm} and the associated table as a model.
2026 The final example in this section shows how this might be done.
2028 @unnumberedsubsubsec Overall MIDI volume
2030 The minimum and maximum overall volume of MIDI dynamic markings is
2031 controlled by setting the properties @code{midiMinimumVolume} and
2032 @code{midiMaximumVolume} at the @code{Score} level. These
2033 properties have an effect only on dynamic marks, so if they
2034 are to apply from the start of the score a dynamic mark must be
2035 placed there. The fraction corresponding to each dynamic mark is
2036 modified with this formula
2039 midiMinimumVolume + (midiMaximumVolume - midiMinimumVolume) * fraction
2042 In the following example the dynamic range of the overall MIDI
2043 volume is limited to the range 0.2 - 0.5.
2045 @lilypond[verbatim,quote]
2051 \set Staff.midiInstrument = #"flute"
2052 \new Voice \relative c''' {
2060 \set Staff.midiInstrument = #"clarinet"
2061 \new Voice \relative c'' {
2072 tempoWholesPerMinute = #(ly:make-moment 72 2)
2073 midiMinimumVolume = #0.2
2074 midiMaximumVolume = #0.5
2080 @unnumberedsubsubsec Equalizing different instruments (i)
2082 If the minimum and maximum MIDI volume properties are set in
2083 the @code{Staff} context the relative volumes of the MIDI
2084 instruments can be controlled. This gives a basic instrument
2085 equalizer, which can enhance the quality of the MIDI output
2088 In this example the volume of the clarinet is reduced relative
2089 to the volume of the flute. There must be a dynamic
2090 mark on the first note of each instrument for this to work
2093 @lilypond[verbatim,quote]
2099 \set Staff.midiInstrument = #"flute"
2100 \set Staff.midiMinimumVolume = #0.7
2101 \set Staff.midiMaximumVolume = #0.9
2102 \new Voice \relative c''' {
2110 \set Staff.midiInstrument = #"clarinet"
2111 \set Staff.midiMinimumVolume = #0.3
2112 \set Staff.midiMaximumVolume = #0.6
2113 \new Voice \relative c'' {
2124 tempoWholesPerMinute = #(ly:make-moment 72 2)
2130 @unnumberedsubsubsec Equalizing different instruments (ii)
2132 If the MIDI minimum and maximum volume properties are not set
2133 LilyPond will, by default, apply a small degree of equalization
2134 to a few instruments. The instruments and the equalization
2135 applied are shown in the table @notation{instrument-equalizer-alist}
2136 in @file{../scm/midi.scm}.
2138 This basic default equalizer can be replaced by setting
2139 @code{instrumentEqualizer} in the @code{Score} context to a new
2140 Scheme procedure which accepts a MIDI instrument name as its only
2141 argument and returns a pair of fractions giving the minimum and
2142 maximum volumes to be applied to that instrument. This replacement
2143 is done in the same way as shown for resetting the
2144 @code{dynamicAbsoluteVolumeFunction} at the start of this section.
2145 The default equalizer, @notation{default-instrument-equalizer}, in
2146 @file{../scm/midi.scm} shows how such a procedure might be written.
2148 The following example sets the relative flute and clarinet volumes
2149 to the same values as the previous example.
2151 @lilypond[verbatim,quote]
2152 #(define my-instrument-equalizer-alist '())
2154 #(set! my-instrument-equalizer-alist
2157 ("flute" . (0.7 . 0.9))
2158 ("clarinet" . (0.3 . 0.6)))
2159 my-instrument-equalizer-alist))
2161 #(define (my-instrument-equalizer s)
2162 (let ((entry (assoc s my-instrument-equalizer-alist)))
2171 \set Score.instrumentEqualizer = #my-instrument-equalizer
2172 \set Staff.midiInstrument = #"flute"
2173 \new Voice \relative c''' {
2181 \set Staff.midiInstrument = #"clarinet"
2182 \new Voice \relative c'' {
2193 tempoWholesPerMinute = #(ly:make-moment 72 2)
2200 @c Delete when satisfied this is adequately covered elsewhere -td
2202 @n ode Microtones in MIDI
2203 @s ubsection Microtones in MIDI
2205 @cindex microtones in MIDI
2207 Microtones consisting of half sharps and half flats are exported
2208 to the MIDI file and render correctly in MIDI players which support
2209 pitch bending. See @ref{Note names in other languages}. Here is
2210 an example showing all the half sharps and half flats. It can be
2211 copied out and compiled to test microtones in your MIDI player.
2213 @lilypond[verbatim,quote]
2230 @node Percussion in MIDI
2231 @subsection Percussion in MIDI
2233 Percussion instruments are generally notated in a @code{DrumStaff}
2234 context and when notated in this way they are outputted correctly
2235 to MIDI channel@tie{}10, but some pitched percussion instruments,
2236 like the xylophone, marimba, vibraphone, timpani, etc., are
2237 treated like @qq{normal} instruments and music for these instruments
2238 should be entered in a normal @code{Staff} context, not a
2239 @code{DrumStaff} context, to obtain the correct MIDI output.
2241 Some non-pitched percussion sounds included in the general MIDI
2242 standard, like melodic tom, taiko drum, synth drum, etc., cannot
2243 be reached via MIDI channel@tie{}10, so the notation for such
2244 instruments should also be entered in a normal @code{Staff}
2245 context, using suitable normal pitches.
2247 Many percussion instruments are not included in the general MIDI
2248 standard, e.g. castanets. The easiest, although unsatisfactory,
2249 method of producing some MIDI output when writing for such
2250 instruments is to substitute the nearest sound from the standard
2253 @c TODO Expand with examples, and any other issues
2257 Because the general MIDI standard does not contain rim shots, the
2258 sidestick is used for this purpose instead.