Documentation/user/converters.itely

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