Documentation/usage/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 @rweb{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 * Other formats::
  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 @warning{This program is not supported, and may be remove from
 202 future versions of LilyPond.}
 203
 204 @cindex ABC
 205
 206 ABC is a fairly simple ASCII based format.  It is described at the ABC site:
 207
 208 @quotation
 209 @uref{http://@/www@/.walshaw@/.plus@/.com/@/abc/@/learn@/.html}.
 210 @end quotation
 211
 212 @command{abc2ly} translates from ABC to LilyPond.  It is invoked as follows:
 213
 214 @example
 215 abc2ly [@var{option}]@dots{} @var{abc-file}
 216 @end example
 217
 218 The following options are supported by @command{abc2ly}:
 219
 220 @table @code
 221 @item -b,--beams=None
 222 preserve ABC's notion of beams
 223 @item -h,--help
 224 this help
 225 @item -o,--output=@var{file}
 226 set output filename to @var{file}.
 227 @item -s,--strict
 228 be strict about success
 229 @item --version
 230 print version information.
 231 @end table
 232
 233 There is a rudimentary facility for adding LilyPond code to the ABC
 234 source file.  If you say:
 235
 236 @example
 237 %%LY voices \set autoBeaming = ##f
 238 @end example
 239
 240 This will cause the text following the keyword @q{voices} to be inserted
 241 into the current voice of the LilyPond output file.
 242
 243 Similarly,
 244
 245 @example
 246 %%LY slyrics more words
 247 @end example
 248
 249 will cause the text following the @q{slyrics} keyword to be inserted
 250 into the current line of lyrics.
 251
 252
 253 @knownissues
 254
 255 The ABC standard is not very @q{standard}.  For extended features
 256 (e.g., polyphonic music) different conventions exist.
 257
 258 Multiple tunes in one file cannot be converted.
 259
 260 ABC synchronizes words and notes at the beginning of a line;
 261 @command{abc2ly} does not.
 262
 263 @command{abc2ly} ignores the ABC beaming.
 264
 265
 266 @node Invoking etf2ly
 267 @section Invoking @command{etf2ly}
 268
 269 @warning{This program is not supported, and may be remove from
 270 future versions of LilyPond.}
 271
 272 @cindex ETF
 273 @cindex enigma
 274 @cindex Finale
 275 @cindex Coda Technology
 276
 277 ETF (Enigma Transport Format) is a format used by Coda Music
 278 Technology's Finale product.  @command{etf2ly} will convert part of an ETF
 279 file to a ready-to-use LilyPond file.
 280
 281 It is invoked from the command-line as follows.
 282
 283 @example
 284 etf2ly [@var{option}]@dots{} @var{etf-file}
 285 @end example
 286
 287 Note that by @q{command-line}, we mean the command line of the
 288 operating system.  See @ref{Converting from other formats}, for
 289 more information about this.
 290
 291 The following options are supported by @command{etf2ly}:
 292
 293 @table @code
 294 @item -h,--help
 295 this help
 296 @item -o,--output=@var{FILE}
 297 set output filename to @var{FILE}
 298 @item --version
 299 version information
 300 @end table
 301
 302
 303 @knownissues
 304
 305 The list of articulation scripts is incomplete.  Empty measures
 306 confuse @command{etf2ly}.  Sequences of grace notes are ended improperly.
 307
 308
 309 @node Other formats
 310 @section Other formats
 311
 312 @cindex External programs, generating LilyPond files
 313
 314 LilyPond itself does not come with support for any other formats,
 315 but some external tools can also generate LilyPond files.  These
 316 are listed in @rweb{Alternate editors}.
 317