Guide, node Updating translation committishes..
@end ignore
-@c \version "2.17.6"
+@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
}
\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 |
tagline = "... music notation for Everyone"
}
\score {
- \relative c' {
- c4 d e f
+ \relative {
+ c'4 d e f
}
}
}
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
}
}
}
tocAct =
-#(define-music-function (parser location text) (markup?)
+#(define-music-function (text) (markup?)
(add-toc-item! 'tocActMarkup text))
@end verbatim
}
tocAct =
-#(define-music-function (parser location text) (markup?)
+#(define-music-function (text) (markup?)
(add-toc-item! 'tocActMarkup text))
\book {
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
@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}.
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;
+ names is included;
music tagged with any other tag name is excluded.
@item
Tagged music preceded by @code{\removeWithTag #'@var{name}} 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
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:
+
+@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
@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:
à 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 ouput file for each line will be
+generated.
+
+@seealso
+Notation Reference:
+@ref{The layout block}.
-More clip regions can be defined by adding more pairs of
-rhythmic-locations to the list.
+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
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.
-
-Standard MIDI output is somewhat crude; optionally, an enhanced and
-more realistic MIDI output is available by means of
-@ref{The Articulate script}.
+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.
-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 Instruments::
-* 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::
+* Enhancing MIDI output::
@end menu
-@node Creating MIDI files
-@subsection Creating MIDI files
+@cindex MIDI, Supported notation
-@cindex MIDI block
-To create a MIDI output file from a LilyPond file, insert a @code{\midi}
-block inside a @code{\score} block;
-
-@example
-\score @{
- @var{@dots{}music@dots{}}
- \layout @{ @}
- \midi @{ @}
-@}
-@end example
+@node Supported notation for MIDI
+@subsection Supported notation for MIDI
-If there is @emph{only} a @code{\midi} block in a @code{\score} (i.e.
-without any @code{\layout} block), then @emph{only} MIDI output will be
-produced. No musical notation will be typeset.
+The following musical notation can be used with LilyPond's default
+capabilities to produce MIDI output;
-@example
-\score @{
- @var{@dots{}music@dots{}}
- \midi @{ @}
-@}
-@end example
-
-Dynamics, pitches, rhythms, tempo changes and ties are all interpreted
-and translated correctly. Dynamic @q{marks} translate into volume
-levels with a @q{fixed fraction} of the available MIDI volume range;
-crescendi and decrescendi make the volume vary linearly between their
-two extremes.
+@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
-All @code{\tempo} indications, including all subsequent tempo changes,
-specified within the music notation will be reflected in the MIDI
-output.
+When combined with the @file{articulate} script the following,
+additional musical notation can be output to MIDI;
-Usually it is enough to leave the @code{\midi} block empty, but it
-can contain context rearrangements, new context definitions or code
-to set the values of properties. Here the tempo is set to 72
-quarter-note beats per minute, but @emph{only} for the MIDI's
-audio playback.
+@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{@dots{}music@dots{}}
- \midi @{
- \tempo 4 = 72
- @}
-@}
+\appoggiatura c8 d2.
@end example
-Note that @code{\tempo} is actually a command for setting properties
-during the interpretation of the music and in the context of output definitions, like a @code{\midi} block, is reinterpreted as if it
-were a context modification.
+@noindent
+The c will take the value of a crotchet.
-@cindex MIDI context definitions
+@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
-Context definitions follow the same syntax as those in a @code{\layout}
-block;
+@noindent
+See @ref{Enhancing MIDI output}.
-@example
-\score @{
- @var{@dots{}music@dots{}}
- \midi @{
- \context @{
- \Voice
- \remove "Dynamic_performer"
- @}
- @}
-@}
-@end example
+@cindex MIDI, Unsupported notation
-removes the effect of dynamics from the MIDI output. Translation
-modules for sound are called @q{performers}.
+@node Unsupported notation for MIDI
+@subsection Unsupported notation for MIDI
+The following items of musical notation cannot be output to MIDI;
-@snippets
+@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
-@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
-{changing-midi-output-to-one-channel-per-voice.ly}
-@knownissues
+@node The MIDI block
+@subsection The MIDI block
-Some operating systems require a @emph{specific} file extension for
-MIDI files. 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;
+@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
-#(ly:set-option 'midi-extension "mid")
+\score @{
+ @var{@dots{} music @dots{}}
+ \layout @{ @}
+ \midi @{ @}
+@}
@end example
-This will set the default extension for MIDI files to @code{.mid}.
+@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.}
-Alternatively, an option can be supplied on the command line:
+The default output file extension (@code{.midi}) can be changed by using
+the @code{-dmidi-extension} option with the @code{lilypond} command:
@example
lilypond -dmidi-extension=mid MyFile.ly
@end example
-Changes in the MIDI volume take place only on starting a note, so
-crescendi and decrescendi cannot affect the volume of a single note.
+Alternatively, add the following Scheme expression before the start of
+either the @code{\book}, @code{\bookpart} or @code{\score} blocks. See
+@ref{File structure}.
-Some MIDI players may not always correctly handle tempo changes in the
-midi output.
+@example
+#(ly:set-option 'midi-extension "mid")
+@end example
@seealso
-Installed Files:
-@file{../ly/performer-init.ly}.
-
-Learning Manual:
-@rlearning{Other sources of information}.
-
-
-@node MIDI Instruments
-@subsection MIDI Instruments
-
-@cindex instrument names
-@cindex MIDI, instruments
-@funindex Staff.midiInstrument
-
-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}.
+Notation Reference:
+@ref{File structure}.
-@example
-\new Staff @{
- \set Staff.midiInstrument = #"glockenspiel"
- @var{@dots{}notes@dots{}}
-@}
-@end example
+Installed Files:
+@file{scm/midi.scm}.
-@example
-\new Staff \with @{midiInstrument = #"cello"@} @{
- @var{@dots{}notes@dots{}}
-@}
-@end example
+@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.
-If the selected instrument does not exactly match an instrument from
-the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
-instrument is used.
+@node Controlling MIDI dynamics
+@subsection Controlling MIDI dynamics
-@node What goes into the MIDI output?
-@subsection What goes into the MIDI output?
+It is possible to control the overall MIDI volume, the relative volume
+of dynamic markings and the relative volume of different instruments.
-@c TODO Check grace notes - timing is suspect?
+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.
@menu
-* Supported in MIDI::
-* Unsupported in MIDI::
+* Dynamic marks in MIDI::
+* Setting MIDI volume::
+* Setting MIDI block properties::
@end menu
-@node Supported in MIDI
-@unnumberedsubsubsec Supported in MIDI
-
-@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
-
-The following items of notation are reflected in the MIDI output:
-
-@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
-
-Using @ref{The Articulate script}, a number of items are added to the
-above list:
+@cindex MIDI volume
+@cindex MIDI equalization
+@cindex MIDI dynamics
+@cindex Dynamics in MIDI
-@itemize
-@item Articulations (slurs, staccato, etc)
-@item Trills, turns
-@item Rallentando and accelerando
-@end itemize
+@node Dynamic marks in MIDI
+@unnumberedsubsubsec Dynamic marks in MIDI
-@node Unsupported in MIDI
-@unnumberedsubsubsec Unsupported 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}.
-@c TODO index as above
-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
-@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
-
-
-@node Repeats in MIDI
-@subsection Repeats in MIDI
-
-@cindex repeats in MIDI
-@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
-
-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,
-and percent repeats). For example,
-
-@example
-\score @{
- @var{@dots{}music@dots{}}
- \layout @{ @dots{} @}
-@}
-\score @{
- \unfoldRepeats @var{@dots{}music@dots{}}
- \midi @{ @dots{} @}
-@}
-@end example
-
-@node Controlling MIDI dynamics
-@subsection Controlling MIDI dynamics
-
-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.
-
-@menu
-* Dynamic marks::
-* Overall MIDI volume::
-* Equalizing different instruments (i)::
-* Equalizing different instruments (ii)::
-@end menu
+@snippets
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
+{creating-custom-dynamics-in-midi-output.ly}
-@node Dynamic marks
-@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.
+Installed Files:
+@file{ly/script-init.ly}
+@file{scm/midi.scm}.
-@lilypond[verbatim,quote]
-#(define (myDynamics dynamic)
- (if (equal? dynamic "rfz")
- 0.9
- (default-dynamic-absolute-volume dynamic)))
+Snippets:
+@rlsr{MIDI}.
-\score {
- \new Staff {
- \set Staff.midiInstrument = #"cello"
- \set Score.dynamicAbsoluteVolumeFunction = #myDynamics
- \new Voice {
- \relative c'' {
- a4\pp b c-\rfz
- }
- }
- }
- \layout {}
- \midi {}
-}
-@end lilypond
+Internals Reference:
+@rinternals{Dynamic_performer}.
-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.
-@node Overall MIDI volume
-@unnumberedsubsubsec Overall MIDI volume
+@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
@end example
In the following example the dynamic range of the overall MIDI
-volume is limited to the range 0.2 - 0.5.
+volume is limited to the range @code{0.2} - @code{0.5}.
-@lilypond[verbatim,quote]
-\score {
+@example
+\score @{
<<
- \new Staff {
- \key g \major
- \time 2/2
+ \new Staff @{
\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
+ @var{@dots{} music @dots{}}
+ @}
+ \new Staff @{
\set Staff.midiInstrument = #"clarinet"
- \new Voice \relative c'' {
- b1\p a2. b8 a
- g2. fis8 e
- fis2 r
- }
- }
+ @var{@dots{} music @dots{}}
+ @}
>>
- \layout {}
- \midi {
- \tempo 2 = 72
- \context {
+ \midi @{
+ \context @{
\Score
midiMinimumVolume = #0.2
midiMaximumVolume = #0.5
- }
- }
-}
-@end lilypond
+ @}
+ @}
+@}
+@end example
-@node Equalizing different instruments (i)
-@unnumberedsubsubsec Equalizing different instruments (i)
+Simple MIDI instrument equalization can be achieved by setting
+@code{midiMinimumVolume} and @code{midiMaximumVolume} properties within
+the @code{Staff} context.
-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.
+@example
+\score @{
+ \new Staff @{
+ \set Staff.midiInstrument = #"flute"
+ \set Staff.midiMinimumVolume = #0.7
+ \set Staff.midiMaximumVolume = #0.9
+ @var{@dots{} music @dots{}}
+ @}
+ \midi @{ @}
+@}
+@end example
-In this example the volume of the clarinet is reduced relative
-to the volume of the flute.
+For scores with multiple staves and multiple MIDI instruments, the
+relative volumes of each instrument can be set individually;
-@lilypond[verbatim,quote]
-\score {
+@example
+\score @{
<<
- \new Staff {
- \key g \major
- \time 2/2
+ \new Staff @{
\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
+ @var{@dots{} music @dots{}}
+ @}
+ \new Staff @{
\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
- }
- }
+ @var{@dots{} music @dots{}}
+ @}
>>
- \layout {}
- \midi {
- \tempo 2 = 72
- }
-}
-@end lilypond
+ \midi @{ @}
+@}
+@end example
+In this example the volume of the clarinet is reduced relative to the
+volume of the flute.
-@node Equalizing different instruments (ii)
-@unnumberedsubsubsec Equalizing different instruments (ii)
+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}.
-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}.
+Installed Files:
+@file{scm/midi.scm}.
-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.
+@seealso
+Notation Reference:
+@ref{Score layout}.
-The following example sets the relative flute and clarinet volumes
-to the same values as the previous example.
+Internals Reference:
+@rinternals{Dynamic_performer}.
-@lilypond[verbatim,quote]
-#(define my-instrument-equalizer-alist '())
+@snippets
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
+{replacing-default-midi-instrument-equalization.ly}
-#(set! my-instrument-equalizer-alist
- (append
- '(
- ("flute" . (0.7 . 0.9))
- ("clarinet" . (0.3 . 0.6)))
- my-instrument-equalizer-alist))
+@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.
-#(define (my-instrument-equalizer s)
- (let ((entry (assoc s my-instrument-equalizer-alist)))
- (if entry
- (cdr entry))))
-\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
+@node Setting MIDI block properties
+@unnumberedsubsubsec Setting MIDI block properties
-@ignore
-@c Delete when satisfied this is adequately covered elsewhere -td
+The @code{\midi} block can contain context rearrangements, new context
+definitions or code that sets the values of certain properties.
-@n ode Microtones in MIDI
-@s ubsection Microtones in MIDI
+@example
+\score @{
+ @var{@dots{} music @dots{}}
+ \midi @{
+ \tempo 4 = 72
+ @}
+@}
+@end example
-@cindex microtones in MIDI
+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.
-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.
+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.
-@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
+@cindex MIDI context definitions
+@cindex context definitions with MIDI
+Context definitions follow the same syntax as those in a @code{\layout}
+block;
-@node Percussion in MIDI
-@subsection Percussion in MIDI
+@example
+\score @{
+ @var{@dots{} music @dots{}}
+ \midi @{
+ \context @{
+ \Voice
+ \remove "Dynamic_performer"
+ @}
+ @}
+@}
+@end example
-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.
+This example removes the effect of dynamics from the MIDI output. Note:
+LilyPond's translation modules used for sound are called @q{performers}.
-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.
+@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}.
-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.
+Notation Reference:
+@ref{Expressive marks},
+@ref{Score layout}.
+
+Installed Files:
+@file{ly/performer-init.ly}.
-@c TODO Expand with examples, and any other issues
+Snippets:
+@rlsr{MIDI}.
+
+Internals Reference:
+@rinternals{Dynamic_performer}.
@knownissues
+Some MIDI players do not always correctly handle tempo changes in the
+midi output.
-Because the general MIDI standard does not contain rim shots, the
-sidestick is used for this purpose instead.
+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.
-@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,
+@node Using MIDI instruments
+@subsection Using MIDI instruments
+
+MIDI instruments are set using the @code{midiInstrument} property within
+a @code{Staff} context.
@example
-\include "articulate.ly"
+\score @{
+ \new Staff @{
+ \set Staff.midiInstrument = #"glockenspiel"
+ @var{@dots{} music @dots{}}
+ @}
+ \midi @{ @}
+@}
@end example
-and in the @code{\score} section do
+or
@example
-\unfoldRepeats \articulate <<
- all the rest of the score@dots{}
->>
+\score @{
+ \new Staff \with @{midiInstrument = #"cello"@} @{
+ @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.
+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}.
-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}.
+
+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
+
+Repeats can be represented in the MIDI output by applying the
+@code{\unfoldRepeats} command.
+
+@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
+
+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{@dots{} music @dots{}}
+ \layout @{ @}
+@}
+\score @{
+ \unfoldRepeats @{
+ @var{@dots{} music @dots{}}
+ @}
+ \midi @{ @}
+@}
+@end example
+
+When using multiple voices, each of the voices must contain completely
+unfolded repeats for correct MIDI output.
+
+@seealso
+Notation Reference:
+@ref{Repeats}.
+
+
+@node Enhancing MIDI output
+@subsection Enhancing MIDI output
+
+@menu
+* The articulate script::
+@end menu
+
+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.
+
+@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
+
+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
+\score @{
+ \articulate <<
+ @var{@dots{} music @dots{}}
+ >>
+ \midi @{ @}
+@}
+@end example
+
+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}.
+
+@seealso
+Learning Manual:
+@rlearning{Other sources of information}.
+
+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
+compenstate 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
projects / lilypond.git / blobdiff