Org-babel-lilypond

Table of Contents

Org Babel support for Lilypond (Score Engraving and Arrangement)

Introduction

An Emacs Org Babel language - provided to allow LilyPond Music Score generation, complete with optional auditioning via Midi, whilst leveraging the full power of Org mode, and Literate Programming.

Usage

There are two modes available with ob-lilypond

  • basic-mode (default)
  • arrange-mode

Which you use depends on what you intend to do. (A quick way to switch modes is via `M-x ly-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 d for pdf export). This is useful if you want to mix blocks of Lilypond-generated score with text, and perhaps other images for 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 to be passed 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 
 }

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 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 
 }

Examples

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

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 initialted 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 organising 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 generate things programatically - store 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 ly-arrange-mode t)

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

M-x ly-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 `ly-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 ly-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] 'ly-tangle)

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

  • ly-toggle-midi-play (toggle whether midi will be played following a successful compilation)
  • ly-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

To use ob-lilypond, you must be on a very recent version of org-mode, (since it relies on a command that has been changed very recently) and will break on older versions (ob-lilypond is also included in the latest Org-mode by default).

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)
    (sh t)
    (org t)
    (lilypond t))) 

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

(require '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 http://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.