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