1 @c -*- coding: utf-8; mode: texinfo; -*-
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. See TRANSLATION for details.
12 @node Converting from other formats
13 @chapter Converting from other formats
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.
21 These are separate programs from @command{lilypond} itself, and are
22 run on the command line; see @ref{Command-line usage} for more
23 information. If you have MacOS 10.3 or 10.4 and you have trouble
24 running some of these scripts, e.g. @code{convert-ly}, see
25 FIXME FIXME @c @ref{Setup for MacOS X}.
29 We unfortunately do not have the resources to maintain these
30 programs; please consider them @qq{as-is}. Patches are appreciated, but
31 bug reports will almost certainly not be resolved.
34 * Invoking midi2ly:: Importing MIDI.
35 * Invoking musicxml2ly:: Importing MusicXML.
36 * Invoking abc2ly:: Importing ABC.
37 * Invoking etf2ly:: Importing Finale.
38 * Generating LilyPond files:: GUIs, transcribers, and algorithmic composition programs.
43 @node Invoking midi2ly
44 @section Invoking @command{midi2ly}
48 @command{midi2ly} translates a Type@tie{}1 MIDI file to a LilyPond source
51 MIDI (Music Instrument Digital Interface) is a standard for digital
52 instruments: it specifies cabling, a serial protocol and a file
53 format. The MIDI file format is a de facto standard format for
54 exporting music from other programs, so this capability may come in
55 useful when importing files from a program that has a converter for a
58 @command{midi2ly} converts tracks into @rinternals{Staff} and
59 channels into @rinternals{Voice} contexts. Relative mode is used
60 for pitches, durations are only written when necessary.
62 It is possible to record a MIDI file using a digital keyboard, and
63 then convert it to @file{.ly}. However, human players are not
64 rhythmically exact enough to make a MIDI to LY conversion trivial.
65 When invoked with quantizing (@code{-s} and @code{-d} options)
66 @command{midi2ly} tries to compensate for these timing errors, but is not
67 very good at this. It is therefore not recommended to use @command{midi2ly}
68 for human-generated midi files.
71 It is invoked from the command-line as follows,
73 midi2ly [@var{option}]@dots{} @var{midi-file}
76 Note that by @q{command-line}, we mean the command line of the
77 operating system. See @ref{Converting from other formats}, for
78 more information about this.
80 The following options are supported by @command{midi2ly}.
83 @item -a, --absolute-pitches
84 Print absolute pitches.
86 @item -d, --duration-quant=@var{DUR}
87 Quantize note durations on @var{DUR}.
89 @item -e, --explicit-durations
90 Print explicit durations.
93 Show summary of usage.
95 @item -k, --key=@var{acc}[:@var{minor}]
96 Set default key. @math{@var{acc} > 0} sets number of sharps;
97 @math{@var{acc} < 0} sets number of flats. A minor key is indicated by
100 @item -o, --output=@var{file}
101 Write output to @var{file}.
103 @item -s, --start-quant=@var{DUR}
104 Quantize note starts on @var{DUR}.
106 @item -t, --allow-tuplet=@var{DUR}*@var{NUM}/@var{DEN}
107 Allow tuplet durations @var{DUR}*@var{NUM}/@var{DEN}.
113 Print version number.
116 Show warranty and copyright.
118 @item -x, --text-lyrics
119 Treat every text as a lyric.
125 Overlapping notes in an arpeggio will not be correctly rendered. The
126 first note will be read and the others will be ignored. Set them all
127 to a single duration and add phrase markings or pedal indicators.
130 @node Invoking musicxml2ly
131 @section Invoking @code{musicxml2ly}
135 @uref{http://@/www.@/musicxml@/.org/,MusicXML} is an XML dialect
136 for representing music notation.
138 @command{musicxml2ly} extracts the notes, articulations, score structure,
139 lyrics, etc. from part-wise MusicXML files, and writes them to a .ly
140 file. It is invoked from the command-line.
143 It is invoked from the command-line as follows,
145 musicxml2ly [@var{option}]@dots{} @var{xml-file}
148 Note that by @q{command-line}, we mean the command line of the
149 operating system. See @ref{Converting from other formats}, for
150 more information about this.
152 If the given filename is @file{-}, @command{musicxml2ly} reads input
153 from the command line.
155 The following options are supported by @command{musicxml2ly}:
159 convert pitches in absolute mode.
162 print usage and option summary.
164 @item -l, --language=LANG
165 use a different language file 'LANG.ly' and corresponding pitch names,
166 e.g. 'deutsch' for deutsch.ly and German note names.
169 use the lxml.etree Python package for XML-parsing; uses less memory and cpu time.
171 @item --nd --no-articulation-directions
172 do not convert directions (@code{^}, @code{_} or @code{-}) for
173 articulations, dynamics, etc.
176 do not convert beaming information, use LilyPond's automatic
179 @item -o,--output=@var{file}
180 set output filename to @var{file}. If @var{file} is @file{-}, the output
181 will be printed on stdout. If not given, @var{xml-file}@file{.ly} will
185 convert pitches in relative mode (default).
191 print version information.
193 @item -z,--compressed
194 input file is a zip-compressed MusicXML file.
198 @node Invoking abc2ly
199 @section Invoking @code{abc2ly}
203 ABC is a fairly simple ASCII based format. It is described at the ABC site:
206 @uref{http://@/www@/.walshaw@/.plus@/.com/@/abc/@/learn@/.html}.
209 @command{abc2ly} translates from ABC to LilyPond. It is invoked as follows:
212 abc2ly [@var{option}]@dots{} @var{abc-file}
215 The following options are supported by @command{abc2ly}:
218 @item -b,--beams=None
219 preserve ABC's notion of beams
222 @item -o,--output=@var{file}
223 set output filename to @var{file}.
225 be strict about success
227 print version information.
230 There is a rudimentary facility for adding LilyPond code to the ABC
231 source file. If you say:
234 %%LY voices \set autoBeaming = ##f
237 This will cause the text following the keyword @q{voices} to be inserted
238 into the current voice of the LilyPond output file.
243 %%LY slyrics more words
246 will cause the text following the @q{slyrics} keyword to be inserted
247 into the current line of lyrics.
252 The ABC standard is not very @q{standard}. For extended features
253 (e.g., polyphonic music) different conventions exist.
255 Multiple tunes in one file cannot be converted.
257 ABC synchronizes words and notes at the beginning of a line;
258 @command{abc2ly} does not.
260 @command{abc2ly} ignores the ABC beaming.
263 @node Invoking etf2ly
264 @section Invoking @command{etf2ly}
269 @cindex Coda Technology
271 ETF (Enigma Transport Format) is a format used by Coda Music
272 Technology's Finale product. @command{etf2ly} will convert part of an ETF
273 file to a ready-to-use LilyPond file.
275 It is invoked from the command-line as follows.
278 etf2ly [@var{option}]@dots{} @var{etf-file}
281 Note that by @q{command-line}, we mean the command line of the
282 operating system. See @ref{Converting from other formats}, for
283 more information about this.
285 The following options are supported by @command{etf2ly}:
290 @item -o,--output=@var{FILE}
291 set output filename to @var{FILE}
299 The list of articulation scripts is incomplete. Empty measures
300 confuse @command{etf2ly}. Sequences of grace notes are ended improperly.
303 @node Generating LilyPond files
304 @section Generating LilyPond files
306 @cindex External programs, generating LilyPond files
308 LilyPond itself does not come with support for any other formats, but
309 there are some external tools that also generate LilyPond files.
315 @uref{http://@/www@/.denemo@/.org/,Denemo}, a graphical score editor.
317 @uref{http://www@/.volny@/.cz/smilauer/rumor/rumor@/.html,Rumor}, a realtime
318 monophonic MIDI to LilyPond converter.
320 @uref{http://nicolas@/.sceaux@/.free@/.fr/lilypond/lyqi@/.html,lyqi}, an
323 @uref{http://@/www@/.nongnu@/.org/@/xml2ly/,xml2ly}, which imports
324 @uref{http://@/www@/.musicxml@/.com/xml@/.html,MusicXML}
326 @uref{http://@/noteedit@/.berlios@/.de,NoteEdit}
327 which imports @uref{http://@/www@/.musicxml@/.com/xml@/.html,MusicXML}
329 @uref{http://@/www@/.rosegardenmusic@/.com,Rosegarden},
332 @uref{http://@/common-lisp@/.net/project/fomus/,FOMUS},
333 a LISP library to generate music notation
335 @uref{http://vsr.informatik.tu-chemnitz.de/staff/jan/nted/nted.xhtml},
336 has experimental export for LilyPond.
338 @uref{http://www.tuxguitar.com.ar/}, can export to LilyPond.
340 @uref{http://musescore.org} can also export to LilyPond.