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