UP | HOME

Support via Liberapay, GitHub or PayPal

Org-babel-lilypond

Table of Contents

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)
  • arrange-mode

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

basic-mode

basic-mode (the default) allows you to embed LilyPond snippets into an Org-mode file, and 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 very flexible replacement to lilypond-book.

Warning! in basic-mode a lilypond source block requires a :file parameter as shown below, as failure to do so will result in an error message.

#+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 a nice image for embedding into a pdf or Latex document, you might consider using the .eps (or .pdf) format as shown in the example below.

#+begin_src lilypond :file Mixolydian.eps
\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

Following are some examples generated in ob-lilypond Basic Mode.

Note: Some of the source files used in these examples were published by Martyn Jago in 2011 and are probably no longer compatible with recent versions of Org and LilyPond.

PDF export

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

HTML export

  • Here is an example of an html page containing images (png) generated by Org-mode and ob-lilypond.
  • and the Org file that compiled the LilyPond snippets and exported the html page.

Compiling LilyPond Blocks

In basic-mode the key sequence C-c C-c within a Lilypond block will compile the block. Exporting of all blocks and Org file contents is initiated with the sequence C-c C-e (standard Org-mode export keys).

Arrange Mode

arrange-mode allows you to develop complete pieces of score, whilst organizing sections of the piece using typical Org-mode techniques. And because you are in Org-mode, you are free to use Literate Programming techniques to do things programatically, like storing information in tables etc.

In addition, there are automated features to automatically audition the piece (via MIDI) and or display the resultant pdf output.

To change the default mode to Arrange Mode, put the following in your Emacs init file:

(setq org-babel-lilypond-arrange-mode t)

…or to temporarily switch between modes use the following command:

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

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

Tangling and Compiling LilyPond Blocks

In arrange-mode, the key sequence C-c C-c within a Lilypond block initiates org-babel-lilypond-tangle (tangling of 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 M-x 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 (toggle whether midi will be played following a successful compilation)
  • org-babel-lilypond-toggle-pdf-display (toggle whether pdf will be displayed following a successful compilation)

Note: If using Timidity for MIDI playback, kill the MIDI stream with C-g in 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 (in your init file):

(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

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