org-contrib/babel/languages/ob-doc-lilypond.org

   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
   6 #+AUTHOR:     Martyn Jago
   7 #+LANGUAGE:   en
   8 #+STYLE:      <style type="text/css">#outline-container-introduction{ clear:both; }</style>
   9
  10 #+begin_html
  11   <div id="subtitle" style="float: center; text-align: center;">
  12   <p>
  13   Org Babel support for
  14   <a href="http://lilypond.org/">Lilypond (Score Engraving and Arrangement)</a>
  15   </p>
  16   <p>
  17   <a href="http://lilypond.org/">
  18   <img src="../examples/lilypond-examples/basic-mode/html-example/mixolydian.png">
  19   </a>
  20   </p>
  21   </div>
  22 #+end_html
  23
  24 * Introduction
  25
  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]].
  28
  29 * Usage
  30
  31 There are two modes available with ob-lilypond
  32
  33   - *basic-mode* (default)
  34
  35   - *arrange-mode*
  36
  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*').
  39
  40 * basic-mode
  41
  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*.
  48
  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
  51  in an error message.
  52
  53 : #+begin_src lilypond :file Mixolydian.png
  54 :
  55 :   \relative c’ {
  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
  57 :  }
  58
  59 The previous block will produce an image file in .png format, which
  60 would be suitable for exporting to HTML for instance. See
  61 [[https://github.com/mjago/ob-lilypond/blob/master/examples/basic-mode/html-example/html-example.org][html-example.org]] for a more complete example.
  62
  63 To generate a nice image for embedding into a pdf or Latex document,
  64 you might consider using the .eps format as shown in the example
  65 below.
  66
  67 : #+begin_src lilypond :file Mixolydian.eps
  68 :
  69 :   \relative c’ {
  70 :     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
  71 :  }
  72
  73 See [[https://github.com/mjago/ob-lilypond/blob/master/examples/basic-mode/pdf-example/pdf-example.org][pdf-example.org]] for a more complete example.
  74
  75 * Examples
  76
  77 Following are some examples generated in ob-lilypond Basic Mode:
  78
  79 ** pdf export
  80
  81   - [[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.
  82   - [[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
  84 ** HTML export
  85
  86   - [[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.
  87   - [[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.
  88
  89 * Compiling LilyPond Blocks
  90 In *basic-mode* the key sequence *C-c C-c* within a Lilypond block
  91 will compile the block. Exporting of all blocks and Org file contents
  92 is initialted with the sequence *C-c C-e* (standard Org-mode export keys).
  93
  94 * Arrange Mode
  95 *arrange-mode* allows you to develop complete pieces of score, whilst
  96 organising sections of the piece using typical Org-mode techniques. And because
  97 you are in Org-mode, you are free to use Literate Programming
  98 techniques to generate things programatically - store information in
  99 tables etc.
 100
 101 In addition, there are automated features to automatically audition
 102 the piece (via MIDI) and or display the resultant pdf output.
 103
 104 To change the default mode to Arrange Mode, put the following in your emacs init file:
 105
 106 : (setq ly-arrange-mode t)
 107
 108 ...or to temporarily switch between modes use the following command:
 109
 110 : *M-x ly-toggle-arrange-mode*
 111
 112 Following are examples generated using ob-lilypond in Arrange Mode...
 113
 114 ** Modal Cycles
 115  - [[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)
 116  - [[https://github.com/mjago/ob-lilypond/blob/master/examples/arrange-mode/Modal-Cycle/modal-cycle.midi?raw=true][Generated Midi File]]
 117  - [[https://raw.github.com/mjago/ob-lilypond/master/examples/arrange-mode/Modal-Cycle/modal-cycle.org][Source Org File]]
 118
 119 ** Modal Cycles 2
 120  - [[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)
 121  - [[https://github.com/mjago/ob-lilypond/blob/master/examples/arrange-mode/Modal-Cycle-2/modal-cycle-2.midi?raw=true][Generated Midi File]]
 122  - [[https://raw.github.com/mjago/ob-lilypond/master/examples/arrange-mode/Modal-Cycle-2/modal-cycle-2.org][Source Org File]]
 123
 124 ** Modes in the Key of C
 125  - [[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)
 126  - [[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]]
 127  - [[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]]
 128
 129 * Tangling and Compiling LilyPond Blocks
 130 In *arrange-mode*, the key sequence *C-c C-c* within a Lilypond block
 131 initiates `ly-tangle' (tangling of all Lilypond blocks within the
 132 current Org file). Depending on the feature settings, ob-lilypond will
 133 then either /display a pdf/ of the score, /play the generated MIDI
 134 file/, both, or neither.
 135
 136 The command *M-x ly-tangle* can also be called from anywhere in the file
 137 and could be tied to a function key with something like...
 138
 139 : (global-set-key [f8] 'ly-tangle)
 140
 141 Some commands are included in arrange-mode to quickly enable / disable certain post-tangle
 142 activities, including:
 143
 144  - *ly-toggle-midi-play* (toggle whether midi will be played following a successful compilation)
 145  - *ly-toggle-pdf-display* (toggle whether pdf will be displayed following a successful compilation)
 146
 147 *NOTE:-* If using [[http://timidity.sourceforge.net/][Timidity]] for MIDI playback, kill the MIDI stream with C-g in Emacs
 148
 149 * Setup
 150 To use *ob-lilypond*, you must be on a *very recent* version of
 151 org-mode, (since it relies on a command that has been changed very
 152 recently) and will break on older versions (ob-lilypond is also
 153 included in the latest Org-mode by default).
 154
 155 For information on obtaining the latest Org-mode follow this link
 156 to the [[http://orgmode.org/manual/Installation.html][Org-mode Manual]] and follow the instructions.
 157
 158 Then, add lilypond to your list of babel languages (in your init
 159 file):
 160
 161 : (org-babel-do-load-languages
 162 :   'org-babel-load-languages
 163 :   '(
 164 :     (emacs-lisp . t)
 165 :     (sh t)
 166 :     (org t)
 167 :     (lilypond t)))
 168
 169 Alternatively you may *require* the ob-lilypond babel language directly:
 170
 171 : (require 'lilypond)
 172
 173 To ensure all is correct consider *running the tests* (see below).
 174
 175 * Requirements
 176
 177 ** Mac OS X
 178  - LilyPond may be [[http://lilypond.org/][downloaded here]]
 179
 180 ** Nix
 181   - LilyPond is [[http://lilypond.org/][available here]] or via the the system-relevant package manager.
 182   - For MIDI, *Timidity* is [[http://timidity.sourceforge.net/][available here]] or via the system-relevant package manager.
 183   - For pdf, *Evince* is [[http://live.gnome.org/Evince/Downloads][available here]] or via package manager.
 184
 185 ** Win32
 186  - Currently untested, although it should be made to work with minimal fuss.
 187
 188 * Testing
 189 Tests are provided and can be executed by running the following commands...
 190 (for more help and information on testing see [[file:../../../org-tests/index.html][Testing Org]].
 191
 192 : M-x load-file RET  testing/lisp/test-ob-lilypond.el
 193 : M-x ert t
 194
 195 * Issues
 196 Any issues should be reported to the [[http://orgmode.org][Org-mode Mailing-list]]
 197