21.1 Creating titles, headers, and footers (LilyPond Notation Reference)

[ << Titles and headers ]	[Top][Contents][Index]	[ Working with input files >> ]
[ < Titles and headers ]	[ Up: Titles and headers ]	[ Titles explained > ]

21.1 Creating titles, headers, and footers

[ << Titles and headers ]	[Top][Contents][Index]	[ Working with input files >> ]
[ < Creating titles, headers, and footers ]	[ Up: Creating titles, headers, and footers ]	[ Default layout of bookpart and score titles > ]

21.1.1 Titles explained

Each \book block in a single input file produces a separate output file, see File structure. Within each output file three types of titling areas are provided: book titles at the beginning of each book, bookpart titles at the beginning of each bookpart, and score titles at the beginning of each score.

Values of titling fields such as title and composer are set in \header blocks. (For the syntax of \header blocks and a complete list of the fields available by default, see Default layout of bookpart and score titles). Book titles, bookpart titles, and score titles can all contain the same fields, although by default the fields in score titles are limited to piece and opus.

\header blocks may be placed in four different places to form a descending hierarchy.

At the top of the input file, before all \book, \bookpart, and \score blocks.
Within a \book block but outside all the \bookpart and \score blocks within that book.
Within a \bookpart block but outside all \score blocks within that bookpart.
Within a \score block.

The values of the fields filter down this hierarchy, with the values set higher in the hierarchy persisting unless they are overridden by a value set lower in the hierarchy.

A book title is derived from fields set at the top of the input file, modified by fields set in the \book block. The resulting fields are used to print the book title for that book, providing that there is other material that generates a page at the start of the book, before the first bookpart. A single \pageBreak suffices.
A bookpart title is derived from fields set at the top of the input file, modified by fields set in the \book block, and further modified by fields set in the \bookpart block. The resulting values are used to print the bookpart title for that bookpart.
A score title is derived from fields set at the top of the input file, modified by fields set in the \book block, further modified by fields set in the \bookpart block and finally modified by fields set in the \score block. The resulting values are used to print the score title for that score. Note, though, that only piece and opus fields are printed by default in score titles unless the \paper variable print-all-headers is set to #t.

It is not necessary to provide \header blocks in all four places: any or even all of them may be omitted. Similarly, simple input files may omit the \book and \bookpart blocks, leaving them to be created implicitly.

If the book has only a single score, the \header block should normally be placed at the top of the file so that just a bookpart title is produced, making all the titling fields available for use.

If the book has multiple scores a number of different arrangements of \header blocks are possible, corresponding to the various types of musical publications. For example, if the publication contains several pieces by the same composer, a \header block placed at the top of the file specifying the book title and the composer with \header blocks in each \score block specifying the piece and/or opus would be most suitable, as here:

\header {
  title = "SUITE I."
  composer = "J. S. Bach."
}

\score {
  \header {
    piece = "Prélude."
  }
  \new Staff \relative {
    \clef bass
    \key g \major
    \repeat unfold 2 { g,16( d' b') a b d, b' d, } |
    \repeat unfold 2 { g,16( e' c') b c e, c' e, } |
  }
}

\score {
  \header {
    piece = "Allemande."
  }
  \new Staff \relative {
    \clef bass
    \key g \major
    \partial 16 b16 |
    <g, d' b'~>4 b'16 a( g fis) g( d e fis) g( a b c) |
    d16( b g fis) g( e d c) b(c d e) fis( g a b) |
  }
}

More complicated arrangements are possible. For example, text fields from the \header block in a book can be displayed in all score titles, with some fields overridden and some manually suppressed:

\book {
  \paper {
    print-all-headers = ##t
  }
  \header {
    title = "DAS WOHLTEMPERIRTE CLAVIER"
    subtitle = "TEIL I"
    % Do not display the default LilyPond footer for this book
    tagline = ##f
  }
  \markup { \vspace #1 }
  \score {
    \header {
      title = "PRAELUDIUM I"
      opus = "BWV 846"
      % Do not display the subtitle for this score
      subtitle = ##f
    }
    \new PianoStaff <<
      \new Staff { s1 }
      \new Staff { \clef "bass" s1 }
    >>
  }
  \score {
    \header {
      title = "FUGA I"
      subsubtitle = "A 4 VOCI"
      opus = "BWV 846"
      % Do not display the subtitle for this score
      subtitle = ##f
    }
    \new PianoStaff <<
      \new Staff { s1 }
      \new Staff { \clef "bass" s1 }
    >>
  }
}

21.1.2 Default layout of bookpart and score titles

The next example demonstrates all printed \header variables. Note that the vertical spacing between the various header elements in the default layout is optimized for single-line entries. If you need multi-line elements, say, a two-line composer entry, try to append \vspace to the field if necessary to adjust the vertical spacing. An alternative is to define your own, custom layout, see Custom layout for titles.

\book {
  \header {
    % The following fields are centered
    dedication = "Dedication"
    title = "Title"
    subtitle = "Subtitle"
    subsubtitle = "Subsubtitle"

    % The following fields are evenly spread on one line;
    % the field "instrument" also appears on following pages
    instrument = \markup \with-color #green "Instrument"
    poet = "Poet"
    composer = "Composer"

    % The following fields are placed at opposite ends
    %of the same line
    meter = "Meter"
    arranger = "Arranger"

    % The following fields are centered at the bottom
    tagline = "The tagline goes at the bottom of the last page"
    copyright = "The copyright goes at the bottom of the first page"
  }
  \score {
    \header {
      % The following fields are placed at opposite ends
      % of the same line
      piece = "Piece 1"
      opus = "Opus 1"
    }
    { s1 }
  }
  \score {
    \header {
      % The following fields are placed at opposite ends
      % of the same line
      piece = "Piece 2 on the same page"
      opus = "Opus 2"
    }
    { s1 }
  }
  \pageBreak
  \score {
    \header {
      % The following fields are placed at opposite ends
      % of the same line
      piece = "Piece 3 on a new page"
      opus = "Opus 3"
    }
    { s1 }
  }
}

Note that

the instrument name is repeated on every page,
only piece and opus are printed in a \score when the paper variable print-all-headers is set to #f (the default),
text fields left unset in a \header block produce no output so that the space is not wasted,
the default settings for scoreTitleMarkup place the piece and opus text fields at opposite ends of the same line.

To change the default layout, see Custom layout for titles.

If a \book block starts immediately with a \bookpart block, no book title gets printed, as there is no page on which to print it. If a book title is required, begin the \book block with some markup material or a \pageBreak command.

Use the breakbefore variable inside a \header block that is itself in a \score block, to make the higher-level \header block titles appear on the first page on their own, with the music (defined in the \score block) starting on the next page.

\book {
  \header {
    title = "This is my Title"
    subtitle = "This is my Subtitle"
    copyright = "This is the bottom of the first page"
  }
  \score {
    \header {
      piece = "This is the Music"
      breakbefore = ##t
    }
    \repeat unfold 4 { e'' e'' e'' e'' }
  }
}

21.1.3 Default layout of headers and footers

Headers and footers are lines of text appearing at the top and bottom of pages, separate from the main text of a book. They are controlled by the following \paper variables:

oddHeaderMarkup
evenHeaderMarkup
oddFooterMarkup
evenFooterMarkup

These markup variables are defined in ly/titling-init.ly and do the following by default.

Page numbers are automatically placed on the top far left (if even) or top far right (if odd), starting from the second page.
The instrument header field is placed in the center of every page, starting from the second page.
The copyright header field is centered on the bottom of the first page.
The tagline header field is centered on the bottom of the last page, and below the copyright field if there is only a single page.

The following shows an example how to change the tag line.

\book {
  \header {
    tagline = "... music notation for Everyone"
  }
  \score {
    \relative {
      c'4 d e f
    }
  }
}

Set tagline to #f if you don’t want a tag line.