version that you are working on. See TRANSLATION for details.
@end ignore
-@c \version "2.11.51"
+@c \version "2.12.0"
-@node Input syntax
-@chapter Input syntax
+@node General input and output
+@chapter General input and output
-This section deals with general LilyPond input syntax issues,
+This section deals with general LilyPond input and output issues,
rather than specific notation.
@menu
block, and inside or outside the single music expression within a
@code{\score} block.
-@seealso
+@seealso
Learning Manual:
-
@rlearning{Working on input files},
@rlearning{Music expressions explained},
@rlearning{Score is a (single) compound musical expression}.
@}
@end example
+@funindex \bookpart
+
+Pieces of music may be grouped into book parts using @code{\bookpart}
+blocks. Book parts are separated by a page break, and can start with a
+title, like the book itself, by specifying a @code{\header} block.
+
+@example
+\bookpart @{
+ \header @{
+ title = "Book title"
+ subtitle = "First part"
+ @}
+ \score @{ @dots{} @}
+ @dots{}
+@}
+\bookpart @{
+ \header @{
+ subtitle = "Second part"
+ @}
+ \score @{ @dots{} @}
+ @dots{}
+@}
+@end example
+
@node File structure
@subsection File structure
@funindex \header
@funindex \score
@funindex \book
+@funindex \bookpart
A @code{.ly} file may contain any number of toplevel expressions, where a
toplevel expression is one of the following:
toplevel scores, and combined as a single @code{\book}.
This behavior can be changed by setting the variable
@code{toplevel-score-handler} at toplevel. The default handler is
-defined in the init file @file{scm/@/lily@/.scm}.
+defined in the init file @file{../scm/@/lily@/.scm}.
@item
A @code{\book} block logically combines multiple movements
or @code{\markup} in the same example. This behavior can be
changed by setting the variable @code{toplevel-book-handler} at
toplevel. The default handler is defined in the init file
-@file{scm/@/lily@/.scm}.
+@file{../scm/@/lily@/.scm}.
+
+@item
+A @code{\bookpart} block. A book may be divided into several parts,
+using @code{\bookpart} blocks, in order to ease the page breaking,
+or to use different @code{\paper} settings in different parts.
@item
A compound music expression, such as
This behavior can be changed by setting the variable
@code{toplevel-music-handler} at toplevel. The default handler is
-defined in the init file @file{scm/@/lily@/.scm}.
+defined in the init file @file{../scm/@/lily@/.scm}.
@item
A markup text, a verse for example
@end example
This can be used later on in the file by entering @code{\foo}. The
-name of an variable should have alphabetic characters only; no
+name of a variable should have alphabetic characters only; no
numbers, underscores or dashes.
@end itemize
@end itemize
-@seealso
+@seealso
Learning Manual:
@rlearning{How LilyPond input files work}.
+
@node Titles and headers
@section Titles and headers
@subsection Creating titles
Titles are created for each @code{\score} block, as well as for the full
-input file (or @code{\book} block).
+input file (or @code{\book} block) and book parts (created by
+@code{\bookpart} blocks).
The contents of the titles are taken from the @code{\header} blocks.
The header block for a book supports the following
@funindex poet
@item poet
-Name of the poet, flush-left below the subtitle.
+Name of the poet, flush-left below the subsubtitle.
+
+@funindex instrument
+@item instrument
+Name of the instrument, centered below the subsubtitle. Also
+centered at the top of pages (other than the first page).
@funindex composer
@item composer
-Name of the composer, flush-right below the subtitle.
+Name of the composer, flush-right below the subsubtitle.
@funindex meter
@item meter
Meter string, flush-left below the poet.
-@funindex opus
-@item opus
-Name of the opus, flush-right below the composer.
-
@funindex arranger
@item arranger
-Name of the arranger, flush-right below the opus.
-
-@funindex instrument
-@item instrument
-Name of the instrument, centered below the arranger. Also
-centered at the top of pages (other than the first page).
+Name of the arranger, flush-right below the composer.
@funindex piece
@item piece
-Name of the piece, flush-left below the instrument.
+Name of the piece, flush-left below the meter.
+
+@funindex opus
+@item opus
+Name of the opus, flush-right below the arranger.
@cindex page breaks, forcing
@funindex breakbefore
\book {
\header {
dedication = "dedicated to me"
- title = \markup \center-align { "Title first line" "Title second line,
+ title = \markup \center-column { "Title first line" "Title second line,
longer" }
subtitle = "the subtitle,"
subsubtitle = #(string-append "subsubtitle LilyPond version "
(lilypond-version))
poet = "Poet"
- composer = \markup \center-align { "composer" \small "(1847-1973)" }
+ composer = \markup \center-column { "composer" \small "(1847-1973)" }
texttranslator = "Text Translator"
meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
"r" }
}
@end lilypond
-@funindex printallheaders
+@funindex print-all-headers
@noindent
You may change this behavior (and print all the headers when defining
@code{\header} inside @code{\score}) by using
@example
\paper@{
- printallheaders=##t
+ print-all-headers = ##t
@}
@end example
A more advanced option is to change the definitions of the following
variables in the @code{\paper} block. The init file
-@file{ly/titling-init.ly} lists the default layout.
+@file{../ly/titling-init.ly} lists the default layout.
@table @code
@funindex bookTitleMarkup
dimensions. If the book has between 10 and 99 pages, it may be "00",
ie. a two digit number.
-@predefined
+@predefined
@funindex \label
-@code{\label}
+@code{\label},
@funindex \page-ref
-@code{\page-ref}
+@code{\page-ref}.
+@endpredefined
+
@node Table of contents
@subsection Table of contents
}
@end lilypond
+
@seealso
+Init files: @file{../ly/@/toc@/-init@/.ly}.
-Init files: @file{ly/@/toc@/-init@/.ly}.
@predefined
-
@funindex \table-of-contents
-@code{\table-of-contents}
+@code{\table-of-contents},
@funindex \tocItem
-@code{\tocItem}
+@code{\tocItem}.
+@endpredefined
@node Working with input files
@end example
Files which are to be included can also contain @code{\include}
-statements of their own. These second-level
+statements of their own. By default, these second-level
@code{\include} statements are not interpreted until they have
been brought into the main file, so the file names they specify
must all be relative to the directory containing the main file,
-not the directory containing the included file.
+not the directory containing the included file. However,
+this behavior can be changed by passing the option
+@code{-drelative-includes} option at the command line
+(or by adding @code{#(ly:set-option 'relative-includes #t)}
+at the top of the main input file). With @code{relative-includes}
+set, the path for each @code{\include} command will be taken
+relative to the file containing that command. This behavior is
+recommended and it will become the default behavior in a future
+version of lilypond.
Files can also be included from a directory in a search path
specified as an option when invoking LilyPond from the command
Files which are to be included in many scores may be placed in
the LilyPond directory @file{../ly}. (The location of this
-directory is installation-dependent - see @rlearning{Other sources
-of information}). These files can then be included simply by
-naming them on an @code{\include} statement. This is how the
-language-dependent files like @file{english.ly} are included.
+directory is installation-dependent - see
+@rlearning{Other sources of information}). These files can then
+be included simply by naming them on an @code{\include} statement.
+This is how the language-dependent files like @file{english.ly} are
+included.
LilyPond includes a number of files by default when you start
the program. These includes are not apparent to the user, but the
files may be identified by running @code{lilypond --verbose} from
the command line. This will display a list of paths and files that
LilyPond uses, along with much other information. Alternatively,
-the more important of these files are discussed in @rlearning{Other
-sources of information}. These files may be edited, but changes to
-them will be lost on installing a new version of LilyPond.
+the more important of these files are discussed in
+@rlearning{Other sources of information}. These files may be
+edited, but changes to them will be lost on installing a new
+version of LilyPond.
Some simple examples of using @code{\include} are shown in
@rlearning{Scores and parts}.
+
@seealso
Learning Manual:
@rlearning{Other sources of information},
@rlearning{Scores and parts}.
+
@knownissues
If an included file is given a name which is the same as one in
the first filter will remove all tagged sections except the one
named, and the second filter will remove even that tagged section.
-@seealso
+@seealso
Learning Manual:
@rlearning{Organizing pieces with variables}.
@ref{Automatic part combining},
@ref{Including LilyPond files}.
+
@ignore
@c This warning is more general than this placement implies.
@c Rests are not merged whether or not they come from tagged sections.
@node Text encoding
@subsection Text encoding
-LilyPond uses the Pango library to format multi-lingual texts, and
-does not perform any input-encoding conversions. This means that any
-text, be it title, lyric text, or musical instruction containing
-non-ASCII characters, must be utf-8. The easiest way to enter such text is
-by using a Unicode-aware editor and saving the file with utf-8 encoding. Most
-popular modern editors have utf-8 support, for example, vim, Emacs,
-jEdit, and GEdit do.
-
-@c TODO Expand - meanings; how to get and install fonts?
-
-@c TODO Explainn that programming error: FT_Get_Glyph_Name () error: invalid argument
-@c is often due to saving in Latin-1 rather than UTF-8
+LilyPond uses the character repertoire defined by the Unicode
+consortium and ISO/IEC 10646. This defines a unique name and
+code point for the character sets used in virtually all modern
+languages and many others too. Unicode can be implemented using
+several different encodings. LilyPond uses the UTF-8 encoding
+(UTF stands for Unicode Transformation Format) which represents
+all common Latin characters in one byte, and represents other
+characters using a variable length format of up to four bytes.
+
+The actual appearance of the characters is determined by the
+glyphs defined in the particular fonts available - a font defines
+the mapping of a subset of the Unicode code points to glyphs.
+LilyPond uses the Pango library to layout and render multi-lingual
+texts.
+
+Lilypond does not perform any input-encoding conversions. This
+means that any text, be it title, lyric text, or musical
+instruction containing non-ASCII characters, must be encoded in
+UTF-8. The easiest way to enter such text is by using a
+Unicode-aware editor and saving the file with UTF-8 encoding. Most
+popular modern editors have UTF-8 support, for example, vim, Emacs,
+jEdit, and GEdit do. All MS Windows systems later than NT use
+Unicode as their native character encoding, so even Notepad can
+edit and save a file in UTF-8 format. A more functional
+alternative for Windows is BabelPad.
+
+If a LilyPond input file containing a non-ASCII character is not
+saved in UTF-8 format the error message
-@c TODO Currently not working
-@ignore
-Depending on the fonts installed, the following fragment shows Hebrew
-and Cyrillic lyrics,
-
-@cindex Cyrillic
-@cindex Hebrew
-@cindex ASCII, non
+@example
+FT_Get_Glyph_Name () error: invalid argument
+@end example
-@li lypondfile[fontload]{utf-8.ly}
+will be generated.
-@c TODO TeX is no longer used as backend
+Here is an example showing Cyrillic, Hebrew and Portuguese
+text:
-The @TeX{} backend does not handle encoding specially at all. Strings
-in the input are put in the output as-is. Extents of text items in the
-@TeX{} backend, are determined by reading a file created via the
-@file{texstr} backend,
+@lilypond[quote]
+%c No verbatim here as the code does not display correctly in PDF
+% Cyrillic
+bulgarian = \lyricmode {
+ Жълтата дюля беше щастлива, че пухът, който цъфна, замръзна като гьон.
+}
-@example
-lilypond -dbackend=texstr input/les-nereides.ly
-latex les-nereides.texstr
-@end example
+% Hebrew
+hebrew = \lyricmode {
+ זה כיף סתם לשמוע איך תנצח קרפד עץ טוב בגן.
+}
-The last command produces @file{les-nereides.textmetrics}, which is
-read when you execute
+% Portuguese
+portuguese = \lyricmode {
+ à vo -- cê uma can -- ção legal
+}
-@example
-lilypond -dbackend=tex input/les-nereides.ly
-@end example
+\relative {
+ c2 d e f g f e
+}
+\addlyrics { \bulgarian }
+\addlyrics { \hebrew }
+\addlyrics { \portuguese }
+@end lilypond
-Both @file{les-nereides.texstr} and @file{les-nereides.tex} need
-suitable LaTeX wrappers to load appropriate La@TeX{} packages for
-interpreting non-ASCII strings.
+To enter a single character for which the Unicode escape sequence
+is known but which is not available in the editor being used, use
+@code{\char ##xhhhh} within a @code{\markup} block, where
+@code{hhhh} is the hexadecimal code for the character required.
+For example, @code{\char ##x03BE} enters the Unicode U+03BE
+character, which has the Unicode name @qq{Greek Small Letter Xi}.
+Any Unicode hexadecimal code may be substituted, and if all special
+characters are entered in this format it is not necessary to save
+the input file in UTF-8 format. Of course, a font containing all
+such encoded characters must be installed and available to LilyPond.
+
+The following example shows UTF-8 coded characters being used in
+four places -- in a rehearsal mark, as articulation text, in lyrics
+and as stand-alone text below the score:
-@end ignore
+@lilypond[quote,verbatim]
+\score {
+ \relative c'' {
+ c1 \mark \markup { \char ##x03EE }
+ c1_\markup { \tiny { \char ##x03B1 " to " \char ##x03C9 } }
+ }
+ \addlyrics { O \markup { \concat{ Ph \char ##x0153 be! } } }
+}
+\markup { "Copyright 2008" \char ##x00A9 }
+@end lilypond
-To use a Unicode escape sequence, use
+To enter the copyright sign in the copyright notice use:
@example
-#(ly:export (ly:wide-char->utf-8 #x2014))
+\header @{
+ copyright = \markup @{ \char ##x00A9 "2008" @}
+@}
@end example
-
@node Displaying LilyPond notation
@subsection Displaying LilyPond notation
@funindex skipTypesetting
+@funindex showFirstLength
@funindex showLastLength
When entering or copying music, usually only the music near the end (where
in your source file. This will render only the last 5 measures
(assuming 4/4 time signature) of every @code{\score} in the input
file. For longer pieces, rendering only a small part is often an order
-of magnitude quicker than rendering it completely
+of magnitude quicker than rendering it completely. When working on the
+beginning of a score you have already typeset (e.g. to add a new part),
+the @code{showFirstLength} property may be useful as well.
Skipping parts of a score can be controlled in a more fine-grained
fashion with the property @code{Score.skipTypesetting}. When it is
that are off or accidentals that were mistyped stand out very much
when listening to the MIDI output.
-@c TODO Move to lower section - next one?
-@knownissues
-
-Many musically interesting effects, such as swing, articulation,
-slurring, etc., are not translated to midi.
-
@c TODO Check this
The midi output allocates a channel for each staff, and one for global
settings. Therefore the midi file should not have more than 15 staves
(or 14 if you do not use drums). Other staves will remain silent.
-Not all midi players correctly handle tempo changes in the midi
-output. Players that are known to work include
-@uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
-
@menu
* Creating MIDI files::
* MIDI block::
-* MIDI instrument names::
-* What goes into the MIDI output?
+* What goes into the MIDI output?::
+* Repeats in MIDI::
+* Controlling MIDI dynamics::
+* Percussion in MIDI::
@end menu
@node Creating MIDI files
@subsection Creating MIDI files
-To create a MIDI from a music piece of music, add a @code{\midi} block
-to a score, for example,
+To create a MIDI output file from a LilyPond input file, add a
+@code{\midi} block to a score, for example,
@example
\score @{
@var{...music...}
- \midi @{
- \context @{
- \Score
- tempoWholesPerMinute = #(ly:make-moment 72 4)
- @}
- @}
+ \midi @{ @}
@}
@end example
-The tempo can be specified using the @code{\tempo} command within the
-actual music, see @ref{Metronome marks}. An alternative, which does not
-result in a metronome mark in the printed score, is shown in the example
-above. In this example the tempo of quarter notes is set to 72 beats per
-minute.
-This kind of tempo
-specification can not take dotted note lengths as an argument. In this
-case, break the dotted notes into smaller units. For example, a tempo
-of 90 dotted quarter notes per minute can be specified as 270 eighth
-notes per minute
-
-@example
-tempoWholesPerMinute = #(ly:make-moment 270 8)
-@end example
-
-If there is a @code{\midi} command in a @code{\score}, only MIDI will
-be produced. When notation is needed too, a @code{\layout} block must
-be added
+If there is a @code{\midi} block in a @code{\score} with no
+@code{\layout} block, only MIDI output will be produced. When
+notation is needed too, a @code{\layout} block must be also be
+present.
@example
\score @{
\layout @{ @}
@}
@end example
-@cindex layout block
+Pitches, rhythms, ties, dynamics, and tempo changes are interpreted
+and translated correctly to the MIDI output. Dynamic marks,
+crescendi and decrescendi translate into MIDI volume levels.
+Dynamic marks translate to a fixed fraction of the available MIDI
+volume range. Crescendi and decrescendi make the volume vary
+linearly between their two extremes. The effect of dynamic markings
+on the MIDI output can be removed completely, see @ref{MIDI block}.
+The initial tempo and later tempo changes can be specified
+with the @code{\tempo} command within the music notation. These
+are reflected in tempo changes in the MIDI output. This command
+will normally result in the metronome mark being printed, but this
+can be suppressed, see @ref{Metronome marks}. An alternative way
+of specifying the inital or overall MIDI tempo is described below,
+see @ref{MIDI block}.
-Ties, dynamics, and tempo changes are interpreted. Dynamic marks,
-crescendi and decrescendi translate into MIDI volume levels. Dynamic
-marks translate to a fixed fraction of the available MIDI volume
-range, crescendi and decrescendi make the volume vary linearly between
-their two extremes. The fractions can be adjusted by
-@code{dynamicAbsoluteVolumeFunction} in @rinternals{Voice} context.
-For each type of MIDI instrument, a volume range can be defined. This
-gives a basic equalizer control, which can enhance the quality of
-the MIDI output remarkably. The equalizer can be controlled by
-setting @code{instrumentEqualizer}, or by setting
+@unnumberedsubsubsec Instrument names
+
+@cindex instrument names
+@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}.
@example
-\set Staff.midiMinimumVolume = #0.2
-\set Staff.midiMaximumVolume = #0.8
+\new Staff @{
+ \set Staff.midiInstrument = #"glockenspiel"
+ @var{...notes...}
+@}
@end example
-To remove dynamics from the MIDI output, insert the following lines
-in the @code{\midi@{@}} section.
-
@example
-\midi @{
- ...
- \context @{
- \Voice
- \remove "Dynamic_performer"
- @}
+\new Staff \with @{midiInstrument = #"cello"@} @{
+ @var{...notes...}
@}
@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.
+
+
+@snippets
+
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+{changing-midi-output-to-one-channel-per-voice.ly}
@knownissues
+@c In 2.11 the following no longer seems to be a problem -td
+@ignore
Unterminated (de)crescendos will not render properly in the midi file,
resulting in silent passages of music. The workaround is to explicitly
terminate the (de)crescendo. For example,
@noindent
will.
+@end ignore
+
+Changes in the MIDI volume take place only on starting a note, so
+crescendi and decrescendi cannot affect the volume of a
+single note.
+
+Not all midi players correctly handle tempo changes in the midi
+output. Players that are known to work include MS Windows Media
+Player and @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
+@node MIDI block
+@subsection MIDI block
+@cindex MIDI block
-MIDI output is only created when the @code{\midi} command is within
-a @code{\score} block. If you put it within an explicitly instantiated
-context ( i.e. @code{\new Score} ) the file will fail. To solve this,
-enclose the @code{\new Score} and the @code{\midi} in a @code{\score} block.
+A @code{\midi} block must appear within a score block if MIDI output
+is required. It is analogous to the layout block, but somewhat
+simpler. Often, the @code{\midi} block is left empty, but it
+can contain context rearrangements, new context definitions or code
+to set the values of properties. For example, the following will
+set the initial tempo exported to a MIDI file without causing a tempo
+indication to be printed:
@example
\score @{
- \new Score @{ @dots{}notes@dots{} @}
- \midi
+ @var{...music...}
+ \midi @{
+ \context @{
+ \Score
+ tempoWholesPerMinute = #(ly:make-moment 72 4)
+ @}
+ @}
@}
@end example
+In this example the tempo is set to 72 quarter note
+beats per minute. This kind of tempo specification cannot take
+a dotted note length as an argument. If one is required, break
+the dotted note into smaller units. For example, a tempo of 90
+dotted quarter notes per minute can be specified as 270 eighth
+notes per minute:
-@node MIDI block
-@subsection MIDI block
-@cindex MIDI block
+@example
+tempoWholesPerMinute = #(ly:make-moment 270 8)
+@end example
-@c TODO Do we need this? Should it be elsewhere?
-@c TODO If we keep it it should be expanded
+@cindex MIDI context definitions
-The MIDI block is analogous to the layout block, but it is somewhat
-simpler. The @code{\midi} block is similar to @code{\layout}. It can contain
-context definitions.
+Context definitions follow precisely the same syntax as those
+within a @code{\layout} block. Translation modules for sound are
+called performers. The contexts for MIDI output are defined in
+@file{../ly/@/performer@/-init@/.ly},
+see @rlearning{Other sources of information}.
+For example, to remove the effect of dynamics
+from the MIDI output, insert the following lines in the
+@code{\midi@{ @}} block.
+@example
+\midi @{
+ ...
+ \context @{
+ \Voice
+ \remove "Dynamic_performer"
+ @}
+@}
+@end example
-@cindex context definition
+MIDI output is created only when a @code{\midi} block is included
+within a score block defined with a @code{\score} command. If it
+is placed within an explicitly instantiated score context (i.e.
+within a @code{\new Score} block) the file will fail. To solve
+this, enclose the @code{\new Score} and the @code{\midi} commands
+in a @code{\score} block.
-Context definitions follow precisely the same syntax as within the
-\layout block. Translation modules for sound are called performers.
-The contexts for MIDI output are defined in @file{ly/@/performer@/-init@/.ly}.
+@example
+\score @{
+ \new Score @{ @dots{}notes@dots{} @}
+ \midi @{ @}
+@}
+@end example
+@node What goes into the MIDI output?
+@subsection What goes into the MIDI output?
-@node MIDI instrument names
-@subsection MIDI instrument names
+@c TODO Check grace notes - timing is suspect?
-@cindex instrument names
-@funindex Staff.midiInstrument
+@unnumberedsubsubsec Supported in MIDI
-The MIDI instrument name is set by the @code{Staff.midiInstrument}
-property. The instrument name should be chosen from the list in
-@ref{MIDI instruments}.
+@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
+@c TODO etc
-@example
-\set Staff.midiInstrument = "glockenspiel"
-@var{...notes...}
-@end example
+The following items of notation are reflected in the MIDI output:
-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.
+@itemize
+@item Pitches
+@item Quarter tones (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
+@unnumberedsubsubsec Unsupported in MIDI
-@node What goes into the MIDI output?
-@subsection What goes into the MIDI output?
+@c TODO index as above
-@c TODO Add Notes, rhythms, dynamics
-@c TODO Check grace notes - timing is suspect?
+The following items of notation have no effect on the MIDI output:
+
+@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
+@end itemize
-@menu
-* Repeats::
-* Microtones::
-@end menu
-@node Repeats
-@subsubsection Repeats
+@node Repeats in MIDI
+@subsection Repeats in MIDI
@cindex repeats in MIDI
@funindex \unfoldRepeats
-With a little bit of tweaking, all types of repeats can be present
+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,fragment,line-width=8.0\cm]
+@lilypond[quote,verbatim]
\unfoldRepeats {
\repeat tremolo 8 {c'32 e' }
\repeat percent 2 { c''8 d'' }
@}
@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.
+
+@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.
+
+@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'' {
+ a\pp b c-\rfz
+ }
+ }
+ }
+ \layout {}
+ \midi {}
+}
+@end lilypond
+
+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.
+
+@unnumberedsubsubsec Overall MIDI volume
+
+The minimum and maximum overall volume of MIDI dynamic markings is
+controlled by setting the properties @code{midiMinimumVolume} and
+@code{midiMaximumVolume} at the @code{Score} level. These
+properties have an effect only on dynamic marks, so if they
+are to apply from the start of the score a dynamic mark must be
+placed there. The fraction corresponding to each dynamic mark is
+modified with this formula
+
+@example
+midiMinimumVolume + (midiMaximumVolume - midiMinimumVolume) * fraction
+@end example
+
+In the following example the dynamic range of the overall MIDI
+volume is limited to the range 0.2 - 0.5.
-@node Microtones
-@subsubsection Microtones
+@lilypond[verbatim,quote]
+\score {
+ <<
+ \new Staff {
+ \key g \major
+ \time 2/2
+ \set Staff.midiInstrument = #"flute"
+ \new Voice \relative c''' {
+ r2 g\mp g fis ~
+ fis4 g8 fis e2 ~
+ e4 d8 cis d2
+ }
+ }
+ \new Staff {
+ \key g \major
+ \set Staff.midiInstrument = #"clarinet"
+ \new Voice \relative c'' {
+ b1\p a2. b8 a
+ g2. fis8 e
+ fis2 r
+ }
+ }
+ >>
+ \layout { }
+ \midi {
+ \context {
+ \Score
+ tempoWholesPerMinute = #(ly:make-moment 72 2)
+ midiMinimumVolume = #0.2
+ midiMaximumVolume = #0.5
+ }
+ }
+}
+@end lilypond
+
+@unnumberedsubsubsec Equalizing different instruments (i)
+
+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.
+
+In this example the volume of the clarinet is reduced relative
+to the volume of the flute. There must be a dynamic
+mark on the first note of each instrument for this to work
+correctly.
+
+@lilypond[verbatim,quote]
+\score {
+ <<
+ \new Staff {
+ \key g \major
+ \time 2/2
+ \set Staff.midiInstrument = #"flute"
+ \set Staff.midiMinimumVolume = #0.7
+ \set Staff.midiMaximumVolume = #0.9
+ \new Voice \relative c''' {
+ r2 g\mp g fis ~
+ fis4 g8 fis e2 ~
+ e4 d8 cis d2
+ }
+ }
+ \new Staff {
+ \key g \major
+ \set Staff.midiInstrument = #"clarinet"
+ \set Staff.midiMinimumVolume = #0.3
+ \set Staff.midiMaximumVolume = #0.6
+ \new Voice \relative c'' {
+ b1\p a2. b8 a
+ g2. fis8 e
+ fis2 r
+ }
+ }
+ >>
+ \layout { }
+ \midi {
+ \context {
+ \Score
+ tempoWholesPerMinute = #(ly:make-moment 72 2)
+ }
+ }
+}
+@end lilypond
+
+@unnumberedsubsubsec Equalizing different instruments (ii)
+
+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}.
+
+This basic default equalizer can be replaced by setting
+@code{instrumentEqualizer} in the @code{Score} context to a new
+Scheme procedure which accepts a MIDI instrument name as its only
+argument and returns a pair of fractions giving the minimum and
+maximum volumes to be applied to that instrument. This replacement
+is done in the same way as shown for resetting the
+@code{dynamicAbsoluteVolumeFunction} at the start of this section.
+The default equalizer, @notation{default-instrument-equalizer}, in
+@file{../scm/midi.scm} shows how such a procedure might be written.
+
+The following example sets the relative flute and clarinet volumes
+to the same values as the previous example.
+
+@lilypond[verbatim,quote]
+#(define my-instrument-equalizer-alist '())
+
+#(set! my-instrument-equalizer-alist
+ (append
+ '(
+ ("flute" . (0.7 . 0.9))
+ ("clarinet" . (0.3 . 0.6)))
+ my-instrument-equalizer-alist))
+
+#(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 {
+ \context {
+ \Score
+ tempoWholesPerMinute = #(ly:make-moment 72 2)
+ }
+ }
+}
+@end lilypond
+
+@ignore
+@c Delete when satisfied this is adequately covered elsewhere -td
+
+@n ode Microtones in MIDI
+@s ubsection Microtones in MIDI
+
+@cindex microtones in MIDI
+
+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.
+
+@lilypond[verbatim,quote]
+\score {
+ \relative c' {
+ c cih cis cisih
+ d dih ees eeh
+ e eih f fih
+ fis fisih g gih
+ gis gisih a aih
+ bes beh b bih
+ }
+ \layout {}
+ \midi {}
+}
+@end lilypond
+@end ignore
+
+
+@node Percussion in MIDI
+@subsection Percussion in MIDI
+
+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.
+
+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.
+
+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.
+
+@c TODO Expand with examples, and any other issues
+
+@knownissues
-Micro tones are also exported to the MIDI file.
-@c TODO Write
+Because the general MIDI standard does not contain rim shots, the
+sidestick is used for this purpose instead.
-@c TODO List things that have no effect
-Figured bass, chords, lyrics have no effect on MIDI.
projects / lilypond.git / blobdiff