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 @node Using GNOME 2 for point and click
111 @unnumberedsubsubsec Using GNOME 2
113 For using GNOME 2, the magic invocation for telling the system
114 about the @samp{textedit:} URI is
116 gconftool-2 -t string -s /desktop/gnome/url-handlers/textedit/command "lilypond-invoke-editor %s"
117 gconftool-2 -s /desktop/gnome/url-handlers/textedit/needs_terminal false -t bool
118 gconftool-2 -t bool -s /desktop/gnome/url-handlers/textedit/enabled true
121 After that invocation,
123 gnome-open textedit:///etc/issue:1:0:0
126 should call @file{lilypond-invoke-editor} for opening files.
128 @node Using GNOME 3 for point and click
129 @unnumberedsubsubsec Using GNOME 3
131 In GNOME 3, URIs are handled by the @q{gvfs} layer rather than by
132 @q{gconf}. Create a file in a local directory such as @file{/tmp}
133 that is called @file{lilypond-invoke-editor.desktop} and has the contents
137 Name=lilypond-invoke-editor
138 GenericName=Textedit URI handler
139 Comment=URI handler for textedit:
140 Exec=lilypond-invoke-editor %u
143 MimeType=x-scheme-handler/textedit;
147 and then execute the commands
149 xdg-desktop-menu install ./lilypond-invoke-editor.desktop
150 xdg-mime default lilypond-invoke-editor.desktop x-scheme-handler/textedit
153 After that invocation,
155 gnome-open textedit:///etc/issue:1:0:0
158 should call @file{lilypond-invoke-editor} for opening files.
160 @node Extra configuration for Evince
161 @unnumberedsubsubsec Extra configuration for Evince
164 If @code{gnome-open} works, but Evince still refuses to open point
165 and click links due to denied permissions, you might need to
166 change the Apparmor profile of Evince which controls the kind of
167 actions Evince is allowed to perform.
169 For Ubuntu, the process is to edit the file
170 @file{/etc/apparmor.d/local/usr.bin.evince} and append the
174 /usr/local/bin/lilypond-invoke-editor Cx -> sanitized_helper,
178 After adding these lines, call
181 sudo apparmor_parser -r -T -W /etc/apparmor.d/usr.bin.evince
185 Now Evince should be able to open point and click links. It is
186 likely that similar configurations will work for other viewers.
188 @node Enabling point and click
189 @unnumberedsubsec Enabling point and click
190 @cindex file size, output
192 Point and click functionality is enabled by default when creating
195 The point and click links enlarge the output files significantly. For
196 reducing the size of PDF and PS files, point and click may be switched
204 in a @file{.ly} file. Point and click may be explicitly enabled with
210 Alternately, you may disable point and click with a command-line
214 lilypond -dno-point-and-click file.ly
217 @warning{You should always turn off point and click in any LilyPond
218 files to be distributed to avoid including path information about
219 your computer in the .pdf file, which can pose a security risk.}
221 @node Selective point-and-click
222 @unnumberedsubsec Selective point-and-click
224 For some interactive applications, it may be desirable to only
225 include certain point-and-click items. For example, if somebody
226 wanted to create an application which played audio or video
227 starting from a particular note, it would be awkward if clicking
228 on the note produced the point-and-click location for an
229 accidental or slur which occurred over that note.
231 This may be controlled by indicating which events to include:
235 Hard-coded in the @file{.ly} file:
238 \pointAndClickTypes #'note-event
247 #(ly:set-option 'point-and-click 'note-event)
257 lilypond -dpoint-and-click=note-event example.ly
262 Multiple events can be included:
266 Hard-coded in the @file{.ly} file:
269 \pointAndClickTypes #'(note-event dynamic-event)
278 #(ly:set-option 'point-and-click '(note-event dynamic-event))
289 -e"(ly:set-option 'point-and-click '(note-event dynamic-event))" \
297 @node Text editor support
298 @section Text editor support
303 @cindex modes, editor
304 @cindex syntax coloring
305 @cindex coloring, syntax
307 There is support for different text editors for LilyPond.
316 @unnumberedsubsec Emacs mode
318 Emacs has a @file{lilypond-mode}, which provides keyword
319 autocompletion, indentation, LilyPond specific parenthesis matching
320 and syntax coloring, handy compile short-cuts and reading LilyPond
321 manuals using Info. If @file{lilypond-mode} is not installed on your
324 An Emacs mode for entering music and running LilyPond is contained in
325 the source archive in the @file{elisp} directory. Do @command{make
326 install} to install it to @var{elispdir}. The file @file{lilypond-init.el}
327 should be placed to @var{load-path}@file{/site-start.d/} or appended
328 to your @file{~/.emacs} or @file{~/.emacs.el}.
330 As a user, you may want add your source path (e.g. @file{~/site-lisp/}) to
331 your @var{load-path} by appending the following line (as modified) to your
334 @c any reason we do not advise: (push "~/site-lisp" load-path)
336 (setq load-path (append (list (expand-file-name "~/site-lisp")) load-path))
341 @unnumberedsubsec Vim mode
343 For @uref{http://@/www@/.vim@/.org,Vim}, a filetype plugin, indent
344 mode, and syntax-highlighting mode are available to use with
345 LilyPond. To enable all of these features, create (or modify)
346 your @file{$HOME/.vimrc} to contain these three lines, in order:
350 set runtimepath+=/usr/local/share/lilypond/current/vim/
355 If LilyPond is not installed in the @file{/usr/local/} directory,
356 change the path appropriately. This topic is discussed in
357 @rlearning{Other sources of information}.
361 @unnumberedsubsec Other editors
363 Other editors (both text and graphical) support LilyPond, but
364 their special configuration files are not distributed with
365 LilyPond. Consult their documentation for more information. Such
366 editors are listed in @rweb{Easier editing}.
369 @node Converting from other formats
370 @section Converting from other formats
372 Music can be entered also by importing it from other formats. This
373 chapter documents the tools included in the distribution to do so.
374 There are other tools that produce LilyPond input, for example GUI
375 sequencers and XML converters. Refer to the
376 @uref{http://@/lilypond@/.org,website} for more details.
378 These are separate programs from @command{lilypond} itself, and are
379 run on the command line; see @ref{Command-line usage} for more
380 information. If you have MacOS 10.3 or 10.4 and you have trouble
381 running some of these scripts, e.g. @code{convert-ly}, see
386 We unfortunately do not have the resources to maintain these
387 programs; please consider them @qq{as-is}. Patches are appreciated, but
388 bug reports will almost certainly not be resolved.
391 * Invoking midi2ly:: Importing MIDI.
392 * Invoking musicxml2ly:: Importing MusicXML.
393 * Invoking abc2ly:: Importing ABC.
394 * Invoking etf2ly:: Importing Finale.
400 @node Invoking midi2ly
401 @subsection Invoking @command{midi2ly}
405 @command{midi2ly} translates a Type@tie{}1 MIDI file to a LilyPond source
408 MIDI (Music Instrument Digital Interface) is a standard for digital
409 instruments: it specifies cabling, a serial protocol and a file
410 format. The MIDI file format is a de facto standard format for
411 exporting music from other programs, so this capability may come in
412 useful when importing files from a program that has a converter for a
415 @command{midi2ly} converts tracks into @rinternals{Staff} and
416 channels into @rinternals{Voice} contexts. Relative mode is used
417 for pitches, durations are only written when necessary.
419 It is possible to record a MIDI file using a digital keyboard, and
420 then convert it to @file{.ly}. However, human players are not
421 rhythmically exact enough to make a MIDI to LY conversion trivial.
422 When invoked with quantizing (@option{-s} and @option{-d} options)
423 @command{midi2ly} tries to compensate for these timing errors, but is not
424 very good at this. It is therefore not recommended to use @command{midi2ly}
425 for human-generated midi files.
428 It is invoked from the command-line as follows,
430 midi2ly [@var{option}]@dots{} @var{midi-file}
433 Note that by @q{command-line}, we mean the command line of the
434 operating system. See @ref{Converting from other formats}, for
435 more information about this.
437 The following options are supported by @command{midi2ly}.
440 @item -a, --absolute-pitches
441 Print absolute pitches.
443 @item -d, --duration-quant=@var{DUR}
444 Quantize note durations on @var{DUR}.
446 @item -e, --explicit-durations
447 Print explicit durations.
450 Show summary of usage.
452 @item -k, --key=@var{acc}[:@var{minor}]
453 Set default key. @math{@var{acc} > 0} sets number of sharps;
454 @math{@var{acc} < 0} sets number of flats. A minor key is indicated by
457 @item -o, --output=@var{file}
458 Write output to @var{file}.
460 @item -s, --start-quant=@var{DUR}
461 Quantize note starts on @var{DUR}.
463 @item -t, --allow-tuplet=@var{DUR}*@var{NUM}/@var{DEN}
464 Allow tuplet durations @var{DUR}*@var{NUM}/@var{DEN}.
470 Print version number.
473 Show warranty and copyright.
475 @item -x, --text-lyrics
476 Treat every text as a lyric.
482 Overlapping notes in an arpeggio will not be correctly rendered. The
483 first note will be read and the others will be ignored. Set them all
484 to a single duration and add phrase markings or pedal indicators.
487 @node Invoking musicxml2ly
488 @subsection Invoking @code{musicxml2ly}
492 @uref{http://@/www.@/musicxml@/.org/,MusicXML} is an XML dialect
493 for representing music notation.
495 @command{musicxml2ly} extracts the notes, articulations, score structure,
496 lyrics, etc. from part-wise MusicXML files, and writes them to a @file{.ly}
497 file. It is invoked from the command-line.
500 It is invoked from the command-line as follows,
502 musicxml2ly [@var{option}]@dots{} @var{xml-file}
505 Note that by @q{command-line}, we mean the command line of the
506 operating system. See @ref{Converting from other formats}, for
507 more information about this.
509 If the given filename is @file{-}, @command{musicxml2ly} reads input
510 from the command line.
512 The following options are supported by @command{musicxml2ly}:
516 convert pitches in absolute mode.
519 print usage and option summary.
521 @item -l, --language=LANG
522 use LANG for pitch names, e.g. 'deutsch' for note names in German.
524 @item --loglevel=@var{loglevel}
525 Set the output verbosity to @var{loglevel}. Possible values are @code{NONE},
526 @code{ERROR}, @code{WARNING}, @code{PROGRESS} (default) and @code{DEBUG}.
529 use the lxml.etree Python package for XML-parsing; uses less memory and cpu time.
534 @item -nd --no-articulation-directions
535 do not convert directions (@code{^}, @code{_} or @code{-}) for
536 articulations, dynamics, etc.
539 do not convert beaming information, use LilyPond's automatic
542 @item -o,--output=@var{file}
543 set output filename to @var{file}. If @var{file} is @file{-}, the output
544 will be printed on stdout. If not given, @var{xml-file}@file{.ly} will
548 convert pitches in relative mode (default).
554 print version information.
556 @item -z,--compressed
557 input file is a zip-compressed MusicXML file.
561 @node Invoking abc2ly
562 @subsection Invoking @code{abc2ly}
564 @warning{This program is not supported, and may be remove from
565 future versions of LilyPond.}
569 ABC is a fairly simple ASCII based format. It is described at the ABC site:
572 @uref{http://@/www@/.walshaw@/.plus@/.com/@/abc/@/learn@/.html}.
575 @command{abc2ly} translates from ABC to LilyPond. It is invoked as follows:
578 abc2ly [@var{option}]@dots{} @var{abc-file}
581 The following options are supported by @command{abc2ly}:
584 @item -b,--beams=None
585 preserve ABC's notion of beams
588 @item -o,--output=@var{file}
589 set output filename to @var{file}.
591 be strict about success
593 print version information.
596 There is a rudimentary facility for adding LilyPond code to the ABC
597 source file. If you say:
600 %%LY voices \set autoBeaming = ##f
603 This will cause the text following the keyword @q{voices} to be inserted
604 into the current voice of the LilyPond output file.
609 %%LY slyrics more words
612 will cause the text following the @q{slyrics} keyword to be inserted
613 into the current line of lyrics.
618 The ABC standard is not very @q{standard}. For extended features
619 (e.g., polyphonic music) different conventions exist.
621 Multiple tunes in one file cannot be converted.
623 ABC synchronizes words and notes at the beginning of a line;
624 @command{abc2ly} does not.
626 @command{abc2ly} ignores the ABC beaming.
629 @node Invoking etf2ly
630 @subsection Invoking @command{etf2ly}
632 @warning{This program is not supported, and may be remove from
633 future versions of LilyPond.}
638 @cindex Coda Technology
640 ETF (Enigma Transport Format) is a format used by Coda Music
641 Technology's Finale product. @command{etf2ly} will convert part of an ETF
642 file to a ready-to-use LilyPond file.
644 It is invoked from the command-line as follows.
647 etf2ly [@var{option}]@dots{} @var{etf-file}
650 Note that by @q{command-line}, we mean the command line of the
651 operating system. See @ref{Converting from other formats}, for
652 more information about this.
654 The following options are supported by @command{etf2ly}:
659 @item -o,--output=@var{FILE}
660 set output filename to @var{FILE}
668 The list of articulation scripts is incomplete. Empty measures
669 confuse @command{etf2ly}. Sequences of grace notes are ended improperly.
673 @subsection Other formats
675 @cindex External programs, generating LilyPond files
677 LilyPond itself does not come with support for any other formats,
678 but some external tools can also generate LilyPond files. These
679 are listed in @rweb{Easier editing}.
683 @node LilyPond output in other programs
684 @section LilyPond output in other programs
686 This section shows methods to integrate text and music, different than
687 the automated method with @command{lilypond-book}.
690 * Many quotes from a large score::
691 * Inserting LilyPond output into OpenOffice.org::
692 * Inserting LilyPond output into other programs::
695 @node Many quotes from a large score
696 @unnumberedsubsec Many quotes from a large score
698 If you need to quote many fragments from a large score, you can also use
699 the clip systems feature, see @ruser{Extracting fragments of music}.
702 @node Inserting LilyPond output into OpenOffice.org
703 @unnumberedsubsec Inserting LilyPond output into OpenOffice.org
705 @cindex OpenOffice.org
707 LilyPond notation can be added to OpenOffice.org with
708 @uref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond}.
711 @node Inserting LilyPond output into other programs
712 @unnumberedsubsec Inserting LilyPond output into other programs
714 To insert LilyPond output in other programs, use @code{lilypond}
715 instead of @code{lilypond-book}. Each example must be created
716 individually and added to the document; consult the documentation for
717 that program. Most programs will be able to insert LilyPond output in
718 @file{PNG}, @file{EPS}, or @file{PDF} formats.
720 To reduce the white space around your LilyPond score, use
721 the following options
729 bookTitleMarkup = ##f
730 scoreTitleMarkup = ##f
736 To produce useful image files:
741 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly
745 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts --png myfile.ly
749 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts \
750 -dpixmap-format=pngalpha --png myfile.ly
754 @node Independent includes
755 @section Independent @code{include}s
757 Some people have written large (and useful!) code that can be
758 shared between projects. This code might eventually make its way
759 into LilyPond itself, but until that happens, you must download
760 and @code{\include} them manually.
764 * MIDI articulation::
768 @node MIDI articulation
769 @subsection MIDI articulation
771 LilyPond can be used to produce MIDI output, for
772 @qq{proof-hearing} what has been written. However, only dynamics,
773 explicit tempo markings, and the notes and durations themselves
774 are produced in the output.
776 The @emph{articulate} project is one attempt to get more of the
777 information in the score into MIDI. It works by shortening
778 notes not under slurs, to @q{articulate} the notes. The amount of
779 shortening depends on any articulation markings attached to a
780 note: staccato halves the note value, tenuto gives a note its full
781 duration, and so on. The script also realises trills and turns,
782 and could be extended to expand other ornaments such as mordents.
785 @uref{http://@/www@/.nicta@/.com@/.au/@/people/@/chubbp/@/articulate}
790 Its main limitation is that it can only affect things it knows
791 about: anything that is merely textual markup (instead of a note
792 property) is still ignored.