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