LilyPond – Beginnershandleiding

Appendices

1 Leerboek

Dit hoofdstuk is de basisinleiding voor het werken met LilyPond.

1.1 Het compileren van een bestand

Deze paragraaf introduceert het “compileren”—het verwerken van LilyPond-invoerbestanden (geschreven door jouzelf) voor het produceren van uitvoerbestanden.

1.1.1 Invoer schrijven

“Compileren” is de term die gebruikt wordt voor het verwerken van een invoerbestand in LilyPond-formaat voor het produceren van één of meer uitvoerbestanden. Uitvoerbestanden zijn gewoonlijk PDF (om te printen of te bekijken), MIDI (om af te spelen), en PNG (for online gebruik). LilyPond-invoerbestanden zijn gewone tekstbestanden.

Dit is een voorbeeld van een eenvoudig invoerbestand:

\version "2.23.3"
{
  c' e' g' e'
}

De grafische uitvoer is:

LilyPond-invoer is hoofdlettergevoelig. ‘{ c d e }’ is geldige invoer; ‘{ C D E }’ zal een foutmelding geven.

Het produceren van uitvoer

Hoe je uitvoer produceert, is afhankelijk van je operating systeem en van de programma’s die je gebruikt.

• MacOS X (grafisch)
• Microsoft Windows (grafisch)
• Alle operating systemens (commandoregel)

Er zijn verscheidene andere tekst-editors beschikbaar met specifieke LilyPond-ondersteuning. Voor meer informatie, zie Eenvoudiger bewerken.

1.1.2 MacOS X

Stap 1. Maak je ‘.ly’-bestand

Dubbelklik de LilyPond.app, een voorbeeldbestand wordt geopend.

Uit de menu’s links bovenaan je scherm, kies Bestand > Opslaan.

Kies een naam voor je bestand, bijvoorbeeld ‘test.ly’.

Stapp 2. Compileer (met LilyPad)

Uit dezelfde menu’s, kies Compile > Tyepset.

Een nieuw venster opent en toont een voortgangslog van de compilatie van het bestand dat je zojuist hebt opgeslagen.

Stap 3. Bekijk de uitvoer

Zodra de compilatie klaar is, wordt een PDF-bestand gemaakt met dezelfde naam als het originele bestand en dat wordt automatisch geopend in de standaard PDF-viewer en op je scherm getoond.

Andere commando’s

Een nieuw LilyPond bestand maken, doe je door het kiezen van Bestand > Nieuw

of je opent met Bestand > Openen een bestaand bestand om te bewerken.

Als je een bestand bewerkt hebt, moet je het eerst opslaan voordat je Compile > Typeset doet en als het PDF-bestand niet wordt getoond, controleer dan het venster met de voortgangslog op foutmeldingen.

Als je geen gebruik maakt van de standaard Preview PDF-viewer die onderdeel is van het Mac Operating systeem en je hebt het PDF-bestand van een vorige compilatie nog open staan, dan kan het zijn dan alle volgende compileerpogingen niet slagen in het genereren van een nieuwe PDF totdat je het originele venster sluit.

1.1.3 Windows

Stap 1. Maak je ‘.ly’-bestand

Dubbelklik het LilyPond ikoon op je Bureaublad, een voorbeeldbestand wordt geopend.

Kies uit de menu’s bovenaan het voorbeeldbestand Bestand > Opslaan als. De optie Bestand > Opslaan kun je voor dit voorbeeldbestand niet gebruiken als je het nog geen geldige LilyPond-naam hebt gegeven.

Kies een naam voor je bestand, bijvoorbeeld ‘test.ly’.

Stap 2a. Compileer (door slepen en neerzetten - drag and drop)

Afhankelijk van wat je voorkeur heeft, compileer je je bestand door ofwel:

te slepen en neer te zetten bovenop het LilyPond ikoon, ofwel

met de tweede muisknop op het bestand te klikken en uit het popup-contextmenu Open met > LilyPond te kiezen.

Stap 2b. Compileer (door te dubbelklikken)

Of dubbelklik het ‘test.ly’ bestand.

Stap 3. Bekijk de uitvoer

Tijdens het compileren van het ‘test.ly’ bestand, wordt een commandovenster geopend dat zich na korte tijd weer sluit. Tijdens dit proces worden drie extra bestanden aangemaakt.

Het PDF-bestand bevat het gegraveerde ‘test.ly’ bestand.

Andere commando’s

Om een nieuw bestand te maken, kies Bestand > Nieuw vanuit een eerder gemaakt bestand of gebruik Bestand > Openen om een eerder gemaakt bestand te openen en te bewerken.

Als je een bestand bewerkt hebt, moet je het eerst opslaan voordat je het compileert en als het PDF-bestand niet wordt aangemaakt, controleer dan het venster met de voortgangslog op foutmeldingen.

Dit logbestand wordt elke keer overschreven als je je LilyPond-bestand compileert.

Het PS-bestand wordt LilyPond intern gebruikt als tussenstap om het PDF-bestand aan te maken, je kunt het verder negeren. Dit bestand wordt ook elke keer overschreven als je je LilyPond-bestand compileert.

Als je je bestand bekijkt met een PDF-viewer, dan moet je de PDF sluiten als je een nieuwe compilatie wilt doen omdat het genereren van een nieuwe PDF kan mislukken zolang je de oude nog aan het bekijken bent.

1.1.4 Commandoregel

Stap 1. Maak je ‘.ly’-bestand

Maak een tekstbestand met de naam ‘test.ly’ en vul het met:

\version "2.22.1"
{
  c' e' g' e'
}

Stap 2. Compileren (op de commandoregel)

Om het ‘test.ly’-bestand te compileren, typ op de commandoregel:

lilypond test.ly

Je ziet dan iets dat lijkt op:

GNU LilyPond 2.22.1
Verwerken van `test.ly'
Ontleden...
Vertolken van muziek...
Voorbewerken van grafische objecten...
Berekenen van 1 pagina-afbreek brokken...[1: 1 pagina's]
Tekenen van systemen...
Opmaakuitvoer naar `test.ps'...
Converteren naar `./test.pdf'...
Success: compilation successfully completed

Stap 3. Bekijk de uitvoer

Je kunt het resulterende ‘test.pdf’-bestand bekijken of printen.

1.2 Het schrijven van invoerbestanden

Deze paragraaf introduceert de LilyPond basissyntax om je op weg te helpen bij het schrijven van invoerbestanden.

1.2.1 Eenvoudige notatie

LilyPond kan bepaalde notatie-elementen automatisch toevoegen. In het volgende voorbeeld hebben we slechts vier toonhoogten ingevoerd, maar LilyPond heeft een muzieksleutel, een maatsoort, en nootlengtes toegevoegd.

{
  c' e' g' e'
}

Dit gedrag kan worden veranderd, maar in de meeste gevallen zijn deze automatische waarden heel handig.

Toonhoogten

Terminologie: pitch, interval, scale, middle C, octave, accidental.

De meest eenvoudige manier voor het invoeren van noten is de \relative modus. In deze modus wordt het octaaf automatisch gekozen door de aanname dat een opvolgende noot altijd zo dicht mogelijk bij de vorige noot geplaatst moet worden, d.w.z., hij wordt geplaatst in het octaaf dat binnen drie notenbalk-ruimtes ten opzichte van de vorige noot valt. We beginnen met het invoeren van het meest elementaire stuk muziek, een toonladder, waarin elke noot precies één notenbalk-ruimte hoger is dan de vorige noot.

% zet het beginpunt op de centrale C
\relative {
  c' d e f
  g a b c
}

De eerste noot is de centrale C. Elke volgende noot wordt zo dicht mogelijk geplaatst ten op zichte van de vorige noot – of anders gezegd, de eerste c is de C het dichtst bij de centrale C. Die wordt gevolgd door dichtstbijzijnde D ten opzichte van de vorige noot. We kunnen melodieën maken die grotere intervallen hebben, nog steeds uitsluitend gebruikmakend van de \relative modus:

\relative {
  d' f a g
  c b f d
}

De eerste noot van de melodie hoeft niet te beginnen met de noot die de begintoonhoogte aangeeft. In bovenstaand voorbeeld is de eerste noot – de d – de dichtstbijzijnde D bij de centrale C.

Door het toevoegen (of weghalen) van apostrofs ' of komma’s , van het ‘\relative c'’-commando, kunnen we het beginoctaaf veranderen:

% één octaaf boven de centrale C
\relative {
  e'' c a c
}

Relatieve modus kan aanvankelijk wat verwarrend zijn, maar het is de eenvoudigste manier om melodieën in te voeren. Laten we eens kijken hoe het uitrekenen van relatieve afstanden in de praktijk werkt. Beginnend met een B, die in de vioolsleutel op de middelste lijn staat, kan je een C, D en E bereiken binnen 3 notenbalk-ruimten omhoog, een een A, G en F binnen 3 notenbalk-ruimten omlaag. Dus als de noot na een B een C, D of E is, wordt aangenomen dat die hoger is dan de B, en van een A, G of F wordt aangenomen dat hij lager is.

\relative {
  b' c  % c is 1 notenbalk-ruimte omhoog, dus de c hoger
  b d  % d is 2 omhoog of 5 omlaag, dus de d hoger
  b e  % e is 3 omhoog of 4 omlaag, dus de e hoger
  b a  % a is 6 omhoog of 1 omlaag, dus de a lager
  b g  % g is 5 omhoog of 2 omlaag, dus de g lager
  b f  % f is 4 omhoog of 3 omlaag, dus de f lager
}

Precies hetzelfde gebeurt als een van deze noten verhoogd of verlaagd is met een kruis of mol. Toevallige tekens worden volledig genegeerd in de berekening van de relatieve positie. Exact dezelfde notenbalkruimte-telling wordt gedaan voor een noot op willekeurig welke andere plaats op de notenbalk.

Om intervallen te gebruiken die groter zijn dan drie notenbalk-ruimten, kunnen we het octaaf verhogen door een apostrof ' (of enkel aanhalingsteken) aan de notenaam toe te voegen. We kunnen het octaaf verlagen door een komma , aan de notenaam toe toe voegen.

\relative {
  a' a, c' f,
  g g'' a,, f'
}

Voor het veranderen van een noot met twee (of meer!) octaven gebruiken we meerdere '' of ,, – maar let op dat je twee enkele apostrofs of aanhalingstekens gebruikt '' en niet één dubbel aanhalingsteken " !

Nootlengten (ritmen)

Terminologie: beam, duration, whole note, half note, quarter note, dotted note.

De lengte van een noot wordt aangegeven door een getal na de notenaam: 1 voor een hele noot, 2 voor een halve noot, 4 voor een kwartnoot enzovoorts. Waardestrepen worden automatisch toegevoegd.

Als je geen lengte aangeeft, word te vorige lengte ook gebruikt voor de volgende noot. De lengte van de eerste noot is standaard een kwartnoot.

\relative {
  a'1
  a2 a4 a8 a
  a16 a a a a32 a a a a64 a a a a a a a a2
}

Voor het maken van gepuncteerde noten voeg je een punt . toe aan het lengte-getal. De lengte van een gepuncteerde noot moet expliciet worden aangegeven (d.w.z., altijd ook met een getal).

\relative {
  a'4 a a4. a8
  a8. a16 a a8. a8 a4.
}

Rusten

Terminologie: rest.

Een rust voer je in net zoals een noot met de naam r :

\relative {
  a'4 r r2
  r8 a r4 r4. r8
}

Maatsoort

Terminologie: time signature.

De maatsoort kun je aangeven met het \time-commando:

\relative {
  \time 3/4
  a'4 a a
  \time 6/8
  a4. a
  \time 4/4
  a4 a a a
}

Tempo-aanduidingen

Terminologie: tempo indication, metronome.

De tempo indication en metronome mark worden gezet met het \tempo-commando:

\relative {
  \time 3/4
  \tempo "Andante"
  a'4 a a
  \time 6/8
  \tempo 4. = 96
  a4. a
  \time 4/4
  \tempo  "Presto" 4 = 120
  a4 a a a
}

Sleutel

Terminologie: clef.

De sleutel kun je aangeven met het \clef commando:

\relative {
  \clef "treble"
  c'1
  \clef "alto"
  c1
  \clef "tenor"
  c1
  \clef "bass"
  c1
}

Alles samen

Hier is een klein voorbeeld dat al deze onderdelen samen toont:

\relative {
  \clef "bass"
  \time 3/4
  \tempo "Andante" 4 = 120
  \clef "bass"
  c,2 e8 c'
  g'2.
  f4 e d
  c4 c, r
}

Zie ook

Notatiehandleiding: Writing pitches, Writing rhythms, Writing rests, Time signature, Clef.

1.2.2 Werken met invoerbestanden

LilyPond-invoerbestanden lijken op broncodebestanden van de meest gebruikte programmeertalen. Ze bevatten een versie-uitdrukking, zijn hoofdlettergevoelig, en witruimte wordt grotendeels genegeerd. Expressies worden gevormd met accolades { }, en commentaren worden aangegeven met % of %{ … %} .

Als de vorige alinea totale onzin lijkt, geen probleem! We leggen hieronder uit wat al deze termen betekenen:

• Versie-uitdrukking: Elk LilyPond-bestand zou een versie-uitdrukking moeten hebben. Een versie-uitdrukking is een regel die aangeeft voor welke versie van LilyPond het bestand is geschreven, zoals in onderstaand voorbeeld:

  \version "2.23.3"
  

  De versie-uitdrukking wordt altijd helemaal bovenin het LilyPond-bestand gezet.

  Er zijn twee redenen waarom de versie-uitdrukking belangrijk is. Ten eerste maakt het een automatische update van het invoerbestand mogelijk voor wanneer de syntax van een nieuwere LilyPond-versie verandert. Ten tweede geeft het de LilyPond-versie aan die nodig is om het bestand te compileren.

  Als de versie-uitdrukking wordt weggelaten uit een invoerbestand, zal LilyPond een waarschuwing geven tijdens het compileren van het bestand.

• Hoofdlettergevoelig: het maakt uit of je een letter als kleine letter typt (bijv. a, b, s, t) of als hoofdletter (bijv. A, B, S, T). Noten zijn met een kleine letter: ‘{ c d e }’ is geldige invoer; ‘{ C D E }’ geeft een foutmelding.
• Witeruimteongevoelig: het maakt niet uit hoeveel spaties (of tabs of nieuwe regels) je invoegt. ‘{ c d e }’ betekent hetzelfde als ‘{ c  ’     d e } en als:

  { c4                       d
                     e   }
  

  Het laatste voorbeeld leest natuurlijk erg lastig. Een goede vuistregel is om blokken code in te springen met twee spaties:

  {
    c4 d e
  }
  

  Echter, vele syntactische elementen moeten van elkaar gescheiden worden door witruimte. Anders gezegd, witruimte kan altijd worden ingevoegd, maar niet altijd worden weggehaald. Omdat ontbrekende witruimte voor vreemde foutmeldingen kan zorgen, is het verstandig altijd witruimte te gebruiken voor en na elk syntactisch element, bijvoorbeeld, voor en na elke accolade.

• Uitdrukkingen: om elk stuk LilyPond-invoer moeten { accolades } heen staan. Deze haakjes vertellen LilyPond dat de invoer een enkele muziekuitdrukking is, net als de haakjes () bij wiskunde. De accolades moeten altijd los staan, d.w.z. omgeven zijn door witruimte, of aan het begin of einde van een regel staan om ambiguïteiten te voorkomen.

  Een LilyPond-commando gevolgd door een enkele uitdrukking tussen accolades (zoals ‘relative c' { … }’) telt ook als een enkele muziekuitdrukking.

• Commentaren: een commentaar is een opmerking voor de lezer van de muziekinvoer; het wordt genegeerd tijdens het verwerken, dus het heeft geen effect op de geprinte uitvoer. Er zijn twee soorten commentaar. Het procentteken % markeert het begin van een regelcommentaar; alles na een % op die regel wordt genegeerd. Een regelcommentaar wordt altijd boven de regel geplaatst waar hij bij hoort.

  a4 a a a
  % dit commentaar slaat op de B's
  b2 b
  

  Een blokcommentaar markeert een heel stuk van de muziekinvoer als commentaar. Alles wat tussen %{ en %} staat, wordt genegeerd. Echter, blockcommentaren kunnen niet worden ge‘nest’. Dat betekent dat je een blokcommentaar niet binnen een ander blokcommentaar kunt zetten. Als je dat toch probeert, zal de eerste %} beide blokcommentaren sluiten. Het volgende fragment toont het gebruik van commentaren:

  % noten voor twinkle twinkle volgen
    c4 c g' g a a g2
  
  %{
    Deze regel, en de noten hieronder worden genegeerd,
    omdat ze in een blokcommentaar staan.
  
    f4 f e e d d c2
  %}
  

1.3 Omgaan met foutmeldingen

Soms produceert LilyPond niet de uitvoer die je verwachtte. Deze paragraaf geeft enkele verwijzingen om je te helpen met het oplossen van problemen die je tegen zou kunnen komen.

1.3.1 Algemene tips voor het oplossen van problemen

Het oplossen van LilyPond-problemen kan een uitdaging als je gewend bent aan een grafische gebruikers interface, omdat ongeldige invoerbestanden kunnen worden gemaakt. Zodra dit gebeurt, is een logische aanpak de beste manier om het probleem te identificeren en op te lossen. Enkele richtlijnen om je te helpen dit te leren, worden gegeven in Troubleshooting.

1.3.2 Enkele algemene fouten

Er zijn een paar algemene fouten die moeilijk op te lossen zijn als je alleen afgaat op de foutmelding die wordt getoond. Deze fouten worden beschreven in errors Common errors.

1.4 Het lezen van de handleidingen

Deze paragraaf laat zien hoe je de documentatie efficient kunt lezen, en introduceert enkele nuttige interactieve functies die beschikbaar zijn in de online-versie.

1.4.1 Weggelaten materiaal

LilyPond-invoer moet tussen { }-tekens of ‘relative c'' { … }’ staan, zoals we gezien hebben in Werken met invoerbestanden. Vanaf nu zullen we dit weglaten uit de meeste voorbeelden in de handleiding. Als je die voorbeelden wilt gebruiken, kun je you de getoonde invoer kopiëren en plakken, maar je moet zelf wel ‘relative c'' { … }’ toevoegen, dus:

\relative c'' {
  …plak hier het voorbeeld…
}

Waarom laten we die accolades weg? De meeste voorbeelden in deze handleiding kunnen midden in een langer stuk muziek worden ingevoegd. Bij zulke voorbeelden is het onzinnig om ‘relative c'' { … }’ toe te voegen – je moet een \relative niet binnen een ander \relative zetten! Als we ‘relative c'' { … }’ om elk voorbeeld heen zouden zetten, zou je een klein documentatievoorbeeld niet zomaar kunnen kopiëren en in een langer stuk kunnen plakken. De meeste mensen willen materiaal toevoegen aan een bestaand stuk, dus zorgen we dat de handleiding daarvoor het meest geschikt is.

Verder moet elk LilyPond-bestand eigenlijk ook een \version-uitdrukking hebben. Omdat de voorbeelden in de handleidingen fragmenten zijn, en geen volledige bestanden, wordt de \version-uitdrukking weggelaten. Maar je zou er een gewoonte van moeten maken ze in je bestanden op te nemen.

1.4.2 Klikbare voorbeelden

Veel mensen leren programma’s door te proberen en er wat mee te prutsen. Dat kan ook goed met LilyPond. Als je op een afbeelding in de HTML-versie van deze handleiding klikt, zie je de exacte LilyPond-invoer die gebruikt is om die afbeelding te genereren. Probeer het maar met deze afbeelding:

Door het knippen en plakken van het gehele “ly snippet”-gedeelte, heb je een sjabloon om je experiment mee te beginnen. Om precies dezelde uitvoer te krijgen (inclusief regelbreedte en alles), kopiëer alles vanaf “Start cut-&-pastable section” tot aan het einde van het bestand.

1.4.3 Overzicht van handleidingen

Er is veel documentatie voor LilyPond. Nieuwe gebruikers weten soms niet helemaal wat ze nu wel en niet zouden moeten lezen, en soms slaan ze essentiële delen over.

• Voordat je ook maar iets probeert: lees uit de Beginnershandleiding het Leerboek, en Algemene muzieknotatie. Als je muziektermen tegenkomt die je niet herkent, zoek ze dan op in de Terminologie.
• Voordat je een heel muziekstuk probeert te schrijven: lees uit de Beginnershandleiding de Fundamentele concepten. Daarna wil je wellicht de relevante delen van de Notatiehandleiding bekijken.
• Voordat je de standaarduitvoer probeert te veranderen: lees uit de Beginnershandleiding over Tweaking output.
• Voordat je een groot project begint: lees uit de Gebruikershandleiding files Suggestions for writing files.

2 Algemene muzieknotatie

In dit hoofdstuk wordt uitgelegd hoe je prachtig geprinte muziek maakt met algemene muzieknotatie; dit is het vervolg op het materiaal in het Leerboek.

2.1 Notatie voor een enkele notenbalk

Deze paragraaf introduceert algemene muzieknotatie gebruikt voor een enkelvoudige melodie op één notenbalk.

2.1.1 Maat-controles

Alhoewel ze niet strikt noodzakelijk zijn, zouden maat-controles gebruikt moeten worden in de invoer-code om aan te geven waar de maatstrepen verwacht worden. Ze worden ingevoerd met het vertikale streep-symbool, |. Met behulp van deze maat-controles kan het programma nagaan, door de nootlengten die je ingevoerd hebt op te tellen, dat alle maten precies gevuld zijn. Maat-controles maken de invoer-code eenvoudiger te lezen, omdat ze helpen deze opgeruimd te houden.

g1 | e1 | c2. c'4 | g4 c g e | c4 r r2 |

Zie ook

Notatiehandleiding: Bar and bar number checks.

2.1.2 Verplaatsingstekens en toonsoorten

Verplaatsingstekens

Terminologie: sharp, flat, sharp double sharp, double flat, accidental.

Een noot met een kruis maak je door is achter de naam te plakken, en een noot met een mol maak je door er es achter te plakken. Zoals je zou kunnen verwachten, een dubbelkruis of dubbelmol wordt gemaakt door het toevoegen van isis of eses. Deze syntax is afgeleid van de Noordse en Germaanse talen zoals het Duits en het Nederlands. Om andere namen te gebruiken voor verplaatsingstekens, zie other languages Note names in other languages.

\relative { cis''4 ees fisis, aeses }

Toonsoorten

Terminologie: key signature, major, minor.

De toonsoort wordt gezet met het commando \key gevolgd door een toonhoogte en \major of \minor.

\key d \major
a1 |
\key c \minor
a1 |

Waarschuwing: toonsoorten en toonhoogten

Terminologie: accidental, key signature, pitch, flat, natural, sharp, transposition, Pitch names.

Om uit te maken of er wel of geen toevallig teken geprint moet worden, onderzoekt LilyPond de toonhoogten en de toonsoort. De toonsoort beïnvloed alleen het printen van toevallige tekens, en niet de toonhoogte van de noot! Deze functie zaait vaak verwarring bij nieuwe gebruikers, dus laten we het eens wat beter bekijken.

LilyPond maakt een duidelijk onderscheid tussen muzikale beschrijving en layout. De verhoging of verlaging (mol, herstellingsteken of kruis) van een noot is onderdeel van de toonhoogte, en is dus de muzikale beschrijving. Of een toevallig teken (een geprinte mol, herstellingteken of kruis) ook daadwerkelijk vóór de betreffende noot wordt geprint, dat is een kwestie van layout. Voor de layout bestaan regels, dus toevallige tekens worden automatisch geprint volgens die regels. De toonhoogten in je muziek zijn kunstuitingen, dus die zullen niet automatisch worden toegevoegd, en je moet zelf datgene invoeren wat je wilt horen.

In dit voorbeeld:

\relative {
  \key d \major
  cis''4 d e fis
}

wordt voor geen enkele noot een toevallig teken geprint, maar je moet toch is toevoegen en cis en fis in het invoerbestand typen.

De code b betekent niet “print een zwart bolletje op de middelste lijn van de notenbalk.” Het betekent veelmeer “er is hier een noot met toonhoogte B-stamtoon.” In de toonsoort van A-mol majeur, krijgt hij bij het printen toch een toevallig teken:

\relative {
  \key aes \major
  aes'4 c b c
}

Als het bovenstaand voorbeeld verwarrend is, ga dan eens na: als je piano aan het spelen was, welke toets zou je aanslaan? Als je een zwarte aan zou slaan, dan moet je -is of -es aan de notenaam toevoegen!

Het expliciet toevoegen van alle verplaatsingen vergt misschien een klein beetje extra inspanning tijdens het intypen, maar het voordeel is dat transponeren eenvoudiger is, en toevallige tekens kunnen automatisch geplaatst en geprint worden volgens verschillende conventies. Voor enkele voorbeelden van het printen van toevallige tekens volgens verschillende regels, zie Automatic accidentals.

Zie ook

Notatiehandleiding: Note names in other languages, Accidentals, Automatic accidentals, Key signature.

2.1.3 Overbindingen en legatobogen

Overbindingen

Terminologie: tie.

Een overbinding maak je door het toevoegen van een tilde ~ aan de eerste noot die overgebonden wordt.

\relative { g'4~ 4 c2~ | 4~ 8 a~ 2 | }

Legatobogen

Terminologie: slur.

Een legatoboog is een kromme, getrokken over een aantal noten. De beginnoot en eindnoot worden gemarkeerd met respectievelijk ( en ).

\relative { d''4( c16) cis( d e c cis d) e( d4) }

Fraseringsbogen

Terminologie: slur, phrasing.

Bogen die langere frasering aangeven kunnen worden ingevoerd met \( en \). Je een legatoboog een een fraseringsboog tegelijkertijd gebruiken, maar je kunt geen gelijktijdige legatobogen of gelijktijdige fraseringsbogen gebruiken.

\relative { g'4\( g8( a) b( c) b4\) }

Waarschuwingen: legatobogen versus overbindingen

Terminologie: articulation, slur, tie.

Een legatoboog ziet er net zo uit als een overbinding, maar heeft een andere betekenis. Een overbinding maakt de eerste noot gewoon langer, en kan alleen gebruikt worden tussen twee noten van dezelfde toonhoogte. Legatobogen geven de speelwijze of articulatie van noten aan, en kunnen worden gebruikt over grotere nootgroepen. Legatobogen en overbindingen kunnen worden genest.

\relative { c''4(~ c8 d~ 4 e) }

Zie ook

Notatiehandleiding: Ties, Slurs, Phrasing slurs.

2.1.4 Articulatie en dynamiek

Articulaties

Terminologie: articulation.

Algemene articulaties kunnen worden toegevoegd aan een noot met een streepje - en een enkel karakter:

\relative {
  c''4-^ c-+ c-- c-!
  c4-> c-. c2-_
}

Vingerzetting

Terminologie: fingering.

Op soortgelijke manier wordt een vingerzetting aan een noot toegevoegd met een streepje (-) en het cijfer dat moet worden geprint:

\relative { c''4-3 e-5 b-2 a-1 }

Je kunt meerdere articulaties bij dezelfde noot gebruiken. Articulaties en vingerzetting worden gewoonlijk automatisch geplaatst, maar je kunt een richting specificeren door het streepje (-) te vervangen door ^ (boven) or _ (onder). Echter, in de meeste gevallen is het beter om LilyPond de richting van de articulaties te laten uitzoeken.

\relative { c''4_-^1 d^. f^4_2-> e^-_+ }

Dynamiek

Terminologie: dynamics, crescendo, decrescendo.

Dynamische tekens maak je door het teken (met een backslash) aan de noot toe te voegen:

\relative { c''4\ff c\mf c\p c\pp }

Crescendi en decrescendi begin je met de commando’s \< en \>. Het volgende dynamische teken, bijvoorbeeld \f, beïndigt de (de)crescendo maar je kunt ook het commando \! gebruiken:

\relative { c''4\< c\ff\> c c\! }

Zie ook

Notatiehandleiding: Articulations and ornamentations, Fingering instructions, Dynamics.

2.1.5 Tekst toevoegen

Je kunt tekst aan je muziek toevoegen door:

c''2^"espr" a'_"legato"

Extra formattering kan worden toegevoegd met het \markup-commando:

c''2^\markup { \bold espr }
a'2_\markup {
  \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p
}

Zie ook

Notatiehandleiding: Writing text.

2.1.6 Automatische en handmatige waardestrepen

Terminologie: beam.

Alle waardestrepen worden automatisch getekend:

\relative { a'8[ ais] d[ ees r d] c16 b a8 }

Als de automatische waardestrepen je niet bevallen, kun je ze handmatig overschijven. Om een bepaalde waardestreep te verbeteren markeer je de eerste noot met [ en de laatste met ].

a8[ ais] d[ ees r d] a b

Als je de automatische waardestrepen helemaal uit wilt zetten voor een bepaald stuk muziek, gebruik je het commando \autoBeamOff om de automatische waardestrepen uit te zetten en \autoBeamOn om ze weer aan te zetten.

\relative {
  \autoBeamOff
  a'8 c b4 d8. c16 b4 |
  \autoBeamOn
  a8 c b4 d8. c16 b4 |
}

Zie ook

Notatiehandleiding: Automatic beams, Manual beams.

2.1.7 Geavanceerde ritmische commando’s

Opmaat

Terminologie: anacrusis.

Een opmaat (of anacrouse) wordt ingevoerd met het sleutelwoord \partial. Het wordt gevolgd door een nootlengte: \partial 4 is een opmaat van een kwart en \partial 8 een achtste.

\relative {
  \partial 8 f''8 |
  c2 d |
}

Antimetrische figuren

Terminologie: note value, triplet.

Antimetrische figuren wordeg gemaakt met het \times sleutelwoord. Het verwacht twee parameters: een fractie (breuk) en een stuk muziek. De lengte van het stuk muziek wordt vermenigvuldigd met de fractie. Een triol maakt dat de noten 2/3 van hun lengte duren, dus een triool heeft als fractie 2/3

\relative {
  \tuplet 3/2 { f''8 g a }
  \tuplet 3/2 { c8 r c }
  \tuplet 3/2 { f,8 g16[ a g a] }
  \tuplet 3/2 { d4 a8 }
}

Versieringen

Terminologie: grace notes, acciaccatura, appoggiatura.

Versieringen worden gemaakt met het \grace commando, hoewel ze ook gemaakt kunenn worden door een het sleutelwoord \appoggiatura of \acciaccatura voor een muziekuitdrukking te zetten

\relative {
  c''2 \grace { a32 b } c2 |
  c2 \appoggiatura b16 c2 |
  c2 \acciaccatura b16 c2 |
}

Zie ook

Notatiehandleiding: Grace notes, Tuplets, Upbeats.

2.2 Verschillende noten tegelijk klinkend

Deze paragraaf introduceert het hebben van meer dan één klinkende noot tegelijkertijd: verscheidene instrumenten, verscheidene notenbalken voor één instrument (bijv. piano), en akkoorden.

Polyfonie betekent in de muziek het hebben van meer dan één klinkende melodie tegelijk. Polyfonie in LilyPond betekent het hebben van meer dan een stem op dezelfde notenbalk.

2.2.1 Muziekuitdrukkingen nader verklaard

In LilyPond-invoerbestanden wordt muziek gerepresenteerd door muziekuitdrukkingen. Een enkele noot is een muziekuitdrukking:

a'4

Een noot tussen accolades zetten maakt er een samengestelde muziekuitdrukking van. Hier hebben we een samengestelde muziekuitdrukking gemaakt die twee noten bevat:

\relative { a'4 g4 }

Een groep muziekuitdrukkingen (bijv. noten) tussen accolades zetten betekent dat ze een sequentie zijn (d.w.z. de ene volgt op de vorige). Het resultaat is een nieuwe muziekuitdrukking:

\relative { { a'4 g } f4 g }

Analogie: wiskundige uitdrukkingen

Dit mechanisme lijkt op wiskundige formules: een grote formule wordt gemaakt door een samenstelling van kleine formules. Zulke formules worden uitdrukkingen genoemd, en ze kunnen andere uitdrukkingen bevatten, zodat je willekeurig ingewikkelde en grote uitdrukkingen kunt maken. Bijvoorbeeld,

1

1 + 2

(1 + 2) * 3

((1 + 2) * 3) / (4 * 5)

Dit is een opeenvolging van uitdrukkingen, waar elke uitdrukking onderdeel is van de volgende (grotere) uitdrukking. De eenvoudigste uitdrukkingen zijn getallen, en grotere worden gemaakt door het combineren van uitdrukkingen met operatoren (zoals +, * en /) en haakjes. Net als wiskundige uitdrukkingen, kunnen muziekuitdrukkingen willekeurig diep worden genest, wat nodig is voor ingewikkelde muziek zoals polyfone partituren.

Simultane muziekuitdrukkingen: meerdere notenbalken

Terminologie: polyphony.

Deze techniek is nuttig voor polyfone muziek. Voor het invoeren van muziek met meerdere stemmen of meerdere notenbalken, combineren we uitdrukkingen gelijktijdig. Om aan te geven dat twee stemmen tegelijk klinken, voer je gewoon een simultane samenstelling van muziekuitdrukkingen in. Een ‘simultane’ muziekuitdrukking wordt gevormd door uitdrukkingen te tussen << en >> te zetten. In onderstaand voorbeeld, zijn drie sequenties (die allemaal enkele noten bevatten) simultaan samengesteld:

<<
  \relative { a'2 g }
  \relative { f'2 e }
  \relative { d'2 b }
>>

Merk op dat we elk niveau van de invoer met een ander aantal spaties hebben ingesprongen. Het maakt LilyPond niet uit hoeveel (of hoe weinig) spaties er aan het begin van een regel staan, maar het op deze wijze inspringen van LilyPond-code maakt het voor mensen veel leesbaarder.

Simultane muziekuitdrukking: enkele notenbalk

Om het aantal notenbalken in een stuk te bepalen, kijkt LilyPond naar het begin van de eerste uitdrukking. Als dat een enkele noot is, is er één notenbalk; als dat een simultane uitdrukking is, is er meer dan één notenbalk. Onderstaand voorbeeld toont een ingewikkelde uitdrukking, maar omdat het begint met een enkele noot wordt het genoteerd op een enkele notenbalk.

\relative {
  c''2 <<c e>> |
  << { e2 f } { c2 <<b d>> } >> |
}

2.2.2 Meerdere notenbalken

LilyPond-invoerbestanden bestaan uit muziekuitdrukkingen, zoals we zagen in Muziekuitdrukkingen nader verklaard. Als de partituur begint met een simultane muziekuitdrukking, maakt LilyPond meerdere notenbalken. Echter, het is eenvoudiger te zien wat er gebeurt als we de notebalk expliciet creëren.

Om meer dan een één notenbalk te printen, wordt elk stuk muziek dat een op een notebalk hoort gemarkeerd door er \new Staff voor te zetten. Deze Staff-elementen worden dan gelijktijdig samengesteld met << en >>:

<<
  \new Staff { \clef "treble" c''4 }
  \new Staff { \clef "bass" c4 }
>>

Het commando \new opent een ‘notatiecontext.’ Een notatiecontext is een omgeving waarin muziekelementen (zoals noten of \clef-commando’s) worden geïnterpreteerd. Voor eenvoudige stukken worden zulke notatiecontexten automatisch aangemaakt. Voor ingewikkeldere stukken, is het beter om contexten expliciet aan te geven.

Er zijn verschillende soorten van contexten. Score, Staff, en Voice zorgen voor melodische notatie, terwijl Lyrics liedteksten zet en ChordNames accoordnamen print.

In syntaxtermen maakt het laten voorafgaan van Als je \new voor een muziekuitdrukking zet, maakt dat in syntaxtermen een grotere muziekuitdrukking. Dat lijkt op het minteken in de wiskunde. De formule (4+5) is een uitdrukking, dus -(4+5) is een grotere uitdrukking.

Maatsoorten die in één notenbalk worden ingevoerd, beïnvloeden standaard ook alle andere notenbalken. And de andere kant, de toonsoort van een notenbalk heeft geen invloed op andere notenbalken. Dit verschil in standaard gedrag is omdat partituren met transponerende instrumenten veel meer voorkomen dan polyritmische partituren.

<<
  \new Staff { \clef "treble" \key d \major \time 3/4 c''4 }
  \new Staff { \clef "bass" c4 }
>>

2.2.3 Notenbalkgroepen

Terminologie: brace, staff, system.

Pianomuziek wordt meestal genoteerd op twee notenbalken die verbonden zijn door een accolade. Het afdrukken van zo’n balk gaat hetzelfde als in het polyfone voorbeeld in Meerdere notenbalken. Echter, nu wordt de gehele uitdrukking in een PianoStaff gestopt:

\new PianoStaff <<
  \new Staff …
  \new Staff …
>>

Hier is een voorbeeldje:

\relative {
  \new PianoStaff <<
    \new Staff { \time 2/4 c''4 e | g g, | }
    \new Staff { \clef bass c,,4 c' | e c | }
  >>
}

Andere notenbalkgroeperingen gaan met \new GrandStaff, geschikt voor for orkestpartituren, en \new ChoirStaff, geschikt voor vocale partituren. Deze notenbalkgroepen vormen allemaal een ander type context, namelijk een die een accolade aan de linkerkant van elk systeem maakt en ook de lengte van de maatstrepen bepaalt.

Zie ook

Notatiehandleiding: Keyboard and other multi-staff instruments, Displaying staves.

2.2.4 Het combineren van noten tot accoorden

Terminologie: chord.

We zagen eerder hoe noten kunnen worden gecombineerd tot accoorden door aan te geven dat ze tegelijk klinken door ze tussen dubbele gehoekte haken te zetten. Echter, de normale manier om een accoord aan te geven is door de toonhoogten tussen enkele hoekige haken te zetten. Merk op dat alle noten in een accoord dezelfde lengte moeten hebben, en dat die lengte na de afsluitende haak komt.

\relative { r4 <c'' e g> <c f a>2 }

Beschouw accoorden als vrijwel identiek aan enkele noten: bijna alles wat je aan een enkele noot kunt plakken, kun je aan een accoord plakken, en alles komt buiten de hoekige haken. Bijvoorbeeld, je kunt markeringen als waardestrepen en overbindingen gebruiken met accoorden. Ze worden geplaatst buiten de hoekige haken.

r4 <c e g>~ <c f a>2 |
<c e g>8[ <c f a> <c e g> <c f a>]
  <c e g>\>[ <c f a> <c f a> <c e g>]\! |
r4 <c e g>8.\p <c f a>16( <c e g>4-. <c f a>) |

Zie ook

Notatiehandleiding: Chorded notes.

2.2.5 Polyfonie binnen een notenbalk

Polyfone muziek in LilyPond, hoewel niet moeilijk, maakt gebruik van concepten die we nog niet hebben besproken, dus kunnen we nog niet introduceren. In plaats daarvan worden in de volgende paragrafen eerst deze concepten uitvoerig verklaard.

Zie ook

Beginnershandleiding: Voices contain music.

Notatiehandleiding: Simultaneous notes.

2.3 Vocale muziek

Deze paragraaf introduceert vocale muziek en eenvoudige liedjes.

2.3.1 Het zetten van eenvoudige liedjes

Terminologie: lyrics.

Hier is het begin van de melodie van een slaapliedje, Girls and boys come out to play:

\relative {
  \key g \major
  \time 6/8
  d''4 b8 c4 a8 | d4 b8 g4
}

De liedteksten kunnen op deze noten worden gezet, door beiden te combineren met het \addlyrics-sleutelwoord. Liedteksten worden ingevoerd door de lettergrepen van elkaar te scheiden met een spatie.

<<
  \relative {
    \key g \major
    \time 6/8
    d''4 b8 c4 a8 | d4 b8 g4
  }
  \addlyrics {
    Girls and boys come | out to play,
  }
>>

Merk de hoekige haken << ... >> op die om het hele stuk heen staan en aangeven dat de muziek en de woorden tegelijk klinken.

2.3.2 Liedteksten uitrichten op een melodie

Terminologie: melisma, extender line.

De volgende regel van het slaapliedje is The moon doth shine as bright as day. Laten we die ook invoeren:

<<
  \relative {
    \key g \major
    \time 6/8
    d''4 b8 c4 a8 | d4 b8 g4 g8 |
    a4 b8 c b a | d4 b8 g4. |
  }
  \addlyrics {
    Girls and boys come | out to play,
    The | moon doth shine as | bright as day; |
  }
>>

Als je de code van het bovenstaand voorbeeld compileert, zul je waarschuwingen op het scherm zien:

song.ly:12:29: waarschuwing: maat-controle gefaald op: 5/8
    The | moon doth shine as
                             | bright as day; |
song.ly:12:46: waarschuwing: maat-controle gefaald op: 3/8
    The | moon doth shine as | bright as day;
                                              |

Dit is een goed voorbeeld van de waarde van maat-controles. Als we naar de muziek kijken, dan zien we dat de extra liedteksten niet helemaal goed uitgericht zijn met de noten. Het woord shine moet op twee noten gezongen worden, niet op één. Dit wordt een melisma genoemd, een enkele lettergreep gezongen op meer dan een noot. Er zijn verschillende manieren om een lettergreep over meerdere noten uit te verdelen, het eenvoudigst is een legatoboog over de noten te zetten, voor details, zie Overbindingen en legatobogen:

<<
  \relative {
    \key g \major
    \time 6/8
    d''4 b8 c4 a8 | d4 b8 g4 g8 |
    a4 b8 c( b) a | d4 b8 g4. |
  }
  \addlyrics {
    Girls and boys come | out to play,
    The | moon doth shine as | bright as day; |
  }
>>

De woorden zijn nu goed uitgericht met de noten, maar de automatische waardestrepen voor de noten boven shine as zien er niet helemaal goed uit. We kunnen dit verbeteren door handmatige waardestreep-aanduidingen in te voegen om de automatische waardestrepen te overschrijven, voor details, see Automatische en handmatige waardestrepen.

<<
  \relative {
    \key g \major
    \time 6/8
    d''4 b8 c4 a8 | d4 b8 g4 g8 |
    a4 b8 c([ b]) a | d4 b8 g4. |
  }
  \addlyrics {
    Girls and boys come | out to play,
    The | moon doth shine as | bright as day; |
  }
>>

Als alternatief voor het gebruik van legatobogen, kunnen melismata worden aangegeven door in de liedtekst een underscore _ toe te voegen voor elke noot die moet worden opgenomen in de melisma:

<<
  \relative {
    \key g \major
    \time 6/8
    d''4 b8 c4 a8 | d4 b8 g4 g8 |
    a4 b8 c[ b] a | d4 b8 g4. |
  }
  \addlyrics {
    Girls and boys come | out to play,
    The | moon doth shine _ as | bright as day; |
  }
>>

Als een lettergreep zich uitstrekt over een aantal noten of over een noot die heel lang duurt, wordt gewoonlijk een legatolijn getrokken vanaf de lettergreep die zich uitstrekt onder alle noten van die lettergreep. Die wordt ingevoerd als twee underscores __. Hier is een voorbeeld uit de eerste drie maten van Dido’s Lament, van Purcells Dido and Æneas:

<<
  \relative {
    \key g \minor
    \time 3/2
    g'2 a bes | bes2( a) b2 |
    c4.( bes8 a4. g8 fis4.) g8 | fis1
  }
  \addlyrics {
    When I am | laid,
    am | laid __ in | earth,
  }
>>

In geen van de voorbeelden tot nu toe zijn woorden met meer dan een lettergreep gebruikt. Zulke woorden worden gewoonlijk opgedeeld in een lettergreep per noot, met koppeltekens tussen de lettergrepen. Zo’n koppelteken worden ingevoerd als twee streepjes, wat een koppelteken midden tussen de twee lettergrepen oplevert. Hier is een voorbeeld dat dit laat zien en alles wat we tot nu toe hebben geleerd over het uitrichten van liedteksten naar noten. notes.

<<
  \relative {
    \key g \major
    \time 3/4
    \partial 4
    d'4 | g4 g a8( b) | g4 g b8( c) |
    d4 d e | c2
  }
  \addlyrics {
    A -- | way in a __ | man -- ger,
    no __ | crib for a | bed, __
  }
>>

Sommige liedteksten, vooral die in het Italiaans, hebben het omgekeerde nodig: het zetten van meer dan een lettergreep op een noot. Dit wordt bereikt door lettergreepen aan elkaar te koppelen met een enkele underscore _ (zonder spaties), of door ze tussen dubbele aanhalingtekens te zetten. Hier is een voorbeeld uit Rossini’s Figaro, waar al op dezelfde noot moet worden gezongen als go uit het Largo in Figaro’s aria Largo al factotum:

<<
  \relative {
    \clef "bass"
    \key c \major
    \time 6/8
    c'4.~ 8 d b | c8([ d]) b c d b | c8
  }
  \addlyrics {
    Lar -- go_al fac -- | to -- tum del -- la cit -- | tà
  }
>>

Zie ook

Notatiehandleiding: Vocal music.

2.3.3 Liedteksten bij meerdere notenbalken

De eenvoudige aanpak met \addlyrics kan gebruikt worden voor het plaatsen van liedteksten onder meer dan een notenbalk. Hier is een voorbeeld uit Handels Judas Maccabæus:

<<
  \relative {
    \key f \major
    \time 6/8
    \partial 8
    c''8 | c8([ bes]) a a([ g]) f | f'4. b, | c4.~ 4
  }
  \addlyrics {
    Let | flee -- cy flocks the | hills a -- | dorn, __
  }
  \relative {
    \key f \major
    \time 6/8
    \partial 8
    r8 | r4. r4 c'8 | a'8([ g]) f f([ e]) d | e8([ d]) c bes'4
  }
  \addlyrics {
    Let | flee -- cy flocks the | hills a -- dorn,
  }
>>

Partituren die ingewikkelder zijn dan dit eenvoudige voorbeeld kun je beter maken door het uit elkaar trekken van de score structuur en de noten en liedteksten door het gebruik van variabelen. Dit wordt behandeld in Stukken organiseren met variabelen.

Zie ook

Notatiehandleiding: Vocal music.

2.4 De puntjes op de i’s

Dit is de laatste paragraaf van het leerboek; het laat zien hoe je de puntjes op de i’s zet voor eenvoudige stukken, en geeft een inleiding op het vervolg van de handleiding.

2.4.1 Stukken organiseren met variabelen

Wanneer alle elementen die eerder zijn besproken worden gecombineerd om grotere bestanden te maken, worden de muziekuitdrukkingen een stuk groter. In polyfone muziek met veel notenbalken, kunnen invoerbestanden heel verwarrend worden. Deze verwarring kunnen we verminderen door het gebruik van variabelen.

Met variabelen (ook bekend als identifiers of macro’s), kunnen we ingewikkelde muziekuitdrukkingen in stukken breken. Een waarde aan een variabele toekennen gaat as volgt:

benoemdeMuziek = { … }

De inhoud van de muziekuitdrukking benoemdeMuziek kan later worden gebruikt door een backslash voor de naam te zetten (\benoemdeMuziek, precies als een gewoon LilyPond-commando).

viool = \new Staff {
  \relative {
    a'4 b c b
  }
}

cello = \new Staff {
  \relative {
    \clef "bass"
    e2 d
  }
}
{
  <<
    \viool
    \cello
  >>
}

De naam van een variabele mag alleen letters bevatten, geen cijfers, underscores, or of streepjes.

Variabelen moeten gedefiniëerd worden voor de eigenlijke muziekuitdrukking, daarna kunnen ze zo vaak als nodig worden hergebruikt. Ze kunnen zelfs worden gebruikt om de inhoud van een nieuwe variabele te construeren, wat een manier is om een stuk muziek met veel herhalingen compacter in te voeren.

trioolA = \tuplet 3/2 { c,8 e g }
maatA = { \trioolA \trioolA \trioolA \trioolA }

\relative c'' {
  \maatA \maatA
}

Variabelen kunnen worden gebruikt voor allerlei andere typen objecten in de invoer. Bijvoorbeeld

breedte = 4.5\cm
naam = "Janneke"
aVijfPapier = \paper { paperheight = 21.0 \cm }

Afhankelijk van de inhoud kan de variabele gebruikt wonden op verschillende plaatsen. Onderstaand voorbeeld maakt gebruik van de bovenstaande variabelen:

\paper {
  \aVijfPapier
  line-width = \breedte
}

{
  c4^\naam
}

2.4.2 Titels toevoegen

De titel, componist, opusnummer, en soortgelijke informatie worden ingevoerd in het \header-blok. Deze bevindt zich buiten de muziekuitdrukking; het \header-blok staat gewoonlijk direct onder het versienummer.

\version "2.23.3"

\header {
  title = "Symfonie"
  composer = "Ik"
  opus = "Op. 9"
}

{
  … muziek …
}

Als het bestand wordt verwerkt, worden titel en componist en opus boven de muziek geprint. Meer informatie over titels staat in Creating titles headers and footers.

2.4.3 Absolute notenamen

Totnutoe hebben we steeds \relative gebruikt om toonhoogten aan te duiden. Dit is voor de meeste muziek de eenvoudigste manier van invoeren, maar er is ook een andere manier om toonhoogten in te voeren: de absolute modus.

Alls je \relative weglaat, behandelt LilyPond alle toonhoogten als absolute waarden. Een c' betekent altijd de centrale C, een b betekent altijd de noot een stapje onder de centrale C en een g, is altijd de noot onderaan de balk bij de bassleutel.

{
  \clef "bass"
  c'4 b g, g, |
  g,4 f, f c' |
}

Hier is een toonladder over vier octaven:

{
  \clef "bass"
  c,4 d, e, f, |
  g,4 a, b, c |
  d4 e f g |
  a4 b c' d' |
  \clef "treble"
  e'4 f' g' a' |
  b'4 c'' d'' e'' |
  f''4 g'' a'' b'' |
  c'''1 |
}

Zoals je ziet, behoeft het schrijven van een melodie in de vioolsleutel nogal wat apostrof-tekens '. Kijk eens naar dit fragment van mozart:

{
  \key a \major
  \time 6/8
  cis''8. d''16 cis''8 e''4 e''8 |
  b'8. cis''16 b'8 d''4 d''8 |
}

Al die apostrofs maken de invoer onleesbaar en zijn een bron van fouten. met \relative is bovenstaand voorbeeld een stuk leesbaarder en ook eenvoudiger in te voeren:

\relative {
  \key a \major
  \time 6/8
  cis''8. d16 cis8 e4 e8 |
  b8. cis16 b8 d4 d8 |
}

Als je een fout maakt met een octaveringsteken (' of ,) in de \relative-modus, wordt dat heel snel duidelijk – veel noten staan in het verkeerde octaaf. Als je in absolute modus werkt, is een enkele octaaffout lang niet zo goed zichtbaar, en zal dus ook niet zo eenvoudig te vinden zijn.

Echter, absolute modus is is nuttig in muziek met zeer grote intervallen en vooral voor lilypond-invoer die met de computer wordt gegenereerd.

2.4.4 Na het leerboek

Als je dit leerboek uit hebt, kun je het beste zelf een paar stukken in gaan voeren. Begin met het toevoegen van noten aan een van de Templates. Als je notatie nodig hebt die niet is behandeld in het leerboek, kijk dan in de notatiehandleiding, beginnend bij Musical notation. Al je een stuk wilt schrijven voor een ensemble waarvoor geen sjabloon beschikbaar is, kijk dan naar Extending the templates.

Zodra je een paar korte stukken hebt geschreven, lees de rest van de beginnershandleiding (hoofdstukken 3-5). Je mag die nu natuurlijk ook best gaan lezen! Echter, het vervolg van de Beginnershandleiding veronderstelt dat je vertrouwd bent met LilyPond-invoer. Je zou die hoofstukken snel kunnne doorkijken en later terugkomen als je wat meer ervaring hebt.

In dit leerboek en in het vervolg van de beginnershandleiding is een alinea Zie ook aan het eind van elke paragraaf met kruisverwijzingen naar andere paragrafen: deze kruisverwijzingen kun je beter niet volgen bij de eerste keer lezen. Als je de gehele beginnershandleiding een keer hebt gelezen, wil je wellicht bepaalde stukken herlezen en kun je deze kruisverwijzingen bijvoorbeeld volgen voor meer informatie.

Mocht je dat nog niet gedaan hebben, lees alsjeblieft het Overzicht van handleidingen. Er is veel informatie beschikbaar over LilyPond, dus nieuwkomers weten vaak niet waar ze precies moeten zoeken. Als je vijf minuten uittrekt om die paragraaf goed te lezen, kun je jezelf uren frustratie besparen met het zoeken op verkeerde plaatsen!

3 Fundamentele concepten

In het Leerboek hebben we gezien hoe je prachtig geprinte muziek maakt van een eenvoudig tekstbestand. Dit hoofdstuk introduceert de achterliggende concepten en benodigde technieken voor het maken van ingewikkeldere partituren die er net zo mooi uitzien.

3.1 Hoe LilyPond-invoerbestanden werken

Het LilyPond invoerformaat is tamelijk vrij, wat ervaren gebruikers veel flexibiliteit geeft hun bestanden te structureren zoals ze dat wensen. Deze flexibiliteit kan verwarrend zijn voor nieuwe gebruikers. Deze paragraaf legt het een en ander uit over deze structuur. Om het leesbaar te houden worden details weggelaten. Een complete beschrijving van het invoerformaat is te vinden in File structure.

3.1.1 Inleiding in de LilyPond-bestandsstructuur

Een basisvoorbeeld van een LilyPond-invoerbestand is

\version "2.23.3"

\header { }

\score {
  ...samengestelde muziekuitdrukking...  % alle muziek komt hier!
  \layout { }
  \midi { }
}

Er zijn veel variaties op dit basispatroon maar dit voorbeeld dient als een handig beginpunt.

Tot nu toe heeft geen van de voorbeelden het \score{}-commando gebruikt. Dit kan omdat LilyPond automatisch de extra commando’s toevoegt die benodigt zijn als je het eenvoudige invoer geeft. LilyPond behandelt invoer zoals dit:

\relative {
  c''4 a d c
}

als een afkorting voor dit:

\book {
  \score {
    \new Staff {
      \new Voice {
        \relative {
          c''4 a b c
        }
      }
    }
    \layout { }
  }
}

Anders gezegd, als de invoer een enkelvoudige muziekuitdrukking bevat, interpreteert LilyPond het bestand alsof die muziekuitdrukking ingepakt is in bovenstaande commando’s.

Een kleine waarschuwing! In veel van de voorbeelden in de LilyPond-documentatie worden de \new Staff- en \new Voice-commando’s weggelaten en worden ze impliciet aangemaakt. Voor eenvoudige voorbeelden werkt dat goed, maar voor ingewikkelde voorbeelden, vooral wanneer additionele commando’s worden gebruikt, kan het impliciete aanmaken van contexten verrassende resultaten opleveren, zoals extra ongewenste notebalken. Hoe je contexten expliciet specificeert, wordt uitgelegd in Contexts and engravers.

Laten we terugkeren naar het eerste voorbeeld en het \score-commando beter bekijken.

Een \score-blok moet altijd precies één muziekuitdrukking bevatten, en die moet direct na het \score-commando staan. Herrinner je dat een muziekuitdrukking alles kan zijn van een enkele noot tot een enorme samengestelde uitdrukking zoals

{
  \new StaffGroup <<
    ...vul de volledige partituur van een Wagner opera hier in...
  >>
}

Omdat alles tussen { ... } staat, telt het als één muziekuitdrukking.

Zoals we eerder al zagen, kan het \score-blok allerlei andere dingen bevatten, zoals

\score {
  { c'4 a b c' }
  \header { }
  \layout { }
  \midi { }
}

Merk op dat deze drie commando’s – \header, \layout en \midi – speciaal zijn: in tegenstelling tot veel andere commando’s die met een backslash (\) beginnen zijn het geen muziekuitdrukkingen en ze zijn ook geen onderdeel van een muziekuitdrukking. Ze kunnen zowel binnen als buiten het \score-blok worden geplaatst. Deze commando’s worden gewoonlijk dan ook buiten het \score-blok gezet – bijvoorbeeld, \header staat meestal boven het \score-commando, zoals het in eerste voorbeeld van deze paragraaf.

De twee andere commando’s die je niet eerder hebt gezien zijn \layout { } en \midi {}. Als deze gebruikt worden als hierboven laten ze LilyPond respectievelijk geprinte- en MIDI-uitvoer genereren. Een volledige beschrijving van deze commando’s is te vinden in de Notatiehandleiding – Score layout, en Creating MIDI files.

Je kunt meer dan een \score-blok gebruiken. Elk wordt behandeld als een afzonderlijke partituur en ze worden allemaal samengevoegd in een enkel uitvoerbestand. Een \book-commando is niet nodig – die wordt impliciet aangemaakt. Echter, als je afzonderlijke uitvoerbestanden vanuit een ‘.ly’-bestand wil maken, dan moet het \book-commando worden gebruikt om de verschillende secties aan te geven: elk \book-blok produceert een apart uitvoerbestand.

Samengevat:

Elk \book-blok geeft een apart uitvoerbestand (bijv., een PDF-bestand). Als je er geen expliciet toevoegt, stopt LilyPond je gehele invoercode impliciet in een \book-blok.

Elk \score-blok is een apart brok muziek binnen een \book-blok.

Elk \layout-blok beïnvloedt het \score- of \book-blok waarin het voorkomt – d.w.z., een \layout-blok binnen een \score-blok heeft uitsluitend invloed op dat \score-blok, maar een \layout-blok buiten een \score-blok (en dus binnen een \book-blok, expliciet danwel impliciet) beïnvloedt elke \score in dat \book.

Voor details zie Multiple scores in a book.

Een andere manier van afkorten is het gebruik van variabelen, zoals getoond in Stukken organiseren met variabelen. Alle sjablonen gebruiken dat:

melodie = \relative {
  c'4 a b c
}

\score {
  \melodie
}

Als LilyPond naar dit bestand kijkt, neemt het de waarde van melodie (alles na het isgelijkteken) en voegt die in zodra ergens \melody staat. De naam van de variable heeft verder geen speciale betekenis – het kan net zo goed melodie, globaal, TijdSleutel, pianorechterhand, of iets anders zijn. Bedenk dat je vrijwel elke naam kunt gebruiken die je wilt, zolang die maar bestaat uit letters en het niet de naam is van een LilyPond-commando. Voor meer details, zie Saving typing with variables and functions. De precieze beperkingen van variabelenamen staan beschreven in File structure.

Zie ook

Voor een volledige definitie van het invoerformaat, zie File structure.

3.1.2 Score is a (single) compound musical expression

We saw the general organization of LilyPond input files in the previous section, @ref{Introduction to the LilyPond file structure}. But we seemed to skip over the most important part: how do we figure out what to write after \score?

We didn’t skip over it at all. The big mystery is simply that there is no mystery. This line explains it all:

A \score block must begin with a compound music expression.

To understand what is meant by a music expression and a compound music expression, you may find it useful to review the tutorial, @ref{Music expressions explained}. In that section, we saw how to build big music expressions from small pieces – we started from notes, then chords, etc. Now we’re going to start from a big music expression and work our way down. For simplicity, we’ll use just a singer and piano in our example. We don’t need a StaffGroup for this ensemble, which simply groups a number of staves together with a bracket at the left, but we do need staves for a singer and a piano, though.

\score {
  <<
    \new Staff = "singer" <<
    >>
    \new PianoStaff = "piano" <<
    >>
  >>
  \layout { }
}

Here we have given names to the staves – “singer” and “piano”. This is not essential here, but it is a useful habit to cultivate so that you can see at a glance what each stave is for.

Remember that we use << ... >> instead of { ... } to show simultaneous music. This causes the vocal part and piano part to appear one above the other in the score. The << ... >> construct would not be necessary for the Singer staff in the example above if it were going to contain only one sequential music expression, but << ... >> rather than braces is necessary if the music in the Staff is to contain two or more simultaneous expressions, e.g. two simultaneous Voices, or a Voice with lyrics. We’re going to have a voice with lyrics, so angle brackets are required. We’ll add some real music later; for now let’s just put in some dummy notes and lyrics. If you’ve forgotten how to add lyrics you may wish to review \addlyrics in @ref{Setting simple songs}.

\score {
  <<
    \new Staff = "singer" <<
      \new Voice = "vocal" { c'1 }
      \addlyrics { And }
    >>
    \new PianoStaff = "piano" <<
      \new Staff = "upper" { c'1 }
      \new Staff = "lower" { c'1 }
    >>
  >>
  \layout { }
}

Now we have a lot more details. We have the singer’s staff: it contains a Voice (in LilyPond, this term refers to a set of notes, not necessarily vocal notes – for example, a violin generally plays one voice) and some lyrics. We also have a piano staff: it contains an upper staff (right hand) and a lower staff (left hand), although the lower staff has yet to be given a bass clef.

At this stage, we could start filling in notes. Inside the curly braces next to \new Voice = "vocal", we could start writing

\relative {
  r4 d''8\noBeam g, c4 r
}

But if we did that, the \score section would get pretty long, and it would be harder to understand what was happening. So let’s use variables instead. These were introduced at the end of the previous section, remember? To ensure the contents of the text variable are interpreted as lyrics we preface them with \lyricmode. Like \addlyrics, this switches the input mode to lyrics. Without that, LilyPond would try to interpret the contents as notes, which would generate errors. (Several other input modes are available, see Input modes.)

So, adding a few notes and a bass clef for the left hand, we now have a piece of real music:

melody = \relative { r4 d''8\noBeam g, c4 r }
text   = \lyricmode { And God said, }
upper  = \relative { <g' d g,>2~ <g d g,> }
lower  = \relative { b,2 e }

\score {
  <<
    \new Staff = "singer" <<
      \new Voice = "vocal" { \melody }
      \addlyrics { \text }
    >>
    \new PianoStaff = "piano" <<
      \new Staff = "upper" { \upper }
      \new Staff = "lower" {
        \clef "bass"
        \lower
      }
    >>
  >>
  \layout { }
}

When writing (or reading) a \score section, just take it slowly and carefully. Start with the outer level, then work on each smaller level. It also really helps to be strict with indentation – make sure that each item on the same level starts on the same horizontal position in your text editor.

Zie ook

Notation Reference: Structure of a score.

3.1.3 Nesting music expressions

It is not essential to declare all staves at the beginning; they may be introduced temporarily at any point. This is particularly useful for creating ossia sections – see ossia. Here is a simple example showing how to introduce a new staff temporarily for the duration of three notes:

\new Staff {
  \relative {
    r4 g'8 g c4 c8 d |
    e4 r8
    <<
      { f8 c c }
      \new Staff {
        f8 f c
      }
    >>
    r4 |
  }
}

Note that the size of the clef is the same as a clef printed following a clef change – slightly smaller than the clef at the beginning of the line. This is usual for clefs printed in the middle of a line.

The ossia section may be placed above the staff as follows:

\new Staff = "main" {
  \relative {
    r4 g'8 g c4 c8 d |
    e4 r8
    <<
      { f8 c c }
      \new Staff \with {
        alignAboveContext = "main"
      } { f8 f c }
    >>
    r4 |
  }
}

This example uses \with, which will be explained more fully later. It is a means of modifying the default behavior of a single Staff. Here it says that the new staff should be placed above the staff called “main” instead of the default position which is below.

Zie ook

Ossia are often written without clef and without time signature and are usually in a smaller font. These require further commands which have not yet been introduced. See Size of objects, and Ossia staves.

3.1.4 On the un-nestedness of brackets and ties

You have already met a number of different types of bracket and bracket-like constructs in writing the input file to LilyPond. These obey different rules which can be confusing at first. Let’s first review the different types of brackets and bracket-like constructs.

To these we should add other constructs which generate lines between or across notes: ties (marked by a tilde, ~), tuplets written as \times x/y {..}, and grace notes written as \grace{..}.

Outside LilyPond, the conventional use of brackets requires the different types to be properly nested, like this, << [ { ( .. ) } ] >>, with the closing brackets being encountered in exactly the opposite order to the opening brackets. This is a requirement for the three types of bracket described by the word ‘Encloses’ in the table above – they must nest properly. However, the remaining bracket-like constructs, described with the word ‘Marks’ in the table above together with ties and tuplets, do not have to nest properly with any of the brackets or bracket-like constructs. In fact, these are not brackets in the sense that they enclose something – they are simply markers to indicate where something starts and ends.

So, for example, a phrasing slur can start before a manually inserted beam and end before the end of the beam – not very musical, perhaps, but possible:

\relative { g'8\( a b[ c b\) a] g4 }

In general, different kinds of brackets, bracket-like constructs, and those implied by tuplets, ties and grace notes, may be mixed freely. This example shows a beam extending into a tuplet (line 1), a slur extending into a tuplet (line 2), a beam and a slur extending into a tuplet, a tie crossing two tuplets, and a phrasing slur extending out of a tuplet (lines 3 and 4).

\relative {
  r16[ g' \tuplet 3/2 { r16 e'8] }
  g,16( a \tuplet 3/2 { b16 d) e }
  g,8[( a \tuplet 3/2 { b8 d) e~] } |
  \tuplet 5/4 { e32\( a, b d e } a4.\)
}

3.2 Voices contain music

Singers need voices to sing, and so does LilyPond. The actual music for all instruments in a score is contained in Voices – the most fundamental of all LilyPond’s concepts.

3.2.1 I’m hearing Voices

The lowest, most fundamental or innermost layers in a LilyPond score are called ‘Voice contexts’ or just ‘Voices’ for short. Voices are sometimes called ‘layers’ in other notation packages.

In fact, a Voice layer or context is the only one which can contain music. If a Voice context is not explicitly declared one is created automatically, as we saw at the beginning of this chapter. Some instruments such as an Oboe can play only one note at a time. Music written for such instruments requires just a single voice. Instruments which can play more than one note at a time like the piano will often require multiple voices to encode the different concurrent notes and rhythms they are capable of playing.

A single voice can contain many notes in a chord, of course, so when exactly are multiple voices needed? Look first at this example of four chords:

\relative {
  \key g \major
  <d' g>4 <d fis> <d a'> <d g>
}

This can be expressed using just the single angle bracket chord symbols, < ... >, and for this just a single voice is needed. But suppose the F-sharp were actually an eighth-note followed by an eighth-note G, a passing note on the way to the A? Now we have two notes which start at the same time but have different durations: the quarter-note D and the eighth-note F-sharp. How are these to be coded? They cannot be written as a chord because all the notes in a chord must have the same duration. And they cannot be written as two sequential notes as they need to start at the same time. This is when two voices are required.

Let us see how this is done in LilyPond input syntax.

The easiest way to enter fragments with more than one voice on a staff is to enter each voice as a sequence (with {...}), and combine them simultaneously with angle brackets, <<...>>. The fragments must also be separated with double backward slashes, \\, to place them in separate voices. Without these, the notes would be entered into a single voice, which would usually cause errors. This technique is particularly suited to pieces of music which are largely homophonic with occasional short sections of polyphony.

Here’s how we split the chords above into two voices and add both the passing note and a slur:

\relative {
  \key g \major
  %    Voice = "1"             Voice = "2"
  << { g'4 fis8( g) a4 g } \\ { d4 d d d }  >>
}

Notice how the stems of the second voice now point down.

Here’s another simple example:

\relative {
  \key d \minor
  %    Voice = "1"           Voice = "2"
  << { r4 g' g4. a8 }   \\ { d,2 d4 g }       >> |
  << { bes4 bes c bes } \\ { g4 g g8( a) g4 } >> |
  << { a2. r4 }         \\ { fis2. s4 }       >> |
}

It is not necessary to use a separate << \\ >> construct for each bar. For music with few notes in each bar this layout can help the legibility of the code, but if there are many notes in each bar it may be better to split out each voice separately, like this:

<<
  \key d \minor
  \relative { % Voice = "1"
    r4 g' g4. a8 |
    bes4 bes c bes |
    a2. r4 |
  } \\
  \relative { % Voice = "2"
    d'2 d4 g |
    g4 g g8( a) g4 |
    fis2. s4 |
  }
>>

This example has just two voices, but the same construct may be used to encode three or more voices by adding more back-slash separators.

The Voice contexts bear the names "1", "2", etc. The first contexts set the outer voices, the highest voice in context "1" and the lowest voice in context "2". The inner voices go in contexts "3" and "4". In each of these contexts, the vertical direction of slurs, stems, ties, dynamics etc., is set appropriately.

\new Staff \relative {
  % Main voice
  c'16 d e f
  %    Voice = "1"   Voice = "2"              Voice = "3"
  << { g4 f e } \\ { r8 e4 d c8~ } >> |
  << { d2 e }   \\ { c8 b16 a b8 g~ 2 } \\ { s4 b c2 } >> |
}

These voices are all separate from the main voice that contains the notes just outside the << .. >> construct. Let’s call this the simultaneous construct. Slurs and ties may only connect notes within the same voice, so slurs and ties cannot go into or out of a simultaneous construct. Conversely, parallel voices from separate simultaneous constructs on the same staff are the same voice. Other voice-related properties also carry across simultaneous constructs. Here is the same example, with different colors and note heads for each voice. Note that changes in one voice do not affect other voices, but they do persist in the same voice later. Note also that tied notes may be split across the same voices in two constructs, shown here in the blue triangle voice.

\new Staff \relative {
  % Main voice
  c'16 d e f
  <<  % Bar 1
    {
      \voiceOneStyle
      g4 f e
    }
  \\
    {
      \voiceTwoStyle
      r8 e4 d c8~
    }
  >> |
  <<  % Bar 2
     % Voice 1 continues
    { d2 e }
  \\
     % Voice 2 continues
    { c8 b16 a b8 g~ 2 }
  \\
    {
      \voiceThreeStyle
      s4 b c2
    }
  >> |
}

The commands \voiceXXXStyle are mainly intended for use in educational documents such as this one. They modify the color of the note head, the stem and the beams, and the style of the note head, so that the voices may be easily distinguished. Voice one is set to red diamonds, voice two to blue triangles, voice three to green crossed circles, and voice four (not used here) to magenta crosses; \voiceNeutralStyle (also not used here) reverts the style back to the default. We shall see later how commands like these may be created by the user. See Visibility and color of objects and Using variables for tweaks.

Polyphony does not change the relationship of notes within a \relative block. Each note is still calculated relative to the note immediately preceding it, or to the first note of the preceding chord. So in

\relative c' { noteA << < noteB noteC > \\ noteD >> noteE }

noteB is relative to noteA
noteC is relative to noteB, not noteA;
noteD is relative to noteB, not noteA or noteC;
noteE is relative to noteD, not noteA.

An alternative way, which may be clearer if the notes in the voices are widely separated, is to place a \relative command at the start of each voice:

\relative c' { noteA ... }
<<
  \relative c'' { < noteB noteC > ... }
\\
  \relative g' { noteD ... }
>>
\relative c' { noteE ... }

Let us finally analyze the voices in a more complex piece of music. Here are the notes from the first two bars of the second of Chopin’s Deux Nocturnes, Op 32. This example will be used at later stages in this and the next chapter to illustrate several techniques for producing notation, so please ignore for now anything in the underlying code which looks mysterious and concentrate just on the music and the voices – the complications will all be explained in later sections.

The direction of the stems is often used to indicate the continuity of two simultaneous melodic lines. Here the stems of the highest notes are all pointing up and the stems of the lower notes are all pointing down. This is the first indication that more than one voice is required.

But the real need for multiple voices arises when notes which start at the same time have different durations. Look at the notes which start at beat three in the first bar. The A-flat is a dotted quarter note, the F is a quarter note and the D-flat is a half note. These cannot be written as a chord as all the notes in a chord must have the same duration. Neither can they be written as sequential notes, as they must start at the same time. This section of the bar requires three voices, and the normal practice would be to write the whole bar as three voices, as shown below, where we have used different note heads and colors for the three voices. Again, the code behind this example will be explained later, so ignore anything you do not understand.

Let us try to encode this music from scratch. As we shall see, this encounters some difficulties. We begin as we have learnt, using the << \\ >> construct to enter the music of the first bar in three voices:

\new Staff \relative {
  \key aes \major
  <<
    { c''2 aes4. bes8 } \\ { <ees, c>2 des } \\ { aes'2 f4 fes }
  >> |
  <c ees aes c>1 |
}

The stem directions are automatically assigned with the odd-numbered voices taking upward stems and the even-numbered voices downward ones. The stems for voices 1 and 2 are right, but the stems in voice 3 should go down in this particular piece of music. We can correct this by skipping voice three and placing the music in voice four. This is done by simply adding another pair of \\.

\new Staff \relative {
  \key aes \major
  <<  % Voice one
    { c''2 aes4. bes8 }
  \\  % Voice two
    { <ees, c>2 des }
  \\  % Omit Voice three
  \\  % Voice four
    { aes'2 f4 fes }
  >> |
  <c ees aes c>1 |
}

We see that this fixes the stem direction, but the horizontal placement of notes is not what we want. LilyPond shifts the inner notes when they or their stems would collide with outer voices, but this is not appropriate for piano music. In other situations, the shifts LilyPond applies might fail to clear the collisions. LilyPond provides several ways to adjust the horizontal placing of notes. We are not quite ready yet to see how to correct this, so we shall leave this problem until a later section — see the force-hshift property in Fixing overlapping notation.

Zie ook

Notation Reference: Multiple voices.

3.2.2 Explicitly instantiating voices

Voice contexts can also be created manually inside a << >> block to create polyphonic music, using \voiceOne … \voiceFour to indicate the required directions of stems, slurs, etc. In longer scores this method is clearer, as it permits the voices to be separated and to be given more descriptive names.

Specifically, the construct << \\ >> which we used in the previous section:

\new Staff {
  \relative {
    << { e'4 f g a } \\ { c,4 d e f } >>
  }
}

is equivalent to

\new Staff <<
  \new Voice = "1" { \voiceOne \relative { e'4 f g a } }
  \new Voice = "2" { \voiceTwo \relative { c'4 d e f } }
>>

Both of the above would produce

The \voiceXXX commands set the direction of stems, slurs, ties, articulations, text annotations, augmentation dots of dotted notes, and fingerings. \voiceOne and \voiceThree make these objects point upwards, while \voiceTwo and \voiceFour make them point downwards. These commands also generate a horizontal shift for each voice when this is required to avoid clashes of note heads. The command \oneVoice reverts the settings back to the normal values for a single voice.

Let us see in some simple examples exactly what effect \oneVoice, \voiceOne and voiceTwo have on markup, ties, slurs, and dynamics:

\relative {
  % Default behavior or behavior after \oneVoice
  c'4 d8~ 8 e4( f | g4 a) b-> c |
}

\relative {
  \voiceOne
  c'4 d8~ 8 e4( f | g4 a) b-> c |
  \oneVoice
  c,4 d8~ 8 e4( f | g4 a) b-> c |
}

\relative {
  \voiceTwo
  c'4 d8~ 8 e4( f | g4 a) b-> c |
  \oneVoice
  c,4 d8~ 8 e4( f | g4 a) b-> c |
}

Now let’s look at three different ways to notate the same passage of polyphonic music, each of which is advantageous in different circumstances, using the example from the previous section.

An expression that appears directly inside a << >> belongs to the main voice (but, note, not in a << \\ >> construct). This is useful when extra voices appear while the main voice is playing. Here is a more correct rendition of our example. The red diamond-shaped notes demonstrate that the main melody is now in a single voice context, permitting a phrasing slur to be drawn over them.

\new Staff \relative {
  \voiceOneStyle
  % This section is homophonic
  c'16^( d e f
  % Start simultaneous section of three voices
  <<
    % Continue the main voice in parallel
    { g4 f e | d2 e) | }
    % Initiate second voice
    \new Voice {
      % Set stems, etc., down
      \voiceTwo
      r8 e4 d c8~ | 8 b16 a b8 g~ 2 |
    }
    % Initiate third voice
    \new Voice {
      % Set stems, etc, up
      \voiceThree
      s2. | s4 b c2 |
    }
  >>
}

More deeply nested polyphony constructs are possible, and if a voice appears only briefly this might be a more natural way to typeset the music:

\new Staff \relative {
  c'16^( d e f
  <<
    { g4 f e | d2 e) | }
    \new Voice {
      \voiceTwo
      r8 e4 d c8~ |
      <<
        { c8 b16 a b8 g~ 2 | }
        \new Voice {
          \voiceThree
          s4 b c2 |
        }
      >>
    }
  >>
}

This method of nesting new voices briefly is useful when only small sections of the music are polyphonic, but when the whole staff is largely polyphonic it can be clearer to use multiple voices throughout, using spacing notes to step over sections where the voice is silent, as here:

\new Staff \relative <<
  % Initiate first voice
  \new Voice {
    \voiceOne
    c'16^( d e f g4 f e | d2 e) |
  }
  % Initiate second voice
  \new Voice {
    % Set stems, etc, down
    \voiceTwo
    s4 r8 e4 d c8~ | 8 b16 a b8 g~ 2 |
  }
  % Initiate third voice
  \new Voice {
    % Set stems, etc, up
    \voiceThree
    s1 | s4 b c2 |
  }
>>

Note columns

Closely spaced notes in a chord, or notes occurring at the same time in different voices, are arranged in two, occasionally more, columns to prevent the note heads overlapping. These are called note columns. There are separate columns for each voice, and the currently specified voice-dependent shift is applied to the note column if there would otherwise be a collision. This can be seen in the example above. In bar 2 the C in voice two is shifted to the right relative to the D in voice one, and in the final chord the C in voice three is also shifted to the right relative to the other notes.

The \shiftOn, \shiftOnn, \shiftOnnn, and \shiftOff commands specify the degree to which notes and chords of the voice should be shifted if a collision would otherwise occur. By default, the outer voices (normally voices one and two) have \shiftOff specified, while the inner voices (three and four) have \shiftOn specified. When a shift is applied, voices one and three are shifted to the right and voices two and four to the left.

\shiftOnn and \shiftOnnn define further shift levels which may be specified temporarily to resolve collisions in complex situations – see Real music example.

A note column can contain just one note (or chord) from a voice with stems up and one note (or chord) from a voice with stems down. If notes from two voices which have their stems in the same direction are placed at the same position and both voices have no shift or the same shift specified, the error message “Too many clashing note columns” will be produced.

Zie ook

Notation Reference: Multiple voices.

3.2.3 Voices and vocals

Vocal music presents a special difficulty: we need to combine two expressions – notes and lyrics.

You have already seen the \addlyrics{} command, which handles simple scores well. However, this technique is quite limited. For more complex music, you must introduce the lyrics in a Lyrics context using \new Lyrics and explicitly link the lyrics to the notes with \lyricsto{}, using the name assigned to the Voice.

<<
  \new Voice = "one" {
    \relative {
      \autoBeamOff
      \time 2/4
      c''4 b8. a16 | g4. f8 | e4 d | c2 |
    }
  }
  \new Lyrics \lyricsto "one" {
    No more let | sins and | sor -- rows | grow. |
  }
>>

Note that the lyrics must be linked to a Voice context, not a Staff context. This is a case where it is necessary to create Staff and Voice contexts explicitly.

The automatic beaming which LilyPond uses by default works well for instrumental music, but not so well for music with lyrics, where beaming is either not required at all or is used to indicate melismata in the lyrics. In the example above we use the command \autoBeamOff to turn off the automatic beaming.

Let us reuse the earlier example from Judas Maccabæus to illustrate this more flexible technique. We first recast it to use variables so the music and lyrics can be separated from the staff structure. We also introduce a ChoirStaff bracket. The lyrics themselves must be introduced with \lyricmode to ensure they are interpreted as lyrics rather than music.

global = { \key f \major \time 6/8 \partial 8 }

SopOneMusic = \relative {
  c''8 | c8([ bes)] a a([ g)] f | f'4. b, | c4.~ 4
}
SopOneLyrics = \lyricmode {
  Let | flee -- cy flocks the | hills a -- dorn, __
}
SopTwoMusic = \relative {
  r8 | r4. r4 c'8 | a'8([ g)] f f([ e)] d | e8([ d)] c bes'
}
SopTwoLyrics = \lyricmode {
  Let | flee -- cy flocks the | hills a -- dorn,
}

\score {
  \new ChoirStaff <<
    \new Staff <<
      \new Voice = "SopOne" {
        \global
        \SopOneMusic
      }
      \new Lyrics \lyricsto "SopOne" {
        \SopOneLyrics
      }
    >>
    \new Staff <<
      \new Voice = "SopTwo" {
        \global
        \SopTwoMusic
      }
      \new Lyrics \lyricsto "SopTwo" {
        \SopTwoLyrics
      }
    >>
  >>
}

This is the basic structure of all vocal scores. More staves may be added as required, more voices may be added to the staves, more verses may be added to the lyrics, and the variables containing the music can easily be placed in separate files should they become too long.

Here is an example of the first line of a hymn with four verses, set for SATB. In this case the words for all four parts are the same. Note how we use variables to separate the music notation and words from the staff structure. See too how a variable, which we have chosen to call ‘keyTime’, is used to hold several commands for use within the two staves. In other examples this is often called ‘global’.

keyTime = { \key c \major \time 4/4 \partial 4 }

SopMusic   = \relative { c'4 | e4. e8 g4  g    | a4   a   g  }
AltoMusic  = \relative { c'4 | c4. c8 e4  e    | f4   f   e  }
TenorMusic = \relative  { e4 | g4. g8 c4.   b8 | a8 b c d e4 }
BassMusic  = \relative  { c4 | c4. c8 c4  c    | f8 g a b c4 }

VerseOne =
  \lyricmode { E -- | ter -- nal fa -- ther, | strong to save, }
VerseTwo   =
  \lyricmode { O | Christ, whose voice the | wa -- ters heard, }
VerseThree =
  \lyricmode { O | Ho -- ly Spi -- rit, | who didst brood }
VerseFour  =
  \lyricmode { O | Tri -- ni -- ty of | love and pow'r }

\score {
  \new ChoirStaff <<
    \new Staff <<
      \clef "treble"
      \new Voice = "Sop"  { \voiceOne \keyTime \SopMusic }
      \new Voice = "Alto" { \voiceTwo \AltoMusic }
      \new Lyrics \lyricsto "Sop" { \VerseOne   }
      \new Lyrics \lyricsto "Sop" { \VerseTwo   }
      \new Lyrics \lyricsto "Sop" { \VerseThree }
      \new Lyrics \lyricsto "Sop" { \VerseFour  }
    >>
    \new Staff <<
      \clef "bass"
      \new Voice = "Tenor" { \voiceOne \keyTime \TenorMusic }
      \new Voice = "Bass"  { \voiceTwo \BassMusic }
    >>
  >>
}

Zie ook

Notation Reference: Vocal music.

3.3 Contexts and engravers

Contexts and engravers have been mentioned informally in earlier sections; we now must look at these concepts in more detail, as they are important in the fine-tuning of LilyPond output.

3.3.1 Contexts explained

When music is printed, many notational elements which do not appear explicitly in the input file must be added to the output. For example, compare the input and output of the following example:

\relative { cis''4 cis2. | a4 a2. | }

The input is rather sparse, but in the output, bar lines, accidentals, clef, and time signature have been added. When LilyPond interprets the input the musical information is parsed from left to right, similar to the way a performer reads the score. While reading the input, the program remembers where measure boundaries are, and which pitches require explicit accidentals. This information must be held on several levels. For example, an accidental affects only a single staff, while a bar line must be synchronized across the entire score.

Within LilyPond, these rules and bits of information are grouped in Contexts. We have already introduced the Voice context. Others are the Staff and Score contexts. Contexts are hierarchical to reflect the hierarchical nature of a musical score. For example: a Staff context can contain many Voice contexts, and a Score context can contain many Staff contexts.

Each context has the responsibility for enforcing some notation rules, creating some notation objects and maintaining the associated properties. For example, the Voice context may introduce an accidental and then the Staff context maintains the rule to show or suppress the accidental for the remainder of the measure.

As another example, the synchronization of bar lines is, by default, handled in the Score context. However, in some music we may not want the bar lines to be synchronized – consider a polymetric score in 4/4 and 3/4 time. In such cases, we must modify the default settings of the Score and Staff contexts.

For very simple scores, contexts are created implicitly, and you need not be aware of them. For larger pieces, such as anything with more than one staff, they must be created explicitly to make sure that you get as many staves as you need, and that they are in the correct order. For typesetting pieces with specialized notation, it is usual to modify existing, or even to define totally new, contexts.

In addition to the Score, Staff and Voice contexts there are contexts which fit between the score and staff levels to control staff groups, such as the PianoStaff and ChoirStaff contexts. There are also alternative staff and voice contexts, and contexts for lyrics, percussion, fret boards, figured bass, etc.

The names of all context types are formed from one or more words, each word being capitalized and joined immediately to the preceding word with no hyphen or underscore, e.g., GregorianTranscriptionStaff.

Zie ook

Notation Reference: Contexts explained.

3.3.2 Creating contexts

In an input file a score block, introduced with a \score command, contains a single music expression and an associated output definition (either a \layout or a \midi block). The Score context is usually left to be created automatically when the interpretation of that music expression starts.

For scores with only one voice and one staff, the Voice and Staff contexts may also be left to be created automatically, but for more complex scores it is necessary to create them by hand. The simplest command that does this is \new. It is prepended to a music expression, for example

\new type music-expression

where type is a context name (like Staff or Voice). This command creates a new context, and starts interpreting the music-expression within that context.

You have seen many practical examples which created new Staff and Voice contexts in earlier sections, but to remind you how these commands are used in practice, here’s an annotated real-music example:

\score {  % start of single compound music expression
  <<  % start of simultaneous staves section
    \time 2/4
    \new Staff {  % create RH staff
      \clef "treble"
      \key g \minor
      \new Voice {  % create voice for RH notes
        \relative {  % start of RH notes
          d''4 ees16 c8. |
          d4 ees16 c8. |
        }  % end of RH notes
      }  % end of RH voice
    }  % end of RH staff
    \new Staff <<  % create LH staff; needs two simultaneous voices
      \clef "bass"
      \key g \minor
      \new Voice {  % create LH voice one
        \voiceOne
        \relative {  % start of LH voice one notes
          g8 <bes d> ees, <g c> |
          g8 <bes d> ees, <g c> |
        }  % end of LH voice one notes
      }  % end of LH voice one
      \new Voice {  % create LH voice two
        \voiceTwo
        \relative {  % start of LH voice two notes
          g4 ees |
          g4 ees |
        }  % end of LH voice two notes
      }  % end of LH voice two
    >>  % end of LH staff
  >>  % end of simultaneous staves section
}  % end of single compound music expression

(Note how all the statements which open a block with either a curly bracket, {, or double angle brackets, <<, are indented by two further spaces, and the corresponding closing bracket is indented by exactly the same amount. While this is not required, following this practice will greatly reduce the number of ‘unmatched bracket’ errors, and is strongly recommended. It enables the structure of the music to be seen at a glance, and any unmatched brackets will be obvious. Note too how the LH staff is created using double angle brackets because it requires two voices for its music, whereas the RH staff is created with a single music expression surrounded by curly brackets because it requires only one voice.)

The \new command may also give an identifying name to the context to distinguish it from other contexts of the same type,

\new type = id music-expression

Note the distinction between the name of the context type, Staff, Voice, etc, and the identifying name of a particular instance of that type, which can be any sequence of letters invented by the user. Digits and spaces can also be used in the identifying name, but then it has to be placed in quotes, i.e. \new Staff = "MyStaff 1" music-expression. The identifying name is used to refer back to that particular instance of a context. We saw this in use in the section on lyrics, see Voices and vocals.

Zie ook

Notation Reference: Creating contexts.

3.3.3 Engravers explained

Every mark on the printed output of a score produced by LilyPond is produced by an Engraver. Thus there is an engraver to print staves, one to print note heads, one for stems, one for beams, etc, etc. In total there are over 120 such engravers! Fortunately, for most scores it is not necessary to know about more than a few, and for simple scores you do not need to know about any.

Engravers live and operate in Contexts. Engravers such as the Metronome_mark_engraver, whose action and output apply to the score as a whole, operate in the highest level context – the Score context.

The Clef_engraver and Key_engraver are to be found in every Staff Context, as different staves may require different clefs and keys.

The Note_heads_engraver and Stem_engraver live in every Voice context, the lowest level context of all.

Each engraver processes the particular objects associated with its function, and maintains the properties that relate to that function. These properties, like the properties associated with contexts, may be modified to change the operation of the engraver or the appearance of those elements in the printed score.

Engravers all have compound names formed from words which describe their function. Just the first word is capitalized, and the remainder are joined to it with underscores. Thus the Staff_symbol_engraver is responsible for creating the lines of the staff, the Clef_engraver determines and sets the pitch reference point on the staff by drawing a clef symbol.

Here are some of the most common engravers together with their function. You will see it is usually easy to guess the function from the name, or vice versa.

We shall see later how the output of LilyPond can be changed by modifying the action of Engravers.

Zie ook

Internals reference: Engravers and Performers.

3.3.4 Modifying context properties

Contexts are responsible for holding the values of a number of context properties. Many of them can be changed to influence the interpretation of the input and so change the appearance of the output. They are changed by the \set command. This takes the form

\set ContextName.propertyName = #value

Where the ContextName is usually Score, Staff or Voice. It may be omitted, in which case the current context (typically Voice) is assumed.

The names of context properties consist of words joined together with no hyphens or underscores, all except the first having a capital letter. Here are a few examples of some commonly used ones. There are many more.

where a Boolean is either True (#t) or False (#f), an Integer is a positive whole number, a Real is a positive or negative decimal number, and text is enclosed in double apostrophes. Note the occurrence of hash signs, (#), in two different places – as part of the Boolean value before the t or f, and before value in the \set statement. So when a Boolean is being entered you need to code two hash signs, e.g., ##t.

Before we can set any of these properties we need to know in which context they operate. Sometimes this is obvious, but occasionally it can be tricky. If the wrong context is specified, no error message is produced, but the expected action will not take place. For example, the instrumentName clearly lives in the Staff context, since it is the staff that is to be named. In this example the first staff is labeled, but not the second, because we omitted the context name.

<<
  \new Staff \relative {
    \set Staff.instrumentName = "Soprano"
    c''2 c
  }
  \new Staff \relative {
    \set instrumentName = "Alto"  % Wrong!
    d'2 d
  }
>>

Remember the default context name is Voice, so the second \set command set the property instrumentName in the Voice context to “Alto”, but as LilyPond does not look for any such property in the Voice context, no further action took place. This is not an error, and no error message is logged in the log file.

Similarly, if the property name is mis-spelt no error message is produced, and clearly the expected action cannot be performed. In fact, you can set any (fictitious) ‘property’ using any name you like in any context that exists by using the \set command. But if the name is not known to LilyPond it will not cause any action to be taken. Some text editors with special support for LilyPond input files document property names with bullets when you hover them with the mouse, like JEdit with LilyPondTool, or highlight unknown property names differently, like ConTEXT. If you do not use an editor with such features, it is recommended to check the property name in the Internals Reference: see Tunable context properties, or Contexts.

The instrumentName property will take effect only if it is set in the Staff context, but some properties can be set in more than one context. For example, the property extraNatural is by default set to ##t (true) for all staves. If it is set to ##f (false) in one particular Staff context it applies just to the accidentals on that staff. If it is set to false in the Score context it applies to all staves.

So this turns off extra naturals in one staff:

<<
  \new Staff \relative {
    aeses'2 aes
  }
  \new Staff \relative {
    \set Staff.extraNatural = ##f
    aeses'2 aes
  }
>>

and this turns them off in all staves:

<<
  \new Staff \relative {
    aeses'2 aes
  }
  \new Staff \relative {
    \set Score.extraNatural = ##f
    aeses'2 aes
  }
>>

As another example, if clefTransposition is set in the Score context this immediately changes the value of the transposition in all current staves and sets a new default value which will be applied to all staves.

The opposite command, \unset, effectively removes the property from the context, which causes most properties to revert to their default value. Usually \unset is not required as a new \set command will achieve what is wanted.

The \set and \unset commands can appear anywhere in the input file and will take effect from the time they are encountered until the end of the score or until the property is \set or \unset again. Let’s try changing the font size, which affects the size of the note heads (among other things) several times. The change is from the default value, not the most recently set value.

\relative {
  c'4 d
  % make note heads smaller
  \set fontSize = #-4
  e4 f |
  % make note heads larger
  \set fontSize = #2.5
  g4 a
  % return to default size
  \unset fontSize
  b4 c |
}

We have now seen how to set the values of several different types of property. Note that integers and numbers are always preceded by a hash sign, #, while a true or false value is specified by ##t and ##f, with two hash signs. A text property should be enclosed in double quotation signs, as above, although we shall see later that text can actually be specified in a much more general way by using the very powerful \markup command.

Setting context properties with \with

The default value of context properties may be set at the time the context is created. Sometimes this is a clearer way of setting a property value if it is to remain fixed for the duration of the context. When a context is created with a \new command it may be followed immediately by a \with { .. } block in which the default property values are set. For example, if we wish to suppress the printing of extra naturals for the duration of a staff we would write:

\new Staff \with { extraNatural = ##f }

like this:

<<
  \new Staff {
    \relative {
      gisis'4 gis aeses aes
    }
  }
  \new Staff \with { extraNatural = ##f } {
    \relative {
      gisis'4 gis aeses aes
    }
  }
>>

Properties set in this way may still be changed dynamically using \set and returned to the default value set in the \with block with \unset.

So if the fontSize property is set in a \with clause it sets the default value of the font size. If it is later changed with \set, this new default value may be restored with the \unset fontSize command.

Setting context properties with \context

The values of context properties may be set in all contexts of a particular type, such as all Staff contexts, with a single command. The context type is identified by using its type name, like Staff, prefixed by a back-slash: \Staff. The statement which sets the property value is the same as that in a \with block, introduced above. It is placed in a \context block within a \layout block. Each \context block will affect all contexts of the type specified throughout the \score or \book block in which the \layout block appears. Here is an example to show the format:

\score {
  \new Staff {
    \relative {
      cisis''4 e d cis
    }
  }
  \layout {
    \context {
      \Staff
      extraNatural = ##t
    }
  }
}

If the property override is to be applied to all staves within the score:

\score {
  <<
    \new Staff {
      \relative {
        gisis'4 gis aeses aes
      }
    }
    \new Staff {
      \relative {
        gisis'4 gis aeses aes
      }
    }
  >>
  \layout {
    \context {
      \Score extraNatural = ##f
    }
  }
}

Context properties set in this way may be overridden for particular instances of contexts by statements in a \with block, and by \set commands embedded in music statements.

Zie ook

Notation Reference: Changing context default settings. The set command.

Internals Reference: Contexts, Tunable context properties.

3.3.5 Adding and removing engravers

We have seen that contexts each contain several engravers, each of which is responsible for producing a particular part of the output, like bar lines, staves, note heads, stems, etc. If an engraver is removed from a context, it can no longer produce its output. This is a crude way of modifying the output, but it can sometimes be useful.

Changing a single context

To remove an engraver from a single context we use the \with command placed immediately after the context creation command, as in the previous section.

As an illustration, let’s repeat an example from the previous section with the staff lines removed. Remember that the staff lines are produced by the Staff_symbol_engraver.

\new Staff \with {
  \remove "Staff_symbol_engraver"
}
\relative {
  c'4 d
  \set fontSize = #-4  % make note heads smaller
  e4 f |
  \set fontSize = #2.5  % make note heads larger
  g4 a
  \unset fontSize  % return to default size
  b4 c |
}

Engravers can also be added to individual contexts. The command to do this is

\consists Engraver_name,

placed inside a \with block. Some vocal scores have an ambitus placed at the beginning of a staff to indicate the range of notes in that staff – see ambitus. The ambitus is produced by the Ambitus_engraver, which is not normally included in any context. If we add it to the Voice context, it calculates the range from that voice only:

\new Staff <<
  \new Voice \with {
    \consists "Ambitus_engraver"
  } {
    \relative {
      \voiceOne
      c''4 a b g
    }
  }
  \new Voice {
    \relative {
      \voiceTwo
      c'4 e d f
    }
  }
>>

but if we add the ambitus engraver to the Staff context, it calculates the range from all the notes in all the voices on that staff:

\new Staff \with {
  \consists "Ambitus_engraver"
}
<<
  \new Voice {
    \relative {
      \voiceOne
      c''4 a b g
    }
  }
  \new Voice {
    \relative {
      \voiceTwo
      c'4 e d f
    }
  }
>>

Changing all contexts of the same type

The examples above show how to remove or add engravers to individual contexts. It is also possible to remove or add engravers to every context of a specific type by placing the commands in the appropriate context in a \layout block. For example, if we wanted to show an ambitus for every staff in a four-staff score, we could write

\score {
  <<
    \new Staff {
      \relative {
        c''4 a b g
      }
    }
    \new Staff {
      \relative {
        c'4 a b g
      }
    }
    \new Staff {
      \clef "G_8"
      \relative {
        c'4 a b g
      }
    }
    \new Staff {
      \clef "bass"
      \relative {
        c4 a b g
      }
    }
  >>
  \layout {
    \context {
      \Staff
      \consists "Ambitus_engraver"
    }
  }
}

The values of context properties may also be set for all contexts of a particular type by including the \set command in a \context block in the same way.

Zie ook

Notation Reference: Modifying context plug-ins, Changing context default settings.

Bekende problemen en waarschuwingen

The Stem_engraver and Beam_engraver attach their objects to note heads. If the Note_heads_engraver is removed no note heads are produced and therefore no stems or beams are created either.

3.4 Extending the templates

You’ve read the tutorial, you know how to write music, you understand the fundamental concepts. But how can you get the staves that you want? Well, you can find lots of templates (see Templates) which may give you a start. But what if you want something that isn’t covered there? Read on.

3.4.1 Soprano and cello

Start off with the template that seems closest to what you want to end up with. Let’s say that you want to write something for soprano and cello. In this case, we would start with the ‘Notes and lyrics’ template (for the soprano part).

\version "2.23.3"

melody = \relative {
  \clef "treble"
  \key c \major
  \time 4/4
  a4 b c d
}

text = \lyricmode {
  Aaa Bee Cee Dee
}

\score {
  <<
    \new Voice = "one" {
      \autoBeamOff
      \melody
    }
    \new Lyrics \lyricsto "one" \text
  >>
  \layout { }
  \midi { }
}

Now we want to add a cello part. Let’s look at the ‘Notes only’ example:

\version "2.23.3"

melody = \relative {
  \clef "treble"
  \key c \major
  \time 4/4
  a4 b c d
}

\score {
  \new Staff \melody
  \layout { }
  \midi { }
}

We don’t need two \version commands. We’ll need the melody section. We don’t want two \score sections – if we had two \scores, we’d get the two parts separately. We want them together, as a duet. Within the \score section, we don’t need two \layout or \midi.

If we simply cut and paste the melody section, we would end up with two melody definitions. This would not generate an error, but the second one would be used for both melodies. So let’s rename them to make them distinct. We’ll call the section for the soprano sopranoMusic and the section for the cello celloMusic. While we’re doing this, let’s rename text to be sopranoLyrics. Remember to rename both instances of all these names – both the initial definition (the melody = \relative c' { part) and the name’s use (in the \score section).

While we’re doing this, let’s change the cello part’s staff – celli normally use bass clef. We’ll also give the cello some different notes.

\version "2.23.3"

sopranoMusic = \relative {
  \clef "treble"
  \key c \major
  \time 4/4
  a4 b c d
}

sopranoLyrics = \lyricmode {
  Aaa Bee Cee Dee
}

celloMusic = \relative {
  \clef "bass"
  \key c \major
  \time 4/4
  d4 g fis8 e d4
}

\score {
  <<
    \new Voice = "one" {
      \autoBeamOff
      \sopranoMusic
    }
    \new Lyrics \lyricsto "one" \sopranoLyrics
  >>
  \layout { }
  \midi { }
}

This is looking promising, but the cello part won’t appear in the score – we haven’t used it in the \score section. If we want the cello part to appear under the soprano part, we need to add

\new Staff \celloMusic

underneath the soprano stuff. We also need to add << and >> around the music – that tells LilyPond that there’s more than one thing (in this case, two Staves) happening at once. The \score looks like this now:

\score {
  <<
  <<
    \new Voice = "one" {
      \autoBeamOff
      \sopranoMusic
    }
    \new Lyrics \lyricsto "one" \sopranoLyrics
  >>
  \new Staff \celloMusic
  >>
  \layout { }
  \midi { }
}

This looks a bit messy; the indentation is messed up now. That is easily fixed. Here’s the complete soprano and cello template.

sopranoMusic = \relative {
  \clef "treble"
  \key c \major
  \time 4/4
  a4 b c d
}

sopranoLyrics = \lyricmode {
  Aaa Bee Cee Dee
}

celloMusic = \relative {
  \clef "bass"
  \key c \major
  \time 4/4
  d4 g fis8 e d4
}

\score {
  <<
    <<
      \new Voice = "one" {
        \autoBeamOff
        \sopranoMusic
      }
      \new Lyrics \lyricsto "one" \sopranoLyrics
    >>
    \new Staff \celloMusic
  >>
  \layout { }
  \midi { }
}

Zie ook

The starting templates can be found in the ‘Templates’ appendix, see Single staff templates.

3.4.2 Four-part SATB vocal score

Most vocal scores of music written for four-part mixed choir with orchestral accompaniment such as Mendelssohn’s Elijah or Handel’s Messiah have the choral music and words on four staves, one for each of SATB, with a piano reduction of the orchestral accompaniment underneath. Here’s an example from Handel’s Messiah:

None of the templates provides this layout exactly. The nearest is SATB vocal score and automatic piano reduction – but we need to change the layout and add a piano accompaniment which is not derived automatically from the vocal parts. The variables holding the music and words for the vocal parts are fine, but we shall need to add variables for the piano reduction.

The order in which the contexts appear in the ChoirStaff of the template do not correspond with the order in the vocal score shown above. We need to rearrange them so there are four staves with the words written directly underneath the notes for each part. All the voices should be \voiceOne, which is the default, so the \voiceXXX commands should be removed. We also need to specify the tenor clef for the tenors. The way in which lyrics are specified in the template has not yet been encountered so we need to use the method with which we are familiar. We should also add the names of each staff.

Doing this gives for our ChoirStaff:

\new ChoirStaff <<
  \new Staff = "sopranos" <<
    \set Staff.instrumentName = "Soprano"
    \new Voice = "sopranos" {
      \global
      \sopranoMusic
    }
  >>
  \new Lyrics \lyricsto "sopranos" {
    \sopranoWords
  }
  \new Staff = "altos" <<
    \set Staff.instrumentName = "Alto"
    \new Voice = "altos" {
      \global
      \altoMusic
    }
  >>
  \new Lyrics \lyricsto "altos" {
    \altoWords
  }
  \new Staff = "tenors" <<
    \set Staff.instrumentName = "Tenor"
    \new Voice = "tenors" {
      \global
      \tenorMusic
    }
  >>
  \new Lyrics \lyricsto "tenors" {
    \tenorWords
  }
  \new Staff = "basses" <<
    \set Staff.instrumentName = "Bass"
    \new Voice = "basses" {
      \global
      \bassMusic
    }
  >>
  \new Lyrics \lyricsto "basses" {
    \bassWords
  }
>>  % end ChoirStaff

Next we must work out the piano part. This is easy - we just pull out the piano part from the ‘Solo piano’ template:

\new PianoStaff <<
  \set PianoStaff.instrumentName = "Piano  "
  \new Staff = "upper" \upper
  \new Staff = "lower" \lower
>>

and add the variable definitions for upper and lower.

The ChoirStaff and PianoStaff must be combined using angle brackets as we want them to be stacked one above the other:

<<  % combine ChoirStaff and PianoStaff one above the other
  \new ChoirStaff <<
    \new Staff = "sopranos" <<
      \new Voice = "sopranos" {
        \global
        \sopranoMusic
      }
    >>
    \new Lyrics \lyricsto "sopranos" {
      \sopranoWords
     }
    \new Staff = "altos" <<
      \new Voice = "altos" {
        \global
        \altoMusic
      }
    >>
    \new Lyrics \lyricsto "altos" {
      \altoWords
    }
    \new Staff = "tenors" <<
      \clef "G_8"  % tenor clef
      \new Voice = "tenors" {
        \global
        \tenorMusic
      }
    >>
    \new Lyrics \lyricsto "tenors" {
      \tenorWords
    }
    \new Staff = "basses" <<
      \clef "bass"
      \new Voice = "basses" {
        \global
        \bassMusic
      }
    >>
    \new Lyrics \lyricsto "basses" {
      \bassWords
    }
  >>  % end ChoirStaff

  \new PianoStaff <<
    \set PianoStaff.instrumentName = "Piano"
    \new Staff = "upper" \upper
    \new Staff = "lower" \lower
  >>
>>

Combining all these together and adding the music for the three bars of the example above gives:

global = { \key d \major \time 4/4 }
sopranoMusic = \relative {
  \clef "treble"
  r4 d''2 a4 | d4. d8 a2 | cis4 d cis2 |
}
sopranoWords = \lyricmode {
  Wor -- thy | is the lamb | that was slain |
}
altoMusic = \relative {
  \clef "treble"
  r4 a'2 a4 | fis4. fis8 a2 | g4 fis fis2 |
}
altoWords = \sopranoWords
tenorMusic = \relative {
  \clef "G_8"
  r4 fis'2 e4 | d4. d8 d2 | e4 a, cis2 |
}
tenorWords = \sopranoWords
bassMusic = \relative {
  \clef "bass"
  r4 d'2 cis4 | b4. b8 fis2 | e4 d a'2 |
}
bassWords = \sopranoWords
upper = \relative {
  \clef "treble"
  \global
  r4 <a' d fis>2 <a e' a>4 |
  <d fis d'>4. <d fis d'>8 <a d a'>2 |
  <g cis g'>4 <a d fis> <a cis e>2 |
}
lower = \relative {
  \clef "bass"
  \global
  <d, d'>4 <d d'>2 <cis cis'>4 |
  <b b'>4. <b' b'>8 <fis fis'>2 |
  <e e'>4 <d d'> <a' a'>2 |
}

\score {
  <<  % combine ChoirStaff and PianoStaff in parallel
    \new ChoirStaff <<
      \new Staff = "sopranos" <<
        \set Staff.instrumentName = "Soprano"
        \new Voice = "sopranos" {
          \global
          \sopranoMusic
        }
      >>
      \new Lyrics \lyricsto "sopranos" {
        \sopranoWords
      }
      \new Staff = "altos" <<
        \set Staff.instrumentName = "Alto"
        \new Voice = "altos" {
          \global
          \altoMusic
        }
      >>
      \new Lyrics \lyricsto "altos" {
        \altoWords
      }
      \new Staff = "tenors" <<
        \set Staff.instrumentName = "Tenor"
        \new Voice = "tenors" {
          \global
          \tenorMusic
        }
      >>
      \new Lyrics \lyricsto "tenors" {
        \tenorWords
      }
      \new Staff = "basses" <<
        \set Staff.instrumentName = "Bass"
        \new Voice = "basses" {
          \global
          \bassMusic
        }
      >>
      \new Lyrics \lyricsto "basses" {
        \bassWords
      }
    >>  % end ChoirStaff

    \new PianoStaff <<
      \set PianoStaff.instrumentName = "Piano  "
      \new Staff = "upper" \upper
      \new Staff = "lower" \lower
    >>
  >>
}

3.4.3 Building a score from scratch

After gaining some facility with writing LilyPond code, you may find that it is easier to build a score from scratch rather than modifying one of the templates. You can also develop your own style this way to suit the sort of music you like. Let’s see how to put together the score for an organ prelude as an example.

We begin with a header section. Here go the title, name of composer, etc, then come any variable definitions, and finally the score block. Let’s start with these in outline and fill in the details later.

We’ll use the first two bars of Bach’s prelude based on Jesu, meine Freude which is written for two manuals and pedal organ. You can see these two bars of music at the bottom of this section. The top manual part has two voices, the lower and pedal organ one each. So we need four music definitions and one to define the time signature and key:

\version "2.23.3"
\header {
  title = "Jesu, meine Freude"
  composer = "J S Bach"
}
keyTime = { \key c \minor \time 4/4 }
ManualOneVoiceOneMusic = { s1 }
ManualOneVoiceTwoMusic = { s1 }
ManualTwoMusic = { s1 }
PedalOrganMusic = { s1 }

\score {
}

For now we’ve just used a spacer note, s1, instead of the real music. We’ll add that later.

Next let’s see what should go in the score block. We simply mirror the staff structure we want. Organ music is usually written on three staves, one for each manual and one for the pedals. The manual staves should be bracketed together, so we need to use a PianoStaff for them. The first manual part needs two voices and the second manual part just one.

\new PianoStaff <<
  \new Staff = "ManualOne" <<
    \new Voice {
      \ManualOneVoiceOneMusic
    }
    \new Voice {
      \ManualOneVoiceTwoMusic
    }
  >>  % end ManualOne Staff context
  \new Staff = "ManualTwo" <<
    \new Voice {
      \ManualTwoMusic
    }
  >>  % end ManualTwo Staff context
>>  % end PianoStaff context

Next we need to add a staff for the pedal organ. This goes underneath the PianoStaff, but it must be simultaneous with it, so we need angle brackets around the two. Missing these out would generate an error in the log file. It’s a common mistake which you’ll make sooner or later! Try copying the final example at the end of this section, remove these angle brackets, and compile it to see what errors it generates.

<<  % PianoStaff and Pedal Staff must be simultaneous
  \new PianoStaff <<
    \new Staff = "ManualOne" <<
      \new Voice {
        \ManualOneVoiceOneMusic
      }
      \new Voice {
        \ManualOneVoiceTwoMusic
      }
    >>  % end ManualOne Staff context
    \new Staff = "ManualTwo" <<
      \new Voice {
        \ManualTwoMusic
      }
    >>  % end ManualTwo Staff context
  >>  % end PianoStaff context
  \new Staff = "PedalOrgan" <<
    \new Voice {
      \PedalOrganMusic
    }
  >>
>>

It is not necessary to use the simultaneous construct << .. >> for the manual two staff and the pedal organ staff, since they contain only one music expression, but it does no harm, and always using angle brackets after \new Staff is a good habit to cultivate in case there are multiple voices. The opposite is true for Voices: these should habitually be followed by braces { .. } in case your music is coded in several variables which need to run consecutively.

Let’s add this structure to the score block, and adjust the indenting. We also add the appropriate clefs, ensure stems, ties and slurs in each voice on the upper staff point to the right direction with \voiceOne and \voiceTwo, and enter the key and time signature to each staff using our predefined variable, \keyTime.

\score {
  <<  % PianoStaff and Pedal Staff must be simultaneous
    \new PianoStaff <<
      \new Staff = "ManualOne" <<
        \keyTime  % set key and time signature
        \clef "treble"
        \new Voice {
          \voiceOne
          \ManualOneVoiceOneMusic
        }
        \new Voice {
          \voiceTwo
          \ManualOneVoiceTwoMusic
        }
      >>  % end ManualOne Staff context
      \new Staff = "ManualTwo" <<
        \keyTime
        \clef "bass"
        \new Voice {
          \ManualTwoMusic
        }
      >>  % end ManualTwo Staff context
    >>  % end PianoStaff context
    \new Staff = "PedalOrgan" <<
      \keyTime
      \clef "bass"
      \new Voice {
        \PedalOrganMusic
      }
    >>  % end PedalOrgan Staff
  >>
}  % end Score context

The above layout of the organ staves is almost perfect; however, there is a slight defect which is not visible by looking at just a single system: The distance of the pedal staff to the left hand staff should behave approximately the same as the right hand staff to the left hand staff. In particular, the stretchability of staves in a PianoStaff context is limited (so that the distance between the staves for the left and right hand can’t become too large), and the pedal staff should behave similarly.

Stretchability of staves can be controlled with the staff-staff-spacing property of the VerticalAxisGroup ‘graphical object’ (commonly called ‘grob’s within the lilypond documentation) – don’t worry about the details right now; this is fully explained later. For the curious, have a look at Overview of modifying properties. In this case, we want to modify the stretchability sub-property only. Again, for the curious, you can find the default values for the staff-staff-spacing property in file ‘scm/define-grobs.scm’ by looking up the definition of the VerticalAxisGroup grob. The value for stretchability is taken from the definition of the PianoStaff context (in file ‘ly/engraver-init.ly’) so that the values are identical.

\score {
  <<  % PianoStaff and Pedal Staff must be simultaneous
    \new PianoStaff <<
      \new Staff = "ManualOne" <<
        \keyTime  % set key and time signature
        \clef "treble"
        \new Voice {
          \voiceOne
          \ManualOneVoiceOneMusic
        }
        \new Voice {
          \voiceTwo
          \ManualOneVoiceTwoMusic
        }
      >>  % end ManualOne Staff context
      \new Staff = "ManualTwo" \with {
        \override VerticalAxisGroup.staff-staff-spacing.stretchability = 5
      } <<
        \keyTime
        \clef "bass"
        \new Voice {
          \ManualTwoMusic
        }
      >>  % end ManualTwo Staff context
    >>  % end PianoStaff context
    \new Staff = "PedalOrgan" <<
      \keyTime
      \clef "bass"
      \new Voice {
        \PedalOrganMusic
      }
    >>  % end PedalOrgan Staff
  >>
}  % end Score context

That completes the structure. Any three-staff organ music will have a similar structure, although the number of voices may vary. All that remains now is to add the music, and combine all the parts together.

\header {
  title = "Jesu, meine Freude"
  composer = "J S Bach"
}
keyTime = { \key c \minor \time 4/4 }
ManualOneVoiceOneMusic = \relative {
  g'4 g f ees |
  d2 c |
}
ManualOneVoiceTwoMusic = \relative {
  ees'16 d ees8~ 16 f ees d c8 d~ d c~ |
  8 c4 b8 c8. g16 c b c d |
}
ManualTwoMusic = \relative {
  c'16 b c8~ 16 b c g a8 g~ 16 g aes ees |
  f16 ees f d g aes g f ees d ees8~ 16 f ees d |
}
PedalOrganMusic = \relative {
  r8 c16 d ees d ees8~ 16 a, b g c b c8 |
  r16 g ees f g f g8 c,2 |
}

\score {
  <<  % PianoStaff and Pedal Staff must be simultaneous
    \new PianoStaff <<
      \new Staff = "ManualOne" <<
        \keyTime  % set key and time signature
        \clef "treble"
        \new Voice {
          \voiceOne
          \ManualOneVoiceOneMusic
        }
        \new Voice {
          \voiceTwo
          \ManualOneVoiceTwoMusic
        }
      >>  % end ManualOne Staff context
      \new Staff = "ManualTwo" \with {
        \override VerticalAxisGroup.staff-staff-spacing.stretchability = 5
      } <<
        \keyTime
        \clef "bass"
        \new Voice {
          \ManualTwoMusic
        }
      >>  % end ManualTwo Staff context
    >>  % end PianoStaff context
    \new Staff = "PedalOrgan" <<
      \keyTime
      \clef "bass"
      \new Voice {
        \PedalOrganMusic
      }
    >>  % end PedalOrgan Staff context
  >>
}  % end Score context

Zie ook

Music Glossary: system.

3.4.4 Saving typing with variables and functions

By this point, you’ve seen this kind of thing:

hornNotes = \relative { c''4 b dis c }

\score {
  {
    \hornNotes
  }
}

You may even realize that this could be useful in minimalist music:

fragmentA = \relative { a'4 a8. b16 }
fragmentB = \relative { a'8. gis16 ees4 }

violin = \new Staff {
  \fragmentA \fragmentA |
  \fragmentB \fragmentA |
}

\score {
  {
    \violin
  }
}

However, you can also use these variables (also known as macros, or user-defined commands) for tweaks:

dolce = \markup { \italic \bold dolce }

padText = { \once \override TextScript.padding = #5.0 }
fthenp =_\markup {
  \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p
}

violin = \relative {
  \repeat volta 2 {
    c''4._\dolce b8 a8 g a b |
    \padText
    c4.^"hi there!" d8 e' f g d |
    c,4.\fthenp b8 c4 c-. |
  }
}

\score {
  {
    \violin
  }
  \layout { ragged-right = ##t }
}

These variables are obviously useful for saving typing. But they’re worth considering even if you only use them once – they reduce complexity. Let’s look at the previous example without any variables. It’s a lot harder to read, especially the last line.

violin = \relative {
  \repeat volta 2 {
    c''4._\markup { \italic \bold dolce } b8 a8 g a b |
    \once \override TextScript.padding = #5.0
    c4.^"hi there!" d8 e' f g d |
    c,4.\markup {
      \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p
    }
    b8 c4 c-. |
  }
}

So far we’ve seen static substitution – when LilyPond sees \padText, it replaces it with the stuff that we’ve defined it to be (ie the stuff to the right of padtext=).

LilyPond can handle non-static substitution, too (you can think of these as functions).

padText =
#(define-music-function
     (padding)
     (number?)
   #{
     \once \override TextScript.padding = #padding
   #})

\relative {
  c'''4^"piu mosso" b a b |
  \padText #1.8
  c4^"piu mosso" d e f |
  \padText #2.6
  c4^"piu mosso" fis a g |
}

Using variables is also a good way to reduce work if the LilyPond input syntax changes (see Updating files with convert-ly). If you have a single definition (such as \dolce) for all your input files (see Style sheets), then if the syntax changes, you only need to update your single \dolce definition, instead of making changes throughout every ‘.ly’ file.

3.4.5 Scores and parts

In orchestral music, all notes are printed twice. Once in a part for the musicians, and once in a full score for the conductor. Variables can be used to avoid double work. The music is entered once, and stored in a variable. The contents of that variable is then used to generate both the part and the full score.

It is convenient to define the notes in a special file. For example, suppose that the file ‘horn-music.ly’ contains the following part of a horn/bassoon duo

hornNotes = \relative {
  \time 2/4
  r4 f8 a | cis4 f | e4 d |
}

Then, an individual part is made by putting the following in a file

\include "horn-music.ly"

\header {
  instrument = "Horn in F"
}

{
 \transpose f c' \hornNotes
}

The line

\include "horn-music.ly"

substitutes the contents of ‘horn-music.ly’ at this position in the file, so hornNotes is defined afterwards. The command \transpose f c' indicates that the argument, being \hornNotes, should be transposed by a fifth upwards. Sounding f is denoted by notated c', which corresponds with the tuning of a normal French Horn in F. The transposition can be seen in the following output

In ensemble pieces, one of the voices often does not play for many measures. This is denoted by a special rest, the multi-measure rest. It is entered with a capital R followed by a duration (1 for a whole note, 2 for a half note, etc.). By multiplying the duration, longer rests can be constructed. For example, this rest takes 3 measures in 2/4 time

R2*3

When printing the part, multi-rests must be condensed. This is done by setting a run-time variable

\set Score.skipBars = ##t

This command sets the property skipBars in the Score context to true (##t). Prepending the rest and this option to the music above, leads to the following result

The score is made by combining all of the music together. Assuming that the other voice is in bassoonNotes in the file ‘bassoon-music.ly’, a score is made with

\include "bassoon-music.ly"
\include "horn-music.ly"

<<
  \new Staff \hornNotes
  \new Staff \bassoonNotes
>>

leading to

4 Tweaking output

This chapter discusses how to modify output. LilyPond is extremely configurable; virtually every fragment of output may be changed.

4.1 Tweaking basics

4.1.1 Introduction to tweaks

‘Tweaking’ is a LilyPond term for the various methods available to the user for modifying the actions taken during interpretation of the input file and modifying the appearance of the printed output. Some tweaks are very easy to use; others are more complex. But taken together the methods available for tweaking permit almost any desired appearance of the printed music to be achieved.

In this section we cover the basic concepts required to understand tweaking. Later we give a variety of ready-made commands which can simply be copied to obtain the same effect in your own scores, and at the same time we show how these commands may be constructed so that you may learn how to develop your own tweaks.

Before starting on this Chapter you may wish to review the section Contexts and engravers, as Contexts, Engravers, and the Properties contained within them are fundamental to understanding and constructing Tweaks.

4.1.2 Objects and interfaces

Tweaking involves modifying the internal operation and structures of the LilyPond program, so we must first introduce some terms which are used to describe those internal operations and structures.

The term ‘Object’ is a generic term used to refer to the multitude of internal structures built by LilyPond during the processing of an input file. So when a command like \new Staff is encountered a new object of type Staff is constructed. That Staff object then holds all the properties associated with that particular staff, for example, its name and its key signature, together with details of the engravers which have been assigned to operate within that staff’s context. Similarly, there are objects to hold the properties of all other contexts, such as Voice objects, Score objects, Lyrics objects, as well as objects to represent all notational elements such as bar lines, note heads, ties, dynamics, etc. Every object has its own set of property values.

Some types of object are given special names. Objects which represent items of notation on the printed output such as note heads, stems, slurs, ties, fingering, clefs, etc are called ‘Layout objects’, often known as ‘Graphical Objects’, or ‘Grobs’ for short. These are still objects in the generic sense above, and so they too all have properties associated with them, such as their position, size, color, etc.

Some layout objects are still more specialized. Phrasing slurs, crescendo hairpins, ottava marks, and many other grobs are not localized in a single place – they have a starting point, an ending point, and maybe other properties concerned with their shape. Objects with an extended shape like these are called ‘Spanners’.

It remains to explain what ‘Interfaces’ are. Many objects, even though they are quite different, share common features which need to be processed in the same way. For example, all grobs have a color, a size, a position, etc, and all these properties are processed in the same way during LilyPond’s interpretation of the input file. To simplify these internal operations these common actions and properties are grouped together in an object called a grob-interface. There are many other groupings of common properties like this, each one given a name ending in interface. In total there are over 100 such interfaces. We shall see later why this is of interest and use to the user.

These, then, are the main terms relating to objects which we shall use in this chapter.

4.1.3 Naming conventions of objects and properties

We met some object naming conventions previously, in Contexts and engravers. Here for reference is a list of the most common object and property types together with the conventions for naming them and a couple of examples of some real names. We have used ‘A’ to stand for any capitalized alphabetic character and ‘aaa’ to stand for any number of lower-case alphabetic characters. Other characters are used verbatim.

As we shall see shortly, the properties of different types of object are modified by different commands, so it is useful to be able to recognize the types of objects and properties from their names.

4.1.4 Tweaking methods

The \override command

We have already met the commands \set and \with, used to change the properties of contexts and to remove and add engravers, in Modifying context properties, and Adding and removing engravers. We must now introduce some more important commands.

The command to change the properties of layout objects is \override. Because this command has to modify internal properties deep within LilyPond its syntax is not as simple as the commands you have used so far. It needs to know precisely which property of which object in which context has to be modified, and what its new value is to be. Let’s see how this is done.

The general syntax of this command is:

\override Context.LayoutObject.layout-property = #value

This will set the property with the name layout-property of the layout object with the name LayoutObject, which is a member of the Context context, to the value value.

The Context may be omitted (and usually is) when the required context is unambiguously implied and is one of lowest level contexts, i.e., Voice, ChordNames or Lyrics, and we shall omit it in many of the following examples. We shall see later when it must be specified.

Later sections deal comprehensively with properties and their values, see Types of properties. But in this section we shall use just a few simple properties and values which are easily understood in order to illustrate the format and use of these commands.

LilyPond’s primary expressions are musical items like notes, durations, and markups. More basic expressions like numbers, strings, and lists are processed in ‘Scheme mode’, which is invoked by prefixing the value with ‘#’. Although the values may sometimes have a valid representation in LilyPond’s musical mode, this manual will always use ‘#’ for their entry for the sake of consistency. For more information about Scheme mode, see LilyPond Scheme syntax.

\override is the most common command used in tweaking, and most of the rest of this chapter will be directed to presenting examples of how it is used. Here is a simple example to change the color of the note head:

\relative {
  c'4 d
  \override NoteHead.color = #red
  e4 f |
  \override NoteHead.color = #green
  g4 a b c |
}

The \revert command

Once overridden, the property retains its new value until it is overridden again or a \revert command is encountered. The \revert command has the following syntax and causes the value of the property to revert to its original default value; note, not its previous value if several \override commands have been issued.

\revert Context.LayoutObject.layout-property

Again, just like Context in the \override command, Context is often not needed. It will be omitted in many of the following examples. Here we revert the color of the note head to the default value for the final two notes:

\relative {
  c'4 d
  \override NoteHead.color = #red
  e4 f |
  \override NoteHead.color = #green
  g4 a
  \revert NoteHead.color
  b4 c |
}

The \once prefix

Both the \override and the \set commands may be prefixed by \once. This causes the following \override or \set command to be effective only during the current musical moment before the property reverts back to its previous value (this can be different from the default if another \override is still in effect). Using the same example, we can change the color of a single note like this:

c4 d
\override NoteHead.color = #red
e4 f |
\once \override NoteHead.color = #green
g4 a
\revert NoteHead.color
b c |

The \overrideProperty command

There is another form of the override command, \overrideProperty, which is occasionally required. We mention it here for completeness, but for details see Difficult tweaks.

The \tweak command

The final tweaking command which is available is \tweak. This should be used when several objects occur at the same musical moment, but you only want to change the properties of selected ones, such as a single note within a chord. Using \override would affect all the notes within a chord, whereas \tweak affects just the following item in the input stream.

Here’s an example. Suppose we wish to change the size of the middle note head (the E) in a C major chord. Let’s first see what \once \override would do:

\relative {
  <c' e g>4
  \once \override NoteHead.font-size = #-3
  <c e g>4
  <c e g>4
}

We see the override affects all the note heads in the chord. This is because all the notes of a chord occur at the same musical moment, and the action of \once is to apply the override to all layout objects of the type specified which occur at the same musical moment as the \override command itself.

The \tweak command operates in a different way. It acts on the immediately following item in the input stream. In its simplest form, it is effective only on objects which are created directly from the following item, essentially note heads and articulations.

So to return to our example, the size of the middle note of a chord would be changed in this way:

\relative {
  <c' e g>4
  <c \tweak font-size #-3 e g>4
}

Note that the syntax of \tweak is different from that of the \override command. The context should not be specified; in fact, it would generate an error to do so. Both context and layout object are implied by the following item in the input stream. Note also that an equals sign should not be present. So the simple form of the \tweak command is

\tweak layout-property #value

A \tweak command can also be used to modify just one in a series of articulations, as shown here:

a'4^"Black"
  -\tweak color #red ^"Red"
  -\tweak color #green _"Green"

Note that the \tweak command must be preceded by an articulation mark since the tweaked expression needs to be applied as an articulation itself. In case of multiple direction overrides (^ or _), the leftmost override wins since it is applied last.

Objects such as stems and accidentals are created later, and not directly from the following event. It is still possible to use \tweak on such indirectly created objects by explicitly naming the layout object, provided that LilyPond can trace its origin back to the original event:

<\tweak Accidental.color #red   cis''4
 \tweak Accidental.color #green es''
 g''>

This long form of the \tweak command can be described as

\tweak layout-object.layout-property value

The \tweak command must also be used to change the appearance of one of a set of nested tuplets which begin at the same musical moment. In the following example, the long tuplet bracket and the first of the three short brackets begin at the same musical moment, so any \override command would apply to both of them. In the example, \tweak is used to distinguish between them. The first \tweak command specifies that the long tuplet bracket is to be placed above the notes and the second one specifies that the tuplet number is to be printed in red on the first short tuplet bracket.

\relative c'' {
  \tweak direction #up
  \tuplet 3/4 {
    \tweak color #red
    \tuplet 3/2 { c8[ c c] }
    \tuplet 3/2 { c8[ c c] }
    \tuplet 3/2 { c8[ c c] }
  }
}

If nested tuplets do not begin at the same moment, their appearance may be modified in the usual way with \override commands:

\relative {
  \tuplet 3/2 { c'8[ c c] }
  \once \override TupletNumber.text = #tuplet-number::calc-fraction-text
  \tuplet 3/2 {
    c8[ c]
    c8[ c]
    \once \override TupletNumber.transparent = ##t
    \tuplet 3/2 { c8[ c c] }
    \tuplet 3/2 { c8[ c c] }
  }
}

Zie ook

Notation Reference: The tweak command.

4.2 The Internals Reference manual

4.2.1 Properties of layout objects

Suppose you have a slur in a score which, to your mind, appears too thin and you’d like to draw it a little heavier. How do you go about doing this? You know from the statements earlier about the flexibility of LilyPond that such a thing should be possible, and you would probably guess that an \override command would be needed. But is there a heaviness property for a slur, and if there is, how might it be modified? This is where the Internals Reference manual comes in. It contains all the information you might need to construct this and all other \override commands.

Before we look at the Internals Reference a word of warning. This is a reference document, which means there is little or no explanation contained within it: its purpose is to present information precisely and concisely. This means it might look daunting at first sight. Don’t worry! The guidance and explanation presented here will enable you to extract the information from the Internals Reference for yourself with just a little practice.

Let’s use a concrete example with a simple fragment of real music:

{
  \key es \major
  \time 6/8
  \relative {
    r4 bes'8 bes[( g]) g |
    g8[( es]) es d[( f]) as |
    as8 g
  }
  \addlyrics {
    The man who | feels love's sweet e -- | mo -- tion
  }
}

Suppose now that we decide we would like the slurs to be a little heavier. Is this possible? The slur is certainly a layout object, so the question is, ‘Is there a property belonging to a slur which controls the heaviness?’ To answer this we must look in the Internals Reference, or IR for short.

The IR for the version of LilyPond you are using may be found on the LilyPond website at https://lilypond.org. Go to the documentation page and click on the Internals Reference link. For learning purposes you should use the standard HTML version, not the ‘one big page’ or the PDF. For the next few paragraphs to make sense you will need to actually do this as you read.

Under the heading Top you will see five links. Select the link to the Backend, which is where information about layout objects is to be found. There, under the heading Backend, select the link to All layout objects. The page that appears lists all the layout objects used in your version of LilyPond, in alphabetic order. Select the link to Slur, and the properties of Slurs are listed.

An alternative way of finding this page is from the Notation Reference. On one of the pages that deals with slurs you may find a link to the Internals Reference. This link will take you directly to this page, but if you have an idea about the name of the layout object to be tweaked, it is easier to go straight to the IR and search there.

This Slur page in the IR tells us first that Slur objects are created by the Slur_engraver. Then it lists the standard settings. Browse through them looking for a property that might control the heaviness of slurs, and you should find

thickness (number)
     1.2
     Line thickness, generally measured in line-thickness

This looks a good bet to change the heaviness. It tells us that the value of thickness is a simple number, that the default value is 1.2, and that the units are in another property called line-thickness.

As we said earlier, there are few to no explanations in the IR, but we already have enough information to try changing the slur thickness. We see that the name of the layout object is Slur, that the name of the property to change is thickness and that the new value should be a number somewhat larger than 1.2 if we are to make slurs thicker.

We can now construct the \override command by simply substituting the values we have found for the names, omitting the context. Let’s use a very large value for the thickness at first, so we can be sure the command is working. We get:

\override Slur.thickness = #5.0

Don’t forget the # preceding the new value!

The final question is, ‘Where should this command be placed?’ While you are unsure and learning, the best answer is, ‘Within the music, before the first slur and close to it.’ Let’s do that:

{
  \key es \major
  \time 6/8
  \relative {
    % Increase thickness of all following slurs from 1.2 to 5.0
    \override Slur.thickness = #5.0
    r4 bes'8 bes[( g]) g |
    g8[( es]) es d[( f]) as |
    as8 g
  }
  \addlyrics {
    The man who | feels love's sweet e -- | mo -- tion
  }
}

and we see that the slur is indeed heavier.

So this is the basic way of constructing \override commands. There are a few more complications that we shall meet in later sections, but you now know all the essentials required to make up your own – but you will still need some practice. This is provided in the examples which follow.

Finding the context

But first, what if we had needed to specify the Context? What should it be? We could guess that slurs are in the Voice context, as they are clearly closely associated with individual lines of music, but can we be sure? To find out, go back to the top of the IR page describing the Slur, where it says ‘Slur objects are created by: Slur engraver’. So slurs will be created in whichever context the Slur_engraver is in. Follow the link to the Slur_engraver page. At the very bottom it tells us that Slur_engraver is part of seven Voice contexts, including the standard voice context, Voice, so our guess was correct. And because Voice is one of the lowest level contexts which is implied unambiguously by the fact that we are entering notes, we can omit it in this location.

Overriding once only

As you can see, all the slurs are thicker in the final example above. But what if we wanted just the first slur to be thicker? This is achieved with the \once command. Placed immediately before the \override command it causes it to change only the slur which begins on the immediately following note. If the immediately following note does not begin a slur the command has no effect at all – it is not remembered until a slur is encountered, it is simply discarded. So the command with \once must be repositioned as follows:

{
  \key es \major
  \time 6/8
  \relative {
    r4 bes'8
    % Increase thickness of immediately following slur only
    \once \override Slur.thickness = #5.0
    bes8[( g]) g |
    g8[( es]) es d[( f]) as |
    as8 g
  }
  \addlyrics {
    The man who | feels love's sweet e -- | mo -- tion
  }
}

Now only the first slur is made heavier.

The \once command can also be used before the \set command.

Reverting

Finally, what if we wanted just the first two slurs to be heavier? Well, we could use two commands, each preceded by \once placed immediately before each of the notes where the slurs begin:

{
  \key es \major
  \time 6/8
  \relative {
    r4 bes'8
    % Increase thickness of immediately following slur only
    \once \override Slur.thickness = #5.0
    bes[( g]) g |
    % Increase thickness of immediately following slur only
    \once \override Slur.thickness = #5.0
    g8[( es]) es d[( f]) as |
    as8 g
  }
  \addlyrics {
    The man who | feels love's sweet e -- | mo -- tion
  }
}

or we could omit the \once command and use the \revert command to return the thickness property to its default value after the second slur:

{
  \key es \major
  \time 6/8
  \relative {
    r4 bes'8
    % Increase thickness of all following slurs from 1.2 to 5.0
    \override Slur.thickness = #5.0
    bes[( g]) g |
    g8[( es]) es
    % Revert thickness of all following slurs to default of 1.2
    \revert Slur.thickness
    d8[( f]) as |
    as8 g
  }
  \addlyrics {
    The man who | feels love's sweet e -- | mo -- tion
  }
}

The \revert command can be used to return any property changed with \override back to its default value. You may use whichever method best suits what you want to do.

That concludes our introduction to the IR, and the basic method of tweaking. Several examples follow in the later sections of this Chapter, partly to introduce you to some of the additional features of the IR, and partly to give you more practice in extracting information from it. These examples will contain progressively fewer words of guidance and explanation.

4.2.2 Properties found in interfaces

Suppose now that we wish to print the lyrics in italics. What form of \override command do we need to do this? We first look in the IR page listing ‘All layout objects’, as before, and look for an object that might control lyrics. We find LyricText, which looks right. Clicking on this shows the settable properties for lyric text. These include the font-series and font-size, but nothing that might give an italic shape. This is because the shape property is one that is common to all font objects, so, rather than including it in every layout object, it is grouped together with other similar common properties and placed in an Interface, the font-interface.

So now we need to learn how to find the properties of interfaces, and to discover what objects use these interface properties.

Look again at the IR page which describes LyricText. At the bottom of the page is a list of clickable interfaces which LyricText supports. The list has several items, including font-interface. Clicking on this brings up the properties associated with this interface, which are also properties of all the objects which support it, including LyricText.

Now we see all the user-settable properties which control fonts, including font-shape(symbol), where symbol can be set to upright, italics or caps.

You will notice that font-series and font-size are also listed there. This immediately raises the question: Why are the common font properties font-series and font-size listed under LyricText as well as under the interface font-interface but font-shape is not? The answer is that font-series and font-size are changed from their global default values when a LyricText object is created, but font-shape is not. The entries in LyricText then tell you the values for those two properties which apply to LyricText. Other objects which support font-interface will set these properties differently when they are created.

Let’s see if we can now construct the \override command to change the lyrics to italics. The object is LyricText, the property is font-shape and the value is italic. As before, we’ll omit the context.

As an aside, although it is an important one, note that some properties take values that are symbols, like italic, and must be preceded by an apostrophe, '. Symbols are then read internally by LilyPond. Note the distinction from arbitrary text strings, which would appear as "a text string"; for more details about symbols and strings, see Scheme tutorial.

So we see that the \override command needed to print the lyrics in italics is:

\override LyricText.font-shape = #'italic

This should be placed just in front of the lyrics we wish to affect, like so:

{
  \key es \major
  \time 6/8
  \relative {
    r4 bes'8 bes[( g]) g |
    g8[( es]) es d[( f]) as |
    as8 g
  }
  \addlyrics {
    \override LyricText.font-shape = #'italic
    The man who | feels love's sweet e -- | mo -- tion
  }
}

and the lyrics are all printed in italics.

Zie ook

Extending: Scheme tutorial.

4.2.3 Types of properties

So far we have seen two types of property: number and symbol. To be valid, the value given to a property must be of the correct type and obey the rules for that type. The type of property is always shown in brackets after the property name in the IR. Here is a list of the types you may need, together with the rules for that type, and some examples. You must always add a hash symbol, #, of course, to the front of these values when they are entered in the \override command, even if the value itself already starts with #. We only give examples for constants here: if you want to compute a value using Scheme, see Calculations in Scheme.

Zie ook

Extending: Scheme tutorial.

4.3 Appearance of objects

Let us now put what we have learned into practice with a few examples which show how tweaks may be used to change the appearance of the printed music.

4.3.1 Visibility and color of objects

In the educational use of music we might wish to print a score with certain elements omitted as an exercise for the student, who is required to supply them. As a simple example, let us suppose the exercise is to supply the missing bar lines in a piece of music. But the bar lines are normally inserted automatically. How do we prevent them printing?

Before we tackle this, let us remember that object properties are grouped in what are called interfaces – see Properties found in interfaces. This is simply to group together those properties that may be used together to tweak a graphical object – if one of them is allowed for an object, so are the others. Some objects then use the properties in some interfaces, others use them from other interfaces. The interfaces which contain the properties used by a particular grob are listed in the IR at the bottom of the page describing that grob, and those properties may be viewed by looking at those interfaces.

We explained how to find information about grobs in Properties of layout objects. Using the same approach, we go to the IR to find the layout object which prints bar lines. Going via Backend and All layout objects we find there is a layout object called BarLine. Its properties include two that control its visibility: break-visibility and stencil. Barline also supports a number of interfaces, including the grob-interface, where we find the transparent and the color properties. All of these can affect the visibility of bar lines (and, of course, by extension, many other layout objects too.) Let’s consider each of these in turn.

The stencil property

This property controls the appearance of the bar lines by specifying the symbol (glyph) which should be printed. In common with many other properties, it can be set to print nothing by setting its value to #f. Let’s try it, as before, omitting the implied Context, Voice:

\relative {
  \time 12/16
  \override BarLine.stencil = ##f
  c''4 b8 c d16 c d8 |
  g,8 a16 b8 c d4 e16 |
  e8
}

The bar lines are still printed. What is wrong? Go back to the IR and look again at the page giving the properties of BarLine. At the top of the page it says “Barline objects are created by: Bar_engraver”. Go to the Bar_engraver page. At the bottom it gives a list of Contexts in which the bar engraver operates. All of them are of the type Staff, so the reason the \override command failed to work as expected is because Barline is not in the default Voice context. If the context is specified incorrectly, the command simply does not work. No error message is produced, and nothing is logged in the log file. Let’s try correcting it by adding the correct context:

\relative {
  \time 12/16
  \override Staff.BarLine.stencil = ##f
  c''4 b8 c d16 c d8 |
  g,8 a16 b8 c d4 e16 |
  e8
}

Now the bar lines have vanished. Setting the stencil property to #f is such a frequent operation that there is a shorthand for it called \omit:

\relative {
  \time 12/16
  \omit Staff.BarLine
  c''4 b8 c d16 c d8 |
  g,8 a16 b8 c d4 e16 |
  e8
}

Note, though, that setting the stencil property to #f will cause errors when the dimensions of the object are required for correct processing. For example, errors will be generated if the stencil property of the NoteHead object is set to #f. If this is the case, you can instead use the point-stencil function, which sets the stencil to an object with zero size:

\relative {
  c''4 c
  \once \override NoteHead.stencil = #point-stencil
  c4 c
}

The break-visibility property

We see from the BarLine properties in the IR that the break-visibility property requires a vector of three booleans. These control respectively whether bar lines are printed at the end of a line, in the middle of lines, and at the beginning of lines. For our example we want all bar lines to be suppressed, so the value we need is #(#f #f #f) (also available under the name all-invisible). Let’s try that, remembering to include the Staff context. Note also that in writing this value we have ## before the opening parenthesis. One # is required as part of vector constant syntax, and the first # is required, as always, to precede the value itself in the \override command.

\relative {
  \time 12/16
  \override Staff.BarLine.break-visibility = ##(#f #f #f)
  c''4 b8 c d16 c d8 |
  g,8 a16 b8 c d4 e16 |
  e8
}

And we see this too removes all the bar lines.

The transparent property

We see from the properties specified in the grob-interface page in the IR that the transparent property is a boolean. This should be set to #t to make the grob transparent. In this next example let us make the time signature invisible rather than the bar lines. To do this we need to find the grob name for the time signature. Back to the ‘All layout objects’ page in the IR to find the properties of the TimeSignature layout object. This is produced by the Time_signature_engraver which you can check also lives in the Staff context and also supports the grob-interface. So the command to make the time signature transparent is:

\relative {
  \time 12/16
  \override Staff.TimeSignature.transparent = ##t
  c''4 b8 c d16 c d8 |
  g,8 a16 b8 c d4 e16 |
  e8
}

Again, setting the transparent property is a rather frequent operation, so we have a shorthand for it called \hide:

\relative {
  \time 12/16
  \hide Staff.TimeSignature
  c''4 b8 c d16 c d8 |
  g,8 a16 b8 c d4 e16 |
  e8
}

In either case, the time signature is gone, but this command leaves a gap where the time signature should be. Maybe this is what is wanted for an exercise for the student to fill it in, but in other circumstances a gap might be undesirable. To remove it, the stencil for the time signature should be set to #f instead:

\relative {
  \time 12/16
  \omit Staff.TimeSignature
  c''4 b8 c d16 c d8 |
  g,8 a16 b8 c d4 e16 |
  e8
}

and the difference is obvious: setting the stencil to #f (possibly via \omit) removes the object entirely; making the object transparent (which can be done using \hide) leaves it where it is, but makes it invisible.

The color property

Finally let us try making the bar lines invisible by coloring them white. (There is a difficulty with this in that the white bar line may or may not blank out the staff lines where they cross. You may see in some of the examples below that this happens unpredictably. The details of why this is so and how to control it are covered in Painting objects white. But at the moment we are learning about color, so please just accept this limitation for now.)

The grob-interface specifies that the color property value is a list, but there is no explanation of what that list should be. The list it requires is actually a list of values in internal units, but, to avoid having to know what these are, several ways are provided to specify colors. The first way is to use one of the ‘normal’ colors listed in the first table in List of colors. To set the bar lines to white we write:

\relative {
  \time 12/16
  \override Staff.BarLine.color = #white
  c''4 b8 c d16 c d8 |
  g,8 a16 b8 c d4 e16 |
  e8
}

and again, we see the bar lines are not visible. Note that white is not preceded by an apostrophe – it is not a symbol, but a variable. When evaluated, it provides the list of internal values required to set the color to white. The other colors in the normal list are variables too. To convince yourself this is working you might like to change the color to one of the other variables in the list.

The second way of changing the color is to use the list of X11 color names in the second list in List of colors. However, these are mapped to the actual values by the function x11-color which converts X11 color symbols into the list of internal values like this:

\relative {
  \time 12/16
  \override Staff.BarLine.color = #(x11-color 'white)
  c''4 b8 c d16 c d8 |
  g,8 a16 b8 c d4 e16 |
  e8
}

Note that in this case the function x11-color takes a symbol as an argument, so the symbol must be preceded by an apostrophe to keep it from being evaluated as a variable, and the whole function call has to be enclosed in parentheses.

There is another function, one which converts RGB values into internal colors – the rgb-color function. This takes three arguments giving the intensities of the red, green and blue colors. These take values in the range 0 to 1. So to set the color to red the value should be (rgb-color 1 0 0) and to white it should be (rgb-color 1 1 1):

\relative {
  \time 12/16
  \override Staff.BarLine.color = #(rgb-color 1 1 1)
  c''4 b8 c d16 c d8 |
  g,8 a16 b8 c d4 e16 |
  e8
}

Finally, there is also a grey scale available as part of the X11 set of colors. These range from black, 'grey0, to white, 'grey100, in steps of 1. Let’s illustrate this by setting all the layout objects in our example to various shades of grey:

\relative {
  \time 12/16
  \override Staff.StaffSymbol.color = #(x11-color 'grey30)
  \override Staff.TimeSignature.color = #(x11-color 'grey60)
  \override Staff.Clef.color = #(x11-color 'grey60)
  \override Voice.NoteHead.color = #(x11-color 'grey85)
  \override Voice.Stem.color = #(x11-color 'grey85)
  \override Staff.BarLine.color = #(x11-color 'grey10)
  c''4 b8 c d16 c d8 |
  g,8 a16 b8 c d4 e16 |
  e8
}

Note the contexts associated with each of the layout objects. It is important to get these right, or the commands will not work! Remember, the context is the one in which the appropriate engraver is placed. The default context for engravers can be found by starting from the layout object, going from there to the engraver which produces it, and on the engraver page in the IR it tells you in which context the engraver will normally be found.

4.3.2 Size of objects

Let us begin by looking again at the earlier example (see Nesting music expressions) which showed how to introduce a new temporary staff, as in an ossia.

\new Staff ="main" {
  \relative {
    r4 g'8 g c4 c8 d |
    e4 r8
    <<
      { f8 c c }
      \new Staff \with {
        alignAboveContext = "main" }
      { f8 f c }
    >>
    r4 |
  }
}

Ossia are normally written without clef and time signature, and are usually printed slightly smaller than the main staff. We already know now how to remove the clef and time signature – we simply set the stencil of each to #f, as follows:

\new Staff ="main" {
  \relative {
    r4 g'8 g c4 c8 d |
    e4 r8
    <<
      { f8 c c }
      \new Staff \with {
        alignAboveContext = "main"
      }
      {
        \omit Staff.Clef
        \omit Staff.TimeSignature
        { f8 f c }
      }
    >>
    r4 |
  }
}

where the extra pair of braces after the \with clause are required to ensure the enclosed overrides and music are applied to the ossia staff.

But what is the difference between modifying the staff context by using \with and modifying the stencils of the clef and the time signature with \override, or in this case \omit? The main difference is that changes made in a \with clause are made at the time the context is created, and remain in force as the default values for the duration of that context, whereas \set or \override commands embedded in the music are dynamic – they make changes synchronized with a particular point in the music. If changes are unset or reverted using \unset or \revert they return to their default values, which will be the ones set in the \with clause, or if none have been set there, the normal default values.

Some context properties can be modified only in \with clauses. These are those properties which cannot sensibly be changed after the context has been created. alignAboveContext and its partner, alignBelowContext, are two such properties – once the staff has been created its alignment is decided and it would make no sense to try to change it later.

The default values of layout object properties can also be set in \with clauses. Simply use the normal \override command leaving out the context name, since this is unambiguously defined as the context which the \with clause is modifying. If fact, an error will be generated if a context is specified in this location.

So we could replace the example above with

\new Staff ="main" {
  \relative {
    r4 g'8 g c4 c8 d |
    e4 r8
    <<
      { f8 c c }
      \new Staff \with {
        alignAboveContext = "main"
        % Don't print clefs in this staff
        \override Clef.stencil = ##f
        % Don't print time signatures in this staff
        \override TimeSignature.stencil = ##f
      }
      { f8 f c }
    >>
    r4 |
  }
}

It turns out that we can also employ the shorthands \hide and \omit for setting the transparent property and clearing the stencil here, leading to the result

\new Staff ="main" {
  \relative {
    r4 g'8 g c4 c8 d |
    e4 r8
    <<
      { f8 c c }
      \new Staff \with {
        alignAboveContext = "main"
        % Don't print clefs in this staff
        \omit Clef
        % Don't print time signatures in this staff
        \omit TimeSignature
      }
      { f8 f c }
    >>
    r4 |
  }
}

Finally we come to changing the size of layout objects.

Some layout objects are created as glyphs selected from a typeface font. These include note heads, accidentals, markup, clefs, time signatures, dynamics and lyrics. Their size is changed by modifying the font-size property, as we shall shortly see. Other layout objects such as slurs and ties – in general, spanner objects – are drawn individually, so there is no font-size associated with them. These objects generally derive their size from the objects to which they are attached, so usually there is no need to change their size manually. Still other properties such as the length of stems and bar lines, thickness of beams and other lines, and the separation of staff lines all need to be modified in special ways.

Returning to the ossia example, let us first change the font-size. We can do this in two ways. We can either change the size of the fonts of each object type, like NoteHeads with commands like

\override NoteHead.font-size = #-2

or we can change the size of all fonts by setting a special property, fontSize, using \set, or by including it in a \with clause (but without the \set).

\set fontSize = #-2

Both of these statements would cause the font size to be reduced by 2 steps from its previous value, where each step reduces or increases the size by approximately 12%.

Let’s try it in our ossia example:

\new Staff ="main" {
  \relative {
    r4 g'8 g c4 c8 d |
    e4 r8
    <<
      { f8 c c }
      \new Staff \with {
        alignAboveContext = "main"
        \omit Clef
        \omit TimeSignature
        % Reduce all font sizes by ~24%
        fontSize = #-2
      }
      { f8 f c }
    >>
    r4 |
  }
}

This is still not quite right. The note heads and flags are smaller, but the stems are too long in proportion and the staff lines are spaced too widely apart. These need to be scaled down in proportion to the font reduction. The next sub-section discusses how this is done.

4.3.3 Length and thickness of objects

Distances and lengths in LilyPond are generally measured in staff-spaces, the distance between adjacent lines in the staff, (or occasionally half staff spaces) while most thickness properties are measured in units of an internal property called line-thickness. For example, by default, the lines of hairpins are given a thickness of 1 unit of line-thickness, while the thickness of a note stem is 1.3. Note, though, that some thickness properties are different; for example, the thickness of beams is controlled by the value of the beam-thickness property, which is measured in staff-spaces.

So how are lengths to be scaled in proportion to the font size? This can be done with the help of a special function called magstep provided for exactly this purpose. It takes one argument, the change in font size (#-2 in the example above) and returns a scaling factor suitable for reducing other objects in proportion. It is used like this:

\new Staff ="main" {
  \relative {
    r4 g'8 g c4 c8 d |
    e4 r8
    <<
      { f8 c c }
      \new Staff \with {
        alignAboveContext = "main"
        \omit Clef
        \omit TimeSignature
        fontSize = #-2
        % Reduce stem length and line spacing to match
        \override StaffSymbol.staff-space = #(magstep -2)
      }
      { f8 f c }
    >>
    r4 |
  }
}

Since the length of stems and many other length-related properties are always calculated relative to the value of the staff-space property these are automatically scaled down in length too. Note that this affects only the vertical scale of the ossia – the horizontal scale is determined by the layout of the main music in order to remain synchronized with it, so it is not affected by any of these changes in size. Of course, if the scale of all the main music were changed in this way then the horizontal spacing would be affected. This is discussed later in the layout section.

This, then, completes the creation of an ossia. The sizes and lengths of all other objects may be modified in analogous ways.

For small changes in scale, as in the example above, the thickness of the various drawn lines such as bar lines, beams, hairpins, slurs, etc does not usually require global adjustment. If the thickness of any particular layout object needs to be adjusted this can be best achieved by overriding its thickness property. An example of changing the thickness of slurs was shown above in Properties of layout objects. The thickness of all drawn objects (i.e., those not produced from a font) may be changed in the same way.

4.4 Placement of objects

4.4.1 Automatic behavior

There are some objects in musical notation that belong to the staff and there are other objects that should be placed outside the staff. These are called within-staff objects and outside-staff objects respectively.

Within-staff objects are those that are located on the staff – note heads, stems, accidentals, etc. The positions of these are usually fixed by the music itself – they are vertically positioned on specific lines of the staff or are tied to other objects that are so positioned. Collisions of note heads, stems and accidentals in closely set chords are normally avoided automatically. There are commands and overrides which can modify this automatic behavior, as we shall shortly see.

Objects belonging outside the staff include things such as rehearsal marks, text and dynamic markings. LilyPond’s rule for the vertical placement of outside-staff objects is to place them as close to the staff as possible but not so close that they collide with any other object. LilyPond uses the outside-staff-priority property to determine the order in which the objects should be placed, as follows.

First, LilyPond places all the within-staff objects. Then it sorts the outside-staff objects according to their outside-staff-priority. The outside-staff objects are taken one by one, beginning with the object with the lowest outside-staff-priority, and placed so that they do not collide with any objects that have already been placed. That is, if two outside-staff grobs are competing for the same space, the one with the lower outside-staff-priority will be placed closer to the staff. If two objects have the same outside-staff-priority the one encountered first will be placed closer to the staff.

In the following example all the markup texts have the same priority (since it is not explicitly set). Note that ‘Text3’ is automatically positioned close to the staff again, nestling under ‘Text2’.

c''2^"Text1"
c''2^"Text2" |
c''2^"Text3"
c''2^"Text4" |

Staves are also positioned, by default, as closely together as possible (subject to a minimum separation). If notes project a long way towards an adjacent staff they will force the staves further apart only if an overlap of the notation would otherwise occur. The following example demonstrates this ‘nestling’ of the notes on adjacent staves:

<<
  \new Staff {
    \relative { c'4 a, }
  }
  \new Staff {
    \relative { c''''4 a, }
  }
>>

4.4.2 Within-staff objects

We have already seen how the commands \voiceXXX affect the direction of slurs, ties, fingering and everything else which depends on the direction of the stems – see Explicitly instantiating voices. These commands are essential when writing polyphonic music to permit interweaving melodic lines to be distinguished. But occasionally it may be necessary to override this automatic behavior. This can be done for whole sections of music or even for an individual note. The property which controls this behavior is the direction property of each layout object. We first explain what this does, and then introduce a number of ready-made commands which avoid your having to code explicit overrides for the more common modifications.

Some layout objects like slurs and ties curve, bend or point either up or down; others like stems and flags also move to right or left when they point up or down. This is controlled automatically when direction is set.

The direction property

The following example shows in bar 1 the default behavior of stems, with those on high notes pointing down and those on low notes pointing up, followed by four notes with all stems forced down, four notes with all stems forced up, and finally four notes reverted back to the default behavior.

a4 g c a |
\override Stem.direction = #DOWN
a4 g c a |
\override Stem.direction = #UP
a4 g c a |
\revert Stem.direction
a4 g c a |

Here we use the constants DOWN and UP. These have the values -1 and +1 respectively, and these numerical values may be used instead. The value 0 may also be used in some cases. It is simply treated as meaning UP for stems, but for some objects it means ‘center’. There is a constant, CENTER which has the value 0.

However, these explicit overrides are not usually used, as there are simpler equivalent predefined commands available. Here is a table of the commonest. The meaning of each is stated where it is not obvious.

The neutral/normal variants of these commands are implemented using \revert and may not be preceded by \once. If you wish to limit the effect of the other commands (which are implemented using \override) to a single timestep, you can precede them with \once like you would do with explicit overrides.

Fingering

The placement of fingering on single notes can also be controlled by the direction property, but changing direction has no effect on chords. As we shall see, there are special commands which allow the fingering of individual notes of chords to be controlled, with the fingering being placed above, below, to the left or to the right of each note.

First, here’s the effect of direction on the fingering attached to single notes. The first bar shows the default behaviour, and the following two bars shows the effect of specifying DOWN and UP:

\relative {
  c''4-5 a-3 f-1 c'-5 |
  \override Fingering.direction = #DOWN
  c4-5 a-3 f-1 c'-5 |
  \override Fingering.direction = #UP
  c4-5 a-3 f-1 c'-5 |
}

However, overriding the direction property is not the easiest way of manually setting the fingering above or below the notes; using _ or ^ instead of - before the fingering number is usually preferable. Here is the previous example using this method:

\relative {
  c''4-5 a-3 f-1 c'-5 |
  c4_5 a_3 f_1 c'_5 |
  c4^5 a^3 f^1 c'^5 |
}

The direction property is ignored for chords, but the directional prefixes, _ and ^ do work. By default, the fingering is automatically placed both above and below the notes of a chord, as shown:

\relative {
  <c''-5 g-3>4
  <c-5 g-3 e-2>4
  <c-5 g-3 e-2 c-1>4
}

but this may be overridden to manually force all or any of the individual fingering numbers above or below:

\relative {
  <c''-5 g-3 e-2 c-1>4
  <c^5 g_3 e_2 c_1>4
  <c^5 g^3 e^2 c_1>4
}

Even greater control over the placement of fingering of the individual notes in a chord is possible by using the \set fingeringOrientations command. The format of this command is:

\set fingeringOrientations = #'([up] [left/right] [down])

\set is used because fingeringOrientations is a property of the Voice context, created and used by the New_fingering_engraver.

The property may be set to a list of one to three values. It controls whether fingerings may be placed above (if up appears in the list), below (if down appears), to the left (if left appears, or to the right (if right appears). Conversely, if a location is not listed, no fingering is placed there. LilyPond takes these constraints and works out the best placement for the fingering of the notes of the following chords. Note that left and right are mutually exclusive – fingering may be placed only on one side or the other, not both.

Here are a few examples:

\relative {
  \set fingeringOrientations = #'(left)
  <f'-2>4
  <c-1 e-2 g-3 b-5>4
  \set fingeringOrientations = #'(left)
  <f-2>4
  <c-1 e-2 g-3 b-5>4 |
  \set fingeringOrientations = #'(up left down)
  <f-2>4
  <c-1 e-2 g-3 b-5>4
  \set fingeringOrientations = #'(up left)
  <f-2>4
  <c-1 e-2 g-3 b-5>4 |
  \set fingeringOrientations = #'(right)
  <f-2>4
  <c-1 e-2 g-3 b-5>4
}

If the fingering seems a little crowded the font-size could be reduced. The default value can be seen from the Fingering object in the IR to be -5, so let’s try -7:

\relative {
  \override Fingering.font-size = #-7
  \set fingeringOrientations = #'(left)
  <f'-2>4
  <c-1 e-2 g-3 b-5>4
  \set fingeringOrientations = #'(left)
  <f-2>4
  <c-1 e-2 g-3 b-5>4 |
  \set fingeringOrientations = #'(up left down)
  <f-2>4
  <c-1 e-2 g-3 b-5>4
  \set fingeringOrientations = #'(up left)
  <f-2>4
  <c-1 e-2 g-3 b-5>4 |
  \set fingeringOrientations = #'(right)
  <f-2>4
  <c-1 e-2 g-3 b-5>4
}

4.4.3 Outside-staff objects

Outside-staff objects are automatically placed to avoid collisions. There are several ways to override the automatic placement if the positioning is not optimum.

The outside-staff-priority property

Objects with the lower value of the outside-staff-priority property are placed nearer to the staff, and other outside-staff objects are then raised as far as necessary to avoid collisions. The outside-staff-priority is defined in the grob-interface and so is a property of all layout objects. By default it is set to #f for all within-staff objects, and to a numerical value appropriate to each outside-staff object when the object is created. The following table shows the default numerical values for some of the commonest outside-staff objects.

Note the unusual names for some of the objects: spanner objects are automatically created to control the vertical positioning of grobs which (might) start and end at different musical moments, so changing the outside-staff-priority of the underlying grob will have no effect. For example, changing outside-staff-priority of the Hairpin object will have no effect on the vertical positioning of hairpins – you must change outside-staff-priority of the associated DynamicLineSpanner object instead. This override must be placed at the start of the spanner, which might include several linked hairpins and dynamics.

Here is an example showing the default placement of some of these.

% Set details for later Text Spanner
\override TextSpanner.bound-details.left.text
    = \markup { \small \bold Slower }
% Place dynamics above staff
\dynamicUp
% Start Ottava Bracket
\ottava #1
c''4 \startTextSpan
% Add Dynamic Text and hairpin
c''4\pp\<
c''4
% Add Text Script
c''4^Text |
c''4 c''
% Add Dynamic Text and terminate hairpin
c''4\ff c'' \stopTextSpan |
% Stop Ottava Bracket
\ottava #0
c'4 c' c' c' |

This example also shows how to create Text Spanners – text with extender lines above a section of music. The spanner extends from the \startTextSpan command to the \stopTextSpan command, and the format of the text is defined by the \override TextSpanner command. For more details see Text spanners.

It also shows how ottava brackets are created.

If the default values of outside-staff-priority do not give you the placing you want, the priority of any of the objects may be overridden. Suppose we would like the ottava bracket to be placed below the text spanner in the example above. All we need to do is to look up the priority of OttavaBracket in the IR or in the tables above, and reduce it to a value lower than that of a TextSpanner, remembering that OttavaBracket is created in the Staff context:

% Set details for later Text Spanner
\override TextSpanner.bound-details.left.text
    = \markup { \small \bold Slower }
% Place dynamics above staff
\dynamicUp
% Place following Ottava Bracket below Text Spanners
\once \override Staff.OttavaBracket.outside-staff-priority = #340
% Start Ottava Bracket
\ottava #1
c''4 \startTextSpan
% Add Dynamic Text
c''4\pp
% Add Dynamic Line Spanner
c''4\<
% Add Text Script
c''4^Text |
c''4 c''
% Add Dynamic Text
c''4\ff c'' \stopTextSpan |
% Stop Ottava Bracket
\ottava #0
c'4 c' c' c' |

Note that some of these objects, in particular bar numbers, metronome marks and rehearsal marks, live by default in the Score context, so be sure to use the correct context when these are being overriden.

Slurs by default are classed as within-staff objects, but they often appear above the staff if the notes to which they are attached are high on the staff. This can push outside-staff objects such as articulations too high, as the slur will be placed first. The avoid-slur property of the articulation can be set to 'inside to bring the articulation inside the slur, but the avoid-slur property is effective only if the outside-staff-priority is also set to #f. Alternatively, the outside-staff-priority of the slur can be set to a numerical value to cause it to be placed along with other outside-staff objects according to that value. Here’s an example showing the effect of the two methods:

\relative c'' {
  c4( c^\markup { \tiny \sharp } d4.) c8 |
  c4(
    \once \override TextScript.avoid-slur = #'inside
    \once \override TextScript.outside-staff-priority = ##f
    c4^\markup { \tiny \sharp } d4.) c8 |
  \once \override Slur.outside-staff-priority = #500
    c4( c^\markup { \tiny \sharp } d4.) c8 |
}

Changing the outside-staff-priority can also be used to control the vertical placement of individual objects, although the results may not always be desirable. Suppose we would like “Text3” to be placed above “Text4” in the example under Automatic behavior, above (see Automatic behavior). All we need to do is to look up the priority of TextScript in the IR or in the tables above, and increase the priority of “Text3” to a higher value:

c''2^"Text1"
c''2^"Text2" |
\once \override TextScript.outside-staff-priority = #500
c''2^"Text3"
c''2^"Text4" |

This certainly lifts “Text3” above “Text4” but it also lifts it above “Text2”, and “Text4” now drops down. Perhaps this is not so good. What we would really like to do is to position all the annotation at the same distance above the staff. To do this, we clearly will need to space the notes out horizontally to make more room for the text. This is done using the textLengthOn command.

The \textLengthOn command

By default, text produced by markup takes up no horizontal space as far as laying out the music is concerned. The \textLengthOn command reverses this behavior, causing the notes to be spaced out as far as is necessary to accommodate the text:

\textLengthOn  % Cause notes to space out to accommodate text
c''2^"Text1"
c''2^"Text2" |
c''2^"Text3"
c''2^"Text4" |

The command to revert to the default behavior is \textLengthOff. Remember \once only works with \override, \set, \revert or \unset, so cannot be used with \textLengthOn.

Markup text will also avoid notes which project above the staff. If this is not desired, the automatic displacement upwards may be turned off by setting the priority to #f. Here’s an example to show how markup text interacts with such notes.

\relative {
  % This markup is short enough to fit without collision
  c''2^"Tex" c'' |
  R1 |

  % This is too long to fit, so it is displaced upwards
  c,,2^"Text" c'' |
  R1 |

  % Turn off collision avoidance
  \once \override TextScript.outside-staff-priority = ##f
  c,,2^"Long Text   " c'' |
  R1 |

  % Turn off collision avoidance
  \once \override TextScript.outside-staff-priority = ##f
  \textLengthOn        % and turn on textLengthOn
  c,,2^"Long Text   "  % Spaces at end are honored
  c''2 |
}

Dynamics placement

Dynamic markings will normally be positioned beneath the staff, but may be positioned above with the \dynamicUp command. They will be positioned vertically relative to the note to which they are attached, and will float below (or above) all within-staff objects such as phrasing slurs and bar numbers. This can give quite acceptable results, as this example shows:

\relative {
  \clef "bass"
  \key aes \major
  \time 9/8
  \dynamicUp
  bes4.~\f\< \( bes4 bes8 des4\ff\> c16 bes\! |
  ees,2.~\)\mf ees4 r8 |
}

However, if the notes and attached dynamics are close together the automatic placement will avoid collisions by displacing later dynamic markings further away, but this may not be the optimum placement, as this rather artificial example shows:

\dynamicUp
a4\f b\mf c\mp b\p

Should a similar situation arise in ‘real’ music, it may be preferable to space out the notes a little further, so the dynamic markings can all fit at the same vertical distance from the staff. We were able to do this for markup text by using the \textLengthOn command, but there is no equivalent command for dynamic marks. So we shall have to work out how to do this using \override commands.

Grob sizing

First we must learn how grobs are sized. All grobs have a reference point defined within them which is used to position them relative to their parent object. This point in the grob is then positioned at a horizontal distance, X-offset, and at a vertical distance, Y-offset, from its parent. The horizontal extent of the object is given by a pair of numbers, X-extent, which say where the left and right edges are relative to the reference point. The vertical extent is similarly defined by a pair of numbers, Y-extent. These are properties of all grobs which support the grob-interface.

By default, outside-staff objects are given a width of zero so that they may overlap in the horizontal direction. This is done by the trick of adding infinity to the leftmost extent and minus infinity to the rightmost extent by setting the extra-spacing-width to '(+inf.0 . -inf.0). So to ensure they do not overlap in the horizontal direction we must override this value of extra-spacing-width to '(0 . 0) so the true width shines through. This is the command to do this for dynamic text:

\override DynamicText.extra-spacing-width = #'(0 . 0)

Let’s see if this works in our previous example:

\dynamicUp
\override DynamicText.extra-spacing-width = #'(0 . 0)
a4\f b\mf c\mp b\p |

Well, it has certainly stopped the dynamic marks being displaced, but two problems remain. The marks should be spaced a little further apart and it would be better if they were all the same distance from the staff. We can solve the first problem easily. Instead of making the extra-spacing-width zero we could add a little more to it. The units are the space between two staff lines, so moving the left edge half a unit to the left and the right edge half a unit to the right should do it:

\dynamicUp
% Extend width by 1 staff space
\override DynamicText.extra-spacing-width = #'(-0.5 . 0.5)
a4\f b\mf c\mp b\p

This looks better, but maybe we would prefer the dynamic marks to be aligned along the same baseline rather than going up and down with the notes. The property to do this is staff-padding which is covered in the following section.

4.5 Collisions of objects

4.5.1 Moving objects

This may come as a surprise, but LilyPond is not perfect. Some notation elements can overlap. This is unfortunate, but in fact rather rare. Usually the need to move objects is for clarity or aesthetic reasons – they would look better with a little more or a little less space around them.

There are three main approaches to resolving overlapping notation. They should be considered in the following order:

1. The direction of one of the overlapping objects may be changed using the predefined commands listed above for within-staff objects (see Within-staff objects). Stems, slurs, beams, ties, dynamics, text and tuplets may be repositioned easily in this way. The limitation is that you have a choice of only two positions, and neither may be suitable.
2. The object properties, which LilyPond uses when positioning layout objects, may be modified using \override. The advantages of making changes to this type of property are (a) that some other objects will be moved automatically if necessary to make room and (b) the single override can apply to all instances of the same type of object. Such properties include:
   • direction

     This has already been covered in some detail – see Within-staff objects.

   • padding, right-padding, staff-padding

     As an object is being positioned the value of its padding property specifies the gap that must be left between itself and the nearest edge of the object against which it is being positioned. Note that it is the padding value of the object being placed that is used; the padding value of the object which is already placed is ignored. Gaps specified by padding can be applied to all objects which support the side-position-interface.

     Instead of padding, the placement of groups of accidentals is controlled by right-padding. This property is to be found in the AccidentalPlacement object which, note, lives in the Staff context. In the typesetting process the note heads are typeset first and then the accidentals, if any, are added to the left of the note heads using the right-padding property to determine the separation from the note heads and between individual accidentals. So only the right-padding property of the AccidentalPlacement object has any effect on the placement of the accidentals.

     The staff-padding property is closely related to the padding property: padding controls the minimum amount of space between any object which supports the side-position-interface and the nearest other object (generally the note or the staff lines); staff-padding applies only to those objects which are always set outside the staff – it controls the minimum amount of space that should be inserted between that object and the staff. Note that staff-padding has no effect on objects which are positioned relative to the note rather than the staff, even though it may be overridden without error for such objects – it is simply ignored.

     To discover which padding property is required for the object you wish to reposition, you need to return to the IR and look up the object’s properties. Be aware that the padding properties might not be located in the obvious object, so look in objects that appear to be related.

     All padding values are measured in staff spaces. For most objects, this value is set by default to be around 1.0 or less (it varies with each object). It may be overridden if a larger (or smaller) gap is required.

   • self-alignment-X

     This property can be used to align the object to the left, to the right, or to center it with respect to the parent object’s reference point. It may be used with all objects which support the self-alignment-interface. In general these are objects that contain text. The values are LEFT, RIGHT or CENTER. Alternatively, a numerical value between -1 and +1 may be specified, where -1 is left-aligned, +1 is right-aligned, and numbers in between move the text progressively from left-aligned to right-aligned. Numerical values greater than 1 may be specified to move the text even further to the left, or less than -1 to move the text even further to the right. A change of 1 in the value corresponds to a movement of half the text’s length.

   • extra-spacing-width

     This property is available for all objects which support the item-interface. It takes two numbers, the first is added to the leftmost extent and the second is added to the rightmost extent. Negative numbers move the edge to the left, positive to the right, so to widen an object the first number must be negative, the second positive. Note that not all objects honor both numbers. For example, the Accidental object only takes notice of the first (left edge) number.

   • staff-position

     staff-position is a property of the staff-symbol-referencer-interface, which is supported by objects which are positioned relative to the staff. It specifies the vertical position of the object relative to the center line of the staff in half staff-spaces. It is useful in resolving collisions between layout objects like multi-measure rests, ties and notes in different voices.

   • force-hshift

     Closely spaced notes in a chord, or notes occurring at the same time in different voices, are arranged in two, occasionally more, columns to prevent the note heads overlapping. These are called note columns, and an object called NoteColumn is created to lay out the notes in that column.

     The force-hshift property is a property of a NoteColumn (actually of the note-column-interface). Changing it permits a note column to be moved in units appropriate to a note column, viz. the note head width of the first voice note. It should be used in complex situations where the normal \shiftOn commands (see Explicitly instantiating voices) do not resolve the note conflict. It is preferable to the extra-offset property for this purpose as there is no need to work out the distance in staff-spaces, and moving the notes into or out of a NoteColumn affects other actions such as merging note heads.

3. Finally, when all else fails, objects may be manually repositioned relative to the staff center line vertically, or by displacing them by any distance to a new position. The disadvantages are that the correct values for the repositioning have to be worked out, often by trial and error, for every object individually, and, because the movement is done after LilyPond has placed all other objects, the user is responsible for avoiding any collisions that might ensue. But the main difficulty with this approach is that the repositioning values may need to be reworked if the music is later modified. The properties that can be used for this type of manual repositioning are:

   extra-offset

   This property applies to any layout object supporting the grob-interface. It takes a pair of numbers which specify the extra displacement in the horizontal and vertical directions. Negative numbers move the object to the left or down. The units are staff-spaces. The extra displacement is made after the typesetting of objects is finished, so an object may be repositioned anywhere without affecting anything else.

   positions

   This is most useful for manually adjusting the slope and height of beams, slurs, and tuplets. It takes a pair of numbers giving the position of the left and right ends of the beam, slur, etc. relative to the center line of the staff. Units are staff-spaces. Note, though, that slurs and phrasing slurs cannot be repositioned by arbitrarily large amounts. LilyPond first generates a list of possible positions for the slur and by default finds the slur that “looks best”. If the positions property has been overridden the slur that is closest to the requested positions is selected from the list.

A particular object may not have all of these properties. It is necessary to go to the IR to look up which properties are available for the object in question.

Here is a list of the objects which are most likely to be involved in collisions, together with the name of the object which should be looked up in the IR in order to discover which properties should be used to move them.

4.5.2 Fixing overlapping notation

Let’s now see how the properties in the previous section can help to resolve overlapping notation.

The padding property

The padding property can be set to increase (or decrease) the distance between symbols that are printed above or below notes.

c'2\fermata
\override Script.padding = #3
b2\fermata

% This will not work, see below
\override MetronomeMark.padding = #3
\tempo 4 = 120
c'1 |
% This works
\override Score.MetronomeMark.padding = #3
\tempo 4 = 80
d'1 |

Note in the second example how important it is to figure out what context handles a certain object. Since the MetronomeMark object is handled in the Score context, property changes in the Voice context will not be noticed. For more details, see Modifying properties.

If the padding property of an object is increased when that object is in a stack of objects being positioned according to their outside-staff-priority, then that object and all objects outside it are moved.

The right-padding property

The right-padding property affects the spacing between the accidental and the note to which it applies. It is not often required, but the default spacing may be wrong for certain special accidental glyphs or combination of glyphs used in some microtonal music. These have to be entered by overriding the accidental stencil with a markup containing the desired symbol(s), like this:

sesquisharp = \markup { \sesquisharp }
\relative {
  c''4
  % This prints a sesquisharp but the spacing is too small
  \once \override Accidental.stencil = #ly:text-interface::print
  \once \override Accidental.text = #sesquisharp
  cis4 c
  % This improves the spacing
  \once \override Score.AccidentalPlacement.right-padding = #0.6
  \once \override Accidental.stencil = #ly:text-interface::print
  \once \override Accidental.text = #sesquisharp
  cis4 |
}

This necessarily uses an override for the accidental stencil which will not be covered until later. The stencil type must be a procedure, here changed to print the contents of the text property of Accidental, which itself is set to be a sesquisharp sign. This sign is then moved further away from the note head by overriding right-padding.

The staff-padding property

staff-padding can be used to align objects such as dynamics along a baseline at a fixed height above the staff, rather than at a height dependent on the position of the note to which they are attached. It is not a property of DynamicText but of DynamicLineSpanner. This is because the baseline should apply equally to all dynamics, including those created as extended spanners. So this is the way to align the dynamic marks in the example taken from the previous section:

\dynamicUp
% Extend width by 1 unit
\override DynamicText.extra-spacing-width = #'(-0.5 . 0.5)
% Align dynamics to a base line 2 units above staff
\override DynamicLineSpanner.staff-padding = #2
a4\f b\mf c\mp b\p

The self-alignment-X property

The following example shows how this can resolve the collision of a string fingering object with a note’s stem by aligning the right edge with the reference point of the parent note:

\voiceOne
<a''\2>
\once \override StringNumber.self-alignment-X = #RIGHT
<a''\2>

The staff-position property

Multimeasure rests in one voice can collide with notes in another. Since these rests are typeset centered between the bar lines, it would require significant effort for LilyPond to figure out which other notes might collide with it, since all the current collision handling between notes and between notes and rests is done only for notes and rests that occur at the same time. Here’s an example of a collision of this type:

<< \relative { c'4 c c c } \\ { R1 } >>

The best solution here is to move the multimeasure rest down, since the rest is in voice two. The default in \voiceTwo (i.e. in the second voice of a <<{...} \\ {...}>> construct) is that staff-position is set to -4 for MultiMeasureRest, so we need to move it, say, four half-staff spaces down to -8.

<<
  \relative { c'4 c c c }
  \\
  \override MultiMeasureRest.staff-position = #-8
  { R1 }
>>

This is better than using, for example, extra-offset, because the ledger line above the rest is inserted automatically.

The extra-offset property

The extra-offset property provides complete control over the positioning of an object both horizontally and vertically.

In the following example, the second fingering is moved a little to the left, and 1.8 staff space downwards:

\stemUp
f4-5
\once \override Fingering.extra-offset = #'(-0.3 . -1.8)
f4-5

The positions property

The positions property allows the vertical position and hence the slope of tuplets, slurs, phrasing slurs and beams to be controlled manually.

Here’s an example in which the phrasing slur and slur collide:

\relative { a'8 \( ( a'16 ) a \) }

One possibility would be to move the two ends of the phrasing slur higher. We can try setting the left end to 2.5 staff-spaces above the centre line and the right end to 4.5 above, and LilyPond will select the phrasing slur from the candidates it has found with its end points closest to these:

\once \override PhrasingSlur.positions = #'(2.5 . 4.5)
a'8 \( ( a''16 ) a'' \)

This is an improvement, but why not lower the right end of the slur a little? If you try it you’ll find it can’t be done in this way. That’s because there are no candidate slurs lower than the one already selected, and in this case the positions property has no effect. However, ties, slurs and phrasing slurs can be positioned and shaped very precisely when necessary. To learn how to do this, see Modifying ties and slurs.

Here’s a further example. We see that the beams collide with the ties:

{
  \time 4/2
  <<
    { c'1 ~ 2. e'8 f' }
    \\
    { e''8 e'' e'' e''  e'' e'' e'' e''  f''2 g'' }
  >>
  <<
    { c'1 ~ 2. e'8 f' }
    \\
    { e''8 e'' e'' e''  e'' e'' e'' e''  f''2 g'' }
  >>
}

This can be resolved by manually moving both ends of the beam up from their position at 1.81 staff-spaces below the center line to, say, 1:

{
  \time 4/2
  <<
    { c'1 ~ 2. e'8 f' }
    \\
    {
      \override Beam.positions = #'(-1 . -1)
      e''8 e'' e'' e''  e'' e'' e'' e''  f''2 g''
    }
  >>
  <<
    { c'1 ~ 2. e'8 f' }
    \\
    { e''8 e'' e'' e''  e'' e'' e'' e''  f''2 g'' }
  >>
}

Note that the override continues to apply in the first voice of the second measure of eighth notes, but not to any of the beams in the second voice.

The force-hshift property

We can now see how to apply the final corrections to the Chopin example introduced at the end of I’m hearing Voices, which was left looking like this:

\new Staff \relative {
  \key aes \major
  <<
    { c''2 aes4. bes8 }
    \\
    { <ees, c>2 des }
    \\
    \\
    { aes'2 f4 fes }
  >> |
  <c ees aes c>1 |
}

The inner note of the first chord (i.e. the A-flat in the fourth Voice) need not be shifted away from the note column of the higher note. To correct this we set force-hshift, which is a property of NoteColumn, of this note to zero.

In the second chord we prefer the F to line up with the A-flat and the lowest note to be positioned slightly right to avoid a collision of stems. We achieve this by setting force-hshift in the NoteColumn of the low D-flat to move it to the right by half a staff-space.

Here’s the final result:

\new Staff \relative {
  \key aes \major
  <<
    { c''2 aes4. bes8 }
    \\
    {
      <ees, c>2
      \once \override NoteColumn.force-hshift = #0.5
      des2
    }
    \\
    \\
    {
      \override NoteColumn.force-hshift = #0
      aes'2 f4 fes
    }
  >> |
  <c ees aes c>1 |
}

4.5.3 Real music example

We end this section on Tweaks by showing the steps to be taken to deal with a tricky example which needs several tweaks to produce the desired output. The example has been deliberately chosen to illustrate the use of the Notation Reference to resolve unusual problems with notation. It is not representative of the more usual engraving process, so please do not let these difficulties put you off! Fortunately, difficulties like these are not very common!

The example is from Chopin’s Première Ballade, Op. 23, bars 6 to 9, the transition from the opening Lento to Moderato. Here, first, is what we want the output to look like, but to avoid over-complicating the example too much we have left out the dynamics, fingering and pedalling.

We note first that the right hand part in the third bar requires four voices. These are the five beamed eighth notes, the tied C, the half-note D which is merged with the eighth note D, and the dotted quarter note F-sharp, which is also merged with the eighth note at the same pitch. Everything else is in a single voice, so the easiest way is to introduce these extra three voices temporarily at the time they are needed. If you have forgotten how to do this, look at I’m hearing Voices and Explicitly instantiating voices. Here we choose to use explicitly instantiated voices for the polyphonic passage, as LilyPond is better able to avoid collisions if all voices are instantiated explicitly in this way.

So let us begin by entering the notes as two variables, setting up the staff structure in a score block, and seeing what LilyPond produces by default:

rhMusic = \relative {
  \new Voice {
    r2 c''4. g8 |
    bes1~ |
    \time 6/4
    bes2. r8
    % Start polyphonic section of four voices
    <<
      { c,8 d fis bes a }  % continuation of main voice
      \new Voice {
        \voiceTwo
        c,8~ 2
      }
      \new Voice {
        \voiceThree
        s8 d2
      }
      \new Voice {
        \voiceFour
        s4 fis4.
      }
    >> |
    g2.  % continuation of main voice
  }
}

lhMusic = \relative {
  r2 <c' g ees>2 |
  <d g, d>1 |
  r2. d,,4 r4 r |
  r4
}

\score {
  \new PianoStaff <<
    \new Staff = "RH"  <<
      \key g \minor
      \rhMusic
    >>
    \new Staff = "LH" <<
      \key g \minor
      \clef "bass"
      \lhMusic
    >>
  >>
}

All the notes are right, but the appearance is far from satisfactory. The tie collides with the change in time signature, some notes are not merged together, and several notation elements are missing. Let’s first deal with the easier things. We can easily add the left hand slur and the right hand phrasing slur, since these were all covered in the Tutorial. Doing this gives:

rhMusic = \relative {
  \new Voice {
    r2 c''4.\( g8 |
    bes1~ |
    \time 6/4
    bes2. r8
    % Start polyphonic section of four voices
    <<
      { c,8 d fis bes a }  % continuation of main voice
      \new Voice {
        \voiceTwo
        c,8~ 2
      }
      \new Voice {
        \voiceThree
        s8 d2
      }
      \new Voice {
        \voiceFour
        s4 fis4.
      }
    >> |
    g2.\)  % continuation of main voice
  }
}

lhMusic = \relative {
  r2 <c' g ees>2( |
  <d g, d>1) |
  r2. d,,4 r4 r |
  r4
}

\score {
  \new PianoStaff <<
    \new Staff = "RH"  <<
      \key g \minor
      \rhMusic
    >>
    \new Staff = "LH" <<
      \key g \minor
      \clef "bass"
      \lhMusic
    >>
  >>
}

The first bar is now correct. The second bar contains an arpeggio and is terminated by a double bar line. How do we do these, as they have not been mentioned in this Learning Manual? This is where we need to turn to the Notation Reference. Looking up ‘arpeggio’ and ‘bar line’ in the index quickly shows us that an arpeggio is produced by appending \arpeggio to a chord, and a double bar line is produced by the \bar "||" command. That’s easily done. We next need to correct the collision of the tie with the time signature. This is best done by moving the tie upwards. Moving objects was covered earlier in Moving objects, which says that objects positioned relative to the staff can be moved vertically by overriding their staff-position property, which is specified in half staff spaces relative to the center line of the staff. So the following override placed just before the first tied note would move the tie up to 3.5 half staff spaces above the center line:

\once \override Tie.staff-position = #3.5

This completes bar two, giving:

rhMusic = \relative {
  \new Voice {
    r2 c''4.\( g8 |
    \once \override Tie.staff-position = #3.5
    bes1~ |
    \bar "||"
    \time 6/4
    bes2. r8
    % Start polyphonic section of four voices
    <<
      { c,8 d fis bes a }  % continuation of main voice
      \new Voice {
        \voiceTwo
        c,8~ 2
      }
      \new Voice {
        \voiceThree
        s8 d2
      }
      \new Voice {
        \voiceFour
        s4 fis4.
      }
    >> |
    g2.\)  % continuation of main voice
  }
}

lhMusic = \relative {
  r2 <c' g ees>2( |
  <d g, d>1)\arpeggio |
  r2. d,,4 r4 r |
  r4
}

\score {
  \new PianoStaff <<
    \new Staff = "RH"  <<
      \key g \minor
      \rhMusic
    >>
    \new Staff = "LH" <<
      \key g \minor
      \clef "bass"
      \lhMusic
    >>
  >>
}

On to bar three and the start of the Moderato section. The tutorial showed how to add bold text with the \markup command, so adding “Moderato” in bold is easy. But how do we merge notes in different voices together? This is where we need to turn again to the Notation Reference for help. A search for “merge” in the Notation Reference index quickly leads us to the commands for merging differently headed and differently dotted notes in Collision resolution. In our example we need to merge both types of note for the duration of the polyphonic section in bar 3, so using the information we find in the Notation Reference we add

\mergeDifferentlyHeadedOn
\mergeDifferentlyDottedOn

to the start of that section and

\mergeDifferentlyHeadedOff
\mergeDifferentlyDottedOff

to the end, giving:

These overrides have merged the two F-sharp notes, but not the two on D. Why not? The answer is there in the same section in the Notation Reference – notes being merged must have stems in opposite directions and two notes cannot be merged successfully if there is a third note in the same note column. Here the two D’s both have upward stems and there is a third note – the C. We know how to change the stem direction using \stemDown, and the Notation Reference also says how to move the C – apply a shift using one of the \shift commands. But which one? The C is in voice two which has shift off, and the two D’s are in voices one and three, which have shift off and shift on, respectively. So we have to shift the C a further level still using \shiftOnn to avoid it interfering with the two D’s. Applying these changes gives:

rhMusic = \relative {
  \new Voice {
    r2 c''4.\( g8 |
    \once \override Tie.staff-position = #3.5
    bes1~ |
    \bar "||"
    \time 6/4
    bes2.^\markup { \bold "Moderato" } r8
    \mergeDifferentlyHeadedOn
    \mergeDifferentlyDottedOn
    % Start polyphonic section of four voices
    <<
      { c,8 d fis bes a }  % continuation of main voice
      \new Voice {
        \voiceTwo
        % Move the c2 out of the main note column
        % so the merge will work
        c,8~ \shiftOnn c2
      }
      \new Voice {
        \voiceThree
        % Stem on the d2 must be down to permit merging
        s8 \stemDown d2
      }
      \new Voice {
        \voiceFour
        s4 fis4.
      }
    >> |
    \mergeDifferentlyHeadedOff
    \mergeDifferentlyDottedOff
    g2.\)  % continuation of main voice
  }
}

lhMusic = \relative {
  r2 <c' g ees>2( |
  <d g, d>1)\arpeggio |
  r2. d,,4 r4 r |
  r4
}

\score {
  \new PianoStaff <<
    \new Staff = "RH"  <<
      \key g \minor
      \rhMusic
    >>
    \new Staff = "LH" <<
      \key g \minor
      \clef "bass"
      \lhMusic
    >>
  >>
}

Nearly there. Only two problems remain: The downward stem on the merged D should not be there, and the C would be better positioned to the right of the D’s. We know how to do both of these from the earlier tweaks: we make the stem transparent, and move the C with the force-hshift property. Here’s the final result:

rhMusic = \relative {
  \new Voice {
    r2 c''4.\( g8 |
    \once \override Tie.staff-position = #3.5
    bes1~ |
    \bar "||"
    \time 6/4
    bes2.^\markup { \bold "Moderato" } r8
    \mergeDifferentlyHeadedOn
    \mergeDifferentlyDottedOn
    % Start polyphonic section of four voices
    <<
      { c,8 d fis bes a }  % continuation of main voice
      \new Voice {
        \voiceTwo
        c,8~
        % Reposition the c2 to the right of the merged note
        \once \override NoteColumn.force-hshift = #1.0
        % Move the c2 out of the main note column
        % so the merge will work
        \shiftOnn
        c2
      }
      \new Voice {
        \voiceThree
        s8
        % Stem on the d2 must be down to permit merging
        \stemDown
        % Stem on the d2 should be invisible
        \tweak Stem.transparent ##t
        d2
      }
      \new Voice {
        \voiceFour
        s4 fis4.
      }
    >> |
    \mergeDifferentlyHeadedOff
    \mergeDifferentlyDottedOff
    g2.\)  % continuation of main voice
  }
}

lhMusic = \relative {
  r2 <c' g ees>2( |
  <d g, d>1)\arpeggio |
  r2. d,,4 r4 r |
  r4
}

\score {
  \new PianoStaff <<
    \new Staff = "RH"  <<
      \key g \minor
      \rhMusic
    >>
    \new Staff = "LH" <<
      \key g \minor
      \clef "bass"
      \lhMusic
    >>
  >>
}

4.6 Further tweaking

4.6.1 Other uses for tweaks

Tying notes across voices

The following example demonstrates how to connect notes in different voices using ties. Normally, only two notes in the same voice can be connected with ties. By using two voices, with the tied notes in one of them

and blanking the first up-stem in that voice, the tie appears to cross voices:

<<
  {
    \tweak Stem.transparent ##t
    b8~ 8\noBeam
  }
\\
  { b8[ g] }
>>

To make sure that the just-blanked stem doesn’t squeeze the tie too much, we can lengthen the stem by setting the length to 8,

<<
  {
    \tweak Stem.transparent ##t
    \tweak Stem.length #8
    b8~ 8\noBeam
  }
\\
  { b8[ g] }
>>

Now for overriding the transparency of a graphical object, we could have used the shorthand \hide as explained above. Tweaking is a different operation, affecting only properties generated from a single music expression. It turns out that we can convert overrides into tweaks using \single, making it possible to rewrite the above example as

<<
  {
    \single \hide Stem
    \single \hide Flag
    \tweak Stem.length #8
    b8~ 8\noBeam
  }
\\
  { b8[ g] }
>>

In this particular case, the difference to \once \hide is not apparent. It is important when there are several objects at the same point in musical time (like noteheads in a chord). In that case, \once will affect all of those objects while \single will only affect a single one, the one generated by the immediately following music expression.

Simulating a fermata in MIDI

For outside-staff objects it is usually better to override the object’s stencil property rather than its transparent property when you wish to remove it from the printed output. Setting the stencil property of an object to #f will remove that object entirely from the printed output. This means it has no effect on the placement of other objects placed relative to it.

For example, if we wished to change the metronome setting in order to simulate a fermata in the MIDI output we would not want the metronome markings to appear in the printed output, and we would not want it to influence the spacing between the two systems or the positions of adjacent annotations on the staff. So setting its stencil property to #f would be the best way. We show here the effect of the two methods:

\score {
  \relative {
    % Visible tempo marking
    \tempo 4=120
    a'4 a a
    \once \hide Score.MetronomeMark
    % Invisible tempo marking to lengthen fermata in MIDI
    \tempo 4=80
    a4\fermata |
    % New tempo for next section
    \tempo 4=100
    a4 a a a |
  }
  \layout { }
  \midi { }
}

\score {
  \relative {
    % Visible tempo marking
    \tempo 4=120
    a'4 a a
    \once \omit Score.MetronomeMark
    % Invisible tempo marking to lengthen fermata in MIDI
    \tempo 4=80
    a4\fermata |
    % New tempo for next section
    \tempo 4=100
    a4 a a a |
  }
  \layout { }
  \midi { }
}

Both methods remove the metronome mark which lengthens the fermata from the printed output, and both affect the MIDI timing as required, but the transparent metronome mark in the first line forces the following tempo indication too high while the second (with the stencil removed) does not.

Zie ook

Music Glossary: system.

4.6.2 Using variables for tweaks

Override commands are often long and tedious to type, and they have to be absolutely correct. If the same overrides are to be used many times it may be worth defining variables to hold them.

Suppose we wish to emphasize certain words in lyrics by printing them in bold italics. The \italic and \bold commands only work within lyrics if they are embedded, together with the word or words to be modified, within a \markup block, which makes them tedious to enter. The need to embed the words themselves prevents their use in simple variables. As an alternative can we use \override and \revert commands?

\override Lyrics.LyricText.font-shape = #'italic
\override Lyrics.LyricText.font-series = #'bold

\revert Lyrics.LyricText.font-shape
\revert Lyrics.LyricText.font-series

These would also be extremely tedious to enter if there were many words requiring emphasis. But we can define these as two variables and use those to bracket the words to be emphasized. Another advantage of using variables for these overrides is that the spaces around the dot are not necessary, since they are not being interpreted in \lyricmode directly. Here’s an example of this, although in practice we would choose shorter names for the variables to make them quicker to type:

emphasize = {
  \override Lyrics.LyricText.font-shape = #'italic
  \override Lyrics.LyricText.font-series = #'bold
}

normal = {
  \revert Lyrics.LyricText.font-shape
  \revert Lyrics.LyricText.font-series
}

global = { \key c \major \time 4/4 \partial 4 }

SopranoMusic = \relative { c'4 | e4. e8 g4 g    | a4   a   g  }
AltoMusic    = \relative { c'4 | c4. c8 e4 e    | f4   f   e  }
TenorMusic   = \relative  { e4 | g4. g8 c4.  b8 | a8 b c d e4 }
BassMusic    = \relative  { c4 | c4. c8 c4 c    | f8 g a b c4 }

VerseOne = \lyricmode {
  E -- | ter -- nal \emphasize Fa -- ther, | \normal strong to save,
}

VerseTwo = \lyricmode {
  O | \once \emphasize Christ, whose voice the | wa -- ters heard,
}

VerseThree = \lyricmode {
  O | \emphasize Ho -- ly Spi -- rit, | \normal who didst brood
}

VerseFour = \lyricmode {
  O | \emphasize Tri -- ni -- ty \normal of | love and pow'r
}

\score {
  \new ChoirStaff <<
    \new Staff <<
      \clef "treble"
      \new Voice = "Soprano"  { \voiceOne \global \SopranoMusic }
      \new Voice = "Alto" { \voiceTwo \AltoMusic }
      \new Lyrics \lyricsto "Soprano" { \VerseOne }
      \new Lyrics \lyricsto "Soprano" { \VerseTwo }
      \new Lyrics \lyricsto "Soprano" { \VerseThree }
      \new Lyrics \lyricsto "Soprano" { \VerseFour }
    >>
    \new Staff <<
      \clef "bass"
      \new Voice = "Tenor" { \voiceOne \TenorMusic }
      \new Voice = "Bass"  { \voiceTwo \BassMusic }
    >>
  >>
}

4.6.3 Style sheets

The output that LilyPond produces can be heavily modified; see Tweaking output, for details. But what if you have many input files that you want to apply your tweaks to? Or what if you simply want to separate your tweaks from the actual music? This is quite easy to do.

Let’s look at an example. Don’t worry if you don’t understand the parts with all the #(). This is explained in Advanced tweaks with Scheme.

mpdolce =
#(make-dynamic-script
  #{ \markup { \hspace #0
               \translate #'(5 . 0)
               \line { \dynamic "mp"
                       \text \italic "dolce" } }
  #})

inst =
#(define-music-function
     (string)
     (string?)
   #{ <>^\markup \bold \box #string #})

\relative {
  \tempo 4=50
  a'4.\mpdolce d8 cis4--\glissando a |
  b4 bes a2 |
  \inst "Clarinet"
  cis4.\< d8 e4 fis |
  g8(\! fis)-. e( d)-. cis2 |
}

Let’s do something about the mpdolce and inst definitions. They produce the output we desire, but we might want to use them in another piece. We could simply copy-and-paste them at the top of every file, but that’s an annoyance. It also leaves those definitions in our input files, and I personally find all the #() somewhat ugly. Let’s hide them in another file:

%%% save this to a file called "definitions.ily"
mpdolce =
#(make-dynamic-script
  #{ \markup { \hspace #0
               \translate #'(5 . 0)
               \line { \dynamic "mp"
                       \text \italic "dolce" } }
  #})

inst =
#(define-music-function
     (string)
     (string?)
   #{ <>^\markup \bold \box #string #})

We will refer to this file using the \include command near the top of the music file. (The extension ‘.ily’ is used to distinguish this included file, which is not meant to be compiled on its own, from the main file.) Now let’s modify our music (let’s save this file as ‘music.ly’).

\include "definitions.ily"

\relative {
  \tempo 4=50
  a'4.\mpdolce d8 cis4--\glissando a |
  b4 bes a2 |
  \inst "Clarinet"
  cis4.\< d8 e4 fis |
  g8(\! fis)-. e( d)-. cis2 |
}

That looks better, but let’s make a few changes. The glissando is hard to see, so let’s make it thicker and closer to the note heads. Let’s put the metronome marking above the clef, instead of over the first note. And finally, my composition professor hates ‘C’ time signatures, so we’d better make that ‘4/4’ instead.

Don’t change ‘music.ly’, though. Replace our ‘definitions.ily’ with this:

%%%  definitions.ily
mpdolce =
#(make-dynamic-script
  #{ \markup { \hspace #0
               \translate #'(5 . 0)
               \line { \dynamic "mp"
                       \text \italic "dolce" } }
  #})

inst =
#(define-music-function
     (string)
     (string?)
   #{ <>^\markup \bold \box #string #})

\layout{
  \context {
    \Score
    \override MetronomeMark.extra-offset = #'(-9 . 0)
    \override MetronomeMark.padding = #'3
  }
  \context {
    \Staff
    \override TimeSignature.style = #'numbered
  }
  \context {
    \Voice
    \override Glissando.thickness = #3
    \override Glissando.gap = #0.1
  }
}

That looks nicer! But now suppose that I want to publish this piece. My composition professor doesn’t like ‘C’ time signatures, but I’m somewhat fond of them. Let’s copy the current ‘definitions.ily’ to ‘web-publish.ily’ and modify that. Since this music is aimed at producing a pdf which will be displayed on the screen, we’ll also increase the overall size of the output.

%%%  web-publish.ily
mpdolce =
#(make-dynamic-script
  #{ \markup { \hspace #0
               \translate #'(5 . 0)
               \line { \dynamic "mp"
                       \text \italic "dolce" } }
  #})

inst =
#(define-music-function
     (string)
     (string?)
   #{ <>^\markup \bold \box #string #})

#(set-global-staff-size 23)

\layout{
  \context {
    \Score
    \override MetronomeMark.extra-offset = #'(-9 . 0)
    \override MetronomeMark.padding = #'3
  }
  \context {
    \Staff
  }
  \context {
    \Voice
    \override Glissando.thickness = #3
    \override Glissando.gap = #0.1
  }
}

Now in our music, I simply replace \include "definitions.ily" with \include "web-publish.ily". Of course, we could make this even more convenient. We could make a ‘definitions.ily’ file which contains only the definitions of mpdolce and inst, a ‘web-publish.ily’ file which contains only the \layout section listed above, and a ‘university.ily’ file which contains only the tweaks to produce the output that my professor prefers. The top of ‘music.ly’ would then look like this:

\include "definitions.ily"

%%%  Only uncomment one of these two lines!
\include "web-publish.ily"
%\include "university.ily"

This approach can be useful even if you are only producing one set of parts. I use half a dozen different ‘style sheet’ files for my projects. I begin every music file with \include "../global.ily", which contains

%%%   global.ily
\version "2.23.3"

#(ly:set-option 'point-and-click #f)

\include "../init/init-defs.ly"
\include "../init/init-layout.ly"
\include "../init/init-headers.ly"
\include "../init/init-paper.ly"

4.6.4 Other sources of information

The Internals Reference documentation contains a lot of information about LilyPond, but even more information can be gathered by looking at the internal LilyPond files. To explore these, you must first find the directory appropriate to your system. The location of this directory depends (a) on whether you obtained LilyPond by downloading a precompiled binary from lilypond.org or whether you installed it from a package manager (i.e. distributed with GNU/Linux, or installed under fink or cygwin) or compiled it from source, and (b) on which operating system it is being used:

Downloaded from lilypond.org

• GNU/Linux

  Navigate to

  ‘INSTALLDIR/lilypond/usr/share/lilypond/current/’
  

• MacOS X

  Navigate to

  ‘INSTALLDIR/LilyPond.app/Contents/Resources/share/lilypond/current/’
  

  by either cd-ing into this directory from the Terminal, or control-clicking on the LilyPond application and selecting ‘Show Package Contents’.

• Windows

  Using Windows Explorer, navigate to

  ‘INSTALLDIR/LilyPond/usr/share/lilypond/current/’
  

Installed from a package manager or compiled from source

Navigate to ‘PREFIX/share/lilypond/X.Y.Z/’, where PREFIX is set by your package manager or configure script, and X.Y.Z is the LilyPond version number.

Within this directory the two interesting subdirectories are

• ‘ly/’ - contains files in LilyPond format
• ‘scm/’ - contains files in Scheme format

Let’s begin by looking at some files in ‘ly/’. Open ‘ly/property-init.ly’ in a text editor. The one you normally use for .ly files will be fine. This file contains the definitions of all the standard LilyPond predefined commands, such as \stemUp and \slurDotted. You will see that these are nothing more than definitions of variables containing one or a group of \override commands. For example, /tieDotted is defined to be:

tieDotted = {
  \override Tie.dash-period = #0.75
  \override Tie.dash-fraction = #0.1
}

If you do not like the default values these predefined commands can be redefined easily, just like any other variable, at the head of your input file.

The following are the most useful files to be found in ‘ly/’: