]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/usage/external.itely
Doc-it: fix the wrong committishes (bad object) in .texidoc files
[lilypond.git] / Documentation / usage / external.itely
1 @c -*- coding: utf-8; mode: texinfo; -*-
2
3 @ignore
4     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
5
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..
9 @end ignore
10
11 @c \version "2.14.0"
12
13 @node External programs
14 @chapter External programs
15
16 LilyPond can interact with other programs in various ways.
17
18 @menu
19 * Point and click::
20 * Text editor support::
21 * Converting from other formats::
22 * LilyPond output in other programs::
23 * Independent includes::
24 @end menu
25
26
27 @node Point and click
28 @section Point and click
29
30 @cindex point and click
31
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
34 some error in the sheet music.
35
36 When this functionality is active, LilyPond adds hyperlinks to the PDF
37 file.  These hyperlinks are sent to the web-browser, which opens a
38 text-editor with the cursor in the right place.
39
40 To make this chain work, you should configure your PDF viewer to
41 follow hyperlinks using the @file{lilypond-invoke-editor} script
42 supplied with LilyPond.
43
44 For Xpdf on UNIX, the following should be present in
45 @file{xpdfrc}@footnote{On UNIX, this file is found either in
46 @file{/etc/xpdfrc} or as @file{.xpdfrc} in your home directory.}
47
48 @example
49 urlCommand     "lilypond-invoke-editor %s"
50 @end example
51
52 The program @file{lilypond-invoke-editor} is a small helper
53 program.  It will invoke an editor for the special @code{textedit}
54 URIs, and run a web browser for others.  It tests the environment
55 variable @code{EDITOR} for the following patterns,
56
57 @table @code
58 @item emacs
59   this will invoke
60 @example
61 emacsclient --no-wait +@var{line}:@var{column} @var{file}
62 @end example
63 @item gvim
64   this will invoke
65 @example
66 gvim --remote +:@var{line}:norm@var{column} @var{file}
67 @end example
68
69 @item nedit
70 this will invoke
71 @example
72   nc -noask +@var{line} @var{file}'
73 @end example
74 @end table
75
76 The environment variable @code{LYEDITOR} is used to override this.  It
77 contains the command line to start the editor, where @code{%(file)s},
78 @code{%(column)s}, @code{%(line)s} is replaced with the file, column
79 and line respectively.  The  setting
80
81 @example
82 emacsclient --no-wait +%(line)s:%(column)s %(file)s
83 @end example
84
85 @noindent
86 for @code{LYEDITOR} is equivalent to the standard emacsclient
87 invocation.
88
89
90 @cindex file size, output
91
92 The point and click links enlarge the output files significantly.  For
93 reducing the size of PDF and PS files, point and click may be switched
94 off by issuing
95
96 @example
97 \pointAndClickOff
98 @end example
99
100 @noindent
101 in a @file{.ly} file.  Point and click may be explicitly enabled with
102
103 @example
104 \pointAndClickOn
105 @end example
106
107 Alternately, you may disable point and click with a command-line
108 option:
109
110 @example
111 lilypond -dno-point-and-click file.ly
112 @end example
113
114 @warning{You should always turn off point and click in any LilyPond
115 files to be distributed to avoid including path information about
116 your computer in the .pdf file, which can pose a security risk.}
117 @node Text editor support
118 @section Text editor support
119
120 @cindex editors
121 @cindex vim
122 @cindex emacs
123 @cindex modes, editor
124 @cindex syntax coloring
125 @cindex coloring, syntax
126
127 There is support for different text editors for LilyPond.
128
129 @menu
130 * Emacs mode::
131 * Vim mode::
132 * Other editors::
133 @end menu
134
135 @node Emacs mode
136 @unnumberedsubsec Emacs mode
137
138 Emacs has a @file{lilypond-mode}, which provides keyword
139 autocompletion, indentation, LilyPond specific parenthesis matching
140 and syntax coloring, handy compile short-cuts and reading LilyPond
141 manuals using Info.  If @file{lilypond-mode} is not installed on your
142 platform, see below.
143
144 An Emacs mode for entering music and running LilyPond is contained in
145 the source archive in the @file{elisp} directory.  Do @command{make
146 install} to install it to @var{elispdir}.  The file @file{lilypond-init.el}
147 should be placed to @var{load-path}@file{/site-start.d/} or appended
148 to your @file{~/.emacs} or @file{~/.emacs.el}.
149
150 As a user, you may want add your source path (e.g. @file{~/site-lisp/}) to
151 your @var{load-path} by appending the following line (as modified) to your
152 @file{~/.emacs}
153
154 @c any reason we do not advise:  (push "~/site-lisp" load-path)
155 @example
156 (setq load-path (append (list (expand-file-name "~/site-lisp")) load-path))
157 @end example
158
159
160 @node Vim mode
161 @unnumberedsubsec Vim mode
162
163 For @uref{http://@/www@/.vim@/.org,Vim}, a filetype plugin, indent
164 mode, and syntax-highlighting mode are available to use with
165 LilyPond.  To enable all of these features, create (or modify)
166 your @file{$HOME/.vimrc} to contain these three lines, in order:
167
168 @example
169 filetype off
170 set runtimepath+=/usr/local/share/lilypond/current/vim/
171 filetype on
172 @end example
173
174 @noindent
175 If LilyPond is not installed in the @file{/usr/local/} directory,
176 change the path appropriately.  This topic is discussed in
177 @rlearning{Other sources of information}.
178
179
180 @node Other editors
181 @unnumberedsubsec Other editors
182
183 Other editors (both text and graphical) support LilyPond, but
184 their special configuration files are not distributed with
185 LilyPond.  Consult their documentation for more information.  Such
186 editors are listed in @rweb{Easier editing}.
187
188
189 @node Converting from other formats
190 @section Converting from other formats
191
192 Music can be entered also by importing it from other formats.  This
193 chapter documents the tools included in the distribution to do so.
194 There are other tools that produce LilyPond input, for example GUI
195 sequencers and XML converters.  Refer to the
196 @uref{http://@/lilypond@/.org,website} for more details.
197
198 These are separate programs from @command{lilypond} itself, and are
199 run on the command line; see @ref{Command-line usage} for more
200 information.  If you have MacOS 10.3 or 10.4 and you have trouble
201 running some of these scripts, e.g. @code{convert-ly}, see
202 @rweb{MacOS X}.
203
204
205 @knownissues
206 We unfortunately do not have the resources to maintain these
207 programs; please consider them @qq{as-is}.  Patches are appreciated, but
208 bug reports will almost certainly not be resolved.
209
210 @menu
211 * Invoking midi2ly::            Importing MIDI.
212 * Invoking musicxml2ly::        Importing MusicXML.
213 * Invoking abc2ly::             Importing ABC.
214 * Invoking etf2ly::             Importing Finale.
215 * Other formats::
216 @end menu
217
218
219
220 @node Invoking midi2ly
221 @subsection Invoking @command{midi2ly}
222
223 @cindex MIDI
224
225 @command{midi2ly} translates a Type@tie{}1 MIDI file to a LilyPond source
226 file.
227
228 MIDI (Music Instrument Digital Interface) is a standard for digital
229 instruments: it specifies cabling, a serial protocol and a file
230 format.  The MIDI file format is a de facto standard format for
231 exporting music from other programs, so this capability may come in
232 useful when importing files from a program that has a converter for a
233 direct format.
234
235 @command{midi2ly} converts tracks into @rinternals{Staff} and
236 channels into @rinternals{Voice} contexts.  Relative mode is used
237 for pitches, durations are only written when necessary.
238
239 It is possible to record a MIDI file using a digital keyboard, and
240 then convert it to @file{.ly}.  However, human players are not
241 rhythmically exact enough to make a MIDI to LY conversion trivial.
242 When invoked with quantizing (@option{-s} and @option{-d} options)
243 @command{midi2ly} tries to compensate for these timing errors, but is not
244 very good at this.  It is therefore not recommended to use @command{midi2ly}
245 for human-generated midi files.
246
247
248 It is invoked from the command-line as follows,
249 @example
250 midi2ly [@var{option}]@dots{} @var{midi-file}
251 @end example
252
253 Note that by @q{command-line}, we mean the command line of the
254 operating system.  See @ref{Converting from other formats}, for
255 more information about this.
256
257 The following options are supported by @command{midi2ly}.
258
259 @table @code
260 @item -a, --absolute-pitches
261 Print absolute pitches.
262
263 @item -d, --duration-quant=@var{DUR}
264 Quantize note durations on @var{DUR}.
265
266 @item -e, --explicit-durations
267 Print explicit durations.
268
269 @item -h,--help
270 Show summary of usage.
271
272 @item -k, --key=@var{acc}[:@var{minor}]
273 Set default key.  @math{@var{acc} > 0} sets number of sharps;
274 @math{@var{acc} < 0} sets number of flats.  A minor key is indicated by
275 @code{:1}.
276
277 @item -o, --output=@var{file}
278 Write output to @var{file}.
279
280 @item -s, --start-quant=@var{DUR}
281 Quantize note starts on @var{DUR}.
282
283 @item -t, --allow-tuplet=@var{DUR}*@var{NUM}/@var{DEN}
284 Allow tuplet durations @var{DUR}*@var{NUM}/@var{DEN}.
285
286 @item -v, --verbose
287 Be verbose.
288
289 @item -V, --version
290 Print version number.
291
292 @item -w, --warranty
293 Show warranty and copyright.
294
295 @item -x, --text-lyrics
296 Treat every text as a lyric.
297 @end table
298
299
300 @knownissues
301
302 Overlapping notes in an arpeggio will not be correctly rendered.  The
303 first note will be read and the others will be ignored.  Set them all
304 to a single duration and add phrase markings or pedal indicators.
305
306
307 @node Invoking musicxml2ly
308 @subsection Invoking @code{musicxml2ly}
309
310 @cindex MusicXML
311
312 @uref{http://@/www.@/musicxml@/.org/,MusicXML} is an XML dialect
313 for representing music notation.
314
315 @command{musicxml2ly} extracts the notes, articulations, score structure,
316 lyrics, etc. from part-wise MusicXML files, and writes them to a @file{.ly}
317 file.  It is invoked from the command-line.
318
319
320 It is invoked from the command-line as follows,
321 @example
322 musicxml2ly [@var{option}]@dots{} @var{xml-file}
323 @end example
324
325 Note that by @q{command-line}, we mean the command line of the
326 operating system.  See @ref{Converting from other formats}, for
327 more information about this.
328
329 If the given filename is @file{-}, @command{musicxml2ly} reads input
330 from the command line.
331
332 The following options are supported by @command{musicxml2ly}:
333
334 @table @code
335 @item -a, --absolute
336 convert pitches in absolute mode.
337
338 @item -h,--help
339 print usage and option summary.
340
341 @item -l, --language=LANG
342 use LANG for pitch names, e.g. 'deutsch' for note names in German.
343
344 @item --loglevel=@var{loglevel}
345 Set the output verbosity to @var{loglevel}. Possible values are @code{NONE},
346 @code{ERROR}, @code{WARNING}, @code{PROGRESS} (default) and @code{DEBUG}.
347
348 @item --lxml
349 use the lxml.etree Python package for XML-parsing; uses less memory and cpu time.
350
351 @item --nd --no-articulation-directions
352 do not convert directions (@code{^}, @code{_} or @code{-}) for
353 articulations, dynamics, etc.
354
355 @item --no-beaming
356 do not convert beaming information, use LilyPond's automatic
357 beaming instead.
358
359 @item -o,--output=@var{file}
360 set output filename to @var{file}.  If @var{file} is @file{-}, the output
361 will be printed on stdout.  If not given, @var{xml-file}@file{.ly} will
362 be used.
363
364 @item -r,--relative
365 convert pitches in relative mode (default).
366
367 @item -v,--verbose
368 be verbose.
369
370 @item --version
371 print version information.
372
373 @item -z,--compressed
374 input file is a zip-compressed MusicXML file.
375 @end table
376
377
378 @node Invoking abc2ly
379 @subsection Invoking @code{abc2ly}
380
381 @warning{This program is not supported, and may be remove from
382 future versions of LilyPond.}
383
384 @cindex ABC
385
386 ABC is a fairly simple ASCII based format.  It is described at the ABC site:
387
388 @quotation
389 @uref{http://@/www@/.walshaw@/.plus@/.com/@/abc/@/learn@/.html}.
390 @end quotation
391
392 @command{abc2ly} translates from ABC to LilyPond.  It is invoked as follows:
393
394 @example
395 abc2ly [@var{option}]@dots{} @var{abc-file}
396 @end example
397
398 The following options are supported by @command{abc2ly}:
399
400 @table @code
401 @item -b,--beams=None
402 preserve ABC's notion of beams
403 @item -h,--help
404 this help
405 @item -o,--output=@var{file}
406 set output filename to @var{file}.
407 @item -s,--strict
408 be strict about success
409 @item --version
410 print version information.
411 @end table
412
413 There is a rudimentary facility for adding LilyPond code to the ABC
414 source file.  If you say:
415
416 @example
417 %%LY voices \set autoBeaming = ##f
418 @end example
419
420 This will cause the text following the keyword @q{voices} to be inserted
421 into the current voice of the LilyPond output file.
422
423 Similarly,
424
425 @example
426 %%LY slyrics more words
427 @end example
428
429 will cause the text following the @q{slyrics} keyword to be inserted
430 into the current line of lyrics.
431
432
433 @knownissues
434
435 The ABC standard is not very @q{standard}.  For extended features
436 (e.g., polyphonic music) different conventions exist.
437
438 Multiple tunes in one file cannot be converted.
439
440 ABC synchronizes words and notes at the beginning of a line;
441 @command{abc2ly} does not.
442
443 @command{abc2ly} ignores the ABC beaming.
444
445
446 @node Invoking etf2ly
447 @subsection Invoking @command{etf2ly}
448
449 @warning{This program is not supported, and may be remove from
450 future versions of LilyPond.}
451
452 @cindex ETF
453 @cindex enigma
454 @cindex Finale
455 @cindex Coda Technology
456
457 ETF (Enigma Transport Format) is a format used by Coda Music
458 Technology's Finale product.  @command{etf2ly} will convert part of an ETF
459 file to a ready-to-use LilyPond file.
460
461 It is invoked from the command-line as follows.
462
463 @example
464 etf2ly [@var{option}]@dots{} @var{etf-file}
465 @end example
466
467 Note that by @q{command-line}, we mean the command line of the
468 operating system.  See @ref{Converting from other formats}, for
469 more information about this.
470
471 The following options are supported by @command{etf2ly}:
472
473 @table @code
474 @item -h,--help
475 this help
476 @item -o,--output=@var{FILE}
477 set output filename to @var{FILE}
478 @item --version
479 version information
480 @end table
481
482
483 @knownissues
484
485 The list of articulation scripts is incomplete.  Empty measures
486 confuse @command{etf2ly}.  Sequences of grace notes are ended improperly.
487
488
489 @node Other formats
490 @subsection Other formats
491
492 @cindex External programs, generating LilyPond files
493
494 LilyPond itself does not come with support for any other formats,
495 but some external tools can also generate LilyPond files.  These
496 are listed in @rweb{Easier editing}.
497
498
499
500 @node LilyPond output in other programs
501 @section LilyPond output in other programs
502
503 This section shows methods to integrate text and music, different than
504 the automated method with @command{lilypond-book}.
505
506 @menu
507 * Many quotes from a large score::
508 * Inserting LilyPond output into OpenOffice.org::
509 * Inserting LilyPond output into other programs::
510 @end menu
511
512 @node Many quotes from a large score
513 @unnumberedsubsec Many quotes from a large score
514
515 If you need to quote many fragments from a large score, you can also use
516 the clip systems feature, see @ruser{Extracting fragments of music}.
517
518
519 @node Inserting LilyPond output into OpenOffice.org
520 @unnumberedsubsec Inserting LilyPond output into OpenOffice.org
521
522 @cindex OpenOffice.org
523
524 LilyPond notation can be added to OpenOffice.org with
525 @uref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond}.
526
527
528 @node Inserting LilyPond output into other programs
529 @unnumberedsubsec Inserting LilyPond output into other programs
530
531 To insert LilyPond output in other programs, use @code{lilypond}
532 instead of @code{lilypond-book}.  Each example must be created
533 individually and added to the document; consult the documentation for
534 that program.  Most programs will be able to insert LilyPond output in
535 @file{PNG}, @file{EPS}, or @file{PDF} formats.
536
537 To reduce the white space around your LilyPond score, use
538 the following options
539
540 @example
541 \paper@{
542   indent=0\mm
543   line-width=120\mm
544   oddFooterMarkup=##f
545   oddHeaderMarkup=##f
546   bookTitleMarkup = ##f
547   scoreTitleMarkup = ##f
548 @}
549
550 @{ c1 @}
551 @end example
552
553 To produce useful image files:
554
555 @example
556 EPS
557
558 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly
559
560 PNG
561
562 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts --png myfile.ly
563
564 A transparent PNG
565
566 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts \
567   -dpixmap-format=pngalpha --png myfile.ly
568 @end example
569
570
571 @node Independent includes
572 @section Independent @code{include}s
573
574 Some people have written large (and useful!) code that can be
575 shared between projects.  This code might eventually make its way
576 into LilyPond itself, but until that happens, you must download
577 and @code{\include} them manually.
578
579
580 @menu
581 * MIDI articulation::
582 @end menu
583
584
585 @node MIDI articulation
586 @subsection MIDI articulation
587
588 LilyPond can be used to produce MIDI output, for
589 @qq{proof-hearing} what has been written.  However, only dynamics,
590 explicit tempo markings, and the notes and durations themselves
591 are produced in the output.
592
593 The @emph{articulate} project is one attempt to get more of the
594 information in the score into he MIDI.  It works by shortening
595 notes not under slurs, to @q{articulate} the notes.  The amount of
596 shortening depends on any articulation markings attached to a
597 note: staccato halves the note value, tenuto gives a note its full
598 duration, and so on.  The script also realises trills and turns,
599 and could be extended to expand other ornaments such as mordents.
600
601 @example
602 @uref{http://@/www@/.nicta@/.com@/.au/@/people/@/chubbp/@/articulate}
603 @end example
604
605 @knownissues
606
607 Its main limitation is that it can only affect things it knows
608 about: anything that is merely textual markup (instead of a note
609 property) is still ignored.
610
611