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