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. In most cases, to upgrade your input file it is sufficient
38 covert-ly -e myfile.ly
41 If there are no changes to myfile.ly and file called myfile.ly.NEW
42 is created, then myfile.ly is already updated.
44 To upgrade LilyPond fragments in texinfo files, use
47 convert-ly --from=... --to=... --no-version *.itely
50 In general, the program is invoked as follows:
53 convert-ly [@var{option}]@dots{} @var{file}@dots{}
57 The following options can be given:
61 Do an inline edit of the input file. Overrides @code{--output}.
63 @item -f,--from=@var{from-patchlevel}
64 Set the version to convert from. If this is not set, @command{convert-ly}
65 will guess this, on the basis of @code{\version} strings in the file.
67 @item -o,--output=@var{file}
68 Set the output file to write.
71 Normally, @command{convert-ly} adds a @code{\version} indicator
72 to the output. Specifying this option suppresses this.
74 @item -s, --show-rules
75 Show all known conversions and exit.
77 @item --to=@var{to-patchlevel}
78 Set the goal version of the conversion. It defaults to the latest
85 @command{convert-ly} always converts up to the last syntax change handled by
86 it. This means that the @code{\version} number left in the file is
87 usually lower than the version of @command{convert-ly} itself.
91 Not all language changes are handled. Only one output option can be
95 @c We might want to make this a completely new section, along with more
96 @c info about how to upgrade old input files. -gp
99 Copy and paste from CVS, last updated
102 http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/lilypond/lily-bugs/bugs/convert-ly.txt?rev=HEAD&content-type=text/plain
106 There are a few things that the convert-ly cannot handle. Here's a list of limitations
107 that the community has complained about.
109 This bug report structure has been chosen because convert-ly has a structure that doesn't
110 allow to smoothly implement all needed changes. Thus this is just a wishlist, placed
114 Doesn't always convert figured bass correctly, specifically things like {< >}. Mats' comment on working around this:
115 To be able to run convert-ly
116 on it, I first replaced all occurencies of '{<' to some dummy like '{#'
117 and similarly I replaced '>}' with '&}'. After the conversion, I could
118 then change back from '{ #' to '{ <' and from '& }' to '> }'.
119 Doesn't convert all text markup correctly. Only very simple cases are fixed.
121 Doesn't handle \partcombine
122 Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple stanzas.
124 \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly converted.
128 @node Invoking midi2ly
129 @section Invoking @command{midi2ly}
133 @command{midi2ly} translates a Type@tie{}1 MIDI file to a LilyPond source
136 MIDI (Music Instrument Digital Interface) is a standard for digital
137 instruments: it specifies cabling, a serial protocol and a file
138 format. The MIDI file format is a de facto standard format for
139 exporting music from other programs, so this capability may come in
140 useful when importing files from a program that has a convertor for a
143 @command{midi2ly} converts tracks into @internalsref{Staff} and
144 channels into @internalsref{Voice} contexts. Relative mode is used
145 for pitches, durations are only written when necessary.
147 It is possible to record a MIDI file using a digital keyboard, and
148 then convert it to @file{.ly}. However, human players are not
149 rhythmically exact enough to make a MIDI to LY conversion trivial.
150 When invoked with quantizing (@code{-s} and @code{-d} options)
151 @command{midi2ly} tries to compensate for these timing errors, but is not
152 very good at this. It is therefore not recommended to use @command{midi2ly}
153 for human-generated midi files.
156 It is invoked from the command-line as follows,
158 midi2ly [@var{option}]@dots{} @var{midi-file}
162 The following options are supported by @command{midi2ly}.
165 @item -a, --absolute-pitches
166 Print absolute pitches.
168 @item -d, --duration-quant=@var{DUR}
169 Quantize note durations on @var{DUR}.
171 @item -e, --explicit-durations
172 Print explicit durations.
175 Show summary of usage.
177 @item -k, --key=@var{acc}[:@var{minor}]
178 Set default key. @math{@var{acc} > 0} sets number of sharps;
179 @math{@var{acc} < 0} sets number of flats. A minor key is indicated by
182 @item -o, --output=@var{file}
183 Write output to @var{file}.
185 @item -s, --start-quant=@var{DUR}
186 Quantize note starts on DUR.
188 @item -t, --allow-tuplet=@var{DUR}*@var{NUM}/@var{DEN}
189 Allow tuplet durations @var{DUR}*@var{NUM}/@var{DEN}.
195 Print version number.
198 Show warranty and copyright.
200 @item -x, --text-lyrics
201 Treat every text as a lyric.
207 Overlapping notes in an arpeggio will not be correctly rendered. The
208 first note will be read and the others will be ignored. Set them all
209 to a single duration and add phrase markings or pedal indicators.
212 @node Invoking etf2ly
213 @section Invoking @command{etf2ly}
218 @cindex Coda Technology
220 ETF (Enigma Transport Format) is a format used by Coda Music
221 Technology's Finale product. @command{etf2ly} will convert part of an ETF
222 file to a ready-to-use LilyPond file.
224 It is invoked from the command-line as follows.
227 etf2ly [@var{option}]@dots{} @var{etf-file}
230 The following options are supported by @command{etf2ly}:
235 @item -o,--output=FILE
236 set output filename to FILE
244 The list of articulation scripts is incomplete. Empty measures
245 confuse @command{etf2ly}. Sequences of grace notes are ended improperly.
248 @node Invoking abc2ly
249 @section Invoking @code{abc2ly}
253 ABC is a fairly simple ASCII based format. It is described at the ABC site:
256 @uref{http://@/www@/.gre@/.ac@/.uk/@/~c.walshaw/@/abc2mtex/@/abc@/.txt}.
259 @command{abc2ly} translates from ABC to LilyPond. It is invoked as follows:
262 abc2ly [@var{option}]@dots{} @var{abc-file}
265 The following options are supported by @command{abc2ly}:
270 @item -o,--output=@var{file}
271 set output filename to @var{file}.
273 print version information.
276 There is a rudimentary facility for adding LilyPond code to the ABC
277 source file. If you say:
280 %%LY voices \set autoBeaming = ##f
283 This will cause the text following the keyword ``voices'' to be inserted
284 into the current voice of the LilyPond output file.
289 %%LY slyrics more words
292 will cause the text following the ``slyrics'' keyword to be inserted
293 into the current line of lyrics.
298 The ABC standard is not very ``standard''. For extended features
299 (e.g., polyphonic music) different conventions exist.
301 Multiple tunes in one file cannot be converted.
303 ABC synchronizes words and notes at the beginning of a line;
304 @command{abc2ly} does not.
306 @command{abc2ly} ignores the ABC beaming.
309 @node Invoking mup2ly
310 @section Invoking @command{mup2ly}
312 Mup (Music Publisher) is a shareware music notation program by Arkkra
313 Enterprises. @command{mup2ly} will convert part of a Mup file to LilyPond
314 format. It is invoked from the command-line as follows:
316 @cindex Music Publisher
321 mup2ly [@var{option}]@dots{} @var{mup-file}
324 The following options are supported by @command{mup2ly}:
328 show what constructs are not converted, but skipped.
329 @item -D, --define=@var{name}[=@code{exp}]
330 define macro @var{name} with opt expansion @code{exp}
331 @item -E,--pre-process
332 only run the pre-processor
335 @item -o,--output=@var{file}
336 write output to @var{file}
340 print warranty and copyright.
346 Only plain notes (pitches, durations), voices, and staves are
351 @section Other formats
353 LilyPond itself does not come with support for other formats, but
354 there are some external tools that also generate LilyPond files.
360 @uref{http://@/denemo@/.sourceforge@/.net/,Denemo}.
362 @uref{http://@/www@/.nongnu@/.org/@/xml2ly/, xml2ly}, that imports
363 @uref{http://@/www@/.musicxml@/.com/,MusicXML}
365 @uref{http://@/rnvs@/.informatik@/.tu@/-chemnitz@/.de/@/~jan/@/noteedit/@/noteedit@/.html,NoteEdit}
366 which imports MusicXML
368 @uref{http://@/www@/.all@/-day@/-breakfast@/.com/@/rosegarden/,Rosegarden},