Guide, node Updating translation committishes..
@end ignore
-@c \version "2.16.0"
+@c \version "2.19.22"
@node General input and output
@chapter General input and output
* Titles and headers::
* Working with input files::
* Controlling output::
-* MIDI output::
+* Creating MIDI output::
* Extracting musical information::
@end menu
@example
\score @{
-...
+ @dots{}
@}
@end example
Comments are one exception to this general rule. (For others see
@ref{File structure}.) Both single-line comments and comments
-delimited by @code{%@{ .. %@}} may be placed anywhere within an
+delimited by @code{%@{ @dots{} %@}} may be placed anywhere within an
input file. They may be placed inside or outside a @code{\score}
block, and inside or outside the single music expression within a
@code{\score} block.
@example
\score @{
- @var{..music..}
+ @var{@dots{}music@dots{}}
@}
@end example
@example
\markup @{
- @var{..text..}
+ @var{@dots{}text@dots{}}
@}
@end example
@example
\score @{
- @var{..}
+ @var{@dots{}}
@}
\markup @{
- @var{..}
+ @var{@dots{}}
@}
\score @{
- @var{..}
+ @var{@dots{}}
@}
@end example
\header @{ piece = "Romanze" @}
@}
\markup @{
- ..text of second verse..
+ @dots{}text of second verse@dots{}
@}
\markup @{
- ..text of third verse..
+ @dots{}text of third verse@dots{}
@}
\score @{
@dots{}
@example
\book @{
\score @{ @dots{} @}
- \layout @{ @dots{} @}
+ \paper @{ @dots{} @}
@}
\book @{
\score @{ @dots{} @}
- \layout @{ @dots{} @}
+ \paper @{ @dots{} @}
@}
\book @{
\score @{ @dots{} @}
- \layout @{ @dots{} @}
+ \paper @{ @dots{} @}
@}
@end example
are used by the various back-ends when producing output files.
In the previous section, we saw how Lilypond prevents name-clashes when
-producing several ouputs from a single source file. You also have the
+producing several outputs from a single source file. You also have the
ability to specify your own suffixes for each @code{\book} block, so
for example you can produce files called
@file{eightminiatures-Romanze.pdf}, @file{eightminiatures-Menuetto.pdf}
\book @{
\bookOutputSuffix "Romanze"
\score @{ @dots{} @}
- \layout @{ @dots{} @}
+ \paper @{ @dots{} @}
@}
\book @{
\bookOutputSuffix "Menuetto"
\score @{ @dots{} @}
- \layout @{ @dots{} @}
+ \paper @{ @dots{} @}
@}
\book @{
\bookOutputSuffix "Nocturne"
\score @{ @dots{} @}
- \layout @{ @dots{} @}
+ \paper @{ @dots{} @}
@}
@end example
\book @{
\bookOutputName "Romanze"
\score @{ @dots{} @}
- \layout @{ @dots{} @}
+ \paper @{ @dots{} @}
@}
\book @{
\bookOutputName "Menuetto"
\score @{ @dots{} @}
- \layout @{ @dots{} @}
+ \paper @{ @dots{} @}
@}
\book @{
\bookOutputName "Nocturne"
\score @{ @dots{} @}
- \layout @{ @dots{} @}
+ \paper @{ @dots{} @}
@}
@end example
is entered at the top level the definitions are combined, but in
conflicting situations the later definitions take precedence. For
details of how this affects the @code{\layout} block see
-@ref{The \layout block}.
+@ref{The layout block,,The @code{@bs{}layout} block}.
@item
A direct scheme expression, such as
@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.
+A @code{\header} block. This sets the global (i.e. the top of
+file) header block. This is the block containing the default
+settings of titling fields like composer, title, etc. for all
+books within the file (see @ref{Titles explained}).
@item
A @code{\score} block. This score will be collected with other
A single-line comment, introduced by a leading @code{%} sign.
@item
-A multi-line comment delimited by @code{%@{ .. %@}}.
+A multi-line comment delimited by @code{%@{ @dots{} %@}}.
@end itemize
circumstances to avoid errors:
@itemize
+
@item Around every opening and closing curly bracket.
+
@item After every command or variable, i.e. every item that
begins with a @code{\} sign.
+
@item After every item that is to be interpreted as a Scheme
expression, i.e. every item that begins with a @code{#}@tie{}sign.
+
@item To separate all elements of a Scheme expression.
-@item In @code{lyricmode} to separate all the terms in both
-@code{\override} and @code{\set} commands. In particular, spaces
-must be used around the dot and the equals sign in commands like
-@code{\override Score . LyricText #'font-size = #5} and before and
-after the entire command.
+
+@item In @code{lyricmode} before and after @code{\set} and
+@code{\override} commands.
@end itemize
@rlearning{How LilyPond input files work}.
Notation Reference:
-@ref{The \layout block}.
+@ref{Titles explained},
+@ref{The layout block,,The @code{@bs{}layout} block}.
@node Titles and headers
@section Titles and headers
+@cindex titles
+@cindex headers
+@cindex footers
+
Almost all printed music includes a title and the composer's name;
some pieces include a lot more information.
@menu
* Creating titles headers and footers::
-* Custom headers footers and titles::
+* Custom titles headers and footers::
+* Creating PDF metadata::
* Creating footnotes::
* Reference to page numbers::
* Table of contents::
@subsection Creating titles headers and footers
@menu
-* Title blocks explained::
-* Default layout of book and score title blocks::
+* Titles explained::
+* Default layout of bookpart and score titles::
* Default layout of headers and footers::
@end menu
-@node Title blocks explained
-@unnumberedsubsubsec Title blocks explained
+@node Titles explained
+@unnumberedsubsubsec Titles explained
+
+Each @code{\book} block in a single input file produces a separate
+output file, see @ref{File structure}. Within each output file
+three types of titling areas are provided: @emph{Book Titles} at the
+beginning of each book, @emph{Bookpart Titles} at the beginning of
+each bookpart and @emph{Score Titles} at the beginning of each score.
+
+Values of titling fields such as @code{title} and @code{composer}
+are set in @code{\header} blocks. (For the syntax of @code{\header}
+blocks and a complete list of the fields available by default see
+@ref{Default layout of bookpart and score titles}). Book Titles,
+Bookpart Titles and Score Titles can all contain the same fields,
+although by default the fields in Score Titles are limited to
+@code{piece} and @code{opus}.
+
+@code{\header} blocks may be placed in four different places to form
+a descending hierarchy of @code{\header} blocks:
+
+@itemize
+
+@item
+At the top of the input file, before all @code{\book},
+@code{\bookpart}, and @code{\score} blocks.
+
+@item
+Within a @code{\book} block but outside all the @code{\bookpart} and
+@code{\score} blocks within that book.
+
+@item
+Within a @code{\bookpart} block but outside all @code{\score} blocks
+within that bookpart.
+
+@item
+After the music expression in a @code{\score} block.
+
+@end itemize
+
+The values of the fields filter down this hierarchy, with the values
+set higher in the hierarchy persisting unless they are over-ridden
+by a value set lower in the hierarchy, so:
+
+@itemize
+
+@item
+A Book Title is derived from fields set at the top of the input file,
+modified by fields set in the @code{\book} block. The resulting
+fields are used to print the Book Title for that book, providing that
+there is other material which generates a page at the start of the
+book, before the first bookpart. A single @code{\pageBreak} will
+suffice.
-@c TODO: figure out how \bookpart titles work
+@item
+A Bookpart Title is derived from fields set at the top of the input
+file, modified by fields set in the @code{\book} block, and further
+modified by fields set in the @code{\bookpart} block. The resulting
+values are used to print the Bookpart Title for that bookpart.
-There are two types of title blocks: the main title block that appears
-above of the first @code{\score} of a book, and individual title
-blocks that appear within each @code{\score} block. Text fields for
-both types are entered using a @code{\header} block.
+@item
+A Score Title is derived from fields set at the top of the input
+file, modified by fields set in the @code{\book} block, further
+modified by fields set in the @code{\bookpart} block and finally
+modified by fields set in the @code{\score} block. The resulting
+values are used to print the Score Title for that score. Note,
+though, that only @code{piece} and @code{opus} fields are printed
+by default in Score Titles unless the @code{\paper} variable,
+@code{print-all-headers}, is set to @code{#t}.
-If the book only has a single score, the @code{\header} block may be
-placed inside or outside of the @code{\score} block.
+@end itemize
-@warning{Remember when adding a @bs{}@code{header} block inside a
+@warning{Remember when placing a @bs{}@code{header} block inside a
@bs{}@code{score} block, that the music expression must come before the
@bs{}@code{header} block.}
+It is not necessary to provide @code{\header} blocks in all four
+places: any or even all of them may be omitted. Similarly, simple
+input files may omit the @code{\book} and @code{\bookpart} blocks,
+leaving them to be created implicitly.
+
+If the book has only a single score, the @code{\header} block should
+normally be placed at the top of the file so that just a Bookpart
+Title is produced, making all the titling fields available for use.
+
+If the book has multiple scores a number of different arrangements
+of @code{\header} blocks are possible, corresponding to the various
+types of musical publications. For example, if the publication
+contains several pieces by the same composer a @code{\header} block
+placed at the top of the file specifying the book title and the
+composer with @code{\header} blocks in each @code{\score} block
+specifying the @code{piece} and/or @code{opus} would be most
+suitable, as here:
+
@lilypond[papersize=a5,quote,verbatim,noragged-right]
\header {
title = "SUITE I."
}
\score {
- \new Staff \relative g, {
+ \new Staff \relative {
\clef bass
\key g \major
- \repeat unfold 2 { g16( d' b') a b d, b' d, } |
+ \repeat unfold 2 { g,16( d' b') a b d, b' d, } |
\repeat unfold 2 { g,16( e' c') b c e, c' e, } |
}
\header {
}
\score {
- \new Staff \relative b {
+ \new Staff \relative {
\clef bass
\key g \major
\partial 16 b16 |
}
@end lilypond
-Text fields from the main title block of a book can be displayed in all
-@code{\score} blocks, or manually suppressed:
+More complicated arrangements are possible. For example, text
+fields from the @code{\header} block in a book can be displayed in
+all Score Titles, with some fields over-ridden and some manually
+suppressed:
@lilypond[papersize=a5,quote,verbatim,noragged-right]
\book {
\header {
title = "DAS WOHLTEMPERIRTE CLAVIER"
subtitle = "TEIL I"
- % Do not display the tagline for this book
+ % Do not display the default LilyPond footer for this book
tagline = ##f
}
\markup { \vspace #1 }
@seealso
Notation Reference:
@ref{File structure},
-@ref{Custom layout for title blocks}.
+@ref{Default layout of bookpart and score titles},
+@ref{Custom layout for titles}.
-@node Default layout of book and score title blocks
-@unnumberedsubsubsec Default layout of book and score title blocks
+@node Default layout of bookpart and score titles
+@unnumberedsubsubsec Default layout of bookpart and score titles
-This example demonstrates all @code{\header} variables:
+This example demonstrates all printed @code{\header} variables:
-@lilypond[papersize=a7,quote,verbatim,noragged-right]
+@lilypond[papersize=a6landscape,quote,verbatim,noragged-right]
\book {
\header {
% The following fields are centered
meter = "Meter"
arranger = "Arranger"
% The following fields are centered at the bottom
- tagline = "tagline goes at the bottom of the last page"
- copyright = "copyright goes at the bottom of the first page"
+ tagline = "The tagline goes at the bottom of the last page"
+ copyright = "The copyright goes at the bottom of the first page"
}
\score {
{ s1 }
@end itemize
-To change the default layout see @ref{Custom layout for title blocks}.
+To change the default layout see @ref{Custom layout for titles}.
@cindex breakbefore
+If a @code{\book} block starts immediately with a @code{\bookpart}
+block, no Book Title will be printed, as there is no page on which
+to print it. If a Book Title is required, begin the @code{\book}
+block with some markup material or a @code{\pageBreak} command.
+
Use the @code{breakbefore} variable inside a @code{\header} block
-that is itself in a @code{\score} block, to make the top-level
+that is itself in a @code{\score} block, to make the higher-level
@code{\header} block titles appear on the first page on their own, with
the music (defined in the @code{\score} block) starting on the next.
-@lilypond[papersize=a8landscape,verbatim,noragged-right]
+@lilypond[papersize=c7landscape,verbatim,noragged-right]
\book {
\header {
title = "This is my Title"
@rlearning{How LilyPond input files work},
Notation Reference:
-@ref{Custom layout for title blocks},
+@ref{Custom layout for titles},
@ref{File structure}.
Installed Files:
@end itemize
-@lilypond[papersize=a8landscape]
-\book {
- \score {
- \relative c' {
- c4 d e f
- }
- }
-}
-@end lilypond
-
-The default tagline can be changed by adding a @code{tagline} in the
-top-level @code{\header} block.
+The default LilyPond footer text can be changed by adding a
+@code{tagline} in the top-level @code{\header} block.
@lilypond[papersize=a8landscape,verbatim]
\book {
tagline = "... music notation for Everyone"
}
\score {
- \relative c' {
- c4 d e f
+ \relative {
+ c'4 d e f
}
}
}
@end lilypond
-To remove the @code{tagline} set the value to @code{##f}.
+To remove the default LilyPond footer text, the @code{tagline} can be
+set to @code{##f}.
-@node Custom headers footers and titles
-@subsection Custom headers footers and titles
+@node Custom titles headers and footers
+@subsection Custom titles headers and footers
@c TODO: somewhere put a link to header spacing info
@c (you'll have to explain it more in NR 4).
@menu
-* Custom text formatting for title blocks::
-* Custom layout for title blocks::
+* Custom text formatting for titles::
+* Custom layout for titles::
* Custom layout for headers and footers::
@end menu
-@node Custom text formatting for title blocks
-@unnumberedsubsubsec Custom text formatting for title blocks
+@node Custom text formatting for titles
+@unnumberedsubsubsec Custom text formatting for titles
Standard @code{\markup} commands can be used to customize any header,
footer and title text within the @code{\header} block.
{ s1 }
\header {
piece = \markup { \fontsize #4 \bold "PRAELUDIUM I" }
- subtitle = \markup { \italic "(Excerpt)" }
+ opus = \markup { \italic "BWV 846" }
}
}
@end lilypond
@ref{Formatting text}.
-@node Custom layout for title blocks
-@unnumberedsubsubsec Custom layout for title blocks
+@node Custom layout for titles
+@unnumberedsubsubsec Custom layout for titles
@cindex bookTitleMarkup
@cindex scoreTitleMarkup
The placement of titles when using the default values of these
@code{\markup} variables is shown in the examples in
-@ref{Default layout of book and score title blocks}.
+@ref{Default layout of bookpart and score titles}.
The default settings for @code{scoreTitleMarkup} as defined in
@file{ly/titling-init.ly} are:
@example
scoreTitleMarkup = \markup @{ \column @{
- \on-the-fly #print-all-headers @{ \bookTitleMarkup \hspace #1 @}
+ \on-the-fly \print-all-headers @{ \bookTitleMarkup \hspace #1 @}
\fill-line @{
\fromproperty #'header:piece
\fromproperty #'header:opus
}
@end lilypond
-Text fields normally reserved for the main title block can be included
-in individual score title blocks with the @code{print-all-headers}
+Text fields not normally effective in score @code{\header} blocks
+can be printed in the Score Title area if @code{print-all-headers} is
placed inside the @code{\paper} block. A disadvantage of using this
-method is that the text fields that are intended specifically for the
-top-level @code{\header} block need to be manually suppressed in every
-@code{\score} block. See @ref{Title blocks explained}.
+method is that text fields that are intended specifically for the
+Bookpart Title area need to be manually suppressed in every
+@code{\score} block. See @ref{Titles explained}.
To avoid this, add the desired text field to the @code{scoreTitleMarkup}
definition. In the following example, the @code{composer} text field
@seealso
Notation Reference:
-@ref{Title blocks explained}.
+@ref{Titles explained}.
@node Custom layout for headers and footers
@example
@code{variable} = @code{\markup} @{
- ...
- @code{\on-the-fly} #@var{procedure} @var{markup}
- ...
+ @dots{}
+ @code{\on-the-fly} \@var{procedure} @var{markup}
+ @dots{}
@}
@end example
@headitem Procedure name @tab Condition tested
@item print-page-number-check-first @tab should this page number be printed?
-@item create-page-number-stencil @tab 'print-page-numbers true?
-@item print-all-headers @tab 'print-all-headers true?
+@item create-page-number-stencil @tab print-page-numbers true?
+@item print-all-headers @tab print-all-headers true?
@item first-page @tab first page in the book?
@item (on-page nmbr) @tab page number = nmbr?
@item last-page @tab last page in the book?
evenHeaderMarkup = \markup \null
oddFooterMarkup = \markup {
\fill-line {
- \on-the-fly #print-page-number-check-first
+ \on-the-fly \print-page-number-check-first
\fromproperty #'page:page-number-string
}
}
@q{and} operation, for example,
@example
- @code{\on-the-fly #first-page}
- @code{\on-the-fly #last-page}
- @code{@{ \markup ... \fromproperty #'header: ... @}}
+ @code{\on-the-fly \first-page}
+ @code{\on-the-fly \last-page}
+ @code{@{ \markup @dots{} \fromproperty #'header: @dots{} @}}
@end example
determines if the output is a single page.
@seealso
Notation Reference:
-@ref{Title blocks explained},
-@ref{Default layout of book and score title blocks}.
+@ref{Titles explained},
+@ref{Default layout of bookpart and score titles}.
Installed Files:
@file{../ly/titling-init.ly}.
+@node Creating PDF metadata
+@subsection Creating PDF metadata
+
+@cindex PDF metadata
+
+In addition to being shown in the printed output, @code{\header} variables
+are also used to set PDF metadata (the information displayed by PDF readers
+as the @code{properties} of the PDF file). For example, setting the
+@code{title} property of the @code{header} block @q{Symphony I} will also give
+this title to the PDF document.
+
+@example
+ @code{\header@{}
+ @code{title = "Symphony I"}
+ @code{@}}
+@end example
+
+If you want to set the title of the printed output to one value, but have the
+title property of the PDF to have a different value, you can use
+@code{pdftitle}, as below.
+
+@example
+ @code{\header@{}
+ @code{title = "Symphony I"}
+ @code{pdftitle = "Symphony I by Beethoven"}
+ @code{@}}
+@end example
+
+The variables @code{title}, @code{subject}, @code{keywords},
+@code{subtitle}, @code{composer}, @code{arranger}, @code{poet}, @code{author}
+and @code{copyright} all set PDF properties and can all be prefixed with
+@q{pdf} to set a PDF property to a value different from the printed output.
+
+The PDF property @code{Creator} is automatically set to @q{LilyPond} plus
+the current LilyPond version, and @code{CreationDate} and @code{ModDate} are
+both set to the current date and time. @code{ModDate} can be overridden by
+setting the header variable @code{moddate} (or @code{pdfmoddate}) to a
+valid PDF date string.
@node Creating footnotes
@subsection Creating footnotes
-There are two types of footnotes that can be created; automatic
-footnotes and manual footnotes.
+@cindex footnotes
+
+Footnotes may be used in many different situations. In all cases,
+a @q{footnote mark} is placed as a reference in text or music, and
+the corresponding @q{footnote text} appears at the bottom of the
+same page.
+
+Footnotes within music expressions and footnotes in stand-alone text
+outside music expressions are created in different ways.
@menu
-* Footnotes overview::
-* Automatic footnotes::
-* Manual footnotes::
+* Footnotes in music expressions::
+* Footnotes in stand-alone text::
@end menu
-@node Footnotes overview
-@unnumberedsubsubsec Footnotes overview
+@node Footnotes in music expressions
+@unnumberedsubsubsec Footnotes in music expressions
-Automatic footnotes create incrementing numerical indicators and manual
-footnotes allow a custom indicator to be created instead. Footnotes are
-normally applied like @code{\tweak} and consequently can be placed
-directly on grobs (graphical objects) created by most music elements and
-post-events. In cases where this does not work (like with bar lines and
-meter changes, where the grobs are produced as a consequence of property
-changes), footnotes can also be specified as a standalone music event
-affecting all grobs of a given type at a particular time step.
+@cindex footnotes in music expressions
+@funindex \footnote
-The full form of a footnote command is
+@subsubsubheading Music footnotes overview
+
+Footnotes in music expressions fall into two categories:
+
+@table @emph
+@item Event-based footnotes
+are attached to a particular event. Examples for such events are
+single notes, articulations (like fingering indications, accents,
+dynamics), and post-events (like slurs and manual beams). The
+general form for event-based footnotes is as follows:
+
+@example
+[@var{direction}] \footnote [@var{mark}] @var{offset} @var{footnote} @var{music}
+@end example
+
+@item Time-based footnotes
+are bound to a particular point of time in a musical context. Some
+commands like @code{\time} and @code{\clef} don't actually use events
+for creating objects like time signatures and clefs. Neither does a
+chord create an event of its own: its stem or flag is created at the
+end of a time step (nominally through one of the note events inside).
+Exactly which of a chord's multiple note events will be deemed the
+root cause of a stem or flag is undefined. So for annotating those,
+time-based footnotes are preferable as well.
+
+A time-based footnote allows such layout objects to be annotated
+without referring to an event. The general form for Time-based
+footnotes is:
@example
-\footnote @var{mark} @var{offset} @var{grob-name} @var{footnote}
-@var{music}
+\footnote [@var{mark}] @var{offset} @var{footnote} [@var{Context}].@var{GrobName}
@end example
-The elements are as follows:
+@end table
+
+The elements for both forms are:
@table @var
+
+@item direction
+If (and only if) the @code{\footnote} is being applied to a
+post-event or articulation, it must be preceded with a direction
+indicator (@code{-, _, ^}) in order to attach @var{music} (with
+a footnote mark) to the preceding note or rest.
+
@item mark
is a markup or string specifying the footnote mark which is used for
-both marking the reference point as well as the footnote itself at the
-bottom of the page. It can be omitted (or equivalently replaced with
-@code{\default}) in which case a number in sequence will be generated.
+marking both the reference point and the footnote itself at the
+bottom of the page. It may be omitted (or equivalently replaced with
+@code{\default}) in which case a number in sequence will be generated
+automatically. Such numerical sequences restart on each page
+containing a footnote.
+
@item offset
-is a number pair such as @samp{#(2 . 1)} specifying the X and Y offset
-from the reference point where the mark will be placed.
-@item grob-name
-specifies a type of grob to mark (like @samp{#'Flag}). If it is given,
-the respective grob will be used as a reference point even in case that
-its @q{cause} is not the referenced @var{music} itself but a grob
-created from it. It can be omitted (or replaced with @code{\default}),
-and then only a directly created grob will be annotated.
+is a number pair such as @samp{#(2 . 1)} specifying the X and
+Y@tie{}offsets in units of staff-spaces from the boundary of the
+object where the mark should be placed. Positive values of the
+offsets are taken from the right/top edge, negative values from the
+left/bottom edge and zero implies the mark is centered on the edge.
+
+@item Context
+is the context in which the grob being footnoted is created. It
+may be omitted if the grob is in a bottom context, e.g. a
+@code{Voice} context.
+
+@item GrobName
+specifies a type of grob to mark (like @samp{Flag}). If it is
+specified, the footnote is not attached to a music expression in
+particular, but rather to all grobs of the type specified which
+occur at that moment of musical time.
+
@item footnote
-This markup or string specifies the footnote text to use at the bottom
-of the page.
+is the markup or string specifying the footnote text to use at the
+bottom of the page.
+
@item music
-This is the item, a music event or chord constituent or post-event, that
-is being annotated. While it cannot be omitted, it @emph{can} be
-replaced by @code{\default} in which case the footnote is not attached
-to a music expression in particular, but rather to a moment of time. It
-is mandatory in this case to use the @var{grob-name} argument for
-selecting an affected grob type, like @samp{#'TimeSignature}.
+is the music event or post-event or articulation
+that is being annotated.
+
@end table
-Like with @code{\tweak}, if your @code{\footnote} is applied to a
-post-event or articulation, it will itself have to be preceded with
-@code{-} to make the parser attach the result to the preceding note or
-rest.
+@subsubsubheading Event-based footnotes
-@node Automatic footnotes
-@unnumberedsubsubsec Automatic footnotes
+@cindex footnotes, event-based
-Automatic footnotes take four arguments: the @samp{(x . y)} position of
-the indicator, the optional @var{grob-name} specifying the layout object
-to be annotated, the @var{footnote} markup itself that will appear at
-the bottom of the page, and of course the @var{music} to attach the
-footnote to.
+A footnote may be attached to a layout object directly caused
+by the event corresponding to @var{music} with the syntax:
-@lilypond[verbatim,quote,ragged-right,papersize=a8]
+@example
+\footnote [@var{mark}] @var{offset} @var{footnote} @var{music}
+@end example
+
+@lilypond[quote,verbatim,papersize=a8landscape]
\book {
\header { tagline = ##f }
- \relative c' {
- \footnote #'(0.5 . -2)
- \markup { The first note }
- a'4 b8
- \footnote #'(0.5 . 1) #'Flag
- \markup { The third note }
- e\noBeam c4 d4
+ \relative c'' {
+ \footnote #'(-1 . 3) "A note" a4
+ a4
+ \footnote #'(2 . 2) "A rest" r4
+ a4
}
}
@end lilypond
-Chorded notes pose no particular difficulty:
+Marking a @emph{whole} chord with an event-based footnote is not
+possible: a chord, even one containing just a single note, does
+not produce an actual event of its own. However, individual
+notes @emph{inside} of the chord can be marked:
-@lilypond[verbatim,quote,ragged-right,papersize=a8]
+@lilypond[quote,verbatim,papersize=a8landscape]
\book {
\header { tagline = ##f }
- \relative c' {
- <
- \footnote #'(1 . -1.25) "Here is a C" c
- \footnote #'(2 . -0.25) \markup { \italic "An E-flat" } es
- \footnote #'(2 . 3) \markup { \bold "This is a G" } g
- >1
+ \relative c'' {
+ \footnote #'(2 . 3) "Does not work" <a-3>2
+ <\footnote #'(-2 . -3) "Does work" a-3>4
+ <a-3 \footnote #'(3 . 1/2) "Also works" c-5>4
}
}
@end lilypond
-@warning {When footnotes have the same vertical position, the footnotes
-are printed in order of descendancy; the higher the footnote, the
-higher up in the list.}
+If the footnote is to be attached to a post-event or articulation
+the @code{\footnote} command @emph{must} be preceded by a direction
+indicator, @code{-, _, ^}, and followed by the post-event or
+articulation to be annotated as the @var{music} argument. In this
+form the @code{\footnote} can be considered to be simply a copy of
+its last argument with a footnote mark attached to it. The syntax
+is:
-Here are some more examples of footnoted grobs, also showing the
-relative position of the footnotes to the tagline and copyright.
+@example
+@var{direction} \footnote [@var{mark}] @var{offset} @var{footnote} @var{music}
+@end example
-@lilypond[verbatim,quote,ragged-right,papersize=a8]
+@lilypond[quote,verbatim,papersize=a8landscape]
\book {
- \header { copyright = \markup { "Copyright 1970" } }
- \relative c' {
- a'4-\footnote #'(-3 . 0) \markup { \bold Forte } \f
- -\footnote #'(0 . 1.5) \markup { A slur } (
- b8)-\footnote #'(0 . -2) \markup { Beam } [ e]
- \footnote #'(1 . -1) #'Stem
- \markup { \teeny { This is a stem } }
- c4
- \footnote #'(0 . 0.5) #'AccidentalCautionary
- \markup \italic { A cautionary accidental }
- \footnote #'(1 . 1) "The note itself"
- dis?4-\footnote #'(0.5 . -0.5) \markup \italic { Slow Down }
- _"rit."
+ \header { tagline = ##f }
+ \relative {
+ a'4_\footnote #'(0 . -1) "A slur forced down" (
+ b8^\footnote #'(1 . 0.5) "A manual beam forced up" [
+ b8 ]
+ c4 )
+ c-\footnote #'(1 . 1) "Tenuto" --
}
}
@end lilypond
-For top-level @code{\markup}, the @code{\auto-footnote} command is
-required:
+@subsubsubheading Time-based footnotes
-@lilypond[verbatim,quote,ragged-right,papersize=a8]
+@cindex footnotes, time-based
+
+If the layout object being footmarked is @emph{indirectly} caused by
+an event (like an @code{Accidental} or @code{Stem} caused by a
+@code{NoteHead} event), the @var{GrobName} of the layout object
+is required after the footnote text instead of @var{music}:
+
+@lilypond[quote,verbatim,papersize=a8landscape]
\book {
\header { tagline = ##f }
- \markup { \auto-footnote "A simple tune" \italic "By me" }
- \relative c' {
- a'4 b8 e c4 d
+ \relative c'' {
+ \footnote #'(-1 . -3) "A flat" Accidental
+ aes4 c
+ \footnote #'(-1 . 0.5) "Another flat" Accidental
+ ees
+ \footnote #'(1 . -2) "A stem" Stem
+ aes
}
}
@end lilypond
+Note, however, that when a GrobName is specified, a footnote
+will be attached to all grobs of that type at the current time step:
-@node Manual footnotes
-@unnumberedsubsubsec Manual footnotes
+@lilypond[quote,verbatim,papersize=a8landscape]
+\book {
+ \header { tagline = ##f }
+ \relative c' {
+ \footnote #'(-1 . 3) "A flat" Accidental
+ <ees ges bes>4
+ \footnote #'(2 . 0.5) "Articulation" Script
+ c'->-.
+ }
+}
+@end lilypond
-@cindex footnotes, manual
+A note inside of a chord can be given an individual (event-based)
+footnote. A @samp{NoteHead} is the only grob directly caused
+from a chord note, so an event-based footnote command is
+@emph{only} suitable for adding a footnote to the @samp{NoteHead}
+within a chord. All other chord note grobs are indirectly caused.
+The @code{\footnote} command itself offers no syntax for
+specifying @emph{both} a particular grob type @emph{as well as} a
+particular event to attach to. However, one can use a time-based
+@code{\footnote} command for specifying the grob type, and then
+prefix this command with @code{\single} in order to have it
+applied to just the following event:
+
+@lilypond[quote,verbatim,papersize=a8landscape]
+\book {
+ \header { tagline = ##f }
+ \relative c'' {
+ < \footnote #'(1 . -2) "An A" a
+ \single \footnote #'(-1 . -1) "A sharp" Accidental
+ cis
+ \single \footnote #'(0.5 . 0.5) "A flat" Accidental
+ ees fis
+ >2
+ }
+}
+@end lilypond
-Manually marked footnotes take an additional first markup argument
-@var{mark} for making the reference mark. In contrast to automatically
-generated footnote marks, they will not appear before the @var{footnote}
-markup at the bottom of the page: establishing the visual connection is
-left to the user. LilyPond will only make sure that the corresponding
-markup appears on the bottom of the same page.
+@warning {When footnotes are attached to several musical elements at
+the same musical moment, as they are in the example above, the
+footnotes are numbered from the higher to the lower elements as they
+appear in the printed output, not in the order in which they are
+written in the input stream.}
+
+Layout objects like clefs and key-change signatures are mostly caused
+as a consequence of changed properties rather than actual events.
+Others, like bar lines and bar numbers, are a direct consequence of
+timing. For this reason, footnotes on such objects have to be based
+on their musical timing. Time-based footnotes are also preferable
+when marking features like stems and beams on @emph{chords}: while
+such per-chord features are nominally assigned to @emph{one} event
+inside the chord, relying on a particular choice would be imprudent.
+
+The layout object in question must always be explicitly specified
+for time-based footnotes, and the appropriate context must be
+specified if the grob is created in a context other than the bottom
+context.
+
+@lilypond[quote,verbatim,papersize=a8landscape]
+\book {
+ \header { tagline = ##f }
+ \relative c'' {
+ r1 |
+ \footnote #'(-0.5 . -1) "Meter change" Staff.TimeSignature
+ \time 3/4
+ \footnote #'(1 . -1) "Chord stem" Stem
+ <c e g>4 q q
+ \footnote #'(-0.5 . 1) "Bar line" Staff.BarLine
+ q q
+ \footnote #'(0.5 . -1) "Key change" Staff.KeySignature
+ \key c \minor
+ q
+ }
+}
+@end lilypond
-Other than that, the use is identical to that of automatically numbered
-footnotes.
+Custom marks can be used as alternatives to numerical marks, and the
+annotation line joining the marked object to the mark can be
+suppressed:
-@lilypond[verbatim,quote,ragged-right,papersize=a8]
+@lilypond[quote,verbatim,papersize=a8landscape]
\book {
\header { tagline = ##f }
\relative c' {
- \footnote
- "1" #'(0.5 . -2)
- \markup { \italic "1. The first note" }
- a'4
+ \footnote "*" #'(0.5 . -2) \markup { \italic "* The first note" } a'4
b8
- \footnote
- \markup { \bold "2" } #'(0.5 . 1)
- "2. The second note"
- e
+ \footnote \markup { \super "$" } #'(0.5 . 1)
+ \markup { \super "$" \italic " The second note" } e
c4
- d-\footnote "3" #'(0.5 . -1) "3. Piano" \p
+ \once \override Score.FootnoteItem.annotation-line = ##f
+ b-\footnote \markup \tiny "+" #'(0.1 . 0.1)
+ \markup { \super "+" \italic " Editorial" } \p
}
}
@end lilypond
-To annotate chorded notes with manual footnotes:
+More examples of custom marks are shown in
+@ref{Footnotes in stand-alone text}.
+
+
+@node Footnotes in stand-alone text
+@unnumberedsubsubsec Footnotes in stand-alone text
+
+@cindex footnotes in stand-alone text
+
+These are for use in markup outside of music expressions. They do
+not have a line drawn to their point of reference: their marks simply
+follow the referenced markup. Marks can be inserted automatically,
+in which case they are numerical. Alternatively, custom marks can be
+provided manually.
+
+Footnotes to stand-alone text with automatic and custom marks are
+created in different ways.
+
+@subsubsubheading Footnotes in stand-alone text with automatic marks
+
+The syntax of a footnote in stand-alone text with automatic marks is
+
+@example
+\markup @{ @dots{} \auto-footnote @var{text} @var{footnote} @dots{} @}
+@end example
+
+The elements are:
+
+@table @var
+
+@item text
+is the markup or string to be marked.
+
+@item footnote
+is the markup or string specifying the footnote text to use at the bottom
+of the page.
+
+@end table
+
+For example:
@lilypond[verbatim,quote,ragged-right,papersize=a8]
\book {
\header { tagline = ##f }
- \relative c' {
- <
- \footnote "1" #'(1 . -1.25) "1. C" c
- \footnote
- \markup { \bold "b" } #'(2 . -0.25) "b. E-flat" es
- \footnote "3" #'(2 . 3) \markup { \italic "iii. G" } g
- >1
+ \markup {
+ "A simple"
+ \auto-footnote "tune" \italic " By me"
+ "is shown below. It is a"
+ \auto-footnote "recent" \italic " Aug 2012"
+ "composition."
+ }
+ \relative {
+ a'4 b8 e c4 d
}
}
@end lilypond
-@warning {When footnotes have the same vertical position, the footnotes
-are printed in order of descendancy; the higher the footnote, the
-higher up in the list.}
+@subsubsubheading Footnotes in stand-alone text with custom marks
+
+The syntax of a footnote in stand-alone text with custom marks is
+
+@example
+\markup @{ @dots{} \footnote @var{mark} @var{footnote} @dots{} @}
+@end example
+
+The elements are:
+
+@table @var
+
+@item mark
+is a markup or string specifying the footnote mark which is used for
+marking the reference point. Note that this mark is @emph{not}
+inserted automatically before the footnote itself.
+
+@item footnote
+is the markup or string specifying the footnote text to use at the
+bottom of the page, preceded by the @var{mark}.
+
+@end table
-Here are some examples of manually footnoted grobs, also showing
-the relative position of the footnotes to the tagline and copyright
+Any easy-to-type character such as * or + may be used as a mark, as
+shown in @ref{Footnotes in music expressions}. Alteratively, ASCII
+aliases may be used (see @ref{ASCII aliases}):
@lilypond[verbatim,quote,ragged-right,papersize=a8]
\book {
+ \paper { #(include-special-characters) }
\header { tagline = ##f }
- \relative c' {
- a'4-\footnote
- \markup { \teeny 1 } #'(-3 . 0)
- \markup { 1. \bold Forte } \f
- -\footnote
- \markup { \teeny b } #'(0 . 1.5)
- \markup { b. A slur } (
- b8)-\footnote
- \markup { \teeny 3 } #'(0 . -2)
- \markup { 3. Beam } [
- e]
- \footnote
- \markup { 4 } #'(1 . -1) #'Stem
- \markup { \bold 4. { This is a stem } }
- c4
- \footnote
- \markup \concat \teeny { "sharp (v)" }
- #'(0 . 0.5) #'AccidentalCautionary
- \markup \italic { v. A cautionary accidental }
- dis?4-\footnote
- \markup \concat \teeny { "a" } #'(0.5 . -0.5)
- \markup \italic { a. Slow Down } _"rit."
- \footnote
- \markup { \teeny \musicglyph #"rests.4" }
- #'(1.5 . -0.25)
- \markup { \null } \breathe
+ \markup {
+ "A simple tune"
+ \footnote "*" \italic "* By me"
+ "is shown below. It is a recent"
+ \footnote \super † \concat {
+ \super † \italic " Aug 2012"
+ }
+ "composition."
+ }
+ \relative {
+ a'4 b8 e c4 d
}
}
@end lilypond
-To manually footnote a top-level @code{\markup}:
+Unicode character codes may also be used to specify marks
+(see @ref{Unicode}):
@lilypond[verbatim,quote,ragged-right,papersize=a8]
\book {
\header { tagline = ##f }
- \markup { "A simple tune" \footnote "*" \italic "* By me" }
- \relative c' {
- a'4 b8 e c4 d4
+ \markup {
+ "A simple tune"
+ \footnote \super \char##x00a7 \concat {
+ \super \char##x00a7 \italic " By me"
+ }
+ "is shown below. It is a recent"
+ \footnote \super \char##x00b6 \concat {
+ \super \char##x00b6 \italic " Aug 2012"
+ }
+ "composition."
+ }
+ \relative {
+ a'4 b8 e c4 d
}
}
@end lilypond
@rlearning{Objects and interfaces}.
Notation Reference:
+@ref{ASCII aliases},
@ref{Balloon help},
-@ref{Page layout},
+@ref{List of special characters},
@ref{Text marks},
@ref{Text scripts},
-@ref{Titles and headers}.
+@ref{Unicode}.
Internals Reference:
@rinternals{FootnoteEvent},
@rinternals{Footnote_engraver}.
@knownissues
-Multiple footnotes for the same page can only be stacked, one on top of
-the other, and cannot be printed on the same line. Footnotes cannot be
-attached to @code{MultiMeasureRests} and may collide with @code{Staff},
-@code{\markup} objects and other @code{footnote} annotations. When
-using any manual @code{footnote} command a @code{\paper} block
-containing @code{footnote-auto-number = ##f} is required.
+Multiple footnotes for the same page can only be stacked, one above
+the other; they cannot be printed on the same line.
+
+Footnotes cannot be attached to @code{MultiMeasureRests} or
+automatic beams or lyrics.
+
+Footnote marks may collide with staves, @code{\markup} objects, other
+footnote marks and annotation lines.
@node Reference to page numbers
@node Table of contents
@subsection Table of contents
-A table of contents is included using the @code{\markuplist \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.
+A table of contents is included using the
+@code{\markuplist \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
\markuplist \table-of-contents
}
@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:
+Markups used for formatting the table of contents are defined in the
+@code{\paper} block. There are two @q{pre-defined} markups already
+available;
+
+@itemize
+
+@item
+@code{tocTitleMarkup}
+
+@noindent
+Used for formatting the title of the table of contents.
+
+@verbatim
+tocTitleMarkup = \markup \huge \column {
+ \fill-line { \null "Table of Contents" \null }
+ \null
+}
+@end verbatim
+
+@item
+@code{tocItemMarkup}
+
+@noindent
+Used for formatting the elements within the table of contents.
+
+@verbatim
+tocItemMarkup = \markup \fill-line {
+ \fromproperty #'toc:text \fromproperty #'toc:page
+}
+@end verbatim
+
+@end itemize
+
+@noindent
+Both of these variables can be changed.
+
+Here is an example changing the table of contents' title into French;
@verbatim
\paper {
- %% Translate the toc title into French:
tocTitleMarkup = \markup \huge \column {
\fill-line { \null "Table des matières" \null }
\hspace #1
}
- %% use larger font size
- tocItemMarkup = \markup \large \fill-line {
- \fromproperty #'toc:text \fromproperty #'toc:page
- }
+@end verbatim
+
+Here is an example changing the font-size of the elements in the table
+of contents;
+
+@verbatim
+tocItemMarkup = \markup \large \fill-line {
+ \fromproperty #'toc:text \fromproperty #'toc:page
}
@end verbatim
-Note how the toc element text and page number are referred to in
-the @code{tocItemMarkup} definition.
+Note how the element text and page numbers are referred 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
+The @code{\tocItemWithDotsMarkup} command can be included within the
+@code{tocItemMarkup} to fill the line, between a table of contents item
+and its corresponding page number, with dots;
+
+@lilypond[verbatim,line-width=10.0\cm]
+\header { tagline = ##f }
+\paper {
+ tocItemMarkup = \tocItemWithDotsMarkup
+}
+
+\book {
+ \markuplist \table-of-contents
+ \tocItem \markup { Allegro }
+ \tocItem \markup { Largo }
+ \markup \null
+}
+@end lilypond
+
+Custom commands with their own markups can also be defined to build a
+more complex table of contents. In the following example, a new style
+is defined for entering act names in a table of contents of an opera;
-In the following example, a new style is defined for entering act names
-in the table of contents of an opera:
+@noindent
+A new markup variable (called @code{tocActMarkup}) is defined in the
+@code{\paper} block;
@verbatim
\paper {
\hspace #1
}
}
+@end verbatim
+@noindent
+A custom music function (@code{tocAct}) is then created -- which uses
+the new @code{tocActMarkup} markup definition.
+
+@verbatim
tocAct =
-#(define-music-function (parser location text) (markup?)
- (add-toc-item! 'tocActMarkup text))
+ #(define-music-function (text) (markup?)
+ (add-toc-item! 'tocActMarkup text))
@end verbatim
+@noindent
+A LilyPond input file, using these customer definitions, could look
+something like this;
+
@lilypond[line-width=10.0\cm]
\header { tagline = ##f }
\paper {
}
tocAct =
-#(define-music-function (parser location text) (markup?)
+#(define-music-function (text) (markup?)
(add-toc-item! 'tocActMarkup text))
\book {
}
@end lilypond
-Dots can be added to fill the line between an item and its page number:
-@lilypond[verbatim,line-width=10.0\cm]
-\header { tagline = ##f }
-\paper {
- tocItemMarkup = \tocItemWithDotsMarkup
-}
+Here is an example of the @code{\fill-with-pattern} command used within
+the context of a table of contents;
-\book {
- \markuplist \table-of-contents
- \tocItem \markup { Allegro }
- \tocItem \markup { Largo }
- \markup \null
+@verbatim
+\paper {
+ tocItemMarkup = \markup { \fill-line {
+ \override #'(line-width . 70)
+ \fill-with-pattern #1.5 #CENTER . \fromproperty #'toc:text \fromproperty #'toc:page
+ }
+ }
}
-@end lilypond
+@end verbatim
@seealso
Installed Files:
@example
\include "parts/VI.ly"
\include "parts/VII.ly"
-... etc
+@dots{} etc
@end example
Files which are to be included can also contain @code{\include}
been brought into the main file, so the file names they specify
must all be relative to the directory containing the main file,
not the directory containing the included file. However,
-this behavior can be changed by passing the option
+this behavior can be changed globally by passing the option
@option{-drelative-includes} option at the command line
(or by adding @code{#(ly:set-option 'relative-includes #t)}
-at the top of the main input file). With @code{relative-includes}
-set, the path for each @code{\include} command will be taken
-relative to the file containing that command. This behavior is
-recommended and it will become the default behavior in a future
-version of lilypond.
+at the top of the main input file).
+
+When @code{relative-includes} is set to @code{#t}, the path for each
+@code{\include} command will be taken relative to the file containing
+that command. This behavior is recommended and it will become the
+default behavior in a future version of lilypond.
+
+Files relative to the main directory and files relative to some other
+directory may both be @code{\include}d by setting
+@code{relative-includes} to @code{#t} or @code{#f} at appropriate
+places in the files. For example, if a general library, libA, has
+been created which itself uses sub-files which are @code{\include}d
+by the entry file of that library, those @code{\include} statements
+will need to be preceded by
+@code{#(ly:set-option #relative-includes #t)} so they are interpreted
+correctly when brought into the main @code{.ly} file, like this:
+
+@example
+libA/
+ libA.ly
+ A1.ly
+ A2.ly
+ @dots{}
+@end example
+
+@noindent
+then the entry file, @code{libA.ly}, will contain
+
+@example
+#(ly:set-option 'relative-includes #t)
+\include "A1.ly"
+\include "A2.ly"
+@dots{}
+% return to default setting
+#(ly:set-option 'relative-includes #f)
+@end example
+
+Any @file{.ly} file can then include the entire library simply with
+
+@example
+\include "~/libA/libA.ly"
+@end example
+
+More complex file structures may be devised by switching at
+appropriate places.
Files can also be included from a directory in a search path
specified as an option when invoking LilyPond from the command
@example
\include "VI.ly"
\include "VII.ly"
-... etc
+@dots{} etc
@end example
Files which are to be included in many scores may be placed in
Here is an example:
@lilypond[verbatim,quote]
-sopranoMusic = \relative c'' { a4 b c b8( a) }
-altoMusic = \relative g' { e4 e e f }
-tenorMusic = \relative c' { c4 b e d8( c) }
-bassMusic = \relative c' { a4 gis a d, }
-allLyrics = \lyricmode {King of glo -- ry }
+sopranoMusic = \relative { a'4 b c b8( a) }
+altoMusic = \relative { e'4 e e f }
+tenorMusic = \relative { c'4 b e d8( c) }
+bassMusic = \relative { a4 gis a d, }
+allLyrics = \lyricmode { King of glo -- ry }
<<
\new Staff = "Soprano" \sopranoMusic
\new Lyrics \allLyrics
\new Lyrics \allLyrics
\new PianoStaff <<
\new Staff = "RH" {
- \set Staff.printPartCombineTexts = ##f
- \partcombine
- \sopranoMusic
- \altoMusic
+ \partcombine \sopranoMusic \altoMusic
}
\new Staff = "LH" {
- \set Staff.printPartCombineTexts = ##f
\clef "bass"
- \partcombine
- \tenorMusic
- \bassMusic
+ \partcombine \tenorMusic \bassMusic
}
>>
>>
@funindex \tag
@funindex \keepWithTag
@funindex \removeWithTag
-@funindex \pushToTag
-@funindex \appendToTag
@cindex tag
@cindex keep tagged music
@cindex remove tagged music
-@cindex splice into tagged music
The @code{\tag #'@var{partA}} command marks a music expression
with the name @var{partA}.
@headitem Filter
@tab Result
@item
-Tagged music preceded by @code{\keepWithTag #'@var{name}}
- @tab Untagged music and music tagged with @var{name} is included;
- music tagged with any other tag name is excluded.
+Tagged music preceded by @code{\keepWithTag #'@var{name}} or
+ @code{\keepWithTag #'(@var{name1} @var{name2}@dots{})}
+@tab Untagged music and music tagged with any of the given tag
+ names is included;
+ music tagged with any other tag name is excluded.
@item
-Tagged music preceded by @code{\removeWithTag #'@var{name}}
-@tab Untagged music and music tagged with any tag name other than
- @var{name} is included; music tagged with @var{name} is
+Tagged music preceded by @code{\removeWithTag #'@var{name}} or
+ @code{\removeWithTag #'(@var{name1} @var{name2}@dots{})}
+@tab Untagged music and music not tagged with any of the given tag names
+ is included; music tagged with any of the given tag names is
excluded.
@item
Tagged music not preceded by either @code{\keepWithTag} or
@end multitable
The arguments of the @code{\tag}, @code{\keepWithTag} and
-@code{\removeWithTag} commands should be a symbol
-(such as @code{#'score} or @code{#'part}), followed
-by a music expression.
+@code{\removeWithTag} commands should be a symbol or list of
+symbols (such as @code{#'score} or @code{#'(violinI violinII}),
+followed by a music expression. If @emph{and only if} the symbols
+are valid LilyPond identifiers (alphabetic characters only, no
+numbers, underscores, or dashes) which cannot be confused with notes,
+the @code{#'} may be omitted and, as a shorthand, a list of symbols
+can use the dot separator: i.e. @code{\tag #'(violinI violinII)} can
+be written @code{\tag violinI.violinII}. The same applies to
+@code{\keepWithTag} and @code{\removeWithTag}.
In the following example, we see two versions of a piece of music,
one showing trills with the usual notation, and one with trills
explicitly expanded:
@lilypond[verbatim,quote]
-music = \relative g' {
- g8. c32 d
+music = \relative {
+ g'8. c32 d
\tag #'trills { d8.\trill }
\tag #'expand { \repeat unfold 3 { e32 d } }
c32 d
Alternatively, it is sometimes easier to exclude sections of music:
@lilypond[verbatim,quote]
-music = \relative g' {
- g8. c32 d
+music = \relative {
+ g'8. c32 d
\tag #'trills { d8.\trill }
\tag #'expand {\repeat unfold 3 { e32 d } }
c32 d
@end example
Multiple tags may be placed on expressions with multiple
-@code{\tag} entries:
+@code{\tag} entries, or by combining multiple tags into one symbol
+list:
@lilypond[quote,verbatim]
music = \relative c'' {
\tag #'a \tag #'both { a4 a a a }
- \tag #'b \tag #'both { b4 b b b }
+ \tag #'(b both) { b4 b b b }
}
<<
\keepWithTag #'a \music
@end lilypond
Multiple @code{\removeWithTag} filters may be applied to a single
-music expression to remove several differently named tagged sections:
+music expression to remove several differently named tagged
+sections. Alternatively, you can use a single
+@code{\removeWithTag} with a list of tags.
@lilypond[verbatim,quote]
music = \relative c'' {
-\tag #'A { a4 a a a }
-\tag #'B { b4 b b b }
-\tag #'C { c4 c c c }
-\tag #'D { d4 d d d }
+ \tag #'A { a4 a a a }
+ \tag #'B { b4 b b b }
+ \tag #'C { c4 c c c }
+ \tag #'D { d4 d d d }
}
-{
-\removeWithTag #'B
-\removeWithTag #'C
-\music
+\new Voice {
+ \removeWithTag #'B
+ \removeWithTag #'C
+ \music
+ \removeWithTag #'(B C)
+ \music
}
@end lilypond
expression will cause @emph{all} tagged sections to be removed, as
the first filter will remove all tagged sections except the one
named, and the second filter will remove even that tagged section.
+Usually you would rather want to use a single @code{\keepWithTag}
+command with a list of multiple tags: this will only remove tagged
+sections not given in @emph{any} of the tags.
+
+@cindex tag groups
+@funindex \tagGroup
+While @code{\keepWithTag} is convenient when dealing with
+@emph{one} set of alternatives, the removal of music tagged with
+@emph{unrelated} tags is problematic when using tags for more than
+one purpose. For that reason, @q{tag groups} of related tags can
+be declared:
-Sometimes you want to splice some music at a particular place in an
-existing music expression. You can use @code{\pushToTag} and
-@code{\appendToTag} for adding material at the front or end of the
-@code{elements} of an existing music construct. Not every music
-construct has @code{elements}, but sequential and simultaneous music are
-safe bets:
+@example
+\tagGroup #'(violinI violinII viola cello)
+@end example
+
+declares the respective tags as belonging to one tag group.
+
+@example
+\keepWithTag #'violinI @dots{}
+@end example
+
+will then only be concerned with tags from @code{violinI}'s tag
+group: any element of the included music that is tagged with one
+or more of tags from this set but @emph{not} with @code{violinI}
+will get removed.
+
+To any @code{\keepWithTag} command, only tags from the tag groups
+of the tags given in the command are visible.
+
+Tags cannot be members of more than one tag group.
+
+@funindex \pushToTag
+@funindex \appendToTag
+@cindex splice into tagged music
+
+Sometimes you want to splice some music at a particular place in an
+existing music expression. You can use @code{\pushToTag} and
+@code{\appendToTag} for adding material at the front or end of the
+@code{elements} of an existing music construct. Not every music
+construct has @code{elements}, but sequential and simultaneous music are
+safe bets:
@lilypond[verbatim,quote]
test = { \tag #'here { \tag #'here <<c''>> } }
@end lilypond
Both commands get a tag, the material to splice in at every occurence of
-the tag, and the tagged expression. The commands make sure to
-copy everything that they change so that the original @code{\test}
-retains its meaning.
+the tag, and the tagged expression.
@seealso
Learning Manual:
@ref{Automatic part combining},
@ref{Including LilyPond files}.
-@ignore
-@c This warning is more general than this placement implies.
-@c Rests are not merged whether or not they come from tagged sections.
-@c Should be deleted? -td
-
@knownissues
-Multiple rests are not merged if you create a score with more
-than one tagged section at the same place.
-
-@end ignore
+Calling @code{\relative} on a music expression obtained by filtering
+music through @code{\keepWithTag} or @code{\removeWithTag} might cause
+the octave relations to change, as only the pitches actually
+remaining in the filtered expression will be considered. Applying
+@code{\relative} first, before @code{\keepWithTag} or
+@code{\removeWithTag}, avoids this danger as @code{\relative} then
+acts on all the pitches as-input.
@node Using global settings
@lilypond[quote]
%c No verbatim here as the code does not display correctly in PDF
+% Font settings for Cyrillic and Hebrew
+% Linux Libertine fonts contain Cyrillic and Hebrew glyphs.
+\paper {
+ #(define fonts
+ (set-global-fonts
+ #:roman "Linux Libertine O,serif"
+ #:sans "Linux Biolinum O,sans-serif"
+ #:typewriter "Linux Libertine Mono O,monospace"
+ ))
+}
+
% Cyrillic
bulgarian = \lyricmode {
Жълтата дюля беше щастлива, че пухът, който цъфна, замръзна като гьон.
à vo -- cê uma can -- ção legal
}
-\relative c' {
- c2 d e f g f e
+\relative {
+ c'2 d e f g f e
}
\addlyrics { \bulgarian }
\addlyrics { \hebrew }
@lilypond[quote,verbatim]
\score {
- \relative c'' {
- c1 \mark \markup { \char ##x03EE }
+ \relative {
+ c''1 \mark \markup { \char ##x03EE }
c1_\markup { \tiny { \char ##x03B1 " to " \char ##x03C9 } }
}
\addlyrics { O \markup { \concat { Ph \char ##x0153 be! } } }
}
-\markup { "Copyright 2008--2012" \char ##x00A9 }
+\markup { "Copyright 2008--2015" \char ##x00A9 }
@end lilypond
@cindex copyright sign
* Replacing the notation font::
@end menu
+@funindex clip-regions
+@cindex Fragments, music
+@cindex Music fragments
+
@node Extracting fragments of music
@subsection Extracting fragments of music
-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 defining the measures that need to be cut out
-separately. For example, including the following definition
-
+It is possible to output one or more fragments of a score by defining
+the explicit location of the music to be extracted within the
+@code{\layout} block of the the input file using the @code{clip-regions}
+function, and then running LilyPond with the @option{-dclip-systems}
+option;
-@verbatim
-\layout {
+@example
+\layout @{
clip-regions
= #(list
(cons
(make-rhythmic-location 5 1 2)
(make-rhythmic-location 7 3 4)))
-}
-@end verbatim
+@}
+@end example
@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.
+This example will extract a single fragment of the input file
+@emph{starting} after a half-note duration in fifth measure
+(@code{5 1 2}) and @emph{ending} after the third quarter-note in the
+seventh measure (@code{7 3 4}).
+
+Additional fragments can be extracted by adding more pairs of
+@code{make-rhythmic-location} entries to the @code{clip-regions} list in
+the @code{\layout} block.
+
+By default, each music fragment will be output as a separate @code{EPS}
+file, but other formats such as @code{PDF} or @code{PNG} can also be
+created if required. The extracted music is output as if had been
+literally @q{cut} from the original printed score so if a fragment runs
+over one or more lines, a separate output file for each line will be
+generated.
-More clip regions can be defined by adding more pairs of
-rhythmic-locations to the list.
+@seealso
+Notation Reference:
+@ref{The layout block}.
+
+Application Usage
+@rprogram{Command-line usage}.
-In order to use this feature, LilyPond must be invoked with
-@option{-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 @rprogram{Invoking lilypond}.
@node Skipping corrected music
@subsection Skipping corrected music
this correction process, it is possible to skip typesetting of all but
the last few measures. This is achieved by putting
-@verbatim
+@example
showLastLength = R1*5
-\score { ... }
-@end verbatim
+\score @{ @dots{} @}
+@end example
@noindent
in your source file. This will render only the last 5 measures
it skips all events, including tempo and instrument changes. You have
been warned.
-@lilypond[quote,relative=2,ragged-right,verbatim]
-c8 d
-\set Score.skipTypesetting = ##t
-e8 e e e e e e e
-\set Score.skipTypesetting = ##f
-c8 d b bes a g c2
+@lilypond[quote,ragged-right,verbatim]
+\relative c' {
+ c1
+ \set Score.skipTypesetting = ##t
+ \tempo 4 = 80
+ c4 c c c
+ \set Score.skipTypesetting = ##f
+ d4 d d d
+}
@end lilypond
In polyphonic music, @code{Score.skipTypesetting} will affect all
@c NOTE: these images are a bit big, but that's important
@c for the font comparison. -gp
-@sourceimage{Gonville_after,,,}
+@sourceimage{Gonville_after,15cm,,}
Here are a few sample bars of music set in LilyPond's Feta font:
-@sourceimage{Gonville_before,,,}
+@sourceimage{Gonville_before,15cm,,}
@subsubheading Installation Instructions for MacOS
Gonville.
-@node MIDI output
-@section MIDI output
+@node Creating MIDI output
+@section Creating 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.
+LilyPond can produce files that conform to the MIDI (Musical Instrument
+Digital Interface) standard and so allow for the checking of the music
+output aurally (with the help of an application or device that
+understands MIDI). Listening to MIDI output may also help in spotting
+errors such as notes that have been entered incorrectly or are missing
+accidentals and so on.
-Standard MIDI output is somewhat crude; optionally, an enhanced and
-more realistic MIDI output is available by means of
-@ref{The Articulate script}.
-
-The MIDI output allocates a channel for each staff, and reserves channel
-10 for drums. There are only 16 MIDI channels per device, so if the
-score contains more than 15 staves, MIDI channels will be reused.
+MIDI files do not contain sound (like AAC, MP3 or Vorbis files) but
+require additional software to produce sound from them.
@menu
-* Creating MIDI files::
-* MIDI block::
-* What goes into the MIDI output?::
-* Repeats in MIDI::
+* Supported notation for MIDI::
+* Unsupported notation for MIDI::
+* The MIDI block::
* Controlling MIDI dynamics::
-* Percussion in MIDI::
-* The Articulate script::
+* Using MIDI instruments::
+* Using repeats with MIDI::
+* MIDI channel mapping::
+* Context properties for MIDI effects::
+* Enhancing MIDI output::
@end menu
-@node Creating MIDI files
-@subsection Creating MIDI files
+@cindex MIDI, Supported notation
+
+@node Supported notation for MIDI
+@subsection Supported notation for MIDI
-To create a MIDI output file from a LilyPond input file, add a
-@code{\midi} block to a score, for example,
+The following musical notation can be used with LilyPond's default
+capabilities to produce MIDI output;
+
+@itemize
+@item Breath marks
+@item Chords entered as chord names
+@item Crescendi, decrescendi over multiple notes. The volume is altered
+linearly between the two extremes
+@item Dynamic markings from @code{ppppp} to @code{fffff}, including
+@code{mp}, @code{mf} and @code{sf}
+@item Microtones but @emph{not} microtonal chords. A MIDI player that
+supports pitch bending will also be required.
+@item Lyrics
+@item Pitches
+@item Rhythms entered as note durations, including tuplets
+@item @q{Simple} articulations; staccato, staccatissimo, accent, marcato
+and portato
+@item Tempo changes using the @code{\tempo} function
+@item Ties
+@item Tremolos that are @emph{not} entered with a
+@q{@code{:}[@var{number}]} value
+@end itemize
+
+Panning, balance, expression, reverb and chorus effects can also be
+controlled by setting context properties,
+see @ref{Context properties for MIDI effects}.
+
+When combined with the @file{articulate} script the following,
+additional musical notation can be output to MIDI;
+
+@itemize
+@item Appogiaturas. These are made to take half the value of the note
+following (without taking dots into account). For example;
@example
-\score @{
- @var{...music...}
- \midi @{ @}
-@}
+\appoggiatura c8 d2.
@end example
-If there is a @code{\midi} block in a @code{\score} with no
-@code{\layout} block, only MIDI output will be produced. When
-notation is needed too, a @code{\layout} block must also be
-present.
+@noindent
+The c will take the value of a crotchet.
+
+@item Ornaments (i.e. mordents, trills and turns et al.)
+@item Rallentando, accelerando, ritardando and a tempo
+@item Slurs, including phrasing slurs
+@item Tenuto
+@end itemize
+
+@noindent
+See @ref{Enhancing MIDI output}.
+
+@cindex MIDI, Unsupported notation
+
+@node Unsupported notation for MIDI
+@subsection Unsupported notation for MIDI
+
+The following items of musical notation cannot be output to MIDI;
+
+@itemize
+@item Articulations other than staccato, staccatissimo, accent, marcato
+and portato
+@item Crescendi and decrescendi over a @emph{single} note
+@item Fermata
+@item Figured bass
+@item Glissandi
+@item Falls and doits
+@item Microtonal chords
+@item Rhythms entered as annotations, e.g. swing
+@item Tempo changes without @code{\tempo} (e.g. entered as annotations)
+@item Tremolos that @emph{are} entered with a @q{@code{:}[@var{number}]}
+value
+@end itemize
+
+
+@node The MIDI block
+@subsection The MIDI block
+
+@cindex MIDI block
+
+To create a MIDI output file from a LilyPond input file, insert a
+@code{\midi} block, which can be empty, within the @code{\score} block;
@example
\score @{
- @var{...music...}
- \midi @{ @}
+ @var{@dots{} music @dots{}}
\layout @{ @}
+ \midi @{ @}
@}
@end example
-Pitches, rhythms, ties, dynamics, and tempo changes are interpreted
-and translated correctly to the MIDI output. 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 effect of dynamic markings
-on the MIDI output can be removed completely, see @ref{MIDI block}.
-
-The initial tempo and later tempo changes can be specified
-with the @code{\tempo} command within the music notation. These
-are reflected in tempo changes in the MIDI output. This command
-will normally result in the metronome mark being printed, but this
-can be suppressed, see @ref{Metronome marks}. An alternative way
-of specifying the initial or overall MIDI tempo is described below,
-see @ref{MIDI block}.
+@warning{ A @code{@bs{}score} block that, as well as the music, contains
+only a @code{@bs{}midi} block (i.e. @emph{without} the @code{@bs{}layout}
+block), will only produce MIDI output files. No notation will be
+printed.}
-Due to some limitations on Windows, the default extension for
-MIDI files on Windows is @code{.mid}. Other operating systems still
-use the extension @code{.midi}. If a different extension is preferred,
-insert the following line at the top-level of the input file,
-before the start of any @code{\book}, @code{\bookpart} or @code{\score} blocks:
+The default output file extension (@code{.midi}) can be changed by using
+the @code{-dmidi-extension} option with the @code{lilypond} command:
@example
-#(ly:set-option 'midi-extension "midi")
+lilypond -dmidi-extension=mid MyFile.ly
@end example
-The line above will set the default extension for MIDI files to
-@code{.midi}.
-
-Alternatively, this option can also be supplied on the command line:
+Alternatively, add the following Scheme expression before the start of
+either the @code{\book}, @code{\bookpart} or @code{\score} blocks. See
+@ref{File structure}.
@example
-lilypond … -dmidi-extension=midi lilyFile.ly
+#(ly:set-option 'midi-extension "mid")
@end example
+@seealso
+Notation Reference:
+@ref{File structure}.
-@unnumberedsubsubsec Instrument names
+Installed Files:
+@file{scm/midi.scm}.
-@cindex instrument names
-@funindex Staff.midiInstrument
+@knownissues
+There are fifteen MIDI channels available and one additional channel
+(#10) for drums. Staves are assigned to channels in sequence, so a
+score that contains more than fifteen staves will result in the extra
+staves sharing (but not overwriting) the same MIDI channel. This may be
+a problem if the sharing staves have conflicting, channel-based, MIDI
+properties -- such as different MIDI instruments -- set.
-The MIDI instrument to be used is specified by setting the
-@code{Staff.midiInstrument} property to the instrument name.
-The name should be chosen from the list in @ref{MIDI instruments}.
-@example
-\new Staff @{
- \set Staff.midiInstrument = #"glockenspiel"
- @var{...notes...}
-@}
-@end example
+@node Controlling MIDI dynamics
+@subsection Controlling MIDI dynamics
-@example
-\new Staff \with @{midiInstrument = #"cello"@} @{
- @var{...notes...}
-@}
-@end example
+It is possible to control the overall MIDI volume, the relative volume
+of dynamic markings and the relative volume of different instruments.
+
+Dynamic marks translate automatically into volume levels in the
+available MIDI volume range whereas crescendi and decrescendi vary the
+volume linearly between their two extremes. It is possible to control
+the relative volume of dynamic markings, and the overall volume levels
+of different instruments.
-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.
+@menu
+* Dynamic marks in MIDI::
+* Setting MIDI volume::
+* Setting MIDI block properties::
+@end menu
+@cindex MIDI volume
+@cindex MIDI equalization
+@cindex MIDI dynamics
+@cindex Dynamics in MIDI
-@snippets
+@node Dynamic marks in MIDI
+@unnumberedsubsubsec Dynamic marks in MIDI
+
+Only the dynamic markings from @code{ppppp} to @code{fffff}, including
+@code{mp}, @code{mf} and @code{sf} have values assigned to them. This
+value is then applied to the value of the overall MIDI volume range to
+obtain the final volume included in the MIDI output for that particular
+dynamic marking. The default fractions range from 0.25 for
+@notation{ppppp} to 0.95 for @notation{fffff}. The complete set of
+dynamic marks and their associated fractions can be found in
+@file{scm/midi.scm}.
+
+
+@snippets
@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
-{changing-midi-output-to-one-channel-per-voice.ly}
+{creating-custom-dynamics-in-midi-output.ly}
-@knownissues
+Installed Files:
+@file{ly/script-init.ly}
+@file{scm/midi.scm}.
+
+Snippets:
+@rlsr{MIDI}.
+
+Internals Reference:
+@rinternals{Dynamic_performer}.
-@c In 2.11 the following no longer seems to be a problem -td
-@ignore
-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,
+
+@node Setting MIDI volume
+@unnumberedsubsubsec Setting MIDI volume
+
+The minimum and maximum overall volume of MIDI dynamic markings is
+controlled by setting the properties @code{midiMinimumVolume} and
+@code{midiMaximumVolume} at the @code{Score} level. These properties
+have an effect only at the start of a voice and on dynamic marks. The
+fraction corresponding to each dynamic mark is modified with this
+formula
@example
-@{ a4\< b c d\f @}
+midiMinimumVolume + (midiMaximumVolume - midiMinimumVolume) * fraction
@end example
-@noindent
-will not work properly but
+In the following example the dynamic range of the overall MIDI
+volume is limited to the range @code{0.2} - @code{0.5}.
+
+@example
+\score @{
+ <<
+ \new Staff @{
+ \set Staff.midiInstrument = #"flute"
+ @var{@dots{} music @dots{}}
+ @}
+ \new Staff @{
+ \set Staff.midiInstrument = #"clarinet"
+ @var{@dots{} music @dots{}}
+ @}
+ >>
+ \midi @{
+ \context @{
+ \Score
+ midiMinimumVolume = #0.2
+ midiMaximumVolume = #0.5
+ @}
+ @}
+@}
+@end example
+
+Simple MIDI instrument equalization can be achieved by setting
+@code{midiMinimumVolume} and @code{midiMaximumVolume} properties within
+the @code{Staff} context.
@example
-@{ a4\< b c d\!\f @}
+\score @{
+ \new Staff @{
+ \set Staff.midiInstrument = #"flute"
+ \set Staff.midiMinimumVolume = #0.7
+ \set Staff.midiMaximumVolume = #0.9
+ @var{@dots{} music @dots{}}
+ @}
+ \midi @{ @}
+@}
@end example
-@noindent
-will.
-@end ignore
+For scores with multiple staves and multiple MIDI instruments, the
+relative volumes of each instrument can be set individually;
+
+@example
+\score @{
+ <<
+ \new Staff @{
+ \set Staff.midiInstrument = #"flute"
+ \set Staff.midiMinimumVolume = #0.7
+ \set Staff.midiMaximumVolume = #0.9
+ @var{@dots{} music @dots{}}
+ @}
+ \new Staff @{
+ \set Staff.midiInstrument = #"clarinet"
+ \set Staff.midiMinimumVolume = #0.3
+ \set Staff.midiMaximumVolume = #0.6
+ @var{@dots{} music @dots{}}
+ @}
+ >>
+ \midi @{ @}
+@}
+@end example
+
+In this example the volume of the clarinet is reduced relative to the
+volume of the flute.
+
+If these volumes properties are not set then LilyPond still applies a
+@q{small degree} of equalization to certain instruments. See
+@file{scm/midi.scm}.
+
+Installed Files:
+@file{scm/midi.scm}.
+
+@seealso
+Notation Reference:
+@ref{Score layout}.
+
+Internals Reference:
+@rinternals{Dynamic_performer}.
+
+@snippets
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
+{replacing-default-midi-instrument-equalization.ly}
+@knownissues
Changes in the MIDI volume take place only on starting a note, so
-crescendi and decrescendi cannot affect the volume of a
-single note.
+crescendi and decrescendi cannot affect the volume of a single note.
-Not all midi players correctly handle tempo changes in the midi
-output. Players that are known to work include MS Windows Media
-Player and @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
-@node MIDI block
-@subsection MIDI block
-@cindex MIDI block
+@node Setting MIDI block properties
+@unnumberedsubsubsec Setting MIDI block properties
-A @code{\midi} block must appear within a score block if MIDI output
-is required. It is analogous to the layout block, but somewhat
-simpler. Often, the @code{\midi} block is left empty, but it
-can contain context rearrangements, new context definitions or code
-to set the values of properties. For example, the following will
-set the initial tempo exported to a MIDI file without causing a tempo
-indication to be printed:
+The @code{\midi} block can contain context rearrangements, new context
+definitions or code that sets the values of certain properties.
@example
\score @{
- @var{...music...}
+ @var{@dots{} music @dots{}}
\midi @{
\tempo 4 = 72
@}
@}
@end example
-In this example the tempo is set to 72 quarter note
-beats per minute. @code{\tempo} is actually a music command for
-setting properties during the interpretation of music: in the
-context of output definitions like a @code{\midi} block, as a matter of
-courtesy those are reinterpreted as if they were context modifications.
+Here the tempo is set to 72 quarter-note beats per minute. The tempo
+mark in the @code{\midi} block will not appear in the printed score.
+Although any other @code{\tempo} indications specified within the
+@code{\score} block will also be reflected in the MIDI output.
-@cindex MIDI context definitions
+In a @code{\midi} block the @code{\tempo} command is setting properties
+during the interpretation of the music and in the context of output
+definitions; so it is interpreted @emph{as if} it were a context
+modification.
-Context definitions follow precisely the same syntax as those
-within a @code{\layout} block. Translation modules for sound are
-called performers. The contexts for MIDI output are defined in
-@file{../ly/performer-init.ly},
-see @rlearning{Other sources of information}.
-For example, to remove the effect of dynamics
-from the MIDI output, insert the following lines in the
-@code{\midi@{ @}} block.
-
-@example
-\midi @{
- ...
- \context @{
- \Voice
- \remove "Dynamic_performer"
- @}
-@}
-@end example
+@cindex MIDI context definitions
+@cindex context definitions with MIDI
-MIDI output is created only when a @code{\midi} block is included
-within a score block defined with a @code{\score} command.
+Context definitions follow the same syntax as those in a @code{\layout}
+block;
@example
\score @{
- @{ @dots{}notes@dots{} @}
- \midi @{ @}
+ @var{@dots{} music @dots{}}
+ \midi @{
+ \context @{
+ \Voice
+ \remove "Dynamic_performer"
+ @}
+ @}
@}
@end example
-@node What goes into the MIDI output?
-@subsection What goes into the MIDI output?
+This example removes the effect of dynamics from the MIDI output. Note:
+LilyPond's translation modules used for sound are called @q{performers}.
-@c TODO Check grace notes - timing is suspect?
+@seealso
+Learning Manual:
+@rlearning{Other sources of information}.
-@unnumberedsubsubsec Supported in MIDI
+Notation Reference:
+@ref{Expressive marks},
+@ref{Score layout}.
-@cindex Pitches in MIDI
-@cindex MIDI, Pitches
-@cindex Quarter tones in MIDI
-@cindex MIDI, quarter tones
-@cindex Microtones in MIDI
-@cindex MIDI, microtones
-@cindex Chord names in MIDI
-@cindex MIDI, chord names
-@cindex Rhythms in MIDI
-@cindex MIDI, Rhythms
-@cindex Articlulate scripts
-@cindex MIDI, articulations
-@cindex articulations in MIDI
-@cindex trills in MIDI
-@cindex turns in MIDI
-@cindex rallentando in MIDI
-@cindex accelerando in MIDI
-@c TODO etc
+Installed Files:
+@file{ly/performer-init.ly}.
-The following items of notation are reflected in the MIDI output:
+Snippets:
+@rlsr{MIDI}.
-@itemize
-@item Pitches
-@item Microtones (See @ref{Accidentals}. Rendering needs a
-player that supports pitch bend.)
-@item Chords entered as chord names
-@item Rhythms entered as note durations, including tuplets
-@item Tremolos entered without @q{@code{:}[@var{number}]}
-@item Ties
-@item Dynamic marks
-@item Crescendi, decrescendi over multiple notes
-@item Tempo changes entered with a tempo marking
-@item Lyrics
-@end itemize
+Internals Reference:
+@rinternals{Dynamic_performer}.
-Using @ref{The Articulate script}, a number of items are added to the
-above list:
+@knownissues
+Some MIDI players do not always correctly handle tempo changes in the
+midi output.
-@itemize
-@item Articulations (slurs, staccato, etc)
-@item Trills, turns
-@item Rallentando and accelerando
-@end itemize
+Changes to the @code{midiInstrument}, as well as some MIDI options, at
+the @emph{beginning} of a staff may appear twice in the MIDI output.
-@unnumberedsubsubsec Unsupported in MIDI
-@c TODO index as above
+@node Using MIDI instruments
+@subsection Using MIDI instruments
-The following items of notation have no effect on the MIDI output,
-unless you use @ref{The Articulate script}:
+MIDI instruments are set using the @code{midiInstrument} property within
+a @code{Staff} context.
-@itemize
-@item Rhythms entered as annotations, e.g. swing
-@item Tempo changes entered as annotations with no tempo marking
-@item Staccato and other articulations and ornamentations
-@item Slurs and Phrasing slurs
-@item Crescendi, decrescendi over a single note
-@item Tremolos entered with @q{@code{:}[@var{number}]}
-@item Figured bass
-@item Microtonal chords
-@end itemize
+@example
+\score @{
+ \new Staff @{
+ \set Staff.midiInstrument = #"glockenspiel"
+ @var{@dots{} music @dots{}}
+ @}
+ \midi @{ @}
+@}
+@end example
+or
-@node Repeats in MIDI
-@subsection Repeats in MIDI
+@example
+\score @{
+ \new Staff \with @{midiInstrument = #"cello"@} @{
+ @var{@dots{} music @dots{}}
+ @}
+ \midi @{ @}
+@}
+@end example
+
+If the instrument name does not match any of the instruments listed in
+the @q{MIDI instruments} section, the @code{acoustic grand} instrument
+will be used instead. See @ref{MIDI instruments}.
+
+@seealso
+Learning Manual:
+@rlearning{Other sources of information}.
+
+Notation Reference:
+@ref{MIDI instruments},
+@ref{Score layout}.
+
+Installed Files:
+@file{scm/midi.scm}.
+
+@knownissues
+Percussion instruments that are notated in a @code{DrumStaff}
+context will be output, correctly, to MIDI channel@tie{}10 but some
+pitched, percussion instruments like the xylophone, marimba, vibraphone
+or timpani, are treated as @qq{normal} instruments so the music for
+these should be entered in a @code{Staff} (not @code{DrumStaff}) context
+to obtain correct MIDI output. A full list of
+@code{channel 10 drum-kits} entries can be found in @file{scm/midi.scm}.
+See @rlearning{Other sources of information}.
+
+
+@node Using repeats with MIDI
+@subsection Using repeats with MIDI
@cindex repeats in MIDI
+@cindex MIDI using repeats
@funindex \unfoldRepeats
-With a few minor additions, all types of repeats can be represented
-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]
-\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
+Repeats can be represented in the MIDI output by applying the
+@code{\unfoldRepeats} command.
-In scores containing multiple voices, unfolding of repeats in MIDI
-output will only occur correctly if @emph{each} voice contains fully
-notated repeat indications.
+@example
+\score @{
+ \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' @}
+ @}
+ @}
+ \midi @{ @}
+@}
+@end example
-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,
+In order to restrict the effect of @code{\unfoldRepeats} to the MIDI
+output only, while also generating printable scores, it is necessary to
+make @emph{two} @code{\score} blocks; one for MIDI (with unfolded
+repeats) and one for the notation (with volta, tremolo, and percent
+repeats);
@example
\score @{
- @var{..music..}
- \layout @{ .. @}
+ @var{@dots{} music @dots{}}
+ \layout @{ @}
@}
\score @{
- \unfoldRepeats @var{..music..}
- \midi @{ .. @}
+ \unfoldRepeats @{
+ @var{@dots{} music @dots{}}
+ @}
+ \midi @{ @}
@}
@end example
-@node Controlling MIDI dynamics
-@subsection Controlling MIDI dynamics
+When using multiple voices, each of the voices must contain completely
+unfolded repeats for correct MIDI output.
-MIDI dynamics are implemented by the Dynamic_performer which lives
-by default in the Voice context. It is possible to control the
-overall MIDI volume, the relative volume of dynamic markings and
-the relative volume of different instruments.
-
-@unnumberedsubsubsec Dynamic marks
-
-Dynamic marks are translated to a fixed fraction of the available
-MIDI volume range. The default fractions range from 0.25 for
-@notation{ppppp} to 0.95 for @notation{fffff}. The set of dynamic
-marks and the associated fractions can be seen in
-@file{../scm/midi.scm}, see @rlearning{Other sources of information}.
-This set of fractions may be changed or extended by providing a
-function which takes a dynamic mark as its argument and returns the
-required fraction, and setting
-@code{Score.dynamicAbsoluteVolumeFunction} to this function.
-
-For example, if a @notation{rinforzando} dynamic marking,
-@code{\rfz}, is required, this will not by default
-have any effect on the MIDI volume, as this dynamic marking is not
-included in the default set. Similarly, if a new dynamic marking
-has been defined with @code{make-dynamic-script} that too will not
-be included in the default set. The following example shows how the
-MIDI volume for such dynamic markings might be added. The Scheme
-function sets the fraction to 0.9 if a dynamic mark of rfz is
-found, or calls the default function otherwise.
+@seealso
+Notation Reference:
+@ref{Repeats}.
+
+
+@node MIDI channel mapping
+@subsection MIDI channel mapping
+
+@cindex MIDI Channels
+@cindex MIDI Tracks
+@funindex midiChannelMapping
+
+When generating a MIDI file from a score, LilyPond will automatically
+assign every note in the score to a MIDI channel, the one on which it
+should be played when it is sent to a MIDI device. A MIDI channel has
+a number of controls available to select, for example, the instrument
+to be used to play the notes on that channel, or to request the MIDI
+device to apply various effects to the sound produced on the channel.
+At all times, every control on a MIDI channel can have only a single
+value assigned to it (which can be modified, however, for example,
+to switch to another instrument in the middle of a score).
+
+The MIDI standard supports only 16 channels per MIDI device. This
+limit on the number of channels also limits the number of different
+instruments which can be played at the same time.
+
+LilyPond creates separate MIDI tracks for each staff, (or discrete
+instrument or voice, depending on the value of
+@code{Score.midiChannelMapping}), and also for each lyrics context.
+There is no limit to the number of tracks.
+
+To work around the limited number of MIDI channels, LilyPond supports
+a number of different modes for MIDI channel allocation, selected using
+the @code{Score.midiChannelMapping} context property. In each case,
+if more MIDI channels than the limit are required, the allocated
+channel numbers wrap around back to 0, possibly causing the incorrect
+assignment of instruments to some notes. This context property can be
+set to one of the following values:
-@lilypond[verbatim,quote]
-#(define (myDynamics dynamic)
- (if (equal? dynamic "rfz")
- 0.9
- (default-dynamic-absolute-volume dynamic)))
+@table @var
-\score {
- \new Staff {
- \set Staff.midiInstrument = #"cello"
- \set Score.dynamicAbsoluteVolumeFunction = #myDynamics
- \new Voice {
- \relative c'' {
- a4\pp b c-\rfz
- }
- }
- }
- \layout {}
- \midi {}
-}
-@end lilypond
+@item @code{'staff}
-Alternatively, if the whole table of fractions needs to be
-redefined, it would be better to use the
-@notation{default-dynamic-absolute-volume} procedure in
-@file{../scm/midi.scm} and the associated table as a model.
-The final example in this section shows how this might be done.
+Allocate a separate MIDI channel to each staff in the score (this is
+the default). All notes in all voices contained within each staff will
+share the MIDI channel of their enclosing staff, and all are encoded
+in the same MIDI track.
-@unnumberedsubsubsec Overall MIDI volume
+The limit of 16 channels is applied to the total number of staff and
+lyrics contexts, even though MIDI lyrics do not take up a MIDI channel.
-The minimum and maximum overall volume of MIDI dynamic markings is
-controlled by setting the properties @code{midiMinimumVolume} and
-@code{midiMaximumVolume} at the @code{Score} level. These
-properties have an effect only on dynamic marks, so if they
-are to apply from the start of the score a dynamic mark must be
-placed there. The fraction corresponding to each dynamic mark is
-modified with this formula
+@item @code{'instrument}
-@example
-midiMinimumVolume + (midiMaximumVolume - midiMinimumVolume) * fraction
-@end example
+Allocate a separate MIDI channel to each distinct MIDI instrument
+specified in the score. This means that all the notes played with the
+same MIDI instrument will share the same MIDI channel (and track), even
+if the notes come from different voices or staves.
-In the following example the dynamic range of the overall MIDI
-volume is limited to the range 0.2 - 0.5.
+In this case the lyrics contexts do not count towards the MIDI channel
+limit of 16 (as they will not be assigned to a MIDI instrument), so
+this setting may allow a better allocation of MIDI channels when the
+number of staves and lyrics contexts in a score exceeds 16.
-@lilypond[verbatim,quote]
-\score {
- <<
- \new Staff {
- \key g \major
- \time 2/2
- \set Staff.midiInstrument = #"flute"
- \new Voice \relative c''' {
- r2 g\mp g fis~
- fis4 g8 fis e2~
- e4 d8 cis d2
- }
- }
- \new Staff {
- \key g \major
- \set Staff.midiInstrument = #"clarinet"
- \new Voice \relative c'' {
- b1\p a2. b8 a
- g2. fis8 e
- fis2 r
- }
- }
- >>
- \layout {}
- \midi {
- \tempo 2 = 72
- \context {
- \Score
- midiMinimumVolume = #0.2
- midiMaximumVolume = #0.5
- }
- }
-}
-@end lilypond
+@item @code{'voice}
-@unnumberedsubsubsec Equalizing different instruments (i)
+Allocate a separate MIDI channel to each voice in the score that has a
+unique name among the voices in its enclosing staff. Voices in
+different staves are always assigned separate MIDI channels, but any two
+voices contained within the same staff will share the same MIDI channel
+if they have the same name. Because @code{midiInstrument} and the
+several MIDI controls for effects are properties of the staff context,
+they cannot be set separately for each voice. The first voice will be
+played with the instrument and effects specified for the staff, and
+voices with a different name from the first will be assigned the default
+instrument and effects.
-If the minimum and maximum MIDI volume properties are set in
-the @code{Staff} context the relative volumes of the MIDI
-instruments can be controlled. This gives a basic instrument
-equalizer, which can enhance the quality of the MIDI output
-remarkably.
+Note: different instruments and/or effects can be assigned to several
+voices on the same staff by moving the @code{Staff_performer} from the
+@code{Staff} to the @code{Voice} context, and leaving
+@code{midiChannelMapping} to default to @code{'staff} or set to
+@code{'instrument}; see the snippet below.
-In this example the volume of the clarinet is reduced relative
-to the volume of the flute. There must be a dynamic
-mark on the first note of each instrument for this to work
-correctly.
+@end table
-@lilypond[verbatim,quote]
-\score {
- <<
- \new Staff {
- \key g \major
- \time 2/2
- \set Staff.midiInstrument = #"flute"
- \set Staff.midiMinimumVolume = #0.7
- \set Staff.midiMaximumVolume = #0.9
- \new Voice \relative c''' {
- r2 g\mp g fis~
- fis4 g8 fis e2~
- e4 d8 cis d2
- }
- }
- \new Staff {
- \key g \major
- \set Staff.midiInstrument = #"clarinet"
- \set Staff.midiMinimumVolume = #0.3
- \set Staff.midiMaximumVolume = #0.6
- \new Voice \relative c'' {
- b1\p a2. b8 a
- g2. fis8 e
- fis2 r
- }
- }
- >>
- \layout {}
- \midi {
- \tempo 2 = 72
- }
-}
-@end lilypond
+For example, the default MIDI channel mapping of a score can be changed
+to the @code{'instrument} setting as shown:
-@unnumberedsubsubsec Equalizing different instruments (ii)
+@example
+\score @{
+ ...music...
+ \midi @{
+ \context @{
+ \Score
+ midiChannelMapping = #'instrument
+ @}
+ @}
+@}
+@end example
-If the MIDI minimum and maximum volume properties are not set
-LilyPond will, by default, apply a small degree of equalization
-to a few instruments. The instruments and the equalization
-applied are shown in the table @notation{instrument-equalizer-alist}
-in @file{../scm/midi.scm}.
+@snippets
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
+{changing-midi-output-to-one-channel-per-voice.ly}
-This basic default equalizer can be replaced by setting
-@code{instrumentEqualizer} in the @code{Score} context to a new
-Scheme procedure which accepts a MIDI instrument name as its only
-argument and returns a pair of fractions giving the minimum and
-maximum volumes to be applied to that instrument. This replacement
-is done in the same way as shown for resetting the
-@code{dynamicAbsoluteVolumeFunction} at the start of this section.
-The default equalizer, @notation{default-instrument-equalizer}, in
-@file{../scm/midi.scm} shows how such a procedure might be written.
-The following example sets the relative flute and clarinet volumes
-to the same values as the previous example.
+@node Context properties for MIDI effects
+@subsection Context properties for MIDI effects
+
+@cindex Effects in MIDI
+@cindex Pan position in MIDI
+@cindex Stereo balance in MIDI
+@cindex Balance in MIDI
+@cindex Expression in MIDI
+@cindex Reverb in MIDI
+@cindex Chorus level in MIDI
+@funindex midiPanPosition
+@funindex midiBalance
+@funindex midiExpression
+@funindex midiReverbLevel
+@funindex midiChorusLevel
+
+The following context properties can be used to apply various MIDI
+effects to notes played on the MIDI channel associated with the
+current staff, MIDI instrument or voice (depending on the value of the
+@code{Score.midiChannelMapping} context property and the context in
+which the @code{Staff_performer} is located; see
+@ref{MIDI channel mapping}).
+
+Changing these context properties will affect all notes played on the
+channel after the change, however some of the effects may even apply
+also to notes which are already playing (depending on the
+implementation of the MIDI output device).
+
+The following context properties are supported:
-@lilypond[verbatim,quote]
-#(define my-instrument-equalizer-alist '())
+@table @var
-#(set! my-instrument-equalizer-alist
- (append
- '(
- ("flute" . (0.7 . 0.9))
- ("clarinet" . (0.3 . 0.6)))
- my-instrument-equalizer-alist))
+@item @code{Staff.midiPanPosition}
-#(define (my-instrument-equalizer s)
- (let ((entry (assoc s my-instrument-equalizer-alist)))
- (if entry
- (cdr entry))))
+The pan position controls how the sound on a MIDI channel is
+distributed between left and right stereo outputs. The context
+property accepts a number between -1.0 (@code{#LEFT}) and 1.0
+(@code{#RIGHT}); the value -1.0 will put all sound power to the left
+stereo output (keeping the right output silent), the value 0.0
+(@code{#CENTER}) will distribute the sound evenly between the left and
+right stereo outputs, and the value 1.0 will move all sound to the
+right stereo output. Values between -1.0 and 1.0 can be used to obtain
+mixed distributions between left and right stereo outputs.
-\score {
- <<
- \new Staff {
- \key g \major
- \time 2/2
- \set Score.instrumentEqualizer = #my-instrument-equalizer
- \set Staff.midiInstrument = #"flute"
- \new Voice \relative c''' {
- r2 g\mp g fis~
- fis4 g8 fis e2~
- e4 d8 cis d2
- }
- }
- \new Staff {
- \key g \major
- \set Staff.midiInstrument = #"clarinet"
- \new Voice \relative c'' {
- b1\p a2. b8 a
- g2. fis8 e
- fis2 r
- }
- }
- >>
- \layout { }
- \midi {
- \tempo 2 = 72
- }
-}
-@end lilypond
+@item @code{Staff.midiBalance}
-@ignore
-@c Delete when satisfied this is adequately covered elsewhere -td
+The stereo balance of a MIDI channel. Similarly to the pan position,
+this context property accepts a number between -1.0 (@code{#LEFT}) and
+1.0 (@code{#RIGHT}). It varies the relative volume sent to the two
+stereo speakers without affecting the distribution of the stereo
+signals.
-@n ode Microtones in MIDI
-@s ubsection Microtones in MIDI
+@item @code{Staff.midiExpression}
-@cindex microtones in MIDI
+Expression level (as a fraction of the maximum available level) to
+apply to a MIDI channel. A MIDI device combines the MIDI channel's
+expression level with a voice's current dynamic level (controlled using
+constructs such as @code{\p} or @code{\ff}) to obtain the total volume
+of each note within the voice. The expression control could be used, for
+example, to implement crescendo or decrescendo effects over single
+sustained notes (not supported automatically by LilyPond).
-Microtones consisting of half sharps and half flats are exported
-to the MIDI file and render correctly in MIDI players which support
-pitch bending. See @ref{Note names in other languages}. Here is
-an example showing all the half sharps and half flats. It can be
-copied out and compiled to test microtones in your MIDI player.
+@c Issue 4059 contains an attached snippet which shows how this might
+@c be done, but this is too large and complex for the NR, even as a
+@c referenced snippet. It could be added to the LSR.
-@lilypond[verbatim,quote]
-\score {
- \relative c' {
- c4 cih cis cisih
- d4 dih ees eeh
- e4 eih f fih
- fis4 fisih g gih
- gis4 gisih a aih
- bes4 beh b bih
- }
- \layout {}
- \midi {}
-}
-@end lilypond
-@end ignore
+The expression level ranges from 0.0 (no expression, meaning zero
+volume) to 1.0 (full expression).
+@item @code{Staff.midiReverbLevel}
-@node Percussion in MIDI
-@subsection Percussion in MIDI
+Reverb level (as a fraction of the maximum available level) to apply
+to a MIDI channel. This property accepts numbers between 0.0 (no
+reverb) and 1.0 (full effect).
-Percussion instruments are generally notated in a @code{DrumStaff}
-context and when notated in this way they are outputted correctly
-to MIDI channel@tie{}10, but some pitched percussion instruments,
-like the xylophone, marimba, vibraphone, timpani, etc., are
-treated like @qq{normal} instruments and music for these instruments
-should be entered in a normal @code{Staff} context, not a
-@code{DrumStaff} context, to obtain the correct MIDI output.
+@item @code{Staff.midiChorusLevel}
-Some non-pitched percussion sounds included in the general MIDI
-standard, like melodic tom, taiko drum, synth drum, etc., cannot
-be reached via MIDI channel@tie{}10, so the notation for such
-instruments should also be entered in a normal @code{Staff}
-context, using suitable normal pitches.
+Chorus level (as a fraction of the maximum available level) to apply to
+a MIDI channel. This property accepts numbers between 0.0 (no chorus
+effect) and 1.0 (full effect).
-Many percussion instruments are not included in the general MIDI
-standard, e.g. castanets. The easiest, although unsatisfactory,
-method of producing some MIDI output when writing for such
-instruments is to substitute the nearest sound from the standard
-set.
+@end table
-@c TODO Expand with examples, and any other issues
@knownissues
-Because the general MIDI standard does not contain rim shots, the
-sidestick is used for this purpose instead.
+As MIDI files do not contain any actual audio data, changes in these
+context properties translate only to requests for changing MIDI channel
+controls in the outputted MIDI files. Whether a particular MIDI device
+(such as a software MIDI player) can actually handle any of these
+requests in a MIDI file is entirely up to the implementation of the
+device: a device may choose to ignore some or all of these requests.
+Also, how a MIDI device will interpret different values for these
+controls (generally, the MIDI standard fixes the behavior only at the
+endpoints of the value range available for each control), and whether a
+change in the value of a control will affect notes already playing on
+that MIDI channel or not, is also specific to the MIDI device
+implementation.
+
+When generating MIDI files, LilyPond will simply transform the
+fractional values within each range linearly into values in a
+corresponding (7-bit, or 14-bit for MIDI channel controls which support
+fine resolution) integer range (0-127 or 0-32767, respectively),
+rounding fractional values towards the nearest integer away from zero.
+The converted integer values are stored as-is in the generated MIDI
+file. Please consult the documentation of your MIDI device for
+information about how the device interprets these values.
+
+
+@node Enhancing MIDI output
+@subsection Enhancing MIDI output
-@node The Articulate script
-@subsection The Articulate script
+@menu
+* The articulate script::
+@end menu
-A more realistic MIDI output is possible when using the Articulate
-script. It tries to take articulations (slurs, staccato, etc) into
-account, by replacing notes with sequential music of suitably
-time-scaled note plus skip. It also tries to unfold trills turns
-etc., and take rallentando and accelerando into account.
+The default MIDI output is basic but can be improved by setting MIDI
+instruments, @code{\midi} block properties and/or using the
+@file{articulate} script.
-To use the Articulate script, you have to include it at the top of
-your input file,
+@cindex instrument names
+@cindex MIDI, instruments
+@cindex articulate script
+@cindex articulate.ly
+@funindex Staff.midiInstrument
+
+
+@node The articulate script
+@unnumberedsubsubsec The @file{articulate} script
+
+To use the @file{articulate} script add the appropriate @code{\include}
+command at the top of the input file;
@example
\include "articulate.ly"
@end example
-and in the @code{\score} section do
+The script creates MIDI output into appropriately @q{time-scaled} notes
+to match many articulation and tempo indications. Engraved output
+however, will also be altered to literally match the MIDI output.
@example
-\unfoldRepeats \articulate <<
- all the rest of the score...
->>
+\score @{
+ \articulate <<
+ @var{@dots{} music @dots{}}
+ >>
+ \midi @{ @}
+@}
@end example
-After altering your input file this way, the visual output is heavily
-altered, but the standard @code{\midi} block will produce a better
-MIDI file.
+The @code{\articulate} command enables abbreviatures (such as trills and
+turns) to be processed. A full list of supported items can be found in
+the script itself. See @file{ly/articulate.ly}.
-Although not essential for the Articulate script to work, you may want
-to insert the @code{\unfoldRepeats} command as it appears in the
-example shown above as it enables performing abbreviatures such as
-@notation{trills}.
+@seealso
+Learning Manual:
+@rlearning{Other sources of information}.
-@knownissues
+Notation Reference:
+@ref{Score layout}.
+
+Installed Files:
+@file{ly/articulate.ly}.
+
+@warning{The @file{articulate} script may shorten chords, which might
+not be appropriate for some types of instrument, such as organ music.
+Notes that do not have any articulations attached to them may also be
+shortened; so to compensate for this, restrict the use of the
+@code{\articulate} function to shorter segments of music or modify the
+values of the variables defined in the @file{articulate} script to
+compentate for the note-shortening behavior.}
-Articulate shortens chords and some music (esp. organ music) could
-sound worse.
@node Extracting musical information
will display
@example
-@{ a,4 cis e fis g @}
+@{ a,4 cis4 e4 fis4 g4 @}
@end example
By default, LilyPond will print these messages to the console
along with all the other LilyPond compilation messages. To split
-up these messages and save the results of @code{\display@{STUFF@}},
+up these messages and save the results of @code{\displayLilyMusic},
redirect the output to a file.
@example
line followed by optional parameters.
@example
-@var{time} @var{type} @var{...params...}
+@var{time} @var{type} @var{@dots{}params@dots{}}
@end example
This information can easily be read into other programs such as
projects / lilypond.git / blobdiff