Documentation/user/converters.itely

   1 @c -*-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 convert-ly::         Older LilyPond versions.
  16 * Invoking midi2ly::            Importing MIDI.
  17 * Invoking etf2ly::             Importing Finale.
  18 * Invoking abc2ly::             Importing ABC.
  19 * Invoking mup2ly::             Importing MUP.
  20 @end menu
  21
  22
  23 @node Invoking convert-ly
  24 @section Invoking convert-ly
  25
  26 The syntax is regularly changed to simplify it or improve it in
  27 different ways. A side effect of this, is that LilyPond often is not
  28 compatible with older files. To remedy this, the program convert-ly
  29 can be used to deal with most of the syntax changes.
  30
  31 It uses @code{\version} statements in the file to detect the old
  32 version number.  For example, to upgrade all LilyPond files in the
  33 current directory and its subdirectories, enter the following on the
  34 command line.
  35
  36 @example
  37         convert-ly -e --to=1.3.150 `find . -name '*.ly' -print`
  38 @end example
  39
  40 The program is invoked as follows:
  41 @example
  42         convert-ly [@var{option}]@dots{} @var{file}@dots{}
  43 @end example
  44
  45
  46 The following options can be given:
  47
  48 @table @code
  49 @item -e,--edit
  50     Do an inline edit of the input file. Overrides @code{--output}.
  51 @item -f,--from=@var{from-patchlevel}
  52     Set the level to convert from. If this is not set, convert-ly will
  53     guess this, on the basis of @code{\version} strings in the file.
  54 @item -o,--output=@var{file}
  55     Set the output file to write.
  56 @item -n,--no-version
  57     Normally, convert-ly adds a @code{\version} indicator
  58     to the output. Specifying this option suppresses this.
  59 @item -s, --show-rules
  60     Show all known conversions and exit.
  61 @item --to=@var{to-patchlevel}
  62     Set the goal version of the conversion. It defaults to the latest
  63     available version.
  64 @item -h, --help
  65     Print usage help.
  66 @end table
  67
  68
  69
  70 @refbugs
  71
  72 Not all language changes are handled. Only one output option can be specified.
  73
  74 @node Invoking midi2ly
  75 @section Invoking midi2ly
  76
  77 @cindex MIDI
  78
  79 Midi2ly translates a Type 1 MIDI file to a LilyPond source file.
  80
  81 MIDI (Music Instrument Digital Interface) is a standard for digital
  82 instruments: it specifies cabling, a serial protocol and a file
  83 format.  The MIDI file format is a de facto standard format for
  84 exporting music from other programs, so this capability may come in
  85 useful when importing files from a program that has convertor for a
  86 direct format.
  87
  88 Midi2ly will convert tracks into @internalsref{Staff} and
  89 channels into @internalsref{Voice} contexts.  Relative mode is used
  90 for pitches, durations are only written when necessary.
  91
  92 It is possible to record a MIDI file using a digital keyboard, and
  93 then convert it to @file{.ly}. However, human players are not
  94 rhythmically exact enough to make a MIDI to LY conversion trivial.
  95 When invoked with quantizing (@code{-s} and @code{-d} options) midi2ly
  96 tries to compensate for these timing errors, but is not very good at
  97 this. It is therefore not recommended to use midi2ly for
  98 human-generated midi files.
  99
 100
 101 It is invoked as follows:
 102 @example
 103         midi2ly [@var{option}]@dots{} @var{midi-file}
 104 @end example
 105
 106 The following options are supported by midi2ly:
 107
 108 @table @code
 109 @item -a, --absolute-pitches
 110     Print absolute pitches.
 111 @item -d, --duration-quant=@var{DUR}
 112     Quantize note durations on @var{DUR}.
 113 @item -e, --explicit-durations
 114     Print explicit durations.
 115 @item -h,--help
 116     Show summary of usage.
 117 @item -k, --key=@var{acc}[:@var{minor}]
 118     Set default key.  @var{acc} > 0 sets number of sharps; @var{acc} < 0
 119     sets number of flats.  A minor key is indicated by ":1".
 120 @item -o, --output=@var{file}
 121     Write output to @var{file}.
 122 @item -s, --start-quant=@var{DUR}
 123     Quantize note starts on DUR.
 124 @item -t, --allow-tuplet=@var{DUR}*@var{NUM}/@var{DEN}
 125     Allow tuplet durations @var{DUR}*@var{NUM}/@var{DEN}.
 126 @item -V, --verbose
 127     Be verbose.
 128 @item -v, --version
 129     Print version number.
 130 @item -w, --warranty
 131     Show warranty and copyright.
 132 @item -x, --text-lyrics
 133     Treat every text as a lyric.
 134 @end table
 135
 136
 137 @refbugs
 138
 139 Overlapping notes in an arpeggio will not be correctly rendered. The
 140 first note will be read and the others will be ignored.  Set them all
 141 to a single duration and add phrase markings or pedal indicators.
 142
 143
 144 @node Invoking etf2ly
 145 @section Invoking etf2ly
 146
 147 @cindex ETF
 148 @cindex enigma
 149 @cindex Finale
 150 @cindex Coda Technology
 151
 152 ETF (Enigma Transport Format) is a format used by Coda Music
 153 Technology's Finale product. etf2ly will convert part of an ETF
 154 file to a ready-to-use LilyPond file.
 155
 156 It is invoked as follows:
 157 @example
 158         etf2ly [@var{option}]@dots{} @var{etf-file}
 159 @end example
 160
 161 The following options are supported by etf2ly:
 162 @table @code
 163 @item   -h,--help
 164 this help
 165 @item  -o,--output=FILE
 166 set output filename to FILE
 167 @item  -v,--version
 168 version information
 169 @end table
 170
 171
 172 @refbugs
 173
 174 The list of articulation scripts is incomplete.  Empty measures
 175 confuse etf2ly. Sequences of grace notes are ended improperly.
 176
 177
 178 @node Invoking abc2ly
 179 @section Invoking abc2ly
 180
 181 @cindex ABC
 182
 183 ABC is a fairly simple ASCII based format. It is described at the ABC site:
 184 @quotation
 185 @uref{http://www.gre.ac.uk/~c.walshaw/abc2mtex/abc.txt}.
 186 @end quotation
 187 abc2ly translates from ABC to LilyPond. It is invoked as follows:
 188
 189 @example
 190         abc2ly [@var{option}]@dots{} @var{abc-file}
 191 @end example
 192
 193 The following options are supported by abc2ly:
 194
 195 @table @code
 196 @item   -h,--help
 197 this help
 198 @item  -o,--output=@var{file}
 199 set output filename to @var{file}.
 200 @item  -v,--version
 201 print version information.
 202 @end table
 203
 204 There is a rudimentary facility for adding LilyPond code to the ABC
 205 source file.  If you say:
 206
 207 @example
 208         %%LY voices \set autoBeaming = ##f
 209 @end example
 210
 211 This will cause the text following the keyword ``voices'' to be inserted
 212 into the current voice of the LilyPond output file.
 213
 214 Similarly,
 215
 216 @example
 217         %%LY slyrics more words
 218 @end example
 219
 220 will cause the text following the ``slyrics'' keyword to be inserted
 221 into the current line of lyrics.
 222
 223
 224 @refbugs
 225
 226 The ABC standard is not very ``standard''. For extended features
 227 (e.g. polyphonic music) different conventions exist.
 228
 229 Multiple tunes in one file cannot be converted.
 230
 231 ABC synchronizes words and notes at the beginning of a line; abc2ly does
 232 not.
 233
 234 abc2ly ignores the ABC beaming.
 235
 236
 237 @node Invoking mup2ly
 238 @section Invoking mup2ly
 239
 240 Mup (Music Publisher) is a shareware music notation program by Arkkra
 241 Enterprises.  Mup2ly will convert part of a Mup file to LilyPond
 242 format. It is invoked as follows:
 243
 244 @cindex Music Publisher
 245 @cindex Mup
 246 @cindex Arkkra
 247
 248 @example
 249         mup2ly [@var{option}]@dots{} @var{mup-file}
 250 @end example
 251
 252 The following options are supported by mup2ly:
 253
 254 @table @code
 255 @item   -d,--debug
 256 show what constructs are not converted, but skipped.
 257 @item -D, --define=@var{name}[=@code{exp}]
 258 define macro @var{name} with opt expansion @code{exp}
 259 @item   -E,--pre-process
 260 only run the pre-processor
 261 @item   -h,--help
 262 print help
 263 @item  -o,--output=@var{file}
 264 write output to @var{file}
 265 @item  -v,--version
 266 version information
 267 @item  -w,--warranty
 268 print warranty and copyright.
 269 @end table
 270
 271
 272 @refbugs
 273
 274 Only plain notes (pitches, durations), voices, and staves are
 275 converted.
 276
 277
 278