@c -*- coding: latin-1; mode: texinfo; -*-
@node Sound
@chapter Sound
@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.

@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.  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 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 

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 

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{\layout} block must
be added

@example 
\score @{
  @var{...music...}
  \midi @{ \tempo 4=72 @}
  \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 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 layout 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
\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
@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}.

If the selected instrument does not exactly match an instrument from
the list of MIDI instruments, the Grand Piano instrument is used.