Documentation/user/converters.itely

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