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 (@code{-s} and @code{-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 --lxml
 345 use the lxml.etree Python package for XML-parsing; uses less memory and cpu time.
 346
 347 @item --nd --no-articulation-directions
 348 do not convert directions (@code{^}, @code{_} or @code{-}) for
 349 articulations, dynamics, etc.
 350
 351 @item --no-beaming
 352 do not convert beaming information, use LilyPond's automatic
 353 beaming instead.
 354
 355 @item -o,--output=@var{file}
 356 set output filename to @var{file}.  If @var{file} is @file{-}, the output
 357 will be printed on stdout.  If not given, @var{xml-file}@file{.ly} will
 358 be used.
 359
 360 @item -r,--relative
 361 convert pitches in relative mode (default).
 362
 363 @item -v,--verbose
 364 be verbose.
 365
 366 @item --version
 367 print version information.
 368
 369 @item -z,--compressed
 370 input file is a zip-compressed MusicXML file.
 371 @end table
 372
 373
 374 @node Invoking abc2ly
 375 @subsection Invoking @code{abc2ly}
 376
 377 @warning{This program is not supported, and may be remove from
 378 future versions of LilyPond.}
 379
 380 @cindex ABC
 381
 382 ABC is a fairly simple ASCII based format.  It is described at the ABC site:
 383
 384 @quotation
 385 @uref{http://@/www@/.walshaw@/.plus@/.com/@/abc/@/learn@/.html}.
 386 @end quotation
 387
 388 @command{abc2ly} translates from ABC to LilyPond.  It is invoked as follows:
 389
 390 @example
 391 abc2ly [@var{option}]@dots{} @var{abc-file}
 392 @end example
 393
 394 The following options are supported by @command{abc2ly}:
 395
 396 @table @code
 397 @item -b,--beams=None
 398 preserve ABC's notion of beams
 399 @item -h,--help
 400 this help
 401 @item -o,--output=@var{file}
 402 set output filename to @var{file}.
 403 @item -s,--strict
 404 be strict about success
 405 @item --version
 406 print version information.
 407 @end table
 408
 409 There is a rudimentary facility for adding LilyPond code to the ABC
 410 source file.  If you say:
 411
 412 @example
 413 %%LY voices \set autoBeaming = ##f
 414 @end example
 415
 416 This will cause the text following the keyword @q{voices} to be inserted
 417 into the current voice of the LilyPond output file.
 418
 419 Similarly,
 420
 421 @example
 422 %%LY slyrics more words
 423 @end example
 424
 425 will cause the text following the @q{slyrics} keyword to be inserted
 426 into the current line of lyrics.
 427
 428
 429 @knownissues
 430
 431 The ABC standard is not very @q{standard}.  For extended features
 432 (e.g., polyphonic music) different conventions exist.
 433
 434 Multiple tunes in one file cannot be converted.
 435
 436 ABC synchronizes words and notes at the beginning of a line;
 437 @command{abc2ly} does not.
 438
 439 @command{abc2ly} ignores the ABC beaming.
 440
 441
 442 @node Invoking etf2ly
 443 @subsection Invoking @command{etf2ly}
 444
 445 @warning{This program is not supported, and may be remove from
 446 future versions of LilyPond.}
 447
 448 @cindex ETF
 449 @cindex enigma
 450 @cindex Finale
 451 @cindex Coda Technology
 452
 453 ETF (Enigma Transport Format) is a format used by Coda Music
 454 Technology's Finale product.  @command{etf2ly} will convert part of an ETF
 455 file to a ready-to-use LilyPond file.
 456
 457 It is invoked from the command-line as follows.
 458
 459 @example
 460 etf2ly [@var{option}]@dots{} @var{etf-file}
 461 @end example
 462
 463 Note that by @q{command-line}, we mean the command line of the
 464 operating system.  See @ref{Converting from other formats}, for
 465 more information about this.
 466
 467 The following options are supported by @command{etf2ly}:
 468
 469 @table @code
 470 @item -h,--help
 471 this help
 472 @item -o,--output=@var{FILE}
 473 set output filename to @var{FILE}
 474 @item --version
 475 version information
 476 @end table
 477
 478
 479 @knownissues
 480
 481 The list of articulation scripts is incomplete.  Empty measures
 482 confuse @command{etf2ly}.  Sequences of grace notes are ended improperly.
 483
 484
 485 @node Other formats
 486 @subsection Other formats
 487
 488 @cindex External programs, generating LilyPond files
 489
 490 LilyPond itself does not come with support for any other formats,
 491 but some external tools can also generate LilyPond files.  These
 492 are listed in @rweb{Easier editing}.
 493
 494
 495
 496 @node LilyPond output in other programs
 497 @section LilyPond output in other programs
 498
 499 This section shows methods to integrate text and music, different than
 500 the automated method with @command{lilypond-book}.
 501
 502 @menu
 503 * Many quotes from a large score::
 504 * Inserting LilyPond output into OpenOffice.org::
 505 * Inserting LilyPond output into other programs::
 506 @end menu
 507
 508 @node Many quotes from a large score
 509 @unnumberedsubsec Many quotes from a large score
 510
 511 If you need to quote many fragments from a large score, you can also use
 512 the clip systems feature, see @ruser{Extracting fragments of music}.
 513
 514
 515 @node Inserting LilyPond output into OpenOffice.org
 516 @unnumberedsubsec Inserting LilyPond output into OpenOffice.org
 517
 518 @cindex OpenOffice.org
 519
 520 LilyPond notation can be added to OpenOffice.org with
 521 @uref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond}.
 522
 523
 524 @node Inserting LilyPond output into other programs
 525 @unnumberedsubsec Inserting LilyPond output into other programs
 526
 527 To insert LilyPond output in other programs, use @code{lilypond}
 528 instead of @code{lilypond-book}.  Each example must be created
 529 individually and added to the document; consult the documentation for
 530 that program.  Most programs will be able to insert LilyPond output in
 531 @file{PNG}, @file{EPS}, or @file{PDF} formats.
 532
 533 To reduce the white space around your LilyPond score, use
 534 the following options
 535
 536 @example
 537 \paper@{
 538   indent=0\mm
 539   line-width=120\mm
 540   oddFooterMarkup=##f
 541   oddHeaderMarkup=##f
 542   bookTitleMarkup = ##f
 543   scoreTitleMarkup = ##f
 544 @}
 545
 546 @{ c1 @}
 547 @end example
 548
 549 To produce a useful @file{EPS} file, use
 550
 551 @example
 552 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts   myfile.ly
 553
 554 @file{PNG}:
 555 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts --png myfile.ly
 556 @end example
 557
 558
 559 @node Independent includes
 560 @section Independent @code{include}s
 561
 562 Some people have written large (and useful!) code that can be
 563 shared between projects.  This code might eventually make its way
 564 into LilyPond itself, but until that happens, you must download
 565 and @code{\include} them manually.
 566
 567
 568 @menu
 569 * MIDI articulation::
 570 @end menu
 571
 572
 573 @node MIDI articulation
 574 @subsection MIDI articulation
 575
 576 LilyPond can be used to produce MIDI output, for
 577 @qq{proof-hearing} what has been written.  However, only dynamics,
 578 explicit tempo markings, and the notes and durations themselves
 579 are produced in the output.
 580
 581 The @emph{articulate} project is one attempt to get more of the
 582 information in the score into he MIDI.  It works by shortening
 583 notes not under slurs, to @q{articulate} the notes.  The amount of
 584 shortening depends on any articulation markings attached to a
 585 note: staccato halves the note value, tenuto gives a note its full
 586 duration, and so on.  The script also realises trills and turns,
 587 and could be extended to expand other ornaments such as mordents.
 588
 589 @example
 590 @uref{http://@/www@/.nicta@/.com@/.au/@/people/@/chubbp/@/articulate}
 591 @end example
 592
 593 @knownissues
 594
 595 Its main limitation is that it can only affect things it knows
 596 about: anything that is merely textual markup (instead of a note
 597 property) is still ignored.
 598
 599