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