]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/user/non-music.itely
eded3eca1b78a8c60cde0204aaceeb25594a9816
[lilypond.git] / Documentation / user / non-music.itely
1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond.tely
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.  See TRANSLATION for details.
8 @end ignore
9
10 @c A menu is needed before every deeper *section nesting of @node's; run
11 @c     M-x texinfo-all-menus-update
12 @c to automatically fill in these menus before saving changes
13
14 @node Non-musical notation
15 @chapter Non-musical notation
16
17 This section deals with general lilypond issues, rather than
18 specific notation.
19
20 @menu
21 * Input files::                 
22 * Titles and headers::          
23 * MIDI output::                 
24 * Displaying LilyPond notation::  
25 * Skipping corrected music::    
26 @end menu
27
28
29 @node Input files
30 @section Input files
31
32 The main format of input for LilyPond are text files.  By convention,
33 these files end with @samp{.ly}.
34
35 @menu
36 * File structure (introduction)::  
37 * File structure::              
38 * A single music expression::   
39 * Multiple scores in a book::   
40 * Extracting fragments of notation::  
41 * Including LilyPond files::    
42 * Text encoding::               
43 @end menu
44
45
46 @node File structure (introduction)
47 @subsection File structure (introduction)
48
49 A basic example of a lilypond input file is
50
51 @example
52 \version "2.11.15"
53 \score @{
54   @{ @}     % this is a single music expression;
55             % all the music goes in here.
56   \header @{ @}
57   \layout @{ @}
58   \midi @{ @}
59 @}
60 @end example
61
62 @noindent
63 There are many variations of this basic pattern, but this
64 example serves as a useful starting place.
65
66 The major part of this manual is concerned with entering various
67 forms of music in LilyPond.  However, many music expressions are not
68 valid input on their own, for example, a @code{.ly} file containing
69 only a note
70 @example
71 c'4
72 @end example
73
74 @noindent
75 will result in a parsing error.  Instead, music should be inside other
76 expressions, which may be put in a file by themselves.  Such
77 expressions are called toplevel expressions; see @ref{File structure}, for
78 a list of all such expressions.
79
80
81 @node File structure
82 @subsection File structure
83
84 A @code{.ly} file contains any number of toplevel expressions, where a
85 toplevel expression is one of the following
86
87 @itemize @bullet
88 @item
89 An output definition, such as @code{\paper}, @code{\midi}, and
90 @code{\layout}.  Such a definition at the toplevel changes the default
91 settings for the block entered.
92
93 @item
94 A direct scheme expression, such as
95 @code{#(set-default-paper-size "a7" 'landscape)} or
96 @code{#(ly:set-option 'point-and-click #f)}.
97
98 @item
99 A @code{\header} block.  This sets the global header block.  This
100 is the block containing the definitions for book-wide settings, like
101 composer, title, etc.
102
103 @item
104 A @code{\score} block.  This score will be collected with other
105 toplevel scores, and combined as a single @code{\book}.
106
107 This behavior can be changed by setting the variable
108 @code{toplevel-score-handler} at toplevel.  The default handler is
109 defined in the init file @file{scm/@/lily@/.scm}.
110
111 The @code{\score} must begin with a music expression, and may
112 contain only one music expression.
113
114 @item
115 A @code{\book} block logically combines multiple movements
116 (i.e., multiple @code{\score} blocks) in one document.  If there are
117 a number of @code{\scores}, one output file will be created for
118 each @code{\book} block, in which all corresponding movements are
119 concatenated. The only reason to explicitly specify @code{\book} blocks
120 in a @code{.ly} file is if you wish multiple output files from a single
121 input file. One exception is within lilypond-book documents, where you
122 explicitly have to add a @code{\book} block if you want more than a
123 single @code{\score} or @code{\markup} in the same example.
124
125 This behavior can be changed by setting the variable
126 @code{toplevel-book-handler} at toplevel.  The default handler is
127 defined in the init file @file{scm/@/lily@/.scm}.
128
129 @item
130 A compound music expression, such as
131 @example
132 @{ c'4 d' e'2 @}
133 @end example
134
135 This will add the piece in a @code{\score} and format it in a
136 single book together with all other toplevel @code{\score}s and music
137 expressions.  In other words, a file containing only the above
138 music expression will be translated into
139
140 @example
141 \book @{
142   \score @{
143     \new Staff @{
144       \new Voice @{
145         @{ c'4 d' e'2 @}
146       @}
147     @}
148   @}
149         \layout @{ @}
150         \header @{ @}
151 @}
152 @end example
153
154 This behavior can be changed by setting the variable
155 @code{toplevel-music-handler} at toplevel.  The default handler is
156 defined in the init file @file{scm/@/lily@/.scm}.
157
158 @item
159 A markup text, a verse for example
160 @example
161 \markup @{
162    2.  The first line verse two.
163 @}
164 @end example
165
166 Markup texts are rendered above, between or below the scores or music
167 expressions, wherever they appear.
168
169 @cindex variables
170 @cindex identifiers
171
172 @item
173 An identifier, such as
174 @example
175 foo = @{ c4 d e d @}
176 @end example
177
178 This can be used later on in the file by entering @code{\foo}.  The
179 name of an identifier should have alphabetic characters only; no
180 numbers, underscores or dashes.
181
182 @end itemize
183
184 The following example shows three things that may be entered at
185 toplevel
186
187 @example
188 \layout @{
189   % movements are non-justified by default
190   ragged-right = ##t
191 @}
192
193 \header @{
194    title = "Do-re-mi"
195 @}
196
197 @{ c'4 d' e2 @}
198 @end example
199
200
201 At any point in a file, any of the following lexical instructions can
202 be entered:
203
204 @itemize @bullet
205 @item @code{\version}
206 @item @code{\include}
207 @item @code{\sourcefilename}
208 @item @code{\sourcefileline}
209
210 @end itemize
211
212
213 @node A single music expression
214 @subsection A single music expression
215
216 A @code{\score} must contain a single music expression.  However,
217 this music expression may be of any size.  Recall that music
218 expressions may be included inside other expressions to form
219 larger expressions.  All of these examples are single music
220 expressions; note the curly braces @{ @} or angle brackets <<
221 >> at the beginning and ending of the music.
222
223 @example
224 @{ c'4 c' c' c' @}
225 @end example
226
227 @lilypond[ragged-right,verbatim,quote]
228 {
229   { c'4 c' c' c'}
230   { d'4 d' d' d'}
231 }
232 @end lilypond
233
234 @lilypond[ragged-right,verbatim,quote]
235 <<
236   \new Staff { c'4 c' c' c' }
237   \new Staff { d'4 d' d' d' }
238 >>
239 @end lilypond
240
241 @example
242 @{
243   \new GrandStaff <<
244     \new StaffGroup <<
245       \new Staff @{ \flute @}
246       \new Staff @{ \oboe @}
247     >>
248     \new StaffGroup <<
249       \new Staff @{ \violinI @}
250       \new Staff @{ \violinII @}
251     >>
252   >>
253 @}
254 @end example
255
256
257 @node Multiple scores in a book
258 @subsection Multiple scores in a book
259
260 @funindex \book
261 @cindex movements, multiple
262
263 A document may contain multiple pieces of music and texts.  Examples
264 of these are an etude book, or an orchestral part with multiple
265 movements.  Each movement is entered with a @code{\score} block,
266
267 @example
268 \score @{
269   @var{..music..}
270 @}
271 @end example
272
273 and texts are entered with a @code{\markup} block,
274
275 @example
276 \markup @{
277   @var{..text..}
278 @}
279 @end example
280
281 @funindex \book
282
283 All the movements and texts which appear in the same @code{.ly} file 
284 will normally be typeset in the form of a single output file. 
285
286 @example
287 \score @{
288   @var{..}
289 @}
290 \markup @{
291   @var{..}
292 @}
293 \score @{
294   @var{..}
295 @}
296 @end example
297
298 However, if you want multiple output files from the same @code{.ly}
299 file, then you can add multiple @code{\book} blocks, where each such
300 @code{\book} block will result in a separate output. If you do not
301 specify any @code{\book} block in the file, LilyPond will implicitly
302 treat the full file as a single @code{\book} block, see @ref{File
303 structure}. One important exception is within lilypond-book documents,
304 where you explicitly have to add a @code{\book} block, otherwise only
305 the first @code{\score} or @code{\markup} will appear in the output.
306
307 The header for each piece of music can be put inside the @code{\score}
308 block.  The @code{piece} name from the header will be printed before
309 each movement.  The title for the entire book can be put inside the
310 @code{\book}, but if it is not present, the @code{\header} which is at
311 the top of the file is inserted.
312
313 @example
314 \header @{
315   title = "Eight miniatures"
316   composer = "Igor Stravinsky"
317 @}
318 \score @{
319   @dots{}
320   \header @{ piece = "Romanze" @}
321 @}
322 \markup @{
323    ..text of second verse..
324 @}
325 \markup @{
326    ..text of third verse..
327 @}
328 \score @{
329   @dots{}
330   \header @{ piece = "Menuetto" @}
331 @}
332 @end example
333
334 @node Extracting fragments of notation
335 @subsection Extracting fragments of notation
336
337 It is possible to quote small fragments of a large score directly from
338 the output. This can be compared to clipping a piece of a paper score
339 with scissors.
340
341 This is done by definining the measures that need to be cut out
342 separately. For example, including the following definition
343
344
345 @verbatim
346 \layout {
347   clip-regions
348   = #(list
349       (cons
350        (make-rhythmic-location 5 1 2)
351        (make-rhythmic-location 7 3 4)))
352 }       
353 @end verbatim
354
355 @noindent
356 will extract a fragment starting halfway the fifth measure, ending in
357 the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note
358 in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7.
359
360 More clip regions can be defined by adding more pairs of
361 rhythmic-locations to the list. 
362
363 In order to use this feature, LilyPond must be invoked with
364 @code{-dclip-systems}. The clips are output as EPS files, and are
365 converted to PDF and PNG if these formats are switched on as well.
366
367 For more information on output formats, see @ref{Invoking lilypond}.
368
369 @seealso
370
371 Examples: @inputfileref{input/regression/,clip-systems.ly}
372
373
374 @node Including LilyPond files
375 @subsection Including LilyPond files
376
377 @funindex \include
378 @cindex including files
379
380 A large project may be split up into separate files.  To refer to another
381 file, use
382
383 @example
384 \include "otherfile.ly"
385 @end example
386
387 The line @code{\include "file.ly"} is equivalent to pasting the contents
388 of file.ly into the current file at the place where you have the
389 \include.  For example, for a large project you might write separate files
390 for each instrument part and create a @q{full score} file which brings
391 together the individual instrument files.
392
393 The initialization of LilyPond is done in a number of files that are
394 included by default when you start the program, normally transparent to the
395 user.  Run lilypond --verbose to see a list of paths and files that Lily
396 finds.
397
398 Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where
399 VERSION is in the form @q{2.6.1}) are on the path and available to
400 @code{\include}.  Files in the
401 current working directory are available to \include, but a file of the same
402 name in LilyPond's installation takes precedence.  Files are
403 available to \include from directories in the search path specified as an
404 option when invoking @code{lilypond --include=DIR} which adds DIR to the
405 search path.
406
407 The @code{\include} statement can use full path information, but with the Unix
408 convention @samp{/} rather than the DOS/Windows @samp{\}.  For example,
409 if @file{stuff.ly} is located one directory higher than the current working
410 directory, use
411
412 @example
413 \include "../stuff.ly"
414 @end example
415
416
417 @node Text encoding
418 @subsection Text encoding
419
420 LilyPond uses the Pango library to format multi-lingual texts, and
421 does not perform any input-encoding conversions.  This means that any
422 text, be it title, lyric text, or musical instruction containing
423 non-ASCII characters, must be utf-8.  The easiest way to enter such text is
424 by using a Unicode-aware editor and saving the file with utf-8 encoding.  Most
425 popular modern editors have utf-8 support, for example, vim, Emacs,
426 jEdit, and GEdit do.
427
428 @c  Currently not working
429 @ignore
430 Depending on the fonts installed, the following fragment shows Hebrew
431 and Cyrillic lyrics,
432
433 @cindex Cyrillic
434 @cindex Hebrew
435 @cindex ASCII, non
436
437 @li lypondfile[fontload]{utf-8.ly}
438
439 The @TeX{} backend does not handle encoding specially at all.  Strings
440 in the input are put in the output as-is.  Extents of text items in the
441 @TeX{} backend, are determined by reading a file created via the
442 @file{texstr} backend,
443
444 @example
445 lilypond -b texstr input/les-nereides.ly
446 latex les-nereides.texstr
447 @end example
448
449 The last command produces @file{les-nereides.textmetrics}, which is
450 read when you execute
451
452 @example
453 lilypond -b tex input/les-nereides.ly
454 @end example
455
456 Both @file{les-nereides.texstr} and @file{les-nereides.tex} need
457 suitable LaTeX wrappers to load appropriate La@TeX{} packages for
458 interpreting non-ASCII strings.
459
460 @end ignore
461
462 To use a Unicode escape sequence, use
463
464 @example
465 #(ly:export (ly:wide-char->utf-8 #x2014))
466 @end example
467
468
469 @seealso
470
471 @lsr{text,utf-8.ly}
472
473
474
475 @node Titles and headers
476 @section Titles and headers
477
478 Almost all printed music includes a title and the composer's name;
479 some pieces include a lot more information.
480
481 @menu
482 * Creating titles::             
483 * Custom titles::               
484 * Table of contents::                
485 @end menu
486
487
488 @node Creating titles
489 @subsection Creating titles
490
491 Titles are created for each @code{\score} block, as well as for the full
492 input file (or @code{\book} block).
493
494 The contents of the titles are taken from the @code{\header} blocks.
495 The header block for a book supports the following
496
497
498 @table @code
499 @funindex dedication
500 @item dedication
501 The dedicatee of the music, centered at the top of the first page.
502
503 @funindex title
504 @item title
505 The title of the music, centered just below the dedication.
506
507 @funindex subtitle
508 @item subtitle
509 Subtitle, centered below the title.
510
511 @funindex subsubtitle
512 @item subsubtitle
513 Subsubtitle, centered below the subtitle.
514
515 @funindex poet
516 @item poet
517 Name of the poet, flush-left below the subtitle.
518
519 @funindex composer
520 @item composer
521 Name of the composer, flush-right below the subtitle.
522
523 @funindex meter
524 @item meter
525 Meter string, flush-left below the poet.
526
527 @funindex opus
528 @item opus
529 Name of the opus, flush-right below the composer.
530
531 @funindex arranger
532 @item arranger
533 Name of the arranger, flush-right below the opus.
534
535 @funindex instrument
536 @item instrument
537 Name of the instrument, centered below the arranger.  Also
538 centered at the top of pages (other than the first page).
539
540 @funindex piece
541 @item piece
542 Name of the piece, flush-left below the instrument.
543
544 @cindex page breaks, forcing
545 @funindex breakbefore
546 @item breakbefore
547 This forces the title to start on a new page (set to ##t or ##f).
548
549 @funindex copyright
550 @item copyright
551 Copyright notice, centered at the bottom of the first page.  To
552 insert the copyright symbol, see @ref{Text encoding}.
553
554 @funindex tagline
555 @item tagline
556 Centered at the bottom of the last page.
557
558 @end table
559
560 Here is a demonstration of the fields available.  Note that you
561 may use any @ref{Text markup}, commands in the header.
562
563 @lilypond[quote,verbatim,line-width=11.0\cm]
564 \paper {
565   line-width = 9.0\cm
566   paper-height = 10.0\cm
567 }
568
569 \book {
570   \header {
571     dedication = "dedicated to me"
572     title = \markup \center-align { "Title first line" "Title second line,
573 longer" }
574     subtitle = "the subtitle,"
575     subsubtitle = #(string-append "subsubtitle LilyPond version "
576 (lilypond-version))
577     poet = "Poet"
578     composer =  \markup \center-align { "composer" \small "(1847-1973)" }
579     texttranslator = "Text Translator"
580     meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
581 "r" }
582     arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize
583 #-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }
584     instrument = \markup \bold \italic "instrument"
585     piece = "Piece"
586   }
587
588   \score {
589     { c'1 }
590     \header {
591       piece = "piece1"
592       opus = "opus1"
593     }
594   }
595   \markup {
596       and now...
597   }
598   \score {
599     { c'1 }
600     \header {
601       piece = "piece2"
602       opus = "opus2"
603     }
604   }
605 }
606 @end lilypond
607
608 As demonstrated before, you can use multiple @code{\header} blocks.
609 When same fields appear in different blocks, the latter is used.
610 Here is a short example.
611
612 @example
613 \header @{
614   composer = "Composer"
615 @}
616 \header @{
617   piece = "Piece"
618 @}
619 \score @{
620   \new Staff @{ c'4 @}
621   \header @{
622     piece = "New piece"  % overwrite previous one
623   @}
624 @}
625 @end example
626
627 If you define the @code{\header} inside the @code{\score} block, then
628 normally only the @code{piece} and @code{opus} headers will be printed.
629 Note that the music expression must come before the @code{\header}.
630
631 @lilypond[quote,verbatim,line-width=11.0\cm]
632 \score {
633   { c'4 }
634   \header {
635     title = "title"  % not printed
636     piece = "piece"
637     opus = "opus"
638   }
639 }
640 @end lilypond
641
642 @funindex printallheaders
643 @noindent
644 You may change this behavior (and print all the headers when defining
645 @code{\header} inside @code{\score}) by using
646
647 @example
648 \paper@{
649   printallheaders=##t
650 @}
651 @end example
652
653 @cindex copyright
654 @cindex tagline
655
656 The default footer is empty, except for the first page, where the
657 @code{copyright} field from @code{\header} is inserted, and the last
658 page, where @code{tagline} from @code{\header} is added.  The default
659 tagline is @qq{Music engraving by LilyPond (@var{version})}.@footnote{Nicely
660 printed parts are good PR for us, so please leave the tagline if you
661 can.}
662
663 Headers may be completely removed by setting them to false.
664
665 @example
666 \header @{
667   tagline = ##f
668   composer = ##f
669 @}
670 @end example
671
672
673 @node Custom titles
674 @subsection Custom titles
675
676 A more advanced option is to change the definitions of the following
677 variables in the @code{\paper} block.  The init file
678 @file{ly/titling-init.ly} lists the default layout.
679
680 @table @code
681 @funindex bookTitleMarkup
682 @item bookTitleMarkup
683   This is the title added at the top of the entire output document.
684 Typically, it has the composer and the title of the piece
685
686 @funindex scoreTitleMarkup
687 @item scoreTitleMarkup
688   This is the title put over a @code{\score} block.  Typically, it has
689 the name of the movement (@code{piece} field).
690
691 @funindex oddHeaderMarkup
692 @item oddHeaderMarkup
693   This is the page header for odd-numbered pages.
694
695 @funindex evenHeaderMarkup
696 @item evenHeaderMarkup
697   This is the page header for even-numbered pages.  If unspecified,
698   the odd header is used instead.
699
700   By default, headers are defined such that the page number is on the
701   outside edge, and the instrument is centered.
702
703 @funindex oddFooterMarkup
704 @item oddFooterMarkup
705   This is the page footer for odd-numbered pages.
706
707 @funindex evenFooterMarkup
708 @item evenFooterMarkup
709   This is the page footer for even-numbered pages.  If unspecified,
710   the odd header is used instead.
711
712   By default, the footer has the copyright notice on the first, and
713   the tagline on the last page.
714 @end table
715
716
717 @cindex \paper
718 @cindex header
719 @cindex footer
720 @cindex page layout
721 @cindex titles
722
723 The following definition will put the title flush left, and the
724 composer flush right on a single line.
725
726 @verbatim
727 \paper {
728   bookTitleMarkup = \markup {
729    \fill-line {
730      \fromproperty #'header:title
731      \fromproperty #'header:composer
732    }
733   }
734 }
735 @end verbatim
736
737 @node Table of contents
738 @subsection Table of contents
739
740 A particular place of a score can be marked using the @code{\label}
741 command, either at top-level or inside music.  This label can then be
742 refered to in a markup, to get the number of the page where the marked
743 point is placed, using the @code{\page-ref} markup command.
744
745 @verbatim
746 \score {
747   {
748     c'1
749     \mark A \label #'markA
750     c'
751   }
752 } \label #'firstScore
753
754 \markup { The first score is on page \page-ref #'firstScore "0" "?" }
755 \markup { Mark A is on page \page-ref #'markA "0" "?" }
756 @end verbatim
757
758 The @code{\page-ref} markup command takes three arguments:
759 @enumerate
760 @item the label, a scheme symbol, eg. #'firstScore
761 @item a markup that will be used as a gauge to estimate the dimensions
762 of the markup
763 @item a markup that will be used if the label is not known
764 @end enumerate
765
766 The reason why a gauge is needed is that, at the time markups are
767 interpreted, the page breaking has not yet occured, so the page numbers
768 are not yet known.  To work around this issue, the actual markup
769 interpretation is delayed to a later time; however, the dimensions of
770 the markup have to be known before, so a gauge is used to decide these
771 dimensions.  If the book has between 10 and 99 pages, it may be "00",
772 ie. a two digit number.
773
774 @code{\label} and @code{\page-ref} can be used to build a table of contents:
775
776 @verbatim
777 #(set-default-paper-size "a6")
778
779 #(define-markup-command (toc-line layout props label text) (symbol? markup?)
780   (interpret-markup layout props
781    (markup #:fill-line (text #:page-ref label "8" "?"))))
782
783 \markup \column {
784   \large \fill-line { \null "Table of contents" \null }
785   \hspace #1
786   \toc-line #'toc "Table of contents"
787   \toc-line #'scoreI "First Score"
788   \toc-line #'markA \line { \hspace #3 Mark A }
789   \toc-line #'scoreII "Second Score"
790 } \label #'toc
791
792 \pageBreak
793
794 \score {
795   { 
796     c'1 \break
797     \mark A \label #'markA
798     c'1
799   }
800   \header { piece = "First score" }
801 } \label #'scoreI
802
803 \pageBreak
804
805 \score {
806   { d' }
807   \header { piece = "Second score" }
808 } \label #'scoreII
809 @end verbatim
810
811 In this example, a @code{\toc-line} markup command is defined to build
812 the table of content items. As this example has less than 10 pages, the
813 gauge used by @code{\page-ref} has a single digit.
814
815 @refcommands
816
817 @funindex \label
818 @code{\label}
819 @funindex \page-ref
820 @code{\page-ref}
821
822 @node MIDI output
823 @section MIDI output
824
825 @cindex Sound
826 @cindex MIDI
827
828 MIDI (Musical Instrument Digital Interface) is a standard for
829 connecting and controlling digital instruments.  A MIDI file is a
830 series of notes in a number of tracks.  It is not an actual
831 sound file; you need special software to translate between the
832 series of notes and actual sounds.
833
834 Pieces of music can be converted to MIDI files, so you can listen to
835 what was entered.  This is convenient for checking the music; octaves
836 that are off or accidentals that were mistyped stand out very much
837 when listening to the MIDI output.
838
839 @refbugs
840
841 Many musically interesting effects, such as swing, articulation,
842 slurring, etc., are not translated to midi.
843
844 The midi output allocates a channel for each staff, and one for global
845 settings.  Therefore the midi file should not have more than 15 staves
846 (or 14 if you do not use drums).  Other staves will remain silent.
847
848 Not all midi players correctly handle tempo changes in the midi
849 output.  Players that are known to work include
850 @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
851
852 @menu
853 * Creating MIDI files::         
854 * MIDI block::                  
855 * MIDI instrument names::       
856 @end menu
857
858 @node Creating MIDI files
859 @subsection Creating MIDI files
860
861 To create a MIDI from a music piece of music, add a @code{\midi} block
862 to a score, for example,
863
864 @example
865 \score @{
866   @var{...music...}
867    \midi @{
868      \context @{
869        \Score
870        tempoWholesPerMinute = #(ly:make-moment 72 4)
871        @}
872      @}
873 @}
874 @end example
875
876 The tempo can be specified using the @code{\tempo} command within the 
877 actual music, see @ref{Metronome marks}.  An alternative, which does not
878 result in a metronome mark in the printed score, is shown in the example
879 above. In this example the tempo of quarter notes is set to 72 beats per
880 minute. 
881 This kind of tempo
882 specification can not take dotted note lengths as an argument. In this
883 case, break the dotted notes into smaller units. For example, a tempo
884 of 90 dotted quarter notes per minute can be specified as 270 eighth
885 notes per minute
886
887 @example
888 tempoWholesPerMinute = #(ly:make-moment 270 8)
889 @end example
890
891 If there is a @code{\midi} command in a @code{\score}, only MIDI will
892 be produced.  When notation is needed too, a @code{\layout} block must
893 be added
894
895 @example
896 \score @{
897   @var{...music...}
898   \midi @{ @}
899   \layout @{ @}
900 @}
901 @end example
902 @cindex layout block
903
904
905
906 Ties, dynamics, and tempo changes are interpreted.  Dynamic marks,
907 crescendi and decrescendi translate into MIDI volume levels.  Dynamic
908 marks translate to a fixed fraction of the available MIDI volume
909 range, crescendi and decrescendi make the volume vary linearly between
910 their two extremes.  The fractions can be adjusted by
911 @code{dynamicAbsoluteVolumeFunction} in @internalsref{Voice} context.
912 For each type of MIDI instrument, a volume range can be defined.  This
913 gives a basic equalizer control, which can enhance the quality of
914 the MIDI output remarkably.  The equalizer can be controlled by
915 setting @code{instrumentEqualizer}, or by setting
916
917 @example
918 \set Staff.midiMinimumVolume = #0.2
919 \set Staff.midiMaximumVolume = #0.8
920 @end example
921
922 To remove dynamics from the MIDI output, insert the following lines
923 in the @code{\midi@{@}} section.
924
925 @example
926 \midi @{
927   ...
928   \context @{
929     \Voice
930     \remove "Dynamic_performer"
931   @}
932 @}
933 @end example
934
935
936 @refbugs
937
938 Unterminated (de)crescendos will not render properly in the midi file,
939 resulting in silent passages of music.  The workaround is to explicitly
940 terminate the (de)crescendo.  For example,
941
942 @example
943 @{ a\< b c d\f @}
944 @end example
945
946 @noindent
947 will not work properly but
948
949 @example
950 @{ a\< b c d\!\f @}
951 @end example
952
953 @noindent
954 will.
955
956
957 MIDI output is only created when the @code{\midi} command is within
958 a @code{\score} block.  If you put it within an explicitly instantiated
959 context ( i.e. @code{\new Score} ) the file will fail.  To solve this,
960 enclose the @code{\new Score} and the @code{\midi} in a @code{\score} block.
961
962 @example
963 \score @{
964   \new Score @{ @dots{}notes@dots{} @}
965   \midi
966 @}
967 @end example
968
969
970 @node MIDI block
971 @subsection MIDI block
972 @cindex MIDI block
973
974
975 The MIDI block is analogous to the layout block, but it is somewhat
976 simpler.  The @code{\midi} block is similar to @code{\layout}. It can contain
977 context definitions.
978
979
980 @cindex context definition
981
982 Context definitions follow precisely the same syntax as within the
983 \layout block.  Translation modules for sound are called performers.
984 The contexts for MIDI output are defined in @file{ly/@/performer@/-init@/.ly}.
985
986
987 @node MIDI instrument names
988 @subsection MIDI instrument names
989
990 @cindex instrument names
991 @funindex Staff.midiInstrument
992
993 The MIDI instrument name is set by the @code{Staff.midiInstrument}
994 property.  The instrument name should be chosen from the list in
995 @ref{MIDI instruments}.
996
997 @example
998 \set Staff.midiInstrument = "glockenspiel"
999 @var{...notes...}
1000 @end example
1001
1002 If the selected instrument does not exactly match an instrument from
1003 the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
1004 instrument is used.
1005
1006
1007 @c  Yes, this is a cop-out; this info doesn't belong in the Scheme
1008 @c  chapter, but I'm not certain where to stick it.
1009 @c  I think I'll eventually split this chapter into a "paper/layout"
1010 @c  chapter and a "misc issues" chapter.  -gp
1011 @node Displaying LilyPond notation
1012 @section Displaying LilyPond notation
1013
1014 @funindex \displayLilyMusc
1015 Displaying a music expression in LilyPond notation can be
1016 done using the music function @code{\displayLilyMusic}.  For example,
1017
1018 @example
1019 @{
1020   \displayLilyMusic \transpose c a, @{ c e g a bes @}
1021 @}
1022 @end example
1023
1024 will display
1025
1026 @example
1027 @{ a, cis e fis g @}
1028 @end example
1029
1030 By default, LilyPond will print these messages to the console along
1031 with all the other messages.  To split up these messages and save
1032 the results of @code{\display@{STUFF@}}, redirect the output to
1033 a file.
1034
1035 @example
1036 lilypond file.ly >display.txt
1037 @end example
1038
1039
1040 @node Skipping corrected music
1041 @section Skipping corrected music
1042
1043
1044 @funindex skipTypesetting
1045 @funindex showLastLength
1046
1047 When entering or copying music, usually only the music near the end (where
1048 you
1049 are adding notes) is interesting to view and correct.  To speed up
1050 this correction process, it is possible to skip typesetting of all but
1051 the last few measures. This is achieved by putting
1052
1053 @verbatim
1054 showLastLength = R1*5
1055 \score { ... }
1056 @end verbatim
1057
1058 @noindent
1059 in your source file. This will render only the last 5 measures
1060 (assuming 4/4 time signature) of every @code{\score} in the input
1061 file. For longer pieces, rendering only a small part is often an order
1062 of magnitude quicker than rendering it completely
1063
1064 Skipping parts of a score can be controlled in a more fine-grained
1065 fashion with the property @code{Score.skipTypesetting}.  When it is
1066 set, no typesetting is performed at all.
1067
1068 This property is also used to control output to the MIDI file. Note that
1069 it skips all events, including tempo and instrument changes. You have
1070 been warned.
1071
1072 @lilypond[quote,fragment,ragged-right,verbatim]
1073 \relative c'' {
1074   c8 d
1075   \set Score.skipTypesetting = ##t
1076   e e e e e e e e
1077   \set Score.skipTypesetting = ##f
1078   c d b bes a g c2 }
1079 @end lilypond
1080
1081 In polyphonic music, @code{Score.skipTypesetting} will affect all
1082 voices and staves, saving even more time.
1083
1084
1085