Documentation/mudela-course.doc

   1 % -*-LaTeX-*-
   2 % this document should be run through the mudela-book script after lilypond
   3 % has been installed.
   4
   5
   6 \documentclass{article}
   7 \usepackage{a4wide}
   8 \title{Mudela and LilyPond crash course}
   9 \author{Han-Wen Nienhuys}
  10 \def\file#1{{\texttt{#1}}}
  11
  12 \begin{document}
  13 \maketitle
  14 \def\interexample{\par Produces the following:\par}
  15 \def\preexample{\par\medskip}
  16 \def\postexample{\par\medskip}
  17
  18 \emph{This document is not complete yet. It's just a brief blurb which
  19   skimps some features of Mudela}
  20
  21 \section{Who is who}
  22
  23 This document describes two different things
  24 \begin{description}
  25 \item[Mudela] A language for defining music.
  26
  27 \item[LilyPond] A package (the only one existing :-) which can
  28   read a mudela file and interpret it.
  29
  30   The name ``LilyPond'' does not have much to do with the purpose of
  31   the package, but we have a special emotional attachment with the
  32   name.  (Of course we are not telling why we chose it; this is an
  33   excercise for the reader, most of the vital clues are contained in
  34   the documentation and the source code.  If you have guess, then let
  35   me know)
  36 \end{description}
  37
  38 \section{Overview}
  39
  40
  41 Let's start with a very simple example, we will enter ``twinkle twinkle
  42 little star.''  We start with the most important part: the notes.
  43
  44 Imagine being in a music-lesson, and that you made an error playing
  45 ``twinkle twinkle''.  Your teacher asks you to read out loud the
  46 melody of the song, just to verify your eyesight.  You would probably
  47 say something like
  48 \begin{quote}
  49   A quarter note C, Another quarter note C, a quarter G, another one, etc.
  50 \end{quote}
  51
  52 Mudela tries to capture this verbal presentation of sheet music, in
  53 the following way.  The first line of twinkle twinkle is written in
  54 as follows
  55 \begin{verbatim}
  56 c4 c4 g4 g4 a4 a4 g2
  57 f4 f4 e4 e4 d4 d4 c2
  58 \end{verbatim}
  59
  60 The notes are entered with names (a, b, c) combined with numbers
  61 (2,4).  The names designate the pitches, the numbers the durations: 4
  62 is a quarter note, 2 a half note, etc.
  63
  64 Now all we have to specify what should be done with the music.  We
  65 want a paper version, so we combine the music with a ``output this on
  66 paper'' statement.  These two are combined in ``score'' block.  This
  67 is the final result with its output.   We add a comment (the line
  68 starting with \verb+%+).
  69 Put this into a file
  70 called \file{twinkle.ly}
  71
  72 \begin{verbatim}
  73
  74 % twinkle, v1
  75 \score {
  76         \melodic {
  77                 c4 c4 g4 g4 a4 a4 g2
  78                 f4 f4 e4 e4 d4 d4 c2
  79         }
  80         \paper {}
  81 }
  82 \end{verbatim}
  83
  84 there are a few things to note about this example:
  85
  86 The braces are grouping characters. In general, in mudela data entry
  87 for a data section called ``foobar'' looks like this:
  88
  89 \begin{verbatim}
  90 \foobar { ...... }
  91 \end{verbatim}
  92
  93 To see if it actually works, we run it through LilyPond.  Invoke the
  94 command
  95 \begin{verbatim}
  96         lilypond twinkle.ly
  97 \end{verbatim}
  98 When LilyPond starts working it will produce various ``operator
  99 pacification'' messages, which you can safely ignore for now.  The run
 100 should have left a file called \file{lelie.tex} in your working
 101 directory.  You can process that file with \TeX, and it will look like
 102 this:
 103
 104 \begin{mudela}
 105 \score {
 106         \melodic {
 107                 c4 c4 g4 g4 a4 a4 g2
 108                 f4 f4 e4 e4 d4 d4 c2
 109         }
 110         \paper {}
 111 }
 112 \end{mudela}
 113
 114 As you can see, this is the song that we wanted, albeit a little
 115 low-pitched.  You would probably want a version of the song which has
 116 all notes an octave higher.  This can be done by adding a
 117 \verb+\octave+ command to the source.  This sets the default octave
 118 for all notes.  Another convenience is the default duration: if you do
 119 not specify a duration with the notename, the last explicitly entered
 120 is used.  The improved version reads thus
 121
 122
 123 \begin[verbatim]{mudela}
 124   % twinkle v2
 125 \score {
 126         \melodic {
 127                 \octave c';
 128                 c4 c g g a a g2
 129                 f4 f e e d d c2
 130         }
 131         \paper {}
 132 }
 133 \end{mudela}
 134
 135
 136
 137 \begin[verbatim]{mudela}
 138   \score {
 139         \melodic {      % {...} is a voice
 140         c'4 g'4         % c and g are pitches, 4 is the duration
 141                         % (crotchet/quarter note)
 142         c''4 ''c4       % c' is 1 octave up, 'c 1 down.
 143         <c'4 g'4>       % <...> is a chord
 144         }
 145 }
 146 \end{mudela}
 147
 148
 149 \begin[fragment,verbatim]{mudela}
 150   { c4 e4 g4 }
 151 \end{mudela}
 152
 153 Basics: the \verb+%+ introduces a comment. All music is inside a
 154 \verb+\score+ block which represents one movement, ie one contiguous
 155 block of music.  Voices are grouped by \verb+{+ and \verb+}+ and
 156 chords by \verb+<+ and \verb+>+.
 157
 158
 159 The \verb+\octave+ command controls the default pitch (octave). If you
 160 do not specify duration, the last one entered is used.  The
 161 \verb+\paper+ block contains parameters for spacing and dimensions.
 162
 163 \begin[verbatim]{mudela}
 164 \score {
 165         % twinkle twinkle little star
 166         \melodic {
 167                 \octave c';
 168                 c4 c g g a a g2
 169                 f4 f e e d [d8. e16] c2
 170
 171         }
 172         \paper { linewidth = 5.\cm; }
 173 }
 174 \end{mudela}
 175
 176 A more complex example; The multi command controls at what level the
 177 different components of a chord are interpreted.  The LilyPond chord
 178 is much more general than a traditional chord.  Multiple voices on a
 179 staff are entered as a chord of voices.  A score is a chord of staffs,
 180 etc.
 181
 182 \begin[verbatim]{mudela}
 183
 184 \score{
 185   \melodic
 186     { \octave c'; c4 c4
 187        \multi 1 <  { c2 c2 } { c'2 c'2 } >
 188        \multi 2 <  { \stemdown c2 c2 } { \stemup c'2 c'2 } >
 189        \multi 3 <
 190         { \clef "bass"; c2 c2 }
 191         { \meter 2/4;\bar "||";
 192           \key fis cis gis; c'2 c'2 } >
 193          c2 c1
 194       c1 c1
 195        \multi 1< \multi 3 <
 196       { \meter 2/4; \clef "violin"; c2 c2 }
 197         { \meter 2/4; \clef "bass"; c2 c2 }
 198       >
 199       \multi 3 <
 200         { \meter 2/4; \clef "violin"; c2 c2 }
 201         { \meter 2/4; \clef "bass"; c2 c2 }
 202       >
 203       >
 204     }
 205 }
 206
 207 \end{mudela}
 208
 209
 210 LilyPond is designed to handle complicated stuff automatically.
 211 Expertise should be in the program, not in the user.
 212
 213 The following example shows how multiple voices on the same staff are
 214 handled graciously (well, somewhat). If the noteheads of different
 215 voices collide, they are moved horizontally. Rests are moved
 216 vertically.
 217
 218 [FIXME]
 219 \def\bla{
 220 \begin[verbatim]{mudelaXX}
 221 two_voice = \melodic
 222          \multi 2 <
 223           {     \octave c'; \stemdown
 224                 c4 d e f g2~  g4 a [c8 d e f] c2| }
 225           { \stemup
 226                 g4 f e g ~ g2 g2  c4 g4 g2 }
 227
 228         >
 229
 230 two_voice_steminvert = \melodic
 231         \multi 2 <
 232           {     \octave c'; \stemup
 233 % the f and g on 4th beat are exceptionally ugh.
 234                 c4 d e f g2 g4 a | }
 235           { \stemdown
 236                 g4 f e g  g2 g2 }
 237
 238         >
 239
 240 three_voice = \melodic
 241         \multi 2 <
 242         { \stemup
 243                 g4 f e f g a g2 }
 244         { \property Voice.hshift = 1 \stemup
 245                 e2  e2  e2  e2 }
 246         { \stemdown
 247                 c4 d e d c d es }
 248         >
 249
 250
 251 restsII = \melodic {
 252         \octave c';
 253                         \multi2 <
 254                                 { \stemup  g'8 f' e' d' c' b a g f e d c }
 255                                 { \stemdown r  r  r  r  r  r r r r r r r }
 256                         >
 257                         r8 r4
 258                         \multi 2 <  r8 r8 >
 259                         \multi 2 <  r8 r8 r8 >
 260                         \multi 2 <  r8 r8 r8 r8 >
 261                         \multi 2 <  r r >
 262                         \multi 2 <  r r r >
 263                         \stemup
 264                         [c''8 r8 c''8 c''8]
 265                         [c8 r8 c8 c8]
 266 }
 267
 268 \score{
 269         \melodic {  \$two_voice  \$two_voice_steminvert
 270                         \$three_voice  \restsII }
 271 }
 272
 273 }
 274 \end{document}