Guide, node Updating translation committishes..
@end ignore
-@c \version "2.19.2"
+@c \version "2.19.22"
@node General input and output
@chapter General input and output
@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 titles headers and footers::
+* Creating PDF metadata::
* Creating footnotes::
* Reference to page numbers::
* Table of contents::
}
\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 |
\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 }
@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=a6landscape,quote,verbatim,noragged-right]
\book {
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
-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 titles headers and footers
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
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
@lilypond[quote,verbatim,papersize=a8landscape]
\book {
\header { tagline = ##f }
- \relative c'' {
- a4_\footnote #'(0 . -1) "A slur forced down" (
+ \relative {
+ a'4_\footnote #'(0 . -1) "A slur forced down" (
b8^\footnote #'(1 . 0.5) "A manual beam forced up" [
b8 ]
c4 )
\auto-footnote "recent" \italic " Aug 2012"
"composition."
}
- \relative c' {
+ \relative {
a'4 b8 e c4 d
}
}
}
"composition."
}
- \relative c' {
+ \relative {
a'4 b8 e c4 d
}
}
}
"composition."
}
- \relative c' {
+ \relative {
a'4 b8 e c4 d
}
}
@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 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;
-In the following example, a new style is defined for entering act names
-in the table of contents of an opera:
+@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;
+
+@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:
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, }
+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
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
@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! } } }
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
* Controlling MIDI dynamics::
* Using MIDI instruments::
* Using repeats with MIDI::
+* MIDI channel mapping::
+* Context properties for MIDI effects::
* Enhancing MIDI output::
@end menu
@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;
@}
@end example
-@warning{ A @code{\score} block that, as well as the music, contains
-only a @code{\midi} block (i.e. @emph{without} the @code{\layout}
+@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.}
This example removes the effect of dynamics from the MIDI output. Note:
LilyPond's translation modules used for sound are called @q{performers}.
-@snippets
-@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
-{changing-midi-output-to-one-channel-per-voice.ly}
-
@seealso
Learning Manual:
@rlearning{Other sources of information}.
@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:
+
+@table @var
+
+@item @code{'staff}
+
+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.
+
+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.
+
+@item @code{'instrument}
+
+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 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.
+
+@item @code{'voice}
+
+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.
+
+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.
+
+@end table
+
+For example, the default MIDI channel mapping of a score can be changed
+to the @code{'instrument} setting as shown:
+
+@example
+\score @{
+ ...music...
+ \midi @{
+ \context @{
+ \Score
+ midiChannelMapping = #'instrument
+ @}
+ @}
+@}
+@end example
+
+@snippets
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
+{changing-midi-output-to-one-channel-per-voice.ly}
+
+
+@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:
+
+@table @var
+
+@item @code{Staff.midiPanPosition}
+
+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.
+
+@item @code{Staff.midiBalance}
+
+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.
+
+@item @code{Staff.midiExpression}
+
+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).
+
+@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.
+
+The expression level ranges from 0.0 (no expression, meaning zero
+volume) to 1.0 (full expression).
+
+@item @code{Staff.midiReverbLevel}
+
+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).
+
+@item @code{Staff.midiChorusLevel}
+
+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).
+
+@end table
+
+
+@knownissues
+
+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
projects / lilypond.git / blobdiff