]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/notation/input.itely
Change the argument order of \pushToTag and \appendToTag to something making better...
[lilypond.git] / Documentation / notation / input.itely
1 @c -*- coding: utf-8; mode: texinfo; -*-
2
3 @ignore
4     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
5
6     When revising a translation, copy the HEAD committish of the
7     version that you are working on.  For details, see the Contributors'
8     Guide, node Updating translation committishes..
9 @end ignore
10
11 @c \version "2.14.0"
12
13 @node General input and output
14 @chapter General input and output
15
16 This section deals with general LilyPond input and output issues,
17 rather than specific notation.
18
19 @menu
20 * Input structure::
21 * Titles and headers::
22 * Working with input files::
23 * Controlling output::
24 * MIDI output::
25 * Extracting musical information::
26 @end menu
27
28
29 @node Input structure
30 @section Input structure
31
32 The main format of input for LilyPond are text files.  By convention,
33 these files end with @file{.ly}.
34
35 @menu
36 * Structure of a score::
37 * Multiple scores in a book::
38 * Multiple output files from one input file::
39 * Output file names::
40 * File structure::
41 @end menu
42
43
44 @node Structure of a score
45 @subsection Structure of a score
46
47 @funindex \score
48
49 A @code{\score} block must contain a single music expression
50 delimited by curly brackets:
51
52 @example
53 \score @{
54 ...
55 @}
56 @end example
57
58 @warning{There must be @strong{only one} outer music expression in
59 a @code{\score} block, and it @strong{must} be surrounded by
60 curly brackets.}
61
62 This single music expression may be of any size, and may contain
63 other music expressions to any complexity.  All of these examples
64 are music expressions:
65
66 @example
67 @{ c'4 c' c' c' @}
68 @end example
69
70 @lilypond[verbatim,quote]
71 {
72   { c'4 c' c' c' }
73   { d'4 d' d' d' }
74 }
75 @end lilypond
76
77 @lilypond[verbatim,quote]
78 <<
79   \new Staff { c'4 c' c' c' }
80   \new Staff { d'4 d' d' d' }
81 >>
82 @end lilypond
83
84 @example
85 @{
86   \new GrandStaff <<
87     \new StaffGroup <<
88       \new Staff @{ \flute @}
89       \new Staff @{ \oboe @}
90     >>
91     \new StaffGroup <<
92       \new Staff @{ \violinI @}
93       \new Staff @{ \violinII @}
94     >>
95   >>
96 @}
97 @end example
98
99 Comments are one exception to this general rule.  (For others see
100 @ref{File structure}.)  Both single-line comments and comments
101 delimited by @code{%@{ .. %@}} may be placed anywhere within an
102 input file.  They may be placed inside or outside a @code{\score}
103 block, and inside or outside the single music expression within a
104 @code{\score} block.
105
106 Remember that even in a file containing only a @code{\score} block, it
107 is implicitly enclosed in a \book block.  A \book block in a source
108 file produces at least one output file, and by default the name of the
109 output file produced is derived from the name of the input file, so
110 @file{fandangoforelephants.ly} will produce
111 @file{fandangoforelephants.pdf}.
112
113 (For more details  about @code{\book} blocks, see
114 @ref{Multiple scores in a book},
115 @ref{Multiple output files from one input file} @ref{File structure}.)
116
117 @seealso
118 Learning Manual:
119 @rlearning{Working on input files},
120 @rlearning{Music expressions explained},
121 @rlearning{Score is a (single) compound musical expression}.
122
123
124 @node Multiple scores in a book
125 @subsection Multiple scores in a book
126
127 @funindex \book
128 @cindex movements, multiple
129
130 A document may contain multiple pieces of music and text.  Examples
131 of these are an etude book, or an orchestral part with multiple
132 movements.  Each movement is entered with a @code{\score} block,
133
134 @example
135 \score @{
136   @var{..music..}
137 @}
138 @end example
139
140 and texts are entered with a @code{\markup} block,
141
142 @example
143 \markup @{
144   @var{..text..}
145 @}
146 @end example
147
148 @funindex \book
149
150 All the movements and texts which appear in the same @file{.ly} file
151 will normally be typeset in the form of a single output file.
152
153 @example
154 \score @{
155   @var{..}
156 @}
157 \markup @{
158   @var{..}
159 @}
160 \score @{
161   @var{..}
162 @}
163 @end example
164
165 One important exception is within lilypond-book documents,
166 where you explicitly have to add a @code{\book} block, otherwise only
167 the first @code{\score} or @code{\markup} will appear in the output.
168
169 The header for each piece of music can be put inside the @code{\score}
170 block.  The @code{piece} name from the header will be printed before
171 each movement.  The title for the entire book can be put inside the
172 @code{\book}, but if it is not present, the @code{\header} which is at
173 the top of the file is inserted.
174
175 @example
176 \header @{
177   title = "Eight miniatures"
178   composer = "Igor Stravinsky"
179 @}
180 \score @{
181   @dots{}
182   \header @{ piece = "Romanze" @}
183 @}
184 \markup @{
185    ..text of second verse..
186 @}
187 \markup @{
188    ..text of third verse..
189 @}
190 \score @{
191   @dots{}
192   \header @{ piece = "Menuetto" @}
193 @}
194 @end example
195
196 @funindex \bookpart
197
198 Pieces of music may be grouped into book parts using @code{\bookpart}
199 blocks.  Book parts are separated by a page break, and can start with a
200 title, like the book itself, by specifying a @code{\header} block.
201
202 @example
203 \bookpart @{
204   \header @{
205     title = "Book title"
206     subtitle = "First part"
207   @}
208   \score @{ @dots{} @}
209   @dots{}
210 @}
211 \bookpart @{
212   \header @{
213     subtitle = "Second part"
214   @}
215   \score @{ @dots{} @}
216   @dots{}
217 @}
218 @end example
219
220 @node Multiple output files from one input file
221 @subsection Multiple output files from one input file
222
223 If you want multiple output files from the same @file{.ly} file,
224 then you can add multiple @code{\book} blocks, where each
225 such \book block will result in a separate output file.
226 If you do not specify any @code{\book} block in the
227 input file, LilyPond will implicitly treat the whole
228 file as a single \book block, see
229 @ref{File structure}.
230
231 When producing multiple files from a single source file, Lilypond
232 ensures that none of the output files from any @code{\book} block
233 overwrites the output file produced by a preceding @code{\book} from
234 the same input file.
235
236 It does this by adding a suffix to the output name for each
237 @code{\book} which uses the default output file name derived from the
238 input source file.
239
240 The default behaviour is to append a version-number suffix for each
241 name which may clash, so
242
243 @example
244 \book @{
245   \score @{ @dots{} @}
246   \layout @{ @dots{} @}
247 @}
248 \book @{
249   \score @{ @dots{} @}
250   \layout @{ @dots{} @}
251 @}
252 \book @{
253   \score @{ @dots{} @}
254   \layout @{ @dots{} @}
255 @}
256 @end example
257
258 in source file @file{eightminiatures.ly}
259 will produce
260
261 @itemize
262 @item
263 @file{eightminiatures.pdf},
264 @item
265 @file{eightminiatures-1.pdf} and
266 @item
267 @file{eightminiatures-2.pdf}.
268 @end itemize
269
270 @node Output file names
271 @subsection Output file names
272
273 @funindex \bookOutputSuffix
274 @funindex \bookOutputName
275
276 Lilypond provides facilities to allow you to control what file names
277 are used by the various back-ends when producing output files.
278
279 In the previous section, we saw how Lilypond prevents name-clashes when
280 producing several ouputs from a single source file.  You also have the
281 ability to specify your own suffixes for each @code{\book} block, so
282 for example you can produce files called
283 @file{eightminiatures-Romanze.pdf}, @file{eightminiatures-Menuetto.pdf}
284 and @file{eightminiatures-Nocturne.pdf} by adding a
285 @code{\bookOutputSuffix} declaration inside each @code{\book} block.
286
287 @example
288 \book @{
289   \bookOutputSuffix "Romanze"
290   \score @{ @dots{} @}
291   \layout @{ @dots{} @}
292 @}
293 \book @{
294   \bookOutputSuffix "Menuetto"
295   \score @{ @dots{} @}
296   \layout @{ @dots{} @}
297 @}
298 \book @{
299   \bookOutputSuffix "Nocturne"
300   \score @{ @dots{} @}
301   \layout @{ @dots{} @}
302 @}
303 @end example
304
305 You can also specify a different output filename for @code{book} block,
306 by using @code{\bookOutputName} declarations
307
308 @example
309 \book @{
310   \bookOutputName "Romanze"
311   \score @{ @dots{} @}
312   \layout @{ @dots{} @}
313 @}
314 \book @{
315   \bookOutputName "Menuetto"
316   \score @{ @dots{} @}
317   \layout @{ @dots{} @}
318 @}
319 \book @{
320   \bookOutputName "Nocturne"
321   \score @{ @dots{} @}
322   \layout @{ @dots{} @}
323 @}
324 @end example
325
326 The file above will produce these output files:
327
328 @itemize
329 @item
330 @file{Romanze.pdf},
331 @item
332 @file{Menuetto.pdf} and
333 @item
334 @file{Nocturne.pdf}.
335 @end itemize
336
337
338 @node File structure
339 @subsection File structure
340
341 @funindex \paper
342 @funindex \midi
343 @funindex \layout
344 @funindex \header
345 @funindex \score
346 @funindex \book
347 @funindex \bookpart
348
349 A @file{.ly} file may contain any number of toplevel expressions, where a
350 toplevel expression is one of the following:
351
352 @itemize
353 @item
354 An output definition, such as @code{\paper}, @code{\midi}, and
355 @code{\layout}.  Such a definition at the toplevel changes the default
356 book-wide settings.  If more than one such definition of
357 the same type is entered at the top level any definitions in the later
358 expressions have precedence.
359
360 @item
361 A direct scheme expression, such as
362 @code{#(set-default-paper-size "a7" 'landscape)} or
363 @code{#(ly:set-option 'point-and-click #f)}.
364
365 @item
366 A @code{\header} block.  This sets the global header block.  This
367 is the block containing the definitions for book-wide settings, like
368 composer, title, etc.
369
370 @item
371 A @code{\score} block.  This score will be collected with other
372 toplevel scores, and combined as a single @code{\book}.
373 This behavior can be changed by setting the variable
374 @code{toplevel-score-handler} at toplevel.  The default handler is
375 defined in the init file @file{../scm/lily.scm}.
376
377 @item
378 A @code{\book} block logically combines multiple movements
379 (i.e., multiple @code{\score} blocks) in one document.  If there
380 are a number of @code{\score}s, one output file will be created
381 for each @code{\book} block, in which all corresponding movements
382 are concatenated.  The only reason to explicitly specify
383 @code{\book} blocks in a @file{.ly} file is if you wish to create
384 multiple output files from a single input file.  One exception is
385 within lilypond-book documents, where you explicitly have to add
386 a @code{\book} block if you want more than a single @code{\score}
387 or @code{\markup} in the same example.  This behavior can be
388 changed by setting the variable @code{toplevel-book-handler} at
389 toplevel.  The default handler is defined in the init file
390 @file{../scm/lily.scm}.
391
392 @item
393 A @code{\bookpart} block.  A book may be divided into several parts,
394 using @code{\bookpart} blocks, in order to ease the page breaking,
395 or to use different @code{\paper} settings in different parts.
396
397 @item
398 A compound music expression, such as
399 @example
400 @{ c'4 d' e'2 @}
401 @end example
402
403 This will add the piece in a @code{\score} and format it in a
404 single book together with all other toplevel @code{\score}s and music
405 expressions.  In other words, a file containing only the above
406 music expression will be translated into
407
408 @example
409 \book @{
410   \score @{
411     \new Staff @{
412       \new Voice @{
413         @{ c'4 d' e'2 @}
414       @}
415     @}
416   @}
417         \layout @{ @}
418         \header @{ @}
419 @}
420 @end example
421
422 This behavior can be changed by setting the variable
423 @code{toplevel-music-handler} at toplevel.  The default handler is
424 defined in the init file @file{../scm/lily.scm}.
425
426 @item
427 A markup text, a verse for example
428 @example
429 \markup @{
430    2.  The first line verse two.
431 @}
432 @end example
433
434 Markup texts are rendered above, between or below the scores or music
435 expressions, wherever they appear.
436
437 @cindex variables
438
439 @item
440 A variable, such as
441 @example
442 foo = @{ c4 d e d @}
443 @end example
444
445 This can be used later on in the file by entering @code{\foo}.  The
446 name of a variable should have alphabetic characters only; no
447 numbers, underscores or dashes.
448
449 @end itemize
450
451 The following example shows three things that may be entered at
452 toplevel
453
454 @example
455 \layout @{
456   % Don't justify the output
457   ragged-right = ##t
458 @}
459
460 \header @{
461    title = "Do-re-mi"
462 @}
463
464 @{ c'4 d' e2 @}
465 @end example
466
467
468 At any point in a file, any of the following lexical instructions can
469 be entered:
470
471 @itemize
472 @item @code{\version}
473 @item @code{\include}
474 @item @code{\sourcefilename}
475 @item @code{\sourcefileline}
476 @item
477 A single-line comment, introduced by a leading @code{%} sign.
478
479 @item
480 A multi-line comment delimited by @code{%@{ .. %@}}.
481
482 @end itemize
483
484 @cindex whitespace
485
486 Whitespace between items in the input stream is generally ignored,
487 and may be freely omitted or extended to enhance readability.
488 However, whitespace should always be used in the following
489 circumstances to avoid errors:
490
491 @itemize
492 @item Around every opening and closing curly bracket.
493 @item After every command or variable, i.e. every item that
494 begins with a @code{\} sign.
495 @item After every item that is to be interpreted as a Scheme
496 expression, i.e. every item that begins with a @code{#}@tie{}sign.
497 @item To separate all elements of a Scheme expression.
498 @item In @code{lyricmode} to separate all the terms in both
499 @code{\override} and @code{\set} commands.  In particular, spaces
500 must be used around the dot and the equals sign in commands like
501 @code{\override Score . LyricText #'font-size = #5} and before and
502 after the entire command.
503
504 @end itemize
505
506
507 @seealso
508 Learning Manual:
509 @rlearning{How LilyPond input files work}.
510
511
512 @node Titles and headers
513 @section Titles and headers
514
515 Almost all printed music includes a title and the composer's name;
516 some pieces include a lot more information.
517
518 @menu
519 * Creating titles headers and footers::
520 * Custom headers footers and titles::
521 * Reference to page numbers::
522 * Table of contents::
523 @end menu
524
525
526 @node Creating titles headers and footers
527 @subsection Creating titles headers and footers
528
529 @menu
530 * Title blocks explained::
531 * Default layout of book and score title blocks::
532 * Default layout of headers and footers::
533 @end menu
534
535
536 @node Title blocks explained
537 @unnumberedsubsubsec Title blocks explained
538
539 @c TODO: figure out how \bookpart titles work
540
541 There are two types of title blocks: the main title block that appears
542 above of the first @code{\score} of a book, and individual title
543 blocks that appear within each @code{\score} block.  Text fields for
544 both types are entered using a @code{\header} block.
545
546 If the book only has a single score, the @code{\header} block may be
547 placed inside or outside of the @code{\score} block.
548
549 @warning{Remember when adding a @bs{}@code{header} block inside a
550 @bs{}@code{score} block, that the music expression must come before the
551 @bs{}@code{header} block.}
552
553 @lilypond[papersize=a5,quote,verbatim,noragged-right]
554 \header {
555   title = "SUITE I."
556   composer = "J. S. Bach."
557 }
558
559 \score {
560   \new Staff \relative g, {
561     \clef bass
562     \key g \major
563     \repeat unfold 2 { g16( d' b') a b d, b' d, } |
564     \repeat unfold 2 { g,16( e' c') b c e, c' e, } |
565   }
566   \header {
567     piece = "Prélude."
568   }
569 }
570
571 \score {
572   \new Staff \relative b {
573     \clef bass
574     \key g \major
575     \partial 16 b16 |
576     <g, d' b'~>4 b'16 a( g fis) g( d e fis) g( a b c) |
577     d16( b g fis) g( e d c) b(c d e) fis( g a b) |
578   }
579   \header {
580     piece = "Allemande."
581   }
582 }
583 @end lilypond
584
585 Text fields from the main title block of a book can be displayed in all
586 @code{\score} blocks, or manually suppressed:
587
588 @lilypond[papersize=a5,quote,verbatim,noragged-right]
589 \book {
590   \paper {
591     print-all-headers = ##t
592   }
593   \header {
594     title = "DAS WOHLTEMPERIRTE CLAVIER"
595     subtitle = "TEIL I"
596     % Do not display the tagline for this book
597     tagline = ##f
598   }
599   \markup { \vspace #1 }
600   \score {
601     \new PianoStaff <<
602       \new Staff { s1 }
603       \new Staff { \clef "bass" s1 }
604     >>
605     \header {
606       title = "PRAELUDIUM I"
607       opus = "BWV 846"
608       % Do not display the subtitle for this score
609       subtitle = ##f
610     }
611   }
612   \score {
613     \new PianoStaff <<
614       \new Staff { s1 }
615       \new Staff { \clef "bass" s1 }
616     >>
617     \header {
618       title = "FUGA I"
619       subsubtitle = "A 4 VOCI"
620       opus = "BWV 846"
621       % Do not display the subtitle for this score
622       subtitle = ##f
623     }
624   }
625 }
626 @end lilypond
627
628 @seealso
629 Notation Reference:
630 @ref{File structure},
631 @ref{Custom layout for title blocks}.
632
633
634 @node Default layout of book and score title blocks
635 @unnumberedsubsubsec Default layout of book and score title blocks
636
637 The layout and formatting of title blocks are controlled by two
638 @code{\paper} variables; @code{bookTitleMarkup} for the main
639 @code{\header} title block and @code{scoreTitleMarkup} for individual
640 @code{\header} blocks within a @code{\score}.
641
642 @lilypond[papersize=a6,quote,verbatim,noragged-right]
643 \header {
644   % The following fields are centered
645   dedication = "Dedication"
646   title = "Title"
647   subtitle = "Subtitle"
648   subsubtitle = "Subsubtitle"
649   instrument = "Instrument"
650
651   % The following fields are left-aligned on the left side
652   poet = "Poet"
653   meter = "Meter"
654
655   % The following fields are right-aligned on the right side
656   composer = "Composer"
657   arranger = "Arranger"
658 }
659
660 \score {
661   { s1 }
662   \header {
663     % The following fields are placed at opposite ends of the same line
664     piece = "Piece"
665     opus = "Opus"
666   }
667 }
668 @end lilypond
669
670 @c Is the bit about \null markups true? -mp
671
672 Text fields left unset in a @code{\header} block are replaced with
673 @code{\null} markups so that the space is not wasted.
674
675 The default settings for @code{scoreTitleMarkup} place the @code{piece}
676 and @code{opus} text fields at opposite ends of the same line.
677
678 @cindex breakbefore
679
680 Use the @code{breakbefore} variable inside a @code{\header} block
681 that is itself in a @code{\score} block, to make the top-level
682 @code{\header} block titles appear on the first page on their own, with
683 the music (defined in the @code{\score} block) starting on the next.
684
685 @lilypond[papersize=a8landscape,verbatim,noragged-right]
686 \book {
687   \header {
688     title = "This is my Title"
689     subtitle = "This is my Subtitle"
690     copyright = "This is the bottom of the first page"
691   }
692   \score {
693     \repeat unfold 4 { e'' e'' e'' e'' }
694     \header {
695       piece = "This is the Music"
696       breakbefore = ##t
697     }
698   }
699 }
700 @end lilypond
701
702 @seealso
703 Learning Manual:
704 @rlearning{How LilyPond input files work},
705
706 Notation Reference:
707 @ref{File structure}.
708
709 Installed Files:
710 @file{ly/titling-init.ly}.
711
712 @node Default layout of headers and footers
713 @unnumberedsubsubsec Default layout of headers and footers
714
715 @emph{Headers} and @emph{footers} are lines of text appearing at
716 the top and bottom of pages, separate from the main text of a book.
717 They are controlled by the following @code{\paper} variables:
718
719 @itemize
720 @item @code{oddHeaderMarkup}
721 @item @code{evenHeaderMarkup}
722 @item @code{oddFooterMarkup}
723 @item @code{evenFooterMarkup}
724 @end itemize
725
726 These markup variables can only access text fields from top-level
727 @code{\header} blocks (which apply to all scores in the book) and are
728 defined in @file{ly/titling-init.ly}.  By default:
729
730 @itemize
731
732 @item
733 page numbers are automatically placed on the top far left (if even) or
734 top far right (if odd), starting from the second page.
735
736 @item
737 the @code{instrument} text field is placed in the center of every
738 page, starting from the second page.
739
740 @item
741 the @code{copyright} text is centered on the bottom of the first page.
742
743 @item
744 the @code{tagline} is centered on the bottom of the last page, and below
745 the @code{copyright} text if there is only a single page.
746
747 @end itemize
748
749 @lilypond[papersize=a8landscape]
750 \book {
751   \score {
752     \relative c' {
753       c4 d e f
754     }
755   }
756 }
757 @end lilypond
758
759 The default tagline can be changed by adding a @code{tagline} in the
760 top-level @code{\header} block.
761
762 @lilypond[papersize=a8landscape,verbatim]
763 \book {
764   \header {
765     tagline = "... music notation for Everyone"
766   }
767   \score {
768     \relative c' {
769       c4 d e f
770     }
771   }
772 }
773 @end lilypond
774
775 To remove the @code{tagline} set the value to @code{##f}.
776
777
778 @node Custom headers footers and titles
779 @subsection Custom headers footers and titles
780
781 @c TODO: somewhere put a link to header spacing info
782 @c       (you'll have to explain it more in NR 4).
783
784 @menu
785 * Custom text formatting for title blocks::
786 * Custom layout for title blocks::
787 * Custom layout for headers and footers::
788 @end menu
789
790
791 @node Custom text formatting for title blocks
792 @unnumberedsubsubsec Custom text formatting for title blocks
793
794 Standard @code{\markup} commands can be used to customize any header,
795 footer and title text within the @code{\header} block.
796
797 @lilypond[quote,verbatim,noragged-right]
798 \score {
799   { s1 }
800   \header {
801     piece = \markup { \fontsize #4 \bold "PRAELUDIUM I" }
802     subtitle = \markup { \italic "(Excerpt)" }
803   }
804 }
805 @end lilypond
806
807 @seealso
808 Notation Reference:
809 @ref{Formatting text}.
810
811
812 @node Custom layout for title blocks
813 @unnumberedsubsubsec Custom layout for title blocks
814
815 @code{\markup} commands in the @code{\header} block are useful for
816 simple text formatting, but they do not allow precise control over the
817 placement of titles.  To customize the placement of the text fields,
818 use either or both of the following @code{\paper} variables:
819
820 @itemize
821 @item @code{bookTitleMarkup}
822 @item @code{scoreTitleMarkup}
823 @end itemize
824
825 These markup variables are discussed in
826 @ref{Default layout of book and score title blocks}.
827
828 The default settings for @code{scoreTitleMarkup} as defined in
829 @file{ly/titling-init.ly} are:
830
831 @example
832 scoreTitleMarkup = \markup @{ \column @{
833   \on-the-fly #print-all-headers @{ \bookTitleMarkup \hspace #1 @}
834   \fill-line @{
835     \fromproperty #'header:piece
836     \fromproperty #'header:opus
837   @}
838 @}
839 @}
840 @end example
841
842 This places the @code{piece} and @code{opus} text fields at opposite
843 ends of the same line:
844
845 @lilypond[quote,verbatim,noragged-right]
846 \score {
847   { s1 }
848   \header {
849     piece = "PRAELUDIUM I"
850     opus = "BWV 846"
851   }
852 }
853 @end lilypond
854
855 This example redefines @code{scoreTitleMarkup} so that the @code{piece}
856 text field is centered and in a large, bold font.
857
858 @lilypond[papersize=a5,quote,verbatim,noragged-right]
859 \book {
860   \paper {
861     indent = 0\mm
862     scoreTitleMarkup = \markup {
863       \fill-line {
864         \null
865         \fontsize #4 \bold \fromproperty #'header:piece
866         \fromproperty #'header:opus
867       }
868     }
869   }
870   \header { tagline = ##f }
871   \score {
872     { s1 }
873     \header {
874       piece = "PRAELUDIUM I"
875       opus = "BWV 846"
876     }
877   }
878 }
879 @end lilypond
880
881 Text fields normally reserved for the main title block can be included
882 in individual score title blocks with the @code{print-all-headers}
883 placed inside the @code{\paper} block.  A disadvantage of using this
884 method is that the text fields that are intended specifically for the
885 top-level @code{\header} block need to be manually suppressed in every
886 @code{\score} block.  See @ref{Title blocks explained}.
887
888 To avoid this, add the desired text field to the @code{scoreTitleMarkup}
889 definition.  In the following example, the @code{composer} text field
890 (normally associated with @code{bookTitleMarkup}) is added to
891 @code{scoreTitleMarkup}, allowing each score to list a different
892 composer:
893
894 @lilypond[papersize=a5,quote,verbatim,noragged-right]
895 \book {
896   \paper {
897     indent = 0\mm
898     scoreTitleMarkup = \markup {
899       \fill-line {
900         \null
901         \fontsize #4 \bold \fromproperty #'header:piece
902         \fromproperty #'header:composer
903       }
904     }
905   }
906   \header { tagline = ##f }
907   \score {
908     { s1 }
909     \header {
910       piece = "MENUET"
911       composer = "Christian Petzold"
912     }
913   }
914   \score {
915     { s1 }
916     \header {
917       piece = "RONDEAU"
918       composer = "François Couperin"
919     }
920   }
921 }
922 @end lilypond
923
924 It is also possible to create your own custom text fields, and refer to
925 them in the markup definition.
926
927 @lilypond[papersize=a5,quote,verbatim,noragged-right]
928 \book {
929   \paper {
930     indent = 0\mm
931     scoreTitleMarkup = \markup {
932       \fill-line {
933         \null
934         \override #`(direction . ,UP) {
935           \dir-column {
936             \center-align \fontsize #-1 \bold
937               \fromproperty #'header:mycustomtext %% User-defined field
938             \center-align \fontsize #4 \bold
939               \fromproperty #'header:piece
940           }
941         }
942         \fromproperty #'header:opus
943       }
944     }
945   }
946   \header { tagline = ##f }
947   \score {
948     { s1 }
949     \header {
950       piece = "FUGA I"
951       mycustomtext = "A 4 VOCI" %% User-defined field
952       opus = "BWV 846"
953     }
954   }
955 }
956 @end lilypond
957
958 @seealso
959 Notation Reference:
960 @ref{Title blocks explained}.
961
962
963 @node Custom layout for headers and footers
964 @unnumberedsubsubsec Custom layout for headers and footers
965
966 @c can make-header and make-footer be removed from
967 @c paper-defaults-init.ly? -mp
968
969 @code{\markup} commands in the @code{\header} block are useful for
970 simple text formatting, but they do not allow precise control over the
971 placement of headers and footers.  To customize the placement of
972 the text fields, use either or both of the following @code{\paper}
973 variables:
974
975 @itemize
976 @item @code{oddHeaderMarkup}
977 @item @code{evenHeaderMarkup}
978 @item @code{oddFooterMarkup}
979 @item @code{evenFooterMarkup}
980 @end itemize
981
982 The following example centers page numbers at the bottom of every
983 page.  First, the default settings for @code{oddHeaderMarkup} and
984 @code{evenHeaderMarkup} are removed by defining each as a @emph{null}
985 markup.  Then, @code{oddFooterMarkup} is redefined with the page
986 number centered.  Finally, @code{evenFooterMarkup} is given the
987 same layout by defining it as @code{\oddFooterMarkup}:
988
989 @lilypond[papersize=a8,quote,verbatim,noragged-right]
990 \book {
991   \paper {
992     print-page-number = ##t
993     print-first-page-number = ##t
994     oddHeaderMarkup = \markup \null
995     evenHeaderMarkup = \markup \null
996     oddFooterMarkup = \markup {
997       \fill-line {
998         \on-the-fly #print-page-number-check-first
999         \fromproperty #'page:page-number-string
1000       }
1001     }
1002     evenFooterMarkup = \oddFooterMarkup
1003   }
1004   \score {
1005     \new Staff { s1 \break s1 \break s1 }
1006   }
1007 }
1008 @end lilypond
1009
1010 @seealso
1011 Notation Reference:
1012 @ref{Title blocks explained},
1013 @ref{Default layout of book and score title blocks}.
1014
1015
1016 @node Reference to page numbers
1017 @subsection Reference to page numbers
1018
1019 A particular place of a score can be marked using the @code{\label}
1020 command, either at top-level or inside music.  This label can then be
1021 referred to in a markup, to get the number of the page where the marked
1022 point is placed, using the @code{\page-ref} markup command.
1023
1024 @lilypond[verbatim]
1025 \header { tagline = ##f }
1026 \book {
1027   \label #'firstScore
1028   \score {
1029     {
1030       c'1
1031       \pageBreak \mark A \label #'markA
1032       c'1
1033     }
1034   }
1035   \markup { The first score begins on page \page-ref #'firstScore "0" "?" }
1036   \markup { Mark A is on page \page-ref #'markA "0" "?" }
1037 }
1038 @end lilypond
1039
1040 The @code{\page-ref} markup command takes three arguments:
1041 @enumerate
1042 @item the label, a scheme symbol, eg. @code{#'firstScore};
1043 @item a markup that will be used as a gauge to estimate the dimensions
1044 of the markup;
1045 @item a markup that will be used in place of the page number if the label
1046 is not known;
1047 @end enumerate
1048
1049 The reason why a gauge is needed is that, at the time markups are
1050 interpreted, the page breaking has not yet occurred, so the page numbers
1051 are not yet known.  To work around this issue, the actual markup
1052 interpretation is delayed to a later time; however, the dimensions of
1053 the markup have to be known before, so a gauge is used to decide these
1054 dimensions.  If the book has between 10 and 99 pages, it may be "00",
1055 ie. a two digit number.
1056
1057
1058 @predefined
1059 @funindex \label
1060 @code{\label},
1061 @funindex \page-ref
1062 @code{\page-ref}.
1063 @endpredefined
1064
1065
1066 @node Table of contents
1067 @subsection Table of contents
1068 A table of contents is included using the @code{\markuplines \table-of-contents}
1069 command.  The elements which should appear in the table of contents are
1070 entered with the @code{\tocItem} command, which may be used either at
1071 top-level, or inside a music expression.
1072
1073 @verbatim
1074 \markuplines \table-of-contents
1075 \pageBreak
1076
1077 \tocItem \markup "First score"
1078 \score {
1079   {
1080     c'4  % ...
1081     \tocItem \markup "Some particular point in the first score"
1082     d'4  % ...
1083   }
1084 }
1085
1086 \tocItem \markup "Second score"
1087 \score {
1088   {
1089     e'4 % ...
1090   }
1091 }
1092 @end verbatim
1093
1094 The markups which are used to format the table of contents are defined
1095 in the @code{\paper} block.  The default ones are @code{tocTitleMarkup},
1096 for formatting the title of the table, and @code{tocItemMarkup}, for
1097 formatting the toc elements, composed of the element title and page
1098 number.  These variables may be changed by the user:
1099
1100 @verbatim
1101 \paper {
1102   %% Translate the toc title into French:
1103   tocTitleMarkup = \markup \huge \column {
1104     \fill-line { \null "Table des matières" \null }
1105     \hspace #1
1106   }
1107   %% use larger font size
1108   tocItemMarkup = \markup \large \fill-line {
1109     \fromproperty #'toc:text \fromproperty #'toc:page
1110   }
1111 }
1112 @end verbatim
1113
1114 Note how the toc element text and page number are referred to in
1115 the @code{tocItemMarkup} definition.
1116
1117 New commands and markups may also be defined to build more elaborated
1118 table of contents:
1119 @itemize
1120 @item first, define a new markup variable in the @code{\paper} block
1121 @item then, define a music function which aims at adding a toc element
1122 using this markup paper variable.
1123 @end itemize
1124
1125 In the following example, a new style is defined for entering act names
1126 in the table of contents of an opera:
1127
1128 @verbatim
1129 \paper {
1130   tocActMarkup = \markup \large \column {
1131     \hspace #1
1132     \fill-line { \null \italic \fromproperty #'toc:text \null }
1133     \hspace #1
1134   }
1135 }
1136
1137 tocAct =
1138 #(define-music-function (parser location text) (markup?)
1139    (add-toc-item! 'tocActMarkup text))
1140 @end verbatim
1141
1142 @lilypond[line-width=11.0\cm]
1143 \header { tagline = ##f }
1144 \paper {
1145   tocActMarkup = \markup \large \column {
1146     \hspace #1
1147     \fill-line { \null \italic \fromproperty #'toc:text \null }
1148     \hspace #1
1149   }
1150 }
1151
1152 tocAct =
1153 #(define-music-function (parser location text) (markup?)
1154    (add-toc-item! 'tocActMarkup text))
1155
1156 \book {
1157   \markuplines \table-of-contents
1158   \tocAct \markup { Atto Primo }
1159   \tocItem \markup { Coro. Viva il nostro Alcide }
1160   \tocItem \markup { Cesare. Presti omai l'Egizzia terra }
1161   \tocAct \markup { Atto Secondo }
1162   \tocItem \markup { Sinfonia }
1163   \tocItem \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
1164   \markup \null
1165 }
1166 @end lilypond
1167
1168 Dots can be added to fill the line between an item and its page number:
1169
1170 @lilypond[verbatim,quote]
1171 \header { tagline = ##f }
1172 \paper {
1173   tocItemMarkup = \tocItemWithDotsMarkup
1174 }
1175
1176 \book {
1177   \markuplines \table-of-contents
1178   \tocItem \markup { Allegro }
1179   \tocItem \markup { Largo }
1180   \markup \null
1181 }
1182 @end lilypond
1183
1184
1185 @seealso
1186 Init files: @file{../ly/toc-init.ly}.
1187
1188
1189 @predefined
1190 @funindex \table-of-contents
1191 @code{\table-of-contents},
1192 @funindex \tocItem
1193 @code{\tocItem}.
1194 @endpredefined
1195
1196
1197 @node Working with input files
1198 @section Working with input files
1199
1200 @menu
1201 * Including LilyPond files::
1202 * Different editions from one source::
1203 * Special characters::
1204 @end menu
1205
1206
1207 @node Including LilyPond files
1208 @subsection Including LilyPond files
1209
1210 @funindex \include
1211 @cindex including files
1212
1213 A large project may be split up into separate files.  To refer to
1214 another file, use
1215
1216 @example
1217 \include "otherfile.ly"
1218 @end example
1219
1220 The line @code{\include "otherfile.ly"} is equivalent to pasting the
1221 contents of @file{otherfile.ly} into the current file at the place
1222 where the @code{\include} appears.  For example, in a large
1223 project you might write separate files for each instrument part
1224 and create a @qq{full score} file which brings together the
1225 individual instrument files.  Normally the included file will
1226 define a number of variables which then become available
1227 for use in the full score file.  Tagged sections can be
1228 marked in included files to assist in making them usable in
1229 different places in a score, see @ref{Different editions from
1230 one source}.
1231
1232 Files in the current working directory may be referenced by
1233 specifying just the file name after the @code{\include} command.
1234 Files in other locations may be included by giving either a full
1235 path reference or a relative path reference (but use the UNIX
1236 forward slash, /, rather than the DOS/Windows back slash, \, as the
1237 directory separator.)  For example, if @file{stuff.ly} is located
1238 one directory higher than the current working directory, use
1239
1240 @example
1241 \include "../stuff.ly"
1242 @end example
1243
1244 @noindent
1245 or if the included orchestral parts files are all located in a
1246 subdirectory called @file{parts} within the current directory, use
1247
1248 @example
1249 \include "parts/VI.ly"
1250 \include "parts/VII.ly"
1251 ... etc
1252 @end example
1253
1254 Files which are to be included can also contain @code{\include}
1255 statements of their own.  By default, these second-level
1256 @code{\include} statements are not interpreted until they have
1257 been brought into the main file, so the file names they specify
1258 must all be relative to the directory containing the main file,
1259 not the directory containing the included file.  However,
1260 this behavior can be changed by passing the option
1261 @option{-drelative-includes} option at the command line
1262 (or by adding @code{#(ly:set-option 'relative-includes #t)}
1263 at the top of the main input file).  With @code{relative-includes}
1264 set, the path for each @code{\include} command will be taken
1265 relative to the file containing that command.  This behavior is
1266 recommended and it will become the default behavior in a future
1267 version of lilypond.
1268
1269 Files can also be included from a directory in a search path
1270 specified as an option when invoking LilyPond from the command
1271 line.  The included files are then specified using just their
1272 file name.  For example, to compile @file{main.ly} which includes
1273 files located in a subdirectory called @file{parts} by this method,
1274 cd to the directory containing @file{main.ly} and enter
1275
1276 @example
1277 lilypond --include=parts main.ly
1278 @end example
1279
1280 and in main.ly write
1281
1282 @example
1283 \include "VI.ly"
1284 \include "VII.ly"
1285 ... etc
1286 @end example
1287
1288 Files which are to be included in many scores may be placed in
1289 the LilyPond directory @file{../ly}.  (The location of this
1290 directory is installation-dependent - see
1291 @rlearning{Other sources of information}).  These files can then
1292 be included simply by naming them on an @code{\include} statement.
1293 This is how the language-dependent files like @file{english.ly} are
1294 included.
1295
1296 LilyPond includes a number of files by default when you start
1297 the program.  These includes are not apparent to the user, but the
1298 files may be identified by running @code{lilypond --verbose} from
1299 the command line.  This will display a list of paths and files that
1300 LilyPond uses, along with much other information.  Alternatively,
1301 the more important of these files are discussed in
1302 @rlearning{Other sources of information}.  These files may be
1303 edited, but changes to them will be lost on installing a new
1304 version of LilyPond.
1305
1306 Some simple examples of using @code{\include} are shown in
1307 @rlearning{Scores and parts}.
1308
1309 @seealso
1310 Learning Manual:
1311 @rlearning{Other sources of information},
1312 @rlearning{Scores and parts}.
1313
1314 @knownissues
1315 If an included file is given a name which is the same as one in
1316 LilyPond's installation files, LilyPond's file from the
1317 installation files takes precedence.
1318
1319
1320 @node Different editions from one source
1321 @subsection Different editions from one source
1322
1323 Several methods can be used to generate different versions of a score
1324 from the same music source.  Variables are perhaps the most useful for
1325 combining lengthy sections of music and/or annotation.  Tags are more
1326 useful for selecting one section from several alternative shorter
1327 sections of music, and can also be used for splicing pieces of music
1328 together at different points.
1329
1330 Whichever method is used, separating the notation from the structure of
1331 the score will make it easier to change the structure while leaving the
1332 notation untouched.
1333
1334 @menu
1335 * Using variables::
1336 * Using tags::
1337 * Using global settings::
1338 @end menu
1339
1340 @node Using variables
1341 @unnumberedsubsubsec Using variables
1342
1343 @cindex variables, use of
1344
1345 If sections of the music are defined in variables they can be
1346 reused in different parts of the score, see @rlearning{Organizing
1347 pieces with variables}.  For example, an @notation{a cappella}
1348 vocal score frequently includes a piano reduction of the parts
1349 for rehearsal purposes which is identical to the vocal music, so
1350 the music need be entered only once.  Music from two variables
1351 may be combined on one staff, see @ref{Automatic part combining}.
1352 Here is an example:
1353
1354 @lilypond[verbatim,quote]
1355 sopranoMusic = \relative c'' { a4 b c b8( a) }
1356 altoMusic = \relative g' { e4 e e f }
1357 tenorMusic = \relative c' { c4 b e d8( c) }
1358 bassMusic = \relative c' { a4 gis a d, }
1359 allLyrics = \lyricmode {King of glo -- ry }
1360 <<
1361   \new Staff = "Soprano" \sopranoMusic
1362   \new Lyrics \allLyrics
1363   \new Staff = "Alto" \altoMusic
1364   \new Lyrics \allLyrics
1365   \new Staff = "Tenor" {
1366     \clef "treble_8"
1367     \tenorMusic
1368   }
1369   \new Lyrics \allLyrics
1370   \new Staff = "Bass" {
1371     \clef "bass"
1372     \bassMusic
1373   }
1374   \new Lyrics \allLyrics
1375   \new PianoStaff <<
1376     \new Staff = "RH" {
1377       \set Staff.printPartCombineTexts = ##f
1378       \partcombine
1379       \sopranoMusic
1380       \altoMusic
1381     }
1382     \new Staff = "LH" {
1383       \set Staff.printPartCombineTexts = ##f
1384       \clef "bass"
1385       \partcombine
1386       \tenorMusic
1387       \bassMusic
1388     }
1389   >>
1390 >>
1391 @end lilypond
1392
1393 Separate scores showing just the vocal parts or just the piano
1394 part can be produced by changing just the structural statements,
1395 leaving the musical notation unchanged.
1396
1397 For lengthy scores, the variable definitions may be placed in
1398 separate files which are then included, see @ref{Including
1399 LilyPond files}.
1400
1401 @node Using tags
1402 @unnumberedsubsubsec Using tags
1403
1404 @funindex \tag
1405 @funindex \keepWithTag
1406 @funindex \removeWithTag
1407 @funindex \pushToTag
1408 @funindex \appendToTag
1409 @cindex tag
1410 @cindex keep tagged music
1411 @cindex remove tagged music
1412 @cindex splice into tagged music
1413
1414 The @code{\tag #'@var{partA}} command marks a music expression
1415 with the name @var{partA}.
1416 Expressions tagged in this way can be selected or filtered out by
1417 name later, using either @code{\keepWithTag #'@var{name}} or
1418 @code{\removeWithTag #'@var{name}}.  The result of applying these filters
1419 to tagged music is as follows:
1420 @multitable @columnfractions .5 .5
1421 @headitem Filter
1422   @tab Result
1423 @item
1424 Tagged music preceded by @code{\keepWithTag #'@var{name}}
1425   @tab Untagged music and music tagged with @var{name} is included;
1426        music tagged with any other tag name is excluded.
1427 @item
1428 Tagged music preceded by @code{\removeWithTag #'@var{name}}
1429 @tab Untagged music and music tagged with any tag name other than
1430      @var{name} is included; music tagged with @var{name} is
1431      excluded.
1432 @item
1433 Tagged music not preceded by either @code{\keepWithTag} or
1434 @code{\removeWithTag}
1435 @tab All tagged and untagged music is included.
1436 @end multitable
1437
1438 The arguments of the @code{\tag}, @code{\keepWithTag} and
1439 @code{\removeWithTag} commands should be a symbol
1440 (such as @code{#'score} or @code{#'part}), followed
1441 by a music expression.
1442
1443 In the following example, we see two versions of a piece of music,
1444 one showing trills with the usual notation, and one with trills
1445 explicitly expanded:
1446
1447 @lilypond[verbatim,quote]
1448 music = \relative g' {
1449   g8. c32 d
1450   \tag #'trills { d8.\trill }
1451   \tag #'expand { \repeat unfold 3 { e32 d } }
1452   c32 d
1453  }
1454
1455 \score {
1456   \keepWithTag #'trills \music
1457 }
1458 \score {
1459   \keepWithTag #'expand \music
1460 }
1461 @end lilypond
1462
1463 @noindent
1464 Alternatively, it is sometimes easier to exclude sections of music:
1465
1466 @lilypond[verbatim,quote]
1467 music = \relative g' {
1468   g8. c32 d
1469   \tag #'trills { d8.\trill }
1470   \tag #'expand {\repeat unfold 3 { e32 d } }
1471   c32 d
1472  }
1473
1474 \score {
1475   \removeWithTag #'expand
1476   \music
1477 }
1478 \score {
1479   \removeWithTag #'trills
1480   \music
1481 }
1482 @end lilypond
1483
1484 Tagged filtering can be applied to articulations, texts, etc. by
1485 prepending
1486
1487 @example
1488 -\tag #'@var{your-tag}
1489 @end example
1490
1491 to an articulation.  For example, this would define a note with a
1492 conditional fingering indication and a note with a conditional
1493 annotation:
1494
1495 @example
1496 c1-\tag #'finger ^4
1497 c1-\tag #'warn ^"Watch!"
1498 @end example
1499
1500 Multiple tags may be placed on expressions with multiple
1501 @code{\tag} entries:
1502
1503 @lilypond[quote,verbatim]
1504 music = \relative c'' {
1505   \tag #'a \tag #'both { a4 a a a }
1506   \tag #'b \tag #'both { b4 b b b }
1507 }
1508 <<
1509 \keepWithTag #'a \music
1510 \keepWithTag #'b \music
1511 \keepWithTag #'both \music
1512 >>
1513 @end lilypond
1514
1515 Multiple @code{\removeWithTag} filters may be applied to a single
1516 music expression to remove several differently named tagged sections:
1517
1518 @lilypond[verbatim,quote]
1519 music = \relative c'' {
1520 \tag #'A { a4 a a a }
1521 \tag #'B { b4 b b b }
1522 \tag #'C { c4 c c c }
1523 \tag #'D { d4 d d d }
1524 }
1525 {
1526 \removeWithTag #'B
1527 \removeWithTag #'C
1528 \music
1529 }
1530 @end lilypond
1531
1532 Two or more @code{\keepWithTag} filters applied to a single music
1533 expression will cause @emph{all} tagged sections to be removed, as
1534 the first filter will remove all tagged sections except the one
1535 named, and the second filter will remove even that tagged section.
1536
1537 Sometimes you want to splice some music at a particular place in an
1538 existing music expression.  You can use @code{\pushToTag} and
1539 @code{\appendToTag} for adding material at the front or end of the
1540 @code{elements} of an existing music construct.  Not every music
1541 construct has @code{elements}, but sequential and simultaneous music are
1542 safe bets:
1543
1544 @lilypond[verbatim,quote]
1545 test = { \tag #'here { \tag #'here <<c''>> } }
1546
1547 {
1548   \pushToTag #'here c'
1549   \pushToTag #'here e'
1550   \pushToTag #'here g' \test
1551   \appendToTag #'here c'
1552   \appendToTag #'here e'
1553   \appendToTag #'here g' \test
1554 }
1555 @end lilypond
1556
1557 Both commands get a tag, the material to splice in at every occurence of
1558 the tag, and the tagged expression.  The commands make sure to
1559 copy everything that they change so that the original @code{\test}
1560 retains its meaning.
1561
1562 @seealso
1563 Learning Manual:
1564 @rlearning{Organizing pieces with variables}.
1565
1566 Notation Reference:
1567 @ref{Automatic part combining},
1568 @ref{Including LilyPond files}.
1569
1570
1571 @ignore
1572 @c This warning is more general than this placement implies.
1573 @c Rests are not merged whether or not they come from tagged sections.
1574 @c Should be deleted?  -td
1575
1576 @knownissues
1577
1578 Multiple rests are not merged if you create a score with more
1579 than one tagged section at the same place.
1580
1581 @end ignore
1582
1583 @node Using global settings
1584 @unnumberedsubsubsec Using global settings
1585
1586 @cindex include-settings
1587
1588 Global settings can be included from a separate file:
1589
1590 @example
1591 lilypond -dinclude-settings=MY_SETTINGS.ly MY_SCORE.ly
1592 @end example
1593
1594 Groups of settings such as page size, font or type face can be stored
1595 in separate files. This allows different editions from the same score
1596 as well as standard settings to be applied to many scores, simply by
1597 specifying the proper settings file.
1598
1599 This technique also works well with the use of style sheets, as
1600 discussed in @rlearning{Style sheets}.
1601
1602 @seealso
1603 Learning Manual:
1604 @rlearning{Organizing pieces with variables},
1605 @rlearning{Style sheets}.
1606
1607 Notation Reference:
1608 @ref{Including LilyPond files}.
1609
1610 @node Special characters
1611 @subsection Special characters
1612
1613 @cindex special characters
1614 @cindex non-ASCII characters
1615
1616 @menu
1617 * Text encoding::
1618 * Unicode::
1619 * ASCII aliases::
1620 @end menu
1621
1622
1623 @node Text encoding
1624 @unnumberedsubsubsec Text encoding
1625
1626 @cindex UTF-8
1627
1628 LilyPond uses the character repertoire defined by the Unicode
1629 consortium and ISO/IEC 10646.  This defines a unique name and
1630 code point for the character sets used in virtually all modern
1631 languages and many others too.  Unicode can be implemented using
1632 several different encodings.  LilyPond uses the UTF-8 encoding
1633 (UTF stands for Unicode Transformation Format) which represents
1634 all common Latin characters in one byte, and represents other
1635 characters using a variable length format of up to four bytes.
1636
1637 The actual appearance of the characters is determined by the
1638 glyphs defined in the particular fonts available - a font defines
1639 the mapping of a subset of the Unicode code points to glyphs.
1640 LilyPond uses the Pango library to layout and render multi-lingual
1641 texts.
1642
1643 LilyPond does not perform any input-encoding conversions.  This
1644 means that any text, be it title, lyric text, or musical
1645 instruction containing non-ASCII characters, must be encoded in
1646 UTF-8.  The easiest way to enter such text is by using a
1647 Unicode-aware editor and saving the file with UTF-8 encoding.  Most
1648 popular modern editors have UTF-8 support, for example, vim, Emacs,
1649 jEdit, and GEdit do.  All MS Windows systems later than NT use
1650 Unicode as their native character encoding, so even Notepad can
1651 edit and save a file in UTF-8 format.  A more functional
1652 alternative for Windows is BabelPad.
1653
1654 If a LilyPond input file containing a non-ASCII character is not
1655 saved in UTF-8 format the error message
1656
1657 @example
1658 FT_Get_Glyph_Name () error: invalid argument
1659 @end example
1660
1661 will be generated.
1662
1663 Here is an example showing Cyrillic, Hebrew and Portuguese
1664 text:
1665
1666 @lilypond[quote]
1667 %c No verbatim here as the code does not display correctly in PDF
1668 % Cyrillic
1669 bulgarian = \lyricmode {
1670   Жълтата дюля беше щастлива, че пухът, който цъфна, замръзна като гьон.
1671 }
1672
1673 % Hebrew
1674 hebrew = \lyricmode {
1675   זה כיף סתם לשמוע איך תנצח קרפד עץ טוב בגן.
1676 }
1677
1678 % Portuguese
1679 portuguese = \lyricmode {
1680   à vo -- cê uma can -- ção legal
1681 }
1682
1683 \relative c' {
1684   c2 d e f g f e
1685 }
1686 \addlyrics { \bulgarian }
1687 \addlyrics { \hebrew }
1688 \addlyrics { \portuguese }
1689 @end lilypond
1690
1691
1692 @node Unicode
1693 @unnumberedsubsubsec Unicode
1694
1695 @cindex Unicode
1696
1697 To enter a single character for which the Unicode code point is
1698 known but which is not available in the editor being used, use
1699 either @code{\char ##xhhhh} or @code{\char #dddd} within a
1700 @code{\markup} block, where @code{hhhh} is the hexadecimal code for
1701 the character required and @code{dddd} is the corresponding decimal
1702 value.  Leading zeroes may be omitted, but it is usual to specify
1703 all four characters in the hexadecimal representation.  (Note that
1704 the UTF-8 encoding of the code point should @emph{not} be used
1705 after @code{\char}, as UTF-8 encodings contain extra bits indicating
1706 the number of octets.)  Unicode code charts and a character name
1707 index giving the code point in hexadecimal for any character can be
1708 found on the Unicode Consortium website,
1709 @uref{http://www.unicode.org/}.
1710
1711 For example, @code{\char ##x03BE} and @code{\char #958} would both
1712 enter the Unicode U+03BE character, which has the Unicode name
1713 @qq{Greek Small Letter Xi}.
1714
1715 Any Unicode code point may be entered in this way and if all special
1716 characters are entered in this format it is not necessary to save
1717 the input file in UTF-8 format.  Of course, a font containing all
1718 such encoded characters must be installed and available to LilyPond.
1719
1720 The following example shows Unicode hexadecimal values being entered
1721 in four places -- in a rehearsal mark, as articulation text, in
1722 lyrics and as stand-alone text below the score:
1723
1724 @lilypond[quote,verbatim]
1725 \score {
1726   \relative c'' {
1727     c1 \mark \markup { \char ##x03EE }
1728     c1_\markup { \tiny { \char ##x03B1 " to " \char ##x03C9 } }
1729   }
1730   \addlyrics { O \markup { \concat { Ph \char ##x0153 be! } } }
1731 }
1732 \markup { "Copyright 2008--2011" \char ##x00A9 }
1733 @end lilypond
1734
1735 @cindex copyright sign
1736
1737 To enter the copyright sign in the copyright notice use:
1738
1739 @example
1740 \header @{
1741   copyright = \markup @{ \char ##x00A9 "2008" @}
1742 @}
1743 @end example
1744
1745
1746 @node ASCII aliases
1747 @unnumberedsubsubsec ASCII aliases
1748
1749 A list of ASCII aliases for special characters can be included:
1750
1751 @lilypond[quote,verbatim]
1752 \paper {
1753   #(include-special-characters)
1754 }
1755
1756 \markup "&flqq; &ndash; &OE;uvre incomplète&hellip; &frqq;"
1757
1758 \score {
1759   \new Staff { \repeat unfold 9 a'4 }
1760   \addlyrics {
1761     This is al -- so wor -- kin'~in ly -- rics: &ndash;_&OE;&hellip;
1762   }
1763 }
1764
1765 \markup \column {
1766   "The replacement can be disabled:"
1767   "&ndash; &OE; &hellip;"
1768   \override #'(replacement-alist . ()) "&ndash; &OE; &hellip;"
1769 }
1770 @end lilypond
1771
1772 You can also make your own aliases, either globally:
1773
1774 @lilypond[quote,verbatim]
1775 \paper {
1776   #(add-text-replacements!
1777     '(("100" . "hundred")
1778       ("dpi" . "dots per inch")))
1779 }
1780 \markup "A 100 dpi."
1781 @end lilypond
1782
1783 or locally:
1784
1785 @lilypond[quote,verbatim]
1786 \markup \replace #'(("100" . "hundred")
1787                     ("dpi" . "dots per inch")) "A 100 dpi."
1788 @end lilypond
1789
1790 @seealso
1791 Notation Reference:
1792 @ref{List of special characters}.
1793
1794 Installed Files:
1795 @file{ly/text-replacements.ly}.
1796
1797
1798
1799 @node Controlling output
1800 @section Controlling output
1801
1802 @menu
1803 * Extracting fragments of music::
1804 * Skipping corrected music::
1805 * Alternative output formats::
1806 * Replacing the notation font::
1807 @end menu
1808
1809 @node Extracting fragments of music
1810 @subsection Extracting fragments of music
1811
1812 It is possible to quote small fragments of a large score directly from
1813 the output.  This can be compared to clipping a piece of a paper score
1814 with scissors.
1815
1816 This is done by defining the measures that need to be cut out
1817 separately.  For example, including the following definition
1818
1819
1820 @verbatim
1821 \layout {
1822   clip-regions
1823   = #(list
1824       (cons
1825        (make-rhythmic-location 5 1 2)
1826        (make-rhythmic-location 7 3 4)))
1827 }
1828 @end verbatim
1829
1830 @noindent
1831 will extract a fragment starting halfway the fifth measure, ending in
1832 the seventh measure.  The meaning of @code{5 1 2} is: after a 1/2 note
1833 in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7.
1834
1835 More clip regions can be defined by adding more pairs of
1836 rhythmic-locations to the list.
1837
1838 In order to use this feature, LilyPond must be invoked with
1839 @option{-dclip-systems}.  The clips are output as EPS files, and are
1840 converted to PDF and PNG if these formats are switched on as well.
1841
1842 For more information on output formats, see @rprogram{Invoking lilypond}.
1843
1844 @node Skipping corrected music
1845 @subsection Skipping corrected music
1846
1847
1848 @funindex skipTypesetting
1849 @funindex showFirstLength
1850 @funindex showLastLength
1851
1852 When entering or copying music, usually only the music near the end (where
1853 you
1854 are adding notes) is interesting to view and correct.  To speed up
1855 this correction process, it is possible to skip typesetting of all but
1856 the last few measures.  This is achieved by putting
1857
1858 @verbatim
1859 showLastLength = R1*5
1860 \score { ... }
1861 @end verbatim
1862
1863 @noindent
1864 in your source file.  This will render only the last 5 measures
1865 (assuming 4/4 time signature) of every @code{\score} in the input
1866 file.  For longer pieces, rendering only a small part is often an order
1867 of magnitude quicker than rendering it completely.  When working on the
1868 beginning of a score you have already typeset (e.g. to add a new part),
1869 the @code{showFirstLength} property may be useful as well.
1870
1871 Skipping parts of a score can be controlled in a more fine-grained
1872 fashion with the property @code{Score.skipTypesetting}.  When it is
1873 set, no typesetting is performed at all.
1874
1875 This property is also used to control output to the MIDI file.  Note that
1876 it skips all events, including tempo and instrument changes.  You have
1877 been warned.
1878
1879 @lilypond[quote,relative=2,ragged-right,verbatim]
1880 c8 d
1881 \set Score.skipTypesetting = ##t
1882 e8 e e e e e e e
1883 \set Score.skipTypesetting = ##f
1884 c8 d b bes a g c2
1885 @end lilypond
1886
1887 In polyphonic music, @code{Score.skipTypesetting} will affect all
1888 voices and staves, saving even more time.
1889
1890 @node Alternative output formats
1891 @subsection Alternative output formats
1892
1893 @cindex scalable vector graphics output
1894 @cindex SVG output
1895 @cindex encapsulated postscript output
1896 @cindex EPS output
1897
1898 The default output formats for the printed score are Portable
1899 Document Format (PDF) and PostScript (PS).  Scalable Vector
1900 Graphics (SVG), Encapsulated PostScript (EPS) and Portable
1901 Network Graphics (PNG) output formats are also available through
1902 command line options, see @rprogram{Command line options for
1903 lilypond}.
1904
1905
1906 @node Replacing the notation font
1907 @subsection Replacing the notation font
1908
1909 Gonville is an alternative to the Feta font used in LilyPond and can
1910 be downloaded from:
1911 @example
1912 @uref{http://www.chiark.greenend.org.uk/~sgtatham/gonville/ ,http://www.chiark.greenend.org.uk/~sgtatham/gonville/}
1913 @end example
1914
1915 Here are a few sample bars of music set in Gonville:
1916
1917 @c NOTE: these images are a bit big, but that's important
1918 @c       for the font comparison.  -gp
1919 @sourceimage{Gonville_after,,,}
1920
1921 Here are a few sample bars of music set in LilyPond's Feta font:
1922
1923 @sourceimage{Gonville_before,,,}
1924
1925 @subsubheading Installation Instructions for MacOS
1926
1927 Download and extract the zip file.  Copy the @code{lilyfonts}
1928 directory to @file{@var{SHARE_DIR}/lilypond/current}; for more
1929 information, see @rlearning{Other sources of information}.  Rename the
1930 existing @code{fonts} directory to @code{fonts_orig} and the
1931 @code{lilyfonts} directory to @code{fonts}.  To revert back to Feta,
1932 reverse the process.
1933
1934 @seealso
1935 Learning Manual: @rlearning{Other sources of information}.
1936
1937 @knownissues
1938 Gonville cannot be used to typeset @q{Ancient Music} notation and it is
1939 likely newer glyphs in later releases of LilyPond may not exist in the
1940 Gonville font family.  Please refer to the author's website for more
1941 information on these and other specifics, including licensing of
1942 Gonville.
1943
1944
1945 @node MIDI output
1946 @section MIDI output
1947
1948 @cindex Sound
1949 @cindex MIDI
1950
1951 MIDI (Musical Instrument Digital Interface) is a standard for
1952 connecting and controlling digital instruments.  A MIDI file is a
1953 series of notes in a number of tracks.  It is not an actual
1954 sound file; you need special software to translate between the
1955 series of notes and actual sounds.
1956
1957 Pieces of music can be converted to MIDI files, so you can listen to
1958 what was entered.  This is convenient for checking the music; octaves
1959 that are off or accidentals that were mistyped stand out very much
1960 when listening to the MIDI output.
1961
1962 Standard MIDI oputput is somewhat crude; optionally, an enhanced and
1963 more realistic MIDI output is available by means of
1964 @ref{The Articulate script}.
1965
1966 @c TODO Check this
1967 The midi output allocates a channel for each staff, and one for global
1968 settings.  Therefore the midi file should not have more than 15 staves
1969 (or 14 if you do not use drums).  Other staves will remain silent.
1970
1971 @menu
1972 * Creating MIDI files::
1973 * MIDI block::
1974 * What goes into the MIDI output?::
1975 * Repeats in MIDI::
1976 * Controlling MIDI dynamics::
1977 * Percussion in MIDI::
1978 * The Articulate script::
1979 @end menu
1980
1981 @node Creating MIDI files
1982 @subsection Creating MIDI files
1983
1984 To create a MIDI output file from a LilyPond input file, add a
1985 @code{\midi} block to a score, for example,
1986
1987 @example
1988 \score @{
1989   @var{...music...}
1990   \midi @{ @}
1991 @}
1992 @end example
1993
1994 If there is a @code{\midi} block in a @code{\score} with no
1995 @code{\layout} block, only MIDI output will be produced.  When
1996 notation is needed too, a @code{\layout} block must also be
1997 present.
1998
1999 @example
2000 \score @{
2001   @var{...music...}
2002   \midi @{ @}
2003   \layout @{ @}
2004 @}
2005 @end example
2006
2007 Pitches, rhythms, ties, dynamics, and tempo changes are interpreted
2008 and translated correctly to the MIDI output.  Dynamic marks,
2009 crescendi and decrescendi translate into MIDI volume levels.
2010 Dynamic marks translate to a fixed fraction of the available MIDI
2011 volume range.  Crescendi and decrescendi make the volume vary
2012 linearly between their two extremes.  The effect of dynamic markings
2013 on the MIDI output can be removed completely, see @ref{MIDI block}.
2014
2015 The initial tempo and later tempo changes can be specified
2016 with the @code{\tempo} command within the music notation.  These
2017 are reflected in tempo changes in the MIDI output.  This command
2018 will normally result in the metronome mark being printed, but this
2019 can be suppressed, see @ref{Metronome marks}.  An alternative way
2020 of specifying the initial or overall MIDI tempo is described below,
2021 see @ref{MIDI block}.
2022
2023 Due to some limitations on Windows, the default extension for
2024 MIDI files on Windows is @code{.mid}.  Other operating systems still
2025 use the extension @code{.midi}.  If a different extension is preferred,
2026 insert the following line at the top-level of the input file,
2027 before the start of any @code{\book}, @code{\bookpart} or @code{\score} blocks:
2028
2029 @example
2030 #(ly:set-option 'midi-extension "midi")
2031 @end example
2032
2033 The line above will set the default extension for MIDI files to
2034 @code{.midi}.
2035
2036 Alternatively, this option can also be supplied on the command line:
2037
2038 @example
2039 lilypond … -dmidi-extension=midi lilyFile.ly
2040 @end example
2041
2042
2043 @unnumberedsubsubsec Instrument names
2044
2045 @cindex instrument names
2046 @funindex Staff.midiInstrument
2047
2048 The MIDI instrument to be used is specified by setting the
2049 @code{Staff.midiInstrument} property to the instrument name.
2050 The name should be chosen from the list in @ref{MIDI instruments}.
2051
2052 @example
2053 \new Staff @{
2054   \set Staff.midiInstrument = #"glockenspiel"
2055   @var{...notes...}
2056 @}
2057 @end example
2058
2059 @example
2060 \new Staff \with @{midiInstrument = #"cello"@} @{
2061   @var{...notes...}
2062 @}
2063 @end example
2064
2065 If the selected instrument does not exactly match an instrument from
2066 the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
2067 instrument is used.
2068
2069
2070 @snippets
2071
2072 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
2073 {changing-midi-output-to-one-channel-per-voice.ly}
2074
2075 @knownissues
2076
2077 @c In 2.11 the following no longer seems to be a problem -td
2078 @ignore
2079 Unterminated (de)crescendos will not render properly in the midi file,
2080 resulting in silent passages of music.  The workaround is to explicitly
2081 terminate the (de)crescendo.  For example,
2082
2083 @example
2084 @{ a4\< b c d\f @}
2085 @end example
2086
2087 @noindent
2088 will not work properly but
2089
2090 @example
2091 @{ a4\< b c d\!\f @}
2092 @end example
2093
2094 @noindent
2095 will.
2096 @end ignore
2097
2098 Changes in the MIDI volume take place only on starting a note, so
2099 crescendi and decrescendi cannot affect the volume of a
2100 single note.
2101
2102 Not all midi players correctly handle tempo changes in the midi
2103 output.  Players that are known to work include MS Windows Media
2104 Player and @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
2105
2106 @node MIDI block
2107 @subsection MIDI block
2108 @cindex MIDI block
2109
2110 A @code{\midi} block must appear within a score block if MIDI output
2111 is required.  It is analogous to the layout block, but somewhat
2112 simpler.  Often, the @code{\midi} block is left empty, but it
2113 can contain context rearrangements, new context definitions or code
2114 to set the values of properties.  For example, the following will
2115 set the initial tempo exported to a MIDI file without causing a tempo
2116 indication to be printed:
2117
2118 @example
2119 \score @{
2120   @var{...music...}
2121   \midi @{
2122     \context @{
2123       \Score
2124       tempoWholesPerMinute = #(ly:make-moment 72 4)
2125     @}
2126   @}
2127 @}
2128 @end example
2129
2130 In this example the tempo is set to 72 quarter note
2131 beats per minute.  This kind of tempo specification cannot take
2132 a dotted note length as an argument.  If one is required, break
2133 the dotted note into smaller units.  For example, a tempo of 90
2134 dotted quarter notes per minute can be specified as 270 eighth
2135 notes per minute:
2136
2137 @example
2138 tempoWholesPerMinute = #(ly:make-moment 270 8)
2139 @end example
2140
2141 @cindex MIDI context definitions
2142
2143 Context definitions follow precisely the same syntax as those
2144 within a @code{\layout} block.  Translation modules for sound are
2145 called performers.  The contexts for MIDI output are defined in
2146 @file{../ly/performer-init.ly},
2147 see @rlearning{Other sources of information}.
2148 For example, to remove the effect of dynamics
2149 from the MIDI output, insert the following lines in the
2150 @code{\midi@{ @}} block.
2151
2152 @example
2153 \midi @{
2154   ...
2155   \context @{
2156     \Voice
2157     \remove "Dynamic_performer"
2158   @}
2159 @}
2160 @end example
2161
2162 MIDI output is created only when a @code{\midi} block is included
2163 within a score block defined with a @code{\score} command.
2164
2165 @example
2166 \score @{
2167   @{ @dots{}notes@dots{} @}
2168   \midi @{ @}
2169 @}
2170 @end example
2171
2172 @node What goes into the MIDI output?
2173 @subsection What goes into the MIDI output?
2174
2175 @c TODO Check grace notes - timing is suspect?
2176
2177 @unnumberedsubsubsec Supported in MIDI
2178
2179 @cindex Pitches in MIDI
2180 @cindex MIDI, Pitches
2181 @cindex Quarter tones in MIDI
2182 @cindex MIDI, quarter tones
2183 @cindex Microtones in MIDI
2184 @cindex MIDI, microtones
2185 @cindex Chord names in MIDI
2186 @cindex MIDI, chord names
2187 @cindex Rhythms in MIDI
2188 @cindex MIDI, Rhythms
2189 @cindex Articlulate scripts
2190 @cindex MIDI, articulations
2191 @cindex articulations in MIDI
2192 @cindex trills in MIDI
2193 @cindex turns in MIDI
2194 @cindex rallentando in MIDI
2195 @cindex accelerando in MIDI
2196 @c TODO etc
2197
2198 The following items of notation are reflected in the MIDI output:
2199
2200 @itemize
2201 @item Pitches
2202 @item Microtones (See @ref{Accidentals}.  Rendering needs a
2203 player that supports pitch bend.)
2204 @item Chords entered as chord names
2205 @item Rhythms entered as note durations, including tuplets
2206 @item Tremolos entered without @q{@code{:}[@var{number}]}
2207 @item Ties
2208 @item Dynamic marks
2209 @item Crescendi, decrescendi over multiple notes
2210 @item Tempo changes entered with a tempo marking
2211 @item Lyrics
2212 @end itemize
2213
2214 Using @ref{The Articulate script}, a number of items are added to the
2215 above list:
2216
2217 @itemize
2218 @item Articulations (slurs, staccato, etc)
2219 @item Trills, turns
2220 @item Rallentando and accelerando
2221 @end itemize
2222
2223
2224 @unnumberedsubsubsec Unsupported in MIDI
2225
2226 @c TODO index as above
2227
2228 The following items of notation have no effect on the MIDI output,
2229 unless you use @ref{The Articulate script}:
2230
2231 @itemize
2232 @item Rhythms entered as annotations, e.g. swing
2233 @item Tempo changes entered as annotations with no tempo marking
2234 @item Staccato and other articulations and ornamentations
2235 @item Slurs and Phrasing slurs
2236 @item Crescendi, decrescendi over a single note
2237 @item Tremolos entered with @q{@code{:}[@var{number}]}
2238 @item Figured bass
2239 @item Microtonal chords
2240 @end itemize
2241
2242
2243 @node Repeats in MIDI
2244 @subsection Repeats in MIDI
2245
2246 @cindex repeats in MIDI
2247 @funindex \unfoldRepeats
2248
2249 With a few minor additions, all types of repeats can be represented
2250 in the MIDI output.  This is achieved by applying the
2251 @code{\unfoldRepeats} music function.  This function changes all
2252 repeats to unfold repeats.
2253
2254 @lilypond[quote,verbatim]
2255 \unfoldRepeats {
2256   \repeat tremolo 8 { c'32 e' }
2257   \repeat percent 2 { c''8 d'' }
2258   \repeat volta 2 { c'4 d' e' f' }
2259   \alternative {
2260     { g' a' a' g' }
2261     { f' e' d' c' }
2262   }
2263 }
2264 \bar "|."
2265 @end lilypond
2266
2267 In scores containing multiple voices, unfolding of repeats in MIDI
2268 output will only occur correctly if @emph{each} voice contains fully
2269 notated repeat indications.
2270
2271 When creating a score file using @code{\unfoldRepeats} for MIDI,
2272 it is necessary to make two @code{\score} blocks: one for MIDI
2273 (with unfolded repeats) and one for notation (with volta, tremolo,
2274 and percent repeats).  For example,
2275
2276 @example
2277 \score @{
2278   @var{..music..}
2279   \layout @{ .. @}
2280 @}
2281 \score @{
2282   \unfoldRepeats @var{..music..}
2283   \midi @{ .. @}
2284 @}
2285 @end example
2286
2287 @node Controlling MIDI dynamics
2288 @subsection Controlling MIDI dynamics
2289
2290 MIDI dynamics are implemented by the Dynamic_performer which lives
2291 by default in the Voice context.  It is possible to control the
2292 overall MIDI volume, the relative volume of dynamic markings and
2293 the relative volume of different instruments.
2294
2295 @unnumberedsubsubsec Dynamic marks
2296
2297 Dynamic marks are translated to a fixed fraction of the available
2298 MIDI volume range.  The default fractions range from 0.25 for
2299 @notation{ppppp} to 0.95 for @notation{fffff}.  The set of dynamic
2300 marks and the associated fractions can be seen in
2301 @file{../scm/midi.scm}, see @rlearning{Other sources of information}.
2302 This set of fractions may be changed or extended by providing a
2303 function which takes a dynamic mark as its argument and returns the
2304 required fraction, and setting
2305 @code{Score.dynamicAbsoluteVolumeFunction} to this function.
2306
2307 For example, if a @notation{rinforzando} dynamic marking,
2308 @code{\rfz}, is required, this will not by default
2309 have any effect on the MIDI volume, as this dynamic marking is not
2310 included in the default set.  Similarly, if a new dynamic marking
2311 has been defined with @code{make-dynamic-script} that too will not
2312 be included in the default set.  The following example shows how the
2313 MIDI volume for such dynamic markings might be added.  The Scheme
2314 function sets the fraction to 0.9 if a dynamic mark of rfz is
2315 found, or calls the default function otherwise.
2316
2317 @lilypond[verbatim,quote]
2318 #(define (myDynamics dynamic)
2319     (if (equal? dynamic "rfz")
2320       0.9
2321       (default-dynamic-absolute-volume dynamic)))
2322
2323 \score {
2324   \new Staff {
2325     \set Staff.midiInstrument = #"cello"
2326     \set Score.dynamicAbsoluteVolumeFunction = #myDynamics
2327     \new Voice {
2328       \relative c'' {
2329         a4\pp b c-\rfz
2330       }
2331     }
2332   }
2333   \layout {}
2334   \midi {}
2335 }
2336 @end lilypond
2337
2338 Alternatively, if the whole table of fractions needs to be
2339 redefined, it would be better to use the
2340 @notation{default-dynamic-absolute-volume} procedure in
2341 @file{../scm/midi.scm} and the associated table as a model.
2342 The final example in this section shows how this might be done.
2343
2344 @unnumberedsubsubsec Overall MIDI volume
2345
2346 The minimum and maximum overall volume of MIDI dynamic markings is
2347 controlled by setting the properties @code{midiMinimumVolume} and
2348 @code{midiMaximumVolume} at the @code{Score} level.  These
2349 properties have an effect only on dynamic marks, so if they
2350 are to apply from the start of the score a dynamic mark must be
2351 placed there.  The fraction corresponding to each dynamic mark is
2352 modified with this formula
2353
2354 @example
2355 midiMinimumVolume + (midiMaximumVolume - midiMinimumVolume) * fraction
2356 @end example
2357
2358 In the following example the dynamic range of the overall MIDI
2359 volume is limited to the range 0.2 - 0.5.
2360
2361 @lilypond[verbatim,quote]
2362 \score {
2363   <<
2364     \new Staff {
2365       \key g \major
2366       \time 2/2
2367       \set Staff.midiInstrument = #"flute"
2368       \new Voice \relative c''' {
2369         r2 g\mp g fis~
2370         fis4 g8 fis e2~
2371         e4 d8 cis d2
2372       }
2373     }
2374     \new Staff {
2375       \key g \major
2376       \set Staff.midiInstrument = #"clarinet"
2377       \new Voice \relative c'' {
2378         b1\p a2. b8 a
2379         g2. fis8 e
2380         fis2 r
2381       }
2382     }
2383   >>
2384   \layout {}
2385   \midi {
2386     \context {
2387       \Score
2388       tempoWholesPerMinute = #(ly:make-moment 72 2)
2389       midiMinimumVolume = #0.2
2390       midiMaximumVolume = #0.5
2391     }
2392   }
2393 }
2394 @end lilypond
2395
2396 @unnumberedsubsubsec Equalizing different instruments (i)
2397
2398 If the minimum and maximum MIDI volume properties are set in
2399 the @code{Staff} context the relative volumes of the MIDI
2400 instruments can be controlled.  This gives a basic instrument
2401 equalizer, which can enhance the quality of the MIDI output
2402 remarkably.
2403
2404 In this example the volume of the clarinet is reduced relative
2405 to the volume of the flute.  There must be a dynamic
2406 mark on the first note of each instrument for this to work
2407 correctly.
2408
2409 @lilypond[verbatim,quote]
2410 \score {
2411   <<
2412     \new Staff {
2413       \key g \major
2414       \time 2/2
2415       \set Staff.midiInstrument = #"flute"
2416       \set Staff.midiMinimumVolume = #0.7
2417       \set Staff.midiMaximumVolume = #0.9
2418       \new Voice \relative c''' {
2419         r2 g\mp g fis~
2420         fis4 g8 fis e2~
2421         e4 d8 cis d2
2422       }
2423     }
2424     \new Staff {
2425       \key g \major
2426       \set Staff.midiInstrument = #"clarinet"
2427       \set Staff.midiMinimumVolume = #0.3
2428       \set Staff.midiMaximumVolume = #0.6
2429       \new Voice \relative c'' {
2430         b1\p a2. b8 a
2431         g2. fis8 e
2432         fis2 r
2433       }
2434     }
2435   >>
2436   \layout {}
2437   \midi {
2438     \context {
2439       \Score
2440       tempoWholesPerMinute = #(ly:make-moment 72 2)
2441     }
2442   }
2443 }
2444 @end lilypond
2445
2446 @unnumberedsubsubsec Equalizing different instruments (ii)
2447
2448 If the MIDI minimum and maximum volume properties are not set
2449 LilyPond will, by default, apply a small degree of equalization
2450 to a few instruments.  The instruments and the equalization
2451 applied are shown in the table @notation{instrument-equalizer-alist}
2452 in @file{../scm/midi.scm}.
2453
2454 This basic default equalizer can be replaced by setting
2455 @code{instrumentEqualizer} in the @code{Score} context to a new
2456 Scheme procedure which accepts a MIDI instrument name as its only
2457 argument and returns a pair of fractions giving the minimum and
2458 maximum volumes to be applied to that instrument.  This replacement
2459 is done in the same way as shown for resetting the
2460 @code{dynamicAbsoluteVolumeFunction} at the start of this section.
2461 The default equalizer, @notation{default-instrument-equalizer}, in
2462 @file{../scm/midi.scm} shows how such a procedure might be written.
2463
2464 The following example sets the relative flute and clarinet volumes
2465 to the same values as the previous example.
2466
2467 @lilypond[verbatim,quote]
2468 #(define my-instrument-equalizer-alist '())
2469
2470 #(set! my-instrument-equalizer-alist
2471   (append
2472     '(
2473       ("flute" . (0.7 . 0.9))
2474       ("clarinet" . (0.3 . 0.6)))
2475     my-instrument-equalizer-alist))
2476
2477 #(define (my-instrument-equalizer s)
2478   (let ((entry (assoc s my-instrument-equalizer-alist)))
2479     (if entry
2480       (cdr entry))))
2481
2482 \score {
2483   <<
2484     \new Staff {
2485       \key g \major
2486       \time 2/2
2487       \set Score.instrumentEqualizer = #my-instrument-equalizer
2488       \set Staff.midiInstrument = #"flute"
2489       \new Voice \relative c''' {
2490         r2 g\mp g fis~
2491         fis4 g8 fis e2~
2492         e4 d8 cis d2
2493       }
2494     }
2495     \new Staff {
2496       \key g \major
2497       \set Staff.midiInstrument = #"clarinet"
2498       \new Voice \relative c'' {
2499         b1\p a2. b8 a
2500         g2. fis8 e
2501         fis2 r
2502       }
2503     }
2504   >>
2505   \layout { }
2506   \midi {
2507     \context {
2508       \Score
2509       tempoWholesPerMinute = #(ly:make-moment 72 2)
2510     }
2511   }
2512 }
2513 @end lilypond
2514
2515 @ignore
2516 @c Delete when satisfied this is adequately covered elsewhere -td
2517
2518 @n ode Microtones in MIDI
2519 @s ubsection Microtones in MIDI
2520
2521 @cindex microtones in MIDI
2522
2523 Microtones consisting of half sharps and half flats are exported
2524 to the MIDI file and render correctly in MIDI players which support
2525 pitch bending.  See @ref{Note names in other languages}.  Here is
2526 an example showing all the half sharps and half flats.  It can be
2527 copied out and compiled to test microtones in your MIDI player.
2528
2529 @lilypond[verbatim,quote]
2530 \score {
2531   \relative c' {
2532     c4 cih cis cisih
2533     d4 dih ees eeh
2534     e4 eih f fih
2535     fis4 fisih g gih
2536     gis4 gisih a aih
2537     bes4 beh b bih
2538   }
2539   \layout {}
2540   \midi {}
2541 }
2542 @end lilypond
2543 @end ignore
2544
2545
2546 @node Percussion in MIDI
2547 @subsection Percussion in MIDI
2548
2549 Percussion instruments are generally notated in a @code{DrumStaff}
2550 context and when notated in this way they are outputted correctly
2551 to MIDI channel@tie{}10, but some pitched percussion instruments,
2552 like the xylophone, marimba, vibraphone, timpani, etc., are
2553 treated like @qq{normal} instruments and music for these instruments
2554 should be entered in a normal @code{Staff} context, not a
2555 @code{DrumStaff} context, to obtain the correct MIDI output.
2556
2557 Some non-pitched percussion sounds included in the general MIDI
2558 standard, like melodic tom, taiko drum, synth drum, etc., cannot
2559 be reached via MIDI channel@tie{}10, so the notation for such
2560 instruments should also be entered in a normal @code{Staff}
2561 context, using suitable normal pitches.
2562
2563 Many percussion instruments are not included in the general MIDI
2564 standard, e.g. castanets.  The easiest, although unsatisfactory,
2565 method of producing some MIDI output when writing for such
2566 instruments is to substitute the nearest sound from the standard
2567 set.
2568
2569 @c TODO Expand with examples, and any other issues
2570
2571 @knownissues
2572
2573 Because the general MIDI standard does not contain rim shots, the
2574 sidestick is used for this purpose instead.
2575
2576 @node The Articulate script
2577 @subsection The Articulate script
2578
2579 A more realistic MIDI output is possible when using the Articulate
2580 script.  It tries to take articulations (slurs, staccato, etc) into
2581 account, by replacing notes with sequential music of suitably
2582 time-scaled note plus skip.  It also tries to unfold trills turns
2583 etc., and take rallentando and accelerando into account.
2584
2585 To use the Articulate script, you have to include it at the top of
2586 your input file,
2587
2588 @example
2589 \include "articulate.ly"
2590 @end example
2591
2592 and in the @code{\score} section do
2593
2594 @example
2595 \unfoldRepeats \articulate <<
2596         all the rest of the score...
2597 >>
2598 @end example
2599
2600 After altering your input file this way, the visual output is heavily
2601 altered, but the standard @code{\midi} block will produce a better
2602 MIDI file.
2603
2604 Although not essential for the Articulate script to work, you may want
2605 to insert the @code{\unfoldRepeats} command as it appears in the
2606 example shown above as it enables performing abbreviatures such as
2607 @notation{trills}.
2608
2609 @knownissues
2610
2611 Articulate shortens chords and some music (esp. organ music) could
2612 sound worse.
2613
2614
2615 @node Extracting musical information
2616 @section Extracting musical information
2617
2618 In addition to creating graphical output and MIDI, LilyPond can
2619 display musical information as text.
2620
2621 @menu
2622 * Displaying LilyPond notation::
2623 * Displaying scheme music expressions::
2624 * Saving music events to a file::
2625 @end menu
2626
2627 @node Displaying LilyPond notation
2628 @subsection Displaying LilyPond notation
2629
2630 @funindex \displayLilyMusic
2631 Displaying a music expression in LilyPond notation can be
2632 done with the music function @code{\displayLilyMusic} but only when
2633 using the command line.  For example,
2634
2635 @example
2636 @{
2637   \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
2638 @}
2639 @end example
2640
2641 will display
2642
2643 @example
2644 @{ a,4 cis e fis g @}
2645 @end example
2646
2647 By default, LilyPond will print these messages to the console
2648 along with all the other LilyPond compilation messages.  To split
2649 up these messages and save the results of @code{\display@{STUFF@}},
2650 redirect the output to a file.
2651
2652 @example
2653 lilypond file.ly >display.txt
2654 @end example
2655
2656
2657 @node Displaying scheme music expressions
2658 @subsection Displaying scheme music expressions
2659
2660 See @rextend{Displaying music expressions}.
2661
2662
2663 @node Saving music events to a file
2664 @subsection Saving music events to a file
2665
2666 Music events can be saved to a file on a per-staff basis by
2667 including a file in your main score.
2668
2669 @example
2670 \include "event-listener.ly"
2671 @end example
2672
2673 This will create file(s) called @file{FILENAME-STAFFNAME.notes} or
2674 @file{FILENAME-unnamed-staff.notes} for each staff.  Note that if
2675 you have multiple unnamed staves, the events for all staves will
2676 be mixed together in the same file.  The output looks like this:
2677
2678 @example
2679 0.000   note     57       4   p-c 2 12
2680 0.000   dynamic  f
2681 0.250   note     62       4   p-c 7 12
2682 0.500   note     66       8   p-c 9 12
2683 0.625   note     69       8   p-c 14 12
2684 0.750   rest     4
2685 0.750   breathe
2686 @end example
2687
2688 The syntax is a tab-delimited line, with two fixed fields on each
2689 line followed by optional parameters.
2690
2691 @example
2692 @var{time}  @var{type}  @var{...params...}
2693 @end example
2694
2695 This information can easily be read into other programs such as
2696 python scripts, and can be very useful for researchers wishing to
2697 perform musical analysis or playback experiments with LilyPond.
2698
2699
2700 @knownissues
2701
2702 Not all lilypond music events are supported by
2703 @file{event-listener.ly}.  It is intended to be a well-crafted
2704 @qq{proof of concept}.  If some events that you want to see are
2705 not included, copy @file{event-listener.ly} into your lilypond
2706 directory and modify the file so that it outputs the information
2707 you want.