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
29 @cindex point and click
31 Point and click lets you find notes in the input by clicking on them
32 in the PDF viewer. This makes it easier to find input that causes
33 some error in the sheet music.
36 * Configuring the system for point and click::
37 * Enabling point and click::
38 * Selective point-and-click::
41 @node Configuring the system for point and click
42 @subsection Configuring the system
44 When this functionality is active, LilyPond adds hyperlinks to the
45 PDF file. These hyperlinks are sent to a @q{URI helper} or a
46 web-browser, which opens a text-editor with the cursor in the
49 To make this chain work, you should configure your PDF viewer to
50 follow hyperlinks using the @file{lilypond-invoke-editor} script
51 supplied with LilyPond.
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
92 * Using Xpdf for point and click::
93 * Using GNOME 2 for point and click::
94 * Using GNOME 3 for point and click::
95 * Extra configuration for Evince::
98 @node Using Xpdf for point and click
99 @unnumberedsubsubsec Using Xpdf
102 For Xpdf on UNIX, the following should be present in
103 @file{xpdfrc}. On UNIX, this file is found either in
104 @file{/etc/xpdfrc} or as @file{$HOME/.xpdfrc}.
107 urlCommand "lilypond-invoke-editor %s"
110 If you are using Ubuntu, it is likely that the version of Xpdf
111 installed with your system crashes on every PDF file: this state
112 has been persisting for several years and is due to library
113 mismatches. Your best bet is to install a current @samp{xpdf}
114 package and the corresponding @samp{libpoppler} package from
115 Debian instead. Once you have tested that this works, you might
118 sudo apt-mark hold xpdf
121 in order to keep Ubuntu from overwriting it with the next
122 @q{update} of its crashing package.
124 @node Using GNOME 2 for point and click
125 @unnumberedsubsubsec Using GNOME 2
127 For using GNOME 2 (and PDF viewers integrated with it), the magic
128 invocation for telling the system about the @samp{textedit:} URI
131 gconftool-2 -t string -s /desktop/gnome/url-handlers/textedit/command "lilypond-invoke-editor %s"
132 gconftool-2 -s /desktop/gnome/url-handlers/textedit/needs_terminal false -t bool
133 gconftool-2 -t bool -s /desktop/gnome/url-handlers/textedit/enabled true
136 After that invocation,
138 gnome-open textedit:///etc/issue:1:0:0
141 should call @file{lilypond-invoke-editor} for opening files.
143 @node Using GNOME 3 for point and click
144 @unnumberedsubsubsec Using GNOME 3
146 In GNOME 3, URIs are handled by the @q{gvfs} layer rather than by
147 @q{gconf}. Create a file in a local directory such as @file{/tmp}
148 that is called @file{lilypond-invoke-editor.desktop} and has the contents
152 Name=lilypond-invoke-editor
153 GenericName=Textedit URI handler
154 Comment=URI handler for textedit:
155 Exec=lilypond-invoke-editor %u
158 MimeType=x-scheme-handler/textedit;
162 and then execute the commands
164 xdg-desktop-menu install ./lilypond-invoke-editor.desktop
165 xdg-mime default lilypond-invoke-editor.desktop x-scheme-handler/textedit
168 After that invocation,
170 gnome-open textedit:///etc/issue:1:0:0
173 should call @file{lilypond-invoke-editor} for opening files.
175 @node Extra configuration for Evince
176 @unnumberedsubsubsec Extra configuration for Evince
179 If @code{gnome-open} works, but Evince still refuses to open point
180 and click links due to denied permissions, you might need to
181 change the Apparmor profile of Evince which controls the kind of
182 actions Evince is allowed to perform.
184 For Ubuntu, the process is to edit the file
185 @file{/etc/apparmor.d/local/usr.bin.evince} and append the
189 /usr/local/bin/lilypond-invoke-editor Cx -> sanitized_helper,
193 After adding these lines, call
196 sudo apparmor_parser -r -T -W /etc/apparmor.d/usr.bin.evince
200 Now Evince should be able to open point and click links. It is
201 likely that similar configurations will work for other viewers.
203 @node Enabling point and click
204 @unnumberedsubsec Enabling point and click
205 @cindex file size, output
207 Point and click functionality is enabled by default when creating
210 The point and click links enlarge the output files significantly. For
211 reducing the size of PDF and PS files, point and click may be switched
219 in a @file{.ly} file. Point and click may be explicitly enabled with
225 Alternately, you may disable point and click with a command-line
229 lilypond -dno-point-and-click file.ly
232 @warning{You should always turn off point and click in any LilyPond
233 files to be distributed to avoid including path information about
234 your computer in the .pdf file, which can pose a security risk.}
236 @node Selective point-and-click
237 @unnumberedsubsec Selective point-and-click
239 For some interactive applications, it may be desirable to only
240 include certain point-and-click items. For example, if somebody
241 wanted to create an application which played audio or video
242 starting from a particular note, it would be awkward if clicking
243 on the note produced the point-and-click location for an
244 accidental or slur which occurred over that note.
246 This may be controlled by indicating which events to include:
250 Hard-coded in the @file{.ly} file:
253 \pointAndClickTypes #'note-event
262 #(ly:set-option 'point-and-click 'note-event)
272 lilypond -dpoint-and-click=note-event example.ly
277 Multiple events can be included:
281 Hard-coded in the @file{.ly} file:
284 \pointAndClickTypes #'(note-event dynamic-event)
293 #(ly:set-option 'point-and-click '(note-event dynamic-event))
304 -e"(ly:set-option 'point-and-click '(note-event dynamic-event))" \
312 @node Text editor support
313 @section Text editor support
318 @cindex modes, editor
319 @cindex syntax coloring
320 @cindex coloring, syntax
322 There is support for different text editors for LilyPond.
331 @unnumberedsubsec Emacs mode
333 Emacs has a @file{lilypond-mode}, which provides keyword
334 autocompletion, indentation, LilyPond specific parenthesis matching
335 and syntax coloring, handy compile short-cuts and reading LilyPond
336 manuals using Info. If @file{lilypond-mode} is not installed on your
339 An Emacs mode for entering music and running LilyPond is contained in
340 the source archive in the @file{elisp} directory. Do @command{make
341 install} to install it to @var{elispdir}. The file @file{lilypond-init.el}
342 should be placed to @var{load-path}@file{/site-start.d/} or appended
343 to your @file{~/.emacs} or @file{~/.emacs.el}.
345 As a user, you may want add your source path (e.g. @file{~/site-lisp/}) to
346 your @var{load-path} by appending the following line (as modified) to your
349 @c any reason we do not advise: (push "~/site-lisp" load-path)
351 (setq load-path (append (list (expand-file-name "~/site-lisp")) load-path))
356 @unnumberedsubsec Vim mode
358 For @uref{http://@/www@/.vim@/.org,Vim}, a filetype plugin, indent
359 mode, and syntax-highlighting mode are available to use with
360 LilyPond. To enable all of these features, create (or modify)
361 your @file{$HOME/.vimrc} to contain these three lines, in order:
365 set runtimepath+=/usr/local/share/lilypond/current/vim/
370 If LilyPond is not installed in the @file{/usr/local/} directory,
371 change the path appropriately. This topic is discussed in
372 @rlearning{Other sources of information}.
376 @unnumberedsubsec Other editors
378 Other editors (both text and graphical) support LilyPond, but
379 their special configuration files are not distributed with
380 LilyPond. Consult their documentation for more information. Such
381 editors are listed in @rweb{Easier editing}.
384 @node Converting from other formats
385 @section Converting from other formats
387 Music can be entered also by importing it from other formats. This
388 chapter documents the tools included in the distribution to do so.
389 There are other tools that produce LilyPond input, for example GUI
390 sequencers and XML converters. Refer to the
391 @uref{http://@/lilypond@/.org,website} for more details.
393 These are separate programs from @command{lilypond} itself, and are
394 run on the command line; see @ref{Command-line usage} for more
395 information. If you have MacOS 10.3 or 10.4 and you have trouble
396 running some of these scripts, e.g. @code{convert-ly}, see
401 We unfortunately do not have the resources to maintain these
402 programs; please consider them @qq{as-is}. Patches are appreciated, but
403 bug reports will almost certainly not be resolved.
406 * Invoking midi2ly:: Importing MIDI.
407 * Invoking musicxml2ly:: Importing MusicXML.
408 * Invoking abc2ly:: Importing ABC.
409 * Invoking etf2ly:: Importing Finale.
415 @node Invoking midi2ly
416 @subsection Invoking @command{midi2ly}
420 @command{midi2ly} translates a Type@tie{}1 MIDI file to a LilyPond source
423 MIDI (Music Instrument Digital Interface) is a standard for digital
424 instruments: it specifies cabling, a serial protocol and a file
425 format. The MIDI file format is a de facto standard format for
426 exporting music from other programs, so this capability may come in
427 useful when importing files from a program that has a converter for a
430 @command{midi2ly} converts tracks into @rinternals{Staff} and
431 channels into @rinternals{Voice} contexts. Relative mode is used
432 for pitches, durations are only written when necessary.
434 It is possible to record a MIDI file using a digital keyboard, and
435 then convert it to @file{.ly}. However, human players are not
436 rhythmically exact enough to make a MIDI to LY conversion trivial.
437 When invoked with quantizing (@option{-s} and @option{-d} options)
438 @command{midi2ly} tries to compensate for these timing errors, but is not
439 very good at this. It is therefore not recommended to use @command{midi2ly}
440 for human-generated midi files.
443 It is invoked from the command-line as follows,
445 midi2ly [@var{option}]@dots{} @var{midi-file}
448 Note that by @q{command-line}, we mean the command line of the
449 operating system. See @ref{Converting from other formats}, for
450 more information about this.
452 The following options are supported by @command{midi2ly}.
455 @item -a, --absolute-pitches
456 Print absolute pitches.
458 @item -d, --duration-quant=@var{DUR}
459 Quantize note durations on @var{DUR}.
461 @item -e, --explicit-durations
462 Print explicit durations.
465 Show summary of usage.
467 @item -k, --key=@var{acc}[:@var{minor}]
468 Set default key. @math{@var{acc} > 0} sets number of sharps;
469 @math{@var{acc} < 0} sets number of flats. A minor key is indicated by
472 @item -o, --output=@var{file}
473 Write output to @var{file}.
475 @item -s, --start-quant=@var{DUR}
476 Quantize note starts on @var{DUR}.
478 @item -t, --allow-tuplet=@var{DUR}*@var{NUM}/@var{DEN}
479 Allow tuplet durations @var{DUR}*@var{NUM}/@var{DEN}.
485 Print version number.
488 Show warranty and copyright.
490 @item -x, --text-lyrics
491 Treat every text as a lyric.
497 Overlapping notes in an arpeggio will not be correctly rendered. The
498 first note will be read and the others will be ignored. Set them all
499 to a single duration and add phrase markings or pedal indicators.
502 @node Invoking musicxml2ly
503 @subsection Invoking @code{musicxml2ly}
507 @uref{http://@/www.@/musicxml@/.org/,MusicXML} is an XML dialect
508 for representing music notation.
510 @command{musicxml2ly} extracts the notes, articulations, score structure,
511 lyrics, etc. from part-wise MusicXML files, and writes them to a @file{.ly}
512 file. It is invoked from the command-line.
515 It is invoked from the command-line as follows,
517 musicxml2ly [@var{option}]@dots{} @var{xml-file}
520 Note that by @q{command-line}, we mean the command line of the
521 operating system. See @ref{Converting from other formats}, for
522 more information about this.
524 If the given filename is @file{-}, @command{musicxml2ly} reads input
525 from the command line.
527 The following options are supported by @command{musicxml2ly}:
531 convert pitches in absolute mode.
534 print usage and option summary.
536 @item -l, --language=LANG
537 use LANG for pitch names, e.g. 'deutsch' for note names in German.
539 @item --loglevel=@var{loglevel}
540 Set the output verbosity to @var{loglevel}. Possible values are @code{NONE},
541 @code{ERROR}, @code{WARNING}, @code{PROGRESS} (default) and @code{DEBUG}.
544 use the lxml.etree Python package for XML-parsing; uses less memory and cpu time.
549 @item -nd, --no-articulation-directions
550 do not convert directions (@code{^}, @code{_} or @code{-}) for
551 articulations, dynamics, etc.
554 do not convert beaming information, use LilyPond's automatic
557 @item -o, --output=@var{file}
558 set output filename to @var{file}. If @var{file} is @file{-}, the output
559 will be printed on stdout. If not given, @var{xml-file}@file{.ly} will
563 convert pitches in relative mode (default).
569 print version information.
571 @item -z, --compressed
572 input file is a zip-compressed MusicXML file.
576 @node Invoking abc2ly
577 @subsection Invoking @code{abc2ly}
579 @warning{This program is not supported, and may be remove from
580 future versions of LilyPond.}
584 ABC is a fairly simple ASCII based format. It is described at the ABC site:
587 @uref{http://@/www@/.walshaw@/.plus@/.com/@/abc/@/learn@/.html}.
590 @command{abc2ly} translates from ABC to LilyPond. It is invoked as follows:
593 abc2ly [@var{option}]@dots{} @var{abc-file}
596 The following options are supported by @command{abc2ly}:
599 @item -b, --beams=None
600 preserve ABC's notion of beams
603 @item -o, --output=@var{file}
604 set output filename to @var{file}.
606 be strict about success
608 print version information.
611 There is a rudimentary facility for adding LilyPond code to the ABC
612 source file. If you say:
615 %%LY voices \set autoBeaming = ##f
618 This will cause the text following the keyword @q{voices} to be inserted
619 into the current voice of the LilyPond output file.
624 %%LY slyrics more words
627 will cause the text following the @q{slyrics} keyword to be inserted
628 into the current line of lyrics.
633 The ABC standard is not very @q{standard}. For extended features
634 (e.g., polyphonic music) different conventions exist.
636 Multiple tunes in one file cannot be converted.
638 ABC synchronizes words and notes at the beginning of a line;
639 @command{abc2ly} does not.
641 @command{abc2ly} ignores the ABC beaming.
644 @node Invoking etf2ly
645 @subsection Invoking @command{etf2ly}
647 @warning{This program is not supported, and may be remove from
648 future versions of LilyPond.}
653 @cindex Coda Technology
655 ETF (Enigma Transport Format) is a format used by Coda Music
656 Technology's Finale product. @command{etf2ly} will convert part of an ETF
657 file to a ready-to-use LilyPond file.
659 It is invoked from the command-line as follows.
662 etf2ly [@var{option}]@dots{} @var{etf-file}
665 Note that by @q{command-line}, we mean the command line of the
666 operating system. See @ref{Converting from other formats}, for
667 more information about this.
669 The following options are supported by @command{etf2ly}:
674 @item -o, --output=@var{FILE}
675 set output filename to @var{FILE}
683 The list of articulation scripts is incomplete. Empty measures
684 confuse @command{etf2ly}. Sequences of grace notes are ended improperly.
688 @subsection Other formats
690 @cindex External programs, generating LilyPond files
692 LilyPond itself does not come with support for any other formats,
693 but some external tools can also generate LilyPond files. These
694 are listed in @rweb{Easier editing}.
698 @node LilyPond output in other programs
699 @section LilyPond output in other programs
701 This section shows methods to integrate text and music, different than
702 the automated method with @command{lilypond-book}.
705 * Many quotes from a large score::
706 * Inserting LilyPond output into OpenOffice.org::
707 * Inserting LilyPond output into other programs::
710 @node Many quotes from a large score
711 @unnumberedsubsec Many quotes from a large score
713 If you need to quote many fragments from a large score, you can also use
714 the clip systems feature, see @ruser{Extracting fragments of music}.
717 @node Inserting LilyPond output into OpenOffice.org
718 @unnumberedsubsec Inserting LilyPond output into OpenOffice.org
720 @cindex OpenOffice.org
722 LilyPond notation can be added to OpenOffice.org with
723 @uref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond}.
726 @node Inserting LilyPond output into other programs
727 @unnumberedsubsec Inserting LilyPond output into other programs
729 To insert LilyPond output in other programs, use @code{lilypond}
730 instead of @code{lilypond-book}. Each example must be created
731 individually and added to the document; consult the documentation for
732 that program. Most programs will be able to insert LilyPond output in
733 @file{PNG}, @file{EPS}, or @file{PDF} formats.
735 To reduce the white space around your LilyPond score, use
736 the following options
744 bookTitleMarkup = ##f
745 scoreTitleMarkup = ##f
751 To produce useful image files:
756 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly
760 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts --png myfile.ly
764 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts \
765 -dpixmap-format=pngalpha --png myfile.ly
769 @node Independent includes
770 @section Independent @code{include}s
772 Some people have written large (and useful!) code that can be
773 shared between projects. This code might eventually make its way
774 into LilyPond itself, but until that happens, you must download
775 and @code{\include} them manually.
779 * MIDI articulation::
783 @node MIDI articulation
784 @subsection MIDI articulation
786 LilyPond can be used to produce MIDI output, for
787 @qq{proof-hearing} what has been written. However, only dynamics,
788 explicit tempo markings, and the notes and durations themselves
789 are produced in the output.
791 The @emph{articulate} project is one attempt to get more of the
792 information in the score into MIDI. It works by shortening
793 notes not under slurs, to @q{articulate} the notes. The amount of
794 shortening depends on any articulation markings attached to a
795 note: staccato halves the note value, tenuto gives a note its full
796 duration, and so on. The script also realises trills and turns,
797 and could be extended to expand other ornaments such as mordents.
800 @uref{http://@/www@/.nicta@/.com@/.au/@/people/@/chubbp/@/articulate}
805 Its main limitation is that it can only affect things it knows
806 about: anything that is merely textual markup (instead of a note
807 property) is still ignored.