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