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