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 It is possible to record a MIDI file using a digital keyboard, and then
  79 convert it to @file{.ly}. However, human players are not rhythmically
  80 exact enough to make a MIDI to LY conversion trivial.  midi2ly tries to
  81 compensate for these timing errors, but is not very good at this. It is
  82 therefore not recommended to use midi2ly for human-generated midi files.
  83
  84 Hackers who know about signal processing are invited to write a more
  85 robust midi2ly.  midi2ly is written in Python, using a module written in
  86 C to parse the MIDI files.
  87
  88 It is invoked as follows:
  89 @example
  90         midi2ly [@var{option}]@dots{} @var{midi-file}
  91 @end example
  92
  93 The following options are supported by midi2ly:
  94
  95 @table @code
  96 @item -b, --no-quantify,
  97     Write exact durations, e.g.: `a4*385/384'.
  98 @item -D, --debug,
  99     Print lots of debugging stuff.
 100 @item -h, --help,
 101     Show a summary of usage.
 102 @item -I, --include=@var{dir},
 103     Add @var{dir} to search path.
 104 @item -k, --key=@var{acc}[:@var{minor}],
 105     Set default key.  @var{acc} > 0 sets number of sharps; @var{acc} < 0
 106 sets number
 107     of flats.  A minor key is indicated by ":1".
 108 @item -n, --no-silly,
 109     Assume no plets or double dots, assume smallest (reciprocal) duration 16.
 110 @item -o, --output=@var{file},
 111     Set @var{file} as default output.
 112 @item -p, --no-plets,
 113     Assume no plets.
 114 @item -q, --quiet,
 115     Be quiet.
 116 @item -s, --smallest=N,
 117     Assume no shorter (reciprocal) durations than N.
 118 @item -v, --verbose,
 119     Be verbose.
 120 @item -w, --warranty,
 121     Show the warranty with which midi2ly comes. (It comes with @strong{NO WARRANTY}!)
 122 @item -x, --no-double-dots,
 123     Assume no double dotted notes.
 124 @end table
 125
 126
 127 @node Invoking etf2ly
 128 @section Invoking etf2ly
 129
 130 @cindex ETF
 131 @cindex enigma
 132 @cindex Finale
 133 @cindex Coda Technology
 134
 135 ETF (Enigma Transport Format) is a format used by Coda Music
 136 Technology's Finale product. etf2ly will convert part of an ETF
 137 file to a ready-to-use LilyPond file.
 138
 139 It is invoked as follows:
 140 @example
 141         etf2ly [@var{option}]@dots{} @var{etf-file}
 142 @end example
 143
 144 The following options are supported by etf2ly.
 145 @table @code
 146 @item   -h,--help
 147 this help
 148 @item  -o,--output=FILE
 149 set output filename to FILE
 150 @item  -v,--version
 151 version information
 152 @end table
 153
 154
 155 @refbugs
 156
 157 The list of articulation scripts is incomplete.  Empty measures confuse
 158 etf2ly.
 159
 160
 161 @node Invoking abc2ly
 162 @section Invoking abc2ly
 163
 164 @cindex ABC
 165
 166 ABC is a fairly simple ASCII based format. It is described at the abc site:
 167 @quotation
 168 @uref{http://www.gre.ac.uk/~c.walshaw/abc2mtex/abc.txt}
 169 @end quotation
 170 abc2ly translates from ABC to LilyPond. It is invoked as follows:
 171
 172 @example
 173         abc2ly [@var{option}]@dots{} @var{abc-file}
 174 @end example
 175
 176 The following options are supported by abc2ly:
 177
 178 @table @code
 179 @item   -h,--help
 180 this help
 181 @item  -o,--output=@var{file}
 182 set output filename to @var{file}.
 183 @item  -v,--version
 184 print version information.
 185 @end table
 186
 187 There is a rudimentary facility for adding lilypond code to the ABC
 188 source file.  If you say:
 189
 190 @example
 191         %%LY voices \property Voice.autoBeaming=##f
 192 @end example
 193
 194 This will cause the text following the keyword ``voices'' to be inserted
 195 into the current voice of the lilypond output file.
 196
 197 Similarly:
 198
 199 @example
 200         %%LY slyrics more words
 201 @end example
 202
 203 will cause the text following the ``slyrics'' keyword to be inserted
 204 into the current line of lyrics.
 205
 206
 207 @refbugs
 208
 209 The ABC standard is not very ``standard''. For extended features
 210 (eg. polyphonic music) different conventions exist.
 211
 212 Multiple tunes in one file cannot be converted.
 213
 214 ABC synchronizes words and notes at the beginning of a line; abc2ly does
 215 not.
 216
 217 abc2ly ignores the ABC beaming.
 218
 219 @node Invoking pmx2ly
 220 @section Invoking pmx2ly
 221
 222 PMX is a MusiXTeX preprocessor written by Don Simons. More information
 223 on PMX is available from the following site:
 224
 225 @quotation
 226 @uref{http://icking-music-archive.sunsite.dk/Misc/Music/musixtex/software/pmx/}.
 227 @end quotation
 228
 229 @cindex PMX
 230 @cindex MusiXTeX
 231 @cindex Simons, Don
 232
 233 pmx2ly converts from PMX to LilyPond input. The program is invoked as
 234 follows:
 235
 236 @example
 237         pmx2ly [@var{option}]@dots{} @var{pmx-file}
 238 @end example
 239
 240 The following options are supported by pmx2ly:
 241
 242 @table @code
 243 @item   -h,--help
 244 this help
 245 @item  -o,--output=FILE
 246 set output filename to FILE
 247 @item  -v,--version
 248 version information
 249 @end table
 250
 251
 252 @node Invoking musedata2ly
 253 @section Invoking musedata2ly
 254
 255 @cindex Musedata
 256 @cindex CCARH
 257
 258 Musedata (@uref{http://www.musedata.org/}) is an electronic library of
 259 classical music scores, currently comprising about 800 composition
 260 dating from 1700 to 1825.  The music is encoded in so-called Musedata
 261 format.  musedata2ly converts a set of musedata files to one .ly file,
 262 and will include a @code{\header} field if a @file{.ref} file is
 263 supplied. It is invoked as follows:
 264
 265 @example
 266         musedata2ly [@var{option}]@dots{} @var{musedata-files}
 267 @end example
 268
 269 The following options are supported by musedata2ly:
 270
 271 @table @code
 272 @item   -h,--help
 273 print help
 274 @item  -o,--output=@var{file}
 275 set output filename to @var{file}
 276 @item  -v,--version
 277 version information
 278 @item  -r,--ref=@var{reffile}
 279  read background information from ref-file
 280 @var{reffile}
 281 @end table
 282
 283 @refbugs
 284
 285 musedata2ly converts only a small subset musedata.
 286
 287 @node Invoking mup2ly
 288 @section Invoking mup2ly
 289
 290 MUP (Music Publisher) is a shareware music notation program by Arkkra
 291 Enterprises.  It is also the name of the input format.  Mup2ly will
 292 convert part of a Mup file to a ready-to-use LilyPond file. Mup2ly is
 293 invoked as follows:
 294
 295 @cindex Music Publisher
 296 @cindex MUP
 297 @cindex Arkkra
 298
 299 @example
 300         mup2ly [@var{option}]@dots{} @var{mup-file}
 301 @end example
 302
 303 The following options are supported by mup2ly:
 304
 305 @table @code
 306 @item   -d,--debug
 307 show what constructs are not converted, but skipped.
 308 @item D, --define=@var{name}[=@code{exp}]
 309 define macro @var{name} with opt expansion @code{exp}
 310 @item   -E,--pre-process
 311 only run the pre-processor
 312 @item   -h,--help
 313 print help
 314 @item  -o,--output=@var{file}
 315 write output to @var{file}
 316 @item  -v,--version
 317 version information
 318 @item  -w,--warranty
 319 print warranty and copyright.
 320 @end table
 321
 322
 323 @refbugs
 324
 325 Currently, only plain notes (pitches, durations), voices and staves are
 326 converted.
 327
 328
 329