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