Numerous editorial and stylistic changes to manual.

[lilypond.git] / Documentation / user / examples.itely

@node Example templates
@chapter Example templates

This section of the manual contains templates with the LilyPond score
already set up for you.  Just add notes, run LilyPond, and enjoy
beautiful printed scores!

@menu
* Suggestions for writing LilyPond files::
* Single staff::
* Piano templates::
* Small ensembles::
* Jazz combo::
* Other templates::
@end menu

@c TODO explain \score{} ?  Maybe add a note to the tutorial?

@node Suggestions for writing LilyPond files
@section Suggestions for writing LilyPond files

Now you're ready to begin writing bigger LilyPond files -- not just the
little examples in the tutorial, but whole pieces.  But how should you
go about doing it?

The best answer is ``however you want to do it''.  As long as LilyPond
can understand your files and produces the output that you want, it
doesn't matter what your files look like.  That said, sometimes we
make mistakes when writing files.  If LilyPond can't understand your
files, or produces output that you don't like, how do you fix the
problem?

Here are a few suggestions that can help you in avoiding or fixing
problems:

@itemize @bullet
@item Include @code{\version} numbers in every file.  Note that all
templates contain a @code{\version "x.y.z"} string.  We
highly recommend that you always include the @code{\version}, no matter
how small your file is.  Speaking from personal experience, it's
quite frustrating to try to remember which version of LilyPond you were
using a few years ago.  @code{convert-ly} requires you to declare
which version of LilyPond you used.

@item Include checks:  See @ref{Bar check} and @ref{Octave check}.  If you
include checks every so often, then if you make a mistake, you can pinpoint
it quicker.  How often is ``every so often''?  It depends on the complexity
of the music.  For very simple music, perhaps just once or twice.  For
very complex music, every bar.

@item One bar per line.  If there's anything complicated, either in the music
itself or in the output you desire, it's often good to write only one bar
per line.  Saving screen space by cramming eight bars per line just isn't
worth it if you have to `debug' your files.

@item Comment your files, with either bar numbers (every so often) or
references to musical themes (``second theme in violins'', ``fourth
variation'').  You may not need it when you're writing the piece for
the first time, but if you want to go back and change something two
or three years later, you won't know how your file is structured if you
don't comment the file.

@end itemize

@node Single staff
@section Single staff
@subsection Notes only

The first example gives you a staff with notes, suitable for a solo
instrument or a melodic fragment.  Cut and paste this into a file,
add notes, and you're finished!

@lilypond[verbatim,raggedright]

\version "2.3.11"
melody = \relative c' {
   \clef treble
   \key c \major
   \time 4/4

   a4 b c d
}

\score{
   \new Staff \melody
   \paper { }
   \midi { \tempo 4=60 }
}

@end lilypond

@subsection Notes and lyrics

The next example demonstrates a simple melody with lyrics.  Cut and
paste, add notes, then words for the lyrics.  This example turns off
automatic beaming, which is common for vocal parts.  If you want to use
automatic beaming, you'll have to change or comment out the relevant
line.

@lilypond[verbatim,raggedright]

\version "2.3.11"
melody = \relative c' {
   \clef treble
   \key c \major
   \time 4/4

   a4 b c d
}

text = \lyrics {
   Aaa Bee Cee Dee
}

\score{
   <<
      \context Voice = one {
         \autoBeamOff
         \melody
      }
      \lyricsto "one" \new Lyrics \text
   >>
   \paper { }
   \midi { \tempo 4=60 }
}

@end lilypond

@subsection Notes and chords

Want to prepare a lead sheet with a melody and chords?  Look no farther!

@lilypond[verbatim,raggedright]

\version "2.3.11"
melody =  \relative c' {
   \clef treble
   \key c \major
   \time 4/4

   f4 e8[ c] d4 g |
   a2 ~ a2 |
}

harmonies = \chords {
   c4:m f:min7 g:maj c:aug d2:dim b:sus
}

\score {
   <<
      \context ChordNames {
         \set chordChanges = ##t
         \harmonies
      }
   \context Staff = one \melody
   >>

   \paper{ }
   \midi  { \tempo 4=60}
}

@end lilypond

@subsection Notes, lyrics, and chords.

This template allows you to prepare a song with melody, words, and chords.

@lilypond[verbatim,raggedright]

\version "2.3.11"
melody =  \relative c' {
   \clef treble
   \key c \major
   \time 4/4

   a b c d
}

text = \lyrics {
   Aaa Bee Cee Dee
}

harmonies = \chords {
   a2 c2
}

\score {
   <<
      \context ChordNames {
         \set chordChanges = ##t
         \harmonies
      }
   \context Voice = one {
      \autoBeamOff
      \melody
   }
   \lyricsto "one" \new Lyrics \text
   >>
   \paper { }
   \midi  { \tempo 4=60}
}

@end lilypond

@node Piano templates
@section Piano templates
@subsection Solo piano

Here's a simple piano staff.

@lilypond[verbatim,raggedright]

\version "2.3.11"
upper = \relative c'' {
   \clef treble
   \key c \major
   \time 4/4

   a b c d
}

lower = \relative c {
   \clef bass
   \key c \major
   \time 4/4

   a2 c
}

\score {
   \context PianoStaff <<
      \set PianoStaff.instrument = "Piano  "
      \context Staff = upper \upper
      \context Staff = lower \lower
   >>  
   \paper { }  
   \midi { \tempo 4=60 }  
}

@end lilypond

@subsection Piano and melody with lyrics

Here's a typical song format: one staff with the melody and lyrics, with
piano accompaniment underneath.

@lilypond[verbatim,raggedright]

\version "2.3.11"
melody =  \relative c'' {
   \clef treble
   \key c \major
   \time 4/4

   a b c d
}

text = \lyrics {
   Aaa Bee Cee Dee
}

upper = \relative c'' {
   \clef treble
   \key c \major
   \time 4/4

   a b c d
}

lower = \relative c {
   \clef bass
   \key c \major
   \time 4/4

   a2 c
}

\score {
   <<
      \context Voice = mel {
          \autoBeamOff
          \melody
      }
      \lyricsto mel \new Lyrics \text

      \context PianoStaff <<
         \context Staff = upper \upper
         \context Staff = lower \lower
      >>
   >>
   \paper {
      \context { \RemoveEmptyStaffContext }
   }  
   \midi { \tempo 4=60}
}

@end lilypond

@node Small ensembles
@section Small ensembles
@subsection SATB vocal score

Here's a standard four-part SATB vocal score.  With larger ensembles,
it's often useful to include a section which is included in all
parts.  For example, the time signature and key signatures are almost
always the same for all parts.

@lilypond[verbatim,raggedright]

\version "2.3.11"
global = {
   \key c \major
   \time 4/4
}

sopMusic = \relative c'' {
   c4 c c8[( b)] c4
}
sopWords = \lyrics {
   hi hi hi hi
}

altoMusic = \relative c' {
   e4 f d e 
}
altoWords =\lyrics {
   ha ha ha ha
}

tenorMusic = \relative c' {
   g4 a f g
}
tenorWords = \lyrics {
   hu hu hu hu
}

bassMusic = \relative c {
   c4 c g c
}
bassWords = \lyrics {
   ho ho ho ho
}

\score { 
   \context ChoirStaff <<
      \context Lyrics = sopranos { s1 }
      \context Staff = women <<
         \context Voice = sopranos { \voiceOne << \global \sopMusic >> }
         \context Voice = altos { \voiceTwo << \global \altoMusic >> }
      >>
      \context Lyrics = altos { s1 }
      \context Lyrics = tenors { s1 }
      \context Staff = men <<
         \clef bass
         \context Voice = tenors { \voiceOne <<\global \tenorMusic >> }
         \context Voice = basses { \voiceTwo <<\global \bassMusic >> }
      >>
      \context Lyrics = basses { s1 }
      \context Lyrics = sopranos \lyricsto sopranos \sopWords
      \context Lyrics = altos \lyricsto altos \altoWords
      \context Lyrics = tenors \lyricsto tenors \tenorWords
      \context Lyrics = basses \lyricsto basses \bassWords
   >>

   \paper {
      \context {
         % a little smaller so lyrics can be closer to the staff. 
         \Staff minimumVerticalExtent = #'(-3 . 3) 
      }
   }
}

@end lilypond

@subsection String quartet

This template demonstrates a string quartet.  It also uses a @code{\global}
section for time and key signatures.

@lilypond[verbatim,raggedright]

\version "2.3.11"
global = {
   \time 4/4
   \key c \major
}
violinOne = \relative c''{
   \set Staff.instrument = "Violin 1  "
   c2 d
   e1
}
violinTwo = \relative c''{
   \set Staff.instrument = "Violin 2  "
   g2 g
   g1
}
viola = \relative c'{
   \set Staff.instrument = "Viola  "
   \clef alto
   e2 d
   c1
}
cello = \relative c'{
   \set Staff.instrument = "Cello  "
   \clef bass
   c2 g
   c,1
}
\score {
   \new StaffGroup <<
      \new Staff << \global \violinOne >>
      \new Staff << \global \violinTwo >>
      \new Staff << \global \viola >>
      \new Staff << \global \cello >>
   >>
   \paper { }
   \midi { \tempo 4=60}
}

@end lilypond

@node Jazz combo
@section Jazz combo

This is a much more complicated template, for a jazz ensemble.  Note that all
instruments are notated @code{\key c \major}.  This refers to the key in
concert pitch; LilyPond will automatically transpose the key if the music
is within a @code{\transpose} section.

@c TODO must clean up this jazz combo example
@c   - transpositions stated in names (ie "trumpet in Bb" or whatever)
@c   - one global section, instead of "global" (time) and "key"
@c   - does it need those wierd macros?  sl, nsl, etc.
@c   - maybe ask Amelie Zapf to clean it up, or whether I should just
@c     make whatever changes I feel like.

@lilypond[verbatim,raggedright]

\version "2.3.11"
\header {
        title = "Song"
        subtitle = "(tune)"
        composer = "Me"
        meter = "moderato"
        piece = "Swing"
        tagline = "LilyPond example file by Amelie Zapf, Berlin 07/07/2003"
        texidoc = "Jazz tune for combo (horns, guitar, piano, bass, drums)."
}

#(set-global-staff-size 16)
\include "english.ly"

%%%%%%%%%%%% Some macros %%%%%%%%%%%%%%%%%%%

sl = {
    \override NoteHead  #'style = #'slash
    \override Stem  #'transparent = ##t
}
nsl = {
    \revert NoteHead #'style
    \revert Stem #'transparent
}
cr = \override NoteHead  #'style = #'cross
ncr = \revert NoteHead #'style

%% insert chord name style stuff here.

jzchords = { } 


%%%%%%%%%%%% Keys'n'thangs %%%%%%%%%%%%%%%%%

global =  {
    \time 4/4
}

Key =  { \key c \major }

% ############ Horns ############
% ------ Trumpet ------
trpt =  \transpose c d \relative c'' {
    \Key
    c1 c c
}

trpharmony = \transpose c' d { \jzchords }
trumpet = {
    \global 
    \set Staff.instrument = #"Trumpet"
    \clef treble
    \context Staff <<
        \trpt
    >>
}

% ------ Alto Saxophone ------
alto = \transpose c a \relative c' {
        \Key
        c1 c c
}

altoharmony = \transpose c' a { \jzchords }
altosax = {
        \global
        \set Staff.instrument = #"Alto Sax"
        \clef treble
        \context Staff <<
                \alto
        >>
}

% ------ Baritone Saxophone ------
bari = \transpose c a' \relative c {
        \Key
        c1 c \sl d4^"Solo" d d d \nsl
}

bariharmony = \transpose c' a \chords { \jzchords s1 s d2:maj e:m7 }
barisax = {
        \global
        \set Staff.instrument = #"Bari Sax"
        \clef treble
        \context Staff <<
                \bari
        >>
}
% ------ Trombone ------
tbone =  \relative c {
        \Key
        c1 c c
}

tboneharmony = \chords { \jzchords }
trombone = {
        \global
        \set Staff.instrument = #"Trombone"
        \clef bass
        \context Staff <<
                \tbone
        >>
}
% ############ Rhythm Section #############
% ------ Guitar ------
gtr =  \relative c'' {
        \Key
        c1 \sl b4 b b b \nsl c1
}

gtrharmony = \chords { \jzchords
        s1 c2:min7+ d2:maj9
}

guitar = {
        \global
        \set Staff.instrument = #"Guitar"
        \clef treble
        \context Staff <<
                \gtr
        >>
}

%% ------ Piano ------
rhUpper =  \relative c'' {
        \voiceOne
        \Key
        c1 c c
}

rhLower =  \relative c' {
        \voiceTwo
        \Key
        e1 e e
}

lhUpper =  \relative c' {
        \voiceOne
        \Key
        g1 g g
}

lhLower =  \relative c {
        \voiceTwo
        \Key
        c1 c c
}

PianoRH = {
        \clef treble
        \global
        \set Staff.midiInstrument = "acoustic grand"
        \context Staff <<
                \context Voice = one \rhUpper
                \context Voice = two \rhLower
        >>
}

PianoLH = {
        \clef bass
        \global
        \set Staff.midiInstrument = "acoustic grand"
        \context Staff <<
                \context Voice = one \lhUpper
                \context Voice = two \lhLower
        >>
}

piano = {
        \context PianoStaff <<
                \set PianoStaff.instrument = #"Piano"
                \context Staff = upper \PianoRH
                \context Staff = lower \PianoLH
        >>
}

% ------ Bass Guitar ------
bass =  \relative c {
        \Key
        c1 c c
}

bass = {
    \global
    \set Staff.instrument = #"Bass"
    \clef bass
    \context Staff <<
        \bass
    >>
}

                                % ------ Drums ------

up = \drums {
    hh4 <hh sn>4 hh <hh sn> hh <hh sn>4
    hh4 <hh sn>4
    hh4 <hh sn>4
    hh4 <hh sn>4
}

down = \drums {
    bd4 s bd s bd s bd s bd s bd s
}

drumContents = {
        \global
        <<
                \set DrumStaff.instrument = #"Drums"
                \new DrumVoice { \voiceOne \up }
                \new DrumVoice { \voiceTwo \down }
        >>
}

%%%%%%%%% It All Goes Together Here %%%%%%%%%%%%%%%%%%%%%%

\score {
<<
        \context StaffGroup = horns <<
                \context Staff = trumpet \trumpet

                \context Staff = altosax \altosax

                \context ChordNames = barichords \bariharmony

                \context Staff = barisax \barisax

                \context Staff = trombone \trombone
        >>

        \context StaffGroup = rhythm <<
                \context ChordNames = chords \gtrharmony
                \context Staff = guitar \guitar
                \context PianoStaff = piano \piano
                
                \context Staff = bass \bass
                
                \new DrumStaff { \drumContents }
        >>
>>
        \paper {
                \context { \RemoveEmptyStaffContext }
                \context {
                        \Score
                        \override BarNumber #'padding = #3
                        \override RehearsalMark #'padding = #2
                        skipBars = ##t
                }
        }
        \midi { \tempo 4 = 75 }
}

@end lilypond

@node Other templates
@section Other templates
@subsection All headers

This template displays all available headers.  Some of them are only
used in the Mutopia project; they don't affect the printed output at
all.  They are used  if you want the piece to be listed with different
information in the Mutopia database than you wish to have printed on the
music.  For example, Mutopia lists the composer of the famous D major
violin concerto as TchaikovskyPI, whereas perhaps you wish to print
"Petr Tchaikowski" on your music.

@lilypond[verbatim,raggedright]

\version "2.3.11"
\header {
   dedication = "dedication"
   title = "Title"
   subtitle = "Subtitle"
   subsubtitle = "Subsubtitle"
   composer = "Composer (xxxx-yyyy)"
   opus = "Opus 0"
   piece = "Piece I"
   instrument = "Instrument"
   arranger = "Arranger"
   poet = "Poet"
   texttranslator = "Translator"
   copyright = "public domain"

% These are headers used by the Mutopia Project  http://www.mutopiaproject.org/
   mutopiatitle = ""
   mutopiacomposer = ""
   mutopiapoet = ""
   mutopiainstrument = ""
   date = "composer's dates"
   source = "urtext "
   maintainer = "your name here"
   maintainerEmail = "your email here"
   maintainerWeb = "your home page"
   lastupdated = "2004/Aug/26"
}

\score {
   \header {
      piece = "piece1"
      opus = "opus1"
   }
   { c'4 }
}

\score {
   \header {
      piece = "piece2"
      opus = "opus2"
   }
   { c'4 }
}

@end lilypond

@subsection Gregorian template

This example demonstrates how to do modern transcriptions of Gregorian
music.  Gregorian music has no measure, no stems; it uses only half and
quarter notes, and two types of barlines, a short one indicating a rest,
and a second one indicating a breath mark.

@lilypond[verbatim,raggedright]

barOne = { \once \override Staff.BarLine  #'bar-size = #2
   \bar "|" }
barTwo = { \once \override Staff.BarLine  #'extra-offset = #'(0 . 2)
   \once \override Staff.BarLine  #'bar-size = #2
   \bar "|" }
chant = \relative c' {
   \set Score.timing = ##f
   \override Staff.Stem  #'transparent = ##t

   f4 a2 \barTwo
   g4 a2 f2 \barOne
   g4( f) f( g) a2
}
\score {
   \chant
   \paper{ }
   \midi { \tempo 4=60 }
}

@end lilypond

@subsection Bagpipe music

Here's an example of bagpipe music.  It demonstrates a big strength of
LilyPond, compared to graphical score editors: in LilyPond, you can
very easily reuse small segments of music without writing them out
completely.  This template defines a large number of small segments
(@code{taor, grip, thrd,} etc), which can be reused easily.

TODO - replace Bagpipe template with Andrew McNabb's work?

@lilypond[verbatim,raggedright]

taor = { \grace { g32[ d' g e'] } }
grip = { \grace { g32[ b g ]    } }
thrd = { \grace { g32[ d' c']   } }
birl = { \grace { g32[ a g]     } }
gstd = { \grace { g'32[ d' g]   } }
fgg =  { \grace { f32[ g'32]    } }
dblb = { \grace { g'32[ b d']   } }
dblc = { \grace { g'32[ c' d']  } }
dble = { \grace { g'32[ e' f']  } }
dblf = { \grace { g'32[ f' g']  } }
dblg = { \grace { g'32[ f']     } }
dbla = { \grace { a'32[ g']     } }
lgg =  { \grace { g32  } }
lag =  { \grace { a32  } }
cg   = { \grace { c'32 } }
eg   = { \grace { e'32 } }
gg   = { \grace { g'32 } }
dg   = { \grace { d'32 } }
hag  = { \grace { a'32 } }
gefg = { \grace { g'32[ e' f']  } }
efg  = { \grace { e'32[ f']     } }
gdcg = { \grace { g'32[ d' c']  } }
gcdg = { \grace { g'32[ c' d']  } }
        
\transpose a a' {
    #(add-grace-property 'Voice 'Stem 'length 6)
    \time 6/8 \partial 4
    \tieUp
    \slurUp
    
    f'4 |
    \gg f'4 e'8 \thrd d'4. |
    \eg a4.(a4) d'8 |
    \gg d'4 f'8 \dble e'4. ( | \noBreak
    e'8) d'4 \gg d'4 e'8 |

    \break
    \time 9/8
    \dblf f'2.( f'4) d'8 |
    \time 6/8
    \dblg g'4 a'8 \gg a'4. |
    \thrd d'4.( d'4) \eg a8 |
    \time 9/8
    \dble e'4 \lag e'8 \gg  e'16[ d'8. e'8] \gg f'4 g'8 |

    \break
    \time 6/8
    \gg f'4 e'8 \thrd d'4. |
    \eg a4.( a4) d'8 |
    \dblg g'4 a'8 \gg a'4. |
    \thrd d'4.( d'4) f'8 |

    \break
    \dblg g'4 e'8( e'8) \dblf  f'8.[ e'16] |
    \thrd d'4.( d'4) \cg d'8 |
    \gg c'4 e'8 \thrd d'4.( |
    d'4.) \gdcg d'4.
    
}

@end lilypond