UP | HOME

Support via Liberapay

Org-babel-lilypond

Org Babel support for LilyPond (Score Engraving and Arrangement)

Introduction

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.

Usage

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).

Basic Mode

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

Examples

  • 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.

Compiling LilyPond Blocks

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.

Arrange Mode

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.

Tangling and Compiling LilyPond Blocks

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.

Setup

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).

Requirements

Mac OS X

Nix

  • LilyPond is available here or via the the system-relevant package manager.
  • For MIDI, Timidity is available here or via the system-relevant package manager.
  • For PDF, Evince is available here or via package manager.

Win32

  • Currently untested, although it should be made to work with minimal fuss.

Testing

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

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

Documentation from the orgmode.org/worg/ website (either in its HTML format or in its Org format) is licensed under the GNU Free Documentation License version 1.3 or later. The code examples and css stylesheets are licensed under the GNU General Public License v3 or later.