Documentation/user/sound-output.itexi

   1 @c -*- coding: latin-1; mode: texinfo; -*-
   2 @node Sound
   3 @chapter Sound
   4 @cindex Sound
   5
   6 @cindex MIDI
   7
   8 MIDI (Musical Instrument Digital Interface) is a standard for
   9 connecting and controlling digital instruments.  A MIDI file is a
  10 series of notes in a number of tracks.  It is not an actual
  11 sound file; you need special software to translate between the
  12 series of notes and actual sounds.
  13
  14 Pieces of music can be converted to MIDI files, so you can listen to
  15 what was entered.  This is convenient for checking the music; octaves
  16 that are off or accidentals that were mistyped stand out very much
  17 when listening to the MIDI output.
  18
  19 @refbugs
  20
  21 Many musically interesting effects, such as swing, articulation,
  22 slurring, etc., are not translated to midi.
  23
  24 The midi output allocates a channel for each staff, and one for global
  25 settings.  Therefore the midi file should not have more than 15 staves
  26 (or 14 if you do not use drums).  Other staves will remain silent.
  27
  28 Not all midi players correctly handle tempo change in the midi
  29 output.  Players that are known to work include
  30 @uref{http://timidity.sourceforge.net/,timidity}.
  31
  32
  33
  34
  35
  36 @menu
  37 * Creating MIDI files::
  38 * MIDI block::
  39 * MIDI instrument names::
  40 @end menu
  41
  42 @node Creating MIDI files
  43 @section Creating MIDI files
  44
  45 To create a MIDI from a music piece of music, add a @code{\midi} block
  46 to a score, for example,
  47
  48 @example
  49 \score @{
  50   @var{...music...}
  51   \midi @{ \tempo 4=72 @}
  52 @}
  53 @end example
  54
  55 The tempo is specified using the @code{\tempo} command.  In this
  56 case the tempo of quarter notes is set to 72 beats per minute.
  57
  58
  59 If there is a @code{\midi} command in a @code{\score}, only MIDI will
  60 be produced.  When notation is needed too, a @code{\layout} block must
  61 be added
  62
  63 @example
  64 \score @{
  65   @var{...music...}
  66   \midi @{ \tempo 4=72 @}
  67   \layout @{ @}
  68 @}
  69 @end example
  70 @cindex layout block
  71
  72
  73
  74 Ties, dynamics and tempo changes are interpreted.  Dynamic marks,
  75 crescendi and decrescendi translate into MIDI volume levels.  Dynamic
  76 marks translate to a fixed fraction of the available MIDI volume
  77 range, crescendi and decrescendi make the volume vary linearly between
  78 their two extremities.  The fractions can be adjusted by
  79 @code{dynamicAbsoluteVolumeFunction} in @internalsref{Voice} context.
  80 For each type of MIDI instrument, a volume range can be defined.  This
  81 gives a basic equalizer control, which can enhance the quality of
  82 the MIDI output remarkably.  The equalizer can be controlled by
  83 setting @code{instrumentEqualizer}.
  84
  85
  86 @node MIDI block
  87 @section MIDI block
  88 @cindex MIDI block
  89
  90
  91 The MIDI block is analogous to the layout block, but it is somewhat
  92 simpler.  The @code{\midi} block can contain
  93 @cindex MIDI block
  94
  95 @itemize @bullet
  96   @item a @code{\tempo} definition, and
  97   @item context definitions.
  98 @end itemize
  99
 100 A number followed by a period is interpreted as a real number, so
 101 for setting the tempo for dotted notes, an extra space should be
 102 inserted, for example
 103
 104 @example
 105   \midi @{ \tempo 4 . = 120 @}
 106 @end example
 107
 108
 109 @cindex context definition
 110
 111 Context definitions follow precisely the same syntax as within the
 112 \layout block.  Translation modules for sound are called performers.
 113 The contexts for MIDI output are defined in @file{ly/performer-init.ly}.
 114
 115
 116 @node MIDI instrument names
 117 @section MIDI instrument names
 118
 119 @cindex instrument names
 120 @cindex @code{Staff.midiInstrument}
 121
 122 The MIDI instrument name is set by the @code{Staff.midiInstrument}
 123 property.  The instrument name should be chosen from the list in
 124 @ref{MIDI instruments}.
 125
 126 If the selected instrument does not exactly match an instrument from
 127 the list of MIDI instruments, the Grand Piano instrument is used.
 128