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 External programs
13 @chapter External programs
20 * Text editor support::
21 * Converting from other formats::
22 * LilyPond output in other programs::
23 * Independent includes::
28 @section Point and click
30 @cindex point and click
32 Point and click lets you find notes in the input by clicking on them
33 in the PDF viewer. This makes it easier to find input that causes
34 some error in the sheet music.
36 When this functionality is active, LilyPond adds hyperlinks to the PDF
37 file. These hyperlinks are sent to the web-browser, which opens a
38 text-editor with the cursor in the right place.
40 To make this chain work, you should configure your PDF viewer to
41 follow hyperlinks using the @file{lilypond-invoke-editor} script
42 supplied with LilyPond.
44 For Xpdf on UNIX, the following should be present in
45 @file{xpdfrc}@footnote{On UNIX, this file is found either in
46 @file{/etc/xpdfrc} or as @file{.xpdfrc} in your home directory.}
49 urlCommand "lilypond-invoke-editor %s"
52 The program @file{lilypond-invoke-editor} is a small helper
53 program. It will invoke an editor for the special @code{textedit}
54 URIs, and run a web browser for others. It tests the environment
55 variable @code{EDITOR} for the following patterns,
61 emacsclient --no-wait +@var{line}:@var{column} @var{file}
66 gvim --remote +:@var{line}:norm@var{column} @var{file}
72 nc -noask +@var{line} @var{file}'
76 The environment variable @code{LYEDITOR} is used to override this. It
77 contains the command line to start the editor, where @code{%(file)s},
78 @code{%(column)s}, @code{%(line)s} is replaced with the file, column
79 and line respectively. The setting
82 emacsclient --no-wait +%(line)s:%(column)s %(file)s
86 for @code{LYEDITOR} is equivalent to the standard emacsclient
90 @cindex file size, output
92 The point and click links enlarge the output files significantly. For
93 reducing the size of PDF and PS files, point and click may be switched
101 in a @file{.ly} file. Point and click may be explicitly enabled with
107 Alternately, you may disable point and click with a command-line
111 lilypond -dno-point-and-click file.ly
114 @warning{You should always turn off point and click in any LilyPond
115 files to be distributed to avoid including path information about
116 your computer in the .pdf file, which can pose a security risk.}
117 @node Text editor support
118 @section Text editor support
123 @cindex modes, editor
124 @cindex syntax coloring
125 @cindex coloring, syntax
127 There is support for different text editors for LilyPond.
136 @unnumberedsubsec Emacs mode
138 Emacs has a @file{lilypond-mode}, which provides keyword
139 autocompletion, indentation, LilyPond specific parenthesis matching
140 and syntax coloring, handy compile short-cuts and reading LilyPond
141 manuals using Info. If @file{lilypond-mode} is not installed on your
144 An Emacs mode for entering music and running LilyPond is contained in
145 the source archive in the @file{elisp} directory. Do @command{make
146 install} to install it to @var{elispdir}. The file @file{lilypond-init.el}
147 should be placed to @var{load-path}@file{/site-start.d/} or appended
148 to your @file{~/.emacs} or @file{~/.emacs.el}.
150 As a user, you may want add your source path (e.g. @file{~/site-lisp/}) to
151 your @var{load-path} by appending the following line (as modified) to your
154 @c any reason we do not advise: (push "~/site-lisp" load-path)
156 (setq load-path (append (list (expand-file-name "~/site-lisp")) load-path))
161 @unnumberedsubsec Vim mode
163 For @uref{http://@/www@/.vim@/.org,VIM}, a @file{vimrc} is supplied,
164 along with syntax coloring tools. A Vim mode for entering music and
165 running LilyPond is contained in the source archive in @code{$VIM}
168 The LilyPond file type is detected if the file
169 @file{~/.vim/filetype.vim} has the following content
172 if exists("did_load_filetypes")
175 augroup filetypedetect
176 au! BufNewFile,BufRead *.ly,*.ily setf lilypond
180 Please include this path by appending the following line to your
184 set runtimepath+=/usr/local/share/lilypond/$@{LILYPOND_VERSION@}/vim/
188 where $@{LILYPOND_VERSION@} is your LilyPond version. If LilyPond was not
189 installed in @file{/usr/local/}, then change this path accordingly.
190 The path may differ significantly. In Fedora the path leads to the
191 current version of Vim instead of Lilypond:
194 set runtimepath+=/usr/share/vim/vim72/
199 @unnumberedsubsec Other editors
201 Other editors (both text and graphical) support LilyPond, but
202 their special configuration files are not distributed with
203 LilyPond. Consult their documentation for more information. Such
204 editors are listed in @rweb{Alternate editors}.
207 @node Converting from other formats
208 @section Converting from other formats
210 Music can be entered also by importing it from other formats. This
211 chapter documents the tools included in the distribution to do so.
212 There are other tools that produce LilyPond input, for example GUI
213 sequencers and XML converters. Refer to the
214 @uref{http://@/lilypond@/.org,website} for more details.
216 These are separate programs from @command{lilypond} itself, and are
217 run on the command line; see @ref{Command-line usage} for more
218 information. If you have MacOS 10.3 or 10.4 and you have trouble
219 running some of these scripts, e.g. @code{convert-ly}, see
224 We unfortunately do not have the resources to maintain these
225 programs; please consider them @qq{as-is}. Patches are appreciated, but
226 bug reports will almost certainly not be resolved.
229 * Invoking midi2ly:: Importing MIDI.
230 * Invoking musicxml2ly:: Importing MusicXML.
231 * Invoking abc2ly:: Importing ABC.
232 * Invoking etf2ly:: Importing Finale.
238 @node Invoking midi2ly
239 @subsection Invoking @command{midi2ly}
243 @command{midi2ly} translates a Type@tie{}1 MIDI file to a LilyPond source
246 MIDI (Music Instrument Digital Interface) is a standard for digital
247 instruments: it specifies cabling, a serial protocol and a file
248 format. The MIDI file format is a de facto standard format for
249 exporting music from other programs, so this capability may come in
250 useful when importing files from a program that has a converter for a
253 @command{midi2ly} converts tracks into @rinternals{Staff} and
254 channels into @rinternals{Voice} contexts. Relative mode is used
255 for pitches, durations are only written when necessary.
257 It is possible to record a MIDI file using a digital keyboard, and
258 then convert it to @file{.ly}. However, human players are not
259 rhythmically exact enough to make a MIDI to LY conversion trivial.
260 When invoked with quantizing (@code{-s} and @code{-d} options)
261 @command{midi2ly} tries to compensate for these timing errors, but is not
262 very good at this. It is therefore not recommended to use @command{midi2ly}
263 for human-generated midi files.
266 It is invoked from the command-line as follows,
268 midi2ly [@var{option}]@dots{} @var{midi-file}
271 Note that by @q{command-line}, we mean the command line of the
272 operating system. See @ref{Converting from other formats}, for
273 more information about this.
275 The following options are supported by @command{midi2ly}.
278 @item -a, --absolute-pitches
279 Print absolute pitches.
281 @item -d, --duration-quant=@var{DUR}
282 Quantize note durations on @var{DUR}.
284 @item -e, --explicit-durations
285 Print explicit durations.
288 Show summary of usage.
290 @item -k, --key=@var{acc}[:@var{minor}]
291 Set default key. @math{@var{acc} > 0} sets number of sharps;
292 @math{@var{acc} < 0} sets number of flats. A minor key is indicated by
295 @item -o, --output=@var{file}
296 Write output to @var{file}.
298 @item -s, --start-quant=@var{DUR}
299 Quantize note starts on @var{DUR}.
301 @item -t, --allow-tuplet=@var{DUR}*@var{NUM}/@var{DEN}
302 Allow tuplet durations @var{DUR}*@var{NUM}/@var{DEN}.
308 Print version number.
311 Show warranty and copyright.
313 @item -x, --text-lyrics
314 Treat every text as a lyric.
320 Overlapping notes in an arpeggio will not be correctly rendered. The
321 first note will be read and the others will be ignored. Set them all
322 to a single duration and add phrase markings or pedal indicators.
325 @node Invoking musicxml2ly
326 @subsection Invoking @code{musicxml2ly}
330 @uref{http://@/www.@/musicxml@/.org/,MusicXML} is an XML dialect
331 for representing music notation.
333 @command{musicxml2ly} extracts the notes, articulations, score structure,
334 lyrics, etc. from part-wise MusicXML files, and writes them to a .ly
335 file. It is invoked from the command-line.
338 It is invoked from the command-line as follows,
340 musicxml2ly [@var{option}]@dots{} @var{xml-file}
343 Note that by @q{command-line}, we mean the command line of the
344 operating system. See @ref{Converting from other formats}, for
345 more information about this.
347 If the given filename is @file{-}, @command{musicxml2ly} reads input
348 from the command line.
350 The following options are supported by @command{musicxml2ly}:
354 convert pitches in absolute mode.
357 print usage and option summary.
359 @item -l, --language=LANG
360 use a different language file 'LANG.ly' and corresponding pitch names,
361 e.g. 'deutsch' for deutsch.ly and German note names.
364 use the lxml.etree Python package for XML-parsing; uses less memory and cpu time.
366 @item --nd --no-articulation-directions
367 do not convert directions (@code{^}, @code{_} or @code{-}) for
368 articulations, dynamics, etc.
371 do not convert beaming information, use LilyPond's automatic
374 @item -o,--output=@var{file}
375 set output filename to @var{file}. If @var{file} is @file{-}, the output
376 will be printed on stdout. If not given, @var{xml-file}@file{.ly} will
380 convert pitches in relative mode (default).
386 print version information.
388 @item -z,--compressed
389 input file is a zip-compressed MusicXML file.
393 @node Invoking abc2ly
394 @subsection Invoking @code{abc2ly}
396 @warning{This program is not supported, and may be remove from
397 future versions of LilyPond.}
401 ABC is a fairly simple ASCII based format. It is described at the ABC site:
404 @uref{http://@/www@/.walshaw@/.plus@/.com/@/abc/@/learn@/.html}.
407 @command{abc2ly} translates from ABC to LilyPond. It is invoked as follows:
410 abc2ly [@var{option}]@dots{} @var{abc-file}
413 The following options are supported by @command{abc2ly}:
416 @item -b,--beams=None
417 preserve ABC's notion of beams
420 @item -o,--output=@var{file}
421 set output filename to @var{file}.
423 be strict about success
425 print version information.
428 There is a rudimentary facility for adding LilyPond code to the ABC
429 source file. If you say:
432 %%LY voices \set autoBeaming = ##f
435 This will cause the text following the keyword @q{voices} to be inserted
436 into the current voice of the LilyPond output file.
441 %%LY slyrics more words
444 will cause the text following the @q{slyrics} keyword to be inserted
445 into the current line of lyrics.
450 The ABC standard is not very @q{standard}. For extended features
451 (e.g., polyphonic music) different conventions exist.
453 Multiple tunes in one file cannot be converted.
455 ABC synchronizes words and notes at the beginning of a line;
456 @command{abc2ly} does not.
458 @command{abc2ly} ignores the ABC beaming.
461 @node Invoking etf2ly
462 @subsection Invoking @command{etf2ly}
464 @warning{This program is not supported, and may be remove from
465 future versions of LilyPond.}
470 @cindex Coda Technology
472 ETF (Enigma Transport Format) is a format used by Coda Music
473 Technology's Finale product. @command{etf2ly} will convert part of an ETF
474 file to a ready-to-use LilyPond file.
476 It is invoked from the command-line as follows.
479 etf2ly [@var{option}]@dots{} @var{etf-file}
482 Note that by @q{command-line}, we mean the command line of the
483 operating system. See @ref{Converting from other formats}, for
484 more information about this.
486 The following options are supported by @command{etf2ly}:
491 @item -o,--output=@var{FILE}
492 set output filename to @var{FILE}
500 The list of articulation scripts is incomplete. Empty measures
501 confuse @command{etf2ly}. Sequences of grace notes are ended improperly.
505 @subsection Other formats
507 @cindex External programs, generating LilyPond files
509 LilyPond itself does not come with support for any other formats,
510 but some external tools can also generate LilyPond files. These
511 are listed in @rweb{Alternate editors}.
515 @node LilyPond output in other programs
516 @section LilyPond output in other programs
518 This section shows methods to integrate text and music, different than
519 the automated method with @command{lilypond-book}.
522 * Many quotes from a large score::
523 * Inserting LilyPond output into OpenOffice.org::
524 * Inserting LilyPond output into other programs::
527 @node Many quotes from a large score
528 @unnumberedsubsec Many quotes from a large score
530 If you need to quote many fragments from a large score, you can also use
531 the clip systems feature, see @ruser{Extracting fragments of music}.
534 @node Inserting LilyPond output into OpenOffice.org
535 @unnumberedsubsec Inserting LilyPond output into OpenOffice.org
537 @cindex OpenOffice.org
539 LilyPond notation can be added to OpenOffice.org with
540 @uref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond}.
543 @node Inserting LilyPond output into other programs
544 @unnumberedsubsec Inserting LilyPond output into other programs
546 To insert LilyPond output in other programs, use @code{lilypond}
547 instead of @code{lilypond-book}. Each example must be created
548 individually and added to the document; consult the documentation for
549 that program. Most programs will be able to insert LilyPond output in
550 @file{PNG}, @file{EPS}, or @file{PDF} formats.
552 To reduce the white space around your LilyPond score, use
553 the following options
561 bookTitleMarkup = ##f
562 scoreTitleMarkup = ##f
568 To produce a useful @file{EPS} file, use
571 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly
574 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts --png myfile.ly
578 @node Independent includes
579 @section Independent @code{include}s
584 * MIDI articulation::
588 @node MIDI articulation
589 @subsection MIDI articulation
591 stub for info about Dr. Peter Chubb's @file{articulate.ly}