@c -*-texinfo-*-
@node Sound
@chapter Sound
@cindex Sound

MIDI (Musical Instrument Digital Interface) is a standard for
connecting and controlling digital instruments.  A MIDI file is like a
tape recording of a MIDI instrument.

Pieces of music can be converted to a MIDI file, 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 musical transcription.

@refbugs

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.  hence, 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 change 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::       
@end menu

@node Creating MIDI files
@section Creating MIDI files 

@cindex sound
@cindex midi

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 @{ \tempo 4=72 @}
@}
@end example 

Here, the tempo is specified using the @code{\tempo} command.  In this
case the tempo of quarter notes is set to 72 beats per minute.


If there is a @code{\midi} command in a @code{\score}, only MIDI will
be produced.  When notation is needed too, a @code{\paper} block must
be added

@example 
\score @{
    @var{...music...}
    \midi @{ \tempo 4=72 @}
    \paper @{ @}
@}
@end example 
@cindex paper 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 extremities.  The fractions can be adjusted by
@code{dynamicAbsoluteVolumeFunction} in @internalsref{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}.


@node MIDI block
@section MIDI block
@cindex MIDI block


The MIDI block is analogous to the paper block, but it is somewhat
simpler.  The @code{\midi} block can contain
@cindex MIDI block

@itemize @bullet
  @item a @code{\tempo} definition, and
  @item context definitions.
@end itemize

A number followed by a period is interpreted as a real number, so
for setting the tempo for dotted notes, an extra space should be
inserted, for example

@example
  \midi @{ \tempo 4 . = 120 @} 
@end example


@cindex context definition

Context definitions follow precisely the same syntax as within the
\paper 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
@section MIDI instrument names

@cindex instrument names
@cindex @code{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}.

@refbugs

If the selected string does not exactly match, the default is used,
which is the Grand Piano.

