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
 167 @uref{http://www.gre.ac.uk/~c.walshaw/abc2mtex/abc.txt}. abc2ly
 168 translates from ABC to LilyPond. It is invoked as follows:
 169
 170 @example
 171         abc2ly [@var{option}]@dots{} @var{abc-file}
 172 @end example
 173
 174 The following options are supported by abc2ly:
 175
 176 @table @code
 177 @item   -h,--help
 178 this help
 179 @item  -o,--output=@var{file}
 180 set output filename to @var{file}.
 181 @item  -v,--version
 182 print version information.
 183 @end table
 184
 185 There is a rudimentary facility for adding lilypond code to the ABC
 186 source file.  If you say:
 187
 188 @example
 189         %%LY voices \property Voice.autoBeaming=##f
 190 @end example
 191
 192 This will cause the text following the keyword ``voices'' to be inserted
 193 into the current voice of the lilypond output file.
 194
 195 Similarly:
 196
 197 @example
 198         %%LY slyrics more words
 199 @end example
 200
 201 will cause the text following the ``slyrics'' keyword to be inserted
 202 into the current line of lyrics.
 203
 204
 205 @refbugs
 206
 207 The ABC standard is not very ``standard''. For extended features
 208 (eg. polyphonic music) different conventions exist.
 209
 210 Multiple tunes in one file cannot be converted.
 211
 212 ABC synchronizes words and notes at the beginning of a line; abc2ly does
 213 not.
 214
 215 abc2ly ignores the ABC beaming.
 216
 217 @node Invoking pmx2ly
 218 @section Invoking pmx2ly
 219
 220 PMX is a MusiXTeX preprocessor written by Don Simons. More information
 221 on PMX is available from the following site:
 222
 223 @quotation
 224 @uref{http://icking-music-archive.sunsite.dk/Misc/Music/musixtex/software/pmx/}.
 225 @end quotation
 226
 227 @cindex PMX
 228 @cindex MusiXTeX
 229 @cindex Simons, Don
 230
 231 pmx2ly converts from PMX to LilyPond input. The program is invoked as
 232 follows:
 233
 234 @example
 235         pmx2ly [@var{option}]@dots{} @var{pmx-file}
 236 @end example
 237
 238 The following options are supported by pmx2ly:
 239
 240 @table @code
 241 @item   -h,--help
 242 this help
 243 @item  -o,--output=FILE
 244 set output filename to FILE
 245 @item  -v,--version
 246 version information
 247 @end table
 248
 249
 250 @node Invoking musedata2ly
 251 @section Invoking musedata2ly
 252
 253 @cindex Musedata
 254 @cindex CCARH
 255
 256 Musedata (@uref{http://www.musedata.org/}) is an electronic library of
 257 classical music scores, currently comprising about 800 composition
 258 dating from 1700 to 1825.  The music is encoded in so-called Musedata
 259 format.  musedata2ly converts a set of musedata files to one .ly file,
 260 and will include a @code{\header} field if a @file{.ref} file is
 261 supplied. It is invoked as follows:
 262
 263 @example
 264         musedata2ly [@var{option}]@dots{} @var{musedata-files}
 265 @end example
 266
 267 The following options are supported by musedata2ly:
 268
 269 @table @code
 270 @item   -h,--help
 271 print help
 272 @item  -o,--output=@var{file}
 273 set output filename to @var{file}
 274 @item  -v,--version
 275 version information
 276 @item  -r,--ref=@var{reffile}
 277  read background information from ref-file
 278 @var{reffile}
 279 @end table
 280
 281 @refbugs
 282
 283 musedata2ly converts only a small subset musedata.
 284
 285 @node Invoking mup2ly
 286 @section Invoking mup2ly
 287
 288 MUP (Music Publisher) is a shareware music notation program by Arkkra
 289 Enterprises.  It is also the name of the input format.  Mup2ly will
 290 convert part of a Mup file to a ready-to-use LilyPond file. Mup2ly is
 291 invoked as follows:
 292
 293 @cindex Music Publisher
 294 @cindex MUP
 295 @cindex Arkkra
 296
 297 @example
 298         mup2ly [@var{option}]@dots{} @var{mup-file}
 299 @end example
 300
 301 The following options are supported by mup2ly:
 302
 303 @table @code
 304 @item   -d,--debug
 305 show what constructs are not converted, but skipped.
 306 @item D, --define=@var{name}[=@code{exp}]
 307 define macro @var{name} with opt expansion @code{exp}
 308 @item   -E,--pre-process
 309 only run the pre-processor
 310 @item   -h,--help
 311 print help
 312 @item  -o,--output=@var{file}
 313 write output to @var{file}
 314 @item  -v,--version
 315 version information
 316 @item  -w,--warranty
 317 print warranty and copyright.
 318 @end table
 319
 320
 321 @refbugs
 322
 323 Currently, only plain notes (pitches, durations), voices and staves are
 324 converted.
 325
 326
 327