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
 144 @node Invoking abc2ly
 145 @section Invoking @code{abc2ly}
 146
 147 @cindex ABC
 148
 149 ABC is a fairly simple ASCII based format.  It is described at the ABC site:
 150
 151 @quotation
 152 @uref{http://@/www@/.gre@/.ac@/.uk/@/~c.walshaw/@/abc2mtex/@/abc@/.txt}.
 153 @end quotation
 154
 155 @command{abc2ly} translates from ABC to LilyPond.  It is invoked as follows:
 156
 157 @example
 158 abc2ly [@var{option}]@dots{} @var{abc-file}
 159 @end example
 160
 161 The following options are supported by @command{abc2ly}:
 162
 163 @table @code
 164 @item -h,--help
 165 this help
 166 @item -o,--output=@var{file}
 167 set output filename to @var{file}.
 168 @item -v,--version
 169 print version information.
 170 @end table
 171
 172 There is a rudimentary facility for adding LilyPond code to the ABC
 173 source file.  If you say:
 174
 175 @example
 176 %%LY voices \set autoBeaming = ##f
 177 @end example
 178
 179 This will cause the text following the keyword ``voices'' to be inserted
 180 into the current voice of the LilyPond output file.
 181
 182 Similarly,
 183
 184 @example
 185 %%LY slyrics more words
 186 @end example
 187
 188 will cause the text following the ``slyrics'' keyword to be inserted
 189 into the current line of lyrics.
 190
 191
 192 @refbugs
 193
 194 The ABC standard is not very ``standard''.  For extended features
 195 (e.g., polyphonic music) different conventions exist.
 196
 197 Multiple tunes in one file cannot be converted.
 198
 199 ABC synchronizes words and notes at the beginning of a line;
 200 @command{abc2ly} does not.
 201
 202 @command{abc2ly} ignores the ABC beaming.
 203
 204
 205 @node Invoking mup2ly
 206 @section Invoking @command{mup2ly}
 207
 208 Mup (Music Publisher) is a shareware music notation program by Arkkra
 209 Enterprises.  @command{mup2ly} will convert part of a Mup file to LilyPond
 210 format.  It is invoked from the command-line as follows:
 211
 212 @cindex Music Publisher
 213 @cindex Mup
 214 @cindex Arkkra
 215
 216 @example
 217 mup2ly [@var{option}]@dots{} @var{mup-file}
 218 @end example
 219
 220 The following options are supported by @command{mup2ly}:
 221
 222 @table @code
 223 @item -d,--debug
 224 show what constructs are not converted, but skipped.
 225 @item -D, --define=@var{name}[=@code{exp}]
 226 define macro @var{name} with opt expansion @code{exp}
 227 @item -E,--pre-process
 228 only run the pre-processor
 229 @item -h,--help
 230 print help
 231 @item -o,--output=@var{file}
 232 write output to @var{file}
 233 @item -v,--version
 234 version information
 235 @item -w,--warranty
 236 print warranty and copyright.
 237 @end table
 238
 239
 240 @refbugs
 241
 242 Only plain notes (pitches, durations), voices, and staves are
 243 converted.
 244
 245
 246 @node Generating LilyPond files
 247 @section Generating LilyPond files
 248
 249 @cindex External programs, generating LilyPond files
 250
 251 LilyPond itself does not come with support for any other formats, but
 252 there are some external tools that also generate LilyPond files.
 253
 254 These tools include
 255
 256 @itemize @bullet
 257 @item
 258 @uref{http://@/denemo@/.sourceforge@/.net/,Denemo}, a graphical score editor.
 259 @item
 260 @uref{http://www@/.volny@/.cz/smilauer/rumor/rumor@/.html,Rumor}, a realtime monophonic MIDI to LilyPond converter.
 261 @item
 262 @uref{http://nicolas@/.sceaux@/.free@/.fr/lilypond/lyqi@/.html,lyqi}, an Emacs major mode.
 263 @item
 264 @uref{http://@/www@/.nongnu@/.org/@/xml2ly/, xml2ly}, which imports
 265 @uref{http://@/www@/.musicxml@/.com/xml@/.html,MusicXML}
 266 @item
 267 @uref{http://@/noteedit@/.berlios@/.de,NoteEdit}
 268 which imports @uref{http://@/www@/.musicxml@/.com/xml@/.html,MusicXML}
 269 @item
 270 @uref{http://@/www@/.rosegardenmusic@/.com,Rosegarden},
 271 which imports MIDI
 272 @end itemize
 273