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.
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
14 @node Non-musical notation
15 @chapter Non-musical notation
17 This section deals with general lilypond issues, rather than
21 * Titles and headers::
26 @node Titles and headers
27 @section Titles and headers
29 Almost all printed music includes a title and the composer's name;
30 some pieces include a lot more information.
35 * Reference to page numbers::
41 @subsection Creating titles
43 Titles are created for each @code{\score} block, as well as for the full
44 input file (or @code{\book} block).
46 The contents of the titles are taken from the @code{\header} blocks.
47 The header block for a book supports the following
53 The dedicatee of the music, centered at the top of the first page.
57 The title of the music, centered just below the dedication.
61 Subtitle, centered below the title.
65 Subsubtitle, centered below the subtitle.
69 Name of the poet, flush-left below the subtitle.
73 Name of the composer, flush-right below the subtitle.
77 Meter string, flush-left below the poet.
81 Name of the opus, flush-right below the composer.
85 Name of the arranger, flush-right below the opus.
89 Name of the instrument, centered below the arranger. Also
90 centered at the top of pages (other than the first page).
94 Name of the piece, flush-left below the instrument.
96 @cindex page breaks, forcing
99 This forces the title to start on a new page (set to ##t or ##f).
103 Copyright notice, centered at the bottom of the first page. To
104 insert the copyright symbol, see @ref{Text encoding}.
108 Centered at the bottom of the last page.
112 Here is a demonstration of the fields available. Note that you
113 may use any @ref{Text markup}, commands in the header.
115 @lilypond[quote,verbatim,line-width=11.0\cm]
118 paper-height = 10.0\cm
123 dedication = "dedicated to me"
124 title = \markup \center-align { "Title first line" "Title second line,
126 subtitle = "the subtitle,"
127 subsubtitle = #(string-append "subsubtitle LilyPond version "
130 composer = \markup \center-align { "composer" \small "(1847-1973)" }
131 texttranslator = "Text Translator"
132 meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
134 arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize
135 #-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }
136 instrument = \markup \bold \italic "instrument"
160 As demonstrated before, you can use multiple @code{\header} blocks.
161 When same fields appear in different blocks, the latter is used.
162 Here is a short example.
166 composer = "Composer"
174 piece = "New piece" % overwrite previous one
179 If you define the @code{\header} inside the @code{\score} block, then
180 normally only the @code{piece} and @code{opus} headers will be printed.
181 Note that the music expression must come before the @code{\header}.
183 @lilypond[quote,verbatim,line-width=11.0\cm]
187 title = "title" % not printed
194 @funindex printallheaders
196 You may change this behavior (and print all the headers when defining
197 @code{\header} inside @code{\score}) by using
208 The default footer is empty, except for the first page, where the
209 @code{copyright} field from @code{\header} is inserted, and the last
210 page, where @code{tagline} from @code{\header} is added. The default
211 tagline is @qq{Music engraving by LilyPond (@var{version})}.@footnote{Nicely
212 printed parts are good PR for us, so please leave the tagline if you
215 Headers may be completely removed by setting them to false.
226 @subsection Custom titles
228 A more advanced option is to change the definitions of the following
229 variables in the @code{\paper} block. The init file
230 @file{ly/titling-init.ly} lists the default layout.
233 @funindex bookTitleMarkup
234 @item bookTitleMarkup
235 This is the title added at the top of the entire output document.
236 Typically, it has the composer and the title of the piece
238 @funindex scoreTitleMarkup
239 @item scoreTitleMarkup
240 This is the title put over a @code{\score} block. Typically, it has
241 the name of the movement (@code{piece} field).
243 @funindex oddHeaderMarkup
244 @item oddHeaderMarkup
245 This is the page header for odd-numbered pages.
247 @funindex evenHeaderMarkup
248 @item evenHeaderMarkup
249 This is the page header for even-numbered pages. If unspecified,
250 the odd header is used instead.
252 By default, headers are defined such that the page number is on the
253 outside edge, and the instrument is centered.
255 @funindex oddFooterMarkup
256 @item oddFooterMarkup
257 This is the page footer for odd-numbered pages.
259 @funindex evenFooterMarkup
260 @item evenFooterMarkup
261 This is the page footer for even-numbered pages. If unspecified,
262 the odd header is used instead.
264 By default, the footer has the copyright notice on the first, and
265 the tagline on the last page.
275 The following definition will put the title flush left, and the
276 composer flush right on a single line.
280 bookTitleMarkup = \markup {
282 \fromproperty #'header:title
283 \fromproperty #'header:composer
289 @node Reference to page numbers
290 @subsection Reference to page numbers
292 A particular place of a score can be marked using the @code{\label}
293 command, either at top-level or inside music. This label can then be
294 refered to in a markup, to get the number of the page where the marked
295 point is placed, using the @code{\page-ref} markup command.
297 @lilypond[verbatim,line-width=11.0\cm]
298 \header { tagline = ##f }
304 \pageBreak \mark A \label #'markA
309 \markup { The first score begins on page \page-ref #'firstScore "0" "?" }
310 \markup { Mark A is on page \page-ref #'markA "0" "?" }
314 The @code{\page-ref} markup command takes three arguments:
316 @item the label, a scheme symbol, eg. @code{#'firstScore};
317 @item a markup that will be used as a gauge to estimate the dimensions
319 @item a markup that will be used in place of the page number if the label
323 The reason why a gauge is needed is that, at the time markups are
324 interpreted, the page breaking has not yet occured, so the page numbers
325 are not yet known. To work around this issue, the actual markup
326 interpretation is delayed to a later time; however, the dimensions of
327 the markup have to be known before, so a gauge is used to decide these
328 dimensions. If the book has between 10 and 99 pages, it may be "00",
329 ie. a two digit number.
338 @node Table of contents
339 @subsection Table of contents
340 A table of contents is included using the @code{\markuplines \table-of-contents}
341 command. The elements which should appear in the table of contents are
342 entered with the @code{\tocItem} command, which may be used either at
343 top-level, or inside a music expression.
346 \markuplines \table-of-contents
349 \tocItem \markup "First score"
353 \tocItem \markup "Some particular point in the first score"
358 \tocItem \markup "Second score"
366 The markups which are used to format the table of contents are defined
367 in the @code{\paper} block. The default ones are @code{tocTitleMarkup},
368 for formatting the title of the table, and @code{tocItemMarkup}, for
369 formatting the toc elements, composed of the element title and page
370 number. These variables may be changed by the user:
374 %% Translate the toc title into French:
375 tocTitleMarkup = \markup \huge \column {
376 \fill-line { \null "Table des matières" \null }
379 %% use larfer font size
380 tocItemMarkup = \markup \large \fill-line {
381 \fromproperty #'toc:text \fromproperty #'toc:page
386 Note how the toc element text and page number are refered to in
387 the @code{tocItemMarkup} definition.
389 New commands and markups may also be defined to build more elaborated
392 @item first, define a new markup variable in the @code{\paper} block
393 @item then, define a music function which aims at adding a toc element
394 using this markup paper variable.
397 In the following example, a new style is defined for entering act names
398 in the table of contents of an opera:
402 tocActMarkup = \markup \large \column {
404 \fill-line { \null \italic \fromproperty #'toc:text \null }
410 #(define-music-function (parser location text) (markup?)
411 (add-toc-item! 'tocActMarkup text))
414 @lilypond[line-width=11.0\cm]
415 \header { tagline = ##f }
417 tocActMarkup = \markup \large \column {
419 \fill-line { \null \italic \fromproperty #'toc:text \null }
425 #(define-music-function (parser location text) (markup?)
426 (add-toc-item! 'tocActMarkup text))
429 \markuplines \table-of-contents
430 \tocAct \markup { Atto Primo }
431 \tocItem \markup { Coro. Viva il nostro Alcide }
432 \tocItem \markup { Cesare. Presti omai l'Egizzia terra }
433 \tocAct \markup { Atto Secondo }
434 \tocItem \markup { Sinfonia }
435 \tocItem \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
442 Init files: @file{ly/@/toc@/-init@/.ly}.
446 @funindex \table-of-contents
447 @code{\table-of-contents}
457 MIDI (Musical Instrument Digital Interface) is a standard for
458 connecting and controlling digital instruments. A MIDI file is a
459 series of notes in a number of tracks. It is not an actual
460 sound file; you need special software to translate between the
461 series of notes and actual sounds.
463 Pieces of music can be converted to MIDI files, so you can listen to
464 what was entered. This is convenient for checking the music; octaves
465 that are off or accidentals that were mistyped stand out very much
466 when listening to the MIDI output.
470 Many musically interesting effects, such as swing, articulation,
471 slurring, etc., are not translated to midi.
473 The midi output allocates a channel for each staff, and one for global
474 settings. Therefore the midi file should not have more than 15 staves
475 (or 14 if you do not use drums). Other staves will remain silent.
477 Not all midi players correctly handle tempo changes in the midi
478 output. Players that are known to work include
479 @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
482 * Creating MIDI files::
484 * MIDI instrument names::
487 @node Creating MIDI files
488 @subsection Creating MIDI files
490 To create a MIDI from a music piece of music, add a @code{\midi} block
491 to a score, for example,
499 tempoWholesPerMinute = #(ly:make-moment 72 4)
505 The tempo can be specified using the @code{\tempo} command within the
506 actual music, see @ref{Metronome marks}. An alternative, which does not
507 result in a metronome mark in the printed score, is shown in the example
508 above. In this example the tempo of quarter notes is set to 72 beats per
511 specification can not take dotted note lengths as an argument. In this
512 case, break the dotted notes into smaller units. For example, a tempo
513 of 90 dotted quarter notes per minute can be specified as 270 eighth
517 tempoWholesPerMinute = #(ly:make-moment 270 8)
520 If there is a @code{\midi} command in a @code{\score}, only MIDI will
521 be produced. When notation is needed too, a @code{\layout} block must
535 Ties, dynamics, and tempo changes are interpreted. Dynamic marks,
536 crescendi and decrescendi translate into MIDI volume levels. Dynamic
537 marks translate to a fixed fraction of the available MIDI volume
538 range, crescendi and decrescendi make the volume vary linearly between
539 their two extremes. The fractions can be adjusted by
540 @code{dynamicAbsoluteVolumeFunction} in @internalsref{Voice} context.
541 For each type of MIDI instrument, a volume range can be defined. This
542 gives a basic equalizer control, which can enhance the quality of
543 the MIDI output remarkably. The equalizer can be controlled by
544 setting @code{instrumentEqualizer}, or by setting
547 \set Staff.midiMinimumVolume = #0.2
548 \set Staff.midiMaximumVolume = #0.8
551 To remove dynamics from the MIDI output, insert the following lines
552 in the @code{\midi@{@}} section.
559 \remove "Dynamic_performer"
567 Unterminated (de)crescendos will not render properly in the midi file,
568 resulting in silent passages of music. The workaround is to explicitly
569 terminate the (de)crescendo. For example,
576 will not work properly but
586 MIDI output is only created when the @code{\midi} command is within
587 a @code{\score} block. If you put it within an explicitly instantiated
588 context ( i.e. @code{\new Score} ) the file will fail. To solve this,
589 enclose the @code{\new Score} and the @code{\midi} in a @code{\score} block.
593 \new Score @{ @dots{}notes@dots{} @}
600 @subsection MIDI block
604 The MIDI block is analogous to the layout block, but it is somewhat
605 simpler. The @code{\midi} block is similar to @code{\layout}. It can contain
609 @cindex context definition
611 Context definitions follow precisely the same syntax as within the
612 \layout block. Translation modules for sound are called performers.
613 The contexts for MIDI output are defined in @file{ly/@/performer@/-init@/.ly}.
616 @node MIDI instrument names
617 @subsection MIDI instrument names
619 @cindex instrument names
620 @funindex Staff.midiInstrument
622 The MIDI instrument name is set by the @code{Staff.midiInstrument}
623 property. The instrument name should be chosen from the list in
624 @ref{MIDI instruments}.
627 \set Staff.midiInstrument = "glockenspiel"
631 If the selected instrument does not exactly match an instrument from
632 the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})