Documentation/user/converters.itely

   1 @c -*- coding: utf-8; mode: 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 These are separate programs from lilypond itself, and are run
  13 on the command-line.  By ``command-line'', we mean the command
  14 line in the operating system.  Windows users
  15 might be more familiar with the terms ``DOS shell'' or
  16 ``command shell''; OSX users might be more familiar with the
  17 terms ``terminal'' or ``console''.  Describing how to use
  18 this part of an operating system is outside the scope of this
  19 manual; please consult other documentation on this topic if
  20 you are unfamiliar with the command-line.
  21
  22
  23
  24 @menu
  25 * Invoking midi2ly::            Importing MIDI.
  26 * Invoking etf2ly::             Importing Finale.
  27 * Invoking musicxml2ly::
  28 * Invoking abc2ly::             Importing ABC.
  29 * Invoking mup2ly::             Importing MUP.
  30 * Generating LilyPond files::
  31 @end menu
  32
  33
  34
  35 @node Invoking midi2ly
  36 @section Invoking @command{midi2ly}
  37
  38 @cindex MIDI
  39
  40 @command{midi2ly} translates a Type@tie{}1 MIDI file to a LilyPond source
  41 file.
  42
  43 MIDI (Music Instrument Digital Interface) is a standard for digital
  44 instruments: it specifies cabling, a serial protocol and a file
  45 format.  The MIDI file format is a de facto standard format for
  46 exporting music from other programs, so this capability may come in
  47 useful when importing files from a program that has a convertor for a
  48 direct format.
  49
  50 @command{midi2ly} converts tracks into @internalsref{Staff} and
  51 channels into @internalsref{Voice} contexts.  Relative mode is used
  52 for pitches, durations are only written when necessary.
  53
  54 It is possible to record a MIDI file using a digital keyboard, and
  55 then convert it to @file{.ly}.  However, human players are not
  56 rhythmically exact enough to make a MIDI to LY conversion trivial.
  57 When invoked with quantizing (@code{-s} and @code{-d} options)
  58 @command{midi2ly} tries to compensate for these timing errors, but is not
  59 very good at this.  It is therefore not recommended to use @command{midi2ly}
  60 for human-generated midi files.
  61
  62
  63 It is invoked from the command-line as follows,
  64 @example
  65 midi2ly [@var{option}]@dots{} @var{midi-file}
  66 @end example
  67
  68 Note that by ``command-line'', we mean the command line of the
  69 operating system.  See @ref{Converting from other formats} for
  70 more information about this.
  71
  72 The following options are supported by @command{midi2ly}.
  73
  74 @table @code
  75 @item -a, --absolute-pitches
  76 Print absolute pitches.
  77
  78 @item -d, --duration-quant=@var{DUR}
  79 Quantize note durations on @var{DUR}.
  80
  81 @item -e, --explicit-durations
  82 Print explicit durations.
  83
  84 @item -h,--help
  85 Show summary of usage.
  86
  87 @item -k, --key=@var{acc}[:@var{minor}]
  88 Set default key.  @math{@var{acc} > 0} sets number of sharps;
  89 @math{@var{acc} < 0} sets number of flats.  A minor key is indicated by
  90 ":1".
  91
  92 @item -o, --output=@var{file}
  93 Write output to @var{file}.
  94
  95 @item -s, --start-quant=@var{DUR}
  96 Quantize note starts on DUR.
  97
  98 @item -t, --allow-tuplet=@var{DUR}*@var{NUM}/@var{DEN}
  99 Allow tuplet durations @var{DUR}*@var{NUM}/@var{DEN}.
 100
 101 @item -V, --verbose
 102 Be verbose.
 103
 104 @item -v, --version
 105 Print version number.
 106
 107 @item -w, --warranty
 108 Show warranty and copyright.
 109
 110 @item -x, --text-lyrics
 111 Treat every text as a lyric.
 112 @end table
 113
 114
 115 @refbugs
 116
 117 Overlapping notes in an arpeggio will not be correctly rendered.  The
 118 first note will be read and the others will be ignored.  Set them all
 119 to a single duration and add phrase markings or pedal indicators.
 120
 121
 122 @node Invoking etf2ly
 123 @section Invoking @command{etf2ly}
 124
 125 @cindex ETF
 126 @cindex enigma
 127 @cindex Finale
 128 @cindex Coda Technology
 129
 130 ETF (Enigma Transport Format) is a format used by Coda Music
 131 Technology's Finale product.  @command{etf2ly} will convert part of an ETF
 132 file to a ready-to-use LilyPond file.
 133
 134 It is invoked from the command-line as follows.
 135
 136 @example
 137 etf2ly [@var{option}]@dots{} @var{etf-file}
 138 @end example
 139
 140 Note that by ``command-line'', we mean the command line of the
 141 operating system.  See @ref{Converting from other formats} for
 142 more information about this.
 143
 144 The following options are supported by @command{etf2ly}:
 145
 146 @table @code
 147 @item -h,--help
 148 this help
 149 @item -o,--output=FILE
 150 set output filename to FILE
 151 @item -v,--version
 152 version information
 153 @end table
 154
 155
 156 @refbugs
 157
 158 The list of articulation scripts is incomplete.  Empty measures
 159 confuse @command{etf2ly}.  Sequences of grace notes are ended improperly.
 160
 161 @node Invoking musicxml2ly
 162 @section Invoking @code{musicxml2ly}
 163
 164 @uref{http://@/www.@/recordarde@/.com/xml@/.html,MusicXML} is an XML dialect
 165 for representing music notation.
 166
 167 @command{musicxml2ly} extracts the notes from part-wise MusicXML
 168 files, and writes it to a .ly file.  It is invoked from the command-line.
 169
 170 Note that by ``command-line'', we mean the command line of the
 171 operating system.  See @ref{Converting from other formats} for
 172 more information about this.
 173
 174 The following options are supported by @command{musicxml2ly}:
 175
 176 @table @code
 177 @item -h,--help
 178 print usage and option summary.
 179 @item -o,--output=@var{file}
 180 set output filename to @var{file}. (default: print to stdout)
 181 @item -v,--version
 182 print version information.
 183 @end table
 184
 185 @node Invoking abc2ly
 186 @section Invoking @code{abc2ly}
 187
 188 @cindex ABC
 189
 190 ABC is a fairly simple ASCII based format.  It is described at the ABC site:
 191
 192 @quotation
 193 @uref{http://@/www@/.gre@/.ac@/.uk/@/~c.walshaw/@/abc2mtex/@/abc@/.txt}.
 194 @end quotation
 195
 196 @command{abc2ly} translates from ABC to LilyPond.  It is invoked as follows:
 197
 198 @example
 199 abc2ly [@var{option}]@dots{} @var{abc-file}
 200 @end example
 201
 202 The following options are supported by @command{abc2ly}:
 203
 204 @table @code
 205 @item -h,--help
 206 this help
 207 @item -o,--output=@var{file}
 208 set output filename to @var{file}.
 209 @item -v,--version
 210 print version information.
 211 @end table
 212
 213 There is a rudimentary facility for adding LilyPond code to the ABC
 214 source file.  If you say:
 215
 216 @example
 217 %%LY voices \set autoBeaming = ##f
 218 @end example
 219
 220 This will cause the text following the keyword ``voices'' to be inserted
 221 into the current voice of the LilyPond output file.
 222
 223 Similarly,
 224
 225 @example
 226 %%LY slyrics more words
 227 @end example
 228
 229 will cause the text following the ``slyrics'' keyword to be inserted
 230 into the current line of lyrics.
 231
 232
 233 @refbugs
 234
 235 The ABC standard is not very ``standard''.  For extended features
 236 (e.g., polyphonic music) different conventions exist.
 237
 238 Multiple tunes in one file cannot be converted.
 239
 240 ABC synchronizes words and notes at the beginning of a line;
 241 @command{abc2ly} does not.
 242
 243 @command{abc2ly} ignores the ABC beaming.
 244
 245
 246 @node Invoking mup2ly
 247 @section Invoking @command{mup2ly}
 248
 249 Mup (Music Publisher) is a shareware music notation program by Arkkra
 250 Enterprises.  @command{mup2ly} will convert part of a Mup file to LilyPond
 251 format.  It is invoked from the command-line as follows:
 252
 253 @cindex Music Publisher
 254 @cindex Mup
 255 @cindex Arkkra
 256
 257 @example
 258 mup2ly [@var{option}]@dots{} @var{mup-file}
 259 @end example
 260
 261 The following options are supported by @command{mup2ly}:
 262
 263 @table @code
 264 @item -d,--debug
 265 show what constructs are not converted, but skipped.
 266 @item -D, --define=@var{name}[=@code{exp}]
 267 define macro @var{name} with opt expansion @code{exp}
 268 @item -E,--pre-process
 269 only run the pre-processor
 270 @item -h,--help
 271 print help
 272 @item -o,--output=@var{file}
 273 write output to @var{file}
 274 @item -v,--version
 275 version information
 276 @item -w,--warranty
 277 print warranty and copyright.
 278 @end table
 279
 280
 281 @refbugs
 282
 283 Only plain notes (pitches, durations), voices, and staves are
 284 converted.
 285
 286
 287 @node Generating LilyPond files
 288 @section Generating LilyPond files
 289
 290 @cindex External programs, generating LilyPond files
 291
 292 LilyPond itself does not come with support for any other formats, but
 293 there are some external tools that also generate LilyPond files.
 294
 295 These tools include
 296
 297 @itemize @bullet
 298 @item
 299 @uref{http://@/denemo@/.sourceforge@/.net/,Denemo}, a graphical score editor.
 300 @item
 301 @uref{http://www@/.volny@/.cz/smilauer/rumor/rumor@/.html,Rumor}, a realtime
 302 monophonic MIDI to LilyPond converter.
 303 @item
 304 @uref{http://nicolas@/.sceaux@/.free@/.fr/lilypond/lyqi@/.html,lyqi}, an
 305 Emacs major mode.
 306 @item
 307 @uref{http://@/www@/.nongnu@/.org/@/xml2ly/, xml2ly}, which imports
 308 @uref{http://@/www@/.musicxml@/.com/xml@/.html,MusicXML}
 309 @item
 310 @uref{http://@/noteedit@/.berlios@/.de,NoteEdit}
 311 which imports @uref{http://@/www@/.musicxml@/.com/xml@/.html,MusicXML}
 312 @item
 313 @uref{http://@/www@/.rosegardenmusic@/.com,Rosegarden},
 314 which imports MIDI
 315 @end itemize
 316