Documentation/user/converters.itely

   1 @c -*- coding: latin-1; mode: texinfo; -*-
   2
   3 @node Converting from other formats
   4 @chapter Converting from other formats
   5
   6 Music can be entered also by importing it from other formats.  This
   7 chapter documents the tools included in the distribution to do so.
   8 There are other tools that produce LilyPond input, for example GUI
   9 sequencers and XML converters.  Refer to the
  10 @uref{http://@/lilypond@/.org,website} for more details.
  11
  12
  13
  14 @menu
  15 * Invoking convert-ly::         Older LilyPond versions.
  16 * Invoking midi2ly::            Importing MIDI.
  17 * Invoking etf2ly::             Importing Finale.
  18 * Invoking abc2ly::             Importing ABC.
  19 * Invoking mup2ly::             Importing MUP.
  20 * Other formats::
  21 @end menu
  22
  23
  24 @node Invoking convert-ly
  25 @section Invoking @command{convert-ly}
  26
  27 The LilyPond input syntax is routinely changed to simplify it or improve
  28 it in different ways.  As a side effect of this, the LilyPond interpreter
  29 often is no longer compatible with older input files.  To remedy this,
  30 the program @command{convert-ly} can be used to deal with most of the
  31 syntax changes between LilyPond versions.
  32
  33 It uses @code{\version} statements in the input files to detect the old
  34 version number.  In most cases, to upgrade your input file it is sufficient
  35 to run
  36
  37 @example
  38 covert-ly -e myfile.ly
  39 @end example
  40
  41 If there are no changes to myfile.ly and file called myfile.ly.NEW
  42 is created, then myfile.ly is already updated.
  43
  44 To upgrade LilyPond fragments in texinfo files, use
  45
  46 @example
  47 convert-ly --from=... --to=... --no-version *.itely
  48 @end example
  49
  50 In general, the program is invoked as follows:
  51
  52 @example
  53 convert-ly [@var{option}]@dots{} @var{file}@dots{}
  54 @end example
  55
  56
  57 The following options can be given:
  58
  59 @table @code
  60 @item -e,--edit
  61 Do an inline edit of the input file.  Overrides @code{--output}.
  62
  63 @item -f,--from=@var{from-patchlevel}
  64 Set the version to convert from.  If this is not set, @command{convert-ly}
  65 will guess this, on the basis of @code{\version} strings in the file.
  66
  67 @item -o,--output=@var{file}
  68 Set the output file to write.
  69
  70 @item -n,--no-version
  71 Normally, @command{convert-ly} adds a @code{\version} indicator
  72 to the output.  Specifying this option suppresses this.
  73
  74 @item -s, --show-rules
  75 Show all known conversions and exit.
  76
  77 @item --to=@var{to-patchlevel}
  78 Set the goal version of the conversion.  It defaults to the latest
  79 available version.
  80
  81 @item -h, --help
  82 Print usage help.
  83 @end table
  84
  85 @command{convert-ly} always converts up to the last syntax change handled by
  86 it.  This means that the @code{\version} number left in the file is
  87 usually lower than the version of @command{convert-ly} itself.
  88
  89 @refbugs
  90
  91 Not all language changes are handled.  Only one output option can be
  92 specified.
  93
  94
  95 @c  We might want to make this a completely new section, along with more
  96 @c  info about how to upgrade old input files.  -gp
  97
  98 @ignore
  99 Copy and paste from CVS, last updated
 100 Feb 14, 2005
 101
 102 http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/lilypond/lily-bugs/bugs/convert-ly.txt?rev=HEAD&content-type=text/plain
 103 @end ignore
 104 @verbatim
 105
 106 There are a few things that the convert-ly cannot handle.  Here's a list of limitations
 107 that the community has complained about.
 108
 109 This bug report structure has been chosen because convert-ly has a structure that doesn't
 110 allow to smoothly implement all needed changes.  Thus this is just a wishlist, placed
 111 here for reference.
 112
 113 1.6->2.0:
 114  Doesn't always convert figured bass correctly, specifically things like {< >}. Mats' comment on working around this:
 115    To be able to run convert-ly
 116    on it, I first replaced all occurencies of '{<' to some dummy like '{#'
 117    and similarly I replaced '>}' with '&}'. After the conversion, I could
 118    then change back from '{ #' to '{ <' and from '& }' to '> }'.
 119  Doesn't convert all text markup correctly. Only very simple cases are fixed.
 120 2.0->2.2:
 121  Doesn't handle \partcombine
 122  Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple stanzas.
 123 2.2->2.4:
 124  \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly converted.
 125 2.4.2->2.5.9
 126  \markup{ \center-align <{ ... }> } should be converted to:
 127  \markup{ \center-align {\line { ... }} }
 128  but now, \line is missing.
 129 @end verbatim
 130
 131
 132 @node Invoking midi2ly
 133 @section Invoking @command{midi2ly}
 134
 135 @cindex MIDI
 136
 137 @command{midi2ly} translates a Type@tie{}1 MIDI file to a LilyPond source
 138 file.
 139
 140 MIDI (Music Instrument Digital Interface) is a standard for digital
 141 instruments: it specifies cabling, a serial protocol and a file
 142 format.  The MIDI file format is a de facto standard format for
 143 exporting music from other programs, so this capability may come in
 144 useful when importing files from a program that has a convertor for a
 145 direct format.
 146
 147 @command{midi2ly} converts tracks into @internalsref{Staff} and
 148 channels into @internalsref{Voice} contexts.  Relative mode is used
 149 for pitches, durations are only written when necessary.
 150
 151 It is possible to record a MIDI file using a digital keyboard, and
 152 then convert it to @file{.ly}.  However, human players are not
 153 rhythmically exact enough to make a MIDI to LY conversion trivial.
 154 When invoked with quantizing (@code{-s} and @code{-d} options)
 155 @command{midi2ly} tries to compensate for these timing errors, but is not
 156 very good at this.  It is therefore not recommended to use @command{midi2ly}
 157 for human-generated midi files.
 158
 159
 160 It is invoked from the command-line as follows,
 161 @example
 162 midi2ly [@var{option}]@dots{} @var{midi-file}
 163 @end example
 164
 165
 166 The following options are supported by @command{midi2ly}.
 167
 168 @table @code
 169 @item -a, --absolute-pitches
 170 Print absolute pitches.
 171
 172 @item -d, --duration-quant=@var{DUR}
 173 Quantize note durations on @var{DUR}.
 174
 175 @item -e, --explicit-durations
 176 Print explicit durations.
 177
 178 @item -h,--help
 179 Show summary of usage.
 180
 181 @item -k, --key=@var{acc}[:@var{minor}]
 182 Set default key.  @math{@var{acc} > 0} sets number of sharps;
 183 @math{@var{acc} < 0} sets number of flats.  A minor key is indicated by
 184 ":1".
 185
 186 @item -o, --output=@var{file}
 187 Write output to @var{file}.
 188
 189 @item -s, --start-quant=@var{DUR}
 190 Quantize note starts on DUR.
 191
 192 @item -t, --allow-tuplet=@var{DUR}*@var{NUM}/@var{DEN}
 193 Allow tuplet durations @var{DUR}*@var{NUM}/@var{DEN}.
 194
 195 @item -V, --verbose
 196 Be verbose.
 197
 198 @item -v, --version
 199 Print version number.
 200
 201 @item -w, --warranty
 202 Show warranty and copyright.
 203
 204 @item -x, --text-lyrics
 205 Treat every text as a lyric.
 206 @end table
 207
 208
 209 @refbugs
 210
 211 Overlapping notes in an arpeggio will not be correctly rendered.  The
 212 first note will be read and the others will be ignored.  Set them all
 213 to a single duration and add phrase markings or pedal indicators.
 214
 215
 216 @node Invoking etf2ly
 217 @section Invoking @command{etf2ly}
 218
 219 @cindex ETF
 220 @cindex enigma
 221 @cindex Finale
 222 @cindex Coda Technology
 223
 224 ETF (Enigma Transport Format) is a format used by Coda Music
 225 Technology's Finale product.  @command{etf2ly} will convert part of an ETF
 226 file to a ready-to-use LilyPond file.
 227
 228 It is invoked from the command-line as follows.
 229
 230 @example
 231 etf2ly [@var{option}]@dots{} @var{etf-file}
 232 @end example
 233
 234 The following options are supported by @command{etf2ly}:
 235
 236 @table @code
 237 @item -h,--help
 238 this help
 239 @item -o,--output=FILE
 240 set output filename to FILE
 241 @item -v,--version
 242 version information
 243 @end table
 244
 245
 246 @refbugs
 247
 248 The list of articulation scripts is incomplete.  Empty measures
 249 confuse @command{etf2ly}.  Sequences of grace notes are ended improperly.
 250
 251
 252 @node Invoking abc2ly
 253 @section Invoking @code{abc2ly}
 254
 255 @cindex ABC
 256
 257 ABC is a fairly simple ASCII based format.  It is described at the ABC site:
 258
 259 @quotation
 260 @uref{http://@/www@/.gre@/.ac@/.uk/@/~c.walshaw/@/abc2mtex/@/abc@/.txt}.
 261 @end quotation
 262
 263 @command{abc2ly} translates from ABC to LilyPond.  It is invoked as follows:
 264
 265 @example
 266 abc2ly [@var{option}]@dots{} @var{abc-file}
 267 @end example
 268
 269 The following options are supported by @command{abc2ly}:
 270
 271 @table @code
 272 @item -h,--help
 273 this help
 274 @item -o,--output=@var{file}
 275 set output filename to @var{file}.
 276 @item -v,--version
 277 print version information.
 278 @end table
 279
 280 There is a rudimentary facility for adding LilyPond code to the ABC
 281 source file.  If you say:
 282
 283 @example
 284 %%LY voices \set autoBeaming = ##f
 285 @end example
 286
 287 This will cause the text following the keyword ``voices'' to be inserted
 288 into the current voice of the LilyPond output file.
 289
 290 Similarly,
 291
 292 @example
 293 %%LY slyrics more words
 294 @end example
 295
 296 will cause the text following the ``slyrics'' keyword to be inserted
 297 into the current line of lyrics.
 298
 299
 300 @refbugs
 301
 302 The ABC standard is not very ``standard''.  For extended features
 303 (e.g., polyphonic music) different conventions exist.
 304
 305 Multiple tunes in one file cannot be converted.
 306
 307 ABC synchronizes words and notes at the beginning of a line;
 308 @command{abc2ly} does not.
 309
 310 @command{abc2ly} ignores the ABC beaming.
 311
 312
 313 @node Invoking mup2ly
 314 @section Invoking @command{mup2ly}
 315
 316 Mup (Music Publisher) is a shareware music notation program by Arkkra
 317 Enterprises.  @command{mup2ly} will convert part of a Mup file to LilyPond
 318 format.  It is invoked from the command-line as follows:
 319
 320 @cindex Music Publisher
 321 @cindex Mup
 322 @cindex Arkkra
 323
 324 @example
 325 mup2ly [@var{option}]@dots{} @var{mup-file}
 326 @end example
 327
 328 The following options are supported by @command{mup2ly}:
 329
 330 @table @code
 331 @item -d,--debug
 332 show what constructs are not converted, but skipped.
 333 @item -D, --define=@var{name}[=@code{exp}]
 334 define macro @var{name} with opt expansion @code{exp}
 335 @item -E,--pre-process
 336 only run the pre-processor
 337 @item -h,--help
 338 print help
 339 @item -o,--output=@var{file}
 340 write output to @var{file}
 341 @item -v,--version
 342 version information
 343 @item -w,--warranty
 344 print warranty and copyright.
 345 @end table
 346
 347
 348 @refbugs
 349
 350 Only plain notes (pitches, durations), voices, and staves are
 351 converted.
 352
 353
 354 @node Other formats
 355 @section Other formats
 356
 357 LilyPond itself does not come with support for other formats, but
 358 there are some external tools that also generate LilyPond files.
 359
 360 These tools include
 361
 362 @itemize @bullet
 363 @item
 364 @uref{http://@/denemo@/.sourceforge@/.net/,Denemo}.
 365 @item
 366 @uref{http://@/www@/.nongnu@/.org/@/xml2ly/, xml2ly}, that imports
 367 @uref{http://@/www@/.musicxml@/.com/,MusicXML}
 368 @item
 369 @uref{http://@/rnvs@/.informatik@/.tu@/-chemnitz@/.de/@/~jan/@/noteedit/@/noteedit@/.html,NoteEdit}
 370 which imports MusicXML
 371 @item
 372 @uref{http://@/www@/.all@/-day@/-breakfast@/.com/@/rosegarden/,Rosegarden},
 373 which imports MIDI
 374 @end itemize