1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond.tely
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. See TRANSLATION for details.
12 @c A menu is needed before every deeper *section nesting of @node's; run
13 @c M-x texinfo-all-menus-update
14 @c to automatically fill in these menus before saving changes
16 @node Non-musical notation
17 @chapter Non-musical notation
19 This section deals with general LilyPond issues, rather than
23 * Titles and headers::
29 @node Titles and headers
30 @section Titles and headers
32 Almost all printed music includes a title and the composer's name;
33 some pieces include a lot more information.
38 * Reference to page numbers::
44 @subsection Creating titles
46 Titles are created for each @code{\score} block, as well as for the full
47 input file (or @code{\book} block).
49 The contents of the titles are taken from the @code{\header} blocks.
50 The header block for a book supports the following
56 The dedicatee of the music, centered at the top of the first page.
60 The title of the music, centered just below the dedication.
64 Subtitle, centered below the title.
68 Subsubtitle, centered below the subtitle.
72 Name of the poet, flush-left below the subtitle.
76 Name of the composer, flush-right below the subtitle.
80 Meter string, flush-left below the poet.
84 Name of the opus, flush-right below the composer.
88 Name of the arranger, flush-right below the opus.
92 Name of the instrument, centered below the arranger. Also
93 centered at the top of pages (other than the first page).
97 Name of the piece, flush-left below the instrument.
99 @cindex page breaks, forcing
100 @funindex breakbefore
102 This forces the title to start on a new page (set to ##t or ##f).
106 Copyright notice, centered at the bottom of the first page. To
107 insert the copyright symbol, see @ref{Text encoding}.
111 Centered at the bottom of the last page.
115 Here is a demonstration of the fields available. Note that you
116 may use any @ref{Formatting text}, commands in the header.
118 @lilypond[quote,verbatim,line-width=11.0\cm]
121 paper-height = 10.0\cm
126 dedication = "dedicated to me"
127 title = \markup \center-align { "Title first line" "Title second line,
129 subtitle = "the subtitle,"
130 subsubtitle = #(string-append "subsubtitle LilyPond version "
133 composer = \markup \center-align { "composer" \small "(1847-1973)" }
134 texttranslator = "Text Translator"
135 meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
137 arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize
138 #-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }
139 instrument = \markup \bold \italic "instrument"
163 As demonstrated before, you can use multiple @code{\header} blocks.
164 When same fields appear in different blocks, the latter is used.
165 Here is a short example.
169 composer = "Composer"
177 piece = "New piece" % overwrite previous one
182 If you define the @code{\header} inside the @code{\score} block, then
183 normally only the @code{piece} and @code{opus} headers will be printed.
184 Note that the music expression must come before the @code{\header}.
186 @lilypond[quote,verbatim,line-width=11.0\cm]
190 title = "title" % not printed
197 @funindex printallheaders
199 You may change this behavior (and print all the headers when defining
200 @code{\header} inside @code{\score}) by using
211 The default footer is empty, except for the first page, where the
212 @code{copyright} field from @code{\header} is inserted, and the last
213 page, where @code{tagline} from @code{\header} is added. The default
214 tagline is @qq{Music engraving by LilyPond (@var{version})}.@footnote{Nicely
215 printed parts are good PR for us, so please leave the tagline if you
218 Headers may be completely removed by setting them to false.
229 @subsection Custom titles
231 A more advanced option is to change the definitions of the following
232 variables in the @code{\paper} block. The init file
233 @file{ly/titling-init.ly} lists the default layout.
236 @funindex bookTitleMarkup
237 @item bookTitleMarkup
238 This is the title added at the top of the entire output document.
239 Typically, it has the composer and the title of the piece
241 @funindex scoreTitleMarkup
242 @item scoreTitleMarkup
243 This is the title put over a @code{\score} block. Typically, it has
244 the name of the movement (@code{piece} field).
246 @funindex oddHeaderMarkup
247 @item oddHeaderMarkup
248 This is the page header for odd-numbered pages.
250 @funindex evenHeaderMarkup
251 @item evenHeaderMarkup
252 This is the page header for even-numbered pages. If unspecified,
253 the odd header is used instead.
255 By default, headers are defined such that the page number is on the
256 outside edge, and the instrument is centered.
258 @funindex oddFooterMarkup
259 @item oddFooterMarkup
260 This is the page footer for odd-numbered pages.
262 @funindex evenFooterMarkup
263 @item evenFooterMarkup
264 This is the page footer for even-numbered pages. If unspecified,
265 the odd header is used instead.
267 By default, the footer has the copyright notice on the first, and
268 the tagline on the last page.
278 The following definition will put the title flush left, and the
279 composer flush right on a single line.
283 bookTitleMarkup = \markup {
285 \fromproperty #'header:title
286 \fromproperty #'header:composer
292 @node Reference to page numbers
293 @subsection Reference to page numbers
295 A particular place of a score can be marked using the @code{\label}
296 command, either at top-level or inside music. This label can then be
297 referred to in a markup, to get the number of the page where the marked
298 point is placed, using the @code{\page-ref} markup command.
300 @lilypond[verbatim,line-width=11.0\cm]
301 \header { tagline = ##f }
307 \pageBreak \mark A \label #'markA
312 \markup { The first score begins on page \page-ref #'firstScore "0" "?" }
313 \markup { Mark A is on page \page-ref #'markA "0" "?" }
317 The @code{\page-ref} markup command takes three arguments:
319 @item the label, a scheme symbol, eg. @code{#'firstScore};
320 @item a markup that will be used as a gauge to estimate the dimensions
322 @item a markup that will be used in place of the page number if the label
326 The reason why a gauge is needed is that, at the time markups are
327 interpreted, the page breaking has not yet occurred, so the page numbers
328 are not yet known. To work around this issue, the actual markup
329 interpretation is delayed to a later time; however, the dimensions of
330 the markup have to be known before, so a gauge is used to decide these
331 dimensions. If the book has between 10 and 99 pages, it may be "00",
332 ie. a two digit number.
341 @node Table of contents
342 @subsection Table of contents
343 A table of contents is included using the @code{\markuplines \table-of-contents}
344 command. The elements which should appear in the table of contents are
345 entered with the @code{\tocItem} command, which may be used either at
346 top-level, or inside a music expression.
349 \markuplines \table-of-contents
352 \tocItem \markup "First score"
356 \tocItem \markup "Some particular point in the first score"
361 \tocItem \markup "Second score"
369 The markups which are used to format the table of contents are defined
370 in the @code{\paper} block. The default ones are @code{tocTitleMarkup},
371 for formatting the title of the table, and @code{tocItemMarkup}, for
372 formatting the toc elements, composed of the element title and page
373 number. These variables may be changed by the user:
377 %% Translate the toc title into French:
378 tocTitleMarkup = \markup \huge \column {
379 \fill-line { \null "Table des matières" \null }
382 %% use larger font size
383 tocItemMarkup = \markup \large \fill-line {
384 \fromproperty #'toc:text \fromproperty #'toc:page
389 Note how the toc element text and page number are referred to in
390 the @code{tocItemMarkup} definition.
392 New commands and markups may also be defined to build more elaborated
395 @item first, define a new markup variable in the @code{\paper} block
396 @item then, define a music function which aims at adding a toc element
397 using this markup paper variable.
400 In the following example, a new style is defined for entering act names
401 in the table of contents of an opera:
405 tocActMarkup = \markup \large \column {
407 \fill-line { \null \italic \fromproperty #'toc:text \null }
413 #(define-music-function (parser location text) (markup?)
414 (add-toc-item! 'tocActMarkup text))
417 @lilypond[line-width=11.0\cm]
418 \header { tagline = ##f }
420 tocActMarkup = \markup \large \column {
422 \fill-line { \null \italic \fromproperty #'toc:text \null }
428 #(define-music-function (parser location text) (markup?)
429 (add-toc-item! 'tocActMarkup text))
432 \markuplines \table-of-contents
433 \tocAct \markup { Atto Primo }
434 \tocItem \markup { Coro. Viva il nostro Alcide }
435 \tocItem \markup { Cesare. Presti omai l'Egizzia terra }
436 \tocAct \markup { Atto Secondo }
437 \tocItem \markup { Sinfonia }
438 \tocItem \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
445 Init files: @file{ly/@/toc@/-init@/.ly}.
449 @funindex \table-of-contents
450 @code{\table-of-contents}
460 MIDI (Musical Instrument Digital Interface) is a standard for
461 connecting and controlling digital instruments. A MIDI file is a
462 series of notes in a number of tracks. It is not an actual
463 sound file; you need special software to translate between the
464 series of notes and actual sounds.
466 Pieces of music can be converted to MIDI files, so you can listen to
467 what was entered. This is convenient for checking the music; octaves
468 that are off or accidentals that were mistyped stand out very much
469 when listening to the MIDI output.
473 Many musically interesting effects, such as swing, articulation,
474 slurring, etc., are not translated to midi.
476 The midi output allocates a channel for each staff, and one for global
477 settings. Therefore the midi file should not have more than 15 staves
478 (or 14 if you do not use drums). Other staves will remain silent.
480 Not all midi players correctly handle tempo changes in the midi
481 output. Players that are known to work include
482 @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
485 * Creating MIDI files::
487 * MIDI instrument names::
488 * What goes into the MIDI? FIXME::
491 @node Creating MIDI files
492 @subsection Creating MIDI files
494 To create a MIDI from a music piece of music, add a @code{\midi} block
495 to a score, for example,
503 tempoWholesPerMinute = #(ly:make-moment 72 4)
509 The tempo can be specified using the @code{\tempo} command within the
510 actual music, see @ref{Metronome marks}. An alternative, which does not
511 result in a metronome mark in the printed score, is shown in the example
512 above. In this example the tempo of quarter notes is set to 72 beats per
515 specification can not take dotted note lengths as an argument. In this
516 case, break the dotted notes into smaller units. For example, a tempo
517 of 90 dotted quarter notes per minute can be specified as 270 eighth
521 tempoWholesPerMinute = #(ly:make-moment 270 8)
524 If there is a @code{\midi} command in a @code{\score}, only MIDI will
525 be produced. When notation is needed too, a @code{\layout} block must
539 Ties, dynamics, and tempo changes are interpreted. Dynamic marks,
540 crescendi and decrescendi translate into MIDI volume levels. Dynamic
541 marks translate to a fixed fraction of the available MIDI volume
542 range, crescendi and decrescendi make the volume vary linearly between
543 their two extremes. The fractions can be adjusted by
544 @code{dynamicAbsoluteVolumeFunction} in @rinternals{Voice} context.
545 For each type of MIDI instrument, a volume range can be defined. This
546 gives a basic equalizer control, which can enhance the quality of
547 the MIDI output remarkably. The equalizer can be controlled by
548 setting @code{instrumentEqualizer}, or by setting
551 \set Staff.midiMinimumVolume = #0.2
552 \set Staff.midiMaximumVolume = #0.8
555 To remove dynamics from the MIDI output, insert the following lines
556 in the @code{\midi@{@}} section.
563 \remove "Dynamic_performer"
571 Unterminated (de)crescendos will not render properly in the midi file,
572 resulting in silent passages of music. The workaround is to explicitly
573 terminate the (de)crescendo. For example,
580 will not work properly but
590 MIDI output is only created when the @code{\midi} command is within
591 a @code{\score} block. If you put it within an explicitly instantiated
592 context ( i.e. @code{\new Score} ) the file will fail. To solve this,
593 enclose the @code{\new Score} and the @code{\midi} in a @code{\score} block.
597 \new Score @{ @dots{}notes@dots{} @}
604 @subsection MIDI block
608 The MIDI block is analogous to the layout block, but it is somewhat
609 simpler. The @code{\midi} block is similar to @code{\layout}. It can contain
613 @cindex context definition
615 Context definitions follow precisely the same syntax as within the
616 \layout block. Translation modules for sound are called performers.
617 The contexts for MIDI output are defined in @file{ly/@/performer@/-init@/.ly}.
620 @node MIDI instrument names
621 @subsection MIDI instrument names
623 @cindex instrument names
624 @funindex Staff.midiInstrument
626 The MIDI instrument name is set by the @code{Staff.midiInstrument}
627 property. The instrument name should be chosen from the list in
628 @ref{MIDI instruments}.
631 \set Staff.midiInstrument = "glockenspiel"
635 If the selected instrument does not exactly match an instrument from
636 the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
640 @node What goes into the MIDI? FIXME
641 @subsection What goes into the MIDI? FIXME
647 @node Repeats and MIDI
648 @subsubsection Repeats and MIDI
650 @cindex expanding repeats
651 @funindex \unfoldRepeats
653 With a little bit of tweaking, all types of repeats can be present
654 in the MIDI output. This is achieved by applying the
655 @code{\unfoldRepeats} music function. This function changes all
656 repeats to unfold repeats.
658 @lilypond[quote,verbatim,fragment,line-width=8.0\cm]
660 \repeat tremolo 8 {c'32 e' }
661 \repeat percent 2 { c''8 d'' }
662 \repeat volta 2 {c'4 d' e' f'}
671 When creating a score file using @code{\unfoldRepeats} for MIDI,
672 it is necessary to make two @code{\score} blocks: one for MIDI
673 (with unfolded repeats) and one for notation (with volta, tremolo,
674 and percent repeats). For example,
682 \unfoldRepeats @var{..music..}
691 Micro tones are also exported to the MIDI file.