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