Documentation/user/converters.itely

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