Documentation/application/converters.itely

   1 @c -*- coding: utf-8; mode: texinfo; -*-
   2
   3 @ignore
   4     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
   5
   6     When revising a translation, copy the HEAD committish of the
   7     version that you are working on.  See TRANSLATION for details.
   8 @end ignore
   9
  10 @c \version "2.12.0"
  11
  12 @node Converting from other formats
  13 @chapter Converting from other formats
  14
  15 Music can be entered also by importing it from other formats.  This
  16 chapter documents the tools included in the distribution to do so.
  17 There are other tools that produce LilyPond input, for example GUI
  18 sequencers and XML converters.  Refer to the
  19 @uref{http://@/lilypond@/.org,website} for more details.
  20
  21 These are separate programs from @command{lilypond} itself, and are
  22 run on the command line; see @ref{Command-line usage} for more
  23 information.  If you have MacOS 10.3 or 10.4 and you have trouble
  24 running some of these scripts, e.g. @code{convert-ly}, see
  25 FIXME FIXME
  26 @c @ref{Setup for MacOS X}.
  27
  28
  29 @knownissues
  30 We unfortunately do not have the resources to maintain these
  31 programs; please consider them @qq{as-is}.  Patches are appreciated, but
  32 bug reports will almost certainly not be resolved.
  33
  34 @menu
  35 * Invoking midi2ly::            Importing MIDI.
  36 * Invoking musicxml2ly::        Importing MusicXML.
  37 * Invoking abc2ly::             Importing ABC.
  38 * Invoking etf2ly::             Importing Finale.
  39 * Generating LilyPond files::   GUIs, transcribers, and algorithmic composition programs.
  40 @end menu
  41
  42
  43
  44 @node Invoking midi2ly
  45 @section Invoking @command{midi2ly}
  46
  47 @cindex MIDI
  48
  49 @command{midi2ly} translates a Type@tie{}1 MIDI file to a LilyPond source
  50 file.
  51
  52 MIDI (Music Instrument Digital Interface) is a standard for digital
  53 instruments: it specifies cabling, a serial protocol and a file
  54 format.  The MIDI file format is a de facto standard format for
  55 exporting music from other programs, so this capability may come in
  56 useful when importing files from a program that has a converter for a
  57 direct format.
  58
  59 @command{midi2ly} converts tracks into @rinternals{Staff} and
  60 channels into @rinternals{Voice} contexts.  Relative mode is used
  61 for pitches, durations are only written when necessary.
  62
  63 It is possible to record a MIDI file using a digital keyboard, and
  64 then convert it to @file{.ly}.  However, human players are not
  65 rhythmically exact enough to make a MIDI to LY conversion trivial.
  66 When invoked with quantizing (@code{-s} and @code{-d} options)
  67 @command{midi2ly} tries to compensate for these timing errors, but is not
  68 very good at this.  It is therefore not recommended to use @command{midi2ly}
  69 for human-generated midi files.
  70
  71
  72 It is invoked from the command-line as follows,
  73 @example
  74 midi2ly [@var{option}]@dots{} @var{midi-file}
  75 @end example
  76
  77 Note that by @q{command-line}, we mean the command line of the
  78 operating system.  See @ref{Converting from other formats}, for
  79 more information about this.
  80
  81 The following options are supported by @command{midi2ly}.
  82
  83 @table @code
  84 @item -a, --absolute-pitches
  85 Print absolute pitches.
  86
  87 @item -d, --duration-quant=@var{DUR}
  88 Quantize note durations on @var{DUR}.
  89
  90 @item -e, --explicit-durations
  91 Print explicit durations.
  92
  93 @item -h,--help
  94 Show summary of usage.
  95
  96 @item -k, --key=@var{acc}[:@var{minor}]
  97 Set default key.  @math{@var{acc} > 0} sets number of sharps;
  98 @math{@var{acc} < 0} sets number of flats.  A minor key is indicated by
  99 @code{:1}.
 100
 101 @item -o, --output=@var{file}
 102 Write output to @var{file}.
 103
 104 @item -s, --start-quant=@var{DUR}
 105 Quantize note starts on @var{DUR}.
 106
 107 @item -t, --allow-tuplet=@var{DUR}*@var{NUM}/@var{DEN}
 108 Allow tuplet durations @var{DUR}*@var{NUM}/@var{DEN}.
 109
 110 @item -v, --verbose
 111 Be verbose.
 112
 113 @item -V, --version
 114 Print version number.
 115
 116 @item -w, --warranty
 117 Show warranty and copyright.
 118
 119 @item -x, --text-lyrics
 120 Treat every text as a lyric.
 121 @end table
 122
 123
 124 @knownissues
 125
 126 Overlapping notes in an arpeggio will not be correctly rendered.  The
 127 first note will be read and the others will be ignored.  Set them all
 128 to a single duration and add phrase markings or pedal indicators.
 129
 130
 131 @node Invoking musicxml2ly
 132 @section Invoking @code{musicxml2ly}
 133
 134 @cindex MusicXML
 135
 136 @uref{http://@/www.@/musicxml@/.org/,MusicXML} is an XML dialect
 137 for representing music notation.
 138
 139 @command{musicxml2ly} extracts the notes, articulations, score structure,
 140 lyrics, etc. from part-wise MusicXML files, and writes them to a .ly
 141 file.  It is invoked from the command-line.
 142
 143
 144 It is invoked from the command-line as follows,
 145 @example
 146 musicxml2ly [@var{option}]@dots{} @var{xml-file}
 147 @end example
 148
 149 Note that by @q{command-line}, we mean the command line of the
 150 operating system.  See @ref{Converting from other formats}, for
 151 more information about this.
 152
 153 If the given filename is @file{-}, @command{musicxml2ly} reads input
 154 from the command line.
 155
 156 The following options are supported by @command{musicxml2ly}:
 157
 158 @table @code
 159 @item -a, --absolute
 160 convert pitches in absolute mode.
 161
 162 @item -h,--help
 163 print usage and option summary.
 164
 165 @item -l, --language=LANG
 166 use a different language file 'LANG.ly' and corresponding pitch names,
 167 e.g. 'deutsch' for deutsch.ly and German note names.
 168
 169 @item --lxml
 170 use the lxml.etree Python package for XML-parsing; uses less memory and cpu time.
 171
 172 @item --nd --no-articulation-directions
 173 do not convert directions (@code{^}, @code{_} or @code{-}) for
 174 articulations, dynamics, etc.
 175
 176 @item --no-beaming
 177 do not convert beaming information, use LilyPond's automatic
 178 beaming instead.
 179
 180 @item -o,--output=@var{file}
 181 set output filename to @var{file}.  If @var{file} is @file{-}, the output
 182 will be printed on stdout.  If not given, @var{xml-file}@file{.ly} will
 183 be used.
 184
 185 @item -r,--relative
 186 convert pitches in relative mode (default).
 187
 188 @item -v,--verbose
 189 be verbose.
 190
 191 @item --version
 192 print version information.
 193
 194 @item -z,--compressed
 195 input file is a zip-compressed MusicXML file.
 196 @end table
 197
 198
 199 @node Invoking abc2ly
 200 @section Invoking @code{abc2ly}
 201
 202 @cindex ABC
 203
 204 ABC is a fairly simple ASCII based format.  It is described at the ABC site:
 205
 206 @quotation
 207 @uref{http://@/www@/.walshaw@/.plus@/.com/@/abc/@/learn@/.html}.
 208 @end quotation
 209
 210 @command{abc2ly} translates from ABC to LilyPond.  It is invoked as follows:
 211
 212 @example
 213 abc2ly [@var{option}]@dots{} @var{abc-file}
 214 @end example
 215
 216 The following options are supported by @command{abc2ly}:
 217
 218 @table @code
 219 @item -b,--beams=None
 220 preserve ABC's notion of beams
 221 @item -h,--help
 222 this help
 223 @item -o,--output=@var{file}
 224 set output filename to @var{file}.
 225 @item -s,--strict
 226 be strict about success
 227 @item --version
 228 print version information.
 229 @end table
 230
 231 There is a rudimentary facility for adding LilyPond code to the ABC
 232 source file.  If you say:
 233
 234 @example
 235 %%LY voices \set autoBeaming = ##f
 236 @end example
 237
 238 This will cause the text following the keyword @q{voices} to be inserted
 239 into the current voice of the LilyPond output file.
 240
 241 Similarly,
 242
 243 @example
 244 %%LY slyrics more words
 245 @end example
 246
 247 will cause the text following the @q{slyrics} keyword to be inserted
 248 into the current line of lyrics.
 249
 250
 251 @knownissues
 252
 253 The ABC standard is not very @q{standard}.  For extended features
 254 (e.g., polyphonic music) different conventions exist.
 255
 256 Multiple tunes in one file cannot be converted.
 257
 258 ABC synchronizes words and notes at the beginning of a line;
 259 @command{abc2ly} does not.
 260
 261 @command{abc2ly} ignores the ABC beaming.
 262
 263
 264 @node Invoking etf2ly
 265 @section Invoking @command{etf2ly}
 266
 267 @cindex ETF
 268 @cindex enigma
 269 @cindex Finale
 270 @cindex Coda Technology
 271
 272 ETF (Enigma Transport Format) is a format used by Coda Music
 273 Technology's Finale product.  @command{etf2ly} will convert part of an ETF
 274 file to a ready-to-use LilyPond file.
 275
 276 It is invoked from the command-line as follows.
 277
 278 @example
 279 etf2ly [@var{option}]@dots{} @var{etf-file}
 280 @end example
 281
 282 Note that by @q{command-line}, we mean the command line of the
 283 operating system.  See @ref{Converting from other formats}, for
 284 more information about this.
 285
 286 The following options are supported by @command{etf2ly}:
 287
 288 @table @code
 289 @item -h,--help
 290 this help
 291 @item -o,--output=@var{FILE}
 292 set output filename to @var{FILE}
 293 @item --version
 294 version information
 295 @end table
 296
 297
 298 @knownissues
 299
 300 The list of articulation scripts is incomplete.  Empty measures
 301 confuse @command{etf2ly}.  Sequences of grace notes are ended improperly.
 302
 303
 304 @node Generating LilyPond files
 305 @section Generating LilyPond files
 306
 307 @cindex External programs, generating LilyPond files
 308
 309 LilyPond itself does not come with support for any other formats, but
 310 there are some external tools that also generate LilyPond files.
 311
 312 These tools include
 313
 314 @itemize
 315 @item
 316 @uref{http://@/www@/.denemo@/.org/,Denemo}, a graphical score editor.
 317 @item
 318 @uref{http://www@/.volny@/.cz/smilauer/rumor/rumor@/.html,Rumor}, a realtime
 319 monophonic MIDI to LilyPond converter.
 320 @item
 321 @uref{http://nicolas@/.sceaux@/.free@/.fr/lilypond/lyqi@/.html,lyqi}, an
 322 Emacs major mode.
 323 @item
 324 @uref{http://@/www@/.nongnu@/.org/@/xml2ly/,xml2ly}, which imports
 325 @uref{http://@/www@/.musicxml@/.com/xml@/.html,MusicXML}
 326 @item
 327 @uref{http://@/noteedit@/.berlios@/.de,NoteEdit}
 328 which imports @uref{http://@/www@/.musicxml@/.com/xml@/.html,MusicXML}
 329 @item
 330 @uref{http://@/www@/.rosegardenmusic@/.com,Rosegarden},
 331 which imports MIDI
 332 @item
 333 @uref{http://@/common-lisp@/.net/project/fomus/,FOMUS},
 334 a LISP library to generate music notation
 335 @item
 336 @uref{http://vsr.informatik.tu-chemnitz.de/staff/jan/nted/nted.xhtml},
 337 has experimental export for LilyPond.
 338 @item
 339 @uref{http://www.tuxguitar.com.ar/}, can export to LilyPond.
 340 @item
 341 @uref{http://musescore.org} can also export to LilyPond.
 342 @end itemize
 343