# Running &lilypond;

## Creating PDF output

There are currently three different ways you can run &lilypond; on your document.

The default one (by pressing the toolbar button or Ctrl+M) is to output a PDF preview document. This document contains clickable notes and other objects. If you click on a note or other object, &frescobaldi; will put the text cursor in the correct place (and even open the document for you if needed). You can also select fragments of the &lilypond; input by clicking a note and then shift-clicking another one.

In the &lilypond; menu, you can also find the command Run &lilypond; (publish). This option also runs &lilypond;, but with clickable notes disabled. The resulting PDF is much smaller and better suitable for distribution via e-mail or the Web. With large musical scores, disabling the clickable notes can make the PDF many times smaller.

The third possibility is the command Run &lilypond; (custom). This option shows a dialog where you can set some parameters for this run, overriding default settings. If you have multiple versions of &lilypond; installed, you can choose which &lilypond; you want to run.

### The custom Run LilyPond dialog

The custom Run LilyPond dialog

While &lilypond; is running, you can follow its progress in the log view. If &lilypond; encounters errors, you can click on the messages to place the text cursor in the offending line and column. If there are many errors you want to correct without waiting for &lilypond; to be finished, you can click the &lilypond; button again to abort the running &lilypond; process.

When you want to run &lilypond; but your document has not been saved yet, or has been saved to a non-local directory, &frescobaldi; copies the document contents to a file in a temporary directory on you local drive, and then runs &lilypond; on it.

If your document is on the local drive but has been modified, &frescobaldi; asks you to save it first. (&frescobaldi; does not use a temporary directory for files that are already on the local drive.) If you want &frescobaldi; to always save your last local modifications before running &lilypond;, check the box "Don't ask this question again." (Under Settings Configure &frescobaldi;... you can re-enable this warning if you want.)

If &lilypond; created a PDF, you can open it in your default PDF viewer by clicking the Play/View toolbar button and selecting the file in the drop-down menu. You can print the PDF using the Print Music button. You can email all generated files (including source files) using File Email Documents .

## Creating MIDI output

If you want &lilypond; to create a MIDI file, add a `\midi { }` line in your `\score { }` section, like this:

    \score {
      \relative c'' {
        \time 7/4
        c2 bes4 a2 g a bes4 a( g) f2
      }
      \addlyrics {
        Join us now and share the soft -- ware!
      }
      \layout { }
      \midi { }
    }

Be sure to also add a `\layout { }` line if you add a `\midi { }` line, otherwise &lilypond; will not generate a PDF.

To play the generated MIDI file(s) in an external MIDI player, click the Play/View toolbar button and select the file from the drop-down menu. You can also use the built-in MIDI player.

### The built-in MIDI player

The built-in MIDI player can be started by clicking its tab at the bottom of the &frescobaldi; window or by pressing Meta+Alt+M. If a &lilypond; document generated multiple MIDI files, you can select which one to play. Use the small play and pause buttons to play the MIDI file.

The media keys (Play/Pause and Stop) and the Pause key can also be used to start or stop the music. If you pause the music using the Pause key, the music will automatically rewind a few seconds when you start the playing again.

The built-in MIDI player uses the embeddable MIDI player component of KMid version 2.4.0 or higher. If the MIDI player doesn't work it is recommended to run KMid once from the Applications menu to configure its sound settings.

## &lilypond; files that include other files

When working on large music scores, it might be possible that you divide the musical score in different files, and include them from a "master" file. Such a master file, named e.g. `NewSong.ly`, might look like:

    \version "2.12.0"

    \header {
      title = "New Song"
    }

    \include "LayoutSettings.ly"

    \include "SopranoPart.ly"
    \include "PianoPart.ly"

    \score {
      <<
        \new Staff = "soprano" \sopranoMusic
        \new Lyrics \lyricsto "soprano" \sopranoText
        \new PianoStaff <<
          \new Staff = "right" \rightHandMusic
          \new Staff = "left" \leftHandMusic
        >>
      >>
    }

The files `SopranoPart.ly` and `PianoPart.ly` just contain the music definitions and `LayoutSettings.ly` has some settings for font and page layout etc. Neither one of them has a `\score { }` section in it. So pressing Ctrl+M and running &lilypond; while you are working on such an included document might not make much sense, as it would probably not generate a PDF output file (the document only contains music expressions that are assigned to variables).

In such cases, you can tell &frescobaldi; that another file is the "master" file for the current document. When you run &lilypond;, &frescobaldi; will run &lilypond; on the master document rather than the current document. So in `SopranoPart.ly` and `PianoPart.ly` you add a special line that is just a &lilypond; comment. But &frescobaldi; will read the line and understand that you want &lilypond; to be run on the master file. Here is an example how `SopranoPart.ly` would look like:

    \version "2.12.0"

    % Soprano part

    sopranoMusic = \relative c' {
      c d e f g f e d
    }

    sopranoText = \lyricmode {
      Boer er ligt een kip in't wa -- ter
    }

    %%master: NewSong.ly

The last line `%%master: <filename>` directs &frescobaldi; to compile `NewSong.ly` instead of the current document when &lilypond; is started.

There are two related special comments: `%%master-preview:` and `%%master-publish:`. Those will only compile the named file in either preview or publish mode. That can be useful if you include several movements or e.g. hymns in a master file, where every source file has it's own score section. If you e.g. use `%%master-publish`, running in preview mode will just show the current document, but running in publish mode will compile the master document so you get a view on the whole score or book.

"Master" and include files only work with documents that are on your local hard drive.

## Using multiple &lilypond; versions

If you have multiple versions of &lilypond; installed you can add them to &frescobaldi; under &menu.settings.lilypond;. One of the &lilypond; instances can be set as the default. It is also possible to automatically start a &lilypond; instance with a version closest to the `\version` statement in your document. You can even download and install different binary releases of &lilypond; from within &frescobaldi;. See Settings Dialog, &lilypond; Preferences for more information.