Merge branch 'master' of git://git.sv.gnu.org/lilypond

[lilypond.git] / Documentation / user / non-music.itely

@c -*- coding: utf-8; mode: texinfo; -*-
@c This file is part of lilypond.tely
@ignore
    Translation of GIT committish: FILL-IN-HEAD-COMMITTISH

    When revising a translation, copy the HEAD committish of the
    version that you are working on.  See TRANSLATION for details.
@end ignore

@c A menu is needed before every deeper *section nesting of @node's; run
@c     M-x texinfo-all-menus-update
@c to automatically fill in these menus before saving changes

@node Non-musical notation
@chapter Non-musical notation

This section deals with general lilypond issues, rather than
specific notation.

@menu
* Titles and headers::          
* MIDI output::                 
* other midi::                  
@end menu


@node Titles and headers
@section Titles and headers

Almost all printed music includes a title and the composer's name;
some pieces include a lot more information.

@menu
* Creating titles::             
* Custom titles::               
* Reference to page numbers::   
* Table of contents::           
@end menu


@node Creating titles
@subsection Creating titles

Titles are created for each @code{\score} block, as well as for the full
input file (or @code{\book} block).

The contents of the titles are taken from the @code{\header} blocks.
The header block for a book supports the following


@table @code
@funindex dedication
@item dedication
The dedicatee of the music, centered at the top of the first page.

@funindex title
@item title
The title of the music, centered just below the dedication.

@funindex subtitle
@item subtitle
Subtitle, centered below the title.

@funindex subsubtitle
@item subsubtitle
Subsubtitle, centered below the subtitle.

@funindex poet
@item poet
Name of the poet, flush-left below the subtitle.

@funindex composer
@item composer
Name of the composer, flush-right below the subtitle.

@funindex meter
@item meter
Meter string, flush-left below the poet.

@funindex opus
@item opus
Name of the opus, flush-right below the composer.

@funindex arranger
@item arranger
Name of the arranger, flush-right below the opus.

@funindex instrument
@item instrument
Name of the instrument, centered below the arranger.  Also
centered at the top of pages (other than the first page).

@funindex piece
@item piece
Name of the piece, flush-left below the instrument.

@cindex page breaks, forcing
@funindex breakbefore
@item breakbefore
This forces the title to start on a new page (set to ##t or ##f).

@funindex copyright
@item copyright
Copyright notice, centered at the bottom of the first page.  To
insert the copyright symbol, see @ref{Text encoding}.

@funindex tagline
@item tagline
Centered at the bottom of the last page.

@end table

Here is a demonstration of the fields available.  Note that you
may use any @ref{Text markup}, commands in the header.

@lilypond[quote,verbatim,line-width=11.0\cm]
\paper {
  line-width = 9.0\cm
  paper-height = 10.0\cm
}

\book {
  \header {
    dedication = "dedicated to me"
    title = \markup \center-align { "Title first line" "Title second line,
longer" }
    subtitle = "the subtitle,"
    subsubtitle = #(string-append "subsubtitle LilyPond version "
(lilypond-version))
    poet = "Poet"
    composer =  \markup \center-align { "composer" \small "(1847-1973)" }
    texttranslator = "Text Translator"
    meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
"r" }
    arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize
#-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }
    instrument = \markup \bold \italic "instrument"
    piece = "Piece"
  }

  \score {
    { c'1 }
    \header {
      piece = "piece1"
      opus = "opus1"
    }
  }
  \markup {
      and now...
  }
  \score {
    { c'1 }
    \header {
      piece = "piece2"
      opus = "opus2"
    }
  }
}
@end lilypond

As demonstrated before, you can use multiple @code{\header} blocks.
When same fields appear in different blocks, the latter is used.
Here is a short example.

@example
\header @{
  composer = "Composer"
@}
\header @{
  piece = "Piece"
@}
\score @{
  \new Staff @{ c'4 @}
  \header @{
    piece = "New piece"  % overwrite previous one
  @}
@}
@end example

If you define the @code{\header} inside the @code{\score} block, then
normally only the @code{piece} and @code{opus} headers will be printed.
Note that the music expression must come before the @code{\header}.

@lilypond[quote,verbatim,line-width=11.0\cm]
\score {
  { c'4 }
  \header {
    title = "title"  % not printed
    piece = "piece"
    opus = "opus"
  }
}
@end lilypond

@funindex printallheaders
@noindent
You may change this behavior (and print all the headers when defining
@code{\header} inside @code{\score}) by using

@example
\paper@{
  printallheaders=##t
@}
@end example

@cindex copyright
@cindex tagline

The default footer is empty, except for the first page, where the
@code{copyright} field from @code{\header} is inserted, and the last
page, where @code{tagline} from @code{\header} is added.  The default
tagline is @qq{Music engraving by LilyPond (@var{version})}.@footnote{Nicely
printed parts are good PR for us, so please leave the tagline if you
can.}

Headers may be completely removed by setting them to false.

@example
\header @{
  tagline = ##f
  composer = ##f
@}
@end example


@node Custom titles
@subsection Custom titles

A more advanced option is to change the definitions of the following
variables in the @code{\paper} block.  The init file
@file{ly/titling-init.ly} lists the default layout.

@table @code
@funindex bookTitleMarkup
@item bookTitleMarkup
  This is the title added at the top of the entire output document.
Typically, it has the composer and the title of the piece

@funindex scoreTitleMarkup
@item scoreTitleMarkup
  This is the title put over a @code{\score} block.  Typically, it has
the name of the movement (@code{piece} field).

@funindex oddHeaderMarkup
@item oddHeaderMarkup
  This is the page header for odd-numbered pages.

@funindex evenHeaderMarkup
@item evenHeaderMarkup
  This is the page header for even-numbered pages.  If unspecified,
  the odd header is used instead.

  By default, headers are defined such that the page number is on the
  outside edge, and the instrument is centered.

@funindex oddFooterMarkup
@item oddFooterMarkup
  This is the page footer for odd-numbered pages.

@funindex evenFooterMarkup
@item evenFooterMarkup
  This is the page footer for even-numbered pages.  If unspecified,
  the odd header is used instead.

  By default, the footer has the copyright notice on the first, and
  the tagline on the last page.
@end table


@cindex \paper
@cindex header
@cindex footer
@cindex page layout
@cindex titles

The following definition will put the title flush left, and the
composer flush right on a single line.

@verbatim
\paper {
  bookTitleMarkup = \markup {
   \fill-line {
     \fromproperty #'header:title
     \fromproperty #'header:composer
   }
  }
}
@end verbatim

@node Reference to page numbers
@subsection Reference to page numbers

A particular place of a score can be marked using the @code{\label}
command, either at top-level or inside music.  This label can then be
refered to in a markup, to get the number of the page where the marked
point is placed, using the @code{\page-ref} markup command.

@lilypond[verbatim,line-width=11.0\cm]
\header { tagline = ##f }
\book {
  \label #'firstScore
  \score {
    {
      c'1
      \pageBreak \mark A \label #'markA
      c'
    }
  }

  \markup { The first score begins on page \page-ref #'firstScore "0" "?" }
  \markup { Mark A is on page \page-ref #'markA "0" "?" }
}
@end lilypond

The @code{\page-ref} markup command takes three arguments:
@enumerate
@item the label, a scheme symbol, eg. @code{#'firstScore};
@item a markup that will be used as a gauge to estimate the dimensions
of the markup;
@item a markup that will be used in place of the page number if the label 
is not known;
@end enumerate

The reason why a gauge is needed is that, at the time markups are
interpreted, the page breaking has not yet occured, so the page numbers
are not yet known.  To work around this issue, the actual markup
interpretation is delayed to a later time; however, the dimensions of
the markup have to be known before, so a gauge is used to decide these
dimensions.  If the book has between 10 and 99 pages, it may be "00",
ie. a two digit number.

@refcommands

@funindex \label
@code{\label}
@funindex \page-ref
@code{\page-ref}

@node Table of contents
@subsection Table of contents
A table of contents is included using the @code{\markuplines \table-of-contents}
command.  The elements which should appear in the table of contents are
entered with the @code{\tocItem} command, which may be used either at
top-level, or inside a music expression.

@verbatim
\markuplines \table-of-contents
\pageBreak

\tocItem \markup "First score"
\score { 
  {
    c'  % ...
    \tocItem \markup "Some particular point in the first score"
    d'  % ... 
  }
}

\tocItem \markup "Second score"
\score {
  {
    e' % ...
  }
}
@end verbatim

The markups which are used to format the table of contents are defined
in the @code{\paper} block.  The default ones are @code{tocTitleMarkup},
for formatting the title of the table, and @code{tocItemMarkup}, for
formatting the toc elements, composed of the element title and page
number.  These variables may be changed by the user:

@verbatim
\paper {
  %% Translate the toc title into French:
  tocTitleMarkup = \markup \huge \column {
    \fill-line { \null "Table des matières" \null }
    \hspace #1
  }
  %% use larfer font size
  tocItemMarkup = \markup \large \fill-line {
    \fromproperty #'toc:text \fromproperty #'toc:page
  }
}
@end verbatim

Note how the toc element text and page number are refered to in
the @code{tocItemMarkup} definition.

New commands and markups may also be defined to build more elaborated
table of contents:
@itemize
@item first, define a new markup variable in the @code{\paper} block
@item then, define a music function which aims at adding a toc element
using this markup paper variable.
@end itemize

In the following example, a new style is defined for entering act names
in the table of contents of an opera:

@verbatim
\paper {
  tocActMarkup = \markup \large \column {
    \hspace #1
    \fill-line { \null \italic \fromproperty #'toc:text \null }
    \hspace #1
  }
}

tocAct = 
#(define-music-function (parser location text) (markup?)
   (add-toc-item! 'tocActMarkup text))
@end verbatim

@lilypond[line-width=11.0\cm]
\header { tagline = ##f }
\paper {
  tocActMarkup = \markup \large \column {
    \hspace #1
    \fill-line { \null \italic \fromproperty #'toc:text \null }
    \hspace #1
  }
}

tocAct = 
#(define-music-function (parser location text) (markup?)
   (add-toc-item! 'tocActMarkup text))

\book {
  \markuplines \table-of-contents
  \tocAct \markup { Atto Primo }
  \tocItem \markup { Coro. Viva il nostro Alcide }
  \tocItem \markup { Cesare. Presti omai l'Egizzia terra }
  \tocAct \markup { Atto Secondo }
  \tocItem \markup { Sinfonia }
  \tocItem \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
  \markup \null
}
@end lilypond

@seealso

Init files: @file{ly/@/toc@/-init@/.ly}.

@refcommands

@funindex \table-of-contents
@code{\table-of-contents}
@funindex \tocItem
@code{\tocItem}

@node MIDI output
@section MIDI output

@cindex Sound
@cindex MIDI

MIDI (Musical Instrument Digital Interface) is a standard for
connecting and controlling digital instruments.  A MIDI file is a
series of notes in a number of tracks.  It is not an actual
sound file; you need special software to translate between the
series of notes and actual sounds.

Pieces of music can be converted to MIDI files, so you can listen to
what was entered.  This is convenient for checking the music; octaves
that are off or accidentals that were mistyped stand out very much
when listening to the MIDI output.

@refbugs

Many musically interesting effects, such as swing, articulation,
slurring, etc., are not translated to midi.

The midi output allocates a channel for each staff, and one for global
settings.  Therefore the midi file should not have more than 15 staves
(or 14 if you do not use drums).  Other staves will remain silent.

Not all midi players correctly handle tempo changes in the midi
output.  Players that are known to work include
@uref{http://@/timidity@/.sourceforge@/.net/,timidity}.

@menu
* Creating MIDI files::         
* MIDI block::                  
* MIDI instrument names::       
* What goes into the MIDI?  FIXME::  
@end menu

@node Creating MIDI files
@subsection Creating MIDI files

To create a MIDI from a music piece of music, add a @code{\midi} block
to a score, for example,

@example
\score @{
  @var{...music...}
   \midi @{
     \context @{
       \Score
       tempoWholesPerMinute = #(ly:make-moment 72 4)
       @}
     @}
@}
@end example

The tempo can be specified using the @code{\tempo} command within the 
actual music, see @ref{Metronome marks}.  An alternative, which does not
result in a metronome mark in the printed score, is shown in the example
above.  In this example the tempo of quarter notes is set to 72 beats per
minute. 
This kind of tempo
specification can not take dotted note lengths as an argument.  In this
case, break the dotted notes into smaller units.  For example, a tempo
of 90 dotted quarter notes per minute can be specified as 270 eighth
notes per minute

@example
tempoWholesPerMinute = #(ly:make-moment 270 8)
@end example

If there is a @code{\midi} command in a @code{\score}, only MIDI will
be produced.  When notation is needed too, a @code{\layout} block must
be added

@example
\score @{
  @var{...music...}
  \midi @{ @}
  \layout @{ @}
@}
@end example
@cindex layout block



Ties, dynamics, and tempo changes are interpreted.  Dynamic marks,
crescendi and decrescendi translate into MIDI volume levels.  Dynamic
marks translate to a fixed fraction of the available MIDI volume
range, crescendi and decrescendi make the volume vary linearly between
their two extremes.  The fractions can be adjusted by
@code{dynamicAbsoluteVolumeFunction} in @internalsref{Voice} context.
For each type of MIDI instrument, a volume range can be defined.  This
gives a basic equalizer control, which can enhance the quality of
the MIDI output remarkably.  The equalizer can be controlled by
setting @code{instrumentEqualizer}, or by setting

@example
\set Staff.midiMinimumVolume = #0.2
\set Staff.midiMaximumVolume = #0.8
@end example

To remove dynamics from the MIDI output, insert the following lines
in the @code{\midi@{@}} section.

@example
\midi @{
  ...
  \context @{
    \Voice
    \remove "Dynamic_performer"
  @}
@}
@end example


@refbugs

Unterminated (de)crescendos will not render properly in the midi file,
resulting in silent passages of music.  The workaround is to explicitly
terminate the (de)crescendo.  For example,

@example
@{ a\< b c d\f @}
@end example

@noindent
will not work properly but

@example
@{ a\< b c d\!\f @}
@end example

@noindent
will.


MIDI output is only created when the @code{\midi} command is within
a @code{\score} block.  If you put it within an explicitly instantiated
context ( i.e. @code{\new Score} ) the file will fail.  To solve this,
enclose the @code{\new Score} and the @code{\midi} in a @code{\score} block.

@example
\score @{
  \new Score @{ @dots{}notes@dots{} @}
  \midi
@}
@end example


@node MIDI block
@subsection MIDI block
@cindex MIDI block


The MIDI block is analogous to the layout block, but it is somewhat
simpler.  The @code{\midi} block is similar to @code{\layout}.  It can contain
context definitions.


@cindex context definition

Context definitions follow precisely the same syntax as within the
\layout block.  Translation modules for sound are called performers.
The contexts for MIDI output are defined in @file{ly/@/performer@/-init@/.ly}.


@node MIDI instrument names
@subsection MIDI instrument names

@cindex instrument names
@funindex Staff.midiInstrument

The MIDI instrument name is set by the @code{Staff.midiInstrument}
property.  The instrument name should be chosen from the list in
@ref{MIDI instruments}.

@example
\set Staff.midiInstrument = "glockenspiel"
@var{...notes...}
@end example

If the selected instrument does not exactly match an instrument from
the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
instrument is used.


@node What goes into the MIDI?  FIXME
@subsection What goes into the MIDI?  FIXME

@menu
* Repeats and MIDI::            
@end menu

@node Repeats and MIDI
@unnumberedsubsubsec Repeats and MIDI

@cindex expanding repeats
@funindex \unfoldRepeats

With a little bit of tweaking, all types of repeats can be present
in the MIDI output.  This is achieved by applying the
@code{\unfoldRepeats} music function.  This function changes all
repeats to unfold repeats.

@lilypond[quote,verbatim,fragment,line-width=8.0\cm]
\unfoldRepeats {
  \repeat tremolo 8 {c'32 e' }
  \repeat percent 2 { c''8 d'' }
  \repeat volta 2 {c'4 d' e' f'}
  \alternative {
    { g' a' a' g' }
    {f' e' d' c' }
  }
}
\bar "|."
@end lilypond

When creating a score file using @code{\unfoldRepeats} for MIDI,
it is necessary to make two @code{\score} blocks: one for MIDI
(with unfolded repeats) and one for notation (with volta, tremolo,
and percent repeats).  For example,

@example
\score @{
  @var{..music..}
  \layout @{ .. @}
@}
\score @{
  \unfoldRepeats @var{..music..}
  \midi @{ .. @}
@}
@end example


@node other midi
@section other midi

Micro tones are also exported to the MIDI file.