FIXME: don't complain about anything in this chapter. It's still
under heavy development.
-FIXME: add comments
-@verbatim
-% %{
-@end verbatim
-to 3.1.
-
@menu
-* Input structure::
-* Useful concepts and properties::
-* Titles and headers::
-* Working with input files::
-* Controlling output::
+* Input structure::
+* Titles and headers::
+* Working with input files::
+* Controlling output::
+* MIDI output::
@end menu
these files end with @code{.ly}.
@menu
-* Structure of a score::
-* Multiple scores in a book::
-* File structure::
+* Structure of a score::
+* Multiple scores in a book::
+* File structure::
@end menu
@node Structure of a score
@subsection Structure of a score
-A @code{\score} must contain a single music expression. However,
-this music expression may be of any size. Recall that music
-expressions may be included inside other expressions to form
-larger expressions. All of these examples are single music
-expressions; note the curly braces @{ @} or angle brackets <<
->> at the beginning and ending of the music.
+@funindex \score
+
+A @code{\score} block must contain a single music expression
+delimited by curly brackets:
+
+@example
+\score @{
+...
+@}
+@end example
+
+@warning{There must be @strong{only one} outer music expression in
+a @code{\score} block, and it @strong{must} be surrounded by
+curly brackets.}
+
+This single music expression may be of any size, and may contain
+other music expressions to any complexity. All of these examples
+are music expressions:
@example
@{ c'4 c' c' c' @}
@end example
-@lilypond[ragged-right,verbatim,quote]
+@lilypond[verbatim,quote]
{
{ c'4 c' c' c'}
{ d'4 d' d' d'}
}
@end lilypond
-@lilypond[ragged-right,verbatim,quote]
+@lilypond[verbatim,quote]
<<
\new Staff { c'4 c' c' c' }
\new Staff { d'4 d' d' d' }
@}
@end example
+Comments are one exception to this general rule. (For others see
+@ref{File structure}.) Both single-line comments and comments
+delimited by @code{%@{ .. %@}} may be placed anywhere within an
+input file. They may be placed inside or outside a @code{\score}
+block, and inside or outside the single music expression within a
+@code{\score} block.
+
+@seealso
+
+Learning Manual:
+
+@rlearning{Working on input files},
+@rlearning{Music expressions explained},
+@rlearning{Score is a (single) compound musical expression}.
+
@node Multiple scores in a book
@subsection Multiple scores in a book
@funindex \book
@cindex movements, multiple
-A document may contain multiple pieces of music and texts. Examples
+A document may contain multiple pieces of music and text. Examples
of these are an etude book, or an orchestral part with multiple
movements. Each movement is entered with a @code{\score} block,
@funindex \book
-All the movements and texts which appear in the same @code{.ly} file
-will normally be typeset in the form of a single output file.
+All the movements and texts which appear in the same @code{.ly} file
+will normally be typeset in the form of a single output file.
@example
\score @{
@node File structure
@subsection File structure
-A @code{.ly} file contains any number of toplevel expressions, where a
-toplevel expression is one of the following
+@funindex \paper
+@funindex \midi
+@funindex \layout
+@funindex \header
+@funindex \score
+@funindex \book
-@itemize
+A @code{.ly} file may contain any number of toplevel expressions, where a
+toplevel expression is one of the following:
+
+@itemize @bullet
@item
An output definition, such as @code{\paper}, @code{\midi}, and
@code{\layout}. Such a definition at the toplevel changes the default
-settings for the block entered.
+book-wide settings. If more than one such definition of
+the same type is entered at the top level any definitions in the later
+expressions have precedence.
@item
A direct scheme expression, such as
@item
A @code{\score} block. This score will be collected with other
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}.
-The @code{\score} must begin with a music expression, and may
-contain only one music expression.
-
@item
A @code{\book} block logically combines multiple movements
-(i.e., multiple @code{\score} blocks) in one document. If there are
-a number of @code{\scores}, one output file will be created for
-each @code{\book} block, in which all corresponding movements are
-concatenated. The only reason to explicitly specify @code{\book} blocks
-in a @code{.ly} file is if you wish multiple output files from a single
-input file. One exception is within lilypond-book documents, where you
-explicitly have to add a @code{\book} block if you want more than a
-single @code{\score} 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}.
+(i.e., multiple @code{\score} blocks) in one document. If there
+are a number of @code{\score}s, one output file will be created
+for each @code{\book} block, in which all corresponding movements
+are concatenated. The only reason to explicitly specify
+@code{\book} blocks in a @code{.ly} file is if you wish to create
+multiple output files from a single input file. One exception is
+within lilypond-book documents, where you explicitly have to add
+a @code{\book} block if you want more than a single @code{\score}
+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}.
@item
A compound music expression, such as
@cindex variables
@item
-An variable, such as
+A variable, such as
@example
foo = @{ c4 d e d @}
@end example
@example
\layout @{
- % movements are non-justified by default
+ % Don't justify the output
ragged-right = ##t
@}
@item @code{\include}
@item @code{\sourcefilename}
@item @code{\sourcefileline}
+@item
+A single-line comment, introduced by a leading @code{%} sign.
-@end itemize
-
-
-@node Useful concepts and properties
-@section Useful concepts and properties
-
-
-@menu
-* Input modes::
-* When to add a -::
-* Controlling direction and placement::
-* Distances and measurements::
-* Spanners::
-@end menu
-
-@node Input modes
-@subsection Input modes
-
-\notemode
-
-\notemode turns the front end of LilyPond into note mode
-(which is the default parsing mode).
-It's certainly useful in certain situations, for example if you
-are in \lyricmode or \chordmode or ... and want to insert
-something that only can be done with \notemode syntax.
-
-See for example
-http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00418.html
-http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00218.html
-http://lists.gnu.org/archive/html/lilypond-user/2006-12/msg00236.html
-http://lists.gnu.org/archive/html/lilypond-user/2006-11/msg00061.html
-
-
-\chords
-\drums
-\fretmode ?
-
-
-@node When to add a -
-@subsection When to add a -
-
-One of these works, the other doesn't.
-
-@verbatim
-\version "2.11.38"
-{ c'\mp\fermata\accent-\markup { "forcefully"} }
-% { c'\mp\fermata\accent\markup { "forcefully"} }
-@end verbatim
-
-@node Controlling direction and placement
-@subsection Controlling direction and placement
-
-TODO: everything
-
-By default, LilyPond does a pretty jazz'n job of picking
-directions. But in some cases, it may be desirable to force a
-direction.
-
-@verbatim
--
-^ _
-@end verbatim
-
-Also cover
-#UP
-#DOWN
-#LEFT
-#RIGHT.
-
-Maybe rename section to "directions".
-
-Also mention \override Foo #'direction = #'DOWN.
-
-also mention the typical \fooDown, \fooNeutral predefined commands.
-
-also mention that some directions are (without other tweaking)
-always up or always down (like dynamics or fermata), while other
-things can alternate between up or down based on the stem direction
-(like slurs or accents).
-
-
-@node Distances and measurements
-@subsection Distances and measurements
-
-DISCUSS after working on other sections.
-
-TODO: staff spaces, #UP #DOWN #LEFT #RIGHT. Maybe move into tweaks?
+@item
+A multi-line comment delimited by @code{%@{ .. %@}}.
+@end itemize
-@node Spanners
-@subsection Spanners
+@seealso
+Learning Manual:
+@rlearning{How LilyPond input files work}.
@node Titles and headers
@section Titles and headers
@section Controlling output
@menu
-* Extracting fragments of notation::
-* Skipping corrected music::
+* Extracting fragments of music::
+* Skipping corrected music::
@end menu
-@node Extracting fragments of notation
-@subsection Extracting fragments of notation
+@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
voices and staves, saving even more time.
+
+@node MIDI output
+@section 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.
+
+@knownissues
+
+Many musically interesting effects, such as swing, articulation,
+slurring, etc., are not translated to midi.
+
+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? FIXME::
+* other 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,
+
+@example
+\score @{
+ @var{...music...}
+ \midi @{
+ \context @{
+ \Score
+ tempoWholesPerMinute = #(ly:make-moment 72 4)
+ @}
+ @}
+@}
+@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
+
+@example
+\score @{
+ @var{...music...}
+ \midi @{ @}
+ \layout @{ @}
+@}
+@end example
+@cindex layout 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
+
+@example
+\set Staff.midiMinimumVolume = #0.2
+\set Staff.midiMaximumVolume = #0.8
+@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"
+ @}
+@}
+@end example
+
+
+@knownissues
+
+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,
+
+@example
+@{ a\< b c d\f @}
+@end example
+
+@noindent
+will not work properly but
+
+@example
+@{ a\< b c d\!\f @}
+@end example
+
+@noindent
+will.
+
+
+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.
+
+@example
+\score @{
+ \new Score @{ @dots{}notes@dots{} @}
+ \midi
+@}
+@end example
+
+
+@node MIDI block
+@subsection MIDI block
+@cindex MIDI block
+
+
+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.
+
+
+@cindex context definition
+
+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}.
+
+
+@node MIDI instrument names
+@subsection MIDI instrument names
+
+@cindex instrument names
+@funindex Staff.midiInstrument
+
+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}.
+
+@example
+\set Staff.midiInstrument = "glockenspiel"
+@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.
+
+
+@node What goes into the MIDI? FIXME
+@subsection What goes into the MIDI? FIXME
+
+@menu
+* Repeats and MIDI::
+@end menu
+
+@node Repeats and MIDI
+@subsubsection Repeats and MIDI
+
+@cindex expanding repeats
+@funindex \unfoldRepeats
+
+With a little bit of tweaking, all types of repeats can be present
+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]
+\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
+
+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{..music..}
+ \layout @{ .. @}
+@}
+\score @{
+ \unfoldRepeats @var{..music..}
+ \midi @{ .. @}
+@}
+@end example
+
+
+@node other midi
+@subsection other midi
+
+Micro tones are also exported to the MIDI file.
+
+Figured bass has no effect on MIDI.
+