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{website,http://lilypond.org} 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.
  86
  87 It is possible to record a MIDI file using a digital keyboard, and then
  88 convert it to @file{.ly}. However, human players are not rhythmically
  89 exact enough to make a MIDI to LY conversion trivial.  midi2ly tries to
  90 compensate for these timing errors, but is not very good at this. It is
  91 therefore not recommended to use midi2ly for human-generated midi files.
  92
  93 Hackers who know about signal processing are invited to write a more
  94 robust midi2ly.  midi2ly is written in Python, using a module written in
  95 C to parse the MIDI files.
  96
  97 It is invoked as follows:
  98 @example
  99         midi2ly [@var{option}]@dots{} @var{midi-file}
 100 @end example
 101
 102 The following options are supported by midi2ly:
 103
 104 @table @code
 105 @item -b, --no-quantify,
 106     Write exact durations, e.g.: `a4*385/384'.
 107 @item -D, --debug,
 108     Print lots of debugging stuff.
 109 @item -h, --help,
 110     Show a summary of usage.
 111 @item -I, --include=@var{dir},
 112     Add @var{dir} to search path.
 113 @item -k, --key=@var{acc}[:@var{minor}],
 114     Set default key.  @var{acc} > 0 sets number of sharps; @var{acc} < 0
 115 sets number
 116     of flats.  A minor key is indicated by ":1".
 117 @item -n, --no-silly,
 118     Assume no plets or double dots, assume smallest (reciprocal) duration 16.
 119 @item -o, --output=@var{file},
 120     Set @var{file} as default output.
 121 @item -p, --no-plets,
 122     Assume no plets.
 123 @item -q, --quiet,
 124     Be quiet.
 125 @item -s, --smallest=N,
 126     Assume no shorter (reciprocal) durations than N.
 127 @item -v, --verbose,
 128     Be verbose.
 129 @item -w, --warranty,
 130     Show the warranty with which midi2ly comes. (It comes with @strong{NO WARRANTY}!)
 131 @item -x, --no-double-dots,
 132     Assume no double dotted notes.
 133 @end table
 134
 135
 136 @node Invoking etf2ly
 137 @section Invoking etf2ly
 138
 139 @cindex ETF
 140 @cindex enigma
 141 @cindex Finale
 142 @cindex Coda Technology
 143
 144 ETF (Enigma Transport Format) is a format used by Coda Music
 145 Technology's Finale product. etf2ly will convert part of an ETF
 146 file to a ready-to-use LilyPond file.
 147
 148 It is invoked as follows:
 149 @example
 150         etf2ly [@var{option}]@dots{} @var{etf-file}
 151 @end example
 152
 153 The following options are supported by etf2ly.
 154 @table @code
 155 @item   -h,--help
 156 this help
 157 @item  -o,--output=FILE
 158 set output filename to FILE
 159 @item  -v,--version
 160 version information
 161 @end table
 162
 163
 164 @refbugs
 165
 166 The list of articulation scripts is incomplete.  Empty measures confuse
 167 etf2ly.
 168
 169
 170 @node Invoking abc2ly
 171 @section Invoking abc2ly
 172
 173 @cindex ABC
 174
 175 ABC is a fairly simple ASCII based format. It is described at the abc site:
 176 @quotation
 177 @uref{http://www.gre.ac.uk/~c.walshaw/abc2mtex/abc.txt}
 178 @end quotation
 179 abc2ly translates from ABC to LilyPond. It is invoked as follows:
 180
 181 @example
 182         abc2ly [@var{option}]@dots{} @var{abc-file}
 183 @end example
 184
 185 The following options are supported by abc2ly:
 186
 187 @table @code
 188 @item   -h,--help
 189 this help
 190 @item  -o,--output=@var{file}
 191 set output filename to @var{file}.
 192 @item  -v,--version
 193 print version information.
 194 @end table
 195
 196 There is a rudimentary facility for adding lilypond code to the ABC
 197 source file.  If you say:
 198
 199 @example
 200         %%LY voices \property Voice.autoBeaming=##f
 201 @end example
 202
 203 This will cause the text following the keyword ``voices'' to be inserted
 204 into the current voice of the lilypond output file.
 205
 206 Similarly:
 207
 208 @example
 209         %%LY slyrics more words
 210 @end example
 211
 212 will cause the text following the ``slyrics'' keyword to be inserted
 213 into the current line of lyrics.
 214
 215
 216 @refbugs
 217
 218 The ABC standard is not very ``standard''. For extended features
 219 (eg. polyphonic music) different conventions exist.
 220
 221 Multiple tunes in one file cannot be converted.
 222
 223 ABC synchronizes words and notes at the beginning of a line; abc2ly does
 224 not.
 225
 226 abc2ly ignores the ABC beaming.
 227
 228 @node Invoking pmx2ly
 229 @section Invoking pmx2ly
 230
 231 PMX is a MusiXTeX preprocessor written by Don Simons. More information
 232 on PMX is available from the following site:
 233
 234 @quotation
 235 @uref{http://icking-music-archive.sunsite.dk/Misc/Music/musixtex/software/pmx/}.
 236 @end quotation
 237
 238 @cindex PMX
 239 @cindex MusiXTeX
 240 @cindex Simons, Don
 241 pmx2ly converts from PMX to LilyPond input. The program is invoked as
 242 follows:
 243
 244 @example
 245         pmx2ly [@var{option}]@dots{} @var{pmx-file}
 246 @end example
 247
 248 The following options are supported by pmx2ly:
 249
 250 @table @code
 251 @item   -h,--help
 252 this help
 253 @item  -o,--output=FILE
 254 set output filename to FILE
 255 @item  -v,--version
 256 version information
 257 @end table
 258
 259 @refbugs
 260
 261 This script was updated last in September 2000, and then successfully
 262 converted the @file{barsant.pmx} example from the PMX
 263 distribution. pmx2ly cannot parse more recent PMX files.
 264
 265
 266 @node Invoking musedata2ly
 267 @section Invoking musedata2ly
 268
 269 @cindex Musedata
 270 @cindex CCARH
 271
 272 Musedata (@uref{http://www.musedata.org/}) is an electronic library of
 273 classical music scores, currently comprising about 800 composition
 274 dating from 1700 to 1825.  The music is encoded in so-called Musedata
 275 format.  musedata2ly converts a set of musedata files to one .ly file,
 276 and will include a @code{\header} field if a @file{.ref} file is
 277 supplied. It is invoked as follows:
 278
 279 @example
 280         musedata2ly [@var{option}]@dots{} @var{musedata-files}
 281 @end example
 282
 283 The following options are supported by musedata2ly:
 284
 285 @table @code
 286 @item   -h,--help
 287 print help
 288 @item  -o,--output=@var{file}
 289 set output filename to @var{file}
 290 @item  -v,--version
 291 version information
 292 @item  -r,--ref=@var{reffile}
 293  read background information from ref-file
 294 @var{reffile}
 295 @end table
 296
 297 @refbugs
 298
 299 musedata2ly converts only a small subset musedata.
 300
 301 @node Invoking mup2ly
 302 @section Invoking mup2ly
 303
 304 MUP (Music Publisher) is a shareware music notation program by Arkkra
 305 Enterprises.  Mup2ly will convert part of a Mup file to LilyPond
 306 format. It is invoked as follows:
 307
 308 @cindex Music Publisher
 309 @cindex MUP
 310 @cindex Arkkra
 311
 312 @example
 313         mup2ly [@var{option}]@dots{} @var{mup-file}
 314 @end example
 315
 316 The following options are supported by mup2ly:
 317
 318 @table @code
 319 @item   -d,--debug
 320 show what constructs are not converted, but skipped.
 321 @item -D, --define=@var{name}[=@code{exp}]
 322 define macro @var{name} with opt expansion @code{exp}
 323 @item   -E,--pre-process
 324 only run the pre-processor
 325 @item   -h,--help
 326 print help
 327 @item  -o,--output=@var{file}
 328 write output to @var{file}
 329 @item  -v,--version
 330 version information
 331 @item  -w,--warranty
 332 print warranty and copyright.
 333 @end table
 334
 335
 336 @refbugs
 337
 338 Currently, only plain notes (pitches, durations), voices and staves are
 339 converted.
 340
 341
 342