1 #+OPTIONS: H:3 num:nil toc:2 \n:nil @:t ::t |:t ^:{} -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
2 #+STARTUP: align fold nodlcheck hidestars oddeven lognotestate hideblocks
3 #+SEQ_TODO: TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
4 #+TAGS: Write(w) Update(u) Fix(f) Check(c) noexport(n)
5 #+TITLE: Org-babel-lilypond
8 #+STYLE: <style type="text/css">#outline-container-introduction{ clear:both; }</style>
11 <div id="subtitle" style="float: center; text-align: center;">
14 <a href="http://lilypond.org/">Lilypond (Score Engraving and Arrangement)</a>
17 <a href="http://lilypond.org/">
18 <img src="../../../images/org-lilypond/mixolydian.png">
26 An /Emacs Org Babel language/ - provided to allow [[http://lilypond.org][LilyPond]] Music Score generation, complete
27 with optional auditioning via Midi, whilst leveraging the full power of Org mode, and [[http://en.wikipedia.org/wiki/Literate_programming][Literate Programming]].
31 There are two modes available with ob-lilypond
33 - *basic-mode* (default)
37 Which you use depends on what you intend to do.
38 (A quick way to switch modes is via `M-x ly-toggle-arrange-mode').
42 *basic-mode* (the default) allows you to embed LilyPond snippets into an Org-mode file, and
43 compile and export them using typical Org-mode commands (such as *C-c
44 C-e d* for pdf export). This is useful if you want to mix
45 blocks of Lilypond-generated score with text, and perhaps other images for export to Latex,
46 Docbook, pdf, or HTML. In other words, *basic-mode* could be used as a
47 very flexible replacement to *lilypond-book*.
49 *Warning!* in *basic-mode* a Lilypond source block requires to be passed
50 a *:file* parameter as shown below, as failure to do so will result
53 : #+begin_src lilypond :file Mixolydian.png
56 : 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
59 The previous block will produce an image file in .png format, which
60 would be suitable for exporting to HTML for instance.
62 To generate a nice image for embedding into a pdf or Latex document,
63 you might consider using the .eps format as shown in the example
66 : #+begin_src lilypond :file Mixolydian.eps
69 : 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
74 Following are some examples generated in ob-lilypond Basic Mode:
78 - [[https://github.com/mjago/ob-lilypond/blob/master/examples/basic-mode/pdf-example/pdf-example.pdf?raw=true][Here is an example]] of a pdf file containing high quality vector graphics generated by Org and ob-lilypond.
79 - [[https://raw.github.com/mjago/ob-lilypond/master/examples/basic-mode/pdf-example/pdf-example.org][and the Org file]] that compiled the LilyPond snippets and exported the pdf.
83 - [[https://github.com/mjago/ob-lilypond/raw/master/examples/basic-mode/html-example/html-example.html][Here is an example ]]of an html page containing images (png) generated by Org-mode and ob-lilypond.
84 - [[https://raw.github.com/mjago/ob-lilypond/master/examples/basic-mode/html-example/html-example.org][and the Org file]] that compiled the LilyPond snippets and exported the html page.
86 * Compiling LilyPond Blocks
87 In *basic-mode* the key sequence *C-c C-c* within a Lilypond block
88 will compile the block. Exporting of all blocks and Org file contents
89 is initialted with the sequence *C-c C-e* (standard Org-mode export keys).
92 *arrange-mode* allows you to develop complete pieces of score, whilst
93 organising sections of the piece using typical Org-mode techniques. And because
94 you are in Org-mode, you are free to use Literate Programming
95 techniques to generate things programatically - store information in
98 In addition, there are automated features to automatically audition
99 the piece (via MIDI) and or display the resultant pdf output.
101 To change the default mode to Arrange Mode, put the following in your emacs init file:
103 : (setq ly-arrange-mode t)
105 ...or to temporarily switch between modes use the following command:
107 : M-x ly-toggle-arrange-mode
109 Following are examples generated using ob-lilypond in Arrange Mode...
112 - [[https://github.com/mjago/ob-lilypond/blob/master/examples/arrange-mode/Modal-Cycle/modal-cycle.pdf?raw=true][Modal Cycles (Utilises org-babel and noweb to generate notes)]] (pdf)
113 - [[https://github.com/mjago/ob-lilypond/blob/master/examples/arrange-mode/Modal-Cycle/modal-cycle.midi?raw=true][Generated Midi File]]
114 - [[https://raw.github.com/mjago/ob-lilypond/master/examples/arrange-mode/Modal-Cycle/modal-cycle.org][Source Org File]]
117 - [[https://github.com/mjago/ob-lilypond/blob/master/examples/arrange-mode/Modal-Cycle-2/modal-cycle-2.pdf?raw=true][Modal Cycles 2 (Utilises org-babel and noweb to generate notes)]] (pdf)
118 - [[https://github.com/mjago/ob-lilypond/blob/master/examples/arrange-mode/Modal-Cycle-2/modal-cycle-2.midi?raw=true][Generated Midi File]]
119 - [[https://raw.github.com/mjago/ob-lilypond/master/examples/arrange-mode/Modal-Cycle-2/modal-cycle-2.org][Source Org File]]
121 ** Modes in the Key of C
122 - [[https://github.com/mjago/ob-lilypond/blob/master/examples/arrange-mode/Modes-in-Key-of-C/modes-in-key-of-c.pdf?raw=true][Modes in the Key of C (another example of polyglot lilypond programming)]] (pdf)
123 - [[https://github.com/mjago/ob-lilypond/blob/master/examples/arrange-mode/Modes-in-Key-of-C/modes-in-key-of-c.midi?raw=true][Generated Midi File]]
124 - [[https://raw.github.com/mjago/ob-lilypond/master/examples/arrange-mode/Modes-in-Key-of-C/modes-in-key-of-c.org][Source Org File]]
126 * Tangling and Compiling LilyPond Blocks
127 In *arrange-mode*, the key sequence *C-c C-c* within a Lilypond block
128 initiates `ly-tangle' (tangling of all Lilypond blocks within the
129 current Org file). Depending on the feature settings, ob-lilypond will
130 then either /display a pdf/ of the score, /play the generated MIDI
131 file/, both, or neither.
133 The command *M-x ly-tangle* can also be called from anywhere in the file
134 and could be tied to a function key with something like...
136 : (global-set-key [f8] 'ly-tangle)
138 Some commands are included in arrange-mode to quickly enable / disable certain post-tangle
139 activities, including:
141 - *ly-toggle-midi-play* (toggle whether midi will be played following a successful compilation)
142 - *ly-toggle-pdf-display* (toggle whether pdf will be displayed following a successful compilation)
144 *NOTE:-* If using [[http://timidity.sourceforge.net/][Timidity]] for MIDI playback, kill the MIDI stream with C-g in Emacs
147 To use *ob-lilypond*, you must be on a *very recent* version of
148 org-mode, (since it relies on a command that has been changed very
149 recently) and will break on older versions (ob-lilypond is also
150 included in the latest Org-mode by default).
152 For information on obtaining the latest Org-mode follow this link
153 to the [[http://orgmode.org/manual/Installation.html][Org-mode Manual]] and follow the instructions.
155 Then, add lilypond to your list of babel languages (in your init
158 : (org-babel-do-load-languages
159 : 'org-babel-load-languages
166 Alternatively you may *require* the ob-lilypond babel language directly:
168 : (require 'lilypond)
170 To ensure all is correct consider *running the tests* (see below).
175 - LilyPond may be [[http://lilypond.org/][downloaded here]]
178 - LilyPond is [[http://lilypond.org/][available here]] or via the the system-relevant package manager.
179 - For MIDI, *Timidity* is [[http://timidity.sourceforge.net/][available here]] or via the system-relevant package manager.
180 - For pdf, *Evince* is [[http://live.gnome.org/Evince/Downloads][available here]] or via package manager.
183 - Currently untested, although it should be made to work with minimal fuss.
186 Tests are provided and can be executed by running the following commands...
187 (for more help and information on testing see [[file:../../../org-tests/index.html][Testing Org]].
189 : M-x load-file RET testing/lisp/test-ob-lilypond.el
193 Any issues should be reported to the [[http://orgmode.org][Org-mode Mailing-list]]