1 @c -*- coding: latin-1; mode: texinfo; -*-
3 @node Converting from other formats
4 @chapter Converting from other formats
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.
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.
24 @node Invoking convert-ly
25 @section Invoking @command{convert-ly}
27 The LilyPond input syntax is routinely changed to simplify it or improve
28 it in different ways. As a side effect of this, the LilyPond interpreter
29 often is no longer compatible with older input files. To remedy this,
30 the program @command{convert-ly} can be used to deal with most of the
31 syntax changes between LilyPond versions.
33 It uses @code{\version} statements in the input files to detect the old
34 version number. For example, to upgrade all LilyPond files in the
35 current directory and its subdirectories, enter the following on the
39 convert-ly -e `find . -name '*.ly' -print`
42 In general, the program is invoked as follows:
45 convert-ly [@var{option}]@dots{} @var{file}@dots{}
49 The following options can be given:
53 Do an inline edit of the input file. Overrides @code{--output}.
55 @item -f,--from=@var{from-patchlevel}
56 Set the version to convert from. If this is not set, @command{convert-ly}
57 will guess this, on the basis of @code{\version} strings in the file.
59 @item -o,--output=@var{file}
60 Set the output file to write.
63 Normally, @command{convert-ly} adds a @code{\version} indicator
64 to the output. Specifying this option suppresses this.
66 @item -s, --show-rules
67 Show all known conversions and exit.
69 @item --to=@var{to-patchlevel}
70 Set the goal version of the conversion. It defaults to the latest
77 @command{convert-ly} always converts up to the last syntax change handled by
78 it. This means that the @code{\version} number left in the file is
79 usually lower than the version of @command{convert-ly} itself.
83 Not all language changes are handled. Only one output option can be
86 @node Invoking midi2ly
87 @section Invoking @command{midi2ly}
91 @command{midi2ly} translates a Type@tie{}1 MIDI file to a LilyPond source
94 MIDI (Music Instrument Digital Interface) is a standard for digital
95 instruments: it specifies cabling, a serial protocol and a file
96 format. The MIDI file format is a de facto standard format for
97 exporting music from other programs, so this capability may come in
98 useful when importing files from a program that has a convertor for a
101 @command{midi2ly} converts tracks into @internalsref{Staff} and
102 channels into @internalsref{Voice} contexts. Relative mode is used
103 for pitches, durations are only written when necessary.
105 It is possible to record a MIDI file using a digital keyboard, and
106 then convert it to @file{.ly}. However, human players are not
107 rhythmically exact enough to make a MIDI to LY conversion trivial.
108 When invoked with quantizing (@code{-s} and @code{-d} options)
109 @command{midi2ly} tries to compensate for these timing errors, but is not
110 very good at this. It is therefore not recommended to use @command{midi2ly}
111 for human-generated midi files.
114 It is invoked from the command-line as follows,
116 midi2ly [@var{option}]@dots{} @var{midi-file}
120 The following options are supported by @command{midi2ly}.
123 @item -a, --absolute-pitches
124 Print absolute pitches.
126 @item -d, --duration-quant=@var{DUR}
127 Quantize note durations on @var{DUR}.
129 @item -e, --explicit-durations
130 Print explicit durations.
133 Show summary of usage.
135 @item -k, --key=@var{acc}[:@var{minor}]
136 Set default key. @math{@var{acc} > 0} sets number of sharps;
137 @math{@var{acc} < 0} sets number of flats. A minor key is indicated by
140 @item -o, --output=@var{file}
141 Write output to @var{file}.
143 @item -s, --start-quant=@var{DUR}
144 Quantize note starts on DUR.
146 @item -t, --allow-tuplet=@var{DUR}*@var{NUM}/@var{DEN}
147 Allow tuplet durations @var{DUR}*@var{NUM}/@var{DEN}.
153 Print version number.
156 Show warranty and copyright.
158 @item -x, --text-lyrics
159 Treat every text as a lyric.
165 Overlapping notes in an arpeggio will not be correctly rendered. The
166 first note will be read and the others will be ignored. Set them all
167 to a single duration and add phrase markings or pedal indicators.
170 @node Invoking etf2ly
171 @section Invoking @command{etf2ly}
176 @cindex Coda Technology
178 ETF (Enigma Transport Format) is a format used by Coda Music
179 Technology's Finale product. @command{etf2ly} will convert part of an ETF
180 file to a ready-to-use LilyPond file.
182 It is invoked from the command-line as follows.
185 etf2ly [@var{option}]@dots{} @var{etf-file}
188 The following options are supported by @command{etf2ly}:
193 @item -o,--output=FILE
194 set output filename to FILE
202 The list of articulation scripts is incomplete. Empty measures
203 confuse @command{etf2ly}. Sequences of grace notes are ended improperly.
206 @node Invoking abc2ly
207 @section Invoking @code{abc2ly}
211 ABC is a fairly simple ASCII based format. It is described at the ABC site:
214 @uref{http://@/www@/.gre@/.ac@/.uk/@/~c.walshaw/@/abc2mtex/@/abc@/.txt}.
217 @command{abc2ly} translates from ABC to LilyPond. It is invoked as follows:
220 abc2ly [@var{option}]@dots{} @var{abc-file}
223 The following options are supported by @command{abc2ly}:
228 @item -o,--output=@var{file}
229 set output filename to @var{file}.
231 print version information.
234 There is a rudimentary facility for adding LilyPond code to the ABC
235 source file. If you say:
238 %%LY voices \set autoBeaming = ##f
241 This will cause the text following the keyword ``voices'' to be inserted
242 into the current voice of the LilyPond output file.
247 %%LY slyrics more words
250 will cause the text following the ``slyrics'' keyword to be inserted
251 into the current line of lyrics.
256 The ABC standard is not very ``standard''. For extended features
257 (e.g., polyphonic music) different conventions exist.
259 Multiple tunes in one file cannot be converted.
261 ABC synchronizes words and notes at the beginning of a line;
262 @command{abc2ly} does not.
264 @command{abc2ly} ignores the ABC beaming.
267 @node Invoking mup2ly
268 @section Invoking @command{mup2ly}
270 Mup (Music Publisher) is a shareware music notation program by Arkkra
271 Enterprises. @command{mup2ly} will convert part of a Mup file to LilyPond
272 format. It is invoked from the command-line as follows:
274 @cindex Music Publisher
279 mup2ly [@var{option}]@dots{} @var{mup-file}
282 The following options are supported by @command{mup2ly}:
286 show what constructs are not converted, but skipped.
287 @item -D, --define=@var{name}[=@code{exp}]
288 define macro @var{name} with opt expansion @code{exp}
289 @item -E,--pre-process
290 only run the pre-processor
293 @item -o,--output=@var{file}
294 write output to @var{file}
298 print warranty and copyright.
304 Only plain notes (pitches, durations), voices, and staves are
309 @section Other formats
311 LilyPond itself does not come with support for other formats, but
312 there are some external tools that also generate LilyPond files.
318 @uref{http://@/denemo@/.sourceforge@/.net/,Denemo}.
320 @uref{http://@/www@/.nongnu@/.org/@/xml2ly/, xml2ly}, that imports
321 @uref{http://@/www@/.musicxml@/.com/,MusicXML}
323 @uref{http://@/rnvs@/.informatik@/.tu@/-chemnitz@/.de/@/~jan/@/noteedit/@/noteedit@/.html,NoteEdit}
324 which imports MusicXML
326 @uref{http://@/www@/.all@/-day@/-breakfast@/.com/@/rosegarden/,Rosegarden},