Documentation/user/converters.itely

   1 \version "2.1.22"
   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 pmx2ly::             Importing PMX.
  21 * Invoking musedata2ly::        Importing Musedata.
  22 * Invoking mup2ly::             Importing MUP.
  23 @end menu
  24
  25
  26 @node Invoking convert-ly
  27 @section Invoking convert-ly
  28
  29 Convert-ly sequentially applies different conversions to upgrade a
  30 LilyPond input file.  It uses @code{\version} statements in the file to
  31 detect the old version number.  For example, to upgrade all LilyPond
  32 files in the current directory and its subdirectories, use
  33 @example
  34         convert-ly -e --to=1.3.150 `find . -name '*.ly' -print`
  35 @end example
  36
  37 The program is invoked as follows:
  38 @example
  39         convert-ly [@var{option}]@dots{} @var{file}@dots{}
  40 @end example
  41
  42
  43 The following options can be given:
  44
  45 @table @code
  46 @item -e,--edit
  47     Do an inline edit of the input file. Overrides @code{--output}.
  48 @item -f,--from=@var{from-patchlevel}
  49     Set the level to convert from. If this is not set, convert-ly will
  50     guess this, on the basis of @code{\version} strings in the file.
  51 @item -o,--output=@var{file}
  52     Set the output file to write.
  53 @item -n,--no-version
  54     Normally, convert-ly adds a @code{\version} indicator
  55     to the output. Specifying this option suppresses this.
  56 @item -s, --show-rules
  57     Show all known conversions and exit.
  58 @item --to=@var{to-patchlevel}
  59     Set the goal version of the conversion. It defaults to the latest
  60     available version.
  61 @item -h, --help
  62     Print usage help.
  63 @end table
  64
  65
  66
  67 @refbugs
  68
  69 Not all language changes are handled. Only one output option can be specified.
  70
  71 @node Invoking midi2ly
  72 @section Invoking midi2ly
  73
  74 @cindex MIDI
  75
  76 Midi2ly translates a MIDI input file to a LilyPond source file. MIDI
  77 (Music Instrument Digital Interface) is a standard for digital
  78 instruments: it specifies cabling, a serial protocol and a file format.
  79
  80 The MIDI file format is a de facto standard format for exporting music
  81 from other programs, so this capability may come in useful when you want
  82 to import files from a program that has no converter for its native
  83 format.
  84
  85 @file{midi2ly} will convert tracks into @internalsref{Staff} and
  86 channels into @internalsref{Voice} contexts.  Relative mode is used
  87 for pitches, durations are only written when necessary.
  88
  89 It is possible to record a MIDI file using a digital keyboard, and then
  90 convert it to @file{.ly}. However, human players are not rhythmically
  91 exact enough to make a MIDI to LY conversion trivial.  midi2ly tries to
  92 compensate for these timing errors, but is not very good at this. It is
  93 therefore not recommended to use midi2ly for human-generated midi files.
  94
  95 Hackers who know about signal processing are invited to write a more
  96 robust midi2ly.  midi2ly is written in Python, using a module written in
  97 C to parse the MIDI files.
  98
  99 It is invoked as follows:
 100 @example
 101         midi2ly [@var{option}]@dots{} @var{midi-file}
 102 @end example
 103
 104 The following options are supported by midi2ly:
 105
 106 @table @code
 107 @item -a, --absolute-pitches
 108     Print absolute pitches.
 109 @item -d, --duration-quant=@var{DUR}
 110     Quantise note durations on @var{DUR}.
 111 @item -e, --explicit-durations
 112     Print explicit durations.
 113 @item -h,--help
 114     Show summary of usage.
 115 @item -k, --key=@var{acc}[:@var{minor}]
 116     Set default key.  @var{acc} > 0 sets number of sharps; @var{acc} < 0
 117     sets number of flats.  A minor key is indicated by ":1".
 118 @item -o, --output=@var{file}
 119     Write output to @var{file}.
 120 @item -s, --start-quant=@var{DUR}
 121     Quantise note starts on DUR.
 122 @item -t, --allow-tuplet=@var{DUR}*@var{NUM}/@var{DEN}
 123     Allow tuplet durations @var{DUR}*@var{NUM}/@var{DEN}.
 124 @item -V, --verbose
 125     Be verbose.
 126 @item -v, --version
 127     Print version number.
 128 @item -w, --warranty
 129     Show warranty and copyright.
 130 @item -x, --text-lyrics
 131     Treat every text as a lyric.
 132 @end table
 133
 134
 135 @node Invoking etf2ly
 136 @section Invoking etf2ly
 137
 138 @cindex ETF
 139 @cindex enigma
 140 @cindex Finale
 141 @cindex Coda Technology
 142
 143 ETF (Enigma Transport Format) is a format used by Coda Music
 144 Technology's Finale product. etf2ly will convert part of an ETF
 145 file to a ready-to-use LilyPond file.
 146
 147 It is invoked as follows:
 148 @example
 149         etf2ly [@var{option}]@dots{} @var{etf-file}
 150 @end example
 151
 152 The following options are supported by etf2ly:
 153 @table @code
 154 @item   -h,--help
 155 this help
 156 @item  -o,--output=FILE
 157 set output filename to FILE
 158 @item  -v,--version
 159 version information
 160 @end table
 161
 162
 163 @refbugs
 164
 165 The list of articulation scripts is incomplete.  Empty measures confuse
 166 etf2ly. Sequences of grace notes are ended improperly sometimes.
 167
 168
 169 @node Invoking abc2ly
 170 @section Invoking abc2ly
 171
 172 @cindex ABC
 173
 174 ABC is a fairly simple ASCII based format. It is described at the abc site:
 175 @quotation
 176 @uref{http://www.gre.ac.uk/~c.walshaw/abc2mtex/abc.txt}.
 177 @end quotation
 178 abc2ly translates from ABC to LilyPond. It is invoked as follows:
 179
 180 @example
 181         abc2ly [@var{option}]@dots{} @var{abc-file}
 182 @end example
 183
 184 The following options are supported by abc2ly:
 185
 186 @table @code
 187 @item   -h,--help
 188 this help
 189 @item  -o,--output=@var{file}
 190 set output filename to @var{file}.
 191 @item  -v,--version
 192 print version information.
 193 @end table
 194
 195 There is a rudimentary facility for adding LilyPond code to the ABC
 196 source file.  If you say:
 197
 198 @example
 199         %%LY voices \set autoBeaming = ##f
 200 @end example
 201
 202 This will cause the text following the keyword ``voices'' to be inserted
 203 into the current voice of the LilyPond output file.
 204
 205 Similarly,
 206
 207 @example
 208         %%LY slyrics more words
 209 @end example
 210
 211 will cause the text following the ``slyrics'' keyword to be inserted
 212 into the current line of lyrics.
 213
 214
 215 @refbugs
 216
 217 The ABC standard is not very ``standard''. For extended features
 218 (eg. polyphonic music) different conventions exist.
 219
 220 Multiple tunes in one file cannot be converted.
 221
 222 ABC synchronizes words and notes at the beginning of a line; abc2ly does
 223 not.
 224
 225 abc2ly ignores the ABC beaming.
 226
 227 @node Invoking pmx2ly
 228 @section Invoking pmx2ly
 229
 230 PMX is a MusiXTeX preprocessor written by Don Simons. More information
 231 on PMX is available from the following site:
 232
 233 @quotation
 234 @uref{http://icking-music-archive.org/Misc/Music/musixtex/software/pmx/}.
 235 @end quotation
 236
 237 @cindex PMX
 238 @cindex MusiXTeX
 239 @cindex Simons, Don
 240 pmx2ly converts from PMX to LilyPond input. The program is invoked as
 241 follows:
 242
 243 @example
 244         pmx2ly [@var{option}]@dots{} @var{pmx-file}
 245 @end example
 246
 247 The following options are supported by pmx2ly:
 248
 249 @table @code
 250 @item   -h,--help
 251 this help
 252 @item  -o,--output=FILE
 253 set output filename to FILE
 254 @item  -v,--version
 255 version information
 256 @end table
 257
 258 @refbugs
 259
 260 This script was updated last in September 2000, and then successfully
 261 converted the @file{barsant.pmx} example from the PMX
 262 distribution. pmx2ly cannot parse more recent PMX files.
 263
 264
 265 @node Invoking musedata2ly
 266 @section Invoking musedata2ly
 267
 268 @cindex Musedata
 269 @cindex CCARH
 270
 271 Musedata (see @uref{http://www.musedata.org/}) is an electronic library of
 272 classical music scores, currently comprising about 800 composition
 273 dating from 1700 to 1825.  The music is encoded in so-called Musedata
 274 format.  musedata2ly converts a set of musedata files to one .ly file,
 275 and will include a @code{\header} field if a @file{.ref} file is
 276 supplied. It is invoked as follows:
 277
 278 @example
 279         musedata2ly [@var{option}]@dots{} @var{musedata-files}
 280 @end example
 281
 282 The following options are supported by musedata2ly:
 283
 284 @table @code
 285 @item   -h,--help
 286 print help
 287 @item  -o,--output=@var{file}
 288 set output filename to @var{file}
 289 @item  -v,--version
 290 version information
 291 @item  -r,--ref=@var{reffile}
 292  read background information from ref-file
 293 @var{reffile}
 294 @end table
 295
 296 @refbugs
 297
 298 @file{musedata2ly} converts only a small subset of musedata.
 299
 300 @node Invoking mup2ly
 301 @section Invoking mup2ly
 302
 303 MUP (Music Publisher) is a shareware music notation program by Arkkra
 304 Enterprises.  Mup2ly will convert part of a Mup file to LilyPond
 305 format. It is invoked as follows:
 306
 307 @cindex Music Publisher
 308 @cindex MUP
 309 @cindex Arkkra
 310
 311 @example
 312         mup2ly [@var{option}]@dots{} @var{mup-file}
 313 @end example
 314
 315 The following options are supported by mup2ly:
 316
 317 @table @code
 318 @item   -d,--debug
 319 show what constructs are not converted, but skipped.
 320 @item -D, --define=@var{name}[=@code{exp}]
 321 define macro @var{name} with opt expansion @code{exp}
 322 @item   -E,--pre-process
 323 only run the pre-processor
 324 @item   -h,--help
 325 print help
 326 @item  -o,--output=@var{file}
 327 write output to @var{file}
 328 @item  -v,--version
 329 version information
 330 @item  -w,--warranty
 331 print warranty and copyright.
 332 @end table
 333
 334
 335 @refbugs
 336
 337 Only plain notes (pitches, durations), voices, and staves are
 338 converted.
 339
 340
 341