1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond.tely
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. See TRANSLATION for details.
15 This section deals with general LilyPond input syntax issues,
16 rather than specific notation.
20 * Titles and headers::
21 * Working with input files::
22 * Controlling output::
28 @section Input structure
30 The main format of input for LilyPond are text files. By convention,
31 these files end with @code{.ly}.
34 * Structure of a score::
35 * Multiple scores in a book::
40 @node Structure of a score
41 @subsection Structure of a score
45 A @code{\score} block must contain a single music expression
46 delimited by curly brackets:
54 @warning{There must be @strong{only one} outer music expression in
55 a @code{\score} block, and it @strong{must} be surrounded by
58 This single music expression may be of any size, and may contain
59 other music expressions to any complexity. All of these examples
60 are music expressions:
66 @lilypond[verbatim,quote]
73 @lilypond[verbatim,quote]
75 \new Staff { c'4 c' c' c' }
76 \new Staff { d'4 d' d' d' }
84 \new Staff @{ \flute @}
85 \new Staff @{ \oboe @}
88 \new Staff @{ \violinI @}
89 \new Staff @{ \violinII @}
95 Comments are one exception to this general rule. (For others see
96 @ref{File structure}.) Both single-line comments and comments
97 delimited by @code{%@{ .. %@}} may be placed anywhere within an
98 input file. They may be placed inside or outside a @code{\score}
99 block, and inside or outside the single music expression within a
106 @rlearning{Working on input files},
107 @rlearning{Music expressions explained},
108 @rlearning{Score is a (single) compound musical expression}.
111 @node Multiple scores in a book
112 @subsection Multiple scores in a book
115 @cindex movements, multiple
117 A document may contain multiple pieces of music and text. Examples
118 of these are an etude book, or an orchestral part with multiple
119 movements. Each movement is entered with a @code{\score} block,
127 and texts are entered with a @code{\markup} block,
137 All the movements and texts which appear in the same @code{.ly} file
138 will normally be typeset in the form of a single output file.
152 However, if you want multiple output files from the same @code{.ly}
153 file, then you can add multiple @code{\book} blocks, where each such
154 @code{\book} block will result in a separate output. If you do not
155 specify any @code{\book} block in the file, LilyPond will implicitly
156 treat the full file as a single @code{\book} block, see @ref{File
157 structure}. One important exception is within lilypond-book documents,
158 where you explicitly have to add a @code{\book} block, otherwise only
159 the first @code{\score} or @code{\markup} will appear in the output.
161 The header for each piece of music can be put inside the @code{\score}
162 block. The @code{piece} name from the header will be printed before
163 each movement. The title for the entire book can be put inside the
164 @code{\book}, but if it is not present, the @code{\header} which is at
165 the top of the file is inserted.
169 title = "Eight miniatures"
170 composer = "Igor Stravinsky"
174 \header @{ piece = "Romanze" @}
177 ..text of second verse..
180 ..text of third verse..
184 \header @{ piece = "Menuetto" @}
189 @subsection File structure
198 A @code{.ly} file may contain any number of toplevel expressions, where a
199 toplevel expression is one of the following:
203 An output definition, such as @code{\paper}, @code{\midi}, and
204 @code{\layout}. Such a definition at the toplevel changes the default
205 book-wide settings. If more than one such definition of
206 the same type is entered at the top level any definitions in the later
207 expressions have precedence.
210 A direct scheme expression, such as
211 @code{#(set-default-paper-size "a7" 'landscape)} or
212 @code{#(ly:set-option 'point-and-click #f)}.
215 A @code{\header} block. This sets the global header block. This
216 is the block containing the definitions for book-wide settings, like
217 composer, title, etc.
220 A @code{\score} block. This score will be collected with other
221 toplevel scores, and combined as a single @code{\book}.
222 This behavior can be changed by setting the variable
223 @code{toplevel-score-handler} at toplevel. The default handler is
224 defined in the init file @file{scm/@/lily@/.scm}.
227 A @code{\book} block logically combines multiple movements
228 (i.e., multiple @code{\score} blocks) in one document. If there
229 are a number of @code{\score}s, one output file will be created
230 for each @code{\book} block, in which all corresponding movements
231 are concatenated. The only reason to explicitly specify
232 @code{\book} blocks in a @code{.ly} file is if you wish to create
233 multiple output files from a single input file. One exception is
234 within lilypond-book documents, where you explicitly have to add
235 a @code{\book} block if you want more than a single @code{\score}
236 or @code{\markup} in the same example. This behavior can be
237 changed by setting the variable @code{toplevel-book-handler} at
238 toplevel. The default handler is defined in the init file
239 @file{scm/@/lily@/.scm}.
242 A compound music expression, such as
247 This will add the piece in a @code{\score} and format it in a
248 single book together with all other toplevel @code{\score}s and music
249 expressions. In other words, a file containing only the above
250 music expression will be translated into
266 This behavior can be changed by setting the variable
267 @code{toplevel-music-handler} at toplevel. The default handler is
268 defined in the init file @file{scm/@/lily@/.scm}.
271 A markup text, a verse for example
274 2. The first line verse two.
278 Markup texts are rendered above, between or below the scores or music
279 expressions, wherever they appear.
289 This can be used later on in the file by entering @code{\foo}. The
290 name of an variable should have alphabetic characters only; no
291 numbers, underscores or dashes.
295 The following example shows three things that may be entered at
300 % Don't justify the output
312 At any point in a file, any of the following lexical instructions can
316 @item @code{\version}
317 @item @code{\include}
318 @item @code{\sourcefilename}
319 @item @code{\sourcefileline}
321 A single-line comment, introduced by a leading @code{%} sign.
324 A multi-line comment delimited by @code{%@{ .. %@}}.
331 @rlearning{How LilyPond input files work}.
333 @node Titles and headers
334 @section Titles and headers
336 Almost all printed music includes a title and the composer's name;
337 some pieces include a lot more information.
342 * Reference to page numbers::
343 * Table of contents::
347 @node Creating titles
348 @subsection Creating titles
350 Titles are created for each @code{\score} block, as well as for the full
351 input file (or @code{\book} block).
353 The contents of the titles are taken from the @code{\header} blocks.
354 The header block for a book supports the following
360 The dedicatee of the music, centered at the top of the first page.
364 The title of the music, centered just below the dedication.
368 Subtitle, centered below the title.
370 @funindex subsubtitle
372 Subsubtitle, centered below the subtitle.
376 Name of the poet, flush-left below the subtitle.
380 Name of the composer, flush-right below the subtitle.
384 Meter string, flush-left below the poet.
388 Name of the opus, flush-right below the composer.
392 Name of the arranger, flush-right below the opus.
396 Name of the instrument, centered below the arranger. Also
397 centered at the top of pages (other than the first page).
401 Name of the piece, flush-left below the instrument.
403 @cindex page breaks, forcing
404 @funindex breakbefore
406 This forces the title to start on a new page (set to ##t or ##f).
410 Copyright notice, centered at the bottom of the first page. To
411 insert the copyright symbol, see @ref{Text encoding}.
415 Centered at the bottom of the last page.
419 Here is a demonstration of the fields available. Note that you
420 may use any @ref{Formatting text}, commands in the header.
422 @lilypond[quote,verbatim,line-width=11.0\cm]
425 paper-height = 10.0\cm
430 dedication = "dedicated to me"
431 title = \markup \center-align { "Title first line" "Title second line,
433 subtitle = "the subtitle,"
434 subsubtitle = #(string-append "subsubtitle LilyPond version "
437 composer = \markup \center-align { "composer" \small "(1847-1973)" }
438 texttranslator = "Text Translator"
439 meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
441 arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize
442 #-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }
443 instrument = \markup \bold \italic "instrument"
467 As demonstrated before, you can use multiple @code{\header} blocks.
468 When same fields appear in different blocks, the latter is used.
469 Here is a short example.
473 composer = "Composer"
481 piece = "New piece" % overwrite previous one
486 If you define the @code{\header} inside the @code{\score} block, then
487 normally only the @code{piece} and @code{opus} headers will be printed.
488 Note that the music expression must come before the @code{\header}.
490 @lilypond[quote,verbatim,line-width=11.0\cm]
494 title = "title" % not printed
501 @funindex printallheaders
503 You may change this behavior (and print all the headers when defining
504 @code{\header} inside @code{\score}) by using
515 The default footer is empty, except for the first page, where the
516 @code{copyright} field from @code{\header} is inserted, and the last
517 page, where @code{tagline} from @code{\header} is added. The default
518 tagline is @qq{Music engraving by LilyPond (@var{version})}.@footnote{Nicely
519 printed parts are good PR for us, so please leave the tagline if you
522 Headers may be completely removed by setting them to false.
533 @subsection Custom titles
535 A more advanced option is to change the definitions of the following
536 variables in the @code{\paper} block. The init file
537 @file{ly/titling-init.ly} lists the default layout.
540 @funindex bookTitleMarkup
541 @item bookTitleMarkup
542 This is the title added at the top of the entire output document.
543 Typically, it has the composer and the title of the piece
545 @funindex scoreTitleMarkup
546 @item scoreTitleMarkup
547 This is the title put over a @code{\score} block. Typically, it has
548 the name of the movement (@code{piece} field).
550 @funindex oddHeaderMarkup
551 @item oddHeaderMarkup
552 This is the page header for odd-numbered pages.
554 @funindex evenHeaderMarkup
555 @item evenHeaderMarkup
556 This is the page header for even-numbered pages. If unspecified,
557 the odd header is used instead.
559 By default, headers are defined such that the page number is on the
560 outside edge, and the instrument is centered.
562 @funindex oddFooterMarkup
563 @item oddFooterMarkup
564 This is the page footer for odd-numbered pages.
566 @funindex evenFooterMarkup
567 @item evenFooterMarkup
568 This is the page footer for even-numbered pages. If unspecified,
569 the odd header is used instead.
571 By default, the footer has the copyright notice on the first, and
572 the tagline on the last page.
582 The following definition will put the title flush left, and the
583 composer flush right on a single line.
587 bookTitleMarkup = \markup {
589 \fromproperty #'header:title
590 \fromproperty #'header:composer
596 @node Reference to page numbers
597 @subsection Reference to page numbers
599 A particular place of a score can be marked using the @code{\label}
600 command, either at top-level or inside music. This label can then be
601 referred to in a markup, to get the number of the page where the marked
602 point is placed, using the @code{\page-ref} markup command.
604 @lilypond[verbatim,line-width=11.0\cm]
605 \header { tagline = ##f }
611 \pageBreak \mark A \label #'markA
616 \markup { The first score begins on page \page-ref #'firstScore "0" "?" }
617 \markup { Mark A is on page \page-ref #'markA "0" "?" }
621 The @code{\page-ref} markup command takes three arguments:
623 @item the label, a scheme symbol, eg. @code{#'firstScore};
624 @item a markup that will be used as a gauge to estimate the dimensions
626 @item a markup that will be used in place of the page number if the label
630 The reason why a gauge is needed is that, at the time markups are
631 interpreted, the page breaking has not yet occurred, so the page numbers
632 are not yet known. To work around this issue, the actual markup
633 interpretation is delayed to a later time; however, the dimensions of
634 the markup have to be known before, so a gauge is used to decide these
635 dimensions. If the book has between 10 and 99 pages, it may be "00",
636 ie. a two digit number.
645 @node Table of contents
646 @subsection Table of contents
647 A table of contents is included using the @code{\markuplines \table-of-contents}
648 command. The elements which should appear in the table of contents are
649 entered with the @code{\tocItem} command, which may be used either at
650 top-level, or inside a music expression.
653 \markuplines \table-of-contents
656 \tocItem \markup "First score"
660 \tocItem \markup "Some particular point in the first score"
665 \tocItem \markup "Second score"
673 The markups which are used to format the table of contents are defined
674 in the @code{\paper} block. The default ones are @code{tocTitleMarkup},
675 for formatting the title of the table, and @code{tocItemMarkup}, for
676 formatting the toc elements, composed of the element title and page
677 number. These variables may be changed by the user:
681 %% Translate the toc title into French:
682 tocTitleMarkup = \markup \huge \column {
683 \fill-line { \null "Table des matières" \null }
686 %% use larger font size
687 tocItemMarkup = \markup \large \fill-line {
688 \fromproperty #'toc:text \fromproperty #'toc:page
693 Note how the toc element text and page number are referred to in
694 the @code{tocItemMarkup} definition.
696 New commands and markups may also be defined to build more elaborated
699 @item first, define a new markup variable in the @code{\paper} block
700 @item then, define a music function which aims at adding a toc element
701 using this markup paper variable.
704 In the following example, a new style is defined for entering act names
705 in the table of contents of an opera:
709 tocActMarkup = \markup \large \column {
711 \fill-line { \null \italic \fromproperty #'toc:text \null }
717 #(define-music-function (parser location text) (markup?)
718 (add-toc-item! 'tocActMarkup text))
721 @lilypond[line-width=11.0\cm]
722 \header { tagline = ##f }
724 tocActMarkup = \markup \large \column {
726 \fill-line { \null \italic \fromproperty #'toc:text \null }
732 #(define-music-function (parser location text) (markup?)
733 (add-toc-item! 'tocActMarkup text))
736 \markuplines \table-of-contents
737 \tocAct \markup { Atto Primo }
738 \tocItem \markup { Coro. Viva il nostro Alcide }
739 \tocItem \markup { Cesare. Presti omai l'Egizzia terra }
740 \tocAct \markup { Atto Secondo }
741 \tocItem \markup { Sinfonia }
742 \tocItem \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
749 Init files: @file{ly/@/toc@/-init@/.ly}.
753 @funindex \table-of-contents
754 @code{\table-of-contents}
759 @node Working with input files
760 @section Working with input files
763 * Including LilyPond files::
764 * Different editions from one source::
766 * Displaying LilyPond notation::
770 @node Including LilyPond files
771 @subsection Including LilyPond files
774 @cindex including files
776 A large project may be split up into separate files. To refer to
780 \include "otherfile.ly"
783 The line @code{\include "otherfile.ly"} is equivalent to pasting the
784 contents of @file{otherfile.ly} into the current file at the place
785 where the @code{\include} appears. For example, in a large
786 project you might write separate files for each instrument part
787 and create a @qq{full score} file which brings together the
788 individual instrument files. Normally the included file will
789 define a number of variables which then become available
790 for use in the full score file. Tagged sections can be
791 marked in included files to assist in making them usable in
792 different places in a score, see @ref{Different editions from
795 Files in the current working directory may be referenced by
796 specifying just the file name after the @code{\include} command.
797 Files in other locations may be included by giving either a full
798 path reference or a relative path reference (but use the UNIX
799 forward slash, /, rather than the DOS/Windows back slash, \, as the
800 directory separator.) For example, if @file{stuff.ly} is located
801 one directory higher than the current working directory, use
804 \include "../stuff.ly"
808 or if the included orchestral parts files are all located in a
809 subdirectory called @file{parts} within the current directory, use
812 \include "parts/VI.ly"
813 \include "parts/VII.ly"
817 Files which are to be included can also contain @code{\include}
818 statements of their own. These second-level
819 @code{\include} statements are not interpreted until they have
820 been brought into the main file, so the file names they specify
821 must all be relative to the directory containing the main file,
822 not the directory containing the included file.
824 Files can also be included from a directory in a search path
825 specified as an option when invoking LilyPond from the command
826 line. The included files are then specified using just their
827 file name. For example, to compile @file{main.ly} which includes
828 files located in a subdirectory called @file{parts} by this method,
829 cd to the directory containing @file{main.ly} and enter
832 lilypond --include=parts main.ly
843 Files which are to be included in many scores may be placed in
844 the LilyPond directory @file{../ly}. (The location of this
845 directory is installation-dependent - see @rlearning{Other sources
846 of information}). These files can then be included simply by
847 naming them on an @code{\include} statement. This is how the
848 language-dependent files like @file{english.ly} are included.
850 LilyPond includes a number of files by default when you start
851 the program. These includes are not apparent to the user, but the
852 files may be identified by running @code{lilypond --verbose} from
853 the command line. This will display a list of paths and files that
854 LilyPond uses, along with much other information. Alternatively,
855 the more important of these files are discussed in @rlearning{Other
856 sources of information}. These files may be edited, but changes to
857 them will be lost on installing a new version of LilyPond.
859 Some simple examples of using @code{\include} are shown in
860 @rlearning{Scores and parts}.
864 @rlearning{Other sources of information},
865 @rlearning{Scores and parts}.
869 If an included file is given a name which is the same as one in
870 LilyPond's installation files, LilyPond's file from the
871 installation files takes precedence.
875 @node Different editions from one source
876 @subsection Different editions from one source
878 Several mechanisms are available to facilitate the generation
879 of different versions of a score from the same music source.
880 Variables are perhaps most useful for combining lengthy sections
881 of music and/or annotation in various ways, while tags are more
882 useful for selecting one from several alternative shorter sections
883 of music. Whichever method is used, separating the notation from
884 the structure of the score will make it easier to change the
885 structure while leaving the notation untouched.
892 @node Using variables
893 @unnumberedsubsubsec Using variables
895 @cindex variables, use of
897 If sections of the music are defined in variables they can be
898 reused in different parts of the score, see @rlearning{Organizing
899 pieces with variables}. For example, an @notation{a cappella}
900 vocal score frequently includes a piano reduction of the parts
901 for rehearsal purposes which is identical to the vocal music, so
902 the music need be entered only once. Music from two variables
903 may be combined on one staff, see @ref{Automatic part combining}.
906 @lilypond[verbatim,quote]
907 sopranoMusic = \relative c'' { a4 b c b8( a)}
908 altoMusic = \relative g' { e4 e e f }
909 tenorMusic = \relative c' { c4 b e d8( c) }
910 bassMusic = \relative c' { a4 gis a d, }
911 allLyrics = \lyricmode {King of glo -- ry }
913 \new Staff = "Soprano" \sopranoMusic
914 \new Lyrics \allLyrics
915 \new Staff = "Alto" \altoMusic
916 \new Lyrics \allLyrics
917 \new Staff = "Tenor" {
921 \new Lyrics \allLyrics
922 \new Staff = "Bass" {
926 \new Lyrics \allLyrics
929 \set Staff.printPartCombineTexts = ##f
935 \set Staff.printPartCombineTexts = ##f
945 Separate scores showing just the vocal parts or just the piano
946 part can be produced by changing just the structural statements,
947 leaving the musical notation unchanged.
949 For lengthy scores, the variable definitions may be placed in
950 separate files which are then included, see @ref{Including
954 @unnumberedsubsubsec Using tags
957 @funindex \keepWithTag
958 @funindex \removeWithTag
960 @cindex keep tagged music
961 @cindex remove tagged music
963 The @code{\tag #'@var{partA}} command marks a music expression
964 with the name @var{partA}.
965 Expressions tagged in this way can be selected or filtered out by
966 name later, using either @code{\keepWithTag #'@var{name}} or
967 @code{\removeWithTag #'@var{name}}. The result of applying these filters
968 to tagged music is as follows:
969 @multitable @columnfractions .5 .5
973 Tagged music preceded by @code{\keepWithTag #'@var{name}}
974 @tab Untagged music and music tagged with @var{name} is included;
975 music tagged with any other tag name is excluded.
977 Tagged music preceded by @code{\removeWithTag #'@var{name}}
978 @tab Untagged music and music tagged with any tag name other than
979 @var{name} is included; music tagged with @var{name} is
982 Tagged music not preceded by either @code{\keepWithTag} or
983 @code{\removeWithTag}
984 @tab All tagged and untagged music is included.
987 The arguments of the @code{\tag}, @code{\keepWithTag} and
988 @code{\removeWithTag} commands should be a symbol
989 (such as @code{#'score} or @code{#'part}), followed
990 by a music expression.
992 In the following example, we see two versions of a piece of music,
993 one showing trills with the usual notation, and one with trills
996 @lilypond[verbatim,quote]
997 music = \relative g' {
999 \tag #'trills {d8.\trill }
1000 \tag #'expand {\repeat unfold 3 {e32 d} }
1005 \keepWithTag #'trills \music
1008 \keepWithTag #'expand \music
1013 Alternatively, it is sometimes easier to exclude sections of music:
1015 @lilypond[verbatim,quote]
1016 music = \relative g' {
1018 \tag #'trills {d8.\trill }
1019 \tag #'expand {\repeat unfold 3 {e32 d} }
1024 \removeWithTag #'expand
1028 \removeWithTag #'trills
1033 Tagged filtering can be applied to articulations, texts, etc. by
1037 -\tag #'@var{your-tag}
1040 to an articulation. For example, this would define a note with a
1041 conditional fingering indication and a note with a conditional
1046 c1-\tag #'warn ^"Watch!"
1049 Multiple tags may be placed on expressions with multiple
1050 @code{\tag} entries:
1052 @lilypond[quote,verbatim]
1053 music = \relative c'' {
1054 \tag #'a \tag #'both { a a a a }
1055 \tag #'b \tag #'both { b b b b }
1058 \keepWithTag #'a \music
1059 \keepWithTag #'b \music
1060 \keepWithTag #'both \music
1064 Multiple @code{\removeWithTag} filters may be applied to a single
1065 music expression to remove several differently named tagged sections:
1067 @lilypond[verbatim,quote]
1068 music = \relative c'' {
1069 \tag #'A { a a a a }
1070 \tag #'B { b b b b }
1071 \tag #'C { c c c c }
1072 \tag #'D { d d d d }
1081 Two or more @code{\keepWithTag} filters applied to a single music
1082 expression will cause @emph{all} tagged sections to be removed, as
1083 the first filter will remove all tagged sections except the one
1084 named, and the second filter will remove even that tagged section.
1089 @rlearning{Organizing pieces with variables}.
1092 @ref{Automatic part combining},
1093 @ref{Including LilyPond files}.
1096 @c This warning is more general than this placement implies.
1097 @c Rests are not merged whether or not they come from tagged sections.
1098 @c Should be deleted? -td
1102 Multiple rests are not merged if you create a score with more
1103 than one tagged section at the same place.
1108 @subsection Text encoding
1110 LilyPond uses the character repertoire defined by the Unicode
1111 consortium and ISO/IEC 10646. This defines a unique name and
1112 code point for the character sets used in virtually all modern
1113 languages and many others too. Unicode can be implemented using
1114 several different encodings. LilyPond uses the UTF-8 encoding
1115 (UTF stands for Unicode Transformation Format) which represents
1116 all common Latin characters in one byte, and represents other
1117 characters using a variable length format of up to four bytes.
1119 The actual appearance of the characters is determined by the
1120 glyphs defined in the particular fonts available - a font defines
1121 the mapping of a subset of the Unicode code points to glyphs.
1122 LilyPond uses the Pango library to layout and render multi-lingual
1125 Lilypond does not perform any input-encoding conversions. This
1126 means that any text, be it title, lyric text, or musical
1127 instruction containing non-ASCII characters, must be encoded in
1128 UTF-8. The easiest way to enter such text is by using a
1129 Unicode-aware editor and saving the file with UTF-8 encoding. Most
1130 popular modern editors have UTF-8 support, for example, vim, Emacs,
1131 jEdit, and GEdit do. All MS Windows systems later than NT use
1132 Unicode as their native character encoding, so even Notepad can
1133 edit and save a file in UTF-8 format. A more functional
1134 alternative for Windows is BabelPad.
1136 If a LilyPond input file containing a non-ASCII character is not
1137 saved in UTF-8 format the error message
1140 FT_Get_Glyph_Name () error: invalid argument
1145 Here is an example showing Cyrillic, Hebrew and Portuguese
1148 @lilypond[verbatim,quote]
1150 bulgarian = \lyricmode {
1151 Жълтата дюля беше щастлива, че пухът, който цъфна, замръзна като гьон.
1155 hebrew = \lyricmode {
1156 זה כיף סתם לשמוע איך תנצח קרפד עץ טוב בגן.
1160 portuguese = \lyricmode {
1161 à vo -- cê uma can -- ção legal
1167 \addlyrics { \bulgarian }
1168 \addlyrics { \hebrew }
1169 \addlyrics { \portuguese }
1172 To enter a single character for which the Unicode escape sequence
1173 is known but which is not available in the editor being used, enter
1176 #(ly:export (ly:wide-char->utf-8 #x03BE))
1179 where in this example @code{x03BE} is the hexadecimal code for the
1180 Unicode U+03BE character, which has the Unicode name @qq{Greek Small
1181 Letter Xi}. Any Unicode hexadecimal code may be substituted, and
1182 if all special characters are entered in this format it is not
1183 necessary to save the input file in UTF-8 format.
1187 The @code{ly:export} format may be used in text within @code{\mark} or
1188 @code{\markup} commands but not in lyrics.
1190 @node Displaying LilyPond notation
1191 @subsection Displaying LilyPond notation
1193 @funindex \displayLilyMusic
1194 Displaying a music expression in LilyPond notation can be
1195 done using the music function @code{\displayLilyMusic}. For example,
1199 \displayLilyMusic \transpose c a, @{ c e g a bes @}
1206 @{ a, cis e fis g @}
1209 By default, LilyPond will print these messages to the console along
1210 with all the other messages. To split up these messages and save
1211 the results of @code{\display@{STUFF@}}, redirect the output to
1214 @c TODO What happens under Windows?
1217 lilypond file.ly >display.txt
1222 @node Controlling output
1223 @section Controlling output
1226 * Extracting fragments of music::
1227 * Skipping corrected music::
1230 @node Extracting fragments of music
1231 @subsection Extracting fragments of music
1233 It is possible to quote small fragments of a large score directly from
1234 the output. This can be compared to clipping a piece of a paper score
1237 This is done by defining the measures that need to be cut out
1238 separately. For example, including the following definition
1246 (make-rhythmic-location 5 1 2)
1247 (make-rhythmic-location 7 3 4)))
1252 will extract a fragment starting halfway the fifth measure, ending in
1253 the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note
1254 in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7.
1256 More clip regions can be defined by adding more pairs of
1257 rhythmic-locations to the list.
1259 In order to use this feature, LilyPond must be invoked with
1260 @code{-dclip-systems}. The clips are output as EPS files, and are
1261 converted to PDF and PNG if these formats are switched on as well.
1263 For more information on output formats, see @rprogram{Invoking lilypond}.
1265 @node Skipping corrected music
1266 @subsection Skipping corrected music
1269 @funindex skipTypesetting
1270 @funindex showLastLength
1272 When entering or copying music, usually only the music near the end (where
1274 are adding notes) is interesting to view and correct. To speed up
1275 this correction process, it is possible to skip typesetting of all but
1276 the last few measures. This is achieved by putting
1279 showLastLength = R1*5
1284 in your source file. This will render only the last 5 measures
1285 (assuming 4/4 time signature) of every @code{\score} in the input
1286 file. For longer pieces, rendering only a small part is often an order
1287 of magnitude quicker than rendering it completely
1289 Skipping parts of a score can be controlled in a more fine-grained
1290 fashion with the property @code{Score.skipTypesetting}. When it is
1291 set, no typesetting is performed at all.
1293 This property is also used to control output to the MIDI file. Note that
1294 it skips all events, including tempo and instrument changes. You have
1297 @lilypond[quote,fragment,ragged-right,verbatim]
1300 \set Score.skipTypesetting = ##t
1302 \set Score.skipTypesetting = ##f
1306 In polyphonic music, @code{Score.skipTypesetting} will affect all
1307 voices and staves, saving even more time.
1312 @section MIDI output
1317 MIDI (Musical Instrument Digital Interface) is a standard for
1318 connecting and controlling digital instruments. A MIDI file is a
1319 series of notes in a number of tracks. It is not an actual
1320 sound file; you need special software to translate between the
1321 series of notes and actual sounds.
1323 Pieces of music can be converted to MIDI files, so you can listen to
1324 what was entered. This is convenient for checking the music; octaves
1325 that are off or accidentals that were mistyped stand out very much
1326 when listening to the MIDI output.
1329 The midi output allocates a channel for each staff, and one for global
1330 settings. Therefore the midi file should not have more than 15 staves
1331 (or 14 if you do not use drums). Other staves will remain silent.
1334 * Creating MIDI files::
1336 * MIDI instrument names::
1338 * What else goes into the MIDI output?::
1341 @node Creating MIDI files
1342 @subsection Creating MIDI files
1344 To create a MIDI output file from a LilyPond input file, add a @code{\midi} block
1345 to a score, for example,
1354 If there is a @code{\midi} block in a @code{\score} with no
1355 @code{\layout} block, only MIDI output will be produced. When
1356 notation is needed too, a @code{\layout} block must be also be
1367 Pitches, rhythms, ties, dynamics, and tempo changes are interpreted
1368 and translated correctly to the MIDI output. Dynamic marks,
1369 crescendi and decrescendi translate into MIDI volume levels.
1370 Dynamic marks translate to a fixed fraction of the available MIDI
1371 volume range. Crescendi and decrescendi make the volume vary
1372 linearly between their two extremes. The effect of dynamic markings
1373 on the MIDI output can be removed completely, see @ref{MIDI block}.
1375 The initial tempo and later tempo changes can be specified
1376 with the @code{\tempo} command within the music notation. These
1377 are reflected in tempo changes in the MIDI output. This command
1378 will normally result in the metronome mark being printed, but this
1379 can be suppressed, see @ref{Metronome marks}. An alternative way
1380 of specifying the inital or overall MIDI tempo is described below,
1381 see @ref{MIDI block}.
1384 @c TODO Investigate dynamicAbsoluteVolumeFunction and the two
1385 @c midi..Volume properties, then document properly.
1387 The fractions can be adjusted by setting
1388 @code{dynamicAbsoluteVolumeFunction} in @rinternals{Voice} context.
1389 For each type of MIDI instrument, a volume range can be defined. This
1390 gives a basic equalizer control, which can enhance the quality of
1391 the MIDI output remarkably. The equalizer can be controlled by
1392 setting @code{instrumentEqualizer}, or by setting
1395 \set Staff.midiMinimumVolume = #0.2
1396 \set Staff.midiMaximumVolume = #0.8
1403 @c In 2.11 the following no longer seems to be a problem -td
1405 Unterminated (de)crescendos will not render properly in the midi file,
1406 resulting in silent passages of music. The workaround is to explicitly
1407 terminate the (de)crescendo. For example,
1414 will not work properly but
1424 Changes in the MIDI volume take place only on starting a note, so
1425 crescendi and decrescendi cannot affect the volume of a
1428 Not all midi players correctly handle tempo changes in the midi
1429 output. Players that are known to work include MS Windows Media
1430 Player and @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
1434 @subsection MIDI block
1437 A @code{\midi} block must appear within a score block if MIDI output
1438 is required. It is analogous to the layout block, but somewhat
1439 simpler. Often, the @code{\midi} block is left empty, but it
1440 can contain context rearrangements, new context definitions or code
1441 to set the values of properties. For example, the following will
1442 set the initial tempo exported to a MIDI file without causing a tempo
1443 indication to be printed:
1451 tempoWholesPerMinute = #(ly:make-moment 72 4)
1457 In this example the tempo is set to 72 quarter note
1458 beats per minute. This kind of tempo specification cannot take
1459 a dotted note length as an argument. If one is required, break
1460 the dotted note into smaller units. For example, a tempo of 90
1461 dotted quarter notes per minute can be specified as 270 eighth
1465 tempoWholesPerMinute = #(ly:make-moment 270 8)
1468 @cindex MIDI context definitions
1470 Context definitions follow precisely the same syntax as those
1471 within a @code{\layout} block. Translation modules for sound are
1472 called performers. The contexts for MIDI output are defined in
1473 @file{ly/@/performer@/-init@/.ly},
1474 see @rlearning{Other sources of information}.
1475 For example, to remove the effect of dynamics
1476 from the MIDI output, insert the following lines in the
1477 @code{\midi@{ @}} block.
1484 \remove "Dynamic_performer"
1489 MIDI output is created only when a @code{\midi} block is included
1490 within a score block defined with a @code{\score} command. If it
1491 is placed within an explicitly instantiated score context (i.e.
1492 within a @code{\new Score} block) the file will fail. To solve
1493 this, enclose the @code{\new Score} and the @code{\midi} commands
1494 in a @code{\score} block.
1498 \new Score @{ @dots{}notes@dots{} @}
1505 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
1506 {changing-midi-output-to-one-channel-per-voice.ly}
1508 @node MIDI instrument names
1509 @subsection MIDI instrument names
1511 @cindex instrument names
1512 @funindex Staff.midiInstrument
1514 The MIDI instrument name is set by the @code{Staff.midiInstrument}
1515 property. The instrument name should be chosen from the list in
1516 @ref{MIDI instruments}.
1519 \set Staff.midiInstrument = "glockenspiel"
1523 If the selected instrument does not exactly match an instrument from
1524 the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
1528 @node Repeats in MIDI
1529 @subsection Repeats in MIDI
1531 @cindex repeats in MIDI
1532 @funindex \unfoldRepeats
1534 With a few minor additions, all types of repeats can be represented
1535 in the MIDI output. This is achieved by applying the
1536 @code{\unfoldRepeats} music function. This function changes all
1537 repeats to unfold repeats.
1539 @lilypond[quote,verbatim]
1541 \repeat tremolo 8 {c'32 e' }
1542 \repeat percent 2 { c''8 d'' }
1543 \repeat volta 2 {c'4 d' e' f'}
1552 When creating a score file using @code{\unfoldRepeats} for MIDI,
1553 it is necessary to make two @code{\score} blocks: one for MIDI
1554 (with unfolded repeats) and one for notation (with volta, tremolo,
1555 and percent repeats). For example,
1563 \unfoldRepeats @var{..music..}
1569 @node What else goes into the MIDI output?
1570 @subsection What else goes into the MIDI output?
1572 @c TODO Check grace notes - timing is suspect?
1574 @unnumberedsubsubsec Microtones
1576 @cindex microtones in MIDI
1578 Microtones consisting of half sharps and half flats are exported
1579 to the MIDI file and render correctly in MIDI players which support
1580 pitch bending. See @ref{Note names in other languages}. Here is
1581 an example showing all the half sharps and half flats. It can be
1582 copied out and compiled to test microtones in your MIDI player.
1584 @lilypond[verbatim,quote]
1601 @c TODO List things that have no effect
1604 Many musically interesting effects, such as swing, articulation,
1605 slurring, etc., are not translated to midi. Also, figured bass,
1606 chords, and lyrics have no effect on MIDI.