# Combining text and music

If you want to create a document with lots of text and some small musical snippets, e.g. an exercise sheet or a musical analysis, what software can you use?

Of course it’s possible to do the entire project in LilyPond or another notation program, inserting passages of text between multiple scores – in LilyPond by combining \markup and \score sections:

\markup { "A first motif:" }
\score \relative c' { c4 d e f  g2 g }
\markup { "A second motif:" }
\score \relative c'' { a4 a a a  g1 }

However, it is clear that notation programs are not originally designed for that task, so many people prefer WYSIWYG word processors like LibreOffice Writer or Microsoft Word that instantly show what the final document will look like. In these text documents music fragments can be inserted as image files that can for example be generated with LilyPond from .ly input files. Of course these images are then static, and to be able to modify the music examples one has to manage the additional files with some care. That’s when things might get a little more complicated…

Wouldn’t it be a killer feature to be able to edit the scores directly from within the word processor document, without having to keep track of and worry about additional files? Well, you may be surprised to learn that this has already been possible for quite some time, and I take the relaunch of OOoLilyPond as an opportunity to show it to you.

## What is OOoLilyPond?

OOoLilyPond (OLy) is a LibreOffice extension that allows to insert snippets of LilyPond code into LibreOffice Writer, Draw and Impress documents and to transparently handle the rendering through LilyPond. So you can write LilyPond code, have that rendered as a score and be able to modify it again.

OOoLilyPond was originally written by Samuel Hartmann and had its first launch in 2006 (hence the name, as the only open-source successor of StarOffice was OpenOffice.org).
Samuel continued the development until 2009 when a stable version 0.4.0 with new features was released. In the following years, OLy was ocasionally mentioned in LilyPond’s user forums, so there might be several people who use it periodically – including myself. Being a music teacher, I work with it everyday. Well, almost…

In 2014 LilyPond had the new 2.19 release which showed a different behaviour when invoked by the command used in OLy. This lead to a somewhat mysterious error message, and the macro execution was aborted. Therefore it was impossible to use OLy with LilyPond’s new development versions. Of course, I googled that problem, but there was no answer.

Someday I wanted to get to the bottom of it. I’m one of those guys who have to unscrew anything they get their hands on. OLy is open source and published under GPL, so why hesitate? After some studying the code, I finally found that the problem was surprisingly small and easy to fix. I posted my solution on the LilyPond mailing list and also began to experiment with new features.

Urs Liska and Joram Berger had already contacted Samuel in the past. They knew that he did not have the time to further work on OOoLilyPond, but he would be glad if someone else could take over the development of the project.

Urs and Joram also contributed lots of work, knowledge and ideas, so that we were finally able to publish a new release that can be adapted to the slightly different characteristics of LibreOffice and OpenOffice, that can be translated into other languages, that can make use of vector graphics etc. This new take on the project now has its home within openLilyLib.

# How to get and install it

The newest release will always be found at github.com/openlilylib/LO-ly/releases where the project is maintained. Look for an *.oxt file with a name similar to OOoLilyPond-0.X.X.oxt and download it:

For anyone who doesn’t want to read the release notes, there’s a simple Download page as well.

In LibreOffice, open the extension manager (Tools -> Extension Manager), click the “Add” button which will open a file dialog. Select the *.oxt file you’ve just downloaded and confirm with the “Open” button.

When asked for whom you want to install the extension, you can choose “only for me” which won’t require administrator privileges on your system. After successful installing, close the extension manager, and probably you will be requested to restart LibreOffice.

Now LibreOffice will have a new “OLy” toolbar. It contains a single “OLy” button that launches the extension.

# Launching for the first time

Here we go: Create a new Writer document and click the OLy button. (Don’t worry if you get some error messages telling you that LilyPond could not be executed. Just click “OK” to close the message boxes. We’ll fix that in a moment.)

Now you should see the OOoLilyPond Editor window.

First, let’s open the configuration dialog by clicking the “Config” button at the bottom:

A new window will pop up:

Of course, you need to have LilyPond installed on your system. In the “LilyPond Executable” field, you need to specify the executable file for LilyPond. On startup, OLy has tried to guess its correct (default) location. If that didn’t work, you already got some error messages.  😉

For a Windows system, you need to know the program folder (probably C:\Program Files (x86)\LilyPond on 64-bit Windows or C:\Program Files\LilyPond on 32-bit Windows systems).
In the subfolder \usr\bin\ you will find the executable file lilypond.exe.

If you are working with Linux, relax and smile. Usually, you simply need to specify lilypond as command, without any path settings. As far as I know, that also applies for the Mac OS family which is based on Unix as well.

On the left side, there are two frames titled “Insert Images”. Depending on the Office version you are using (OpenOffice or LibreOffice), you should click the appropriate options.

For the moment, all remaining settings can be left at their default values. In case you’ve messed up anything, there’s also a “Reset to Default” button.

At the right bottom, click “OK” to apply the settings and close the dialog. Now you are back in the main Editor window. It contains some sample code, so just click the “LilyPond” button at the bottom right.

In the background, LilyPond is now translating the code into a *.png graphic file which will be inserted into Writer. The code itself is invisibly saved inside the document.

After a few seconds, the editor window should disappear, and a newly created image should show up.

# How to work with it

If you want to modify an existing OLy object, click on it to select it in Writer. Then, hit the “OLy” button.

The Editor window will show the code as it has been entered before. Here you can modify it, e.g. change some pitches (there’s also no need to keep the comments) and click the “LilyPond” button again. OLy will generate a new image and replace the old one.

To insert a new OLy object, just make sure that no existing object is selected when hitting the “OLy” button.

# Templates

In the Editor window, you might have noticed that you were not presented an entire LilyPond file, but only an excerpt of it. This is because OLy always works with a template. It allows you to quickly enter short snippets while not having to care about any other settings for layout etc.

The snippet you just created is based on the template Default.ly which looks (more or less) like this:

\transpose %{OOoLilyPondCustom1%}c c'%{OOoLilyPondEnd%}
{
%{OOoLilyPondCode%}
\key e \major
e8 fis gis e fis8 b,4. |
e2\fermata \bar "|."
%{OOoLilyPondEnd%}
}

\include "lilypond-book-preamble.ly"
#(set-global-staff-size %{OOoLilyPondStaffSize%}20%{OOoLilyPondEnd%})

\paper {
#(define dump-extents #t)
ragged-right = ##t
line-width = %{OOoLilyPondLineWidth%}17\cm%{OOoLilyPondEnd%}
}

\layout {
indent = #0
\context {
\Score
\remove "Bar_number_engraver"
}
}


In the Editor window, there are five text fields: the big “Code” area on top, and four additional small fields named “Line Width”, “Staff Size”, “Custom 1” and “Custom 2”. They contain the template parts that are enclosed by tags, i.e. preceeded by %{OOoLilyPondCode%}, %{OOoLilyPondLineWidth%}, %{OOoLilyPondStaffSize%}, %{OOoLilyPondCustom1%} and %{OOoLilyPondCustom2%} respectively, each terminated by %{OOoLilyPondEnd%}. (Those tags themselves are ignored by LilyPond because they are comments.)

All remaining parts of the template stay “invisible” to the user and cannot be changed. Don’t worry, you can modify existing templates and create your own.

A template must at least have a Code section, other sections are optional. There is a template Direct to LilyPond which only consists of a Code section and contains no “invisible” parts at all. You can use it to paste ordinary *.ly files into your document. But please keep in mind that the resulting graphic should be smaller than your paper size.

Most templates (the ones without [SVG] inside the file name) make use of \include "lilypond-book-preamble.ly which results in a cropped image. Any whitespace around the music is automatically removed.

Below the code view, there is a dropdown field that lets you choose which template to use. Of course, different templates have different default code in their Code sections.

When switching the template, the code field always will update to the corresponding default code as long as you haven’t made any edits yet. However, this will not happen automatically if you already made any changes. To have your current code replaced anyway, click the “Default Code” checkbox.

The “Edit” button will open a new dialog where you can edit the current template. Optionally, you can save it under a new file name.

# Easier editing

Probably you are used to a particular text editor when working on LilyPond files. Of course you can use it for OLy templates as well. The path to the template files can be found (and changed) in the configuration dialog. Here you can also specify where your text editor’s executable file is located. You can use any text editor like Mousepad, Notepad etc., but if you don’t yet know Frescobaldi, you really should give it a try.

Back in the main OLy window, another button might be useful: “Open as temp. file in Ext. Editor”. It saves the entire snippet into a *.ly file – not only the contents of the “Code” field, but including the other fields and the “invisible” parts between them. This file is opened in the external editor you’ve specified before. If you use an IDE like Frescobaldi, you can instantly preview your changes.

As soon as editing is finished, save your changes (without changing the file name). You can now close your external editor.

Back in OLy, hit the “Import from temp. file” button to load the updated file back into OLy. In the text fields you will recognize the changes you have applied. Hit the “LilyPond” button to insert the graphic into your document.

A word of caution: Only changes to the Code, Line Width, Staff Size, Custom 1 and Custom 2 fields are recognized. Changes to the “invisible” parts of the template are ignored! If you intend to modify those sections as well, you need to create a new template.

A very last word of caution: If you use a template that is modified or created by yourself, and you share your Office document with other collaborators, you have to share your template as well.

## To be continued…

OLy can be configured for using vector graphic formats (*.svg or *.eps) instead of *.png. They offer better quality, especially for printing. However, some additional things will have to be considered. This will soon be covered in a follow-up post.