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 Point and click adds links to pdf documents for certain music
34 * Enabling point and click::
35 * Selective point-and-click::
38 @node Enabling point and click
39 @unnumberedsubsec Enabling point and click
41 @cindex point and click
43 Point and click lets you find notes in the input by clicking on them
44 in the PDF viewer. This makes it easier to find input that causes
45 some error in the sheet music.
47 When this functionality is active, LilyPond adds hyperlinks to the PDF
48 file. These hyperlinks are sent to the web-browser, which opens a
49 text-editor with the cursor in the right place.
51 To make this chain work, you should configure your PDF viewer to
52 follow hyperlinks using the @file{lilypond-invoke-editor} script
53 supplied with LilyPond.
55 For Xpdf on UNIX, the following should be present in
56 @file{xpdfrc}. On UNIX, this file is found either in
57 @file{/etc/xpdfrc} or as @file{$HOME/.xpdfrc}.
60 urlCommand "lilypond-invoke-editor %s"
63 The program @file{lilypond-invoke-editor} is a small helper
64 program. It will invoke an editor for the special @code{textedit}
65 URIs, and run a web browser for others. It tests the environment
66 variable @code{EDITOR} for the following patterns,
72 emacsclient --no-wait +@var{line}:@var{column} @var{file}
77 gvim --remote +:@var{line}:norm@var{column} @var{file}
83 nc -noask +@var{line} @var{file}'
87 The environment variable @code{LYEDITOR} is used to override this. It
88 contains the command line to start the editor, where @code{%(file)s},
89 @code{%(column)s}, @code{%(line)s} is replaced with the file, column
90 and line respectively. The setting
93 emacsclient --no-wait +%(line)s:%(column)s %(file)s
97 for @code{LYEDITOR} is equivalent to the standard emacsclient
101 @cindex file size, output
103 The point and click links enlarge the output files significantly. For
104 reducing the size of PDF and PS files, point and click may be switched
112 in a @file{.ly} file. Point and click may be explicitly enabled with
118 Alternately, you may disable point and click with a command-line
122 lilypond -dno-point-and-click file.ly
125 @warning{You should always turn off point and click in any LilyPond
126 files to be distributed to avoid including path information about
127 your computer in the .pdf file, which can pose a security risk.}
129 @node Selective point-and-click
130 @unnumberedsubsec Selective point-and-click
132 For some interactive applications, it may be desirable to only
133 include certain point-and-click items. For example, if somebody
134 wanted to create an application which played audio or video
135 starting from a particular note, it would be awkward if clicking
136 on the note produced the point-and-click location for an
137 accidental or slur which occurred over that note.
139 This may be controlled by indicating which events to include:
143 Hard-coded in the @file{.ly} file:
146 \pointAndClickTypes #'note-event
155 #(ly:set-option 'point-and-click 'note-event)
165 lilypond -dpoint-and-click=note-event example.ly
170 Multiple events can be included:
174 Hard-coded in the @file{.ly} file:
177 \pointAndClickTypes #'(note-event dynamic-event)
186 #(ly:set-option 'point-and-click '(note-event dynamic-event))
197 -e"(ly:set-option 'point-and-click '(note-event dynamic-event))" \
205 @node Text editor support
206 @section Text editor support
211 @cindex modes, editor
212 @cindex syntax coloring
213 @cindex coloring, syntax
215 There is support for different text editors for LilyPond.
224 @unnumberedsubsec Emacs mode
226 Emacs has a @file{lilypond-mode}, which provides keyword
227 autocompletion, indentation, LilyPond specific parenthesis matching
228 and syntax coloring, handy compile short-cuts and reading LilyPond
229 manuals using Info. If @file{lilypond-mode} is not installed on your
232 An Emacs mode for entering music and running LilyPond is contained in
233 the source archive in the @file{elisp} directory. Do @command{make
234 install} to install it to @var{elispdir}. The file @file{lilypond-init.el}
235 should be placed to @var{load-path}@file{/site-start.d/} or appended
236 to your @file{~/.emacs} or @file{~/.emacs.el}.
238 As a user, you may want add your source path (e.g. @file{~/site-lisp/}) to
239 your @var{load-path} by appending the following line (as modified) to your
242 @c any reason we do not advise: (push "~/site-lisp" load-path)
244 (setq load-path (append (list (expand-file-name "~/site-lisp")) load-path))
249 @unnumberedsubsec Vim mode
251 For @uref{http://@/www@/.vim@/.org,Vim}, a filetype plugin, indent
252 mode, and syntax-highlighting mode are available to use with
253 LilyPond. To enable all of these features, create (or modify)
254 your @file{$HOME/.vimrc} to contain these three lines, in order:
258 set runtimepath+=/usr/local/share/lilypond/current/vim/
263 If LilyPond is not installed in the @file{/usr/local/} directory,
264 change the path appropriately. This topic is discussed in
265 @rlearning{Other sources of information}.
269 @unnumberedsubsec Other editors
271 Other editors (both text and graphical) support LilyPond, but
272 their special configuration files are not distributed with
273 LilyPond. Consult their documentation for more information. Such
274 editors are listed in @rweb{Easier editing}.
277 @node Converting from other formats
278 @section Converting from other formats
280 Music can be entered also by importing it from other formats. This
281 chapter documents the tools included in the distribution to do so.
282 There are other tools that produce LilyPond input, for example GUI
283 sequencers and XML converters. Refer to the
284 @uref{http://@/lilypond@/.org,website} for more details.
286 These are separate programs from @command{lilypond} itself, and are
287 run on the command line; see @ref{Command-line usage} for more
288 information. If you have MacOS 10.3 or 10.4 and you have trouble
289 running some of these scripts, e.g. @code{convert-ly}, see
294 We unfortunately do not have the resources to maintain these
295 programs; please consider them @qq{as-is}. Patches are appreciated, but
296 bug reports will almost certainly not be resolved.
299 * Invoking midi2ly:: Importing MIDI.
300 * Invoking musicxml2ly:: Importing MusicXML.
301 * Invoking abc2ly:: Importing ABC.
302 * Invoking etf2ly:: Importing Finale.
308 @node Invoking midi2ly
309 @subsection Invoking @command{midi2ly}
313 @command{midi2ly} translates a Type@tie{}1 MIDI file to a LilyPond source
316 MIDI (Music Instrument Digital Interface) is a standard for digital
317 instruments: it specifies cabling, a serial protocol and a file
318 format. The MIDI file format is a de facto standard format for
319 exporting music from other programs, so this capability may come in
320 useful when importing files from a program that has a converter for a
323 @command{midi2ly} converts tracks into @rinternals{Staff} and
324 channels into @rinternals{Voice} contexts. Relative mode is used
325 for pitches, durations are only written when necessary.
327 It is possible to record a MIDI file using a digital keyboard, and
328 then convert it to @file{.ly}. However, human players are not
329 rhythmically exact enough to make a MIDI to LY conversion trivial.
330 When invoked with quantizing (@option{-s} and @option{-d} options)
331 @command{midi2ly} tries to compensate for these timing errors, but is not
332 very good at this. It is therefore not recommended to use @command{midi2ly}
333 for human-generated midi files.
336 It is invoked from the command-line as follows,
338 midi2ly [@var{option}]@dots{} @var{midi-file}
341 Note that by @q{command-line}, we mean the command line of the
342 operating system. See @ref{Converting from other formats}, for
343 more information about this.
345 The following options are supported by @command{midi2ly}.
348 @item -a, --absolute-pitches
349 Print absolute pitches.
351 @item -d, --duration-quant=@var{DUR}
352 Quantize note durations on @var{DUR}.
354 @item -e, --explicit-durations
355 Print explicit durations.
358 Show summary of usage.
360 @item -k, --key=@var{acc}[:@var{minor}]
361 Set default key. @math{@var{acc} > 0} sets number of sharps;
362 @math{@var{acc} < 0} sets number of flats. A minor key is indicated by
365 @item -o, --output=@var{file}
366 Write output to @var{file}.
368 @item -s, --start-quant=@var{DUR}
369 Quantize note starts on @var{DUR}.
371 @item -t, --allow-tuplet=@var{DUR}*@var{NUM}/@var{DEN}
372 Allow tuplet durations @var{DUR}*@var{NUM}/@var{DEN}.
378 Print version number.
381 Show warranty and copyright.
383 @item -x, --text-lyrics
384 Treat every text as a lyric.
390 Overlapping notes in an arpeggio will not be correctly rendered. The
391 first note will be read and the others will be ignored. Set them all
392 to a single duration and add phrase markings or pedal indicators.
395 @node Invoking musicxml2ly
396 @subsection Invoking @code{musicxml2ly}
400 @uref{http://@/www.@/musicxml@/.org/,MusicXML} is an XML dialect
401 for representing music notation.
403 @command{musicxml2ly} extracts the notes, articulations, score structure,
404 lyrics, etc. from part-wise MusicXML files, and writes them to a @file{.ly}
405 file. It is invoked from the command-line.
408 It is invoked from the command-line as follows,
410 musicxml2ly [@var{option}]@dots{} @var{xml-file}
413 Note that by @q{command-line}, we mean the command line of the
414 operating system. See @ref{Converting from other formats}, for
415 more information about this.
417 If the given filename is @file{-}, @command{musicxml2ly} reads input
418 from the command line.
420 The following options are supported by @command{musicxml2ly}:
424 convert pitches in absolute mode.
427 print usage and option summary.
429 @item -l, --language=LANG
430 use LANG for pitch names, e.g. 'deutsch' for note names in German.
432 @item --loglevel=@var{loglevel}
433 Set the output verbosity to @var{loglevel}. Possible values are @code{NONE},
434 @code{ERROR}, @code{WARNING}, @code{PROGRESS} (default) and @code{DEBUG}.
437 use the lxml.etree Python package for XML-parsing; uses less memory and cpu time.
442 @item -nd --no-articulation-directions
443 do not convert directions (@code{^}, @code{_} or @code{-}) for
444 articulations, dynamics, etc.
447 do not convert beaming information, use LilyPond's automatic
450 @item -o,--output=@var{file}
451 set output filename to @var{file}. If @var{file} is @file{-}, the output
452 will be printed on stdout. If not given, @var{xml-file}@file{.ly} will
456 convert pitches in relative mode (default).
462 print version information.
464 @item -z,--compressed
465 input file is a zip-compressed MusicXML file.
469 @node Invoking abc2ly
470 @subsection Invoking @code{abc2ly}
472 @warning{This program is not supported, and may be remove from
473 future versions of LilyPond.}
477 ABC is a fairly simple ASCII based format. It is described at the ABC site:
480 @uref{http://@/www@/.walshaw@/.plus@/.com/@/abc/@/learn@/.html}.
483 @command{abc2ly} translates from ABC to LilyPond. It is invoked as follows:
486 abc2ly [@var{option}]@dots{} @var{abc-file}
489 The following options are supported by @command{abc2ly}:
492 @item -b,--beams=None
493 preserve ABC's notion of beams
496 @item -o,--output=@var{file}
497 set output filename to @var{file}.
499 be strict about success
501 print version information.
504 There is a rudimentary facility for adding LilyPond code to the ABC
505 source file. If you say:
508 %%LY voices \set autoBeaming = ##f
511 This will cause the text following the keyword @q{voices} to be inserted
512 into the current voice of the LilyPond output file.
517 %%LY slyrics more words
520 will cause the text following the @q{slyrics} keyword to be inserted
521 into the current line of lyrics.
526 The ABC standard is not very @q{standard}. For extended features
527 (e.g., polyphonic music) different conventions exist.
529 Multiple tunes in one file cannot be converted.
531 ABC synchronizes words and notes at the beginning of a line;
532 @command{abc2ly} does not.
534 @command{abc2ly} ignores the ABC beaming.
537 @node Invoking etf2ly
538 @subsection Invoking @command{etf2ly}
540 @warning{This program is not supported, and may be remove from
541 future versions of LilyPond.}
546 @cindex Coda Technology
548 ETF (Enigma Transport Format) is a format used by Coda Music
549 Technology's Finale product. @command{etf2ly} will convert part of an ETF
550 file to a ready-to-use LilyPond file.
552 It is invoked from the command-line as follows.
555 etf2ly [@var{option}]@dots{} @var{etf-file}
558 Note that by @q{command-line}, we mean the command line of the
559 operating system. See @ref{Converting from other formats}, for
560 more information about this.
562 The following options are supported by @command{etf2ly}:
567 @item -o,--output=@var{FILE}
568 set output filename to @var{FILE}
576 The list of articulation scripts is incomplete. Empty measures
577 confuse @command{etf2ly}. Sequences of grace notes are ended improperly.
581 @subsection Other formats
583 @cindex External programs, generating LilyPond files
585 LilyPond itself does not come with support for any other formats,
586 but some external tools can also generate LilyPond files. These
587 are listed in @rweb{Easier editing}.
591 @node LilyPond output in other programs
592 @section LilyPond output in other programs
594 This section shows methods to integrate text and music, different than
595 the automated method with @command{lilypond-book}.
598 * Many quotes from a large score::
599 * Inserting LilyPond output into OpenOffice.org::
600 * Inserting LilyPond output into other programs::
603 @node Many quotes from a large score
604 @unnumberedsubsec Many quotes from a large score
606 If you need to quote many fragments from a large score, you can also use
607 the clip systems feature, see @ruser{Extracting fragments of music}.
610 @node Inserting LilyPond output into OpenOffice.org
611 @unnumberedsubsec Inserting LilyPond output into OpenOffice.org
613 @cindex OpenOffice.org
615 LilyPond notation can be added to OpenOffice.org with
616 @uref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond}.
619 @node Inserting LilyPond output into other programs
620 @unnumberedsubsec Inserting LilyPond output into other programs
622 To insert LilyPond output in other programs, use @code{lilypond}
623 instead of @code{lilypond-book}. Each example must be created
624 individually and added to the document; consult the documentation for
625 that program. Most programs will be able to insert LilyPond output in
626 @file{PNG}, @file{EPS}, or @file{PDF} formats.
628 To reduce the white space around your LilyPond score, use
629 the following options
637 bookTitleMarkup = ##f
638 scoreTitleMarkup = ##f
644 To produce useful image files:
649 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly
653 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts --png myfile.ly
657 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts \
658 -dpixmap-format=pngalpha --png myfile.ly
662 @node Independent includes
663 @section Independent @code{include}s
665 Some people have written large (and useful!) code that can be
666 shared between projects. This code might eventually make its way
667 into LilyPond itself, but until that happens, you must download
668 and @code{\include} them manually.
672 * MIDI articulation::
676 @node MIDI articulation
677 @subsection MIDI articulation
679 LilyPond can be used to produce MIDI output, for
680 @qq{proof-hearing} what has been written. However, only dynamics,
681 explicit tempo markings, and the notes and durations themselves
682 are produced in the output.
684 The @emph{articulate} project is one attempt to get more of the
685 information in the score into MIDI. It works by shortening
686 notes not under slurs, to @q{articulate} the notes. The amount of
687 shortening depends on any articulation markings attached to a
688 note: staccato halves the note value, tenuto gives a note its full
689 duration, and so on. The script also realises trills and turns,
690 and could be extended to expand other ornaments such as mordents.
693 @uref{http://@/www@/.nicta@/.com@/.au/@/people/@/chubbp/@/articulate}
698 Its main limitation is that it can only affect things it knows
699 about: anything that is merely textual markup (instead of a note
700 property) is still ignored.