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