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