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
* 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
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
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::
+* MIDI channel mapping::
+* Context properties for MIDI effects::
+* Enhancing MIDI output::
@end menu
-@node Creating MIDI files
-@subsection Creating MIDI files
+@cindex MIDI, Supported notation
-@cindex MIDI block
-To create a MIDI output file from a LilyPond file, insert a @code{\midi}
-block inside a @code{\score} block;
+@node Supported notation for MIDI
+@subsection Supported notation for MIDI
+
+The following musical notation can be used with LilyPond's default
+capabilities to produce MIDI output;
+
+@itemize
+@item Breath marks
+@item Chords entered as chord names
+@item Crescendi, decrescendi over multiple notes. The volume is altered
+linearly between the two extremes
+@item Dynamic markings from @code{ppppp} to @code{fffff}, including
+@code{mp}, @code{mf} and @code{sf}
+@item Microtones but @emph{not} microtonal chords. A MIDI player that
+supports pitch bending will also be required.
+@item Lyrics
+@item Pitches
+@item Rhythms entered as note durations, including tuplets
+@item @q{Simple} articulations; staccato, staccatissimo, accent, marcato
+and portato
+@item Tempo changes using the @code{\tempo} function
+@item Ties
+@item Tremolos that are @emph{not} entered with a
+@q{@code{:}[@var{number}]} value
+@end itemize
+
+Panning, balance, expression, reverb and chorus effects can also be
+controlled by setting context properties,
+see @ref{Context properties for MIDI effects}.
+
+When combined with the @file{articulate} script the following,
+additional musical notation can be output to MIDI;
+
+@itemize
+@item Appogiaturas. These are made to take half the value of the note
+following (without taking dots into account). For example;
@example
-\score @{
- @var{@dots{}music@dots{}}
- \layout @{ @}
- \midi @{ @}
-@}
+\appoggiatura c8 d2.
@end example
-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.
+@noindent
+The c will take the value of a crotchet.
+
+@item Ornaments (i.e. mordents, trills and turns et al.)
+@item Rallentando, accelerando, ritardando and a tempo
+@item Slurs, including phrasing slurs
+@item Tenuto
+@end itemize
+
+@noindent
+See @ref{Enhancing MIDI output}.
+
+@cindex MIDI, Unsupported notation
+
+@node Unsupported notation for MIDI
+@subsection Unsupported notation for MIDI
+
+The following items of musical notation cannot be output to MIDI;
+
+@itemize
+@item Articulations other than staccato, staccatissimo, accent, marcato
+and portato
+@item Crescendi and decrescendi over a @emph{single} note
+@item Fermata
+@item Figured bass
+@item Glissandi
+@item Falls and doits
+@item Microtonal chords
+@item Rhythms entered as annotations, e.g. swing
+@item Tempo changes without @code{\tempo} (e.g. entered as annotations)
+@item Tremolos that @emph{are} entered with a @q{@code{:}[@var{number}]}
+value
+@end itemize
+
+
+@node The MIDI block
+@subsection The MIDI block
+
+@cindex MIDI block
+
+To create a MIDI output file from a LilyPond input file, insert a
+@code{\midi} block, which can be empty, within the @code{\score} block;
@example
\score @{
- @var{@dots{}music@dots{}}
+ @var{@dots{} music @dots{}}
+ \layout @{ @}
\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.
+@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.}
-All @code{\tempo} indications, including all subsequent tempo changes,
-specified within the music notation will be reflected in the MIDI
-output.
+The default output file extension (@code{.midi}) can be changed by using
+the @code{-dmidi-extension} option with the @code{lilypond} command:
-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.
+@example
+lilypond -dmidi-extension=mid MyFile.ly
+@end example
+
+Alternatively, add the following Scheme expression before the start of
+either the @code{\book}, @code{\bookpart} or @code{\score} blocks. See
+@ref{File structure}.
@example
-\score @{
- @var{@dots{}music@dots{}}
- \midi @{
- \tempo 4 = 72
- @}
-@}
+#(ly:set-option 'midi-extension "mid")
@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.
+@seealso
+Notation Reference:
+@ref{File structure}.
-@cindex MIDI context definitions
+Installed Files:
+@file{scm/midi.scm}.
-Context definitions follow the same syntax as those in a @code{\layout}
-block;
+@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.
-@example
-\score @{
- @var{@dots{}music@dots{}}
- \midi @{
- \context @{
- \Voice
- \remove "Dynamic_performer"
- @}
- @}
-@}
-@end example
-removes the effect of dynamics from the MIDI output. Translation
-modules for sound are called @q{performers}.
+@node Controlling MIDI dynamics
+@subsection Controlling MIDI dynamics
-@snippets
-@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
-{changing-midi-output-to-one-channel-per-voice.ly}
+It is possible to control the overall MIDI volume, the relative volume
+of dynamic markings and the relative volume of different instruments.
-@seealso
-Learning Manual:
-@rlearning{Other sources of information}.
+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
+* Dynamic marks in MIDI::
+* Setting MIDI volume::
+* Setting MIDI block properties::
+@end menu
+
+@cindex MIDI volume
+@cindex MIDI equalization
+@cindex MIDI dynamics
+@cindex Dynamics in MIDI
+
+
+@node Dynamic marks in MIDI
+@unnumberedsubsubsec Dynamic marks in MIDI
+
+Only the dynamic markings from @code{ppppp} to @code{fffff}, including
+@code{mp}, @code{mf} and @code{sf} have values assigned to them. This
+value is then applied to the value of the overall MIDI volume range to
+obtain the final volume included in the MIDI output for that particular
+dynamic marking. The default fractions range from 0.25 for
+@notation{ppppp} to 0.95 for @notation{fffff}. The complete set of
+dynamic marks and their associated fractions can be found in
+@file{scm/midi.scm}.
-Notation Reference:
-@ref{Expressive marks},
-@ref{Score layout}.
+
+@snippets
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
+{creating-custom-dynamics-in-midi-output.ly}
Installed Files:
-@file{ly/performer-init.ly}.
+@file{ly/script-init.ly}
+@file{scm/midi.scm}.
Snippets:
@rlsr{MIDI}.
Internals Reference:
@rinternals{Dynamic_performer}.
-@knownissues
-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;
-
-@example
-#(ly:set-option 'midi-extension "mid")
-@end example
-This will set the default extension for MIDI files to @code{.mid}.
+@node Setting MIDI volume
+@unnumberedsubsubsec Setting MIDI volume
-Alternatively, an option can be supplied on the command line:
+The minimum and maximum overall volume of MIDI dynamic markings is
+controlled by setting the properties @code{midiMinimumVolume} and
+@code{midiMaximumVolume} at the @code{Score} level. These properties
+have an effect only at the start of a voice and on dynamic marks. The
+fraction corresponding to each dynamic mark is modified with this
+formula
@example
-lilypond -dmidi-extension=mid MyFile.ly
+midiMinimumVolume + (midiMaximumVolume - midiMinimumVolume) * fraction
@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.
-
-Some MIDI players may not always correctly handle tempo changes in the
-midi output.
-
-Changes to @code{midiInstrument} (and other MIDI options) at the
-beginning of a staff may appear twice in the MIDI output.
-
-
-@node MIDI Instruments
-@subsection MIDI Instruments
+In the following example the dynamic range of the overall MIDI
+volume is limited to the range @code{0.2} - @code{0.5}.
-@cindex instrument names
-@cindex MIDI, instruments
-@funindex Staff.midiInstrument
+@example
+\score @{
+ <<
+ \new Staff @{
+ \set Staff.midiInstrument = #"flute"
+ @var{@dots{} music @dots{}}
+ @}
+ \new Staff @{
+ \set Staff.midiInstrument = #"clarinet"
+ @var{@dots{} music @dots{}}
+ @}
+ >>
+ \midi @{
+ \context @{
+ \Score
+ midiMinimumVolume = #0.2
+ midiMaximumVolume = #0.5
+ @}
+ @}
+@}
+@end example
-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}.
+Simple MIDI instrument equalization can be achieved by setting
+@code{midiMinimumVolume} and @code{midiMaximumVolume} properties within
+the @code{Staff} context.
@example
-\new Staff @{
- \set Staff.midiInstrument = #"glockenspiel"
- @var{@dots{}notes@dots{}}
+\score @{
+ \new Staff @{
+ \set Staff.midiInstrument = #"flute"
+ \set Staff.midiMinimumVolume = #0.7
+ \set Staff.midiMaximumVolume = #0.9
+ @var{@dots{} music @dots{}}
+ @}
+ \midi @{ @}
@}
@end example
+For scores with multiple staves and multiple MIDI instruments, the
+relative volumes of each instrument can be set individually;
+
@example
-\new Staff \with @{midiInstrument = #"cello"@} @{
- @var{@dots{}notes@dots{}}
+\score @{
+ <<
+ \new Staff @{
+ \set Staff.midiInstrument = #"flute"
+ \set Staff.midiMinimumVolume = #0.7
+ \set Staff.midiMaximumVolume = #0.9
+ @var{@dots{} music @dots{}}
+ @}
+ \new Staff @{
+ \set Staff.midiInstrument = #"clarinet"
+ \set Staff.midiMinimumVolume = #0.3
+ \set Staff.midiMaximumVolume = #0.6
+ @var{@dots{} music @dots{}}
+ @}
+ >>
+ \midi @{ @}
@}
@end example
-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.
+In this example the volume of the clarinet is reduced relative to the
+volume of the flute.
+
+If these volumes properties are not set then LilyPond still applies a
+@q{small degree} of equalization to certain instruments. See
+@file{scm/midi.scm}.
+
+Installed Files:
+@file{scm/midi.scm}.
@seealso
Notation Reference:
-@ref{MIDI instruments}.
+@ref{Score layout}.
Internals Reference:
@rinternals{Dynamic_performer}.
+@snippets
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
+{replacing-default-midi-instrument-equalization.ly}
-@node What goes into the MIDI output?
-@subsection What goes into the MIDI output?
+@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.
-@c TODO Check grace notes - timing is suspect?
-@menu
-* Supported in MIDI::
-* Unsupported in MIDI::
-@end menu
+@node Setting MIDI block properties
+@unnumberedsubsubsec Setting MIDI block properties
-@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:
+The @code{\midi} block can contain context rearrangements, new context
+definitions or code that sets the values of certain properties.
-@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
-@item Simple articulations: staccato, staccatissimo, accent, marcato, portato
-@item @ref{Breath marks}
-@end itemize
-
-There is a script that adds the following items; see
-@ref{The Articulate script}:
+@example
+\score @{
+ @var{@dots{} music @dots{}}
+ \midi @{
+ \tempo 4 = 72
+ @}
+@}
+@end example
-@itemize
-@item Slurs and phrasing slurs
-@item Ornaments (mordents, trills, turns, etc.)
-@item Rallentando, accelerando, ritard, and a tempo
-@end itemize
+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.
-@seealso
-Notation Reference:
-@ref{Accidentals},
-@ref{Breath marks},
-@ref{Expressive marks}.
+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.
-Installed Files:
-@file{ly/articulate.ly}.
+@cindex MIDI context definitions
+@cindex context definitions with MIDI
+Context definitions follow the same syntax as those in a @code{\layout}
+block;
-@node Unsupported in MIDI
-@unnumberedsubsubsec Unsupported in MIDI
+@example
+\score @{
+ @var{@dots{} music @dots{}}
+ \midi @{
+ \context @{
+ \Voice
+ \remove "Dynamic_performer"
+ @}
+ @}
+@}
+@end example
-@c TODO index as above
+This example removes the effect of dynamics from the MIDI output. Note:
+LilyPond's translation modules used for sound are called @q{performers}.
-The following items of notation have no effect on the MIDI output, even
-if you use @ref{The Articulate script}:
+@seealso
+Learning Manual:
+@rlearning{Other sources of information}.
-@itemize
-@item Rhythms entered as annotations, e.g. swing
-@item Tempo changes entered as annotations with no tempo marking
-@item Fermatas
-@item Other articulations
-@item Crescendi, decrescendi over a single note
-@item Tremolos entered with @q{@code{:}[@var{number}]}
-@item Figured bass
-@item Microtonal chords
-@item Glissandi, falls and doits
-@end itemize
+Notation Reference:
+@ref{Expressive marks},
+@ref{Score layout}.
-@seealso
Installed Files:
-@file{ly/articulate.ly}.
+@file{ly/performer-init.ly}.
+Snippets:
+@rlsr{MIDI}.
-@node Repeats in MIDI
-@subsection Repeats in MIDI
+Internals Reference:
+@rinternals{Dynamic_performer}.
-@cindex repeats in MIDI
-@funindex \unfoldRepeats
+@knownissues
+Some MIDI players do not always correctly handle tempo changes in the
+midi output.
+
+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.
-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.
+@node Using MIDI instruments
+@subsection Using MIDI instruments
-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):
+MIDI instruments are set using the @code{midiInstrument} property within
+a @code{Staff} context.
@example
\score @{
- @var{@dots{}music@dots{}}
- \layout @{ @dots{} @}
-@}
-\score @{
- \unfoldRepeats @var{@dots{}music@dots{}}
- \midi @{ @dots{} @}
+ \new Staff @{
+ \set Staff.midiInstrument = #"glockenspiel"
+ @var{@dots{} music @dots{}}
+ @}
+ \midi @{ @}
@}
@end example
-@seealso
-Notation Reference:
-@ref{Score layout}.
-
-Installed Files:
-@file{ly/articulate.ly}.
-
-
-@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.
+or
-@menu
-* Dynamic marks::
-* Overall MIDI volume::
-* Equalizing different instruments (i)::
-* Equalizing different instruments (ii)::
-@end menu
-
-@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 @code{rfz} is found, or calls the default function
-otherwise.
-
-@lilypond[verbatim,quote]
-#(define (myDynamics dynamic)
- (if (equal? dynamic "rfz")
- 0.9
- (default-dynamic-absolute-volume dynamic)))
-
-\score {
- \new Staff {
- \set Staff.midiInstrument = #"cello"
- \set Score.dynamicAbsoluteVolumeFunction = #myDynamics
- \new Voice {
- \relative c'' {
- a4\pp b c-\rfz
- }
- }
- }
- \layout {}
- \midi {}
-}
-@end lilypond
+@example
+\score @{
+ \new Staff \with @{midiInstrument = #"cello"@} @{
+ @var{@dots{} music @dots{}}
+ @}
+ \midi @{ @}
+@}
+@end example
-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.
+If the instrument name does not match any of the instruments listed in
+the @q{MIDI instruments} section, the @code{acoustic grand} instrument
+will be used instead. See @ref{MIDI instruments}.
@seealso
+Learning Manual:
+@rlearning{Other sources of information}.
+
Notation Reference:
-@ref{Expressive marks},
+@ref{MIDI instruments},
@ref{Score layout}.
Installed Files:
@file{scm/midi.scm}.
-Internals Reference:
-@rinternals{Dynamic_performer}.
+@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
-@node Overall MIDI volume
-@unnumberedsubsubsec Overall MIDI volume
+@cindex repeats in MIDI
+@cindex MIDI using repeats
+@funindex \unfoldRepeats
-The minimum and maximum overall volume of MIDI dynamic markings is
-controlled by setting the properties @code{midiMinimumVolume} and
-@code{midiMaximumVolume} at the @code{Score} level. These properties
-have an effect only at the start of a voice and on dynamic marks. The
-fraction corresponding to each dynamic mark is modified with this
-formula
+Repeats can be represented in the MIDI output by applying the
+@code{\unfoldRepeats} command.
@example
-midiMinimumVolume + (midiMaximumVolume - midiMinimumVolume) * fraction
+\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 the following example the dynamic range of the overall MIDI
-volume is limited to the range 0.2 - 0.5.
+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);
-@lilypond[verbatim,quote]
-\score {
- <<
- \new Staff {
- \key g \major
- \time 2/2
- \set Staff.midiInstrument = #"flute"
- \new Voice \relative c''' {
- r2 g\mp g fis~
- 4 g8 fis e2~
- 4 d8 cis d2
- }
- }
- \new Staff {
- \key g \major
- \set Staff.midiInstrument = #"clarinet"
- \new Voice \relative c'' {
- b1\p a2. b8 a
- g2. fis8 e
- fis2 r
- }
- }
- >>
- \layout {}
- \midi {
- \tempo 2 = 72
- \context {
- \Score
- midiMinimumVolume = #0.2
- midiMaximumVolume = #0.5
- }
- }
-}
-@end lilypond
+@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{Score layout}.
+@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:
-Internals Reference:
-@rinternals{Dynamic_performer}.
+@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.
-@node Equalizing different instruments (i)
-@unnumberedsubsubsec Equalizing different instruments (i)
+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.
-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.
+@item @code{'instrument}
-In this example the volume of the clarinet is reduced relative to the
-volume of the flute.
+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.
-@lilypond[verbatim,quote]
-\score {
- <<
- \new Staff {
- \key g \major
- \time 2/2
- \set Staff.midiInstrument = #"flute"
- \set Staff.midiMinimumVolume = #0.7
- \set Staff.midiMaximumVolume = #0.9
- \new Voice \relative c''' {
- r2 g\mp g fis~
- 4 g8 fis e2~
- 4 d8 cis d2
- }
- }
- \new Staff {
- \key g \major
- \set Staff.midiInstrument = #"clarinet"
- \set Staff.midiMinimumVolume = #0.3
- \set Staff.midiMaximumVolume = #0.6
- \new Voice \relative c'' {
- b1\p a2. b8 a
- g2. fis8 e
- fis2 r
- }
- }
- >>
- \layout {}
- \midi {
- \tempo 2 = 72
- }
-}
-@end lilypond
-
-@seealso
-Notation Reference:
-@ref{Score layout}.
+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}
-@node Equalizing different instruments (ii)
-@unnumberedsubsubsec Equalizing different instruments (ii)
+Allocate a separate MIDI channel to each voice in the score that has a
+unique name among the voices in its enclosing staff. Voices in
+different staves are always assigned separate MIDI channels, but any two
+voices contained within the same staff will share the same MIDI channel
+if they have the same name. Because @code{midiInstrument} and the
+several MIDI controls for effects are properties of the staff context,
+they cannot be set separately for each voice. The first voice will be
+played with the instrument and effects specified for the staff, and
+voices with a different name from the first will be assigned the default
+instrument and effects.
-If the 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}.
+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.
-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.
+@end table
-The following example sets the relative flute and clarinet volumes to
-the same values as the previous example.
+For example, the default MIDI channel mapping of a score can be changed
+to the @code{'instrument} setting as shown:
-@lilypond[verbatim,quote]
-#(define my-instrument-equalizer-alist '())
+@example
+\score @{
+ ...music...
+ \midi @{
+ \context @{
+ \Score
+ midiChannelMapping = #'instrument
+ @}
+ @}
+@}
+@end example
-#(set! my-instrument-equalizer-alist
- (append
- '(
- ("flute" . (0.7 . 0.9))
- ("clarinet" . (0.3 . 0.6)))
- my-instrument-equalizer-alist))
+@snippets
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
+{changing-midi-output-to-one-channel-per-voice.ly}
-#(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~
- 4 g8 fis e2~
- 4 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 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:
-@seealso
-Installed Files:
-@file{scm/midi.scm}.
+@table @var
-Internals Reference:
-@rinternals{Dynamic_performer}.
+@item @code{Staff.midiPanPosition}
-@ignore
-@c Delete when satisfied this is adequately covered elsewhere -td
+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.
-@n ode Microtones in MIDI
-@s ubsection Microtones in MIDI
+@item @code{Staff.midiBalance}
-@cindex microtones in MIDI
+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.
-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.
+@item @code{Staff.midiExpression}
-@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
+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.
-@node Percussion in MIDI
-@subsection Percussion in MIDI
+The expression level ranges from 0.0 (no expression, meaning zero
+volume) to 1.0 (full expression).
-Percussion instruments are generally notated in a @code{DrumStaff}
-context and when notated in this way they are outputted correctly to
-MIDI channel@tie{}10, but some pitched percussion instruments, like the
-xylophone, marimba, vibraphone, timpani, etc., are treated like
-@qq{normal} instruments and music for these instruments should be
-entered in a normal @code{Staff} context, not a @code{DrumStaff}
-context, to obtain the correct MIDI output.
+@item @code{Staff.midiReverbLevel}
-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.
+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).
-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.
+@item @code{Staff.midiChorusLevel}
-@c TODO Expand with examples, and any other issues
+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).
-@seealso
-Notation Reference:
-@ref{Percussion},
-@ref{Score layout}.
+@end table
-Internals Reference:
-@rinternals{Dynamic_performer}.
@knownissues
-Because the general MIDI standard does not contain rim shots, the
-sidestick is used for this purpose instead.
+As MIDI files do not contain any actual audio data, changes in these
+context properties translate only to requests for changing MIDI channel
+controls in the outputted MIDI files. Whether a particular MIDI device
+(such as a software MIDI player) can actually handle any of these
+requests in a MIDI file is entirely up to the implementation of the
+device: a device may choose to ignore some or all of these requests.
+Also, how a MIDI device will interpret different values for these
+controls (generally, the MIDI standard fixes the behavior only at the
+endpoints of the value range available for each control), and whether a
+change in the value of a control will affect notes already playing on
+that MIDI channel or not, is also specific to the MIDI device
+implementation.
+
+When generating MIDI files, LilyPond will simply transform the
+fractional values within each range linearly into values in a
+corresponding (7-bit, or 14-bit for MIDI channel controls which support
+fine resolution) integer range (0-127 or 0-32767, respectively),
+rounding fractional values towards the nearest integer away from zero.
+The converted integer values are stored as-is in the generated MIDI
+file. Please consult the documentation of your MIDI device for
+information about how the device interprets these values.
+
+
+@node Enhancing MIDI output
+@subsection Enhancing MIDI output
+
+@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
-@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.
+@node The articulate script
+@unnumberedsubsubsec The @file{articulate} script
-To use the Articulate script, you have to include it at the top of your
-input file,
+To use the @file{articulate} script add the appropriate @code{\include}
+command at the top of the input file;
@example
\include "articulate.ly"
@end example
-and in the @code{\score} section do
+The script creates MIDI output into appropriately @q{time-scaled} notes
+to match many articulation and tempo indications. Engraved output
+however, will also be altered to literally match the MIDI output.
@example
-\unfoldRepeats \articulate <<
- all the rest of the score@dots{}
->>
+\score @{
+ \articulate <<
+ @var{@dots{} music @dots{}}
+ >>
+ \midi @{ @}
+@}
@end example
-After altering your input file this way, the visual output is heavily
-altered, but the standard @code{\midi} block will produce a better
-MIDI file.
-
-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}.
+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}.
-Internals Reference:
-@rinternals{UnfoldedRepeatedMusic}.
+@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.}
-@knownissues
-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