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