01

A file at a glance

The smallest complete document is four lines:

part melody { clef treble }
section Main { melody { c4 d e f | g2 g | } }
form { ~Main }
score { staff melody }

Everything else is optional, and top-level settings come first:

// comments are // to end of line, or /* … */
title    "Song"
subtitle "Op. 1"             // also: poet "Lyricist" — LilyPond's title block
composer "Composer"
tempo    120                 // also: tempo "Allegro" 4 = 96, tempo 120 swing
time     4/4                 // default 4/4; engraves as C, and 2/2 as cut-C
key      c major             // default c major; all church modes work
octave   absolute            // optional; relative is the default — see Pitches
pitch    written             // optional; concert = the letters are what SOUNDS — see Transposing instruments

fonts { serif "Georgia" }    // optional, a face per kind of text
paper { size a4 }            // optional, page geometry
layout { barNumbers every 4 }  // optional, score-wide display switches — see Layout

part rightHand { clef treble }
part leftHand  { clef bass octave 3 }

phrase motif { c4 d e f | }  // optional reusable music

section Main {
  rightHand { motif g2 g | }   // a section binds music to each part by name
  leftHand  { c2 c | g2 g | }
}

form { ~Main }          // the playing order; ~ keeps the name off the page

score {               // one or more render blocks
  grandStaff { staff rightHand  staff leftHand }
}

The declaration order above is the conventional one. Parts must be declared before the sections that use them. A score plays the file's unnamed form, or the one a form NAME item inside it names.

02

Lexical rules

Whitespace and newlines are not significant. You can put a whole part on one line or one bar per line; the samples on the showcase page do both.

03

Pitches and octaves

Note names are Dutch: c d e f g a b, sharp is, flat es.

Two octave modes

Relative (the default). Each bare pitch takes the octave nearest the previous note — an interval of a fourth or less — and '/, shift from there. Compact, but one wrong mark moves everything after it.

Absolute. Write octave absolute at the top level, in a part header, or mid-music. Bare c is then C4 (or CN in a part that says octave N) and the marks are absolute offsets from it: c' is C5, c, is C3, resolved independently per note. A wrong octave stays one wrong note instead of cascading.

Write relative. It is the default, it is shorter, and it is how a person reads music anyway — each note against the one before it. Reach for absolute when something other than a person is doing the writing: a generator, an importer, or an AI producing a score it cannot hear back. There the guarantee that a mistake stays local is worth the extra marks; at the keyboard it usually is not. part bass { octave 3 } re-anchors a low part so its commas do not pile up.

Sections restore the file-level mode, so a mid-music switch does not leak.

Show the whole file

// Relative is the DEFAULT: each bare pitch takes the octave nearest the note before
// it. `octave absolute` switches that off and anchors a bare c to C4 (or to the part's
// `octave N`), so a wrong octave never cascades — worth it when a generator is writing,
// not by hand.
octave absolute
time 4/4
part melody { clef treble }
section A { melody { c4 c' c'' c, | e g e' g, | } }
form { ~A }
score { staff melody }

04

Durations

A duration is glued to what it lengthens: c4, <c e g>4. It never sits on a chord member — <c e g2> is an error.

The bare duration

A duration standing alone repeats the previous note, chord or slash at the new length, and sets the running default:

bes8 8 8 8        // four B♭ eighths, written once
<c e g>4 4        // the chord again
/4 4 4 4          // four beats of slash comping

Rests are transparent to it. With nothing before it to repeat, it is an error. Reaching back across a barline only warns — because that shape is also what a dropped pitch letter looks like (4 g f e meant as a4 g f e), so open a measure with the event itself.

05

Notes, rests, chords

Repeating a chord — and why there are two ways

A bare duration and a q both repeat what came before, and for the plain case they are the same music — <c e g>4 4 and <c e g>4 q4 engrave and play identically. They differ in what they are, and that is what decides which one you can modify:

• A bare duration is a LENGTH. “The previous event again, this long.” It cannot be displaced, because a length has nothing to move — 4' is not a spelling.
• q is an EVENT. “This chord again.” It takes its own duration, its own post-events (q@staccato — the original's are never copied), and octave marks.

The displacement accumulates along the chain: q' q plays the chord an octave up both times, q' q' climbs by one and then two, and a bare duration in the run repeats the chord where the last q left it. A q with no chord before it warns and occupies its time silently; notes and rests are transparent to it, and the run does not leak across a part, section or phrase body.

Octave marks on q are Lily#'s own — LilyPond's q takes none.

Show the whole file

// A duration standing alone repeats the previous event at the new length, and `q`
// repeats the previous CHORD. Only `q` can be displaced: q' is an octave up.
time 4/4
part melody { clef treble }
section A {
  melody { c8 8 8 8 c4 4 | <c e g>4 q q' q | }
}
form { ~A }
score { staff melody }

Show the whole file

// Rests, spacers, a full-measure rest, a pitched rest, chords by letter and by
// scale degree, and the pitchless slash note.
time 4/4
key c major
part melody { clef treble }
section A {
  melody {
    c4 r4 s4 g'4 | R1 | c,4 a4@rest d4 r4 |
    <c e g>4 <c 3 5>4 <1 3 5>2 | /4 4 8 8 4 |
  }
}
form { ~A }
score { staff melody }

A rest normally places itself: middle line, voiced position inside a voice span, clear of what sounds with it. @rest on a note overrides that — the rest sits where that pitch would and nothing moves it again, which is how two voices' colliding rests get pulled apart. The pitch never sounds and prints no accidental. On anything but a note it is an error.

Chord octaves — the anchor model

One rule: a mark moves only what it is attached to. The anchor is the first member's bare letter (or the key tonic for a degrees-only chord), resolved nearest the running frame; members sit at or above it, so order is free except the first slot. The chord never moves the frame itself — only a mark after the > does.

Arpeggios — written-out broken chords

<< … >> plays its members in sequence, equally subdividing the group's total. Members take no durations of their own — a bare number inside is always a scale degree.

<< c e g >>      // c, then e and g stacked above it — a triplet of eighths after c4
<< 8 5 3 1 >>    // degrees only: descending from the octave
<< c r e >>      // a rest is a gap — an equal share
<< c e g >>2     // a duration after >> is the group's TOTAL
<< c e g >>'     // marks after >> shift the group and propagate
<< c . d >>4     // a SPACED dot holds the member before it one more share: 2:1, the swing figure
<< c . . d >>4   // 3:1 — c8. d16 (never glued: c. would be a duration dot, 3. a decimal)
<< c@accent e\3 g( a) >>   // a member carries scripts, string numbers, fingering, dynamics, slur marks
<< c e g >>4\2   // on the group: a dynamic, a chord name, a string number (every member's);
                 //   a ~ or ( written after >> hangs on the last member
<< chord(C x32010) >>2   // a shape is SPREAD: its strings in turn, lowest first — five, under 5:4

The tuplet is spelled the way engraving convention spells it — the member count against the power of two below it (3:2, 5:4, 7:4), a dotted total against 3 (2:3, 4:3) — from the total number of shares.

This is not LilyPond's << >>. Parallel voices are voice { } { } in Lily#, and a \\ inside is an error.

Show the whole file

// `<< … >>` writes a broken chord out: the members play in sequence and divide the
// group's total. A bare number inside is a scale degree, never a duration.
time 4/4
key c major
part melody { clef treble }
section A {
  melody { << c e g >>4 << c 3 5 >>4 << 8 5 3 1 >>2 | << c e g >>2 << c r e >>2 | }
}
form { ~A }
score { staff melody }

06

Ties, slurs, beams

c4~ | c4 d e f       // tie — same pitch, with ~
c4( d e f)           // slur — different pitches, with ( )
<c e>4( <d f>)       // a slur may bind chords too
<c e( g>4 <d f) a>   // ...or one note of each: the mark after the pitch, inside the brackets
c8[ d e f]           // manual beam; beaming is automatic otherwise
c4@phrasingSlur d( e) f g@!phrasingSlur   // a phrasing slur over a whole phrase; ordinary slurs may sit inside

A tie whose next note is a different pitch warns and tells you to use a slur instead. Beaming follows the meter unless you bracket it yourself. A phrasing slur is a spanner: its end is required, and one may be open per voice.

Show the whole file

// A tie joins the SAME pitch, a slur joins different ones, and square brackets
// beam by hand where the meter's own beaming is not what you want.
time 4/4
part melody { clef treble }
section A {
  melody { c4~ c4 d4( e4) | <c e>4( <d f>4) c8[ d e f] | }
}
form { ~A }
score { staff melody }

Across a section boundary

A slur, a phrasing slur, a tie or a hairpin still open when a section ends is carried into the section the form plays next, and must end there. The carry follows the form, play by play — form { C D C E } carries C's slur into D the first time and into E the second — so it is checked per form, per part and per play:

part vc {
  section C { g4 a b c( || }
  section D { d4) e f g~ || }
  section E { g'1 | }   // the frame resets at E: g' is the tied G
}
form { C D E }
score { staff vc }

A span that breaks the rule draws nothing (a hairpin is cut at its own section's end) and is reported as LYS4023: carried in and not ended in that next section, a ) at a section's start with nothing carried in, or carried into a section the part plays nothing in (warnings); a slur, phrasing slur or hairpin carried over a repeat sign, into or out of a volta ending, or over a jump mark (an error — what comes before differs from pass to pass).

A tie may cross any of those. It is carried to the first note of every section played after its own — the body again at each pass, that pass's ending, whatever follows the block — and each of those notes must repeat the pitch. Where the section played next is also the one printed next the tie is an ordinary arc; where it is not (back to the |:, into a later ending) the tied note gets a hanging tie and the note it reaches an automatic repeat tie, and playback holds the note over.

Show the whole file

// A tie may cross a repeat sign or an ending. I's C ties into A (the next section printed
// and played); A's E ties into ending 1 as an ordinary arc and into ending 2, which is not
// printed next, as an automatic repeat tie.
part vn {
  section I { c''1~ || }
  section A { c''1 | e1~ || }
  section B { e''1 | }
}
form { I |: A [1. B] :| [2. B] }
score { staff vn }

Everything else a section starts from still resets at the boundary — the relative frame, the note value, the meter, key and clef — so the note a tie reaches states its own octave.

07

Annotations

Attach with @; one note may take several (c4@staccato@p). Two suffixes force a side: .up and .down (c4@staccato.up, @f.up). An annotation that takes a value puts it in parentheses: @finger(3), @figuredBass(6 4), @text("dolce").

Spanners — the end is required

These open on one note and must be closed on another. A spanner nobody closes draws nothing at all, its word included, and says so:

These take no argument. @ped, @ped(off), @una(corda) do not exist. A pedal change — release and press again on the same note — is the pedal's name again while it is down: in c4@sustain d e f | g4@sustain a b c@!sustain the second @sustain re-pedals, and the bracket draws its notch there (@!sustain@sustain on one note means the same).

The dot after a name is placement, not an argument

@fermata.up is a fermata forced above. It follows that @notehead.x does not work — an argument always goes in parentheses: @notehead(cross).

Notes to yourself — @todo

@todo marks a note, rest or chord to come back to. It prints nothing and plays nothing. The editor lists each one as a warning, and the preview rings the item in red and writes the memo, underlined, in its staff's margin with a line down to the ring (.down puts the memo below the staff). Done? Delete the mark, or press Ctrl+. on it: Resolve this TODO.

c'4 fis'8@todo("F# or F natural?") e'8 g'2 |
r2@todo("bar 12 is only 7/8").down d'2 |
c'4@todo e'4 g'2 |

A chords row's symbol takes one too (Am7@todo("or C?")). An export draws none unless asked — lysc svg --todo (and png, pdf) draws them as the preview does. lysc check --todo-as-error fails while any is left.

Show the whole file

// Articulations, ornaments and dynamics attach with '@'. A hairpin goes on the
// note it starts from and runs to the next dynamic. '.up' forces the side.
time 4/4
part melody { clef treble }
section A {
  melody {
    c4@staccato d4@accent e4@tenuto f4@marcato |
    g4@trill a4@mordent b4@fermata c4@staccato.up |
    c4@p@cresc b4 a4 g4@f | f4@f@decresc e4 d4 c4@p |
  }
}
form { ~A }
score { staff melody }

Show the whole file

// A spanner opens on one note and MUST be closed on another: one that is never
// closed draws nothing at all and says so.
time 4/4
part rh { clef treble }
part lh { clef bass octave 3 }
section A {
  rh {
    c'4@ottava d e f | g4 a b c@!ottava |
    c,4@rit b a g@!rit | c1 |
  }
  lh {
    c4@sustain e g e | c4@sustain e g e |   // a second @sustain while down re-pedals
    c4@sustain e g e | c1@!sustain |
  }
}
form { ~A }
score { grandStaff { staff rh  staff lh } }

08

Tuplets, grace notes, voices, cues

tuplet 3/2 { c8 d e }                          // 3 in the time of 2
tuplet 3/2 { c8 d tuplet 3/2 { e16 f g } }     // nesting is allowed

grace        { d16 e } f4     // grace notes before f
acciaccatura { a16 }    b4    // slashed
appoggiatura { c8 }     d4    // unslashed

voice { c'2 d } { e2 f }      // `voice` opens the span ONCE; each further { } is another voice

repeat unfold 8 { ground }        // write the body out 8 times
repeat percent 2 { c4 d e f | }   // repeat the previous measure
repeat tremolo 8 { c16 e } |      // N x the pair: 8 x two 16ths fills a 4/4 bar

repeat is only for unfold / percent / tremolo — things that abbreviate notes. It is not how a repeat sign is written; see Forms.

Cue notes

A cue is a region, not an annotation, so there is no @cue:

c4 cue { e4 f } g4 |            // small notes, a voice of their own
c4 cue bass { e4 f } g4 |       // drawn in another instrument's clef; the staff's clef returns

A slur or tie may not cross the region's edge — close it inside the cue, or keep both ends outside. Two adjacent cue blocks are two voices, so a span cannot run from one into the next either.

Show the whole file

// Tuplets nest, grace notes come in three flavours, and `voice { } { }` opens a
// span of simultaneous voices on ONE staff.
time 4/4
part melody { clef treble }
section A {
  melody {
    tuplet 3/2 { c8 d e } tuplet 3/2 { f8 g a } c2 |
    grace { d,16 e } f4 acciaccatura { a16 } b4 appoggiatura { c8 } d4 r4 |
    voice { g2 a2 } { c2 c2 } |
  }
}
form { ~A }
score { staff melody }

09

Barlines and breaks

A written | closes exactly one measure, and a measure with nothing in it is an empty one. So { | | | | } is four empty bars and { | c1 } is an empty bar then c1. An empty bar fills itself with a full-measure spacer, on the page and in playback, so it is never diagnosed — which is what lets a rhythm staff say nothing for pages at a time.

Typed barlines close nothing: || and |. decorate the bar behind them, and a | landing where the meter just auto-filled a bar merely confirms it. That is why a trailing c1 | is one bar, not two.

The repeat barlines |: :| :|: are not music items. Writing one among the notes is refused, with a message naming the form to write instead.

Forcing where a line or page turns

Four bare words, written in the music (or in the form). At a bar line they end the system there; inside a bar, break splits that bar across two systems. They are spelled in camelCase and, like everything else, are case-sensitive — nobreak is not a word.

Line and page breaking are otherwise automatic — Lily# uses LilyPond's Knuth-Plass line breaking and its page-breaking search — so these are for the places where you disagree with the result, not for laying a score out by hand.

Show the whole file

// Every written '|' closes exactly one measure, so a bar with nothing in it is an
// empty bar. '||' and '|.' decorate the bar behind them; '!' is dashed.
time 4/4
part melody { clef treble }
section A {
  melody { c1 | | d1 || e1 ! f1 |. }
}
form { ~A }
score { staff melody }

10

Keys and accidentals

key takes a tonic and a mode: key d major, key fis minor, key bes major. Every church mode works too (dorian, mixolydian, …). With none written, a piece is in C major.

key g major                    // the file's key
part melody { clef treble }
section A { melody { g'4 fis e d | c'4 b a2 | } }
section B {
  key ees major                // this section's key, in every part
  melody { ees'4 f g aes | bes2 g | }
}
section C { melody { g'4 f e d | g1 | } }   // back in G: f is F natural, and prints one
form { A B C }
score { staff melody }

A note name says the pitch, not what is printed. In G major you write fis and no sharp is drawn, because the key signature already has it; write f and a natural is drawn. So transposing, or changing the key, never changes which notes sound. An accidental the music prints holds to the bar line, in its own octave; layout { accidentals modern } and the other styles are in Layout switches. To print one that is not needed, write @courtesy (in parentheses) or @editorial (small, above the note).

A key that changes nothing is not drawn — at a section's start, the key the section before it left counts. To draw it anyway (a courtesy key at a new movement) write key!. Not sure of the key of music you took down by ear? The editor's Guess Section Key suggests one, and Respell Notes to Key turns fis into ges where the key wants it.

11

Time signatures and pickups

time 3/4 sets the meter; with none written it is 4/4, which engraves as C (and 2/2 as cut C). Like key, it can stand at the top of the file, in a section (that section's meter), or in the music — there, at the start of a bar, it is the meter of every part from that bar to the end of the section.

time 3/4
part melody { clef treble }
section Intro {
  partial 4                      // the section opens on a one-beat pickup
  melody { d'4 | g2 a4 | b2. | }
}
section Verse {
  melody { g'4 a b | time 2/4 c2 | time 3/4 b2. | }   // a change from that bar on
}
section Cadenza {
  melody { time none g'8 a b c d e f g a b | time 3/4 g2. | }   // unmetered: bars only where written
}
form { Intro Verse Cadenza }
score { staff melody }

• A pickup is partial and the length of the short bar, written in the section before its parts — one pickup for every part. Written in a part's music in the section's first bar it is refused, with this spelling as the fix.
• A short bar later on is partial at that bar's start — | partial 2. r2. | — in every part that shares the bar.
• time none is unmetered music (a cadenza, a recitative): no time signature, and a bar ends only where a | is written. With no beat to follow, beams are not added for you (write them: c8[ d e f]), and the bar number does not advance. The next time ends it.
• A meter that changes nothing is not drawn; time! draws it anyway.

12

Tempo

tempo 120                      // a quarter = 120
tempo "Allegro"                // a word, no metronome mark
tempo "Andante" 4 = 76         // both; the beat can be any value: 4. = 60, 2 = 50
tempo 120 swing                // the swing equation beside the mark (swing 16: sixteenths)

Written at the top of the file it is the opening tempo; in a section, the section's. A tempo lasts until the next one — unlike key and meter, it does not go back at the next section. Playback and the MIDI export follow the number; the word prints.

tempo "Andante" 4 = 76
part melody { clef treble }
section A { melody { c'4 d e f | g1 | } }
section B {
  tempo "Più mosso" 4 = 96         // from here on: a tempo stays until the next one
  melody { a'4 g f e | d1 | }
}
section C { melody { c'4 e g e | c1 | } }   // still 96
form { A B C }
score { staff melody }

13

Clefs and register

A part's clef goes on the part: part cello { clef bass }. The words are treble, bass, alto, tenor, treble_8 (a tenor voice's), treble^8, bass_8, soprano, mezzosoprano, baritone, and percussion for a drum part (Drums). A change mid-piece is written in the music where it happens, and takes one of the first five.

A clef only draws. Where a part's bare letters land is octave N on the part (or an instrument, which sets clef and register together): a cello in bass clef with no octave would start its c at middle C.

part cello {
  clef bass
  octave 3                       // where bare letters land; the clef only draws
}
section A {
  cello { c4 d e f | clef tenor g a b c | clef bass c,1 | }
}
form { A }
score { staff cello }

A clef that changes nothing is not drawn; clef! draws it anyway (after a long rest, say). In a section that holds part cells, a loose clef beside the cells belongs to no part and is refused — put it on the part, or in the music.

14

Dynamics and hairpins

A dynamic is an annotation on the note it starts on: c4@p, from @ppp to @fff, and @sfz @sf @fp @rfz @fz. A hairpin — @cresc, @decresc, @dim — starts on its note and runs to the next dynamic or hairpin on the staff.

part melody { clef treble }
section A {
  melody { c'4@p@cresc d e f | g2@f g@decresc | f4 e d c | c1@niente | }
}
form { A }
score { staff melody }

• Dynamics sit below the staff; @f.up puts one above. A hairpin is always below, so .up on it is an error.
• A note takes one dynamic: in c4@f@sfz the second warns and is not printed. A dynamic and a hairpin together are fine (c4@p@cresc).
• @niente is the silent end: a hairpin that fades into it (or grows out of it) gets the small circle at its tip, and the word is not printed.
• Playback and the MIDI export follow the levels: each sets the loudness of the notes from it on. A hairpin itself is drawn, not played — the loudness changes at the next level, not gradually.

The full list of marks is in Annotations.