* Documentation/user/global.itely (Extracting fragments of

[lilypond.git] / Documentation / user / global.itely

@c -*- coding: utf-8; mode: texinfo; -*-
@c This file is part of lilypond.tely

@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
* Input files::                 
* Titles and headers::          
* MIDI output::                 
* Displaying LilyPond notation::  
* Skipping corrected music::    
@end menu


@node Input files
@section Input files

The main format of input for LilyPond are text files.  By convention,
these files end with ``@code{.ly}''.

@menu
* File structure (introduction)::  
* Multiple scores in a book::   
* Extracting fragments of notation::  
* File structure::              
* A single music expression::   
* Including LilyPond files::    
* Text encoding::               
@end menu


@node File structure (introduction)
@subsection File structure (introduction)

A basic example of a lilypond input file is

@example
\version "2.9.13"
\score @{
  @{ @}     % this is a single music expression;
            % all the music goes in here.
  \header @{ @}
  \layout @{ @}
  \midi @{ @}
@}
@end example

@noindent
There are many variations of this basic pattern, but this
example serves as a useful starting place.

The major part of this manual is concerned with entering various
forms of music in LilyPond.  However, many music expressions are not
valid input on their own, for example, a @code{.ly} file containing
only a note
@example
c'4
@end example

@noindent
will result in a parsing error.  Instead, music should be inside other
expressions, which may be put in a file by themselves.  Such
expressions are called toplevel expressions.  The next section enumerates
them all.


@node Multiple scores in a book
@subsection Multiple scores in a book

@funindex \book
@cindex movements, multiple

A document may contain multiple pieces of music and texts.  Examples
of these are an etude book, or an orchestral part with multiple
movements.  Each movement is entered with a @code{\score} block,

@example
\score @{
  @var{..music..}
@}
@end example

and texts are entered with a @code{\markup} block,

@example
\markup @{
  @var{..text..}
@}
@end example

@funindex \book

The movements and texts are combined together in a @code{\book} block,
like

@example
\book @{
  \score @{
    @var{..}
  @}
  \markup @{
    @var{..}
  @}
  \score @{
    @var{..}
  @}
@}
@end example


The header for each piece of music can be put inside the @code{\score}
block.  The @code{piece} name from the header will be printed before
each movement.  The title for the entire book can be put inside the
@code{\book}, but if it is not present, the @code{\header} which is at
the top of the file is inserted.

@example
\book @{
  \header @{
    title = "Eight miniatures"
    composer = "Igor Stravinsky"
  @}
  \score @{
    @dots{}
    \header @{ piece = "Romanze" @}
  @}
  \markup @{
     ..text of second verse..
  @}
  \markup @{
     ..text of third verse..
  @}
  \score @{
    @dots{}
    \header @{ piece = "Menuetto" @}
  @}
@}
@end example

@node Extracting fragments of notation
@subsection Extracting fragments of notation

It is possible to quote small fragments of a large score directly from
the output. This can be compared to clipping a piece of a paper score
with scissors.

This is done by definining the measures that need to be cut out
separately. For example, including the following definition


@verbatim
\layout {
  clip-regions
  = #(list
      (cons
       (make-rhythmic-location 5 1 2)
       (make-rhythmic-location 7 3 4)))
}       
@end verbatim

@noindent
will extract a fragment starting halfway the fifth measure, ending in
the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note
in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7.

More clip regions can be defined by adding more pairs of
rhythmic-locations to the list. 

In order to use this feature, LilyPond must be invoked with
@code{-dclip-systems}. The clips are output as EPS files, and are
converted to PDF and PNG if these formats are switched on as well.

For more information on output formats, see @ref{Invoking lilypond}.

@seealso

Examples: @inputfileref{input/regression/clip-systems.ly}


@node File structure
@subsection File structure

A @code{.ly} file contains any number of toplevel expressions, where a
toplevel expression is one of the following

@itemize @bullet
@item
An output definition, such as @code{\paper}, @code{\midi}, and
@code{\layout}.  Such a definition at the toplevel changes the default
settings for the block entered.

@item
A direct scheme expression, such as
@code{#(set-default-paper-size "a7" 'landscape)} or
@code{#(ly:set-option 'point-and-click #f)}.

@item
A @code{\header} block.  This sets the global header block.  This
is the block containing the definitions for book-wide settings, like
composer, title, etc.

@item
An @code{\addquote} statement.  See @ref{Quoting other voices}
for more information.

@item
A @code{\score} block.  This score will be collected with other
toplevel scores, and combined as a single @code{\book}.

This behavior can be changed by setting the variable
@code{toplevel-score-handler} at toplevel.  The default handler is
defined in the init file @file{scm/@/lily@/.scm}.

The @code{\score} must begin with a music expression, and may
contain only one music expression.

@item
A @code{\book} block logically combines multiple movements
(i.e., multiple @code{\score} blocks) in one document.  If there are
a number of @code{\scores}, a single output file will be created
in which all movements are concatenated.

This behavior can be changed by setting the variable
@code{toplevel-book-handler} at toplevel.  The default handler is
defined in the init file @file{scm/@/lily@/.scm}.

@item
A compound music expression, such as
@example
@{ c'4 d' e'2 @}
@end example

This will add the piece in a @code{\score} and format it in a
single book together with all other toplevel @code{\score}s and music
expressions.  In other words, a file containing only the above
music expression will be translated into

@example
\book @{
  \score @{
    \new Staff @{
      \new Voice @{
        @{ c'4 d' e'2 @}
      @}
    @}
  @}
        \layout @{ @}
        \header @{ @}
@}
@end example

This behavior can be changed by setting the variable
@code{toplevel-music-handler} at toplevel.  The default handler is
defined in the init file @file{scm/@/lily@/.scm}.

@item
A markup text, a verse for example
@example
\markup @{
   2.  The first line verse two.
@}
@end example

Markup texts are rendered above, between or below the scores or music
expressions, wherever they appear.

@item
An identifier, such as
@example
foo = @{ c4 d e d @}
@end example

This can be used later on in the file by entering @code{\foo}.  The
name of an identifier should have alphabetic characters only; no
numbers, underscores or dashes.

@end itemize

The following example shows three things that may be entered at
toplevel

@example
\layout @{
  % movements are non-justified by default
  ragged-right = ##t
@}

\header @{
   title = "Do-re-mi"
@}

@{ c'4 d' e2 @}
@end example


At any point in a file, any of the following lexical instructions can
be entered:

@itemize @bullet
@item @code{\version}
@item @code{\include}
@item @code{\renameinput}
@end itemize


@node A single music expression
@subsection A single music expression

A @code{\score} must contain a single music expression.  However,
this music expression may be of any size.  Recall that music
expressions may be included inside other expressions to form
larger expressions.  All of these examples are single music
expressions; note the curly braces @{ @} or angle brackets <<
>> at the beginning and ending of the music.

@example
@{ c'4 c' c' c' @}
@end example

@lilypond[ragged-right,verbatim,quote]
{
  { c'4 c' c' c'}
  { d'4 d' d' d'}
}
@end lilypond

@lilypond[ragged-right,verbatim,quote]
<<
  \new Staff { c'4 c' c' c' }
  \new Staff { d'4 d' d' d' }
>>
@end lilypond

@example
@{
  \new GrandStaff <<
    \new StaffGroup <<
      \new Staff @{ \flute @}
      \new Staff @{ \oboe @}
    >>
    \new StaffGroup <<
      \new Staff @{ \violinI @}
      \new Staff @{ \violinII @}
    >>
  >>
@}
@end example


@node Including LilyPond files
@subsection Including LilyPond files

@funindex \include
@cindex including files

A large project may be split up into separate files.  To refer to another
file, use

@example
\include "otherfile.ly"
@end example

The line @code{\include "file.ly"} is equivalent to pasting the contents
of file.ly into the current file at the place where you have the
\include.  For example, for a large project you might write separate files
for each instrument part and create a ``full score'' file which brings
together the individual instrument files.

The initialization of LilyPond is done in a number of files that are
included by default when you start the program, normally transparent to the
user.  Run lilypond --verbose to see a list of paths and files that Lily
finds.

Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where
VERSION is in the form ``2.6.1'') are on the path and available to
@code{\include}.  Files in the
current working directory are available to \include, but a file of the same
name in LilyPond's installation takes precedence.  Files are
available to \include from directories in the search path specified as an
option when invoking @code{lilypond --include=DIR} which adds DIR to the
search path.

The @code{\include} statement can use full path information, but with the Unix
convention @code{"/"} rather than the DOS/Windows @code{"\"}.  For example,
if @file{stuff.ly} is located one directory higher than the current working
directory, use

@example
\include "../stuff.ly"
@end example


@node Text encoding
@subsection Text encoding

LilyPond uses the Pango library to format multi-lingual texts, and
does not perform any input-encoding conversions.  This means that any
text, be it title, lyric text, or musical instruction containing
non-ASCII characters, must be utf-8.  The easiest way to enter such text is
by using a Unicode-aware editor and saving the file with utf-8 encoding.  Most
popular modern editors have utf-8 support, for example, vim, Emacs,
jEdit, and GEdit do.

@c  Currently not working
@ignore
Depending on the fonts installed, the following fragment shows Hebrew
and Cyrillic lyrics,

@cindex Cyrillic
@cindex Hebrew
@cindex ASCII, non

@li lypondfile[fontload]{utf-8.ly}

The @TeX{} backend does not handle encoding specially at all.  Strings
in the input are put in the output as-is.  Extents of text items in the
@TeX{} backend, are determined by reading a file created via the
@file{texstr} backend,

@example
lilypond -b texstr input/les-nereides.ly
latex les-nereides.texstr
@end example

The last command produces @file{les-nereides.textmetrics}, which is
read when you execute

@example
lilypond -b tex input/les-nereides.ly
@end example

Both @file{les-nereides.texstr} and @file{les-nereides.tex} need
suitable LaTeX wrappers to load appropriate La@TeX{} packages for
interpreting non-ASCII strings.

@end ignore

To use a Unicode escape sequence, use

@example
#(ly:export (ly:wide-char->utf-8 #x2014))
@end example


@seealso

@inputfileref{input/regression,utf-8.ly}



@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::               
@end menu


@node Creating titles
@subsection Creating titles

Titles are created for each @code{\score} block, and over a
@code{\book}.

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 ``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 put over an entire @code{\book} block.  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 within a
@code{\book}.  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 evenFotterMarkup
@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


@refbugs

The @code{breakbefore=##t} header requires that there is a @code{piece}
header as well.  It may be used as a normal header, or left  blank
(@code{=""}) as in the example above, but it must be present.



@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::       
@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 @{  @}
@}
@end example

FIXME

The tempo is specified using the @code{\tempo} command.  In this
example the tempo of quarter notes is set to 72 beats per minute.


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"
    \remove "Span_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.


@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.


@c  Yes, this is a cop-out; this info doesn't belong in the Scheme
@c  chapter, but I'm not certain where to stick it.
@c  I think I'll eventually split this chapter into a "paper/layout"
@c  chapter and a "misc issues" chapter.  -gp
@node Displaying LilyPond notation
@section Displaying LilyPond notation

@funindex \displayLilyMusc
Displaying a music expression in LilyPond notation can be
done using the music function @code{\displayLilyMusic}.  For example,

@example
@{
  \displayLilyMusic \transpose c a, @{ c e g a bes @}
@}
@end example

will display

@example
@{ a, cis e fis g @}
@end example

By default, LilyPond will print these messages to the console along
with all the other messages.  To split up these messages and save
the results of @code{\display@{STUFF@}}, redirect the output to
a file.

@example
lilypond file.ly >display.txt
@end example


@node Skipping corrected music
@section Skipping corrected music


@funindex skipTypesetting
@funindex showLastLength

When entering or copying music, usually only the music near the end (where
you
are adding notes) is interesting to view and correct.  To speed up
this correction process, it is possible to skip typesetting of all but
the last few measures. This is achieved by putting

@verbatim
showLastLength = R1*5
\score { ... }
@end verbatim

@noindent
in your source file. This will render only the last 5 measures
(assuming 4/4 time signature) of every @code{\score} in the input
file. For longer pieces, rendering only a small part is often an order
of magnitude quicker than rendering it completely

Skipping parts of a score can be controlled in a more fine-grained
fashion with the property @code{Score.skipTypesetting}.  When it is
set, no typesetting is performed at all.

This property is also used to control output to the MIDI file. Note that
it skips all events, including tempo and instrument changes. You have
been warned.

@lilypond[quote,fragment,ragged-right,verbatim]
\relative c'' {
  c8 d
  \set Score.skipTypesetting = ##t
  e e e e e e e e
  \set Score.skipTypesetting = ##f
  c d b bes a g c2 }
@end lilypond

In polyphonic music, @code{Score.skipTypesetting} will affect all
voices and staves, saving even more time.