Documentation/user/converters.itely

   1 @c -*- coding: utf-8; mode: texinfo; -*-
   2 @c This file is part of lilypond-program.tely
   3 @ignore
   4     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
   5
   6     When revising a translation, copy the HEAD committish of the
   7     version that you are working on.  See TRANSLATION for details.
   8 @end ignore
   9
  10 @node Converting from other formats
  11 @chapter Converting from other formats
  12
  13 Music can be entered also by importing it from other formats.  This
  14 chapter documents the tools included in the distribution to do so.
  15 There are other tools that produce LilyPond input, for example GUI
  16 sequencers and XML converters.  Refer to the
  17 @uref{http://@/lilypond@/.org,website} for more details.
  18
  19 These are separate programs from lilypond itself, and are run
  20 on the command-line; see @ref{Command-line usage} for more information.
  21
  22
  23 @knownissues
  24 We unfortunately do not have the resources to maintain these
  25 programs; please consider them @qq{as-is}.  Patches are appreciated, but
  26 bug reports will almost certainly not be resolved.
  27
  28 @menu
  29 * Invoking midi2ly::            Importing MIDI.
  30 * Invoking musicxml2ly::        Importing MusicXML.
  31 * Invoking abc2ly::             Importing ABC.
  32 * Invoking etf2ly::             Importing Finale.
  33 * Generating LilyPond files::   GUIs, transcribers, and algorithmic composition programs.
  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 @q{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 @code{: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 @knownissues
 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 musicxml2ly
 126 @section Invoking @code{musicxml2ly}
 127
 128 @uref{http://@/www.@/recordarde@/.com/xml@/.html,MusicXML} is an XML dialect
 129 for representing music notation.
 130
 131 @command{musicxml2ly} extracts the notes from part-wise MusicXML
 132 files, and writes it to a .ly file.  It is invoked from the command-line.
 133
 134 Note that by @q{command-line}, we mean the command line of the
 135 operating system.  See @ref{Converting from other formats}, for
 136 more information about this.
 137
 138 The following options are supported by @command{musicxml2ly}:
 139
 140 @table @code
 141 @item -h,--help
 142 print usage and option summary.
 143 @item -o,--output=@var{file}
 144 set output filename to @var{file}. (default: print to stdout)
 145 @item -v,--version
 146 print version information.
 147 @end table
 148
 149
 150 @node Invoking abc2ly
 151 @section Invoking @code{abc2ly}
 152
 153 @cindex ABC
 154
 155 ABC is a fairly simple ASCII based format.  It is described at the ABC site:
 156
 157 @quotation
 158 @uref{http://@/www@/.walshaw@/.plus@/.com/@/abc/@/abc2mtex/@/abc@/.txt}.
 159 @end quotation
 160
 161 @command{abc2ly} translates from ABC to LilyPond.  It is invoked as follows:
 162
 163 @example
 164 abc2ly [@var{option}]@dots{} @var{abc-file}
 165 @end example
 166
 167 The following options are supported by @command{abc2ly}:
 168
 169 @table @code
 170 @item -h,--help
 171 this help
 172 @item -o,--output=@var{file}
 173 set output filename to @var{file}.
 174 @item -v,--version
 175 print version information.
 176 @end table
 177
 178 There is a rudimentary facility for adding LilyPond code to the ABC
 179 source file.  If you say:
 180
 181 @example
 182 %%LY voices \set autoBeaming = ##f
 183 @end example
 184
 185 This will cause the text following the keyword @q{voices} to be inserted
 186 into the current voice of the LilyPond output file.
 187
 188 Similarly,
 189
 190 @example
 191 %%LY slyrics more words
 192 @end example
 193
 194 will cause the text following the @q{slyrics} keyword to be inserted
 195 into the current line of lyrics.
 196
 197
 198 @knownissues
 199
 200 The ABC standard is not very @q{standard}.  For extended features
 201 (e.g., polyphonic music) different conventions exist.
 202
 203 Multiple tunes in one file cannot be converted.
 204
 205 ABC synchronizes words and notes at the beginning of a line;
 206 @command{abc2ly} does not.
 207
 208 @command{abc2ly} ignores the ABC beaming.
 209
 210
 211 @node Invoking etf2ly
 212 @section Invoking @command{etf2ly}
 213
 214 @cindex ETF
 215 @cindex enigma
 216 @cindex Finale
 217 @cindex Coda Technology
 218
 219 ETF (Enigma Transport Format) is a format used by Coda Music
 220 Technology's Finale product.  @command{etf2ly} will convert part of an ETF
 221 file to a ready-to-use LilyPond file.
 222
 223 It is invoked from the command-line as follows.
 224
 225 @example
 226 etf2ly [@var{option}]@dots{} @var{etf-file}
 227 @end example
 228
 229 Note that by @q{command-line}, we mean the command line of the
 230 operating system.  See @ref{Converting from other formats}, for
 231 more information about this.
 232
 233 The following options are supported by @command{etf2ly}:
 234
 235 @table @code
 236 @item -h,--help
 237 this help
 238 @item -o,--output=FILE
 239 set output filename to FILE
 240 @item -v,--version
 241 version information
 242 @end table
 243
 244
 245 @knownissues
 246
 247 The list of articulation scripts is incomplete.  Empty measures
 248 confuse @command{etf2ly}.  Sequences of grace notes are ended improperly.
 249
 250
 251 @node Generating LilyPond files
 252 @section Generating LilyPond files
 253
 254 @cindex External programs, generating LilyPond files
 255
 256 LilyPond itself does not come with support for any other formats, but
 257 there are some external tools that also generate LilyPond files.
 258
 259 These tools include
 260
 261 @itemize
 262 @item
 263 @uref{http://@/denemo@/.sourceforge@/.net/,Denemo}, a graphical score editor.
 264 @item
 265 @uref{http://www@/.volny@/.cz/smilauer/rumor/rumor@/.html,Rumor}, a realtime
 266 monophonic MIDI to LilyPond converter.
 267 @item
 268 @uref{http://nicolas@/.sceaux@/.free@/.fr/lilypond/lyqi@/.html,lyqi}, an
 269 Emacs major mode.
 270 @item
 271 @uref{http://@/www@/.nongnu@/.org/@/xml2ly/, xml2ly}, which imports
 272 @uref{http://@/www@/.musicxml@/.com/xml@/.html,MusicXML}
 273 @item
 274 @uref{http://@/noteedit@/.berlios@/.de,NoteEdit}
 275 which imports @uref{http://@/www@/.musicxml@/.com/xml@/.html,MusicXML}
 276 @item
 277 @uref{http://@/www@/.rosegardenmusic@/.com,Rosegarden},
 278 which imports MIDI
 279 @item
 280 @uref{http://@/common-lisp@/.net/project/fomus/,FOMUS},
 281 a LISP library to generate music notation
 282 @end itemize
 283