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 some
34 error in the sheet music.
37 * Configuring the system for point and click::
38 * Enabling point and click::
39 * Selective point-and-click::
43 @node Configuring the system for point and click
44 @subsection Configuring the system
46 When this functionality is active, LilyPond adds hyperlinks to PDF and
47 SVG files. These hyperlinks are sent to a @q{URI helper} or a
48 web-browser, which opens a text-editor with the cursor in the right
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 The program @file{lilypond-invoke-editor} is a small helper
56 program. It will invoke an editor for the special @code{textedit}
57 URIs, and run a web browser for others. It tests the environment
58 variable @code{EDITOR} for the following patterns,
64 emacsclient --no-wait +@var{line}:@var{column} @var{file}
69 gvim --remote +:@var{line}:norm@var{column} @var{file}
75 nc -noask +@var{line} @var{file}'
79 The environment variable @code{LYEDITOR} is used to override this. It
80 contains the command line to start the editor, where @code{%(file)s},
81 @code{%(column)s}, @code{%(line)s} is replaced with the file, column
82 and line respectively. The setting
85 emacsclient --no-wait +%(line)s:%(column)s %(file)s
89 for @code{LYEDITOR} is equivalent to the standard emacsclient
93 * Using Xpdf for point and click::
94 * Using GNOME 2 for point and click::
95 * Using GNOME 3 for point and click::
96 * Extra configuration for Evince::
100 @node Using Xpdf for point and click
101 @unnumberedsubsubsec Using Xpdf
105 For Xpdf on UNIX, the following should be present in
106 @file{xpdfrc}. On UNIX, this file is found either in
107 @file{/etc/xpdfrc} or as @file{$HOME/.xpdfrc}.
110 urlCommand "lilypond-invoke-editor %s"
113 If you are using Ubuntu, it is likely that the version of Xpdf
114 installed with your system crashes on every PDF file: this state
115 has been persisting for several years and is due to library
116 mismatches. Your best bet is to install a current @samp{xpdf}
117 package and the corresponding @samp{libpoppler} package from
118 Debian instead. Once you have tested that this works, you might
122 sudo apt-mark hold xpdf
126 in order to keep Ubuntu from overwriting it with the next
127 @q{update} of its crashing package.
130 @node Using GNOME 2 for point and click
131 @unnumberedsubsubsec Using GNOME 2
133 For using GNOME 2 (and PDF viewers integrated with it), the magic
134 invocation for telling the system about the @samp{textedit:} URI
138 gconftool-2 -t string -s /desktop/gnome/url-handlers/textedit/command "lilypond-invoke-editor %s"
139 gconftool-2 -s /desktop/gnome/url-handlers/textedit/needs_terminal false -t bool
140 gconftool-2 -t bool -s /desktop/gnome/url-handlers/textedit/enabled true
143 After that invocation;
146 gnome-open textedit:///etc/issue:1:0:0
150 should call @file{lilypond-invoke-editor} for opening files.
153 @node Using GNOME 3 for point and click
154 @unnumberedsubsubsec Using GNOME 3
156 In GNOME 3, URIs are handled by the @q{gvfs} layer rather than by
157 @q{gconf}. Create a file in a local directory such as @file{/tmp}
158 that is called @file{lilypond-invoke-editor.desktop} and has the
164 Name=lilypond-invoke-editor
165 GenericName=Textedit URI handler
166 Comment=URI handler for textedit:
167 Exec=lilypond-invoke-editor %u
170 MimeType=x-scheme-handler/textedit;
174 and then execute the commands
176 xdg-desktop-menu install ./lilypond-invoke-editor.desktop
177 xdg-mime default lilypond-invoke-editor.desktop x-scheme-handler/textedit
180 After that invocation;
183 gnome-open textedit:///etc/issue:1:0:0
186 should call @file{lilypond-invoke-editor} for opening files.
189 @node Extra configuration for Evince
190 @unnumberedsubsubsec Extra configuration for Evince
194 If @code{gnome-open} works, but Evince still refuses to open point
195 and click links due to denied permissions, you might need to
196 change the Apparmor profile of Evince which controls the kind of
197 actions Evince is allowed to perform.
199 For Ubuntu, the process is to edit the file
200 @file{/etc/apparmor.d/local/usr.bin.evince} and append the
205 /usr/local/bin/lilypond-invoke-editor Cx -> sanitized_helper,
209 After adding these lines, call
212 sudo apparmor_parser -r -T -W /etc/apparmor.d/usr.bin.evince
216 Now Evince should be able to open point and click links. It is
217 likely that similar configurations will work for other viewers.
220 @node Enabling point and click
221 @unnumberedsubsec Enabling point and click
222 @cindex file size, output
224 Point and click functionality is enabled by default when creating
227 The point and click links enlarge the output files significantly. For
228 reducing the size of these (and PS) files, point and click may
229 be switched off by issuing
236 in a @file{.ly} file. Point and click may be explicitly enabled with
242 Alternately, you may disable point and click with a command-line
246 lilypond -dno-point-and-click file.ly
249 @warning{You should always turn off point and click in any LilyPond
250 files to be distributed to avoid including path information about
251 your computer in the PDF file, which can pose a security risk.}
254 @node Selective point-and-click
255 @unnumberedsubsec Selective point-and-click
257 For some interactive applications, it may be desirable to only
258 include certain point-and-click items. For example, if somebody
259 wanted to create an application which played audio or video
260 starting from a particular note, it would be awkward if clicking
261 on the note produced the point-and-click location for an
262 accidental or slur which occurred over that note.
264 This may be controlled by indicating which events to include:
268 Hard-coded in the @file{.ly} file:
271 \pointAndClickTypes #'note-event
280 #(ly:set-option 'point-and-click 'note-event)
290 lilypond -dpoint-and-click=note-event example.ly
295 Multiple events can be included:
299 Hard-coded in the @file{.ly} file:
302 \pointAndClickTypes #'(note-event dynamic-event)
311 #(ly:set-option 'point-and-click '(note-event dynamic-event))
322 -e"(ly:set-option 'point-and-click '(note-event dynamic-event))" \
329 @node Text editor support
330 @section Text editor support
335 @cindex modes, editor
336 @cindex syntax coloring
337 @cindex coloring, syntax
339 There is support for different text editors for LilyPond.
349 @unnumberedsubsec Emacs mode
351 Emacs has a @file{lilypond-mode}, which provides keyword
352 autocompletion, indentation, LilyPond specific parenthesis matching
353 and syntax coloring, handy compile short-cuts and reading LilyPond
354 manuals using Info. If @file{lilypond-mode} is not installed on your
357 An Emacs mode for entering music and running LilyPond is contained in
358 the source archive in the @file{elisp} directory. Do @command{make
359 install} to install it to @var{elispdir}. The file @file{lilypond-init.el}
360 should be placed to @var{load-path}@file{/site-start.d/} or appended
361 to your @file{~/.emacs} or @file{~/.emacs.el}.
363 As a user, you may want add your source path (e.g. @file{~/site-lisp/}) to
364 your @var{load-path} by appending the following line (as modified) to your
367 @c any reason we do not advise: (push "~/site-lisp" load-path)
369 (setq load-path (append (list (expand-file-name "~/site-lisp")) load-path))
374 @unnumberedsubsec Vim mode
376 For @uref{http://@/www@/.vim@/.org,Vim}, a filetype plugin, indent
377 mode, and syntax-highlighting mode are available to use with
378 LilyPond. To enable all of these features, create (or modify)
379 your @file{$HOME/.vimrc} to contain these three lines, in order:
383 set runtimepath+=/usr/local/share/lilypond/current/vim/
389 If LilyPond is not installed in the @file{/usr/local/} directory,
390 change the path appropriately. This topic is discussed in
391 @rlearning{Other sources of information}.
395 @unnumberedsubsec Other editors
397 Other editors (both text and graphical) support LilyPond, but
398 their special configuration files are not distributed with
399 LilyPond. Consult their documentation for more information. Such
400 editors are listed in @rweb{Easier editing}.
403 @node Converting from other formats
404 @section Converting from other formats
406 Music can be entered also by importing it from other formats. This
407 chapter documents the tools included in the distribution to do so.
408 There are other tools that produce LilyPond input, for example GUI
409 sequencers and XML converters. Refer to the
410 @uref{http://@/lilypond@/.org,website} for more details.
412 These are separate programs from @command{lilypond} itself, and are
413 run on the command line; see @ref{Command-line usage} for more
414 information. If you have MacOS 10.3 or 10.4 and you have trouble
415 running some of these scripts, e.g. @code{convert-ly}, see
419 We unfortunately do not have the resources to maintain these
420 programs; please consider them @qq{as-is}. Patches are appreciated, but
421 bug reports will almost certainly not be resolved.
424 * Invoking midi2ly:: Importing MIDI.
425 * Invoking musicxml2ly:: Importing MusicXML.
426 * Invoking abc2ly:: Importing ABC.
427 * Invoking etf2ly:: Importing Finale.
432 @node Invoking midi2ly
433 @subsection Invoking @command{midi2ly}
437 @command{midi2ly} translates a Type@tie{}1 MIDI file to a LilyPond
440 MIDI (Music Instrument Digital Interface) is a standard for digital
441 instruments: it specifies cabling, a serial protocol and a file
442 format. The MIDI file format is a de facto standard format for
443 exporting music from other programs, so this capability may come in
444 useful when importing files from a program that has a converter for a
447 @command{midi2ly} converts tracks into @rinternals{Staff} and
448 channels into @rinternals{Voice} contexts. Relative mode is used
449 for pitches, durations are only written when necessary.
451 It is possible to record a MIDI file using a digital keyboard, and
452 then convert it to @file{.ly}. However, human players are not
453 rhythmically exact enough to make a MIDI to LY conversion trivial.
454 When invoked with quantizing (@option{-s} and @option{-d} options)
455 @command{midi2ly} tries to compensate for these timing errors, but is
456 not very good at this. It is therefore not recommended to use
457 @command{midi2ly} for human-generated midi files.
459 It is invoked from the command-line as follows,
462 midi2ly [@var{option}]@dots{} @var{midi-file}
465 Note that by @q{command-line}, we mean the command line of the
466 operating system. See @ref{Converting from other formats}, for
467 more information about this.
469 The following options are supported by @command{midi2ly}.
472 @item -a, --absolute-pitches
473 Print absolute pitches.
475 @item -d, --duration-quant=@var{DUR}
476 Quantize note durations on @var{DUR}.
478 @item -e, --explicit-durations
479 Print explicit durations.
482 Show summary of usage.
484 @item -k, --key=@var{acc}[:@var{minor}]
485 Set default key. @math{@var{acc} > 0} sets number of sharps;
486 @math{@var{acc} < 0} sets number of flats. A minor key is indicated by
489 @item -o, --output=@var{file}
490 Write output to @var{file}.
492 @item -s, --start-quant=@var{DUR}
493 Quantize note starts on @var{DUR}.
495 @item -t, --allow-tuplet=@var{DUR}*@var{NUM}/@var{DEN}
496 Allow tuplet durations @var{DUR}*@var{NUM}/@var{DEN}.
502 Print version number.
505 Show warranty and copyright.
507 @item -x, --text-lyrics
508 Treat every text as a lyric.
512 Overlapping notes in an arpeggio will not be correctly rendered. The
513 first note will be read and the others will be ignored. Set them all
514 to a single duration and add phrase markings or pedal indicators.
517 @node Invoking musicxml2ly
518 @subsection Invoking @code{musicxml2ly}
522 @uref{http://@/www.@/musicxml@/.org/,MusicXML} is an XML dialect
523 for representing music notation.
525 @command{musicxml2ly} extracts the notes, articulations, score structure,
526 lyrics, etc. from part-wise MusicXML files, and writes them to a @file{.ly}
527 file and is invoked from the command-line as follows;
530 musicxml2ly [@var{option}]@dots{} @var{xml-file}
533 Note that by @q{command-line}, we mean the command line of the
534 operating system. See @ref{Converting from other formats}, for
535 more information about this.
537 If the given filename is @file{-}, @command{musicxml2ly} reads input
538 from the command line.
540 The following options are supported by @command{musicxml2ly}:
544 convert pitches in absolute mode.
547 print usage and option summary.
549 @item -l, --language=LANG
550 use LANG for pitch names, e.g. 'deutsch' for note names in German.
552 @item --loglevel=@var{loglevel}
553 Set the output verbosity to @var{loglevel}. Possible values are
554 @code{NONE}, @code{ERROR}, @code{WARNING}, @code{PROGRESS} (default) and
558 use the lxml.etree Python package for XML-parsing; uses less memory and
564 @item -nd, --no-articulation-directions
565 do not convert directions (@code{^}, @code{_} or @code{-}) for
566 articulations, dynamics, etc.
569 do not convert beaming information, use LilyPond's automatic
572 @item -o, --output=@var{file}
573 set output filename to @var{file}. If @var{file} is @file{-}, the
574 output will be printed on stdout. If not given,
575 @var{xml-file}@file{.ly} will be used.
578 convert pitches in relative mode (default).
584 print version information.
586 @item -z, --compressed
587 input file is a zip-compressed MusicXML file.
591 @node Invoking abc2ly
592 @subsection Invoking @code{abc2ly}
594 @warning{This is not currently supported and may eventually be removed
595 from future versions of LilyPond.}
599 ABC is a fairly simple ASCII based format. It is described at the ABC
603 @uref{http://@/www@/.walshaw@/.plus@/.com/@/abc/@/learn@/.html}.
606 @command{abc2ly} translates from ABC to LilyPond. It is invoked as
610 abc2ly [@var{option}]@dots{} @var{abc-file}
613 The following options are supported by @command{abc2ly}:
616 @item -b, --beams=None
617 preserve ABC's notion of beams
620 @item -o, --output=@var{file}
621 set output filename to @var{file}.
623 be strict about success
625 print version information.
628 There is a rudimentary facility for adding LilyPond code to the ABC
629 source file. For example;
632 %%LY voices \set autoBeaming = ##f
635 This will cause the text following the keyword @q{voices} to be inserted
636 into the current voice of the LilyPond output file.
641 %%LY slyrics more words
644 will cause the text following the @q{slyrics} keyword to be inserted
645 into the current line of lyrics.
648 The ABC standard is not very @q{standard}. For extended features
649 (e.g., polyphonic music) different conventions exist.
651 Multiple tunes in one file cannot be converted.
653 ABC synchronizes words and notes at the beginning of a line;
654 @command{abc2ly} does not.
656 @command{abc2ly} ignores the ABC beaming.
659 @node Invoking etf2ly
660 @subsection Invoking @command{etf2ly}
662 @warning{This is not currently supported and may eventually be removed
663 from future versions of LilyPond.}
665 @cindex Enigma Transport Format
669 @cindex Coda Technology
671 ETF (Enigma Transport Format) is a format used by Coda Music
672 Technology's Finale product. @command{etf2ly} will convert part of an
673 ETF file to a ready-to-use LilyPond file.
675 It is invoked from the command-line as follows;
678 etf2ly [@var{option}]@dots{} @var{etf-file}
681 Note that by @q{command-line}, we mean the command line of the
682 operating system. See @ref{Converting from other formats}, for
683 more information about this.
685 The following options are supported by @command{etf2ly}:
690 @item -o, --output=@var{FILE}
691 set output filename to @var{FILE}
697 The list of articulation scripts is incomplete. Empty measures
698 confuse @command{etf2ly}. Sequences of grace notes are ended
703 @subsection Other formats
705 @cindex External programs, generating LilyPond files
707 LilyPond itself does not come with support for any other formats,
708 but some external tools can also generate LilyPond files. These
709 are listed in @rweb{Easier editing}.
712 @node LilyPond output in other programs
713 @section LilyPond output in other programs
715 This section shows methods to integrate text and music, different than
716 the automated method with @command{lilypond-book}.
720 * OpenOffice and LibreOffice::
731 As well as @code{lilypond-book} to integrate LilyPond output,
732 there is an alternative program that can be used when using LuaTex
734 @uref{https://github.com/jperon/lyluatex/blob/master/README.en.md,lyluatex}.
737 @node OpenOffice and LibreOffice
738 @subsection OpenOffice and LibreOffice
740 @cindex OpenOffice.org
741 @cindex LibreOffice.org
744 LilyPond notation can be added to OpenOffice.org and LibreOffice with
745 @uref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond}, an
746 OpenOffice.org extension that converts LilyPond files into images within
747 OpenOffice.org documents. Although this is no longer being developed,
748 it appears to still work with version 4.
752 @subsection Other programs
754 Other programs that can handle @file{PNG}, @file{EPS}, or @file{PDF}
755 formats should use @code{lilypond} instead of @code{lilypond-book}.
756 Each LilyPond output file must be created and inserted separately.
757 Consult the program's own documentation on how to insert files from
760 To help reduce the white space around your LilyPond score, use the
769 bookTitleMarkup = ##f
770 scoreTitleMarkup = ##f
773 @var{@dots{} music @dots{}}
777 To produce @file{EPS} images;
780 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly
784 To produce @file{PNG} images;
787 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts --png myfile.ly
791 For transparent @file{PNG} images
794 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts -dpixmap-format=pngalpha --png myfile.ly
797 @cindex fragments, music
798 @cindex quoting, music fragments
799 @cindex music fragments, quoting
801 If you need to quote many fragments from a large score, you can also use
802 the clip systems feature, see @ruser{Extracting fragments of music}.
805 @node Independent includes
806 @section Independent @code{include}s
808 Some users have produced files that can be @code{\include}d with
809 LilyPond to produce certain effects and those listed below are part of
810 the LilyPond distribution. Also see @ruser{Working with input files}.
813 * MIDI articulation::
817 @node MIDI articulation
818 @subsection MIDI articulation
821 @cindex Articulate project
823 The @uref{http://www.nicta.com.au/articulate,Articulate} project is an
824 attempt to enhance LilyPond's MIDI output and works by adjusting note
825 lengths (that are not under slurs) according to the articulation
826 markings attached to them. For example, a @q{staccato} halves the note
827 value, @q{tenuto} gives a note its full duration and so on. See
828 @ruser{Enhancing MIDI output}.