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 Type 1 MIDI file to a LilyPond source file.
  75
  76 MIDI (Music Instrument Digital Interface) is a standard for digital
  77 instruments: it specifies cabling, a serial protocol and a file
  78 format.  The MIDI file format is a de facto standard format for
  79 exporting music from other programs, so this capability may come in
  80 useful when you want to import files from a program that has no
  81 converter for its native format.
  82
  83 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
  88 then convert it to @file{.ly}. However, human players are not
  89 rhythmically exact enough to make a MIDI to LY conversion trivial.
  90 midi2ly tries to compensate for these timing errors, but is not very
  91 good at this. It is therefore not recommended to use midi2ly for
  92 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     Quantize 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     Quantize 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 @refbugs
 135
 136
 137 Quantizing start-times and durations should be recommended.
 138 This relates to the notes regarding the transcription of a MIDI
 139 recording of a performance. I realize it can be done via the utility,
 140 but a sequencer gives better visual feedback.
 141
 142 Overlapping notes in an arpeggio will not be correctly
 143 rendered. The first note will be read and the others will be ignored.
 144 Set them all to a single duration and add phrase markings or pedal
 145 indicators.
 146
 147
 148 @node Invoking etf2ly
 149 @section Invoking etf2ly
 150
 151 @cindex ETF
 152 @cindex enigma
 153 @cindex Finale
 154 @cindex Coda Technology
 155
 156 ETF (Enigma Transport Format) is a format used by Coda Music
 157 Technology's Finale product. etf2ly will convert part of an ETF
 158 file to a ready-to-use LilyPond file.
 159
 160 It is invoked as follows:
 161 @example
 162         etf2ly [@var{option}]@dots{} @var{etf-file}
 163 @end example
 164
 165 The following options are supported by etf2ly:
 166 @table @code
 167 @item   -h,--help
 168 this help
 169 @item  -o,--output=FILE
 170 set output filename to FILE
 171 @item  -v,--version
 172 version information
 173 @end table
 174
 175
 176 @refbugs
 177
 178 The list of articulation scripts is incomplete.  Empty measures confuse
 179 etf2ly. Sequences of grace notes are ended improperly sometimes.
 180
 181
 182 @node Invoking abc2ly
 183 @section Invoking abc2ly
 184
 185 @cindex ABC
 186
 187 ABC is a fairly simple ASCII based format. It is described at the ABC site:
 188 @quotation
 189 @uref{http://www.gre.ac.uk/~c.walshaw/abc2mtex/abc.txt}.
 190 @end quotation
 191 abc2ly translates from ABC to LilyPond. It is invoked as follows:
 192
 193 @example
 194         abc2ly [@var{option}]@dots{} @var{abc-file}
 195 @end example
 196
 197 The following options are supported by abc2ly:
 198
 199 @table @code
 200 @item   -h,--help
 201 this help
 202 @item  -o,--output=@var{file}
 203 set output filename to @var{file}.
 204 @item  -v,--version
 205 print version information.
 206 @end table
 207
 208 There is a rudimentary facility for adding LilyPond code to the ABC
 209 source file.  If you say:
 210
 211 @example
 212         %%LY voices \set autoBeaming = ##f
 213 @end example
 214
 215 This will cause the text following the keyword ``voices'' to be inserted
 216 into the current voice of the LilyPond output file.
 217
 218 Similarly,
 219
 220 @example
 221         %%LY slyrics more words
 222 @end example
 223
 224 will cause the text following the ``slyrics'' keyword to be inserted
 225 into the current line of lyrics.
 226
 227
 228 @refbugs
 229
 230 The ABC standard is not very ``standard''. For extended features
 231 (e.g. polyphonic music) different conventions exist.
 232
 233 Multiple tunes in one file cannot be converted.
 234
 235 ABC synchronizes words and notes at the beginning of a line; abc2ly does
 236 not.
 237
 238 abc2ly ignores the ABC beaming.
 239
 240 @node Invoking musedata2ly
 241 @section Invoking musedata2ly
 242
 243 @cindex MuseData
 244 @cindex CCARH
 245
 246 @uref{http://www.musedata.org/,MuseData} is an electronic library of
 247 classical music scores, comprising at the time of writing about 800
 248 composition dating from 1700 to 1825.  The music is encoded in
 249 so-called MuseData format.  musedata2ly converts a set of MuseData
 250 files to one .ly file, and will include a @code{\header} field if a
 251 @file{.ref} file is supplied. It is invoked as follows:
 252
 253 @example
 254         musedata2ly [@var{option}]@dots{} @var{musedata-files}
 255 @end example
 256
 257 The following options are supported by musedata2ly:
 258
 259 @table @code
 260 @item   -h,--help
 261 print help
 262 @item  -o,--output=@var{file}
 263 set output filename to @var{file}
 264 @item  -v,--version
 265 version information
 266 @item  -r,--ref=@var{reffile}
 267  read background information from ref-file
 268 @var{reffile}
 269 @end table
 270
 271 @refbugs
 272
 273 @file{musedata2ly} converts only a small subset of MuseData.
 274
 275 @node Invoking mup2ly
 276 @section Invoking mup2ly
 277
 278 Mup (Music Publisher) is a shareware music notation program by Arkkra
 279 Enterprises.  Mup2ly will convert part of a Mup file to LilyPond
 280 format. It is invoked as follows:
 281
 282 @cindex Music Publisher
 283 @cindex Mup
 284 @cindex Arkkra
 285
 286 @example
 287         mup2ly [@var{option}]@dots{} @var{mup-file}
 288 @end example
 289
 290 The following options are supported by mup2ly:
 291
 292 @table @code
 293 @item   -d,--debug
 294 show what constructs are not converted, but skipped.
 295 @item -D, --define=@var{name}[=@code{exp}]
 296 define macro @var{name} with opt expansion @code{exp}
 297 @item   -E,--pre-process
 298 only run the pre-processor
 299 @item   -h,--help
 300 print help
 301 @item  -o,--output=@var{file}
 302 write output to @var{file}
 303 @item  -v,--version
 304 version information
 305 @item  -w,--warranty
 306 print warranty and copyright.
 307 @end table
 308
 309
 310 @refbugs
 311
 312 Only plain notes (pitches, durations), voices, and staves are
 313 converted.
 314
 315
 316