Documentation/user/converters.itely

   1 @c -*-texinfo-*-
   2
   3 @node Conversion tools
   4 @chapter Converting to LilyPond format.
   5
   6
   7 @menu
   8 * midi2ly::
   9 * etf2ly::
  10 * abc2ly::
  11 * pmx2ly::
  12 * musedata2ly::
  13 * mup2ly::
  14 @end menu
  15
  16 @node midi2ly
  17 @section midi2ly
  18
  19 @cindex MIDI
  20 @cindex importing MIDI
  21
  22 Midi2ly translates a MIDI input file to a LilyPond source file. MIDI
  23 (Music Instrument Digital Interface) is a standard for digital
  24 instruments: it specifies cabling, a serial protocol and a file format.
  25
  26 The MIDI file format is a de facto standard format for exporting music
  27 from other programs, so this capability may come in useful when you want
  28 to import files from a program that has no converter for its native
  29 format.
  30
  31 It is possible to record a MIDI file using a digital keyboard, and then
  32 convert it to @file{.ly}. However, human players are not rhythmically
  33 exact enough to make a MIDI to LY conversion trivial.  midi2ly tries to
  34 compensate for these timing errors, but is not very good at this. It is
  35 therefore not recommended to use midi2ly for human-generated midi
  36 files. Correcting the quantization mistakes of the human player takes a
  37 lot of time.
  38
  39 Hackers who know about signal processing are invited to write a more
  40 robust midi2ly.  midi2ly is written in Python, using a module written in
  41 C to parse the MIDI files.
  42
  43
  44 @subsection Invoking midi2ly
  45
  46 @example
  47         midi2ly [@var{OPTION}]@dots{} @var{MIDI-FILE}
  48 @end example
  49
  50 @unnumberedsubsec Options
  51
  52 @table @code
  53 @item -b, --no-quantify,
  54     Write exact durations, e.g.: `a4*385/384'.
  55 @item -D, --debug,
  56     Print lots of debugging stuff.
  57 @item -h, --help,
  58     Show a summary of usage.
  59 @item -I, --include=@file{DIR},
  60     Add DIR to search path.
  61 @item -k, --key=ACC[:MINOR],
  62     Set default key.  ACC > 0 sets number of sharps; ACC < 0 sets number
  63     of flats.  A minor key is indicated by ":1".
  64 @item -n, --no-silly,
  65     Assume no plets or double dots, assume smallest (reciprocal) duration 16.
  66 @item -o, --output=@file{FILE},
  67     Set @file{FILE} as default output.
  68 @item -p, --no-plets,
  69     Assume no plets.
  70 @item -q, --quiet,
  71     Be quiet.
  72 @item -s, --smallest=N,
  73     Assume no shorter (reciprocal) durations than N.
  74 @item -v, --verbose,
  75     Be verbose.
  76 @item -w, --warranty,
  77     Show the warranty with which midi2ly comes. (It comes with @strong{NO WARRANTY}!)
  78 @item -x, --no-double-dots,
  79     Assume no double dotted notes.
  80 @end table
  81
  82
  83 @node etf2ly
  84 @section etf2ly
  85
  86 @cindex ETF
  87 @cindex enigma
  88 @cindex Finale
  89 @cindex Coda Technology
  90
  91 ETF (Enigma Transport Format) is a format used by Coda Music
  92 Technology's Finale product. This program will convert part of an ETF
  93 file to a ready-to-use LilyPond file.
  94
  95 @subsection Invoking etf2ly
  96 Usage:
  97
  98 @example
  99         etf2ly [@var{OPTION}]@dots{} @var{ETF-FILE}
 100 @end example
 101
 102 Convert ETF to LilyPond.
 103
 104 @unnumberedsubsec Options
 105 @table @code
 106 @item   -h,--help
 107 this help
 108 @item  -o,--output=FILE
 109 set output filename to FILE
 110 @item  -v,--version
 111 version information
 112 @end table
 113
 114
 115 @refbugs
 116
 117 The list of articulation scripts is incomplete.  Empty measures confuse
 118 etf2ly.
 119
 120
 121 @node abc2ly
 122 @section abc2ly
 123
 124 ABC is a fairly simple ASCII based format. It is described at
 125 @uref{http://www.gre.ac.uk/~c.walshaw/abc2mtex/abc.txt}.
 126
 127 @cindex ABC
 128 @cindex Importing ABC
 129
 130 @subsection Invoking abc2ly
 131
 132 @example
 133         abc2ly [@var{OPTION}]@dots{} @var{ABC-FILE}
 134 @end example
 135
 136 Convert ABC to LilyPond.
 137
 138 There is a rudimentary facility for adding lilypond code to the ABC
 139 source file.  If you say:
 140
 141 @example
 142         %%LY voices \property Voice.noAutoBeaming=##t
 143 @end example
 144
 145 This will cause the text following the keyword ``voices'' to be inserted
 146 into the current voice of the lilypond output file.
 147
 148 Similarly:
 149
 150 @example
 151         %%LY slyrics more words
 152 @end example
 153
 154 will cause the text following the ``slyrics'' keyword to be inserted
 155 into the current line of lyrics.
 156
 157 @unnumberedsubsec Options
 158 @table @code
 159 @item   -h,--help
 160 this help
 161 @item  -o,--output=FILE
 162 set output filename to FILE
 163 @item  -v,--version
 164 version information
 165 @end table
 166
 167 @refbugs
 168
 169 The ABC standard is not very "standard". For extended features
 170 (eg. polyphonic music) different conventions exist.
 171
 172 Multiple tunes in one file cannot be converted.
 173
 174 ABC synchronizes words and notes at the beginning of a line; abc2ly does
 175 not.
 176
 177 abc2ly ignores the ABC beaming.
 178
 179 @node pmx2ly
 180 @section pmx2ly
 181
 182 PMX is a MusiXTeX preprocessor written by Don Simons, see
 183 @uref{http://icking-music-archive.sunsite.dk/Misc/Music/musixtex/software/pmx/}.
 184
 185 @cindex PMX
 186 @cindex MusiXTeX
 187 @cindex Simons, Don
 188
 189 @subsection Invoking pmx2ly
 190
 191 @example
 192         pmx2ly [@var{OPTION}]@dots{} @var{PMX-FILE}
 193 @end example
 194
 195 Convert PMX to LilyPond.
 196
 197 @unnumberedsubsec Options
 198
 199 @table @code
 200 @item   -h,--help
 201 this help
 202 @item  -o,--output=FILE
 203 set output filename to FILE
 204 @item  -v,--version
 205 version information
 206 @end table
 207
 208
 209 @node musedata2ly
 210 @section musedata2ly
 211
 212 @cindex Musedata
 213 @cindex CCARH
 214
 215 Musedata (@uref{http://www.musedata.org/}) is an electronic library of
 216 classical music scores, currently comprising about 800 composition
 217 dating from 1700 to 1825.  The music is encoded in so-called Musedata
 218 format
 219 (@uref{http://www.ccarh.org/publications/books/beyondmidi/online/musedata}).
 220 musedata2ly converts a set of musedata files to one .ly file, and will
 221 include a @code{\header} field if a @file{.ref} file is supplied
 222
 223 @subsection Invoking musedata2ly
 224
 225 @example
 226         musedata2ly [@var{OPTION}]@dots{} @var{MUSEDATA-FILE}
 227 @end example
 228
 229 Convert Musedata to LilyPond.
 230
 231 @unnumberedsubsec Options
 232
 233 @table @code
 234 @item   -h,--help
 235 print help
 236 @item  -o,--output=@var{file}
 237 set output filename to @var{file}
 238 @item  -v,--version
 239 version information
 240 @item  -r,--ref=@var{reffile}
 241  read background information from ref-file
 242 @var{REFFILE}
 243 @end table
 244
 245
 246 @node mup2ly
 247 @section mup2ly
 248
 249 MUP (Music Publisher) is a shareware music notation program by Arkkra
 250 Enterprises.  It is also the name of the input format.  Mup2ly will
 251 convert part of a Mup file to a ready-to-use LilyPond file.
 252
 253 @cindex MUP
 254 @cindex Arkkra
 255
 256 @subsection Invoking mup2ly
 257
 258 @example
 259         mup2ly [@var{OPTION}]@dots{} @var{MUP-FILE}
 260 @end example
 261
 262 Convert Mup to LilyPond.
 263
 264 @unnumberedsubsec Options
 265
 266 @table @code
 267 @item   -d,--debug
 268 show what constructs are not converted, but skipped.
 269 @item D, --define=@var{NAME}[=@code{EXP}]
 270 define macro @var{NAME} with opt expansion @code{EXP}
 271 @item   -E,--pre-process
 272 only run the pre-processor
 273 @item   -h,--help
 274 print help
 275 @item  -o,--output=FILE
 276 write output to @var{FILE}
 277 @item  -v,--version
 278 version information
 279 @item  -w,--warranty
 280 print warranty and copyright.  Mup2ly comes with absolutely @strong{NO WARRANTY}.
 281 @end table
 282
 283
 284 @refbugs
 285
 286 Currently, only plain notes (pitches, durations), voices and staves are
 287 converted.
 288
 289
 290