Documentation/user/converters.itely

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