(Frescobaldi 1.x User Guide)

Frescobaldi Manual

Frescobaldi is a light-weight, but powerful editor for LilyPond music files. This manual is written by Wilbert Berendsen and documents Frescobaldi version 2.0.5.

How to get help inside Frescobaldi

In many dialogs there are Help buttons or you can press the F1 key. Many user interface items also have "What's This" information which can be revealed by pressing Shift+F1 or by selecting Help→What's This.

Table of Contents

Introduction

⬀LilyPond is an open-source music engraving program, producing very high-quality sheet music printouts from fairly simple text input files. Input files can be created using virtually any text editor, which LilyPond can then compile and output beautiful engraving, by default but not restricted to, PDF.

Frescobaldi is an application to make editing LilyPond music scores faster and easier. You will still need to learn LilyPond's input language but if you read the Getting Started section of this User Guide, you'll pickup some LilyPond basics to get you started.

Once you have grasped the basics, the next step would be to use the LilyPond Learning Manual from ⬀LilyPond's excellent online documentation.

Getting Started

The default screen of Frescobaldi shows a text document on the left and an empty Music View window on the right.

Now, in the text view, enter some LilyPond code, like this: 

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

Then click the Lily toolbar button or press Ctrl+M. LilyPond will start to processes your file and the PDF will be displayed in the Music View on the right. If LilyPond encounters any errors or warnings they will be displayed in the LilyPond Log at the bottom of the screen.

The Music View has many possibilities:

When your music score is complete, run LilyPond once more but with clickable notes turned off: menu LilyPond→Engrave (publish). This significantly reduces the size of the PDF.

If LilyPond does not start at all, check if you have installed LilyPond correctly and that the lilypond command is in your system's PATH environment variable. If needed, provide the exact path to your LilyPond executable under Edit→Preferences→LilyPond Preferences.

If LilyPond encounters any warnings or errors in your document they will show up in the LilyPond Log window at the bottom of the screen. Frescobaldi will then highlight these lines in the text view where the errors are. Clicking the error in the Log Window or pressing Ctrl+E immediately brings the text cursor to the offending line in your text view. Pressing Ctrl+E again will move to the next error message, and so on. LilyPond will remove any previous error line highlights the next time it is run but you can also remove any error line markings manually with the option View→Clear Error Marks.

The Score Wizard

The Score Setup Wizard (Ctrl+Shift+N) in Tools→Setup New Score... is designed to quickly setup a LilyPond music score.

In the first tab, Titles and Headers, you can enter titling information.

In the second tab, Parts, you can compose your score out of many available part types. Doubleclick a part type to add it to your score (or click Add). Select the part in the score list to change some settings for the selected part, if desired. Many parts, especially Choir, have powerful options to set up the score the way you want it.

In the third tab, Score settings, global score properties and preferences can be set.

Click the Preview button to get a preview with some example music filled in. Click OK to copy the generated LilyPond source text to the editor.

Multiple pieces or movements

A special and powerful feature of the Parts tab is hidden in the "Containers" category in the part types list.

This category contains the Score, Book and Bookpart types, with which you can setup a LilyPond document containing multiple scores or even books. You may add Score, Bookpart or Book entries to the score view. They can be nested: a Score can be added to a Bookpart or Book but you can't add a Book to a Bookpart or a Score.

Then you can add musical parts. If you want to create multiple scores with exact the same parts, you can just add the parts to the top level of the score view, and then the scores, without adding musical parts to the scores. The scores will then use the parts in the top level of the score.

The Music View

The Music View displays the PDF document created by LilyPond.

When LilyPond was run in preview mode (i.e. with Point & Click turned on), the PDF contains a clickable link for every music object, pointing to its definition in the text document.

The Music View uses this information to provide smart, two-way integration with the text document:

You can also adjust the view:

You can copy music right from the PDF view to a raster image: Hold Shift and drag a rectangular selection (or use the right mouse button) and then press Ctrl+Shift+C or select Edit→Copy to Image... to copy the selected music as a raster image to the clipboard, a file or another application.

See also: Edit in Place, After engraving a score, the Music View does not show the music

Other Tools

Some other important tools are listed here.

The Quick Insert Panel

With the tools in the Quick Insert Panel you can add various music elements to the current note or selected music.

The Direction chooser specifies if articulations, dynamics or slurs appear in a neutral position (e.g. determined by stem direction), or above or below the staff by prepending a -, ^ or _ character.

Click on a tab to select a tool. You can cycle through the tools with Ctrl (or ⌘) and the mouse wheel. All buttons in the Quick Insert Panel have configurable keyboard shortcuts; you can change them by right-clicking a button.

Articulations

These musical symbols can be added to a note or rest or a selected range of music. If you add them to a selection, rests will be skipped. If there is no text selected, the cursor will automatically move to the next pitch, rest, skip or chord.

If Allow shorthands is checked, Frescobaldi will use short signs for articulations if they exist (e.g. -. instead of -\staccato).

Dynamics

Dynamics can also be added to a note or rest. If you select a range of music, you can add spanners which will automatically terminate at the last note, rest or chord in the selection. If you then click a sign, it will replace the terminator.

Spanners

This tool lets you add arpeggio, glissandos and other spanners like slurs, phrasing slurs, manual beams or trills.

Arpeggios and glissandos apply to the current note; they need no music to be selected. The slurs, beams or trill apply to the current note and the next one if no music is selected, or to the first and the last note or chord in the selection.

Bar Lines

Here you can insert bar lines or various breathing signs.

Snippets

With the snippets manager you can store often used pieces of text called "snippets", and easily paste them into the text editor.

The snippets manager can be activated via the menu Insert→Snippets... or by pressing Ctrl+T.

Snippets can be searched by browsing the list or by typing some characters in the search entry. Snippets can also have keyboard shortcuts applied to them. Some snippets have a special mnemonic (short name) which you can also type in the search entry to select the snippet. Pressing the Return key will then apply the snippet to the text editor and hide the snippets manager.

Add new snippets using Ins. Edit the selected snippet with F2. Remove selected snippets using Ctrl+Del. Warning: this cannot be undone!

Snippets can also be put in the menu (see Snippet editor). And finally, there are snippets which can include or alter selected text. Some snippets do this by using special variables, while others are small scripts written in Python.

Snippet editor

Here you can edit the text of the snippet.

If you start the first line(s) with '-*- ' (note the space), the remainder of that line(s) defines variables like name: value; or simply name; which influence the behaviour of the snippet. The following variables can be used:

menu
Place the snippet in the insert menu, grouped by the (optional) value.
template
Place the snippet in the menu File→New from Template, grouped by the (optional) value. When triggered via the menu, the snippet is inserted into a new document.
name
The mnemonic to type to select the snippet.
indent: no;
Do not auto-indent the snippet after inserting.
icon
The icon to show in menu and snippet list.
symbol
The symbol to show in menu and snippet list. Symbols are icons that use the default text color and can be found in 'frescobaldi_app/symbols'.
python
Execute the snippet as a Python script. See Python Snippets.
selection
One of more of the following words (separated with spaces or commas): yes: Requires text to be selected. strip: Adjusts the selection to not include starting and trialing whitespace. keep: Selects all inserted text.

The other lines of the snippet define the text to be inserted in the editor. Here, you can insert variables prefixed with a $. A double $ will be replaced with a single one. The following variables are recognized:

$ANCHOR
Selects text from here to the position given using the $CURSOR variable
$CURSOR
Moves the text cursor here after insert.
$DATE
The current date in YYYY-MM-DD format.
$DOCUMENT_NAME
The name of the current document.
$FILE_NAME
The full local filename of the current document.
$FRESCOBALDI_VERSION
The version of Frescobaldi.
$LILYPOND_VERSION
The version of the default LilyPond program.
$SELECTION
The selected text if available. If not, the text cursor is moved here.
$URL
The URL of the current document.
Python Snippets

Python snippets can read and should set the variable text. The variable text contains the currently selected text (which may be an empty string).

You may set text to a string or a list of strings.

Other variables that may be referenced:

state
A list of strings describing the type of text the cursor is at.
cursor
The current QTextCursor, giving access to the document. Don't change the document through the cursor, however.
CURSOR
When setting text to a list instead of a string, you can use this value to specify the place the text cursor will be placed after inserting the snippet.
ANCHOR
When setting text to a list instead of a string, this value can be used together with CURSOR to select text when inserting the string parts of the list.
main
When you define a function with this name, it is called without arguments, instead of inserting the text from the text variable. In this case you may alter the document through the cursor.
Maintaining a library of snippets

To keep a certain group of snippets manageable as a snippet library, you can of course prefix the snippet titles with some sort of special name. But a smarter way is to use a snippet variable.

It is suggested to use the "set" variable, and set it to the name of the library you want the snippet to belong to.

Then in the snippet manager, you can easily select all the snippets belonging to the library by entering :set name in the snippet search bar, where "name" is the name you want to use. And then e.g. export the snippets to an XML file for sharing the snippets with others.

Importing and exporting snippets

Snippets can be imported from and exported to XML files.

To export snippets, either select them in the snippet manager, or filter the snippets using the search bar and select none, so that all the snippets visible in the snippet manager are exported. Export the snippets by selecting Menu→Export..., and then choose a file name, preferably ending in .xml.

To import snippets, select Menu→Import... and choose the file you want to import. You may also drop an XML file on the snippet manager. A dialog will be displayed where you can select which snippets you want to import.

The XML format of the snippet library files is simple and documented inside the XML file.

Pitch manipulation

Frescobaldi offers the following pitch-manipulating functions, all in the menu Tools→Pitch:

Pitch language
This translates pitch names in the whole document or a selection.
Convert relative music to absolute
This converts all \relative music parts to absolute pitch names. It removes, but honours, octave checks.
Convert absolute music to relative
Checks all toplevel music expressions, changing them into \relative mode as soon as the expression contains a pitch. If you want to make separate sub-expressions relative, it may be necessary to select music from the first expression, leaving out higher-level opening braces.
Transpose

When transposing music, two absolute pitches need to be given to specify the distance to transpose over. The pitches may include octave marks. The pitches must be entered in the pitch name language used in the document.

The music will then be transposed from the first pitch to the second, just as the \transpose LilyPond command would do.

E.g. when transposing a minor third upwards, you would enter:
c es

To transpose down a major second, you can enter:
c bes,

or:
d c

It is also possible to use the transpose function to change a piece of music from C-sharp to D-flat, or to specify quarter tones if supported in the pitch name language that is used.

The transpose function can transpose both relative and absolute music, correctly handling key signatures, chordmode and octave checks.

Rhythm manipulation

The rhythm functions of Frescobaldi alter the durations written after notes, chords, rests, etcetera. Using those functions, all in menu Tools→Rhythm, it is possible to double or halve the length of notes, to add or remove dots and to remove scaling factors.

Also it is possible to change the way rhythm is specified: for every note (explicit), or only when the duration changes (implicit). Some users may prefer the option implicit per line, which always specifies the duration for the first note, chord or rest on a line.

The last three menu commands can copy, paste or apply a rhythm that is entered in a dialog.

In the "Apply Rhythm" dialog you can enter a series of durations, e.g.:

4. 8 4 16 16 8 2

which will then, repetitively, be applied to a selection of notes.

Lyrics

Frescobaldi can automatically place hyphens ' -- ' inside texts to make those texts usable as lyrics. It can use hyphenation dictionaries of OpenOffice.org, Scribus, etc.

To use this feature you must first select the text you want to hyphenate. Then press Ctrl+L or choose Tools→Lyrics. In the dialog that appears, select the language. Click OK or press Enter to have the hyphenation take place.

A small limitation is that word processor hyphenation dictionaries often don't want to break a word right after the first letter (e.g. 'a -- men'), because that does not look nice in word processor texts. So it can happen that you have to add some hyphens after the first letter of such lyrics.

There is also a command to remove hyphenation. This can be useful if you have a stanza of lyrics that you just want to display as a markup below the music. Under Edit→Preferences you can enter a list of directories to search for hyphenation pattern files.

The editor

In this part the features of the editor are discussed, e.g. how to control auto-indenting, how to use search and replace, etcetera.

Search and replace

In the menu Edit the commands Find (Ctrl+F) and Replace (Ctrl+H) can be found, which open a small window at the bottom of the view. It is possible to search for plain text or regular expressions.

Regular expressions are advanced search texts that contain characters that can match multiple characters in the document. When replacing text, it is also possible to refer to parenthesized parts of the search text.

In regular expression search mode, some characters have a special meaning:

*
matches the preceding character or group zero or more times
+
matches the preceding character or group one or more times
?
matches the preceding character or group zero or one time
[ ]
matches one of the contained characters
( )
group characters. This also saves the matched text in the group. When replacing, you can use characters like \1, \2 etcetera, to write the text of the corresponding group in the replacement text.
\\ \n \t \s \d \w
match, respectively, a backslash, a newline, a tab, any whitespace character, a digit, a generic word-like character.

A full discussion on regular expressions can be found in the ⬀Python documentation.

Document variables

Document variables are variables that influence the behaviour of Frescobaldi. They can be written in the first five or last five lines of a document. If a line contains '-*-', Frescobaldi searches the rest of the lines for variable definitions like name: value;.

The following variables are recognized:

mode: mode;
Force mode to be one of lilypond, html, texinfo, latex, docbook or scheme. Default: automatic mode recognition.
master: filename;
Compiles another LilyPond document instead of the current.
output: name;
Looks for output documents (PDF, MIDI, etc.) starting with the specified name or comma-separated list of names. More information.
coding: encoding;
Use another encoding than the default UTF-8.
version: version;
Set the LilyPond version to use, can be used for non-LilyPond documents.
tab-width: number;
The width of a tab character, by default 8.
indent-tabs: yes/no;
Whether to use tabs in indent, by default no.
document-tabs: yes/no;
Whether to use tabs elsewhere in the document, by default yes.
indent-width: number;
The number of spaces each indent level uses, by default 2.

You can put document variables in comments.

The "output" document variable

Setting this variable suppresses the automatic output file name determination and makes Frescobaldi look for output documents (PDF, MIDI, etc.) with the specified basename, or comma-separated list of names.

If a name ends with a directory separator, output files are looked for in the specified directory.

All names are relative to the document's filename.

For example:

\version "2.14.2"
% -*- output: pdfs/;
\book {
  \bookOutputName #(string-append "pdfs/" some-variable)
  \score {
    \relative c' {
      c d e f g
    }
  }
}

You can set this variable if the automatic output file name determination would be time-consuming (as Frescobaldi parses the document and all the documents it includes, searching for the LilyPond commands that specify the output name, such as \bookOutputName, etc); or when the automatic output file name determination does not work due to complicated LilyPond code.

Sessions

A session is basically a list of open files. At any time you can choose Session→Save or Session→New and save the current list of open files to a named session.

When you switch sessions, all current documents are closed first and then the documents of the other session are opened.

Inside the session properties dialog, you can choose whether to always save the list of open documents to that session, or to only save on creation (or via Session→Save). This can be useful if you want to keep the list of documents in session the same, even if you open or close documents while working.

You can also specify a default directory for the session.

See also: General Preferences

Preferences

In the Preferences Dialog (under Edit→Preferences) you can configure many aspects of Frescobaldi and LilyPond.

General Preferences

Under General Preferences, you can choose in which language Frescobaldi's user interface is translated, which user interface style you want to use, and whether you want to use the built-in Tango iconset or to use the system-wide configured icon set.

Language and style take effect immediately, but the new iconset is visible after Frescobaldi has been restarted.

Under Session to load if Frescobaldi is started without arguments you can configure which session to load if Frescobaldi is started without a filename. You can choose whether to start with one empty document, with the last used session, or with a specific session. See also Sessions.

Under When saving documents, you can choose what to do when a document is saved, such as remembering the cursor position and marked lines, or leaving a backup copy of the document (with a ~ appended). Also, you can specify a default folder in which you keep your LilyPond documents.

LilyPond Preferences

Here you can configure how LilyPond is run when you engrave your document.

If you have multiple versions of LilyPond installed you can specify them here, and configure Frescobaldi to automatically choose the right one, based on the version number that is set in the document (more info).

You can also configure how LilyPond is run. See the tooltips of the settings for more information.

Finally, you can specify a list of paths where the LilyPond \include command looks for files.

MIDI Settings

Here you can configure Frescobaldi's MIDI settings.

You can specify the MIDI port name to play to. If there are no port names visible in the drop-down box, it may be necessary to connect a hardware MIDI synthesizer to your computer, or to start a software synthesizer program such as TiMidity or Fluidsynth. On Linux, the synthesizer should be available as an ALSA MIDI device.

If you have a device with multiple ports, you can specify the first letters of the name, to have Frescobaldi automatically pick the first available one.

And finally, when using a software synthesizer it is recommended to enable the option Close unused MIDI output.

If checked, Frescobaldi will close MIDI output ports that are not used for one minute.

This could free up system resources that a software MIDI synthesizer might be using, thus saving battery power.

A side effect is that if you pause a MIDI file for a long time the instruments are reset to the default piano (instrument 0). In that case, playing the file from the beginning sets up the instruments again.

Helper Applications

In this page you can enter commands to open different file types. $f is replaced with the filename, $u with the URL. Leave a field empty to use the operating system default application.

For the e-mail setting, the command should accept a mailto: url. For the command prompt, the command should open a console window. A $f value is replaced with the directory of the current document.

Paths

Here, directories can be added that contain hyph_*.dic files, where the * stands for different language codes.

These hyphenation dictionaries are used by Frescobaldi to break lyrics text into syllabes.

LilyPond Documentation

Here you can add local paths or URLs pointing to LilyPond documentation. A local path should point to the directory where either the "Documentation" directory lives, or the whole "share/doc/lilypond/html/offline-root" path.

If those can't be found, documentation is looked for in all subdirectories of the given path, one level deep. This makes it possible to put multiple versions of LilyPond documentation in different subdirectories and have Frescobaldi automatically find them.

Keyboard Shortcuts

Here you can add keyboard shortcuts to all commands available. Also the Snippets or Quick Insert buttons that have keyboard shortcuts are listed here.

To change a keyboard shortcut, highlight an action in the list and click the Edit button, or double-click an action. In the dialog that appears, you can enter up to four shortcuts for the action by clicking the button and typing the shortcut.

You can define a new scheme by using the New button.

Fonts & Colors

Here you can set the editor font (a monospace font is recommended) and all colors.

The first item lets you set the colors for the text editor backgroud, foreground, selection background, the current line, line markings, the paper color in the Music View, etcetera.

The second item lets you set color and other attributes of the general highlighting styles, e.g. keyword, variable, value, comment, etcetera.

The other items contain the types of text the syntax highlighter recognizes for every particular document type Frescobaldi supports. Some of these types inherit a general style. It is possible to set the attributes bold, italic, underline and the foreground, background and underline color.

You can define a new scheme by using the New button.

Tools

Here you can change the settings for various tools.

Troubleshooting

Sometimes things don't go the way you would expect; this section may give some solutions.

After engraving a score, the Music View does not show the music

  1. Does the \score block have a layout section?

    If a \score block has a \midi section but no \layout section, no PDF output is generated.

  2. Do you use an exotic way to specify the output filename?

    Frescobaldi is able to determine the output file names by looking at the document's filename and the various LilyPond commands that specify the output filename or -suffix. Frescobaldi even searches \include files for commands like \bookOutputName and \bookOutputSuffix.

    But if you use more complicated Scheme code in your document to specify the output filenames, Frescobaldi may not be able to correctly determine those filenames.

    In that case you can override the base name(s) using the output document variable.

See also: Document variables

How to generate a MIDI file?

By default, LilyPond creates only a PDF file of the music. To create a MIDI file, you must wrap the music in a \score block and add a \midi block to it.

For example:

\version "2.14.2"

music = \relative c' {
  c4 d e f g2
}

\score {
  \music
  \layout {}
  \midi {}
}

If you omit the \layout block, no PDF file will be generated, only a MIDI file.

About Frescobaldi

Frescobaldi is named after ⬀Girolamo Frescobaldi (1583 – 1643), an Italian organist and composer.

Frescobaldi's homepage is at ⬀www.frescobaldi.org and there is a mailinglist at frescobaldi@googlegroups.com (⬀more info).

Credits

Frescobaldi's main author is Wilbert Berendsen.

Frescobaldi is written in ⬀Python and uses the ⬀Qt4 toolkit.

The Music View is powered by the ⬀Poppler library by Kristian Høgsberg, Albert Astals Cid and others.

Most of the bundled icons are created by ⬀The Tango Desktop Project.

Frescobaldi is translated into the following languages:

Braziliaans Portugees: Édio Mazera

Duits: Henrik Evers, Georg Hennig, Markus W. Kropp

Frans: Raphaël Doursenaud, Philippe Massart, Valentin Villenave, Yann Collette, David Bouriaud, Ryan Kavanagh

Galicisch: Manuel A. Vázquez

Italiaans: Gianluca D'Orazio

Nederlands: Wilbert Berendsen

Pools: Piotr Komorowski

Russisch: Sergey Poltavski, Artem Zolochevskiy

Spaans: Francisco Vila

Tsjechisch: Pavel Fric

Turks: Server ACİM

Contributing

Frescobaldi is a ⬀Free Software project to create a user friendly LilyPond music score editor. The goal is to make Frescobaldi available on all major platforms.

Frescobaldi is developed in a public GitHub repository at ⬀github.com/wbsoft/frescobaldi. There you can browse or checkout the source code and report bugs and wishes.

You can contribute by simply using Frescobaldi and reporting bugs and suggestions. Translations are also very welcome. How to create new translations is described in the file README-translations in the source distribution of Frescobaldi. If you want to add functionality you can find information about the source code structure in the file README-development.

History of Frescobaldi

Frescobaldi has its roots in LilyKDE, which was a plugin for KDE3's editor Kate. LilyKDE was written in Python and released in 2007 on Christmas.

When KDE developed version 4, it was not immediately possible to make Kate plugins in Python. So LilyKDE became a standalone application, wrapping the Kate texteditor part, and was renamed to Frescobaldi. It still used the Okular KDE part to display PDF documents. Frescobaldi 0.7 was the first public release, on Christmas 2008. On Christmas 2009 version 1.0.0 was released and on Christmas 2010 version 1.2.0.

At that time it was decided to move away from the KDE4 libraries and just use Python and Qt4 which are easily available on all major computing platforms. Frescobaldi 2.0 is a complete rewrite from scratch. Its release date is targeted at Christmas 2011.

Automatically choose LilyPond version from document

If this setting is enabled, the document is searched for a LilyPond \version command or a version document variable.

The LilyPond version command looks like:

\version "2.14.0"

The document variable looks like:

-*- version: 2.14.0;

somewhere (in a comments section) in the first or last 5 lines of the document. This way the LilyPond version to use can also be specified in non-LilyPond documents like HTML, LaTeX, etc.

If the document specifies a version, the oldest suitable LilyPond version is chosen. Otherwise, the default version is chosen.

See also: Document variables

Edit in Place

In this dialog you can edit one line of the text document.

Click OK or press Ctrl+Return to place the modified text in the document.

You can open the "Edit in Place" dialog by Shift-clicking a clickable object in the Music View or by right-clicking the object and selecting Edit in Place.

Nederlands, Español, Français, Italiano, Český | Last Modified: 01 mei 2012