Org-babel-lilypond

LilyPond is a music engraving program devoted to producing the highest-quality sheet music possible. Org-mode supports lilypond source code blocks that can generate music scores with optional auditing via MIDI.

There are two modes available with ob-lilypond:

• basic-mode (default), and
• arrange-mode

Which one you use depends on what you intend to do (type M-x org-babel-lilypond-toggle-arrange-mode to switch modes).

With basic-mode you can embed LilyPond snippets into an Org-mode file, compile and export them using typical Org-mode commands (such as C-c C-e l p for PDF export). This is useful if you want to mix blocks of LilyPond-generated score with text, and perhaps other images to export to LaTeX, Docbook, PDF, or HTML. In other words, basic-mode could be used as a flexible replacement to the lilypond-book command.

Note that in basic-mode a lilypond source block requires a :file parameter as shown below.

#+begin_src lilypond :file mixolydian.png
\relative c' {
  g a b c
  d e f g
  f e d c
  b a g a
  b c d e
  f g f e
  d c b a
  g1
}
#+end_src

The previous block will produce an image file in .png format, which would be suitable for exporting to HTML, for instance.

To generate an image suitable for embedding into a PDF/LaTeX document, you might consider using the .pdf (or .eps) format as shown in the following example.

#+begin_src lilypond :file mixolydian.pdf
\relative c' {
  g a b c
  d e f g
  f e d c
  b a g a
  b c d e
  f g f e
  d c b a
  g1
}
#+end_src

• Here is an example of a PDF file containing high quality vector graphics generated by Org-mode and ob-lilypond.
• and the Org file that compiled the LilyPond snippets and generated the PDF.

In basic-mode, pressing C-c C-c within a lilypond block compiles the block. Likewise, pressing C-c C-e (standard Org-mode export keys) exports the Org document.

With arrange-mode you can develop complete pieces of score whilst organizing sections of the piece using typical literate programming techniques. This allows you to assemble scores programatically by using tables to store information among other methods.

The mode also includes features to audition the piece (via MIDI) automatically and or display the resultant PDF output. Again, you can switch modes using the following command:

M-x org-babel-lilypond-toggle-arrange-mode

Or you can define your mode preference by changing the org-babel-lilypond-arrange-mode variable. Setting it to a non-nil value makes Arrange Mode the default mode.

Following are examples generated using ob-lilypond in Arrange Mode.

In arrange-mode, pressing C-c C-c within a LilyPond block initiates org-babel-lilypond-tangle, tangling all LilyPond blocks within the current Org file. Depending on the feature settings, ob-lilypond will then either display a PDF of the score, play the generated MIDI file, both, or neither.

The command org-babel-lilypond-tangle can also be called from anywhere in the file and could be tied to a function key with something like:

(global-set-key [f8] 'org-babel-lilypond-tangle)

Some commands are included in arrange-mode to quickly enable/disable certain post-tangle activities, including:

• org-babel-lilypond-toggle-midi-play, which decides whether to play the corresponding MIDI following a successful compilation, and
• org-babel-lilypond-toggle-pdf-display, which decides whether to display the PDF following a successful compilation.

Note that when using Timidity for MIDI playback, you can kill the MIDI stream by pressing C-g from Emacs.

By default, ob-lilypond is included in the latest Org-mode. For information on obtaining the latest Org-mode follow this link to the Org-mode Manual and follow the instructions.

Then, add lilypond to your list of babel languages:

(org-babel-do-load-languages
 'org-babel-load-languages
 '((emacs-lisp . t)
   (org . t)
   (lilypond . t)))

Alternatively, you may require the ob-lilypond babel language directly:

(require 'ob-lilypond)

To ensure all is correct consider running the tests (see below).

Tests are provided and can be executed by running the following commands (for more help and information on testing see Testing Org):

M-x load-file RET  testing/lisp/test-ob-lilypond.el
M-x ert t

Issues should be reported to the Org-mode Mailing-list.