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
16 LilyPond can interact with other programs in various ways.
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 filetype plugin, indent
164 mode, and syntax-highlighting mode are available to use with
165 LilyPond. To enable all of these features, create (or modify)
166 your @file{$HOME/.vimrc} to contain these three lines, in order:
170 set runtimepath+=/usr/local/share/lilypond/current/vim/
175 If LilyPond is not installed in the @file{/usr/local/} directory,
176 change the path appropriately. This topic is discussed in
177 @rlearning{Other sources of information}.
181 @unnumberedsubsec Other editors
183 Other editors (both text and graphical) support LilyPond, but
184 their special configuration files are not distributed with
185 LilyPond. Consult their documentation for more information. Such
186 editors are listed in @rweb{Easier editing}.
189 @node Converting from other formats
190 @section Converting from other formats
192 Music can be entered also by importing it from other formats. This
193 chapter documents the tools included in the distribution to do so.
194 There are other tools that produce LilyPond input, for example GUI
195 sequencers and XML converters. Refer to the
196 @uref{http://@/lilypond@/.org,website} for more details.
198 These are separate programs from @command{lilypond} itself, and are
199 run on the command line; see @ref{Command-line usage} for more
200 information. If you have MacOS 10.3 or 10.4 and you have trouble
201 running some of these scripts, e.g. @code{convert-ly}, see
206 We unfortunately do not have the resources to maintain these
207 programs; please consider them @qq{as-is}. Patches are appreciated, but
208 bug reports will almost certainly not be resolved.
211 * Invoking midi2ly:: Importing MIDI.
212 * Invoking musicxml2ly:: Importing MusicXML.
213 * Invoking abc2ly:: Importing ABC.
214 * Invoking etf2ly:: Importing Finale.
220 @node Invoking midi2ly
221 @subsection Invoking @command{midi2ly}
225 @command{midi2ly} translates a Type@tie{}1 MIDI file to a LilyPond source
228 MIDI (Music Instrument Digital Interface) is a standard for digital
229 instruments: it specifies cabling, a serial protocol and a file
230 format. The MIDI file format is a de facto standard format for
231 exporting music from other programs, so this capability may come in
232 useful when importing files from a program that has a converter for a
235 @command{midi2ly} converts tracks into @rinternals{Staff} and
236 channels into @rinternals{Voice} contexts. Relative mode is used
237 for pitches, durations are only written when necessary.
239 It is possible to record a MIDI file using a digital keyboard, and
240 then convert it to @file{.ly}. However, human players are not
241 rhythmically exact enough to make a MIDI to LY conversion trivial.
242 When invoked with quantizing (@code{-s} and @code{-d} options)
243 @command{midi2ly} tries to compensate for these timing errors, but is not
244 very good at this. It is therefore not recommended to use @command{midi2ly}
245 for human-generated midi files.
248 It is invoked from the command-line as follows,
250 midi2ly [@var{option}]@dots{} @var{midi-file}
253 Note that by @q{command-line}, we mean the command line of the
254 operating system. See @ref{Converting from other formats}, for
255 more information about this.
257 The following options are supported by @command{midi2ly}.
260 @item -a, --absolute-pitches
261 Print absolute pitches.
263 @item -d, --duration-quant=@var{DUR}
264 Quantize note durations on @var{DUR}.
266 @item -e, --explicit-durations
267 Print explicit durations.
270 Show summary of usage.
272 @item -k, --key=@var{acc}[:@var{minor}]
273 Set default key. @math{@var{acc} > 0} sets number of sharps;
274 @math{@var{acc} < 0} sets number of flats. A minor key is indicated by
277 @item -o, --output=@var{file}
278 Write output to @var{file}.
280 @item -s, --start-quant=@var{DUR}
281 Quantize note starts on @var{DUR}.
283 @item -t, --allow-tuplet=@var{DUR}*@var{NUM}/@var{DEN}
284 Allow tuplet durations @var{DUR}*@var{NUM}/@var{DEN}.
290 Print version number.
293 Show warranty and copyright.
295 @item -x, --text-lyrics
296 Treat every text as a lyric.
302 Overlapping notes in an arpeggio will not be correctly rendered. The
303 first note will be read and the others will be ignored. Set them all
304 to a single duration and add phrase markings or pedal indicators.
307 @node Invoking musicxml2ly
308 @subsection Invoking @code{musicxml2ly}
312 @uref{http://@/www.@/musicxml@/.org/,MusicXML} is an XML dialect
313 for representing music notation.
315 @command{musicxml2ly} extracts the notes, articulations, score structure,
316 lyrics, etc. from part-wise MusicXML files, and writes them to a .ly
317 file. It is invoked from the command-line.
320 It is invoked from the command-line as follows,
322 musicxml2ly [@var{option}]@dots{} @var{xml-file}
325 Note that by @q{command-line}, we mean the command line of the
326 operating system. See @ref{Converting from other formats}, for
327 more information about this.
329 If the given filename is @file{-}, @command{musicxml2ly} reads input
330 from the command line.
332 The following options are supported by @command{musicxml2ly}:
336 convert pitches in absolute mode.
339 print usage and option summary.
341 @item -l, --language=LANG
342 use a different language file 'LANG.ly' and corresponding pitch names,
343 e.g. 'deutsch' for deutsch.ly and German note names.
346 use the lxml.etree Python package for XML-parsing; uses less memory and cpu time.
348 @item --nd --no-articulation-directions
349 do not convert directions (@code{^}, @code{_} or @code{-}) for
350 articulations, dynamics, etc.
353 do not convert beaming information, use LilyPond's automatic
356 @item -o,--output=@var{file}
357 set output filename to @var{file}. If @var{file} is @file{-}, the output
358 will be printed on stdout. If not given, @var{xml-file}@file{.ly} will
362 convert pitches in relative mode (default).
368 print version information.
370 @item -z,--compressed
371 input file is a zip-compressed MusicXML file.
375 @node Invoking abc2ly
376 @subsection Invoking @code{abc2ly}
378 @warning{This program is not supported, and may be remove from
379 future versions of LilyPond.}
383 ABC is a fairly simple ASCII based format. It is described at the ABC site:
386 @uref{http://@/www@/.walshaw@/.plus@/.com/@/abc/@/learn@/.html}.
389 @command{abc2ly} translates from ABC to LilyPond. It is invoked as follows:
392 abc2ly [@var{option}]@dots{} @var{abc-file}
395 The following options are supported by @command{abc2ly}:
398 @item -b,--beams=None
399 preserve ABC's notion of beams
402 @item -o,--output=@var{file}
403 set output filename to @var{file}.
405 be strict about success
407 print version information.
410 There is a rudimentary facility for adding LilyPond code to the ABC
411 source file. If you say:
414 %%LY voices \set autoBeaming = ##f
417 This will cause the text following the keyword @q{voices} to be inserted
418 into the current voice of the LilyPond output file.
423 %%LY slyrics more words
426 will cause the text following the @q{slyrics} keyword to be inserted
427 into the current line of lyrics.
432 The ABC standard is not very @q{standard}. For extended features
433 (e.g., polyphonic music) different conventions exist.
435 Multiple tunes in one file cannot be converted.
437 ABC synchronizes words and notes at the beginning of a line;
438 @command{abc2ly} does not.
440 @command{abc2ly} ignores the ABC beaming.
443 @node Invoking etf2ly
444 @subsection Invoking @command{etf2ly}
446 @warning{This program is not supported, and may be remove from
447 future versions of LilyPond.}
452 @cindex Coda Technology
454 ETF (Enigma Transport Format) is a format used by Coda Music
455 Technology's Finale product. @command{etf2ly} will convert part of an ETF
456 file to a ready-to-use LilyPond file.
458 It is invoked from the command-line as follows.
461 etf2ly [@var{option}]@dots{} @var{etf-file}
464 Note that by @q{command-line}, we mean the command line of the
465 operating system. See @ref{Converting from other formats}, for
466 more information about this.
468 The following options are supported by @command{etf2ly}:
473 @item -o,--output=@var{FILE}
474 set output filename to @var{FILE}
482 The list of articulation scripts is incomplete. Empty measures
483 confuse @command{etf2ly}. Sequences of grace notes are ended improperly.
487 @subsection Other formats
489 @cindex External programs, generating LilyPond files
491 LilyPond itself does not come with support for any other formats,
492 but some external tools can also generate LilyPond files. These
493 are listed in @rweb{Easier editing}.
497 @node LilyPond output in other programs
498 @section LilyPond output in other programs
500 This section shows methods to integrate text and music, different than
501 the automated method with @command{lilypond-book}.
504 * Many quotes from a large score::
505 * Inserting LilyPond output into OpenOffice.org::
506 * Inserting LilyPond output into other programs::
509 @node Many quotes from a large score
510 @unnumberedsubsec Many quotes from a large score
512 If you need to quote many fragments from a large score, you can also use
513 the clip systems feature, see @ruser{Extracting fragments of music}.
516 @node Inserting LilyPond output into OpenOffice.org
517 @unnumberedsubsec Inserting LilyPond output into OpenOffice.org
519 @cindex OpenOffice.org
521 LilyPond notation can be added to OpenOffice.org with
522 @uref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond}.
525 @node Inserting LilyPond output into other programs
526 @unnumberedsubsec Inserting LilyPond output into other programs
528 To insert LilyPond output in other programs, use @code{lilypond}
529 instead of @code{lilypond-book}. Each example must be created
530 individually and added to the document; consult the documentation for
531 that program. Most programs will be able to insert LilyPond output in
532 @file{PNG}, @file{EPS}, or @file{PDF} formats.
534 To reduce the white space around your LilyPond score, use
535 the following options
543 bookTitleMarkup = ##f
544 scoreTitleMarkup = ##f
550 To produce a useful @file{EPS} file, use
553 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly
556 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts --png myfile.ly
560 @node Independent includes
561 @section Independent @code{include}s
563 Some people have written large (and useful!) code that can be
564 shared between projects. This code might eventually make its way
565 into LilyPond itself, but until that happens, you must download
566 and @code{\include} them manually.
570 * MIDI articulation::
574 @node MIDI articulation
575 @subsection MIDI articulation
577 LilyPond can be used to produce MIDI output, for
578 @qq{proof-hearing} what has been written. However, only dynamics,
579 explicit tempo markings, and the notes and durations themselves
580 are produced in the output.
582 The @emph{articulate} project is one attempt to get more of the
583 information in the score into he MIDI. It works by shortening
584 notes not under slurs, to @q{articulate} the notes. The amount of
585 shortening depends on any articulation markings attached to a
586 note: staccato halves the note value, tenuto gives a note its full
587 duration, and so on. The script also realises trills and turns,
588 and could be extended to expand other ornaments such as mordents.
591 @uref{http://@/www@/.nicta@/.com@/.au/@/people/@/chubbp/@/articulate}
596 Its main limitation is that it can only affect things it knows
597 about: anything that is merely textual markup (instead of a note
598 property) is still ignored.