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