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 Dec 22, 2004
 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 @end verbatim
 126
 127
 128 @node Invoking midi2ly
 129 @section Invoking @command{midi2ly}
 130
 131 @cindex MIDI
 132
 133 @command{midi2ly} translates a Type@tie{}1 MIDI file to a LilyPond source
 134 file.
 135
 136 MIDI (Music Instrument Digital Interface) is a standard for digital
 137 instruments: it specifies cabling, a serial protocol and a file
 138 format.  The MIDI file format is a de facto standard format for
 139 exporting music from other programs, so this capability may come in
 140 useful when importing files from a program that has a convertor for a
 141 direct format.
 142
 143 @command{midi2ly} converts tracks into @internalsref{Staff} and
 144 channels into @internalsref{Voice} contexts.  Relative mode is used
 145 for pitches, durations are only written when necessary.
 146
 147 It is possible to record a MIDI file using a digital keyboard, and
 148 then convert it to @file{.ly}.  However, human players are not
 149 rhythmically exact enough to make a MIDI to LY conversion trivial.
 150 When invoked with quantizing (@code{-s} and @code{-d} options)
 151 @command{midi2ly} tries to compensate for these timing errors, but is not
 152 very good at this.  It is therefore not recommended to use @command{midi2ly}
 153 for human-generated midi files.
 154
 155
 156 It is invoked from the command-line as follows,
 157 @example
 158 midi2ly [@var{option}]@dots{} @var{midi-file}
 159 @end example
 160
 161
 162 The following options are supported by @command{midi2ly}.
 163
 164 @table @code
 165 @item -a, --absolute-pitches
 166 Print absolute pitches.
 167
 168 @item -d, --duration-quant=@var{DUR}
 169 Quantize note durations on @var{DUR}.
 170
 171 @item -e, --explicit-durations
 172 Print explicit durations.
 173
 174 @item -h,--help
 175 Show summary of usage.
 176
 177 @item -k, --key=@var{acc}[:@var{minor}]
 178 Set default key.  @math{@var{acc} > 0} sets number of sharps;
 179 @math{@var{acc} < 0} sets number of flats.  A minor key is indicated by
 180 ":1".
 181
 182 @item -o, --output=@var{file}
 183 Write output to @var{file}.
 184
 185 @item -s, --start-quant=@var{DUR}
 186 Quantize note starts on DUR.
 187
 188 @item -t, --allow-tuplet=@var{DUR}*@var{NUM}/@var{DEN}
 189 Allow tuplet durations @var{DUR}*@var{NUM}/@var{DEN}.
 190
 191 @item -V, --verbose
 192 Be verbose.
 193
 194 @item -v, --version
 195 Print version number.
 196
 197 @item -w, --warranty
 198 Show warranty and copyright.
 199
 200 @item -x, --text-lyrics
 201 Treat every text as a lyric.
 202 @end table
 203
 204
 205 @refbugs
 206
 207 Overlapping notes in an arpeggio will not be correctly rendered.  The
 208 first note will be read and the others will be ignored.  Set them all
 209 to a single duration and add phrase markings or pedal indicators.
 210
 211
 212 @node Invoking etf2ly
 213 @section Invoking @command{etf2ly}
 214
 215 @cindex ETF
 216 @cindex enigma
 217 @cindex Finale
 218 @cindex Coda Technology
 219
 220 ETF (Enigma Transport Format) is a format used by Coda Music
 221 Technology's Finale product.  @command{etf2ly} will convert part of an ETF
 222 file to a ready-to-use LilyPond file.
 223
 224 It is invoked from the command-line as follows.
 225
 226 @example
 227 etf2ly [@var{option}]@dots{} @var{etf-file}
 228 @end example
 229
 230 The following options are supported by @command{etf2ly}:
 231
 232 @table @code
 233 @item -h,--help
 234 this help
 235 @item -o,--output=FILE
 236 set output filename to FILE
 237 @item -v,--version
 238 version information
 239 @end table
 240
 241
 242 @refbugs
 243
 244 The list of articulation scripts is incomplete.  Empty measures
 245 confuse @command{etf2ly}.  Sequences of grace notes are ended improperly.
 246
 247
 248 @node Invoking abc2ly
 249 @section Invoking @code{abc2ly}
 250
 251 @cindex ABC
 252
 253 ABC is a fairly simple ASCII based format.  It is described at the ABC site:
 254
 255 @quotation
 256 @uref{http://@/www@/.gre@/.ac@/.uk/@/~c.walshaw/@/abc2mtex/@/abc@/.txt}.
 257 @end quotation
 258
 259 @command{abc2ly} translates from ABC to LilyPond.  It is invoked as follows:
 260
 261 @example
 262 abc2ly [@var{option}]@dots{} @var{abc-file}
 263 @end example
 264
 265 The following options are supported by @command{abc2ly}:
 266
 267 @table @code
 268 @item -h,--help
 269 this help
 270 @item -o,--output=@var{file}
 271 set output filename to @var{file}.
 272 @item -v,--version
 273 print version information.
 274 @end table
 275
 276 There is a rudimentary facility for adding LilyPond code to the ABC
 277 source file.  If you say:
 278
 279 @example
 280 %%LY voices \set autoBeaming = ##f
 281 @end example
 282
 283 This will cause the text following the keyword ``voices'' to be inserted
 284 into the current voice of the LilyPond output file.
 285
 286 Similarly,
 287
 288 @example
 289 %%LY slyrics more words
 290 @end example
 291
 292 will cause the text following the ``slyrics'' keyword to be inserted
 293 into the current line of lyrics.
 294
 295
 296 @refbugs
 297
 298 The ABC standard is not very ``standard''.  For extended features
 299 (e.g., polyphonic music) different conventions exist.
 300
 301 Multiple tunes in one file cannot be converted.
 302
 303 ABC synchronizes words and notes at the beginning of a line;
 304 @command{abc2ly} does not.
 305
 306 @command{abc2ly} ignores the ABC beaming.
 307
 308
 309 @node Invoking mup2ly
 310 @section Invoking @command{mup2ly}
 311
 312 Mup (Music Publisher) is a shareware music notation program by Arkkra
 313 Enterprises.  @command{mup2ly} will convert part of a Mup file to LilyPond
 314 format.  It is invoked from the command-line as follows:
 315
 316 @cindex Music Publisher
 317 @cindex Mup
 318 @cindex Arkkra
 319
 320 @example
 321 mup2ly [@var{option}]@dots{} @var{mup-file}
 322 @end example
 323
 324 The following options are supported by @command{mup2ly}:
 325
 326 @table @code
 327 @item -d,--debug
 328 show what constructs are not converted, but skipped.
 329 @item -D, --define=@var{name}[=@code{exp}]
 330 define macro @var{name} with opt expansion @code{exp}
 331 @item -E,--pre-process
 332 only run the pre-processor
 333 @item -h,--help
 334 print help
 335 @item -o,--output=@var{file}
 336 write output to @var{file}
 337 @item -v,--version
 338 version information
 339 @item -w,--warranty
 340 print warranty and copyright.
 341 @end table
 342
 343
 344 @refbugs
 345
 346 Only plain notes (pitches, durations), voices, and staves are
 347 converted.
 348
 349
 350 @node Other formats
 351 @section Other formats
 352
 353 LilyPond itself does not come with support for other formats, but
 354 there are some external tools that also generate LilyPond files.
 355
 356 These tools include
 357
 358 @itemize @bullet
 359 @item
 360 @uref{http://@/denemo@/.sourceforge@/.net/,Denemo}.
 361 @item
 362 @uref{http://@/www@/.nongnu@/.org/@/xml2ly/, xml2ly}, that imports
 363 @uref{http://@/www@/.musicxml@/.com/,MusicXML}
 364 @item
 365 @uref{http://@/rnvs@/.informatik@/.tu@/-chemnitz@/.de/@/~jan/@/noteedit/@/noteedit@/.html,NoteEdit}
 366 which imports MusicXML
 367 @item
 368 @uref{http://@/www@/.all@/-day@/-breakfast@/.com/@/rosegarden/,Rosegarden},
 369 which imports MIDI
 370 @end itemize