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. For details, see the Contributors'
8 Guide, node Updating translation committishes..
13 @node External programs
14 @chapter External programs
21 * Text editor support::
22 * Converting from other formats::
23 * LilyPond output in other programs::
24 * Independent includes::
29 @section Point and click
31 @cindex point and click
33 Point and click lets you find notes in the input by clicking on them
34 in the PDF viewer. This makes it easier to find input that causes
35 some error in the sheet music.
37 When this functionality is active, LilyPond adds hyperlinks to the PDF
38 file. These hyperlinks are sent to the web-browser, which opens a
39 text-editor with the cursor in the right place.
41 To make this chain work, you should configure your PDF viewer to
42 follow hyperlinks using the @file{lilypond-invoke-editor} script
43 supplied with LilyPond.
45 For Xpdf on UNIX, the following should be present in
46 @file{xpdfrc}@footnote{On UNIX, this file is found either in
47 @file{/etc/xpdfrc} or as @file{.xpdfrc} in your home directory.}
50 urlCommand "lilypond-invoke-editor %s"
53 The program @file{lilypond-invoke-editor} is a small helper
54 program. It will invoke an editor for the special @code{textedit}
55 URIs, and run a web browser for others. It tests the environment
56 variable @code{EDITOR} for the following patterns,
62 emacsclient --no-wait +@var{line}:@var{column} @var{file}
67 gvim --remote +:@var{line}:norm@var{column} @var{file}
73 nc -noask +@var{line} @var{file}'
77 The environment variable @code{LYEDITOR} is used to override this. It
78 contains the command line to start the editor, where @code{%(file)s},
79 @code{%(column)s}, @code{%(line)s} is replaced with the file, column
80 and line respectively. The setting
83 emacsclient --no-wait +%(line)s:%(column)s %(file)s
87 for @code{LYEDITOR} is equivalent to the standard emacsclient
91 @cindex file size, output
93 The point and click links enlarge the output files significantly. For
94 reducing the size of PDF and PS files, point and click may be switched
102 in a @file{.ly} file. Point and click may be explicitly enabled with
108 Alternately, you may disable point and click with a command-line
112 lilypond -dno-point-and-click file.ly
115 @warning{You should always turn off point and click in any LilyPond
116 files to be distributed to avoid including path information about
117 your computer in the .pdf file, which can pose a security risk.}
118 @node Text editor support
119 @section Text editor support
124 @cindex modes, editor
125 @cindex syntax coloring
126 @cindex coloring, syntax
128 There is support for different text editors for LilyPond.
137 @unnumberedsubsec Emacs mode
139 Emacs has a @file{lilypond-mode}, which provides keyword
140 autocompletion, indentation, LilyPond specific parenthesis matching
141 and syntax coloring, handy compile short-cuts and reading LilyPond
142 manuals using Info. If @file{lilypond-mode} is not installed on your
145 An Emacs mode for entering music and running LilyPond is contained in
146 the source archive in the @file{elisp} directory. Do @command{make
147 install} to install it to @var{elispdir}. The file @file{lilypond-init.el}
148 should be placed to @var{load-path}@file{/site-start.d/} or appended
149 to your @file{~/.emacs} or @file{~/.emacs.el}.
151 As a user, you may want add your source path (e.g. @file{~/site-lisp/}) to
152 your @var{load-path} by appending the following line (as modified) to your
155 @c any reason we do not advise: (push "~/site-lisp" load-path)
157 (setq load-path (append (list (expand-file-name "~/site-lisp")) load-path))
162 @unnumberedsubsec Vim mode
164 For @uref{http://@/www@/.vim@/.org,VIM}, a @file{vimrc} is supplied,
165 along with syntax coloring tools. A Vim mode for entering music and
166 running LilyPond is contained in the source archive in @code{$VIM}
169 The LilyPond file type is detected if the file
170 @file{~/.vim/filetype.vim} has the following content
173 if exists("did_load_filetypes")
176 augroup filetypedetect
177 au! BufNewFile,BufRead *.ly,*.ily setf lilypond
181 Please include this path by appending the following line to your
185 set runtimepath+=/usr/local/share/lilypond/$@{LILYPOND_VERSION@}/vim/
189 where $@{LILYPOND_VERSION@} is your LilyPond version. If LilyPond was not
190 installed in @file{/usr/local/}, then change this path accordingly.
191 The path may differ significantly. In Fedora the path leads to the
192 current version of Vim instead of Lilypond:
195 set runtimepath+=/usr/share/vim/vim72/
200 @unnumberedsubsec Other editors
202 Other editors (both text and graphical) support LilyPond, but
203 their special configuration files are not distributed with
204 LilyPond. Consult their documentation for more information. Such
205 editors are listed in @rweb{Alternate editors}.
208 @node Converting from other formats
209 @section Converting from other formats
211 Music can be entered also by importing it from other formats. This
212 chapter documents the tools included in the distribution to do so.
213 There are other tools that produce LilyPond input, for example GUI
214 sequencers and XML converters. Refer to the
215 @uref{http://@/lilypond@/.org,website} for more details.
217 These are separate programs from @command{lilypond} itself, and are
218 run on the command line; see @ref{Command-line usage} for more
219 information. If you have MacOS 10.3 or 10.4 and you have trouble
220 running some of these scripts, e.g. @code{convert-ly}, see
225 We unfortunately do not have the resources to maintain these
226 programs; please consider them @qq{as-is}. Patches are appreciated, but
227 bug reports will almost certainly not be resolved.
230 * Invoking midi2ly:: Importing MIDI.
231 * Invoking musicxml2ly:: Importing MusicXML.
232 * Invoking abc2ly:: Importing ABC.
233 * Invoking etf2ly:: Importing Finale.
239 @node Invoking midi2ly
240 @subsection Invoking @command{midi2ly}
244 @command{midi2ly} translates a Type@tie{}1 MIDI file to a LilyPond source
247 MIDI (Music Instrument Digital Interface) is a standard for digital
248 instruments: it specifies cabling, a serial protocol and a file
249 format. The MIDI file format is a de facto standard format for
250 exporting music from other programs, so this capability may come in
251 useful when importing files from a program that has a converter for a
254 @command{midi2ly} converts tracks into @rinternals{Staff} and
255 channels into @rinternals{Voice} contexts. Relative mode is used
256 for pitches, durations are only written when necessary.
258 It is possible to record a MIDI file using a digital keyboard, and
259 then convert it to @file{.ly}. However, human players are not
260 rhythmically exact enough to make a MIDI to LY conversion trivial.
261 When invoked with quantizing (@code{-s} and @code{-d} options)
262 @command{midi2ly} tries to compensate for these timing errors, but is not
263 very good at this. It is therefore not recommended to use @command{midi2ly}
264 for human-generated midi files.
267 It is invoked from the command-line as follows,
269 midi2ly [@var{option}]@dots{} @var{midi-file}
272 Note that by @q{command-line}, we mean the command line of the
273 operating system. See @ref{Converting from other formats}, for
274 more information about this.
276 The following options are supported by @command{midi2ly}.
279 @item -a, --absolute-pitches
280 Print absolute pitches.
282 @item -d, --duration-quant=@var{DUR}
283 Quantize note durations on @var{DUR}.
285 @item -e, --explicit-durations
286 Print explicit durations.
289 Show summary of usage.
291 @item -k, --key=@var{acc}[:@var{minor}]
292 Set default key. @math{@var{acc} > 0} sets number of sharps;
293 @math{@var{acc} < 0} sets number of flats. A minor key is indicated by
296 @item -o, --output=@var{file}
297 Write output to @var{file}.
299 @item -s, --start-quant=@var{DUR}
300 Quantize note starts on @var{DUR}.
302 @item -t, --allow-tuplet=@var{DUR}*@var{NUM}/@var{DEN}
303 Allow tuplet durations @var{DUR}*@var{NUM}/@var{DEN}.
309 Print version number.
312 Show warranty and copyright.
314 @item -x, --text-lyrics
315 Treat every text as a lyric.
321 Overlapping notes in an arpeggio will not be correctly rendered. The
322 first note will be read and the others will be ignored. Set them all
323 to a single duration and add phrase markings or pedal indicators.
326 @node Invoking musicxml2ly
327 @subsection Invoking @code{musicxml2ly}
331 @uref{http://@/www.@/musicxml@/.org/,MusicXML} is an XML dialect
332 for representing music notation.
334 @command{musicxml2ly} extracts the notes, articulations, score structure,
335 lyrics, etc. from part-wise MusicXML files, and writes them to a .ly
336 file. It is invoked from the command-line.
339 It is invoked from the command-line as follows,
341 musicxml2ly [@var{option}]@dots{} @var{xml-file}
344 Note that by @q{command-line}, we mean the command line of the
345 operating system. See @ref{Converting from other formats}, for
346 more information about this.
348 If the given filename is @file{-}, @command{musicxml2ly} reads input
349 from the command line.
351 The following options are supported by @command{musicxml2ly}:
355 convert pitches in absolute mode.
358 print usage and option summary.
360 @item -l, --language=LANG
361 use a different language file 'LANG.ly' and corresponding pitch names,
362 e.g. 'deutsch' for deutsch.ly and German note names.
365 use the lxml.etree Python package for XML-parsing; uses less memory and cpu time.
367 @item --nd --no-articulation-directions
368 do not convert directions (@code{^}, @code{_} or @code{-}) for
369 articulations, dynamics, etc.
372 do not convert beaming information, use LilyPond's automatic
375 @item -o,--output=@var{file}
376 set output filename to @var{file}. If @var{file} is @file{-}, the output
377 will be printed on stdout. If not given, @var{xml-file}@file{.ly} will
381 convert pitches in relative mode (default).
387 print version information.
389 @item -z,--compressed
390 input file is a zip-compressed MusicXML file.
394 @node Invoking abc2ly
395 @subsection Invoking @code{abc2ly}
397 @warning{This program is not supported, and may be remove from
398 future versions of LilyPond.}
402 ABC is a fairly simple ASCII based format. It is described at the ABC site:
405 @uref{http://@/www@/.walshaw@/.plus@/.com/@/abc/@/learn@/.html}.
408 @command{abc2ly} translates from ABC to LilyPond. It is invoked as follows:
411 abc2ly [@var{option}]@dots{} @var{abc-file}
414 The following options are supported by @command{abc2ly}:
417 @item -b,--beams=None
418 preserve ABC's notion of beams
421 @item -o,--output=@var{file}
422 set output filename to @var{file}.
424 be strict about success
426 print version information.
429 There is a rudimentary facility for adding LilyPond code to the ABC
430 source file. If you say:
433 %%LY voices \set autoBeaming = ##f
436 This will cause the text following the keyword @q{voices} to be inserted
437 into the current voice of the LilyPond output file.
442 %%LY slyrics more words
445 will cause the text following the @q{slyrics} keyword to be inserted
446 into the current line of lyrics.
451 The ABC standard is not very @q{standard}. For extended features
452 (e.g., polyphonic music) different conventions exist.
454 Multiple tunes in one file cannot be converted.
456 ABC synchronizes words and notes at the beginning of a line;
457 @command{abc2ly} does not.
459 @command{abc2ly} ignores the ABC beaming.
462 @node Invoking etf2ly
463 @subsection Invoking @command{etf2ly}
465 @warning{This program is not supported, and may be remove from
466 future versions of LilyPond.}
471 @cindex Coda Technology
473 ETF (Enigma Transport Format) is a format used by Coda Music
474 Technology's Finale product. @command{etf2ly} will convert part of an ETF
475 file to a ready-to-use LilyPond file.
477 It is invoked from the command-line as follows.
480 etf2ly [@var{option}]@dots{} @var{etf-file}
483 Note that by @q{command-line}, we mean the command line of the
484 operating system. See @ref{Converting from other formats}, for
485 more information about this.
487 The following options are supported by @command{etf2ly}:
492 @item -o,--output=@var{FILE}
493 set output filename to @var{FILE}
501 The list of articulation scripts is incomplete. Empty measures
502 confuse @command{etf2ly}. Sequences of grace notes are ended improperly.
506 @subsection Other formats
508 @cindex External programs, generating LilyPond files
510 LilyPond itself does not come with support for any other formats,
511 but some external tools can also generate LilyPond files. These
512 are listed in @rweb{Alternate editors}.
516 @node LilyPond output in other programs
517 @section LilyPond output in other programs
519 This section shows methods to integrate text and music, different than
520 the automated method with @command{lilypond-book}.
523 * Many quotes from a large score::
524 * Inserting LilyPond output into OpenOffice.org::
525 * Inserting LilyPond output into other programs::
528 @node Many quotes from a large score
529 @unnumberedsubsec Many quotes from a large score
531 If you need to quote many fragments from a large score, you can also use
532 the clip systems feature, see @ruser{Extracting fragments of music}.
535 @node Inserting LilyPond output into OpenOffice.org
536 @unnumberedsubsec Inserting LilyPond output into OpenOffice.org
538 @cindex OpenOffice.org
540 LilyPond notation can be added to OpenOffice.org with
541 @uref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond}.
544 @node Inserting LilyPond output into other programs
545 @unnumberedsubsec Inserting LilyPond output into other programs
547 To insert LilyPond output in other programs, use @code{lilypond}
548 instead of @code{lilypond-book}. Each example must be created
549 individually and added to the document; consult the documentation for
550 that program. Most programs will be able to insert LilyPond output in
551 @file{PNG}, @file{EPS}, or @file{PDF} formats.
553 To reduce the white space around your LilyPond score, use
554 the following options
562 bookTitleMarkup = ##f
563 scoreTitleMarkup = ##f
569 To produce a useful @file{EPS} file, use
572 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly
575 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts --png myfile.ly
579 @node Independent includes
580 @section Independent @code{include}s
585 * MIDI articulation::
589 @node MIDI articulation
590 @subsection MIDI articulation
592 stub for info about Dr. Peter Chubb's @file{articulate.ly}