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::
27 @node Titles and headers
28 @section Titles and headers
30 Almost all printed music includes a title and the composer's name;
31 some pieces include a lot more information.
36 * Reference to page numbers::
42 @subsection Creating titles
44 Titles are created for each @code{\score} block, as well as for the full
45 input file (or @code{\book} block).
47 The contents of the titles are taken from the @code{\header} blocks.
48 The header block for a book supports the following
54 The dedicatee of the music, centered at the top of the first page.
58 The title of the music, centered just below the dedication.
62 Subtitle, centered below the title.
66 Subsubtitle, centered below the subtitle.
70 Name of the poet, flush-left below the subtitle.
74 Name of the composer, flush-right below the subtitle.
78 Meter string, flush-left below the poet.
82 Name of the opus, flush-right below the composer.
86 Name of the arranger, flush-right below the opus.
90 Name of the instrument, centered below the arranger. Also
91 centered at the top of pages (other than the first page).
95 Name of the piece, flush-left below the instrument.
97 @cindex page breaks, forcing
100 This forces the title to start on a new page (set to ##t or ##f).
104 Copyright notice, centered at the bottom of the first page. To
105 insert the copyright symbol, see @ref{Text encoding}.
109 Centered at the bottom of the last page.
113 Here is a demonstration of the fields available. Note that you
114 may use any @ref{Text markup}, commands in the header.
116 @lilypond[quote,verbatim,line-width=11.0\cm]
119 paper-height = 10.0\cm
124 dedication = "dedicated to me"
125 title = \markup \center-align { "Title first line" "Title second line,
127 subtitle = "the subtitle,"
128 subsubtitle = #(string-append "subsubtitle LilyPond version "
131 composer = \markup \center-align { "composer" \small "(1847-1973)" }
132 texttranslator = "Text Translator"
133 meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
135 arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize
136 #-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }
137 instrument = \markup \bold \italic "instrument"
161 As demonstrated before, you can use multiple @code{\header} blocks.
162 When same fields appear in different blocks, the latter is used.
163 Here is a short example.
167 composer = "Composer"
175 piece = "New piece" % overwrite previous one
180 If you define the @code{\header} inside the @code{\score} block, then
181 normally only the @code{piece} and @code{opus} headers will be printed.
182 Note that the music expression must come before the @code{\header}.
184 @lilypond[quote,verbatim,line-width=11.0\cm]
188 title = "title" % not printed
195 @funindex printallheaders
197 You may change this behavior (and print all the headers when defining
198 @code{\header} inside @code{\score}) by using
209 The default footer is empty, except for the first page, where the
210 @code{copyright} field from @code{\header} is inserted, and the last
211 page, where @code{tagline} from @code{\header} is added. The default
212 tagline is @qq{Music engraving by LilyPond (@var{version})}.@footnote{Nicely
213 printed parts are good PR for us, so please leave the tagline if you
216 Headers may be completely removed by setting them to false.
227 @subsection Custom titles
229 A more advanced option is to change the definitions of the following
230 variables in the @code{\paper} block. The init file
231 @file{ly/titling-init.ly} lists the default layout.
234 @funindex bookTitleMarkup
235 @item bookTitleMarkup
236 This is the title added at the top of the entire output document.
237 Typically, it has the composer and the title of the piece
239 @funindex scoreTitleMarkup
240 @item scoreTitleMarkup
241 This is the title put over a @code{\score} block. Typically, it has
242 the name of the movement (@code{piece} field).
244 @funindex oddHeaderMarkup
245 @item oddHeaderMarkup
246 This is the page header for odd-numbered pages.
248 @funindex evenHeaderMarkup
249 @item evenHeaderMarkup
250 This is the page header for even-numbered pages. If unspecified,
251 the odd header is used instead.
253 By default, headers are defined such that the page number is on the
254 outside edge, and the instrument is centered.
256 @funindex oddFooterMarkup
257 @item oddFooterMarkup
258 This is the page footer for odd-numbered pages.
260 @funindex evenFooterMarkup
261 @item evenFooterMarkup
262 This is the page footer for even-numbered pages. If unspecified,
263 the odd header is used instead.
265 By default, the footer has the copyright notice on the first, and
266 the tagline on the last page.
276 The following definition will put the title flush left, and the
277 composer flush right on a single line.
281 bookTitleMarkup = \markup {
283 \fromproperty #'header:title
284 \fromproperty #'header:composer
290 @node Reference to page numbers
291 @subsection Reference to page numbers
293 A particular place of a score can be marked using the @code{\label}
294 command, either at top-level or inside music. This label can then be
295 refered to in a markup, to get the number of the page where the marked
296 point is placed, using the @code{\page-ref} markup command.
298 @lilypond[verbatim,line-width=11.0\cm]
299 \header { tagline = ##f }
305 \pageBreak \mark A \label #'markA
310 \markup { The first score begins on page \page-ref #'firstScore "0" "?" }
311 \markup { Mark A is on page \page-ref #'markA "0" "?" }
315 The @code{\page-ref} markup command takes three arguments:
317 @item the label, a scheme symbol, eg. @code{#'firstScore};
318 @item a markup that will be used as a gauge to estimate the dimensions
320 @item a markup that will be used in place of the page number if the label
324 The reason why a gauge is needed is that, at the time markups are
325 interpreted, the page breaking has not yet occured, so the page numbers
326 are not yet known. To work around this issue, the actual markup
327 interpretation is delayed to a later time; however, the dimensions of
328 the markup have to be known before, so a gauge is used to decide these
329 dimensions. If the book has between 10 and 99 pages, it may be "00",
330 ie. a two digit number.
339 @node Table of contents
340 @subsection Table of contents
341 A table of contents is included using the @code{\markuplines \table-of-contents}
342 command. The elements which should appear in the table of contents are
343 entered with the @code{\tocItem} command, which may be used either at
344 top-level, or inside a music expression.
347 \markuplines \table-of-contents
350 \tocItem \markup "First score"
354 \tocItem \markup "Some particular point in the first score"
359 \tocItem \markup "Second score"
367 The markups which are used to format the table of contents are defined
368 in the @code{\paper} block. The default ones are @code{tocTitleMarkup},
369 for formatting the title of the table, and @code{tocItemMarkup}, for
370 formatting the toc elements, composed of the element title and page
371 number. These variables may be changed by the user:
375 %% Translate the toc title into French:
376 tocTitleMarkup = \markup \huge \column {
377 \fill-line { \null "Table des matières" \null }
380 %% use larfer font size
381 tocItemMarkup = \markup \large \fill-line {
382 \fromproperty #'toc:text \fromproperty #'toc:page
387 Note how the toc element text and page number are refered to in
388 the @code{tocItemMarkup} definition.
390 New commands and markups may also be defined to build more elaborated
393 @item first, define a new markup variable in the @code{\paper} block
394 @item then, define a music function which aims at adding a toc element
395 using this markup paper variable.
398 In the following example, a new style is defined for entering act names
399 in the table of contents of an opera:
403 tocActMarkup = \markup \large \column {
405 \fill-line { \null \italic \fromproperty #'toc:text \null }
411 #(define-music-function (parser location text) (markup?)
412 (add-toc-item! 'tocActMarkup text))
415 @lilypond[line-width=11.0\cm]
416 \header { tagline = ##f }
418 tocActMarkup = \markup \large \column {
420 \fill-line { \null \italic \fromproperty #'toc:text \null }
426 #(define-music-function (parser location text) (markup?)
427 (add-toc-item! 'tocActMarkup text))
430 \markuplines \table-of-contents
431 \tocAct \markup { Atto Primo }
432 \tocItem \markup { Coro. Viva il nostro Alcide }
433 \tocItem \markup { Cesare. Presti omai l'Egizzia terra }
434 \tocAct \markup { Atto Secondo }
435 \tocItem \markup { Sinfonia }
436 \tocItem \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
443 Init files: @file{ly/@/toc@/-init@/.ly}.
447 @funindex \table-of-contents
448 @code{\table-of-contents}
458 MIDI (Musical Instrument Digital Interface) is a standard for
459 connecting and controlling digital instruments. A MIDI file is a
460 series of notes in a number of tracks. It is not an actual
461 sound file; you need special software to translate between the
462 series of notes and actual sounds.
464 Pieces of music can be converted to MIDI files, so you can listen to
465 what was entered. This is convenient for checking the music; octaves
466 that are off or accidentals that were mistyped stand out very much
467 when listening to the MIDI output.
471 Many musically interesting effects, such as swing, articulation,
472 slurring, etc., are not translated to midi.
474 The midi output allocates a channel for each staff, and one for global
475 settings. Therefore the midi file should not have more than 15 staves
476 (or 14 if you do not use drums). Other staves will remain silent.
478 Not all midi players correctly handle tempo changes in the midi
479 output. Players that are known to work include
480 @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
483 * Creating MIDI files::
485 * MIDI instrument names::
486 * What goes into the MIDI? FIXME::
489 @node Creating MIDI files
490 @subsection Creating MIDI files
492 To create a MIDI from a music piece of music, add a @code{\midi} block
493 to a score, for example,
501 tempoWholesPerMinute = #(ly:make-moment 72 4)
507 The tempo can be specified using the @code{\tempo} command within the
508 actual music, see @ref{Metronome marks}. An alternative, which does not
509 result in a metronome mark in the printed score, is shown in the example
510 above. In this example the tempo of quarter notes is set to 72 beats per
513 specification can not take dotted note lengths as an argument. In this
514 case, break the dotted notes into smaller units. For example, a tempo
515 of 90 dotted quarter notes per minute can be specified as 270 eighth
519 tempoWholesPerMinute = #(ly:make-moment 270 8)
522 If there is a @code{\midi} command in a @code{\score}, only MIDI will
523 be produced. When notation is needed too, a @code{\layout} block must
537 Ties, dynamics, and tempo changes are interpreted. Dynamic marks,
538 crescendi and decrescendi translate into MIDI volume levels. Dynamic
539 marks translate to a fixed fraction of the available MIDI volume
540 range, crescendi and decrescendi make the volume vary linearly between
541 their two extremes. The fractions can be adjusted by
542 @code{dynamicAbsoluteVolumeFunction} in @internalsref{Voice} context.
543 For each type of MIDI instrument, a volume range can be defined. This
544 gives a basic equalizer control, which can enhance the quality of
545 the MIDI output remarkably. The equalizer can be controlled by
546 setting @code{instrumentEqualizer}, or by setting
549 \set Staff.midiMinimumVolume = #0.2
550 \set Staff.midiMaximumVolume = #0.8
553 To remove dynamics from the MIDI output, insert the following lines
554 in the @code{\midi@{@}} section.
561 \remove "Dynamic_performer"
569 Unterminated (de)crescendos will not render properly in the midi file,
570 resulting in silent passages of music. The workaround is to explicitly
571 terminate the (de)crescendo. For example,
578 will not work properly but
588 MIDI output is only created when the @code{\midi} command is within
589 a @code{\score} block. If you put it within an explicitly instantiated
590 context ( i.e. @code{\new Score} ) the file will fail. To solve this,
591 enclose the @code{\new Score} and the @code{\midi} in a @code{\score} block.
595 \new Score @{ @dots{}notes@dots{} @}
602 @subsection MIDI block
606 The MIDI block is analogous to the layout block, but it is somewhat
607 simpler. The @code{\midi} block is similar to @code{\layout}. It can contain
611 @cindex context definition
613 Context definitions follow precisely the same syntax as within the
614 \layout block. Translation modules for sound are called performers.
615 The contexts for MIDI output are defined in @file{ly/@/performer@/-init@/.ly}.
618 @node MIDI instrument names
619 @subsection MIDI instrument names
621 @cindex instrument names
622 @funindex Staff.midiInstrument
624 The MIDI instrument name is set by the @code{Staff.midiInstrument}
625 property. The instrument name should be chosen from the list in
626 @ref{MIDI instruments}.
629 \set Staff.midiInstrument = "glockenspiel"
633 If the selected instrument does not exactly match an instrument from
634 the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
638 @node What goes into the MIDI? FIXME
639 @subsection What goes into the MIDI? FIXME
645 @node Repeats and MIDI
646 @subsubsection Repeats and MIDI
648 @cindex expanding repeats
649 @funindex \unfoldRepeats
651 With a little bit of tweaking, all types of repeats can be present
652 in the MIDI output. This is achieved by applying the
653 @code{\unfoldRepeats} music function. This function changes all
654 repeats to unfold repeats.
656 @lilypond[quote,verbatim,fragment,line-width=8.0\cm]
658 \repeat tremolo 8 {c'32 e' }
659 \repeat percent 2 { c''8 d'' }
660 \repeat volta 2 {c'4 d' e' f'}
669 When creating a score file using @code{\unfoldRepeats} for MIDI,
670 it is necessary to make two @code{\score} blocks: one for MIDI
671 (with unfolded repeats) and one for notation (with volta, tremolo,
672 and percent repeats). For example,
680 \unfoldRepeats @var{..music..}
689 Micro tones are also exported to the MIDI file.