Guide, node Updating translation committishes..
@end ignore
-@c \version "2.13.36"
+@c \version "2.14.0"
@node General input and output
@chapter General input and output
* Working with input files::
* Controlling output::
* MIDI output::
+* Extracting musical information::
@end menu
@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{#} sign.
+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
some pieces include a lot more information.
@menu
-* Creating titles::
+* Creating titles headers and footers::
* Custom headers footers and titles::
* Reference to page numbers::
* Table of contents::
@end menu
-@node Creating titles
-@subsection Creating titles
+@node Creating titles headers and footers
+@subsection Creating titles headers and footers
-Titles are created for each @code{\score} block, as well as for the full
-input file (or @code{\book} block) and book parts (created by
-@code{\bookpart} blocks).
-
-The contents of the titles are taken from the @code{\header} blocks.
-The header block for a book supports the following
+@menu
+* Title blocks explained::
+* Default layout of book and score title blocks::
+* Default layout of headers and footers::
+@end menu
-@table @code
-@funindex dedication
-@item dedication
-The dedicatee of the music, centered at the top of the first page.
+@node Title blocks explained
+@unnumberedsubsubsec Title blocks explained
-@funindex title
-@item title
-The title of the music, centered just below the dedication.
+@c TODO: figure out how \bookpart titles work
-@funindex subtitle
-@item subtitle
-Subtitle, centered below the title.
+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.
-@funindex subsubtitle
-@item subsubtitle
-Subsubtitle, centered below the subtitle.
+If the book only has a single score, the @code{\header} block may be
+placed inside or outside of the @code{\score} block.
-@funindex poet
-@item poet
-Name of the poet, flush-left below the subsubtitle.
+@warning{Remember when adding a @bs{}@code{header} block inside a
+@bs{}@code{score} block, that the music expression must come before the
+@bs{}@code{header} block.}
-@funindex instrument
-@item instrument
-Name of the instrument, centered below the subsubtitle. Also
-centered at the top of pages (other than the first page).
+@lilypond[papersize=a5,quote,verbatim,noragged-right]
+\header {
+ title = "SUITE I."
+ composer = "J. S. Bach."
+}
-@funindex composer
-@item composer
-Name of the composer, flush-right below the subsubtitle.
+\score {
+ \new Staff \relative g, {
+ \clef bass
+ \key g \major
+ \repeat unfold 2 { g16( d' b') a b d, b' d, } |
+ \repeat unfold 2 { g,16( e' c') b c e, c' e, } |
+ }
+ \header {
+ piece = "Prélude."
+ }
+}
-@funindex meter
-@item meter
-Meter string, flush-left below the poet.
+\score {
+ \new Staff \relative b {
+ \clef bass
+ \key g \major
+ \partial 16 b16 |
+ <g, d' b'~>4 b'16 a( g fis) g( d e fis) g( a b c) |
+ d16( b g fis) g( e d c) b(c d e) fis( g a b) |
+ }
+ \header {
+ piece = "Allemande."
+ }
+}
+@end lilypond
-@funindex arranger
-@item arranger
-Name of the arranger, flush-right below the composer.
+Text fields from the main title block of a book can be displayed in all
+@code{\score} blocks, or manually suppressed:
-@funindex piece
-@item piece
-Name of the piece, flush-left below the meter.
+@lilypond[papersize=a5,quote,verbatim,noragged-right]
+\book {
+ \paper {
+ print-all-headers = ##t
+ }
+ \header {
+ title = "DAS WOHLTEMPERIRTE CLAVIER"
+ subtitle = "TEIL I"
+ % Do not display the tagline for this book
+ tagline = ##f
+ }
+ \markup { \vspace #1 }
+ \score {
+ \new PianoStaff <<
+ \new Staff { s1 }
+ \new Staff { \clef "bass" s1 }
+ >>
+ \header {
+ title = "PRAELUDIUM I"
+ opus = "BWV 846"
+ % Do not display the subtitle for this score
+ subtitle = ##f
+ }
+ }
+ \score {
+ \new PianoStaff <<
+ \new Staff { s1 }
+ \new Staff { \clef "bass" s1 }
+ >>
+ \header {
+ title = "FUGA I"
+ subsubtitle = "A 4 VOCI"
+ opus = "BWV 846"
+ % Do not display the subtitle for this score
+ subtitle = ##f
+ }
+ }
+}
+@end lilypond
-@funindex opus
-@item opus
-Name of the opus, flush-right below the arranger.
+@seealso
+Notation Reference:
+@ref{File structure},
+@ref{Custom layout for title blocks}.
-@cindex page breaks, forcing
-@funindex breakbefore
-@item breakbefore
-This forces the title to start on a new page (set to ##t or ##f).
-@funindex copyright
-@item copyright
-Copyright notice, centered at the bottom of the first page. To
-insert the copyright symbol, see @ref{Text encoding}.
+@node Default layout of book and score title blocks
+@unnumberedsubsubsec Default layout of book and score title blocks
-@funindex tagline
-@item tagline
-Centered at the bottom of the last page.
+The layout and formatting of title blocks are controlled by two
+@code{\paper} variables; @code{bookTitleMarkup} for the main
+@code{\header} title block and @code{scoreTitleMarkup} for individual
+@code{\header} blocks within a @code{\score}.
-@end table
+@lilypond[papersize=a6,quote,verbatim,noragged-right]
+\header {
+ % The following fields are centered
+ dedication = "Dedication"
+ title = "Title"
+ subtitle = "Subtitle"
+ subsubtitle = "Subsubtitle"
+ instrument = "Instrument"
-Here is a demonstration of the fields available. Note that you
-may use any @ref{Formatting text}, commands in the header.
+ % The following fields are left-aligned on the left side
+ poet = "Poet"
+ meter = "Meter"
-@lilypond[quote,verbatim,line-width=11.0\cm]
-\paper {
- line-width = 9.0\cm
- paper-height = 10.0\cm
+ % The following fields are right-aligned on the right side
+ composer = "Composer"
+ arranger = "Arranger"
}
-\book {
+\score {
+ { s1 }
\header {
- dedication = "dedicated to me"
- title = \markup \center-column { "Title first line" "Title second line,
-longer" }
- subtitle = "the subtitle,"
- subsubtitle = #(string-append "subsubtitle LilyPond version "
-(lilypond-version))
- poet = "Poet"
- composer = \markup \center-column { "composer" \small "(1847-1973)" }
- texttranslator = "Text Translator"
- meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
-"r" }
- arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize
-#-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }
- instrument = \markup \bold \italic "instrument"
+ % The following fields are placed at opposite ends of the same line
piece = "Piece"
+ opus = "Opus"
}
+}
+@end lilypond
+
+@c Is the bit about \null markups true? -mp
+
+Text fields left unset in a @code{\header} block are replaced with
+@code{\null} markups so that the space is not wasted.
+The default settings for @code{scoreTitleMarkup} place the @code{piece}
+and @code{opus} text fields at opposite ends of the same line.
+
+@cindex breakbefore
+
+Use the @code{breakbefore} variable inside a @code{\header} block
+that is itself in a @code{\score} block, to make the top-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]
+\book {
+ \header {
+ title = "This is my Title"
+ subtitle = "This is my Subtitle"
+ copyright = "This is the bottom of the first page"
+ }
\score {
- { c'1 }
+ \repeat unfold 4 { e'' e'' e'' e'' }
\header {
- piece = "piece1"
- opus = "opus1"
+ piece = "This is the Music"
+ breakbefore = ##t
}
}
- \markup {
- and now...
+}
+@end lilypond
+
+@seealso
+Learning Manual:
+@rlearning{How LilyPond input files work},
+
+Notation Reference:
+@ref{File structure}.
+
+Installed Files:
+@file{ly/titling-init.ly}.
+
+@node Default layout of headers and footers
+@unnumberedsubsubsec Default layout of headers and footers
+
+@emph{Headers} and @emph{footers} are lines of text appearing at
+the top and bottom of pages, separate from the main text of a book.
+They are controlled by the following @code{\paper} variables:
+
+@itemize
+@item @code{oddHeaderMarkup}
+@item @code{evenHeaderMarkup}
+@item @code{oddFooterMarkup}
+@item @code{evenFooterMarkup}
+@end itemize
+
+These markup variables can only access text fields from top-level
+@code{\header} blocks (which apply to all scores in the book) and are
+defined in @file{ly/titling-init.ly}. By default:
+
+@itemize
+
+@item
+page numbers are automatically placed on the top far left (if even) or
+top far right (if odd), starting from the second page.
+
+@item
+the @code{instrument} text field is placed in the center of every
+page, starting from the second page.
+
+@item
+the @code{copyright} text is centered on the bottom of the first page.
+
+@item
+the @code{tagline} is centered on the bottom of the last page, and below
+the @code{copyright} text if there is only a single page.
+
+@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.
+
+@lilypond[papersize=a8landscape,verbatim]
+\book {
+ \header {
+ tagline = "... music notation for Everyone"
}
\score {
- { c'1 }
- \header {
- piece = "piece2"
- opus = "opus2"
+ \relative c' {
+ c4 d e f
}
}
}
@end lilypond
-As demonstrated before, you can use multiple @code{\header} blocks.
-When same fields appear in different blocks, the latter is used.
-Here is a short example.
+To remove the @code{tagline} set the value to @code{##f}.
-@example
-\header @{
- composer = "Composer"
-@}
-\header @{
- piece = "Piece"
-@}
-\score @{
- \new Staff @{ c'4 @}
- \header @{
- piece = "New piece" % overwrite previous one
- @}
-@}
-@end example
-If you define the @code{\header} inside the @code{\score} block, then
-normally only the @code{piece} and @code{opus} headers will be printed.
-Note that the music expression must come before the @code{\header}.
+@node Custom headers footers and titles
+@subsection Custom headers footers and titles
+
+@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 layout for headers and footers::
+@end menu
+
+
+@node Custom text formatting for title blocks
+@unnumberedsubsubsec Custom text formatting for title blocks
+
+Standard @code{\markup} commands can be used to customize any header,
+footer and title text within the @code{\header} block.
-@lilypond[quote,verbatim,line-width=11.0\cm]
+@lilypond[quote,verbatim,noragged-right]
\score {
- { c'4 }
+ { s1 }
\header {
- title = "title" % not printed
- piece = "piece"
- opus = "opus"
+ piece = \markup { \fontsize #4 \bold "PRAELUDIUM I" }
+ subtitle = \markup { \italic "(Excerpt)" }
}
}
@end lilypond
-@funindex print-all-headers
-@noindent
-You may change this behavior (and print all the headers when defining
-@code{\header} inside @code{\score}) by using
+@seealso
+Notation Reference:
+@ref{Formatting text}.
-@example
-\paper@{
- print-all-headers = ##t
-@}
-@end example
-@cindex copyright
-@cindex tagline
+@node Custom layout for title blocks
+@unnumberedsubsubsec Custom layout for title blocks
+
+@code{\markup} commands in the @code{\header} block are useful for
+simple text formatting, but they do not allow precise control over the
+placement of titles. To customize the placement of the text fields,
+use either or both of the following @code{\paper} variables:
+
+@itemize
+@item @code{bookTitleMarkup}
+@item @code{scoreTitleMarkup}
+@end itemize
-The default footer is empty, except for the first page, where the
-@code{copyright} field from @code{\header} is inserted, and the last
-page, where @code{tagline} from @code{\header} is added. The default
-tagline is @qq{Music engraving by LilyPond (@var{version})}.@footnote{Nicely
-printed parts are good PR for us, so please leave the tagline if you
-can.}
+These markup variables are discussed in
+@ref{Default layout of book and score title blocks}.
-Headers may be completely removed by setting them to false.
+The default settings for @code{scoreTitleMarkup} as defined in
+@file{ly/titling-init.ly} are:
@example
-\header @{
- tagline = ##f
- composer = ##f
+scoreTitleMarkup = \markup @{ \column @{
+ \on-the-fly #print-all-headers @{ \bookTitleMarkup \hspace #1 @}
+ \fill-line @{
+ \fromproperty #'header:piece
+ \fromproperty #'header:opus
+ @}
+@}
@}
@end example
+This places the @code{piece} and @code{opus} text fields at opposite
+ends of the same line:
-@node Custom headers footers and titles
-@subsection Custom headers, footers, and titles
+@lilypond[quote,verbatim,noragged-right]
+\score {
+ { s1 }
+ \header {
+ piece = "PRAELUDIUM I"
+ opus = "BWV 846"
+ }
+}
+@end lilypond
-A more advanced option is to change the definitions of the following
-variables in the @code{\paper} block. The init file
-@file{../ly/titling-init.ly} lists the default layout.
+This example redefines @code{scoreTitleMarkup} so that the @code{piece}
+text field is centered and in a large, bold font.
-@table @code
-@funindex bookTitleMarkup
-@item bookTitleMarkup
- This is the title added at the top of the entire output document.
-Typically, it has the composer and the title of the piece
+@lilypond[papersize=a5,quote,verbatim,noragged-right]
+\book {
+ \paper {
+ indent = 0\mm
+ scoreTitleMarkup = \markup {
+ \fill-line {
+ \null
+ \fontsize #4 \bold \fromproperty #'header:piece
+ \fromproperty #'header:opus
+ }
+ }
+ }
+ \header { tagline = ##f }
+ \score {
+ { s1 }
+ \header {
+ piece = "PRAELUDIUM I"
+ opus = "BWV 846"
+ }
+ }
+}
+@end lilypond
-@funindex scoreTitleMarkup
-@item scoreTitleMarkup
- This is the title put over a @code{\score} block. Typically, it has
-the name of the movement (@code{piece} field).
+Text fields normally reserved for the main title block can be included
+in individual score title blocks with the @code{print-all-headers}
+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}.
-@funindex oddHeaderMarkup
-@item oddHeaderMarkup
- This is the page header for odd-numbered pages.
+To avoid this, add the desired text field to the @code{scoreTitleMarkup}
+definition. In the following example, the @code{composer} text field
+(normally associated with @code{bookTitleMarkup}) is added to
+@code{scoreTitleMarkup}, allowing each score to list a different
+composer:
-@funindex evenHeaderMarkup
-@item evenHeaderMarkup
- This is the page header for even-numbered pages. If unspecified,
- the odd header is used instead.
+@lilypond[papersize=a5,quote,verbatim,noragged-right]
+\book {
+ \paper {
+ indent = 0\mm
+ scoreTitleMarkup = \markup {
+ \fill-line {
+ \null
+ \fontsize #4 \bold \fromproperty #'header:piece
+ \fromproperty #'header:composer
+ }
+ }
+ }
+ \header { tagline = ##f }
+ \score {
+ { s1 }
+ \header {
+ piece = "MENUET"
+ composer = "Christian Petzold"
+ }
+ }
+ \score {
+ { s1 }
+ \header {
+ piece = "RONDEAU"
+ composer = "François Couperin"
+ }
+ }
+}
+@end lilypond
- By default, headers are defined such that the page number is on the
- outside edge, and the instrument is centered.
+It is also possible to create your own custom text fields, and refer to
+them in the markup definition.
-@funindex oddFooterMarkup
-@item oddFooterMarkup
- This is the page footer for odd-numbered pages.
+@lilypond[papersize=a5,quote,verbatim,noragged-right]
+\book {
+ \paper {
+ indent = 0\mm
+ scoreTitleMarkup = \markup {
+ \fill-line {
+ \null
+ \override #`(direction . ,UP) {
+ \dir-column {
+ \center-align \fontsize #-1 \bold
+ \fromproperty #'header:mycustomtext %% User-defined field
+ \center-align \fontsize #4 \bold
+ \fromproperty #'header:piece
+ }
+ }
+ \fromproperty #'header:opus
+ }
+ }
+ }
+ \header { tagline = ##f }
+ \score {
+ { s1 }
+ \header {
+ piece = "FUGA I"
+ mycustomtext = "A 4 VOCI" %% User-defined field
+ opus = "BWV 846"
+ }
+ }
+}
+@end lilypond
-@funindex evenFooterMarkup
-@item evenFooterMarkup
- This is the page footer for even-numbered pages. If unspecified,
- the odd header is used instead.
+@seealso
+Notation Reference:
+@ref{Title blocks explained}.
- By default, the footer has the copyright notice on the first, and
- the tagline on the last page.
-@end table
+@node Custom layout for headers and footers
+@unnumberedsubsubsec Custom layout for headers and footers
-@cindex \paper
-@cindex header
-@cindex footer
-@cindex page layout
-@cindex titles
+@c can make-header and make-footer be removed from
+@c paper-defaults-init.ly? -mp
-The following definition will put the title flush left, and the
-composer flush right on a single line.
+@code{\markup} commands in the @code{\header} block are useful for
+simple text formatting, but they do not allow precise control over the
+placement of headers and footers. To customize the placement of
+the text fields, use either or both of the following @code{\paper}
+variables:
-@example
-\paper @{
- bookTitleMarkup = \markup @{
- \fill-line @{
- \fromproperty #'header:title
- \fromproperty #'header:composer
- @}
- @}
-@}
-@end example
+@itemize
+@item @code{oddHeaderMarkup}
+@item @code{evenHeaderMarkup}
+@item @code{oddFooterMarkup}
+@item @code{evenFooterMarkup}
+@end itemize
-The header and footer are created by the functions
-@code{make-header} and @code{make-footer}, defined in
-@code{\paper}. The default implementations are in
-@file{ly/paper-defaults-init.ly} and
-@file{ly/titling-init.ly}.
+The following example centers page numbers at the bottom of every
+page. First, the default settings for @code{oddHeaderMarkup} and
+@code{evenHeaderMarkup} are removed by defining each as a @emph{null}
+markup. Then, @code{oddFooterMarkup} is redefined with the page
+number centered. Finally, @code{evenFooterMarkup} is given the
+same layout by defining it as @code{\oddFooterMarkup}:
-This example centers page numbers at the bottom of every page.
+@lilypond[papersize=a8,quote,verbatim,noragged-right]
+\book {
+ \paper {
+ print-page-number = ##t
+ print-first-page-number = ##t
+ oddHeaderMarkup = \markup \null
+ evenHeaderMarkup = \markup \null
+ oddFooterMarkup = \markup {
+ \fill-line {
+ \on-the-fly #print-page-number-check-first
+ \fromproperty #'page:page-number-string
+ }
+ }
+ evenFooterMarkup = \oddFooterMarkup
+ }
+ \score {
+ \new Staff { s1 \break s1 \break s1 }
+ }
+}
+@end lilypond
-@example
-\paper @{
- print-page-number = ##t
- print-first-page-number = ##t
- oddHeaderMarkup = \markup \fill-line @{ " " @}
- evenHeaderMarkup = \markup \fill-line @{ " " @}
- oddFooterMarkup = \markup @{
- \fill-line @{
- \bold \fontsize #3
- \on-the-fly #print-page-number-check-first
- \fromproperty #'page:page-number-string
- @}
- @}
- evenFooterMarkup = \markup @{
- \fill-line @{
- \bold \fontsize #3
- \on-the-fly #print-page-number-check-first
- \fromproperty #'page:page-number-string
- @}
- @}
-@}
-@end example
+@seealso
+Notation Reference:
+@ref{Title blocks explained},
+@ref{Default layout of book and score title blocks}.
@node Reference to page numbers
referred to in a markup, to get the number of the page where the marked
point is placed, using the @code{\page-ref} markup command.
-@lilypond[verbatim,line-width=11.0\cm]
+@lilypond[verbatim]
\header { tagline = ##f }
\book {
\label #'firstScore
c'1
}
}
-
\markup { The first score begins on page \page-ref #'firstScore "0" "?" }
\markup { Mark A is on page \page-ref #'markA "0" "?" }
}
}
@end lilypond
+Dots can be added to fill the line between an item and its page number:
+
+@lilypond[verbatim,quote]
+\header { tagline = ##f }
+\paper {
+ tocItemMarkup = \tocItemWithDotsMarkup
+}
+
+\book {
+ \markuplines \table-of-contents
+ \tocItem \markup { Allegro }
+ \tocItem \markup { Largo }
+ \markup \null
+}
+@end lilypond
+
@seealso
Init files: @file{../ly/toc-init.ly}.
* Including LilyPond files::
* Different editions from one source::
* Text encoding::
-* Displaying LilyPond notation::
@end menu
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
-@code{-drelative-includes} option at the command line
+@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
@menu
* Using variables::
* Using tags::
+* Using global settings::
@end menu
@node Using variables
@end ignore
+@node Using global settings
+@unnumberedsubsubsec Using global settings
+
+@cindex include-settings
+
+Global settings can be included from a separate file:
+
+@example
+lilypond -dinclude-settings=MY_SETTINGS.ly MY_SCORE.ly
+@end example
+
+Groups of settings such as page size, font or type face can be stored
+in separate files. This allows different editions from the same score
+as well as standard settings to be applied to many scores, simply by
+specifying the proper settings file.
+
+This technique also works well with the use of style sheets, as
+discussed in @rlearning{Style sheets}.
+
+@seealso
+Learning Manual:
+@rlearning{Organizing pieces with variables},
+@rlearning{Style sheets}.
+
+Notation Reference:
+@ref{Including LilyPond files}.
+
@node Text encoding
@subsection Text encoding
}
\addlyrics { O \markup { \concat { Ph \char ##x0153 be! } } }
}
-\markup { "Copyright 2008--2010" \char ##x00A9 }
+\markup { "Copyright 2008--2011" \char ##x00A9 }
@end lilypond
@cindex copyright sign
@}
@end example
-@node Displaying LilyPond notation
-@subsection Displaying LilyPond notation
-
-@funindex \displayLilyMusic
-Displaying a music expression in LilyPond notation can be
-done with the music function @code{\displayLilyMusic} but only when
-using the command line. For example,
-
-@example
-@{
- \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
-@}
-@end example
-
-will display
-
-@example
-@{ a,4 cis e fis g @}
-@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@}},
-redirect the output to a file.
-
-@example
-lilypond file.ly >display.txt
-@end example
-
@node Controlling output
rhythmic-locations to the list.
In order to use this feature, LilyPond must be invoked with
-@code{-dclip-systems}. The clips are output as EPS files, and are
+@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}.
Download and extract the zip file. Copy the @code{lilyfonts}
directory to @file{@var{SHARE_DIR}/lilypond/current}; for more
-information, see @rlearning{Other sources of information}.
-Move the existing @code{fonts} directory to @code{fonts_orig} and
-move the @code{lilyfonts} directory to @code{fonts}. Simply move
-@code{fonts_orig} back to @code{fonts} to revert back to Feta.
+information, see @rlearning{Other sources of information}. Rename the
+existing @code{fonts} directory to @code{fonts_orig} and the
+@code{lilyfonts} directory to @code{fonts}. To revert back to Feta,
+reverse the process.
@seealso
Learning Manual: @rlearning{Other sources of information}.
@knownissues
-
-Gonville cannot be used to typeset @q{Ancient Music} notation. Please
-refer to the author's website for more information on this and other
-specifics including licensing of Gonville.
+Gonville cannot be used to typeset @q{Ancient Music} notation and it is
+likely newer glyphs in later releases of LilyPond may not exist in the
+Gonville font family. Please refer to the author's website for more
+information on these and other specifics, including licensing of
+Gonville.
@node MIDI output
that are off or accidentals that were mistyped stand out very much
when listening to the MIDI output.
+Standard MIDI oputput is somewhat crude; optionally, an enhanced and
+more realistic MIDI output is available by means of
+@ref{The Articulate script}.
+
@c TODO Check this
The midi output allocates a channel for each staff, and one for global
settings. Therefore the midi file should not have more than 15 staves
* Repeats in MIDI::
* Controlling MIDI dynamics::
* Percussion in MIDI::
+* The Articulate script::
@end menu
@node Creating MIDI files
@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
The following items of notation are reflected in the MIDI output:
@item Lyrics
@end itemize
+Using @ref{The Articulate script}, a number of items are added to the
+above list:
+
+@itemize
+@item Articulations (slurs, staccato, etc)
+@item Trills, turns
+@item Rallentando and accelerando
+@end itemize
+
+
@unnumberedsubsubsec Unsupported in MIDI
@c TODO index as above
-The following items of notation have no effect on the MIDI output:
+The following items of notation have no effect on the MIDI output,
+unless you use @ref{The Articulate script}:
@itemize
@item Rhythms entered as annotations, e.g. swing
\bar "|."
@end lilypond
+In scores containing multiple voices, unfolding of repeats in MIDI
+output will only occur correctly if @emph{each} voice contains fully
+notated repeat indications.
+
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,
Because the general MIDI standard does not contain rim shots, the
sidestick is used for this purpose instead.
+@node The Articulate script
+@subsection The Articulate script
+
+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.
+
+To use the Articulate script, you have to include it at the top of
+your input file,
+
+@example
+\include "articulate.ly"
+@end example
+
+and in the @code{\score} section do
+
+@example
+\unfoldRepeats \articulate <<
+ all the rest of the score...
+>>
+@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.
+
+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}.
+
+@knownissues
+
+Articulate shortens chords and some music (esp. organ music) could
+sound worse.
+
+
+@node Extracting musical information
+@section Extracting musical information
+
+In addition to creating graphical output and MIDI, LilyPond can
+display musical information as text.
+
+@menu
+* Displaying LilyPond notation::
+* Displaying scheme music expressions::
+* Saving music events to a file::
+@end menu
+
+@node Displaying LilyPond notation
+@subsection Displaying LilyPond notation
+
+@funindex \displayLilyMusic
+Displaying a music expression in LilyPond notation can be
+done with the music function @code{\displayLilyMusic} but only when
+using the command line. For example,
+
+@example
+@{
+ \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
+@}
+@end example
+
+will display
+
+@example
+@{ a,4 cis e fis g @}
+@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@}},
+redirect the output to a file.
+
+@example
+lilypond file.ly >display.txt
+@end example
+
+
+@node Displaying scheme music expressions
+@subsection Displaying scheme music expressions
+
+See @rextend{Displaying music expressions}.
+
+
+@node Saving music events to a file
+@subsection Saving music events to a file
+
+Music events can be saved to a file on a per-staff basis by
+including a file in your main score.
+
+@example
+\include "event-listener.ly"
+@end example
+
+This will create file(s) called @file{FILENAME-STAFFNAME.notes} or
+@file{FILENAME-unnamed-staff.notes} for each staff. Note that if
+you have multiple unnamed staves, the events for all staves will
+be mixed together in the same file. The output looks like this:
+
+@example
+0.000 note 57 4 p-c 2 12
+0.000 dynamic f
+0.250 note 62 4 p-c 7 12
+0.500 note 66 8 p-c 9 12
+0.625 note 69 8 p-c 14 12
+0.750 rest 4
+0.750 breathe
+@end example
+
+The syntax is a tab-delimited line, with two fixed fields on each
+line followed by optional parameters.
+
+@example
+@var{time} @var{type} @var{...params...}
+@end example
+
+This information can easily be read into other programs such as
+python scripts, and can be very useful for researchers wishing to
+perform musical analysis or playback experiments with LilyPond.
+
+
+@knownissues
+Not all lilypond music events are supported by
+@file{event-listener.ly}. It is intended to be a well-crafted
+@qq{proof of concept}. If some events that you want to see are
+not included, copy @file{event-listener.ly} into your lilypond
+directory and modify the file so that it outputs the information
+you want.
projects / lilypond.git / blobdiff