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.
18 FIXME: don't complain about anything in this chapter. It's still
19 under heavy development.
23 * Titles and headers::
24 * Working with input files::
25 * Controlling output::
31 @section Input structure
33 The main format of input for LilyPond are text files. By convention,
34 these files end with @code{.ly}.
37 * Structure of a score::
38 * Multiple scores in a book::
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
109 @rlearning{Working on input files},
110 @rlearning{Music expressions explained},
111 @rlearning{Score is a (single) compound musical expression}.
114 @node Multiple scores in a book
115 @subsection Multiple scores in a book
118 @cindex movements, multiple
120 A document may contain multiple pieces of music and text. Examples
121 of these are an etude book, or an orchestral part with multiple
122 movements. Each movement is entered with a @code{\score} block,
130 and texts are entered with a @code{\markup} block,
140 All the movements and texts which appear in the same @code{.ly} file
141 will normally be typeset in the form of a single output file.
155 However, if you want multiple output files from the same @code{.ly}
156 file, then you can add multiple @code{\book} blocks, where each such
157 @code{\book} block will result in a separate output. If you do not
158 specify any @code{\book} block in the file, LilyPond will implicitly
159 treat the full file as a single @code{\book} block, see @ref{File
160 structure}. One important exception is within lilypond-book documents,
161 where you explicitly have to add a @code{\book} block, otherwise only
162 the first @code{\score} or @code{\markup} will appear in the output.
164 The header for each piece of music can be put inside the @code{\score}
165 block. The @code{piece} name from the header will be printed before
166 each movement. The title for the entire book can be put inside the
167 @code{\book}, but if it is not present, the @code{\header} which is at
168 the top of the file is inserted.
172 title = "Eight miniatures"
173 composer = "Igor Stravinsky"
177 \header @{ piece = "Romanze" @}
180 ..text of second verse..
183 ..text of third verse..
187 \header @{ piece = "Menuetto" @}
192 @subsection File structure
201 A @code{.ly} file may contain any number of toplevel expressions, where a
202 toplevel expression is one of the following:
206 An output definition, such as @code{\paper}, @code{\midi}, and
207 @code{\layout}. Such a definition at the toplevel changes the default
208 book-wide settings. If more than one such definition of
209 the same type is entered at the top level any definitions in the later
210 expressions have precedence.
213 A direct scheme expression, such as
214 @code{#(set-default-paper-size "a7" 'landscape)} or
215 @code{#(ly:set-option 'point-and-click #f)}.
218 A @code{\header} block. This sets the global header block. This
219 is the block containing the definitions for book-wide settings, like
220 composer, title, etc.
223 A @code{\score} block. This score will be collected with other
224 toplevel scores, and combined as a single @code{\book}.
225 This behavior can be changed by setting the variable
226 @code{toplevel-score-handler} at toplevel. The default handler is
227 defined in the init file @file{scm/@/lily@/.scm}.
230 A @code{\book} block logically combines multiple movements
231 (i.e., multiple @code{\score} blocks) in one document. If there
232 are a number of @code{\score}s, one output file will be created
233 for each @code{\book} block, in which all corresponding movements
234 are concatenated. The only reason to explicitly specify
235 @code{\book} blocks in a @code{.ly} file is if you wish to create
236 multiple output files from a single input file. One exception is
237 within lilypond-book documents, where you explicitly have to add
238 a @code{\book} block if you want more than a single @code{\score}
239 or @code{\markup} in the same example. This behavior can be
240 changed by setting the variable @code{toplevel-book-handler} at
241 toplevel. The default handler is defined in the init file
242 @file{scm/@/lily@/.scm}.
245 A compound music expression, such as
250 This will add the piece in a @code{\score} and format it in a
251 single book together with all other toplevel @code{\score}s and music
252 expressions. In other words, a file containing only the above
253 music expression will be translated into
269 This behavior can be changed by setting the variable
270 @code{toplevel-music-handler} at toplevel. The default handler is
271 defined in the init file @file{scm/@/lily@/.scm}.
274 A markup text, a verse for example
277 2. The first line verse two.
281 Markup texts are rendered above, between or below the scores or music
282 expressions, wherever they appear.
292 This can be used later on in the file by entering @code{\foo}. The
293 name of an variable should have alphabetic characters only; no
294 numbers, underscores or dashes.
298 The following example shows three things that may be entered at
303 % Don't justify the output
315 At any point in a file, any of the following lexical instructions can
319 @item @code{\version}
320 @item @code{\include}
321 @item @code{\sourcefilename}
322 @item @code{\sourcefileline}
324 A single-line comment, introduced by a leading @code{%} sign.
327 A multi-line comment delimited by @code{%@{ .. %@}}.
334 @rlearning{How LilyPond input files work}.
336 @node Titles and headers
337 @section Titles and headers
339 Almost all printed music includes a title and the composer's name;
340 some pieces include a lot more information.
345 * Reference to page numbers::
346 * Table of contents::
350 @node Creating titles
351 @subsection Creating titles
353 Titles are created for each @code{\score} block, as well as for the full
354 input file (or @code{\book} block).
356 The contents of the titles are taken from the @code{\header} blocks.
357 The header block for a book supports the following
363 The dedicatee of the music, centered at the top of the first page.
367 The title of the music, centered just below the dedication.
371 Subtitle, centered below the title.
373 @funindex subsubtitle
375 Subsubtitle, centered below the subtitle.
379 Name of the poet, flush-left below the subtitle.
383 Name of the composer, flush-right below the subtitle.
387 Meter string, flush-left below the poet.
391 Name of the opus, flush-right below the composer.
395 Name of the arranger, flush-right below the opus.
399 Name of the instrument, centered below the arranger. Also
400 centered at the top of pages (other than the first page).
404 Name of the piece, flush-left below the instrument.
406 @cindex page breaks, forcing
407 @funindex breakbefore
409 This forces the title to start on a new page (set to ##t or ##f).
413 Copyright notice, centered at the bottom of the first page. To
414 insert the copyright symbol, see @ref{Text encoding}.
418 Centered at the bottom of the last page.
422 Here is a demonstration of the fields available. Note that you
423 may use any @ref{Formatting text}, commands in the header.
425 @lilypond[quote,verbatim,line-width=11.0\cm]
428 paper-height = 10.0\cm
433 dedication = "dedicated to me"
434 title = \markup \center-align { "Title first line" "Title second line,
436 subtitle = "the subtitle,"
437 subsubtitle = #(string-append "subsubtitle LilyPond version "
440 composer = \markup \center-align { "composer" \small "(1847-1973)" }
441 texttranslator = "Text Translator"
442 meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
444 arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize
445 #-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }
446 instrument = \markup \bold \italic "instrument"
470 As demonstrated before, you can use multiple @code{\header} blocks.
471 When same fields appear in different blocks, the latter is used.
472 Here is a short example.
476 composer = "Composer"
484 piece = "New piece" % overwrite previous one
489 If you define the @code{\header} inside the @code{\score} block, then
490 normally only the @code{piece} and @code{opus} headers will be printed.
491 Note that the music expression must come before the @code{\header}.
493 @lilypond[quote,verbatim,line-width=11.0\cm]
497 title = "title" % not printed
504 @funindex printallheaders
506 You may change this behavior (and print all the headers when defining
507 @code{\header} inside @code{\score}) by using
518 The default footer is empty, except for the first page, where the
519 @code{copyright} field from @code{\header} is inserted, and the last
520 page, where @code{tagline} from @code{\header} is added. The default
521 tagline is @qq{Music engraving by LilyPond (@var{version})}.@footnote{Nicely
522 printed parts are good PR for us, so please leave the tagline if you
525 Headers may be completely removed by setting them to false.
536 @subsection Custom titles
538 A more advanced option is to change the definitions of the following
539 variables in the @code{\paper} block. The init file
540 @file{ly/titling-init.ly} lists the default layout.
543 @funindex bookTitleMarkup
544 @item bookTitleMarkup
545 This is the title added at the top of the entire output document.
546 Typically, it has the composer and the title of the piece
548 @funindex scoreTitleMarkup
549 @item scoreTitleMarkup
550 This is the title put over a @code{\score} block. Typically, it has
551 the name of the movement (@code{piece} field).
553 @funindex oddHeaderMarkup
554 @item oddHeaderMarkup
555 This is the page header for odd-numbered pages.
557 @funindex evenHeaderMarkup
558 @item evenHeaderMarkup
559 This is the page header for even-numbered pages. If unspecified,
560 the odd header is used instead.
562 By default, headers are defined such that the page number is on the
563 outside edge, and the instrument is centered.
565 @funindex oddFooterMarkup
566 @item oddFooterMarkup
567 This is the page footer for odd-numbered pages.
569 @funindex evenFooterMarkup
570 @item evenFooterMarkup
571 This is the page footer for even-numbered pages. If unspecified,
572 the odd header is used instead.
574 By default, the footer has the copyright notice on the first, and
575 the tagline on the last page.
585 The following definition will put the title flush left, and the
586 composer flush right on a single line.
590 bookTitleMarkup = \markup {
592 \fromproperty #'header:title
593 \fromproperty #'header:composer
599 @node Reference to page numbers
600 @subsection Reference to page numbers
602 A particular place of a score can be marked using the @code{\label}
603 command, either at top-level or inside music. This label can then be
604 referred to in a markup, to get the number of the page where the marked
605 point is placed, using the @code{\page-ref} markup command.
607 @lilypond[verbatim,line-width=11.0\cm]
608 \header { tagline = ##f }
614 \pageBreak \mark A \label #'markA
619 \markup { The first score begins on page \page-ref #'firstScore "0" "?" }
620 \markup { Mark A is on page \page-ref #'markA "0" "?" }
624 The @code{\page-ref} markup command takes three arguments:
626 @item the label, a scheme symbol, eg. @code{#'firstScore};
627 @item a markup that will be used as a gauge to estimate the dimensions
629 @item a markup that will be used in place of the page number if the label
633 The reason why a gauge is needed is that, at the time markups are
634 interpreted, the page breaking has not yet occurred, so the page numbers
635 are not yet known. To work around this issue, the actual markup
636 interpretation is delayed to a later time; however, the dimensions of
637 the markup have to be known before, so a gauge is used to decide these
638 dimensions. If the book has between 10 and 99 pages, it may be "00",
639 ie. a two digit number.
648 @node Table of contents
649 @subsection Table of contents
650 A table of contents is included using the @code{\markuplines \table-of-contents}
651 command. The elements which should appear in the table of contents are
652 entered with the @code{\tocItem} command, which may be used either at
653 top-level, or inside a music expression.
656 \markuplines \table-of-contents
659 \tocItem \markup "First score"
663 \tocItem \markup "Some particular point in the first score"
668 \tocItem \markup "Second score"
676 The markups which are used to format the table of contents are defined
677 in the @code{\paper} block. The default ones are @code{tocTitleMarkup},
678 for formatting the title of the table, and @code{tocItemMarkup}, for
679 formatting the toc elements, composed of the element title and page
680 number. These variables may be changed by the user:
684 %% Translate the toc title into French:
685 tocTitleMarkup = \markup \huge \column {
686 \fill-line { \null "Table des matières" \null }
689 %% use larger font size
690 tocItemMarkup = \markup \large \fill-line {
691 \fromproperty #'toc:text \fromproperty #'toc:page
696 Note how the toc element text and page number are referred to in
697 the @code{tocItemMarkup} definition.
699 New commands and markups may also be defined to build more elaborated
702 @item first, define a new markup variable in the @code{\paper} block
703 @item then, define a music function which aims at adding a toc element
704 using this markup paper variable.
707 In the following example, a new style is defined for entering act names
708 in the table of contents of an opera:
712 tocActMarkup = \markup \large \column {
714 \fill-line { \null \italic \fromproperty #'toc:text \null }
720 #(define-music-function (parser location text) (markup?)
721 (add-toc-item! 'tocActMarkup text))
724 @lilypond[line-width=11.0\cm]
725 \header { tagline = ##f }
727 tocActMarkup = \markup \large \column {
729 \fill-line { \null \italic \fromproperty #'toc:text \null }
735 #(define-music-function (parser location text) (markup?)
736 (add-toc-item! 'tocActMarkup text))
739 \markuplines \table-of-contents
740 \tocAct \markup { Atto Primo }
741 \tocItem \markup { Coro. Viva il nostro Alcide }
742 \tocItem \markup { Cesare. Presti omai l'Egizzia terra }
743 \tocAct \markup { Atto Secondo }
744 \tocItem \markup { Sinfonia }
745 \tocItem \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
752 Init files: @file{ly/@/toc@/-init@/.ly}.
756 @funindex \table-of-contents
757 @code{\table-of-contents}
762 @node Working with input files
763 @section Working with input files
766 * Including LilyPond files::
767 * Different editions from one source::
769 * Displaying LilyPond notation::
773 @node Including LilyPond files
774 @subsection Including LilyPond files
777 @cindex including files
779 A large project may be split up into separate files. To refer to
783 \include "otherfile.ly"
786 The line @code{\include "otherfile.ly"} is equivalent to pasting the
787 contents of @file{otherfile.ly} into the current file at the place
788 where the @code{\include} appears. For example, in a large
789 project you might write separate files for each instrument part
790 and create a @qq{full score} file which brings together the
791 individual instrument files. Normally the included file will
792 define a number of variables which then become available
793 for use in the full score file. Tagged sections can be
794 marked in included files to assist in making them usable in
795 different places in a score, see @ref{Different editions from
798 Files in the current working directory may be referenced by
799 specifying just the file name after the @code{\include} command.
800 Files in other locations may be included by giving either a full
801 path reference or a relative path reference (but use the UNIX
802 forward slash, /, rather than the DOS/Windows back slash, \, as the
803 directory separator.) For example, if @file{stuff.ly} is located
804 one directory higher than the current working directory, use
807 \include "../stuff.ly"
811 or if the included orchestral parts files are all located in a
812 subdirectory called @file{parts} within the current directory, use
815 \include "parts/VI.ly"
816 \include "parts/VII.ly"
820 Files which are to be included can also contain @code{\include}
821 statements of their own. These second-level
822 @code{\include} statements are not interpreted until they have
823 been brought into the main file, so the file names they specify
824 must all be relative to the directory containing the main file,
825 not the directory containing the included file.
827 Files can also be included from a directory in a search path
828 specified as an option when invoking LilyPond from the command
829 line. The included files are then specified using just their
830 file name. For example, to compile @file{main.ly} which includes
831 files located in a subdirectory called @file{parts} by this method,
832 cd to the directory containing @file{main.ly} and enter
835 lilypond --include=parts main.ly
846 Files which are to be included in many scores may be placed in
847 the LilyPond directory @file{../ly}. (The location of this
848 directory is installation-dependent - see @rlearning{Other sources
849 of information}). These files can then be included simply by
850 naming them on an @code{\include} statement. This is how the
851 language-dependent files like @file{english.ly} are included.
853 LilyPond includes a number of files by default when you start
854 the program. These includes are not apparent to the user, but the
855 files may be identified by running @code{lilypond --verbose} from
856 the command line. This will display a list of paths and files that
857 LilyPond uses, along with much other information. Alternatively,
858 the more important of these files are discussed in @rlearning{Other
859 sources of information}. These files may be edited, but changes to
860 them will be lost on installing a new version of LilyPond.
862 Some simple examples of using @code{\include} are shown in
863 @rlearning{Scores and parts}.
867 @rlearning{Other sources of information},
868 @rlearning{Scores and parts}.
872 If an included file is given a name which is the same as one in
873 LilyPond's installation files, LilyPond's file from the
874 installation files takes precedence.
878 @node Different editions from one source
879 @subsection Different editions from one source
881 Several mechanisms are available to facilitate the generation
882 of different versions of a score from the same music source.
883 Variables are perhaps most useful for combining lengthy sections
884 of music and/or annotation in various ways, while tags are more
885 useful for selecting one from several alternative shorter sections
886 of music. Whichever method is used, separating the notation from
887 the structure of the score will make it easier to change the
888 structure while leaving the notation untouched.
895 @node Using variables
896 @unnumberedsubsubsec Using variables
898 @cindex variables, use of
900 If sections of the music are defined in variables they can be
901 reused in different parts of the score, see @rlearning{Organizing
902 pieces with variables}. For example, an @notation{a cappella}
903 vocal score frequently includes a piano reduction of the parts
904 for rehearsal purposes which is identical to the vocal music, so
905 the music need be entered only once. Music from two variables
906 may be combined on one staff, see @ref{Automatic part combining}.
909 @lilypond[verbatim,quote]
910 sopranoMusic = \relative c'' { a4 b c b8( a)}
911 altoMusic = \relative g' { e4 e e f }
912 tenorMusic = \relative c' { c4 b e d8( c) }
913 bassMusic = \relative c' { a4 gis a d, }
914 allLyrics = \lyricmode {King of glo -- ry }
916 \new Staff = "Soprano" \sopranoMusic
917 \new Lyrics \allLyrics
918 \new Staff = "Alto" \altoMusic
919 \new Lyrics \allLyrics
920 \new Staff = "Tenor" {
924 \new Lyrics \allLyrics
925 \new Staff = "Bass" {
929 \new Lyrics \allLyrics
932 \set Staff.printPartCombineTexts = ##f
938 \set Staff.printPartCombineTexts = ##f
948 Separate scores showing just the vocal parts or just the piano
949 part can be produced by changing just the structural statements,
950 leaving the musical notation unchanged.
952 For lengthy scores, the variable definitions may be placed in
953 separate files which are then included, see @ref{Including
957 @unnumberedsubsubsec Using tags
960 @funindex \keepWithTag
961 @funindex \removeWithTag
963 @cindex keep tagged music
964 @cindex remove tagged music
966 The @code{\tag #'@var{partA}} command marks a music expression
967 with the name @var{partA}.
968 Expressions tagged in this way can be selected or filtered out by
969 name later, using either @code{\keepWithTag #'@var{name}} or
970 @code{\removeWithTag #'@var{name}}. The result of applying these filters
971 to tagged music is as follows:
972 @multitable @columnfractions .5 .5
976 Tagged music preceded by @code{\keepWithTag #'@var{name}}
977 @tab Untagged music and music tagged with @var{name} is included;
978 music tagged with any other tag name is excluded.
980 Tagged music preceded by @code{\removeWithTag #'@var{name}}
981 @tab Untagged music and music tagged with any tag name other than
982 @var{name} is included; music tagged with @var{name} is
985 Tagged music not preceded by either @code{\keepWithTag} or
986 @code{\removeWithTag}
987 @tab All tagged and untagged music is included.
990 The arguments of the @code{\tag}, @code{\keepWithTag} and
991 @code{\removeWithTag} commands should be a symbol
992 (such as @code{#'score} or @code{#'part}), followed
993 by a music expression.
995 In the following example, we see two versions of a piece of music,
996 one showing trills with the usual notation, and one with trills
999 @lilypond[verbatim,quote]
1000 music = \relative g' {
1002 \tag #'trills {d8.\trill }
1003 \tag #'expand {\repeat unfold 3 {e32 d} }
1008 \keepWithTag #'trills \music
1011 \keepWithTag #'expand \music
1016 Alternatively, it is sometimes easier to exclude sections of music:
1018 @lilypond[verbatim,quote]
1019 music = \relative g' {
1021 \tag #'trills {d8.\trill }
1022 \tag #'expand {\repeat unfold 3 {e32 d} }
1027 \removeWithTag #'expand
1031 \removeWithTag #'trills
1036 Tagged filtering can be applied to articulations, texts, etc. by
1040 -\tag #'@var{your-tag}
1043 to an articulation. For example, this would define a note with a
1044 conditional fingering indication and a note with a conditional
1049 c1-\tag #'warn ^"Watch!"
1052 Multiple tags may be placed on expressions with multiple
1053 @code{\tag} entries:
1055 @lilypond[quote,verbatim]
1056 music = \relative c'' {
1057 \tag #'a \tag #'both { a a a a }
1058 \tag #'b \tag #'both { b b b b }
1061 \keepWithTag #'a \music
1062 \keepWithTag #'b \music
1063 \keepWithTag #'both \music
1067 Multiple @code{\removeWithTag} filters may be applied to a single
1068 music expression to remove several differently named tagged sections:
1070 @lilypond[verbatim,quote]
1071 music = \relative c'' {
1072 \tag #'A { a a a a }
1073 \tag #'B { b b b b }
1074 \tag #'C { c c c c }
1075 \tag #'D { d d d d }
1084 Two or more @code{\keepWithTag} filters applied to a single music
1085 expression will cause @emph{all} tagged sections to be removed, as
1086 the first filter will remove all tagged sections except the one
1087 named, and the second filter will remove even that tagged section.
1092 @rlearning{Organizing pieces with variables}.
1095 @ref{Automatic part combining},
1096 @ref{Including LilyPond files}.
1099 @c This warning is more general than this placement implies.
1100 @c Rests are not merged whether or not they come from tagged sections.
1101 @c Should be deleted? -td
1105 Multiple rests are not merged if you create a score with more
1106 than one tagged section at the same place.
1111 @subsection Text encoding
1113 LilyPond uses the Pango library to format multi-lingual texts, and
1114 does not perform any input-encoding conversions. This means that any
1115 text, be it title, lyric text, or musical instruction containing
1116 non-ASCII characters, must be utf-8. The easiest way to enter such text is
1117 by using a Unicode-aware editor and saving the file with utf-8 encoding. Most
1118 popular modern editors have utf-8 support, for example, vim, Emacs,
1119 jEdit, and GEdit do.
1121 @c Currently not working
1123 Depending on the fonts installed, the following fragment shows Hebrew
1124 and Cyrillic lyrics,
1130 @li lypondfile[fontload]{utf-8.ly}
1132 The @TeX{} backend does not handle encoding specially at all. Strings
1133 in the input are put in the output as-is. Extents of text items in the
1134 @TeX{} backend, are determined by reading a file created via the
1135 @file{texstr} backend,
1138 lilypond -dbackend=texstr input/les-nereides.ly
1139 latex les-nereides.texstr
1142 The last command produces @file{les-nereides.textmetrics}, which is
1143 read when you execute
1146 lilypond -dbackend=tex input/les-nereides.ly
1149 Both @file{les-nereides.texstr} and @file{les-nereides.tex} need
1150 suitable LaTeX wrappers to load appropriate La@TeX{} packages for
1151 interpreting non-ASCII strings.
1155 To use a Unicode escape sequence, use
1158 #(ly:export (ly:wide-char->utf-8 #x2014))
1162 @node Displaying LilyPond notation
1163 @subsection Displaying LilyPond notation
1165 @funindex \displayLilyMusic
1166 Displaying a music expression in LilyPond notation can be
1167 done using the music function @code{\displayLilyMusic}. For example,
1171 \displayLilyMusic \transpose c a, @{ c e g a bes @}
1178 @{ a, cis e fis g @}
1181 By default, LilyPond will print these messages to the console along
1182 with all the other messages. To split up these messages and save
1183 the results of @code{\display@{STUFF@}}, redirect the output to
1187 lilypond file.ly >display.txt
1192 @node Controlling output
1193 @section Controlling output
1196 * Extracting fragments of music::
1197 * Skipping corrected music::
1200 @node Extracting fragments of music
1201 @subsection Extracting fragments of music
1203 It is possible to quote small fragments of a large score directly from
1204 the output. This can be compared to clipping a piece of a paper score
1207 This is done by defining the measures that need to be cut out
1208 separately. For example, including the following definition
1216 (make-rhythmic-location 5 1 2)
1217 (make-rhythmic-location 7 3 4)))
1222 will extract a fragment starting halfway the fifth measure, ending in
1223 the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note
1224 in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7.
1226 More clip regions can be defined by adding more pairs of
1227 rhythmic-locations to the list.
1229 In order to use this feature, LilyPond must be invoked with
1230 @code{-dclip-systems}. The clips are output as EPS files, and are
1231 converted to PDF and PNG if these formats are switched on as well.
1233 For more information on output formats, see @rprogram{Invoking lilypond}.
1235 @node Skipping corrected music
1236 @subsection Skipping corrected music
1239 @funindex skipTypesetting
1240 @funindex showLastLength
1242 When entering or copying music, usually only the music near the end (where
1244 are adding notes) is interesting to view and correct. To speed up
1245 this correction process, it is possible to skip typesetting of all but
1246 the last few measures. This is achieved by putting
1249 showLastLength = R1*5
1254 in your source file. This will render only the last 5 measures
1255 (assuming 4/4 time signature) of every @code{\score} in the input
1256 file. For longer pieces, rendering only a small part is often an order
1257 of magnitude quicker than rendering it completely
1259 Skipping parts of a score can be controlled in a more fine-grained
1260 fashion with the property @code{Score.skipTypesetting}. When it is
1261 set, no typesetting is performed at all.
1263 This property is also used to control output to the MIDI file. Note that
1264 it skips all events, including tempo and instrument changes. You have
1267 @lilypond[quote,fragment,ragged-right,verbatim]
1270 \set Score.skipTypesetting = ##t
1272 \set Score.skipTypesetting = ##f
1276 In polyphonic music, @code{Score.skipTypesetting} will affect all
1277 voices and staves, saving even more time.
1282 @section MIDI output
1287 MIDI (Musical Instrument Digital Interface) is a standard for
1288 connecting and controlling digital instruments. A MIDI file is a
1289 series of notes in a number of tracks. It is not an actual
1290 sound file; you need special software to translate between the
1291 series of notes and actual sounds.
1293 Pieces of music can be converted to MIDI files, so you can listen to
1294 what was entered. This is convenient for checking the music; octaves
1295 that are off or accidentals that were mistyped stand out very much
1296 when listening to the MIDI output.
1300 Many musically interesting effects, such as swing, articulation,
1301 slurring, etc., are not translated to midi.
1303 The midi output allocates a channel for each staff, and one for global
1304 settings. Therefore the midi file should not have more than 15 staves
1305 (or 14 if you do not use drums). Other staves will remain silent.
1307 Not all midi players correctly handle tempo changes in the midi
1308 output. Players that are known to work include
1309 @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
1312 * Creating MIDI files::
1314 * MIDI instrument names::
1315 * What goes into the MIDI? FIXME::
1319 @node Creating MIDI files
1320 @subsection Creating MIDI files
1322 To create a MIDI from a music piece of music, add a @code{\midi} block
1323 to a score, for example,
1331 tempoWholesPerMinute = #(ly:make-moment 72 4)
1337 The tempo can be specified using the @code{\tempo} command within the
1338 actual music, see @ref{Metronome marks}. An alternative, which does not
1339 result in a metronome mark in the printed score, is shown in the example
1340 above. In this example the tempo of quarter notes is set to 72 beats per
1343 specification can not take dotted note lengths as an argument. In this
1344 case, break the dotted notes into smaller units. For example, a tempo
1345 of 90 dotted quarter notes per minute can be specified as 270 eighth
1349 tempoWholesPerMinute = #(ly:make-moment 270 8)
1352 If there is a @code{\midi} command in a @code{\score}, only MIDI will
1353 be produced. When notation is needed too, a @code{\layout} block must
1363 @cindex layout block
1367 Ties, dynamics, and tempo changes are interpreted. Dynamic marks,
1368 crescendi and decrescendi translate into MIDI volume levels. Dynamic
1369 marks translate to a fixed fraction of the available MIDI volume
1370 range, crescendi and decrescendi make the volume vary linearly between
1371 their two extremes. The fractions can be adjusted by
1372 @code{dynamicAbsoluteVolumeFunction} in @rinternals{Voice} context.
1373 For each type of MIDI instrument, a volume range can be defined. This
1374 gives a basic equalizer control, which can enhance the quality of
1375 the MIDI output remarkably. The equalizer can be controlled by
1376 setting @code{instrumentEqualizer}, or by setting
1379 \set Staff.midiMinimumVolume = #0.2
1380 \set Staff.midiMaximumVolume = #0.8
1383 To remove dynamics from the MIDI output, insert the following lines
1384 in the @code{\midi@{@}} section.
1391 \remove "Dynamic_performer"
1399 Unterminated (de)crescendos will not render properly in the midi file,
1400 resulting in silent passages of music. The workaround is to explicitly
1401 terminate the (de)crescendo. For example,
1408 will not work properly but
1418 MIDI output is only created when the @code{\midi} command is within
1419 a @code{\score} block. If you put it within an explicitly instantiated
1420 context ( i.e. @code{\new Score} ) the file will fail. To solve this,
1421 enclose the @code{\new Score} and the @code{\midi} in a @code{\score} block.
1425 \new Score @{ @dots{}notes@dots{} @}
1432 @subsection MIDI block
1436 The MIDI block is analogous to the layout block, but it is somewhat
1437 simpler. The @code{\midi} block is similar to @code{\layout}. It can contain
1438 context definitions.
1441 @cindex context definition
1443 Context definitions follow precisely the same syntax as within the
1444 \layout block. Translation modules for sound are called performers.
1445 The contexts for MIDI output are defined in @file{ly/@/performer@/-init@/.ly}.
1448 @node MIDI instrument names
1449 @subsection MIDI instrument names
1451 @cindex instrument names
1452 @funindex Staff.midiInstrument
1454 The MIDI instrument name is set by the @code{Staff.midiInstrument}
1455 property. The instrument name should be chosen from the list in
1456 @ref{MIDI instruments}.
1459 \set Staff.midiInstrument = "glockenspiel"
1463 If the selected instrument does not exactly match an instrument from
1464 the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
1468 @node What goes into the MIDI? FIXME
1469 @subsection What goes into the MIDI? FIXME
1472 * Repeats and MIDI::
1475 @node Repeats and MIDI
1476 @subsubsection Repeats and MIDI
1478 @cindex expanding repeats
1479 @funindex \unfoldRepeats
1481 With a little bit of tweaking, all types of repeats can be present
1482 in the MIDI output. This is achieved by applying the
1483 @code{\unfoldRepeats} music function. This function changes all
1484 repeats to unfold repeats.
1486 @lilypond[quote,verbatim,fragment,line-width=8.0\cm]
1488 \repeat tremolo 8 {c'32 e' }
1489 \repeat percent 2 { c''8 d'' }
1490 \repeat volta 2 {c'4 d' e' f'}
1499 When creating a score file using @code{\unfoldRepeats} for MIDI,
1500 it is necessary to make two @code{\score} blocks: one for MIDI
1501 (with unfolded repeats) and one for notation (with volta, tremolo,
1502 and percent repeats). For example,
1510 \unfoldRepeats @var{..music..}
1517 @subsection other midi
1519 Micro tones are also exported to the MIDI file.
1521 Figured bass has no effect on MIDI.