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 some
33 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 PDF and
45 SVG files. These hyperlinks are sent to a @q{URI helper} or a
46 web-browser, which opens a text-editor with the cursor in the right
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 these (and PS) files, point and click may
212 be switched off by issuing
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/
371 If LilyPond is not installed in the @file{/usr/local/} directory,
372 change the path appropriately. This topic is discussed in
373 @rlearning{Other sources of information}.
377 @unnumberedsubsec Other editors
379 Other editors (both text and graphical) support LilyPond, but
380 their special configuration files are not distributed with
381 LilyPond. Consult their documentation for more information. Such
382 editors are listed in @rweb{Easier editing}.
385 @node Converting from other formats
386 @section Converting from other formats
388 Music can be entered also by importing it from other formats. This
389 chapter documents the tools included in the distribution to do so.
390 There are other tools that produce LilyPond input, for example GUI
391 sequencers and XML converters. Refer to the
392 @uref{http://@/lilypond@/.org,website} for more details.
394 These are separate programs from @command{lilypond} itself, and are
395 run on the command line; see @ref{Command-line usage} for more
396 information. If you have MacOS 10.3 or 10.4 and you have trouble
397 running some of these scripts, e.g. @code{convert-ly}, see
402 We unfortunately do not have the resources to maintain these
403 programs; please consider them @qq{as-is}. Patches are appreciated, but
404 bug reports will almost certainly not be resolved.
407 * Invoking midi2ly:: Importing MIDI.
408 * Invoking musicxml2ly:: Importing MusicXML.
409 * Invoking abc2ly:: Importing ABC.
410 * Invoking etf2ly:: Importing Finale.
416 @node Invoking midi2ly
417 @subsection Invoking @command{midi2ly}
421 @command{midi2ly} translates a Type@tie{}1 MIDI file to a LilyPond source
424 MIDI (Music Instrument Digital Interface) is a standard for digital
425 instruments: it specifies cabling, a serial protocol and a file
426 format. The MIDI file format is a de facto standard format for
427 exporting music from other programs, so this capability may come in
428 useful when importing files from a program that has a converter for a
431 @command{midi2ly} converts tracks into @rinternals{Staff} and
432 channels into @rinternals{Voice} contexts. Relative mode is used
433 for pitches, durations are only written when necessary.
435 It is possible to record a MIDI file using a digital keyboard, and
436 then convert it to @file{.ly}. However, human players are not
437 rhythmically exact enough to make a MIDI to LY conversion trivial.
438 When invoked with quantizing (@option{-s} and @option{-d} options)
439 @command{midi2ly} tries to compensate for these timing errors, but is not
440 very good at this. It is therefore not recommended to use @command{midi2ly}
441 for human-generated midi files.
444 It is invoked from the command-line as follows,
446 midi2ly [@var{option}]@dots{} @var{midi-file}
449 Note that by @q{command-line}, we mean the command line of the
450 operating system. See @ref{Converting from other formats}, for
451 more information about this.
453 The following options are supported by @command{midi2ly}.
456 @item -a, --absolute-pitches
457 Print absolute pitches.
459 @item -d, --duration-quant=@var{DUR}
460 Quantize note durations on @var{DUR}.
462 @item -e, --explicit-durations
463 Print explicit durations.
466 Show summary of usage.
468 @item -k, --key=@var{acc}[:@var{minor}]
469 Set default key. @math{@var{acc} > 0} sets number of sharps;
470 @math{@var{acc} < 0} sets number of flats. A minor key is indicated by
473 @item -o, --output=@var{file}
474 Write output to @var{file}.
476 @item -s, --start-quant=@var{DUR}
477 Quantize note starts on @var{DUR}.
479 @item -t, --allow-tuplet=@var{DUR}*@var{NUM}/@var{DEN}
480 Allow tuplet durations @var{DUR}*@var{NUM}/@var{DEN}.
486 Print version number.
489 Show warranty and copyright.
491 @item -x, --text-lyrics
492 Treat every text as a lyric.
498 Overlapping notes in an arpeggio will not be correctly rendered. The
499 first note will be read and the others will be ignored. Set them all
500 to a single duration and add phrase markings or pedal indicators.
503 @node Invoking musicxml2ly
504 @subsection Invoking @code{musicxml2ly}
508 @uref{http://@/www.@/musicxml@/.org/,MusicXML} is an XML dialect
509 for representing music notation.
511 @command{musicxml2ly} extracts the notes, articulations, score structure,
512 lyrics, etc. from part-wise MusicXML files, and writes them to a @file{.ly}
513 file. It is invoked from the command-line.
516 It is invoked from the command-line as follows,
518 musicxml2ly [@var{option}]@dots{} @var{xml-file}
521 Note that by @q{command-line}, we mean the command line of the
522 operating system. See @ref{Converting from other formats}, for
523 more information about this.
525 If the given filename is @file{-}, @command{musicxml2ly} reads input
526 from the command line.
528 The following options are supported by @command{musicxml2ly}:
532 convert pitches in absolute mode.
535 print usage and option summary.
537 @item -l, --language=LANG
538 use LANG for pitch names, e.g. 'deutsch' for note names in German.
540 @item --loglevel=@var{loglevel}
541 Set the output verbosity to @var{loglevel}. Possible values are @code{NONE},
542 @code{ERROR}, @code{WARNING}, @code{PROGRESS} (default) and @code{DEBUG}.
545 use the lxml.etree Python package for XML-parsing; uses less memory and cpu time.
550 @item -nd, --no-articulation-directions
551 do not convert directions (@code{^}, @code{_} or @code{-}) for
552 articulations, dynamics, etc.
555 do not convert beaming information, use LilyPond's automatic
558 @item -o, --output=@var{file}
559 set output filename to @var{file}. If @var{file} is @file{-}, the output
560 will be printed on stdout. If not given, @var{xml-file}@file{.ly} will
564 convert pitches in relative mode (default).
570 print version information.
572 @item -z, --compressed
573 input file is a zip-compressed MusicXML file.
577 @node Invoking abc2ly
578 @subsection Invoking @code{abc2ly}
580 @warning{This program is not supported, and may be remove from
581 future versions of LilyPond.}
585 ABC is a fairly simple ASCII based format. It is described at the ABC site:
588 @uref{http://@/www@/.walshaw@/.plus@/.com/@/abc/@/learn@/.html}.
591 @command{abc2ly} translates from ABC to LilyPond. It is invoked as follows:
594 abc2ly [@var{option}]@dots{} @var{abc-file}
597 The following options are supported by @command{abc2ly}:
600 @item -b, --beams=None
601 preserve ABC's notion of beams
604 @item -o, --output=@var{file}
605 set output filename to @var{file}.
607 be strict about success
609 print version information.
612 There is a rudimentary facility for adding LilyPond code to the ABC
613 source file. If you say:
616 %%LY voices \set autoBeaming = ##f
619 This will cause the text following the keyword @q{voices} to be inserted
620 into the current voice of the LilyPond output file.
625 %%LY slyrics more words
628 will cause the text following the @q{slyrics} keyword to be inserted
629 into the current line of lyrics.
634 The ABC standard is not very @q{standard}. For extended features
635 (e.g., polyphonic music) different conventions exist.
637 Multiple tunes in one file cannot be converted.
639 ABC synchronizes words and notes at the beginning of a line;
640 @command{abc2ly} does not.
642 @command{abc2ly} ignores the ABC beaming.
645 @node Invoking etf2ly
646 @subsection Invoking @command{etf2ly}
648 @warning{This program is not supported, and may be remove from
649 future versions of LilyPond.}
654 @cindex Coda Technology
656 ETF (Enigma Transport Format) is a format used by Coda Music
657 Technology's Finale product. @command{etf2ly} will convert part of an ETF
658 file to a ready-to-use LilyPond file.
660 It is invoked from the command-line as follows.
663 etf2ly [@var{option}]@dots{} @var{etf-file}
666 Note that by @q{command-line}, we mean the command line of the
667 operating system. See @ref{Converting from other formats}, for
668 more information about this.
670 The following options are supported by @command{etf2ly}:
675 @item -o, --output=@var{FILE}
676 set output filename to @var{FILE}
684 The list of articulation scripts is incomplete. Empty measures
685 confuse @command{etf2ly}. Sequences of grace notes are ended improperly.
689 @subsection Other formats
691 @cindex External programs, generating LilyPond files
693 LilyPond itself does not come with support for any other formats,
694 but some external tools can also generate LilyPond files. These
695 are listed in @rweb{Easier editing}.
699 @node LilyPond output in other programs
700 @section LilyPond output in other programs
702 This section shows methods to integrate text and music, different than
703 the automated method with @command{lilypond-book}.
706 * Many quotes from a large score::
707 * Inserting LilyPond output into OpenOffice and LibreOffice::
708 * Inserting LilyPond output into other programs::
711 @node Many quotes from a large score
712 @unnumberedsubsec Many quotes from a large score
714 If you need to quote many fragments from a large score, you can also use
715 the clip systems feature, see @ruser{Extracting fragments of music}.
718 @node Inserting LilyPond output into OpenOffice and LibreOffice
719 @unnumberedsubsec Inserting LilyPond output into OpenOffice and LibreOffice
721 @cindex OpenOffice.org
722 @cindex LibreOffice.org
724 LilyPond notation can be added to OpenOffice.org and LibreOffice with
725 @uref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond}.
728 @node Inserting LilyPond output into other programs
729 @unnumberedsubsec Inserting LilyPond output into other programs
731 To insert LilyPond output in other programs, use @code{lilypond}
732 instead of @code{lilypond-book}. Each example must be created
733 individually and added to the document; consult the documentation for
734 that program. Most programs will be able to insert LilyPond output in
735 @file{PNG}, @file{EPS}, or @file{PDF} formats.
737 To reduce the white space around your LilyPond score, use
738 the following options
746 bookTitleMarkup = ##f
747 scoreTitleMarkup = ##f
753 To produce useful image files:
758 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly
762 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts --png myfile.ly
766 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts \
767 -dpixmap-format=pngalpha --png myfile.ly
771 @node Independent includes
772 @section Independent @code{include}s
774 Some people have written large (and useful!) code that can be
775 shared between projects. This code might eventually make its way
776 into LilyPond itself, but until that happens, you must download
777 and @code{\include} them manually.
781 * MIDI articulation::
785 @node MIDI articulation
786 @subsection MIDI articulation
788 LilyPond can be used to produce MIDI output, for
789 @qq{proof-hearing} what has been written. However, only dynamics,
790 explicit tempo markings, and the notes and durations themselves
791 are produced in the output.
793 The @emph{articulate} project is one attempt to get more of the
794 information in the score into MIDI. It works by shortening
795 notes not under slurs, to @q{articulate} the notes. The amount of
796 shortening depends on any articulation markings attached to a
797 note: staccato halves the note value, tenuto gives a note its full
798 duration, and so on. The script also realises trills and turns,
799 and could be extended to expand other ornaments such as mordents.
802 @uref{http://@/www@/.nicta@/.com@/.au/@/people/@/chubbp/@/articulate}
807 Its main limitation is that it can only affect things it knows
808 about: anything that is merely textual markup (instead of a note
809 property) is still ignored.