Documentation/user/non-music.itely

   1 @c -*- coding: utf-8; mode: texinfo; -*-
   2 @c This file is part of lilypond.tely
   3 @ignore
   4     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
   5
   6     When revising a translation, copy the HEAD committish of the
   7     version that you are working on.  See TRANSLATION for details.
   8 @end ignore
   9
  10 @c \version "2.11.38"
  11
  12 @c A menu is needed before every deeper *section nesting of @node's; run
  13 @c     M-x texinfo-all-menus-update
  14 @c to automatically fill in these menus before saving changes
  15
  16 @node Non-musical notation
  17 @chapter Non-musical notation
  18
  19 This section deals with general LilyPond issues, rather than
  20 specific notation.
  21
  22 @menu
  23 * MIDI output::
  24 * other midi::
  25 @end menu
  26
  27
  28 @node MIDI output
  29 @section MIDI output
  30
  31 @cindex Sound
  32 @cindex MIDI
  33
  34 MIDI (Musical Instrument Digital Interface) is a standard for
  35 connecting and controlling digital instruments.  A MIDI file is a
  36 series of notes in a number of tracks.  It is not an actual
  37 sound file; you need special software to translate between the
  38 series of notes and actual sounds.
  39
  40 Pieces of music can be converted to MIDI files, so you can listen to
  41 what was entered.  This is convenient for checking the music; octaves
  42 that are off or accidentals that were mistyped stand out very much
  43 when listening to the MIDI output.
  44
  45 @knownissues
  46
  47 Many musically interesting effects, such as swing, articulation,
  48 slurring, etc., are not translated to midi.
  49
  50 The midi output allocates a channel for each staff, and one for global
  51 settings.  Therefore the midi file should not have more than 15 staves
  52 (or 14 if you do not use drums).  Other staves will remain silent.
  53
  54 Not all midi players correctly handle tempo changes in the midi
  55 output.  Players that are known to work include
  56 @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
  57
  58 @menu
  59 * Creating MIDI files::
  60 * MIDI block::
  61 * MIDI instrument names::
  62 * What goes into the MIDI?  FIXME::
  63 @end menu
  64
  65 @node Creating MIDI files
  66 @subsection Creating MIDI files
  67
  68 To create a MIDI from a music piece of music, add a @code{\midi} block
  69 to a score, for example,
  70
  71 @example
  72 \score @{
  73   @var{...music...}
  74    \midi @{
  75      \context @{
  76        \Score
  77        tempoWholesPerMinute = #(ly:make-moment 72 4)
  78        @}
  79      @}
  80 @}
  81 @end example
  82
  83 The tempo can be specified using the @code{\tempo} command within the
  84 actual music, see @ref{Metronome marks}.  An alternative, which does not
  85 result in a metronome mark in the printed score, is shown in the example
  86 above.  In this example the tempo of quarter notes is set to 72 beats per
  87 minute.
  88 This kind of tempo
  89 specification can not take dotted note lengths as an argument.  In this
  90 case, break the dotted notes into smaller units.  For example, a tempo
  91 of 90 dotted quarter notes per minute can be specified as 270 eighth
  92 notes per minute
  93
  94 @example
  95 tempoWholesPerMinute = #(ly:make-moment 270 8)
  96 @end example
  97
  98 If there is a @code{\midi} command in a @code{\score}, only MIDI will
  99 be produced.  When notation is needed too, a @code{\layout} block must
 100 be added
 101
 102 @example
 103 \score @{
 104   @var{...music...}
 105   \midi @{ @}
 106   \layout @{ @}
 107 @}
 108 @end example
 109 @cindex layout block
 110
 111
 112
 113 Ties, dynamics, and tempo changes are interpreted.  Dynamic marks,
 114 crescendi and decrescendi translate into MIDI volume levels.  Dynamic
 115 marks translate to a fixed fraction of the available MIDI volume
 116 range, crescendi and decrescendi make the volume vary linearly between
 117 their two extremes.  The fractions can be adjusted by
 118 @code{dynamicAbsoluteVolumeFunction} in @rinternals{Voice} context.
 119 For each type of MIDI instrument, a volume range can be defined.  This
 120 gives a basic equalizer control, which can enhance the quality of
 121 the MIDI output remarkably.  The equalizer can be controlled by
 122 setting @code{instrumentEqualizer}, or by setting
 123
 124 @example
 125 \set Staff.midiMinimumVolume = #0.2
 126 \set Staff.midiMaximumVolume = #0.8
 127 @end example
 128
 129 To remove dynamics from the MIDI output, insert the following lines
 130 in the @code{\midi@{@}} section.
 131
 132 @example
 133 \midi @{
 134   ...
 135   \context @{
 136     \Voice
 137     \remove "Dynamic_performer"
 138   @}
 139 @}
 140 @end example
 141
 142
 143 @knownissues
 144
 145 Unterminated (de)crescendos will not render properly in the midi file,
 146 resulting in silent passages of music.  The workaround is to explicitly
 147 terminate the (de)crescendo.  For example,
 148
 149 @example
 150 @{ a\< b c d\f @}
 151 @end example
 152
 153 @noindent
 154 will not work properly but
 155
 156 @example
 157 @{ a\< b c d\!\f @}
 158 @end example
 159
 160 @noindent
 161 will.
 162
 163
 164 MIDI output is only created when the @code{\midi} command is within
 165 a @code{\score} block.  If you put it within an explicitly instantiated
 166 context ( i.e. @code{\new Score} ) the file will fail.  To solve this,
 167 enclose the @code{\new Score} and the @code{\midi} in a @code{\score} block.
 168
 169 @example
 170 \score @{
 171   \new Score @{ @dots{}notes@dots{} @}
 172   \midi
 173 @}
 174 @end example
 175
 176
 177 @node MIDI block
 178 @subsection MIDI block
 179 @cindex MIDI block
 180
 181
 182 The MIDI block is analogous to the layout block, but it is somewhat
 183 simpler.  The @code{\midi} block is similar to @code{\layout}.  It can contain
 184 context definitions.
 185
 186
 187 @cindex context definition
 188
 189 Context definitions follow precisely the same syntax as within the
 190 \layout block.  Translation modules for sound are called performers.
 191 The contexts for MIDI output are defined in @file{ly/@/performer@/-init@/.ly}.
 192
 193
 194 @node MIDI instrument names
 195 @subsection MIDI instrument names
 196
 197 @cindex instrument names
 198 @funindex Staff.midiInstrument
 199
 200 The MIDI instrument name is set by the @code{Staff.midiInstrument}
 201 property.  The instrument name should be chosen from the list in
 202 @ref{MIDI instruments}.
 203
 204 @example
 205 \set Staff.midiInstrument = "glockenspiel"
 206 @var{...notes...}
 207 @end example
 208
 209 If the selected instrument does not exactly match an instrument from
 210 the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
 211 instrument is used.
 212
 213
 214 @node What goes into the MIDI?  FIXME
 215 @subsection What goes into the MIDI?  FIXME
 216
 217 @menu
 218 * Repeats and MIDI::
 219 @end menu
 220
 221 @node Repeats and MIDI
 222 @subsubsection Repeats and MIDI
 223
 224 @cindex expanding repeats
 225 @funindex \unfoldRepeats
 226
 227 With a little bit of tweaking, all types of repeats can be present
 228 in the MIDI output.  This is achieved by applying the
 229 @code{\unfoldRepeats} music function.  This function changes all
 230 repeats to unfold repeats.
 231
 232 @lilypond[quote,verbatim,fragment,line-width=8.0\cm]
 233 \unfoldRepeats {
 234   \repeat tremolo 8 {c'32 e' }
 235   \repeat percent 2 { c''8 d'' }
 236   \repeat volta 2 {c'4 d' e' f'}
 237   \alternative {
 238     { g' a' a' g' }
 239     {f' e' d' c' }
 240   }
 241 }
 242 \bar "|."
 243 @end lilypond
 244
 245 When creating a score file using @code{\unfoldRepeats} for MIDI,
 246 it is necessary to make two @code{\score} blocks: one for MIDI
 247 (with unfolded repeats) and one for notation (with volta, tremolo,
 248 and percent repeats).  For example,
 249
 250 @example
 251 \score @{
 252   @var{..music..}
 253   \layout @{ .. @}
 254 @}
 255 \score @{
 256   \unfoldRepeats @var{..music..}
 257   \midi @{ .. @}
 258 @}
 259 @end example
 260
 261
 262 @node other midi
 263 @section other midi
 264
 265 Micro tones are also exported to the MIDI file.
 266
 267 Figured bass has no effect on MIDI.
 268