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.
12 @node General input and output
13 @chapter General input and output
15 This section deals with general LilyPond input and output 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" @}
190 Pieces of music may be grouped into book parts using @code{\bookpart}
191 blocks. Book parts are separated by a page break, and can start with a
192 title, like the book itself, by specifying a @code{\header} block.
198 subtitle = "First part"
205 subtitle = "Second part"
213 @subsection File structure
223 A @code{.ly} file may contain any number of toplevel expressions, where a
224 toplevel expression is one of the following:
228 An output definition, such as @code{\paper}, @code{\midi}, and
229 @code{\layout}. Such a definition at the toplevel changes the default
230 book-wide settings. If more than one such definition of
231 the same type is entered at the top level any definitions in the later
232 expressions have precedence.
235 A direct scheme expression, such as
236 @code{#(set-default-paper-size "a7" 'landscape)} or
237 @code{#(ly:set-option 'point-and-click #f)}.
240 A @code{\header} block. This sets the global header block. This
241 is the block containing the definitions for book-wide settings, like
242 composer, title, etc.
245 A @code{\score} block. This score will be collected with other
246 toplevel scores, and combined as a single @code{\book}.
247 This behavior can be changed by setting the variable
248 @code{toplevel-score-handler} at toplevel. The default handler is
249 defined in the init file @file{../scm/@/lily@/.scm}.
252 A @code{\book} block logically combines multiple movements
253 (i.e., multiple @code{\score} blocks) in one document. If there
254 are a number of @code{\score}s, one output file will be created
255 for each @code{\book} block, in which all corresponding movements
256 are concatenated. The only reason to explicitly specify
257 @code{\book} blocks in a @code{.ly} file is if you wish to create
258 multiple output files from a single input file. One exception is
259 within lilypond-book documents, where you explicitly have to add
260 a @code{\book} block if you want more than a single @code{\score}
261 or @code{\markup} in the same example. This behavior can be
262 changed by setting the variable @code{toplevel-book-handler} at
263 toplevel. The default handler is defined in the init file
264 @file{../scm/@/lily@/.scm}.
267 A @code{\bookpart} block. A book may be divided into several parts,
268 using @code{\bookpart} blocks, in order to ease the page breaking,
269 or to use different @code{\paper} settings in different parts.
272 A compound music expression, such as
277 This will add the piece in a @code{\score} and format it in a
278 single book together with all other toplevel @code{\score}s and music
279 expressions. In other words, a file containing only the above
280 music expression will be translated into
296 This behavior can be changed by setting the variable
297 @code{toplevel-music-handler} at toplevel. The default handler is
298 defined in the init file @file{../scm/@/lily@/.scm}.
301 A markup text, a verse for example
304 2. The first line verse two.
308 Markup texts are rendered above, between or below the scores or music
309 expressions, wherever they appear.
319 This can be used later on in the file by entering @code{\foo}. The
320 name of a variable should have alphabetic characters only; no
321 numbers, underscores or dashes.
325 The following example shows three things that may be entered at
330 % Don't justify the output
342 At any point in a file, any of the following lexical instructions can
346 @item @code{\version}
347 @item @code{\include}
348 @item @code{\sourcefilename}
349 @item @code{\sourcefileline}
351 A single-line comment, introduced by a leading @code{%} sign.
354 A multi-line comment delimited by @code{%@{ .. %@}}.
361 @rlearning{How LilyPond input files work}.
363 @node Titles and headers
364 @section Titles and headers
366 Almost all printed music includes a title and the composer's name;
367 some pieces include a lot more information.
372 * Reference to page numbers::
373 * Table of contents::
377 @node Creating titles
378 @subsection Creating titles
380 Titles are created for each @code{\score} block, as well as for the full
381 input file (or @code{\book} block) and book parts (created by
382 @code{\bookpart} blocks).
384 The contents of the titles are taken from the @code{\header} blocks.
385 The header block for a book supports the following
391 The dedicatee of the music, centered at the top of the first page.
395 The title of the music, centered just below the dedication.
399 Subtitle, centered below the title.
401 @funindex subsubtitle
403 Subsubtitle, centered below the subtitle.
407 Name of the poet, flush-left below the subsubtitle.
411 Name of the instrument, centered below the subsubtitle. Also
412 centered at the top of pages (other than the first page).
416 Name of the composer, flush-right below the subsubtitle.
420 Meter string, flush-left below the poet.
424 Name of the arranger, flush-right below the composer.
428 Name of the piece, flush-left below the meter.
432 Name of the opus, flush-right below the arranger.
434 @cindex page breaks, forcing
435 @funindex breakbefore
437 This forces the title to start on a new page (set to ##t or ##f).
441 Copyright notice, centered at the bottom of the first page. To
442 insert the copyright symbol, see @ref{Text encoding}.
446 Centered at the bottom of the last page.
450 Here is a demonstration of the fields available. Note that you
451 may use any @ref{Formatting text}, commands in the header.
453 @lilypond[quote,verbatim,line-width=11.0\cm]
456 paper-height = 10.0\cm
461 dedication = "dedicated to me"
462 title = \markup \center-column { "Title first line" "Title second line,
464 subtitle = "the subtitle,"
465 subsubtitle = #(string-append "subsubtitle LilyPond version "
468 composer = \markup \center-column { "composer" \small "(1847-1973)" }
469 texttranslator = "Text Translator"
470 meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
472 arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize
473 #-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }
474 instrument = \markup \bold \italic "instrument"
498 As demonstrated before, you can use multiple @code{\header} blocks.
499 When same fields appear in different blocks, the latter is used.
500 Here is a short example.
504 composer = "Composer"
512 piece = "New piece" % overwrite previous one
517 If you define the @code{\header} inside the @code{\score} block, then
518 normally only the @code{piece} and @code{opus} headers will be printed.
519 Note that the music expression must come before the @code{\header}.
521 @lilypond[quote,verbatim,line-width=11.0\cm]
525 title = "title" % not printed
532 @funindex print-all-headers
534 You may change this behavior (and print all the headers when defining
535 @code{\header} inside @code{\score}) by using
539 print-all-headers = ##t
546 The default footer is empty, except for the first page, where the
547 @code{copyright} field from @code{\header} is inserted, and the last
548 page, where @code{tagline} from @code{\header} is added. The default
549 tagline is @qq{Music engraving by LilyPond (@var{version})}.@footnote{Nicely
550 printed parts are good PR for us, so please leave the tagline if you
553 Headers may be completely removed by setting them to false.
564 @subsection Custom titles
566 A more advanced option is to change the definitions of the following
567 variables in the @code{\paper} block. The init file
568 @file{../ly/titling-init.ly} lists the default layout.
571 @funindex bookTitleMarkup
572 @item bookTitleMarkup
573 This is the title added at the top of the entire output document.
574 Typically, it has the composer and the title of the piece
576 @funindex scoreTitleMarkup
577 @item scoreTitleMarkup
578 This is the title put over a @code{\score} block. Typically, it has
579 the name of the movement (@code{piece} field).
581 @funindex oddHeaderMarkup
582 @item oddHeaderMarkup
583 This is the page header for odd-numbered pages.
585 @funindex evenHeaderMarkup
586 @item evenHeaderMarkup
587 This is the page header for even-numbered pages. If unspecified,
588 the odd header is used instead.
590 By default, headers are defined such that the page number is on the
591 outside edge, and the instrument is centered.
593 @funindex oddFooterMarkup
594 @item oddFooterMarkup
595 This is the page footer for odd-numbered pages.
597 @funindex evenFooterMarkup
598 @item evenFooterMarkup
599 This is the page footer for even-numbered pages. If unspecified,
600 the odd header is used instead.
602 By default, the footer has the copyright notice on the first, and
603 the tagline on the last page.
613 The following definition will put the title flush left, and the
614 composer flush right on a single line.
618 bookTitleMarkup = \markup {
620 \fromproperty #'header:title
621 \fromproperty #'header:composer
627 @node Reference to page numbers
628 @subsection Reference to page numbers
630 A particular place of a score can be marked using the @code{\label}
631 command, either at top-level or inside music. This label can then be
632 referred to in a markup, to get the number of the page where the marked
633 point is placed, using the @code{\page-ref} markup command.
635 @lilypond[verbatim,line-width=11.0\cm]
636 \header { tagline = ##f }
642 \pageBreak \mark A \label #'markA
647 \markup { The first score begins on page \page-ref #'firstScore "0" "?" }
648 \markup { Mark A is on page \page-ref #'markA "0" "?" }
652 The @code{\page-ref} markup command takes three arguments:
654 @item the label, a scheme symbol, eg. @code{#'firstScore};
655 @item a markup that will be used as a gauge to estimate the dimensions
657 @item a markup that will be used in place of the page number if the label
661 The reason why a gauge is needed is that, at the time markups are
662 interpreted, the page breaking has not yet occurred, so the page numbers
663 are not yet known. To work around this issue, the actual markup
664 interpretation is delayed to a later time; however, the dimensions of
665 the markup have to be known before, so a gauge is used to decide these
666 dimensions. If the book has between 10 and 99 pages, it may be "00",
667 ie. a two digit number.
678 @node Table of contents
679 @subsection Table of contents
680 A table of contents is included using the @code{\markuplines \table-of-contents}
681 command. The elements which should appear in the table of contents are
682 entered with the @code{\tocItem} command, which may be used either at
683 top-level, or inside a music expression.
686 \markuplines \table-of-contents
689 \tocItem \markup "First score"
693 \tocItem \markup "Some particular point in the first score"
698 \tocItem \markup "Second score"
706 The markups which are used to format the table of contents are defined
707 in the @code{\paper} block. The default ones are @code{tocTitleMarkup},
708 for formatting the title of the table, and @code{tocItemMarkup}, for
709 formatting the toc elements, composed of the element title and page
710 number. These variables may be changed by the user:
714 %% Translate the toc title into French:
715 tocTitleMarkup = \markup \huge \column {
716 \fill-line { \null "Table des matières" \null }
719 %% use larger font size
720 tocItemMarkup = \markup \large \fill-line {
721 \fromproperty #'toc:text \fromproperty #'toc:page
726 Note how the toc element text and page number are referred to in
727 the @code{tocItemMarkup} definition.
729 New commands and markups may also be defined to build more elaborated
732 @item first, define a new markup variable in the @code{\paper} block
733 @item then, define a music function which aims at adding a toc element
734 using this markup paper variable.
737 In the following example, a new style is defined for entering act names
738 in the table of contents of an opera:
742 tocActMarkup = \markup \large \column {
744 \fill-line { \null \italic \fromproperty #'toc:text \null }
750 #(define-music-function (parser location text) (markup?)
751 (add-toc-item! 'tocActMarkup text))
754 @lilypond[line-width=11.0\cm]
755 \header { tagline = ##f }
757 tocActMarkup = \markup \large \column {
759 \fill-line { \null \italic \fromproperty #'toc:text \null }
765 #(define-music-function (parser location text) (markup?)
766 (add-toc-item! 'tocActMarkup text))
769 \markuplines \table-of-contents
770 \tocAct \markup { Atto Primo }
771 \tocItem \markup { Coro. Viva il nostro Alcide }
772 \tocItem \markup { Cesare. Presti omai l'Egizzia terra }
773 \tocAct \markup { Atto Secondo }
774 \tocItem \markup { Sinfonia }
775 \tocItem \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
782 Init files: @file{../ly/@/toc@/-init@/.ly}.
786 @funindex \table-of-contents
787 @code{\table-of-contents},
793 @node Working with input files
794 @section Working with input files
797 * Including LilyPond files::
798 * Different editions from one source::
800 * Displaying LilyPond notation::
804 @node Including LilyPond files
805 @subsection Including LilyPond files
808 @cindex including files
810 A large project may be split up into separate files. To refer to
814 \include "otherfile.ly"
817 The line @code{\include "otherfile.ly"} is equivalent to pasting the
818 contents of @file{otherfile.ly} into the current file at the place
819 where the @code{\include} appears. For example, in a large
820 project you might write separate files for each instrument part
821 and create a @qq{full score} file which brings together the
822 individual instrument files. Normally the included file will
823 define a number of variables which then become available
824 for use in the full score file. Tagged sections can be
825 marked in included files to assist in making them usable in
826 different places in a score, see @ref{Different editions from
829 Files in the current working directory may be referenced by
830 specifying just the file name after the @code{\include} command.
831 Files in other locations may be included by giving either a full
832 path reference or a relative path reference (but use the UNIX
833 forward slash, /, rather than the DOS/Windows back slash, \, as the
834 directory separator.) For example, if @file{stuff.ly} is located
835 one directory higher than the current working directory, use
838 \include "../stuff.ly"
842 or if the included orchestral parts files are all located in a
843 subdirectory called @file{parts} within the current directory, use
846 \include "parts/VI.ly"
847 \include "parts/VII.ly"
851 Files which are to be included can also contain @code{\include}
852 statements of their own. These second-level
853 @code{\include} statements are not interpreted until they have
854 been brought into the main file, so the file names they specify
855 must all be relative to the directory containing the main file,
856 not the directory containing the included file.
858 Files can also be included from a directory in a search path
859 specified as an option when invoking LilyPond from the command
860 line. The included files are then specified using just their
861 file name. For example, to compile @file{main.ly} which includes
862 files located in a subdirectory called @file{parts} by this method,
863 cd to the directory containing @file{main.ly} and enter
866 lilypond --include=parts main.ly
877 Files which are to be included in many scores may be placed in
878 the LilyPond directory @file{../ly}. (The location of this
879 directory is installation-dependent - see @rlearning{Other sources
880 of information}). These files can then be included simply by
881 naming them on an @code{\include} statement. This is how the
882 language-dependent files like @file{english.ly} are included.
884 LilyPond includes a number of files by default when you start
885 the program. These includes are not apparent to the user, but the
886 files may be identified by running @code{lilypond --verbose} from
887 the command line. This will display a list of paths and files that
888 LilyPond uses, along with much other information. Alternatively,
889 the more important of these files are discussed in @rlearning{Other
890 sources of information}. These files may be edited, but changes to
891 them will be lost on installing a new version of LilyPond.
893 Some simple examples of using @code{\include} are shown in
894 @rlearning{Scores and parts}.
898 @rlearning{Other sources of information},
899 @rlearning{Scores and parts}.
903 If an included file is given a name which is the same as one in
904 LilyPond's installation files, LilyPond's file from the
905 installation files takes precedence.
909 @node Different editions from one source
910 @subsection Different editions from one source
912 Several mechanisms are available to facilitate the generation
913 of different versions of a score from the same music source.
914 Variables are perhaps most useful for combining lengthy sections
915 of music and/or annotation in various ways, while tags are more
916 useful for selecting one from several alternative shorter sections
917 of music. Whichever method is used, separating the notation from
918 the structure of the score will make it easier to change the
919 structure while leaving the notation untouched.
926 @node Using variables
927 @unnumberedsubsubsec Using variables
929 @cindex variables, use of
931 If sections of the music are defined in variables they can be
932 reused in different parts of the score, see @rlearning{Organizing
933 pieces with variables}. For example, an @notation{a cappella}
934 vocal score frequently includes a piano reduction of the parts
935 for rehearsal purposes which is identical to the vocal music, so
936 the music need be entered only once. Music from two variables
937 may be combined on one staff, see @ref{Automatic part combining}.
940 @lilypond[verbatim,quote]
941 sopranoMusic = \relative c'' { a4 b c b8( a)}
942 altoMusic = \relative g' { e4 e e f }
943 tenorMusic = \relative c' { c4 b e d8( c) }
944 bassMusic = \relative c' { a4 gis a d, }
945 allLyrics = \lyricmode {King of glo -- ry }
947 \new Staff = "Soprano" \sopranoMusic
948 \new Lyrics \allLyrics
949 \new Staff = "Alto" \altoMusic
950 \new Lyrics \allLyrics
951 \new Staff = "Tenor" {
955 \new Lyrics \allLyrics
956 \new Staff = "Bass" {
960 \new Lyrics \allLyrics
963 \set Staff.printPartCombineTexts = ##f
969 \set Staff.printPartCombineTexts = ##f
979 Separate scores showing just the vocal parts or just the piano
980 part can be produced by changing just the structural statements,
981 leaving the musical notation unchanged.
983 For lengthy scores, the variable definitions may be placed in
984 separate files which are then included, see @ref{Including
988 @unnumberedsubsubsec Using tags
991 @funindex \keepWithTag
992 @funindex \removeWithTag
994 @cindex keep tagged music
995 @cindex remove tagged music
997 The @code{\tag #'@var{partA}} command marks a music expression
998 with the name @var{partA}.
999 Expressions tagged in this way can be selected or filtered out by
1000 name later, using either @code{\keepWithTag #'@var{name}} or
1001 @code{\removeWithTag #'@var{name}}. The result of applying these filters
1002 to tagged music is as follows:
1003 @multitable @columnfractions .5 .5
1007 Tagged music preceded by @code{\keepWithTag #'@var{name}}
1008 @tab Untagged music and music tagged with @var{name} is included;
1009 music tagged with any other tag name is excluded.
1011 Tagged music preceded by @code{\removeWithTag #'@var{name}}
1012 @tab Untagged music and music tagged with any tag name other than
1013 @var{name} is included; music tagged with @var{name} is
1016 Tagged music not preceded by either @code{\keepWithTag} or
1017 @code{\removeWithTag}
1018 @tab All tagged and untagged music is included.
1021 The arguments of the @code{\tag}, @code{\keepWithTag} and
1022 @code{\removeWithTag} commands should be a symbol
1023 (such as @code{#'score} or @code{#'part}), followed
1024 by a music expression.
1026 In the following example, we see two versions of a piece of music,
1027 one showing trills with the usual notation, and one with trills
1028 explicitly expanded:
1030 @lilypond[verbatim,quote]
1031 music = \relative g' {
1033 \tag #'trills {d8.\trill }
1034 \tag #'expand {\repeat unfold 3 {e32 d} }
1039 \keepWithTag #'trills \music
1042 \keepWithTag #'expand \music
1047 Alternatively, it is sometimes easier to exclude sections of music:
1049 @lilypond[verbatim,quote]
1050 music = \relative g' {
1052 \tag #'trills {d8.\trill }
1053 \tag #'expand {\repeat unfold 3 {e32 d} }
1058 \removeWithTag #'expand
1062 \removeWithTag #'trills
1067 Tagged filtering can be applied to articulations, texts, etc. by
1071 -\tag #'@var{your-tag}
1074 to an articulation. For example, this would define a note with a
1075 conditional fingering indication and a note with a conditional
1080 c1-\tag #'warn ^"Watch!"
1083 Multiple tags may be placed on expressions with multiple
1084 @code{\tag} entries:
1086 @lilypond[quote,verbatim]
1087 music = \relative c'' {
1088 \tag #'a \tag #'both { a a a a }
1089 \tag #'b \tag #'both { b b b b }
1092 \keepWithTag #'a \music
1093 \keepWithTag #'b \music
1094 \keepWithTag #'both \music
1098 Multiple @code{\removeWithTag} filters may be applied to a single
1099 music expression to remove several differently named tagged sections:
1101 @lilypond[verbatim,quote]
1102 music = \relative c'' {
1103 \tag #'A { a a a a }
1104 \tag #'B { b b b b }
1105 \tag #'C { c c c c }
1106 \tag #'D { d d d d }
1115 Two or more @code{\keepWithTag} filters applied to a single music
1116 expression will cause @emph{all} tagged sections to be removed, as
1117 the first filter will remove all tagged sections except the one
1118 named, and the second filter will remove even that tagged section.
1123 @rlearning{Organizing pieces with variables}.
1126 @ref{Automatic part combining},
1127 @ref{Including LilyPond files}.
1130 @c This warning is more general than this placement implies.
1131 @c Rests are not merged whether or not they come from tagged sections.
1132 @c Should be deleted? -td
1136 Multiple rests are not merged if you create a score with more
1137 than one tagged section at the same place.
1142 @subsection Text encoding
1144 LilyPond uses the character repertoire defined by the Unicode
1145 consortium and ISO/IEC 10646. This defines a unique name and
1146 code point for the character sets used in virtually all modern
1147 languages and many others too. Unicode can be implemented using
1148 several different encodings. LilyPond uses the UTF-8 encoding
1149 (UTF stands for Unicode Transformation Format) which represents
1150 all common Latin characters in one byte, and represents other
1151 characters using a variable length format of up to four bytes.
1153 The actual appearance of the characters is determined by the
1154 glyphs defined in the particular fonts available - a font defines
1155 the mapping of a subset of the Unicode code points to glyphs.
1156 LilyPond uses the Pango library to layout and render multi-lingual
1159 Lilypond does not perform any input-encoding conversions. This
1160 means that any text, be it title, lyric text, or musical
1161 instruction containing non-ASCII characters, must be encoded in
1162 UTF-8. The easiest way to enter such text is by using a
1163 Unicode-aware editor and saving the file with UTF-8 encoding. Most
1164 popular modern editors have UTF-8 support, for example, vim, Emacs,
1165 jEdit, and GEdit do. All MS Windows systems later than NT use
1166 Unicode as their native character encoding, so even Notepad can
1167 edit and save a file in UTF-8 format. A more functional
1168 alternative for Windows is BabelPad.
1170 If a LilyPond input file containing a non-ASCII character is not
1171 saved in UTF-8 format the error message
1174 FT_Get_Glyph_Name () error: invalid argument
1179 Here is an example showing Cyrillic, Hebrew and Portuguese
1183 %c No verbatim here as the code does not display correctly in PDF
1185 bulgarian = \lyricmode {
1186 Жълтата дюля беше щастлива, че пухът, който цъфна, замръзна като гьон.
1190 hebrew = \lyricmode {
1191 זה כיף סתם לשמוע איך תנצח קרפד עץ טוב בגן.
1195 portuguese = \lyricmode {
1196 à vo -- cê uma can -- ção legal
1202 \addlyrics { \bulgarian }
1203 \addlyrics { \hebrew }
1204 \addlyrics { \portuguese }
1207 To enter a single character for which the Unicode escape sequence
1208 is known but which is not available in the editor being used, use
1209 @code{\char ##xhhhh} within a @code{\markup} block, where
1210 @code{hhhh} is the hexadecimal code for the character required.
1211 For example, @code{\char ##x03BE} enters the Unicode U+03BE
1212 character, which has the Unicode name @qq{Greek Small Letter Xi}.
1213 Any Unicode hexadecimal code may be substituted, and if all special
1214 characters are entered in this format it is not necessary to save
1215 the input file in UTF-8 format. Of course, a font containing all
1216 such encoded characters must be installed and available to LilyPond.
1218 The following example shows UTF-8 coded characters being used in
1219 four places -- in a rehearsal mark, as articulation text, in lyrics
1220 and as stand-alone text below the score:
1222 @lilypond[quote,verbatim]
1225 c1 \mark \markup { \char ##x03EE }
1226 c1_\markup { \tiny { \char ##x03B1 " to " \char ##x03C9 } }
1228 \addlyrics { O \markup { \concat{ Ph \char ##x0153 be! } } }
1230 \markup { "Copyright 2008" \char ##x00A9 }
1233 To enter the copyright sign in the copyright notice use:
1237 copyright = \markup @{ \char ##x00A9 "2008" @}
1241 @node Displaying LilyPond notation
1242 @subsection Displaying LilyPond notation
1244 @funindex \displayLilyMusic
1245 Displaying a music expression in LilyPond notation can be
1246 done using the music function @code{\displayLilyMusic}. For example,
1250 \displayLilyMusic \transpose c a, @{ c e g a bes @}
1257 @{ a, cis e fis g @}
1260 By default, LilyPond will print these messages to the console along
1261 with all the other messages. To split up these messages and save
1262 the results of @code{\display@{STUFF@}}, redirect the output to
1265 @c TODO What happens under Windows?
1268 lilypond file.ly >display.txt
1273 @node Controlling output
1274 @section Controlling output
1277 * Extracting fragments of music::
1278 * Skipping corrected music::
1281 @node Extracting fragments of music
1282 @subsection Extracting fragments of music
1284 It is possible to quote small fragments of a large score directly from
1285 the output. This can be compared to clipping a piece of a paper score
1288 This is done by defining the measures that need to be cut out
1289 separately. For example, including the following definition
1297 (make-rhythmic-location 5 1 2)
1298 (make-rhythmic-location 7 3 4)))
1303 will extract a fragment starting halfway the fifth measure, ending in
1304 the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note
1305 in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7.
1307 More clip regions can be defined by adding more pairs of
1308 rhythmic-locations to the list.
1310 In order to use this feature, LilyPond must be invoked with
1311 @code{-dclip-systems}. The clips are output as EPS files, and are
1312 converted to PDF and PNG if these formats are switched on as well.
1314 For more information on output formats, see @rprogram{Invoking lilypond}.
1316 @node Skipping corrected music
1317 @subsection Skipping corrected music
1320 @funindex skipTypesetting
1321 @funindex showFirstLength
1322 @funindex showLastLength
1324 When entering or copying music, usually only the music near the end (where
1326 are adding notes) is interesting to view and correct. To speed up
1327 this correction process, it is possible to skip typesetting of all but
1328 the last few measures. This is achieved by putting
1331 showLastLength = R1*5
1336 in your source file. This will render only the last 5 measures
1337 (assuming 4/4 time signature) of every @code{\score} in the input
1338 file. For longer pieces, rendering only a small part is often an order
1339 of magnitude quicker than rendering it completely. When working on the
1340 beginning of a score you have already typeset (e.g. to add a new part),
1341 the @code{showFirstLength} property may be useful as well.
1343 Skipping parts of a score can be controlled in a more fine-grained
1344 fashion with the property @code{Score.skipTypesetting}. When it is
1345 set, no typesetting is performed at all.
1347 This property is also used to control output to the MIDI file. Note that
1348 it skips all events, including tempo and instrument changes. You have
1351 @lilypond[quote,fragment,ragged-right,verbatim]
1354 \set Score.skipTypesetting = ##t
1356 \set Score.skipTypesetting = ##f
1360 In polyphonic music, @code{Score.skipTypesetting} will affect all
1361 voices and staves, saving even more time.
1366 @section MIDI output
1371 MIDI (Musical Instrument Digital Interface) is a standard for
1372 connecting and controlling digital instruments. A MIDI file is a
1373 series of notes in a number of tracks. It is not an actual
1374 sound file; you need special software to translate between the
1375 series of notes and actual sounds.
1377 Pieces of music can be converted to MIDI files, so you can listen to
1378 what was entered. This is convenient for checking the music; octaves
1379 that are off or accidentals that were mistyped stand out very much
1380 when listening to the MIDI output.
1383 The midi output allocates a channel for each staff, and one for global
1384 settings. Therefore the midi file should not have more than 15 staves
1385 (or 14 if you do not use drums). Other staves will remain silent.
1388 * Creating MIDI files::
1390 * What goes into the MIDI output?::
1392 * Controlling MIDI dynamics::
1393 * Percussion in MIDI::
1396 @node Creating MIDI files
1397 @subsection Creating MIDI files
1399 To create a MIDI output file from a LilyPond input file, add a
1400 @code{\midi} block to a score, for example,
1409 If there is a @code{\midi} block in a @code{\score} with no
1410 @code{\layout} block, only MIDI output will be produced. When
1411 notation is needed too, a @code{\layout} block must be also be
1422 Pitches, rhythms, ties, dynamics, and tempo changes are interpreted
1423 and translated correctly to the MIDI output. Dynamic marks,
1424 crescendi and decrescendi translate into MIDI volume levels.
1425 Dynamic marks translate to a fixed fraction of the available MIDI
1426 volume range. Crescendi and decrescendi make the volume vary
1427 linearly between their two extremes. The effect of dynamic markings
1428 on the MIDI output can be removed completely, see @ref{MIDI block}.
1430 The initial tempo and later tempo changes can be specified
1431 with the @code{\tempo} command within the music notation. These
1432 are reflected in tempo changes in the MIDI output. This command
1433 will normally result in the metronome mark being printed, but this
1434 can be suppressed, see @ref{Metronome marks}. An alternative way
1435 of specifying the inital or overall MIDI tempo is described below,
1436 see @ref{MIDI block}.
1438 @unnumberedsubsubsec Instrument names
1440 @cindex instrument names
1441 @funindex Staff.midiInstrument
1443 The MIDI instrument to be used is specified by setting the
1444 @code{Staff.midiInstrument} property to the instrument name.
1445 The name should be chosen from the list in @ref{MIDI instruments}.
1449 \set Staff.midiInstrument = "glockenspiel"
1455 \new Staff \with @{midiInstrument = "cello"@} @{
1460 If the selected instrument does not exactly match an instrument from
1461 the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
1467 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
1468 {changing-midi-output-to-one-channel-per-voice.ly}
1472 @c In 2.11 the following no longer seems to be a problem -td
1474 Unterminated (de)crescendos will not render properly in the midi file,
1475 resulting in silent passages of music. The workaround is to explicitly
1476 terminate the (de)crescendo. For example,
1483 will not work properly but
1493 Changes in the MIDI volume take place only on starting a note, so
1494 crescendi and decrescendi cannot affect the volume of a
1497 Not all midi players correctly handle tempo changes in the midi
1498 output. Players that are known to work include MS Windows Media
1499 Player and @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
1502 @subsection MIDI block
1505 A @code{\midi} block must appear within a score block if MIDI output
1506 is required. It is analogous to the layout block, but somewhat
1507 simpler. Often, the @code{\midi} block is left empty, but it
1508 can contain context rearrangements, new context definitions or code
1509 to set the values of properties. For example, the following will
1510 set the initial tempo exported to a MIDI file without causing a tempo
1511 indication to be printed:
1519 tempoWholesPerMinute = #(ly:make-moment 72 4)
1525 In this example the tempo is set to 72 quarter note
1526 beats per minute. This kind of tempo specification cannot take
1527 a dotted note length as an argument. If one is required, break
1528 the dotted note into smaller units. For example, a tempo of 90
1529 dotted quarter notes per minute can be specified as 270 eighth
1533 tempoWholesPerMinute = #(ly:make-moment 270 8)
1536 @cindex MIDI context definitions
1538 Context definitions follow precisely the same syntax as those
1539 within a @code{\layout} block. Translation modules for sound are
1540 called performers. The contexts for MIDI output are defined in
1541 @file{../ly/@/performer@/-init@/.ly},
1542 see @rlearning{Other sources of information}.
1543 For example, to remove the effect of dynamics
1544 from the MIDI output, insert the following lines in the
1545 @code{\midi@{ @}} block.
1552 \remove "Dynamic_performer"
1557 MIDI output is created only when a @code{\midi} block is included
1558 within a score block defined with a @code{\score} command. If it
1559 is placed within an explicitly instantiated score context (i.e.
1560 within a @code{\new Score} block) the file will fail. To solve
1561 this, enclose the @code{\new Score} and the @code{\midi} commands
1562 in a @code{\score} block.
1566 \new Score @{ @dots{}notes@dots{} @}
1571 @node What goes into the MIDI output?
1572 @subsection What goes into the MIDI output?
1574 @c TODO Check grace notes - timing is suspect?
1576 @unnumberedsubsubsec Supported in MIDI
1578 @cindex Pitches in MIDI
1579 @cindex MIDI, Pitches
1580 @cindex Quarter tones in MIDI
1581 @cindex MIDI, quarter tones
1582 @cindex Microtones in MIDI
1583 @cindex MIDI, microtones
1584 @cindex Chord names in MIDI
1585 @cindex MIDI, chord names
1586 @cindex Rhythms in MIDI
1587 @cindex MIDI, Rhythms
1590 The following items of notation are reflected in the MIDI output:
1594 @item Quarter tones (See @ref{Accidentals}. Rendering needs a
1595 player that supports pitch bend.)
1596 @item Chords entered as chord names
1597 @item Rhythms entered as note durations, including tuplets
1598 @item Tremolos entered without @q{@code{:}[@var{number}]}
1601 @item Crescendi, decrescendi over multiple notes
1602 @item Tempo changes entered with a tempo marking
1606 @unnumberedsubsubsec Unsupported in MIDI
1608 @c TODO index as above
1610 The following items of notation have no effect on the MIDI output:
1613 @item Rhythms entered as annotations, e.g. swing
1614 @item Tempo changes entered as annotations with no tempo marking
1615 @item Staccato and other articulations and ornamentations
1616 @item Slurs and Phrasing slurs
1617 @item Crescendi, decrescendi over a single note
1618 @item Tremolos entered with @q{@code{:}[@var{number}]}
1623 @node Repeats in MIDI
1624 @subsection Repeats in MIDI
1626 @cindex repeats in MIDI
1627 @funindex \unfoldRepeats
1629 With a few minor additions, all types of repeats can be represented
1630 in the MIDI output. This is achieved by applying the
1631 @code{\unfoldRepeats} music function. This function changes all
1632 repeats to unfold repeats.
1634 @lilypond[quote,verbatim]
1636 \repeat tremolo 8 {c'32 e' }
1637 \repeat percent 2 { c''8 d'' }
1638 \repeat volta 2 {c'4 d' e' f'}
1647 When creating a score file using @code{\unfoldRepeats} for MIDI,
1648 it is necessary to make two @code{\score} blocks: one for MIDI
1649 (with unfolded repeats) and one for notation (with volta, tremolo,
1650 and percent repeats). For example,
1658 \unfoldRepeats @var{..music..}
1663 @node Controlling MIDI dynamics
1664 @subsection Controlling MIDI dynamics
1666 MIDI dynamics are implemented by the Dynamic_performer which lives
1667 by default in the Voice context. It is possible to control the
1668 overall MIDI volume, the relative volume of dynamic markings and
1669 the relative volume of different instruments.
1671 @unnumberedsubsubsec Dynamic marks
1673 Dynamic marks are translated to a fixed fraction of the available
1674 MIDI volume range. The default fractions range from 0.25 for
1675 @notation{ppppp} to 0.95 for @notation{fffff}. The set of dynamic
1676 marks and the associated fractions can be seen in
1677 @file{../scm/midi.scm}, see @rlearning{Other sources of information}.
1678 This set of fractions may be changed or extended by providing a
1679 function which takes a dynamic mark as its argument and returns the
1680 required fraction, and setting
1681 @code{Score.dynamicAbsoluteVolumeFunction} to this function.
1683 For example, if a @notation{rinforzando} dynamic marking,
1684 @code{\rfz}, is required, this will not by default
1685 have any effect on the MIDI volume, as this dynamic marking is not
1686 included in the default set. Similarly, if a new dynamic marking
1687 has been defined with @code{make-dynamic-script} that too will not
1688 be included in the default set. The following example shows how the
1689 MIDI volume for such dynamic markings might be added. The Scheme
1690 function sets the fraction to 0.9 if a dynamic mark of rfz is
1691 found, or calls the default function otherwise.
1693 @lilypond[verbatim,quote]
1694 #(define (myDynamics dynamic)
1695 (if (equal? dynamic "rfz")
1697 (default-dynamic-absolute-volume dynamic)))
1701 \set Staff.midiInstrument = "cello"
1702 \set Score.dynamicAbsoluteVolumeFunction = #myDynamics
1714 Alternatively, if the whole table of fractions needs to be
1715 redefined, it would be better to use the
1716 @notation{default-dynamic-absolute-volume} procedure in
1717 @file{../scm/midi.scm} and the associated table as a model.
1718 The final example in this section shows how this might be done.
1720 @unnumberedsubsubsec Overall MIDI volume
1722 The minimum and maximum overall volume of MIDI dynamic markings is
1723 controlled by setting the properties @code{midiMinimumVolume} and
1724 @code{midiMaximumVolume} at the @code{Score} level. These
1725 properties have an effect only on dynamic marks, so if they
1726 are to apply from the start of the score a dynamic mark must be
1727 placed there. The fraction corresponding to each dynamic mark is
1728 modified with this formula
1731 midiMinimumVolume + (midiMaximumVolume - midiMinimumVolume) * fraction
1734 In the following example the dynamic range of the overall MIDI
1735 volume is limited to the range 0.2 - 0.5.
1737 @lilypond[verbatim,quote]
1743 \set Staff.midiInstrument = #"flute"
1744 \new Voice \relative c''' {
1752 \set Staff.midiInstrument = #"clarinet"
1753 \new Voice \relative c'' {
1764 tempoWholesPerMinute = #(ly:make-moment 72 2)
1765 midiMinimumVolume = #0.2
1766 midiMaximumVolume = #0.5
1772 @unnumberedsubsubsec Equalizing different instruments (i)
1774 If the minimum and maximum MIDI volume properties are set in
1775 the @code{Staff} context the relative volumes of the MIDI
1776 instruments can be controlled. This gives a basic instrument
1777 equalizer, which can enhance the quality of the MIDI output
1780 In this example the volume of the clarinet is reduced relative
1781 to the volume of the flute. There must be a dynamic
1782 mark on the first note of each instrument for this to work
1785 @lilypond[verbatim,quote]
1791 \set Staff.midiInstrument = #"flute"
1792 \set Staff.midiMinimumVolume = #0.7
1793 \set Staff.midiMaximumVolume = #0.9
1794 \new Voice \relative c''' {
1802 \set Staff.midiInstrument = #"clarinet"
1803 \set Staff.midiMinimumVolume = #0.3
1804 \set Staff.midiMaximumVolume = #0.6
1805 \new Voice \relative c'' {
1816 tempoWholesPerMinute = #(ly:make-moment 72 2)
1822 @unnumberedsubsubsec Equalizing different instruments (ii)
1824 If the MIDI minimum and maximum volume properties are not set
1825 LilyPond will, by default, apply a small degree of equalization
1826 to a few instruments. The instruments and the equalization
1827 applied are shown in the table @notation{instrument-equalizer-alist}
1828 in @file{../scm/midi.scm}.
1830 This basic default equalizer can be replaced by setting
1831 @code{instrumentEqualizer} in the @code{Score} context to a new
1832 Scheme procedure which accepts a MIDI instrument name as its only
1833 argument and returns a pair of fractions giving the minimum and
1834 maximum volumes to be applied to that instrument. This replacement
1835 is done in the same way as shown for resetting the
1836 @code{dynamicAbsoluteVolumeFunction} at the start of this section.
1837 The default equalizer, @notation{default-instrument-equalizer}, in
1838 @file{../scm/midi.scm} shows how such a procedure might be written.
1840 The following example sets the relative flute and clarinet volumes
1841 to the same values as the previous example.
1843 @lilypond[verbatim,quote]
1844 #(define my-instrument-equalizer-alist '())
1846 #(set! my-instrument-equalizer-alist
1849 ("flute" . (0.7 . 0.9))
1850 ("clarinet" . (0.3 . 0.6)))
1851 my-instrument-equalizer-alist))
1853 #(define (my-instrument-equalizer s)
1854 (let ((entry (assoc s my-instrument-equalizer-alist)))
1863 \set Score.instrumentEqualizer = #my-instrument-equalizer
1864 \set Staff.midiInstrument = #"flute"
1865 \new Voice \relative c''' {
1873 \set Staff.midiInstrument = #"clarinet"
1874 \new Voice \relative c'' {
1885 tempoWholesPerMinute = #(ly:make-moment 72 2)
1892 @c Delete when satisfied this is adequately covered elsewhere -td
1894 @n ode Microtones in MIDI
1895 @s ubsection Microtones in MIDI
1897 @cindex microtones in MIDI
1899 Microtones consisting of half sharps and half flats are exported
1900 to the MIDI file and render correctly in MIDI players which support
1901 pitch bending. See @ref{Note names in other languages}. Here is
1902 an example showing all the half sharps and half flats. It can be
1903 copied out and compiled to test microtones in your MIDI player.
1905 @lilypond[verbatim,quote]
1922 @node Percussion in MIDI
1923 @subsection Percussion in MIDI
1925 Percussion instruments are generally notated in a @code{DrumStaff}
1926 context and when notated in this way they are outputted correctly
1927 to MIDI channel@tie{}10, but some pitched percussion instruments,
1928 like the xylophone, marimba, vibraphone, timpani, etc., are
1929 treated like @qq{normal} instruments and music for these instruments
1930 should be entered in a normal @code{Staff} context, not a
1931 @code{DrumStaff} context, to obtain the correct MIDI output.
1933 Some non-pitched percussion sounds included in the general MIDI
1934 standard, like melodic tom, taiko drum, synth drum, etc., cannot
1935 be reached via MIDI channel@tie{}10, so the notation for such
1936 instruments should also be entered in a normal @code{Staff}
1937 context, using suitable normal pitches.
1939 Many percussion instruments are not included in the general MIDI
1940 standard, e.g. castanets. The easiest, although unsatisfactory,
1941 method of producing some MIDI output when writing for such
1942 instruments is to substitute the nearest sound from the standard
1945 @c TODO Expand with examples, and any other issues
1949 Because the general MIDI standard does not contain rim shots, the
1950 sidestick is used for this purpose instead.