User:Crantila/FSC/Typesetting/LilyPond

!! Somewhere in here, I have to mention bar- and octave-check devices !!

Links to Files for This Tutorial

 * Counterpoint (LilyPond)
 * [[File:FSC-counterpoint.pdf]]
 * Orchestra (LilyPond)
 * [[File:FSC-orchestra.pdf]]
 * Piano (LilyPond)
 * [[File:FSC-piano.pdf]]

What LilyPond Is
LilyPond is a notation engraving program, with a focus on creating a visually appealing product. LilyPond is text-based, and allows you to focus on the (semantic?) content of your musical scores, rather than on their visual appearance. Conventional commercial notation engraving programs allow users to edit the score visually. While this approach has its benefits, especially because it's very easy to see exactly what the printed score will look like, it also has disadvantages - chief among these is the fact that users of those programs are constantly worrying about what their score looks like.

This is where LilyPond comes in - users don't need to worry about how their score will work, because they know that the expertly-crafted methods of LilyPond will automatically configure the objects on the score so that they look good, and are easy to read. LilyPond's users focus on what needs to be displayed, rather than on how it is going to be displayed.

As with any particular approach, the LilyPond approach is not for everybody. However, once you have become accustomed to working with the software, and once you have learned methods to help deal with problems and organize your scores' source-files, you will probably realize that LilyPond is both much faster, and much more flexible, than traditional, commercially-available music engraving programs.

It is the goal of this guide to help users more quickly overcome the initial learning handicap incurred because of the text-based approach. Making use of tools such as the Frescobaldi text-editor will help to increase productivity, to make trouble-shooting easier, and to ease the memory burden associated with the text-based approach.

How LilyPond Works
LilyPond itself can be thought of as a highly-skilled automobile mechanic with a well-equipped toolbox. Regardless of the problem presented to the mechanic, they will automatically know which tools to use. Some of their tools are available elsewhere, and some are quite basic, but it is not the tools themselves that gives the mechanic their power, but rather the ways in which the mechanic uses the tools. Similarly, LilyPond is run as a single program (as you would consult a single mechanic), but it employs a multitude of tools - some available elsewhere, but others specialized, so that the resulting output is useful to us in some way.

In order to create meaningful output with LilyPond, we need to provide it meaningful instructions, and this we do in text files with the *.ly extension. These instructions will tell LilyPond which tools to use, when, and with what settings. Sometimes, we will need to change LilyPond's default settings; this is intimidating at first, but really we are just providing more specific instructions for what we want LilyPond to do. To return to the mechanic metaphor: not only would you be able to ask for repairs, but you will be able to ask for specific components or specific methods of installation; once you realize the power, flexibility, and easiness that is changing LilyPond settings, you will have truly unleashed its power.

Other Features

 * Put fragments of music into texts with without cutting and pasting pictures. Integrate music into LaTeX or HTML seamlessly, or add music to OpenOffice.org with ooolilypond.
 * Multi-platform
 * Flexibility (part-extraction, stuff)

The LilyPond Approach
For an extensive explanation of the following section, please see the official LilyPond documentation, from where this was sourced.

?? LilyPond works by separating the tasks of what to put, and where to put it. Each aspect of an object's positioning is controlled by a specific plug-in. Although software using "plug-ins" often results in messy and uncooperative plug-ins, such is not the case with LilyPond. You can think of the plug-ins as tools. LilyPond knows how and when to use each tool; if it doesn't know enough about a tool, then it isn't used, so there's no concern about half-baked plug-ins that work for one person in one situation, but for nothing else. ??

Before LilyPond places an object, it first considers many different possibilities for the specific alignment and layout of that object. Then it evaluates the possibilities according to aesthetic criteria set out to reflect those used in hand-engraved notation. After assigning each possibility a score representing how closely it resembles to the aesthetic ideal, LilyPond then chooses the least problematic possibility.

LilyPond Basics
At its heart, LilyPond's syntax is designed to offer the most flexibility through the most diverse musical conditions. Over time, you will realize that features which seem too complex at first are really a very powerful and simple way to solve complex problems that commercial programs can't attempt.

Letters Are Pitches
One letter is all that's required to create a note in LilyPond. There are additional symbols and letters that are added to indicate further details, like the register, and whether the note is "sharp" or "flat."

Although it can be changed, the default (and recommended) way to indicate "sharp" or "flat" is by using Dutch note-names: "-is" to indicate a sharp, and "-es" to indicate a flat. For example, the following command would create b-double-flat, b-flat, b, b-sharp, and b-double-sharp: beses bes b bis bisis Getting used to these names happens quickly, and they take less time to input than the English alternative. Furthermore, with these names, it becomes possible to sing note-names when you are ear training!

Pitch can be entered either absolutely, or relative to the preceding notes. Usually (for music without frequent large leaps) it is more convenient to use the "relative" mode. The symbols, and ' (comma and apostrophe) are used to indicate register.

When entering pitches absolutely, the register is indicated mostly as in the Helmholtz system: octaves begin on the pitch "C," and end eleven tones higher on the pitch "B." The octave below "middle C" (octave 3 in Scientific Pitch Notation) has no commas or apostrophes. The octave starting on "middle C" (octave 4) has one apostrophe; the octave above that (octave 5) has two apostrophes, and so on. Octave 2 (starting two octaves below "middle C") has one comma, the octave below that has two commas, and so on. It is usually not necessary to understand how to use this in LilyPond, or to be able to use it quickly, because most scores will use "relative mode."

When entering pitches relative to the previous one, the register is still indicated with commas or apostrophes, but usually none are needed. When using this input mode, the octave of each note is guessed based on the octave of the previous note. Think of it this way: the next note will always be placed so it produces the smaller interval. For example, after a C, an E could be placed as a major third, a minor sixth, a major tenth, a minor thirteenth, and so on. In relative mode, LilyPond will always choose the "major third" option. If you wanted LilyPond to notate the E so that it's a minor sixth, you would tell LilyPond with a comma appended:  so that LilyPond knows what you want. It's the same case if you were to input  (meaning "C then A-flat"): the A-flat will be notated so that it is a major third from the C; if you wanted LilyPond to notate it so that the A-flat is a minor sixth higher than the C, you would need to append an apostrophe:

The only possible ambiguity with this is with a tritone. LilyPond solves this by not recognizing "tritones," per se, and thinking of them as "augmented fourth" or "diminished fifth." Unless instructed otherwise (with a comma or apostrophe), LilyPond will always notate the interval as an augmented fourth.

You must always indicate a sharp or flat, even if it is already in a key signature. This ultimately helps to reduce the number of errors.

Letters used to indicate pitch are always in lower-case.

Numbers Are Durations
A number appended to a letter is understood by LilyPond to indicate that note's note-value. A whole note is indicated with a 1, and all other notes with a number representing the fraction of a whole note that they occupy: half notes are 2 (like "1/2 note"); quarter notes are 4 (like "1/4 note"); eighth notes are 8 (like "1/8 note") and so on.

To add a "dot" to a note (thereby increasing its length by one half), you simply include a period after the number. For example,  means "dotted quarter note on E."

To add a "tie" from one note to the next (thereby continuing its duration across a measure-line), add a tilde ( ~ ) after the pitch and duration.

After indicating a duration, it is assumed that all subsequent notes have the same duration, until indicated otherwise.

Articulations
Many different symbols are used to tell LilyPond to add articulation signs to a note. They are all appended after the pitch and (if included) duration, and many have a position indicator, too.

A full list of articulation markings is available in the LilyPond manual, and Frescobaldi remembers most of them for you (they are stored in the left-side panel).

These are some of the most common articulation marks, which use a position indicator unless specified otherwise:
 * ( to begin a slur (no position indicator)
 * ) to end a slur (no position indicator)
 * ~ to begin a tie (which needs no end; no position indicator)
 * . for a staccato mark
 * > for an accent
 * - for a tenuto mark
 * ^ for a marcato mark
 * _ for a portato mark (dot and line)

There are three position indicators: These position indicators will sometimes result in notes like:,  , and  , but although this may look incorrect, it is perfectly acceptable.
 * - which means to put the articulation mark wherever LilyPond thinks it makes sense
 * _ which means to put the articulation mark below the note-head
 * ^ which means to put the articulation mark above the note-head

Simultaneity
Simply put, anything enclosed inside < > is considered by LilyPond to happen simultaneously. This can be used in any context (and any Context - see above/below). It is possible to tell LilyPond that you want two notes to happen at the same time in the same voice (yielding a chord), at the same time on the same staff (yielding polyphony), and so on. Moreover, any score with multiple staves will use < > to tell LilyPond that the parts should begin at the same time, and creative use of < > is one of the keys to advanced notation.

It is not important to understand simultaneity at first. By observing how Frescobaldi creates scores for you, and how examples on the internet take advantage of these symbols, you will eventually understand how to use them.

Chords
Making use of the < > idea to indicate simultaneity, if a note has multiple pitches indicated between then LilyPond assumes that they are in a chord together. Notating a single chord with single < > brackets has two advantages: firstly, it is easier to see that they are a chord and not something more complex; secondly, it allows you to enter information more clearly.

Consider the following examples, which should produce equivalent output: <-5 b d>> 4->-5 With the first example, it is more difficult to see the chord notes, the duration, and what the "5" means. With the second example, it is easy to see that the chord notes are a G, a B, and a D, that they have quarter-note duration, and that the "5" is actually a fingering indication.

There is another advantage to using for notation of simple chords: they preserve logical continuity in "relative" mode. The following note will always be notated as relative to the lowest note in the chord, regardless of how many octaves the chord covers. This is not true with < >, where where following notes will be notated as relative to the last note between the < >.

Commands
There are a wide variety of commands available in LilyPond, some of them quite simple, and other quite complex. They all begin with a backslash, followed by the name of the command, and subsequent "arguments" that give the command further information about what you want it to do. Just like using a letter to indicate a note, commands are simply another way for you to tell LilyPond how you want your score to be rendered.

For example,  and   are two commands that you are likely to use quite often. They happen to do precisely what it seems like they should: time changes the time signature and metre, and clef changes the clef. they belong to differen contexts (time applies for the whole Score, but clef for only one Staff).

It can take some time to remember even these basic commands and the way you should format their input, and this is where Frescobaldi's built-in documentation viewer can help out. All of the official LilyPond documentation is made available in Frescobaldi, which makes it easy for you to view the documentation and make changes to your score in the same window of the same application.

Customization
It is rarely necessary to customize LilyPond's output in a way that is very specific, and not allowed for in the standard LilyPond syntax. As a beginner, this can happen quite often when you are trying to exactly emulate the look of a pre-existing score. Remember that LilyPond provides a content-focussed way to express music, and that it will usually produce meaningful output without advanced interference. If in doubt about whether a customization is really necessary, ask yourself this: will it change the music that is played from the score?

If you really must customize some setting, then keep in mind these two points:
 * 1) Tinkering with LilyPond can become as complex as you want.
 * 2) Ultimately all tinkering takes the form of commands.

Searching the internet for LilyPond tips and tricks can be a life-saver, but it can also lead to needlessly complex solutions. Sometimes this is the result of poor solutions being posted on the internet, but more often it is the result of LilyPond's ongoing development, which makes better solutions available regularly. For this reason, it is recommended to search the official LilyPond documentation first, then the "LilyPond Snippet Repository" (LSR - link here), and then Google.

Contexts
Another aspect of LilyPond that often confuses beginners is the idea of "contexts." It is an essential concept for modifying default behaviour. Like everything in LilyPond, it makes perfect sense: "context" means "context." The three primary contexts are "Voice," "Staff," and "Score." Everything that happens in a score happens in a context - it's just that simple - everything happens in a context! Everything that happens in a score happens in Score context, everything that happens on a staff happens in a Staff context, and everything that happens in a voice happens in a Voice context.

To help clear things up a little, here are three examples:  Where does the title of a composition belong? Does it belong on the score? Yes, so it belongs in the Score context. Does it belong on a staff? No, so it doesn't belong in a Staff context. Does it belong in a voice? No, since it would have to be on a staff to be in a voice. The composition's title doesn't belong on a staff or in a voice, but it does belong on the score, so we say that it happens in the Score context. Where does a clef belong? Does it belong on the score? Yes, because it is a part of notation.</li> Does it belong on a staff? Yes, because it wouldn't make sense to have a clef off a staff.</li> Does it belong in a voice? No, because it's not related to a specific "line" or voice.</li></ol> Clefs usually belong on the staff, at the beginning of every line, so we say that they happen in a Staff context.</li> Where does a note-head belong? Does it belong on the score? Yes, because it is a part of notation.</li> Does it belong on a staff? Yes - even if it's on a ledger line, note-heads are meaningless unless they're on a staff.</li> Does it belong in a voice? Yes, because one particular musical line is indicated primarily with note-heads.</li></ol> Note-heads belong to a particular voice, so we say they happen in a Voice context.</li> </ol>

To help further clarify, consider the following:
 * As in the real world, objects in LilyPond can potentially happen in any context...
 * (like a doorknob on a door)
 * (like a bus driver sitting in a bus' drivers' seat)
 * (like a person buying groceries at a supermarket)
 * (like a flat-sign next to a note-head)
 * ... some contexts are unusual, but make sense...
 * (like a doorknob on a wall, if the wall is designed to look like a door)
 * (like a bus driver sitting in a passenger seat, if they are going to the garage)
 * (like a person buying groceries from a corner store, if the supermarkets are closed)
 * (like a flat sign in a paragraph of text, if that paragraph describes what flat signs do)
 * ... and some contexts do not make sense, but can still happen...
 * (like a doorknob on a television)
 * (like a bus driver serving patrons at a restaurant)
 * (like a person buying groceries at a governmental office)
 * (like a flat sign in the top corner of a score, where the page number should be)

Because LilyPond's designers wisely decided that they could not conceive of all the possible uses for something, they allowed any plug-in/engraver/tool to be used in any context(?? I think ??). Furthermore, they decided that a Context should be allowed to happen within another Context, which makes sense - a Voice context only makes sense if it appears on a Staff, and a Staff only makes sense if it appears in a Score.

So, when trying to sort out the context in which something should apply, ask yourself exactly that: "In what context does this apply?" Beams and flags happen in one voice, accidentals apply to a whole staff, and tempo markings apply to the whole score. Although it may take some careful thought to get used to the idea, contexts ultimately make perfect sense.

Source Files and Their Formatting
Source files are the text files prepared with instructions telling LilyPond the content of the score you want it to create. They are so called because these files are the "source" of what you wish to create. As with programming languages, the text inside these files is often referred to as "source code." It sounds scary to think that you must edit code in order to use LilyPond, but "code" just means that it isn't normal English (or insert-language-here).

The particular formatting (the placement of tabs, spaces, and newlines) is not determined by LilyPond, but by individual users. This can be a headache when you encounter somebody else's formatting, but it is one of the keys to LilyPond's flexibility. This Guide uses a very specific style of formatting, but it should be understood that this is simply the style of one user, affected by their experiences, and the tasks they usually perform in LilyPond.

You will eventually develop your own style, better-suited to the kinds of tasks that you accomplish. When you do this, there is only one rule to keep in mind: be consistent within source files. When source files are programmed in a consistent way, it means that anybody who wants to use those files (like yourself, in the future) will easily be able to determine how they are organized.

Organizing Files, and Where to Put the Notes
LilyPond files are constructed as a series of commands. For better or worse, LilyPond's interpreter allows a great deal of flexibility when it comes to source file setup. This can lead to confusion about where things should be done, especially when using automated score-setup tools like Frescobaldi.

The generic structure of a LilyPond source file is this: \version "whatever_version"

\header { things like title, composer, and so on }

\score { \new Staff {   notes can go here } \layout { }

and so on }

Confusion arises here: for maximum flexibility, LilyPond allows source files to create its own commands. On hearing this, you may think, "Okay that's it - I don't need advanced commands or any of this stuff, so I'm packing it in and just using Finale!" There's no need to do that just yet - commands are easy! Think of commands - whether you wrote them or they were included with LilyPond - as a means of text-substition.

It works like this:
 * 1) You "define" (create) a command with the form
 * 2) You can then use the command anywhere below that, as many times as you want, by writing   in your source file.  When LilyPond processes that portion of text, it will instead see whatever you wrote in the definition.

It's as easy as 1-2!

Frescobaldi (along with most LilyPond users) take advantage of this functionality to provide well-organized, easy-to-use source files.

Here is a good template source file, that might be created for you by Frescobaldi: \version "2.12.2"

\header { title = "Example" }

violin = \relative c'' { \key c \major \time 4/4 % Music follows here. }

\score { \new Staff \with {     instrumentName = "Violin" }   \violin \layout { } }

This source file makes use of many commands, and even defines "violin" for its own use. It may not be easy to see from this simple example, but keeping your notes separated from the formatting of a complex \score section will greatly improve the readability of both sections. Furthermore, you will easily be able to search through thousands of lines of source file to find the section that you want.

So where do the notes go? In this template, they should go in the "violin" section. Frescobaldi usually marks this off with a friendly comment, stating "% Music follows here." That's exactly what it means: most of your time will be spent working with what follows there.

As a final note, I would like to give a warning against removing the "layout" section of the "score" section. The "layout" section for a particular score may or may not be empty, but it must always be there. Removing it would cause LilyPond not to render a score as output.

Installation

 * 1) Run   or use PackageKit or KPackageKit to install the "lilypond" package.
 * 2) Review the dependencies; it will want to install a lot of things called lilypond-*-fonts
 * 3) LilyPond can be run from the command-line, as 'lilypond'

It is recommended that you use the "Frescobaldi" text editor, which is designed specifically for use with LilyPond. It has many features that help to enhance productivity when editing LilyPond files, and which greatly speed up the learning process. Please see this section of the Musicians' Guide for help installing Frescobaldi.