Documentation/user/converters.itely

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